Sub-agents cannot spawn other sub-agents: `Task`/`Agent` primitive not exposed in nested contexts

[xblabs]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Sub-agents spawned via the Agent tool cannot themselves spawn nested sub-agents. The Task / Agent ephemeral spawn primitive is available to the top-level Claude Code session, but it is silently filtered out of the tool surface inside spawned sub-agent contexts, even when the agent definition's frontmatter declares tools: All tools (or leaves tools: unset, inheriting defaults).

This is a contract mismatch. The frontmatter promises full tool access; the runtime delivers a restricted set. Only the persistent-teammate primitive (TeamCreate / SendMessage / TeamDelete) is reachable from within a sub-agent, which breaks the ephemeral fresh-context spawn pattern that hierarchical orchestrators are designed around.

Affected agent surface from inside a sub-agent context (Claude Code, Opus 4.7):

• Present: TeamCreate, TeamDelete, SendMessage, TaskOutput, TaskStop, plus standard file/shell tools.
• Absent: Task, Agent.

The sub-agent has no way to detect this silently-filtered state at startup. The failure surfaces only at the first attempted nested spawn, which makes it look like a manifest or task problem when it is actually a harness configuration gap.

What Should Happen?

Sub-agents declared with tools: All tools (or tools: unset) should have Task / Agent accessible from within their own context. The frontmatter contract should match the runtime tool surface.

If filtering nested-spawn primitives at depth > 1 is intentional (for example security or cost containment), then ONE of the following should be true:

1. The restriction is documented in the agent-definition spec, so authors do not design hierarchical orchestrators that silently halt at runtime.
2. The restriction is opt-in-able via an explicit frontmatter field, for example nested_spawn: enabled, defaulting to current restricted behavior but allowing authors to declare hierarchical-orchestrator intent.
3. The restriction emits a structured error or warning when the sub-agent attempts a nested spawn, instead of behaving as if the tool simply was not requested.

Of these, option 1 (just expose the primitive) is preferred because the existing agent-definition frontmatter already declares the contract. Option 2 is acceptable if there is a real reason to default-deny. Option 3 alone is insufficient because it leaves the orchestrator pattern unimplementable.

Error Messages/Logs

There is no error message at the harness layer. The failure mode is silent at spawn time. The sub-agent observes its own tool surface and halts based on what it sees.

Below is the run log emitted by my batch-executor sub-agent (a real CLO batch invocation, 4 tasks) when it discovered the gap at the cohort spawn step:

---
# Run Log: BATCH_2026_05_24_canon_clo_cohesion_partition

## Halt Rate
- halted_items: 0
- dispatched_items: 0
- skipped_items: 0
- halt_rate: undefined

## Halt Causes

## Items
(No items reached the per-item dispatch gate. The batch halted at the cohort-spawn stage; see Run Outcome below.)

## Run Outcome

Status: failed (contract-floor halt at wave_1 cohort spawn)
Halt point: batch-executor Process Step 3 (Execute Path), immediately before the wave_1 cohort spawn.
Cause: The harness exposes no per-item ephemeral subagent-spawn primitive (Task / Agent). Only TeamCreate (persistent teammate model) and SendMessage are available. The batch-executor spec requires spawning one fresh worker per checklist item with stateless single-iteration context. This contract is non-negotiable per the CLO pattern.

TeamCreate would create persistent teammates that accumulate cross-item context across turns, violating the worker's stateless-per-invocation guarantee. Adopting it is a substantive contract change requiring sandbox validation, not a like-for-like swap.

What was NOT executed:
- No worker spawn attempted (primitive absent).
- No work-items dispatched.
- No commits made.
- No files modified.
---

The sub-agent's final-message verdict to its parent orchestrator was:

"Halt point: pre-spawn for wave_1 cohort. No worker received a prompt. Zero commits, zero checklist mutations. Harness exposes no per-item ephemeral subagent-spawn primitive. TeamCreate would violate clo-executor persistence: stateless frontmatter and the fresh-context-per-item contract."

No stack trace. No exception. No console error from the Claude Code CLI itself. The gap is observable only by the sub-agent introspecting its own available tools.

Steps to Reproduce

Minimal reproduction in any Claude Code workspace.

Step 1. Create a parent orchestrator agent definition at .claude/agents/repro-parent.md:

---

name: repro-parent
description: Reproduction harness for nested-spawn gap. Attempts to spawn a child sub-agent from within itself.
model: opus
tools: All tools

Repro Parent

When invoked, attempt to spawn a child sub-agent named repro-child via the Agent tool. Report whether the spawn primitive was available in your tool surface, and what tools you observed (specifically: was Task or Agent present, or only TeamCreate / SendMessage?). Do not actually do any real work.

---

Step 2. Create a child agent definition at .claude/agents/repro-child.md:

name: repro-child
description: Trivial leaf worker for the nested-spawn reproduction.
model: haiku
tools: All tools

Repro Child

Return the string "child reached" and exit. No file operations needed.

---

Step 3. From a top-level Claude Code session, invoke the parent orchestrator:

Agent(subagent_type="repro-parent", prompt="Attempt to spawn repro-child via Agent. Report tool surface inventory.")

Step 4. Observe the parent agent's response.

Expected: the parent successfully spawns the child, the child returns "child reached", and the parent reports Task / Agent was available in its tool surface.

Actual: the parent reports that Task and Agent are absent from its tool surface; only TeamCreate, SendMessage, TeamDelete, TaskOutput, TaskStop (plus standard non-orchestration tools) are present. The child is never spawned.

Step 5. To confirm this is a nested-context restriction and not a global one, run from the same top-level session:

Agent(subagent_type="repro-child", prompt="say hello")

Expected and actual: this works fine. The child returns "child reached". The Agent primitive is available at the top level. Only the nested context filters it.

Notes:

• Both agent definitions declare tools: All tools in frontmatter, which should grant access to every available tool including the orchestration primitive.
• No .claude/settings.json permission rules or hook configurations affect this; the filtering is at the harness layer.
• Reproduction was observed on Windows 10 with Claude Code CLI, model Opus 4.7, date 2026-05-24.

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.1.146

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Cursor

Additional Information

No response

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Sub-agents can't create sub-sub-agents, even with Task tool access #19077
2. [BUG] Agent tool not available to sub-agents — prevents orchestrator pattern #46424
3. Task tool unavailable from inside sub-agent — collapses multi-role orchestrators to single-agent execution #59523

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

[yurukusa]

The contract-vs-runtime gap you articulate here is the part the cluster hasn't named explicitly yet, and it is worth pinning down because the documentation language elides it.
Cluster context (so the auto-close bot has a fair chance of being wrong here)
The bot grouped this with #19077, #46424, and #59523 — and the same shape also shows up in #60763 (filed 2026-05-20, no comments yet). Across those five reports the timeline is January → April → May (×3) → today, with cumulative comment counts of 18 + 7 + 4 + 0 + 1 and reaction counts of 11 + 1 + 2 + 0 + 0 on the opening posts alone. That is not "one user's design preference," it is a four-month-old structural ceiling that re-surfaces each time a new orchestrator author hits it. Worth pushing 👎 on the duplicate-detector comment so this thread stays open for the new framing.
The distinction the documentation doesn't make
The docs sentence "Subagents cannot spawn other subagents" reads as a single rule but it is hiding two different primitives with different operational semantics:

• Task / Agent — ephemeral, fresh-context, stateless per invocation. Lifecycle is bounded by the spawn call. Suited to fan-out worker patterns where each item must not see sibling state.
• TeamCreate / SendMessage / TeamDelete — persistent teammate. Lifecycle is owned by the spawner. State accumulates across SendMessage calls. Suited to long-lived collaborator patterns.
  Your batch-executor run log makes the operational consequence explicit: substituting TeamCreate for Task is not a like-for-like swap. It silently changes the worker's persistence guarantee from stateless-per-item to accumulating-across-items, which violates the very contract the executor was designed around. The 4-task CLO batch halted at the cohort-spawn gate for that reason, not because the orchestrator was "trying to recurse."
  That distinction matters because the existing thread ([BUG] Sub-agents can't create sub-sub-agents, even with Task tool access #19077) has been read by some commenters as "I want recursion for its own sake." What you and @ariccio (one layer more) and @dug-21 (coordinator-worker pattern, 40+ shipped features) and @adamjgmiller (9-hour /goal session, compaction tax) and @ThinkOffApp (external coordinator workaround) are actually describing is a single missing primitive: ephemeral per-item spawn from inside a sub-agent context, with the parent's stateless-context contract preserved. TeamCreate is not that.
  Frontmatter contract
  tools: All tools (and the unset default) is a contract surface that the agent author reads to design around. When the runtime silently filters Task / Agent out of that "all," there is no in-agent way to detect it at startup — only at first attempted spawn, by which point the agent has already entered its execute path. From the sub-agent's introspection point of view, the harness behaves as if the author had written tools: Read, Edit, Bash, ... and forgotten to add Task. That is exactly the failure shape that makes the gap look like a config bug rather than a harness restriction.
  Your three remediation options are well-sized. To push on Option 2 a bit: an explicit opt-in field like nested_spawn: enabled would also give the documentation a natural place to articulate the ephemeral-vs-persistent distinction above, which the current "subagents cannot spawn other subagents" sentence collapses.
  External-coordinator workaround (partial)
  For anyone arriving from search before this is resolved: moving the orchestrator out of the sub-agent tree, as @ThinkOffApp described ([BUG] Sub-agents can't create sub-sub-agents, even with Task tool access #19077, 2026-03-01) and as you allude to with the "external coordinator" framing, is the only currently-viable pattern that preserves the ephemeral-spawn contract. The trade-off is that all cross-item coordination state has to be reified into files (work queue, progress ledger, halt log) because the parent can no longer hold it in-context. The pattern works, but it is strictly more operational scaffolding than the in-harness primitive would require, and it places observability burden on the operator rather than the harness — which is the surface this cluster is implicitly asking the harness to take back.
  — independent observer; the operator-side observability gap around sub-agent dispatch is a topic I have been documenting separately, happy to share notes off-thread if useful.

[yurukusa]

Promoted the cluster framing to an evergreen reference so the contract distinction has a stable URL outside the issue thread: https://gist.github.com/yurukusa/cf477f03f03d9f93c184f1fb7d894f96 (1,775 words).
It consolidates the contract-surface-vs-runtime articulation from your bug report, the depth-capped opt-in proposal from @bradygrapentine on #60763, the external-coordinator workaround from @ThinkOffApp on #19077, and the four-month / five-report cluster context so newcomers landing from search have one place to read before filing a sixth duplicate.

[xblabs]

yurukusa - the contract-vs-runtime articulation is the upgrade. The local framing here had "the harness silently filters the primitive" but didn't pin down why that filtering matters structurally, which is the part that turns "annoying limitation" into "contract violation." Your two-primitive table is the substantial piece. I have absorbed it as the canonical local statement of the gap (referencing your gist as the external anchor).

On operator-observability - yes, would value notes. I've reified the external-coordinator pattern across four agents (planner / executor / per-item worker / scrutinizer) with cross-item state pushed to files: a run_log.md schema (halted_items, dispatched_items, skipped_items, halt_rate, halt_causes), sentinel logs, and a halt-reason taxonomy that ties each halt to a structured cause rather than free-text. The 80-second cooperative-shutdown finding from our empirical probe sits in that taxonomy - the kind of timing data that only surfaces once you've already invested in the observability primitives.

My repo is private for now, but happy to share excerpts directly: the run_log schema, the halt-reason taxonomy, and the four-ground analysis from our 2026-05-24 probe. Could send via a gist or whatever channel suits you.

Curious especially about what failure modes you've seen in the operator-side observability gap that we haven't instrumented for yet.

[abhinas90]

We hit this in our 4-agent fleet. Sub-agents that need to delegate (e.g., code-review agent spawning a linting sub-agent) silently fail.

Workaround: flat agent pool with file-based handoffs. When a sub-agent needs delegation, it writes a handoff.md with task + context. The orchestrator picks it up and spawns the next agent. More overhead but works reliably.

The real fix: the Agent tool should either support nesting or explicitly declare "does not support nesting" in its tool description so the model stops trying.

[xblabs]

Found 3 possible duplicate issues:

1. [BUG] Sub-agents can't create sub-sub-agents, even with Task tool access #19077
2. [BUG] Agent tool not available to sub-agents — prevents orchestrator pattern #46424
3. Task tool unavailable from inside sub-agent — collapses multi-role orchestrators to single-agent execution #59523

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

---

Pushing back on the duplicate-close. This filing overlaps with #19077, #46424, #59523, and #60763 in symptom, but adds material the earlier reports don't cover:

1. A reproducible minimal harness (the parent + child agent definitions in the Steps to Reproduce section) that isolates the gap from any specific orchestrator pattern.

2. The contract-vs-runtime articulation @yurukusa elaborated above and consolidated in the gist (https://gist.github.com/yurukusa/cf477f03f03d9f93c184f1fb7d894f96): the docs sentence "subagents cannot spawn other subagents" hides two distinct primitives with different lifecycle and state semantics. Task / Agent are ephemeral and stateless; TeamCreate / SendMessage / TeamDelete are persistent and accumulate state across calls. Substitution between them is not like-for-like. It silently changes the worker's persistence guarantee.

3. Operational consequence at the harness-contract layer: with tools: All tools declared in agent frontmatter, the agent author has no in-agent way to detect the filtering at startup. Failure surfaces only at first attempted nested spawn, which makes the gap present as a config bug rather than a harness restriction.

Across the cluster, cumulative engagement on the four prior filings is 30+ comments and 14+ reactions, filed January, April, May ×2, and today. Not duplicate noise. A four-month-old structural ceiling that re-surfaces each time a new orchestrator author hits it.

Requesting the thread stay open while the contract distinction propagates.

[xblabs]

We hit this in our 4-agent fleet. Sub-agents that need to delegate (e.g., code-review agent spawning a linting sub-agent) silently fail.

Workaround: flat agent pool with file-based handoffs. When a sub-agent needs delegation, it writes a handoff.md with task + context. The orchestrator picks it up and spawns the next agent. More overhead but works reliably.

The real fix: the Agent tool should either support nesting or explicitly declare "does not support nesting" in its tool description so the model stops trying.

abhinas90 - sounds like you hit the same architectural endpoint. Your handoff.md is structurally what I call run_log.md plus a sentinel-log directory. Different surface, same shape: cross-item state lives on disk because the parent can't hold it in context. Reassuring to see the pattern converge from a different angle.

Strong agree on the tool-description fix as the low-cost intermediate. Right now the model sees Task in its training data, tries to invoke it from sub-agent contexts, harness silently filters. If the tool description declared "not available in nested sub-agent contexts" three things stop bleeding:

• Agent authors stop designing hierarchical orchestrators that silently halt in production
• Models stop burning tokens on retries before the failure surfaces (your fleet's silent-fail observation)
• Maintainers stop triaging as if it's a config bug rather than a documented restriction

That's the same as Suggestion #3 in this filing. Independent arrival strengthens the case.

[yurukusa]

xblabs — the run_log schema you described (halted_items, dispatched_items, skipped_items, halt_rate, halt_causes) is structurally sound for the observable-halt surface. The failure modes I want to flag are the ones that sit outside that surface — they don't trip your halt-reason taxonomy because they don't present as halts at all. They present as completions, dispatches, or silent state drift, which is why most operator-side observability tooling misses them on first instrumentation pass.

Four modes I'd add to the taxonomy, each with the instrumentation shape that catches them:

1. Dispatch fabrication — parent narrates a successful spawn that never happened at the OS / harness layer.

The shape: Agent.dispatch() returns "Spawned successfully", the parent's narrative continues as if the worker is running, but the subprocess died at the harness boundary (pty absence, env misconfig, stdin contract mismatch). Issue #60987 is the canonical filing — spawn succeeded in narrative, subprocess died on "Input must be provided either through stdin or as a prompt argument", parent kept reporting in-progress for the full session.

Why your current schema misses it: dispatched_items is incremented from the parent's view of the call, not from the worker's actual liveness. You log "I dispatched it" and then later log "I halted because the worker didn't respond" — but the worker was never alive.

Instrumentation: a sibling hook on PreToolUse(Agent | Task) that emits a structured receipt before the parent agent can narrate outcome. The receipt records dispatch_id, target_subagent, scope_hash, spawn_timestamp. The completion path then has to reference the dispatch_id and the parent's "dispatched" counter only increments from receipts that have a matching post-spawn liveness probe (any tool call from the child within N seconds of spawn). Without that, you're trusting the parent's narrative against itself.

2. Silent stall on permission gate — subprocess alive but blocked, no signal propagation to parent UI.

Different shape from #60987. Sub-agent successfully spawned, hit an MCP permission prompt or permissions.deny rule, and is now waiting on operator approval that never surfaces in the parent's UI. Issue #61315 is the canonical filing. Operator sees "sub-agent working" indefinitely; sub-agent is sitting on a modal it cannot see.

Why your wall-clock watchdog catches the symptom but not the cause: your 80-second cooperative-shutdown finding is exactly the kind of timing data that surfaces here, but it tells you the worker stopped responding — it doesn't tell you whether that's a runtime crash, a permission gate, or a model loop. The halt-cause classification has to come from a separate channel.

Instrumentation: pre-dispatch enumeration. Before spawn, walk the worker's intended tool surface and the project's permissions.deny rules. If any tool in the worker's likely call path is gated by a permission prompt that the parent cannot satisfy, refuse to spawn and return a structured error to the orchestrator. (Closest existing public reference for this pattern is PR #286 on cc-safe-setup — dispatch-allowlist-preflight — but the principle generalizes.)

3. Scope expansion drift — worker accepts task A, completes task B, returns "done."

Shape: orchestrator dispatches worker with scope = {update auth middleware}. Worker reads the surrounding code, decides the cleaner fix is to refactor the entire request pipeline, makes 40 file edits across that surface, returns final message "Auth middleware updated and tested." Run log shows item completed. No halt. No error. The scope contract was violated, but the violation is invisible to the schema because the worker's final message reads as completion.

Why your schema misses it: dispatched_items - halted_items - skipped_items = completed_items, and "completed" trusts the worker's final-message verdict. There is no per-item audit that the work actually delivered matches the scope declared at dispatch.

Instrumentation: scope_hash on the dispatch receipt (mode 1), plus a post-completion gate that asks the orchestrator (not the worker) to verify the actual file change set fits within the declared scope. If the worker touched files outside the dispatch scope, the item logs as scope_drift rather than completed. Cheap to instrument once mode 1's receipts exist. Issue #61102 is the cleanest field example I've seen — Awis dispatched a subagent for a 1-file refactor, worker extended to 12 files silently, the surface that caught it was a manual diff review after the run completed.

4. Claim-verify gap — completion narrated, verification tool call absent from the tool-use log.

Shape: worker's final message says "Migration applied successfully and verified against staging." Tool-use log shows: 12 edits, 3 bash calls (none of them the verification command), no read-back of the staging endpoint. The completion claim has no tool evidence behind it. Structurally a peer of mode 3 but lives one layer up: not "did the work match the scope" but "did the verification step the worker claimed to perform actually happen at the tool layer."

Why your schema misses it: same root as mode 3 — completed trusts the worker's final-message verdict. The tool-use log is the ground truth, and most run-log schemas don't cross-check the narrative against it.

Instrumentation: a verifier-pass step in the orchestrator that, on receipt of a completion, scans the worker's tool-use log for the specific tool call (or call class) the completion claim depends on. If the claim is "verified via curl" and there is no Bash(curl ...) invocation in the log, the item logs as claim_unverified rather than completed. The verifier doesn't have to understand the work — it just has to grep the tool log for the tool-call shape the claim implies.

---

Cross-cutting note on schema. All four modes resolve to the same underlying instrumentation primitive: tool-layer ground truth must be the source of completed / dispatched classifications, not the agent's narrative. Your run_log gets the halt surface cleanly; what's missing is the symmetric audit on the non-halt paths.

I have a small public diagnostic that walks an operator through whether their setup is exposed to modes 1–3 (12 yes/no symptoms, maps to PR references and to specific cc-safe-setup hooks): https://gist.github.com/yurukusa/c87e440b6d0ccf8b464d53685a3a30f6 — not a substitute for in-fleet instrumentation, but useful as a one-shot triage before deciding which of the four modes to instrument first in a new fleet.

Happy to receive your run_log schema, halt-reason taxonomy, and the four-ground analysis — gist or whatever channel is convenient. The 80-second cooperative-shutdown timing finding is the kind of data I haven't seen published anywhere and would value seeing in shape.

I'm consolidating field notes from the cluster (#19077 → #60763 → this filing, plus the dispatch / stall / scope failure surfaces I've been collecting from adjacent threads) into a longer-form writeup landing 2026-05-27. If the timing works I can route a draft of the dispatch-fabrication and silent-stall chapters past you before publication — your run_log instrumentation would be the strongest existing field reference I could cite, and the inverse direction (failure modes outside your halt taxonomy) is exactly the cross-check that would make the writeup more useful to the next fleet operator landing in this thread.

[xblabs]

yurukusa - This is a genuine upgrade to my taxonomy. All four modes describe gaps in my current aproach. None of them trip my halt counters because, as you said, halt is the wrong axis to count them on. The cross-cutting principle, tool-layer ground truth as the source of completed / dispatched classifications, not the agent's narrative, is the part that reframes the schema rather than extends it.

Quick mapping to where each mode would land in my current shape:

• Mode 1 (dispatch fabrication): the receipt-with-liveness-probe pattern fits into my pre-dispatch gate (currently in batch-executor Process Step 0). That gate halts loudly when the spawn primitive itself is absent (the [BUG] Sub-agents can't create sub-sub-agents, even with Task tool access #19077-cluster symptom). It should also emit a structured dispatch receipt and gate completion-counter increments on a matching post-spawn liveness signal. The receipt fields you listed (dispatch_id, target_subagent, scope_hash, spawn_timestamp) translate cleanly into my existing schema.

• Mode 2 (silent stall on permission gate): my 80s finding catches the cooperative-shutdown timing but, as you flagged, conflates runtime crash / permission gate / model loop into one bucket. The pre-dispatch enumeration of intended tool surface against permissions.deny rules would split the bucket. I'd need a permission-gate halt-reason as a separate taxonomy entry.

• Mode 3 (scope expansion drift): my completed = dispatched - halted - skipped formula does trust the worker's final-message verdict, and I have no post-completion file-set audit. The scope_hash + post-completion gate path is the right shape. Would slot into the pre-dispatch gate's response-handling step.

• Mode 4 (claim-verify gap): closest existing analogue in my stack is a scrutinizer agent (per-task spec audit + per-issue 5-question framework), but it runs at task-completion time on the spec, not on the worker's tool-use log mid-execution. Your verifier-pass shape, grep the tool log for the claim-implied call shape, is a lighter, faster check that would catch the gap before it reaches the scrutinizer. Need to think about that.

The receipt-as-source-of-truth principle is what links all four. Useful reframe.

On the artifacts you asked for: will compile the run_log schema, the halt-reason taxonomy, and the four-ground probe analysis as gist excerpts and route them. Will flag any places where my current shape would need the four-mode extensions before it's worth citing.

Cross-citation works. Your dispatch-fabrication and silent-stall chapters as the inbound reference, my run_log use as your outbound field reference. Happy to review the two chapters before pub if a draft window opens. Route whenever it's ready.

Reading the diagnostic gist now (c87e440b6d0ccf8b464d53685a3a30f6). The 12-symptom walkthrough looks like the triage layer this work needs.