摘要：2026 年 10 月 8 日，Anthropic 发布 Claude Code v2.1.295。本次更新里最值得看的一条是给 command 与 HTTP 两类 hook 增加了 onFailure: "block"：钩子无法启动、超时，或以非预期退出码结束时，直接拦住该动作，而不是放行。这条改动的意义要结合官方文档才看得出来——按现有文档，钩子失败在多数情况下是静默放行的：退出码 1 属非阻断错误，超时的钩子会被取消且不产生任何决定，官方甚至写明"不要指望卡住的钩子充当闸门"。同版本还带上终端状态协议 OSC 7501，以及网关上游的超时与模型白名单控制。
导语：把策略写进 hook 的人，迟早会问同一个问题：钩子自己出错时，是被拦住还是放行？过去很长时间里，答案在多数事件上是"放行"，而且是不报错的那种放行。你写了禁止写入某个目录的检查脚本，某天脚本依赖的运行时没装好、启动失败，命令照跑，因为没有任何东西告诉 Claude Code 该停下来。v2.1.295 给的，是把这件事变成显式选择的能力。本文讲三件事：这条选项改了什么、默认行为的边界在哪、开启后要承担什么。
AI Coding 交流群
如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。
发生了什么：一条新选项，两个配套改动
按 v2.1.295 的官方 Release 说明，本次新增的第一项也是最核心的一项，是给 command 与 HTTP 两类 hook 增加 onFailure: "block"。语义很明确：钩子如果无法启动、超时，或以非预期退出码结束，该动作被拦住而不是放行。默认行为保持不变——不加这项配置的钩子行为与之前一致。
第二项是终端协议支持：新增 Program Status Protocol（OSC 7501）。实现该协议的终端可以显示 Claude Code 当前处于三种状态中的哪一种——正在工作、在等你输入、已经完成。对把 Claude Code 放在 tmux、终端分屏或自定义状态栏里的人来说，这解决的是"我离开了三分钟，回来不知道它是在跑还是已经停下来等我"的问题。
第三项面向使用 Claude apps gateway 的部署：网关上游新增 timeouts.upstream_ttfb_ms，可用于 Bedrock、Vertex、Foundry 以及其他云端上游，限制一条流开始前的等待时间，超过之后要么故障转移到其他上游，要么返回 502；每个上游还可以配一个可选的 models 列表，只有列表内的模型会被发往该上游，故障转移时同样生效，列表项里的单个 * 作为通配符。可观测性上，网关的 inference 审计事件新增 upstream_request_id，成功响应的头部新增 request-id，用来把 Claude Code 侧的遥测和网关审计日志对上。
其他调整一并记录：MCP 工具描述经工具搜索加载时的截断上限从 2048 个字符提高到 16384；子 Agent 最多预载 32 个 skill；远程 MCP 反复断开的重连退避最高到 30 秒；WebSocket 类 MCP 服务器上超过 16 MiB 的消息不再解析并直接关闭连接。另有一处行为变化：在 macOS 或未安装后台服务的 Linux 上，随后台服务一同停止的 claude agents，运行中的会话现在会在大约一分钟后停止，除非再次运行它。
为什么这条选项重要：官方文档里，钩子默认是"失败即放行"
要理解 onFailure: "block" 的价值，得先看清默认行为。官方 Hooks 参考文档把失败路径写得很细，逐条读下来几乎是一份"闸门为什么会漏"的清单。
第一，退出码不会自动帮你拦。文档写明：stdout 上没有合法 JSON 时，退出码 1 被当作非阻断错误，执行继续，即便 1 是 Unix 约定俗成的失败码；要拦停必须用退出码 2。同一处还提醒，settings.json 里一个写错的路径会让这道闸门悄悄失效，而你不会收到任何提示。
第二，超时的钩子等于没有表态。文档说明，命令、HTTP、MCP 工具三类钩子在到达超时后会被取消并丢弃输出，在多数事件上"没有产生任何决定"；在 PreToolUse 上，超时的 command / http / mcp_tool 钩子不会拦住工具调用，调用会继续走正常权限流程。文档里有一句非常直白的表述：不要指望卡住的钩子充当闸门。只有 Agent SDK 回调钩子超时会拦住工具调用。
第三，HTTP 型 hook 的失败路径同样偏软：非 2xx 状态、连接失败、超时都算非阻断错误，执行继续；要拦截必须返回 2xx 并带上含决定字段的 JSON。
三条合起来看，结论是：以前 hook 更像"建议"——它拦得住自己能正常判断的情况，自己出问题时却会安静让路。这正是 onFailure: "block" 要改的那件事。
同日发布的 v2.1.294 是一个旁证。它修了一个具体缺陷：把 prompt 与 agent 型钩子写成指令形式时，它们会放行本该拦停的操作；该版本还改进了 Stop 与 SubagentStop 上 prompt 钩子的判断，让 Claude 更不容易提前收工。一边修"钩子判断错了"，一边加"钩子坏了怎么办"。
一个具体工作流：从"策略脚本崩了就静默失效"到"崩了就停"
假设一个团队用命令型钩子做仓库级护栏：在 PreToolUse 阶段跑脚本检查这次工具调用要写的路径是否落在允许目录里，不允许就退回退出码 2。
改造前的风险链条是这样的：某天有人升级了机器，脚本依赖的解释器路径变了，钩子启动失败；按文档描述，这属于非阻断错误，退出码不是 2，Claude Code 继续执行工具调用；一次本该被拦下的写入顺利完成，而且没有任何人收到告警。这类问题不会在测试里暴露，因为它只在钩子坏掉时才发生，而那时系统是静默的。
给这个钩子加上 onFailure: "block" 之后，同一个场景的结果变成：脚本启动失败，动作被拦住，工作流停在那里等人处理。这个变化把一类"静默失效"转成了"显式故障"。对真正的策略闸门来说，这是正确的失败方向——安全控制在不确定时应该拒绝，而不是放行。
代价也随之而来，而且是确定的：钩子本身的问题现在会挡住正常工作。如果这个脚本需要访问网络、需要加载一个较大的运行时，或者在负载高的机器上偶尔超过超时阈值，那么开启之后，这些原本被忽略的抖动都会变成阻塞。所以开启之前应该先做两件事：把钩子的超时值调到足够宽，以及在真实环境里压测它在冷启动和异常输入下的表现。
限制、边界，以及人应该在哪里接管
第一，这是按钩子逐个开启的选项，不是全局开关。声明里只说对 command 与 HTTP 两类钩子生效，没有承诺 mcp_tool 与 Agent SDK 回调钩子也走同一套失败语义——后者在 PreToolUse 上超时本来就是拦住工具调用的。混合使用多种钩子类型的团队，需要分别确认每一类在失败时的行为。
第二，OSC 7501 依赖终端实现。它是协议支持，不是 Claude Code 自己能决定的效果；终端不实现该协议时不会显示这些状态。它解决的是看得到状态，不解决把状态推给你——离开终端的人仍需别的方式获知结果。
第三，网关相关的新选项只对使用 Claude apps gateway 的部署有意义。普通直连 Anthropic API 或使用官方云上游的个人用户，timeouts.upstream_ttfb_ms 与 models 白名单这两项用不上，不必为此调整配置。
关于人应该在哪里接管：把钩子从"失败放行"改成"失败拦停"，本质上是把可用性换成确定性。凡是拦停之后会直接中断生产的钩子，都不该在没有人盯着的时候开启；反过来，只影响本地开发的护栏，开启后最坏结果是自己被挡住几分钟。建议按影响面分批启用，先覆盖改文件和执行命令这类高代价动作，再考虑其他。
如何试用
升级到 v2.1.295 即可拿到上述全部改动。要使用新的失败策略，在 command 或 HTTP 类型的钩子配置里加上 onFailure: "block"；不加则维持原行为。
终端状态显示需要在实现了 Program Status Protocol（OSC 7501）的终端中运行。网关相关配置属于使用 Claude apps gateway 的场景，按部署在对应上游上设置 timeouts.upstream_ttfb_ms 与可选的 models 列表。
在开启失败拦停之前，建议先回到官方 Hooks 参考文档重读一遍超时与退出码两节——那里逐条写明了几类钩子在超时、非 2xx、连接失败时各自会发生什么，是决定"这个钩子该不该拦停"的直接依据。
信息来源
- Claude Code 官方 Release：v2.1.295（2026-10-08，
onFailure: "block"、OSC 7501、网关上游选项与其他变更） - Claude Code 官方 Release：v2.1.294（2026-10-08，prompt / agent 钩子放行问题的修复）
- Claude Code 文档：Hooks reference（退出码、超时、HTTP 响应处理等失败路径的默认行为）
HiFox ：将 Agent 变成真正的队友
另外，我们也在思考，AI 如何从个人提效走进团队协作。
HiFox 是一个让人和 AI Agent 在同一个工作现场协作的平台：你可以像给同事分派任务一样指派 Agent，在任务看板中跟踪进度、查看结果，让 Agent 成为团队里的队友。
👉 立即体验 Hifox：https://hifox.com
AI Coding 交流群
如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。