meta-hook-creator

钩子创建器

概述

Claude Code 钩子是用户定义的 shell 命令、LLM 提示词或 Agent 评估，会在特定生命周期节点自动执行。钩子通过 stdin 接收 JSON 上下文、执行操作，并通过退出代码、stdout 和 stderr 传达结果。

适用场景： 阻止危险命令、在写入后自动格式化、保护敏感文件、自定义通知、设置环境、强制执行项目规范、自动批准安全工具、在更改后运行测试。

不适用场景： 注入静态上下文（使用 CLAUDE.md）、设置简单的权限规则（使用允许列表设置）、执行一次性设置（直接使用 shell 脚本）。

快速参考

模式	事件	匹配器	要点
阻止工具调用	PreToolUse	工具名称	退出码为 2，或使用 JSON permissionDecision: "deny"
自动批准工具	PreToolUse	工具名称	JSON permissionDecision: "allow"
修改工具输入	PreToolUse	工具名称	JSON updatedInput，包含修改后的参数
写入后格式化	PostToolUse	Write|Edit	运行格式化工具，退出码为 0
记录工具失败	PostToolUseFailure	工具名称	工具抛出错误或返回失败时触发
处理权限	PermissionRequest	工具名称	JSON decision.behavior: "allow" 或 "deny"
验证用户提示词	UserPromptSubmit	无匹配器	退出码为 2 会阻止提示词，stdout 会添加上下文
桌面通知	Notification	通知类型	permission_prompt、idle_prompt 等
强制继续	Stop	无匹配器	使用 JSON decision: "block" 并附上原因
子 Agent 生命周期	SubagentStop	Agent 类型	与 Stop 相同的决策控制
环境设置	SessionStart	来源类型	写入 CLAUDE_ENV_FILE 以保留环境变量
会话清理	SessionEnd	退出原因	无法阻止终止
压缩前上下文	PreCompact	manual|auto	在上下文压缩前触发
后台任务	任意后置事件	任意	在命令钩子中设置 async: true
LLM 评估	支持的事件	任意	使用 type: "prompt" 进行单轮 LLM 检查
多轮验证	支持的事件	任意	使用 type: "agent" 启用可访问工具的子 Agent

常见错误

错误	正确做法
期待用 Exit 1 阻止工具调用	在 PreToolUse 和 PermissionRequest 中使用 exit 2 来阻止
在 exit 2 时输出 JSON	只有在 exit 0 时才会处理 JSON 输出；exit 2 时使用 stderr
在 settings.json 中编写复杂的内联 bash	将其提取到脚本文件中，并通过 $CLAUDE_PROJECT_DIR 引用
慢速 hook 未设置超时	设置 timeout 字段；默认值为命令 600s、提示词 30s、Agent 60s
未给 $CLAUDE_PROJECT_DIR 加引号	始终加引号："$CLAUDE_PROJECT_DIR"/.claude/hooks/script.sh
期望在所有 hook 中都能使用 CLAUDE_ENV_FILE	仅在 SessionStart hook 中可用
在 Stop 或 UserPromptSubmit 中添加 matcher	这些事件会忽略 matcher；它们始终会触发
在 PreToolUse 的顶层使用 decision/reason	使用 hookSpecificOutput.permissionDecision 和 permissionDecisionReason
Stop hook 未检查 stop_hook_active	检查此字段以防止无限继续循环
混用退出代码和 JSON 决策	每个 hook 选择一种方式：仅使用退出代码，或使用 exit 0 并输出 JSON

委派

• Hook 模式发现：使用 Explore Agent 查找项目中现有的 hook
• Hook 测试与验证：使用 Task Agent 验证 hook 的行为
• 代码审查：委派给 code-reviewer Agent 审查 hook 脚本

参考资料

• 事件类型、匹配器和输入架构
• Hook 配置、退出代码、JSON 输出和环境变量
• 常见自动化模式的 Hook 模板