fix: persist user model preference across sessions (#284)

.squad-templates/squad.agent.md

@@ -311,7 +311,13 @@ For read-only queries, use the explore agent: `agent_type: "explore"` with `"You
 
 Before spawning an agent, determine which model to use. Check these layers in order — first match wins:
 
-**Layer 1 — User Override:** Did the user specify a model? ("use opus", "save costs", "use gpt-5.2-codex for this"). If yes, use that model. Session-wide directives ("always use haiku") persist until contradicted.
+**Layer 0 — Persistent Config (`.squad/config.json`):** On session start, read `.squad/config.json`. If `agentModelOverrides.{agentName}` exists, use that model for this specific agent. Otherwise, if `defaultModel` exists, use it for ALL agents. This layer survives across sessions — the user set it once and it sticks.
+
+- **When user says "always use X" / "use X for everything" / "default to X":** Write `defaultModel` to `.squad/config.json`. Acknowledge: `✅ Model preference saved: {model} — all future sessions will use this until changed.`
+- **When user says "use X for {agent}":** Write to `agentModelOverrides.{agent}` in `.squad/config.json`. Acknowledge: `✅ {Agent} will always use {model} — saved to config.`
+- **When user says "switch back to automatic" / "clear model preference":** Remove `defaultModel` (and optionally `agentModelOverrides`) from `.squad/config.json`. Acknowledge: `✅ Model preference cleared — returning to automatic selection.`
+
+**Layer 1 — Session Directive:** Did the user specify a model for this session? ("use opus for this session", "save costs"). If yes, use that model. Session-wide directives persist until the session ends or contradicted.
 
 **Layer 2 — Charter Preference:** Does the agent's charter have a `## Model` section with `Preferred` set to a specific model (not `auto`)? If yes, use that model.
 

.squad/config.json

@@ -1,3 +1,4 @@
 {
-  "version": 1
+  "version": 1,
+  "defaultModel": "claude-sonnet-4.6"
 }

.squad/skills/model-selection/SKILL.md

@@ -0,0 +1,117 @@
+# 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 18+ models 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 | Code → sonnet, docs → haiku, visual → opus | Computed per-spawn |
+| **4** | Default | `claude-haiku-4.5` | 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:
+   - Code (implementation, tests, refactoring, bug fixes) → `claude-sonnet-4.6`
+   - Prompts, agent designs → `claude-sonnet-4.6`
+   - Visual/design with image analysis → `claude-opus-4.6`
+   - Non-code (docs, planning, triage, changelogs) → `claude-haiku-4.5`
+6. FALLBACK Layer 4: `claude-haiku-4.5`
+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 (18+ models)
+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.`
+
+### 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-4.6",
+  "agentModelOverrides": {
+    "fenster": "claude-sonnet-4.6",
+    "mcmanus": "claude-haiku-4.5"
+  }
+}
+```
+
+- `defaultModel` — applies to ALL agents unless overridden by `agentModelOverrides`
+- `agentModelOverrides` — per-agent overrides that take priority over `defaultModel`
+- Both 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-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.6
+Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex → claude-sonnet-4
+Fast:     claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini
+```
+
+**Never fall UP in tier.** A fast task won't land on a premium model via fallback.

docs/src/content/docs/features/model-selection.md

@@ -3,7 +3,12 @@
 > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
 
-**Try this to prioritize quality for the session:**
+**Try this to set a persistent preference (survives across sessions):**
+```
+Always use Opus
+```
+
+**Try this to prioritize quality for the session only:**
 ```
 Have all agents use Opus for the rest of this session
 ```
@@ -18,21 +23,27 @@ Switch to Haiku — I'm trying to save costs
 Use Sonnet for code, Haiku for everything else
 ```
 
-Squad adjusts model selection based on your directive. Agents writing code get quality models (Sonnet/Opus), agents doing docs/logs get cost-optimized models (Haiku). You can override anytime.
+**Try this to go back to automatic selection:**
+```
+Switch back to automatic model selection
+```
+
+Squad adjusts model selection based on your directive. Agents writing code get quality models (Sonnet/Opus), agents doing docs/logs get cost-optimized models (Haiku). You can override anytime — and persistent overrides survive across sessions.
 
 ---
 
 ## How It Works
 
-Squad routes each agent to the right model based on what they're doing — not a one-size-fits-all default. The governing principle: **cost first, unless code is being written.**
+Squad routes each agent to the right model based on what they're doing — not a one-size-fits-all default. The governing principle: **cost first, unless code is being written** — but your preferences always take priority.
 
-## How It Works
+## 5-Layer Model Resolution
 
 Model selection uses a layered system. First match wins:
 
-1. **User Override** — You said "use opus" or "save costs"? Done. Session-wide directives persist until contradicted.
-2. **Charter Preference** — The agent's charter specifies a `## Model` section with a preferred model.
-3. **Task-Aware Auto-Selection** — The coordinator checks what the agent is actually doing:
+1. **Persistent Config** (`.squad/config.json`) — You said "always use opus"? It's saved to disk. Every session, every agent, until you change it. Per-agent overrides (`agentModelOverrides`) take priority over the global `defaultModel`.
+2. **Session Directive** — You said "use opus for this session"? Done. Applies until the session ends.
+3. **Charter Preference** — The agent's charter specifies a `## Model` section with a preferred model.
+4. **Task-Aware Auto-Selection** — The coordinator checks what the agent is actually doing:
 
 | Task Output | Model | Tier |
 |-------------|-------|------|
@@ -41,7 +52,26 @@ Model selection uses a layered system. First match wins:
 | Non-code work (docs, planning, triage, changelogs) | `claude-haiku-4.5` | Fast |
 | Visual/design work requiring image analysis | `claude-opus-4.6` | Premium |
 
-4. **Default** — If nothing matched, `claude-haiku-4.5`. Cost wins when in doubt.
+5. **Default** — If nothing matched, `claude-haiku-4.5`. Cost wins when in doubt.
+
+## Persistent Model Preferences
+
+Squad stores your model preferences in `.squad/config.json`:
+
+```json
+{
+  "version": 1,
+  "defaultModel": "claude-opus-4.6",
+  "agentModelOverrides": {
+    "fenster": "claude-sonnet-4.6",
+    "mcmanus": "claude-haiku-4.5"
+  }
+}
+```
+
+- **`defaultModel`** — applies to ALL agents unless overridden. Set with "always use X".
+- **`agentModelOverrides`** — per-agent overrides. Set with "use X for {agent}".
+- **Clear with** "switch back to automatic" — removes `defaultModel`, returns to auto-selection.
 
 ## Role-to-Model Mapping
 
@@ -80,9 +110,10 @@ Never falls back UP in tier — a fast task won't land on a premium model.
 
 Tell the coordinator what you want:
 
-- `"use opus for this"` — one-off premium
-- `"always use haiku"` — session-wide cost savings
-- `"use gpt-5.2-codex for Fenster"` — agent-specific override
+- `"use opus for this"` — one-off premium for current task
+- `"always use opus"` — **persistent** preference saved to `.squad/config.json` (survives sessions)
+- `"use gpt-5.2-codex for Fenster"` — **persistent** per-agent override
+- `"switch back to automatic"` — clears persistent preference
 
 ## Sample Prompts