Claude Code Hooks 全面掌握框架，覆盖全部 13 个 hook 生命周期事件，支持 Prompt 级别控制、安全增强、TTS 语音反馈、Sub-Agent 编排与团队验证工作流。基于 UV 单文件脚本架构，提供完整示例代码、配置模板和视频教程。

Claude Code Hooks Mastery#

项目概述#

Claude Code Hooks Mastery 是一套完整的 Claude Code hooks 学习与实战框架，覆盖全部 13 个 hook 生命周期事件，支持 Prompt 级别控制、安全增强、TTS 反馈、Sub-Agent 编排与团队验证工作流。

Hook 生命周期事件#

Hook 事件	触发时机	核心能力
UserPromptSubmit	用户提交 prompt 时	验证/阻止/记录 prompt、注入上下文
PreToolUse	工具执行前	阻止危险命令、敏感文件访问控制
PostToolUse	工具成功执行后	日志记录、JSONL→JSON 转换
PostToolUseFailure	工具执行失败时	错误处理、告警
Notification	Claude Code 发送通知时	TTS 警报、自定义通知处理
Stop	Claude Code 完成响应时	强制继续、额外处理
SubagentStart	Subagent 启动时	记录、上下文注入
SubagentStop	Subagent 完成时	TTS 播放、结果处理
PreCompact	压缩操作前	会话备份、状态保存
SessionStart	新会话开始/恢复时	加载开发上下文、环境初始化
SessionEnd	会话结束时	清理任务、状态保存
PermissionRequest	权限对话框显示时	权限审计、自动决策
Setup	进入仓库或定期维护时	环境检查、依赖更新

核心特性#

安全与控制#

命令阻止：PreToolUse 可拦截 rm -rf、sudo rm、chmod 777 等危险模式
文件访问控制：敏感文件路径保护
Prompt 验证：UserPromptSubmit 支持安全验证模式
权限审计：PermissionRequest hook 记录所有权限请求

TTS 语音反馈系统#

语音优先级：ElevenLabs > OpenAI > pyttsx3

Sub-Agent 与团队验证#

Meta-Agent：专门用于生成新 sub-agents 的 agent
Builder：拥有所有工具，执行实现任务，自验证 Ruff + Ty
Validator：只读权限，验证 builder 工作是否满足验收标准

Output Styles（9 种）#

Style	描述	最佳用途
genui	生成带嵌入式样式的美观 HTML	交互式视觉输出
table-based	Markdown 表格组织信息	比较、结构化数据
yaml-structured	YAML 配置格式	设置、层级数据
bullet-points	清晰的嵌套列表	任务跟踪、文档
ultra-concise	最少词汇、最快速度	快速原型设计
html-structured	语义 HTML5	Web 文档
markdown-focused	优化 markdown 特性	复杂文档
tts-summary	通过 ElevenLabs TTS 宣布完成	音频反馈

Status Lines (v1-v9)#

实时终端状态显示：Git 分支、目录、模型信息、最新 prompt、成本追踪、上下文窗口使用、会话持续时间、Token/cache 统计等。

架构设计#

采用 UV 单文件脚本架构：

隔离：Hook 逻辑与项目依赖分离
可移植性：每个 hook 脚本内联声明自己的依赖
零虚拟环境管理：UV 自动处理依赖解析
快速执行：UV 依赖解析极快

关键文件结构#

.claude/
├── settings.json          # Hook 配置与权限
├── hooks/                 # Python hook 脚本
│   ├── user_prompt_submit.py
│   ├── pre_tool_use.py
│   ├── post_tool_use.py
│   ├── validators/        # 代码质量验证 hooks
│   └── utils/             # TTS 和 LLM 工具脚本
├── status_lines/          # 实时终端状态显示 (v1-v9)
├── output-styles/         # 响应格式化配置
├── commands/              # 自定义斜杠命令
└── agents/                # Sub-agent 配置
    ├── team/
    │   ├── builder.md
    │   └── validator.md
    └── meta-agent.md
logs/                      # JSON 日志
ai_docs/                   # 文档资源

配置与使用#

Hook 配置示例#

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

Hook 选项#

--log-only: 仅记录 prompt（默认）
--validate: 启用安全验证
--context: 向 prompt 添加项目上下文

Exit Code 行为#

Exit Code	行为	描述
0	Success	Hook 成功执行
2	Blocking Error	stderr 自动反馈给 Claude
Other	Non-blocking Error	stderr 显示给用户

环境要求#

必需:

Astral UV - 快速 Python 包安装和解析器
Claude Code - Anthropic 的 Claude AI CLI

可选:

ElevenLabs - 文本转语音提供商
OpenAI - 语言模型 + TTS 提供商
Anthropic - 语言模型提供商
Ollama - 本地语言模型提供商

Claude Code Hooks Mastery