Claude Code v2.1.317：帳號 email 檢查與 gateway 成本報表

Claude Code v2.1.317 共有 87 條變更：62 條修正、10 條新增、8 條改進、6 條行為變更、1 條移除。主要的新增項目有：網頁或 shell 工具呼叫要把你的帳號 email 地址送上網路前會先詢問、Agent SDK 的 hook callback 支援 onFailure: "block"、Claude apps gateway 的成本報表，以及四個新的 OpenTelemetry 屬性。修正範圍很廣，比較集中在 headless claude -p 執行與自架 runner、經由代理伺服器的 OpenTelemetry 匯出、agent team，以及 VS Code 擴充套件。另有幾條改動了既有行為，包括 subagent 使用的 effort 等級，以及 Read 工具對未變更檔案的回傳內容，更新前請先看「值得注意的行為變更」一節。

新功能

帳號 email 送出前先詢問。 當網頁或 shell 工具呼叫要把你的帳號 email 地址送上網路時，Claude Code 現在會先詢問你。

Agent SDK hook callback 的 onFailure: "block"。 設定這個選項後，Agent SDK 的 hook callback 一旦失敗，就會擋下該動作，而不是讓它照常執行；拿來當防線的 callback 因此會「失敗即阻擋」（fail closed）。command 與 HTTP hook 從 v2.1.295 起就支援 onFailure: "block"，這一版把它延伸到 SDK callback。

新的通知與警告。

auto 模式的檢查對 subagent 的工具呼叫沒有給出答案時，現在會顯示通知；過去主畫面上什麼都不會出現。
組織的遠端受管設定尚未在該 session 載入時，Claude Desktop 的 Code 分頁會顯示通知，載入完成後再顯示另一則。
新的雲端排程任務被加上你沒有要求的 connector 時，/schedule 會發出警告，並說明如何移除。
MCP 伺服器要求你造訪某個連結時，雲端 session 會顯示連結卡片，讓你選擇開啟或拒絕；過去這類請求你根本看不到。

值得注意的行為變更

使用其他模型的 subagent 與 teammate 改用該模型的 effort。 與主對話使用不同模型的 subagent 或 agent team teammate，現在會使用該模型已儲存的 effort 等級或該模型的預設值，而不是 session 的 effort 等級。調高 session 的 effort，不會再延續到交給其他模型處理的工作。effort 的其他設定方式，請見我們的 effort 等級指南。
SendMessage 更快送達執行中的背景 agent。 用 SendMessage 傳給執行中背景 agent 的訊息現在會更早送達：該 agent 正在執行的命令會移到背景，而且不會被中止。
結束時不再為外掛 monitor 詢問。 外掛 monitor 不再於你結束時觸發「Background work is running」提示。
移除 Read 工具的「未變更」替代內容。 再次讀取沒有變更的檔案時，現在會回傳檔案內容；過去 Read 會回傳「file unchanged since your last Read」這段替代內容。
plugin-authoring 會提議協助分享 mod。 你做的 mod 能正常運作後，內建的 plugin-authoring skill 現在會提議一次，協助你分享它。
claude -p 的結束碼與 session ID。 下一節的兩項修正會改變腳本看到的結果：在 text 與 json 輸出下，寫入遺失時 claude -p 現在會以 1 結束；在雲端或自架 runner session 內執行的 claude -p，也不再共用該 session 的 ID。

Headless 執行與自架 runner

寫入遺失現在會讓執行失敗。 過去當磁碟或配額已滿，導致 transcript 或 ~/.claude.json 的寫入遺失時，claude -p 仍然以 0 結束。現在它會印出錯誤，並在 text 與 json 輸出下以 1 結束。變更日誌也註明，NFS export 已滿的情況仍可能偵測不到。

巢狀執行不再共用 session 的 ID。 在雲端或自架 runner session 內執行的 claude -p，過去會共用該 session 的 ID：它會寫進該 session 的 transcript，重新啟動後也可能恢復到錯誤的對話。它還會自行產生標題並送到該 session。這兩個問題都已修正。如果你的自架 runner 設定仰賴舊行為，請在 runner 上設定 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1，session 內執行的 claude -p 就會像先前版本一樣，使用該 session 的 ID 與 transcript。

無人值守執行的其他修正：

有許多外掛註冊命令的 headless session，不再出現記憶體用量偏高與啟動緩慢。
在計畫（plan）等待核准期間重新啟動的自架 runner session，不再遺失最近幾輪或整段對話。
session 移到新的 runner，且該輪已超過 CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS 的時限時，Claude 現在看得到被中斷的工具呼叫。
你關閉的 MCP 伺服器，不再於 session 移到新機器後重新開啟；這個問題發生在 session 服務先前拒絕儲存該切換的情況。
三項改進調整了 runner 及其 session 從連線失敗中復原的方式。遇到 501 與 529 以外的 5xx 錯誤後，runner 的下一次輪詢與 session 本身都會開新連線，而不是重用失敗的那條。heartbeat 沒有得到回應後，session 會開新連線，而不是逐一嘗試每條閒置連線。

Claude apps gateway

管理 API 的成本報表。 GET /v1/organizations/analytics/cost 可讀取指定日期區間內的過往花費，可以看總計，也可以依開發者、依日或依 IdP 群組拆分。
IdP 群組的每日紀錄。 設有 admin: 的 gateway 現在會每天記錄每位開發者所屬的 IdP 群組，保留 admin.identity_retention_days 所設的天數，成本報表就依這份紀錄分組。
共用預算。 群組的共用預算用完後，狀態列與 /usage 不再把開發者自己的花費上限顯示為已用 100%。
Bedrock 的「Input is too long.」。 gateway 不再隱藏這個 Amazon Bedrock 錯誤。過去錯誤被隱藏，session 每一輪都以「upstream rejected the request」失敗，而不會進行壓縮。
更清楚的啟動錯誤。 連不上必要的 gateway 時，啟動錯誤現在會指向網路而不是登入，並在無法驗證 gateway 的 TLS 憑證時明確說明。

OpenTelemetry

四個新屬性。 OTel 的 metrics、events 與 spans 現在都會加上 anthropic.plan、anthropic.seat_type、anthropic.provider 與 anthropic.custom_base_url。
經由代理伺服器送往 https:// 端點的匯出，若在另一筆匯出尚未完成時開始，過去永遠不會送出；現在會正常送出。
會封鎖（HTTP 403）http:// 端點匯出的代理伺服器，不再收到大量連線嘗試。
在永遠不回應的代理伺服器後方，匯出不再無限期卡住；現在會在 10 秒後逾時，或依 OTEL_EXPORTER_OTLP_TIMEOUT 的設定逾時，最長 30 秒。

其他修正與改進

Session 與壓縮

超大型 CLAUDE.md 在上次送出後有變更的 session，自動壓縮後不再出現「Prompt is too long」。
壓縮必須縮短自身請求時，超長對話不再遺失先前的摘要。
恢復（resume）的 session 不再把 Claude 早已知道的檔案變更再告訴它一次。
在恢復的 session 中，若先前某次呼叫因工具被關閉而失敗，Claude 有時會因此不再使用該內建工具；這個問題已修正。
結束時顯示的「Resume this session with」提示，現在會在 --resume 前面重複你啟動時用的旗標，例如 --chrome --debug。
在 session 很多的專案中，當連結的 session 比第一頁還舊時，claude --from-pr 不再回報「No conversations found」。
在雲端與 SDK session 中，若標題產生期間收到新訊息或 Stop，session 標題不再遺失。
在部分執行會略過清理的機器上（例如使用 --setting-sources 的執行），舊的 transcript 現在也會被清理。

檔案、搜尋與設定

搜尋達到時間上限時，Claude 不再把 Grep 與 Glob 的部分結果當成完整結果。
PDF 本身的中繼資料，不再能讓 Read 與 @ 提及少算它的頁數。
啟動後大約第一秒內對設定檔做的修改現在會生效，不必等到設定檔再次變更。
專案的 effortLevel 設定，現在也會套用到由應用程式預先啟動、之後才在專案中開啟的 session，例如桌面應用 Code 分頁裡的新 session。
DISABLE_PROMPT_CACHING_OPUS 與 DISABLE_PROMPT_CACHING_SONNET 現在對預設模型的 [1m]、其他區域與不含日期的寫法也會生效。

Agent team、背景工作與權限

已刪除的 agent team 收件匣，不再因 teammate 遲到的訊息而被重新建立；重新建立的 teammate，也不再被先前的 shutdown 核准移出團隊。
lead session 處於 manual 模式時，tmux 或 iTerm2 窗格中的 teammate 不再以 auto 模式啟動。
背景 session 在升級或退役時，不再有時遺失你剛做的權限模式變更。
在輸入列按 Ctrl+C 清除已輸入的文字，不再停止所有執行中的背景 agent。
已停止的 shell 命令的子行程，不再有時收到兩次 SIGTERM；這曾讓部分程式略過清理工作。
設為 base URL 的 LLM gateway 對伺服器端安全檢查回應 403 或 422 時，auto 模式不再每一輪都失敗。搭配 apiKeyHelper 時的 403 行為維持不變。
在雲端 session 中，Artifact 工具上傳、寫入資料庫，或透過 outputs 資料夾儲存檔案時，auto 模式不再停下來等待核准。
在 claude.ai 與行動應用程式上，同時出現兩個權限提示時，第二個現在也會顯示其檔案路徑或命令。
Remote Control 與 SDK host 不再對 mod 的工具呼叫提供「don’t ask again」選項。
在螢幕閱讀器模式下，執行中 subagent 的經過時間與 token 數，不再於每次變動時都被唸出。

登入、代理伺服器與供應商

地區或網路封鎖（HTTP 403）不再被顯示為登入失敗；錯誤訊息現在會說明封鎖情形。
claude auth status 不再於較慢的 token 重新整理儲存完成前就結束；過去這可能讓你在下次執行時被登出。
根憑證更新後，在部分進行 TLS 檢查的代理伺服器後方，API 請求不再以「unable to get local issuer certificate」失敗。
在 Microsoft Foundry 上無法載入 Azure 憑證時，錯誤訊息現在會提示你檢查或重新整理憑證，並回報為 cloud_credential_error。
stdio MCP 伺服器的 env 設定把 AWS_BEARER_TOKEN_BEDROCK 設為空值時，該變數現在會被取消設定，而不是以空值傳入，伺服器因此可以使用本機自己的 AWS 憑證。

MCP、skill 與命令

在部分 Claude Desktop session 中，專案與本機（local）MCP 伺服器不再於第一輪後斷線。
在雲端 session 中，同步的外掛包含同一個伺服器時，Claude 不再誤稱正常運作的 claude.ai connector 需要授權或已經失敗。
從 claude.ai 同步的 skill 無法寫入磁碟時，不再遺失，也不再每十分鐘重新下載一次。
/team-onboarding：被要求刪除指南卻沒指明哪一份時，Claude 不再刪掉你最近更新的那一份；伺服器拒絕刪除時，也不再聲稱指南已刪除。
你自己的 artifact 有 200 個以上時，/artifacts 與 Artifact 工具的共用清單現在也會顯示共用的 artifact。
/remote-control 現在會說明 Remote Control 已被 disableRemoteControl 設定關閉，而不是回答「Unknown command」。
/design-sync 現在會事先告知你的設計系統已移到 Claude，並在建置前停止，而不是到上傳時才失敗。
回報送出期間，/feedback 不再顯示「Enter to confirm」。

排程任務

建立或更新雲端排程任務後，/schedule 的結果現在會包含下次執行時間與連結。
關閉排程任務後，現在仍可列出與刪除已儲存的排程任務。
Claude 在請求中漏掉某個欄位時，由 Claude 自行控制節奏（self-paced）的 /loop 喚醒不再有時沒被排入。
在雲端 session 中，新排程任務的表單現在會從管理員為組織選定的預設環境開始，而不是 Anthropic 代管的預設環境。

Windows

在部分原生路徑查詢會失敗的磁碟區上，過去每個工具呼叫都會被拒絕。工作目錄檢查現在改為比對資料夾本身的識別（identity）。
在不是由 Claude Desktop 啟動的 session 中，session scratchpad 與其他暫存路徑不再隨專案路徑長度增長；過去這會讓 clone 到其中的儲存庫碰上 260 字元的路徑上限。

VS Code

分叉（fork）的對話不再遺失訊息。過去 Claude 平行執行的多個工具呼叫只會保留其中一個，壓縮所保留的最後幾則訊息也會遺失，可能讓 Claude 的回答少了它所回應的問題。
Claude 未能及時完成啟動時，訊息會遺失；擴充套件現在會在顯示錯誤前再啟動一次 Claude。
請求因地區或網路被封鎖時，不再開啟登入畫面。
Claude 分頁中的檔案連結現在會在另一個編輯器群組開啟，而不是蓋在聊天畫面上。
調高 chat.fontSize 時，Claude 面板中的附件 chip、選單、橫幅與對話框不再維持小尺寸。
關閉遙測時，ultrathink 現在也會提高該輪的 effort，並顯示彩虹效果。
Account 面板不再把方案名稱的第二個字顯示為小寫。

雲端 session、Remote Control 與 Claude Tag

雲端 session： 為已有網路 secret 的主機新增 secret 時，不再無聲地取代原本的 secret；Add secret 表單會拒絕，並引導你到既有的 secret。管理設定中的組織環境對話框，現在改用個人對話框的精簡版面：每個區塊從一列展開，有未儲存的輸入時，關閉前會先詢問。
Remote Control： 重新啟動 claude remote-control 後，若在上一則訊息後一分鐘內傳訊息給閒置的 session，這則訊息不再得不到回應。應用程式沒有設定 fork 名稱時，過長的名稱會保留結尾的「(fork)」；在以 claude remote-control 啟動的 session 中，「Name (fork)」的 fork 會命名為「Name (fork 2)」。
Claude Tag： 在 Slack 新貼上的 artifact 連結，會顯示較簡潔的卡片與 Open 按鈕，直接在 Claude 中開啟 artifact，而不是開啟 Slack 的側邊面板。

全部 87 條的原文，請見官方變更日誌。

如何更新

檢查已安裝的版本：claude --version
直接就地更新：claude update
在自架 runner 上，如果 session 內的 claude -p 應繼續使用該 session 的 ID 與 transcript，請設定 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1。

新功能