claude-code - 💡(How to fix) Fix [DOCS] `claude agents` dispatched sessions missing documentation for `agent` setting and `--agent` flag

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

"Dispatch new agents" section, "Settings, plugins, and MCP servers" subsection, and "Permission mode, model, and effort" subsection

Current Documentation

The agent view page documents several flags that claude agents accepts for configuring dispatched sessions:

To set defaults for every session you dispatch from agent view, pass any of --permission-mode, --model, or --effort when opening it:

claude agents --permission-mode plan --model opus --effort high

The flags table in "Settings, plugins, and MCP servers" lists --settings, --add-dir, --plugin-dir, and --mcp-config, but not --agent.

The CLI reference entry for claude agents lists --permission-mode, --model, --effort, --settings, --add-dir, --plugin-dir, and --mcp-config, but does not mention --agent.

The agent field is documented in the settings page:

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

The sub-agents page documents session-wide agent usage:

Session-wide: the whole session uses that subagent's system prompt, tool restrictions, and model via the --agent flag or the agent setting

To make it the default for every session in a project, set agent in .claude/settings.json:

{
  "agent": "code-reviewer"
}

The CLI flag overrides the setting if both are present.

However, neither page explains that this behavior also applies to sessions dispatched from claude agents.

What's Wrong or Missing?

A. Missing documentation for agent setting in dispatch context

The agent field in settings.json is now honored when dispatching sessions from claude agents (as of v2.1.157). When a user has "agent": "code-reviewer" in their settings, sessions dispatched from the agent view input should use that agent by default. The agent-view page does not mention this.

B. Missing documentation for --agent flag on claude agents

The --agent <name> flag is accepted by claude agents and overrides the agent setting for dispatched sessions, but it is not listed in the agent-view flags table, the dispatch defaults section, or the CLI reference entry for claude agents.

Suggested Improvement

Agent-view page: "Dispatch new agents" section

After the paragraph about --permission-mode, --model, and --effort:

To dispatch every session as a specific agent, pass --agent <name> when opening agent view. This overrides the agent setting for dispatched sessions:

claude agents --agent code-reviewer

Without --agent, dispatched sessions use the agent setting from the working directory's settings.json if one is configured there.

Agent-view page: "Settings, plugins, and MCP servers" table

Add a row for --agent:

| --agent <name> | Set the default agent for dispatched sessions (overrides the agent setting) |

CLI reference: claude agents entry

Add --agent to the list of accepted flags:

Pass --agent, --permission-mode, --model, or --effort to set defaults for dispatched sessions.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version reference: This feature was introduced in Claude Code v2.1.157. The agent setting in settings.json is now honored for dispatched sessions, and --agent <name> is accepted by claude agents to override it.