@open-agent-toolkit/cli 0.1.43 → 0.1.46

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -1,6 +1,6 @@
 ---
 title: Dispatch Policy
-description: 'How OAT dispatch policy works: managed capped tiers, managed Uncapped, Inherit Host Defaults, legacy dispatch-ceiling compatibility, and provider-specific enforcement.'
+description: 'How OAT dispatch policy works: managed tiers, dispatch matrix cells, ordered routes, producer provenance, legacy compatibility, and provider-specific enforcement.'
 ---
 
 # Dispatch Policy
@@ -21,20 +21,27 @@ dispatch policy terminology.
 For raw config keys see [Configuration](../../cli-utilities/configuration.md);
 for execution-time behavior see [Implementation Execution](implementation-execution.md).
 
+Multi-family providers such as Cursor use the same abstract policy names, but
+their concrete model values come from a dispatch matrix under
+`workflow.dispatchCeiling.providers.*`. A matrix cell can be a single value, a
+per-tier value, or an ordered route for escalation.
+
 ## Policy Choices
 
-| Policy                  | Mode    | Codex target | Claude target | Meaning                                      |
-| ----------------------- | ------- | ------------ | ------------- | -------------------------------------------- |
-| `Economy`               | managed | `medium`     | `sonnet`      | Lower-cost managed cap                       |
-| `Balanced`              | managed | `high`       | `sonnet`      | Default managed cap                          |
-| `High`                  | managed | `xhigh`      | `opus`        | High-capability managed cap                  |
-| `Frontier`              | managed | `xhigh`      | `fable`       | Top managed tier currently exposed by OAT    |
-| `Uncapped`              | managed | none         | none          | OAT selects preferred controls without a cap |
-| `Inherit Host Defaults` | inherit | none         | none          | OAT does not select model/effort controls    |
+| Policy                  | Mode    | Codex cap | Claude target | Meaning                                      |
+| ----------------------- | ------- | --------- | ------------- | -------------------------------------------- |
+| `Economy`               | managed | `medium`  | `sonnet`      | Lower-cost managed cap                       |
+| `Balanced`              | managed | `high`    | `sonnet`      | Default managed cap                          |
+| `High`                  | managed | `xhigh`   | `opus`        | High-capability managed cap                  |
+| `Frontier`              | managed | `xhigh`   | `fable`       | Top managed tier currently exposed by OAT    |
+| `Uncapped`              | managed | none      | none          | OAT selects preferred controls without a cap |
+| `Inherit Host Defaults` | inherit | none      | none          | OAT does not select model/effort controls    |
 
 `Uncapped` is explicit managed state. It is not represented by omitting policy
 state. Existing projects with absent legacy ceiling state remain unresolved or
-legacy-compatible; they do not silently become managed `Uncapped`.
+legacy-compatible; they do not silently become managed `Uncapped`. `Unresolved`
+is a deferral state for planning/preflight only. Implementation preflight must
+resolve a managed policy or inherit/default mode before work starts.
 
 ## Config Shapes
 
@@ -85,13 +92,55 @@ oat_dispatch_policy:
 Legacy compatibility keys remain readable:
 
 - `workflow.dispatchCeiling.preset`
-- `workflow.dispatchCeiling.providers.codex`
-- `workflow.dispatchCeiling.providers.claude`
+- `workflow.dispatchCeiling.providers.<provider>`
+- `workflow.dispatchCeiling.providers.<provider>.<tier>`
 - `oat_dispatch_ceiling`
 
 Legacy preset names map into the managed ladder: `cost-conscious` maps to
 `Economy`, `balanced` maps to `Balanced`, and `maximum` maps to `High`.
 
+## Dispatch Matrix
+
+The dispatch matrix maps the abstract policy rung (`economy`, `balanced`,
+`high`, `frontier`) to concrete provider controls. Existing bare Codex and
+Claude values remain valid, and multi-family providers can use tier cells:
+
+```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.cursor.high gpt-5.5-xhigh --shared
+```
+
+For ordered escalation, write a route in config JSON. The resolver selects the
+floor entry at escalation level `0` and advances by route entry when the
+implementation/fix loop escalates:
+
+```json
+{
+  "workflow": {
+    "dispatchCeiling": {
+      "providers": {
+        "cursor": {
+          "high": [
+            "composer-2.5",
+            { "harness": "cursor", "model": "gpt-5.5-xhigh" }
+          ],
+          "frontier": [
+            { "harness": "cursor", "model": "gpt-5.5-xhigh" },
+            { "harness": "cursor", "model": "fable-5" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+Project `state.md` may carry only sparse project-specific matrix overrides
+under `oat_dispatch_policy.matrix`. The full reusable matrix belongs in user,
+shared, or local config so switching harnesses mid-project re-resolves the same
+abstract policy through the active provider column.
+
 ## How Resolution Works
 
 Before dispatching a subagent, the orchestrator calls:
@@ -105,6 +154,7 @@ For implementer or fix dispatch, pass the preferred runtime control:
 ```bash
 oat project dispatch-ceiling resolve --provider codex --role implementer --preferred high --json
 oat project dispatch-ceiling resolve --provider claude --role implementer --preferred opus --json
+oat project dispatch-ceiling resolve --provider cursor --role implementer --preferred high --escalation-level 0 --json
 ```
 
 The resolver returns the resolved policy, optional cap, source, provider default
@@ -114,6 +164,9 @@ Selection modes:
 
 - `capped` - implementer/fix dispatch selects `min(preferred, cap)`.
 - `uncapped` - implementer/fix dispatch selects the preferred value.
+- `matrix-pinned` - a matrix cell supplied the selected provider value.
+- `prompt-persisted` - an interactive prompt filled a missing cell and persisted it.
+- `escalation-target` - an ordered route entry supplied the selected target.
 - `review-target` - reviewer dispatch targets a configured cap when one exists.
 - `no-review-target` - managed uncapped reviewer dispatch has no configured
   target and falls back to the base/unpinned reviewer.
@@ -122,23 +175,53 @@ Selection modes:
 
 ## Provider Behavior
 
-|                   | Codex                                       | Claude Code                             | Unsupported provider |
-| ----------------- | ------------------------------------------- | --------------------------------------- | -------------------- |
-| Managed mechanism | Pinned role variants                        | Task `model` argument                   | None                 |
-| Axis              | effort (`low < medium < high < xhigh`)      | model (`haiku < sonnet < opus < fable`) | None                 |
-| Capped policy     | selected pinned variant up to cap           | selected Task model up to cap           | advisory/unsupported |
-| Uncapped          | preferred pinned variant, no cap            | preferred Task model, no cap            | advisory/unsupported |
-| Inherit/default   | base/unpinned role follows provider default | omit `model`                            | normal behavior      |
-
-Codex uses pinned variants because per-call effort controls were unreliable in
-dogfooding. For managed `Uncapped`, OAT still selects the preferred pinned
-variant; the dispatching host should verify whether upward effort selection is
-actually honored in the current session.
+|                   | Codex                                                 | Claude Code                             | Cursor / model-arg providers | Unsupported provider |
+| ----------------- | ----------------------------------------------------- | --------------------------------------- | ---------------------------- | -------------------- |
+| Managed mechanism | Materialized roles with explicit `model` and `effort` | Task `model` argument                   | Task/CLI `model` argument    | None                 |
+| Axis              | model plus effort (`low < medium < high < xhigh`)     | model (`haiku < sonnet < opus < fable`) | opaque model slug            | None                 |
+| Capped policy     | materialized target selected up to cap                | selected Task model up to cap           | selected matrix cell         | advisory/unsupported |
+| Uncapped          | preferred materialized target, no cap                 | preferred Task model, no cap            | preferred matrix cell        | advisory/unsupported |
+| Inherit/default   | base/unpinned role follows provider default           | omit `model`                            | omit model selection         | normal behavior      |
+
+Codex uses materialized roles because per-call model/effort controls were
+unreliable in dogfooding. The resolver compiles an explicit model+effort target
+into a role name such as `oat-phase-implementer-gpt-5-6-terra-xhigh`, and the
+Codex spawn payload uses that role as `agent_type`. For managed `Uncapped`, OAT
+still selects the preferred materialized target. If the Codex preferred value is
+an effort rather than a matrix tier, OAT looks up the highest managed tier that
+compiles to that effort before resolving the matrix target; for example,
+`--preferred xhigh` resolves through the `frontier` matrix cell. The dispatching
+host should verify whether upward effort selection is actually honored in the
+current session. The old effort-only Codex pins are not the managed dispatch
+contract for new projects.
 
 Claude Code uses the per-call Task `model` argument. It has no OAT-managed
 per-dispatch effort axis, so dispatch logs use `effort_axis=not-applicable`.
 `Frontier` maps to Claude `fable`.
 
+Cursor and other model-arg providers use matrix values as opaque slugs. OAT
+validates availability with provider oracles when possible, but tier semantics
+come from the configured matrix, not from a built-in model catalog. For Cursor,
+that validation checks subagent Task eligibility, not just broad catalog
+visibility, because a slug can appear in `cursor-agent models` and still be
+rejected for subagent dispatch.
+
+## Producer Provenance
+
+Dispatch notes use a parseable single-line stamp so later gates can identify
+the producer family:
+
+```text
+Dispatch: scope=p06 action=implementation role=implementer producer=gpt-5.5-xhigh provenance=declared model_axis=selected:gpt-5.5-xhigh effort_axis=not-applicable dispatch_policy=high dispatch_ceiling=xhigh target=cursor
+```
+
+`producer` is the resolved model slug when OAT knows it, otherwise `unknown`.
+`provenance` is one of `declared`, `observed`, `inferred`, or `unknown`.
+Concrete same-harness model arguments can be declared. Codex materialized
+model+effort roles declare `model_axis=selected:<model>` and
+`effort_axis=selected:<effort>` from resolver output, but producer identity
+remains `unknown` unless an observed or inferred model identity is available.
+
 ## Implementer, Fix, and Reviewer Behavior
 
 For implementer and fix dispatches:
@@ -164,9 +247,9 @@ say `provider-default`.
 Examples:
 
 ```text
-Dispatch policy: balanced; selected=high; cap=high (codex, enforced — variant oat-phase-implementer-high)
-Dispatch policy: high; selected=xhigh; cap=xhigh (codex, enforced — variant oat-reviewer-xhigh)
-Dispatch policy: uncapped; selected=xhigh; cap=none (codex, enforced — variant oat-phase-implementer-xhigh)
+Dispatch policy: balanced; selected=high; cap=high (codex, enforced — variant oat-phase-implementer-gpt-5-6-terra-high)
+Dispatch policy: high; selected=xhigh; cap=xhigh (codex, enforced — variant oat-reviewer-gpt-5-6-terra-xhigh)
+Dispatch policy: uncapped; selected=xhigh; cap=none (codex, enforced — variant oat-phase-implementer-gpt-5-6-sol-xhigh)
 Dispatch policy: inherit host defaults; selected=none; cap=none (codex, advisory — base role follows provider default)
 Dispatch policy: frontier; selected=fable; cap=fable (claude, enforced — Task model arg)
 ```

package/assets/docs/workflows/projects/implementation-execution.md

@@ -70,16 +70,16 @@ Runtime dispatch reads the resolved policy and provider-specific selection only.
 For Codex, provider default effort is displayed when available but is not treated as managed `Uncapped` or as a cap. Provider defaults apply only to explicit inherit/default behavior or base/unpinned fallback paths.
 
 ```text
-Dispatch policy: balanced (codex, managed capped — pinned-variant)
+Dispatch policy: balanced (codex, managed capped — materialized-role)
 Resolved cap: high
 Source: project state
 Provider default effort: medium
-Note: OAT will use pinned subagent variants up to high. Base/unpinned roles resolve through the provider default only on fallback paths.
+Note: OAT will use resolver-returned materialized Codex role names up to high. Base/unpinned roles resolve through the provider default only on fallback paths.
 ```
 
 **Enforcement modes** (from resolver):
 
-- `enforced` — the adapter compiled concrete dispatch args and the provider accepted them (Codex: pinned variants; Claude: Task `model` parameter).
+- `enforced` — the adapter compiled concrete dispatch args and the provider accepted them (Codex: materialized model+effort roles; Claude: Task `model` parameter).
 - `advisory` — the provider is supported but no value resolved, or an upgrade request was not honored by the provider.
 - `unsupported` — the provider has no registered adapter; the policy is informational only. Dispatch follows provider behavior.
 
@@ -112,7 +112,14 @@ Model and effort are separate axes. Each axis logs one of these states:
 - `not-applicable` — this host/API has no meaningful per-dispatch concept for that axis.
 - `host-auto` — exceptional; the host uses that axis internally but the orchestrator cannot read or pin it.
 
-In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and pass it to `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <effort>`. For capped managed policies, the resolver selects `min(preferred, resolved_cap)` and returns the matching pinned role. For managed `Uncapped`, the resolver selects the preferred pinned role with no cap. For inherit/default mode, it returns no pinned role and OAT uses the base/unpinned role. Reviewer dispatch targets the configured cap only when a capped managed policy exists; managed `Uncapped` and inherit/default use base `oat-reviewer` fallback.
+In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and pass it to `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <effort>`. For capped managed policies, the resolver selects `min(preferred, resolved_cap)` and returns a materialized role name compiled from an explicit model+effort target. For managed `Uncapped`, the resolver selects the preferred materialized role with no cap. For inherit/default mode, it returns no materialized role and OAT uses the base/unpinned role. Reviewer dispatch targets the configured cap only when a capped managed policy exists; managed `Uncapped` and inherit/default use base `oat-reviewer` fallback.
+
+Because Codex preferred values are effort names while dispatch matrix cells are
+keyed by OAT tiers, managed `Uncapped` maps preferred efforts through the
+managed tier table before resolving matrix targets. For example, `xhigh` maps to
+the highest matching tier, `frontier`, so `--preferred xhigh` can resolve a
+`frontier` Codex matrix target such as
+`oat-phase-implementer-gpt-5-6-sol-xhigh`.
 
 In Claude Code, implementation and fix dispatch classify a preferred model tier (`haiku`, `sonnet`, `opus`, or `fable`) and pass it to `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <model> --orchestrator-tier <current-orchestrator-tier>`. Capped policies select `min(preferred, resolved_cap)`, managed `Uncapped` selects the preferred model, and inherit/default omits `model`. Reviewer dispatch passes a `model` only when the resolver returns one. The separate effort axis is `not-applicable`.
 
@@ -135,9 +142,9 @@ Selected effort: medium
 Policy source: repo config
 Provider default effort: high
 Selection mode: capped
-Model axis: inherited
+Model axis: selected:gpt-5.6-terra
 Effort axis: selected:medium
-Dispatch target: oat-phase-implementer-medium
+Dispatch target: oat-phase-implementer-gpt-5-6-terra-medium
 Rationale: shared TypeScript/config substrate; high preferred due to integration risk, capped by configured policy.
 
 OAT Dispatch: Phase p03 review
@@ -148,9 +155,9 @@ Selected effort: xhigh
 Policy source: project state
 Provider default effort: medium
 Selection mode: review-target
-Model axis: inherited
+Model axis: selected:gpt-5.6-terra
 Effort axis: selected:xhigh
-Dispatch target: oat-reviewer-xhigh
+Dispatch target: oat-reviewer-gpt-5-6-terra-xhigh
 Rationale: reviewer runs at the configured policy cap for deterministic quality gate behavior.
 
 OAT Dispatch: Phase p03 implementation
@@ -162,10 +169,10 @@ Selected effort: xhigh
 Policy source: project state
 Provider default effort: medium
 Selection mode: uncapped
-Model axis: inherited
+Model axis: selected:gpt-5.6-sol
 Effort axis: selected:xhigh
-Dispatch target: oat-phase-implementer-xhigh
-Rationale: high-risk phase; managed uncapped policy allows the preferred pinned variant.
+Dispatch target: oat-phase-implementer-gpt-5-6-sol-xhigh
+Rationale: high-risk phase; managed uncapped policy allows the preferred materialized target.
 
 OAT Dispatch: Phase p04 implementation
 Host: Other
@@ -203,10 +210,10 @@ Add Dispatch Profile rows only when the user has an explicit constraint or prefe
 For each phase in the plan (whether sequential or inside a parallel group):
 
 1. **Select runtime dispatch control** for the phase and log the chosen control plus rationale.
-2. **Dispatch the selected implementer role** with a Phase Scope block (project path, phase id, artifact paths, commit convention, workflow mode, and dispatch context when known). In Codex, `effort_axis=selected:low|medium|high|xhigh` uses `oat-phase-implementer-low|medium|high|xhigh`. Base `oat-phase-implementer` means provider-default/unpinned fallback.
+2. **Dispatch the selected implementer role** with a Phase Scope block (project path, phase id, artifact paths, commit convention, workflow mode, and dispatch context when known). In Codex, selected model+effort axes use the resolver-returned materialized role name, such as `oat-phase-implementer-gpt-5-6-terra-xhigh`. Base `oat-phase-implementer` means provider-default/unpinned fallback.
 3. **Receive the summary:** `DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
    - `BLOCKED` stops the run and surfaces the blocker to the user.
-4. **Dispatch the selected reviewer role** with a Review Scope block (phase id, commit range, optional files-changed hint, and dispatch context). The commit range is authoritative; the file list is only orientation metadata. In Codex, pass this as a self-contained packet with `fork_context: false`; use an `oat-reviewer-<value>` variant only for capped managed policies, and use base `oat-reviewer` for managed `Uncapped` or inherit/default. In Claude Code, pass a review `model` only when the resolver returns one and always record `effort_axis=not-applicable`. If the reviewer does not conclude on the first wait, poll once more, then send a concise "return now with current findings" nudge before falling back inline for that phase.
+4. **Dispatch the selected reviewer role** with a Review Scope block (phase id, commit range, optional files-changed hint, and dispatch context). The commit range is authoritative; the file list is only orientation metadata. In Codex, pass this as a self-contained packet with `fork_context: false`; use the resolver-returned materialized reviewer role only for capped managed policies, and use base `oat-reviewer` for managed `Uncapped` or inherit/default. In Claude Code, pass a review `model` only when the resolver returns one and always record `effort_axis=not-applicable`. If the reviewer does not conclude on the first wait, poll once more, then send a concise "return now with current findings" nudge before falling back inline for that phase.
 5. **Parse the verdict:** zero Critical + zero Important findings → `pass`; otherwise `fail`.
 6. **On fail, run the bounded fix loop** (see below).
 7. **Update artifacts** (`implementation.md`, `plan.md` review row, `state.md`) and make the mandatory bookkeeping commit.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.43",
-  "docs-config": "0.1.43",
-  "docs-theme": "0.1.43",
-  "docs-transforms": "0.1.43"
+  "cli": "0.1.46",
+  "docs-config": "0.1.46",
+  "docs-theme": "0.1.46",
+  "docs-transforms": "0.1.46"
 }