---

name: hook-capabilities description: Claude Code Hook system reference for capabilities, possibilities, and limitations. Use when you want to know what hooks can do. allowed-tools: ["Read"]

Claude Code Hook Capabilities

Reference for what hooks can do in Claude Code.

Why Hooks Matter: The Only Guarantee

CopyHook = 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

Event Types and Characteristics

22 Universal Approaches

Control Patterns

Input Manipulation

Context Management

State Management

External Integration

Security & Compliance

Implementation Techniques

Capabilities vs Limitations

Data Passing Methods (Important)

stdin JSON (Verified)

All session/project info is passed via stdin JSON:

• session_id - Session UUID
• cwd - Project directory
• transcript_path - Session log file path
• tool_use_id - Tool call ID (PreToolUse/PostToolUse)

stdin JSON Structure by Event

Copy# 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:

CopyCLAUDE_CODE_ENABLE_CFC="false"
CLAUDE_CODE_ENTRYPOINT="cli"

Settings Reload

• settings.json changes only apply in new sessions

Exit Code Reference

Exit 2 behavior by event:

Hook Execution Order

CopyMultiple hooks on same event → Sequential execution (definition order)
One hook exits 2 → Subsequent hooks don't run

Timeout Setting

Copy{"type": "command", "command": "script.sh", "timeout": 10000}

Default: 60000ms (1 minute)

Common Mistakes

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