hook-development

Claude Code 插件的 Hook 开发

概述

Hook 是响应 Claude Code 事件执行的事件驱动自动化脚本。使用 Hook 来验证操作、执行策略、添加上下文以及将外部工具集成到工作流程中。

核心能力：

• 在执行前验证工具调用（PreToolUse）
• 响应工具结果（PostToolUse）
• 强制执行完成标准（Stop、SubagentStop）
• 加载项目上下文（SessionStart）
• 在开发生命周期中自动化工作流程

Hook 类型

基于提示的 Hook（推荐）

使用 LLM 驱动的决策进行上下文感知验证：

{ "type": "prompt", "prompt": "评估此工具使用是否合适: $TOOL_INPUT", "timeout": 30 }

支持的事件： Stop、SubagentStop、UserPromptSubmit、PreToolUse

优点：

• 基于自然语言推理的上下文感知决策
• 无需 bash 脚本的灵活评估逻辑
• 更好的边缘情况处理
• 更易于维护和扩展

命令 Hook

执行 bash 命令进行确定性检查：

{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh", "timeout": 60 }

适用于：

• 快速确定性验证
• 文件系统操作
• 外部工具集成
• 性能关键检查

Hook 配置格式

插件 hooks.json 格式

对于 hooks/hooks.json 中的插件 hook，使用包装格式：

{
  "description": "Hook 的简要说明（可选）",
  "hooks": {
    "PreToolUse": [...],
    "Stop": [...],
    "SessionStart": [...]
  }
}

设置格式（直接）

对于 .claude/settings.json 中的用户设置，使用直接格式：

{
  "PreToolUse": [...],
  "Stop": [...],
  "SessionStart": [...]
}

Hook 事件

PreToolUse

在任何工具运行之前执行。用于批准、拒绝或修改工具调用。

PostToolUse

在工具完成后执行。用于响应结果、提供反馈或记录日志。

输出行为：

• 退出码 0：stdout 显示在记录中
• 退出码 2：stderr 反馈给 Claude
• systemMessage 包含在上下文中

Stop

当主代理考虑停止时执行。用于验证完成度。

SubagentStop

当子代理考虑停止时执行。用于确保子代理完成其任务。

UserPromptSubmit

当用户提交提示时执行。用于添加上下文、验证或阻止提示。

SessionStart

当 Claude Code 会话开始时执行。用于加载上下文和设置环境。

SessionEnd

当会话结束时执行。用于清理、日志记录和状态保存。

PreCompact

在上下文压缩之前执行。用于添加要保留的关键信息。

Notification

当 Claude 发送通知时执行。用于响应用户通知。

环境变量

所有命令 hook 中可用：

• $CLAUDE_PROJECT_DIR - 项目根路径
• $CLAUDE_PLUGIN_ROOT - 插件目录（用于可移植路径）
• $CLAUDE_ENV_FILE - 仅限 SessionStart：在此处持久化环境变量
• $CLAUDE_CODE_REMOTE - 如果在远程上下文中运行则设置

始终在 hook 命令中使用 ${CLAUDE_PLUGIN_ROOT} 以确保可移植性。

安全最佳实践

输入验证

始终在命令 hook 中验证输入。

路径安全

检查路径遍历和敏感文件。

引用所有变量

# 正确：带引号
echo "$file_path"
cd "$CLAUDE_PROJECT_DIR"

# 错误：不带引号（注入风险）
echo $file_path
cd $CLAUDE_PROJECT_DIR

性能考虑

并行执行

所有匹配的 hook 并行运行。

设计影响：

• Hook 看不到彼此的输出
• 非确定性排序
• 设计时考虑独立性

优化

1. 使用命令 hook 进行快速确定性检查
2. 使用提示 hook 进行复杂推理
3. 在临时文件中缓存验证结果
4. 最小化热路径中的 I/O

调试 Hook

启用调试模式

claude --debug

查找 hook 注册、执行日志、输入/输出 JSON 和计时信息。

快速参考

应该做：

• ✅ 对复杂逻辑使用基于提示的 hook
• ✅ 使用 ${CLAUDE_PLUGIN_ROOT} 确保可移植性
• ✅ 在命令 hook 中验证所有输入
• ✅ 引用所有 bash 变量
• ✅ 设置适当的超时
• ✅ 返回结构化 JSON 输出
• ✅ 彻底测试 hook

不应该做：

• ❌ 使用硬编码路径
• ❌ 不验证就信任用户输入
• ❌ 创建长时间运行的 hook
• ❌ 依赖 hook 执行顺序
• ❌ 不可预测地修改全局状态
• ❌ 记录敏感信息

实现工作流程

1. 确定要挂钩的事件（PreToolUse、Stop、SessionStart 等）
2. 决定使用基于提示（灵活）还是命令（确定性）的 hook
3. 在 hooks/hooks.json 中编写 hook 配置
4. 对于命令 hook，创建 hook 脚本
5. 对所有文件引用使用 ${CLAUDE_PLUGIN_ROOT}
6. 使用 scripts/validate-hook-schema.sh hooks/hooks.json 验证配置
7. 在部署前使用 scripts/test-hook.sh 测试 hook
8. 使用 claude --debug 在 Claude Code 中测试
9. 在插件 README 中记录 hook