tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.