Hooks Deep Dive

• Fire synchronously before/after Claude actions
• Shell scripts, HTTP endpoints, MCP tools, or prompts
• Can approve, block, or modify tool calls in-flight
• Configured in settings.json at project or global scope
• Run as the logged-in user — full filesystem access
• Receive context via stdin (JSON); respond via stdout

5 Handler Types

Level 1 — Event Name

Top-level key is the lifecycle event: PreToolUse, Stop, etc.

Level 2 — Matcher Group

• matcher — glob against tool name (optional; omit = all)
• if — boolean guard; skip spawn if false
• hooks — array of handler objects

Level 3 — Handler

• type — one of the 5 handler types
• command / url / tool_name / text — per type

matcher — glob on tool_name

"matcher": "Bash"         // exact
"matcher": "*"           // all tools
"matcher": "mcp__*"      // all MCP tools
"matcher": "Read|Edit"   // alternation

Matcher determines which tool events activate the group. Without it, all tool calls activate it.

if — boolean guard expression

// Skip spawn entirely when false
"if": "Bash(rm *)"
"if": "Bash(* --force)"
"if": "Edit(*.prod.*)"

Fires once when a Claude Code session begins. Ideal for injecting session-scoped environment variables.

CLAUDE_ENV_FILE

The harness sets CLAUDE_ENV_FILE in the hook's environment. Write KEY=VALUE lines to that path — they become env vars for the entire session.

CwdChanged

Fires when Claude's working directory changes. Re-inject project context or reload env files.

FileChanged

Fires when a file is modified. CLAUDE_ENV_FILE is available here too — reload config after a .env file changes.

Fires before any tool runs. The most powerful hook — you can approve, block, or modify the tool input.

stdin shape

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/old"
  },
  "session_id": "abc123"
}

Decision responses

• approve proceed as-is (or empty stdout)
• block cancel; reason shown to Claude
• modify replace via modifiedInput

Return decision: "modify" with modifiedInput to replace the tool's input before execution. Claude sees the modified version.

Fires after a tool completes. Receives input and output. Read-only — decisions are ignored.

stdin shape

{
  "tool_name": "Bash",
  "tool_input": { "command": "ls -la" },
  "tool_output": "total 48\ndrwxr-xr-x...",
  "tool_error": null,
  "session_id": "abc123"
}

Use cases

• Audit logging — who ran what, when
• Metrics — tool frequency, latency
• Alerting — writes to sensitive paths
• Side effects — notify Slack on deploys

Fires after Claude executes a batch of parallel tool calls. Receives an array of results.

stdin shape

{
  "tool_results": [
    {
      "tool_name": "Bash",
      "tool_input": {...},
      "tool_output": "..."
    }
  ],
  "session_id": "abc123"
}

Fires when Claude requests permission for a tool that isn't pre-approved. Implement custom authorization logic.

stdin shape

{
  "tool_name": "Bash",
  "tool_input": { "command": "..." },
  "permission_type": "tool_use",
  "session_id": "..."
}

Decision response

{ "decision": "approve" }  // or "deny"

// with modification — uses updatedInput!
{
  "decision": "approve",
  "updatedInput": { ... }
}

Fires when Claude is about to end its turn. You can block the stop to force Claude to continue work — the "rewake" pattern.

stdin shape

{
  "stop_reason": "end_turn",
  "session_id": "abc123"
}

The rewake pattern

The reason is injected as a new instruction, causing Claude to continue.

asyncRewake hooks run asynchronously in the background. To rewake Claude they exit 2 and write to stderr.

Shell form vs script path

// Inline shell string
{
  "type": "command",
  "command": "cat >> /tmp/audit.jsonl"
}

// Script file (recommended)
{
  "type": "command",
  "command": "~/.claude/hooks/my-hook.sh"
}

Path placeholders

• ${CLAUDE_PROJECT_DIR} — project root
• ${CLAUDE_PLUGIN_ROOT} — plugin install dir
• ${CLAUDE_PLUGIN_DATA} — plugin data dir
• $CLAUDE_ENV_FILE — env injection path

Execution model

• Runs via sh -c — system sh, not bash
• Working directory = project root
• stdin = event JSON (piped automatically)
• stdout = parsed for decision JSON (exit 0)
• stderr = logged (exit 0) or shown (exit 2)
• Default timeout applies — configurable per hook

HTTP handler

{
  "type": "http",
  "url": "https://hooks.slack.com/services/...",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "timeout": 5000
}

• Body = full event JSON (same as command stdin)
• Response body parsed as decision JSON
• HTTP errors ~ exit 1 (non-blocking)
• No process spawn — lower overhead

MCP tool handler

{
  "type": "mcp_tool",
  "tool_name": "my-server__my_tool",
  "input": {
    "event_data": "${EVENT_JSON}"
  }
}

• Calls an MCP tool registered in the session
• Tool must be available in current MCP config
• Tool response parsed as decision JSON
• Synchronous — blocks until tool returns

prompt — inject context

{
  "type": "prompt",
  "text": "When editing Go files, always run gofmt after writing."
}

• Injects text into Claude's conversation context
• Fires at event time, not session start
• Good for event-specific instructions
• Text can reference env vars via ${VAR}

agent — spawn subagent

{
  "type": "agent",
  "prompt": "Review the just-edited file for security issues.",
  "subagent_type": "claude"
}

• Spawns a Claude subagent for the event
• Subagent has full tool access
• Can return decisions to parent
• Higher latency — complex gating only

Standard decisions

// Approve (or empty stdout)
{ "decision": "approve" }

// Block with reason
{
  "decision": "block",
  "reason": "Force pushes are not permitted."
}

// Modify input (PreToolUse only)
{
  "decision": "modify",
  "modifiedInput": {
    "command": "git push origin HEAD"
  }
}

hookSpecificOutput

For events needing extra fields beyond a plain decision, wrap in hookSpecificOutput — hookEventName is required:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "decision": "block",
    "reason": "Post summary first"
  }
}

// terminalSequence: OS notification
{
  "terminalSequence": "\x1b]9;Done\x07"
}

settings.json config

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "Bash(rm *)",
        "hooks": [{
          "type": "command",
          "command": "~/.claude/hooks/guard-bash.sh"
        }]
      }
    ]
  }
}

Alternative: native HTTP handler

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{
          "type": "http",
          "url": "https://hooks.slack.com/...",
          "method": "POST",
          "timeout": 3000
        }]
      }
    ]
  }
}

Hooks can be defined in a skill's .md frontmatter. They are scoped to the skill's execution — active while the skill runs, then deactivated.

---
name: my-skill
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: ./skill-guard.sh
---

Skill instructions here...

Use cases

• Enforce dry-run mode during a review skill
• Block writes during a read-only audit skill
• Inject skill-specific environment context
• Log all tool calls during a debug skill

/hooks slash command

Run /hooks in any session to inspect active hooks:

• Lists all events with registered hooks
• Shows matcher, if guard, and handler type
• Indicates which config file each came from
• The fast path for debugging unexpected behavior

Config file precedence

Managed distribution

Teams distribute hook configs via committed .claude/settings.json:

# .claude/settings.json (committed)
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh"
      }]
    }]
  }
}

Hooks run as you

• Full filesystem and network access
• Can read secrets, modify files, call APIs
• No sandboxing — treat as first-class code
• Review committed hook scripts like production code

Input validation

• Parse stdin JSON safely (try/except)
• Never eval/exec values from stdin
• Quote all bash variables: "$VAR"
• Validate paths before writing
• Use absolute paths for commands

Injection prevention

## UNSAFE — command injection
CMD=$(echo "$STDIN" | jq -r .command)
eval "$CMD"          # NEVER

## SAFE — extract as data, never code
CMD=$(echo "$STDIN" | python3 -c "
import json,sys
print(json.load(sys.stdin)['tool_input']['command'])
")
echo "$CMD" | grep -qE 'pattern'

Common problems

Debug techniques

# 1. Log all stdin
cat >> /tmp/hook-stdin.jsonl

# 2. Run Claude in debug mode
claude --debug

# 3. Test the hook manually
echo '{"tool_name":"Bash",
  "tool_input":{"command":"ls"},
  "session_id":"test"}' \
  | ~/.claude/hooks/my-hook.sh

# 4. Inspect the exit code
echo $?