[FEATURE] Extend deferred tool loading to built-in subagents

[djpeck94]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

I use Claude Code as the central hub for my engineering workflow, with 8+ MCP servers (GitHub, Linear, PostHog, Sentry, Ahrefs, Supabase, Webflow, Playwright) and dozens of plugins/skills configured at the project level. This gives me ~300+ tools and ~90 skill definitions.

The problem: built-in subagents (Explore, Plan, general-purpose) silently fail because all tool definitions are serialized into the subagent's prompt, exceeding the context window before the agent can even start. The subagent returns immediately with 0 tool uses, 0 tokens, and "Prompt is too long".

This forces me to choose between deep tool integration OR subagent functionality — I can't have both. The main orchestrator thread handles this fine via deferred tool loading (ToolSearch), but subagents don't have access to that mechanism.

Proposed Solution

Built-in subagents should use the same deferred tool loading mechanism that the main orchestrator uses. Specifically:

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 orchestrator could optionally hint which tools the subagent might need based on the task description

The interface wouldn't change at all — subagents would just work regardless of how many MCP servers are configured.

Alternative Solutions

What I've tried or considered:

• Removing MCP servers — Works but defeats the purpose. I use all these integrations regularly, just not all in every subagent call.
• Using direct tool calls instead of subagents — Works for simple searches, but loses the autonomous multi-step exploration that makes subagents valuable.
• Creating custom agents with tools allowlists — This works (custom agents support tools: and disallowedTools: in YAML frontmatter), but requires duplicating built-in agent functionality. I'd have to rebuild Explore, Plan, etc. as custom agents just to get tool filtering.
• Using MCP config profiles — Manually switching between "lightweight" and "full" configs is clunky and error-prone.

Priority

Critical - Blocking my work

Feature Category

MCP server integration

Use Case Example

Example scenario:

1. I'm working on a full-stack app with 8 MCP servers configured (GitHub, Linear, PostHog, Sentry, Ahrefs, Supabase, Webflow, Playwright) plus plugins
2. I ask Claude to explore the codebase for attribution-related code
3. Claude spawns an Explore subagent, which only needs Read, Grep, and Glob
4. Currently: The subagent receives all ~300 tool definitions, the prompt exceeds the context limit, and it fails silently with Done (0 tool uses - 0 tokens - 1s)
5. With this feature: The subagent launches with only its core tools + ToolSearch, operates within context limits, and successfully explores the codebase

Additional Context

• The deferred tool loading architecture already exists and works well for the main thread — this is about extending it to subagents
• Custom agents already support tool scoping via tools/disallowedTools in YAML — the missing piece is applying similar scoping to built-in agent types
• This likely affects any user with 5+ MCP servers configured, which should become increasingly common as the MCP ecosystem grows
• Reproducible on macOS with Claude Code CLI

[github-actions]

Found 3 possible duplicate issues:

1. Intelligently disable MCP tools for subagents to prevent context overflow #29157
2. Teammate agents cannot see ToolSearch in their visible tool list #23625
3. [Bug] Subagents (Agent tool) hit context limit without auto-compact ever triggering #30396

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

[joefulfill]

Having this same exact issue!

[djpeck94]

Differentiating from related issues:

This request is related to but distinct from three existing issues:

• Intelligently disable MCP tools for subagents to prevent context overflow #29157 — Closest overlap. That issue proposes intelligent filtering of MCP tools at spawn time based on task description or subagent type. My request goes further: rather than trying to guess which tools a subagent needs upfront, extend the existing deferred tool loading (ToolSearch) mechanism to subagents so they can load tools on demand. This is architecturally simpler (the system already exists for the main thread) and more robust than heuristic-based filtering. Note that Intelligently disable MCP tools for subagents to prevent context overflow #29157 was closed as duplicate without resolution.

• Teammate agents cannot see ToolSearch in their visible tool list #23625 — That issue reports that ToolSearch works for teammate agents but isn't visible in their tool list, causing the model to avoid calling it. My issue is upstream of that: built-in subagents (Explore, Plan) don't have access to ToolSearch at all, and they receive the full unfiltered tool payload instead. Even if Teammate agents cannot see ToolSearch in their visible tool list #23625 is fixed (ToolSearch becomes visible), it wouldn't help because built-in subagents still get all ~300 tool definitions injected into their prompt before they start.

• [Bug] Subagents (Agent tool) hit context limit without auto-compact ever triggering #30396 — That issue is about subagents exhausting context during execution on research-heavy tasks, with auto-compact failing to trigger. My issue is about subagents failing before execution even begins — the tool definitions alone exceed the context window, so the agent returns 0 tool uses, 0 tokens in under 1 second. The subagent never gets a chance to do any work or hit a compaction threshold.

In short:
#30396 = context exhausted during work.
#23625 = ToolSearch exists but is hidden.
#29157 = filter tools at spawn time.

This issue = extend deferred tool loading to subagents so the problem doesn't arise in the first place.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.