hook-capabilities

chkim-su's avatarfrom chkim-su

Claude Code Hook system reference for capabilities, possibilities, and limitations. Use when you want to know what hooks can do.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026⬇️3downloads
[Tool Routing and Orchestration]

When & Why to Use This Skill

This Claude skill serves as a comprehensive technical reference for the Claude Code Hook system, a powerful framework for event-based execution. Unlike standard agentic tools that rely on LLM judgment, hooks provide a 100% execution guarantee for specific events. It enables developers to build sophisticated workflows including security gates, automated side effects, state management, and external system integrations, ensuring precise control over the AI's operational lifecycle.

Use Cases

  • Security & Compliance: Implementing automated secret scanning to detect and block API keys or sensitive data before a tool executes.
  • Workflow Automation: Setting up 'Side Effect' hooks to automatically run linters, formatters, or git commits immediately after code modifications.
  • Context Injection: Dynamically injecting project-specific settings, environment variables, or session history into the Claude context based on user prompts.
  • Guardrails: Creating 'Gate' hooks that intercept dangerous commands or enforce dry-run modes for critical infrastructure changes.
  • External Integration: Forwarding agent notifications and status updates to external platforms like Slack, Discord, or custom monitoring dashboards.
namehook-capabilities
descriptionClaude 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

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 UUID
  • cwd - Project directory
  • transcript_path - Session log file path
  • tool_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