CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHとは — 入れ子の段数を変える環境変数

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHは、サブエージェントがさらに自分のサブエージェント(孫エージェント)を起動できる段数を制御する環境変数です。既定ではメイン会話の下に3階層まで入れ子にでき、1を指定すると入れ子そのものを無効化できます。v2.1.217以降のClaude Codeで使えます。

既定の挙動と上限到達時の動き

段数の上限に達したサブエージェントからは、Agentツールだけが自動的に取り上げられます。それ以外に割り当てられたReadやBashなどのツールはそのまま使えるため、委譲先を持たないその階層のサブエージェントも、任された作業を自力でこなして要約だけを返せます。中間層の細かいやり取りがメイン会話まで上がってこない設計です。

入れ子は「調査役のサブエージェントが、見つけた指摘ごとに検証役のサブエージェントをさらに束ねる」ような、委任先で作業がもう一段分岐するタスクに向いています。メイン会話に戻ってくるのは最上位のサブエージェントがまとめた要約1件だけで、途中の階層でどれだけ枝分かれしても表には出ません。

フォークだけは扱いが少し違います。会話をそのままフォークして走らせる/subtaskは、段数の上限に達してもツール一覧からAgentが消えません。ただし実際に呼び出そうとするとエラーが返るだけで、新しいサブエージェントは起動しません。ツールの有無だけを見るとフォークは制限されていないように映りますが、最終的な挙動は非フォークと同じです。

段数はメイン会話そのものを含めず、その下に伸びるサブエージェントの層だけを数えます。既定値3であれば、メイン会話が起動したサブエージェントを1階層目として、そこからさらに2階層分の孫・ひ孫エージェントまでを許すという数え方です。

サブエージェント定義のtoolsにAgentを含めると、そのサブエージェントは段数の上限まで自分の子を起動できるようになります。ただしAgent(reviewer, tester)のようにカッコ内へ起動してよい種類を書く絞り込み構文が効くのは、claude --agentでメインスレッドとして動く場合だけです。サブエージェント定義の内側に書いても、カッコ内の型リストは無視されます。定義側から子の種類だけを絞り込む手段は用意されておらず、指定できるのはAgentツールそのものを許可するか外すかの二択です。

既定値は3段階の歴史を経ている

この変数が今の形になるまでに、既定の段数は3回変わっています。バージョンごとの違いを知らずに設定すると、手元のバージョンでは効かない指定をしてしまうことがあります。

最初に入れ子起動が入ったv2.1.172の時点では、段数を選ぶ手段がなく5階層に固定されていました。v2.1.217でサブエージェントの並列実行に初めて上限が導入された際、入れ子はいったん既定でオフに寄せられ、既定値は1に変わっています。段数の既定変更は、同じv2.1.217で同時実行数の上限が初めて入ったタイミングと重なっており、1つの指示から無制限にサブエージェントが枝分かれする経路を、横方向(同時実行数)と縦方向(段数)の両面から一度に塞いだ形です。v2.1.219で今の既定値3に落ち着きました。同じ「入れ子ができる」という説明でも、動いているバージョンによって既定の段数はまるで違います。

段数(縦方向)とは別に、セッション全体で起動できるサブエージェントの総数を絞る仕組みも一時期存在しました。v2.1.212で導入されたCLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION(既定200件)がそれですが、v2.1.224で撤廃されて現在はno-opです。今も有効に残っているのは、段数とこのあと触れる同時実行数の2つだけです。

設定のしかた

シェルの環境変数として渡す方法が最も手早く試せます。

export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2
claude

プロジェクト全体で固定したい場合はsettings.jsonのenvキーに書きます。次の例はメイン会話の下を2階層までに制限する設定です。

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

受け付けるのは正の整数だけです。小数・負の数・文字列のような値は無視され、その場合は既定値が使われ続けます。入れ子を完全に止めたいなら1を指定します。既定の3より大きい値を入れることも技術的には可能ですが、階層が深くなるほど中間層の要約が重なって元の情報が失われやすくなるため、必要な深さぶんだけ引き上げる考え方が扱いやすくなります。

特定のサブエージェントだけネストを止める

環境変数を動かすと、その設定を読み込むすべてのサブエージェントに影響します。読み取り専用でいてほしいレビュー専任のサブエージェントなど、特定の1つだけ入れ子を禁じたい場合は、変数を触らずそのサブエージェント定義のtoolsからAgentを外すか、disallowedToolsに加える方法が的確です。全体の上限は変えずに、個別の挙動だけをピンポイントで固定できます。

ネストしたサブエージェントの設定方法は、最上位のサブエージェントと同じです。プロジェクト・ユーザーいずれのスコープからも同じ規則で解決されます。用途に応じた設定の目安は次のとおりです。

上限に達すると画面上ではどう見えるか

Claude Codeはネストしたサブエージェントを、プロンプト入力欄の下にあるサブエージェントパネルにツリー表示します。まだ子を持っている行には(+N)という件数が添えられ、開くとその階層のきょうだいと直接の子を、mainまで遡る経路つきで確認できます。

上限に達した階層でtoolsにAgentしか持たないサブエージェントは、ツールがゼロの状態になって起動そのものがエラーで拒否されます。このエラーへの対処は「spawned with zero tools」の対処にまとめています。ネストの上限を引き上げるか、そのサブエージェントのtoolsに他のツールを最低1つ加えるかのどちらかで解消します。

1を指定して入れ子をオフにしている場合、このパネルにネストは現れません。メイン会話が起動した1階層ぶんのサブエージェントが並ぶだけの、フラットな一覧表示になります。段数を増やすほどツリーは深くなり、(+N)表示を辿って追う手間も比例して増えます。

並列数の上限とは別の変数

サブエージェントの数を絞る変数はもう1つあり、この変数とは制御する軸が異なります。段数(縦方向)を絞っても、同時に動ける本数(横方向)は変わりません。

同時実行数の既定値・上限にカウントされる対象・ダイナミックワークフローとの関係はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSとはに詳しくまとめています。深い階層構造を持つ並列処理を組むときは、両方の変数を目的に応じて別々に調整します。なお、段数・同時実行数のどちらの上限も、セッション全体で起動できるサブエージェントの累計数そのものには上限をかけません。

サブエージェントの数にまつわる環境変数はこの2つだけではありません。CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY(既定10)は、読み取り専用のツールとサブエージェントを合わせて同時に実行できる数を制御する、また別の変数です。段数と同時実行数がAgentツール経由のサブエージェント起動そのものを対象にするのに対し、こちらは読み取り専用ツールの並列実行も同じ枠に含めて数えます。名前が似た3つの変数がそれぞれ違う軸を制御しているため、値を変える前にどれが目的の挙動を制御しているかを確認する必要があります。

Agent SDKでも同じ変数が効く

TypeScript・PythonいずれのAgent SDKでも、同じCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHをenvオプション経由で渡して段数を制御できます。SDK側には支出上限(maxBudgetUsd)という別の歯止めもあり、深さ・同時実行数・支出の3つを組み合わせた上限設計はAgent SDKのサブエージェント上限で扱っています。

/subtaskのフォークがこの深さ制限とどう絡むかはClaude Codeのサブエージェント並列設計に書きました。フォークは上限に達してもツール定義上はAgentが残る一方、非フォークは最初からツールを取り上げられる非対称な挙動があります。

よくある質問

既定値の3に戻すにはどうすればよいか

settings.jsonのenvからCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHの行を削除するか、シェルでunset CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHを実行します。変数自体が存在しなければ、Claude Codeはバージョンに応じた既定値(v2.1.219以降なら3)を使い続けます。値を明示的に書かず未設定のままにしておけば、将来また既定値が変わったときも設定ファイルを直さず自動的に追従できます。

Agent SDK経由でも上限に達したときの挙動は同じか

同じです。SDK経由でもClaude Code本体と同じ判定ロジックが働き、段数の上限に達したサブエージェントからはAgentツールが取り上げられます。SDK側の違いは、段数とは別に支出上限(maxBudgetUsd)を組み合わせて設定できる点です。

まとめ

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHは、サブエージェントが入れ子で持てる段数を変える環境変数です。既定値は3ですが、v2.1.172〜v2.1.216は5段階固定、v2.1.217〜v2.1.218は1という別の既定を経ており、参照するバージョンによって書かれている数字が変わります。上限に達すると非フォークのサブエージェントからAgentツールが取り上げられ、フォークだけはツールを保持したままエラーを返す非対称な挙動も押さえておく価値があります。特定の1つだけネストを止めたいなら、変数ではなくtools・disallowedTools側で個別に制御します。環境変数全体の一覧はClaude Code環境変数リファレンスを参照してください。