Claude Code v2.1.317 の主要アップデート - 別モデルのサブエージェントの effort 変更と Read のスタブ削除
クラウド事業統括本部の石川です。Claude Code の v2.1.317（2026-11-02 公開）がリリースされました。今回は、別モデルで動くサブエージェントの effort の変更と、Read ツールのスタブの削除を中心に取り上げます。本日は、別モデルのサブエージェントの effort を試してみました。
前回のアップデート記事はこちらです。
アップデートサマリー
v2.1.317 では 87 件の変更が入りました。CHANGELOG の記載では、修正（Fixed）が 62 件、追加（Added）が 10 件、改善（Improved）が 8 件、変更（Changed）が 6 件、削除（Removed）が 1 件です。本記事では、このうち権限・確認・失敗時の扱いに関わる 7 件をセキュリティとしてまとめ、既存の使い方に影響する 3 件を破壊的変更・非推奨として扱います。セルフホストランナー（9 件）、VS Code 拡張（7 件）、Claude apps gateway（5 件）、クラウドセッション（4 件）を対象とした変更も含まれます。
また、公式Xの投稿によると、Message threads （パブリックベータ）で提供されました。
Message threadsとは、Messages APIで会話履歴を毎ターン送り直さずに済む新機能です。threadパラメータを付けた初回リクエストで全履歴を送ってスレッドを開始し、以降は新しいメッセージと直前のレスポンスIDだけを送ります。スレッドはディスクに書き込まれず暗号化された状態でメモリに保持され、最後のリクエストから5分で失効します。Claudeは毎回全文を読むためトークン消費は変わりませんが、応答開始までの時間が短縮されます。これによって、50万〜100万トークンで中央値約35%減されるという仕組みです。長時間動くコーディングエージェントやComputer Useに向いています。
注目のアップデート
アカウントのメールアドレスをネットワークに送る前の確認を追加
Web ツールまたはシェルツールの呼び出しがアカウントのメールアドレスをネットワークに送信する前に、確認を求めるチェックが追加されました。
なお、v2.1.234 の CHANGELOG には、Claude がアカウントのメールアドレスをユーザーの識別にのみ使い、依頼がない限り無関係なサービスに送らないよう指示されるようになったと記載されています。今回追加されたのは、ツールの呼び出しがメールアドレスを送信する前に確認を求めるチェックです。
Web ツールやシェルツールに外部へのアクセスを任せることが多い方は、アカウントのメールアドレスが送られる前に確認が入るため、意図しない送信に気付きやすくなると感じます。
Agent SDK のフックコールバックに onFailure: "block" を追加
Agent SDK のフックコールバックに onFailure: "block" が追加されました。コールバックが失敗した場合に、アクションをそのまま実行させる代わりにブロックします。
onFailure: "block" は、v2.1.295 で command フックと HTTP フックに追加されています（起動できない、タイムアウトする、想定外の終了コードで終了するフックが、アクションを通さずにブロックします）。v2.1.317 では、Agent SDK のフックコールバックでも指定できるようになりました。指定しない場合の挙動は、CHANGELOG の「instead of letting it run」という記述から、失敗したコールバックがあってもアクションが実行されると推測します。
Agent SDK のフックで権限チェックや監査を実装している方は、失敗したときに処理を止めたいフックに onFailure: "block" を指定しておくと良いと考えます。
別モデルのサブエージェントが、そのモデルの保存済み effort で動くよう変更
メインの会話と異なるモデルで動くサブエージェントとチームメイトが、セッションの effort レベルではなく、そのモデルの保存済みの effort レベル、またはそのモデルの既定値を使うよう変更されました。
公式ドキュメントでは、Claude Code は effort レベルをモデルごとに、ユーザー設定の modelSettings キーへ保存すると説明されています。モデルの既定の effort は、effort に対応するモデルでは high、Opus 5.5・Sonnet 5.5・Haiku 5.5 では medium、Opus 4.7 では xhigh です。変更前後の挙動は後述の「破壊的変更・非推奨」で整理し、実際の挙動は「試してみた」で確認します。
メインを高い effort で動かしつつ Sonnet や Haiku のサブエージェントを使っている方は、サブエージェントの effort が変わる可能性があるため、そのモデルの保存済み effort を確認しておくと良いと感じます。
Read ツールの "file unchanged since your last Read" スタブを削除
Read ツールの "file unchanged since your last Read" スタブが削除されました。変更されていないファイルを再度読み込むと、そのファイルの内容が返されます。
同じファイルを何度も読み直す長い作業では、再読み込みのたびに内容が返るため、コンテキストの消費量が以前より増える可能性があると見ています。
セッション内の claude -p がセッション ID を共有する問題の修正と CLAUDE_CODE_DISABLE_NESTED_SESSION_ID の追加
クラウドまたはセルフホストランナーのセッション内で実行した claude -p が、そのセッションの ID を共有する問題が修正されました。これまでは、claude -p がセッションのトランスクリプトに書き込み、再起動時に別の会話が再開される場合がありました。同じ条件の claude -p が独自のタイトルを生成してセッションに送る問題も修正されています。
あわせて、環境変数 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID が追加されました。セルフホストランナーで 1 を設定すると、セッション内で実行した claude -p が、以前のバージョンと同様にそのセッションの ID とトランスクリプトを使います。
セルフホストランナーのセッション内で claude -p を呼び出している方は、セッション ID の扱いが変わるため、CLAUDE_CODE_DISABLE_NESTED_SESSION_ID の要否を確認しておくのが安全だと考えます。
Claude apps gateway の管理 API にコストレポートを追加
Claude apps gateway の管理 API にコストレポート GET /v1/organizations/analytics/cost が追加されました。日付範囲を指定して、過去の支出を合計・開発者別・日別・IdP グループ別に読み取れます。
IdP グループ別の集計には、同じく追加された IdP グループの日次記録が使われます。admin: を設定した Claude apps gateway で各開発者の IdP グループが日ごとに記録され、admin.identity_retention_days の期間保持されます。
Claude apps gateway で開発者の利用料を管理している組織は、IdP グループ別に過去の支出を読み取れるため、グループ単位の費用把握に使えるのではと考えます。
アップデート内容
新機能
- Claude Desktop の Code タブにリモート管理設定の読み込み状況の通知を追加: 組織のリモート管理設定（remote managed settings）がセッションに読み込まれていない場合に通知が表示され、読み込まれた時点でも通知が表示されます。
- auto mode のチェックが回答を返さなかった場合の通知を追加: サブエージェントのツール呼び出しに auto mode のチェックが回答を返さなかった場合に通知が表示されます。これまではメインの画面に何も表示されていませんでした。
- OTel のメトリクス・イベント・スパンに属性を追加:
anthropic.plan、anthropic.seat_type、anthropic.provider、anthropic.custom_base_urlが追加されました。 - Claude apps gateway の管理 API にコストレポートを追加:
GET /v1/organizations/analytics/costで、日付範囲を指定して過去の支出を合計・開発者別・日別・IdP グループ別に読み取れます。 - Claude apps gateway に開発者の IdP グループの日次記録を追加:
admin:を設定した Claude apps gateway で記録され、admin.identity_retention_daysの期間保持されます。コストレポートの IdP グループ別の集計に使われます。 - 環境変数
CLAUDE_CODE_DISABLE_NESTED_SESSION_IDを追加: セルフホストランナーで1を設定すると、セッション内で実行したclaude -pが、以前のバージョンと同様にそのセッションの ID とトランスクリプトを使います（後述の「破壊的変更・非推奨」でも扱います）。 - [Cloud sessions] リンクカードを追加: MCP サーバーが開くよう求めるリンクを、開くか辞退するかを選べます。リクエストが表示されないままになることがなくなります。
セキュリティ
- アカウントのメールアドレスをネットワークに送る前の確認を追加: Web ツールまたはシェルツールの呼び出しがアカウントのメールアドレスをネットワークに送信する前に、確認を求めます。
- Agent SDK のフックコールバックに
onFailure: "block"を追加: コールバックが失敗した場合に、アクションをそのまま実行させる代わりにブロックします。 /scheduleに依頼していないコネクタの警告を追加: 新しいクラウドのスケジュールタスクに、依頼していないコネクタが付与された場合に警告が表示されます。警告には削除方法も示されます。- 同時に表示された 2 つ目の権限プロンプトに情報が表示されない問題を修正: claude.ai とモバイルアプリで、同時に表示された 2 つの権限プロンプトのうち 2 つ目に、ファイルパスやコマンドが表示されていませんでした。
- mod のツール呼び出しに「don't ask again」が提示される問題を修正: Remote Control と SDK のホストで発生していました。
- エージェントチームのチームメイトが auto mode で起動する問題を修正: リードセッションが manual モードのときに、tmux や iTerm2 のペインで動くチームメイトが auto mode で起動していました。
- バックグラウンドセッションで権限モードの変更が失われる問題を修正: バックグラウンドセッションがアップグレードまたは終了されるときに、直前に変更した権限モードが失われることがありました。
改善・開発者体験
- SendMessage を変更: 実行中のバックグラウンドエージェントへのメッセージがより早く届きます。実行中のコマンドは停止されずにバックグラウンドへ移ります。
- 終了時の "Resume this session with" のヒントを改善: 起動時に指定したフラグ（例:
--chrome --debug）を--resumeの前に含めて表示します。 - Microsoft Foundry で Azure の認証情報を読み込めない場合のエラーを改善: 認証情報の確認・更新を促し、
cloud_credential_errorとして報告します。 - 必須の Claude apps gateway に接続できない場合の起動時のエラーを改善: サインインではなくネットワークを示し、ゲートウェイの TLS 証明書を検証できない場合はその旨を伝えます。
/design-syncを改善: デザインシステムが Claude に移行済みの場合は最初にその旨を伝え、アップロード時に失敗する代わりにビルド前に停止します。- プラグインのモニターの終了時のプロンプトを変更: プラグインのモニターについては、終了時に "Background work is running" プロンプトを表示しません。
- 組み込みの
plugin-authoringスキルを変更: 作成した mod が動作した後に、mod の共有を手伝うことを 1 回だけ提案します。 - Remote Control のフォーク名を改善: アプリがフォーク名を設定しない場合に、長い名前でも "(fork)" の末尾が残り、
claude remote-controlで開始したセッションでは "Name (fork)" のフォークが "Name (fork 2)" になります。 - [Cloud sessions] 管理者設定の組織環境ダイアログを変更: 個人用のダイアログと同じ短いレイアウトになり、各セクションは行から開き、未保存の入力がある場合は閉じる前に確認されます。
- [Claude Tag] Slack に新しく貼り付けたアーティファクトのリンクを変更: Slack のサイドパネルではなく、Claude でアーティファクトを開く Open ボタン付きのシンプルなカードで表示されます。
- セルフホストランナーのサーバーエラーと無応答の接続からの復旧を改善: 501・529 以外の 5xx の後、ランナーの次のポーリングとセッションは、失敗した接続を再利用せず新しい接続を開きます。セッションはハートビートに応答がない場合も、アイドル状態の接続を順に試す代わりに新しい接続を開きます。
修正
claude -pがディスクの容量不足時に終了コード 0 で終わる問題を修正: ディスクの空き容量不足やクォータによってトランスクリプトや~/.claude.jsonの書き込みが失われたときに、終了コード 0 で終了していました。修正後はエラーを表示し、text と json の出力形式では終了コード 1 で終了します。容量がいっぱいの NFS エクスポートは検出されない場合があります。claude auth statusがトークン更新の保存前に終了する問題を修正: 時間のかかるトークン更新の保存前に終了し、次回の実行でサインアウトされる場合がありました。- Claude Desktop で MCP サーバーが最初のターンの後に切断される問題を修正: 一部の Claude Desktop のセッションで、プロジェクトとローカルの MCP サーバーが切断されていました。
- Grep・Glob の部分的な結果を完全な結果として扱う問題を修正: 検索が時間制限に達した場合に、Claude が部分的な結果を完全な結果として扱っていました。
- 大きな CLAUDE.md の変更後に "Prompt is too long" になる問題を修正: 非常に大きな CLAUDE.md が前回の送信時から変更されたセッションで、自動コンパクションの後に発生していました。
- TLS 検査プロキシの背後で証明書エラーになる問題を修正: ルート証明書の更新後、一部の TLS 検査プロキシの背後で、API リクエストが "unable to get local issuer certificate" で失敗していました。
- stdio MCP サーバーに空の
AWS_BEARER_TOKEN_BEDROCKが渡される問題を修正: env 設定で空に設定した場合に、空の値が渡されていました。修正後は変数が設定されない状態になり、サーバーはマシン自身の AWS 認証情報を使えます。 - Claude apps gateway が Amazon Bedrock の "Input is too long." エラーを隠す問題を修正: セッションがコンパクションせずに "upstream rejected the request" で毎ターン失敗していました。
- 地味に嬉しい修正: プロンプトに入力したテキストを消すために Ctrl+C を押すと、実行中のバックグラウンドエージェントがすべて停止する問題が修正されました。バックグラウンドでエージェントを動かしながらプロンプトを書き直すことが多い方には、嬉しい修正だと感じます。
- このほか、プロキシ経由の OpenTelemetry のエクスポート、セルフホストランナーとクラウドセッション、エージェントチームとスケジュールタスク、Windows のパス、VS Code 拡張など、多数の細かな不具合が修正されています。
破壊的変更・非推奨
CHANGELOG で破壊的変更と明記された項目はありませんが、本記事では既存の使い方に影響する次の 3 件を扱います。以下の変更前・変更後は、いずれも CHANGELOG の記述から構成した例です。
Read ツールの "file unchanged since your last Read" スタブの削除
変更のないファイルを 2 回続けて Read したときの例です。
変更前（〜v2.1.316）:
Read file.txt → ファイルの内容
（file.txt を変更しないまま）
Read file.txt → "file unchanged since your last Read" のスタブ
変更後（v2.1.317〜）:
Read file.txt → ファイルの内容
（file.txt を変更しないまま）
Read file.txt → ファイルの内容
セッション内の claude -p がセッション ID を共有しなくなった
クラウドまたはセルフホストランナーのセッション内で claude -p を実行したときの例です。CLAUDE_CODE_DISABLE_NESTED_SESSION_ID は、CHANGELOG ではセルフホストランナーで設定するものとして記載されており、クラウドセッションでの扱いは記載がありません。
変更前（〜v2.1.316）:
セッション内で claude -p を実行
→ そのセッションの ID を共有し、セッションのトランスクリプトに書き込む
→ 再起動時に別の会話が再開される場合がある
変更後（v2.1.317〜）:
セッション内で claude -p を実行
→ そのセッションの ID を共有しないセルフホストランナーで以前の挙動に戻す場合
→ CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 を設定する
別モデルのサブエージェント・チームメイトの effort
メインの会話を Opus 5.5・effort high で動かし、model: sonnet のサブエージェントを起動したときの例です。変更前の挙動は、CHANGELOG の「instead of the session's effort level」という記述からの推測です。変更後の挙動のうち、Sonnet の effort を保存していない場合は、後述の「試してみた」で確認しています。
変更前（〜v2.1.316、推測）:
model: sonnet のサブエージェント → セッションの effort（high）
変更後（v2.1.317〜）:
model: sonnet のサブエージェント → Sonnet の保存済み effort
保存がなければそのモデルの既定値
（今回の環境では Sonnet 5.5 の medium）
別モデルのサブエージェントの effort を試してみた
先日のアップデート（v2.1.316）でも同様の検証をしましたが、v2.1.317 では、アップデートに伴い以下の検証も実施しました。
- モデル名（message.model）も集計し、Sonnet で動いたことを確かめた
- Agent ツールの呼び出しに model と effort が渡っていないことを確かめた
- 現在のセッションから引き継がれる CLAUDE_EFFORT=xhigh などの環境変数を外して実行した
v2.1.317 で変更された、メインの会話と異なるモデルで動くサブエージェントの effort を、メインと同じモデルで動くサブエージェントと比べて確認しました。
検証の方法
以降のコマンドでは、検証用ディレクトリの絶対パスをシェル変数 V に入れて使います。今回の検証では、Claude Code のセッション用の一時ディレクトリの下に作ったディレクトリを用意します。
# 例: 検証用の空ディレクトリを作成し、そのパスを V に入れる
% V="$(mktemp -d)"
% mkdir -p $V/work
% cd $V/work
検証の条件は次のとおりです。
--model opus --effort highで、メインの会話を Opus 5.5・efforthighにする--agentsで、メインと同じモデルで動くprobe-same（model: inherit）と、Sonnet で動くprobe-sonnet（model: sonnet）の 2 つのサブエージェントを定義する--tools Agentで使えるツールを Agent だけにし、--strict-mcp-configで MCP サーバーを読み込まない- プロンプトで、Agent ツールの
modelとeffortのパラメータを指定しないよう伝える - 今回の環境では、ユーザー設定の
modelSettingsに Sonnet の effort は保存されていません（ユーザー設定のeffortLevelはxhighですが、--effort highでセッションの effort をhighにしています） - 環境変数
CLAUDE_CODE_EFFORT_LEVELとCLAUDE_CODE_SUBAGENT_EFFORTは設定していません
なお、今回は Claude Code のセッション内からコマンドを実行したため、セッションから引き継がれる環境変数（CLAUDECODE、CLAUDE_CODE_CHILD_SESSION、CLAUDE_CODE_SESSION_ID、CLAUDE_EFFORT、CLAUDE_CODE_MESSAGING_SOCKET、CLAUDE_CODE_MESSAGING_TOKEN、CLAUDE_PID、CLAUDE_CODE_SESSION_ATTENDED）を unset したサブシェルで、以降の claude コマンドを実行しています。ターミナルから直接実行する場合、この操作は不要です。
% AGENTS='{"probe-same":{"description":"Probe agent that runs on the main conversation model","prompt":"Reply with only: ok","model":"inherit"},"probe-sonnet":{"description":"Probe agent that runs on Sonnet","prompt":"Reply with only: ok","model":"sonnet"}}'
メインと同じモデルのサブエージェント（runA）
% claude -p --max-turns 1 --model opus --effort high --tools Agent --strict-mcp-config \
--agents "$AGENTS" --output-format stream-json --verbose \
"Agent ツールで probe-same サブエージェントを 1 つ起動してください。model と effort のパラメータは指定しないでください" > $V/runA.jsonl
Sonnet のサブエージェント（runB）
% claude -p --max-turns 1 --model opus --effort high --tools Agent --strict-mcp-config \
--agents "$AGENTS" --output-format stream-json --verbose \
"Agent ツールで probe-sonnet サブエージェントを 1 つ起動してください。model と effort のパラメータは指定しないでください" > $V/runB.jsonl
結果の確認
まず、Claude が Agent ツールを呼び出すときに model と effort のパラメータを渡していないことを確認しました。
% for r in runA runB; do
jq -c 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Agent") | .input | {subagent_type, model, effort}' $V/$r.jsonl
done
{"subagent_type":"probe-same","model":null,"effort":null}
{"subagent_type":"probe-sonnet","model":null,"effort":null}
effort は、Claude Code が自動で保存するセッション記録（JSONL）で確認しました。今回の環境では、メインのセッションの記録は ~/.claude/projects/<作業ディレクトリに対応するディレクトリ>/<セッション ID>.jsonl に、サブエージェントの記録は同じ場所の <セッション ID>/subagents/agent-*.jsonl に保存されていました。各記録の assistant レコードにある message.model と effort の値を集計します。
% P=~/.claude/projects/<作業ディレクトリに対応するディレクトリ>
% for r in runA runB; do
SID=$(jq -r 'select(.type=="system" and .subtype=="init") | .session_id' $V/$r.jsonl | head -1)
echo "== $r"
echo "main:"; jq -r 'select(.type=="assistant") | "\(.message.model) \(.effort)"' "$P/$SID.jsonl" | sort | uniq -c
echo "subagent:"; jq -r 'select(.type=="assistant") | "\(.message.model) \(.effort)"' "$P/$SID"/subagents/agent-*.jsonl | sort | uniq -c
done
== runA
main:
3 claude-opus-5-5 high
subagent:
2 claude-opus-5-5 high
== runB
main:
3 claude-opus-5-5 high
subagent:
1 claude-sonnet-5-5 medium
数字は、各記録の assistant レコードのうち、そのモデルと effort の組み合わせを持つものの件数です。
- メインと同じモデルのサブエージェント（runA）は、セッション記録では、メインの会話と同じ
claude-opus-5-5のhighで動作していました。 - Sonnet のサブエージェント（runB）は、セッション記録では、メインの会話が
highのまま、claude-sonnet-5-5のmediumで動作していました。Sonnet の effort を保存していない環境のため、公式ドキュメントにある Sonnet 5.5 の既定値（medium）と一致します。
どちらの実行も終了コードは 0 でした。stream-json の結果イベントは次のとおりで、各実行とも 1 つ目は --max-turns 1 の上限に達したことを示す error_max_turns、2 つ目は success でした。
% for r in runA runB; do jq -c 'select(.type=="result") | {subtype, terminal_reason}' $V/$r.jsonl; done
{"subtype":"error_max_turns","terminal_reason":"max_turns"}
{"subtype":"success","terminal_reason":"completed"}
{"subtype":"error_max_turns","terminal_reason":"max_turns"}
{"subtype":"success","terminal_reason":"completed"}
今回確認したのは v2.1.317 での挙動のみで、旧バージョンとの比較はしていません。また、CLAUDE_CODE_SUBAGENT_EFFORT やサブエージェント定義の effort フィールドと組み合わせた場合、Haiku のサブエージェント、チームメイトの挙動は確認していません。
メインは Opus 5.5 の high のまま、Sonnet のサブエージェントは Sonnet 5.5 の既定値の medium で動いていました。メインの effort に引きずられず、モデルごとの既定値で動くようになったのは嬉しい変更だと感じます。
最後に
v2.1.317 は、別モデルのサブエージェントの effort、Read の再読み込み、ランナー内の claude -p のセッション ID と、既存の使い方に影響する挙動変更が 3 件入ったバージョンだと感じます。あわせて、メールアドレス送信前の確認や Agent SDK のフックの onFailure: "block" など、安全側に倒す変更も入っています。
別モデルのサブエージェントを使っている方や、セルフホストランナーを運用している方は、アップデートして試してみてはいかがでしょうか。
参考文献
