Problem

When users want to override contextWindow for a model (e.g. setting openai-codex/gpt-5.4 to 1M tokens), the only path is:

1. Add a full provider entry in models.providers.openai-codex
2. Include baseUrl, api, name (all required by schema validation) even though the built-in provider already defines them
3. Define the model with the desired contextWindow

This is unintuitive because:

• agents.defaults.models."openai-codex/gpt-5.4" is the natural place users look to configure per-model settings
• That path already supports params (pass-through API params like reasoning_effort), alias, and streaming
• But it does not accept contextWindow, maxTokens, reasoning, or input — forcing users into the provider-level config

Current schema

// agents.defaults.models — only 3 fields
z.object({
  alias: z.string().optional(),
  params: z.record(z.string(), z.unknown()).optional(),
  streaming: z.boolean().optional(),
}).strict()

// models.providers[].models[] — has contextWindow but requires full provider setup
z.object({
  id: z.string().min(1),
  name: z.string().min(1),       // required
  contextWindow: z.number().positive().optional(),
  maxTokens: z.number().positive().optional(),
  // ...
}).strict()

Proposal

Add contextWindow and maxTokens to agents.defaults.models schema:

z.object({
  alias: z.string().optional(),
  params: z.record(z.string(), z.unknown()).optional(),
  streaming: z.boolean().optional(),
  contextWindow: z.number().positive().optional(),  // new
  maxTokens: z.number().positive().optional(),       // new
}).strict()

These values should override the provider-level or default values during model resolution (in src/config/defaults.ts).

Secondary issue

When a user adds an explicit provider entry that matches a built-in provider (e.g. openai-codex), schema validation still requires baseUrl and models[].name even though the built-in already provides them. The merge logic in mergeProviderModels() already handles this correctly at runtime, but validation rejects the config before merging happens.

Relaxing required fields when the provider key matches a known built-in would make overrides much simpler:

{
  "models": {
    "providers": {
      "openai-codex": {
        "models": [{ "id": "gpt-5.4", "contextWindow": 1000000 }]
      }
    }
  }
}

Context

• DEFAULT_CONTEXT_TOKENS = 200_000 (src/agents/defaults.ts:6)
• gpt-5.4 actually supports 1M tokens but Codex CLI reports context_window: 272000 in its models.json
• Users wanting to push context limits have no simple config path today