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

bash

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

Blocking

bash

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

MCP Tool Search

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

json

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

References

Detailed Skill Selection Guide

Search AI Tools

hook-system

Install this agent skill to your Project

SKILL.md