[DOCS] Subagents docs still say background subagents auto-deny permission prompts

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

"Run subagents in foreground or background"

Current Documentation

The Subagents page currently says:

"Foreground subagents block the main conversation until complete. Permission prompts are passed through to you as they come up."

But it then says background subagents behave differently:

"Background subagents run concurrently while you continue working. They run with the permissions already granted in the session and auto-deny any tool call that would otherwise prompt."

The same section also says:

"If a background subagent fails due to missing permissions, you can start a new foreground subagent with the same task to retry with interactive prompts."

And the fork note says:

"Forks still surface permission prompts in your terminal as they occur; named subagents auto-deny anything that would prompt, as described above."

What's Wrong or Missing?

Claude Code v2.1.186 changed background subagents so permission prompts surface in the main session instead of being auto-denied. The dialog shows which agent is asking, and Esc denies just that tool.

The current Subagents page now describes the old behavior and tells users to retry with a foreground subagent. That is outdated for v2.1.186 and later.

Suggested Improvement

Replace the background-subagent auto-deny text with the new prompt-routing behavior. For example:

Background subagents run concurrently while you continue working. When a background subagent needs permission for a tool, Claude Code surfaces the prompt in the main session and names the agent requesting permission. Press Esc to deny that tool request only; the background subagent can continue if it can recover.

Also update the fork note so it no longer says named subagents auto-deny anything that would prompt.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | Background subagent permission behavior is stale |
| https://code.claude.com/docs/en/agent-view | May need a cross-reference if background-session prompts appear there |
| https://code.claude.com/docs/en/permissions | Permission prompt behavior reference |

Total scope: 3 pages affected