[FEATURE] Agent definitions: optional condition on the main-loop model

Status Open
Reported on v2.1.296
Maintainer reply None cached
Activity 0 comments · opened Oct 11, 2026

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.deny rule Agent(<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

  1. I keep an advisor agent with model: fable for hard design calls and a bulk agent with model: sonnet for high-volume reading.
  2. In an Opus session both are useful: Opus escalates to advisor and hands reading to bulk.
  3. In a Fable session advisor is the same model as the main loop, so a call to it buys nothing. In a Sonnet session the same is true of bulk.
  4. 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.

View original on GitHub ↗