[DOCS] Conflicting information regarding Plan subagent model vs. Opus 4.5 reasoning

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents#plan-subagent https://code.claude.com/docs/en/model-config#opusplan-model-setting

Section/Topic

Built-in subagents > Plan subagent and Model Aliases (opusplan)

Current Documentation

The "Subagents" page under "Built-in subagents" states:

Plan subagent Model: Uses Sonnet for more capable analysis

The "Model configuration" page states:

opusplan model setting In plan mode - Uses opus for complex reasoning and architecture decisions In execution mode - Automatically switches to sonnet for code generation and implementation

What's Wrong or Missing?

There is a direct contradiction and a lack of clarity regarding which model handles the "Planning" phase in versions 2.1.0 and higher:

1. Conflicting Models: The built-in subagents documentation explicitly says the Plan subagent uses Sonnet. However, the opusplan alias and the "Models overview" describe Opus 4.5 as the smartest model for premium reasoning.
2. Override Ambiguity: As of version 2.1.0, the Plan subagent is triggered automatically by the /plan command or EnterPlanMode tool. If the built-in agent is hardcoded to use Sonnet (as stated in the Subagents doc), it is not using the "smartest" reasoning available (Opus 4.5).
3. Redundancy/Logic Gap: If the Plan subagent is intended to be a "Software Architect," it is confusing why it would default to a less intelligent model than Opus 4.5, especially when the documentation for opusplan suggests that Opus is the preferred choice for the planning phase.
4. No Override Path: There is no documented way to tell the built-in Plan subagent to use Opus reasoning specifically, since subagents operate in isolated contexts and the /plan shortcut doesn't currently accept model overrides.

Suggested Improvement

The documentation should be updated to clarify the relationship between the built-in Plan subagent and the opusplan model alias:

1. Clarify Default: State clearly whether the Plan subagent uses Sonnet by default or if it respects the opusplan alias/Opus 4.5 when configured.
2. Update Subagent Table: If the Plan subagent can use Opus, update the "Built-in subagents" table to reflect that it uses the highest available reasoning model (Opus 4.5) when in opusplan mode.
3. Instruction for Best Reasoning: Provide a specific command or configuration (e.g., ANTHROPIC_MODEL=opusplan or claude --model opusplan) that ensures the Plan subagent utilizes Opus 4.5 for the architectural research phase.
4. Address Hardcoding: If the built-in subagent is indeed locked to Sonnet, provide a justification for why the "smartest" model isn't used for the planning phase, or provide a way to override it.

Impact

High - Prevents users from using a feature

Additional Context

Users frequently use /plan for complex refactors (touching 10+ files). If this phase is handled by the Sonnet-based Plan subagent instead of Opus 4.5, the architectural integrity of the plan may be lower than expected based on the "Models overview" performance claims.