[FEATURE] Controllable subagent context: filter MCP servers, plugins, skills, and rules per agent

[moxer-mmh]

Problem

When users have many MCP servers, plugins, skills, and rules configured, subagents fail immediately with "prompt is too long" because they inherit the full system prompt including all MCP tool schemas. This makes Explore, Plan, and general-purpose agents completely unusable for power users.

Live Reproduction (Today)

In a single Claude Code session (v2.1.81, Opus 4.6, Claude Max) with ~15 MCP servers and ~200 skills:

# All three subagents failed simultaneously:
Agent 1 (Explore): "Prompt is too long" — 0 tool uses, 0 tokens
Agent 2 (Explore): "Prompt is too long" — 0 tool uses, 0 tokens  
Agent 3 (Explore): "Prompt is too long" — 0 tool uses, 0 tokens

The failure is completely silent in the TUI — users see Done (0 tool uses · 0 tokens) with no error explanation.

Root Cause

Subagents inherit ALL MCP tool definitions from the parent session regardless of:

• The tools: allowlist in agent frontmatter
• Whether the subagent needs those tools
• Whether the tool schemas exceed the subagent's context window

The main session already handles this via deferred tool loading (ToolSearch/MCPSearch), but subagents don't get this treatment.

Proposed Solution: Controllable Subagent Context

Add parameters to the Agent tool that control what context gets passed to subagents:

Option A: New Agent tool parameters

# In Agent tool invocation:
mcp_servers: ["github", "supabase"]  # Whitelist specific MCP servers (default: none)
inherit_plugins: false                # Don't inherit plugin tools/skills (default: true)
inherit_rules: false                  # Don't inherit rules (default: true)  
context_budget: 50000                 # Max tokens for inherited context

Option B: Extend existing mechanisms (lower effort)

1. Apply deferred tool loading to subagents — Give subagents access to ToolSearch/MCPSearch so they can load MCP tools on demand instead of upfront
2. Respect tools: frontmatter as a hard filter — When an agent specifies tools: Read, Grep, Glob, don't include ANY other tool schemas (including MCP)
3. Inherit parent's deferred-tool configuration — If the main session uses auto:10 for MCP tool search, subagents should too

Option C: Agent-level MCP configuration

# In agent .md frontmatter:
name: my-explorer
tools: Read, Grep, Glob
mcp_servers: []           # No MCP servers for this agent
inherit_mcp: false        # Explicit opt-out

Why This Isn't a Duplicate

• Subagents fail with 'prompt is too long' when user has many MCP servers (tool definitions exceed 200k) #37793 documents the bug (subagents fail with prompt too long). This issue proposes the feature to fix it.
• [FEATURE] Extend deferred tool loading to built-in subagents #31623 proposes extending deferred tool loading to subagents. This issue proposes a broader solution with explicit context control.
• [BUG] In mass agent work, prompt is too long #23448 documents mass agent failures. Related but focused on a different scenario.

All three issues describe symptoms of the same missing capability: subagent context is not controllable.

Current Workarounds

Workaround	Problem
Use model: "opus" on all agents	Costs more quota, defeats purpose of lightweight agents
Reduce MCP servers	Defeats the purpose of having them
Create custom agents with tools: allowlists	Tool filtering doesn't exclude MCP schemas (the bug)
Move MCP servers to project-level configs	Tedious, fragile, easy to forget

Impact

This affects any Claude Code user with 10+ MCP servers configured. As the MCP ecosystem grows, this will affect an increasing percentage of users. The combination of:

1. Silent failure (no error shown in TUI)
2. No workaround that doesn't sacrifice functionality
3. Growing MCP adoption

makes this a critical gap in the agent system.

Interim Plugin

As a workaround, I've created the lean-agents plugin with lightweight agent replacements. But this is a bandaid — the proper fix needs to happen in the runtime.

[yurukusa]

A PreToolUse hook on Agent can inject tool restrictions into the subagent prompt:

INPUT=$(cat)
DESCRIPTION=$(echo "$INPUT" | jq -r '.tool_input.description // empty')
RESTRICTION=""
if echo "$DESCRIPTION" | grep -qiE '(test|spec|coverage)'; then
    RESTRICTION="Only use: Bash (for running tests), Read, Grep, Glob. Do NOT use Edit, Write, or Agent."
elif echo "$DESCRIPTION" | grep -qiE '(review|audit)'; then
    RESTRICTION="Only use: Read, Grep, Glob. Do NOT use Edit, Write, Bash, or Agent. This is a read-only review."
elif echo "$DESCRIPTION" | grep -qiE '(explore|search|find)'; then
    RESTRICTION="Only use: Read, Grep, Glob, Bash (read-only commands). Do NOT use Edit or Write."
fi
[ -z "$RESTRICTION" ] && exit 0
echo "[AgentFilter] Tool restriction: $RESTRICTION" >&2
exit 0

[kateleext]

+1 — experiencing the same issue on v2.1.86, Opus 4.6 1M, Claude Max.

Setup: 2 MCP servers (PostHog ~100 tools, Google Drive ~80 tools), ~26 custom skills, 5 enabled plugins (document-skills, figma, frontend-design, code-review, ruby-lsp).

Symptoms: All Explore agents fail with Done (0 tool uses · 0 tokens · 1s). Explicitly setting model: "opus" or model: "sonnet" on the Agent tool works — only Haiku (the Explore default) fails because the full expanded tool schemas exceed its 200K context window.

Key observation: The main session handles this fine via deferred tool loading (ToolSearch). The bug is that subagents receive fully expanded tool schemas instead of deferred listings. An Explore agent only needs filesystem tools (Read, Glob, Grep, Bash) but gets all 300+ MCP tool definitions.

Strongly support Option B from the proposal — applying deferred tool loading to subagents would fix this without requiring new configuration.