Docs: fallbackModel behavior for subagents with frontmatter-pinned models is unspecified

Summary

The interaction between fallbackModel (settings.json) and subagents whose model is pinned via agent-definition frontmatter is not documented. It's unclear whether a subagent API call gets fallback-chain retries when its pinned model is overloaded/unavailable, or whether the subagent simply fails and reports back to the orchestrator.

Context

• Claude Code v2.1.227 (native, darwin-arm64)
• ~/.claude/settings.json: "model": "claude-fable-5[1m]", "fallbackModel": ["opus", "sonnet"]
• Custom agents in ~/.claude/agents/ with frontmatter-pinned models (e.g. model: sonnet, model: haiku) as a cost-tiering setup

What the docs say today

• Model configuration — fallback chains: "When the primary model is overloaded, unavailable, or returns another non-retryable server error, Claude Code can switch to a fallback model instead of failing the request." No mention of subagents.
• Subagents — documents the model resolution order (env var → per-invocation → frontmatter → session model), but not what happens when the resolved model is unavailable mid-task. The API-errors section says a subagent that hits "a usage limit, overload, or server error" reports the failure back to the orchestrator, without specifying whether fallback is attempted first.

Ask

Document the actual behavior explicitly, whichever it is:

1. fallbackModel applies only to the main-loop/session model; subagent calls fail and surface the error to the orchestrator (no automatic fallback), or
2. subagent calls also walk the fallback chain (and if so, whether the chain or the session model is tried first).

If (1) is the current behavior, a note in both docs pages would let users design their tiering around orchestrator-side retry/escalation deliberately. Subagent-level fallback (or a per-agent fallbackModel frontmatter key) would also be a welcome feature, but the immediate ask is just documenting the current semantics.