[DOCS] Contradiction in Subagent Model Inheritance: Documentation vs. v2.1.0 Behavior

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Supported frontmatter fields" table and the "Choose a model" section.

Current Documentation

The table under "Supported frontmatter fields" states:

"model ... Defaults to sonnet"

The "Choose a model" section states:

"Omitted: If not specified, uses the default model configured for subagents (sonnet)"

What's Wrong or Missing?

There is a contradiction between the current guide and the documented behavior in recent updates. The documentation currently states that the model defaults to sonnet. However, according to the version 2.1.0 release notes, subagents were fixed to inherit the parent's model by default. This makes the "Defaults to sonnet" claim incorrect and misleading for users who expect their subagents to use the same model (e.g., Opus or Haiku) as their primary session.

Suggested Improvement

Update the documentation to reflect that the default behavior is now inheritance.

Suggested text for the frontmatter table:

model | No | Model to use: sonnet, opus, haiku, or inherit. Defaults to inherit (uses the same model as the parent conversation).

Suggested text for the "Choose a model" section:

Omitted: If not specified, the subagent inherits the model from the parent conversation (behavior introduced in v2.1.0).

Impact

High - Prevents users from using a feature

Additional Context

The release notes for version 2.1.0 explicitly state: "Fixed subagents sometimes not inheriting the parent's model by default."

Ensuring the guide aligns with this fix will prevent confusion when users switch to a high-reasoning model like opus and expect subagents to utilize that same intelligence level without explicit configuration.

Related documentation: https://code.claude.com/docs/en/sub-agents#choose-a-model