[DOCS] Background subagents documentation describes old auto-deny behavior instead of new pre-launch permission prompts

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background

Section/Topic

"Run subagents in foreground or background" section

Current Documentation

The docs currently say:

Background subagents run concurrently while you continue working. They inherit the parent's permissions and auto-deny anything not pre-approved. If a background subagent needs a permission it doesn't have or needs to ask clarifying questions, that tool call fails but the subagent continues. MCP tools are not available in background subagents.

And:

If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.

What's Wrong or Missing?

The 2.1.20 release notes state: "Changed background agents to prompt for tool permissions before launching"

This is a behavior change. The current documentation describes the old behavior where:

1. Background subagents auto-deny permissions during execution
2. Tool calls fail silently if permissions are missing
3. Users must resume in foreground to retry with prompts

The new behavior prompts for tool permissions before the background agent launches, not during execution. This is a significant UX improvement that prevents wasted work from permission failures mid-execution.

Suggested Improvement

Update the background subagents bullet point to describe the new behavior:

Before:

Background subagents run concurrently while you continue working. They inherit the parent's permissions and auto-deny anything not pre-approved. If a background subagent needs a permission it doesn't have or needs to ask clarifying questions, that tool call fails but the subagent continues. MCP tools are not available in background subagents.

After:

Background subagents run concurrently while you continue working. Before launching, Claude Code prompts for any tool permissions the subagent will need. Once running, background subagents cannot ask clarifying questions (via AskUserQuestion), so those calls are skipped. MCP tools are not available in background subagents.

Also update or remove the sentence about resuming due to missing permissions, since permissions are now requested upfront:

Before:

If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.

After:

If a background subagent needs to ask clarifying questions that it couldn't ask while running, you can [resume it](#resume-subagents) in the foreground to continue interactively.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 434 | Background subagents bullet describes old auto-deny behavior |
| https://code.claude.com/docs/en/sub-agents | 436 | Resume guidance assumes permissions fail during execution |

Total scope: 1 page affected (2 locations on same page)