claude-code - 💡(How to fix) Fix Task tool unavailable from inside sub-agent — collapses multi-role orchestrators to single-agent execution

Summary

The Task tool is not available from inside a sub-agent in Claude Code. Orchestrator agents that try to dispatch their own children fail and fall back to inlining the work as a single agent — collapsing multi-role specialist designs to one-agent-doing-N-jobs sequentially. The limit is undocumented in the agent definition format, so designs only discover it at runtime.

Reproduction

1. Define an orchestrator sub-agent (~/.claude/agents/orchestrator.md) whose body says: "Dispatch two child sub-agents in parallel via the Task tool."
2. Invoke it from the main session.
3. The orchestrator does not have Task in its tool list. It typically proceeds to do both jobs itself, sequentially, inline.

Observed in

A bake-off comparing a 5-role planning cell (Lead Strategist + Research Director + Devil's Advocate + Sandbox Verifier + Decision Recorder) against a simpler Plan-architect shape. The 5-role design assumed it could fan out 5 children from a parent orchestrator. The continuation agent's run notes report:

Target: 2 parallel sub-agents (Sandbox Verifier + Decision Recorder) via Task/Agent tool. Actual: Task/Agent tool not available in this execution environment. Both roles executed inline by Lead Strategist (this session).

The independent judge's verdict flagged this as the structural ceiling of the experimental arm: the 5-role org chart produced "5 sequential reasoning passes by one agent," not 5 parallel work-streams.

Impact

Any multi-role orchestration that needs more than one level of parallel sub-agent dispatch collapses to sequential single-agent work. In the bake-off, a 5-role cell intended to fan out across 5 parallel children collapsed to 1 agent doing all 5 jobs sequentially — paying the design cost of org-chart specialization with none of the parallelism benefit. This silently invalidates a common architectural pattern (parent-orchestrator with N specialist children) that the agent definition format appears to support.

Workarounds

Top-level shell orchestration via claude --bg from a launch script works, because each session is a top-level invocation and gets Task. The downside: loses in-process ergonomics (shared context, structured returns, integrated TodoWrite) and forces filesystem handoffs.

Request

Either:

• (a) Expose Task to sub-agents with a configurable depth limit (e.g., max 2 levels) to prevent runaway recursion, or
• (b) Document the limitation in the agent definition format so designs stop assuming nested parallelism.