[FEATURE] Extend deferred tool loading to subagents — refile of #31623

Why this is filed fresh

Refiling #31623 ("Extend deferred tool loading to built-in subagents"), which was auto-closed as NOT_PLANNED on 2026-04-04 by github-actions inactivity sweep — no Anthropic engineer ever responded — then auto-locked on 2026-04-13. The architectural problem it described is still entirely present and now affects more users with heavier MCP/skill loads than when it was originally filed.

The bug-side issue #37793 ("Subagents fail with 'prompt is too long' when user has many MCP servers") is still open and labeled has repro, but it tracks the symptom, not the architectural fix. As of CLI 2.1.121 the symptom persists — see reproduction below.

Problem

The main session uses deferred tool loading (ToolSearch) — tool names are listed in the system context but full JSON schemas only load on demand. This is what lets a parent session run with 18 MCP servers / 400+ tools without overflowing.

Built-in subagents (Explore, Plan, general-purpose) do not use this mechanism. Every MCP tool schema is serialized into the subagent's spawn context, before the subagent prompt is even appended. With a heavy MCP load, the spawn payload alone exceeds the subagent model's context window (Explore defaults to Haiku 4.5, 200k cap) and the dispatch is rejected with Prompt is too long, or — more insidiously — squeaks through dispatch but auto-compacts mid-run and returns a hallucinated meta-reply instead of doing the work it was asked to.

Evidence (CLI 2.1.121, Opus 4.7 1M parent, macOS 25.3.0)

Reproduction in a clean claude -p non-interactive session, prompted to dispatch one Explore subagent. Setup: a heavy MCP/skills configuration well past the threshold others have reported in #37793 (low hundreds of tools, ~100 skills).

Default config — Explore unusable. 13 dispatches with progressively shorter prompts:

| Subagent prompt length | Result |
|---|---|
| 1711 / 990 / 728 / 591 / 508 / 341 / 298 / 161 / 86 / 52 / 40 / 20 / 11 / 10 chars | Prompt is too long |
| 4 ("test") / 2 ("hi") | Generic Explore greeting (no work) |

Failure is not proportional to user prompt length — even an 11-char prompt ("read api.ts") was rejected. The cliff is hard, consistent with the pre-prompt payload (MCP schemas + skills) consuming nearly the full Haiku-200k budget.

Slim config (--strict-mcp-config --disable-slash-commands) — first dispatch succeeds. Same prompt, same model, same files. Total: 1 dispatch, 6,701 chars of accurate ground-truth output, 56 s vs 389 s, $0.30 vs $1.53.

Agent({ model: "opus" }) override — works in normal session. Tested in this user's normal Opus-1M parent session: dispatching Explore with explicit model: "opus" succeeds where the default Haiku-Explore fails. This is currently the cleanest user-facing workaround, but it shouldn't be necessary.

Why existing workarounds aren't enough

• model: "opus" / "sonnet" override — works, but forces every Explore dispatch to a more expensive/slower model purely for context-window reasons. Choice of model for cost/latency reasons should be orthogonal to context-window engineering.
• --disable-slash-commands --strict-mcp-config — works, but you lose access to your skills and MCPs in that session, defeating the point of having them.
• Disabling heavy MCPs in ~/.claude.json — works, but forces users to give up real functionality. The whole premise of deferred loading at the parent level was that you don't have to do this.
• toolc proxy (third-party) — band-aid; users shouldn't need an external Go proxy to make the built-in subagents work.
• PreToolUse hook restrictions — orthogonal; restricts which tools subagents use, not which schemas get loaded.

Proposed solution (verbatim from #31623, still the right framing)

1. When spawning a built-in subagent, only pass the core tools it needs (e.g., Explore gets Read, Grep, Glob, Bash, ToolSearch).
2. Give subagents access to ToolSearch so they can load additional MCP tools on demand if needed.
3. The deferred-loading registry (tool names + brief metadata) inherited from the parent should be passed in the same form the parent already uses — not re-serialized as full schemas.

This is architecturally simpler than heuristic filtering of MCP tools at spawn time (e.g., #29157), because the system already exists for the main thread. It's an extension, not a new mechanism.

Why this matters more now than when #31623 was filed

• Cloud claude.ai connectors push many users well past 200+ tools without them noticing — they're enabled with one click.
• Plugins/skills are increasingly recommended workflows; users now routinely have 50–100+ skills.
• Single MCP servers commonly publish very large tool surfaces (productivity, finance, and CRM integrations frequently expose 40–100+ tools each).
• Each new MCP server a user adds further breaks subagent functionality, with no warning, and no diagnosis pointer in the UI — Explore just silently fails or returns nonsense.

Suggested next steps

• Reopen the architectural work (or accept this as the new tracking issue).
• At minimum: surface the failure visibly in the UI when an Explore dispatch is rejected for context-overflow reasons, with a pointer to the workarounds, until the architectural fix lands.
• Extend the existing /doctor command to estimate subagent dispatch payload size and warn when current MCP/skills configuration would overflow Haiku-200k Explore. Today /doctor reports installation health but says nothing about the loaded tool/skill catalog vs. subagent budgets — it's a natural home for this check.

Related

• #31623 (closed NOT_PLANNED, locked) — original architectural request
• #37793 (open, has repro) — bug-side tracker
• #38928, #41208, #40104, #38044 — related open issues, various angles
• #42565, #50284, #52400, #45357 — closed as duplicates