Claude Code Hooks：在工具调用前做确定性检查

什么时候用

• 你有必须按事件重复执行的确定性检查，而不是依赖模型判断的开放问题。[1]

什么时候不用

• 希望 PostToolUse 撤销已经发生的外部操作，或把示例字符串匹配当作完整 shell 解析。[1]

先选择动作前还是动作后

PreToolUse 在工具调用前触发，可用于阻止调用；PostToolUse 用于动作后的处理。matcher 选择事件中的工具名称，例如 Bash；它并不自动理解你的业务条件。命令型 Hook 从 stdin 读取 JSON，脚本须按当前事件的数据字段取值。[1]

注册一个演示检查

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "python3 .claude/hooks/demo-command-check.py"}]
    }]
  }
}

[1]

若配置已有 hooks，添加事件或处理器，不覆盖其他事件。该示例假定命令的工作目录是项目根目录，并且 Python 3 可用。保存脚本前核对路径；使用 /hooks 查看注册情况。[1]

读取输入并返回结果

import json
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "").strip()
if command == "npm publish":
    print("Demo publication requires separate review.", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

[1]

官方文档说明退出码 2 是阻止错误，效果依事件而定；这里使用 PreToolUse，因此拒绝这次调用。这个脚本只匹配确切字符串，带参数、包装 shell 或其他发布入口不在示例覆盖范围。它只演示返回协议，不承担完整权限策略。[1]

先单独检查脚本，再接入事件

• 给脚本输入模拟的 tool_input.command：npm publish 应退出 2，npm test 应退出 0。
• 确认 stdout 不混入 shell 启动输出；错误说明留在 stderr，区分脚本错误与业务拒绝。
• 接入后用 /hooks 和事件日志核对是否触发；没有触发先查事件名、matcher、工作目录和权限。

[1]

本页 JSON 可解析，Python 脚本已用两组模拟输入执行；没有启动 Claude Code 或触发真实 Hook，没有执行 npm publish。上线应用前仍需在自己的可丢弃项目验证事件链路。[1]