Claude Code v2.1.317 转正：磁盘写满时 claude -p 退出码从 0 变 1

要点

• v2.1.317 于 tag 时间戳 2026-11-03T01:25:46Z 发布，prerelease: false，接替 10-31 的 v2.1.316。生产请从 v2.1.316 改钉 v2.1.317。
• claude -p 在磁盘写满或配额耗尽导致 transcript / ~/.claude.json 写入失败时，退出码从 0 改为 1：官方原文 "it now prints an error and, in text and json output, exits 1. Full NFS exports may be missed"。用退出码判成败的 CI 会从「静默通过」变成「显式失败」。
• stdio MCP 服务器的 AWS_BEARER_TOKEN_BEDROCK 从「传空串」改为「不设置」：官方原文 "the variable is now unset, so the server can use the machine's own AWS credentials"。这是环境变量语义变更，不是新增开关。
• Grep / Glob 命中时间上限时不再被当成完整结果：官方原文 "Fixed Claude treating partial Grep and Glob results as complete when a search hit its time limit"。此前搜索被截断后，模型会把它当「这就是全部」继续推理。
• Removed 一条最容易被忽略：Read 工具的「file unchanged since your last Read」占位符被撤掉，重复读取未改动文件重新返回全文——这是把上一轮为省 token 做的优化回退了，长会话上下文占用会回升。
• 新增 onFailure: "block"（Agent SDK hook 回调）：回调失败时阻断该动作，而不是让动作照常执行——把「钩子挂了 = 不生效」翻成「钩子挂了 = 不许做」，这是 fail-closed 语义。
• 新增一道隐私确认：在 web 或 shell 工具调用把账号邮箱地址发往网络前先询问。
• /schedule 新增告警：云定时任务拿到「你没要求的 connectors」时会提示并可移除。
• 新增 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID：在自建 runner 上设 1，让 claude -p 在会话内运行时使用该会话的 ID 与 transcript（回到早期版本行为）。
• Changed 两条会改行为：① SendMessage 发给运行中的后台 agent 会更早到达——它正在跑的命令被移到后台，而不是被停掉；② 子代理 / 队友用的是另一模型时，改用该模型自己保存的 effort 档位或它的默认值，不再继承会话 effort。这一条与 v2.1.316 新增的 CLAUDE_CODE_SUBAGENT_EFFORT 是同一问题的两个层次，fan-out 编排的实际 effort 需要重新核对。
• 网关补齐成本可见性：新增 GET /v1/organizations/analytics/cost（按日期区间读历史花费，可按总量 / 按开发者 / 按天 / 按 IdP 组聚合），以及 admin: 网关上每名开发者 IdP 组的按日记录，保留期 admin.identity_retention_days，成本报表正是按它分组。
• OTel 属性扩四项：anthropic.plan、anthropic.seat_type、anthropic.provider、anthropic.custom_base_url 进入指标 / 事件 / span——此前无法在可观测性侧区分套餐与供应商，现在可以。
• OTel 导出补超时：代理不应答时不再无限挂起，10 秒超时，可用 OTEL_EXPORTER_OTLP_TIMEOUT 放宽到最多 30 秒。

背景与分析

三条「写在 Fixes 里、实为行为变更」的条目

本站从 10 月起反复记录同一现象：Anthropic 把改变运行行为的条目放进 Bug Fixes 段。这次是第五次命中，而且三条都属于「判据改变」而非「缺陷消失」：

三条的共同点：它们改的不是「某个功能坏了」，而是「什么算成功、什么算有值、什么算查完了」。本站据此把判据固化为一条：凡改变退出码、改变默认值、改变「算不算数」的判定，一律按行为变更处理，不论它写在哪个段落。

为什么退出码这条比看起来重要

claude -p 是脚本化调用的主入口。此前磁盘写满或配额耗尽时，transcript 写不进去，但进程仍以 0 退出——上游 CI 看到的是绿色，实际这次任务的结果没有被保存。

改成 1 之后，行为是「显式失败」，这本身是修对了方向；但对既有流水线是破坏性的：任何把 claude -p 包在 if 里、或依赖 set -e 之外判断的脚本，从此会走进失败分支。

官方在同一句里写了一个边界："Full NFS exports may be missed"——NFS 完全写满这种情况仍可能漏判。也就是说修复的覆盖面是「本地磁盘与配额」，不是「所有写盘失败」。

Read 工具回退省 token 优化

v2.1.3xx 早期版本给 Read 加过一个占位符：同一文件未改动时，重复 Read 只返回「file unchanged since your last Read」，用极小代价提醒模型不必再看。本次 Removed 把这条撤掉，重复读取重新返回全文。

方向上的解读是：占位符让模型误判文件内容的情况多于它省下的 token。代价是长会话里反复读同一文件的场景，上下文增长会更快——与 v2.1.311 起「超过 200K 自动压缩续跑」叠加后，压缩会更早触发。习惯让 agent 反复回读大文件的团队，值得在升级后观察压缩频率。

企业侧：成本终于能按人、按组读了

GET /v1/organizations/analytics/cost 加 IdP 组按日记录，是这一版对企业客户最实际的一条。此前网关侧只有「用量上限」和「池化预算」（v2.1.316 新增 pooled_budget），能限流但不能归因；现在可以按开发者、按天、按 IdP 组拉历史花费。

两处需要读者自己核对：报表的取数口径（是否含 cache 读写、是否含 pooled 扣减）官方本条未写；admin.identity_retention_days 的默认值与上限也未给出。这两点直接决定报表能不能当账单用，本站不替官方推断，列为待核实。

版本序列

经 Releases 与 /tags 双端点核对，序列为 …312 → 314 → 316 → 317。v2.1.313 / v2.1.315 两个缺口此前已多次确认（前者为本站第三次、后者第二次），官方始终未说明原因，本站不补写编号、不作推断。另 v2.1.297 / v2.1.298 的缺口延续未解。

对开发者的影响

• 用 claude -p 跑流水线的，先跑一次失败路径。磁盘满不容易构造，可以用配额或只读挂载模拟；重点看上游是否把「退出码 1」正确识别为失败，而不是当异常吞掉。
• stdio MCP 服务器依赖 AWS_BEARER_TOKEN_BEDROCK 的，升级后逐个确认凭据来源。从「传空串」变成「不设置」，意味着此前因为拿到空串而失败的 Bedrock 调用，现在会真的去用机器上的 AWS 凭据——在共享机器或多账号环境里，这是个需要复核的权限面。
• 把 Grep / Glob 当穷举结果的自动化要加兜底。搜索结果被截断时会明确告知，但下游流程是否处理这个信号，得自己实现。
• fan-out 编排重新核对 effort 实际值。子代理不再无条件继承会话 effort，主会话设 xhigh 不再等于所有子任务都 xhigh。
• 长会话成本重新估算。Read 占位符撤销后，重复读取的 token 开销回来了，压缩点会前移。

AI 之家 观点

这一版没有新功能头条，但它改了三处「判据」。 退出码、环境变量、搜索结果完整性——这三样东西平时没人盯着，出了问题也不会报错，只会静默给错结果。Anthropic 这次把它们从「静默出错」改成「明确失败」，方向是对的；代价是所有依赖旧判据的自动化会在升级后集中暴露。

我们的判断是：升级该升，但别当成一次普通小版本。 建议顺序是「先升级，再逐条跑失败路径验证，最后才放开给团队用」。特别是 claude -p 退出码这条——它的修复价值只有在流水线真的把 1 当失败时才兑现，如果上游用 || true 吞掉，这次升级对你等于没发生。

另一点值得记下：把「为省 token 的优化」撤回，是需要一点勇气的。占位符省下的 token 是显性的，模型误判文件的代价是隐性的，官方选择回到隐性成本更低的一侧。这个取舍比功能本身更值得参考。

相关阅读

• Claude Code 工具卡——完整版本演进、定价与国内使用门槛
• Claude Code v2.1.316 资讯——Opus 4.8 fast mode 11-30 硬失败，本条早一版
• AI 编程 IDE 与 CLI 版本对照——五个 CLI 的当前 stable 版本表
• Agent 记忆与上下文管理——自动压缩续跑与长会话上下文的关系
• Cursor 扩展市场投毒事件——同产品线的供应链安全事件

来源

• ⭐ Claude Code v2.1.317 Release Notes（GitHub Releases 官方原文，tag 时间戳 2026-11-03T01:25:46Z，prerelease: false）
• anthropics/claude-code Releases 列表（官方，同批核对 v2.1.316 / v2.1.314 / v2.1.312 时间戳）
• Claude Code 官方文档（Anthropic，用于核对环境变量与权限相关表述）

取证边界：本条事实全部来自 GitHub Releases 的官方 Release Notes 原文，未对 GET /v1/organizations/analytics/cost 做实际调用验证（无企业网关环境），报表字段与口径属「官方声明」，不是本站实测。官方 Release Notes 标题为 What's changed，标题下不标注发布日期，本文 2026-11-03T01:25:46Z 取自 tag 时间戳，非厂商公布发布日。