Claude Code Hook Capabilities
Reference for what hooks can do in Claude Code.
Why Hooks Matter: The Only Guarantee
Hook = 100% execution guarantee (event-based)
Skill/Agent/MCP = ~20-80% (Claude's judgment)
Key insight: Hooks are the ONLY mechanism that executes without Claude's decision.
See orchestration-patterns.md for forcing skill/agent activation.
5 Hook Roles
| Role | Description | Examples |
|---|
| Gate | Block/allow tool execution | Prevent dangerous commands, workflow precondition checks |
| Side Effect | Auto-actions after tool execution | Formatters, linters, auto-commit |
| State Manager | Workflow state management | State file creation/deletion, phase tracking |
| External Integrator | External system integration | MCP calls, HTTP API, WebSocket, Slack |
| Context Injector | Session context injection | Load project settings, activate services |
Event Types and Characteristics
| Event | Block | Special Features | Verification |
|---|
| SessionStart | No | source (compact/new) | Verified |
| UserPromptSubmit | Yes | stdout auto-injects into Claude context | Verified |
| PreToolUse | Yes | updatedInput modifies input, tool_use_id | Verified |
| PermissionRequest | Yes | allow/deny/ask + input modification | Unverified |
| PostToolUse | No | tool_response (access results) | Verified |
| Stop | Yes | stop_hook_active (loop prevention) | Verified |
| SubagentStop | Yes | parent-child correlation via tool_use_id | Unverified |
| Notification | No | includes notification_type | Verified |
| PreCompact | No | trigger (auto/manual) | Verified |
| SessionEnd | No | On session end | Unverified |
22 Universal Approaches
Control Patterns
| Approach | Description | Event |
|---|
| Iteration Control | Track iteration count + max limit | Stop |
| Force Continuation | Use exit 2 to continue Claude work | Stop |
| Promise Detection | Detect Claude response patterns, conditional exit | Stop |
| Infinite Loop Prevention | Prevent recursion via parent_tool_use_id | UserPromptSubmit |
| Threshold Branching | Branch based on error/warning count | Stop |
Input Manipulation
| Approach | Description | Event |
|---|
| Input Modification | Modify tool input via updatedInput | PreToolUse, PermissionRequest |
| Path Normalization | Auto-convert relative to absolute paths | PreToolUse |
| Environment Injection | Auto-inject environment variables | PreToolUse |
| Dry-run Enforcement | Auto-add --dry-run to dangerous commands | PreToolUse |
Context Management
| Approach | Description | Event |
|---|
| Context Injection | stdout auto-injects into Claude context | UserPromptSubmit |
| Progressive Loading | Load context/skills on demand | UserPromptSubmit |
| Skill Auto-Activation | Keywords trigger skill suggestions | UserPromptSubmit |
| Transcript Parsing | Read and analyze previous responses | Stop |
| Transcript Backup | Backup session transcript | PreCompact |
State Management
| Approach | Description | Event |
|---|
| Session Cache | Accumulate per-session state + aggregate results | PostToolUse |
| Session Lifecycle | Initialize/cleanup state via SessionStart/End | SessionStart/End |
| Checkpoint Commit | Checkpoint on every change, then squash | PostToolUse, Stop |
| Session Branching | Auto-isolate Git branches per session | Pre/PostToolUse |
External Integration
| Approach | Description | Event |
|---|
| Notification Forwarding | Forward notifications to Slack/Discord/external | Notification |
| Desktop/Audio Alert | osascript, notify-send, TTS | Notification |
| Subagent Correlation | Track parent-child via tool_use_id | SubagentStop |
Security & Compliance
| Approach | Description | Event |
|---|
| Auto-Approval | Auto-approve specific tools/commands | PermissionRequest |
| Secret Scanning | Detect and block API keys/secrets | PreToolUse |
| Compliance Audit | Compliance logging + violation detection | PostToolUse |
Implementation Techniques
| Approach | Description | Event |
|---|
| TypeScript Delegation | Delegate complex logic to .ts | Any |
| Hook Chaining | Execute multiple hooks sequentially | Any |
| Background Execution | Async via run_in_background | Any |
| Argument Pattern Matching | Match arguments like Bash(npm test*) | PreToolUse |
| MCP Tool Matching | Match MCP like mcp__memory__.* | PreToolUse |
| Prompt-Type Hook | LLM evaluation via type: "prompt" | Any |
Capabilities vs Limitations
| Possible | Not Possible |
|---|
| File create/delete/modify | Block in PostToolUse |
| MCP/HTTP/WebSocket calls | Direct Claude context modification |
| UserPromptSubmit stdout to context | Delete existing context |
| PreToolUse/PermissionRequest input modification | Cancel already-executed tools |
| Continue work from Stop | Unlimited forcing (infinite loop risk) |
Data Passing Methods (Important)
stdin JSON (Verified)
All session/project info is passed via stdin JSON:
session_id - Session UUIDcwd - Project directorytranscript_path - Session log file pathtool_use_id - Tool call ID (PreToolUse/PostToolUse)
stdin JSON Structure by Event
# UserPromptSubmit
{"prompt": "user message", "session_id": "...", "cwd": "/path"}
# PreToolUse / PostToolUse
{"tool_name": "Bash", "tool_input": {"command": "npm test"}, "session_id": "..."}
# PermissionRequest
{"tool_name": "Bash", "tool_input": {...}, "permission_type": "execute"}
# Stop
{"stop_reason": "end_turn", "session_id": "..."}
# SubagentStop
{"agent_name": "backend-dev", "result": "...", "session_id": "..."}
Environment Variables (Verified)
CLAUDE_PROJECT_DIR, CLAUDE_SESSION_ID etc. are NOT environment variables!
Actually set environment variables:
CLAUDE_CODE_ENABLE_CFC="false"
CLAUDE_CODE_ENTRYPOINT="cli"
Settings Reload
settings.json changes only apply in new sessions
Exit Code Reference
| Exit Code | Meaning | Behavior |
|---|
| 0 | Success/Allow | Normal proceed |
| 1 | Error | Hook failure, show warning |
| 2 | Block/Continue | Varies by event |
Exit 2 behavior by event:
| Event | exit 2 Behavior |
|---|
| PreToolUse | Block tool execution |
| PostToolUse | Ignore result (prompt retry) |
| PermissionRequest | Deny permission request |
| Stop | Force Claude to continue |
| UserPromptSubmit | Abort prompt processing |
Hook Execution Order
Multiple hooks on same event → Sequential execution (definition order)
One hook exits 2 → Subsequent hooks don't run
Timeout Setting
{"type": "command", "command": "script.sh", "timeout": 10000}
Default: 60000ms (1 minute)
Common Mistakes
| Mistake | Problem | Solution |
|---|
| Not reading stdin | Missing JSON input | INPUT=$(cat) required |
| stdout debug output | Context pollution | Use stderr (>&2) |
| exit 1 vs exit 2 confusion | Unintended behavior | exit 1=error, exit 2=block |
| Parsing without jq | Unstable | Install and use jq |
References
- Event Details - 10 event specifications
- Pattern Details - Role, usage, examples
- Orchestration Patterns - Force skill/agent activation
- Real-World Examples - Implementation case studies
- Advanced Patterns - Complex combinations
