@open-agent-toolkit/cli 0.1.46 → 0.1.50

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

@@ -33,7 +33,7 @@ Gate config lives under `workflow.gates.skills` and is keyed by skill name.
     "gates": {
       "skills": {
         "oat-project-implement": {
-          "command": "oat gate review \"Use oat-project-review-provide code final to review the current project\"",
+          "command": "oat gate review --project \"$PROJECT_PATH\" --review-type code --review-scope final \"Use oat-project-review-provide code final for the declared project\"",
           "description": "Run a fresh-runtime final review before implementation is considered done.",
           "onFailure": "block",
           "maxAttempts": 2
@@ -69,9 +69,65 @@ review side effects are expected:
   tracked state
 
 Gate-produced review artifacts use `oat_review_invocation: gate` in
-frontmatter. After a gate review reports a produced artifact, the host must run
-or hand off to `oat-project-review-receive` before treating the review as
-dispositioned. Until receive runs, the artifact is only produced, not consumed.
+frontmatter. After a gate returns a corroborated `ok` or `blocked` result with a
+non-null `handoff`, the host must run or hand off to
+`oat-project-review-receive` before treating the review as dispositioned. An
+artifact path by itself is not receive eligibility. Until receive runs for a
+receive-eligible result, the artifact is only produced, not consumed.
+
+Gate-originated artifacts also copy the configured invocation record that the
+CLI places in the review prompt:
+
+```yaml
+oat_review_invocation: gate
+oat_project: .oat/projects/shared/example
+oat_gate_run_id: 00000000-0000-0000-0000-000000000000
+oat_gate_target: codex-sol-max
+oat_gate_runtime: codex
+oat_invocation_model: gpt-5.6-sol # or provider-default | unknown
+oat_invocation_reasoning_effort: max # or provider-default | unknown
+oat_invocation_source: exec-target-config # or unknown
+```
+
+These fields describe configured invocation controls. They do not confirm the
+model that ran, and the reviewer must not replace them with self-identification.
+The CLI compares the copied values with its gate-owned record before it applies
+the severity threshold.
+
+### Gate dispatch report semantics
+
+When gate dispatch is represented in a `DispatchReportV1`, consumers require
+`schemaVersion: 1` and keep three facts independent:
+
+- `gateInvocation` is the immutable configured run ID, target, runtime, model,
+  reasoning effort, and source.
+- `runtimeIdentity` is observed or otherwise supported producer identity; it is
+  `not-reported` when no runtime evidence exists.
+- gate `diversity` describes producer/reviewer routing and achieved separation;
+  it does not overwrite either configured invocation or runtime identity.
+
+Configured target values, requested controls, producer stamps, and reviewer
+self-report are not interchangeable. The human report is rendered from the
+versioned object, and any parseable `Dispatch:` compatibility line is derived
+from that same report rather than rebuilt from target IDs or model names.
+
+### Review project resolution and corroboration
+
+`--project <path-or-name>` is a declaration. OAT normalizes the declared path
+and reports `projectResolutionSource: declared`. When the option is omitted,
+the compatibility resolver may use the configured active project
+(`active-project`) or the only project candidate (`single-candidate`); those
+ambient paths report `corroboration.project: ambient` rather than pretending a
+declaration was made.
+
+After dispatch, OAT searches direct, non-archived review files across project
+review directories for the unique `oat_gate_run_id`. An explicitly resolved
+project is included even when it is outside the configured shared projects
+root. For a declaration to corroborate, both the artifact's containing project
+and its parsed, normalized `oat_project` must equal the declaration. Sibling
+project writes, missing or wrong `oat_project`, missing or wrong run IDs,
+outside-repository artifact project values, and duplicate run-ID matches all
+fail closed before invocation-field remediation or severity evaluation.
 
 `oat gate review` parses the produced artifact and returns a blocking exit
 status when the configured threshold is met. `cross-provider-exec` does not do
@@ -101,24 +157,54 @@ once an artifact exists, its `generatedAt` (the artifact's seconds-precision
 `oat_generated_at`), so a caller can correlate the result to the exact artifact
 and disambiguate re-gate rounds:
 
-| `status`                     | Exit | Meaning                                                   |
-| ---------------------------- | ---- | --------------------------------------------------------- |
-| `ok`                         | 0    | Review completed; gate passed at the threshold.           |
-| `blocked`                    | 1    | Review completed; findings at/above the threshold.        |
-| `review_failed`              | ≠0   | The provider target exited non-zero; no verdict.          |
-| `artifact_validation_failed` | 1    | Provider ran but the review artifact could not be parsed. |
-
-`ok` and `blocked` also include `outcome`, `artifactPath`, `counts`, `scope`,
-and `handoff`. Treat any status other than `ok`/`blocked` as an operational
-failure, not a passing gate.
+| `status`                       | Exit | Meaning                                                      |
+| ------------------------------ | ---- | ------------------------------------------------------------ |
+| `ok`                           | 0    | Review completed; gate passed at the threshold.              |
+| `blocked`                      | 1    | Review completed; findings at/above the threshold.           |
+| `review_failed`                | ≠0   | The provider target exited non-zero; no verdict.             |
+| `artifact_validation_failed`   | 1    | Artifact format or configured invocation fields are invalid. |
+| `targeting_correlation_failed` | 1    | Identity did not correlate; do not run review-receive.       |
+
+Only `ok` and `blocked` are positive, receive-eligible review outcomes: both
+follow successful identity corroboration and carry a non-null `handoff`.
+`blocked` exits nonzero because of findings, while `ok` exits zero; callers must
+therefore route receive from the structured status and handoff rather than from
+the exit code. `review_failed` has no validated verdict and is not eligible.
+For `artifact_validation_failed`, correct the artifact and rerun the gate; do
+not invoke review-receive until the gate successfully revalidates it as `ok` or
+`blocked`.
+
+`ok` and `blocked` also include `receiveEligible: true`, `outcome`,
+`artifactPath`, `counts`, `scope`, `handoff`, `gateInvocation`, and
+`corroboration`. Invoke review-receive only when all three conditions hold:
+the status is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is
+non-null. `gateInvocation` contains the
+configured `runId`, `targetId`, `runtime`, `model`, `reasoningEffort`, and
+`source`. `corroboration.run` and `corroboration.invocation` are each
+`matched`, `missing`, or `mismatched`. `corroboration.project` is `matched` for
+an explicitly declared, corroborated project and `ambient` when the command
+relied on active-project or single-candidate compatibility. Expected and actual
+diagnostics include the declared project, containing project, artifact
+`oat_project`, normalized artifact project, matching run-ID paths, and configured
+invocation. Treat any status other than `ok`/`blocked` as an operational failure,
+not a passing gate.
+
+`targeting_correlation_failed` is non-remediable by review-fix retries. Its JSON
+sets `receiveEligible: false`, `remediable: false`, and `handoff: null`; do not
+run review-receive for that artifact even when `artifactPath` is present.
+Correct the stored project declaration or reviewer output routing and run a new
+gate instead. Invocation-only mismatch continues to use
+`artifact_validation_failed`; correct the exact configured invocation fields
+and rerun the gate for successful revalidation before receive.
 
 **Drive gates through `oat gate review`, not raw provider invocation.** An
 orchestrator that hand-rolls the review (for example, calling
 `codex exec … oat-project-review-provide <scope>` directly) and then watches
 `reviews/` for a file is reimplementing — less reliably — what the CLI already
-does: `oat gate review` snapshots the reviews directory, dispatches the
-provider, and attributes the produced artifact by content hash, so it is immune
-to a stale file lingering from a prior round. It works standalone, not only
+does: `oat gate review` dispatches the provider, locates direct active project
+review artifacts by the unique gate run ID, and uses before/after signatures
+only for compatibility diagnostics. Archived and ad-hoc reviews remain
+ineligible. It works standalone, not only
 inside the `oat-project-implement` auto-loop — a one-off final review is just:
 
 ```bash
@@ -127,7 +213,7 @@ oat --json gate review \
   --review-type code \
   --review-scope final \
   --exit-nonzero-on important \
-  'Use oat-project-review-provide code final to review the current project'
+  'Use oat-project-review-provide code final for the declared project'
 ```
 
 Read the resulting envelope and exit code; that is the whole completion
@@ -183,6 +269,10 @@ that candidate's model and is not double-pinned.
         "cursor-family-gate": {
           "runtime": "cursor",
           "baseCommand": ["cursor-agent", "-p", "--force"],
+          "invocation": {
+            "model": "composer-2.5",
+            "reasoningEffort": "provider-default"
+          },
           "models": ["composer-2.5", "gpt-5.5-xhigh", "claude-opus-4-8"],
           "availabilityCommand": [
             "sh",
@@ -221,6 +311,8 @@ for the same behavior.
 oat gate target set codex-5.5-xhigh \
   --runtime codex \
   --base-command-json '["codex","exec","--model","gpt-5.5","-c","model_reasoning_effort=\"xhigh\"","--dangerously-bypass-approvals-and-sandbox"]' \
+  --invocation-model gpt-5.5 \
+  --invocation-reasoning-effort xhigh \
   --availability-json '["codex","--version"]' \
   --priority 120 \
   --layer user
@@ -228,6 +320,8 @@ oat gate target set codex-5.5-xhigh \
 oat gate target set claude-opus-skip-permissions \
   --runtime claude \
   --base-command-json '["claude","-p","--model","opus","--dangerously-skip-permissions"]' \
+  --invocation-model opus \
+  --invocation-reasoning-effort provider-default \
   --availability-json '["claude","--version"]' \
   --priority 115 \
   --layer user
@@ -235,6 +329,8 @@ oat gate target set claude-opus-skip-permissions \
 oat gate target set cursor-force \
   --runtime cursor \
   --base-command-json '["cursor-agent","-p","--force"]' \
+  --invocation-model provider-default \
+  --invocation-reasoning-effort provider-default \
   --availability-json '["cursor-agent","--version"]' \
   --priority 90 \
   --layer user
@@ -252,7 +348,7 @@ Set or clear a skill gate:
 
 ```bash
 oat gate set oat-project-implement \
-  --command 'oat gate review --review-type code --review-scope final "Use oat-project-review-provide code final to review the current project"' \
+  --command 'oat gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
   --description "Run final review in another runtime" \
   --on-failure block \
   --max-attempts 2 \
@@ -261,31 +357,67 @@ oat gate set oat-project-implement \
 oat gate unset oat-project-implement --layer user
 ```
 
-Lifecycle gate commands should normally omit `--target <id>`. Leaving the
-target unset lets the dispatcher avoid the current runtime and choose the
+Lifecycle review gate commands must declare `--project "$PROJECT_PATH"` and
+omit `--target <id>`. The lifecycle skill exports `PROJECT_PATH` into the gate
+command shell, validates the resolved review command, and then executes it
+exactly as configured. It does not inject missing arguments. Leaving the target
+unset lets the dispatcher avoid the current runtime and choose the
 highest-priority available non-host target. Pin a target only for manual
 dispatch, debugging, or a deliberate local/user-specific override.
 
+### Migrate ambient lifecycle commands
+
+Older user-level lifecycle commands often asked a reviewer to inspect the
+"current project" but omitted a machine-readable declaration. Migrate each
+stored `oat gate review` command by inserting `--project "$PROJECT_PATH"` and
+retaining provider-neutral target selection. For example:
+
+```bash
+export PROJECT_PATH
+oat gate set oat-project-implement \
+  --command 'oat gate review --project "$PROJECT_PATH" --review-type code --review-scope final "Use oat-project-review-provide code final for the declared project"' \
+  --description "Run final review in another runtime" \
+  --on-failure block \
+  --max-attempts 2 \
+  --layer user
+```
+
+Apply the same command shape to `oat-project-plan`,
+`oat-project-quick-start`, and `oat-project-import-plan` when those lifecycle
+skills have configured review gates. Do not add `--target`; explicit targets
+remain manual/debug or deliberate local/user-specific overrides.
+
 Set or clear an exec target:
 
 ```bash
 oat gate target set codex-high \
   --runtime codex \
   --base-command-json '["codex","exec","--model","gpt-5.5"]' \
+  --invocation-model gpt-5.5 \
+  --invocation-reasoning-effort provider-default \
   --availability-json '["codex","--version"]' \
   --priority 90 \
   --layer user
 
 oat gate target unset codex-high --layer user
+
+oat --json gate target list
 ```
 
+`gate target list` is read-only. It reports each resolved target's origin,
+explicit configuration, enabled state, current availability, and normalized
+invocation values without selecting or executing a reviewer. Omitted invocation
+values are reported as `unknown`; `provider-default` is an explicit configured
+value, not an inference from the provider command.
+
 Dispatch a review through the target registry:
 
 ```bash
 oat gate review \
+  --project "$PROJECT_PATH" \
   --review-type code \
   --review-scope final \
-  "Use oat-project-review-provide code final to review the current project"
+  "Use oat-project-review-provide code final for the declared project"
 ```
 
 Leaving `--target` unset lets target priority choose the highest-priority
@@ -295,10 +427,10 @@ For manual or debug dispatch, use `--target <id>` to pin one target and skip
 detection/avoidance:
 
 ```bash
-oat gate review --target codex-5.5-xhigh \
+oat gate review --project "$PROJECT_PATH" --target codex-5.5-xhigh \
   --review-type code \
   --review-scope final \
-  "Use oat-project-review-provide code final to review the current project"
+  "Use oat-project-review-provide code final for the declared project"
 ```
 
 Dispatch a generic prompt through the target registry:
@@ -313,7 +445,9 @@ By default the dispatcher:
 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.
+   available. Exact phase/task scopes use the matching stamp. `final` and
+   contiguous ranges such as `p02-p03` aggregate every in-range implementer/fix
+   stamp.
 5. Applies `--avoid same-family`.
 6. Checks candidate availability in descending priority order, with target id as
    the tie-breaker.
@@ -338,15 +472,32 @@ producer when no project dispatch stamp exists:
 
 ```bash
 oat gate review \
+  --project "$PROJECT_PATH" \
   --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"
+  "Use oat-project-review-provide code final for the declared project"
 ```
 
 Gate JSON output includes `diversity` metadata with the requested avoid mode,
 producer identity/provenance/confidence, reviewer target/model/family, and the
-achieved level:
+achieved level. Claimable exact phase/task matches with a known family report
+producer source `stamp` without contributor fields; legacy or otherwise
+non-claimable exact matches remain fully `unknown`. An explicit flag reports
+`flag` and remains authoritative. Final and contiguous range scopes report
+`aggregated-stamps` whenever at least one relevant stamp exists, even for a
+single stamp or when no stamp has a claimable family. Their producer record uses
+an unknown representative instead of presenting the latest stamp as aggregate
+truth:
+
+- `avoidFamilies` is the stable deduplicated union of claimable known families.
+- `contributingScopes` is the stable document-order list of distinct scopes from
+  every relevant stamp.
+- `contributingStampCount` counts every relevant stamp, including unknown or
+  otherwise non-claimable identities.
+
+When no relevant aggregate stamp exists, producer source is `unknown` and the
+contributor fields are absent. The achieved level is one of:
 
 - `different-family`
 - `degraded-to-different-slug`

package/assets/docs/contributing/skills.md

@@ -88,18 +88,24 @@ The Gate Execution step should:
 
 1. Run `oat gate resolve <this-skill> --json`.
 2. Treat `null` as "no gate configured."
-3. Run the resolved `command` as the skill's last step when a gate is present.
-4. Use the command exit code as the pass/fail signal.
-5. Follow the gate's `onFailure` policy:
+3. Export the resolved path with `export PROJECT_PATH` before launching the
+   command shell.
+4. For `oat gate review`, require the configured command to include
+   `--project "$PROJECT_PATH"`; do not append it at runtime, because the resolved
+   command must execute exactly as configured.
+5. Run the resolved `command` as the skill's last step and use its exit code as
+   the pass/fail signal.
+6. Follow the gate's `onFailure` policy:
    - `block` - remediate and rerun up to `maxAttempts`, then escalate.
    - `prompt` - surface the failure and ask the user.
    - `warn` - record the failure and continue.
 
-For OAT review gates, prefer putting `oat gate review "<prompt>"` in the
-configured gate command rather than hard-coding a provider CLI directly in the
-skill. Use `oat gate cross-provider-exec "<prompt>"` for generic cross-runtime
-commands that should report only the child process status, not review findings.
-Reusable lifecycle gate commands should normally omit `--target <id>` so the
+For OAT review gates, prefer putting
+`oat gate review --project "$PROJECT_PATH" "<prompt>"` in the configured gate
+command rather than hard-coding a provider CLI directly in the skill. Use
+`oat gate cross-provider-exec "<prompt>"` for generic cross-runtime commands
+that should report only the child process status, not review findings.
+Reusable lifecycle gate commands must omit `--target <id>` so the
 dispatcher can avoid the current runtime; reserve explicit targets for
 manual/debug commands or deliberate local/user-specific overrides. See
 [Workflow Gates](../cli-utilities/workflow-gates.md) for the config and command

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

@@ -12,14 +12,20 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Project: `.agents/skills` -> `.claude/skills`, `.agents/agents` -> `.claude/agents`, `.agents/rules` -> `.claude/rules`
     - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
     - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
+    - Managed task workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Task `model`
 
 === "Cursor"
 
     - Project: `.agents/skills` -> `.cursor/skills`, `.agents/agents` -> `.cursor/agents`, `.agents/rules` -> `.cursor/rules`
     - User: `~/.agents/skills` -> `~/.cursor/skills`, `~/.agents/agents` -> `~/.cursor/agents`
     - Subagent invocation in Cursor is prompt-driven (`/name` or natural mention), not `subagent_type`
-    - OAT-controlled Cursor dispatch uses the generic `.cursor/agents/<name>.md` file plus the Task-level `model` argument selected from the dispatch matrix. A `model` frontmatter value is only a default/fallback mechanism.
-    - Cursor model validation checks whether the selected model is eligible for subagent Task dispatch; the broad `cursor-agent models` catalog alone is not enough proof.
+    - OAT-controlled Cursor dispatch uses the generic `.cursor/agents/<name>.md` file plus the exact `providers.cursor.dispatchArgs.model` value selected from the candidate ladder. OAT passes it byte-for-byte as the actual Task-level `model`; a `model` frontmatter value is only a default/fallback mechanism.
+    - Cursor model strings are opaque. OAT does not infer family, effort, cost, or capability from their spelling; the configured candidate position owns the named tier meaning.
+    - Cursor model validation checks whether the selected model is eligible for subagent Task dispatch. Each adopt/doctor command probes each distinct exact candidate once and shares one lazy broad-catalog lookup across that pass; the cache ends with the command.
+    - A correlated accepted Task carrying the exact model argument plus the child sentinel proves argument eligibility for that account/client. It does not prove backend runtime identity; that remains `not-reported` without trusted Cursor telemetry or support confirmation. Structured rejection can establish `unknown-value`, while parent prose and broad `cursor-agent models` catalog presence remain diagnostic-only.
+    - The [dated GPT-5.6 verification artifact](https://github.com/voxmedia/open-agent-toolkit/blob/main/.oat/repo/reference/project-summaries/20260711-cursor-gpt-5-6-subagent-verification.md) preserves the original probe and a stream-JSON control pass. The controls observed no Task events, so the stop rule ran zero recommendation or exploratory candidates and retained the recommendation unchanged.
+    - The artifact's structured second-pass block contains only allowlisted event fields, derived outcomes, sanitized auth presence, and identifier hashes. Exact request/session/tool-call IDs and credential-redacted unprojected streams from that pass remain in gitignored local project storage for support escalation.
+    - The same public artifact retains the sanitized historical v1 text-mode record for provenance. That older section includes command arguments and prompts, stdout and stderr, exit and duration data, and capture-environment details such as user-specific binary paths; it is not limited to the structured second-pass allowlist.
     - Rule files render as `.cursor/rules/*.mdc`
 
 === "Copilot"
@@ -43,20 +49,52 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
       - `.codex/agents/<role>.toml`
       - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
-    - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project`
-    - The Codex sync extension also generates materialized roles from explicit model+effort targets, such as `oat-phase-implementer-gpt-5-6-terra-xhigh` or `oat-reviewer-gpt-5-6-terra-xhigh`, alongside canonical-derived base roles. These generated variants are managed by `oat sync` and are not treated as strays (see Manifest and Drift -> Generated provider roles)
-    - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a one-off user-scope role.
+    - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
+    - Project sync writes and maintains the version-controlled supported catalogue: Luna and Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and `max`, for both `oat-phase-implementer` and `oat-reviewer` (26 pinned variants). Sync writes files; it does not create a Git commit.
+    - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.
+    - User sync loads only the bundled canonical `oat-phase-implementer` and `oat-reviewer` definitions needed to expand user-config targets. It does not enable general user-agent mirroring, and it refuses stale user-role cleanup if either managed definition is unavailable.
+    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership. Cleanup removes stale entries only for the owner being reconciled and preserves other scopes plus unrelated Codex entries.
+    - All project-generated Codex variants and config registrations are repository-owned, version-controlled output and are never auto-ignored by OAT. User-config output remains under `~/.codex`.
+    - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
     - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
-    - User-scope Codex role generation via provider sync (`~/.codex`) remains deferred
+    - Sync-time materialization is best effort; managed workflow correctness uses exact registered roles or a fresh child pinned to the resolved model plus reasoning effort with canonical role instructions, and does not require provider restart/hot reload
+    - Codex `max` is a first-class dispatch effort. It is present only for the Sol family in the committed supported catalogue, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
+    - `oat-phase-implementer` is dual-mode: Phase Scope makes it a phase coordinator, while Task Scope makes the exact materialized variant a one-task worker. The coordinator does not implement ordinary tasks itself.
+
+## Managed dispatch views
+
+Reusable ordered candidate ladders live in `workflow.dispatchCeiling.providers`.
+The project or phase named ceiling is only a maximum over those candidates; it
+does not select one permanent model family for the project.
+
+Adopt the complete ladder into an explicit owning config scope before sync:
+
+```bash
+oat config adopt dispatch-matrix --shared
+oat config adopt dispatch-matrix --local
+oat config adopt dispatch-matrix --user
+```
+
+Project-config candidates materialize into the tracked, version-controlled
+project `.codex` view. User-config candidates materialize under `~/.codex`.
+OAT does not auto-ignore project output or create its Git commit; the team owns
+that repository change.
+
+At implementation time, the phase coordinator passes the recorded named
+maximum through invocation-only `--ceiling-tier`, resolves one exact candidate
+per bounded task, and dispatches one task worker at a time. Codex uses the
+resolver-returned materialized role. Claude and Cursor bind the exact model
+arguments described above. A missing or unselectable managed target blocks
+rather than falling back to the coordinator or a base role.
 
 ## Scope rules
 
 - Project scope: skills + agents + rules
-- User scope: skills + agents (provider mappings vary by adapter)
+- User scope: skills, plus the two bundled managed Codex role definitions used only for user-owned target expansion (provider mappings vary by adapter)
 - Rules are project-scoped only in this release
-- Codex user-scope role generation under `~/.codex` via provider sync remains deferred in this release; direct one-off materialization can use `--scope user`
+- Codex user-scope sync materializes user-config custom roles under `~/.codex`; project-config and supported-catalogue output remains project-scoped and version controlled
 
 ## Adoption model
 

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

@@ -47,9 +47,9 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Project provider enablement is stored in `.oat/sync/config.json` (`providers.<name>.enabled`).
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
-- Codex project-scope subagent sync is generated output (`.codex/agents/*.toml` + `.codex/config.toml`) computed at command layer after path-mapping sync. Generated Codex roles - including materialized model+effort implementer and reviewer variants - are tracked as managed by `oat status` and `oat init`, not as strays.
+- Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
-- Codex user-scope role generation remains intentionally deferred in this release.
+- Codex user-config materialization writes user-owned implementer and reviewer roles under the user provider directory, `~/.codex`; it does not write those roles into the repository.
 
 ## Non-interop namespaces in the same CLI
 

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

@@ -68,7 +68,9 @@ Notable commands introduced in the current CLI surface:
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings; produced gate reviews use `oat_review_invocation: gate` and still require `oat-project-review-receive` handoff before they are dispositioned. With `--json`, the result envelope on exit is the canonical completion signal — `status` (`ok` | `blocked` | `review_failed` | `artifact_validation_failed`), `runId`, `generatedAt`, `artifactPath` — so orchestrators should read it rather than poll the filesystem. Runs standalone (e.g. `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
+- `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. For `artifact_validation_failed`, correct the artifact and rerun the gate for successful revalidation before receive. `targeting_correlation_failed` sets `receiveEligible: false`; do not run review-receive even if it reports an artifact path. Orchestrators should read the structured result rather than poll the filesystem. The command runs standalone (for example, `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
+- `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
+- `oat gate target list --json` - inspect resolved gate targets without selecting or executing a reviewer. Each entry reports its config origin, whether it is explicitly configured and enabled, current availability, and normalized configured invocation values (`unknown` when omitted).
 - `oat gate cross-provider-exec <prompt...>` - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command and exit with the child status.
 
 ## `oat config` surface flags

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

@@ -93,32 +93,33 @@ 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.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. `inherit` mode is separate and leaves controls to the host/provider.                            |
-| `workflow.dispatchCeiling.preset`           | `string`   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                    |
-| `workflow.dispatchCeiling.providers.codex`  | `string`   | unset                    | Legacy concrete Codex capped target (`low`, `medium`, `high`, or `xhigh`). New managed Codex dispatch resolves explicit model+effort targets to materialized role names; provider default effort is informational only for explicit inherit/default behavior or base/unpinned fallback paths.           |
-| `workflow.dispatchCeiling.providers.claude` | `string`   | unset                    | Legacy concrete Claude capped target (`haiku`, `sonnet`, `opus`, or `fable`). Claude has no separate per-dispatch effort axis. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed (no migration).                                                        |
-| `workflow.gates.skills`                     | `object`   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                     |
-| `workflow.gates.execTargets`                | `object`   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                             |
-| `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. `inherit` mode is separate and leaves controls to the host/provider.                            |
+| `workflow.dispatchCeiling.preset`                          | `string`                   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                    |
+| `workflow.dispatchCeiling.providers.<provider>`            | `object` or legacy scalar  | unset                    | Reusable provider candidate ladder. The canonical shape maps `economy`, `balanced`, `high`, and `frontier` to ordered candidate cells; project and phase state record only a named maximum over that ladder.                                                                                            |
+| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex entries carry exact `model` plus `effort` and resolve to materialized roles; Claude entries carry a model; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                   |
+| `workflow.dispatchCeiling.providers.{codex,claude,cursor}` | `string`, route, or target | unset                    | Legacy compatibility input normalized to a one-candidate ladder. New configuration should use tiered candidate cells. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed without migration.                                                              |
+| `workflow.gates.skills`                                    | `object`                   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                     |
+| `workflow.gates.execTargets`                               | `object`                   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                             |
+| `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>`.