Claude Code 2.1.219 で、サブエージェントが自分のサブエージェントを深さ3まで生成できるようになった。従来は1段どまりで、下請けの下請けは作れなかった。段数が1つ増えると、走りうるエージェントの本数は掛け算で増える。トークンの請求も同じ増え方をする。
目次
2.1.219 で変わった1行
2026年7月24日のリリースで、ネストの上限が既定で深さ3になった。3日前の 2.1.217（7月21日）では、ネストは一度「既定では生やさない」に倒されている。2.1.219 はそれを深さ3で開け直した形だ。公式 changelog の該当行はこう書かれている。
Subagents can now spawn nested subagents up to depth 3 by default (was 1); set
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1to disable nesting
戻し方も同じ行に書いてある。環境変数を1つ置けば従来の挙動になる。
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1同じ版には sandbox.network.strictAllowlist（サンドボックスで走らせるコマンドについて、許可リスト外のホストを確認を出さずに拒否する設定）と、動的ワークフローのサイズガイドライン用の設定キー workflowSizeGuideline も入っている。筆者はこの2つをネストの解禁と並べて読んだ。走らせっぱなしのエージェントが増える版で、外向き通信と生成物の大きさを縛る口が同時に増えている。開発側の意図までは分からないので、あくまで筆者の読み方として書いておく。
もう1つ、深さ2以降のサブエージェントの出力を stream-json へ流す仕組みが同版に入った。--forward-subagent-text を付けると、どの Agent ツール呼び出しから生えた出力かを紐づけた形で流れてくる。headless の stream-json 出力が前提なので、通常の対話画面では見えない。多段の中身を機械的に追う手段が用意されたことは、後で述べる計測にも効いてくる。
深さの数え方と、本数の増え方
本数を数える前に、段の数え方を決めておく。ここではメインの会話を0段目、そこから起動した最初のサブエージェントを1段目と数える。changelog が深さ2以降のサブエージェントを「depth-2+」と呼んでいるので、この数え方で合う。
1本のエージェントが下請けを b 本呼ぶとすると、走りうる本数の上限は b + b² + b³ になる。
| 1段あたりの分岐 | 深さ1（従来） | 深さ2 | 深さ3 |
|---|---|---|---|
| 2本 | 2 | 6 | 14 |
| 3本 | 3 | 12 | 39 |
| 4本 | 4 | 20 | 84 |
掛け算をしただけの上限値なので、実際にここまで伸びる保証はない。全部の枝が最大まで開くわけではないし、下請けが短い調べもので終わるなら消費も小さい。それでも「3本ずつ呼ぶ」という素朴な組み方で、深さ3では理屈のうえで39本が動きうる。1本あたりのコンテキストが数万トークンなら、合計がどこへ向かうかは想像がつく。
Claude Code には1セッションあたりの起動数に別の上限があって、既定は200だ（2.1.212・7月17日で入った per-session cap。/clear で戻る）。上限200を調べたときに、この200はネスト・フォーク・バックグラウンドを含む数え方だと書いた。深さを解放するなら、この起動数のほうが最後の歯止めになる。
筆者の編集部は今のところ直列で回っている
手元には記事づくりを分担させるサブエージェントの並びがある。記者が下書きを書き、校閲が数字と表記を当たり、SEO 係が内部リンクと meta を見る。呼び出しは直列で、前の成果物を次へ渡していく形だ。
ネストが効くようになると、この分け方を記者の内側へ持ち込める。記者が「価格表を組み立てる係」と「一次ソースの日付を突き合わせる係」を自分で呼ぶ、といった形になる。工程を手前で増やさずに、記者の判断で必要なときだけ下請けが立つ。
面白そうではあるが、まだ既定のまま解放していない。呼ぶかどうかの判断がモデル側へ移るので、同じ入力でも実行のたびに本数が変わる。原稿1本あたりの費用が読めなくなるのが1点。もう1点は、下請けの下請けが落ちたときに、どの段で何が起きたのかが上まで届きにくいこと。直列なら落ちた工程がそのまま分かる。ここは stream-json の転送で部分的に埋まりそうなので、計測のときに一緒に確かめる。
測る前に条件を固める
入れるかどうかを体感で決めたくないので、比べる項目と条件を先に決めた。同じ記事1本を書かせる作業を深さ1・深さ2・深さ3の3条件で回す。深さ2を入れるのは、採否の落とし所が「記者の内側に1段だけ許す」＝深さ2になるからで、そこのデータが無いと結論が出せない。
入力も先に固定しておく。書かせるのは trends 記事1本ぶんの下書きで、渡すのは週次の候補データから1件と、参照素材として既存記事2本。エージェントに読ませる規約ファイルは計測開始時点のコミットのものを使い、モデルは既定任せにせずモデル ID で固定する。表を埋めるときは、このとき使った入力一式と実行ログのモデル ID を併記する。入力が違えば、深さ3で消費が倍になった理由が段数なのか題材なのかを切り分けられない。
| 計測項目 | 取り方 | 深さ1 | 深さ2 | 深さ3 |
|---|---|---|---|---|
| 総トークン消費 | /usage の内訳を実行の前後で差分 |
未実測 | 未実測 | 未実測 |
| 起動された本数 | headless 実行の stream-json を --forward-subagent-text 付きで取り、Agent ツール呼び出しの id ごとに数える |
未実測 | 未実測 | 未実測 |
| 完走率 | 同一入力で5回走らせ、成果物が最後まで返った回数 | 未実測 | 未実測 | 未実測 |
| 所要時間 | 開始から成果物が揃うまでの実時間 | 未実測 | 未実測 | 未実測 |
条件をここまで決めたうえで、今回は走らせないことにした。3条件×5回で15本の原稿を書かせることになる。筆者の編集部は1本あたり5部署が動いて上限90分まで待つ作りなので、15本ぶんの実行時間と課金が、この記事1本で分かることに見合わない。
表の右3列は空けたままにしてある。見込みの数字で埋めると、あとで本当に測ったときに自分の記事が邪魔になる。
走らせる引き金も決めておく。深さ2を日常運用に入れると決めた日か、原稿1本あたりの課金が今より目に見えて増えた日。そのどちらかが来たら、上の条件のまま測る。設計を先に置いておくのは、そのときに条件から考え直さずに済ませるためだ。
4項目とも同一入力で5回。トークンと所要時間は中央値を採り、最小と最大も併記する。1回だけ測って平均のふりをすると、ばらつきの大きい対象では都合のいい数字を選べてしまう。
条件のほうも先に固めておく。同じ CLAUDE.md、同じ入力ファイル、モデルは既定任せにせずモデル ID で固定する。トークン比をそのまま費用比として読むには、3条件が同じ単価で走っている必要がある。既定モデルは版で入れ替わるので、実行ログにモデル ID を残す。
カウントは /clear で戻してから開始する。公式の記述は「/clear で予算が戻る」までで、クリアをまたぐ処理があるときにどう数えられるかは書かれていない。戻ったことを /usage で確かめてから走らせる。深さの切り替えは settings.json 側へ寄せる。設定ファイルがシェルの環境変数を上書きするため、両方に書くとどちらが効いているのか分からなくなる。
{
"env": {
"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "3",
"CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION": "60"
}
}値は文字列で書く。2つ目は1セッションあたりの起動数の上限で、既定は200だ。計測のあいだは60に置く。深さ3・分岐3本の理論上限が39なので、60なら上限に当たらずに素の消費を測れる。ここを10のような小さい値にすると、深さ3だけが途中で打ち切られた消費を測ることになって、深さ1との比較が成り立たなくなる。
数字が出たらどう判断するか
しきい値も先に置いておく。あとから基準を作ると、都合のいいほうへ寄せてしまう。
- 深さ3の総トークンが深さ1の2倍を超え、完走率が改善していないなら入れない。費用だけ増えたことになる
- 1.2倍から2倍の範囲で完走率が同等なら、原稿1本あたりの増加額を円で出して、短縮できた工程の手間と見合うかで個別に決める
- 総トークンが1.2倍以内で完走率が同等なら、記者の内側に1段だけ許して1週間運用する
- 深さ3で完走率が落ちたら深さ2の数字を見る。深さ2でも落ちるなら設計側の問題なので、設定では解決しない
- 所要時間が無人ジョブの実行枠に収まらないなら、対話セッション限定で使う
筆者の見立てでは、原稿1本という規模だと深さ3まで使い切る場面は多くない。それを確かめるための計測でもある。
暴走に備える設定は測る前に入れる
深さを解放して困るのは、失敗が静かなときだ。計測用の60とは別に、日常運用では起動数の上限を2桁の前半まで落としておく。changelog はこの上限を「暴走する委譲のループを止めるため」とだけ説明していて、当たった瞬間の挙動までは書いていない。増殖は止まるが、メイン会話が続くぶんの課金まで止まるとは限らないと考えておく。増え方に蓋をする手段だと考えておくのがちょうどいい。
実行の前後で /usage を開いて内訳を控えておけば、差分で消費が追える。走っている最中の残量を対話画面で見る手段は見当たらなかったので、前後の記録で代用する。中身の追跡が要るときは headless の stream-json 側に寄せる。
上限を下げる作業は無料でできて、効き目もその場で分かる。有料の枠を広げる前に、止める側を締めておきたい。
無人ジョブへ入れるのは最後にする
気にしているのは所要時間だ。筆者の定期ジョブは Windows のタスクスケジューラから回していて、実行時間の上限を分単位で決めてある。上限に触れると途中で強制終了され、翌朝ログを見て初めて気づく。
段数が増えると、下請けの完了を待つ時間がそのまま積み上がる。トークンの心配ばかりしていて、枠を食い潰して落ちるほうを見落とすと痛い。対話セッションで1回きりの作業に限って試し、無人ジョブへ入れるのは所要時間の数字が出てからにする。
筆者ならこう入れる
深さ3を既定のまま使うつもりはない。日常の起動数上限を2桁に落として、そのうえで記者の内側に1段だけ許す。深さ2で原稿の質が足りるなら、そこで止める。
段数を増やして得られるのは、工程の設計をモデルに任せられる自由度だ。編集部を直列で組んだのは、どの工程で何が起きたかを自分で追えるようにするためで、そこを手放すなら見返りが要る。トークンと完走率の数字が出てから決める。
戻し方が分かっている変更は、先に触っておくほうが早い。環境変数を1行足せば元の挙動に戻るのだから、試すこと自体のリスクは小さい。
参考
深さ別のトークン消費・完走率・所要時間は未実測。実行に見合う場面が来ていないため、本稿では計測条件の設計までを載せている。測った際は使った入力一式と実行ログのモデル ID を併記して表を埋める。バージョン番号・環境変数名・changelog の引用は公式ドキュメントで原文と突き合わせた。
