# Claude Code hooks and subagents: what they are and how to use them

Claude Code hooks are commands that Claude Code runs automatically at fixed points in a session, such as before a tool call, and they can block the action. Subagents are specialized assistants that run in their own context window with their own tools and permissions, and return only a summary. Use hooks to enforce rules the model must never break, and subagents to isolate research, review or parallel work from the main conversation.

By Shai Goldenberg. Updated: 2026-11-13.

## Why hooks exist

Instructions in a prompt or in `CLAUDE.md` shape what Claude tries to do. They do not guarantee it. A model that follows a rule on most runs will, sooner or later, miss it on one.

Hooks close that gap. A hook is your code, run by Claude Code itself at a fixed point, with the power to stop an action. The model does not decide whether the hook runs.

The details below were checked against the official Claude Code documentation as of November 2026. The feature set changes often, so confirm names against the current hooks reference before relying on them.

## Hook events

Claude Code fires events throughout a session, and a hook attaches to one of them. The current reference lists more than 30 events. These are the ones most teams use:

| Event | When it fires | Typical use |
|---|---|---|
| `SessionStart` | A session begins | Load context, set up the environment |
| `UserPromptSubmit` | The user sends a prompt | Add context, validate the prompt |
| `PreToolUse` | Before a tool call runs | Block dangerous commands or edits |
| `PostToolUse` | After a tool call succeeds | Run a formatter or linter on changed files |
| `PermissionRequest` | A permission prompt would appear | Approve or deny automatically |
| `Notification` | Claude Code sends a notification | Forward alerts to your own channel |
| `SubagentStart`, `SubagentStop` | A subagent starts or finishes | Log or check subagent work |
| `Stop` | Claude finishes responding | Check that the work is complete |
| `PreCompact` | Before context is compacted | Save state |
| `SessionEnd` | A session ends | Clean up, write logs |

Other events cover worktree creation and removal, configuration changes, file changes and more.

## How a hook is configured

Hooks live under the `hooks` key of a settings file. The structure has three levels: the event, a matcher group that filters when it applies, and one or more handlers.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-force-push.sh"
          }
        ]
      }
    ]
  }
}
```

- **`matcher`** filters by tool name for tool events. `"Bash"` matches shell commands.
- **`type`** is the handler type. `command` runs a shell command. The reference also lists `http`, `mcp_tool`, `prompt` and `agent` handlers.
- **`command`** is what to run. `${CLAUDE_PROJECT_DIR}` resolves to the project root where the session started, so the path works from any directory.

Handlers accept optional fields too, including `timeout` and an `if` condition written in permission rule syntax, such as `"Bash(rm *)"`.

Where the file lives decides who gets the hook: `~/.claude/settings.json` applies to all your projects, `.claude/settings.json` is the project file you commit, and `.claude/settings.local.json` is the project file you keep out of git.

## What a hook receives and returns

A command hook receives a JSON object on stdin. For `PreToolUse`, the fields include `session_id`, `cwd`, `permission_mode`, `hook_event_name`, `tool_name` and `tool_input`. For a Bash call, the command text is at `tool_input.command`.

The hook answers through its exit code:

- **Exit 0.** Success. If stdout is a single JSON object, Claude Code applies its fields. With no output, no decision is made and the normal permission flow continues.
- **Exit 2.** A blocking error. On `PreToolUse`, the tool call is blocked and the text on stderr is passed to Claude as the reason.
- **Any other code.** A non-blocking error. The action proceeds and a hook error notice is shown.

That last point catches people out. A guard script that crashes with exit code 1 does not block anything. Blocking requires exit code 2 or a JSON decision.

For finer control, exit 0 and print JSON. A `PreToolUse` hook can set `permissionDecision` to `allow`, `deny`, `ask` or `defer`, with a reason:

```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}
```

## A working PreToolUse guard hook

This hook blocks `git push --force` and `git push -f`. A force push can overwrite other people's commits, and an agent that hits a rejected push may try it as a fix.

Save this as `.claude/hooks/block-force-push.sh`:

```bash
#!/bin/bash
# .claude/hooks/block-force-push.sh
COMMAND=$(jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -Eq 'git[[:space:]]+push.*(--force|[[:space:]]-f([[:space:]]|$))'; then
  echo "Blocked: force push is not allowed in this repo. Push a new commit instead." >&2
  exit 2
fi

exit 0
```

Make it executable:

```sh
chmod +x .claude/hooks/block-force-push.sh
```

Then register it with the settings block shown in the configuration section above. The script needs `jq` on the PATH.

How it works: the script reads the event JSON from stdin, extracts the command, and tests it against a pattern. On a match it writes the reason to stderr and exits with code 2, which blocks the call. Claude reads the reason and chooses another route. On no match it exits 0 and the normal permission flow continues. The pattern also matches `--force-with-lease`. Narrow it if your team allows that variant.

Test it without Claude Code by piping sample input:

```sh
echo '{"tool_name":"Bash","tool_input":{"command":"git push --force origin main"}}' \
  | .claude/hooks/block-force-push.sh; echo "exit: $?"
```

This prints the block message and `exit: 2`. The same test with `git push origin main` prints `exit: 0`.

### Limits of pattern-matching hooks

A text pattern catches the form of the command the model usually writes. It will not catch every way to reach the same effect, for example a script that runs the push internally. Treat guard hooks as one layer. Pair them with permission deny rules, branch protection on the server, and credentials that cannot do the dangerous thing at all.

## How hooks interact with permissions

Two rules from the permissions documentation are worth knowing:

- A hook that blocks wins over allow rules. A hook that exits with code 2 stops the call before permission rules are evaluated.
- A hook that returns `allow` does not override deny rules. A matching deny rule still blocks the call.

So hooks can tighten the rules freely but cannot loosen a deny. That is the right shape for a safety layer.

## Hooks from real incidents

The most useful hooks come from things that went wrong. Shai's production codebase has guard hooks that block two SQL patterns that caused real incidents. Once the hook existed, the pattern could not be written again by any agent, in an interactive session, an overnight run or CI.

The method is general. After an incident, ask whether a check before the tool call could have stopped it. If yes, write the hook the same day and commit it. Our [Claude Code best practices](https://goldenroz.com/blog/claude-code-best-practices/) post covers how hooks fit with permission envelopes and worktrees, and [Supabase Row Level Security](https://goldenroz.com/blog/supabase-row-level-security/) covers the database side of those guardrails.

## What subagents are

A subagent is a specialized assistant that Claude can delegate a task to. Each subagent runs in its own context window with a custom system prompt, specific tool access and independent permissions. It does not see your conversation history. Claude writes it a task message, it does the work, and only its summary comes back.

That last property is the main benefit. A search across 200 files produces a lot of output. Done in the main session, it fills the context. Done in a subagent, the main session receives a few paragraphs.

Claude Code ships with built-in subagents, including Explore (a fast, read-only agent for searching code), Plan (used in plan mode to gather context) and a general-purpose agent for multi-step tasks.

### Defining a subagent

A custom subagent is a Markdown file with YAML frontmatter, stored in `.claude/agents/` for the project or `~/.claude/agents/` for all your projects. Only `name` and `description` are required.

```markdown
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
```

The `description` tells Claude when to delegate. The `tools` list limits what the subagent can do. This reviewer can read and search but cannot edit or run commands. Other supported fields include `disallowedTools`, `permissionMode`, `maxTurns`, `skills`, `mcpServers`, `hooks` and `isolation`.

Claude delegates automatically when a task matches a description. You can also ask by name ("use the code-reviewer subagent on the auth changes").

Two fields connect to the rest of this post. `isolation: worktree` runs the subagent in a temporary git worktree, so parallel subagents do not edit the same files. `hooks` attaches hooks that run only while that subagent is active, so a database-migration subagent can carry its own SQL guard.

## When to use subagents

| Situation | Main session | Subagent |
|---|---|---|
| Quick lookup in a known file | Yes | No |
| Broad search across the codebase | No | Yes, read-only |
| Independent review of a change | No | Yes, with restricted tools |
| Several independent tasks at once | No | Yes, in worktrees |
| A task that needs the conversation's full history | Yes | No |
| Small edit you want to watch | Yes | No |

Subagents have costs. Each starts without your conversation's context, so the delegation message must carry everything it needs. They count toward the same usage limits. And a summary can leave out a detail you needed. For a handful of tool calls, do the work in the main session.

## What to do next

Write one guard hook this week for the worst thing an agent could do in your repository, and commit it. Then add a read-only reviewer subagent. If you want hooks, permission envelopes and subagents set up across your team's repositories, our [Claude Code training](https://goldenroz.com/claude-code-training/) program does that in 4 to 8 weeks at a fixed price, quoted after a 30-minute scoping call. For a review of what agents have already written, see our [security audit](https://goldenroz.com/security-audit/).

## Questions buyers ask

### What are Claude Code hooks?

Hooks are handlers that Claude Code runs at defined lifecycle events, such as PreToolUse, PostToolUse and SessionStart. The most common type is a shell command that receives JSON on stdin describing the event. Some events, including PreToolUse, let the hook block the action.

### How does a PreToolUse hook block a command?

There are two ways. The script can exit with code 2, in which case the tool call is blocked and the text written to stderr is given to Claude as the reason. Or it can exit with code 0 and print a JSON object whose hookSpecificOutput sets permissionDecision to deny.

### Where are Claude Code hooks configured?

In settings files: ~/.claude/settings.json for all your projects, .claude/settings.json for a project shared through git, and .claude/settings.local.json for a project on your machine only. Hooks can also come from managed policy settings, plugins, and skill or subagent frontmatter.

### What are Claude Code subagents?

Subagents are specialized assistants defined as Markdown files with YAML frontmatter, stored in .claude/agents/ for a project or ~/.claude/agents/ for all your projects. Each runs in a fresh context window with its own system prompt, tool access and permissions, and only its summary returns to the main conversation.

### When should I use a subagent instead of the main session?

Use one when the work would flood the main conversation with output you do not need to keep, such as a broad codebase search, when you want a restricted tool set such as a read-only reviewer, or when independent tasks can run in parallel. For a quick lookup or a small edit, the main session is simpler.

---
Page: https://goldenroz.com/blog/claude-code-hooks/
Book a free one-hour call: https://calendly.com/daniarozin/daniel-rozin-consultation-1-hour-clone
