[Bug] Subagent tool stripped in nested subagent calls breaks tool invocation

[omar-codes]

Bug Description

The subagents docs state the Agent tool is
inherited by subagents, so a subagent can spawn nested subagents (documented depth cap: 5). In
practice, a subagent spawned with subagent_type: "general-purpose" or "claude" comes back
with no Agent/Task launch tool in its active or deferred set — so it cannot spawn a
nested subagent at all (depth 1 → 2 is impossible), regardless of the depth cap.

The strip is inconsistent: a fork subagent does inherit Agent. So the launch
primitive is not globally removed — it is removed specifically from the fresh non-fork subagent
types the docs say should keep it.

Expected: a general-purpose/claude subagent inherits Agent and can launch nested
subagents up to depth 5, per the docs.

Actual: general-purpose and claude subagents have no Agent/Task tool and are leaf
agents. Only fork retains it.

Reproduction — from a top-level session that has the Agent tool, spawn a probe subagent
and ask it to inventory its own tools and attempt to launch a sub-subagent:

• subagent_type: "general-purpose" → launch tool = NONE; cannot nest.
• subagent_type: "claude" → launch tool = NONE; cannot nest.
• subagent_type: "fork" → Agent tool present (inherited full parent surface).

Observed tool inventories:

• general-purpose active: Artifact, Bash, Edit, Read, Skill, ToolSearch, Write; deferred:
  EnterWorktree, ExitWorktree, Monitor, NotebookEdit, SendMessage, TaskStop, WebFetch, WebSearch.
  No Agent/Task.
• claude — same as above. No Agent/Task.
• fork active includes Agent.

Impact: any workflow that runs a fan-out skill inside a subagent breaks. Example: an
orchestrator spawns a code-review skill as a subagent, and that skill is designed to launch
several parallel independent reviewers; with no Agent tool the fan-out silently degrades to a
single-context inline pass, losing the reviewer independence that is its whole purpose.

Suggested fix: honor the documented inheritance — freshly-spawned general-purpose/claude
subagents should retain Agent (subject to the depth-5 cap), matching fork. Or, if
single-level nesting is intended for these types, correct the docs.

Environment Info

• Platform: darwin
• Terminal: Apple_Terminal
• Version: 2.1.217
• Feedback ID: ab7ee1d8-4d11-4f64-9b78-7df5c4717cc6

Errors

[]

[maw501]

Confirming this independently on the same build - macOS (Darwin 25.5.0), Claude Code 2.1.217,
homebrew install. My general-purpose tool inventory matches yours exactly.

Two additional data points that narrow the cause.

1. It is not frontmatter parsing.

#80104 reports the same bug and attributes it to Agent being dropped from an explicit
frontmatter tools: list. That isn't the mechanism. I tested three request paths and all three
fail identically:

• built-in general-purpose / claude (documented as Tools: *)
• a custom agent listing Agent explicitly in tools:
• a custom agent omitting tools: entirely, so it inherits the full parent tool surface

The third case is the informative one - there is no list to mis-parse, and Agent is still
withheld. So the tool is being filtered at provisioning, not lost while resolving frontmatter
entries.

2. The error string suggests a deliberate gate, not a missing registration.

Calling Agent from inside a subagent returns:

No such tool available: Agent. Agent exists but is not enabled in this context.
Use one of the available tools instead.

ToolSearch with select:Agent separately returns No matching deferred tools found, so it
isn't merely an unloaded deferred tool either. The harness knows the tool exists and is
declining to provision it to the subagent.

Also ruled out

• Version threshold - 2.1.217 is well past the documented 2.1.172
• Local config - no disallowedTools and no relevant env var in project or user settings.json
• Session context - reproduces identically in an IDE child session
  (CLAUDE_CODE_CHILD_SESSION=1) and in a fresh top-level claude -p session

One correction to scope, re #80104

That issue also reports ToolSearch being stripped from subagents. I can't reproduce that half
on macOS - every subagent I ran had ToolSearch and used it successfully (it's how they queried
select:Agent). #80104 mentions PowerShell in its tools list, so that symptom may be
Windows-specific and separable from the Agent bug described here.

Not verified

I could not test your fork finding. fork isn't dispatchable as a subagent_type in my
session - the Agent tool rejects it with Agent type 'fork' not found and lists only the
registered agent types. It appears reachable only via /subtask. Noting this so the workaround
isn't assumed to be universally available; your observation stands, I just can't add
confirmation to it.

Docs line 849 of sub-agents.md ("A fork still can't spawn another fork. It can spawn other
subagent types...") is at least consistent with what you saw.

[yasushihonda-acg]

Sharing field data that's consistent with (though not conclusive proof of) the mechanism described here — we've been trying to diagnose why /code-review (bundled skill) appears to hang for a long time with no visible progress.

Environment: Claude Code v2.1.220, macOS (darwin), same project across both incidents.

Incident 1: /code-review at large tier (should fan out to ~10 parallel finder subagents) ran for ~87 minutes with one finder subagent showing no output at all, while others completed in seconds-to-minutes. User gave up waiting and re-ran at medium tier, which completed normally.

Incident 2 (next session): /code-review with no args (defaults to a tier that should spawn 6 finder agents + a monitor agent) ran for ~1h30m with no visible progress before the user manually stopped it. Retried at low tier (which, per the skill's own prompt template, is a single-pass no-subagent review) — after ~1h13m it still appeared to be doing nothing.

Post-hoc, we inspected the session's local transcript directory. The no-args run had real subagent transcript files with activity timestamps (~20 min of activity, then nothing for the remaining ~70 min it was left running). The low-tier retry had zero subagent transcript files at all, despite low tier not being supposed to spawn subagents in the first place — so this data point doesn't confirm or rule out anything about #80036 specifically, just that something about the orchestration was stuck before producing any observable output either way.

In both cases TaskList showed no visibility into the skill-internal subagents, so there was no way to distinguish "still working" from "wedged" from the client side.

If it's useful, I can dig up more transcript excerpts (redacted of project-specific content) — this has now happened twice in the same project and effectively made /code-review at anything above low tier unusable for us; we've been falling back to codex review-diff instead, which has completed reliably both times.