Source:Anthropic official docs — Hooks guide + Anthropic official docs — Hooks reference + Anthropic first-party blog — Claude Code power user customization: How to configure hooks (2026-07-16 ingest — overlap-checked against this article per claude-ai/_research-agenda.md; contributed 7 deltas not previously documented here, most notably resolving the default-timeout Open Question below) + anthropics/claude-code release notes v2.1.248–v2.1.284 + code.claude.com changelog (ai-research/claude-code-docs-changelog-2026-08-28.md) and W36 What’s New digest (ai-research/claude-code-docs-whats-new-w36-2026-09-18.md) + hooks-reference watchlist snapshot (ai-research/watchlist-snapshots/code-claude-com-docs-en-hooks-2026-09-20.md)
Type: Product Feature
Product: Claude Code
Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, or LLM prompts that execute at specific points in Claude Code’s lifecycle. They give deterministic control — actions always fire instead of depending on the LLM choosing to run them. Use hooks to enforce project rules (block edits to protected files), automate repetitive work (auto-format on save), inject context (re-load CLAUDE.md after compaction), or wire Claude Code into existing tools (audit logs, notifications, CI).
Lifecycle events (when hooks fire)
Event
When it fires
SessionStart
A session begins or resumes. Resume hooks receive session staleness and the estimated re-cache cost (v2.1.251+)
Setup
Runs with --init-only, or when --init/--maintenance are used in -p mode. For one-time CI/script preparation. Matcher values: init, maintenance
UserPromptSubmit
User submits a prompt, before Claude processes it
UserPromptExpansion
A slash command expands; can block the expansion
PreToolUse
Before a tool call executes; can block, allow, deny, ask, or defer
PermissionRequest
When a permission dialog appears
PermissionDenied
When a tool call is auto-denied; can allow retry
PostToolUse
After a tool call succeeds
PostToolUseFailure
After a tool call fails
PostToolBatch
After parallel tool calls resolve
SubagentStart / SubagentStop
Subagent spawn / finish
TaskCreated / TaskCompleted
Tasks created or marked complete (used by Agent Teams)
Stop / StopFailure
Claude finishes or turn ends with API error
TeammateIdle
An [[claude-ai/agent-teams
InstructionsLoaded
CLAUDE.md or .claude/rules files load
ConfigChange
Configuration files change
CwdChanged
Working directory changes
FileChanged
Watched files change on disk
WorktreeCreate / WorktreeRemove
Worktrees created or removed
PreCompact / PostCompact
Before / after context compaction
Elicitation / ElicitationResult
MCP server input requests and responses
Notification
Claude Code sends a notification (waiting for input/permission)
PreModelSwitch
Before the active model changes; can block, confirm, or annotate the switch (v2.1.251+)
PostModelSwitch
After the session’s model changes; can add context for Claude (v2.1.251+)
MessageDisplay
Claude Code is about to display an assistant message; hook can transform or suppress the text (v2.1.152+)
SessionEnd
Session terminates; matcher = termination reason. Cannot block — side effects only
DirectoryAdded
A new working directory is registered mid-session via /add-dir or the SDK register_repo_root control request (v2.1.219+). Distinct from CwdChanged — fires when the session’s directory set expands, not when the active cwd changes
Hook handler types
Type
What it does
command
Runs a shell script. Receives JSON on stdin, returns exit codes
http
POSTs JSON to a URL
mcp_tool
Calls a tool on a pre-connected MCP server
prompt
Sends a prompt to Claude for evaluation (judgment-based gating)
agent
Spawns a subagent for verification
Common hook input fields
All hooks receive JSON via stdin. Fields present across nearly every event: session_id, transcript_path, cwd, permission_mode, hook_event_name, and (v2.1.257+) scratchpad_dir. Tool-related hooks (PreToolUse, PostToolUse, PermissionRequest, etc.) additionally receive tool_name and tool_input. Individual events layer on further extras documented throughout the “Recent additions” sections below — agent_id/agent_type inside subagent turns, prompt_id, effort.level, and others.
scratchpad_dir (v2.1.257+) — path to the session’s scratchpad directory, where Claude keeps temporary working files. Absent when the session has no scratchpad or the temp directory is unavailable.
Exit codes (command hooks)
Exit 0 — success; JSON output processed.
Exit 2 — blocking error; stderr is fed back to Claude as feedback. The pending tool call (or task creation/completion) is blocked.
Other codes — non-blocking error; execution continues.
Per-event exit code 2 behavior
Event
Blocks?
Effect
PreToolUse
Yes
Blocks tool call
PermissionRequest
Yes
Denies permission
UserPromptSubmit
Yes
Blocks prompt, erases it
UserPromptExpansion
Yes
Blocks the expansion
Stop
Yes
Prevents Claude from stopping
SubagentStop
Yes
Prevents the subagent from stopping
TeammateIdle
Yes
Prevents the teammate from going idle
TaskCreated
Yes
Rolls back the task creation
TaskCompleted
Yes
Prevents the task from being marked as completed
ConfigChange
Yes
Blocks the configuration change (except policy_settings)
PostToolBatch
Yes
Stops the agentic loop before the next model call
PreCompact
Yes
Blocks compaction
Elicitation
Yes
Denies the elicitation
ElicitationResult
Yes
Blocks the response (action becomes decline)
WorktreeCreate
Yes
Any non-zero exit fails creation
PostToolUse
No
Shows stderr to Claude
PostToolUseFailure
No
Shows stderr to Claude
PermissionDenied
No
Ignored; use hookSpecificOutput.retry: true to let model retry
terminalSequence (v2.1.141+) — a terminal escape sequence for Claude Code to emit on your behalf: desktop notification, window title, or bell. Restricted to OSC 0/1/2/9/99/777 and BEL. Race-free and works inside tmux, GNU screen, and on Windows. Use this instead of writing to /dev/tty, which is unavailable to command hooks as of v2.1.139. Quick invocation: jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
Decision control varies by event:
Top-level decision applies to UserPromptSubmit, PostToolUse, Stop, PreCompact.
Path return for WorktreeCreate (command prints path to stdout).
No decision control for SessionEnd, PostCompact, FileChanged, Notification.
Execution semantics
Default timeout: 60 seconds per hook, configurable per hook. The settings field for overriding it isn’t named in the source that surfaced this — flagged in Open Questions.
Parallel execution. When multiple hooks match the same event (e.g. two PostToolUse hooks with overlapping matchers, or the same event registered at user, project, and plugin scope), they run concurrently rather than sequentially.
Automatic deduplication. Identical hook commands registered more than once for the same event are deduplicated so they don’t fire twice.
Async hooks
Command hooks support background execution:
"async": true — runs without blocking; output discarded.
"asyncRewake": true — runs in background, but if it exits with code 2, Claude is woken with stderr/stdout shown as a system reminder. Useful for long-running checks that surface findings later without blocking the current turn.
The /hooks slash command opens a read-only browser listing all configured hooks, the matching event, matcher, type, and source file. Use it to verify configuration; edit the JSON to make changes.
Safeguard: direct edits to hook configuration files require review in the /hooks menu before they take effect — this prevents a plugin, skill, or other process from silently adding a hook to your configuration without your seeing it first. Hooks otherwise execute arbitrary shell commands at your own user permission level, so treat hook scripts like any other code you’d run locally: validate and sanitize stdin input, quote shell variables, use absolute paths, and avoid letting a hook touch .env or credential files unless that’s specifically its job.
Matchers
Filter hooks by tool name, event type, or regex:
"Bash" — match a single tool
"Edit|Write" — match either of two tools
"mcp__memory__.*" — regex match against MCP tools
"if": "Bash(rm *)" — further filter using permission rule syntax
Case sensitive — "bash" will not match the Bash tool.
Common patterns
Desktop notification when Claude needs input — Notification event + osascript (mac), notify-send (Linux), or PowerShell MessageBox (Windows).
Auto-format on edit — PostToolUse with matcher "Edit|Write", command pipes file path through jq to prettier --write.
Block edits to protected files — PreToolUse with permissionDecision: "deny" for paths matching .env*, secrets/**, etc.
Re-inject context after compaction — PostCompact reads CLAUDE.md and feeds it back as additionalContext.
Audit configuration changes — ConfigChange event logs all settings.json edits to a versioned audit log.
Reload env when files change — FileChanged watches .env / .envrc and re-sources them.
Auto-approve specific permissions — PermissionRequest returns behavior: "allow" for predictable cases.
Defer tool calls — permissionDecision: "defer" pauses execution for an external UI to make the decision (requires -p flag).
Prompt-based and agent-based hooks
For decisions requiring judgment rather than deterministic rules:
type: "prompt" — sends a prompt to a Claude model, returns its decision.
type: "agent" — spawns a subagent for verification or analysis before allowing the action through. Not on PermissionRequest since v2.1.280 (2026-09-22): an agent-type hook no longer runs there, “since its answer could never allow or deny the request”; Claude Code shows an error pointing to command or http hooks.
These are slower and more expensive than command/HTTP hooks but handle ambiguous cases (e.g., “is this commit message acceptable?”) that pattern-matching cannot.
Permission relay & defer
Hooks can update permission rules dynamically — add or remove rules, change permission modes, modify tool input. Combined with permissionDecision: "defer", this lets external systems (e.g., a Channel forwarding to a phone) make the call.
Debugging
Every hook receives transcript_path, pointing to the session’s full JSONL history — no extra setup needed. Watch it live: tail -f /path/to/transcript.jsonl | jq.
Transcripts show what Claude did, not why your hook approved or blocked it. For hook-specific debugging, wrap the actual tool command in a small logging script that captures stdin, the firing event, and the exit code:
Reference it in the hook’s command field ahead of the real command: log-wrapper.sh your-tool-command.py.
Recent additions (v2.1.246–v2.1.284, August 25 – September 28 2026)
From the anthropics/claude-code release notes, cross-checked against the code.claude.com changelog (ai-research/claude-code-docs-changelog-2026-08-28.md) and the W36 What’s New digest; digests: W35 · W36 · W37 · W38 · W39 · W40. The watch-feed copy of v2.1.281 is truncated; its remaining items were read from https://github.com/anthropics/claude-code/releases/tag/v2.1.281.
2026-08-28 — v2.1.251: model-switch hooks. New PreModelSwitch and PostModelSwitch events can block, confirm or annotate a model switch. Per the W36 digest, a PreModelSwitch hook can block a model switch you request, and a PostModelSwitch hook can add context for Claude after the session’s model changes. SessionStart resume hooks now receive session staleness and the estimated re-cache cost; a hook could use them to warn on, or refuse, resuming a session that has sat idle long enough that re-caching would be expensive.^[inferred] Model switches had been a state change hooks could not observe or gate.^[inferred] The same release changed CLAUDE_CODE_SUBAGENT_MODEL to set only the default subagent model (an agent definition’s model: and an explicit per-spawn model now take precedence), which makes a PreModelSwitch hook the deterministic place to enforce a model policy.^[inferred] Sketch from the 2026-09-20 sweep, unverified — the sources give neither what this event’s matcher is compared against nor its output schema:
// Block model switches to Fable in cost-sensitive projects (unverified sketch){ "hooks": { "PreModelSwitch": [{ "matcher": "fable", "hooks": [{"type": "command", "command": "echo '{\"decision\": \"block\", \"reason\": \"Fable not approved for this project\"}'"}] }] }}
2026-09-22 — v2.1.280: no agent hooks on PermissionRequest. An agent-type hook no longer runs there; an error points to command or http hooks. The UserPromptSubmit hook timeout notice now names the hook.
2026-09-28 — v2.1.284: {"decision":"block"} works on elicitation hooks. It was ignored on Elicitation and ElicitationResult; it now declines the MCP elicitation, as exit code 2 does. Failed hooks’ stderr is no longer dropped from the debug log when they also wrote stdout, and failed hooks log their status code.
v2.1.248: stdout that looks like a {…} object but isn’t valid JSON is reported as a hook error with the parse message instead of being treated as plain text; background sessions name a PermissionRequest/PreToolUse hook that prints an invalid answer in the claude agents row.
v2.1.259: blocking Stop hooks no longer cause the next turn to lose the model’s reasoning or, on some models, miss the prompt cache.
v2.1.268:PermissionRequest hooks fire in --print mode; CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS now extends SessionEnd hooks that have no per-hook timeout (they had been cancelled after 1.5 seconds); --continue / --resume show the conversation immediately instead of waiting for SessionStart hooks.
v2.1.271: while a SessionStart, UserPromptSubmit, PreToolUse or SessionEnd hook runs, the spinner says so with elapsed time, and Esc cancels a prompt waiting on a SessionStart hook.
v2.1.274: Stop prompt hooks’ repeat blocks name the condition with a 500-character label instead of re-sending the whole prompt.
v2.1.275: SubagentStop hooks with a specific matcher no longer fire for subagents whose agent type is empty.
v2.1.281:mcp_tool hooks on blocking events (PreToolUse and similar) wait for their MCP server to connect, up to the MCP connect timeout, instead of being skipped; the /hooks detail screen says what kind of hook it is and where to change it.
Practical: in unattended sessions, a PreModelSwitch hook can block or require confirmation for a model switch nobody is watching.
Recent additions (2026-09-20 watchlist sweep)
Source: ai-research/watchlist-snapshots/code-claude-com-docs-en-hooks-2026-09-20.md (the snapshot also added the scratchpad_dir input field, covered above).
Admin controls — allowManagedHooksOnly
Enterprise admins can restrict which hooks are permitted with allowManagedHooksOnly. When enabled:
User-level, project-level, project-local, and plain plugin hooks are blocked.
Hooks from force-enabled managed settings plugins are exempt.
Also narrows statusLine, fileSuggestion, and subagentStatusLine hook sources.
Disables command-source plugins unless disableCommandPluginSources: false is also set.
HTTP allowlists — allowedHttpHookUrls and httpHookAllowedEnvVars
Two new managed settings for HTTP hooks:
allowedHttpHookUrls — merged allowlist gate for HTTP hook handlers. Any HTTP hook whose URL does not match an entry in this list is silently skipped, regardless of which settings layer registered it.
httpHookAllowedEnvVars — restricts which environment variables can be interpolated into hook headers (e.g., Authorization: Bearer $TOKEN). Only env vars in this list are permitted as $VAR substitutions in hook header values.
Bash pattern matching table
The hooks reference now includes a reference table documenting how common shell patterns are recognized by the hook if field’s pattern-matching syntax: compound if statements, $() command substitutions, && chaining, $VAR expansion, and related constructs, with 7 example patterns and their match behavior.
Recent additions (v2.1.210–v2.1.212, July 2026)
New hook behavior from v2.1.210–v2.1.212, sourced from ai-research/claude-code-docs-changelog-2026-07-17.md:
Hook callback timeout was misreported as user rejection (v2.1.210 fix). A hook that timed out (exceeded its timeout window) was previously reporting back to the model as a “user rejection” of the tool call — this caused unattended sessions to stop and wait for human input when a hook simply ran too long. Now correctly reported as a timeout, not a user rejection. Relevant to hooks with async: false (synchronous/blocking) that wrap slow external calls.
continue: false hook output no longer dropped mid-stream (v2.1.211 fix). A PreToolUse hook returning {"continue": false} now reliably halts the agentic loop. Previously, if the hook’s output arrived between two streaming chunks of Claude’s response, the halt signal was silently ignored and the loop continued. This was a timing-dependent correctness bug — hooks whose continue: false seemed intermittently ineffective should be re-tested on v2.1.211+.
Auto mode no longer overrides PreToolUse hook ask decision (v2.1.211 fix). A PreToolUse hook returning permissionDecision: "ask" for unsandboxed Bash was previously being overridden by the auto-mode classifier’s own verdict — the hook asked but auto mode’s permission grant silently bypassed it. Now the hook’s ask decision floors the outcome at a human permission prompt regardless of auto mode’s classifier verdict. This restores the expected hook authority: if a hook says “ask a human,” auto mode cannot override that.
Recent additions (2026-07-12 watchlist sweep)
New hooks reference content as of this sweep, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-hooks-2026-07-12.md:
agent_id and agent_type as common hook input fields (subagent context). Hook events now include agent_id (unique identifier for the subagent) and agent_type (agent name, e.g. "Explore", "security-reviewer", or plugin-scoped like "my-plugin:reviewer") in the JSON input when the hook fires inside a subagent turn (i.e., when Claude Code is running with --agent or as a spawned subagent). These fields are distinct from the per-event fields on agent-teams events (TeammateIdle, TaskCreated, TaskCompleted) which have their own schemas.
Recent additions (2026-07-05 watchlist sweep)
New hook-reference content in Claude Code as of v2.1.196–v2.1.199, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-hooks-2026-07-05.md:
prompt_id in common hook input fields (v2.1.196+). All hook events now include a prompt_id UUID in the JSON input. The value identifies the user prompt currently being processed and matches the prompt.id attribute on OpenTelemetry events, enabling correlation between hook output and telemetry for a single prompt. Absent until first user input.
CLAUDE_CODE_BRIDGE_SESSION_ID in hook environment (v2.1.199+). Set to the Remote Control session ID while the local session has an active Remote Control connection; unset otherwise. Complements the existing $CLAUDE_CODE_REMOTE (set in web environments).
PostToolBatch in exit-code-2 table.PostToolBatch exit code 2 stops the agentic loop before the next model call — the first time this event has been documented with blocking semantics. The per-event table above now includes it alongside the other blocking events.
Additional events in exit-code-2 table. The table now explicitly covers: UserPromptExpansion (blocks expansion), SubagentStop (prevents subagent stopping), ConfigChange (blocks config change except policy_settings), Elicitation (denies), ElicitationResult (blocks response), PreCompact (blocks compaction), plus all non-blocking events that were previously implied but not enumerated.
Hyphen support in exact-match matchers documented (v2.1.195+). Hyphens are now in the exact-match character set. On earlier versions (<v2.1.195), a hyphenated matcher like code-reviewer is evaluated as a regex — anchor it as ^code-reviewer$ for pre-v2.1.195 compatibility.
Recent additions (2026-07-03, v2.1.199)
SessionStart, Setup, and SubagentStart hooks now surface stderr on code-2 exit. Previously, when these three hooks exited with code 2, their stderr output was silently discarded — the blocking signal fired but the error message was invisible. Fixed in v2.1.199: the error is now shown in the transcript, making hook failures diagnosable without adding extra logging. This is a silent regression fix affecting the three startup-phase events; PreToolUse, PostToolUse, and other events were already surfacing stderr correctly.
Recent additions (2026-06-28 watchlist sweep)
Per-event exit code 2 behavior table. The official hooks reference now documents exactly which events block vs. which ones don’t when a hook returns exit code 2. See the “Per-event exit code 2 behavior” table in the Exit codes section above. Key distinctions: UserPromptSubmit exit 2 erases the prompt (not just blocks it); WorktreeCreate fails on any non-zero exit (not just 2); PostToolUse and StopFailure are non-blocking (exit 2 shows stderr to Claude without stopping the turn). This was previously implied by individual event descriptions but not consolidated into a single table.
Recent additions (2026-06-14 watchlist sweep)
CLAUDE_ENV_FILE — persisting environment variables across the session. A CLAUDE_ENV_FILE path is now exposed in the hook environment for SessionStart, Setup, CwdChanged, and FileChanged hooks. Write export VAR=value lines to this file to make environment variables available for the rest of the session — including to Claude’s Bash tool. This is the documented pattern for direnv-style setups where a SessionStart hook should set NODE_ENV, PATH entries, or secrets:
$CLAUDE_CODE_REMOTE — detect web environment. Set to "true" when Claude Code is running in the web environment (cloud session on claude.ai). Hooks can branch on this to skip operations that require local filesystem access (e.g., writing to ~/.local/).
$ARGUMENTS placeholder in prompt hooks. The type: "prompt" hook’s prompt field now supports a $ARGUMENTS placeholder that injects the hook event context (tool name, arguments, etc.) into the prompt text sent to Claude for evaluation.
updatedInput in PreToolUse and PermissionRequest hookSpecificOutput. Hooks on these events can rewrite the tool’s input before execution by returning updatedInput alongside (or instead of) a permissionDecision. Distinct from "deny" (which blocks the call) — updatedInput passes through with modified parameters. Use case: sanitize or redirect file paths, cap dangerous argument ranges, or inject audit metadata transparently.
Path placeholders formalized. The reference now lists ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT}, and ${CLAUDE_PLUGIN_DATA} as a distinct “Path placeholders” group that auto-substitute in hook command strings and MCP tool input fields. Previously scattered; now a named section.
Recent additions (v2.1.169, June 8 2026 — post-session hook)
New post-session lifecycle hook (self-hosted runner). Runs after the session ends and before the workspace is deleted — the place to snapshot uncommitted work or export logs on a self-hosted runner. The child-process SIGTERM→SIGKILL window is now configurable (default unchanged at 5s). Distinct from SessionEnd (which fires client-side at session close): post-session is a runner-side teardown hook on the self-hosted runner. See the Week 25 digest.
Recent additions (v2.1.143, May 15 2026)
Stop hook block cap (v2.1.143) — a Stop hook that blocks repeatedly (exit 2 every turn) will now cause Claude to end the turn with a warning after 8 consecutive blocks. Override the default with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=<N>. Prevents runaway loops where a misconfigured Stop hook locks the session indefinitely.
Recent additions (2026-05-17 watchlist sweep)
terminalSequence JSON output field (v2.1.141) — see JSON output section above. Hooks can now emit desktop notifications, window title changes, and bell by returning terminalSequence in their JSON output. Replaces direct /dev/tty writes, which are unavailable to hooks as of v2.1.139.
Command hooks run without controlling terminal (v2.1.139) — as of v2.1.139 on macOS and Linux, command hooks run in their own session without a controlling terminal. Neither the hook process nor any child process can open /dev/tty or send escape sequences directly to Claude Code’s terminal. Use systemMessage in JSON output to surface text; use terminalSequence for notifications/title/bell. Windows has no /dev/tty regardless of version.
Agent team hook input schemas — per-event extra fields (corrected in 2026-05-24 sweep — the 2026-05-17 snapshot had wrong field names):
TaskCreated: receives task_name + task_description (no task_id, no task_title)
TaskCompleted: receives task_id + task_name (no task_title, no task_description)
TeammateIdle: receives agent_type + idle_reason only (no agent_id)
Exit code 2 for TaskCreated/TaskCompleted rolls back the action; exit code 2 for TeammateIdle keeps the teammate working. {"continue": false, "stopReason": "..."} stops the teammate entirely (matching Stop hook semantics).
Recent additions (2026-05-24 watchlist sweep)
Field name corrections for agent team hook events — the 2026-05-17 snapshot had incorrect field names. Corrected values: TaskCreated receives task_name + task_description (not task_id/task_title); TaskCompleted receives task_id + task_name; TeammateIdle receives agent_type + idle_reason only (no agent_id). See Lifecycle events table and agent-teams section above.
statusMessage JSON output field — hooks can return {"statusMessage": "..."} to set the spinner/status-line text visible in the TUI during processing. UI-only; not injected into Claude’s context (unlike systemMessage).
once field (skill hooks only) — "once": true in a skill-bundled hook causes it to fire only on the first occurrence of the event per session, not every time. Useful for session-initialization hooks.
Exec form for command hooks — "command": ["cmd", "arg1", "arg2"] array syntax bypasses shell interpolation. Recommended when hook arguments contain external data (e.g., file paths from tool_input) that could contain shell metacharacters.
watchPaths in SessionStart input — the session start payload now includes the list of files registered for FileChanged watching, so SessionStart hooks can see which watchers are active.
initialUserMessage in SessionStart input — the session start payload now includes the first user message (or empty string). Useful for session-title hooks that generate a title from the initial prompt.
suppressOriginalPrompt in UserPromptSubmit hookSpecificOutput — set to true to prevent the user’s raw prompt from being forwarded to Claude; only the hook’s additionalContext is seen by the model. For privacy-filtering or prompt-rewriting workflows.
Recent additions (2026-06-09, events-table gap fix)
SessionEnd event documented — fires when a session terminates. The matcher value is the termination reason: clear (/clear), resume (session saved via --resume/--continue//resume), logout, prompt_input_exit (-p mode exit), bypass_permissions_disabled, or other. Input adds a reason field alongside the common session_id/transcript_path/cwd fields. SessionEnd cannot block — the exit code is ignored (on exit 2, stderr is shown to the user only); use it purely for side effects: session logging, cleanup, analytics, saving state. Source: ai-research/claude-code-docs-hooks-sessionend-2026-06-09.md.
Recent additions (2026-06-12, v2.1.176)
if condition fix for Read/Edit/Write tool paths. Hook if conditions using permission rule syntax on file-path tools — e.g. Edit(src/**), Read(~/.ssh/**), Read(.env) — now match correctly. Prior to v2.1.176, these patterns silently failed on the three file-path tools (Read, Edit, Write), meaning hooks gated on file paths were not firing as documented. If you wrote path-gated hooks on Read/Edit/Write and found them unreliable, update to v2.1.176. See the Week 26 digest.
Recent additions (2026-06-24, v2.1.191)
Comma-separated hook matchers now fire (v2.1.191 fix). Hooks configured with a comma-separated matcher list — e.g. "Bash,PowerShell" — were silently never firing before v2.1.191. The single-tool ("Bash"), alternation ("Edit|Write"), and regex ("mcp__memory__.*") matcher forms were unaffected; only the comma-joined list form was broken. If you relied on a multi-tool comma matcher and found the hook dead, update to v2.1.191 and re-test. See the Week 26 digest.
Recent additions (2026-06-04, v2.1.163)
Stop and SubagentStop hooks: hookSpecificOutput.additionalContext for feedback loops (v2.1.163) — Stop and SubagentStop hooks can now return hookSpecificOutput.additionalContext to inject feedback into Claude’s turn and keep it going, without being labeled a “hook error.” Previously, exit code 2 from a Stop hook blocked the turn but the error label was misleading for feedback use cases. Example pattern: a Stop hook that checks whether the output compiles and, if not, returns additionalContext: "your last diff doesn't compile — fix it before finishing" to drive a correction pass. This is distinct from the block-cap behavior (8 consecutive blocks triggers a forced exit, v2.1.143) — additionalContext is for cooperative feedback, not veto. Sources: raw/anthropic-watch-claude-code-tag-v2-1-163.md; ai-research/claude-code-docs-changelog-2026-06-05.md.
Recent additions (2026-05-31 watchlist sweep)
sessionTitle for SessionStart hookSpecificOutput — SessionStart hooks can now emit sessionTitle to set the session title (same effect as /rename). Applies only when source is "startup" or "resume"; ignored on "clear" and "compact". Read the existing session_title input field first to avoid overwriting a title the user set with --name. Distinct from UserPromptSubmit.sessionTitle (W15) — that fires on each prompt; this fires once at session startup.
reloadSkills for SessionStart hookSpecificOutput — Boolean. When true, Claude Code re-scans skill and command directories after all SessionStart hooks finish, making skills the hook installed available from the first prompt. Without it, files the hook writes into ~/.claude/skills/ only appear in the next session (skill discovery runs before SessionStart hooks complete). Example: echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
MessageDisplay.displayContent — The MessageDisplay hook (v2.1.152+, already in the events table above) can return {"hookSpecificOutput": {"hookEventName": "MessageDisplay", "displayContent": "..."}} to replace the text shown on screen. Display-only: the transcript and what Claude sees internally keep the original text. No matcher support — fires on every assistant message. Use for terminal markup, output filtering, or rendered syntax highlighting.
Recent additions (May 2026 watchlist sweep)
$CLAUDE_EFFORT environment variable (2026-05-10 sweep, W19, v2.1.128+) — hooks now receive the active effort level via two surfaces: (1) effort.level JSON input field in the hook’s stdin payload, alongside existing fields like tool_name and tool_input; (2) $CLAUDE_EFFORT environment variable set in the hook’s process environment and also available in Bash tool subprocess commands. Values: low, medium, high, xhigh, max. Practical use: gate expensive hook logic behind effort level, or include the level in audit logs. $CLAUDE_CODE_SESSION_ID also now set in Bash subprocess environment (matching the session_id passed to hooks).
PostToolUseupdatedToolOutput for any tool (2026-05-10 sweep, W18) — PostToolUse hooks can replace tool output for any tool via hookSpecificOutput.updatedToolOutput, not only MCP tools. Enables post-processing of any tool’s output before Claude sees it.
Setup hook event (2026-05-03 sweep) — fires when Claude Code starts with --init-only, or when --init/--maintenance flags are used in -p (print) mode. Intended for one-time CI/script preparation that should not repeat every session. Matcher values: init (fires on --init) and maintenance (fires on --maintenance). This event explains why --init and --maintenance are documented as “print mode only” in the CLI reference — they route through the Setup hook event, which only makes sense in non-interactive flows.
if field on individual hooks (v2.1.85, Week 13) — uses permission rule syntax to scope a hook to a specific call pattern. Pre-commit linter only spawns for Bash(git commit *) instead of every Bash call. Already shown in Matchers above.
CwdChanged and FileChanged events (Week 13) — direnv-style setups (re-source .envrc on directory change, watch config files for hot-reload).
PermissionDenied event (Week 14) — fires when auto mode’s classifier denies a tool call. Return retry: true from the hook to let Claude try a different approach; /permissions → Recent retries manually with r.
defer exit-with-payload in -p mode (Week 14) — permissionDecision: "defer" in -p (print-mode / SDK) sessions pauses at the tool call and exits with a deferred_tool_use payload so an SDK app or custom UI can surface the decision; resume with --resume. The non--p defer path still routes through normal permission UI.
Hook output > 50K → disk (Week 14) — large stdout/stderr from a hook is saved to disk with a path + preview instead of injected into context. Prevents one chatty hook from blowing up your conversation budget.
disableSkillShellExecution setting (Week 14) — top-level lockdown switch that blocks inline shell from skills, slash commands, and plugin commands. Useful for tightly-scoped enterprise environments where only explicitly-configured hooks should ever run shells.
UserPromptSubmit.sessionTitle (Week 15) — hooks on UserPromptSubmit can set the session title via hookSpecificOutput.sessionTitle. Set programmatic titles based on the first user message instead of the auto-generated default.
Recent additions (2026-07-16 watchlist sweep)
v2.1.207 — Shell-form plugin hooks no longer substitute ${user_config.*}. Plugin hooks can reference ${user_config.*} values, but as of v2.1.207 this only substitutes in exec form (command + args), not shell form. A shell-form hook whose command references ${user_config.*} now fails with an error instead of running — read $CLAUDE_PLUGIN_OPTION_<KEY> (e.g. $CLAUDE_PLUGIN_OPTION_WEBHOOK_URL) from a shell-form hook instead, or switch to exec form. Before v2.1.207, shell-form hooks substituted these values directly — a shell-injection-shaped gap given shell form re-parses the whole command string. The same exec-form-only restriction shipped the same release for plugin monitor commands and MCP headersHelper (see Plugins and Marketplaces).
Key Takeaways
Hooks turn “Claude usually does X” into “X always happens” — the deterministic backbone for project rules, formatting, and security policy.
Hooks run with a 60-second default timeout (configurable per hook), execute in parallel when multiple match the same event, and identical commands are automatically deduplicated.
Five handler types cover the spectrum from deterministic (command, http, mcp_tool) to judgment-based (prompt, agent).
Exit code 2 is the blocking signal: stderr is fed to Claude as feedback. Any other non-zero exit is non-blocking.
The /hooks menu is read-only — edit settings JSON to add or remove hooks.
Async hooks (async, asyncRewake) decouple long-running checks from the current turn while still surfacing findings.
Decision control depends on event: top-level decision for some, permissionDecision for PreToolUse, no control at all for terminal events.
Hooks are layered — user, project, project-local (gitignored), plus plugins/skills/agents — and all fire when their event matches.
Try It
Notification on idle — paste this into ~/.claude/settings.json (mac):
{ "hooks": { "Notification": [ { "matcher": "", "hooks": [{"type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"}] } ] }}
Run /hooks in any session to confirm it registered.
Ask Claude to do something requiring permission, switch tabs — desktop notification fires.
Add an auto-format hook to a project’s .claude/settings.json:
Week 42 release digest — UserPromptSubmit now runs before skill expansion (v2.1.299); prompt.change Mods hook (v2.1.300).
Security-Guidance Plugin — a production feature built entirely from hooks (SessionStart bootstrap, UserPromptSubmit baseline, PostToolUse on edits + git commit/push, Stop end-of-turn review).
A disableAllHooks: true key in any settings file disables all user-level and project-level hooks for the session. Managed hooks (from admin policy via force-enabled plugins) are exempt and still fire.
{ "disableAllHooks": true}
For a single run without editing settings files:
claude --settings '{"disableAllHooks": true}'
Distinct from allowManagedHooksOnly (which keeps managed hooks and blocks everything else) — disableAllHooks blocks even managed-source hooks registered by non-force-enabled plugins.
SessionStart resume cost field names resolved
The official hooks reference now documents the SessionStart input fields for resume staleness and cache-cost estimation (v2.1.251+):
Field
Type
Description
seconds_since_last_response
number
Seconds since the session’s last assistant response
context_tokens
number
Token count in the session context at resume
prompt_cache_likely_expired
boolean
Whether the prompt cache is likely stale
estimated_cache_write_usd
number
Estimated USD cost to re-prime the cache
These appear only when source: "resume" on the SessionStart hook. Use seconds_since_last_response + prompt_cache_likely_expired together to decide whether to start fresh (clear + restart) vs. resuming — a stale cache with many tokens can cost more to re-prime than the session saves.
onFailure: "block" for command and HTTP hooks (v2.1.295)
A new declarative field for command and HTTP hooks. When "onFailure": "block" is set, a hook failure (non-zero exit code for command hooks, non-2xx for HTTP hooks) automatically blocks the underlying action — equivalent to exit code 2 but configured in the hook definition rather than the hook script.
Use case: when the hook script itself may fail unexpectedly (missing binary, network error, crash), onFailure: "block" makes the failure safe-by-default rather than letting the tool call proceed unvalidated. Previously, a crashed hook would silently allow the underlying action.
Security fix: prompt and agent hooks instruction bypass (v2.1.294)
A bug where prompt and agent type hooks written as instructions could allow actions they were supposed to block is fixed. Additionally, the judgment of prompt hooks on Stop and SubagentStop events is improved so Claude is less likely to stop early when a prompt hook returns feedback. Update to v2.1.294+ if you use prompt or agent hooks for blocking policy.
agent.spawn for teammates (v2.1.289)
Teammates can now be spawned dynamically mid-session via agent.spawn, not only at session initialization. $.agent.list() now returns idle and waiting as distinct states.
UserPromptSubmit hooks now run before skill expansion (v2.1.299)
UserPromptSubmit hooks now fire before skills are expanded into the prompt. Previously they ran after skill expansion, meaning the hook saw the expanded content. Now the hook receives the raw user prompt text.
Migration: if you have a UserPromptSubmit hook that matched against skill-expanded text, update the matcher or hook logic to work against the pre-expansion prompt instead. UserPromptExpansion continues to cover the expansion step itself.
prompt.change mod hook (v2.1.300)
A new Mods hook event: prompt.change. Plugins using the Claude Mods system can listen to prompt.change to intercept and modify the user’s prompt before it is sent to the model. Distinct from prompt.autocomplete (W41 v2.1.292), which fires on autocomplete suggestion events.
By default, files referenced with @ in a prompt are inserted into the prompt without a tool call, so PreToolUse hooks (including those matching Read) don’t fire for @-mentioned files. Two options:
Block specific paths: add a Read deny rule.
Disable file-mention insertion: set CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 in your shell, user settings.json, or managed settings. Claude receives the mentioned paths with a note to read them using its file tools, and matching PreToolUse hooks then fire. Ignored in project and local settings.
Additional PostToolUse fields
classifierContext (v2.1.236+) — provides auto-mode classifier context for the tool call in PostToolUse hook input.
tool_response.bashEditDiff (v2.1.269+) — provides a diff of Bash edit operations in PostToolUse hook input.
Skill hook limits per source per session (v2.1.304)
A single skill source (a repo, your own folder, or a plugin) can now register at most 1,024 hooks and 16,384 matcher characters per session. Skills that exceed the limit have their excess hooks silently dropped. This cap was introduced to prevent pathological plugin configurations from consuming unbounded hook-registration space. If you author a large skill with many hooks, audit against these limits.
Additionally, skills under a policy that allows hooks from plugins only (e.g., a managed setting of allowPluginHooksOnly) no longer receive their allowed-tools grant when used in the main conversation — only plugin-registered hooks get the grant. This closes a policy bypass path.
Per session, hooks now run at most 24 at a time (sub-agents included), plus at most 12 that have waited longer than their event’s timeout. A timeout under 1 second now counts as 1 second. The SubagentStop bug (firing roughly twice a minute per running subagent instead of once at completion) was also fixed in v2.1.312.
Hook if conditions match Monitor tool commands (v2.1.314)
Hook if conditions such as Monitor(tail *) now match the Monitor tool’s shell commands the same way Bash(tail *) matches Bash commands. Previously, Monitor tool invocations were invisible to hook condition patterns. Additionally, hooks that match Bash now run on commands started by the Monitor tool.
Cowork cloud sessions: hook allow counts as no answer (v2.1.314)
In Cowork cloud sessions, a hook’s allow decision on an MCP tool call no longer short-circuits the permission pipeline — it counts as no answer, so the classifier or a permission prompt decides. This prevents hooks from granting MCP tool access that the session’s permission policy should govern.
onFailure: "block" for Agent SDK hook callbacks (v2.1.317): a hook registered with onFailure: "block" now blocks the tool call when the hook callback fails, instead of the default permissive behavior where a failed hook lets the call proceed. This aligns Agent SDK hooks with Claude Code’s existing hook-level failure handling.
/schedule connector warning (v2.1.317): creating a cloud scheduled task with /schedule now warns when the task would inherit connectors you did not explicitly request for it. Prevents tasks from silently acquiring broad connector access.
30-second progress heartbeat for long hooks in claude -p / SDK sessions (v2.1.323): When a hook runs in a non-interactive (claude -p) or SDK session and takes more than 30 seconds, Claude Code now emits a progress heartbeat to the caller. This prevents the caller from timing out the session while a long hook is executing (e.g., a heavy PreToolUse linter or a slow external API call). No config change is needed; the heartbeat is automatic in those session types.
W44–W46 in Related
Week 44 release digest — hook concurrency caps (v2.1.312); hook if for Monitor tool (v2.1.314).
Resolved 2026-07-16: default hook execution timeout is 60 seconds, configurable per hook (source: claude.com/blog/how-to-configure-hooks). The settings field name for overriding the default isn’t given by that source — still open if a reader needs the exact key.
How do hooks interact with --dangerously-skip-permissions? Does the mode override PreToolUse deny verdicts?
Order of evaluation when multiple hooks register for the same event from user, project, and plugin scopes — which wins on conflicting decision values? The 2026-07-16 blog post confirms same-event hooks run in parallel rather than sequentially, which reframes the question (it’s not “order” so much as “conflict resolution between concurrent results”) but doesn’t answer it.
Resolved 2026-10-04: SessionStart resume cost field names are seconds_since_last_response, context_tokens, prompt_cache_likely_expired, estimated_cache_write_usd — confirmed from live hooks reference. See “Recent additions (2026-10-04)” above.
onFailure: "block" on post-event hooks: Does it apply to PostToolUse or PostToolUseFailure (where blocking an already-completed call is undefined)? Not stated in the changelog.
What does a PreModelSwitchmatcher match against, and what output schema confirms or annotates a switch?