[BUG] Background general-purpose sub-agents can't resolve MCP tools via ToolSearch even with exact tool names (parent session unaffected)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Background-dispatched general-purpose sub-agents (spawned via Agent({subagent_type: "general-purpose", run_in_background: true}) from within a Skill's execution context) cannot resolve any MCP tool via ToolSearch, even when queried with the exact, fully-qualified deferred-tool name. The parent session resolves and calls the same MCP tools successfully hundreds of times in the same run.

This looks related to #64909 but is not the same code path: #64909 was about named sub-agents with an explicit tools: frontmatter wildcard, and was fixed in v2.1.163. Here the sub-agent type is the built-in general-purpose (inherit-all, no tools: restriction) — the exact type #64909's own comment thread reported as the working control case before that fix. We're reproducing the same "empty deferred-tool registry" symptom on that previously-working path, on a much newer build.

What Should Happen?

Per the sub-agent docs:

Subagents inherit the internal tools and MCP tools available in the main conversation by default.

general-purpose has no tools: restriction, so nothing should filter the MCP tools out. ToolSearch inside the sub-agent should resolve the same deferred tools the parent session already resolved successfully in the same run — especially when queried with the exact correct fully-qualified tool name via select:.

Error Messages/Logs

No error is thrown — the failure is silent. `ToolSearch` simply returns no usable result for every query form tried. The sub-agent's own transcript ends with it giving up and reporting to its orchestrator (via `SendMessage`) that the MCP server is inaccessible:


"xxxx MCP 도구 접근 불가 — 앵커링 착수 못함"
(= "xxxx MCP tool access unavailable — cannot start anchoring")

Steps to Reproduce

1. Start a Claude Code session with an MCP server connected that exposes a large number of tools (~150 in our case), so its tools are deferred by default and must be resolved via ToolSearch before first use. Ensure the server's tools are in --allowedTools (e.g. mcp__<server>__*) along with Agent.
2. In the parent session, confirm MCP works: call ToolSearch, then invoke a resolved tool directly. (Our transcript: 8 ToolSearch calls → 105 successful direct mcp__<server>__* tool calls in the same run.)
3. From within a Skill's instructions, dispatch a sub-agent via the Agent tool with:

``json
{
"subagent_type": "general-purpose",
"run_in_background": true,
"description": "...",
"prompt": "... use MCP tool X, Y, Z to do <task> ..."
}
``

1. Inside that sub-agent, have it try to resolve the exact MCP tools it needs via ToolSearch, starting with the exact, fully-qualified tool names:

``
ToolSearch({query: "select:mcp__<server>__tool_a,mcp__<server>__tool_b,mcp__<server>__tool_c,mcp__<server>__tool_d"})
`
then fall back to keyword queries ("<tool_name> keyword", "<tool_name>", "<server>"`, etc.).

1. Observe: every query form fails to resolve any tool. In our transcript the sub-agent tried 12 ToolSearch calls total (exact-name select: twice, then 10 keyword variants) — 0 successful resolutions, vs. the parent's 8→105 in the same run.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

N/A — see note above: the type of dispatch we used (general-purpose, inherit-all) is the one #64909's thread reported as never-broken prior to that issue's own fix (v2.1.163), so if this is a regression, the reference point would be pre-2.1.163 general-purpose behavior, not a version we've directly tested ourselves.

Claude Code Version

2.1.216 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

• OS detail: macOS 26.5 (Darwin 25.5.0), arm64.
• Not a traditional terminal: the parent session runs as an interactive PTY spawned programmatically via node-pty from a third-party Electron desktop app (not a terminal emulator), with --permission-mode dontAsk and an explicit --allowedTools list including the MCP server's tool wildcard and Agent. Flagging this since it may be a relevant variable, though the parent session itself has no trouble reaching MCP tools — only the dispatched sub-agents do.
• Suspected distinguishing variable — run_in_background: true: all 5 sub-agents in our reproduction were dispatched with run_in_background: true (the Agent tool's default). Neither #64909 nor #30280 mention foreground vs. background dispatch explicitly. We have not isolated whether run_in_background: false (synchronous/foreground) avoids the issue — this is an untested but plausible lead, since background dispatch is a distinct code path (results delivered via notification rather than inline return) that may not wire up the same MCP/ToolSearch session context as a foreground sub-agent call.
• Evidence available on request: sanitized JSONL excerpts (tool names/queries only, no MCP response payloads) from both the parent session transcript (8 ToolSearch / 105 successful MCP calls) and the sub-agent transcript (12 ToolSearch / 0 successful MCP calls, including the exact-name select: query for the 4 specific tools it needed).
• Related issues:
• #64909 (closed, fixed in v2.1.163) — same symptom description, but a different sub-agent dispatch shape (named custom sub-agent with explicit tools: frontmatter wildcards). That issue's own thread confirmed general-purpose/inherit-all was NOT broken pre-fix, so this looks like either a regression of a related-but-distinct code path, or an uncovered variant — not a duplicate.
• #30280 (open) — "Sub-agents spawned via Agent tool don't reliably inherit MCP tools (inconsistent with docs)" — reports the opposite asymmetry (works inside a skill context, fails via direct top-level Agent dispatch outside a skill). Our case fails inside a skill context, so together these reports suggest MCP/ToolSearch inheritance for sub-agents is unreliable across multiple, possibly-overlapping code paths rather than one single root cause.
• #13890 (open) — "Subagents unable to write files and call MCP tools silently" — same class of silent failure.
• Impact: any Skill-driven workflow that fans out MCP-tool-dependent work to background sub-agents (a documented, encouraged pattern for parallelizing large analysis/ETL jobs) silently degrades to "sub-agents can prepare data via non-MCP tools only; the orchestrator must serialize all MCP writes itself" — defeating the parallelism the pattern is meant to provide, with no error surfaced to the user unless the sub-agent's own prompt happens to instruct it to self-report the failure.