環境変数

CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION

1つのセッション内でAgentツールを使用して起動できるサブエージェントの最大数を制限します。

使い方・用途

  • デフォルト値は200で、正の整数を指定して上限を引き上げることが可能です（上限なしへの無効化は不可）。
  • 制限に達すると、以降のサブエージェント作成は失敗し、Claudeは残りの作業を直接完了するよう指示されます。
  • ネストされたサブエージェントやフォーク、バックグラウンドでの作成もカウント対象となるため、大規模なワークフロー実行時に調整が必要となります。
英語原文(公式ドキュメントより)

Cap on the number of subagents one session can spawn with the Agent tool (default: 200). When Claude reaches the cap, spawning another subagent fails with an error telling Claude to finish the remaining work directly. Accepts a positive whole number in plain digits with no upper bound; this variable doesn't take the scientific notation or digit-separator spellings. Anything else is ignored and the default applies, so the cap can be raised but not turned off. Requires Claude Code v2.1.212 or later

関連する変更履歴

v2.1.212(1件)

Added
サブエージェントの起動数にセッションごとの上限（デフォルト200回）を設け、ループ時の過剰な委譲を抑制します。
英語原文を表示
Added a per-session cap on subagent spawns (default 200, override with CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION) to stop runaway delegation loops; /clear resets the budget

変更前

サブエージェントが連鎖的に起動してしまい、セッション全体がハングアップする事象がありました。

変更後

起動上限に達すると自動的に停止し、必要に応じて /clear でリセットできるようになりました。

ユーザーへの恩恵

再帰的な処理エラーによるセッションの完全停止を心配する必要がなくなります。

関連ドキュメント