在 Claude Code 插件中创建事件驱动 Hook…

当需要为 Claude Code 插件添加 PreToolUse/PostToolUse/Stop 等事件钩子，以校验工具调用、拦截危险命令、注入上下文或自动化工作流时使用。

适用场景

解决思路

1. 根据需求选择 Hook 类型：需要上下文感知的灵活判断用 prompt 型（type: prompt，支持 Stop、SubagentStop、UserPromptSubmit、PreToolUse 事件，默认超时 30s）；需要快速确定性校验、文件系统操作或外部工具集成用 command 型（type: command，默认超时 60s）。
2. 按配置位置选择格式：插件 hooks 写在 hooks/hooks.json 中，使用包装格式 {"description": "...", "hooks": {"PreToolUse": [...]}}，其中 description 可选、hooks 为必需包装；用户设置写在 .claude/settings.json 中，使用直接格式，事件直接位于顶层且无 description 字段。
3. 为每个 Hook 事件配置 matcher 与 hooks 数组：matcher 支持精确匹配（"Write"）、多工具（"Read|Write|Edit"）、通配（"*"）和正则（如 "mcp__.*__delete.*"），注意 matcher 区分大小写。
4. PreToolUse 用于工具执行前审批/拒绝/修改调用，输出 hookSpecificOutput.permissionDecision（allow|deny|ask）与 updatedInput，并可附 systemMessage。
5. PostToolUse 用于工具完成后反馈或记录：退出码 0 时 stdout 显示在 transcript，退出码 2 时 stderr 回传给 Claude，systemMessage 会加入上下文。
6. Stop 用于主 agent 准备停止时校验任务完整性，输出 decision（approve|block）、reason 与 systemMessage；SubagentStop 同理但作用于子 agent。
7. UserPromptSubmit 用于用户提交提示时添加上下文、校验或拦截提示。
8. SessionStart 用于会话开始时加载上下文，可通过 $CLAUDE_ENV_FILE 持久化环境变量（如 echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"）；SessionEnd 用于清理、日志与状态保存；PreCompact 用于在上下文压缩前保留关键信息；Notification 用于响应用户通知。
9. 在 command hook 脚本中通过 stdin 读取 JSON 输入，公共字段包括 session_id、transcript_path、cwd、permission_mode、hook_event_name；事件专属字段：PreToolUse/PostToolUse 有 tool_name、tool_input、tool_result，UserPromptSubmit 有 user_prompt，Stop/SubagentStop 有 reason。在 prompt 中用 $TOOL_INPUT、$TOOL_RESULT、$USER_PROMPT 等访问字段。
10. 使用标准输出格式 {"continue": true, "suppressOutput": false, "systemMessage": "..."} 控制流程：continue 为 false 时中止处理，suppressOutput 隐藏 transcript 输出。
11. 在 command hook 中始终使用 ${CLAUDE_PLUGIN_ROOT} 引用插件内脚本以保证可移植性，如 bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh；其他可用环境变量包括 $CLAUDE_PROJECT_DIR、$CLAUDE_ENV_FILE（仅 SessionStart）、$CLAUDE_CODE_REMOTE。
12. 在 command hook 脚本中做输入校验：用 set -euo pipefail，用 jq 解析 tool_name 并校验格式（如 ^[a-zA-Z0-9_]+$），不合法则输出 {"decision": "deny", "reason": "..."} 到 stderr 并 exit 2。
13. 做路径安全检查：拒绝包含 .. 的路径穿越，拒绝 .env 等敏感文件，命中时输出 deny 并 exit 2。
14. 所有 bash 变量加引号（如 echo "$file_path"、cd "$CLAUDE_PROJECT_DIR"）以防注入。
15. 为每个 hook 设置合适的 timeout（command 默认 60s，prompt 默认 30s），避免长时间运行的 hook。
16. 注意所有匹配的 hook 并行执行：彼此看不到对方输出、顺序不确定，因此要设计为相互独立；快速确定性检查用 command hook，复杂推理用 prompt hook，可在临时文件缓存校验结果并减少热路径 I/O。
17. 实现条件激活的临时 hook：在脚本中检查标志文件（如 $CLAUDE_PROJECT_DIR/.enable-strict-validation）或配置文件（如 .claude/plugin-config.json 中的 strictMode），未启用则 exit 0 跳过；并在插件 README 中记录激活机制。
18. 注意 hook 在会话启动时加载，修改 hooks/hooks.json 或脚本后必须退出并重启 Claude Code（claude 或 cc）才能生效，无法热替换；启动时会校验 hook，JSON 无效会导致加载失败。
19. 调试时用 claude --debug 查看 hook 注册、执行日志、输入输出 JSON 与耗时；用 /hooks 命令查看当前会话已加载的 hook；用 echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh 直接测试脚本，并用 jq 校验输出 JSON 合法性。
20. 按实现工作流落地：确定要挂钩的事件 → 选择 prompt 或 command 类型 → 在 hooks/hooks.json 写配置 → 为 command hook 编写脚本 → 全部文件引用使用 ${CLAUDE_PLUGIN_ROOT} → 用 scripts/validate-hook-schema.sh hooks/hooks.json 校验配置 → 用 scripts/test-hook.sh 部署前测试 → 在 Claude Code 中用 claude --debug 测试 → 在插件 README 中记录 hook。
21. 遵循最佳实践：优先用 prompt hook 处理复杂逻辑，用 ${CLAUDE_PLUGIN_ROOT} 保证可移植，校验所有输入，引用所有 bash 变量，设置合适超时，返回结构化 JSON，充分测试；避免硬编码路径、不校验就信任用户输入、创建长时间运行的 hook、依赖 hook 执行顺序、不可预测地修改全局状态、记录敏感信息。

适用边界 · 注意事项

• 不适用于非 Claude Code 环境或未使用 Claude Code 插件/设置体系的项目。
• 不适用于需要热更新 hook 配置的场景——hook 仅在会话启动时加载，修改后必须重启 Claude Code。
• 不适用于需要 hook 之间按确定顺序传递输出的场景——所有匹配 hook 并行执行且顺序不确定。