design(gt-yy9v): architecture for model selection by role

Adds comprehensive design document for GitHub issue gastownhall#335:
"Ability to choose models for different roles"

Contents:
- requirements.md - Problem statement and success criteria
- codebase-context.md - Relevant code patterns and integration points
- 6 dimension analyses: api.md, data.md, ux.md, scale.md, security.md, integration.md
- design-doc.md - Unified design document with Rule-of-5 refinement

Key finding: This feature works today with no code changes.
Users can define agent variants with --model flags and map them
via role_agents in ~/gt/settings/config.json.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: furiosa

.designs/gt-yy9v/api.md

@@ -0,0 +1,244 @@
+# API & Interface Design: Model Selection by Role
+
+## Command-Line Interface
+
+### Option A: Using Existing RoleAgents (Recommended)
+
+No new CLI flags needed. Users define agent presets with models baked in:
+
+```bash
+# Town-level config: ~/gt/settings/agents.json
+{
+  "version": 1,
+  "agents": {
+    "claude-opus": {
+      "command": "claude",
+      "args": ["--dangerously-skip-permissions", "--model", "opus-4.5"]
+    },
+    "claude-sonnet": {
+      "command": "claude",
+      "args": ["--dangerously-skip-permissions", "--model", "sonnet-4"]
+    },
+    "claude-haiku": {
+      "command": "claude",
+      "args": ["--dangerously-skip-permissions", "--model", "haiku-3.5"]
+    }
+  }
+}
+
+# Town-level settings: ~/gt/settings/config.json
+{
+  "type": "town-settings",
+  "version": 1,
+  "default_agent": "claude-opus",
+  "role_agents": {
+    "polecat": "claude-opus",
+    "witness": "claude-sonnet",
+    "refinery": "claude-haiku",
+    "mayor": "claude-sonnet",
+    "deacon": "claude-sonnet",
+    "crew": "claude-sonnet"
+  }
+}
+```
+
+### Option B: New --model Flag (Alternative)
+
+Add explicit model flag to spawn commands:
+
+```bash
+# Override at spawn time
+gt sling <bead> <rig> --model sonnet
+
+# Show current model config
+gt config models
+
+# Set role model
+gt config set role-model polecat opus
+gt config set role-model witness sonnet
+```
+
+### Subcommand Ergonomics
+
+If implementing Option B, new commands would be:
+
+```bash
+# View all model assignments
+gt config models
+# Output:
+# Role       Model         Source
+# ----       -----         ------
+# polecat    opus-4.5      rig (gastown)
+# witness    sonnet-4      town
+# refinery   haiku-3.5     default
+# crew       sonnet-4      town
+
+# Set model for a role
+gt config set-model <role> <model>
+
+# List available models
+gt config list-models
+# Output: opus-4.5, sonnet-4, haiku-3.5
+```
+
+## Programmatic API
+
+### Configuration Interface (Go)
+
+For Option A (agent presets with models):
+```go
+// No API changes needed - use existing RoleAgents
+
+// Get agent for role (existing function)
+func ResolveRoleAgentConfig(role string, rigSettings *RigSettings, townSettings *TownSettings) (*AgentPresetInfo, error)
+```
+
+For Option B (explicit model field):
+```go
+// New function to resolve model
+func ResolveRoleModel(role string, rigSettings *RigSettings, townSettings *TownSettings) string
+
+// Extended TownSettings
+type TownSettings struct {
+    // ...existing fields...
+    RoleModels map[string]string `json:"role_models,omitempty"`
+}
+
+// Extended RigSettings
+type RigSettings struct {
+    // ...existing fields...
+    RoleModels map[string]string `json:"role_models,omitempty"`
+}
+```
+
+### Return Types
+
+Model resolution returns a simple string:
+- `"opus-4.5"` | `"sonnet-4"` | `"haiku-3.5"` | `""`
+
+Empty string means "use Claude's default" (currently Opus 4.5).
+
+## Configuration Interface
+
+### File Locations
+
+| Level | File | Purpose |
+|-------|------|---------|
+| Town | `~/gt/settings/agents.json` | Custom agent definitions with model args |
+| Town | `~/gt/settings/config.json` | Default agent and role_agents mapping |
+| Rig | `<rig>/settings/agents.json` | Rig-specific agent definitions |
+| Rig | `<rig>/settings/config.json` | Rig-specific overrides |
+
+### Environment Variables
+
+For runtime override (useful for debugging/testing):
+```bash
+GT_MODEL_OVERRIDE=haiku  # Forces all roles to use haiku
+```
+
+Not recommended for production use - config files are better for persistence.
+
+## Error Messages
+
+### Invalid Model Name
+```
+Error: unknown model "gpt4"
+Available models: opus-4.5, sonnet-4, haiku-3.5
+```
+
+### Invalid Role Name
+```
+Error: unknown role "worker"
+Valid roles: polecat, witness, refinery, mayor, deacon, crew
+```
+
+### Config Validation
+```
+Warning: role_agents references undefined agent "claude-fast"
+Available agents: claude, claude-opus, claude-sonnet, claude-haiku, gemini, codex
+```
+
+## Help Text
+
+```
+MODEL SELECTION
+
+Gas Town supports per-role model selection for cost optimization.
+
+Configuration:
+  Define agent presets with model args in ~/gt/settings/agents.json:
+
+  {
+    "agents": {
+      "claude-opus": {"command": "claude", "args": ["--model", "opus-4.5"]},
+      "claude-sonnet": {"command": "claude", "args": ["--model", "sonnet-4"]}
+    }
+  }
+
+  Then assign to roles in ~/gt/settings/config.json:
+
+  {
+    "role_agents": {
+      "polecat": "claude-opus",
+      "witness": "claude-sonnet"
+    }
+  }
+
+Resolution order:
+  1. Rig role_agents (if set)
+  2. Town role_agents (if set)
+  3. Rig default_agent (if set)
+  4. Town default_agent (if set)
+  5. Built-in default: "claude"
+```
+
+## Naming Conventions
+
+### Model Names
+Use Claude Code's short names for ergonomics:
+- `opus` → `opus-4.5` (aliases work)
+- `sonnet` → `sonnet-4`
+- `haiku` → `haiku-3.5`
+
+### Agent Preset Names
+Convention: `<cli>-<model>` for model variants:
+- `claude-opus` (Claude with Opus)
+- `claude-sonnet` (Claude with Sonnet)
+- `claude-haiku` (Claude with Haiku)
+
+## Discoverability
+
+### How Users Learn This Feature
+
+1. **Documentation**: Add section to Gas Town README and `gt help config`
+2. **Example configs**: Ship example `agents.json` with model presets
+3. **Status command**: `gt status` shows current model for each active agent
+4. **Cost reporting**: `gt costs` shows model breakdown (existing feature)
+
+### Happy Path
+
+1. User wants to reduce costs
+2. Runs `gt help config` or reads docs
+3. Copies example agent definitions to settings
+4. Maps roles to agents via `role_agents`
+5. Starts Gas Town - polecats run on Opus, others on Sonnet/Haiku
+
+### Edge Cases
+
+1. **Undefined agent**: Config references agent not in registry → warning, fall back to default
+2. **Invalid model**: Claude rejects model name → agent fails to start, error in logs
+3. **Mixed models in rig**: Different polecats in same rig can't use different models (by design)
+
+## Consistency with Existing Interfaces
+
+### Follows Existing Patterns
+
+- Uses same config file locations (`settings/config.json`, `settings/agents.json`)
+- Uses same resolution hierarchy (rig → town → default)
+- Uses same JSON schema patterns (`map[string]string` for mappings)
+- Uses existing `RoleAgents` field (Option A)
+
+### Changes from Existing Patterns
+
+- Option B would add a new `RoleModels` field (parallel to `RoleAgents`)
+- New CLI flags if implementing `gt config set-model`

.designs/gt-yy9v/codebase-context.md

@@ -0,0 +1,148 @@
+# Codebase Context: Model Selection by Role
+
+## Relevant Files
+
+| File | Purpose | Relevance |
+|------|---------|-----------|
+| `internal/config/types.go` | Config type definitions | Contains `TownSettings`, `RigSettings` with `RoleAgents` map - infrastructure exists but for agents, not models |
+| `internal/config/agents.go` | Agent registry and presets | Defines agent presets (claude, gemini, etc.) and `AgentPresetInfo` - could be extended for model selection |
+| `internal/config/loader.go` | Config loading and resolution | `ResolveRoleAgentConfig()` resolves role → agent mapping; command building would need `--model` injection |
+| `internal/cmd/polecat_spawn.go` | Polecat spawning | `SpawnPolecatForSling()` creates polecats; uses `BuildPolecatStartupCommandWithAgentOverride()` |
+| `internal/cmd/start.go` | Agent startup orchestration | Manager `Start()` methods for each role type |
+| `internal/polecat/session_manager.go` | Session management | `SessionStartOptions` - could pass model selection here |
+| `internal/cmd/sling.go` | Work dispatch | `gt sling` supports `--agent` flag, could add `--model` |
+
+## Existing Patterns
+
+### Role-Based Agent Selection (Already Exists)
+
+The codebase already supports per-role agent selection via `RoleAgents`:
+
+```go
+// types.go lines 53-58 (TownSettings)
+RoleAgents map[string]string `json:"role_agents,omitempty"`
+// Example: {"mayor": "claude", "witness": "gemini", "polecat": "claude"}
+
+// types.go lines 221-226 (RigSettings)
+RoleAgents map[string]string `json:"role_agents,omitempty"`
+// Example: {"witness": "claude-haiku", "polecat": "claude-sonnet"}
+```
+
+### Resolution Hierarchy
+
+Config resolution follows this precedence (loader.go):
+1. `agentOverride` flag (e.g., `--agent gemini`)
+2. Rig-level `RigSettings.Agent` or `RigSettings.RoleAgents[role]`
+3. Town-level `TownSettings.DefaultAgent` or `TownSettings.RoleAgents[role]`
+4. Ultimate fallback: `"claude"`
+
+### Command Building
+
+Startup commands are built with:
+```go
+// loader.go line 1294
+BuildPolecatStartupCommand(rigName, polecatName, rigPath, prompt string) string
+// Results in: "claude --dangerously-skip-permissions ..."
+```
+
+The `Args` array from `AgentPresetInfo` or `RuntimeConfig` gets appended to the command.
+
+## Key Data Structures
+
+### AgentPresetInfo (agents.go)
+```go
+type AgentPresetInfo struct {
+    Name    AgentPreset // "claude"
+    Command string      // "claude"
+    Args    []string    // ["--dangerously-skip-permissions"]
+    // ... other fields
+}
+```
+
+### RuntimeConfig (types.go)
+```go
+type RuntimeConfig struct {
+    Command string   // "claude"
+    Args    []string // ["--dangerously-skip-permissions"]
+    // ... other fields
+}
+```
+
+**Key insight**: `Args` is where `--model opus` would be injected.
+
+### TownSettings / RigSettings
+Both have:
+- `DefaultAgent string` - which agent preset to use
+- `Agents map[string]*RuntimeConfig` - custom agent definitions
+- `RoleAgents map[string]string` - role → agent mapping
+
+## Integration Points
+
+### Where Model Selection Could Be Injected
+
+1. **At Config Level** - New field in `TownSettings`/`RigSettings`:
+   ```go
+   RoleModels map[string]string `json:"role_models,omitempty"`
+   // {"polecat": "opus", "witness": "sonnet", "refinery": "haiku"}
+   ```
+
+2. **At Agent Definition Level** - Add `Model` to `AgentPresetInfo`:
+   ```go
+   type AgentPresetInfo struct {
+       // ...existing fields...
+       Model string `json:"model,omitempty"` // "opus", "sonnet", "haiku"
+   }
+   ```
+
+3. **At Command Building** - Inject `--model` in `BuildStartupCommand`:
+   ```go
+   // In BuildStartupCommand or normalizeRuntimeConfig
+   if model != "" {
+       args = append(args, "--model", model)
+   }
+   ```
+
+4. **At Spawn Time** - Add `--model` flag to `gt sling`:
+   ```bash
+   gt sling <bead> <rig> --model sonnet
+   ```
+
+### Claude Code --model Flag
+
+Claude Code accepts `--model` flag:
+```bash
+claude --model opus-4.5          # Use Opus 4.5
+claude --model sonnet-4          # Use Sonnet 4
+claude --model haiku-3.5         # Use Haiku 3.5
+```
+
+This is the mechanism to leverage.
+
+## Constraints from Code
+
+1. **Backwards Compatibility**: `RoleAgents` already exists - new model config must coexist
+2. **Command Building**: All paths must flow through `BuildStartupCommand*` functions
+3. **Agent Presets**: Model could be per-preset (define "claude-opus", "claude-sonnet") OR per-role
+4. **Session Persistence**: Claude remembers model per session - must set on every init
+5. **Multiple Resolution Layers**: Town → Rig → Role → Override hierarchy must be maintained
+
+## Recommended Approach
+
+Based on the existing patterns, the cleanest approach is:
+
+**Option A: Model as Agent Variant** (Minimal Changes)
+- Define agent presets: `"claude-opus"`, `"claude-sonnet"`, `"claude-haiku"`
+- Use existing `RoleAgents` map: `{"polecat": "claude-opus", "witness": "claude-sonnet"}`
+- Add `--model` to preset Args
+
+**Option B: Separate RoleModels Config** (More Flexible)
+- Add `RoleModels map[string]string` to `TownSettings`/`RigSettings`
+- Resolve model separately from agent
+- Inject `--model` in command building
+
+**Option C: Model in RuntimeConfig** (Most Granular)
+- Add `Model string` field to `RuntimeConfig`
+- Allow per-agent model specification
+- Most flexible but more complex
+
+Given the issue request ("role-based configuration"), **Option A** is simplest and works with existing infrastructure.