Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] `--agent` and `agent` setting docs omit session `permissionMode` behavior [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52605•Fetched 2026-04-24 06:02:40
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3

Root Cause

This matters because users need to understand that:

RAW_BUFFERClick to expand / collapse

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:

PageContext
https://code.claude.com/docs/en/sub-agentsSession-wide --agent behavior and the permissionMode frontmatter field
https://code.claude.com/docs/en/settingsagent setting description
https://code.claude.com/docs/en/cli-reference--agent flag reference
https://code.claude.com/docs/en/pluginsPlugin 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

extent analysis

TL;DR

Update the documentation for --agent and agent settings to include the application of the selected agent's permissionMode for the main session.

Guidance

  • Review the affected pages (sub-agents, settings, cli-reference, and plugins) to ensure consistency in describing the behavior of --agent and agent settings.
  • Update the documentation to explicitly state that selecting an agent for the main session applies the agent's system prompt, tool restrictions, model, and permissionMode.
  • Consider adding information on the precedence of explicit --permission-mode flags or other overrides over the agent-defined mode.
  • Verify that the updated documentation accurately reflects the behavior change introduced in Changelog v2.1.119.

Notes

The suggested improvement aims to clarify the user-visible behavior change introduced in Changelog v2.1.119, ensuring that users understand the implications of selecting an agent for the main session.

Recommendation

Apply workaround: Update the documentation to reflect the correct behavior, as this will improve the understanding of the feature and reduce confusion.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#permission error#memory optimization#batch processing#GPU compatibility#latency issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] `--agent` and `agent` setting docs omit session `permissionMode` behavior [1 participants]