@open-agent-toolkit/cli 0.1.43 → 0.1.46

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.4
+version: 1.1.5
 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
 color: yellow
@@ -68,7 +68,7 @@ You will be given a "Review Scope" block including:
 
 The orchestrator owns dispatch control. Do not read `plan.md` Dispatch Profile rows to self-select a tier.
 
-For Codex, deterministic review dispatch under a capped managed policy uses pinned reviewer variants (`oat-reviewer-low`, `oat-reviewer-medium`, `oat-reviewer-high`, or `oat-reviewer-xhigh`) selected by the resolved OAT dispatch policy cap. Managed `Uncapped` and inherit/default policies have no reviewer target, so the base `oat-reviewer` role is used 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.
+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`.
 

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

@@ -0,0 +1,23 @@
+{
+  "version": "2026-07-07.1",
+  "providers": {
+    "codex": {
+      "economy": "low",
+      "balanced": "medium",
+      "high": "high",
+      "frontier": "xhigh"
+    },
+    "claude": {
+      "economy": "haiku",
+      "balanced": "sonnet",
+      "high": "opus",
+      "frontier": "fable"
+    },
+    "cursor": {
+      "economy": "composer-2.5",
+      "balanced": "composer-2.5-fast",
+      "high": "gpt-5.5-high",
+      "frontier": "fable-5"
+    }
+  }
+}

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -113,6 +113,13 @@ Use `oat config` for repo runtime config inspection and supported key mutation.
 
 Use `oat config dump --json` when you need the whole resolved config in one machine-readable response rather than a single key or a human-oriented list view.
 
+Dispatch policy keys are part of this surface, but provider-specific generation
+still belongs to provider commands. Use `oat config describe
+workflow.dispatchPolicy.policy` to inspect capped managed, managed uncapped,
+inherit/default, and unresolved behavior; use `oat providers codex materialize`
+or `oat sync --scope project` to create materialized Codex roles from explicit
+model+effort targets.
+
 Archive lifecycle settings live here as shared repo config:
 
 - `archive.s3Uri`

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

@@ -173,8 +173,8 @@ oat config describe activeIdea
 Dispatch policy is the workflow setting that tells OAT whether to manage
 subagent model/effort selection and, if so, which managed policy to use.
 
-For the full conceptual model - managed capped tiers, managed `Uncapped`,
-`Inherit Host Defaults`, and provider-specific enforcement - see
+For the full conceptual model - managed capped tiers, dispatch matrix cells,
+managed `Uncapped`, `Inherit Host Defaults`, and provider-specific enforcement - see
 [Dispatch Policy](../workflows/projects/dispatch-ceiling.md).
 
 ### Config keys
@@ -196,35 +196,109 @@ Managed policies compile to:
 | `frontier` | `xhigh`  | `fable`  |
 | `uncapped` | none     | none     |
 
-Legacy compatibility keys remain supported for capped managed behavior:
+Dispatch matrix and legacy compatibility keys:
 
-| Key                                         | Values                                  | Purpose                                                                      |
-| ------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
-| `workflow.dispatchCeiling.preset`           | `balanced`, `maximum`, `cost-conscious` | Legacy preset alias; `maximum` maps to `high`, `cost-conscious` to `economy` |
-| `workflow.dispatchCeiling.providers.codex`  | `low`, `medium`, `high`, `xhigh`        | Legacy concrete Codex capped target                                          |
-| `workflow.dispatchCeiling.providers.claude` | `haiku`, `sonnet`, `opus`, `fable`      | Legacy concrete Claude capped target                                         |
+| Key                                                    | Values                                  | Purpose                                                                                |
+| ------------------------------------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------- |
+| `workflow.dispatchCeiling.preset`                      | `balanced`, `maximum`, `cost-conscious` | Legacy preset alias; `maximum` maps to `high`, `cost-conscious` to `economy`           |
+| `workflow.dispatchCeiling.providers.<provider>`        | bare value or tier map                  | Provider column; bare Codex/Claude values remain legacy capped targets                 |
+| `workflow.dispatchCeiling.providers.<provider>.<tier>` | bare value or ordered route             | One matrix cell for `economy`, `balanced`, `high`, or `frontier`                       |
+| `workflow.dispatchCeiling.recommendationVersion`       | string                                  | Version stamp written by `oat config adopt dispatch-matrix`; used for drift visibility |
 
-`Uncapped` is explicit managed state. Do not represent it by leaving policy
-state absent. To request no OAT model/effort selection, set:
+Examples:
+
+```bash
+oat config adopt dispatch-matrix --shared
+oat config set workflow.dispatchCeiling.providers.cursor.balanced composer-2.5 --shared
+oat config set workflow.dispatchCeiling.providers.codex high --shared
+oat config set workflow.dispatchCeiling.providers.claude opus --shared
+```
+
+For ordered routes, edit the config JSON so a tier cell is an array. Route
+entries are either bare slugs or objects with `harness`, `model`, and optional
+`effort`:
+
+```json
+{
+  "workflow": {
+    "dispatchCeiling": {
+      "providers": {
+        "cursor": {
+          "high": [
+            "composer-2.5",
+            { "harness": "cursor", "model": "gpt-5.5-xhigh" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+`Uncapped` is explicit managed state: OAT still selects the preferred
+provider-specific dispatch target, but does not apply a maximum cap. Do not
+represent it by leaving policy state absent. To request no OAT model/effort
+selection, set:
 
 ```bash
 oat config set workflow.dispatchPolicy.mode inherit
 ```
 
+If no managed policy, legacy cap, or inherit/default mode resolves during an
+implementation preflight, the policy remains unresolved. Interactive
+implementation may ask once and persist a choice; non-interactive
+implementation blocks rather than silently falling back to host defaults.
+
 ### How enforcement works
 
 OAT applies managed policies where the provider exposes a reliable mechanism.
-Other providers receive them as advisory/unsupported.
+Providers without an adapter receive them as advisory/unsupported.
+
+| Provider | Mechanism                            | Enforcement mode                |
+| -------- | ------------------------------------ | ------------------------------- |
+| Codex    | Materialized model+effort role names | `enforced`                      |
+| Claude   | Task `model` parameter               | `enforced`                      |
+| Cursor   | `--model` argument / Task `model`    | `enforced` when a cell resolves |
+| Others   | None (informational only)            | `advisory` / `unsupported`      |
+
+Codex managed dispatch compiles an explicit `model` plus reasoning `effort`
+target into a materialized OAT role name, for example
+`oat-phase-implementer-gpt-5-6-terra-xhigh`. OAT-managed Codex roles are not
+the old hard-coded effort-only pins; they come from resolver targets, dispatch
+matrix cells, or an explicit materialization command. Base roles such as
+`oat-phase-implementer` and `oat-reviewer` are fallback paths that follow the
+provider default effort when inherit/default behavior is selected or no
+materialized target resolves.
 
-| Provider | Mechanism                 | Enforcement mode           |
-| -------- | ------------------------- | -------------------------- |
-| Codex    | Pinned role variants      | `enforced`                 |
-| Claude   | Task `model` parameter    | `enforced`                 |
-| Others   | None (informational only) | `advisory` / `unsupported` |
-
-Codex uses effort (`low < medium < high < xhigh`) and pinned OAT role variants.
 Claude uses Task `model` (`haiku < sonnet < opus < fable`) and keeps
-`effort_axis=not-applicable`.
+`effort_axis=not-applicable`. Cursor and other model-arg providers use opaque
+matrix slugs; OAT validates availability when a provider oracle is available,
+but the configured matrix owns tier meaning. For Cursor subagents, validation
+checks the model can actually be used by Task subagent dispatch, not just that
+the broad `cursor-agent models` catalog lists the slug.
+
+### Codex role materialization
+
+Use `oat providers codex materialize` when you need to materialize one
+canonical agent as a Codex role outside a full sync run:
+
+```bash
+oat providers codex materialize oat-reviewer --model gpt-5.6-terra --effort xhigh --dry-run
+oat providers codex materialize oat-phase-implementer --model gpt-5.6-terra --effort high
+```
+
+Required inputs are the canonical agent name, `--model <model-id>`, and
+`--effort <reasoning-effort>`. The command defaults to project scope, reads
+`.agents/agents/<agent-name>.md`, writes `.codex/agents/<role>.toml`, and
+upserts `.codex/config.toml` unless `--dry-run` is present. `--agent-path` can
+point at a specific canonical agent markdown file, and `--role-name` can
+override the generated role name.
+
+Normal project sync also materializes Codex roles for configured matrix targets:
+
+```bash
+oat sync --scope project
+```
 
 **Verify-on-upgrade:** when the requested tier exceeds the current orchestrator
 tier (an upgrade request), the resolver sets `verifyOnDispatch: true`. The skill
@@ -249,12 +323,14 @@ oat project dispatch-ceiling resolve --provider codex --json
 oat project dispatch-ceiling resolve --provider codex --role implementer --preferred medium --json
 oat project dispatch-ceiling resolve --provider claude --role implementer --preferred sonnet --orchestrator-tier sonnet --json
 oat project dispatch-ceiling resolve --provider claude --orchestrator-tier sonnet --json
+oat project dispatch-ceiling resolve --provider cursor --role implementer --preferred high --escalation-level 0 --json
 ```
 
 The resolver checks effective config first, then project `state.md`
-`oat_dispatch_policy` frontmatter, then legacy `oat_dispatch_ceiling`.
-For Codex it also reports `providerDefaultEffort`, which is informational only
-for explicit inherit/default behavior or base/unpinned fallback paths.
+`oat_dispatch_policy` frontmatter, including sparse `matrix` overrides, then
+legacy `oat_dispatch_ceiling`. For Codex it also reports
+`providerDefaultEffort`, which is informational only for explicit
+inherit/default behavior or base/unpinned fallback paths.
 
 For non-interactive preflight checks, use:
 
@@ -284,10 +360,11 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.autoArtifactReview.plan` — boolean, default `true`. Automatically run the bounded artifact-review loop for generated `plan.md` files before implementation handoff. Set to `false` only when you intentionally want to skip the plan artifact review.
 - `workflow.autoArtifactReview.analysis` — boolean, default `true`. Automatically run the bounded accuracy-review loop for generated docs and agent-instructions analysis artifacts before the matching apply workflow consumes them.
 - `workflow.dispatchPolicy.mode` — `managed` or `inherit`. `managed` means OAT selects model/effort controls from `workflow.dispatchPolicy.policy`; `inherit` means OAT leaves controls to host/provider defaults.
-- `workflow.dispatchPolicy.policy` — `economy`, `balanced`, `high`, `frontier`, or `uncapped`. `economy` through `frontier` are capped managed policies; `uncapped` keeps OAT-managed preferred selection without provider caps.
+- `workflow.dispatchPolicy.policy` — `economy`, `balanced`, `high`, `frontier`, or `uncapped`. `economy` through `frontier` are capped managed policies; `uncapped` keeps OAT-managed preferred selection without provider caps. It is distinct from `workflow.dispatchPolicy.mode=inherit`, which leaves controls to the host/provider.
 - `workflow.dispatchCeiling.preset` — legacy compatibility alias (`balanced`, `maximum`, or `cost-conscious`) for capped managed policy setup.
-- `workflow.dispatchCeiling.providers.codex` — legacy concrete Codex cap (`low`, `medium`, `high`, or `xhigh`).
-- `workflow.dispatchCeiling.providers.claude` — legacy concrete Claude cap (`haiku`, `sonnet`, `opus`, or `fable`). Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
+- `workflow.dispatchCeiling.providers.<provider>` — dispatch matrix provider column or legacy bare provider target.
+- `workflow.dispatchCeiling.providers.<provider>.<tier>` — one matrix cell for `economy`, `balanced`, `high`, or `frontier`.
+- `workflow.dispatchCeiling.recommendationVersion` — version of the adopted recommended matrix.
 - `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
 
 ### Auto artifact-review preferences
@@ -324,6 +401,7 @@ oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.autoNarrowReReviewScope true --user
 oat config set workflow.designMode selective --user
 oat config set workflow.dispatchCeiling.preset balanced --user
+oat config adopt dispatch-matrix --user
 oat config set workflow.autoArtifactReview.plan true --user
 oat config set workflow.autoArtifactReview.analysis true --user
 
@@ -331,6 +409,7 @@ oat config set workflow.autoArtifactReview.analysis true --user
 oat config set workflow.createPrOnComplete false --shared
 oat config set workflow.designMode collaborative --shared
 oat config set workflow.dispatchCeiling.preset balanced --shared
+oat config set workflow.dispatchCeiling.providers.cursor.high composer-2.5 --shared
 oat config set workflow.autoArtifactReview.plan false --shared
 
 # Repo-local: personal override for this repo (default when no flag)

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

@@ -1,6 +1,6 @@
 ---
 title: Workflow Gates
-description: Configure per-skill final commands and cross-runtime review dispatch with oat gate.
+description: Configure per-skill final commands and family-aware review dispatch with oat gate.
 ---
 
 # Workflow Gates
@@ -16,6 +16,13 @@ selects an exec target, runs the prompt, and exits with the child process
 status. Use `oat gate review` when the command is specifically an OAT review
 gate that should inspect the produced review artifact.
 
+:::note Release note: default avoidance changed
+Gate dispatch now defaults to `--avoid same-family`, not `same-runtime`.
+For multi-family providers such as Cursor, this prevents a gate from reviewing
+with the same model family that produced the work. Use `--avoid none` only when
+you intentionally allow same-family review.
+:::
+
 ## Gate config
 
 Gate config lives under `workflow.gates.skills` and is keyed by skill name.
@@ -129,9 +136,9 @@ contract.
 ## Exec targets
 
 `oat gate cross-provider-exec` chooses from `workflow.gates.execTargets`.
-Targets are keyed by opaque id. OAT uses only the declared runtime, commands,
-and priority; it does not parse model names or infer provider semantics from the
-id.
+Targets are keyed by opaque id. OAT uses the declared runtime, commands,
+priority, optional `models` list, and any pinned `--model` already present in
+the command. It does not infer provider semantics from the target id.
 
 Built-in targets:
 
@@ -162,6 +169,34 @@ oat gate target set claude-opus \
 JSON argv is intentional: provider commands often contain flags such as `-p` or
 `--model`, which would be ambiguous as variadic CLI options.
 
+Targets may also define a `models` list directly in config. During selection,
+OAT expands that target into `(target, model)` candidates, preserves the target
+priority and model list order, and appends `--model <winner>` to the command.
+A long-form target that already pins `--model` in `baseCommand` is treated as
+that candidate's model and is not double-pinned.
+
+```json
+{
+  "workflow": {
+    "gates": {
+      "execTargets": {
+        "cursor-family-gate": {
+          "runtime": "cursor",
+          "baseCommand": ["cursor-agent", "-p", "--force"],
+          "models": ["composer-2.5", "gpt-5.5-xhigh", "claude-opus-4-8"],
+          "availabilityCommand": [
+            "sh",
+            "-c",
+            "command -v cursor-agent || command -v agent"
+          ],
+          "priority": 95
+        }
+      }
+    }
+  }
+}
+```
+
 ### Trusted target examples
 
 Use these examples only in trusted environments where the provider process may
@@ -275,12 +310,15 @@ oat gate cross-provider-exec "Use oat-project-review-provide to review the curre
 By default the dispatcher:
 
 1. Resolves built-in and configured exec targets.
-2. Detects the current runtime with host detection commands.
-3. Applies `--avoid same-runtime`.
-4. Checks candidate availability in descending priority order, with target id as
+2. Expands target `models` into candidate `(target, model)` pairs.
+3. Detects the current runtime with host detection commands.
+4. Resolves producer identity from `--producer-identity` or dispatch stamps when
+   available.
+5. Applies `--avoid same-family`.
+6. Checks candidate availability in descending priority order, with target id as
    the tie-breaker.
-5. Runs the chosen `baseCommand` with the prompt appended.
-6. Exits with the child process status.
+7. Runs the chosen `baseCommand` with the selected model and prompt appended.
+8. Exits with the child process status.
 
 Use `--target <id>` to pin one target and skip detection/avoidance:
 
@@ -289,12 +327,32 @@ oat gate cross-provider-exec --target claude-opus "Review the current project"
 ```
 
 Use `--avoid none` only when you intentionally allow the current runtime to be
-selected:
+selected or same-family review to run:
 
 ```bash
 oat gate cross-provider-exec --avoid none "Run this gate on any available target"
 ```
 
+Use `--producer-identity <value>:<provenance>` to route manually from a known
+producer when no project dispatch stamp exists:
+
+```bash
+oat gate review \
+  --producer-identity gpt-5.5-xhigh:declared \
+  --review-type code \
+  --review-scope final \
+  "Use oat-project-review-provide code final to review the current project"
+```
+
+Gate JSON output includes `diversity` metadata with the requested avoid mode,
+producer identity/provenance/confidence, reviewer target/model/family, and the
+achieved level:
+
+- `different-family`
+- `degraded-to-different-slug`
+- `same-family - no diverse target available`
+- `unknown-producer`
+
 ## Failure behavior
 
 Gate failure behavior is owned by the gate-aware skill:
@@ -309,11 +367,16 @@ Gate failure behavior is owned by the gate-aware skill:
 available target. Once a target actually runs, its exit code is the gate result;
 OAT does not try another target after a failed review.
 
+Gate target execution has a child-process timeout (default 10 minutes, override
+with `OAT_GATE_EXEC_TIMEOUT_MS`). When a review target times out, JSON output
+reports `status: review_failed`, `outcome: review_did_not_complete`,
+`timedOut: true`, and the timeout value so automation can distinguish a hung
+provider prompt from a completed review with findings.
+
 ## Current limits
 
-V1 gates avoid the current runtime, not the current model or effort setting.
-Same-runtime but different-target dispatch, such as using Cursor again with a
-different model slug, is future work. Until that exists, reusable lifecycle
-gates should rely on default `same-runtime` avoidance for cross-runtime review;
-manual and local overrides can pin an explicit reviewer target with
-`--target <id>`.
+Family diversity is selected before dispatch. If the selected provider command
+starts and then fails, OAT does not try another target after dispatch. If no
+different-family target is available, OAT warns, records the degraded achieved
+level, and runs the best available target rather than pretending diversity was
+achieved.

package/assets/docs/contributing/code.md

@@ -12,15 +12,21 @@ Use this page when you are changing the OAT codebase itself rather than only edi
 Install and verify the workspace from the repo root:
 
 ```bash
-pnpm install
-pnpm build
-pnpm run cli -- help
+nvm use
+corepack pnpm install
+corepack pnpm build
+corepack pnpm run cli -- help
 ```
 
+The repo pins Node in `.nvmrc` and the package manager in `package.json`
+(`packageManager`). If your machine has multiple Node or pnpm installs, prefer
+Corepack from the active `.nvmrc` Node so workspace commands use the same pnpm
+version as the hooks and CI.
+
 For worktree-based implementation, initialize the worktree before starting the CLI workflow:
 
 ```bash
-pnpm run worktree:init
+corepack pnpm run worktree:init
 ```
 
 ## Monorepo Structure

package/assets/docs/contributing/hooks-and-safety.md

@@ -20,6 +20,29 @@ The hook is non-blocking: it never fails the commit, even when managed drift is
 
 OAT installs the hook into Git's currently active hook directory. When a consumer repo keeps hooks in a repo-managed folder such as `.githooks/`, Git must be configured to use that path before install, or OAT must configure it during the hook prompt flow.
 
+## OAT repo developer hooks
+
+The `open-agent-toolkit` repository also ships its own managed hook scripts under
+`tools/git-hooks/`. These are contributor hooks for this repo, separate from the
+consumer hook snippet that `oat init` installs into other repositories.
+
+The repo hooks source `tools/git-hooks/repo-toolchain.sh` before running pnpm
+commands. The helper changes to the repo root, loads `.nvmrc` through nvm when
+available, and then prefers Corepack pnpm. This keeps `commit-msg`,
+`pre-commit`, `pre-push`, and `post-checkout` on the same Node/pnpm toolchain
+even when a developer shell has multiple versions installed.
+
+The repo's `pre-commit` OAT status check uses the repo-local source CLI when the
+OAT source tree is present:
+
+```bash
+corepack pnpm run --silent cli:source -- status --scope project --hook
+```
+
+That avoids false sync drift from a stale globally installed `oat` while still
+leaving the consumer-repo hook contract unchanged: generated hooks in other
+repos continue to call `oat status --scope project --hook`.
+
 ## Safety contracts
 
 - `sync` mutates by default; use `--dry-run` to preview.

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

@@ -95,7 +95,11 @@ canonical `.agents/skills` inventory.
   - unset: provider falls back to directory detection.
 - `defaultStrategy` is used when no provider-specific `strategy` is set.
 - At runtime, config is normalized so `providers` is always present in memory.
-- Codex project sync also manages generated role variants derived from canonical agents. `oat-phase-implementer-low|medium|high|xhigh` and `oat-reviewer-low|medium|high|xhigh` are managed outputs used by dispatch-ceiling-aware implementation. They should not be adopted as stray roles.
+- Codex project sync also manages generated materialized roles derived from
+  canonical agents and explicit model+effort targets. Dispatch-aware roles such
+  as `oat-phase-implementer-gpt-5-6-terra-xhigh` and
+  `oat-reviewer-gpt-5-6-terra-xhigh` are managed outputs and should not be
+  adopted as stray roles.
 
 ## Recommended management flow
 

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -69,7 +69,12 @@ After adoption, `oat sync` regenerates the managed provider copies from the cano
 
 ### Generated provider roles
 
-Some Codex roles are **generated-derived** — produced by the Codex sync extension rather than mapped 1:1 from a canonical `.agents/agents/*.md` file. The effort-specific implementer variants (`oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`) are the current example.
+Some Codex roles are **generated-derived** - produced by the Codex sync
+extension rather than mapped 1:1 from a canonical `.agents/agents/*.md` file.
+Materialized dispatch roles are the current example: a matrix target or
+`oat providers codex materialize` command supplies a canonical agent, model, and
+reasoning effort, and OAT writes a role such as
+`oat-phase-implementer-gpt-5-6-terra-xhigh`.
 
 `oat status` and `oat init` treat any role listed in the Codex extension plan's `managedRoles` set as managed, so generated variants are **not** reported as `stray` and are **not** offered for adoption — even though they have no canonical `.agents` source. A genuinely orphaned Codex role (no canonical source and not in `managedRoles`) is still flagged.
 

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

@@ -18,6 +18,8 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Project: `.agents/skills` -> `.cursor/skills`, `.agents/agents` -> `.cursor/agents`, `.agents/rules` -> `.cursor/rules`
     - User: `~/.agents/skills` -> `~/.cursor/skills`, `~/.agents/agents` -> `~/.cursor/agents`
     - Subagent invocation in Cursor is prompt-driven (`/name` or natural mention), not `subagent_type`
+    - OAT-controlled Cursor dispatch uses the generic `.cursor/agents/<name>.md` file plus the Task-level `model` argument selected from the dispatch matrix. A `model` frontmatter value is only a default/fallback mechanism.
+    - Cursor model validation checks whether the selected model is eligible for subagent Task dispatch; the broad `cursor-agent models` catalog alone is not enough proof.
     - Rule files render as `.cursor/rules/*.mdc`
 
 === "Copilot"
@@ -42,9 +44,10 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
       - `.codex/agents/<role>.toml`
       - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
     - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project`
-    - The Codex sync extension also generates effort-specific implementer role variants — `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, each setting `model_reasoning_effort` — alongside the canonical-derived roles; the base `oat-phase-implementer` role represents inherited effort. These generated variants are managed by `oat sync` and are not treated as strays (see Manifest and Drift → Generated provider roles)
+    - The Codex sync extension also generates materialized roles from explicit model+effort targets, such as `oat-phase-implementer-gpt-5-6-terra-xhigh` or `oat-reviewer-gpt-5-6-terra-xhigh`, alongside canonical-derived base roles. These generated variants are managed by `oat sync` and are not treated as strays (see Manifest and Drift -> Generated provider roles)
+    - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a one-off user-scope role.
     - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
-    - User-scope Codex role generation (`~/.codex`) remains deferred
+    - User-scope Codex role generation via provider sync (`~/.codex`) remains deferred
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
 
@@ -53,7 +56,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
 - Project scope: skills + agents + rules
 - User scope: skills + agents (provider mappings vary by adapter)
 - Rules are project-scoped only in this release
-- Codex user-scope role generation under `~/.codex` remains deferred in this release
+- Codex user-scope role generation under `~/.codex` via provider sync remains deferred in this release; direct one-off materialization can use `--scope user`
 
 ## Adoption model
 

package/assets/docs/provider-sync/scope-and-surface.md

@@ -34,6 +34,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat providers list`
 - `oat providers inspect`
 - `oat providers set`
+- `oat providers codex materialize`
 
 ## Adjacent CLI commands (commonly used with provider interop)
 
@@ -46,7 +47,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Project provider enablement is stored in `.oat/sync/config.json` (`providers.<name>.enabled`).
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
-- Codex project-scope subagent sync is generated output (`.codex/agents/*.toml` + `.codex/config.toml`) computed at command layer after path-mapping sync. Generated Codex roles — including the effort-specific implementer variants — are tracked as managed by `oat status` and `oat init`, not as strays.
+- Codex project-scope subagent sync is generated output (`.codex/agents/*.toml` + `.codex/config.toml`) computed at command layer after path-mapping sync. Generated Codex roles - including materialized model+effort implementer and reviewer variants - are tracked as managed by `oat status` and `oat init`, not as strays.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - Codex user-scope role generation remains intentionally deferred in this release.
 

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

@@ -107,9 +107,9 @@ Current schema keys:
 | `git.defaultBranch`                         | `string`   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                      |
 | `workflow.autoReviewAtHillCheckpoints`      | `boolean`  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback. |
 | `workflow.dispatchPolicy.mode`              | `string`   | unset                    | Dispatch policy mode: `managed` lets OAT select model/effort controls; `inherit` leaves controls to the host/provider defaults.                                                                                                                                                                         |
-| `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.                                                                                                 |
+| `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.codex`  | `string`   | unset                    | Legacy concrete Codex capped target (`low`, `medium`, `high`, or `xhigh`). Codex provider default effort is informational only for explicit inherit/default behavior or base/unpinned fallback paths.                                                                                                   |
+| `workflow.dispatchCeiling.providers.codex`  | `string`   | unset                    | Legacy concrete Codex capped target (`low`, `medium`, `high`, or `xhigh`). New managed Codex dispatch resolves explicit model+effort targets to materialized role names; provider default effort is informational only for explicit inherit/default behavior or base/unpinned fallback paths.           |
 | `workflow.dispatchCeiling.providers.claude` | `string`   | unset                    | Legacy concrete Claude capped target (`haiku`, `sonnet`, `opus`, or `fable`). Claude has no separate per-dispatch effort axis. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed (no 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.                                                                                                                                             |