WebSearch とサブエージェントに上限200 — 片方は無言で止まる

200。Claude Code v2.1.212 で入った、1セッションあたりの WebSearch 呼び出し数とサブエージェント起動数の既定上限だ。引き上げはできるが、オフにはできない。そして上限に達したとき、片方は無言で止まる。

【PR】本記事は広告を含みます。末尾の Claude Code 紹介リンクは Anthropic の紹介プログラムのリンクで、登録が有料プランへ進むと筆者に利用クレジットが入ります。

目次

1. 2つの上限
2. 上限に達したとき、挙動が非対称になる
3. 「2分」はタイムアウトではない
4. /fork の意味が変わった
5. 他のコスト制御と組み合わせる
6. 上限は保険として使う
   1. 自分が何回呼んでいるか、意外と知らない
7. チームで使うなら先に揃えておく
8. 試すなら、下げて再現するのが早い
9. 参考

2つの上限

どちらも合計でカウントされる点に注意したい。サブエージェントを10本走らせて各20回検索すれば、それだけで200に届く。

設定はシェルの環境変数でも settings.json の env キーでもよく、優先されるのは設定ファイル側になる。値は正の整数のみで、上限はない。指数表記や桁区切り（2e3 や 1_000）は受け付けないと明記されている。

不正な値を入れると無視されて既定値が使われる。上限を引き上げることはできても、機能を止めることはできない設計だ。

/clear するとカウントはリセットされる。ワークフローなど、クリア後も生き残る処理があるとカウントは引き継がれるとされているので、そこだけ例外になる。

{

  "env": {

    "CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION": "500",

    "CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION": "50",

    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "30000"

  }

}

値は文字列で書く。

上限に達したとき、挙動が非対称になる

ここが今回いちばん注意したい部分だ。2つの上限は、到達時の振る舞いが違う。

サブエージェント側はエラーになる。Agent ツールが Subagent spawn limit reached で失敗し、残りは自分のツールで直接やるよう Claude に伝わる。止まったことが分かる。

ちなみに、ユーザー自身が打つ /subtask は同じ予算を消費するものの、ブロックされるのは Claude が Agent ツールで起動する分だけだ。上限に達したあとも手動での起動はできる。

WebSearch 側はエラーにならない。通知が返り、既に集めた情報で続行するよう伝えられる。リトライを誘発しないための意図的な設計だと説明されている。そして公式ドキュメントにこう書かれている。

あなたにはその通知は見えない。上限に達した呼び出しは、何もしなかった検索として会話に現れる

検索したように見えて、何も返っていない。上限に達したかどうかをユーザーが直接検知する手段についての記述は、ドキュメントに見当たらなかった。/usage が現在のカウントを表示するかも書かれていない。残数を確認する公式の手段は見つけられなかった。

従来200を超える WebSearch を回していた調査系のワークフローは、v2.1.212 以降無言で結果が劣化する可能性がある。深掘り調査を自動化している人は、明示的に引き上げておいたほうがいい。

この非対称は、設計としては筋が通っている。サブエージェントの失敗は代替手段があるのでエラーで知らせ、検索の打ち切りは「もう調べなくていい」という指示に近いので静かに済ませる。ただ運用する側としては、静かに減った情報のほうが怖い。

「2分」はタイムアウトではない

同じリリースで、2分を超える MCP ツール呼び出しが自動的にバックグラウンドへ移るようになった。閾値は CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS で、既定は120000ミリ秒。こちらは 0 にすればオフにできる。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 でも止まるが、こちらは他のバックグラウンド機能ごと無効になる。

誤読しやすいのは、これが打ち切り時間ではないという点だ。2分でセッションをブロックしなくなる、という意味になる。実際の打ち切りを決めるのは別の設定だ。

バックグラウンドに移ると Claude は即座にタスク ID を受け取って作業を続け、決着した時点で結果が通知として届く。/tasks に並び、そこから停止もできる。セッションが終わると生き残らないので、投げっぱなしの長時間ジョブには使えない。

バックグラウンド化されない条件も決まっている。サブエージェントからの呼び出し、IDE サーバーへの呼び出し、非対話モード、elicitation ダイアログが開いている間。サブエージェント経由だと効かない点は、並列調査を組んでいる人には効いてくる。

/fork の意味が変わった

破壊的変更として、これが一番危ない。

v2.1.161 から v2.1.211 までの /fork は、結果が返ってくる挙動だった。既存のスクリプトや SKILL.md、CLAUDE.md、手順書で /fork を「結果が返る前提」で使っている箇所は、すべて /subtask に置き換える必要がある。

置き換えないとどうなるか。フォーク先が独立セッションになるので結果が会話に返らず、しかもエラーにはならない。静かに壊れる。

agent view を無効化している環境では例外で、/subtask が使えず /fork が従来の挙動を維持する。チーム内でバージョンが混在すると、片方でしか動かない手順書ができあがる。バージョンの境界は v2.1.161 と v2.1.212 の2箇所なので、社内ドキュメントを直すときはこの2つを基準にするといい。

他のコスト制御と組み合わせる

今回の上限だけを見ても片手落ちになる。公式が挙げている制御手段を並べておく。

• /usage — スキル・サブエージェント・MCP サーバー別の内訳を24時間 / 7日で切り替えて表示
• Pro / Max の月額 spend limit
• MAX_THINKING_TOKENS — 固定思考予算のモデル向け。適応推論のモデルは非ゼロ予算を無視するので /effort を使う
• MAX_MCP_OUTPUT_TOKENS — 既定25,000トークン制限、10,000で警告
• 冗長な処理のサブエージェントへの委譲、plan mode の活用

MAX_MCP_OUTPUT_TOKENS は地味に効く。巨大な JSON を返す MCP サーバーを繋いでいると、ここで削られる。

上限は保険として使う

筆者はモデルを常に最上位で固定せず、タスクの難度で使い分けている。同じ発想で、サブエージェントの数も「使えるだけ使う」ものとは考えていない。

複数の AI エージェントを1画面に統合するツールを作ったとき、並列で走らせる数を増やすほど、結果の突き合わせと打ち切り判断のほうが重くなった。並列数を増やすと、どこで止めるかを決める仕事が増える。

自分が何回呼んでいるか、意外と知らない

200という数字を見て「そんなに使わない」と思った人は多いと思う。筆者もそう思った。

ただ、サブエージェントに調査を任せる形のワークフローだと、数はすぐ膨らむ。10個のテーマを並列で調べさせて、各エージェントが裏取りに15回ずつ検索すれば150。そこにメイン会話の分が乗る。1セッションで完結させようとするほど、合計は増えていく。

厄介なのは、この数を普段は意識しないことだ。/usage はスキルやサブエージェント、MCP サーバー別の内訳を出してくれるが、WebSearch の残り回数を表示するとは書かれていない。走っている最中に「あと何回使えるか」を知る手段が見当たらなかった。

だから引き上げるにしても下げるにしても、まずは自分の典型的なセッションが何回呼んでいるかを掴んでおきたい。上限を3に下げて意図的に頭打ちにすれば、どのあたりで足りなくなるかが体感できる。

だから200という既定は、制約というより保険だと受け取っている。むしろ自分で下げておくほうが実利がある。CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION を20や50にしておけば、暴走したときに気づける。有料サービスはまず無料枠で回してから課金価値を判断する方針なので、こういう歯止めは自分で締めておきたい。

チームで使うなら先に揃えておく

ひとりで使う分には自分の設定を直せば済むが、手順書を共有している場合は事情が変わる。

settings.json の env はシェルの環境変数を上書きするので、プロジェクトの .claude/settings.json に書いておけば全員に同じ上限が効く。個人ごとの調整を許したいなら書かない、という判断もできる。

更新の周知も要る。/fork の意味が変わった件は、古い版を使っている人の手元では従来どおり動く。同じ手順書を読んでいるのに結果が違う、という状態が起きる。

試すなら、下げて再現するのが早い

上限は引き下げもできるので、挙動の確認は簡単にできる。

export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=3

claude

この状態で検索が要る調査を頼むと、4回目以降が「何も返さない検索」として現れるはずだ。ドキュメントが言う「ユーザーには通知が見えない」を自分の目で確認できる。サブエージェント側を2にすれば Subagent spawn limit reached が出る。無言と明示、2つの挙動を並べて見ると違いが分かりやすい。

MCP の閾値を確かめたいなら、30秒スリープするだけの stdio サーバーを1本書いて CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=10000 で呼ぶ。10秒後に /tasks に現れ、セッションが操作可能なまま結果が通知で返る様子が見える。0 にした場合と比べれば、ブロックされる状態との差もはっきりする。

筆者はまだ実測していない。実際に走らせて挙動を確認したら、結果をあらためて書く。

AI エージェントを組み合わせた開発については複数のAIエージェントを1画面に統合した制作記事で扱っている。まずは自分の settings.json に env キーがあるかどうか、開いて確かめるところから。

参考

• Week 29 · July 13–17, 2026（公式）
• 環境変数リファレンス（公式）
• MCP ドキュメント（公式）
• コスト管理（公式）