claude-code - 💡(How to fix) Fix [BUG] Sub-agent dispatched via Agent tool stalls silently on MCP permission gate — no surface to parent CLI UI

What's Wrong?

When a sub-agent is dispatched via the Agent tool with run_in_background: true, and that sub-agent attempts to invoke an MCP tool, the permission gate fires inside the sub-agent's process but does not surface to the parent CLI UI. The sub-agent stalls silently — it sends no idle notification, no message, no error, no log output — and the parent CLI has no signal that a permission grant is needed.

The user (in our case, the human PO supervising a parent "team-lead" Claude Code session) sees a sub-agent that appears dead. There is no permission prompt anywhere in the parent CLI UI for them to approve. Pre-allowing the MCP tool in the project-scoped .claude/settings.local.json (the permissions.allow list) does not help — sub-agents do not appear to inherit the parent's allowlist for MCP tools.

The stall is recoverable: in one instance (session 11), the PO independently cleared a pending permission request that surfaced in a different UI surface, and the sub-agent unblocked and continued normally — confirming the sub-agent process was alive and waiting, not crashed.

What Should Happen?

One of:

1. Best: the sub-agent's permission request surfaces in the parent CLI UI (the surface where the parent user is actively working), so the parent user can approve/deny. This matches the framing in #47339 (enhancement request to escalate sub-agent permission requests to the parent session).
2. Acceptable: the parent's permissions.allow list (especially explicit MCP tool entries) is inherited by sub-agents at dispatch time, so a tool the parent has already approved doesn't re-prompt for sub-agents.
3. Minimum: the sub-agent emits an idle notification (or some other observable signal) when it stalls on a permission gate, so the parent and the user have a hook for diagnosing the stall. The current silent-block is the worst-of-both: no permission UI AND no signal that anything is wrong.

Steps to Reproduce

Environment used: a multi-agent team coordinated via the Agent + SendMessage + TeamCreate toolchain (the "team-lead" pattern). The parent is a Claude Code CLI session; sub-agents are dispatched as background agents.

1. In a project directory, create .claude/settings.local.json with an allow list that explicitly includes the MCP tool you'll use:

   {
     \"permissions\": {
       \"allow\": [
         \"mcp__plugin_context7_context7__resolve-library-id\",
         \"mcp__plugin_context7_context7__query-docs\"
       ]
     }
   }

2. Confirm the parent session can use the MCP tool without a prompt (allowlist works at parent scope).
3. Spawn a sub-agent via the Agent tool with run_in_background: true. Give it a prompt that requires using the MCP tool. Example prompt: "On startup, use `mcp__plugin_context7_context7__resolve-library-id` with query 'react' and report the resolved library ID back via SendMessage."
4. Observe the parent CLI UI.

Expected

Either a permission prompt appears in the parent CLI UI for the sub-agent's tool use, or the sub-agent inherits the parent's allowlist and the tool runs without prompting. In either case, the sub-agent makes progress.

Actual

• Sub-agent starts cleanly. Reads its prompt files. Sends a clean intro message back to the parent (if the prompt asks for one).
• On reaching the MCP tool call, the sub-agent silently stops.
• Parent CLI receives no permission prompt.
• Sub-agent emits no idle notification, no message, no log line, no error.
• The block persists indefinitely. In our two observations:
  • Session 10 (2026-05-20): ~28 min stall, never recovered, dropped and restarted the sub-agent.
  • Session 11 (2026-05-21): ~58 min stall, recovered when the PO independently cleared a pending permission elsewhere in their UI (a surface separate from the parent CLI session).

Confirmed twice with controlled variants

We initially suspected a prompt-content issue (parent was passing only a "read your prompt file" directive instead of embedding the full prompt content per spec). We A/B tested by spawning a second sub-agent with the spec-correct embedded prompt but no MCP-tool instruction (just "intro and wait for first assignment"). The second agent introed cleanly in <60 sec — confirming the prompt-shape theory was a confound; the structural issue is the MCP permission gate not surfacing.

Is this a regression?

Don't know. The pattern (multi-agent team coordinated via the Agent tool) is fairly new in our usage, and we don't have a clean "this version worked, that version doesn't" comparison. Related issues #32402, #38859, #51288 suggest this is a broader class of bug that has been accumulating reports without visible fix momentum.

Related issues (cross-links)

Found via repo search; ours is a distinct symptom but shares root cause with:

• #47339 — Feature: Background subagents should be able to escalate permission requests to the parent session — describes the desired fix directly.
• #32402 — [BUG] Background subagents silently auto-deny permissions (Write tool) — closest existing report by symptom shape (silent stall, no prompt), scoped to Write tool rather than MCP.
• #38859 — Background agents cannot get Bash permissions — bypassPermissions ignored for Agent tool — same class (parent permission state not propagated to sub-agents), scoped to Bash + bypassPermissions.
• #51288 — Concurrent subagent dispatch: parent's permission state does not propagate to parallel subagents — root-cause umbrella.
• #57037 — [BUG] Subagent permission cascade-failure when multiple Agent tool calls in one message (2.1.126)
• #56686 — [BUG] Sub-agents denied Read on paths outside project root despite explicit permissions.allow Read(...) rule — settings.json allowlist not inherited.

The MCP-specific cluster (#61015, #61027, #61141, #61203) is scoped to routines (remote scheduled agents) rather than the local Agent tool + run_in_background: true pattern, but is the same root behavior in a different surface.

Claude Code Version

claude --version → 2.1.146 (Claude Code)

Platform

Anthropic API (Claude Code CLI; Opus 4.7, fast mode enabled).

Operating System

Linux (Debian-derived: Linux 6.12.74+deb13+1-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.12.74-2 (2026-03-08) x86_64).

Terminal/Shell

bash.

Additional Information

Project settings excerpt (./.claude/settings.local.json):

{
  \"permissions\": {
    \"allow\": [
      \"WebFetch(domain:entu.ee)\",
      \"WebFetch(domain:inlang.com)\",
      \"WebSearch\",
      \"mcp__plugin_context7_context7__resolve-library-id\",
      \"mcp__plugin_context7_context7__query-docs\",
      \"WebFetch(domain:svelte.dev)\"
    ]
  }
}

User-global settings excerpt (~/.claude/settings.json):

{
  \"permissions\": {
    \"allow\": [\"Read\", \"Glob\", \"Grep\", \"Edit\", \"Write\", \"Bash\", \"WebFetch(domain:github.com)\", \"WebFetch(domain:raw.githubusercontent.com)\"],
    \"defaultMode\": \"default\"
  }
}

The parent CLI session honors the project-level allow list and can call mcp__plugin_context7_context7__* without a prompt. The dispatched sub-agent does not inherit this.

Permission mode: defaultMode: \"default\" (interactive). Not bypassPermissions.

Multi-agent team setup: the sub-agents are dispatched as part of a TeamCreate-managed team (parent agent is the team-lead; sub-agents have name, team_name, run_in_background: true). It's possible the team context contributes to the surfacing issue, but the underlying root cause (allowlist not inherited; permission prompt not surfaced) matches reports from non-team contexts (#32402, #56686).