はじめに
対象読者は、Claude Code でサブエージェントやワークフローを動かしていて、コンテキストの膨張・モデルコスト・過負荷エラー（529）に悩んでいる方です。
2026年10月9日に公開された Claude Code v2.1.296 では、サブエージェントまわりの設定が3つ増えました。公式の changelog では1行ずつ書かれているだけなので、「どこに書くのか」「どの設定と競合するのか」を、手元にインストールした v2.1.296 で確認しました。
この記事でわかること
- 3つの新設定がそれぞれ何を変えるのか
- 設定の書き場所（frontmatter と環境変数）
- 競合する既存設定との関係
- 確かめられたことと、確かめられていないこと
3つの新設定の全体像
changelog（v2.1.296）の該当行は次のとおりです。
| 設定 | 種類 | 公式の説明（要約） |
|---|---|---|
autoCompactWindow |
サブエージェントの frontmatter / --agents
|
サブエージェントがメイン会話の窓より早く自動圧縮できる |
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL |
環境変数 | すべてのワークフローエージェントを1つのモデルで動かし、ほかのサブエージェントは各自のモデルのまま |
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS |
環境変数 | 過負荷（529）の再試行で、バックオフの最大待ち時間をより長くできる |
出典は Claude Code changelog の 2.1.296（2026-10-09）です。
手元の v2.1.296 で確かめたこと
確認に使った環境は、Claude Code 2.1.296 です。
$ claude --version
2.1.296 (Claude Code)
実行ファイルの中の文字列を検索して、3つの名前が実在するかを数えました。
$ B=$(readlink -f $(which claude))
$ for k in CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS autoCompactWindow; do
> printf "%s: " $k; grep -a -o "$k" "$B" | wc -l
> done
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL: 10
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS: 3
autoCompactWindow: 108
3つとも実行ファイルに含まれています。これだけでは動作は分かりません。そこで、周辺のコードも読んで、設定の意味を確かめました。この方法は実行ファイルの内部を読むものなので、将来のバージョンで変わる可能性があります。以下の記述は、あくまで 2.1.296 の範囲の観察です。
autoCompactWindow は「下げるだけ」の設定
エージェント定義のスキーマに、次の説明が書かれていました。
autoCompactWindow: 整数（最小 100000・最大 1000000）
Token count at which this agent compacts its own conversation when it runs as a subagent.
It only lowers the window the subagent would otherwise inherit. No effect on the main session agent.
読み取れることは3点です。
- 値は整数で、範囲があります。範囲の数値（10万〜100万）は、スキーマが参照する定数を実行ファイルから読んだ値です。
- 継承する窓を「下げる」ことしかできません。メイン会話より大きい値を指定しても、窓は広がりません。
- メインセッションのエージェントには効きません。
書き方は、エージェントの frontmatter に1行足すだけです。
---
name: log-reader
description: 大きなログを読んで要点だけ返す
model: sonnet
autoCompactWindow: 200000
---
ログを読み、重要な行だけを要約して返してください。
この記述例は、スキーマのフィールド名と型に合わせて書いたものです。実際にサブエージェントを起動して圧縮が走る様子までは、確認していません（後述）。
実行ファイル内のエージェント定義の許可フィールド一覧にも autoCompactWindow が並んでいました。maxTurns と skills の間にあります。
["name","description","prompt","tools","disallowedTools","model","effort",
"permissionMode","mcpServers","hooks","maxTurns","autoCompactWindow","skills",
"initialPrompt","memory","background","omitClaudeMd","isolation"]
changelog には、未知の frontmatter フィールドを --debug で名指しする改善も同じ版で入っています。typo（たとえば autoCompactWindows）に気づきやすくなります。
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL は既存のモデル指定と同じ並びにある
環境変数の定義表で、既存の2つと隣り合って登録されていました。
CLAUDE_CODE_SUBAGENT_MODEL
CLAUDE_CODE_SUBAGENT_MODEL_FORCE
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL
さらに、ワークフローのエージェントが個別にモデルを指定したとき、次の形のメッセージが出る分岐がありました。
Workflow agent model "<指定されたモデル>" ignored: <理由>
理由として、CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL is set と CLAUDE_CODE_SUBAGENT_MODEL_FORCE is on の2種類の文字列が実行ファイルに入っていました。つまり、どちらかが設定されていると、ワークフロー内で個別に指定したモデルは無視される作りです。
使い分けの整理は次のとおりです。
| 目的 | 使う設定 |
|---|---|
| 定義や呼び出しでモデルを指定していないサブエージェントの既定値を決めたい | CLAUDE_CODE_SUBAGENT_MODEL |
| ワークフローのエージェントだけ同じモデルにしたい | CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL |
| すべてのサブエージェントを同じモデルに揃えたい |
CLAUDE_CODE_SUBAGENT_MODEL と CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 の併用 |
公式ドキュメントでは、CLAUDE_CODE_SUBAGENT_MODEL は定義の model や呼び出し時の指定がないエージェントの既定値で、v2.1.251 以降はそれらを上書きしません。全員を揃えるには CLAUDE_CODE_SUBAGENT_MODEL_FORCE の併用が必要です。このリポジトリの運用では、役割ごとにモデルを分けているため、CLAUDE_CODE_SUBAGENT_MODEL をグローバルに置かない方針です（指定のないエージェントが一律で同じモデルになるため）。ワークフロー専用の変数は影響範囲が狭いので、ワークフローだけを安いモデルへ寄せたいときの選択肢になります。なお、CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL と autoCompactWindow は、記事の執筆時点で公式ドキュメントの設定一覧に項目がなく、changelog が唯一の公式根拠です。個別指定が無視されるという読み取りは実行ファイル由来なので、実際に設定して確かめるまでは運用に入れないほうが安全です。
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS は529のときだけ読まれる
再試行の待ち時間を決める箇所を読むと、環境変数は「過負荷（529）と判定された場合」にだけ参照されていました。
過負荷と判定された場合:
最大待ち時間 = CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS
基準待ち時間 = CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS
それ以外:
バックオフ関数の既定の上限（32000 ミリ秒）
待ち時間を計算する関数は、試行回数・基準値・上限・乱数を受け取り、25%の比率のジッター（ばらつき）を付けます。上限の既定引数は 32000 ミリ秒でした。つまり、過負荷のときだけ上限を伸ばせる設定です。ほかのエラーの再試行には影響しません。
近い名前の CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS は、2.1.295 で入った別の設定です。無人リトライモード（CLAUDE_CODE_RETRY_WATCHDOG）が 429 と 529 を待ち続ける時間を制限します。長く待たせたい設定と、待ちすぎを止める設定が別にある点に注意が必要です。
公式ドキュメントによると、CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS（v2.1.296 以降）と基準待ち時間の CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS（500〜32000、v2.1.292 以降）は、CLAUDE_CODE_RETRY_WATCHDOG を 1 にしている場合と、ファストモードで送ったリクエストには効きません。無人リトライモードと組み合わせる場合、この変数は効かない点に注意してください。この点は読者の @Skillselion さんのコメントで教えていただきました。
環境変数を置く場所
2つの環境変数は、シェルで export するほか、プロジェクトの .claude/settings.json の env に書く方法もあります。チームで同じ設定を共有したいときは、こちらがバージョン管理に載せやすい置き場所です。
{
"env": {
"CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL": "sonnet",
"CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS": "64000"
}
}
値の sonnet と 64000 は書き方の例です。推奨値ではありません。CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS は公式ドキュメントの環境変数一覧に項目があり、有効な値は 32000〜64000 ミリ秒の整数（数字のみ）です。範囲外の値は未設定として扱われるため、上限は既定の 32000 のままになります。モデル名は、使っているプロバイダーで通る指定にそろえてください。
確かめられていないこと
次の3点は、今回の確認範囲に含まれていません。
-
圧縮が実際に走る挙動:
autoCompactWindowを指定したサブエージェントを起動し、圧縮が走るタイミングは確認していません。 - 環境変数どうしの優先順位: 文字列と分岐から読み取れる範囲で、実際に設定して動かしてはいません。
- 529 の実環境での待ち時間: 過負荷を再現できないため、再試行間隔の実測はしていません。
この環境ではモデル API を新たに呼ぶ検証を行わず、実行ファイルの内容と公式 changelog の突き合わせだけにとどめました。
どれから試すか
優先順位をつけるなら、次の順です。
- autoCompactWindow: 大量のファイルを読むサブエージェントが1つあるなら、そのエージェントの frontmatter に1行足すだけです。メインには影響しないので、試す際の失敗コストが小さい設定です。
- WORKFLOW_SUBAGENT_MODEL: ワークフローを使っていて、モデルのコストを下げたいときに検討します。
- OVERLOADED_RETRY_MAX_DELAY_MS: 無人運用で529に当たって止まることがある場合だけ、最大待ち時間を伸ばします。
著者視点の発見ポイント
changelog は1行ずつ要約されており、「下げるだけ」「529のときだけ」のような制約が書かれていませんでした。スキーマの説明文と分岐を読むと、この2点が分かります。設定名だけで判断すると、autoCompactWindow を大きくして窓を広げられると誤解しやすい設定です。
まとめ
- v2.1.296 で、サブエージェントの圧縮窓・ワークフロー専用のモデル・529 の最大待ち時間が設定できるようになった
-
autoCompactWindowは継承した窓を下げるだけで、メインには効かない - ワークフロー専用のモデル変数は、既存の全体指定・強制指定と並ぶ別の設定
- 過負荷の最大待ち時間は 529 のときだけ参照される
- 実際の動作は未確認で、導入前に自分の環境で確かめる必要がある
関連記事
- Claude Code v2.1.129-136 新機能解説 — plugin-url・project purge・effortフック
- Claude Code Agent View入門 — 複数セッションを1画面で管理するCLIダッシュボード
- Claude Code Dynamic Workflows入門 — 並列サブエージェントで大規模タスクを自動化する