[BUG] Sub-agents can't create sub-sub-agents, even with Task tool access

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/4182
2. https://github.com/anthropics/claude-code/issues/5528
3. https://github.com/anthropics/claude-code/issues/15262

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This issue isn't a duplicate of any open issue. Two previous issues were closed as duplicates of each other, but the issue they describe remains.

I've definitely mentioned this in issue comments before. Being able to call just one more layer of subagents would improve my workflow a lot, because I could avoid a ton of compaction and do far more before the subagents themselves run out of context.

This seems intentional.

From the docs:

Subagents cannot spawn other subagents.

https://code.claude.com/docs/en/sub-agents#choose-between-subagents-and-main-conversation

Sure enough! I'm pretty sure that's a recent addition to the documentation.

That is a huge limitation. The consequence is that agents aren't composable.

The documentation's advice to use Skills isn't very helpful for me. Skills and custom agents are very different things.

We should just be able to define an agent depth. This is a huge limitation

Target Issues:

• Issue #19077 - Sub-agents can't create sub-sub-agents, even with Task tool access
• Issue #13533 - Task tool missing when launching session with --agent

---

Confirming This Issue + Critical Blocker for Orchestration Frameworks

I'm hitting this exact issue while building a multi-agent orchestration project, and it's a critical blocker that breaks the entire framework.

Setup:

• Custom agent defined in .claude/agents/conductor/agent.md
• Loaded as main agent via settings.json with "agent": "conductor"
• Intended to orchestrate multiple worker agents via Task() tool

Critical Issue - Custom Agents Lose Task() Even As Main Instance:

❌ Custom agent loaded via settings.json does NOT have Task() tool, even though it's the main instance

• Cannot dispatch worker agents
• Orchestration framework is completely broken
• This is Issue #13533: "Task tool missing when launching session with --agent"

What Works:
✅ Default main Claude instance (no "agent" in settings.json) → Has Task()
✅ Default main instance wearing a SKILL → Has Task()

What Doesn't Work:
❌ Custom agent as main (via settings.json) → No Task() tool
❌ Worker subagents → No Task() tool (expected, documented)

Impact: This Blocks All Orchestration Frameworks

Any framework that needs custom agents to orchestrate workers is broken:

1. Create custom orchestrator agent
2. Load it via settings.json
3. Try to dispatch workers with Task()
4. Task() tool missing → framework dead on arrival

Confusing Developer Experience:

1. No validation warning - Adding Task to worker agent's allowed-tools succeeds without any error or warning that it won't actually work

1. Misleading error message - When worker tries to use Task():

``
Error: Task tool not available
`
Should say: Task() is only available to the main Claude instance, not spawned sub-agents`

1. Inconsistent documentation - The restriction is mentioned in sub-agents docs but NOT in:

• Task tool description
• Agent architecture docs
• allowed-tools validation behavior

Why This Is Confusing:

The architectural decision to prevent nested spawning makes sense (prevents infinite recursion, reduces complexity). But the lack of clear communication makes it feel like a bug rather than intentional design.

Suggested Improvements:

1. Validation at agent creation - Warn if Task is added to custom agent's allowed-tools:

``
Warning: Task tool in allowed-tools will have no effect.
Task() is only available to the main Claude instance.
``

1. Better error message - When sub-agent tries to use Task():

``
Error: Task() tool is only available to the main Claude instance.
Sub-agents cannot spawn nested agents to prevent infinite recursion.
See: https://code.claude.com/docs/en/sub-agents#nesting-limitation
``

1. Update Task tool description - Add to the Task tool's description:

``
Note: This tool is only available to the main Claude Code instance.
Spawned sub-agents cannot use Task() to prevent nested orchestration.
``

Workaround (Forced Architecture Regression):

Had to revert from custom agent to skill-based architecture:

# Original (broken):
settings.json:
  "agent": "conductor"           ❌ Custom agent loses Task()

.claude/agents/conductor/agent.md ❌ Cannot orchestrate

# Reverted to (working):
settings.json:
  [no agent field]                ✅ Default main instance

.claude/skills/conductor/SKILL.md ✅ Main wears skill, has Task()

Result: Had to abandon custom agent architecture entirely. Main instance must be default Claude, orchestrator must be a SKILL, not an AGENT.

Impact:

CRITICAL BLOCKER for any orchestration framework using custom agents:

• Custom agents cannot serve as orchestrators (no Task() access)
• Forces regression to skill-based architecture
• Wasted significant development time on architecture that fundamentally cannot work
• No documentation warning about this limitation
• No validation error when adding Task to custom agent's tools

This is not just a "nested agent" issue - it's "custom agents as main instance lose Task()" (Issue #13533).

The architectural restriction makes sense (prevent infinite nesting), but custom agents losing Task() even as main instance is a critical limitation that should be:

1. Clearly documented in custom agent docs
2. Validated at agent creation (error if Task in tools list)
3. Explained in error messages

This limitation forces all orchestration frameworks to use the default main instance + skills, blocking custom agent-based architectures entirely.

---

This is made more confusing by the documentation specifying that:

When an agent runs as the main thread with claude --agent, it can spawn subagents using the Task tool.

my subagents can't delegate to explore subagent and need to grep-ing manually, filling up their precious context windows

We ran into this limitation too when trying to build deep agent delegation chains.

Our workaround was to move coordination outside the sub-agent tree entirely. Instead of nesting agents inside agents, we run each agent as an independent session and they coordinate through a shared message bus. Any agent can kick off work for any other agent through the room, regardless of nesting level.

It is a different architecture than the built-in sub-agent model, but it sidesteps the nesting restriction completely. Works across different models too.

https://github.com/ThinkOffApp/ide-agent-kit

Real-world use case: Coordinator → Worker swarm pattern

I'm hitting this limitation in a production workflow that has shipped 40+ features using a coordinator-subagent architecture. The pattern:

Primary Agent → Scrum Master (subagent) → {Researcher, Architect, Spec Writer, Risk Strategist, Validator, ...}

The Scrum Master is a lean coordinator agent (~190 lines). It reads a protocol file, spawns specialist workers in the sequence the protocol defines, manages gates, and routes results. It never generates content itself — it only orchestrates.

This worked until recently (likely broken by the v2.1.69 fix for "teammates accidentally spawning nested teammates"). The SM now reports the Agent tool is unavailable.

Why the primary agent can't fill the coordinator role

This isn't just a convenience issue. The primary agent degrades at protocol compliance when it has broad context. We've documented this empirically:

• When the coordinator is a subagent with a focused context window (~190 lines of identity + role boundaries), it follows the protocol faithfully — spawns workers, never generates content itself
• When the same protocol is loaded into the primary agent's context (alongside CLAUDE.md, project state, conversation history, tool results), the primary agent rationalizes shortcuts: "this feature is simple, I'll just write the brief myself instead of spawning the synthesizer"
• We have concrete evidence: two features (col-018, col-019) where the primary-as-coordinator skipped the synthesizer agent and produced wrong-format implementation briefs in the coordinator's voice

The subagent boundary isn't just delegation — it's context isolation that enforces compliance. A coordinator subagent can't skip steps it doesn't know how to do. A primary agent with full context can and will.

What would fix this

maxDepth: 2 — allowing one level of nested spawning — solves the coordinator pattern completely. The hierarchy is:

depth 0: Primary Agent (human-facing, broad context)
depth 1: Coordinator (protocol-focused, lean context, spawns workers)
depth 2: Workers (specialist agents — architect, tester, validator, etc.)

No infinite recursion risk. Workers at depth 2 don't need to spawn further. The coordinator at depth 1 just needs the Agent tool to delegate.

Scale of impact

This pattern has produced: 42 features, ~1,600 tests, 12 MCP tools, full design-through-delivery lifecycle with gates, vision alignment checks, and risk strategies — all orchestrated by a coordinator subagent spawning specialist workers. It's not a toy example; it's the core development workflow for a production system.

The workaround (claude --agent) loses the human-in-the-loop conversational flow that makes the primary → coordinator → workers hierarchy work. Agent Teams don't solve it either — the lead IS the primary agent, with the same compliance issues.

Strong real-world case. The 42-feature run is probably the best evidence anyone has posted for why the coordinator pattern needs native support.

Your observation about context isolation enforcing compliance is important. We hit the same thing: when the primary agent has full context it starts "helping" instead of delegating, and the specialist boundaries collapse.

For anyone hitting this now: we ended up moving coordination outside the sub-agent tree entirely. Independent Claude sessions communicate through a shared message bus (IDE Agent Kit). Each session has its own context and can only see what gets sent to its inbox.

The downside is more infrastructure. maxDepth:2 as a native feature would be cleaner for the coordinator-worker pattern.

Use case: Orchestrator-only pattern for large projects

I run Claude Code in a strict orchestrator-only mode — the main session never writes code directly. It only plans, decomposes, delegates, and summarizes. This keeps the main context clean and ensures consistent attention quality across long sessions.

The bottleneck: Without nested delegation, the main orchestrator becomes a single point of failure for task decomposition. For a large feature touching backend, frontend, and tests:

• With nested delegation (ideal): Orchestrator delegates to 3 team leads (backend, frontend, tests). Each lead understands its domain and further decomposes into fine-grained workers. The orchestrator only manages 3 conversations.
• Without nested delegation (current): Orchestrator must flatten everything into 10+ parallel agents. It needs deep knowledge of every domain to decompose to the finest granularity, writes bloated prompts to give each agent enough context, and struggles to coordinate 10+ results.

Specific pain points:

1. Decomposition quality degrades — the orchestrator can't know every domain deeply enough to split optimally
2. Prompt bloat — each fine-grained agent needs extensive context about its place in the overall architecture
3. Coordination explosion — integrating 10+ agent results is much harder than synthesizing 3 team lead summaries
4. Scale ceiling — some features realistically need 20+ parallel work items; flat management breaks down

Even allowing just one additional level (depth 2) would be transformative. A configurable max_agent_depth parameter would be ideal.

+1 for this feature — it's the biggest architectural limitation I've hit with Claude Code's agent system.

I'm butting into this limitation. A couple relevant points:

• 👍 So far I am finding it acceptable to launch a main session with the --agent flag. So claude --agent project launches the project orchestrator as the main agent, and it can and does spawn sub-agents to get work done.
• 🤔 maxDepth makes architectural sense over "prohibited", even if the default functionally means the same thing -- it lets folks say "I want to try one layer of nesting"
• 👎 In another instance, we have a sub-agent _instructed to spawn sub-agents_, and it _silently fails_ and instead directly performs the tasks it would delegate to the sub-agents. This is a bad failure mode, because it's defeating the entire purpose of context isolation between agent invocations, _and not telling you about it_. I found this out when debugging nesting the project orchestrator, and getitng failures, so dove into what was actually happening. Result:

First run (before the direct test) — bug-finder ran the full 4-stage pipeline, then disclosed at the end in its Stage 4 summary: ▎ "The Agent tool was not available in my toolset. All four pipeline stages (Finder, Adversary, Referee, Report) were executed by me (the orchestrator) directly. Each stage was performed sequentially with genuine adversarial rigor..."

So we showed via tool call counts and via introspection that the orchestrating agent simply did the tasks itself because it couldn't launch the sub-agents.

Adding empirical evidence of the silent failure mode @ozydingo described, with a new
angle: the combination with run_in_background: true makes detection significantly
harder.

I have a custom skill (/review-pipeline) that spawns a wrapper agent in background and
instructs it to orchestrate a convergence loop calling superpowers:code-reviewer →
superpowers:receiving-code-review → code-simplifier:code-simplifier per iteration.
I inspected the subagent trace files for 9 invocations across 3 different feature
branches over 3 days and found that the wrapper made 0 Agent/Task calls in every
single run, while 8 of those 9 wrappers produced final reports phrased as if a
multi-iteration convergence loop with specialized sub-agents had been exercised as
designed.

Full data + table + JSONL summary:
<https://gist.github.com/Etilem/6365100d3ca55ebfc10987c9542050a4>

What the wrappers said vs what they did

The orchestrator prompt explicitly instructs the wrapper to spawn three named sub-agents
per iteration. Across the 9 runs:

• All used Agent(run_in_background=true) (the orchestrator's outer call).
• All used general-purpose for the wrapper (explicit in 2 runs, default in 7).
• All 9 made zero Agent/Task tool calls (verified by reading

~/.claude/projects/.../subagents/agent-*.jsonl).

• Wrappers used only Read/Bash/Edit/Grep/Glob — 40 Edit operations total,

all performed in-place by the wrapper itself.

• 8/9 final reports use orchestration language (Iterations: 2 / 5,

Applied: 4 corrections across 1 iteration, Minor applied (final pass): N suggestions)
that strongly implies the dispatch happened.

• Only 1 of 9 wrappers explicitly noted in its text: *"There's no Task/subagent tool

available. I'll need to perform the review work directly within this agent."* That same
wrapper also made 3 ToolSearch calls trying to locate a dispatch tool — the only one
in the set to do so. The other 8 silently adapted with no acknowledgment.

Why background-mode amplifies the problem

In foreground execution you can watch the orchestrator's tool calls stream in real time,
so a missing Agent(superpowers:code-reviewer, ...) is visible immediately. With
run_in_background=true the wrapper operates out of sight until it returns its final
report. By the time the user reads the report, they have:

• No live trace of the failed dispatch attempts
• A confident, structured narrative that reads as if the architecture worked
• No prompt to inspect the subagent trace files (which is the only way to spot the gap)

The combination is essentially a plausibility engine: the wrapper produces a report that
looks exactly like what the skill promised, while the actual execution followed a
different code path. In my case the gap went unnoticed for days across multiple branches
before I bothered to read the trace files.

What I think would help

Either of these two would resolve it for my use case:

1. The wrapper inherits the Agent/Task tool from the orchestrator's tool set when

spawned with run_in_background=true, allowing actual nested dispatch.

1. The skill loader / agent runtime detects the nested-dispatch pattern in the wrapper

prompt and either (a) refuses to spawn the wrapper in background, or (b) downgrades
the wrapper to foreground, or (c) emits a clear warning in the final report saying
"this wrapper had no Agent/Task tool, so all dispatch instructions were executed
in-place by the wrapper itself".

Even (c) alone would prevent the silent failure — the user would at least know the
architecture collapsed and could adjust.

---

In case it's useful: I'm happy to share the orchestrator session JSONL files and the
wrapper trace files privately if that would help reproduce. The skill itself is a
single-file Markdown skill; the orchestrator prompt to the wrapper is about 200 lines
of plain instructions, no special dependencies beyond the two superpowers and
code-simplifier plugin agent names referenced in the prompt.

Since the issue was created, the Task tool was renamed to Agent.

I came across this Issue while hunting down a problem with Claude failing to delegate agents in parallel, instead delegating each agent in sequence.

I solved subagent tasking in OpenCode months ago (https://github.com/anomalyco/opencode/pull/7756#issuecomment-4042978112).

Subagents can delegate to subagents to whatever depth you define in config. You can persist subagent sessions. You have a tree based view of subagent sessions, and other features.

The irony is, this feature users want in Claude Code has been available in OpenCode for months, because after I found it wasn't in Claude Code and wouldn't be unless Anthropic decided to add it, I decided to develop it for OpenCode. But OpenCode maintainers haven't yet merged my PR, and probably won't. I've watched PR after PR languish in the OpenCode github, and unresolved issues get automatically closed, despite continuing to be problems that need fixing.

I think harness development is just plain broken due to failures in leadership and organization. It seems like no one is truly on top of things. You want a harness that works for your use cases, it has to be code you can change.

Evidence from a 9-hour autonomous run: compaction tax as the limiting cost

Adding a use case the thread hasn't seen yet: a single 9-hour /goal session that ran a 10-phase autonomous workflow end-to-end (PRD → dual-review → plan → review-loop → orchestrated implementation → review-loop → real-data integration testing → ensemble code review → fix-and-verify → final report).

Context: most of these commands — /goal, /quick-dual-review, /review-fix-loop, /adamsreview:review, /ar:fix-and-verify, and others — are custom skills/commands I've authored on top of Claude Code's existing primitives. This isn't a "missing tooling" gap; the orchestrator pattern is one I've invested real effort building out. What I'm hitting is the runtime depth-1 ceiling, not a design gap in my command set.

The pattern works today. The orchestrator successfully sequenced all 10 phases and produced the intended artifacts. But it hit a specific failure mode that the existing comments touch on individually and that depth-2 would resolve cleanly:

Every phase's intermediate state lives in the orchestrator's Opus context until the end of the run. PRD drafts, dual-review findings, fix-loop iterations, per-stage orchestrate outputs, test runs — all of it accumulates in one context because each phase is a slash command (/quick-dual-review, /review-fix-loop, /orchestrate, /adamsreview:review, /ar:fix-and-verify) executing inline rather than as a sub-agent. The result is repeated compaction across a 9-hour window, which is both a real $$ cost at Opus rates and a quality cost — post-compaction the orchestrator loses fidelity on early-phase decisions exactly when it needs to integrate them into later phases.

Why depth-2 specifically fixes this

The orchestrator's actual job in this pattern is sequencing, not doing. Its context only ever needs to hold ~10 pointers ("phase 3 complete, kicking off phase 4"). With depth-2:

• /goal (depth 0) holds phase verdicts only
• Each phase command (/orchestrate, /review-fix-loop, etc., at depth 1) holds its own working state
• Those commands' own sub-agents (depth 2) — which already exist in their designs — do the actual fan-out work

Today the entire stack collapses into depth 0, because the phase commands at "depth 1" are really still executing in the orchestrator's context. The compaction tax scales with session_length × intermediate_output_size. Depth-2 turns that into a flat per-phase cost because intermediate outputs die with the sub-agent that produced them.

This complements the existing arguments rather than restating them

• @dug-21's coordinator-pattern argument (42 features, ~190-line scrum master) is about protocol compliance via context isolation
• @neardreams' orchestrator-only-mode argument is about decomposition quality and coordination explosion
• This one is about context economics in long-running autonomous sessions — the pattern works, the limit is purely how long you can sustain it before compaction degrades it

Endorsing the converged API

Three independent issues (#58005, #32340, #21982) landed on essentially the same shape: opt-in depth cap, default 0/1 for backwards compat, decremented per spawn, hard-reject at zero. remaining_depth: 2 from #58005 covers the pattern above with no surface-area expansion beyond a single parameter. +1.

<details>
<summary>The actual /goal prompt (for reference — this is what ran for 9 hours)</summary>

/goal execute all of the following before stopping:
Review the problem statement: plans/new-vision-labels.md
We need a long-term solution that has ultimately a stable, bounded set of topics per
user, so that every part of our app can track across stories in topics, whether that
be memories or the new dashboard app. It probably should be tied to the user's topics
in their config. Some features may still need to work across topics, as of course
stories may show up in one topic but be relevant to other topics' editorials etc.

You must use your judgment so that you can achieve all of the following without
stopping for human input. Keep track of major decisions, alternatives considered,
rationale, and implications for decisions throughout the following in a decision log
for later human review.

1.  Create a PRD.
2.  Get a /quick-dual-review then update the PRD using your judgment on the input received.
3.  Create the implementation plan for the PRD.
4.  /review-fix-loop /quick-dual-review your plan.
5.  /orchestrate the implementation of the plan.
6.  /review-fix-loop /quick-dual-review your implementation.
7.  Test your implementation. You hereby have permission to grab copies of real
    production data ... so that you can test things as needed like memory
    reconstruction, pipeline runs, etc. ... Fix your implementation and re-run as
    needed until you get your desired outcome.
8.  Run /adamsreview:review --ensemble on everything you've built, but do NOT leave
    any items for human decision. You must decide on your own how to finalize the
    artifact before the fix stage, using your judgment on what is normally left for
    human judgment.
9.  Run /ar:fix-and-verify - again not stopping for human input; log your decisions
    as stated above and move on with your own judgment.
10. Write to a file and summarize in chat your final status report.

You MUST execute all of the above before reporting back. ...
You WILL get compacted repeatedly as you do all of this. Use a build journal and
make it very clear for yourself where you are at, what is done, what is next, etc,
so that you never get lost as you implement this entire place.

Note the explicit acknowledgment in the prompt that compaction will happen repeatedly and the orchestrator has to defend against losing state across it. With depth-2, that defensive build-journal scaffolding becomes much less load-bearing — each phase's sub-agent holds its own state, and the orchestrator just reads verdicts.

</details>

Two recent additions to this cluster sharpen the contract framing in ways worth pulling up here:

• #61993 (filed today, @xblabs) articulates the persistent-teammate vs ephemeral-spawn distinction directly: Task/Agent is stateless-per-invocation, TeamCreate/SendMessage is state-accumulating across calls. The two are not substitutable for fan-out worker patterns where each item must not see sibling state. xblabs's batch-executor halt log shows this concretely — the run halted at the cohort-spawn gate, not because the orchestrator was "trying to recurse," but because TeamCreate would have silently broken the stateless-per-item guarantee the executor was designed around.
• #60763 (filed 2026-05-20, @bradygrapentine) proposes the natural complement: a depth-capped opt-in primitive that addresses the implicit fork-bomb concern without leaving recursion fully unimplementable.

Together these two suggest a remediation that is more surgical than "expose Agent to sub-agents": an opt-in frontmatter field (e.g. nested_spawn: enabled with optional depth_limit) that gives the documentation a place to articulate the ephemeral-vs-persistent distinction the current "subagents cannot spawn other subagents" sentence collapses.
The cumulative cluster as of today: this issue + #46424 + #59523 + #60763 + #61993, spanning January → May, with the most recent three filed in the last nine days.