Hook System Guide

Entry point for Claude Code Hook system. Routes to appropriate skills.

What are Hooks?

Scripts that auto-execute at specific events during Claude Code sessions.

User Input → [UserPromptSubmit Hook] → Claude Processing
          → [PreToolUse Hook] → Tool Execution → [PostToolUse Hook]
          → Claude Response → [Stop Hook] → End

Skill Selection Guide

| Question | Skill | |----------|-------| | What can hooks do? | hook-capabilities | | Need pattern/implementation examples | hook-capabilities → references | | Need templates for quick start | hook-templates | | Want to call LLM from hooks | hook-sdk-integration | | Need cost optimization | hook-sdk-integration | | Want background execution | hook-sdk-integration |

Quick Decision Tree

Hook Question
    │
    ├─ "What's possible?" ──────→ hook-capabilities
    │
    ├─ "How to implement?" ─────→ hook-capabilities/patterns-detailed.md
    │
    ├─ "Need templates?" ───────→ hook-templates
    │
    ├─ "LLM evaluation?" ───────→ hook-sdk-integration
    │
    └─ "Real project examples?" → hook-capabilities/real-world-examples.md
                                  hook-sdk-integration/real-world-projects.md

Hook Skills Architecture

                    hook-system (You are here)
                         │ Entry Point
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
   hook-capabilities  hook-templates  hook-sdk-integration
   ┌─────────────┐   ┌────────────┐   ┌─────────────────┐
   │ WHAT/WHY   │   │ HOW       │   │ ADVANCED       │
   │ • Events    │   │ • Gate    │   │ • LLM calls    │
   │ • Patterns  │   │ • Side Fx │   │ • Background   │
   │ • Debugging │   │ • Orch.   │   │ • Cost optim.  │
   └─────────────┘   └────────────┘   └─────────────────┘
         │                                    │
         └──────────► workflow-state-patterns ◄┘
                      (Multi-phase flows)

Related Skills

| Skill | Role | When to Use | |-------|------|-------------| | hook-capabilities | Events, patterns, debugging | First stop - understanding what's possible | | hook-templates | Gate/Side-effect/Orchestration templates | Implementation - copy-paste ready code | | hook-sdk-integration | SDK/CLI LLM calls | Advanced - AI evaluation in hooks | | workflow-state-patterns | State-based multi-phase workflows | Complex - chained automation with gates |

Core Concepts

Activation Reliability

| Method | Success Rate | When to Use | |--------|--------------|-------------| | Hook | 100% | Forced automation | | Hook + Forced Eval | 84% | Skill activation | | Skill (default) | ~20% | Simple suggestions | | MCP (all tools) | ~13% | Many tools loaded | | MCP (Tool Search) | ~43-88% | Enable enableToolSearch |

Events (10 types)

| Event | Can Block | Use For | |-------|-----------|---------| | SessionStart | ❌ | Initialization | | UserPromptSubmit | ✅ | Context injection | | PreToolUse | ✅ | Gate (block/modify) | | PostToolUse | ❌ | Side Effects | | Stop | ✅ | Termination control |

Data Passing

# Passed via stdin JSON (NOT environment variables!)
INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

Blocking

exit 0   # Allow
exit 2   # Block (stderr → feedback to Claude)

MCP Tool Search

Enable for better tool selection (13% → 43%+):

{
  "mcpServers": {
    "my-server": {
      "command": "...",
      "enableToolSearch": true
    }
  }
}

References

• Detailed Skill Selection Guide