[DOCS] Logic contradiction and "failure trap" regarding MCP tools in background subagents

Documentation Type

Unclear/confusing documentation

Documentation Location

docs/en/agent-sdk/subagents.md (Specifically the "Run subagents in foreground or background" section)

Section/Topic

Section: Work with subagents -> Run subagents in foreground or background

Current Documentation

"Background subagents run concurrently while you continue working... MCP tools are not available in background subagents."

Additionally, CHANGELOG.md for version 2.0.19 states:

"Auto-background long-running bash commands instead of killing them. Customize with BASH_DEFAULT_TIMEOUT_MS"

What's Wrong or Missing?

There is a significant logic contradiction between the recommended use cases for subagents and the limitations of background execution:

1. Specialization Conflict: Both mcp.md and plugins-reference.md encourage bundling MCP servers for specialized tasks (e.g., GitHub, Jira, or Database access). Subagents are the primary way to "specialize" behavior for these domains.
2. The "Auto-Background" Trap: Per the v2.0.19 changelog, long-running tasks are now auto-backgrounded. If a specialized "Researcher" subagent is using an MCP tool (like querying a large database or scanning a GitHub repo) and the task takes long enough to trigger auto-backgrounding, it will suddenly lose access to its primary capability ("MCP tools are not available in background subagents").
3. Silent Failure/UX Gap: The documentation does not explain why this technical restriction exists or how a user is supposed to know that their agent has suddenly "gone blind" to its MCP tools once it moves to the background. This leads to a scenario where an agent simply stops working or claims it "can't find" tools it was using 30 seconds prior.

Suggested Improvement

The documentation should be updated to address this "failure trap" proactively:

1. Technical Clarification: Add a note explaining why MCP tools are disabled in the background (e.g., security restrictions or session locking).
2. Explicit Warning: In the "Background subagents" section, add a warning:

• "Warning: If a subagent relies on MCP tools, ensure it remains in the foreground. If a task is auto-backgrounded or moved to the background via Ctrl+B, MCP tool access will be revoked, likely causing the task to fail."

1. Promote the "Resume" Workflow: Add a troubleshooting step or a "Best Practice" callout suggesting that if an MCP-heavy subagent fails in the background, the user should resume it in the foreground:

• "If a background subagent fails due to missing MCP permissions, ask Claude to 'Resume the [agent-name] in the foreground' to restore tool access."

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: docs/en/agent-sdk/mcp.md, docs/en/plugins-reference.md.
• Changelog Reference: Version 2.0.19 (Auto-backgrounding behavior).
• Example of confusion: A user creates a "Security Reviewer" agent that uses a custom "Snyk/Vulnerability MCP" tool. The tool takes 2 minutes to run, triggers auto-backgrounding, and then the agent errors out because it can no longer see the Snyk tool. The user is left confused because the tool is clearly configured in .mcp.json.