掌握 Claude Code Hooks：让 AI 变得更聪明！

Master Claude Code Hooks Mastery

前置条件

要使用Claude Code Hooks，您需要：

Astral UV - 快速的Python包安装和解析工具
Claude Code - Anthropic的Claude AI命令行工具

可选设置：

可选的工具包括：

ElevenLabs - 语音合成提供商
OpenAI - 语言模型提供商
Ollama - 本地语言模型提供商

挂钩生命周期与有效负载

本演示捕获了所有13个Claude Code挂钩生命周期事件及其JSON有效负载：

挂钩生命周期概覽

🗜️ 维护
🔄 主对话循环
🟢 会话生命周期
🤖 子代理生命周期
🛠️ 工具执行
🔧 初始化/维护
▶️ 会话开始
⏹️ 会话结束
📝 用户提示提交
Claude 处理
🔒 使用前钩子
❓ 权限请求
工具执行
✅ 使用后钩子
❌ 使用后钩子失败
🚀 子代理开始
子代理工作
🏁 子代理结束
🔔 通知 (异步)
🛑 停止
📦 使用前压缩

挂钩事件

用户提示提交挂钩：
- 触发时机：用户提交提示时
- 有效负载 ：包含提示文本、会话ID、时间戳
- 增强功能：提示验证、日志记录、上下文注入、安全过滤
预工具使用挂钩：
- 触发时机：任何工具执行前
- 有效负载：工具名称、工具输入参数
- 增强功能：阻止危险命令
后工具使用挂钩：
- 触发时机：工具执行成功后
- 有效负载：工具名称、工具输入、工具响应
通知挂钩：
- 触发时机：Claude Code发送通知时
- 有效负载：消息内容
停止挂钩：
- 触发时机：Claude Code完成响应时
- 有效负载：停止挂钩活动标志
子代理停止挂钩：
- 触发时机：Claude Code子代理（任务工具）完成响应时
- 有效负载：停止挂钩活动标志
压缩前挂钩：
- 触发时机：在进行压缩操作前
- 有效负载：触发器类型、会话信息
会话开始挂钩：
- 触发时机：当Claude Code开始新会话或恢复时
- 有效负载：会话信息
会话结束挂钩：
- 触发时机：当会话结束时
- 有效负载：会话ID、转录路径、工作目录
权限请求挂钩：
- 触发时机：当用户显示权限对话框
- 有效负载：工具名称、工具输入、会话信息
后工具使用失败挂钩：
- 触发时机：工具执行失败时
- 有效负载：工具名称、输入、错误对象
子代理开始挂钩：
- 触发时机：当子代理产生时
- 有效负载：代理ID，代理类型，会话信息
设置挂钩：
- 触发时机：当Claude进入一个库中或周期性地
- 有效负载：触发器类型、会话信息

示例展示

完整挂钩生命周期覆盖 - 实现所有13个挂钩事件及日志记录（11/13通过自动化测试验证）
提示级控制 - 用户提示提交挂钩在Claude看到之前验证和增强提示
智能TTS系统 - AI生成音频反馈
安全增强 - 多层次阻止危险命令和敏感文件访问
个性化体验 - 结合开发者姓名
自动日志记录 - 所有挂钩事件以JSON格式记录
聊天转录提取 - 后工具使用挂钩将JSONL转录转换为可读JSON格式

UV单文件脚本架构

该项目利用**UV单文件脚本**，保持挂钩逻辑与主要代码库清晰分离。所有挂钩作为独立Python脚本存放在.claude/hooks/中，并嵌入依赖声明。

好处：

隔离性 - 挂钩逻辑与项目依赖独立
便携性 - 每个挂钩脚本在线声明其依赖
无虚拟环境管理 - UV自动处理依赖
快速执行 - UV的依赖解析速度极快
自包含 - 每个挂钩都可以独立理解和修改

关键文件

.claude/settings.json - 挂钩配置与权限
.claude/hooks/ - 使用uv的Python脚本，按挂钩类型
- user_prompt_submit.py - 提示验证、日志和上下文注入
- pre_tool_use.py - 安全阻止与日志记录
- post_tool_use.py - 日志及转录转换
- post_tool_use_failure.py - 结构化错误日志
- notification.py - 字段响应与日志
- stop.py - AI生成的完成信息
.claude/agents/ - 子代理配置
- /crypto/ - 加密货币分析代理
- greeting_agent.md - 简单问候示例

演示功能

提示验证与安全过滤
上下文注入以增强AI响应
命令日志记录与审计
自动转录转换
基于权限的工具访问控制
挂钩执行中的错误处理

挂钩错误代码与流程控制

Claude Code挂钩提供强大的机制来控制执行流程并通过退出代码和结构化JSON提供反馈。

退出代码行为

退出代码	行为	描述
0	成功	挂钩成功执行
2	阻止错误	关键: stderr会自动反馈给Claude
其他	非阻止错误	stderr显示给用户，执行继续

挂钩特定流程控制

每个挂钩类型具有不同的控制能力，具体如下：

用户提示提交挂钩

主要控制点：在Claude处理提示前拦截用户提示
退出代码2：完全阻止提示，向用户显示错误信息
示例：日志记录所有提示并可以验证

预工具使用挂钩

主要控制点：在工具调用前拦截
退出代码2：完全阻止工具调用，向Claude显示错误

后工具使用挂钩

不能阻止（工具已执行）
示例：验证结果，提供反馈

UserPromptSubmit挂钩深入解析

UserPromptSubmit挂钩是在Claude Code交互中的第一道防线和增强层。它在用户提交提示时立即触发。

它能做些什么

日志记录提示 - 记录每个提示及时间戳与会话ID
阻止提示 - 退出代码2令Claude无法看到该提示
添加上下文 - 在用户提示前添加文本
验证内容 - 检查危险模式、机密、政策违规

工作原理

用户输入提示 → Claude Code捕获
UserPromptSubmit挂钩触发 → 收到包含用户提示的JSON
挂钩处理 → 记录、验证、阻止或添加上下文
Claude接收 → 被阻止的消息或原始提示+上下文

示例用例

审计日志

json 复制代码

{
  "timestamp": "2024-01-20T15:30:45.123Z",
  "session_id": "550e8400-e29b-41d4-a716",
  "prompt": "删除项目中的所有测试文件"
}

安全验证

bash 复制代码

用户: "rm -rf / --no-preserve-root"
挂钩: 阻止: 检测到危险的系统删除命令

Claude Code子代理

Claude Code支持专用的子代理，处理特定任务的自定义系统提示、工具和单独的上下文窗口。子代理是您可以将任务委托给的AI助手。

团队基础验证系统

该存储库包含一种强大的构建/验证工作模式，利用Claude Code任务系统来协作专门的代理团队。

`/plan_w_team`元提示

/plan_w_team命令不仅仅是一个普通提示，它具备三个强大的组件：

自我验证
代理协调
模板化

示例工作流

使用命令创建团队计划，并自动验证其输出。程序将协调执行不同角色的任务，以确保工作正确完成。

输出样式集合

该项目包括一组全面的自定义输出样式，用于改变Claude Code的响应方式。用户可以通过运行 /output-style [name] 来激活任何样式。

自定义状态行

自定义状态行在Claude Code会话过程中动态展示实时情境信息，帮助用户掌握当前进度和任务状态。

以上是关于Master Claude Code Hooks的全面介绍，利用这些功能，用户可以极大地提升操作的灵活性、安全性和便利性，以更好地与Claude Code进行交互和管理。