はじめに
対象読者は、claude -p のスクリプトやサブエージェント、Agent SDK を組み合わせて Claude Code を実務で運用している方です。
Claude Code のリリースノートは 1 版で数十行に及ぶことが珍しくありません。2.1.317 も例外ではなく、全部を読み込む時間はなかなか取れません。かといって読み飛ばすと、ある日スクリプトの終了コードが変わっていた、サブエージェントの出力の傾向が変わっていた、といった形で後から気づくことになります。運用している側が知りたいのは「この版で、自分の設定やスクリプトのどこを見直せばよいか」です。
この記事では、2.1.317 の changelog から運用者が手を動かして確認すべき変更を 8 つ選び、確認の順番に並べました。/schedule の不要コネクタ警告とログイン期限の扱いは、2.1.317 と 2.1.318 をあわせて扱った別記事「Claude Code 2.1.318、/schedule警告とログイン期限の変更点ガイド」で取り上げているため、ここでは重複させず、サブエージェントと非対話実行に関わる変更を中心に扱います。
この記事で分かること
- 2.1.317 の 87 行の changelog のうち、運用設定やスクリプトに影響する 8 項目
- 項目ごとに「何を確認し、どう判断するか」の基準
- 筆者が実機で確かめた範囲（Read ツールの二度読み）と、changelog の記載どまりの範囲の区別
前提条件
- Claude Code 2.1.317 以降
- 本文で「確認した」と書いているのは、2026-11-06 JST に Claude Code 2.1.318 の環境で Read ツールの二度読みを試した 1 点だけです。それ以外の項目は、すべて公式 changelog の記載に基づく説明です
TL;DR
この記事の手順を一通り終えると、次のことができるようになります。
- Read ツールが未変更のファイルでも本文を返す前提で、手順書やプロンプトを書けるようになります
- 無人実行でメールアドレス送信前の確認が承認待ちを生まないか、事前に洗い出せます
-
claude -pのラッパーで、記録の書き込み失敗を終了コードから検知できます - 別モデルのサブエージェントで effort が変わる影響を把握し、コストと出力の変化を見張れます
- Grep・Glob の結果が時間切れで部分的なとき、それを前提に判断する手順を組めます
2.1.317 の changelog の規模
公式の CHANGELOG.md の「2.1.317」節は 87 行あります。各行の先頭の語で分けて数えると、次のとおりです（[VSCode] や Windows: のような接頭辞付きの行も、その後ろの語で分類しています）。
| 種別 | 行数 |
|---|---|
| Fixed（修正） | 62 |
| Added（追加） | 10 |
| Improved（改善） | 8 |
| Changed（変更） | 6 |
| Removed（削除） | 1 |
| 合計 | 87 |
修正が 7 割を占めますが、運用で「既存の挙動が変わった」と気づきやすいのは Added・Changed・Removed です。Fixed にも、claude -p の exit 1 化のように無人運用では挙動が変わるものがあります。今回選んだ 8 項目のうち 6 項目は、この 3 種別から拾っています。
8 項目を「何に影響するか」で整理すると次の図になります。手順 4 の環境変数は付随項目として図に含めています。図は changelog の記載を整理したもので、各変更の挙動を筆者が確かめたものではありません（Read の項目を除く）。
手順
1. バージョンを確認する
まず手元の版が 2.1.317 以降かを確かめます。
claude --version
2.1.316 以前の場合、以降の項目はまだ反映されていません。複数の実行環境（手元の端末、CI、セルフホストのランナーなど）がある場合は、それぞれで確認しておくと、挙動の違いに悩まずに済みます。
2. Read ツールの二度読みを前提に手順を見直す
changelog には次のように書かれています。
Removed the Read tool's "file unchanged since your last Read" stub: reading an unchanged file again returns its content
これまでは、前回の Read 以降に変更のないファイルをもう一度読むと、本文の代わりに「前回の Read から変更なし」という短いスタブが返る場合がありました。2.1.317 からは、未変更でも本文がそのまま返ります。
筆者は 2026-11-06 JST、Claude Code 2.1.318 の環境で、同じファイルを Read ツールで 2 回続けて読みました。2 回目も 1〜5 行目の本文がそのまま返り、「file unchanged since your last Read」のスタブは返りませんでした。確かめたのはこの 1 ケースだけで、行範囲を変えた場合や大きなファイルの場合の挙動までは見ていません。
見直す点は次の 2 つです。
- 手順書やプロンプトに「未変更なら再読込は省略される」「スタブが返ったら変更なしとみなす」といった前提を書いている場合は、その記述を外します
- 逆に、同じファイルを何度も読み直す手順は、毎回本文が返る分だけ入力が増えます。必要な範囲を行番号で絞って読む書き方にしておくと、無駄が減ります
3. メールアドレス送信前の確認が承認待ちを生まないか洗い出す
changelog の記載は次のとおりです。
Added a check that asks before a web or shell tool call sends your account email address to the network
Web やシェルのツール呼び出しが、アカウントのメールアドレスをネットワークに送ろうとするとき、事前に確認を求めるようになりました。対話セッションでは、意図しない個人情報の送信を止められる安全側の変更です。
一方、無人実行では確認に答える人がいません。どの条件で確認が出るのか、無人実行でどう扱われるのか（承認待ちで止まるのか、拒否扱いになるのか）は、changelog には記載がありません。そのため判断基準は次のようにしておくのが無難です。
- 無人タスクのプロンプトやスクリプトに、メールアドレスを外部 API に渡す処理（問い合わせフォームへの送信、外部サービスへの登録など）が含まれていないかを洗い出します
- 含まれている場合は、更新後の初回実行を人が見張り、確認で止まらないかを確かめます
- そもそも無人タスクにアカウントのメールアドレスを扱わせる必要があるかを見直します
4. claude -p の終了コードを確実に拾う
changelog には次の修正があります。
Fixed
claude -pexiting 0 when a full disk or quota lost its transcript or ~/.claude.json writes; it now prints an error and, in text and json output, exits 1. Full NFS exports may be missed
ディスクやクォータが満杯で transcript や ~/.claude.json の書き込みに失敗しても、これまでは exit 0 で終わっていました。2.1.317 からは、text と json の出力形式でエラーを表示して exit 1 で終わります。ただし、満杯になった NFS のエクスポートは検出できない場合がある、と但し書きが付いています。
スクリプトから claude -p を呼んでいる場合は、終了コードを確実に拾う書き方になっているかを確認します。以下は一般的な書き方の例で、筆者が実行したログではありません。
#!/usr/bin/env bash
set -u
claude -p "今日の作業ログを要約してください" --output-format json > result.json
status=$?
if [ "$status" -ne 0 ]; then
echo "claude -p が終了コード ${status} で失敗しました" >&2
exit "$status"
fi
判断の基準は 3 つです。
- パイプで別コマンドにつないでいる場合、
$?は最後のコマンドの終了コードになります。set -o pipefailを付けるか、出力をいったんファイルに書いてから終了コードを見る形にします - changelog が exit 1 を明記しているのは text と json の出力形式です。それ以外の出力形式の扱いは changelog には記載がありません
- NFS 上にホームディレクトリを置いている環境では、終了コードだけに頼らず、ディスク使用率の監視を別に持っておきます
あわせて、CLAUDE_CODE_DISABLE_NESTED_SESSION_ID という環境変数も追加されています。
Added
CLAUDE_CODE_DISABLE_NESTED_SESSION_ID: set it to1on a self-hosted runner to haveclaude -prun inside a session use that session's ID and transcript, as in earlier versions
同じ版の修正一覧には、クラウドやセルフホストのランナーのセッション内で実行した claude -p が、そのセッションの ID を共有して transcript に書き込み、再起動時に別の会話を再開しうる問題の修正も載っています。つまり 2.1.317 からは、セッション内の claude -p は既定で親セッションとは別の ID を使います。セルフホストのランナーで、親セッションの transcript に claude -p の記録が残ることを前提に組んでいた場合だけ、この変数を 1 にすると以前の挙動に戻せます。
CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 claude -p "..."
前提にしていないなら、何も設定しないのが安全側です。
5. auto mode の判定不能が表に出るようになったことを把握する
Added a notice when auto mode's check has no answer for a subagent's tool call, which used to leave nothing in the main view
auto mode の判定が、サブエージェントのツール呼び出しに答えを出せなかったとき、これまではメイン画面に何も表示されませんでした。2.1.317 からは通知が出ます。
changelog が述べているのは「メイン画面に何も表示されなかった」点だけです。以下は changelog の記載ではなく筆者の推測ですが、サブエージェントが黙って止まっているように見えたケースの一部は、この判定不能だった可能性があります。通知が出るようになったら、その通知が多発していないかを見ておきます。特定のツールで繰り返し出る場合は、そのツールを許可設定で明示的に許可するか拒否するかを決めておくと（筆者の運用上の提案です）、判定に頼る場面が減ります。通知の文言や、通知後にサブエージェントがどう振る舞うかは changelog には記載がありません。
6. 別モデルのサブエージェントの effort を確認する
Changed subagents and teammates on a different model from the main conversation to use that model's saved effort level or its default, instead of the session's effort level
メイン会話と異なるモデルで動くサブエージェントやチームメイトは、これまでセッションの effort をそのまま使っていました。2.1.317 からは、そのモデルに保存されている effort か、そのモデルの既定値を使います。
たとえばメイン会話で effort を高めに設定し、サブエージェントだけ別モデルにしている構成では、サブエージェントの effort がメイン会話の値から外れる可能性があります。見直す点は次のとおりです。
- サブエージェントに別モデルを指定している定義を洗い出します
- 更新前後で、そのサブエージェントのコストや所要時間、出力の詳しさに変化がないかを見ます
- 意図した effort で動かしたい場合は、そのモデル側の effort を保存しておく必要があります。モデルごとに effort を保存する具体的な手順は、2.1.317 の changelog には記載がありません
メイン会話と同じモデルのサブエージェントは、この変更の対象外です。
7. SendMessage の到達タイミングの変化を知っておく
Changed SendMessage so a message to a running background agent arrives earlier: its running command moves to the background, without being stopped
実行中のバックグラウンドエージェントに SendMessage を送ると、これまでよりも早く届くようになりました。その際、エージェントが実行していたコマンドは止められずにバックグラウンドへ移ります。
途中で方針を伝え直す使い方では、待ち時間が減る方向の変更です。ただ、メッセージを受け取った時点でコマンドがまだ動いている可能性があるため、メッセージで「いまの作業を止めて」と伝えた場合でも、裏で動いているコマンドがそのまま完了まで進むことはありえます。長時間かかるコマンドや外部に書き込むコマンドを実行中のエージェントに指示を送るときは、その点を念頭に置いておきます。
8. Grep・Glob の部分結果を前提にした判断を見直す
Fixed Claude treating partial Grep and Glob results as complete when a search hit its time limit
検索が時間制限に達して結果が部分的なとき、Claude がそれを完全な結果として扱っていた問題が修正されました。
大きなリポジトリで「該当箇所はありません」と結論していた判断の一部は、時間切れの部分結果に基づいていた可能性があります。重要な判断（使われていない関数の削除、設定値の全置換など）を Grep・Glob の結果に委ねている手順では、検索範囲をディレクトリで絞る、件数を別の手段でも確かめる、といった二重確認を入れておくと安心です。
9. Agent SDK のフックで失敗時に止める選択肢を検討する
Added
onFailure: "block"for Agent SDK hook callbacks, so a callback that fails blocks the action instead of letting it run
Agent SDK のフックコールバックに onFailure: "block" が追加されました。コールバック自体が失敗したとき、処理を通すのではなく止められます。
フックで秘密情報の混入チェックや書き込み先の制限をしている場合、そのフックが例外で落ちると、これまでは処理がそのまま実行されていたことになります。安全確認のためのフックには onFailure: "block" を指定する価値があります。逆に、ログ送信のように失敗しても処理を続けてほしいフックには指定しない、という使い分けが判断の基準になります。指定の書き方の詳細は、Agent SDK の公式ドキュメントで確認してください。
無人運用の視点から見た 2.1.317
筆者は Claude Code をスケジュール実行で無人運用しており、その立場で 8 項目を読むと、性質の違う 2 種類の変更が混ざっていると感じました。
1 つ目は、これまで黙って起きていた失敗を表に出す変更です。claude -p の exit 1 化、auto mode の判定不能の通知、Grep・Glob の部分結果の扱い、onFailure: "block" がこれに当たります。どれも、失敗しているのに成功として扱われる状態を減らします。無人運用ではこの「成功の顔をした失敗」がいちばん発見が遅れるため、歓迎できる方向です。ただし表に出た失敗を拾う側（終了コードの判定、通知の監視）が用意されていなければ、効果はありません。
2 つ目は、対話では安全側でも、無人では止まる原因になりうる変更です。メールアドレス送信前の確認がこれに当たります。確認を求める仕組みは、人がその場にいることを前提にしています。
Read ツールの変更は、実機で確かめたうえで、どちらにも属さない「前提の書き換え」だと考えています。スタブが返らなくなったこと自体は単純ですが、手順書やプロンプトに古い前提が残っていると、読み直しの回数や入力量の見積もりがずれます。挙動の変化が小さく見える変更ほど、文書側の前提が取り残されやすい点には注意が必要です。
トラブルシューティング
Q1: 更新後、claude -p を使うスクリプトが失敗扱いで止まるようになった
A: changelog によると、2.1.317 から記録の書き込み失敗で exit 1 になります（text と json の出力形式）。まず標準エラー出力のメッセージと、ディスク使用率・クォータを確認してください。これまで exit 0 で見えていなかった失敗が表に出ただけの可能性があります。
Q2: 別モデルのサブエージェントのコストが変わった
A: 手順 6 の effort の変更が影響している可能性があります。そのサブエージェントが、メイン会話と異なるモデルを指定しているかを確認してください。
Q3: セルフホストのランナーで、claude -p の記録が親セッションの transcript に残らなくなった
A: 2.1.317 で、セッション内の claude -p がそのセッションの ID を共有しないよう修正されています。以前の挙動が必要な場合は CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 を設定します。
検証できなかった範囲
次の項目は手元で確かめておらず、changelog の記載に基づく説明にとどまります。
- メールアドレス送信前の確認が出る条件と、無人実行での扱い
-
claude -pの exit 1 化（ディスク満杯を再現していません） - auto mode の判定不能の通知の文言と、その後の挙動
- 別モデルのサブエージェントの effort の変化
- SendMessage の到達タイミングの変化
- Grep・Glob の部分結果の扱い
- Agent SDK の
onFailure: "block"の挙動 - セッション内
claude -pの ID 共有の修正とCLAUDE_CODE_DISABLE_NESTED_SESSION_IDの効果