Claude Codeのサブエージェント、禁止→解禁を1週間で繰り返した理由
Claude Codeはサブエージェントの同時実行を20体に制限した4日後、ネストの入れ子生成を既定で禁止し、さらに3日後には深さ3まで既定で解禁した。7月17日〜24日の3リリースを時系列で追い、暴走コストの正体とCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS等の実務での調整方法を解説する。
エンジニアのゆとです。
結論から言う。Claude Codeのサブエージェントのネスト機能（サブエージェントがさらにサブエージェントを呼ぶ機能）は、2026年7月17日から24日までのわずか1週間で「利用量に上限をつける→ネストを完全に禁止する→深さ3までのネストを既定で解禁する」という三段階の変更を経験してる。バージョンで言うと2.1.212→2.1.217→2.1.219の3リリース分。
普段チェンジログを見る時って、大体は直近1本だけ見て「へえ新機能追加されたのか」で終わる。でもこの3本は繋げて読むと違う顔を見せる。Anthropicは一度「ネスト禁止」まで踏み込んで、3日後に「深さ3までならOK」と部分的に撤回してる。単なる機能追加の羅列じゃなくて、方針が揺れた記録。この記事はその経緯を時系列で並べて、実務でどう構えればいいかまで書く。
タイムラインで追う3つのリリース
まず事実を並べる。公式チェンジログ（code.claude.com/docs/en/changelog）に載ってる内容そのまま。
| バージョン | 日付 | 変更内容 |
|---|---|---|
| 2.1.212 | 7月17日 | セッション単位でWeb検索200回・サブエージェント生成200回の上限を追加 |
| 2.1.217 | 7月21日 | 同時実行サブエージェントを20体に上限設定、ネスト生成を既定で禁止に変更 |
| 2.1.219 | 7月24日 | ネストを既定で復活、深さ3まで許可（禁止前の既定は深さ1） |
順番に見ていく。
7月17日の2.1.212は、まだ「上限をつけ始めた」段階。セッション単位でWebSearchツールの呼び出し数に上限（既定200回、CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSIONで変更可）を追加、同時にセッション単位でサブエージェントの生成数にも上限（既定200回、CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSIONで変更可）を追加してる。/clearを打つとこの予算はリセットされる。この時点ではまだネストそのものは制限してない。「暴走したループを止める」という説明がついてるのがポイントで、Web検索やサブエージェント生成が制御不能に増えるケースが実際にあったからこその対応だと読める。
4日後の7月21日、2.1.217でグッと踏み込む。同時に走るサブエージェントの数に上限（既定20体、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変更可）を追加したのに加えて、サブエージェントが既定でネスト（入れ子の）サブエージェントを生成しなくなるよう変更した。つまりサブエージェントがさらに別のサブエージェントを呼ぶ、という多段構成が既定オフになった。同じリリースで「—max-budget-usdが背景で動くサブエージェントを止めきれてなかった」バグも直してる。予算の天井に達したら新規生成を拒否して、動いてる背景エージェントも止める、という挙動に変わった。ここまで見ると、Anthropicは「サブエージェントが増えすぎてコストや負荷が制御しにくくなる」問題に対して、かなり強めのブレーキを踏んだことになる。
さらに3日後の7月24日、2.1.219でネストが戻ってくる。サブエージェントは既定で深さ3までネストしたサブエージェントを生成できるようになった（禁止前の既定は1）。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1でネストを無効化できる、という記述。同じリリースでstream-json出力に「深さ2以降で生成されたサブエージェントのテキストを転送する」機能も追加されてる。ネスト自体が復活しただけじゃなくて、深いネストで何が起きてるかを観測できるようにする機能まで足された。禁止した4日後には次善の落としどころを用意していた、というスピード感。
なぜ一度は「完全禁止」までいったのか
3リリースを続けて読むと、Anthropic側の動きが透けて見える。7/17の「利用回数の上限」だけでは足りなかった、というのが素直な解釈だと思う。回数に天井をつけても、1回のメッセージで大量のサブエージェントを同時に立ち上げて、しかもそれぞれがさらに孫エージェントを生成する、みたいな使い方をされると、同時実行数もコストも制御できない。だから4日後に同時実行数の上限（20体）を追加して、さらにネストという「増殖の経路」そのものを一旦断つ判断をした。
これ、正直かなり強い対応だと思う。機能を段階的に絞るんじゃなくて、既定オフまで持っていってる。それだけ「ネストしたサブエージェントが暴走してコストや負荷を食い荒らすケース」が無視できない頻度で起きてたんだろうなという推測ができる。深いネストって書いてる本人も全体像を把握しづらくて、気づいたら子・孫・ひ孫エージェントが並列で動いてAPIコールを食ってた、というのは普通に起こりうる話だと思う。
そのうえで3日で「深さ3までなら」に落ち着いたのは、完全禁止だと正当な用途（後述する監査系タスクとか）まで巻き込んでしまうから、程よい上限を探った結果だと思う。深さ1（実質禁止）と無制限の間に、深さ3という具体的な線を引いた。
深さ3のネストは実際どう動くか
言葉だとイメージしづらいので具体例で。深さ1はメインのセッションが1個のサブエージェントを呼ぶところまで（サブエージェント自身は誰も呼べない）。深さ3になると、メインセッションがサブエージェントAを呼び、Aがサブエージェントdeep-diveBを呼び、Bがさらにサブエージェントdeep-diveCを呼べる、という3階層構成が既定で許可される。
僕が実際に使う場面で言うと、大規模リファクタリングの監査タスクがこれに近い。メインで「全モジュールの型安全性を監査して」と投げると、そのサブエージェントが「このディレクトリだけ深掘りして」と別のサブエージェントに投げて、さらにそのサブエージェントが「このファイルのこの関数だけ確認して」ともう一段掘る、みたいな階層。これが深さ3で表現できる範囲。逆に単純なコードレビューや1ファイルの修正なら、ネストは1段あれば十分で、深さ3を使う理由がそもそもない。
上限を自分で確認・調整する方法
今のバージョンでどう設定されてるかは環境変数を見れば分かる。ターミナルで以下を叩く。
echo $CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
echo $CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH
echo $CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION何も出力されなければ既定値（同時実行20体、ネスト深さ3、セッション生成上限200回）が使われてる。変更したい場合はシェルの設定ファイル（.zshrcとか）か、Claude Code起動時の環境変数として渡す。
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=10
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1深いネストを使う予定がない案件では、僕は深さを1に落として運用してる。理由は単純で、ネストが深くなるほど「今何が動いてるか」を目で追うのが難しくなるから。逆に大規模監査みたいに階層的な深掘りが要る作業だけ、一時的に既定の3のまま使う、という切り替えでいい。
フリーランスの実務でどう向き合うべきか
1人運営でClaude Codeのサブエージェントを使う場合、この上限は制約というより防波堤として捉えた方がいい。同時実行20体、ネスト深さ3という数字は、普通に使ってる分には天井にぶつからない。ぶつかるのは、大規模なリファクタや全文監査タスクをサブエージェント任せで並列に投げまくった時。
worktree isolationを組み合わせて並列実行してる人は特に注意した方がいい。ファイルの競合は防げても、同時に走るサブエージェントの数とネストの深さは別の上限で管理されてるから、両方を意識しないと「同時実行数の上限に引っかかって一部のタスクだけ止まる」みたいな事象に遭遇する。
しかもサブエージェントを並列で投げまくると、この上限とは別に使用量制限そのものにも早く近づく。同時実行数の天井とセッションの使用量、両方が別軸で効いてくることは覚えておいた方がいい。
正直、この1週間の変遷を見て思うのは、Anthropic側も「どこまで自由にサブエージェントを増殖させていいか」の正解をまだ探ってる最中ってこと。だからこそ、既定値に依存しきらずに、自分のタスクの規模に応じて環境変数を都度見直す習慣をつけておくのが一番安全だと思う。
