@open-agent-toolkit/cli 0.1.43 → 0.1.45

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/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,13 +196,44 @@ 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 |
+
+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. Do not represent it by leaving policy
 state absent. To request no OAT model/effort selection, set:
@@ -214,17 +245,20 @@ oat config set workflow.dispatchPolicy.mode inherit
 ### 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    | Pinned role variants      | `enforced`                 |
-| Claude   | Task `model` parameter    | `enforced`                 |
-| Others   | None (informational only) | `advisory` / `unsupported` |
+| Provider | Mechanism                 | Enforcement mode                |
+| -------- | ------------------------- | ------------------------------- |
+| Codex    | Pinned role variants      | `enforced`                      |
+| Claude   | Task `model` parameter    | `enforced`                      |
+| Cursor   | `--model` argument        | `enforced` when a cell resolves |
+| 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.
 
 **Verify-on-upgrade:** when the requested tier exceeds the current orchestrator
 tier (an upgrade request), the resolver sets `verifyOnDispatch: true`. The skill
@@ -249,12 +283,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:
 
@@ -286,8 +322,9 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `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.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 +361,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 +369,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/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,6 +21,11 @@ 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                                      |
@@ -85,13 +90,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 +152,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 +162,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,13 +173,13 @@ 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                                       | Claude Code                             | Cursor / model-arg providers | Unsupported provider |
+| ----------------- | ------------------------------------------- | --------------------------------------- | ---------------------------- | -------------------- |
+| Managed mechanism | Pinned role variants                        | Task `model` argument                   | `--model` argument           | None                 |
+| Axis              | effort (`low < medium < high < xhigh`)      | model (`haiku < sonnet < opus < fable`) | opaque model slug            | None                 |
+| Capped policy     | selected pinned variant up to cap           | selected Task model up to cap           | selected matrix cell         | advisory/unsupported |
+| Uncapped          | preferred pinned variant, no cap            | preferred Task model, no cap            | preferred matrix cell        | advisory/unsupported |
+| Inherit/default   | base/unpinned role follows provider default | omit `model`                            | 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
@@ -139,6 +190,25 @@ 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.
+
+## 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 pinned effort
+variants declare effort, not concrete producer identity, unless an observed or
+inferred model is available.
+
 ## Implementer, Fix, and Reviewer Behavior
 
 For implementer and fix dispatches:

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.45",
+  "docs-config": "0.1.45",
+  "docs-theme": "0.1.45",
+  "docs-transforms": "0.1.45"
 }