[DOCS] `--agent` and `agent` setting docs omit session `permissionMode` behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Invoke subagents explicitly" → the session-wide --agent / agent setting behavior

Current Documentation

The docs currently say:

* Session-wide: the whole session uses that subagent's system prompt, tool restrictions, and model via the --agent flag or the agent setting Run the whole session as a subagent. Pass --agent <name> to start a session where the main thread itself takes on that subagent's system prompt, tool restrictions, and model: This works with built-in and custom subagents, and the choice persists when you resume the session.

The settings docs say:

| agent | Run the main thread as a named subagent. Applies that subagent's system prompt, tool restrictions, and model. |

The plugin docs repeat the same behavior:

Setting agent activates one of the plugin's custom agents as the main thread, applying its system prompt, tool restrictions, and model.

No page in the --agent / agent documentation explains that the main session can also inherit the selected agent's permissionMode.

What's Wrong or Missing?

Changelog v2.1.119 says:

--agent <name> now honors the agent definition's permissionMode for built-in agents

The current docs still describe session-wide agent activation as applying only the agent's system prompt, tool restrictions, and model. That leaves out a user-visible behavior change: selecting an agent for the main session can also change the session permission mode.

This matters because users need to understand that:

• permissionMode is part of the behavior applied when an agent runs as the main session via --agent or the agent setting
• built-in agents now honor their agent-defined permissionMode in that flow
• running a session with --agent is not the same as spawning a subagent inside an existing session, where parent permission context rules still apply

Suggested Improvement

Update the sub-agents, settings, cli-reference, and plugin agent setting references so they describe session-wide agent activation as applying the selected agent's permissionMode, not just its system prompt, tool restrictions, and model.

Suggested wording near the --agent explanation:

Running Claude Code with --agent <name> (or setting "agent" in settings.json) applies the selected agent's system prompt, tool restrictions, model, and permissionMode for the main session. This includes built-in agents. If an agent definition uses permissionMode: plan, starting the session with that agent begins in Plan mode.

If explicit --permission-mode flags or other overrides take precedence over the agent-defined mode, document that precedence here too.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | Session-wide --agent behavior and the permissionMode frontmatter field |
| https://code.claude.com/docs/en/settings | agent setting description |
| https://code.claude.com/docs/en/cli-reference | --agent flag reference |
| https://code.claude.com/docs/en/plugins | Plugin settings.json agent behavior |

Total scope: 4 pages affected

Source: Changelog v2.1.119

Changelog entry: --agent <name> now honors the agent definition's permissionMode for built-in agents