Claude Code Hooks 配置与退出码 2 详解
了解 Claude Code Hook 的配置位置、触发事件和输入方式,重点掌握 PreToolUse 返回退出码 2 如何取消工具调用,以及 stderr 如何将原因传回模型,并评估强制执行带来的安全成本。
Claude Code hook 是什么
Claude Code hook 是 Claude Code 在自身生命周期的固定节点自动执行的 shell 命令。这就是 hook 与规则文件之间的根本区别。CLAUDE.md 中的指令属于建议,模型会将其与上下文中的其他信息权衡。hook 则是代码,无论模型是否同意都会执行。如果代理持续跳过你已经两次告知它的格式化工具,就不需要编写更强硬的指令。你需要的是 hook。
其机制很简单。你可以在设置文件中按事件名称注册命令。事件触发后,Claude Code 会执行该命令,并将事件数据以 JSON(JavaScript 对象表示法)格式写入命令的标准输入(stdin)。命令读取这些数据并执行相应操作,然后通过退出状态返回结果。PreToolUse hook 返回退出状态 2 时,会在工具调用执行前将其取消;脚本写入标准错误(stderr)的内容会作为原因传回模型,除非 hook 同时输出包含阻止决策的 JSON,此时该决策中的原因优先。
这里的事件名称和字段名称来自 Claude Code 的 hook 参考文档,该文档于 November 1, 2026 检查。此接口变化很快,因此在复制任何博客文章(包括本文)中的 JSON 之前,请先查看与你使用的版本对应的参考文档。使用 claude --version 输出你的版本。
Hook 配置所在位置
Hook 是设置文件中的 JSON 块。以下 6 个位置可以包含 Hook,文件的作用域就是 Hook 的作用域。
~/.claude/settings.json:适用于您计算机上的所有项目,不影响其他人的项目。.claude/settings.json:适用于单个项目,并提交到代码库,因此克隆该项目的所有人都会获得此 Hook。.claude/settings.local.json:适用于单个项目,仅在您的计算机上生效。- 托管策略设置:适用于整个组织,由管理员设置。
- 插件中的
hooks/hooks.json:在插件启用期间生效。 - Skill 或 subagent 的 frontmatter。调用 Skill 后,其中的 Hook 会在本次会话剩余时间内持续生效;subagent 的 Hook 会在该 subagent 运行期间生效。
这些文件中的 Hook 条目会合并,而不是相互覆盖。项目设置文件会将其中的 Hook 添加到用户设置中的 Hook,而不是替换它们。因此,同一事件可以包含来自多个文件的多个 Hook。设置 "disableAllHooks": true 可停用这些 Hook,但有一个例外:托管策略设置中的 Hook 会继续运行,除非同时在托管设置中应用该设置。
在会话中运行 /hooks,可按事件列出当前注册的所有 Hook,并显示每个 Hook 的源文件和匹配器。该菜单为只读菜单,因此需要编辑设置文件来修改 Hook。文件监视器通常会自动检测编辑内容,无需重启。
Claude Code 中有哪些 hook 事件
hooks 参考文档列出了 33 个事件,从 SessionStart 到 SessionEnd,涵盖上下文压缩、子代理、worktree 和配置文件。服务器管理通常只会用到其中几个。
PreToolUse:工具调用执行前触发。这是可以阻止调用的事件。PostToolUse:工具调用成功后触发。工具调用失败时则触发PostToolUseFailure,因此必须查看每种结果的 hook 需要同时使用这两个事件。PermissionRequest:工具调用需要权限决定时触发,也就是即将显示批准提示的时刻。UserPromptSubmit:提交提示词时触发,在 Claude 处理提示词之前执行。成功 hook 输出的纯文本 stdout 会添加到模型上下文中。SessionStart和SessionEnd:分别在会话开始和结束时触发。上下文压缩后也会触发SessionStart,此时 matcher 值为compact。Stop:Claude 完成响应时触发。每轮触发一次,而不是每个完成的任务触发一次。
对于支持 matcher 的事件,一个组可以包含 matcher,用于决定哪些事件触发 hook。在工具事件中,它按工具名称进行筛选,因此 "Edit|Write" 只会在编辑文件时触发,不会在其他情况下触发。Matcher 区分大小写。空 matcher 会在每次事件发生时触发。来自 MCP(model context protocol)服务器的工具名称为 mcp__<server>__<tool>,因此使用 "mcp__github__.*" 作为 matcher 可以匹配一个服务器的工具,而不会匹配其他服务器的工具。
Stop hook 有一个需要在编写前了解的陷阱。阻止操作的 Stop hook 会让模型返回并继续工作;默认情况下,Claude Code 会在连续 8 次继续后覆盖下一次阻止操作。每当 Claude 调用工具时,计数都会重置。请从 hook 输入中读取 stop_hook_active 字段,并在其值为 true 时退出并返回 0,否则 hook 可能会不断让 Claude 返回并继续工作。
钩子通过标准输入接收的内容
当 Claude 即将运行 npm test 时,Bash 上的 PreToolUse 钩子会通过标准输入读取以下内容:
{
"session_id": "abc123",
"cwd": "/home/deploy/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}常见输入字段包括 session_id、cwd、transcript_path 和 hook_event_name;并非每个事件都会发送 permission_mode。工具事件还会添加 tool_name、tool_input 和 tool_use_id。其他事件包含各自的字段:UserPromptSubmit 会获取 prompt 文本,而 SessionStart 会获取一个由 startup、resume、clear、compact 或 fork 组成的 source。
在 shell 脚本中,通常使用 jq 读取这些内容;精简的服务器镜像中没有该工具。请先在 Ubuntu 和 Debian 上使用 sudo apt install -y jq 安装它。
退出状态对当前工具调用的影响
共有三种结果。
- 退出码 0 表示成功,任何有效的 JSON 决策字段仍然生效,包括阻止或拒绝。在
PreToolUse中,退出码为 0 但未提供决策并不表示批准,正常的权限流程仍会执行。在UserPromptSubmit、UserPromptExpansion、SessionStart和PostModelSwitch中,纯文本 stdout 会添加到模型的上下文中。在大多数其他事件中,stdout 只会写入调试日志。 - 退出码 2 会在可阻止的事件上阻止操作,其中包括
PreToolUse;stderr 会成为阻止消息,除非 JSON 输出包含阻止决策,此时以该决策的原因优先。具体由谁读取该消息取决于事件。在PreToolUse和Stop中,模型会将其视为原因。在UserPromptSubmit和PreModelSwitch中,消息会显示给您,但不会添加到模型的上下文中。在无法阻止的PostToolUse和PostToolUseFailure中,阻止会被忽略,但 stderr 仍会作为反馈传给模型。在大多数其他无法阻止的事件中,stderr 只会显示给您,或被忽略。在Stop、SubagentStop、TaskCompleted以及插件的UserPromptSubmithook 中,如果 stdout 为空且 stderr 中包含文件缺失错误,退出码 2 会被视为非阻止错误。 - 任何其他退出码,如果 stdout 为纯文本或为空,通常都会被视为非阻止错误。会话记录会显示一条 hook 错误提示,内容为
Failed with non-blocking status code:后接 stderr 的第一行。在PreToolUse等事件中,有效的 JSON 仍可决定结果,除非 hook 失败会阻止操作。WorktreeCreate在任意非零退出码下都会失败;如果目录在此之后仍然存在,WorktreeRemove会在非零退出码下失败。
如果需要执行阻止或保持静默以外的操作,请使用退出码 0,并将 JSON 对象写入 stdout。PreToolUse hook 使用 permissionDecision 进行决策:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database drops go through a migration, not through the agent."
}
}在权限规则和工具批准要求允许的情况下,"allow" 会跳过交互式提示;"deny" 会取消调用,并将原因发送给模型;"ask" 会请求确认。每个 hook 选择一种方式。退出码 2 与 stdout 中的 JSON 决策同时使用时,仍会保持阻止状态,即使 JSON 表示 "allow"。
当多个 hook 匹配同一事件时,它们会并行运行;prompt hook 和 agent hook 同时运行的数量上限为 12。某个 hook 返回 deny 不会停止其他同级 hook,因此日志 hook 仍会写入记录,同时防护 hook 拒绝同一个调用。对于 PreToolUse,Claude Code 随后会合并各项结果,并按拒绝、延后、询问、允许的顺序保留限制最严格的结果。
示例 1:在破坏性命令执行前将其阻止
将以下内容保存为项目中的 .claude/hooks/block-destructive.sh:
#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
exit 2
fi
done
exit 0为其添加可执行权限,然后在 .claude/settings.json 的 PreToolUse 中注册它:
chmod +x .claude/hooks/block-destructive.sh{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
"timeout": 10,
"statusMessage": "Checking the command against policy"
}
]
}
]
}
}在信任脚本前,先手动测试它。因为当 onFailure 未设置时,因处理自身输入而崩溃的钩子通常会默认放行。 在没有 Git Bash 的 Windows 上,失败的 shell 形式 PreToolUse 或 PermissionRequest 命令钩子则可能直接阻止工具调用:
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
| .claude/hooks/block-destructive.sh
echo $?您应在 stderr 中看到 Blocked by policy: 行,退出码应为 2。传入 ls -la 之类的无害命令时,应看不到任何输出,退出码应为 0。在会话中,被拒绝的调用会出现在记录中,并将您的消息作为原因;模型会读取该消息并调整行为。
有一个特性使这项措施很有价值:PreToolUse 钩子会在权限模式检查之前触发,并且在所有权限模式下都如此,因此即使处于 bypassPermissions,拒绝规则仍然有效。这使钩子可以与 Claude Code 自动模式及其权限设置 配合使用:提示被减少,但钩子仍会触发。
需要明确其边界。针对命令字符串进行模式匹配,可以防止代理粗心操作,但无法防止代理采取规避方式,因为同一条命令可以用 grep 看不到的形式编写。硬性规则应配置在权限系统中,并通过运行该进程的账户权限 enforced.
每次编辑后格式化并执行代码检查
PostToolUse 与 Edit|Write 匹配器会在这两个文件编辑工具中的任意一个成功后运行。将以下内容保存为 .claude/hooks/after-edit.sh:
#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0
case "$FILE" in
*.py)
ruff format "$FILE" >/dev/null 2>&1
if ! ruff check "$FILE" >&2; then
exit 2
fi
;;
*.sh)
if ! shellcheck "$FILE" >&2; then
exit 2
fi
;;
esac
exit 0{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
"timeout": 60
}
]
}
]
}
}让 Claude 向 Python 文件中添加一个缩进错误的函数,然后打开该文件。文件会自动完成格式化。这可以证明钩子已运行,因为钩子成功时不会在对话中显示任何内容。
这里的 exit 2 不会撤销任何操作。PostToolUse 会在工具已经执行后触发,因此无论退出码是什么,编辑结果都会写入磁盘。exit 2 的作用是将 ruff check 的输出作为反馈传回模型,让模型修复刚刚引入的错误,而不是继续执行。这就是提交时才发现的代码检查失败与代理在同一轮中修复错误之间的区别。
这里有两个匹配器限制需要注意。Edit|Write 看不到 shell 命令修改的文件,而 Claude 经常通过 Bash 写入文件,因此这个遗漏确实会造成影响。要覆盖每次调用,请同时匹配 Bash,并让脚本使用 git status --porcelain 列出已修改的文件。要覆盖每轮对话一次,请改为将扫描放入 Stop 钩子中。
示例 3:记录每次工具调用以供审计
在 PostToolUse 上使用空匹配器,会对每次成功的工具调用触发。将记录写入系统日志,而不是写入主目录中的文件,并不能阻止代理自己的 shell 访问这些记录:访问权限取决于账户的权限。用户可以读取自己的私有用户日志;root 以及 systemd-journal、adm 或 wheel 的成员可以读取所有日志文件:
{
"hooks": {
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
}
]
}
]
}
}使用 journalctl -t claude-code -o cat | tail -n 5 读取记录。拥有记录读取权限时,您应看到每次成功工具调用对应一行 JSON,最新记录位于最后。如果没有任何输出,请同时检查日志访问权限和钩子是否运行;下面的故障排查部分介绍了钩子相关问题。
在 PostToolUseFailure 下添加相同的代码块,以记录失败的调用,因为 PostToolUse 只在成功时触发,而失败的命令通常更值得关注。使用 logger 而不是将内容追加到主目录中的文件,原因在于所有权:钩子以与代理 shell 相同的用户身份运行,因此该用户能够追加的内容,也能够截断。日志由 systemd-journald 写入;能否防止其被删除,仍取决于代理账户的权限。
钩子最长可运行多长时间
此图表背后的数据
[
{
"label": "command, http or mcp_tool hook",
"default_timeout_seconds": 600
},
{
"label": "agent hook",
"default_timeout_seconds": 60
},
{
"label": "prompt hook",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
"default_timeout_seconds": 30
},
{
"label": "command, http or mcp_tool on MessageDisplay",
"default_timeout_seconds": 10
},
{
"label": "any hook on SessionEnd",
"default_timeout_seconds": 1.5
}
]命令钩子默认可运行 600 秒,即 10 分钟。某些事件会大幅缩短这一时间。SessionEnd 钩子共用 1.5 秒的总预算,因此会话结束时的清理操作必须快速完成。不过,在设置文件中为某个钩子设置更长的 timeout,可将这个共享预算提高到相应值,最高为 60 秒。
达到超时时间的同步命令、HTTP 或 MCP 工具钩子会被取消,通常不会生成决策;对于 PreModelSwitch,超时会阻止切换。对于 PreToolUse 防护钩子,超时通常会让工具调用继续进入正常的权限流程;如果未设置 onFailure,则适用上文所述的 Windows 例外。基于这一点,防护脚本应保持简短。自版本 2.1.295 起,可通过 "onFailure": "block" 反转 command 或 http 钩子的默认行为,将超时、崩溃或意外退出代码转换为阻止操作。不过,这对 Stop、SubagentStop、TaskCompleted、TeammateIdle 或后台命令钩子不起作用。对于无人等待的慢速任务,例如将日志发送到其他位置,请设置 "async": true,这样钩子会在后台运行,不会阻塞工具调用。
Hooks、规则文件、skills 和 MCP 服务器
这四种机制都会改变 agent 的行为,因此经常被混淆。只有其中一种不会停留在建议层面。
规则文件(CLAUDE.md,或 .claude/rules/ 下的文件)是加载到模型上下文中的文本。它会影响行为,但不会强制执行任何内容。面对较长的对话、大型 diff 和新的用户请求时,其中的一行内容可能失效。这就是 agent 忽略你写下的指令 的常见原因。
skill 是一个包含指令和脚本的目录。模型认为相关时才会加载它。这个判断正是 skill 的作用所在,也是它的限制:仍然由模型决定是否使用它。Ponytail 会引导 agent 采用能够奏效的最小改动,就是一个例子。它能影响整个任务的处理方式,这是 hook 无法做到的,但只有模型选择加载它时才会生效。
MCP(model context protocol)服务器为模型提供可调用的新工具。它扩大了 agent 可以访问的范围,但不会让 agent 主动调用任何工具。MCP 服务器还是一个需要单独运行和维护的进程,这本身就是一项工作:参见 在 VPS 上运行 MCP 服务器。
在这四种机制中,只有 hook 不需要模型选择就会运行。对于偏好设置,使用规则文件;对于模型在适用时应遵循的流程,使用 skill。对于每次都必须执行的步骤,或绝对不能发生的事情,使用 hook。更深入的比较,包括 skill 何时优于规则文件,请参见 skills、MCP 和规则文件的比较。
plugin 是一种打包方式,不是第五种机制。它会将 hook 和 skill 打包成一个可安装单元。团队可以借此将相同的防护措施部署到每台机器上:参见 Claude Code plugin 的工作方式。
共享 VPS 上的安全决策
Hook 是由代理触发并运行的代码,运行身份是启动 Claude Code 的用户。它继承该用户的文件权限和环境,但会移除部分遥测和凭据变量。在笔记本电脑上,这属于工作流问题。在无人值守运行代理的 VPS 上,这属于安全问题,主要涉及以下四个方面。
仓库中的 hook 可能是你未编写的代码。 .claude/settings.json 已提交到仓库,因此克隆仓库并在其中启动会话,可能会注册仓库自带的 hook。在交互式会话中,Claude Code 会通过该目录的工作区信任对话框控制项目 hook,这意味着接受信任的时刻,就是你决定运行这些 hook 的时刻。先阅读 hooks 块。无人值守代理通常使用的 claude -p 或 SDK 会话不会显示该对话框,而是将目录视为可信目录,因此仓库中的 hook 会直接运行,不会请求确认。在编写脚本调用它之前,先检查其 .claude/ 文件,或者使用 --settings '{"disableAllHooks": true}' 运行。
Hook 可以看到完整的工具输入。 记录 tool_input 的审计 hook 会将每条命令的所有参数写入日志,包括碰巧出现在命令行中的任何令牌。该日志需要与机密信息相同级别的保护。这也是 让机密信息远离 AI 代理可访问范围这一更大问题的一部分。
Hook 可以向模型上下文写入内容。 成功的 SessionStart 或 UserPromptSubmit hook 输出的纯文本 stdout 会添加到对话中。将外部来源、问题跟踪器或日志文件中的文本传入模型的 hook,实际上是在把不受信任的文本交给模型,就像这些文字是你亲自输入的一样。将 同一 VPS 上另一个 Claude Code 会话的输出转发过来的 hook 也会产生相同效果。一个代理的输出并不比问题跟踪器的内容更值得信任。应将这类 stdout 视为输入,而不是输出。
权限才是真正的控制手段。 使用专用的非特权用户运行代理,只授予它所需的 sudo 规则。设置 PreToolUse deny 规则是有价值的,但它本来就只是尽力而为:参考文档对 if 过滤器也有相同说明,并建议在需要强制拒绝时使用权限系统。权限规则和进程运行所用的账户,才是在高压情况下仍然有效的控制措施。
在所有权限模式下,都有一个属性成立。PreToolUse hook 会在每种权限模式下的权限模式检查之前触发,因此返回 deny 的 hook 即使在 bypassPermissions 下也会阻止工具执行。Hook 可以收紧权限规则允许的操作,但不能放宽这些限制。例外是 mod。在没有托管设置的机器上,如果会话未通过 /login 登录 Team 或 Enterprise 计划,已安装且处理 tool.check 的 mod 可能会批准原本被 PreToolUse hook 阻止的调用。通过 API 密钥或长期有效的 CLAUDE_CODE_OAUTH_TOKEN 运行的会话(许多服务器采用这种方式)会被视为未登录,即使系统中保存了登录信息也是如此。在服务器上安装 mod 之前,先确认 Claude Code mod 可以更改哪些内容。
为什么我的 hook 没有触发?
按以下顺序排查。每一步都说明了你实际会看到的现象。
- 运行
/hooks,检查 hook 是否显示在预期的事件下。hook 未出现在菜单中,通常表示设置文件存在 JSON 语法错误,因为不允许使用尾随逗号和注释;也可能表示文件不在上述六个位置之一。 - 将匹配器与工具名称逐字比较。匹配器区分大小写,因此
"bash"永远不会匹配Bash工具。 - 按上面示例 1 的方式,使用示例输入手动运行脚本。意外的退出码表示脚本存在问题;同时检查其标准输出,因为即使 JSON 有效,也可能为
PreToolUse等事件提供决策。 - 如果看到
jq: command not found,表示该计算机缺少jq。如果你自己的脚本出现command not found,表示路径无法解析,因此请使用${CLAUDE_PROJECT_DIR}或绝对路径。如果脚本完全没有运行,通常是因为它没有执行权限。 - hook 输出了有效 JSON,但没有任何效果。在 macOS 和 Linux 上,shell 形式的 hook 会通过
sh -c在非交互式 shell 中运行,但某些配置仍会加载用户配置文件,例如BASH_ENV指向~/.bashrc时。如果该配置文件输出启动横幅,横幅就会添加到 JSON 前面。标准输出不再以{开头,因此 Claude Code 会将整个输出作为纯文本读取,并忽略其中的决策。由于 hook 以 0 退出,执行记录中不会显示错误。对于大多数事件,这些文本只会写入调试日志;但对于UserPromptSubmit、UserPromptExpansion、SessionStart和PostModelSwitch,文本会连同横幅一起添加到模型上下文中。在配置文件中,将任何echo包裹起来,使其仅在交互式 shell 中运行。 - 仍无法解决时,使用
claude --debug-file /tmp/claude.log启动会话,并在第二个终端中运行tail -f /tmp/claude.log。调试日志会记录匹配的 hook、每个 hook 返回的退出码,以及它们写入标准输出和标准错误的全部内容。
FAQ
Claude Code hook 与 CLAUDE.md 指令有什么区别?
CLAUDE.md 指令是模型上下文中的文本,因此会与对话和当前请求竞争注意力,模型可以权衡这些内容。hook 是 Claude Code 在生命周期中的固定阶段执行的 shell 命令,因此每次发生相应事件时都会执行,不受模型决策影响。偏好设置应使用指令。必须始终执行的步骤或绝不能执行的操作应使用 hook。
如何阻止 Claude Code 执行特定的 shell 命令?
注册一个 PreToolUse hook,并使用 Bash 匹配器从 .tool_input.command 读取命令,将原因写入 stderr,然后退出并返回 2。Claude Code 会取消此次调用,并向模型显示你的原因。此操作发生在权限模式检查之前,因此即使处于 bypassPermissions 模式,拒绝仍然有效。针对命令字符串进行模式匹配只能提供防护,不能构成安全边界,因为同一命令可能以模式无法匹配的形式书写。因此,还应结合权限规则和非特权账户使用。
我的 hook 输出了有效 JSON,但没有任何效果。为什么?
检查 shell 配置文件,确认 JSON 前没有输出其他文本。在 macOS 和 Linux 上,不包含 args 字段的 hook 会通过 sh -c 执行。在仍会加载配置文件的环境中,例如 BASH_ENV 指向 ~/.bashrc 时,如果配置文件输出启动横幅,该内容就会出现在 JSON 之前。由于输出不再以 { 开头,Claude Code 会将全部输出视为普通文本并忽略其中的决策;又因为 hook 以 0 退出,记录中不会显示错误。在配置文件中,使用交互式 shell 检查保护所有 echo。然后读取 claude --debug-file /tmp/claude.log 中的调试日志,确认问题已修复。
在共享服务器上运行 Claude Code hook 是否安全?
hook 会以启动 Claude Code 的用户身份运行,并使用该用户的文件权限,因此 hook 可以执行该账户有权限执行的任何操作。以下两项做法可以覆盖大多数风险:使用具有严格 sudo 策略的专用非特权账户运行代理;在接受仓库的工作区信任对话框或在其中运行 claude -p 前,先阅读仓库的 hooks 区块,因为项目 hook 位于 .claude/settings.json 中,而 -p 模式不会显示该对话框。在设置文件中设置 "disableAllHooks": true 以禁用 hook,但需要在托管级别设置该选项的托管 hook 除外。项目设置中的 false 可以覆盖用户设置中的 true。