@open-agent-toolkit/cli 0.1.42 → 0.1.45

package/assets/agents/oat-phase-implementer.md

@@ -35,14 +35,16 @@ You will be given a "Phase Scope" block including:
 - **workflow_mode**: `spec-driven` | `quick` | `import` (default `spec-driven`)
 - **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
 - **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
-- **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this dispatch
-- **ceiling_source**: Optional source for the resolved ceiling (`repo config`, `project state`, or `preflight prompt`)
-- **provider_default_effort**: Optional Codex provider default effort, used only to explain base/unpinned fallback dispatches
+- **dispatch_policy**: Optional resolved policy label (`economy`, `balanced`, `high`, `frontier`, `uncapped`, `inherit host defaults`, or `legacy capped`)
+- **dispatch_ceiling**: Optional resolved provider cap that may have capped/selected this dispatch; absent or null for `uncapped` and inherit/default modes
+- **policy_source**: Optional source for the resolved policy (`repo config`, `project state`, or `preflight prompt`)
+- **ceiling_source**: Optional compatibility alias for policy source (`repo config`, `project state`, or `preflight prompt`)
+- **provider_default_effort**: Optional Codex provider default effort, used only to explain inherit/default behavior or base/unpinned fallback dispatches
 - **dispatch_rationale**: Optional short rationale for the model/effort axis choices
 
-The `model_axis`, `effort_axis`, `dispatch_ceiling`, `ceiling_source`, and `provider_default_effort` fields describe dispatch state the orchestrator already chose; they are descriptive context for your report, not actions for you to take. Echo whatever values were provided in your summary. If a field is absent, report it as "not provided."
+The `model_axis`, `effort_axis`, `dispatch_policy`, `dispatch_ceiling`, `policy_source`, `ceiling_source`, and `provider_default_effort` fields describe dispatch state the orchestrator already chose; they are descriptive context for your report, not actions for you to take. Echo whatever values were provided in your summary. If a field is absent, report it as "not provided."
 
-For Codex, `provider-default` means the base/unpinned role follows Codex configured/provider default effort. It does not mean OAT inherited the parent session ceiling.
+For Codex, `provider-default` means explicit inherit/default behavior or a base/unpinned fallback follows Codex configured/provider default effort. It does not mean managed `Uncapped`, and it does not mean OAT inherited the parent session ceiling.
 
 If `mode: fix`, the block also includes:
 
@@ -131,8 +133,9 @@ Report format:
 **Confidence:** high | medium | low
 **Model axis:** {model_axis if provided, otherwise "not provided"}
 **Effort axis:** {effort_axis if provided, otherwise "not provided"}
+**Dispatch policy:** {dispatch_policy if provided, otherwise "not provided"}
 **Dispatch ceiling:** {dispatch_ceiling if provided, otherwise "not provided"}
-**Ceiling source:** {ceiling_source if provided, otherwise "not provided"}
+**Policy source:** {policy_source if provided, otherwise ceiling_source if provided, otherwise "not provided"}
 **Provider default effort:** {provider_default_effort if provided, otherwise "not provided"}
 
 ### Task Outcomes
@@ -200,8 +203,9 @@ If a fix introduces a regression or doesn't address its finding, either re-fix w
 **Confidence:** high | medium | low
 **Model axis:** {model_axis if provided, otherwise "not provided"}
 **Effort axis:** {effort_axis if provided, otherwise "not provided"}
+**Dispatch policy:** {dispatch_policy if provided, otherwise "not provided"}
 **Dispatch ceiling:** {dispatch_ceiling if provided, otherwise "not provided"}
-**Ceiling source:** {ceiling_source if provided, otherwise "not provided"}
+**Policy source:** {policy_source if provided, otherwise ceiling_source if provided, otherwise "not provided"}
 **Provider default effort:** {provider_default_effort if provided, otherwise "not provided"}
 
 ### Fix Outcomes

package/assets/agents/oat-reviewer.md

@@ -57,16 +57,18 @@ You will be given a "Review Scope" block including:
 - **oat_review_invocation**: Optional provenance selector for artifact-mode reviews. Use `manual`, `auto`, or `gate`; default to `manual` when absent.
 - **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
 - **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
-- **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this review dispatch
-- **ceiling_source**: Optional source for the resolved ceiling (`repo config`, `project state`, or `preflight prompt`)
-- **provider_default_effort**: Optional Codex provider default effort, used only to explain base/unpinned fallback dispatches
+- **dispatch_policy**: Optional resolved policy label (`economy`, `balanced`, `high`, `frontier`, `uncapped`, `inherit host defaults`, or `legacy capped`)
+- **dispatch_ceiling**: Optional resolved provider cap that may have capped/selected this review dispatch; absent or null for `uncapped` and inherit/default modes
+- **policy_source**: Optional source for the resolved policy (`repo config`, `project state`, or `preflight prompt`)
+- **ceiling_source**: Optional compatibility alias for policy source (`repo config`, `project state`, or `preflight prompt`)
+- **provider_default_effort**: Optional Codex provider default effort, used only to explain inherit/default behavior or base/unpinned fallback dispatches
 - **dispatch_rationale**: Optional short rationale for the model/effort axis choices
 
 ## Dispatch Control
 
 The orchestrator owns dispatch control. Do not read `plan.md` Dispatch Profile rows to self-select a tier.
 
-For Codex, normal deterministic review dispatch uses pinned reviewer variants (`oat-reviewer-low`, `oat-reviewer-medium`, `oat-reviewer-high`, or `oat-reviewer-xhigh`) selected by the resolved OAT dispatch ceiling. The base `oat-reviewer` role is 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 an OAT ceiling.
+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 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/configuration.md

@@ -168,50 +168,97 @@ oat config get lastPausedProject
 oat config describe activeIdea
 ```
 
-## Dispatch ceiling resolution
+## Dispatch policy resolution
 
-The dispatch ceiling is set as a **provider-neutral preset** (or per-provider
-advanced values) and compiled at write time into concrete per-provider values.
-Runtime dispatch reads only the concrete values — never the preset label.
+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 — presets, the compile/resolve flow, and how
-enforcement differs for Codex, Claude, and unsupported providers — see
-[Dispatch Ceiling](../workflows/projects/dispatch-ceiling.md).
+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
 
-Three keys control the ceiling, all under `workflow.dispatchCeiling`:
+Preferred keys:
 
-| Key                                         | Values                                  | Purpose                                             |
-| ------------------------------------------- | --------------------------------------- | --------------------------------------------------- |
-| `workflow.dispatchCeiling.preset`           | `balanced`, `maximum`, `cost-conscious` | Convenience preset; compiles to concrete values     |
-| `workflow.dispatchCeiling.providers.codex`  | `low`, `medium`, `high`, `xhigh`        | Concrete Codex ceiling (set by preset or Advanced)  |
-| `workflow.dispatchCeiling.providers.claude` | `haiku`, `sonnet`, `opus`               | Concrete Claude ceiling (set by preset or Advanced) |
+| Key                              | Values                                                | Purpose                                                                            |
+| -------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `workflow.dispatchPolicy.mode`   | `managed`, `inherit`                                  | `managed` lets OAT select controls; `inherit` leaves controls to the host/provider |
+| `workflow.dispatchPolicy.policy` | `economy`, `balanced`, `high`, `frontier`, `uncapped` | Managed policy. Setting this key writes `mode=managed`                             |
 
-**Presets compile to:**
+Managed policies compile to:
 
-| Preset           | Codex    | Claude   |
-| ---------------- | -------- | -------- |
-| `balanced`       | `high`   | `sonnet` |
-| `maximum`        | `xhigh`  | `opus`   |
-| `cost-conscious` | `medium` | `sonnet` |
+| Policy     | Codex    | Claude   |
+| ---------- | -------- | -------- |
+| `economy`  | `medium` | `sonnet` |
+| `balanced` | `high`   | `sonnet` |
+| `high`     | `xhigh`  | `opus`   |
+| `frontier` | `xhigh`  | `fable`  |
+| `uncapped` | none     | none     |
 
-**Advanced (no preset):** set `providers.codex` and/or `providers.claude`
-individually. No `preset` key is stored.
+Dispatch matrix and legacy compatibility keys:
 
-**No ceiling:** leave `oat_dispatch_ceiling` unset; implementer subagents run at
-provider defaults.
+| 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:
+
+```bash
+oat config set workflow.dispatchPolicy.mode inherit
+```
 
 ### How enforcement works
 
-OAT applies the ceiling where the provider exposes a reliable mechanism. Other
-providers receive it as advisory.
+OAT applies managed policies where the provider exposes a reliable mechanism.
+Providers without an adapter receive them as 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`      |
 
-| 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`. 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
@@ -219,11 +266,12 @@ confirms the actual model used after dispatch. If the provider did not honor the
 upgrade, the enforcement log reads `advisory — provider did not honor upgrade;
 ran <tier>` instead of `enforced`.
 
-### Clean break
+### Legacy compatibility
 
-The previous flat keys (`workflow.dispatchCeiling.codex` and
-`workflow.dispatchCeiling.claude`) are removed. There is no migration path — set
-the new keys.
+The command group and docs path still use `dispatch-ceiling` for compatibility.
+Legacy `workflow.dispatchCeiling.*` config and project `oat_dispatch_ceiling`
+frontmatter remain readable as capped managed policy input. Absent legacy state
+does not mean managed `Uncapped`.
 
 ### Using the resolver
 
@@ -235,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_ceiling` frontmatter. For Codex it also reports
-`providerDefaultEffort`, which is informational for base/unpinned roles and is
-not treated as the OAT ceiling.
+`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:
 
@@ -269,9 +319,12 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.
 - `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.dispatchCeiling.preset` — `balanced`, `maximum`, or `cost-conscious`. Convenience preset that compiles to per-provider values at write time. Setting this key is the recommended way to configure the ceiling.
-- `workflow.dispatchCeiling.providers.codex` — `low`, `medium`, `high`, or `xhigh`. Concrete Codex ceiling. Set automatically when a preset is selected; also settable directly for Advanced (no preset) configurations. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
-- `workflow.dispatchCeiling.providers.claude` — `haiku`, `sonnet`, or `opus`. Concrete Claude ceiling. Set automatically when a preset is selected; also settable directly for Advanced configurations. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
+- `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.<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
@@ -308,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
 
@@ -315,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/reference/oat-directory-structure.md

@@ -93,30 +93,32 @@ Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files m
 
 Current schema keys:
 
-| Key                                         | Type       | Default                  | Description                                                                                                                                                                                                                                                                                                                   |
-| ------------------------------------------- | ---------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                                                                                                                                                                |
-| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                                                  |
-| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                                       |
-| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                                                   |
-| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                                                 |
-| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                                                   |
-| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                                        |
-| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                                               |
-| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                 |
-| `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.dispatchCeiling.preset`           | `string`   | unset                    | Convenience preset compiled at write time to concrete per-provider ceilings (`balanced` = codex `high` / claude `sonnet`; `maximum` = codex `xhigh` / claude `opus`; `cost-conscious` = codex `medium` / claude `sonnet`). Stored only when a preset is chosen; runtime reads compiled `providers.*`, never the preset label. |
-| `workflow.dispatchCeiling.providers.codex`  | `string`   | unset                    | Maximum Codex reasoning effort OAT may select through deterministic pinned implementer/reviewer variants (`low`, `medium`, `high`, or `xhigh`). Codex provider default effort is informational for base/unpinned roles and is not treated as this ceiling.                                                                    |
-| `workflow.dispatchCeiling.providers.claude` | `string`   | unset                    | Maximum Claude model tier OAT may select for provider-native subagent dispatch (`haiku`, `sonnet`, or `opus`). 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.                                                                                                                                                                   |
-| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                                      |
-| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                                                    |
-| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                                             |
-| `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                                                    |
-| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                           |
-| `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                               |
+| Key                                         | Type       | Default                  | Description                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------- | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                   | `number`   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
+| `worktrees.root`                            | `string`   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
+| `projects.root`                             | `string`   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
+| `localPaths`                                | `string[]` | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
+| `documentation.root`                        | `string`   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
+| `documentation.tooling`                     | `string`   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
+| `documentation.config`                      | `string`   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                  |
+| `documentation.index`                       | `string`   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                         |
+| `documentation.requireForProjectCompletion` | `boolean`  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                           |
+| `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.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.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.                                                                                                                                             |
+| `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                |
+| `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                              |
+| `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                       |
+| `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                              |
+| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                     |
+| `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                         |
 
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.