model-selection

# Model Selection > Determines which LLM model to use for each agent spawn. ## SCOPE ✅ THIS SKILL PRODUCES: - A resolved `model` parameter for every `task` tool call - Persistent model preferences in `.squad/config.json` - Spawn acknowledgments that include the resolved model ❌ THIS SKILL DOES NOT PRODUCE: - Code, tests, or documentation - Model performance benchmarks - Cost reports or billing artifacts ## Context Squad supports a curated model catalog across three tiers (premium, standard, fast). The coordinator must select the right model for each agent spawn. Users can set persistent preferences that survive across sessions. ## 5-Layer Model Resolution Hierarchy Resolution is **first-match-wins** — the highest layer with a value wins. | Layer | Name | Source | Persistence | |-------|------|--------|-------------| | **0a** | Per-Agent Config | `.squad/config.json` → `agentModelOverrides.{name}` | Persistent (survives sessions) | | **0b** | Global Config | `.squad/config.json` → `defaultModel` | Persistent (survives sessions) | | **1** | Session Directive | User said "use X" in current session | Session-only | | **2** | Charter Preference | Agent's `charter.md` → `## Model` section | Persistent (in charter) | | **3** | Task-Aware Auto | Task type → tier under the active quality profile (default `quality-first`) | Computed per-spawn | | **4** | Default | Head of the standard chain (`claude-sonnet-5.5`); `gpt-5.6-luna` under the `economy` profile | Hardcoded fallback | **Key principle:** Layer 0 (persistent config) beats everything. If the user said "always use opus" and it was saved to config.json, every agent gets opus regardless of role or task type. This is intentional — the user explicitly chose quality over cost. ## AGENT WORKFLOW ### On Session Start 1. READ `.squad/config.json` 2. CHECK for `defaultModel` field — if present, this is the Layer 0 override for all spawns 3. CHECK for `agentModelOverrides` field — if present, these are per-agent Layer 0a overrides 4. STORE both values in session context for the duration ### On Every Agent Spawn 1. CHECK Layer 0a: Is there an `agentModelOverrides.{agentName}` in config.json? → Use it. 2. CHECK Layer 0b: Is there a `defaultModel` in config.json? → Use it. 3. CHECK Layer 1: Did the user give a session directive? → Use it. 4. CHECK Layer 2: Does the agent's charter have a `## Model` section? → Use it. 5. CHECK Layer 3: Determine task type and use the head of its tier chain for the active profile (`quality-first` unless the session or `.squad/config.json` `modelProfile` says `balanced` or `economy`, or `economyMode` is on): - Architecture, research, verification, reviewer gates, security, design, visual → premium (`claude-opus-5.5`); `balanced` and `economy` move research down - Code (implementation, tests, refactoring, bug fixes), prompts, agent designs → standard (`claude-sonnet-5.5`) - Docs, writing, planning, triage → standard under `quality-first`; fast under `economy` (and planning under `balanced`) - Mechanical (Scribe, git, release, changelogs, version bumps) → fast (`claude-haiku-5.5`) - `economy` then applies the economy map (premium → standard, standard → `gpt-5.6-luna`) and says so in the rationale - `hydrafusion` (opt-in only) sends architecture, research, verification, reviewer gates, security and design to `hydrafusion`, then the premium chain; everything else (including visual and Scribe) follows `quality-first` 6. FALLBACK Layer 4: head of the standard chain; `gpt-5.6-luna` under `economy` 7. INCLUDE model in spawn acknowledgment: `🔧 {Name} ({resolved_model}) — {task}` ### When User Sets a Preference **Trigger phrases:** "always use X", "use X for everything", "switch to X", "default to X" 1. VALIDATE the model ID against the catalog 2. WRITE `defaultModel` to `.squad/config.json` (merge, don't overwrite) 3. ACKNOWLEDGE: `✅ Model preference saved: {model} — all future sessions will use this until changed.` **Per-agent trigger:** "use X for {agent}" 1. VALIDATE model ID 2. WRITE to `agentModelOverrides.{agent}` in `.squad/config.json` 3. ACKNOWLEDGE: `✅ {Agent} will always use {model} — saved to config.` **Profile trigger:** "use the {quality-first|balanced|economy|hydrafusion} profile" / "always use economy" 1. WRITE `modelProfile` to `.squad/config.json` (merge, don't overwrite); for "this session" only, keep it in session context instead 2. ACKNOWLEDGE: `✅ Model profile saved: {profile}` A profile never replaces an explicit model (config, session, charter or per-spawn), including an opt-in model the user chose. ### HydraFusion (research preview, opt-in) `hydrafusion` and `hydrafusion-max` are GitHub multi-model orchestration models in research preview. They may be unavailable, for example in corporate environments where preview models are turned off, so Squad never uses them by default: they are in no fallback chain, no GA profile and no example. The runtime runs the orchestration; Squad only passes the model ID. - **Opt in:** `modelProfile: "hydrafusion"` (or "use the hydrafusion profile for this session"), or pick `hydrafusion` as the session model, `defaultModel`, an `agentModelOverrides` entry or a per-spawn model. A session model is inherited by every sub-agent spawn. - **`hydrafusion-max`:** only when named explicitly by ID. Never chosen implicitly, even under the `hydrafusion` profile. - **Fallback:** when `hydrafusion` is unavailable, fall forward to the head of the premium chain; never back, never over the cost ceiling; omit the model if nothing in the ceiling is left. - **Unchanged:** Scribe and mechanical ops stay fast; reviewer gates still run. - **VS Code** uses the single session model for every agent; per-agent selection applies where Squad passes a model per spawn (Copilot CLI and app). ### When User Clears a Preference **Trigger phrases:** "switch back to automatic", "clear model preference", "use default models" 1. REMOVE `defaultModel` from `.squad/config.json` 2. ACKNOWLEDGE: `✅ Model preference cleared — returning to automatic selection.` ### STOP After resolving the model and including it in the spawn template, this skill is done. Do NOT: - Generate model comparison reports - Run benchmarks or speed tests - Create new config files (only modify existing `.squad/config.json`) - Change the model after spawn (fallback chains handle runtime failures) ## Config Schema `.squad/config.json` model-related fields: ```json { "version": 1, "defaultModel": "claude-opus-5.5", "modelProfile": "balanced", "agentModelOverrides": { "agent-alpha": "claude-sonnet-5.5", "agent-beta": "claude-haiku-5.5" } } ``` - `defaultModel` — applies to ALL agents unless overridden by `agentModelOverrides` - `agentModelOverrides` — per-agent overrides that take priority over `defaultModel` - `modelProfile` — `quality-first` (default), `balanced`, `economy` or `hydrafusion` (opt-in research preview); affects only Layers 3-4 - All fields are optional. When absent, Layers 1-4 apply normally. ## Fallback Chains If a model is unavailable (rate limit, plan restriction), retry within the same tier: ``` Premium: claude-opus-5.5 → gpt-6.1-sol → claude-opus-5 → gpt-6-sol → claude-opus-4.8 → gpt-5.6-sol → (omit model param) Standard: claude-sonnet-5.5 → gpt-5.6-terra → claude-sonnet-5 → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → (omit model param) Fast: claude-haiku-5.5 → gpt-6-luna → gpt-5.6-luna → gemini-3.8-flash → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini → (omit model param) ``` Chains list only public GA models (https://docs.github.com/en/copilot/reference/ai-models/supported-models, verified 2026-10-14). When the runtime supplies a live model list, it decides availability. **Never fall UP in tier.** A fast task won't land on a premium model via fallback.