[FEATURE] Agent definitions: optional condition on the main-loop model
Preflight Checklist
- [x] I have searched existing requests
- [x] This is a single feature request (not multiple features)
Problem Statement
A subagent definition (.claude/agents/*.md) is registered and offered to the main loop whatever model the main loop runs on. No frontmatter key or setting says "offer this agent only when the session model is X".
The right delegation target often depends on the main-loop model:
- An escalation agent pinned to a stronger model (
model: fable) is useful from an Opus or Sonnet main loop. From a session already running that model it is a same-model round trip. - A cheap bulk-reading agent (
model: haiku) is the right default from an expensive main loop and needless indirection from a session already running the cheap model.
Today the description text has to carry the condition ("use from an Opus main loop"), and the model has to notice its own model id and comply. The agent stays in the roster and in the prompt either way.
Proposed Solution
An optional frontmatter key on agent definitions, for example:
---
name: advisor
description: Second opinion at a judgment wall
model: fable
when-model: [opus, sonnet] # offer this agent only when the main loop runs one of these
---
- Values: the same aliases
model:accepts (opus,sonnet,haiku,fable) or a full model id. - An agent whose condition is false is not listed to the main loop and cannot be spawned.
- The condition is re-evaluated when the session model changes (
/model). - A negative form (
unless-model: [fable]) would cover the same cases.
Alternative Solutions
- The condition in the description text: what I do now; nothing enforces it.
- A SessionStart hook that reads the session model and injects a per-model routing note: what I also do now. It is prompt text steering a choice the harness could make, and it costs context in every session.
- A
permissions.denyruleAgent(<name>): it removes the agent, but it is static and cannot follow the session model. - One agent directory per model, swapped by a wrapper before launch: breaks as soon as the model changes mid-session.
Priority
Medium - Would be very helpful
Feature Category
Configuration and settings
Use Case Example
- I keep an
advisoragent withmodel: fablefor hard design calls and abulkagent withmodel: sonnetfor high-volume reading. - In an Opus session both are useful: Opus escalates to
advisorand hands reading tobulk. - In a Fable session
advisoris the same model as the main loop, so a call to it buys nothing. In a Sonnet session the same is true ofbulk. - With
when-model:each agent is offered only where it helps, and the routing note goes away.
Additional Context
Checked on version 2.1.296.
Related but different: #73931 asked for a declared fallback model per subagent, which changes the model an agent runs on. This request is about whether the agent is offered at all.