← All posts

Guide

Hooks in the Claude Agent SDK

A hook in the Claude Agent SDK is an async function you pass in options.hooks, keyed by event name, that the SDK awaits when a lifecycle event fires. It receives a typed object describing the event; what it returns can allow, deny or rewrite a tool call, inject context into the model's next turn, or stop the run. There are 31 events in HOOK_EVENTS. In practice a normal single-prompt run fires seven of them.

This is the part of the SDK that is documented as a list and almost never as a behaviour. So we installed it, registered a callback on every one of the 31 events, and ran it against a toy repository until we had the thing nobody publishes: the measured order events actually arrive in, including what happens inside a subagent, what the permission flow looks like from the hook's side, and which events never showed up at all. Everything below was run against @anthropic-ai/claude-agent-sdk 0.3.231 (npm latest and next) on Node 22.22.2, on August 11, 2026. Where we could not trigger something, it says so.

If you have not written an SDK agent before, start with building an agent on the Claude Agent SDK — it covers query(), the message loop and the permission chain. This post assumes all of that and only talks about hooks.

First: two different things are called "hooks"

This is the confusion worth resolving before anything else, because the two mechanisms share event names, share an output schema, and are otherwise nothing alike.

The trap is that they are not alternatives. They both run, in the same session, for the same event. We put a PreToolUse command hook in the toy repo's .claude/settings.json that appended a line to a log file, registered SDK PreToolUse callbacks for the same run, and got three SDK callback firings and three lines in the log — one pair per tool call. The docs are explicit about why: settings files are loaded "for default query() options."

The switch is settingSources. Re-running the identical program with settingSources: [] produced the same SDK callbacks and an empty log file. So:

Everything you know about the shell flavour — the 30-plus events, the matcher grammar, exit 2 versus exit 1 — still applies on that side, and we took it apart in Claude Code hooks explained, with working configs in five copy-paste examples. From here on, "hook" means the SDK kind.

The callback signature, exactly

Three arguments, and a promise of an object. This is the whole contract:

type HookCallback = (
  input: HookInput,
  toolUseID: string | undefined,
  options: { signal: AbortSignal },
) => Promise<HookJSONOutput>

You register them per event, in an array of matchers, each holding an array of callbacks:

import { query } from '@anthropic-ai/claude-agent-sdk'

const q = query({
  prompt: 'Read src/a.js and summarise it.',
  options: {
    hooks: {
      PreToolUse: [
        {
          matcher: 'Write|Edit',
          timeout: 30,
          hooks: [
            async (input, toolUseID, { signal }) => {
              console.log(input.hook_event_name, input.tool_name, toolUseID)
              return {}
            },
          ],
        },
      ],
    },
  },
})

The three arguments, in order of how often you will care:

• input — a discriminated union over 31 member types, narrowed by hook_event_name. Every member extends BaseHookInput: session_id, transcript_path, cwd, and the optional prompt_id, permission_mode, agent_id, agent_type and effort. PreToolUseHookInput adds tool_name, tool_input and tool_use_id; PostToolUseHookInput adds tool_response and duration_ms.
• toolUseID — the correlation key between PreToolUse and PostToolUse for one call. For tool events it is the real toolu_01… id; for non-tool events we observed a session-scoped UUID (UserPromptSubmit, Stop) and, for PostToolBatch, an id of the form hook-6052628…. Do not parse it, only compare it.
• { signal } — an AbortSignal that fires when the hook times out. Pass it to your fetch. If you do not, a hung HTTP call is a hung agent for the duration of the timeout.

One field detail worth having before you write a path check. The tool_input a hook sees is the resolved input, not what the model emitted:

model emitted:   {"file_path": "src/a.js"}
hook received:   {"file_path": "/private/tmp/…/toyrepo/src/a.js"}

That is convenient — you can compare against an absolute allowlist without resolving anything yourself — and it is also the reason a naive startsWith('src/') guard silently matches nothing.

All 31 events

HOOK_EVENTS in sdk.d.ts is the authoritative list. The Python SDK exposes a subset; the TypeScript SDK exposes all of them.

The measured firing order

Here is the run. One prompt, a two-file toy repository, permissionMode: 'dontAsk', Bash in disallowedTools, and one callback registered on all 31 events that logs the elapsed milliseconds. Nothing is elided; the only lines added are the tool_use blocks from the message stream and the terminal result, for orientation.

  4903ms  UserPromptSubmit
  4907ms  --- system init  model=claude-opus-5
  7047ms  MessageDisplay
  7674ms  >>> tool_use Read
  7678ms  PreToolUse [Read]
  7696ms  PostToolUseFailure [Read]
  8236ms  >>> tool_use Read
  8236ms  PreToolUse [Read]
  8240ms  PostToolUseFailure [Read]
  8417ms  PostToolBatch
 10335ms  MessageDisplay
 11797ms  >>> tool_use Read
 11799ms  PreToolUse [Read]
 11812ms  PostToolUse [Read]
 12269ms  >>> tool_use Read
 12270ms  PreToolUse [Read]
 12277ms  PostToolUse [Read]
 12282ms  PostToolBatch
 15064ms  >>> tool_use Write
 15065ms  PreToolUse [Write]
 15092ms  PostToolUse [Write]
 15093ms  PostToolBatch
 18558ms  MessageDisplay
 18576ms  Stop
 18580ms  --- result success turns=6 usd=0.3516

Seven distinct events fired. Read the shape off it:

• UserPromptSubmit is first — before the system init message. Your hook runs before your own message loop has seen anything at all. Any per-run state a UserPromptSubmit hook needs must exist before you call query().
• PostToolUseFailure fires instead of PostToolUse, not alongside it. The first two Read calls failed (wrong paths) and produced no PostToolUse at all. An audit log built on PostToolUse alone silently omits every failed call. If you want one line per tool call, subscribe to both, or use PostToolBatch.
• PostToolBatch fires once per batch, after the last tool in it resolves. Three batches here: two failed reads, two successful reads, one write. It is the only event with a one-to-one relationship to model turns, which makes it the right hook for "inject a reminder once per turn" rather than once per tool.
• MessageDisplay is the assistant-text heartbeat, once per completed text message — three of them, at 7,047 ms, 10,335 ms and 18,558 ms, bracketing the tool batches.
• Stop lands 4 ms before the result message. If your UI reacts to both, expect them effectively simultaneously.

What a subagent looks like from outside

Second run, same setup, but the prompt asks for one general-purpose subagent. This is the trace people guess at:

  6946ms  >>> tool_use Agent
  6950ms  PreToolUse [Agent]
  6956ms  SubagentStart [general-purpose]
 11923ms  PreToolUse [Read]        <-- inside the subagent
 11938ms  PostToolUse [Read]
 11943ms  PostToolBatch            <-- inside the subagent
 16503ms  SubagentStop [general-purpose]
 16510ms  PostToolUse [Agent]
 16533ms  PostToolBatch
 22543ms  Stop

Two things fall out of that. First, the nesting is strict and complete: PreToolUse [Agent] wraps SubagentStart, which wraps the subagent's own tool events, which are followed by SubagentStop and only then PostToolUse [Agent]. Second, and more usefully: your PreToolUse hook fires for tools called inside subagents too. A guard registered once on the main query covers the whole tree. The way to tell them apart is input.agent_id, which is populated only inside a subagent — not agent_type, which is also set on the main thread of an --agent session.

PostToolBatch fires at both levels. If you use it for per-turn bookkeeping in a run with subagents, count on more of them than you have main-thread turns.

What did not fire, and why

Across five runs with all 31 events registered, 24 never fired. That is not a bug list; most of them describe situations a short headless run does not contain. But two of them are genuinely surprising, and worth more than a shrug.

The practical consequence is small but sharp: do not put session setup or resource cleanup in a hook. Setup goes before query(), teardown goes after the for await loop, in a finally. If you need on-disk session hooks to fire, that is the settings.json path — which, remember, is loaded by default.

The rest, honestly categorised:

• Needs an interactive surface. Notification — even under permissionMode: 'default' with a tool call being denied, no Notification fired. In headless SDK use there is nobody to notify, so the event that most people reach for first in the CLI is the one you are least likely to see here.
• Needs a longer or unluckier session. PreCompact / PostCompact (our runs never came close to the context window), StopFailure (no API error occurred), TeammateIdle.
• Needs a feature we did not exercise. Setup, UserPromptExpansion (needs a typed slash command or MCP prompt), Elicitation / ElicitationResult (needs an MCP server that asks for input — see building one), TaskCreated / TaskCompleted (needs the TaskCreate tool), WorktreeCreate / WorktreeRemove, CwdChanged, DirectoryAdded, FileChanged, ConfigChange, InstructionsLoaded (which did not fire even with settingSources at its default and a project directory present).
• Did not fire when we expected it to. PermissionDenied. We denied a Write from canUseTool and got PermissionRequest but no PermissionDenied; the documentation scopes that event to auto mode classifier denials, which we did not run. Do not use it as a general "a tool was blocked" signal.

The permission flow, from the hook's seat

Third run: permissionMode: 'default', a canUseTool callback that denies everything, and a prompt that wants to write a file. The order is not the one the field names suggest:

  4137ms  >>> tool_use Write
  4140ms  PreToolUse [Write]
  4151ms  canUseTool(Write) -> DENY
  4152ms  PermissionRequest [Write]
  4199ms  PostToolBatch

PreToolUse runs first, and only if it has not already decided does the call fall through to the permission flow. PermissionRequest is that fall-through — it is not fired for tools that PreToolUse, an allow rule or the permission mode already settled, which is the same short-circuit that makes canUseTool go quiet under bypassPermissions. And after a denial there is no PostToolUse, no PostToolUseFailure and no PermissionDenied: the batch simply closes.

Which leaves a real gap worth naming. There is no single event that means "this tool call did not happen." If you are building an audit trail, the honest reconstruction is PreToolUse minus PostToolUse minus PostToolUseFailure, or the tool_calls[] array on PostToolBatch, which carries an optional tool_response per call.

What a hook can return

Return {} to observe and change nothing. Everything else lives in two places: a handful of top-level fields accepted on every event, and one hookSpecificOutput object whose shape depends on the event.

return {
  hookSpecificOutput: {
    hookEventName: 'PreToolUse',
    permissionDecision: 'deny',
    permissionDecisionReason:
      'Writing to disk is not permitted in this run. Print the content in your reply instead.',
  },
}

  4790ms  >>> tool_use Read {"file_path":"src/b.js"}
  4791ms  PreToolUse [Read b.js] -> continue:false
  4795ms  PostToolUse [Read]
  4848ms  --- result success turns=3 is_error=false result=""

  2925ms  A: matcher "Read" #1   (sleeps 300ms)
  2926ms  B: matcher "Read" #2
  2926ms  C: matcher "Rea.*"
  2926ms  D: no matcher
  3228ms  A: matcher "Read" #1 wakes
  3239ms  PostToolUse [Read]

  3544ms  >>> tool_use Read
  3545ms  PreToolUse [Read] -> sleeping 3000ms
  6551ms  PreToolUse [Read] -> awake, returning allow
  6571ms  PostToolUse [Read]

 10219ms  D: no matcher
 10219ms  E: matcher "Write" -- THROWS
 10234ms  PostToolUse [Write]
 13326ms  --- result success turns=4 is_error=false

const guard: HookCallback = async (input) => {
  try {
    if (await isDangerous(input)) {
      return {
        hookSpecificOutput: {
          hookEventName: 'PreToolUse',
          permissionDecision: 'deny',
          permissionDecisionReason: 'Blocked by policy: writes outside the workspace.',
        },
      }
    }
    return {}
  } catch (err) {
    if (err instanceof Error && err.name === 'AbortError') return {}
    metrics.increment('hook.guard.error')
    return {
      hookSpecificOutput: {
        hookEventName: 'PreToolUse',
        permissionDecision: 'deny',
        permissionDecisionReason: 'Policy check failed to run; denying by default.',
      },
    }
  }
}