Source: Intercept and control agent behavior with hooks (Claude Agent SDK docs)
In-process hook callbacks for the Claude Agent SDK: event list by language, HookMatcher registration, output fields, decision precedence, async outputs, onFailure fail-closed mode and per-event timeout behaviour.
Contents
- What: official documentation page, Claude Code docs (Agent SDK section)
- Author: Anthropic
- Date: undated living docs (read 2026-11-14)
- Original: https://code.claude.com/docs/en/agent-sdk/hooks
Summary
The Agent SDK exposes the same hook system as Claude Code, but lets an application register hooks as callback functions in its own process instead of shell commands. The page covers which events each SDK supports, how matchers filter callbacks, what a callback can return, how several hooks combine, and what happens when a callback fails or times out.
Key claims
- Hooks come from two places: callbacks passed in
options.hooks, plus shell command hooks from settings files when the matchingsettingSources/setting_sourcesentry is enabled (it is by default). - Registration: event name → list of matchers; each matcher (
HookMatcherin Python) has an optionalmatcherpattern, a requiredhookslist of callbacks, an optionaltimeoutin seconds and an optionalonFailure(on_failure). - Matchers test only the tool name (or the event’s own filter field), never arguments; an exact list like
Write|Editor a regex like^mcp__. AWrite|Editmatcher does not catch a Bash command that writes the same file. - Python supports a subset of events (
PreToolUse,PostToolUse,PostToolUseFailure,UserPromptSubmit,Stop,SubagentStart/Stop,PreCompact,PermissionRequest,Notification); TypeScript adds many more, includingSessionStart/End,PostToolBatch,PostCompact,PreModelSwitch,PermissionDenied,TaskCompleted,ElicitationandFileChanged. - Callback arguments: event input (shared
session_id,cwd,hook_event_name;agent_id/agent_typeinside subagents), a tool-use ID that correlates pre and post events, and a context (anAbortSignalin TypeScript; reserved in Python). - Outputs: top-level
systemMessage(shown to the user, not the model) andcontinue;hookSpecificOutputwithpermissionDecision(allow,deny,ask,defer),permissionDecisionReasonandupdatedInputonPreToolUse, andadditionalContextorupdatedToolOutputonPostToolUse.{}means allow unchanged. updatedInputwithout a decision still flows through normal permission evaluation; withdeferit is ignored.deferends the turn withstop_reasontool_deferredfor later resumption.- Matching hooks run in parallel; with conflicting decisions, deny beats defer, which beats ask, which beats allow. Hooks should not depend on each other’s ordering.
- Async output (
async: true) lets the agent continue immediately; it cannot block, modify or add context. - A callback that throws or returns invalid output (or nothing) fails open by default;
onFailure: "block"makes it fail closed (TypeScript SDK v0.3.317+, Python SDK v0.2.177+).Stop,SubagentStop,TaskCompletedandTeammateIdleignore it. - Default timeout is 600 s for most events (30 s for
UserPromptSubmitand model-switch events, 10 s forMessageDisplay, a 1.5 s shutdown budget forSessionEnd). A timed-outPreToolUsecallback blocks the tool call; a timed-outStopcallback counts as no decision. - Pitfalls: hooks may not fire when the run hits
max_turns; aUserPromptSubmithook that spawns subagents can loop recursively.