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 运行,在这种情况下调用进程会暂停工具并在稍后恢复它。
您几乎不会用到它。
其形态如下所示:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Don't push to main. Open a pull request instead."
}
}您也可以不阻止调用,而是改写它。返回带有 updatedInput 的 allow 或 ask。使用 ask 时,您会看到改写后
的调用并批准它。使用 allow 时,它会在不提示的情况下运行:
{
"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 并提交,您的团队就可以共享它:
{
"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 让它可执行:
#!/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就能从中断的地方继续,而不是从零开始。下面这个会列出您尚未提交的更改:
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [{ "type": "command", "command": "git status --short" }]
}
]
}
}总结
Hook把Claude通常会遵循的一条规则,变成了它始终会遵循的规则。不要只满足于自动格式化:用PreToolUse 守护工具,用Stop把关回合,并在压缩过程中保留状态。前期设置需要花费一点功夫,但当它在您甚至都没有 盯着看的一次运行中捕获到问题的那一刻,这番功夫就值回来了。