The Hooks System

What are hooks?

Hooks let you inject side effects at precisely defined points in the Claude Code lifecycle — before a tool runs, after sampling completes, when a session starts, when a file changes. Each hook is a matcher + command pair stored in a settings file (or in memory for session hooks). When an event fires, Claude Code finds every matching hook, runs all of them, then interprets exit codes and stdout to decide whether to continue, block, or feed output back to the model.

Hooks are the primary extension surface. They power lint-on-save behaviors, policy enforcement, observability pipelines, structured verification agents, and more — all without modifying Claude Code itself.

All 27 hook events

Events are grouped by category. Each badge shows the event name as it appears in settings.json and in the TypeScript source.

Lifecycle (session boundaries)

Tool execution

Agent & subagent

Compaction

Permission & policy

Collaborative / multi-agent

Filesystem & environment

MCP elicitation

How a hook fires

The diagram below shows the execution path for a single PreToolUse event. Other events follow the same shape: gather hooks for event → run matchers in order → aggregate results → decide.

Exit code semantics

Each event defines its own exit-code semantics. Below is the cross-event summary. Read the full per-event description in hooksConfigManager.ts → getHookEventMetadata().

5 hook command types

The type discriminant field selects the execution engine. All types except function can be persisted to settings.json; function is session-only and defined in TypeScript code.

Config sources & priority

Hooks can originate from six sources. When the same event + matcher has hooks from multiple sources, they are merged and all run; the priority ordering (from SOURCES in settings/constants.ts) determines display order in /hooks, but all hooks execute.

How hooks are matched

Each entry in a hook event's array is a HookMatcher — an object with an optional matcher string and an array of hook commands. For events that support matchers (e.g. PreToolUse matches on tool_name; Notification matches on notification_type; SessionStart matches on source), hooks with a matching string run; hooks with no matcher run unconditionally.

// ~/.claude/settings.json — minimal example
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",        // only fires when tool_name === "Write"
        "hooks": [
          { "type": "command", "command": "./scripts/pre-write.sh" }
        ]
      },
      {
        // no matcher → runs for every tool call
        "hooks": [
          { "type": "command", "command": "./scripts/audit-log.sh" }
        ]
      }
    ]
  }
}
settings.json

Session hooks

Session hooks are in-memory only, attached to a specific sessionId stored in a Map<string, SessionStore>. They are created programmatically via three functions in sessionHooks.ts:

// Adding a command/prompt/agent/http hook for this session
addSessionHook(setAppState, sessionId, 'Stop', '', {
  type: 'command',
  command: './verify-output.sh'
})

// Adding a TypeScript callback hook (function type)
const hookId = addFunctionHook(
  setAppState, sessionId,
  'Stop',
  '',                                // matcher (empty = all)
  (messages, signal) => checkCondition(messages),  // callback
  'Condition not met',             // errorMessage if false
  { timeout: 5000, id: 'my-hook' }   // optional
)

// Removing a function hook by ID
removeFunctionHook(setAppState, sessionId, 'Stop', hookId)
sessionHooks.ts API

Session hooks are not reactive — they sit in a Map (not a plain object) so that Object.is(next, prev) returns true during state updates and does not fire unnecessary re-renders. The map is mutated in place; only the session-scoped data changes.

Session hooks from frontmatter

When a skill or agent is loaded, its frontmatter hooks section is registered as session hooks via registerSkillHooks() or registerFrontmatterHooks(). These hooks live only while the session (or agent) is active.

One detail: agents trigger SubagentStop, not Stop. The registerFrontmatterHooks() function automatically converts any Stop entries in an agent's frontmatter to SubagentStop so they fire at the correct point.

Async & asyncRewake

Command hooks support two async flags. When async: true, the hook process is launched but Claude does not wait for it — the conversation continues immediately. The process is tracked in AsyncHookRegistry and polled in the main loop.

When asyncRewake: true, the hook runs in background but the main loop wakes the model if the process exits with code 2. This allows a background watcher to interrupt Claude's next response with a blocking error, even though the hook itself ran asynchronously.

{
  "PostToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "./run-tests-background.sh",
          "asyncRewake": true   // wakes model if tests fail (exit 2)
        }
      ]
    }
  ]
}
asyncRewake example

The registry tracks each pending hook by processId. When the main loop polls via checkForAsyncHookResponses(), completed hooks are finalized and their stdout parsed for a JSON SyncHookJSONOutput response. If none is found, the response object defaults to {}.

HTTP hooks: security model

HTTP hooks POST JSON to a URL. The security model has three layers:

1. URL allowlist: If allowedHttpHookUrls is set in merged settings, only URLs matching the listed glob patterns (using * as wildcard) are permitted. An empty array blocks all HTTP hooks.
2. Env var allowlist: Header values can contain $VAR_NAME interpolation, but only variables listed in the hook's allowedEnvVars array are resolved. Variables not on the list are replaced with empty strings to prevent secret exfiltration via project hooks.
3. SSRF guard: DNS resolution is intercepted by ssrfGuardedLookup(), which blocks private IP ranges (10.x, 172.16-31.x, 192.168.x, 169.254.x, 100.64-127.x) and unspecified/link-local IPv6. Loopback (127.0.0.1, ::1) is intentionally allowed for local dev servers. When a sandbox proxy or env-var proxy is active, the guard is bypassed (the proxy performs its own DNS; blocking the proxy's own IP would break corporate proxies on private networks).

{
  "Stop": [
    {
      "hooks": [
        {
          "type": "http",
          "url": "https://api.example.com/claude-stop-event",
          "headers": {
            "Authorization": "Bearer $MY_TOKEN"
          },
          "allowedEnvVars": ["MY_TOKEN"],
          "timeout": 10
        }
      ]
    }
  ]
}
settings.json — http hook with env var auth

Prompt & agent hooks: deep dive

Prompt hooks

A prompt hook sends a message to an LLM using queryModelWithoutStreaming. The system prompt tells the model to respond as JSON matching {"ok": boolean, "reason"?: string}. The output format is enforced via a JSON schema output mode — the model cannot produce anything unparseable.

The hook resolves argument placeholders ($ARGUMENTS, $0, $ARGUMENTS[0], etc.) before sending. The model used defaults to the "small fast model" (configurable per-hook via model field).

If the model returns {"ok": false}, the hook result is blocking with a preventContinuation: true flag. If it returns {"ok": true}, the hook is a success. Malformed JSON or schema validation failures produce a non-blocking error.

Agent hooks

Agent hooks run a full multi-turn agent loop (up to 50 turns) via query(). The agent gets a custom system prompt including the path to the conversation transcript, access to all tools filtered by permissions, plus a StructuredOutput tool it must call to return results. The structured output enforcement is registered as a session-level Stop function hook before the agent loop starts, and cleaned up after.

If the agent hits 50 turns without calling StructuredOutput, the outcome is cancelled — no error is shown to the user. The same applies if the agent finishes without calling the tool at all.

// hookHelpers.ts — registerStructuredOutputEnforcement
addFunctionHook(
  setAppState,
  sessionId,
  'Stop',
  '',               // no matcher = all stops
  messages => hasSuccessfulToolCall(messages, SYNTHETIC_OUTPUT_TOOL_NAME),
  `You MUST call the ${SYNTHETIC_OUTPUT_TOOL_NAME} tool to complete this request. Call this tool now.`,
  { timeout: 5000 }
)
hookHelpers.ts

Hook event system (SDK telemetry)

In addition to executing hooks, Claude Code emits hook execution events to SDK consumers via a separate in-process event bus in hookEvents.ts. This is distinct from the hook execution system — it is purely observability/telemetry.

Three event types

• started — emitted when a hook begins executing
• progress — emitted on a polling interval (default 1s) while the hook runs, carrying current stdout/stderr
• response — emitted when the hook finishes, with full output, exit code, and outcome

Always-emitted events

Two events are always emitted regardless of the includeHookEvents SDK option: SessionStart and Setup. These are described in the source as "low-noise lifecycle events that were in the original allowlist and are backwards-compatible." All other events require includeHookEvents: true in the SDK options or running in CLAUDE_CODE_REMOTE mode.

The if filter field

Every persisted hook command type supports an optional if field. It uses permission rule syntax — the same syntax as allowedTools patterns. Examples: "Bash(git *)", "Read(*.ts)". The hook only spawns if the tool call matches the pattern.

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "./git-safety.sh",
          "if": "Bash(git push*)"  // only fire on git push commands
        }
      ]
    }
  ]
}
if field — only fires for git push

The if field is part of hook identity: two hooks with the same command but different if values are considered distinct hooks and both run when the session has them registered. The shell field is also part of identity — "command": "foo" with "shell": "bash" and "command": "foo" with "shell": "powershell" are distinct hooks.

Real-world patterns

{
  "PreToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "jq -e '.tool_input.file_path | test(\"test.*\\.ts$\")' <<< \"$CLAUDE_HOOK_INPUT\" && echo 'Must write tests alongside implementation' >&2 && exit 2 || exit 0",
          "statusMessage": "Checking test coverage policy..."
        }
      ]
    }
  ]
}

{
  "SessionStart": [
    {
      "matcher": "startup",
      "hooks": [
        {
          "type": "command",
          "command": "echo \"Today is $(date). Open PRs: $(gh pr list --json number | jq length)\""
        }
      ]
    }
  ]
}

{
  "Stop": [
    {
      "hooks": [
        {
          "type": "agent",
          "prompt": "Verify that the implementation includes unit tests and that they all pass. Read the transcript at $ARGUMENTS[transcript_path] to understand what was built, then run the tests.",
          "timeout": 120
        }
      ]
    }
  ]
}

{
  "CwdChanged": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "[ -f .envrc ] && direnv export bash >> \"$CLAUDE_ENV_FILE\" || true"
        }
      ]
    }
  ]
}

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "prompt",
          "prompt": "The following bash command is about to run: $ARGUMENTS\nReturn ok: true only if the command does not destructively modify production infrastructure. Common destructive patterns: terraform destroy, kubectl delete on prod namespaces, DROP TABLE, rm -rf on critical paths.",
          "model": "claude-sonnet-4-6"
        }
      ]
    }
  ]
}

Quiz