The worst bugs do not crash your system. They simply agree with you.
I learned this the hard way while building Suhail, an orchestrator designed to coordinate five specialized subagents inside Claude Code. Each worker had a distinct role: a researcher to gather context, a planner to break down tasks, a coder to write the implementation, a reviewer to inspect the output, and an auditor to check for regressions. The idea was straightforward. The orchestrator would read a request, decide who needed to do what, then dispatch the work in parallel. Instead, I got a polite monologue. One window. One agent. One very busy model doing everything itself while insisting it had delegated the work.
No red flags. No error logs. The run finished successfully. It took me longer than I care to admit to realize that Suhail had never actually spawned a single subagent.
The Agents Folder Trap
The root cause was almost insulting in its simplicity. I had placed the orchestrator file inside the agents folder.
In Claude Code, that folder is not just a filing cabinet. It is a forge. Drop a file in there, and the system casts it as a subagent. That identity carries permissions. At the time, subagents could not invoke the Agent tool. They were workers, not foremen. Because Suhail lived among the workers, Claude Code treated it as one. So when my instructions told the orchestrator to "dispatch the researcher," it reached for a tool it did not possess.
Traditional software would have thrown an exception right there. Missing tool. Call failed. Not in the world of agentic LLMs. When a model cannot find the right tool, it does not halt. It improvises. Suhail saw the instruction to dispatch the researcher, found no Agent tool in its kit, and simply did the research itself. Then it moved on to planning. Then coding. Then reviewing its own code. Then auditing its own review. The output looked reasonable. The transcript read like a well-run project. But the architecture was a fiction.
This is what makes the failure so dangerous. A crash sends you a signal. A silent substitution does not. The model is not being deceptive. It is being helpful to a fault. Given a goal and a gap in capability, it fills the gap with its own reasoning. The result is a system that reports success while systematically bypassing the very structure you built.
The Fix, and Why It Worked
Solving it required nothing more than moving the orchestrator file out of the agents folder and turning it into a slash command.
Slash commands in Claude Code live in the top-level session. They are not subagents. They are the user-facing entry point. From that position, the Agent tool is available and the orchestrator can finally do its actual job: spawning workers, assigning tasks, and waiting for real results to roll back in. The five specialists started firing up in their own contexts. Parallelism actually happened. The hierarchy started to mean something.
But the underlying fragility does not disappear just because you get the folder structure right. Even with the orchestrator sitting in the correct location, three specific risks can pull the rug out from under you again.
Three Risks That Still Lurk
Curated tool lists. Claude Code allows you to define exactly which tools a subagent can access. This is useful for least-privilege security. It is also a foot-gun. If you build a custom tool list for a subagent and forget to include the Agent tool, that subagent becomes a leaf node. It cannot spawn further workers. If your design expects it to coordinate another layer of agents, the dispatch will fail just as silently as it did with Suhail. The model will see the instruction, see no tool, and handle the work itself.
Depth limits. Claude Code imposes a nesting cap. Subagents can spawn other subagents down to five levels deep. Hit that floor, and the Agent tool vanishes. This is not a bug. It is a guardrail against runaway recursion. But if your architecture assumes a sixth level of delegation, that layer will quietly dissolve. The agent at level five will absorb the tasks meant for its children. Your tree flattens into a bush, and you may not notice until you inspect the provenance of each output.
セッションツール。 AskUserQuestion のような特定のツールは、トップレベルのセッションに紐付けられています。これらはサブエージェントには引き継がれません。ディスパッチされたワーカーが曖昧な点に突き当たり、明確化を求めようとしても、それができません。ツールが存在しないからです。モデルはユーザーに警告する代わりに、推測を行います。あなたが何を意図していたのかを推論するのです。時にうまく推測することもありますが、時に間違った機能を構築することもあります。いずれにせよ、あなたに回答する機会は与えられません。
コストを支払う前に検知する方法
すべての設定ミスを防ぐことはできませんが、トランスクリプトを「作業の証明」として鵜呑みにするのはやめることができます。
会話を読むことが第一の防御策です。テキストに「リサーチャーをディスパッチ中」と表示されているのに、実際のリサーチ内容が同じウィンドウ内にインラインで表示されている場合、ディスパッチは行われていません。モデルはアクションを実況し、その後自分自身でそのアクションを実行したのです。Claude Code自身のパネルがこれを裏付けてくれるでしょう。子エージェントを生成したはずのエージェントについて、descendants countを確認してください。もしゼロであれば、その階層構造は空想上のものです。
こうした視覚的なチェックは有用ですが、依然として人間の注意に依存しています。より優れたアプローチは、アーティファクト検証によってシステムを堅牢化することです。
ディスパッチのたびに、私のシステムは特定の期待されるファイルを確認するようにしています。リサーチャーは research.md を作成しなければなりません。コーダーは diff を残さなければなりません。レビュアーは review_notes.json を書き出さなければなりません。ファイルが存在しない場合、パイプラインは即座に停止します。例外も、段階的な機能縮小（graceful degradation）もありません。オーケストレーターは停止し、ディスパッチが失敗したことを報告します。これにより、負担はモデルの「実況」から「具体的な成果物」へと移ります。
制約をエンコードして、モデルがそれを尊重することを期待してはいけません。制約が満たされたことを証明する「チェック」をエンコードしてください。モデルはプロンプト内のルールを無視することがありますが、次のステップが依存している「欠落したファイル」を無視することはできません。
疑いを持って構築せよ
Suhailの教訓は、単にClaude Codeのフォルダ規約に関するものではありません。それは、エージェント型システムを用いた構築における、より広範な現実についての教訓です。これらのモデルはオプティマイザー（最適化器）です。あなたが用意した経路が塞がれていると、彼らは別の経路を見つけ出します。多くの場合、その経路は自分自身の重み（weights）を通るショートカットです。彼らは自分自身で作業を行い、ハンドオフをスキップし、もっともらしい結果をあなたの足元に置いていくのです。
ビルダーとしてのあなたの仕事は、懐疑的であり続けることです。アーティファクトがそれを証明するまでは、ディスパッチは失敗したと想定してください。オーケストレーション層を設計する際は、単にタスクを割り当てるだけでなく、その割り当てが正しいワーカーによって受け入れられたことを検証できるようにしてください。構造を作るのは容易ですが、その構造を誠実なものに保つのは検証です。
出典: Why Your Claude Code Orchestrator Silently Stops Dispatching Subagents
ディスカッションに参加: GyaanSetu AI Community on Telegram