Claude Code Hooks: Events, Exit Codes and Examples

Claude Code has 33 hook events, and exit 2 blocks on 16 of them. One-page tables of events, exit codes and JSON fields, plus links to our tested hook guides.

Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts or subagents that Claude Code runs automatically at specific points in its lifecycle. They fire the same way in the terminal, IDE extensions, the Desktop app and cloud sessions. This page is a reference: one table of every event, one table of exit codes and JSON fields, a minimal example, and links to our guides that test each kind of hook. We checked everything against the official hooks reference on 2026-10-24, with Claude Code 2.1.310.

Every hook event

The docs list 33 events. “Exit 2” says what happens when a hook on that event exits with code 2. “Matcher” says what the matcher field is compared with; “none” means the event has no matcher support and always fires.

Source: https://code.claude.com/docs/en/hooks (checked 2026-10-24)

Sixteen events can block with exit 2: PreToolUse, UserPromptSubmit, UserPromptExpansion, Stop, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted, ConfigChange, PostToolBatch, PreCompact, PreModelSwitch, Elicitation, ElicitationResult, WorktreeCreate and WorktreeRemove. WorktreeCreate and WorktreeRemove fail on any non-zero exit code, and WorktreeRemove only when the directory still exists afterward.

Exit codes and JSON output

Common JSON fields:

Source: https://code.claude.com/docs/en/hooks (checked 2026-10-24)

Where hooks live, and a minimal example

Hook entries merge across these levels instead of replacing each other (source: https://code.claude.com/docs/en/hooks, checked 2026-10-24).

The smallest useful PreToolUse hook blocks one command. This one stops npm publish in a dummy project:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/no-publish.sh" } ] }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/no-publish.sh  (PreToolUse, matcher: Bash)
cmd=$(jq -r '.tool_input.command // ""')
case "$cmd" in
  *"npm publish"*) echo "Blocked: publishing is done by a human." >&2; exit 2 ;;
esac
exit 0

We piped dummy JSON into it on 2026-10-24. {"tool_name":"Bash","tool_input":{"command":"npm publish"}} printed Blocked: publishing is done by a human. and exited 2. npm test exited 0. The settings file passed jq and claude doctor. We did not watch it fire in a live session.

Our hook guides, in reading order

Start with the concepts, then copy an example, then debug, then design.

• Claude Code Hooks in Practice: why a hook beats a prose rule, what exit codes really do, and how we found holes in a git guard by measuring it.
• Claude Code PreToolUse Hook Examples: six copy-paste PreToolUse hooks, from blocking rm -rf / and secret files to asking before migrations.
• Claude Code PostToolUse: Format and Test on Edit: run Prettier and the tests after every edit, and why PostToolUse can report but not undo.
• Claude Code UserPromptSubmit Hook Examples: add git context to every prompt and block prompts that contain API keys, with the 30-second timeout in mind.
• Claude Code Stop Hook: Verify Before It Stops: keep Claude working until the tests pass, and the loop guard you need.
• Claude Code Hooks Not Working? A Checklist: the causes we reproduced, from invalid JSON to a missing jq that let everything through.
• Don’t Trust an Agent’s “Done”: using hooks and git numbers to check an agent’s completion report.
• Permission Design for AI Agents: how deny rules and hooks are evaluated, and letting an agent read production without writing.
• Claude Code settings.json Permissions: A Cheat Sheet: allow, ask and deny rules to pair with your hooks.

Summary

• Claude Code has 33 hook events; 16 of them can block with exit 2.
• Exit 0 is success and exit 2 blocks where the event allows it. Other exit codes let the action through unless the hook prints valid JSON that decides otherwise.
• "onFailure": "block" (v2.1.295+) makes a crashed or timed-out hook fail closed, except on Stop-type and async hooks.
• Use PreToolUse to stop a tool call, PostToolUse to report after one, and Stop to check work before Claude finishes.
• Hooks from user, project, local, managed and plugin settings merge rather than replace each other.