If you use providers like openrouter, bedrock the single max_token setting isn't enough. It needs to be dynamic based on the model.

Summary

Adds a model.models.<id>.max_tokens overlay so a single profile can switch between models with different output-token ceilings without mutating the flat model.max_tokens fallback.

model:
  default: anthropic/claude-opus-4.6
  max_tokens: 8192              # fallback for unmatched models
  models:
    anthropic/claude-opus-4.6:
      max_tokens: 32768
    gpt-5.5:
      max_tokens: 65536

Resolution order is:

1. Explicit constructor/programmatic max_tokens
2. model.models.<active_model>.max_tokens
3. Flat model.max_tokens
4. Provider/model default

Why this is not a duplicate

Related PRs solve adjacent scopes, but not this specific config shape:

• feat(config): per-model context_length and provider_routing overrides #24495 establishes the same model.models.<id> overlay pattern for context_length and provider_routing, and explicitly notes max_tokens as a natural future extension. This PR is that focused extension for output-token caps.
• fix(agent_init): read max_tokens from custom_providers per-model config #28142 / feat: per-provider max_tokens via custom_providers models.<model>.max_tokens #28786 target custom_providers[].models.<model>.max_tokens, which helps custom-provider entries but not built-in providers like Bedrock/Anthropic/OpenAI or normal model switching within one profile.
• fix(config): propagate max_tokens from config.yaml to AI transport (#20741) #20769 covers flat/global model.max_tokens propagation, but not per-active-model overrides.

Changes

• agent/agent_init.py: resolve model.models.<active>.max_tokens before flat model.max_tokens, preserving constructor precedence and positive-int validation.
• gateway/run.py: include model.models in gateway agent cache-busting keys so edits to overlays rebuild cached agents.
• cli-config.yaml.example: document the per-model output-token overlay.
• Tests cover override wins, unmatched fallback, invalid per-model fallback, constructor precedence, and gateway cache invalidation.