Allow configuring mach6 skill agent models via settings with TUI ranking

[maxscheurer]

Closes #219

Add a mach6.models section in settings to configure subagent model fallback lists without copying entire agent .md files. Includes a new TUI RankedList component for intuitive model priority ordering, and stale-key validation to safeguard against upstream agent renames.

Implementation plan posted as a comment below.

[maxscheurer]

Implementation Plan

Analysis

The feature needs 4 layers of changes:

1. Settings type + persistence — Add mach6 section to the Settings interface with getters/setters
2. Model resolution injection — Thread settings into executeSingle so mach6.models overrides are consulted between per-invocation override and agent definition
3. Stale-key validation — Warn when mach6.models references agent names not found in the discovered agent map
4. TUI — New RankedList component in @dreb/tui + "Mach6 Models" submenu in settings selector

Deliverables

1. Settings interface & persistence (packages/coding-agent)

• Add Mach6Settings interface: { models?: Record<string, string[]> }
• Add mach6?: Mach6Settings to Settings interface
• Add getters/setters in SettingsManager:
  • getMach6Models(): Record<string, string[]> (merged view)
  • getMach6ModelsForAgent(name: string): string[] | undefined
  • setMach6ModelsForAgent(name: string, models: string[]): void
  • removeMach6ModelsForAgent(name: string): void
• Nested key tracking via markModified("mach6", "models")

2. Model resolution override (packages/coding-agent)

• Add settingsManager?: SettingsManager to SubagentToolOptions
• In executeSingle: after checking modelOverride, before falling through to config.model, check settingsManager?.getMach6ModelsForAgent(agentName)
• Wire settingsManager: this._settingsManager in agent-session.ts subagent options
• Resolution order: per-invocation modelOverride → mach6.models[agentName] → config.model → parent model fallback

3. Stale-key validation

• In executeSingle, when mach6.models has a key matching the requested agent but the agent is not in the discovered map, emit a warning via onProgress
• At TUI settings load time, validate keys against discovered agents and show stale entries distinctly (e.g., dimmed with a warning icon)

4. RankedList component (packages/tui)

• New file: packages/tui/src/components/ranked-list.ts
• Implements Component interface
• Items: { value: string; label: string; description?: string }[]
• Keyboard: up/down to navigate, Shift+up/Shift+down to reorder, Enter to add (opens model picker), Delete/Backspace to remove, Escape to close
• Renders numbered list with position indicators (e.g., 1. anthropic/opus, 2. anthropic/sonnet)
• Callbacks: onChange(items: string[]), onCancel()
• Export from packages/tui/src/index.ts

5. TUI settings integration (packages/coding-agent)

• Add "Mach6 Models" section header + per-agent items in settings-selector.ts
• Each agent item shows current override (or "default" if not overridden)
• Submenu opens a RankedList pre-populated with current models
• "Add model" sub-flow: SelectList of authenticated models from registry
• Callbacks: onMach6ModelChange(agentName, models) added to SettingsCallbacks
• Agent list sourced from discoverAgentTypes() — passed via SettingsConfig

6. Documentation

• Create packages/coding-agent/docs/mach6-models.md documenting the mach6.models setting
• Update root README.md if it mentions skill/agent configuration

Files to Create or Modify

File	Action
packages/tui/src/components/ranked-list.ts	Create — new reorderable list component
packages/tui/src/index.ts	Modify — export RankedList
packages/coding-agent/src/core/settings-manager.ts	Modify — add Mach6Settings, getters/setters
packages/coding-agent/src/core/tools/subagent.ts	Modify — add settings to options, inject into resolution
packages/coding-agent/src/core/agent-session.ts	Modify — wire settingsManager into subagent options
packages/coding-agent/src/modes/interactive/components/settings-selector.ts	Modify — add Mach6 Models section
packages/coding-agent/src/modes/interactive/interactive-mode.ts	Modify — wire new callbacks in showSettingsSelector()
packages/tui/test/ranked-list.test.ts	Create — unit tests for RankedList
packages/coding-agent/test/subagent-mach6-models.test.ts	Create — tests for settings-based model override
packages/coding-agent/docs/mach6-models.md	Create — documentation

Testing Approach

1. packages/tui/test/ranked-list.test.ts (Node test runner):

   • Renders items in numbered order
   • Up/down navigation with wrap
   • Shift+up/down reorders items and fires onChange
   • Delete removes item and fires onChange
   • Escape fires onCancel
   • Empty list renders placeholder

2. packages/coding-agent/test/subagent-mach6-models.test.ts (Vitest):

   • executeSingle with mach6.models override picks settings model over agent definition
   • Per-invocation modelOverride still takes precedence over settings
   • Missing settings key falls through to agent definition
   • Empty array [] treated as "no override" (falls through)
   • Stale key emits warning via onProgress

3. Existing test suites — verify no regressions in subagent-model-fallback.test.ts and subagent-model-override.test.ts

Acceptance Criteria

• settings.json with mach6.models overrides agent models without copying .md files
• Per-invocation model override still takes highest precedence
• Global and project settings merge correctly (project mach6.models replaces global)
• TUI /settings shows "Mach6 Models" with reorderable ranked list per agent
• Stale agent name keys produce a visible warning
• All existing subagent tests pass unchanged
• New tests cover the settings override path and RankedList component

Risks & Open Questions

• Modifier key detection: Shift+up/down produces different escape sequences across terminals. The keybindings system may need new entries (tui.select.moveUp / tui.select.moveDown). Fallback: use [/] or +/- keys for reordering.
• Agent enumeration for TUI: discoverAgentTypes() runs at tool creation time. Need to pass the agent name list to the settings UI via SettingsConfig.
• deepMerge depth: mach6.models is 2 levels deep. Current deepMergeSettings does one-level shallow merge, so project mach6 → { ...global.mach6, ...project.mach6 } meaning project models replaces global models entirely. Acceptable behavior, to be documented.

---

Plan created by mach6

[maxscheurer]

Progress Update

Full implementation committed and pushed.

Changes:

• agentModels settings key (renamed from mach6 — cleaner JSON and not mach6-specific)
• RankedList TUI component with [/] for reorder, Delete to remove, Enter to add
• Agent Models submenu in /settings — single entry, opens agent picker, then ranked model list with searchable add-model picker
• Model resolution: per-invocation override → agentModels settings → agent definition → parent model fallback
• Running agent progress shows the model being used: Running Explore agent (claude-sonnet-4-6)...
• Fix for pre-existing flaky test in bash-truncation.test.ts
• Fix for pre-existing build error in packages/agent (stale model name)
• New tests: 14 for settings-based model override, 11 for RankedList component
• Docs: packages/coding-agent/docs/mach6-models.md

Example settings.json:

{
  "agentModels": {
    "models": {
      "feature-dev": ["anthropic/claude-opus-4-6"],
      "explore": ["anthropic/claude-sonnet-4-6"]
    }
  }
}

Commit: 3bce663

---

Progress tracked by mach6