「spawned with zero tools」の対処 — Claude Codeのサブエージェント権限設定

Agent 'code-reviewer' would be spawned with zero tools — refusing. — サブエージェントを起動しようとしてこう出たら、そのサブエージェントのtoolsリストに書かれた項目が1つも実際のツールに解決できず、Claude Codeが起動そのものを拒否したことを意味します。ツールが0個のまま起動しても何もできないため、v2.1.208以降はこの時点で止める設計になりました。原因はエラーメッセージが挙げる3グループのどれかです。

「zero tools」エラーの意味

サブエージェント定義のtoolsフロントマターは、そのサブエージェントが使えるツールのallowlistです。ここに書いた項目が実行時に1つも有効なツールへ解決できないと、Claude Codeは空のツールセットでの起動を拒否し、解決できなかった項目名を挙げてエラーを返します。toolsフィールド自体を省略した場合はこの拒否は起きません。省略時はサブエージェントが使えるツールをすべて継承する扱いになるためです。

v2.1.208より前は挙動が違いました。ツールが0個のまま実際に起動してしまい、何もできないサブエージェントが空の、または要領を得ない結果を返すという形で失敗していました。エラーとして明示されるようになったのはv2.1.208からです。

エラーメッセージの読み方

実際のエラーは次のような形で出ます。

Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.

unrecognizedの後ろの角括弧に、解決できなかった項目名が列挙されます。この例ではGrepのつもりで書いたGrpeが1件だけ残っており、他に問題が無ければこの1件を直すだけで解決します。複数グループにまたがって原因がある場合は、unrecognized・not available to subagents・matched no tools in this sessionのラベルごとに項目が分けて表示されるため、メッセージを上から順に読めば原因の切り分けに迷いません。

原因は3グループに分類される

エラーメッセージは、解決できなかったtoolsエントリを次の3グループに分けて報告します。

同じtools: Grep, Bashのような設定でも、タイポが1つ混じっているだけでこのグループ分けの1件目に該当し、リスト全体が空扱いになるわけではありません。他の項目が正しく解決されていれば、そのサブエージェントは残りのツールで起動します。全滅するのは、リストの全項目が3グループのどれかに該当したときだけです。

見落としやすい「Not available to subagents」

このエラーで一番気づきにくいのは2番目のグループです。LSPのように、フォアグラウンドのサブエージェントなら使えるのに、バックグラウンドでは除外されるツールがあります。サブエージェントはデフォルトでバックグラウンド実行のため、tools: LSPのような指定は普段は普通に動いていたのに、フォアグラウンド前提で書いたある日から急にこのエラーになる、という形で顔を出します。

バックグラウンドのサブエージェントが保持する組み込みツールは、AgentとExitPlanModeを除けば次の一覧に限られます。

Read / Grep / Glob / Bash / PowerShell / Edit / Write / NotebookEdit / WebFetch / WebSearch / TodoWrite / Skill / ToolSearch / EnterWorktree / ExitWorktree / Monitor / TaskStop / SendMessage / Artifact

この一覧に無い組み込みツールは、toolsに書いても継承していても、バックグラウンド実行では機械的に除去されます。除去自体はエラーにならず、除去した結果リストが空になったときだけこのエラーが出ます。MCPツールはこの絞り込みの対象外で、バックグラウンドでもすべて保持されます。

サブエージェントの実行形態を切り替えられる場合、background: trueをあえて外してフォアグラウンド実行を試すだけで、この絞り込み自体が働かなくなり同じtools定義がそのまま通ることがあります。フォーク経由で起動したサブエージェントも同様にこの2番目の絞り込みをスキップします。「昨日まで動いていた定義が急に動かなくなった」というときは、実行形態がフォアグラウンドからバックグラウンドへ切り替わっていないかも合わせて確認してください。

対処法

原因グループごとに直し方が変わります。

• Unrecognized: エラーが挙げた項目名を、正しいツール名に修正する。タイポの可能性を最初に疑う
• Not available to subagents: そのツールをtoolsから外すか、background: trueを外してフォアグラウンドで動かす。フォーク経由で起動したサブエージェントもこの絞り込みをスキップする
• Matched no tools in this session: MCPサーバーが未接続なら先に接続する。存在しないサブエージェント種別ならsubagent_typeを見直す
• toolsフィールドごと削除: 特定のツールに絞る必要が無いなら、フィールド自体を省略してサブエージェントが使えるツールをすべて継承させる

tools: Read, Grep, Glob, Bash

上記のように動作確認済みのツール名だけで再定義すれば、大半のケースはこれで解決します。

tools: Agentだけがゼロになるケース

原因の3番目には、サブエージェントの入れ子に関する特殊なパターンがあります。サブエージェントは既定で3階層まで自分のサブエージェントを起動できますが、この上限(depth limit)に達すると、Claude Codeはフォーク以外のすべてのサブエージェントからAgentツールを取り上げます。toolsリストにAgentしか書いていないサブエージェントが、たまたま深い階層で起動されると、それだけでツールがゼロになりこのエラーに該当します。

対処は2つです。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH環境変数でネストの上限を引き上げるか、そのサブエージェントのtoolsにAgent以外のツールを最低1つ加えるかです。後者のほうが、他のサブエージェントへの影響が少なく安全です。

上限を引き上げる対処は、その設定を読み込むすべてのサブエージェントに影響します。深い階層でしか動かない特定の1つだけを直したいなら、上限そのものを動かすより、そのサブエージェント定義のtoolsを見直すほうが副作用が小さくなります。逆に、複数のサブエージェントが同じ深さで同じ理由に当たっているなら、上限の引き上げのほうが1箇所の変更で済みます。

export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=5

サブエージェントがAPIエラーで途中停止する別のケースは「Agent terminated early」の対処で扱っています。ツールがゼロで起動を拒否されるケースとは原因の層が異なりますが、どちらもサブエージェントが動かない場面でまず疑うべきエラーです。

空リストと省略は別扱い

toolsフィールドを完全に省略した場合、このエラーは起きません。省略時は「サブエージェントが使えるすべてのツールを継承する」という意味に解釈されるためです。一方で、toolsを明示的に空配列で書いた場合、あるいはdisallowedToolsで継承したリストの全項目を打ち消した場合も、Claude Codeはこの拒否を発動させず、ツール無しでサブエージェントを起動します。

つまり「ツールを一切使わせたくない」という意図を明示的に書いたときは、拒否ではなくそのまま通ります。拒否が発動するのは、書いた項目のどれかがツールを指しているつもりで、実際には1つも解決できなかったときだけです。意図と結果がズレているケースだけを検知する設計だと理解しておくと、挙動の予測がしやすくなります。

言い換えると、このエラーは「ツールが0個であること」自体を問題視しているのではありません。問題視しているのは、「書いた項目が実在するツールを指すつもりだったのに、実行時になって解決先が1つも見つからなかった」というズレそのものです。

よくある質問

一部のツールだけ解決できないときも起動できませんか

起動できます。このエラーが出るのはtoolsリストの全項目が解決不能なときだけです。1つでも有効なツールが残っていれば、そのサブエージェントは残ったツールで起動します。

MCPサーバー名のタイポも「Unrecognized」に入りますか

入ります。mcp__<server>やmcp__<server>__*のパターン自体が誤っていれば未認識扱いになり、サーバー名は合っているのに接続されていない場合は「Matched no tools in this session」に分類されます。

disallowedToolsで全部消したときもこのエラーになりますか

なりません。disallowedToolsで継承リストの全項目を打ち消した結果ツールがゼロになった場合、Claude Codeはこの拒否を発動させずそのまま起動します。拒否の対象はtools側の項目が解決に失敗したケースに限られます。

v2.1.208より前ではどう見分ければよいですか

専用のエラー表示が無いため、サブエージェントが空の結果や要領を得ない返答をしていないかを確認してください。toolsフィールドに問題があるサインです。バージョンを上げれば、以降は明示的にこのエラーとして表示されます。

disallowedToolsとtoolsを両方書いたときはどちらが優先されますか

disallowedToolsが先に適用され、残ったツールの集合に対してtoolsが絞り込みとして働きます。両方に同じツール名を書いた場合はそのツールは除外されます。このエラーの判定は、この2段階の適用を経た最終的なリストが空かどうかで決まるため、tools単体を見るだけでは原因が分からないことがあります。disallowedTools側で必要なツールまで巻き込んで除外していないか、あわせて確認してください。

MCPサーバー丸ごとを許可・拒否する書き方でも同じ判定になりますか

なります。mcp__<server>やmcp__<server>__*のようなサーバー単位のパターンも、個別のツール名と同じ扱いで解決されます。指定したサーバーが接続されていなければ、そのパターンは何のツールにも解決されず、他に有効なツールが残っていない限りこのエラーの対象になります。

まとめ

「Agent would be spawned with zero tools」は、サブエージェントのtoolsリストに書いた全項目が、未認識・サブエージェント非対応・セッション内に存在しない、のいずれかで解決できずに起動を拒否されたときのエラーです。エラーメッセージが挙げるグループ分けをそのまま手がかりに、タイポの修正・非対応ツールの除外・MCP接続の確認のいずれかで直せます。toolsをすべて削除して継承に任せるか、明示的に空配列で書いて意図的にツール無しにするかは、どちらもこの拒否の対象外である点も押さえておくと切り分けが早くなります。