claude-code - 💡(How to fix) Fix Agent/subagent spawn fails with 'Prompt is too long' even for tiny prompts (large MCP tool set)

Summary

Spawning a subagent via the Agent / Task tool fails immediately with Prompt is too long — even when the prompt I pass is one or two short sentences. The failure is independent of my prompt length: shrinking a ~400-word prompt down to a single sentence ("Map the Omnibar in this iOS app...") still returns Prompt is too long. It appears the subagent's inherited context (system prompt + the very large enumerated/deferred tool list) already exceeds the subagent model's context window before my prompt is appended, so no prompt is small enough to succeed.

Repro

1. Run Claude Code in a session with many MCP servers connected (in my case: Datadog, Figma, Linear, Slack, Sentry, Notion, GitHub, PostHog, Intercom, Granola, Google, etc. — a very large deferred-tool list shown in the system reminder).
2. Main model is Opus 4.8 (1M context).
3. Call the Agent tool with subagent_type: "Explore" and a short prompt.
4. Observe the tool result: Prompt is too long.
5. Reduce the prompt to a single short sentence and retry → still Prompt is too long.
6. Launching 3 in parallel, then 1 alone — same result every time.

Expected

A short subagent prompt should spawn successfully. If the inherited tool/context payload is what's over the limit, the error should say so (e.g. "subagent context exceeds model limit; reduce connected MCP tools") rather than blaming the user-supplied "prompt", which is misleading and un-actionable. Ideally the subagent should also inherit the parent's large context window (the parent was on a 1M-context model) and/or only load deferred tool schemas on demand rather than eagerly.

Impact

Plan mode strongly steers toward using Explore/Plan subagents for codebase research; when every spawn fails, the whole subagent-based workflow is unusable and you have to fall back to doing all searching inline in the main loop.

Environment

• Claude Code CLI (terminal)
• Model: claude-opus-4-8 (1M context) as main loop
• OS: macOS (Darwin 25.5.0)
• Many MCP servers connected (large deferred tool list)
• Subagent types attempted: Explore (likely affects all types)

Hypothesis

The subagent is initialized with the full tool catalog (including the large set of MCP tools surfaced as deferred tools) baked into its context, and/or is started on a model/context-window smaller than the parent's, so the baseline context already overflows before any user prompt is added. The error message attributes this to the "prompt," which masks the real cause.