Hooks — Deterministic Loop Control¶
Hooks inject deterministic logic at specific points in the Claude Code lifecycle.
Unlike CLAUDE.md instructions (advisory), hooks always run — they cannot be
skipped, forgotten, or overridden by the model.
This makes hooks the right tool for loop control: verification gates, circuit breakers, audit logging, and automatic continuation.
Five hook types¶
| Type | What it does | Timeout |
|---|---|---|
command |
Runs a shell command; stdout parsed as JSON | 600 s (10 min) |
http |
POSTs JSON to an HTTP endpoint | 600 s (10 min) |
mcp_tool |
Calls an MCP tool | 600 s (10 min) |
prompt |
Sends a prompt to an LLM for yes/no decisions | 30 s |
agent |
Spawns a subagent for verification (experimental) | 60 s |
Raised from 60 s to 10 minutes in v2.1.3. Claude Code lowers the command/http/mcp_tool
default back to 30 s specifically on UserPromptSubmit, PreModelSwitch, and PostModelSwitch
(and to 10 s on MessageDisplay), because those events block the model turn while they run — see
the Hooks reference.
Exit codes (command hooks)¶
| Code | Meaning | Effect |
|---|---|---|
0 |
Success | Parse stdout as JSON; apply output fields |
2 |
Blocking | PreToolUse: deny tool. Stop/SubagentStop: prevent stopping. UserPromptSubmit: block prompt |
Other (incl. 1) |
Non-blocking warning | Show first line of stderr; continue |
Exit code 2 is the loop control signal: returning 2 from a Stop hook
tells Claude "you are not done — re-enter the loop."
After 8 consecutive blocks from a Stop hook, Claude Code overrides and ends the
turn to prevent infinite loops (v2.1.143+). The cap is configurable via the
CLAUDE_CODE_STOP_HOOK_BLOCK_CAP environment variable.
A project-level Stop hook should cap its own retry count below this built-in override (e.g. 5, not 8) so the loop's own gate, not the platform's safety valve, is what stops it — a widely-used implementation of this pairs the capped Stop-hook gate with a fresh-context judge that re-verifies every criterion each round, including ones already passed, rather than trusting a prior round's "done." (first-fluke/oh-my-agent, Sep 2026.)
Safety contract: never exit 1 in a denial hook¶
Exit code 1 (or any non-2 non-zero exit) is treated as a non-blocking warning
— Claude logs the error and continues. A hook that intends to deny but crashes
with exit code 1 silently allows the action instead of blocking it.
Rule: All deny logic must be wrapped so that any exception exits 2, not 1.
Test every denial path explicitly.
#!/bin/bash
# deny-hook.sh — safe pattern
deny_reason() {
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny"}}'
exit 2
}
# Wrap all logic — any unhandled error exits 2 (deny), not 1 (allow)
set -e
trap 'deny_reason' ERR
# ... your check logic ...
if [[ "$SOME_CONDITION" == "true" ]]; then
deny_reason
fi
exit 0 # allow
Key lifecycle events¶
| Event | Fires when | Can block (exit 2)? |
|---|---|---|
SessionStart |
Session begins | No |
Setup |
Fires only on claude --init-only, or claude -p --init/claude -p --maintenance (v2.1.10+) — never on normal startup |
No |
UserPromptSubmit |
User sends a message — can inject context or block | Yes |
PreToolUse |
Before any tool call — can modify input or deny | Yes |
PermissionRequest |
Instead of interactive permission dialog | No¹ |
PostToolUse |
After tool completes — can rewrite what Claude sees | No |
PostToolBatch |
After all parallel tool calls, before next model turn | Yes |
SubagentStart |
Subagent session begins | No |
SubagentStop |
Subagent ends — can validate output and continue | Yes |
Stop |
Claude is about to stop — can inject more work | Yes |
StopFailure |
Claude stopped due to error (rate limit, billing, etc.) | No |
PreCompact |
Before context compaction — can block by exiting 2 or returning {"decision":"block"} (v2.1.105) |
Yes |
PostCompact |
After context compaction | No |
PreModelSwitch |
Before a model switch — block, confirm, or annotate it (v2.1.251+) | Yes |
PostModelSwitch |
After a model switch completes — annotate the outcome (v2.1.251+) | No* |
SessionEnd |
Session terminates | No |
¹ PermissionRequest is the trap in this column: it is a decision hook, but exit code 2 is
not honored for it — "the permission flow proceeds unchanged. Deny through the decision object
instead" (Hooks reference — Exit code 2 behavior per
event, fetched 2026-09-07). A guard written as exit 2
here fails open and looks like it is working.
* The switch has already happened by the time PostModelSwitch fires, so blocking applies to
PreModelSwitch; the changelog states both events together as "block, confirm, or annotate a
model switch." (Claude Code v2.1.251, release
notes.)
SessionStart resume hooks got richer in v2.1.251 too: they now receive session staleness
and the estimated re-cache cost, verbatim: "SessionStart resume hooks now receive session
staleness and the estimated re-cache cost." A resume hook can use this to warn (or refuse to
resume) a session that has gone stale enough that resuming it would trigger an expensive
uncached re-processing of the whole history — see Cost & Turn
Control for why
that re-cache cost matters.
JSON output API¶
Every hook can return a JSON object on stdout to influence what happens next:
{
"continue": true,
"suppressOutput": false,
"systemMessage": "Context added to Claude's system prompt for this session",
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "allow", // PreToolUse only: allow|deny|ask|defer
"updatedInput": {}, // PreToolUse: replace the tool's input before execution
"updatedToolOutput": "...", // PostToolUse: replace what Claude sees as output
"additionalContext": "..." // injects context at the point the hook fired (see below)
}
}
PermissionRequest does not use permissionDecision — it returns a decision object with
behavior: "allow"|"deny" instead. See Permissions & Auto Mode → PermissionRequest
hook for that event's own schema.
Key fields for loop engineering:
additionalContext— inject a message into Claude's context at the point the hook fired. Originally Stop/SubagentStop-only; extended toPreToolUsein v2.1.9. As of the current Hooks reference (fetched 2026-09-07) it also works onSessionStart,SubagentStart,UserPromptSubmit,UserPromptExpansion,PostToolUse,PostToolUseFailure,PostToolBatch, andPostModelSwitch. Only onStop/SubagentStopdoes it continue the loop by preventing the stop; elsewhere it just adds context to the next model turn without blocking anything.updatedInput— rewrite a tool's input before execution (PreToolUse)updatedToolOutput— rewrite what Claude sees after a tool runs (PostToolUse)continue: false— halt the entire session immediately. ForTeammateIdle, and forTaskCompletedwhen a teammate finishing its turn triggered the event, it instead stops that teammate — the lead and other teammates in the agent team keep running (fixed to matchStophook semantics in v2.1.69).TaskCompletedignorescontinue: falsewhen theTaskUpdatetool itself triggered the event — only exit code 2 blocks that completion.suppressOutput— hide the hook result from the transcript (clean logs)
Hooks cannot loosen a static deny or ask rule. Three fixes establish this as current
behavior:
- v2.1.77: "Fixed
PreToolUsehooks returning"allow"bypassingdenypermission rules, including enterprise managed settings." - v2.1.101: "Fixed
permissions.denyrules not overriding aPreToolUsehook'spermissionDecision: "ask"— previously the hook could downgrade a deny into a prompt." - v2.1.110 / v2.1.211: closed the same gap for
PermissionRequest'supdatedInputand for auto mode overriding a hook'saskdecision on unsandboxed Bash.
Net effect: a PreToolUse/PermissionRequest hook can make an action stricter than the static
rules (turn an allow into an ask, or deny outright) but cannot make it looser — not by returning
a laxer permissionDecision, and not by rewriting the tool input. Design permission hooks as a
restriction layered on top of permissions.deny/ask, never as a way to route around them.
Source: Permissions reference, verbatim: "Hook decisions don't bypass permission rules." (v2.1.77, v2.1.101, v2.1.110, v2.1.211 release notes.)
Async hooks and the circuit breaker pattern¶
By default, hooks run synchronously and Claude waits. Two async modes:
{
"event": "PostToolUse",
"matcher": "Bash",
"type": "command",
"command": "audit-log.sh",
"async": true // run in background; Claude does not wait
}
{
"event": "Stop",
"type": "command",
"command": "verify-output.sh",
"async": true,
"asyncRewake": true // if script exits 2, Claude is woken back up
}
asyncRewake is the circuit breaker pattern: verification runs in the background
after Claude stops. If the check fails (exit code 2), Claude is automatically re-woken
with the verification output as context — without blocking the main loop while
verification runs.
#!/bin/bash
# verify-output.sh
npm test > /tmp/test-results.txt 2>&1
if [ $? -ne 0 ]; then
RESULTS=$(cat /tmp/test-results.txt)
# Use jq to safely escape the test output into JSON
jq -n --arg ctx "Tests failed:\n$RESULTS" \
'{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":$ctx}}'
exit 2 # re-wake Claude with failure context
fi
Conditional hooks (if field)¶
Run a hook only when the tool input matches a pattern (the if field, added in v2.1.85):
{
"event": "PreToolUse",
"matcher": "Bash",
"if": "Bash(rm *)",
"type": "command",
"command": "confirm-delete.sh"
}
Uses the same pattern syntax as permissions.allow/permissions.deny.
Avoids running expensive hooks on every tool call.
Environment variables in hooks¶
| Variable | Value |
|---|---|
CLAUDE_PROJECT_DIR |
Absolute path to project root (hook env var since v1.0.58) |
CLAUDE_CODE_SESSION_ID |
Current session ID. Matches the session_id field in the hook JSON input, and is updated on /clear |
CLAUDE_EFFORT |
Current effort level (low/medium/high/xhigh/max), since v2.1.133 |
CLAUDE_CODE_REMOTE |
true in a cloud session (Routines run as cloud sessions) |
CLAUDE_CODE_REMOTE_SESSION_ID |
The cloud session's own ID — use it to build a link back to the session transcript |
CLAUDE_ENV_FILE |
Write KEY=VALUE here to persist env vars across Bash tool calls |
CLAUDE_ENV_FILE is useful for hooks that inject credentials or state for subsequent
Bash tool calls in the same session.
Two traps in the table above
CLAUDE_CODE_REMOTE is true, not "1". A hook guarding on
[ "$CLAUDE_CODE_REMOTE" = "1" ] never fires — the reference says it is "Set automatically
to true when Claude Code is running as a cloud session."
CLAUDE_CODE_SESSION_ID is not a stable loop key across resumes. It is reliable on a
fresh session and on --resume <session-id>, but on --continue, or --resume without an
explicit ID, "it may receive the initial startup ID instead." A loop that keys its state
directory on this variable can silently write two runs into one bucket. An MCP server
subprocess keeps the ID it was spawned with.
Source: environment variables reference,
verified against claude 2.1.261, 2026-09-05.
Configuration example¶
Each entry under an event is a matcher group, and its handlers live in that group's own
nested hooks array — the flat matcher + type + command shorthand used elsewhere in this
doc is abbreviated notation, not loadable file content. A PostToolUse command hook receives
the tool input as JSON on stdin.
// .claude/settings.json
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "scripts/verify.sh",
"async": true,
"asyncRewake": true
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(rm -rf *)",
"command": "scripts/confirm-destruct.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "scripts/auto-lint.sh",
"async": true
}
]
}
]
}
}
Schema verified against Hooks reference, fetched
2026-09-07 — every worked settings.json example on that page nests handlers this way.
Scope hierarchy¶
Hook entries merge across sources rather than one replacing another — user, project, local,
and plugin hooks all add to the set that runs; a hook from one source doesn't remove or replace a
hook from another. (Settings values follow a different rule — highest level wins; see
Permissions & Auto Mode → Settings precedence.)
disableAllHooks and allowManagedHooksOnly are the exception: for these, managed policy is a
floor nothing below it can lower. Ordinary precedence still applies among the non-managed scopes —
Claude Code reads the value left after settings precedence applies, so a project's
"disableAllHooks": false overrides a user setting of true, and claude --settings
'{"disableAllHooks": true}' overrides both for one run — but only disableAllHooks set at the
managed-settings level can disable hooks an administrator configured through managed policy.
Fixed in v2.1.49, verbatim: "Fixed disableAllHooks setting to respect managed settings
hierarchy — non-managed settings can no longer disable managed hooks set by policy (#26637)."
Source: Hooks reference — Disable or remove hooks,
verified against claude 2.1.263, 2026-09-07.
Loop engineering patterns¶
Verify-before-stop (asyncRewake circuit breaker):
{ "event": "Stop", "type": "command", "command": "run-tests.sh",
"async": true, "asyncRewake": true }
What a production "done" check contains (one codebase). The maintainer of the open-source
blade-code CLI agent says in a Chinese
reply to a relay of a
565-line teaching agent
that its agent/loop directory is 17 files and 8,387 lines (re-counted on main, 2026-10-19: they match), most
of it beyond the bare loop being, in his list, when work counts as done, independent verification, error recovery and context compaction. completionPolicy.ts (644 lines)
holds recovery when output is cut off at the length limit, up to 2 retries when a turn ends like an announced
action ("Let me check", a trailing colon) or emits a long code block with no tool call, and a stop hook run under
a timeout; independentVerification.ts (320) tracks modified files and a PASS/FAIL/PARTIAL verdict with a retry
cap of 3. The 4,882-line executeLoopGenerator.ts was not broken down, so how much of the total is "done" logic
is the maintainer's reading. See the Stop Condition Taxonomy.
Block destructive commands in unattended runs:
{ "event": "PreToolUse", "matcher": "Bash", "if": "Bash(rm -rf *)",
"type": "command",
"command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\"}}'" }
Audit log every tool call:
{ "event": "PostToolUse", "type": "command", "async": true,
"command": "curl -s -X POST https://audit.example.com/events -H \"Authorization: Bearer $AUDIT_TOKEN\" -d @-" }
async field — they run synchronously and block the tool call until the
endpoint responds or the timeout elapses (600 s by default). True fire-and-forget audit logging
needs a command-type hook with async: true, piping the JSON input to curl in the background,
as above.
Gate a model switch (v2.1.251+): before PreModelSwitch/PostModelSwitch existed, a model
switch mid-session (whether Claude's own choice or a user's /model call) was unobservable and
ungatable by a hook — the loop had no deterministic control point to stop, log, or confirm it.
PreModelSwitch makes an accidental downgrade to a cheaper/weaker model mid-task a blockable
event rather than a silent one, and PostModelSwitch gives an audit trail of every switch a
loop actually made — the same "always runs, cannot be skipped" property this doc opens with,
now applied to model choice instead of only tool calls.
Ordering guarantees belong outside the loop. A post
(19 Oct 2026) reports an agent running git commit before its tests had finished; a
reply says "ordering guarantees belong outside the agent loop,
not in the prompt". The tool in the thread, Strands Box (Apache-2.0,
preview, macOS on Apple silicon only as of 2026-10-19), enforces default-deny policy outside the agent process,
and its rules can read earlier actions and elapsed time. Its
documented example refuses git commit
unless a cargo test exited 0 within the last hour, keyed on the recorded result of that run because a request
event also exists for a refused attempt, so a rule keyed on it "would pass after a refused cargo test". For a
hook gate the transferable point is to check a persisted outcome, not that the command was issued; with hooks
that means storing the result where the agent cannot edit it (inference, untested here).
Chain background agents via SubagentStop:
When a background agent finishes, inspect its output and fire the next step.Beyond hooks: mods¶
Hooks gate an event and, through the JSON output above, can rewrite a tool call's input or output. Anthropic says they cannot rewrite events more generally, draw UI, or replace built-in features. Claude Code mods (added in v2.1.287, Oct 2026) are the layer above: TypeScript functions that hook one of the events Claude Code emits (a tool call, a permission request, a screen draw) and can run before, after, instead of, or around it. Per Anthropic's announcement (1 Oct 2026), a mod can rewrite a prompt before it reaches the model, block, rewrite or retry a tool call, approve or deny a permission request, and redact secrets from tool output before Claude reads it. The v2.1.287 changelog entry (1 Oct 2026) is the version stamp: "Added Claude Mods: plugins may now modify deeper behavior", alongside a built-in "You should know" mod, a side agent that watches the session. Coverage: The New Stack (2 Oct 2026), claude.com tutorial.
| Hook | Mod | |
|---|---|---|
| Form | Command, HTTP, MCP tool, prompt or agent, declared in settings | TypeScript function, shipped inside a plugin |
| Reach | The lifecycle events and JSON output API above | Events including tool calls, permission requests and screen draws; can also edit the UI Claude Code draws |
| Sandboxed | n/a | No: per the announcement, a mod has the same machine access as Claude Code itself; install only from sources you trust |
| Ordering | n/a | Several mods on one event run in load order; the first to load sees the event first and the result last |
Three things matter for an unattended loop, all from the announcement and the changelog:
- Admin guardrail. On Team and Enterprise plans, and on machines with managed settings, a
built-in
sec-defaultmod loads first and stops user-installed mods from doing risky things such as overriding permission deny rules. Admins can load their own mods first instead; the post says to keepsec-defaultin the list to keep its restrictions. v2.1.299 further improved enforcement of managed permission rules, managed hooks and organization MCP tool names against user-installed mods (changelog, 14 Oct 2026). - An audit seam. The announcement's own example for teams: a mod that loads first can record
every call that every other mod makes, which complements the
PostToolUseaudit hook above rather than replacing it. - A way to break a stop condition. v2.1.299 fixed a mod that submits a prompt at the end of every
turn keeping a headless run going past
--max-turns,--max-budget-usd, an interrupt, or the end of the host's conversation. A mod is code in the loop's control path: audit it like a hook that can veto your STOP.
What Anthropic's Thariq Shihipar says he is building with mods. In the Latent Space interview (29 Sep 2026; transcript read) he says a mod runs in-process with turn count, token use and the messages in scope, can spawn sub-agents and parse their structured output, and can change the UI, which hooks cannot. His example forks an agent at the end of each turn to ask whether the task is complete and, if so, generate a quiz; a fork keeps the prompt cache, so it is cheap, though he calls the pattern "slightly token-intensive" because it runs every turn. A mod that fires every turn is where the v2.1.299 stop-condition bug above lived, so give it its own cap (inference). He is also building a model-router mod and says, hedging with "I want to say", that routing is not on by default because it is a hard problem, and that a good router is one that "doesn't break prompt cache all the time" (the caching concern was the host's; see Cost Control). One interviewee's account of work in progress, not documented behaviour.
Later changelog entries: agent.spawn for teammates (v2.1.289, 3 Oct 2026), and (v2.1.300, 14 Oct
2026) the agent.spawn mod hook can rewrite a workflow agent's prompt and model, where before it
could only refuse workflow agents. This KB has not exercised mods; the facts above are the vendor's
description and changelog, not a tested loop.
Related¶
- Verification — the broader verification philosophy
- Human-in-the-Loop Escalation — when hooks should escalate vs. loop
- Background Agents — SubagentStart/SubagentStop patterns
- Failure Patterns — missing circuit breaker anti-pattern