Anthropic Hooks Reference

Anthropic Hooks Reference

Part of the Anthropic Best Practices series. Covers: All 14 hook event types, input/output schemas, configuration, and design patterns.

Sources:

• Claude Code Hooks Reference (code.claude.com/docs/en/hooks)
• Claude Code Hooks Guide (code.claude.com/docs/en/hooks-guide)

25. Hooks -- Lifecycle Events & Context Injection

Hooks are shell commands (or LLM prompts) that fire at specific lifecycle events. They let you observe, block, modify, or inject context into Claude's behavior -- without changing the model itself.

Architecture

  User prompt -> [UserPromptSubmit] -> Claude thinks -> [PreToolUse] -> Permission check
       |                                                  |
  [SessionStart]                                   [PermissionRequest]
                                                          |
                                               Tool executes (or blocked)
                                                          |
                                                   [PostToolUse] or [PostToolUseFailure]
                                                          |
                                               Claude responds -> [Stop]
                                                          |
                                               [Notification] (if idle/permission)
                                                          |
                                               [SessionEnd] (on exit)

Subagent lifecycle: [SubagentStart] -> subagent works -> [SubagentStop] Team lifecycle: teammate works -> [TeammateIdle] / [TaskCompleted] Context management: [PreCompact] -> compaction occurs

Hook Handler Types

Three types of handler can be attached to any event:

{
  "type": "command",
  "command": "python hooks/my_hook.py",
  "async": false,
  "timeout": 600,
  "statusMessage": "Running quality check...",
  "once": false
}

Exit Code Protocol

Common Input Fields (All Events)

Every hook receives these on stdin as JSON:

Universal Output Fields (All Events)

Any hook can return these in the stdout JSON:

Event Reference

1. SessionStart

When: Session begins, resumes, clears, or compacts. Matcher values: startup, resume, clear, compact Can block: No

Input fields:

Output actions:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project is on sprint 14. Focus area: payments."
  }
}

2. UserPromptSubmit

When: User submits a prompt, before Claude processes it. Matcher: None Can block: Yes (exit 2, or decision: "block" in output)

Input fields:

Output actions:

{
  "decision": "block",
  "reason": "Prompt contains production database credentials. Remove them before submitting.",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "User's last prompt was blocked for containing secrets."
  }
}

Use cases: Secret scanning, prompt transformation, injecting project state.

3. PreToolUse

When: Before a tool executes (before permission check). Matcher: Tool name regex -- Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch, mcp__server__tool Can block: Yes (via permissionDecision: "deny")

Input fields:

Tool-specific tool_input shapes:

Output actions:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Cannot write to production config files.",
    "updatedInput": null,
    "additionalContext": "Tool call was blocked by project policy."
  }
}

Use cases: Auto-approve safe operations, block dangerous commands, rewrite file paths, inject warnings.

4. PermissionRequest

When: A permission dialog is about to be shown to the user. Matcher: Tool name regex (same as PreToolUse) Can block: Yes (via decision.behavior: "deny")

Input fields:

Output actions:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": { "command": "npm test -- --bail" },
      "updatedPermissions": {}
    },
    "interrupt": false
  }
}

Use cases: Auto-approve CI-safe commands, enforce org policies, add safety flags to commands.

5. PostToolUse

When: After a tool executes successfully. Matcher: Tool name regex Can block: Yes (via decision: "block" -- doesn't undo the tool, but tells Claude to address the issue)

Input fields:

Output actions:

{
  "decision": "block",
  "reason": "File was written without 'use server' directive. Add it before proceeding.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Lint check failed on the written file.",
    "updatedMCPToolOutput": null
  }
}

Use cases: Post-write linting, enforcing coding standards, augmenting tool output, telemetry.

6. PostToolUseFailure

When: After a tool fails. Matcher: Tool name regex Can block: No

Input fields:

Output actions:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "This error usually means the Supabase container isn't running. Try: pnpm supabase:web:start"
  }
}

Use cases: Error enrichment, suggested fixes, failure telemetry.

7. Stop

When: Claude finishes its response and is about to stop. Matcher: None Can block: Yes (via decision: "block" -- tells Claude to keep working)

Input fields:

Output actions:

{
  "decision": "block",
  "reason": "You haven't run pnpm verify yet. Run typecheck + lint + test before stopping."
}

Use cases: Enforce verification steps, ensure Claude doesn't stop prematurely, append summaries.

Warning: Check stop_hook_active to avoid infinite loops -- if it's true, a previous stop hook already forced continuation this turn.

8. Notification

When: Claude Code sends a system notification (permission prompt, idle, auth, dialog). Matcher: permission_prompt, idle_prompt, auth_success, elicitation_dialog Can block: No

Input fields:

Output actions:

Use cases: Custom notification routing (Slack, desktop), telemetry, notification filtering.

9. SubagentStart

When: A subagent (Task tool) is spawned. Matcher: Agent type regex -- Bash, Explore, Plan, or custom agent names Can block: No

Input fields:

Output actions:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "You are working in a monorepo. Always use absolute paths."
  }
}

Use cases: Inject project rules into subagents, log subagent spawning, enforce subagent policies.

10. SubagentStop

When: A subagent finishes its work. Matcher: Agent type regex Can block: Yes (via decision: "block" -- tells subagent to keep working)

Input fields:

Output actions:

{
  "decision": "block",
  "reason": "Subagent output is missing test coverage. Write tests before finishing."
}

Use cases: Quality gates on subagent output, transcript analysis, telemetry.

11. PreCompact

When: Before context window compaction occurs. Matcher: manual, auto Can block: No Output: Exit code only -- no JSON decision control.

Input fields:

Use cases: Save pre-compaction state, log context size, inject compaction instructions.

12. SessionEnd

When: Session terminates. Matcher: clear, logout, prompt_input_exit, bypass_permissions_disabled, other Can block: No Output: Exit code only -- no JSON decision control.

Input fields:

Use cases: Cleanup, final telemetry, save session summaries.

13. TeammateIdle (Agent Teams)

When: An agent team teammate is about to go idle. Matcher: None Can block: Exit code 2 only (stderr as feedback). No JSON decision control.

Input fields:

Use cases: Prevent premature idling, reassign work, log idle patterns.

14. TaskCompleted (Agent Teams)

When: A task is being marked as completed. Matcher: None Can block: Exit code 2 only (stderr as feedback). No JSON decision control.

Input fields:

Use cases: Verify acceptance criteria, enforce "tests must pass" gates, log completion metrics.

Hook Configuration Structure

Hooks are configured in settings.json (project or user level):

{
  "hooks": {
    "EventName": [
      {
        "matcher": "regex_pattern",
        "hooks": [
          {
            "type": "command",
            "command": "python hooks/my_hook.py",
            "async": false,
            "timeout": 600,
            "statusMessage": "Checking...",
            "once": false
          }
        ]
      }
    ]
  }
}

Matcher examples:

Hook Scope & Priority

Async Hooks

Setting "async": true on command hooks runs them in the background:

• Hook output is delivered on the next conversation turn
• Cannot block or modify tool calls (already completed)
• Only systemMessage and additionalContext are processed from output
• Ideal for telemetry, logging, and non-blocking notifications

Design Patterns

Pattern 1: Pre/Post Sandwich (Quality Gates)

PreToolUse(Write) -> validate file path, inject coding standards
  | tool executes
PostToolUse(Write) -> lint the written file, flag issues

The user depends on this pattern for enforcing import 'server-only', 'use client', and coding standards without manual review.

Pattern 2: Context Enrichment Pipeline

SessionStart -> inject project status, sprint context
UserPromptSubmit -> inject relevant file context based on prompt analysis
PreToolUse -> inject tool-specific guidance
PostToolUse -> inject follow-up suggestions

Each hook adds targeted context, building a rich understanding without bloating the system prompt.

Pattern 3: Telemetry Pipeline (Async)

Every event -> async send_event.py -> external analytics

Non-blocking telemetry on every lifecycle event. The async flag ensures zero latency impact.

Pattern 4: Stop Gate (Verification Enforcement)

Stop -> check if pnpm verify was run -> block with reason if not

Prevents Claude from stopping before running required verification steps.

Pattern 5: Subagent Policy Injection

SubagentStart -> inject project rules into subagent context
SubagentStop -> analyze transcript, block if quality insufficient

Ensures subagents follow project conventions even though they don't inherit the parent's CLAUDE.md.

Lessons Learned