Hooks Reference

Hooks Reference

I. Philosophy

Hooks are the mechanical enforcement layer of agent safety and observability. Unlike CLAUDE.md instructions, which guide agent behavior through documentation, hooks execute code at lifecycle boundaries where the agent cannot override them. A well-designed hook system makes dangerous operations impossible rather than merely discouraged.

This skill is a reference card, not a tutorial. It assumes you know what hooks are and need to quickly find the right event, the right exit code, or the right configuration pattern. For architectural understanding, read the seed_hooks_lifecycle_mastery and seed_mechanical_safety_enforcement seeds.

II. When to Use

• Writing a new hook and need to know which event type to target.
• Debugging why a hook is not firing (wrong event name, wrong exit code).
• Reviewing the full lifecycle to understand execution order.
• Implementing a security block pattern (exit code 2).
• Configuring hooks in .claude/settings.json or plugin hooks/hooks.json.
• Building sub-agent coordination via SubagentStart/SubagentStop hooks.

Do not use this skill for designing observability dashboards (use observability-dashboard instead) or for understanding the correction-capture pipeline (use reflect-and-learn instead).

III. All 26 Lifecycle Events

Events are organized by category. The "Block?" column indicates whether exit 2 halts execution.

Session Events

User / Prompt Events

Tool Execution Events

SubAgent Events

Completion Events

Context Events

Config / File Events

Worktree Events

Agent-Team Events

MCP Events

NOTE: TaskCompleted does NOT exist in Claude Code hooks. Do not register or reference it.

IV. Exit Code Reference

Critical: exit 1 does NOT block. Only exit 2 blocks. This is the single most common hook debugging mistake.

V. Four Hook Types

command (default)

Runs a shell script or executable. Receives event JSON on stdin.

{
  "hooks": {
    "PreToolUse": [{"matcher": "Write", "hooks": [{"type": "command", "command": "python3 .claude/hooks/guard.py"}]}]
  }
}

prompt

Single-turn Haiku LLM call. Returns {"ok": true/false, "reason": "..."}. Low latency but requires network. Best for Stop/SubagentStop task-completion enforcement.

{"type": "prompt", "prompt": "Did the agent complete all required steps? Check for missing tests."}

agent

Spawns a subagent with Read/Grep/Glob for codebase verification. Returns {"ok": true/false, "reason": "..."}. 60-second timeout, 50 tool turns. Use on Stop for deep multi-file verification.

{"type": "agent", "prompt": "Verify all modified Go files compile. Run go build ./... and report."}

http

POSTs event JSON to an HTTP endpoint. Response uses the same format as command hooks. Headers support $VAR interpolation (requires allowedEnvVars list).

{"type": "http", "url": "https://hooks.example.com/events", "headers": {"Authorization": "Bearer $HOOK_TOKEN"}, "allowedEnvVars": ["HOOK_TOKEN"]}

VI. Advanced Features

if Field (PreToolUse / PostToolUse scoping)

Scopes a hook to specific tool+argument patterns without spawning a process. Only works on: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied.

{"if": "Write(**/SKILL.md)", "hooks": [{"type": "command", "command": "skill-validate.sh"}]}
{"if": "Bash(git *)", "hooks": [{"type": "command", "command": "git-guard.py"}]}

async: true

Runs the hook in the background. Exit code and stdout are ignored. Use for logging and notifications where latency matters.

{"type": "command", "command": "logger.py", "async": true}

updatedInput (PreToolUse)

PreToolUse hooks can rewrite tool arguments before the tool executes via stdout JSON:

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow", "updatedInput": {"content": "...modified content..."}}}

additionalContext (PreToolUse)

Inject context without blocking. Claude sees this as additional background:

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": "Note: this file is under active review."}}

updatedMCPToolOutput (PostToolUse)

PostToolUse hooks can replace MCP tool output before Claude sees it:

{"hookSpecificOutput": {"hookEventName": "PostToolUse", "updatedMCPToolOutput": "...filtered output..."}}

stop_hook_active

Field present in Stop hook stdin JSON when a Stop hook already forced continuation this turn. Check this to prevent infinite loops:

event = json.loads(sys.stdin.read())
if event.get("stop_hook_active"):
    sys.exit(0)  # Do not force continuation again

$CLAUDE_ENV_FILE

Write export VAR=val lines to this file path (available in env) during SessionStart or CwdChanged hooks to persist environment variables across all subsequent Bash calls in the session.

Plugin Hooks

Plugin hooks live at {plugin-root}/hooks/hooks.json with the same format as the hooks object in settings.json. Two extra env vars are available inside plugin hooks:

• $CLAUDE_PLUGIN_ROOT — absolute path to the plugin directory
• $CLAUDE_PLUGIN_DATA — writable data directory for the plugin

VII. Workflow

Step 1 -- Identify the lifecycle stage. Use the event tables in Section III to find the right event.

Step 2 -- Choose the enforcement pattern.

• Block (exit 2): halts the operation. Only for PreToolUse, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TeammateIdle, TaskCreated, ConfigChange, Elicitation, ElicitationResult, WorktreeCreate.
• Observe (exit 0): event logged, execution continues. Use for all non-blocking events.
• Modify (stdout JSON): rewrites inputs or injects context. Use updatedInput, additionalContext, updatedMCPToolOutput.

Step 3 -- Write the hook script.

UV single-file Python with embedded dependencies:

# /// script
# dependencies = ["requests"]
# ///
import json, sys

event = json.loads(sys.stdin.read())
tool_name = event.get("tool_name", "")
tool_input = event.get("tool_input", {})

# Guard: block writes to protected paths
if tool_input.get("file_path", "").endswith("CLAUDE.md"):
    print("Blocked: CLAUDE.md is write-protected", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

Step 4 -- Register in settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/pre-tool-use/guard.py"}]
      }
    ],
    "Stop": [
      {
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/stop/done-notify.py"}]
      }
    ]
  }
}

Step 5 -- Test the hook. Trigger the target event in a real session. Verify side effects (log file, blocked operation, HTTP POST).

VIII. Hooks Active in This Ecosystem

These hooks are registered in ~/.claude/settings.json (global, fires in all projects):

IX. Quality Checklist

• Hook targets the correct lifecycle event (check Section III)
• Exit code matches intent (0 = observe, 2 = block, NOT 1)
• stop_hook_active guard present in all Stop hooks
• Script is idempotent (safe to re-execute)
• Performance acceptable for hot-path hooks (PreToolUse fires on every tool call)
• Hook registered in settings.json or plugin hooks.json
• async: true used for logging/notification hooks to avoid latency

X. Related Skills

• observability-dashboard -- Visualize events captured by hooks
• tool-intercept-logger -- OTEL-compatible tool call logging
• claude-md-guardian -- Protect CLAUDE.md via hook enforcement
• agent-performance-report -- Aggregate hook data into performance metrics

Output

• A UV single-file Python hook script (with embedded dependency declarations) ready to drop into .claude/hooks/{event-type}/.
• A settings.json snippet registering the hook under the correct event key.
• Exit code guidance specific to the chosen enforcement pattern (0 = observe, 2 = block — never 1).

Examples

Scenario 1: "I want to block sub-agents from writing to CLAUDE.md" → PreToolUse hook with if: "Write|Edit(**/CLAUDE.md)" field. Script exits 2 when matched. Settings.json snippet with if scoping provided. Scenario 2: "Log every tool call to a file for debugging" → PostToolUse hook (exit 0, async: true) that appends tool_name, duration_ms, and status to .claude/hooks/tool-log.jsonl. No blocking. Scenario 3: "Verify all required steps are done before agent stops" → Stop hook using prompt or agent type. Guard with stop_hook_active check to prevent infinite loop. Scenario 4: "Persist an API key across Bash calls after SessionStart" → SessionStart hook that writes export MY_API_KEY=... to $CLAUDE_ENV_FILE.

Edge Cases

• Stop hooks that trigger agent re-runs MUST check stop_hook_active in stdin JSON and exit 0 if true — without this guard the hook will loop until the session is killed.
• If a PreToolUse hook has heavy imports, move them inside the function or use lazy loading — a 2-second import delay fires on every single tool call.
• WorktreeCreate blocks on any non-zero exit, not just exit 2. All other blocking events require specifically exit 2.
• CwdChanged cannot block, but $CLAUDE_ENV_FILE is the correct channel to propagate environment changes to subsequent Bash calls.
• prompt and agent hook types require network access; if the network is unavailable they will fail non-blockingly (treated as exit 1).

Anti-Patterns

• Using the wrong event name casing ("pre_tool_use" instead of "PreToolUse") — the hook silently never fires.
• Using exit 1 intending to block — exit 1 shows a warning but does NOT block. Only exit 2 blocks.
• Referencing TaskCompleted — this event does not exist in Claude Code. Use Stop or SubagentStop instead.
• Assuming hooks survive context compaction — use Setup/SessionStart hooks for re-initialization rather than relying on context that may be compacted away.
• Writing heavy synchronous hooks on PostToolUse without async: true — blocks Claude's response loop for every tool execution.