@open-agent-toolkit/cli 0.3.0 → 0.3.2

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.7
+version: 1.2.9
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -72,7 +72,12 @@ The orchestrator owns dispatch control. Do not read `plan.md` Dispatch Profile r
 
 For Codex, deterministic review dispatch under a capped managed policy uses the materialized Codex role name returned by `providers.codex.dispatchArgs.variant`; the orchestrator also supplies `providers.codex.selection.target` context when available and should derive `model_axis` and `effort_axis` from resolver output. Managed `Uncapped` and inherit/default policies have no reviewer target, so the base `oat-reviewer` role is used only when the resolver returns no `dispatchArgs.variant`, as a provider-default/unpinned fallback. If you are running as the base role, report any provided `provider_default_effort` as context but do not treat it as managed uncapped selection or an OAT cap. Use base `oat-reviewer` only when the resolver returns no `dispatchArgs.variant`.
 
-For Claude Code, review dispatch is model-axis based and the effort axis is `not-applicable`.
+For Claude Code, an effort-pinned managed review launches the exact generated
+variant returned by `providers.claude.dispatchArgs.variant`; the variant's
+frontmatter applies both model and effort because the Agent call has no effort
+field. Any per-call model must match the definition. Derive both selected axes
+from resolver output and the launcher payload. Legacy model-only and inherited
+routes retain their existing provider-default or inherited effort behavior.
 
 ## Bounded Reviewer Reconnaissance
 
@@ -430,6 +435,8 @@ worker claims, and root-inline coverage}
 
 ## Findings
 
+{Every finding MUST be written as a markdown list item — a line starting with `- `, `* `, `+ `, or `1. `. The gate counts list items only; a finding written as a bold paragraph, a heading, or any other prose shape counts as zero and makes the gate refuse the whole artifact.}
+
 ### Critical
 
 {If none: "None"}
@@ -494,7 +501,7 @@ Run the `oat-project-review-receive` skill to convert findings into plan tasks.
 
 ```
 
-Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat gate review`, MUST include either the complete `Findings by severity: {N} critical, {N} high, {N} medium, {N} low` count line or the standard `## Findings` sections shown above with every severity subsection present. When more than one count source is present — the frontmatter count fields, the count line, and the sections — the counts must agree; the gate refuses an artifact whose sources contradict each other rather than picking one.
+Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat gate review`, MUST include either the complete `Findings by severity: {N} critical, {N} high, {N} medium, {N} low` count line or the standard `## Findings` sections shown above with every severity subsection present. When more than one count source is present — the frontmatter count fields, the count line, and the sections — the counts must agree; the gate refuses an artifact whose sources contradict each other rather than picking one. How a section is counted is load-bearing: the gate counts only markdown list items (`- `, `* `, `+ `, or `1. `) as findings. A finding written as a bold paragraph, a heading, or any other prose shape counts as zero, so a section of prose findings under a non-zero count line is a contradiction and the gate refuses the artifact — the entire review is rejected, not just the miscounted section.
 
 For every artifact-mode code review, `oat_review_head_sha` is required and must be the full 40-character commit SHA at the head of the authoritative review range. Resolve it with `git rev-parse <authoritative-range-head>^{commit}`. An abbreviated SHA, symbolic ref, or range string is invalid. When the review narrowed, `oat_review_range`, `oat_prior_review_artifact`, and `oat_prior_review_head_sha` are also required; the prior head must likewise be a full 40-character SHA. These code-review fields are independent of the gate-only block and do not apply to artifact, analysis, or structured-output reviews.
 

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.0"
+  "oatVersion": "0.3.2"
 }

package/assets/config/dispatch-matrix-recommendation.json

@@ -1,22 +1,22 @@
 {
-  "version": "2026-07-27.1",
+  "version": "2026-09-23.2",
   "providers": {
     "codex": {
       "economy": {
         "candidates": [
           {
             "harness": "codex",
-            "model": "gpt-5.6-luna",
+            "model": "gpt-6-luna",
             "effort": "low"
           },
           {
             "harness": "codex",
-            "model": "gpt-5.6-luna",
+            "model": "gpt-6-luna",
             "effort": "medium"
           },
           {
             "harness": "codex",
-            "model": "gpt-5.6-luna",
+            "model": "gpt-6-luna",
             "effort": "high"
           }
         ]
@@ -25,28 +25,13 @@
         "candidates": [
           {
             "harness": "codex",
-            "model": "gpt-5.6-luna",
+            "model": "gpt-6-luna",
             "effort": "xhigh"
           },
           {
             "harness": "codex",
-            "model": "gpt-5.6-terra",
-            "effort": "low"
-          },
-          {
-            "harness": "codex",
-            "model": "gpt-5.6-terra",
-            "effort": "medium"
-          },
-          {
-            "harness": "codex",
-            "model": "gpt-5.6-terra",
-            "effort": "high"
-          },
-          {
-            "harness": "codex",
-            "model": "gpt-5.6-terra",
-            "effort": "xhigh"
+            "model": "gpt-6-luna",
+            "effort": "max"
           }
         ]
       },
@@ -54,17 +39,17 @@
         "candidates": [
           {
             "harness": "codex",
-            "model": "gpt-5.6-sol",
+            "model": "gpt-6-sol",
             "effort": "low"
           },
           {
             "harness": "codex",
-            "model": "gpt-5.6-sol",
+            "model": "gpt-6-sol",
             "effort": "medium"
           },
           {
             "harness": "codex",
-            "model": "gpt-5.6-sol",
+            "model": "gpt-6-sol",
             "effort": "high"
           }
         ]
@@ -73,12 +58,12 @@
         "candidates": [
           {
             "harness": "codex",
-            "model": "gpt-5.6-sol",
+            "model": "gpt-6-sol",
             "effort": "xhigh"
           },
           {
             "harness": "codex",
-            "model": "gpt-5.6-sol",
+            "model": "gpt-6-sol",
             "effort": "max"
           }
         ]
@@ -86,16 +71,61 @@
     },
     "claude": {
       "economy": {
-        "candidates": ["haiku", "sonnet"]
+        "candidates": [
+          "haiku",
+          {
+            "harness": "claude",
+            "model": "claude-sonnet-5",
+            "effort": "medium"
+          }
+        ]
       },
       "balanced": {
-        "candidates": ["sonnet"]
+        "candidates": [
+          {
+            "harness": "claude",
+            "model": "claude-opus-5-5",
+            "effort": "low"
+          }
+        ]
       },
       "high": {
-        "candidates": ["opus"]
+        "candidates": [
+          {
+            "harness": "claude",
+            "model": "claude-opus-5-5",
+            "effort": "low"
+          },
+          {
+            "harness": "claude",
+            "model": "claude-opus-5-5",
+            "effort": "medium"
+          },
+          {
+            "harness": "claude",
+            "model": "claude-opus-5-5",
+            "effort": "high"
+          }
+        ]
       },
       "frontier": {
-        "candidates": ["fable"]
+        "candidates": [
+          {
+            "harness": "claude",
+            "model": "claude-opus-5-5",
+            "effort": "xhigh"
+          },
+          {
+            "harness": "claude",
+            "model": "claude-opus-5-5",
+            "effort": "max"
+          },
+          {
+            "harness": "claude",
+            "model": "claude-fable-5-1",
+            "effort": "high"
+          }
+        ]
       }
     },
     "cursor": {
@@ -107,24 +137,14 @@
         ]
       },
       "balanced": {
-        "candidates": [
-          "cursor-grok-4.5-high",
-          "gpt-5.6-terra-high",
-          "claude-opus-5-thinking-low"
-        ]
+        "candidates": ["cursor-grok-4.5-high", "gpt-5.6-terra-high"]
       },
       "high": {
-        "candidates": [
-          "claude-opus-5-thinking-medium",
-          "gpt-5.6-sol-medium",
-          "claude-opus-5-thinking-high",
-          "gpt-5.6-sol-high"
-        ]
+        "candidates": ["gpt-5.6-sol-medium", "gpt-5.6-sol-high"]
       },
       "frontier": {
         "candidates": [
           "gpt-5.6-sol-xhigh",
-          "claude-opus-5-thinking-xhigh",
           "gpt-5.6-sol-max",
           "claude-fable-5-thinking-high"
         ]

package/assets/docs/cli-utilities/configuration.md

@@ -475,12 +475,24 @@ even when the reusable ladder is user-owned.
 The example above is illustrative rather than a copy of the bundled ladder; its
 tiers are trimmed for readability.
 
-The bundled recommendation covers 13 Codex model/effort combinations: Luna and
-Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and
-`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. The recommendation
-carries 14 Cursor candidates across four tiers, drawn from a materialization
-catalogue with 18 catalogued multi-family flat IDs spanning Composer, Claude
-(Sonnet, Opus, and Fable), GPT, and Grok; the two figures differ because some
+The bundled recommendation covers 10 Codex model/effort combinations: GPT-6
+Luna at `low` through `max`, and GPT-6 Sol at the same efforts.
+Claude covers `haiku`, plus explicit Sonnet, Opus, and Fable
+model/effort pairs. Effort-pinned Claude cells require a recognized versioned
+model ID (`fable-5-1`, `fable-5`, `opus-5-5`, `sonnet-5`,
+`opus-4-7`, `opus-4-6`, or `sonnet-4-6`) or a matching
+`ANTHROPIC_DEFAULT_<FAMILY>_MODEL` pin. A custom provider pin must declare
+matching capability through `<PIN>_SUPPORTED_CAPABILITIES`: `effort` enables
+`low`, `medium`, and `high`, while `xhigh_effort` and `max_effort` add those
+rungs. A present declaration is authoritative. Host-managed routing through
+`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` takes precedence over family pins, and a
+bare effort-pinned alias fails closed when its generation cannot be proven.
+Model-only Claude aliases remain compatible through the per-call model argument
+and report `effortAxis: not-applicable` because the Agent API exposes no
+per-call effort argument. The recommendation carries 10 Cursor candidates
+across four tiers, drawn from a materialization
+catalogue with 17 catalogued multi-family flat IDs spanning Composer, Claude
+(Sonnet, Opus 5.5, and Fable), GPT, and Grok; the two figures differ because some
 approved mappings stay materializable without being recommended. An explicit
 mapping connects each flat ladder ID to a separate bracket-form frontmatter
 model; configuration and skills never derive or normalize either form.
@@ -598,7 +610,7 @@ not the exact managed phase-agent path.
 | Provider | Exact phase-agent or optional-child mechanism                                                        |
 | -------- | ---------------------------------------------------------------------------------------------------- |
 | Codex    | `providers.codex.dispatchArgs.variant` as `agent_type`, or a fresh child pinned to model plus effort |
-| Claude   | `providers.claude.dispatchArgs.model` as the actual Agent `model`                                    |
+| Claude   | `providers.claude.dispatchArgs.variant` for effort-pinned targets; exact `model` for legacy targets  |
 | Cursor   | `providers.cursor.dispatchArgs.variant` as the exact native agent type first                         |
 
 Project sync materializes the supported Codex and Cursor catalogues and every
@@ -617,7 +629,7 @@ ownership. Cleanup reconciles only the current owner. Cursor's mapping registry
 rejects unknown flat IDs instead of writing unverified frontmatter.
 
 Reviewer resolution uses the final candidate at the configured review ceiling.
-Codex and Cursor select exact native reviewer variants; Claude passes the
+Codex, Cursor, and effort-pinned Claude targets select exact native reviewer variants; legacy Claude passes the
 resolver's exact model argument. Timeout retries preserve the same complete
 payload. A lower reviewer candidate requires a separate reviewed contract.
 

package/assets/docs/cli-utilities/workflow-gates.md

@@ -605,7 +605,7 @@ that candidate's model and is not double-pinned.
             "model": "composer-2.5",
             "reasoningEffort": "provider-default"
           },
-          "models": ["composer-2.5", "gpt-5.5-xhigh", "claude-opus-4-8"],
+          "models": ["composer-2.5", "gpt-5.5-xhigh", "claude-opus-5-5"],
           "availabilityCommand": [
             "sh",
             "-c",

package/assets/docs/contributing/index.md

@@ -17,4 +17,5 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
 - [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
+- [Updating Model Guidance](updating-model-guidance.md) - Source map and verification checklist for provider model refreshes.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.

package/assets/docs/contributing/updating-model-guidance.md

@@ -0,0 +1,106 @@
+---
+title: Updating Model Guidance
+description: How to verify provider model IDs, update supported dispatch targets and preferred ladders, sync agent views, and validate a model refresh.
+---
+
+# 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
+
+| Concern                                | Canonical source                                                                                                                                                        | Effect                                                                                                                                                                                      |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Codex model and effort support         | `packages/cli/src/providers/codex/codec/shared.ts`, `packages/cli/src/commands/project/dispatch-ceiling/index.ts`, and `packages/cli/src/providers/ceiling/registry.ts` | The catalogue materializes role variants; candidate validation accepts supported efforts through `max`, while the scalar ceiling in `packages/cli/src/config/oat-config.ts` stops at `max`. |
+| Claude generation and effort support   | `packages/cli/src/providers/claude/targets.ts` and `packages/cli/src/providers/claude/dispatch-envelope.ts`                                                             | Resolver validates the versioned model and permitted efforts, including the schema for a dispatch envelope.                                                                                 |
+| Cursor flat ID to frontmatter selector | `packages/cli/src/providers/cursor/codec/catalog.ts`                                                                                                                    | Approved, evidence-backed mappings can be materialized; flat IDs are not derived from selector syntax.                                                                                      |
+| Bundled preferred ladder               | `packages/cli/config/dispatch-matrix-recommendation.json`                                                                                                               | Ordered candidates per provider and tier; it is a preference, not the entire support catalog.                                                                                               |
+| Dispatch advice                        | `.agents/skills/subagent-orchestration/SKILL.md` and `references/provider-{codex,claude,cursor}.md`                                                                     | Agents learn the task-class routes and evidence limits. Increment `metadata.version` when bundled skill content changes.                                                                    |
+| Published CLI asset                    | `packages/cli/assets/config/dispatch-matrix-recommendation.json`                                                                                                        | Generated copy of the canonical recommendation; regenerate via the CLI asset build.                                                                                                         |
+| Generated project agent views          | `.codex/agents`, `.codex/config.toml`, `.claude/agents`, `.cursor/agents`                                                                                               | Outputs of `oat sync`; never use them as catalog sources.                                                                                                                                   |
+
+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 in Codex. 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](https://developers.openai.com/api/docs/models)
+lists GPT-6 Sol and Luna; compare it with the installed Codex runtime model
+cache for the exact names and local effort set. The
+[Anthropic Opus 5.5 documentation](https://www.anthropic.com/claude-opus-5-5)
+names `claude-opus-5-5`; confirm a Claude Code invocation reports that exact
+assistant model before admitting it to the Claude catalog. Claude subagent
+`model` and `effort` frontmatter select a per-agent route; see the
+[Claude Code subagent fields](https://code.claude.com/docs/en/sub-agents).
+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](verifying-cursor-pins.md): 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
+Cursor targets until that runtime lists and verifies them. See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#cursor-evidence-authority)
+for the distinction between catalog, configured mapping, and runtime identity.
+
+## 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.
+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](code.md) for the current validation and PR workflow.
+
+## Adoption Is Separate
+
+The bundled ladder is a default for missing provider/tier cells. `oat config
+adopt dispatch-matrix --shared`, `--local`, or `--user` fills missing cells but
+does not replace populated explicit cells, even when its recommendation version
+changes. A user who wants the new model ordering must edit those cells or
+clear and re-adopt them deliberately. 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](../workflows/projects/dispatch-ceiling.md#ownership-and-adoption)
+for config precedence and examples.

package/assets/docs/contributing/verifying-cursor-pins.md

@@ -6,8 +6,8 @@ description: 'Runbook for probe-verifying a Cursor model pin before shipping it:
 # Verifying Cursor Pins
 
 A Cursor model pin maps an OAT ladder model ID to the frontmatter selector that
-materialized role files carry, for example `claude-opus-5-thinking-medium` to
-`claude-opus-5[effort=medium]`. Adding one to
+materialized role files carry, for example `gpt-5.6-sol-medium` to
+`gpt-5.6-sol[reasoning=medium]`. Adding one to
 `packages/cli/src/providers/cursor/codec/catalog.ts` requires evidence that
 Cursor actually resolves that selector to the intended model.
 
@@ -26,7 +26,7 @@ that look like evidence are not:
   ask.
 
 The catalog alone is also insufficient wherever a family carries both a
-thinking and a non-thinking flat ID at the same rung. Opus 5 carries both at
+thinking and a non-thinking flat ID at the same rung. Historically, Opus 5 carried both at
 low, medium, and high, so the bracket selector is genuinely ambiguous there and
 only a probe can resolve it. At rungs where only one variant exists, the
 catalog settles the question without a probe — but you still need the probe to
@@ -57,6 +57,15 @@ flag) is empty and `model_id` is absent. Thinking is therefore established by
 the resolved slug itself, which is sound because the non-thinking IDs are
 distinct.
 
+The 2026-09-23 Opus 5.5 desktop probe is an example: all five
+`claude-opus-5-5[effort=...]` selectors resolved to matching flat IDs in
+Cursor 3.20.14, while `effort=ultra` fell back to medium. The Sonnet 5 high control
+resolved to `claude-sonnet-5-thinking-high`, correcting an older flat ID. The provenance summary at
+`packages/cli/src/providers/cursor/codec/__fixtures__/README.md` identifies
+the adjacent redacted summary and 32-event native JSONL records in the OAT
+repository. Re-run this procedure for a new family or changed
+provider behavior.
+
 ## Prerequisites
 
 - Cursor desktop app, with the repository open as a workspace.
@@ -133,10 +142,10 @@ the probe is the hook payload, not anything the agent produces.
 ````markdown
 ---
 # TEMPORARY pin probe - not oat-managed. Delete after probing.
-# Class: subject - expect claude-opus-5-thinking-medium
-name: zz-pin-probe-opus5-medium
-description: Temporary pin probe (subject) for claude-opus-5[effort=medium]. Delete after use.
-model: claude-opus-5[effort=medium]
+# Class: subject - expect gpt-5.6-sol-medium
+name: zz-pin-probe-sol56-medium
+description: Temporary pin probe (subject) for gpt-5.6-sol[reasoning=medium]. Delete after use.
+model: gpt-5.6-sol[reasoning=medium]
 ---
 
 ## Role
@@ -144,7 +153,7 @@ model: claude-opus-5[effort=medium]
 You are a throwaway pin probe. Run exactly one command and then stop:
 
 ```bash
-echo PIN-PROBE zz-pin-probe-opus5-medium
+echo PIN-PROBE zz-pin-probe-sol56-medium
 ```
 
 Then reply with the single word `done`. Do not read files or use any
@@ -162,12 +171,12 @@ corroborating `preToolUse` event.
 Probe every rung you intend to pin. Then add controls, which are what make the
 subject results interpretable:
 
-| Class            | Example selector               | Proves                                                           |
-| ---------------- | ------------------------------ | ---------------------------------------------------------------- |
-| Subject          | `claude-opus-5[effort=medium]` | The mapping resolves as intended                                 |
-| Positive control | `claude-sonnet-5[effort=high]` | Reproduces an already-verified mapping                           |
-| Negative control | `claude-opus-9[effort=high]`   | Unknown family — the channel reports resolution, not the request |
-| Negative control | `claude-opus-5[effort=ultra]`  | Unknown effort — exposes rung-level fallback                     |
+| Class            | Example selector                 | Proves                                                           |
+| ---------------- | -------------------------------- | ---------------------------------------------------------------- |
+| Subject          | `gpt-5.6-sol[reasoning=medium]`  | The mapping resolves as intended                                 |
+| Positive control | `claude-sonnet-5[effort=high]`   | Reproduces an already-verified mapping                           |
+| Negative control | `claude-opus-9[effort=high]`     | Unknown family — the channel reports resolution, not the request |
+| Negative control | `gpt-5.6-sol[reasoning=unknown]` | Unknown effort — exposes rung-level fallback                     |
 
 The negative controls carry most of the interpretive weight. Without them you
 cannot distinguish a hook that reports what Cursor actually resolved from one
@@ -194,6 +203,9 @@ PY
 
 ## Interpreting results
 
+The following Opus 5 observations document earlier probes; Opus 5 is retired
+from current mappings. Use the current live catalogue for new selectors.
+
 ### Unresolvable components fall back silently
 
 Cursor does not reject a malformed pin. It substitutes a default for whichever
@@ -240,10 +252,10 @@ approved it:
 
 ```ts
 approvedMapping(
-  'claude-opus-5-thinking-medium',
-  'claude-opus-5[effort=medium]',
-  'claude-effort',
-  { probeName: 'zz-pin-probe-opus5-medium', verifiedAt: '2026-07-25', evidencePath: '...' },
+  'gpt-5.6-sol-medium',
+  'gpt-5.6-sol[reasoning=medium]',
+  'gpt-reasoning',
+  { probeName: 'zz-pin-probe-sol56-medium', verifiedAt: '2026-07-25', evidencePath: '...' },
 ),
 ```
 

package/assets/docs/provider-sync/providers.md

@@ -12,7 +12,9 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Project: `.agents/skills` -> `.claude/skills`, `.agents/agents` -> `.claude/agents`, `.agents/rules` -> `.claude/rules`
     - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
     - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
-    - Managed phase implementers and optional nested workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Agent `model`
+    - Managed effort-pinned phase implementers and reviewers use the exact generated candidate returned as `providers.claude.dispatchArgs.variant`; its frontmatter carries model and effort because Agent has no per-call effort field. Legacy model-only candidates retain `providers.claude.dispatchArgs.model`, and any model supplied alongside a variant must match its definition.
+    - Generated names preserve the full normalized configured model ID after the provider token. A versioned ID such as `claude-opus-5-5` therefore produces the deterministic slug `oat-reviewer-claude-claude-opus-5-5-high`. This doubled `claude-` is the current managed-role contract, not a request to rename existing roles.
+    - Project variants live under `.claude/agents/`; user variants live under `~/.claude/agents/`. Sync removes stale managed variants for the reconciled owner while preserving base roles and unmanaged agents.
     - Claude's official subagent contract says existing agent directories are watched and changes load within seconds. It describes a conditional restart for the first agent added to a directory that was absent when the session started, for agents added through `--add-dir`, and when Claude starts with `--disable-slash-commands`. OAT cannot observe those session-start and launch-mode facts. After a successful provider-visible file change, the generic OAT repository policy therefore conservatively advises starting a new provider session; it does not claim that Claude hot-reloaded the file or that the application process must restart. The provider semantics were verified against [Claude Code subagent documentation](https://code.claude.com/docs/en/sub-agents) on 2026-08-31.
 
 === "Cursor"
@@ -100,7 +102,8 @@ provenance and cannot replace those values.
 Only an explicit pre-start native role-selection rejection permits another
 target-preserving route. An accepted child, including one that later returns
 `BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
-Claude binds the exact model argument described above. Cursor launches the
+Claude binds the exact generated variant for effort-pinned targets or the exact
+model argument for legacy targets. Cursor launches the
 exact native variant. A missing or unselectable managed target blocks rather
 than falling back to the root target or a base role.
 

package/assets/docs/reference/cli-reference.md

@@ -153,7 +153,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal (optional; no lifecycle skill requires it). Omit `--project` to validate without persisting. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
+- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal (optional; no lifecycle skill requires persistence). Omit `--project` to validate without persisting. Managed, effort-pinned Claude launches use the validation-only form before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.

package/assets/docs/reference/oat-directory-structure.md

@@ -133,7 +133,7 @@ Current schema keys:
 | `workflow.dispatchPolicy.policy`                           | `string`                   | unset                    | Managed dispatch policy: `economy`, `balanced`, `high`, `frontier`, or `uncapped`. Capped policies compile to provider targets; `uncapped` keeps OAT-managed preferred selection without provider caps. `inherit` mode is separate and leaves controls to the host/provider.                                                                                                                                                                                                                        |
 | `workflow.dispatchCeiling.preset`                          | `string`                   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                                                                                                                                                                                                                |
 | `workflow.dispatchCeiling.providers.<provider>`            | `object` or legacy scalar  | unset                    | Reusable provider candidate ladder. The canonical shape maps `economy`, `balanced`, `high`, and `frontier` to ordered candidate cells; project and phase state record only a named maximum over that ladder.                                                                                                                                                                                                                                                                                        |
-| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex entries carry exact `model` plus `effort` and resolve to materialized roles; Claude entries carry a model; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                                                                                                                                                                                                               |
+| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex and effort-pinned Claude entries carry exact `model` plus `effort` and resolve to materialized roles; legacy Claude model-only entries remain supported; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                                                                                                                                                                 |
 | `workflow.dispatchCeiling.providers.{codex,claude,cursor}` | `string`, route, or target | unset                    | Legacy compatibility input normalized to a one-candidate ladder. New configuration should use tiered candidate cells. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed without migration.                                                                                                                                                                                                                                                          |
 | `workflow.gates.skills`                                    | `object`                   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                                                                                                                                                                                                                 |
 | `workflow.gates.execTargets`                               | `object`                   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                                                                                                                                                                                                                         |

package/assets/docs/workflows/projects/artifacts.md

@@ -223,7 +223,7 @@ Each inner array is a group of phases that execute concurrently in their own wor
 - Each group must contain **2 or more** phases — singleton groups are rejected.
 - Every phase ID must exist in the plan body.
 - No phase may appear in more than one group.
-- Parallelism is only honored at Tier 1 (native subagents). Tier 2 degrades parallel groups to sequential target-preserving execution, not unconditional inline review. Concrete managed Claude reviewers retain the exact resolver-returned `dispatchArgs.model`; Cursor reviewers retain the exact `providers.cursor.dispatchArgs.variant` native agent type; Codex retains its exact role or pinned child. Every retry preserves the complete target. Inline review requires verified equivalent host controls or an explicit inherit/default or managed-uncapped base-role exception, and otherwise blocks.
+- Parallelism is only honored at Tier 1 (native subagents). Tier 2 degrades parallel groups to sequential target-preserving execution, not unconditional inline review. Concrete managed Claude reviewers use the exact generated `providers.claude.dispatchArgs.variant` for effort-pinned targets and retain `providers.claude.dispatchArgs.model` only for legacy model-only targets; Cursor reviewers retain the exact `providers.cursor.dispatchArgs.variant` native agent type; Codex retains its exact role or pinned child. Every retry preserves the complete target. Inline review requires verified equivalent host controls or an explicit inherit/default or managed-uncapped base-role exception, and otherwise blocks.
 
 **Authoring responsibility:**