[FEATURE] Per-subagent availability fallback model (declarative), not just silent inherit

Open 💬 1 comment Opened Jul 3, 2026 by flound1129

Summary

A subagent definition can pin a model: (e.g. claude-fable-5), but there is no way to declare what that subagent should fall back to if the pinned model is unavailable, overloaded, or excluded. Today it silently runs on the inherited (main-session) model, and the fallback target is not controllable. The session-level fallback chain (fallbackModel / --fallback-model) is documented as applying to the main model, not to subagents. Please let a subagent declare its own availability-fallback model (or extend the fallback chain to subagent resolution).

Scope note: this is about availability / capacity fallback (model overloaded, unavailable, or excluded by allowlist) — not the Fable 5 content-refusal fallback. Please don't dedupe against the refusal-fallback reports (e.g. #66822, #67415, #73330, #73833); that is a separate mechanism.

Motivation / use case

I run reasoning-heavy subagents (a math "prover" / "professor") pinned to claude-fable-5[1m]. If Fable is unavailable, I want them to fall back to a specific, task-chosen model — claude-opus-4-8[1m] — not to "whatever model the main session happens to be on." A collaborator invoking the same agents from a Haiku session would silently get Haiku for work that needs Opus-tier reasoning, with no error and no way to prevent it.

Current behavior (documented)

  • sub-agents.md: the model frontmatter field accepts a single value — sonnet | opus | haiku | fable, a full id such as claude-opus-4-8, or inherit (default). No list syntax, no fallback: field.
  • Resolution order is CLAUDE_CODE_SUBAGENT_MODEL → per-invocation model → frontmatter model → main-conversation model — each a single value, not a chain.
  • When the pinned value resolves to an excluded model (org availableModels allowlist), Claude Code "skips a value that resolves to an excluded model and runs the subagent on the inherited model instead" — so the fallback target is fixed to the inherited model, not configurable.
  • model-config.md: fallbackModel (settings.json array) and --fallback-model (CLI, --print only) provide availability fallback for the session / main model and do not extend to subagents.

Requested

Any one of:

  1. Let the subagent model: field accept an ordered list (first available wins), e.g. model: [claude-fable-5, claude-opus-4-8]; or
  2. Add a dedicated fallbackModel: frontmatter field to subagent definitions; and/or
  3. Extend the session fallbackModel chain so it also governs subagent model resolution, with the subagent's own pin taking precedence while available.

Why inherit is not enough

The effective fallback becomes "the session model," which varies by caller and can be a far weaker tier than the task requires. There is currently no way to express "use Fable, else Opus" for a given subagent.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗