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

Master Claude Code Hooks Mastery

目录

• 前置条件
• 挂钩生命周期与有效负载
• 示例展示
• UV单文件脚本架构
• 关键文件
• 演示功能
• 挂钩错误代码与流程控制
• UserPromptSubmit挂钩深入解析
• Claude Code子代理
• 团队基础验证系统
• 输出样式集合
• 自定义状态行

前置条件

要使用Claude Code Hooks，您需要：

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

可选设置：

可选的工具包括：

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

挂钩生命周期与有效负载

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

挂钩生命周期概覽

挂钩事件

1. 用户提示提交挂钩：

   • 触发时机：用户提交提示时
   • 有效负载：包含提示文本、会话ID、时间戳
   • 增强功能：提示验证、日志记录、上下文注入、安全过滤

2. 预工具使用挂钩：

   • 触发时机：任何工具执行前
   • 有效负载：工具名称、工具输入参数
   • 增强功能：阻止危险命令

3. 后工具使用挂钩：

   • 触发时机：工具执行成功后
   • 有效负载：工具名称、工具输入、工具响应

4. 通知挂钩：

   • 触发时机：Claude Code发送通知时
   • 有效负载：消息内容

5. 停止挂钩：

   • 触发时机：Claude Code完成响应时
   • 有效负载：停止挂钩活动标志

6. 子代理停止挂钩：

   • 触发时机：Claude Code子代理（任务工具）完成响应时
   • 有效负载：停止挂钩活动标志

7. 压缩前挂钩：

   • 触发时机：在进行压缩操作前
   • 有效负载：触发器类型、会话信息

8. 会话开始挂钩：

   • 触发时机：当Claude Code开始新会话或恢复时
   • 有效负载：会话信息

9. 会话结束挂钩：

   • 触发时机：当会话结束时
   • 有效负载：会话ID、转录路径、工作目录

10. 权限请求挂钩：

    • 触发时机：当用户显示权限对话框
    • 有效负载：工具名称、工具输入、会话信息

11. 后工具使用失败挂钩：

    • 触发时机：工具执行失败时
    • 有效负载：工具名称、输入、错误对象

12. 子代理开始挂钩：

    • 触发时机：当子代理产生时
    • 有效负载：代理ID，代理类型，会话信息

13. 设置挂钩：

    • 触发时机：当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提供反馈。

退出代码行为

挂钩特定流程控制

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

用户提示提交挂钩

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

预工具使用挂钩

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

后工具使用挂钩

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

UserPromptSubmit挂钩深入解析

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

它能做些什么

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

工作原理

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

示例用例

1. 审计日志

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

2. 安全验证

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

Claude Code子代理

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

团队基础验证系统

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

/plan_w_team元提示

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

1. 自我验证
2. 代理协调
3. 模板化

示例工作流

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

输出样式集合

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

自定义状态行

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

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