A comprehensive framework for mastering Claude Code hooks, covering all 13 lifecycle events with prompt-level control, security hardening, TTS feedback, sub-agent orchestration, and team-based validation workflows. Built on UV single-file script architecture with complete examples and video tutorials.

Claude Code Hooks Mastery#

Overview#

Claude Code Hooks Mastery is a comprehensive framework for mastering Claude Code hooks, covering all 13 hook lifecycle events with prompt-level control, security hardening, TTS feedback, sub-agent orchestration, and team-based validation workflows.

Hook Lifecycle Events#

Hook Event	Trigger	Core Capability
UserPromptSubmit	When user submits prompt	Validate/block/log prompt, inject context
PreToolUse	Before tool execution	Block dangerous commands, sensitive file access control
PostToolUse	After successful tool execution	Logging, JSONL→JSON conversion
PostToolUseFailure	On tool execution failure	Error handling, alerts
Notification	When Claude Code sends notification	TTS alerts, custom notification handling
Stop	When Claude Code completes response	Force continue, additional processing
SubagentStart	When Subagent starts	Logging, context injection
SubagentStop	When Subagent completes	TTS playback, result processing
PreCompact	Before compact operation	Session backup, state saving
SessionStart	New session start/resume	Load dev context, environment init
SessionEnd	Session end	Cleanup tasks, state saving
PermissionRequest	Permission dialog display	Permission audit, auto decision
Setup	Repository entry or periodic maintenance	Environment check, dependency update

Core Features#

Security & Control#

Command Blocking: PreToolUse intercepts rm -rf, sudo rm, chmod 777 patterns
File Access Control: Sensitive file path protection
Prompt Validation: UserPromptSubmit supports security validation mode
Permission Audit: PermissionRequest hook logs all permission requests

TTS Feedback System#

Voice priority: ElevenLabs > OpenAI > pyttsx3

Sub-Agent & Team Validation#

Meta-Agent: Agent specialized in generating new sub-agents
Builder: All tools, executes implementation tasks, self-validates with Ruff + Ty
Validator: Read-only, verifies builder work meets acceptance criteria

Output Styles (9 types)#

Style	Description	Best Use
genui	Beautiful HTML with embedded styles	Interactive visual output
table-based	Markdown table organization	Comparisons, structured data
yaml-structured	YAML config format	Settings, hierarchical data
bullet-points	Clear nested lists	Task tracking, documentation
ultra-concise	Minimal words, max speed	Rapid prototyping
html-structured	Semantic HTML5	Web documentation
markdown-focused	Optimized markdown features	Complex documents
tts-summary	Announce completion via ElevenLabs TTS	Audio feedback

Status Lines (v1-v9)#

Real-time terminal status display: Git branch, directory, model info, latest prompt, cost tracking, context window usage, session duration, Token/cache stats, etc.

Architecture#

Uses UV Single-File Script Architecture:

Isolation: Hook logic separated from project dependencies
Portability: Each hook script declares its own dependencies inline
Zero venv management: UV handles dependency resolution automatically
Fast execution: UV dependency resolution is extremely fast

Key File Structure#

.claude/
├── settings.json          # Hook config & permissions
├── hooks/                 # Python hook scripts
│   ├── user_prompt_submit.py
│   ├── pre_tool_use.py
│   ├── post_tool_use.py
│   ├── validators/        # Code quality validation hooks
│   └── utils/             # TTS and LLM utility scripts
├── status_lines/          # Real-time terminal status (v1-v9)
├── output-styles/         # Response formatting config
├── commands/              # Custom slash commands
└── agents/                # Sub-agent config
    ├── team/
    │   ├── builder.md
    │   └── validator.md
    └── meta-agent.md
logs/                      # JSON logs
ai_docs/                   # Documentation resources

Configuration & Usage#

Hook Config Example#

"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/user_prompt_submit.py --log-only"
      }
    ]
  }
]

Hook Options#

--log-only: Log prompt only (default)
--validate: Enable security validation
--context: Add project context to prompt

Exit Code Behavior#

Exit Code	Behavior	Description
0	Success	Hook executed successfully
2	Blocking Error	stderr fed back to Claude
Other	Non-blocking Error	stderr shown to user

Requirements#

Required:

Astral UV - Fast Python package installer and resolver
Claude Code - Anthropic's Claude AI CLI

Optional:

ElevenLabs - Text-to-speech provider
OpenAI - Language model + TTS provider
Anthropic - Language model provider
Ollama - Local language model provider

Claude Code Hooks Mastery