用途
Hook Development 用于为 Claude Code 插件编写事件驱动的自动化钩子。钩子是在 Claude Code 发生特定事件时自动执行的脚本,可用来在工具执行前验证操作、拦截危险调用、在工具完成后反馈问题、检查任务是否真正完成,以及加载项目上下文、集成外部工具。
主要能力
- PreToolUse:在任意工具运行前执行,可批准、拒绝或修改工具调用,输出 permissionDecision(allow/deny/ask)与 updatedInput。
- PostToolUse:在工具完成后执行,用于分析结果、提供反馈或记录日志。
- Stop / SubagentStop:在主代理或子代理准备停止时执行,校验任务完整性,返回 approve 或 block 及原因。
- UserPromptSubmit:用户提交提示词时执行,可补充上下文、校验或阻止提示词。
- SessionStart / SessionEnd:会话开始或结束时执行,用于加载上下文、设置环境、清理与状态保存;SessionStart 可通过 $CLAUDE_ENV_FILE 持久化环境变量。
- PreCompact / Notification:上下文压缩前保留关键信息、响应通知事件。
钩子类型
- Prompt 型(推荐):由 LLM 依据自然语言推理做上下文感知判断,适合复杂逻辑与边界情况;支持 Stop、SubagentStop、UserPromptSubmit、PreToolUse 事件。
- Command 型:执行 bash 命令做确定性检查,适合快速校验、文件系统操作、外部工具集成和性能敏感场景。
配置格式
- 插件内
hooks/hooks.json使用包装格式:外层有可选的 description 字段和必填的 hooks 字段,实际事件放在 hooks 内。 - 用户设置
.claude/settings.json使用直接格式:事件直接位于顶层,无包装、无 description 字段。
插件钩子会与用户钩子合并并并行运行。
输入输出与匹配
- 所有钩子通过 stdin 接收 JSON,含 session_id、transcript_path、cwd、permission_mode、hook_event_name 等公共字段,以及事件特有字段(如 tool_name、tool_input、tool_result、user_prompt、reason)。
- 通用输出字段包括 continue(false 时停止处理)、suppressOutput、systemMessage。
- 退出码:0 表示成功并显示输出,2 表示阻断性错误并将 stderr 反馈给 Claude,其它表示非阻断性错误。
- matcher 支持精确匹配、多个工具用竖线分隔、通配符
*和正则(如mcp__.*__delete.*),区分大小写。
使用方式
实现流程:确定要挂钩的事件 → 选择 prompt 型或 command 型 → 在 hooks/hooks.json 中编写配置 → 为 command 型编写脚本 → 所有文件引用使用 ${CLAUDE_PLUGIN_ROOT} 保证可移植 → 用 scripts/validate-hook-schema.sh 校验配置 → 用 scripts/test-hook.sh 测试 → 在 Claude Code 中用 claude --debug 调试 → 在插件 README 中说明钩子。
安全与性能注意事项
- 在 command 钩子中校验输入,防范路径遍历与敏感文件(如 .env)。
- 所有 bash 变量加引号以防注入。
- 合理设置超时(command 默认 60 秒,prompt 默认 30 秒)。
- 所有匹配钩子并行执行,彼此看不到对方输出且顺序不确定,应设计为相互独立。
限制
- 钩子在会话启动时加载,修改配置需重启 Claude Code 才能生效,无法热替换。
- hooks.json 中 JSON 无效会导致加载失败,脚本缺失会产生警告。
- 可用 /hooks 命令查看当前会话已加载的钩子。
适用场景
适合 Claude Code 插件开发者实现文件写入安全校验、Bash 命令校验、任务完成度检查、会话上下文加载、严格模式的条件启用等开发流程中的自动化管控。