Claude Code Hooks: A Practical Guide for 2026

Quick definition: A Claude Code hook is a handler that Claude Code runs automatically at a fixed point in its lifecycle, such as before a tool call or after Claude finishes responding. Anthropic's wording: "Hooks are user-defined shell commands. Claude Code runs them at specific points in its lifecycle, which gives you deterministic control: certain actions always happen rather than relying on the LLM to choose to run them."¹

One-minute highlights

• 31 events exist in the current reference. Five of them carry almost all the real work.²
• Config nests three levels: event, matcher group, handler.²
• Handlers come in five flavours now: command, http, mcp_tool, prompt, and agent.¹
• Exit 2 blocks. Exit 0 plus JSON on stdout returns a structured decision.²
• A PreToolUse deny survives bypassPermissions and --dangerously-skip-permissions.¹

This is the practical layer on top of the official hooks reference and the hooks guide, both of which are canonical and worth reading in full. What follows is the part that took me longer to learn: which of those 31 events you'll actually use, what the exit codes really mean, and the three failure modes that make a hook go quiet instead of loud.

---

What a hook actually is

Every project has rules that live in CLAUDE.md and get followed most of the time. Hooks are where you put the rules that have to be followed every time.

Akshay Pachaar put the distinction better than the docs do: "CLAUDE.md is just a suggestion. Hooks are a guarantee. … A CLAUDE.md that says 'always run Prettier' is a hope. A PostToolUse hook that runs Prettier is a fact."³

That's the whole pitch. An instruction in a Markdown file competes for the model's attention with everything else in context. A hook is code your machine runs whether or not the model was paying attention.

Ado from Anthropic frames the mechanics as middleware: "PreToolUse → intercept before Claude runs a command. PostToolUse → react after it completes. Notification → custom alerts on your terms."⁴ If you've written Express or Django middleware, you already have the mental model. Requests flow through, and you get to inspect, log, rewrite, or reject them.

Anthropic runs this on their own code. Boris Cherny, on the Claude Code team: "We use a PostToolUse hook to format Claude's code. Claude usually generates well-formatted code out of the box, and the hook handles the last 10% to avoid formatting errors in CI later."⁵ That last 10% is exactly the shape of problem hooks solve. The model is good enough that you stop thinking about it, and then a bad build reminds you that "good enough" isn't "always."

---

The lifecycle and the five events that matter

The reference lists 31 events.² You will not use 31 events. Here are the ones worth learning first.

The blocking column is the one people get wrong. "PostToolUse hooks can't undo actions since the tool has already executed."¹ If you need to stop something, you need PreToolUse. A PostToolUse hook that exits 2 shows its stderr to Claude, which is useful feedback, but the file is already written.

The other 26 events are real and occasionally exactly what you need: PostToolUseFailure for reacting to failed calls, SubagentStart and SubagentStop for scoping rules to delegated work, PreCompact and PostCompact around context compaction, ConfigChange for auditing settings edits, FileChanged for reacting to disk changes, SessionEnd for cleanup.² Skim the full table once so you know what exists, then ignore it until you hit a problem that needs it.

Worth knowing about Stop: it fires whenever Claude finishes responding, not only at task completion, and it doesn't fire on user interrupts.¹ People wire up "notify me when the task is done" and get pinged after every single turn.

---

Configuration and a minimal working hook

Hooks live in JSON settings files, nested three levels: the event, then a matcher group that filters when it fires, then the handlers that run.²

Here's the smallest useful one. Add it to .claude/settings.json in your project root, and Prettier runs on every file Claude edits:¹

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

The hook receives event data as JSON on stdin. jq pulls out the path, xargs hands it to Prettier. That's the entire pattern: read stdin, do something, optionally write JSON to stdout.

Where the file goes

Seven locations, and scope is the only difference that matters:¹

Team rules go in .claude/settings.json and get committed. Personal preferences like desktop notifications go in ~/.claude/settings.json, where they won't annoy anyone else. The last two rows are the ones people miss: a skill or a subagent can carry its own hooks in frontmatter, scoped to when it's running, which is a much tighter blast radius than registering everything session-wide. Packaging hooks for a team is what plugins are for.

Run /hooks in your session to see everything currently registered, grouped by event.¹

Matchers

Without a matcher, a hook fires on every occurrence of its event. The matcher narrows it, and the syntax has a trap in it:²

• "*", "", or omitted matches everything.
• A value containing only letters, digits, _, -, spaces, ,, and | is treated as an exact name or an alternation list. Edit|Write matches those two tools.
• Anything else is evaluated as an unanchored JavaScript regular expression. So mcp__memory__.* works as a regex, and a stray . or ( in what you meant as a literal name silently changes how it's parsed.

Matchers are case-sensitive.¹ Comma alternation ("Edit, Write") works the same as pipe alternation on v2.1.191 or later.¹

Ten events accept no matcher at all and always fire: UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, CwdChanged, and MessageDisplay.² Adding a matcher to those does nothing, which is a fun twenty minutes to lose.

---

Five handler types, not just shell commands

The definition says "shell commands," and for most people that's still accurate. But type now takes five values, and two of them put a model inside your hook:¹

prompt hooks are for decisions that need judgment rather than a rule. Claude Code sends your prompt plus the hook input to a model, "Haiku by default," and the model returns {"ok": true} or {"ok": false, "reason": "..."}.¹ A Stop hook that asks "are all the requested tasks actually done?" is the canonical example, and the reason becomes Claude's next instruction.

agent hooks go further: they spawn a subagent that can read files and run commands before deciding. Verifying that tests actually pass before letting Claude stop needs the real state of the codebase, not just the event payload. The docs are blunt about maturity, though: "Agent hooks are experimental. Behavior and configuration may change in future releases. For production workflows, prefer command hooks."¹ Treat them as something to play with, not something to build a policy on.

http hooks have a quirk worth flagging. Unlike command hooks, they "can't signal a blocking error through status codes alone."² A 500 is a non-blocking error and the action proceeds. To actually block, return a 2xx with a JSON body carrying the decision. An endpoint that goes down fails open, which is the wrong default for a guardrail.

---

Exit codes and decision JSON

This is where most hooks break, and the failure is quiet rather than loud.

Exit 2 blocks. The reference is unambiguous: "Exit 2 means a blocking error. On events that can block, exit 2 blocks whether or not you print JSON: even a JSON permissionDecision of "allow" can't override it."² The message Claude sees is the reason from your JSON decision if you made one, otherwise your stderr.

Exit 0 is how you return structured output. Print JSON to stdout and Claude Code parses it. Two rules govern that parse:²

1. If the first non-whitespace character is {, stdout is parsed as JSON. Anything else, and the whole thing is treated as plain text.
2. If it parses but fails schema validation, you get a non-blocking error and the action proceeds anyway.

On most events, exit 0 stdout goes to the debug log and never appears in your transcript. The exceptions are UserPromptSubmit, UserPromptExpansion, and SessionStart, where plain-text stdout is added as context Claude can read.² That's the mechanism behind every "inject context at session start" recipe: just echo the text.

The structured form for a permission decision looks like this:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by project policy"
  }
}

permissionDecision takes allow, deny, or escalate (the last only on PermissionRequest).² additionalContext passes a note to Claude. updatedInput rewrites the tool's arguments before it runs. And two top-level fields apply everywhere: continue: false stops Claude entirely after the hook, with stopReason shown to you but not to Claude.²

One cap to know: hook output strings, including additionalContext and plain stdout, are "capped at 10,000 characters."² Past that, the output is written to a file and replaced with a preview plus the path.

When several hooks fire at once

All matching hooks run in parallel, and every one runs to completion before results merge.¹ Two consequences people trip on:

"One hook returning deny doesn't stop sibling hooks from executing."¹ Your logging hook still writes its line even though the guardrail hook rejected the call. Usually fine, occasionally not, if a sibling hook has side effects you assumed were conditional.

For PreToolUse permission decisions, "the most restrictive answer applies, in the order deny, defer, ask, allow."¹ Restrictive wins, which is the right default for a safety layer.

The genuinely dangerous one is updatedInput. "When multiple PreToolUse hooks return updatedInput to rewrite a tool's arguments, the last one to finish takes effect. Since hooks run in parallel, the order is non-deterministic."¹ Two hooks rewriting the same tool's input is a race condition you'll debug at midnight. Keep it to one.

---

Recipes worth copying

Block edits to protected files

The official pattern, and the one I'd install first. Save this as .claude/hooks/protect-files.sh:¹

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x it, then register it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Claude gets the Blocked: message as feedback and adjusts, rather than just failing.

Deny destructive shell commands

Same idea aimed at Bash, using the decision JSON instead of a bare exit. This is close to what one practitioner posted as their whole guardrail layer:⁶

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -qE 'rm -rf|git push --force|DROP TABLE'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "destructive command blocked"
    }
  }'
  exit 0
fi

exit 0

Two ways to say no, and they're not equivalent. Exit 2 sends your stderr as the reason. The JSON form gives you a structured reason and works alongside the merge rules above. Pick one per script so you're not reasoning about both.

Cut the noise before Claude reads it

Ruchish Shah described the shape of this well: "Your agent doesn't need the full test output. It needs the failures. … Ten thousand tokens of green checkmarks become a few hundred. Deterministic beats agentic for plumbing."⁷

The documented lever is updatedInput on PreToolUse, which rewrites the tool's arguments before the call runs.² Match on Bash, spot the test command, and rewrite it to pipe through a filter. The model never spends context on 400 passing assertions. This is the recipe I'd reach for second, right after file protection, because context is the scarcest thing in a long session and test output is usually the biggest waste of it.

Inject context at session start

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          { "type": "command", "command": "git log --oneline -10" }
        ]
      }
    ]
  }
}

SessionStart is one of the three events where plain stdout becomes context Claude can see.² No JSON needed. The matcher filters on how the session started: startup, resume, clear, compact, or fork.²

Enforce house style on prose, not just code

Nothing about PostToolUse cares whether the file is TypeScript. Ryosuke Sensui posted a production setup that uses it on Japanese-language content: the gist is that unnatural AI Japanese gets killed with a hook rather than a prompt, running a regex check right after the file is written and making Claude rewrite what matches, against a rule set they put at around 500 rules.⁸

That's the same Edit|Write matcher as the Prettier recipe pointed at a different problem. If you maintain docs, marketing copy, or a style guide with rules people actually argue about, the guarantee-versus-suggestion logic applies exactly as it does to formatting. A style rule in CLAUDE.md gets followed when the model remembers it. A regex in a PostToolUse hook gets followed.

Don't let Claude stop early

A Stop hook that exits 2 prevents Claude from stopping and continues the conversation.² Useful for "run the tests before you call it done" loops, and easy to turn into an infinite one. Claude Code has a backstop: it "overrides a Stop hook after it blocks eight times in a row without progress."¹

Write the guard yourself rather than relying on the cap:

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi
# your verification logic here

If a loop legitimately needs more than eight rounds, raise CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.¹ If it needs more than eight rounds regularly, the hook is doing a job that belongs in CI.

---

What hooks can and cannot enforce

One line in the docs turns hooks from a convenience into a real policy layer. "PreToolUse hooks fire before any permission-mode check, in every permission mode, including dontAsk. A hook that returns permissionDecision: "deny" blocks the tool even in bypassPermissions mode or with --dangerously-skip-permissions."¹

Nobody on your team can --dangerously-skip-permissions their way past a committed PreToolUse hook. That's the enforcement primitive.

The reverse doesn't hold. "Hooks can tighten restrictions but not loosen them past what permission rules allow."¹ A hook returning allow won't bypass deny rules in settings, and it won't suppress prompts for connector tools your organization set to ask. Auto-approving your way to a frictionless session only works within what permissions already permit.

Three more controls sit above all of this:²

• allowManagedHooksOnly in managed policy settings blocks user, project, local, and plugin hooks entirely.
• allowedHttpHookUrls restricts which URLs an HTTP hook may call, applied to hooks from every source.
• disableAllHooks: true turns hooks off, and settings precedence means a project's file can override yours.

Also worth knowing if you clone repos you don't fully trust: frontmatter hooks in a project subagent "run only after you accept the workspace trust dialog for the folder the agent file came from. Before v2.1.218, these hooks could run from folders you hadn't trusted."² Update if you're on anything older.

One thing I'll argue about: a lot of people install a dozen hooks in week one and turn most of them off by week three. Start with one PreToolUse guardrail and one PostToolUse formatter. Add the third only after something goes wrong that a hook would have caught.

---

Hooks vs skills vs subagents vs MCP

Four extension points, constantly conflated.

Determinism is the whole axis. Hooks are the only one of the four that runs whether or not the model chose it. Everything else is a capability the model may or may not use.

They compose, too. A hook can call an MCP tool via type: "mcp_tool". A skill can carry hooks in its frontmatter that register the moment the skill is invoked. A subagent can carry hooks scoped to its own run, and its name is what those hooks receive as agent_type.² Hooks are less a separate feature than the enforcement layer under all three.

For the wider map of what else works this way, the AI coding agents hub covers the landscape, and the 2026 Claude Code roundup covers what else has shifted on the platform.

---

Troubleshooting

The bolded row is the nastiest bug in this whole feature and it's worth understanding once. When Claude Code runs a shell-form command hook, the shell may still source your profile. An unconditional echo "Shell ready" in ~/.zshrc gets prepended to your hook's stdout. The combined output no longer starts with {, so "Claude Code treats all of stdout as plain text and ignores the JSON."¹ On exit 0, nothing is reported. Your guardrail is registered, running, exiting cleanly, and enforcing nothing.

To debug anything: Ctrl+O opens the transcript view, claude --debug-file /tmp/claude.log writes full hook execution details including exit codes and stdout, and /debug turns logging on mid-session.¹

Test scripts outside Claude Code before trusting them:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /tmp/x"}}' | ./my-hook.sh
echo $?

---

FAQ

What are Claude Code hooks? User-defined shell commands Claude Code runs at specific lifecycle points, giving you "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them."¹

How many hook events are there? 31 in the current reference, spanning the session lifecycle, tool calls, permissions, subagents, tasks, compaction, worktrees, and MCP elicitation.² Five cover most real setups.

What's the difference between PreToolUse and PostToolUse? PreToolUse fires before the call and can block it. PostToolUse fires after success and can't undo anything, "since the tool has already executed."¹

How do I block a command? A PreToolUse hook that exits 2, or returns JSON with hookSpecificOutput.permissionDecision set to deny. Exit 2 wins over any JSON allow.²

Can a hook override my permission mode? It can tighten. A deny holds even under bypassPermissions or --dangerously-skip-permissions. It can't loosen past what permission rules allow.¹

Where do I put hooks? .claude/settings.json for project rules you commit, ~/.claude/settings.json for personal ones. Skills and subagents can also carry hooks in frontmatter, scoped to when they run.¹

What's the default timeout? 600 seconds for command, http, and mcp_tool. UserPromptSubmit lowers it to 30 and MessageDisplay to 10. prompt hooks default to 30, agent hooks to 60, and SessionEnd hooks share a 1.5-second budget.¹

Do hooks run in parallel? Yes. All matching hooks run at once, and every one completes before results merge. For PreToolUse decisions, the most restrictive answer wins in the order deny, defer, ask, allow.¹

Can a hook use a model instead of a script? Yes. type: "prompt" runs a single-turn evaluation on Haiku by default. type: "agent" spawns a subagent with tool access, though agent hooks are experimental and the docs recommend command hooks for production.¹

Why does my hook's JSON do nothing? Almost always a shell profile printing something before your JSON. Stdout has to start with { or the whole thing is read as plain text, silently.¹

How do I turn hooks off? "disableAllHooks": true in a settings file. Note that a project's settings can override yours, and managed hooks keep running unless it's set there too.²

---

Where to start

Install two hooks this week. A PreToolUse guard on Edit|Write that protects .env and lockfiles, and a PostToolUse formatter on the same matcher. Both are ten lines. Both catch things you'd otherwise catch in review, or in CI, or not at all.

Then test them properly: pipe fake JSON into the script, check the exit code, and confirm from the transcript that a block actually blocks. A guardrail you never verified is worse than no guardrail, because you've stopped watching for the thing it was supposed to catch.

The honest limitation is that hooks only cover what you thought of in advance. They're a policy layer, not a safety net. If you're relying on a PreToolUse regex to be the only thing standing between Claude and your production database, the regex isn't the problem in that setup.

What's the one hook you'd never work without? I'm still looking for a good PostToolUseFailure pattern.

---

Sources

Footnotes

1. Automate actions with hooks, Claude Code Docs ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶ ↩²⁷ ↩²⁸ ↩²⁹ ↩³⁰ ↩³¹ ↩³² ↩³³ ↩³⁴ ↩³⁵ ↩³⁶ ↩³⁷ ↩³⁸ ↩³⁹

2. Hooks reference, Claude Code Docs ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶ ↩²⁷

3. Akshay Pachaar on X: CLAUDE.md is a suggestion, hooks are a guarantee ↩

4. Ado on X: hooks as middleware for your AI agent ↩

5. Boris Cherny on X: PostToolUse hook for formatting ↩

6. Practitioner example: block-rm.sh PreToolUse guardrail ↩

7. Ruchish Shah on X: filtering test output before the model sees it ↩

8. Ryosuke Sensui on X: enforcing Japanese-language rules with a PostToolUse hook ↩