Updating Model Guidance

A model refresh crosses several independently owned surfaces. First establish the provider's exact model ID and effort controls; then update the runtime's supported targets, the optional preferred dispatch ladder, and the human selection guidance. A model appearing in a provider's catalog does not by itself establish that a subagent pin resolves to it. Keep an explicit user's dispatch cells intact unless they choose to adopt a newer recommendation.

Source Ownership

A model can remain supported for a user's explicit configuration without being recommended by the new ladder. For example, this refresh keeps GPT-5.6 Codex and Cursor targets available while preferring GPT-6.1 Sol and GPT-6 Luna in Codex. GPT-6 Sol remains supported for explicit compatibility configurations. Claude Opus 4.8 and 5.0 have left current supported generations and recommendations; historical probe records can still describe past behavior, clearly labeled as historical.

Establish Provider Evidence

Check the provider's official model documentation and the local runtime before editing an ID or effort range. The OpenAI model catalog lists GPT-6.1 Sol and GPT-6 Astra, Sol, and Luna. The GPT-6.1 Sol model page identifies gpt-6.1-sol and supports low, medium, high, xhigh, and max; none and minimal are not supported efforts for this family. Direct API tool calls require the Responses API. The Astra model page names gpt-6-astra and documents low, medium, high, xhigh, and max; compare it with the installed Codex runtime model cache for the exact names and local effort set. Catalog presence establishes support, not relative task quality. The Anthropic Opus 5.5 documentation names claude-opus-5-5; confirm a Claude Code invocation reports that exact assistant model before admitting it to the Claude catalog. The Sonnet 5.5 overview and effort reference identify claude-sonnet-5-5 and its five low-through-max efforts. Verify Claude Code identity separately. Claude subagent model and effort frontmatter select a per-agent route; see the Claude Code subagent fields. An API model announcement alone does not prove a third-party harness supports or resolves that model.

Cursor requires an additional mapping-specific native desktop probe. Follow Verifying Cursor Pins: launch a temporary subagent in Cursor Agent Chat and compare the subagentStart.subagent_model hook value with the proposed flat ID, using positive and unknown-family/effort controls. Record the submitted selector, resolved model, time, and evidence path in the mapping. agent models proves catalog visibility only; CLI agent -p and remote runs do not emit the required native subagent hook.

During this refresh, agent models listed claude-opus-5-5-* flat IDs. The CLI agent -p bracket selector returned Cannot use this model, but a later Cursor desktop 3.20.14 native hook probe (provenance at packages/cli/src/providers/cursor/codec/__fixtures__/README.md, observations in adjacent JSONL records) resolved each of the five Opus 5.5 effort selectors to its matching flat ID. The positive Sonnet control resolved, while invalid family and effort controls fell back to defaults. Five Opus 5.5 mappings are now approved for desktop subagents; the CLI result alone does not establish that the same bracket syntax works as a CLI top-level --model argument. Likewise, do not add GPT-6 or GPT-6.1 Cursor targets until that runtime lists and verifies them.

A 2026-09-25 desktop 3.21.18 probe added Grok 4.6 and Fable 5.1 mappings and moved the bundled Cursor ladder to them. The same probe showed Grok 4.7 resolves only bare flat IDs, never bracket selectors. It still needs its own approved registry entry and complete per-pin evidence before admission; see Verifying Cursor Pins. See Dispatch Policy for the distinction between catalog, configured mapping, and runtime identity.

The October 1 refresh migrates Codex Sol defaults and examples to gpt-6.1-sol while preserving existing effort choices, including medium for intelligent recon. Claude Economy moves to claude-sonnet-5-5 medium by user direction. GPT-6 Sol and Sonnet 5 remain explicitly supported. Cursor lists Sonnet 5.5 flat IDs at low through max. Cursor 3.22.12 native probes matched those exact IDs at start, Shell execution, and stop while every Sonnet 5.5 bracket pin fell back to the account default. The existing Opus low control matched; unknown-family and Sonnet ultra exact-ID controls fell back. The fixture summary and event records at packages/cli/src/providers/cursor/codec/__fixtures__/cursor-pin-probe-2026-10-01{,-events}.jsonl retain both rounds. Ship explicit, evidence-backed exact-ID mappings for that family; keep existing bracket mappings. An exact-ID mapping requires the same per-pin native evidence and controls as a bracket mapping. Do not enable generic pass-through of CLI IDs. Cursor does not list GPT-6 Sol or GPT-6.1 Sol in the observed catalog. Do not carry Codex model IDs into Cursor configurations. These selector changes do not import a separate vault policy refresh or claim newly measured task-performance gains.

Change and Validate

1. Update the supported catalog for each verified runtime and its tests. Preserve old model targets that are intentionally still supported; remove retired generations from active support and recommendations, while retaining historically sourced fixtures when they are explicitly testing history.
2. Update the bundled recommendation's ordered candidate cells and version. Check the last candidate in each tier: it determines that tier's pinned self-review target. Keep the ladder within its provider's supported catalog. A recommendation may reflect an explicit operator preference before a workload comparison exists; label that boundary instead of presenting the preference as measured superiority or accepted portfolio policy.
3. Update the provider selection references and bump the canonical skill version once for the PR. Search the repository for the old and new IDs, including schemas, fixtures, examples, and generated projections. Replace current guidance; do not rewrite clearly marked historical evidence.
4. Build the CLI to regenerate its bundled asset, run project sync, and inspect the generated role definitions and configuration diff. Use oat sync --scope project --dry-run afterward to verify source/output parity.
5. Run the focused catalog, recommendation, sync, and asset tests, followed by the repository gates in AGENTS.md: pnpm check, pnpm type-check, pnpm test, pnpm build, pnpm run check:skill-bumps, pnpm release:check-versions, pnpm release:validate, and pnpm build:docs. Fetch origin/main before the version check. For .agents/skills changes also run pnpm lint and pnpm format. Inspect cache replay in Turborepo output; force fresh tests when the evidence matters. Record exact failures and distinguish an unavailable native provider probe from a successful one.

Changes to shipped skills, generated agents, CLI assets, or docs require the public packages' lockstep version bump under the repository release policy. Follow Contributing Code for the current validation and PR workflow.

Adoption Is Separate

A bundled ladder update does not mutate adopted user or repository config. oat config adopt dispatch-matrix --shared, --local, or --user replaces bundled cells in the chosen scope, with a warning and a --dry-run preview; extra custom cells remain. Add --keep-existing to fill only missing cells. The active project's named ceiling is a separate policy in its state.md; a model update must not silently change it. See Dispatch Policy for config precedence and examples.