Allow custom agents to select a model context window in .agent.md
- Dominant language
- TypeScript
- Stars
- 193k
- Forks
- 42.4k
- PR merge metrics
- PR metrics pending
Description
## Feature request: allow custom agents to declare the model context window
### Problem
Custom `.agent.md` files can select a model with the `model` front-matter property, but they cannot declare which supported context-window profile that agent should use. This makes the agent's context behavior depend on the current UI/session state and prevents teams from sharing a reproducible configuration.
For models that expose multiple context profiles, such as 200K and 1M, the desired choice should be part of the agent definition rather than an undocumented per-session setting.
### Proposed configuration
Add a supported front-matter property such as `context-window` or `context-window-tokens`:
```yaml
---
name: Pester Agent
model: GPT-5.6 Luna (copilot)
context-window: 200000
---
```
An enum form such as `200k` / `1m` would also work if the available profiles are model-defined. The value should select an available context profile, not claim a provider limit that the selected model does not support.
### UX requirements
- Add schema validation and IntelliSense for the property in `.agent.md` files.
- Add a control in the Agent Customizations editor to choose from context profiles supported by the selected model.
- Expose the effective context profile in the agent/session UI so the active behavior is visible.
- Provide an equivalent option in the Copilot CLI/TUI agent configuration flow.
- If a configured profile is unavailable for the selected model, show a clear warning and use a documented fallback rather than silently ignoring the value.
- Preserve backward compatibility: agents without this property continue using the current default/session behavior.
- Make handoffs and subagents inherit the configured profile unless the target agent explicitly overrides it.
### Rationale
This would make custom agents reproducible across developers and reduce accidental use of a larger or smaller context profile than intended. It would also make the existing context-window choice discoverable and manageable for users who primarily configure agents through YAML.
Related issues:
- #322201: Context window dial assumes 1M tokens when 200K tokens are selected
- #313546: Support reasoning effort configuration in custom `.agent.md` files
- #293125: Context window details incorrect
### Acceptance criteria
1. A documented front-matter property can select a supported context profile for a custom agent.
2. The property is validated in the editor and can be configured through the Agent Customizations UI.
3. The active context profile is visible in the agent/session UI and available through the CLI/TUI flow.
4. Unsupported or unavailable values produce an actionable diagnostic and deterministic fallback behavior.
5. Existing `.agent.md` files without the property behave exactly as they do today.
Contributor guide
Assessment
This issue has not been assessed yet.