[FEATURE] Managed Default for Sub Agent Model

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When orchestrating multi-agent workflows, CLAUDE_CODE_SUBAGENT_MODEL overrides the model for all spawned agents — including those that already have a model declared in their frontmatter or in the model: parameter of the Agent tool call. This makes it unusable as a "smart default." If I want to save cost by routing undeclared agents to Haiku, but still let specific agents (e.g. an Explore or code-reviewer) run on Sonnet as declared, I have no mechanism to do that. I must either pin everything (losing intentional declarations) or declare the model on every single Agent call (burdensome and error-prone).

The current workflow requires me to either:

• Accept that all agents use the parent model (expensive for lightweight tasks), or
• Explicitly pass model: on every Agent tool invocation, or
• Set CLAUDE_CODE_SUBAGENT_MODEL and have it clobber intentional frontmatter overrides.

Proposed Solution

Add a defaultSubAgentModel key to settings.json (both user-level ~/.claude/settings.json and project-level .claude/settings.json) that acts as a fallback only — applied strictly when no model is declared through a higher-priority mechanism.

Priority cascade (high → low):

1. model parameter in Agent(...) tool call
2. Agent definition frontmatter model: field
3. defaultSubAgentModel in project .claude/settings.json
4. defaultSubAgentModel in user ~/.claude/settings.json
5. Inherit from parent agent (current behavior)

Example config:
{
"defaultSubAgentModel": "claude-haiku-4-5-20251001"
}

With this in place, an Explore agent that has model: claude-sonnet-5 in its frontmatter keeps running on Sonnet. A general-purpose agent with no model declared falls back to Haiku. No per-call annotation needed.

Alternative Solutions

• CLAUDE_CODE_SUBAGENT_MODEL — exists today but is a hard pin, not a fallback. It overrides frontmatter and explicit model: parameters, making it incompatible with workflows that intentionally mix models across agent types.
• Manually annotate every Agent call — works but is verbose, fragile, and defeats the purpose of agent definitions having their own model declarations.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

1. I'm running a visa-dev workflow that fans out: an Explore agent (declared model: sonnet) for code search, a general-purpose agent (no model declared) for synthesis, and a Haiku-speed agent for boilerplate generation.
2. I add "defaultSubAgentModel": "claude-haiku-4-5-20251001" to my project settings.
3. The Explore agent still uses Sonnet (frontmatter respected). The general-purpose agent and boilerplate agent both fall back to Haiku.
4. This saves significant cost on lightweight agents without touching any agent definition files or adding model: to every Agent call.

Additional Context

Related closed issues: #33734, #25546, #16594 — all closed as "not planned" or duplicate, but none specifically frames the ask as fallback semantics vs. override semantics. The key distinction from CLAUDE_CODE_SUBAGENT_MODEL is that this setting must not override explicitly declared models — it only fills the gap. That makes it safe to set globally without disrupting purpose-built agents.