加载中
加载中

Hooks

在CLAUDE.md文件中告诉Claude做某件事,问题在于:这是一个请求,而不是保证。您可以写"编辑后始终格式化", Claude通常会听从。通常。但在一次您没有盯着看的长时间运行中,"通常"是不够的。Hook解决了这个问题。 Hook是在循环中固定点运行的确定性代码,因此它可以保证行为,而不是寄希望于它发生。它把一条规则从 "Claude通常会听从"变成了"Claude无法跳过它"。

这就是全部要点。现在让我们看看它实际上是如何运作的。

Hook事件

Claude Code在一次会话过程中会触发大约30个hook事件。您不需要了解所有事件,hooks参考文档列出了所有事件。有一小部分您会反复用到,它们与智能体循环中您希望介入的时间点相对应。

它们在循环中的位置是这样的:会话开始,提示进来,工具被调用,回合最终结束。每一个这样的时刻都有一个您可以挂载代码的hook。

值得了解的几个是:

  • PreToolUse 在工具调用之前触发。这是您的强制执行原语。它是那个可以在事情发生之前阻止它的hook。
  • PostToolUse 在工具调用成功后触发。这通常是自动格式化或自动lint所在的位置。
  • Stop 在Claude想要结束其回合时触发。如果某个条件未满足,您可以拒绝并说"不,你还没完成"。 当子智能体完成时,有一个对应的 SubagentStop。
  • PreCompact 和 PostCompact 分别在压缩前后触发。
  • InstructionsLoaded 在加载CLAUDE.md或规则文件时触发。对于审计实际进入上下文的内容很方便。
  • SessionStart 在开始时触发,并为环境做准备。如果您只想在全新启动时触发,可以使用 startup 来源。

有一点容易让人犯糊涂:要在压缩后重新注入上下文,不要使用PostCompact。要使用带有 compact 匹配器的 SessionStart。那才是真正能把输出带回对话中的那个。

PreToolUse:以JSON形式返回决策

PreToolUse是真正的力量所在,因为它可以在工具调用运行之前阻止它。您回应Claude的方式是打印JSON并以零退出。 关键字段是 permissionDecision,它取三个值之一:

  • allow —— 放行调用
  • deny —— 阻止调用
  • ask —— 交还给用户决定

技术上还有第四个值 defer,但它只适用于非交互式 -p 运行,在这种情况下调用进程会暂停工具并在稍后恢复它。 您几乎不会用到它。

其形态如下所示:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Don't push to main. Open a pull request instead."
  }
}

您也可以不阻止调用,而是改写它。返回带有 updatedInput 的 allow 或 ask。使用 ask 时,您会看到改写后 的调用并批准它。使用 allow 时,它会在不提示的情况下运行:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "updatedInput": {
      "command": "..."
    }
  }
}

这就是您从bash命令中脱敏并仍然让它运行的方式。有一点要注意:updatedInput 替换的是整个输入对象, 因此您必须把不打算更改的字段原样带回去,否则就会丢失它们。

退出码,适用于不返回JSON的hook

并不是每个hook都需要使用JSON交流。对于更简单的hook,退出码就能完成任务。有三个重要的数字。

  • 0表示成功。 如果标准输出是JSON,Claude会解析它。纯文本在大多数事件中会被忽略,但在SessionStart、 UserPromptSubmit和UserPromptExpansion这几个事件上,纯文本会被添加到上下文中。这正是状态保存hook 能发挥作用的原因。
  • 2表示阻塞性错误。 标准错误会作为上下文反馈给Claude。这几乎在所有地方都是阻塞退出码。
  • 其他任何值都是非阻塞的。标准错误会被记录下来,Claude会继续执行。

容易让人犯错的是退出码1。它看起来像是一个错误,但它并不阻塞。Claude会照样运行该命令。所以如果您想要 阻止某件事,请用退出码2,而不是1。

还有几个细节。退出码2甚至可以阻塞Stop,这就是您告诉Claude它还没完成的方式。但PostToolUse是在工具已经 运行之后触发的,所以在那里阻塞为时已晚,无法阻止调用,不过它仍然可以把文本反馈给Claude。还有少数事件 完全忽略阻塞,比如Notification和SessionStart。SessionStart只把您的标准错误显示给您自己,Notification会 忽略它,两者都会照常继续。

一个真正的护栏:脱敏而不是阻止

让我们用一个实际的例子把这些串起来。假设您想在Bash工具上设置一个PreToolUse护栏。您在设置文件中注册一个 hook。把这个放进 .claude/settings.json 并提交,您的团队就可以共享它:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

matcher 用来选取要监视的工具,hook上一个可选的 if 字段可以将其范围缩小到特定命令,比如 "if": "Bash(curl *)"。运行 /hooks 来检查该hook是否已注册。

明显的做法是返回 deny 并阻止一次危险调用。这很好。但不太为人所知、也更有意思的做法是返回 updatedInput 来改写调用。这就是您从命令中剥离密钥、同时仍然让它运行的方式,而不是简单地拒绝。

下面是实际运作的样子。Claude被要求运行一个包含看起来是真实密钥的命令。hook拦截了它,发现了 sk_live_ 模式,并在命令执行之前将其替换为一个占位符。

这是脚本,.claude/hooks/redact-secrets.sh。它需要 jq,并且您需要用 chmod +x 让它可执行:

bash
#!/bin/bash
# 在命令运行前替换看起来像真实密钥的内容。
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "ask",
    permissionDecisionReason: "Replaced a live key with a placeholder",
    updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
  }
} else empty end'

它返回 ask,所以您需要批准改写后的命令。返回 allow 会跳过该模式所匹配的每个命令的这个提示。 一旦您批准了它,该命令就会在不含密钥的情况下运行。这就是阻止和脱敏之间的区别,也是hook每次都能 强制执行的一种事情。

在压缩过程中保留状态

还有一个值得设置的模式。当Claude压缩一段长对话时,它会丢弃大量细节。带有 compact 匹配器的 SessionStart hook会在压缩之后立即运行。让它打印一份您一直在处理的文件的简短摘要。该摘要会回到 上下文中,这样Claude就能从中断的地方继续,而不是从零开始。下面这个会列出您尚未提交的更改:

json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "git status --short" }]
      }
    ]
  }
}

总结

Hook把Claude通常会遵循的一条规则,变成了它始终会遵循的规则。不要只满足于自动格式化:用PreToolUse 守护工具,用Stop把关回合,并在压缩过程中保留状态。前期设置需要花费一点功夫,但当它在您甚至都没有 盯着看的一次运行中捕获到问题的那一刻,这番功夫就值回来了。