Customizable model-mapping config with CLI-managed defaults and user overrides #987

Squad already has model-selection concepts such as defaultModel, agentModelOverrides, economy mode, and session alignment, but it still lacks an explicit user-facing config for task-to-model mapping.

Right now, users who want a policy such as:

• coding -> gpt-5.4
• heavy coding -> gpt-5.3-codex
• architecture -> gpt-5.4
• review -> gemini-3-pro-preview
• docs -> gpt-5.4-mini
• ui / vision -> claude-opus-4.6

have to edit generated docs, prompts, or internal routing rules instead of using a stable config surface.

This makes upgrades fragile, because the upgrade process can overwrite or reintroduce upstream model mappings that do not match the user's preferred routing strategy.

Problem

The missing piece is a first-class config file for task-category model mapping.

Current pain points:

1. There is no durable config for mapping task categories to preferred models.
2. Users can set a single default model, but not an explicit routing table such as coding vs heavy coding vs review vs docs.
3. Upgrades can reapply upstream defaults that conflict with local user preferences.
4. Users end up patching generated files manually after upgrades.
5. The current behavior mixes three concerns that should be separated:
   • Squad-maintained default routing
   • user-specific overrides
   • runtime session model alignment

Proposal

Add a dedicated model-mapping config file that supports:

1. a default section managed by Squad CLI
2. an override section managed by the user
3. upgrade behavior that refreshes default but preserves override
4. runtime resolution that merges override over default

Example config shape

{
  "version": 1,
  "modelMappings": {
    "default": {
      "coding-model": "gpt-5.4",
      "heavy-coding-model": "gpt-5.3-codex",
      "architecture-model": "gpt-5.4",
      "review-model": "gemini-3-pro-preview",
      "docs-model": "gpt-5.4-mini",
      "fast-model": "gpt-5.4-mini",
      "ui-model": "claude-opus-4.6"
    },
    "override": {}
  }
}

Expected resolution rules

At runtime, Squad should resolve mappings in this order:

1. explicit per-agent override if present
2. modelMappings.override.<key>
3. modelMappings.default.<key>
4. platform/session fallback behavior

This would allow the CLI to ship sane defaults while still giving the user a stable, upgrade-safe place to customize routing.

Why agentModelOverrides is not enough

This proposal is intentionally different from the existing agentModelOverrides setting.

agentModelOverrides is useful for pinning a specific named agent to a specific model, but it does not solve task-category routing.

For example, it can express:

• fenster -> gpt-5.4
• mcmanus -> gpt-5.4-mini

But it cannot express:

• all coding tasks -> gpt-5.4
• all heavy coding tasks -> gpt-5.3-codex
• all review tasks -> gemini-3-pro-preview
• all docs tasks -> gpt-5.4-mini

That distinction matters because agents can do different kinds of work over time, and the desired model choice is often based on task type rather than agent identity.

So the request here is not to replace agentModelOverrides, but to complement it:

• agentModelOverrides for per-agent pinning
• modelMappings.default for Squad-managed task routing defaults
• modelMappings.override for user-managed task routing overrides

Upgrade behavior

The squad upgrade command should:

1. create the config file if it does not exist
2. update only the default section when upstream defaults change
3. preserve the override section exactly as authored by the user
4. optionally report when an override references a model not present in the current catalog
5. avoid rewriting generated docs or prompt templates in a way that silently conflicts with user overrides

Suggested mapping keys

The exact names are negotiable, but the system should support keys like:

• coding-model
• heavy-coding-model
• architecture-model
• review-model
• docs-model
• fast-model
• ui-model
• scribe-model

If preferred, these could also be normalized to a nested structure such as:

{
  "modelMappings": {
    "default": {
      "coding": "gpt-5.4",
      "heavyCoding": "gpt-5.3-codex",
      "architecture": "gpt-5.4",
      "review": "gemini-3-pro-preview",
      "docs": "gpt-5.4-mini",
      "ui": "claude-opus-4.6"
    },
    "override": {}
  }
}

Acceptance criteria

1. Squad supports a dedicated config surface for task-category model mappings.
2. Squad CLI installs a default mapping table.
3. The user has a separate override section that starts empty.
4. squad upgrade updates defaults without clobbering user overrides.
5. Runtime model selection respects overrides before defaults.
6. Documentation clearly explains which keys map to which task classes.
7. The config is compatible with existing defaultModel and agentModelOverrides behavior, or a migration path is documented.

Related existing work

These look related and suggest the feature area already exists but is not yet exposed as a stable mapping config:

• #618 explicit model picker - aligned to sesson model
• #588 Update default AI model list to match current Copilot offerings
• #585 Economy Mode: Honest E2E Validation, Reliable Activation, and Cost Measurement
• #500 feat: Economy mode for cost-conscious model selection
• #491 fix: persist user model preference across sessions

Why this matters

This is primarily a request for a stable contract between:

• upstream Squad defaults
• local user preferences
• the upgrade process

Without that contract, users end up maintaining downstream patches to generated model-selection content after every upgrade.