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.
ਸੈਸ਼ਨ ਟੂਲਜ਼ (Session tools). ਕੁਝ ਟੂਲਜ਼, ਜਿਵੇਂ ਕਿ AskUserQuestion, ਟਾਪ-ਲੈਵਲ ਸੈਸ਼ਨ ਨਾਲ ਜੁੜੇ ਹੁੰਦੇ ਹਨ। ਉਹ ਸਬ-ਏਜੰਟਸ (subagents) ਵਿੱਚ ਨਹੀਂ ਜਾਂਦੇ। ਜੇਕਰ ਕੋਈ ਡਿਸਪੈਚ ਕੀਤਾ ਗਿਆ ਵਰਕਰ ਕਿਸੇ ਅਸਪਸ਼ਟਤਾ ਦਾ ਸਾਹਮਣਾ ਕਰਦਾ ਹੈ ਅਤੇ ਸਪਸ਼ਟੀਕਰਨ ਮੰਗਣ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰਦਾ ਹੈ, ਤਾਂ ਉਹ ਅਜਿਹਾ ਨਹੀਂ ਕਰ ਸਕਦਾ। ਉਹ ਟੂਲ ਉੱਥੇ ਮੌਜੂਦ ਨਹੀਂ ਹੁੰਦਾ। ਯੂਜ਼ਰ ਨੂੰ ਸੂਚਿਤ ਕਰਨ ਦੀ ਬਜਾਏ, ਮਾਡਲ ਅੰਦਾਜ਼ਾ ਲਗਾਏਗਾ। ਇਹ ਅੰਦਾਜ਼ਾ ਲਗਾਏਗਾ ਕਿ ਤੁਹਾਡਾ ਸ਼ਾਇਦ ਕੀ ਮਤਲਬ ਸੀ। ਕਦੇ-ਕਦੇ ਇਹ ਸਹੀ ਅੰਦਾਜ਼ਾ ਲਗਾਉਂਦਾ ਹੈ। ਕਦੇ-ਕਦੇ ਇਹ ਗਲਤ ਫੀਚਰ ਬਣਾ ਦਿੰਦਾ ਹੈ। ਕਿਸੇ ਵੀ ਹਾਲਤ ਵਿੱਚ, ਤੁਹਾਨੂੰ ਜਵਾਬ ਦੇਣ ਦਾ ਮੌਕਾ ਨਹੀਂ ਮਿਲਦਾ।
ਇਸਨੂੰ ਨੁਕਸਾਨ ਪਹੁੰਚਾਉਣ ਤੋਂ ਪਹਿਲਾਂ ਕਿਵੇਂ ਫੜਿਆ ਜਾਵੇ
ਤੁਸੀਂ ਹਰ ਗਲਤ ਕੌਂਫਿਗਰੇਸ਼ਨ ਨੂੰ ਰੋਕ ਨਹੀਂ ਸਕਦੇ, ਪਰ ਤੁਸੀਂ ਕੰਮ ਦੇ ਸਬੂਤ ਵਜੋਂ ਟ੍ਰਾਂਸਕ੍ਰਿਪਟ (transcript) 'ਤੇ ਭਰੋਸਾ ਕਰਨਾ ਬੰਦ ਕਰ ਸਕਦੇ ਹੋ।
ਗੱਲਬਾਤ ਨੂੰ ਪੜ੍ਹਨਾ ਬਚਾਅ ਦੀ ਪਹਿਲੀ ਲਾਈਨ ਹੈ। ਜੇਕਰ ਟੈਕਸਟ ਕਹਿੰਦਾ ਹੈ "dispatching the researcher" ਪਰ ਅਸਲ ਖੋਜ ਸਮੱਗਰੀ (research content) ਉਸੇ ਵਿੰਡੋ ਵਿੱਚ ਦਿਖਾਈ ਦਿੰਦੀ ਹੈ, ਤਾਂ ਡਿਸਪੈਚ ਕਦੇ ਹੋਇਆ ਹੀ ਨਹੀਂ ਸੀ। ਮਾਡਲ ਨੇ ਇੱਕ ਕਾਰਵਾਈ ਬਾਰੇ ਦੱਸਿਆ ਅਤੇ ਫਿਰ ਉਹ ਕਾਰਵਾਈ ਖੁਦ ਹੀ ਕਰ ਦਿੱਤੀ। Claude Code ਦਾ ਆਪਣਾ ਪੈਨਲ ਇਸਦੀ ਪੁਸ਼ਟੀ ਕਰੇਗਾ। ਕਿਸੇ ਵੀ ਅਜਿਹੇ ਏਜੰਟ ਲਈ ਡੈਸੈਂਡੈਂਟ ਕਾਊਂਟ (descendants count) ਦੀ ਜਾਂਚ ਕਰੋ ਜਿਸ ਤੋਂ ਤੁਸੀਂ ਬੱਚੇ (children) ਬਣਾਉਣ ਦੀ ਉਮੀਦ ਕਰਦੇ ਹੋ। ਜੇਕਰ ਇਹ ਜ਼ੀਰੋ ਦਿਖਾਉਂਦਾ ਹੈ, ਤਾਂ ਤੁਹਾਡੀ ਹਾਇਰਾਰਕੀ ਕਲਪਨਾਤਮਕ ਹੈ।
ਉਹ ਵਿਜ਼ੂਅਲ ਚੈੱਕ (visual checks) ਉਪਯੋਗੀ ਹਨ, ਪਰ ਉਹ ਅਜੇ ਵੀ ਮਨੁੱਖੀ ਧਿਆਨ 'ਤੇ ਨਿਰਭਰ ਕਰਦੇ ਹਨ। ਬਿਹਤਰ ਤਰੀਕਾ ਆਰਟੀਫੈਕਟ ਵੈਰੀਫਿਕੇਸ਼ਨ (artifact verification) ਨਾਲ ਸਿਸਟਮ ਨੂੰ ਮਜ਼ਬੂਤ ਕਰਨਾ ਹੈ।
ਹਰ ਡਿਸਪੈਚ ਤੋਂ ਬਾਅਦ, ਮੇਰਾ ਸਿਸਟਮ ਹੁਣ ਇੱਕ ਖਾਸ, ਉਮੀਦ ਕੀਤੀ ਗਈ ਫਾਈਲ ਦੀ ਜਾਂਚ ਕਰਦਾ ਹੈ। ਰਿਸਰਚਰ ਨੂੰ research.md ਤਿਆਰ ਕਰਨੀ ਚਾਹੀਦੀ ਹੈ। ਕੋਡਰ ਨੂੰ ਇੱਕ diff ਛੱਡਣਾ ਚਾਹੀਦਾ ਹੈ। ਰਿਵਿਊਅਰ ਨੂੰ review_notes.json ਲਿਖਣਾ ਚਾਹੀਦਾ ਹੈ। ਜੇਕਰ ਫਾਈਲ ਮੌਜੂਦ ਨਹੀਂ ਹੈ, ਤਾਂ ਪਾਈਪਲਾਈਨ ਤੁਰੰਤ ਰੁਕ ਜਾਂਦੀ ਹੈ। ਕੋਈ ਅਪਵਾਦ ਨਹੀਂ, ਕੋਈ ਗ੍ਰੇਸਫੁੱਲ ਡਿਗ੍ਰੇਡੇਸ਼ਨ (graceful degradation) ਨਹੀਂ। ਆਰਕੈਸਟਰੇਟਰ (orchestrator) ਰੁਕ ਜਾਂਦਾ ਹੈ ਅਤੇ ਰਿਪੋਰਟ ਕਰਦਾ ਹੈ ਕਿ ਡਿਸਪੈਚ ਅਸਫਲ ਰਿਹਾ। ਇਹ ਬੋਝ ਮਾਡਲ ਦੇ ਬਿਰਤਾਂਤ (narration) ਤੋਂ ਹਟਾ ਕੇ ਠੋਸ ਡਿਲੀਵਰੇਬਲਜ਼ (deliverables) 'ਤੇ ਲਿਆਉਂਦਾ ਹੈ।
ਆਪਣੀਆਂ ਸੀਮਾਵਾਂ (constraints) ਨੂੰ ਸਿਰਫ਼ ਕੋਡ ਵਿੱਚ ਨਾ ਲਿਖੋ ਅਤੇ ਉਮੀਦ ਨਾ ਕਰੋ ਕਿ ਮਾਡਲ ਉਹਨਾਂ ਦਾ ਸਤਿਕਾਰ ਕਰੇਗਾ। ਅਜਿਹੇ ਚੈੱਕ ਕੋਡ ਕਰੋ ਜੋ ਸਾਬਤ ਕਰਨ ਕਿ ਸੀਮਾਵਾਂ ਪੂਰੀਆਂ ਕੀਤੀਆਂ ਗਈਆਂ ਸਨ। ਇੱਕ ਮਾਡਲ ਪ੍ਰੋਂਪਟ ਵਿੱਚ ਦਿੱਤੇ ਨਿਯਮ ਨੂੰ ਨਜ਼ਰਅੰਦਾਜ਼ ਕਰ ਸਕਦਾ ਹੈ। ਪਰ ਉਹ ਕਿਸੇ ਅਜਿਹੀ ਗੁੰਮ ਹੋਈ ਫਾਈਲ ਨੂੰ ਨਜ਼ਰਅੰਦਾਜ਼ ਨਹੀਂ ਕਰ ਸਕਦਾ ਜਿਸ 'ਤੇ ਅਗਲਾ ਕਦਮ ਨਿਰਭਰ ਕਰਦਾ ਹੈ।
ਅਵਿਸ਼ਵਾਸ ਲਈ ਤਿਆਰ ਕਰੋ
ਸੁਹੈਲ (Suhail) ਦਾ ਸਬਕ ਸਿਰਫ਼ Claude Code ਫੋਲਡਰ ਕਨਵੈਂਸ਼ਨਾਂ ਬਾਰੇ ਨਹੀਂ ਹੈ। ਇਹ ਏਜੈਂਟਿਕ ਸਿਸਟਮਾਂ (agentic systems) ਨਾਲ ਬਣਾਉਣ ਦੀ ਵਿਆਪਕ ਹਕੀਕਤ ਬਾਰੇ ਹੈ। ਇਹ ਮਾਡਲ ਆਪਟੀਮਾਈਜ਼ਰ (optimizers) ਹਨ। ਜਦੋਂ ਤੁਹਾਡੇ ਦੁਆਰਾ ਤਿਆਰ ਕੀਤਾ ਗਿਆ ਰਸਤਾ ਰੁਕ ਜਾਂਦਾ ਹੈ, ਤਾਂ ਉਹ ਕੋਈ ਹੋਰ ਰਸਤਾ ਲੱਭ ਲੈਣਗੇ। ਅਕਸਰ ਉਹ ਰਸਤਾ ਉਹਨਾਂ ਦੇ ਆਪਣੇ ਵੇਟਸ (weights