Claude Code Hooks Explained: The Deterministic Layer Around Your Agent

What are Claude Code hooks? Hooks are user-defined shell commands (plus HTTP endpoints, MCP tools, and model prompts) that Claude Code executes automatically at fixed points in its lifecycle: before a tool call, after an edit, at session start, when Claude finishes responding.¹ Where CLAUDE.md gives the model instructions it will probably follow, hooks execute whether or not the model cooperates. Type /hooks inside any session to see every lifecycle event and what is wired to it. {.answer-block}

Most developers run Claude Code with two layers of control: permissions gating what the agent may do, and CLAUDE.md describing what it should do. Hooks are the third layer, and the only one that guarantees anything. Below: the mental model, every lifecycle event in the current docs, the exact input/output contract, configuration, five working patterns, and a decision framework. Every API detail was verified against the official hooks reference and guide as of July 1, 2026 — this system moves fast, so where this post and the reference disagree, the reference wins. (New to Claude Code? Start with the 5-minute setup or the New to Claude Code path.)

TL;DR: Hooks receive JSON on stdin and answer with exit codes or JSON on stdout. Exit 0 allows, exit 2 blocks (on the events that can block), and exit 1 — the conventional Unix failure code — blocks nothing, which is the single biggest hook footgun.² Configure them in settings.json under event names like PreToolUse and Stop, filtered by matchers. Use hooks for anything that must always happen; use CLAUDE.md for anything the model should merely know.

The mental model: guarantees around a non-deterministic core

A coding agent is a probabilistic system. Ask it to run Prettier after every edit and it will — most of the time. It might skip the step when the change looks trivial, when context runs long, or when your phrasing lands differently. CLAUDE.md, skills, and prompts are all suggestions: high-quality, usually followed, never guaranteed.

Hooks are the deterministic shell around that core. The official definition: “user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code’s lifecycle,” providing “deterministic control over Claude Code’s behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them.”³ The formatter fires on every edit. The command guard evaluates every Bash call. The completion gate checks every finish.

The enforcement is real, not cosmetic: PreToolUse hooks fire before any permission-mode check, so a hook that returns permissionDecision: "deny" blocks the tool even in bypassPermissions mode or under --dangerously-skip-permissions. The reverse does not hold — a hook returning "allow" cannot loosen deny rules from settings. Hooks can tighten policy past what permissions allow, never weaken it.⁴

The lifecycle: every hook event

As of July 1, 2026, the reference documents 30 hook events.¹ They fall into three cadences: once per session (SessionStart, SessionEnd), once per turn (UserPromptSubmit, Stop, StopFailure), and on every tool call inside the agentic loop (PreToolUse, PostToolUse). The rest fire on specific conditions — config changes, compaction, subagents, MCP interactions.

You will not need most of these. Nearly every production setup is built from five: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, and Stop. The rest exist for the day you need them.

The contract: JSON in, exit codes or JSON out

Command hooks receive JSON on stdin and answer through exit codes, stdout, and stderr. (HTTP hooks receive the same JSON as a POST body and answer through the response body.)²

Every event delivers a common envelope — session_id, transcript_path, cwd, and hook_event_name, with permission_mode on most events — plus event-specific fields. A PreToolUse hook for a Bash command receives:

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

Other events swap the tail: UserPromptSubmit carries prompt, SessionStart carries source (startup/resume/clear/compact), Stop carries stop_hook_active and last_assistant_message. Hooks fired inside subagents additionally receive agent_id and agent_type.²

Exit codes

Three outcomes:²

• Exit 0 — success. Claude Code parses stdout for JSON output fields. For most events stdout goes to the debug log only; for UserPromptSubmit, UserPromptExpansion, and SessionStart, plain stdout is added as context Claude can see.
• Exit 2 — blocking error. Stdout (including any JSON) is ignored; stderr is fed back to Claude as the error message. What “block” means depends on the event.
• Any other exit code — non-blocking error. The transcript shows a <hook name> hook error notice, and execution continues.

That last line deserves bold: exit 1 does not block anything. The docs warn about this directly — Claude Code treats exit 1 as a non-blocking error and proceeds, even though 1 is the conventional Unix failure code. Policy hooks must exit 2.²

What exit 2 does, per event:²

Everything else cannot block. PostToolUse and PostToolUseFailure show stderr to Claude (the tool already ran); SessionStart, Notification, SessionEnd, CwdChanged, FileChanged, PostCompact, SubagentStart, and Setup show stderr to the user only; StopFailure, InstructionsLoaded, MessageDisplay, and PermissionDenied ignore the exit code — for PermissionDenied the only lever is JSON retry: true.²

JSON output

For finer control than block-or-silence, exit 0 and print a JSON object to stdout. One rule up front: exit codes or JSON, never both — JSON is only processed on exit 0, and exit 2 discards it.⁵

Universal fields work on every event: continue: false stops Claude entirely (with stopReason shown to the user), suppressOutput hides stdout from the transcript, systemMessage shows the user a warning, and terminalSequence emits an allowlisted terminal escape (desktop notification, window title, bell). Decision fields are per-event:⁵

Two details that bite people. First, PreToolUse is the exception to the top-level-decision pattern: it used top-level decision/reason historically, but those are deprecated for this event ("approve"/"block" map to "allow"/"deny"); use hookSpecificOutput.permissionDecision.⁵ Second, when multiple PreToolUse hooks disagree, precedence is deny > defer > ask > allow.⁵

Configuration: settings.json, matchers, scope

Hook configuration nests three levels: pick an event, add a matcher group to filter when it fires, and define one or more hook handlers to run.⁶

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/path/to/lint-check.sh" }
        ]
      }
    ]
  }
}

Where you put this determines scope: ~/.claude/settings.json applies to all your projects, .claude/settings.json is project-scoped and committable, .claude/settings.local.json is project-scoped and gitignored, and the standard settings precedence applies — managed policy over local over project over user.⁹ Hooks can also ship in plugins (hooks/hooks.json) and in skill or agent frontmatter, and enterprise admins can enforce managed hooks that users cannot override.⁶

Matchers are evaluated by their characters: "*", "", or an omitted matcher matches everything; a value containing only letters, digits, _, -, spaces, commas, and | is an exact string or list (Bash, Edit|Write); anything else becomes an unanchored JavaScript regex, so Edit.* matches both Edit and NotebookEdit — anchor with ^Edit$ when you mean exactly one tool. Matchers are case-sensitive, and each event matches on its own field: tool name for tool events, source for SessionStart, agent type for SubagentStart, notification type for Notification.⁶ For sharper filtering on tool events, the per-handler if field accepts one permission rule like "Bash(git *)" — but it is best-effort (it fails open on unparseable commands), so use permission rules, not if, for hard guarantees.⁶

Handlers come in five types: command (shell), http (POST endpoint), mcp_tool, prompt (single-turn model evaluation), and agent (a subagent with Read/Grep/Glob access; experimental). Default timeouts: 600 seconds for command/http/mcp_tool (lowered to 30 for UserPromptSubmit and 10 for MessageDisplay), 30 for prompt, 60 for agent — override per hook with timeout.⁶ All matching hooks run in parallel with identical handlers deduplicated, and $CLAUDE_PROJECT_DIR points scripts at your project root.

Verify with /hooks: a read-only browser showing every event, its configured hooks, and which settings file each came from. To change anything, edit the JSON (or ask Claude to). To kill everything temporarily, set "disableAllHooks": true.⁶

Five patterns

Genericized and minimal. The hooks tutorial builds fuller production versions of several of these, and Hooks for Apple Development applies them to the iOS toolchain.

1. Auto-format after edits (PostToolUse)

Straight from the official guide — every file Claude touches gets formatted, no exceptions:³

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Swap the command for ruff format, gofmt, or swiftformat as your stack demands.

2. Block dangerous commands (PreToolUse, exit 2)

#!/bin/bash
# .claude/hooks/guard-bash.sh — register on PreToolUse, matcher "Bash"
command=$(jq -r '.tool_input.command // empty')
case "$command" in
  *"rm -rf"* | *"git push --force"* | *"DROP TABLE"*)
    echo "Blocked: matches a destructive pattern. Propose a safer alternative." >&2
    exit 2 ;;
esac
exit 0

Exit 2 blocks the call and feeds stderr back to Claude, which adjusts course instead of retrying blindly. The JSON equivalent — permissionDecision: "deny" with a reason — does the same with room to grow into "ask" (escalate to the human) or updatedInput (rewrite the command).⁵

3. Inject context on session start (SessionStart)

Plain stdout from a SessionStart hook becomes context Claude can see — no JSON required:¹

#!/bin/bash
# .claude/hooks/session-context.sh — register on SessionStart
echo "Current branch: $(git branch --show-current)"
echo "Recent commits:"
git log --oneline -5
echo "Uncommitted files: $(git status --porcelain | wc -l | tr -d ' ')"
exit 0

Use this for dynamic state. Static conventions belong in CLAUDE.md, which the docs themselves recommend for context that does not require a script.¹

4. A completion gate on Stop

Stop fires when Claude finishes responding. Blocking it forces the agent to keep working until a condition holds:

#!/bin/bash
# .claude/hooks/stop-gate.sh — register on Stop
input=$(cat)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # already continuing because of this hook; don't loop forever
fi
if ! npm test --silent > /tmp/stop-gate.log 2>&1; then
  jq -n '{decision: "block", reason: "Tests are failing. Fix them before finishing. Log: /tmp/stop-gate.log"}'
fi
exit 0

The stop_hook_active check matters: Claude Code hard-caps a Stop hook at 8 consecutive blocks, and a gate that never checks whether it already triggered a continuation will burn straight through them.⁷ For softer steering, return hookSpecificOutput.additionalContext instead of decision: "block" — same continuation, but labeled feedback rather than a hook error. And for one-off conditions, the built-in /goal command is a session-scoped prompt-based Stop hook with zero configuration.¹

5. The dispatcher: one entry point, many small hooks

Registering ten hooks means ten settings.json entries that drift across machines and projects. The alternative: register one dispatcher per event and route by convention.

#!/bin/bash
# .claude/hooks/dispatch.sh — register once per event you care about
input=$(cat)
event=$(echo "$input" | jq -r '.hook_event_name')
dir="$CLAUDE_PROJECT_DIR/.claude/hooks/$event"
[ -d "$dir" ] || exit 0
for hook in "$dir"/*.sh; do
  [ -x "$hook" ] || continue
  echo "$input" | "$hook" || exit $?
done
exit 0

Adding a guard is now chmod +x on a new file in .claude/hooks/PreToolUse/ — settings.json never changes, each script stays small enough to test in isolation, and the first exit 2 propagates. One caveat: the dispatcher serializes what Claude Code would run in parallel, and it suits exit-code hooks best — a JSON-emitting hook should stay standalone, since stdout must contain exactly one JSON object.⁵

Hook vs CLAUDE.md vs skill vs memory

Four mechanisms, four jobs:

The failure mode runs in both directions. Encoding conventions as hooks buys you brittle scripts enforcing things a sentence of guidance handles fine. Encoding policy as CLAUDE.md prose buys you an agent that force-pushes to main on the one day it matters. The test: what is the cost when the model ignores this once? Annoyance → CLAUDE.md. Incident → hook.

What hooks can’t do

Honest limits, all from the official docs:⁷

• Hooks cannot call tools or slash commands. Command hooks speak stdout, stderr, and exit codes — nothing else. Context returned via additionalContext is injected as plain text.
• PostToolUse cannot undo. The tool already ran. Prevention lives in PreToolUse.
• Stop fires on every response end, not only at “task complete,” and never on user interrupts (API errors fire StopFailure instead). Gate logic must tolerate mid-task stops.
• PermissionRequest does not fire in headless (-p) mode. Use PreToolUse for automated permission decisions.
• PreToolUse does not see @-referenced files. Files pulled in via @ in your prompt involve no tool call; use Read deny rules to protect paths from that route.¹
• Parallel updatedInput is non-deterministic. When several PreToolUse hooks rewrite the same tool’s arguments, the last to finish wins. Let one hook own each rewrite.
• Timeouts cancel the hook. 600 seconds default for command hooks (30 for UserPromptSubmit, 10 for MessageDisplay); a slow gate that times out is a gate that didn’t run.
• Output is capped at 10,000 characters — overflow is written to a file and replaced with a preview.
• Hooks run with your full user permissions. The reference’s own warning: they “can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration.”⁸ Quote your variables, use absolute paths, skip sensitive files.
• A broken hook degrades every session until fixed. Debug with the transcript view (Ctrl+O), claude --debug-file /tmp/claude.log, or /debug mid-session; a classic gotcha is a shell profile that echoes on startup and corrupts your hook’s JSON output.⁷

FAQ

What are Claude Code hooks?

Hooks are user-defined commands — shell scripts, HTTP endpoints, MCP tools, or model prompts — that Claude Code executes automatically at specific lifecycle points.³ They receive event JSON on stdin and answer with exit codes or JSON: block a tool call, inject context, rewrite arguments, keep the agent working. Unlike CLAUDE.md instructions, they execute every time, regardless of model behavior.

What’s the difference between PreToolUse hooks and permissions?

Permission rules are declarative: static allow/deny/ask patterns that Claude Code evaluates itself. PreToolUse hooks are programmable: your code inspects the full tool input and decides. Hooks fire before permission-mode checks, so a hook’s "deny" holds even in bypassPermissions mode — but a hook’s "allow" cannot override a settings deny rule.⁴ Use permission rules for anything a pattern can express; reach for a hook when the decision needs logic, external state, or input rewriting.

Do hooks work in headless (-p) mode?

Yes — with one documented exception: PermissionRequest hooks do not fire in non-interactive mode, so automated permission decisions belong in PreToolUse.⁷ Headless mode also unlocks one option interactive sessions ignore: permissionDecision: "defer", which pauses a tool call so a wrapping process (an Agent SDK app, a custom UI) can collect input and resume the session later.⁵

Why does my hook run but not block anything?

Almost always a contract violation. Exit 1 doesn’t block — only exit 2 does, and only on events that support blocking.² JSON decisions are only parsed on exit 0 — a script that prints {"decision": "block"} and then exits 2 has its JSON discarded. And matchers are case-sensitive — bash never matches Bash. Confirm registration with /hooks, then test by piping sample JSON into the script and checking echo $?.⁷

Sources

Verified against the official documentation on July 1, 2026. The hooks API has changed materially across Claude Code v2.1.x releases (new events, new fields, matcher semantics), so treat version-sensitive details as “as of this date.”

Related on this site: the Claude Code guide’s hooks section for the full-system view including prompt and agent hooks, the hooks tutorial for five production builds with complete configs, Hooks for Apple Development for the applied iOS patterns, and the quickstart if you haven’t installed Claude Code yet.