Hooks Deep Dive

• Fire synchronously before/after Claude actions
• Shell scripts, HTTP endpoints, MCP tools, or prompts
• Approve, block, or modify tool calls in-flight
• Configured in settings.json — 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 vs 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

matcher — glob on tool_name

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

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

if — boolean guard

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

Fires once when a 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 whole session.

CwdChanged

Fires when the 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 heavyweight — approve, block, or modify the tool input.

stdin

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

Decisions

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 + output. Read-only — decisions are ignored.

stdin

{
  "tool_name": "Bash",
  "tool_input": { "command": "ls -la" },
  "tool_output": "total 48...",
  "tool_error": null
}

Use cases

• Audit logging — who ran what, when
• Metrics — tool frequency, latency
• Alerting — writes to sensitive paths

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

stdin

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

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

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

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

Fires when Claude is about to end its turn. Block the stop to force Claude to keep working — the "rewake".

The rewake pattern

The reason is injected as a new instruction, so Claude continues.

asyncRewake hooks run asynchronously. 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/h.sh" }

Path placeholders

• ${CLAUDE_PROJECT_DIR} — project root
• ${CLAUDE_PLUGIN_ROOT} — plugin dir
• $CLAUDE_ENV_FILE — env injection

Execution model

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

HTTP handler

{ "type": "http",
  "url": "https://hooks.slack.com/...",
  "method": "POST",
  "timeout": 5000 }

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

MCP tool handler

{ "type": "mcp_tool",
  "tool_name": "my-server__tool",
  "input": { "data": "${EVENT_JSON}" } }

• Calls a registered MCP tool
• Must be in current MCP config
• Tool response parsed as decision
• Synchronous — blocks until return

prompt — inject context

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

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

agent — spawn subagent

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

• Spawns a Claude subagent
• Subagent has full tool access
• Can return decisions to parent
• Higher latency — gate carefully

Standard decisions

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

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

// Modify (PreToolUse only)
{ "decision": "modify",
  "modifiedInput": { "command": "..." } }

hookSpecificOutput

Events needing extra fields wrap in hookSpecificOutput — hookEventName required:

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

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

settings.json

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

Or: 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're scoped to the skill's execution — active while it runs, then deactivated.

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

Use cases

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

/hooks slash command

• Lists all events with registered hooks
• Shows matcher, if guard, handler type
• Indicates the source config file
• Fast path for debugging

Precedence

Managed distribution

# .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 + network access
• Can read secrets, modify files, call APIs
• No sandboxing — first-class code
• Review committed hooks like prod code

Input validation

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

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

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

Debug techniques

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

# 2. Debug mode
claude --debug

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

# 4. Check exit code
echo $?