Problem

Currently, model configuration in config.yaml is scattered and repetitive. Every location that needs a model must repeat the full set of provider fields (provider, model, api_key_env, base_url, temperature, etc.) rather than referencing a single definition.

For example, a user who wants to use the same model for chat, delegation, compression, and vision must repeat the configuration four times:

# Current (verbose and error-prone)
model:
  provider: openrouter
  model: anthropic/claude-sonnet-4
  api_key_env: OPENROUTER_API_KEY
  base_url: https://openrouter.ai/api/v1
  temperature: 0.5
  max_tokens: 8192

delegation:
  provider: openrouter        # repeated
  model: anthropic/claude-sonnet-4  # repeated
  api_key_env: OPENROUTER_API_KEY   # repeated
  base_url: https://openrouter.ai/api/v1  # repeated
  temperature: 0.5            # repeated
  max_tokens: 8192            # repeated

auxiliary:
  compression:
    provider: openrouter      # repeated
    model: anthropic/claude-sonnet-4  # repeated
    # ... same fields again
  vision:
    provider: openrouter      # repeated
    model: anthropic/claude-sonnet-4  # repeated
    # ... same fields again

This violates DRY and makes rotation/updating painful. If the base_url or api_key_env changes, the user must edit N locations.

Proposed Solution

Introduce a top-level models (or model_profiles) section where users define model objects once, and then reference them by name everywhere else:

# Proposed
models:
  claude-sonnet:
    provider: openrouter
    model_id: anthropic/claude-sonnet-4
    api_key_env: OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1
    temperature: 0.5
    max_tokens: 8192
  gpt-4o-mini:
    provider: openai
    model_id: gpt-4o-mini
    api_key_env: OPENAI_API_KEY

model: claude-sonnet          # scalar reference

delegation:
  model: gpt-4o-mini          # reference
  max_depth: 2
  max_spawn: 3

auxiliary:
  compression: claude-sonnet  # reference
  vision: claude-sonnet       # reference

fallback_model: gpt-4o-mini   # reference

Reference resolution rules:

1. If the value is a string, look it up in models by name.
2. If the value is a dict, treat it as an inline definition (backward-compatible).
3. models entries themselves are not active until referenced.

Scope / Affected Config Paths

Backward Compatibility

• Fully backward-compatible: existing inline dicts continue to work.
• Opt-in: only users who define models: and use string references benefit.
• Migration path: a future CLI command could inline existing configs into models and replace usages with references.

Relation to Existing Issues/PRs

• #9459 (agent_profiles) \u2014 focuses on agent personas (toolsets, prompts), not model deduplication. Complementary.
• #11657 (JSON config system) \u2014 introduces a new config format, but still repeats provider/model blocks per feature. This proposal could be applied to either YAML or JSON.
• #5012 / #7586 (per-call provider/model override) \u2014 runtime flexibility; this proposal is static config DRY.

Non-Goals

• This is not about runtime model switching (use /model or delegate_task overrides for that).
• This is not about adding new providers or changing the inference layer.
• This is not about replacing the existing custom_providers section (which defines provider endpoints, not model configurations).