@open-agent-toolkit/cli 0.1.50 → 0.1.51

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

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.4
+version: 1.0.5
 description: Acts as a phase coordinator that dispatches one exact target-pinned task worker at a time, or executes exactly one bounded Task Scope when dispatched as a worker. Used by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -148,10 +148,12 @@ downgrade for a managed task.
 
 #### 4. Build the Exact Invocation Before Logging
 
-- Codex: use `providers.codex.dispatchArgs.variant` as the actual `agent_type`.
-  If the native host cannot select that registered role, launch a fresh Codex
-  child pinned to `selection.target.model` and `selection.target.effort` with
-  these canonical instructions and the Task Scope. If neither exact route is
+- Codex: use `providers.codex.dispatchArgs.variant` as the actual `agent_type`
+  and attempt the exact materialized `agent_type` first. Only explicit
+  pre-start native role-selection rejection of that exact `agent_type`, before
+  any child starts, permits a fresh pinned fallback: launch a fresh Codex child
+  pinned to `selection.target.model` and `selection.target.effort` with these
+  canonical instructions and the Task Scope. If neither exact route is
   available, block.
 - Claude: pass `providers.claude.dispatchArgs.model` as the actual Task `model`.
 - Cursor: pass `providers.cursor.dispatchArgs.model` byte-for-byte as the actual
@@ -163,6 +165,15 @@ transient retry must reuse the same exact role/model/effort payload. A
 substantive escalation must re-resolve another configured candidate without
 exceeding the same named maximum.
 
+The launcher-owned `target`, `model_axis`, and `effort_axis` come only from the
+resolver output and constructed invocation payload. They are immutable and
+must not be populated, replaced, or contradicted by worker self-report. Spawn
+acceptance confirms that configured invocation; worker output is only task
+outcome data. Missing telemetry, missing self-report, and accepted terminal
+results including `BLOCKED` never trigger fallback. Once a child starts, every
+terminal result is authoritative for that attempt and is not native
+role-selection rejection.
+
 #### 5. Dispatch and Verify Serially
 
 Run one exact task worker at a time, serially in the same worktree:

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

@@ -518,7 +518,7 @@ 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
+Gate target execution has a child-process timeout (default 15 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

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

@@ -21,7 +21,7 @@ These command definitions inherit the cross-cutting CLI conventions in:
 
 - What it does: defines the day-to-day provider-sync command surface for inspecting state, reconciling provider views, and changing provider enablement.
 - When to use it: after you have canonical assets in place and need to check sync state, write provider views, or change provider config.
-- Primary commands: `oat status`, `oat sync`, `oat providers list`, `oat providers inspect`, `oat providers set`
+- Primary commands: `oat status`, `oat sync`, `oat providers list`, `oat providers inspect`, `oat providers set`, `oat providers codex materialize`
 
 ## `oat status`
 
@@ -71,6 +71,34 @@ Key behavior:
 - Options: `--enabled <providers>`, `--disabled <providers>` (comma-separated)
 - Changes take effect on next `oat sync`
 
+## `oat providers codex materialize`
+
+Purpose:
+
+- Materialize one canonical Markdown agent as a Codex TOML role and register it
+  in Codex configuration
+
+Required operands:
+
+```bash
+oat providers codex materialize <agent-name> \
+  --model <model-id> \
+  --effort <reasoning-effort>
+```
+
+Key behavior:
+
+- Project scope is the default and writes only `.codex/config.toml` plus the
+  project role file; `--scope user` writes only under `~/.codex`
+- `--agent-path` selects a specific canonical agent and `--role-name` overrides
+  the generated role name
+- Managed role registration enables multi-agent support and merges an
+  `agents.max_depth` floor of `2`
+- Project writes preserve a higher existing project depth or inherited user
+  depth without mutating user configuration; user writes do not inspect or
+  mutate project configuration
+- Existing unrelated Codex configuration and custom roles are preserved
+
 ## Notes
 
 - `oat init --scope project` is commonly used before provider-interop commands because it initializes `.oat/sync/config.json`.

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

@@ -61,6 +61,9 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - 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
+    - Managed Codex roles require `agents.max_depth >= 2` for the native topology: root (depth 0) → phase coordinator (depth 1) → task worker (depth 2). Sync and direct materialization merge that floor without lowering a higher target value; project writes also preserve a higher inherited user value.
+    - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
+    - When managed roles exist and effective depth is missing, invalid, or below `2`, `oat doctor` and managed implementation preflight explain the topology and recommend `oat sync --scope project` or `oat sync --scope user` for the affected scope. Direct materialization with the same scope is the single-role repair path.
     - `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
@@ -84,10 +87,16 @@ 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.
+per bounded task, and dispatches one task worker at a time. Codex first
+attempts the resolver-returned materialized role as the native `agent_type`.
+The launcher records the target, model axis, and effort axis from that resolved
+payload; worker self-report is not provenance and cannot replace those values.
+Only an explicit pre-start native role-selection rejection permits a fresh
+pinned-child fallback. An accepted child, including one that later returns
+`BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
+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
 

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

@@ -48,9 +48,22 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `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 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.
+- Managed Codex roles require an effective `agents.max_depth` of at least `2` for `root (0) → phase coordinator (1) → task worker (2)`. Sync and direct materialization apply that floor without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in the project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
+- If a managed role has missing, invalid, or insufficient effective depth, `oat doctor` and managed implementation preflight report the topology and give a scope-specific repair: `oat sync --scope project` for project scope or `oat sync --scope user` for user scope. For a single role, use `oat providers codex materialize` with the same explicit scope.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - 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.
 
+## Codex managed dispatch
+
+For managed Codex work, the resolver-returned materialized role is attempted as
+the native `agent_type` first. The launcher owns the resulting target, model,
+and reasoning-effort provenance, derived from the resolved candidate and
+compiled invocation payload; worker output cannot populate or overwrite it.
+A fresh pinned child is allowed only after explicit pre-start native
+role-selection rejection. Missing runtime telemetry, missing self-report, or a
+child accepted by the native route that later returns `BLOCKED` are not
+role-selection rejection and do not permit fallback.
+
 ## Non-interop namespaces in the same CLI
 
 - `oat project new <name>` (workflow/project scaffolding)

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

@@ -113,6 +113,19 @@ An unresolved non-interactive preflight blocks. Managed `Uncapped` and
 `Inherit Host Defaults` are explicit modes; omitted policy state is not an
 implicit fallback.
 
+For a managed Codex implementer, preflight also resolves the effective
+`agents.max_depth`. Native `root (0) → phase coordinator (1) → task worker (2)`
+execution requires a depth of at least `2`. Missing, invalid, or lower values
+block before dispatch and identify the owning scope:
+
+- Project scope: run `oat sync --scope project`
+- User scope: run `oat sync --scope user`
+- Single-role repair: rerun `oat providers codex materialize` with the required
+  agent name, model, effort, and matching scope
+
+Project preflight may inherit a valid higher user depth, but remediation never
+writes across the project/user boundary.
+
 ## Resolve the Effective Named Maximum
 
 For each phase, the orchestrator determines the task maximum:
@@ -202,9 +215,14 @@ candidate above the maximum or absent from the configured ladder blocks.
 Build the complete host payload before writing dispatch logs:
 
 - **Codex:** use `providers.codex.dispatchArgs.variant` as the actual
-  `agent_type`. If the registered role cannot be selected, launch a fresh Codex
-  child pinned to `selection.target.model` and `selection.target.effort` with
-  canonical `oat-phase-implementer` instructions and the Task Scope.
+  `agent_type`. An accepted launch with that exact materialized role is
+  authoritative evidence of the configured invocation for coordinators and
+  task workers. A fresh Codex child pinned to `selection.target.model` and
+  `selection.target.effort` is permitted only after an actual native
+  role-selection rejection; missing self-reporting or model/effort telemetry
+  does not justify the fallback. An accepted child, including one that later
+  returns `BLOCKED`, is a task outcome and never triggers another pinned-child
+  fallback.
 - **Claude:** pass `providers.claude.dispatchArgs.model` as the actual Task
   `model`. Its separate effort axis is `not-applicable`.
 - **Cursor:** pass `providers.cursor.dispatchArgs.model` byte-for-byte as the
@@ -238,6 +256,14 @@ Configured defaults and configured gate invocation remain distinct from runtime
 identity; when runtime identity is not observed, the report says so without
 weakening exact requested model or effort controls.
 
+After constructing the complete payload, the launcher records the selected
+target and requested model/effort controls in the report. Those configured
+invocation fields are launcher-owned and derive from resolver output plus the
+actual payload; worker output cannot populate or overwrite them. Optional
+coordinator or worker self-report remains non-authoritative runtime evidence.
+Runtime attestation, when available, is separate host-generated metadata rather
+than an agent claim.
+
 ## Task Scope and Commit Verification
 
 Each worker receives only one task:

package/assets/docs/workflows/projects/reviews.md

@@ -207,7 +207,24 @@ Final review `passed` gate requires:
   - Project-scope Codex role files are generated from canonical `.agents/agents/*.md` during `oat sync --scope project`.
   - User-config Codex roles materialize under `~/.codex`; project-config and supported-catalogue roles remain in the project-scoped, version-controlled `.codex` view.
   - Some Codex hosts require explicit user authorization before the skill may call `spawn_agent`. In those hosts, `oat-project-review-provide` should ask whether to delegate to `oat-reviewer` instead of reporting the reviewer as unresolved.
-- If subagent dispatch is unavailable, follow the existing fallback path (fresh session preferred, inline reset as fallback).
+  - An accepted launch using the exact materialized `agent_type` is authoritative
+    configured-invocation evidence for a reviewer. After the complete payload
+    is built, the launcher records its `target`, `model_axis`, and
+    `effort_axis`; reviewer self-report cannot supply or overwrite those
+    fields. Optional self-report is non-authoritative, while runtime
+    attestation is host-generated metadata.
+  - A fresh pinned CLI child is a fallback only for an actual native
+    role-selection rejection, never for absent self-reporting or model/effort
+    telemetry. A child accepted by the native host, including one that later
+    returns `BLOCKED`, has produced a review outcome and cannot trigger the
+    fallback.
+  - An accepted reviewer that returns `BLOCKED` blocks the relevant review. It
+    cannot trigger the pinned fallback, and absent findings in that blocked
+    outcome cannot be interpreted as a pass.
+- For unmanaged review dispatch, if subagent dispatch is unavailable, follow
+  the existing fallback path (fresh session preferred, inline reset as
+  fallback). This generic fallback does not override managed exact-target
+  rules: a managed reviewer that cannot be launched exactly blocks the review.
 
 ## Reference artifacts
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.50",
-  "docs-config": "0.1.50",
-  "docs-theme": "0.1.50",
-  "docs-transforms": "0.1.50"
+  "cli": "0.1.51",
+  "docs-config": "0.1.51",
+  "docs-theme": "0.1.51",
+  "docs-transforms": "0.1.51"
 }

package/assets/skills/oat-agent-instructions-analyze/references/docs/provider-reference.md

@@ -220,6 +220,8 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 - Enable feature flag in config:
   - `[features]`
   - `multi_agent = true`
+- For OAT's nested root → coordinator → worker topology, configure
+  `[agents] max_depth = 2` or higher.
 - Define role(s) in config:
   - `[agents.oat-reviewer]` (or role names your workflow dispatches)
 - Dispatch by role name using `agent_type` (not `subagent_type`).
@@ -228,8 +230,12 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 **Note on OAT provider sync:**
 
 - Codex runtime dispatch is config-role based (`[agents.<name>]`) and TOML-backed.
-- OAT currently does not sync canonical markdown agents into `.codex/agents`.
-- Canonical markdown agent definitions require a markdown→TOML adapter to become Codex-executable role configs.
+- OAT sync exports canonical Markdown agents as `.codex/agents/*.toml` role
+  configs and registers them in `.codex/config.toml`.
+- Project-scoped output is repository-owned and version controlled. Explicit
+  user-scope materialization writes under `~/.codex` instead.
+- Sync and direct materialization merge an `agents.max_depth` floor of `2`
+  without lowering a higher project or inherited user value.
 
 ### Other Codex Resources
 

package/assets/skills/oat-agent-instructions-apply/references/docs/provider-reference.md

@@ -220,6 +220,8 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 - Enable feature flag in config:
   - `[features]`
   - `multi_agent = true`
+- For OAT's nested root → coordinator → worker topology, configure
+  `[agents] max_depth = 2` or higher.
 - Define role(s) in config:
   - `[agents.oat-reviewer]` (or role names your workflow dispatches)
 - Dispatch by role name using `agent_type` (not `subagent_type`).
@@ -228,8 +230,12 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
 **Note on OAT provider sync:**
 
 - Codex runtime dispatch is config-role based (`[agents.<name>]`) and TOML-backed.
-- OAT currently does not sync canonical markdown agents into `.codex/agents`.
-- Canonical markdown agent definitions require a markdown→TOML adapter to become Codex-executable role configs.
+- OAT sync exports canonical Markdown agents as `.codex/agents/*.toml` role
+  configs and registers them in `.codex/config.toml`.
+- Project-scoped output is repository-owned and version controlled. Explicit
+  user-scope materialization writes under `~/.codex` instead.
+- Sync and direct materialization merge an `agents.max_depth` floor of `2`
+  without lowering a higher project or inherited user value.
 
 ### Other Codex Resources
 

package/assets/skills/oat-project-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.34
+version: 2.0.35
 description: Use when plan.md is ready for execution. Dispatches phase coordinators that select one exact target-pinned worker per task; supports bounded fix loops and plan-declared worktree-isolated parallel phases.
 oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'
@@ -107,16 +107,21 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 **Mandatory target-first order:** Complete Dispatch Policy Preflight and resolve
 the concrete managed Codex target before probing generic agent availability or
 locking Tier 1/Tier 2. A concrete target takes precedence over tier selection:
-use the exact registered role, or an explicitly pinned fresh Codex child when
-that role is unavailable. If neither route is possible, inline execution is
-allowed only with verified equivalent current-host model and effort controls;
-otherwise block before work starts. Explicit inherit/default and documented
-managed-uncapped reviewer behavior remain the only base-role exceptions.
-
-When a concrete managed Codex role is unavailable or the host cannot select
-it, launch a fresh Codex child pinned to the resolver-returned model and effort
-with canonical role instructions. If that fresh child cannot be launched, fail
-closed and block; never substitute the coordinator or base role.
+first send the exact registered role through native dispatch. Only a native
+role-selection rejection permits an explicitly pinned fresh Codex child. If
+neither exact route is possible, inline execution is allowed only with verified
+equivalent current-host model and effort controls; otherwise block before work
+starts. Explicit inherit/default and documented managed-uncapped reviewer
+behavior remain the only base-role exceptions.
+
+For a concrete managed Codex role, first send the resolver-returned Codex
+variant through the native spawn API as `agent_type`. Spawn acceptance plus the
+constructed launcher payload is configured invocation evidence; independent
+runtime telemetry or agent self-report is not required. Launch a fresh Codex
+child pinned to the resolver-returned model and effort with canonical role
+instructions only after a native role-selection rejection as defined below. If
+that fresh child cannot be launched, fail closed and block; never substitute
+the coordinator or base role.
 
 Use base `oat-phase-implementer` only for the allowed exceptions above:
 explicit inherit/default behavior. It is never a managed task-worker fallback.
@@ -142,9 +147,9 @@ Detection logic:
     - Declined → Tier 2.
 
 - If the host does not resolve either generic agent, first attempt the exact
-  registered role or explicitly pinned fresh-child route for any concrete
-  managed target. Select Tier 2 only when inline execution is allowed by the
-  target-first rule above.
+  registered role natively for any concrete managed target. Use the explicitly
+  pinned fresh-child route only after a native role-selection rejection. Select
+  Tier 2 only when inline execution is allowed by the target-first rule above.
 
 **Approval scope rule:** this Tier selection applies to both phase implementation and checkpoint review. Do not infer a mixed mode from conversational emphasis on review checkpoints. If the user has not explicitly approved Tier 1 for the run, stay Tier 2 throughout. Mixed mode is only valid when the user explicitly requests it.
 
@@ -181,6 +186,20 @@ If approved: Selected: Tier 1 — Subagents
 Forbidden: Selected: Tier 2 — Inline because the user did not separately mention subagents.
 ```
 
+**Native role-selection rejection:** This means the native host explicitly
+reports that the requested `agent_type` is unsupported, unknown, unregistered,
+or rejected before the child or agent starts. Missing runtime telemetry,
+missing agent self-report, a timeout after spawn acceptance, or any terminal
+result from an accepted child — including `BLOCKED` — is not role
+unavailability and is not a native role-selection rejection. Self-report is
+optional diagnostic data and cannot populate or overwrite launcher-owned
+`target`, `model_axis`, or `effort_axis` fields. An accepted child cannot
+trigger the fresh pinned-child or CLI fallback. If an accepted native reviewer
+later times out, retry the same already-selected native `agent_type` route. The
+fresh pinned-child route is eligible only when the original native attempt
+received explicit pre-start role-selection rejection; a timeout after native
+spawn acceptance never changes routes.
+
 **Legacy state migration:** If `state.md` contains `oat_execution_mode: subagent-driven`, silently ignore it. On the next bookkeeping write, remove that key. Do not redirect to `oat-project-subagent-implement` — that skill is deprecated.
 
 ### Dispatch Policy Preflight
@@ -427,14 +446,19 @@ Axis states:
 Codex rules:
 
 **Managed Codex execution invariant:** When the resolver returns a model+effort
-target, prefer the exact registered role or variant from
-`providers.codex.dispatchArgs.variant`. If the current host cannot select that
-exact registered target, launch a fresh Codex child with the resolver target's
-explicit model, reasoning effort, and canonical role instructions from
+target, the resolver-returned Codex variant from
+`providers.codex.dispatchArgs.variant` must first be sent through the native
+spawn API as `agent_type`. Spawn acceptance plus the launcher payload is
+configured invocation evidence with launcher-selected/config-declared
+provenance. If and only if the host returns a native role-selection rejection,
+launch a fresh Codex child with the resolver target's explicit model, reasoning
+effort, and canonical role instructions from
 `.agents/agents/oat-phase-implementer.md` or
-`.agents/agents/oat-reviewer.md`. Workflow correctness must not require provider
-restart or hot reload. A managed base role is forbidden when a concrete target
-was requested; never silently downgrade to it. Base roles remain valid only for
+`.agents/agents/oat-reviewer.md`. Missing runtime telemetry or agent self-report
+is not role unavailability, and an accepted child result such as `BLOCKED`
+cannot trigger fallback. Workflow correctness must not require provider restart
+or hot reload. A managed base role is forbidden when a concrete target was
+requested; never silently downgrade to it. Base roles remain valid only for
 explicit inherit/default behavior and the documented managed-uncapped reviewer
 fallback.
 
@@ -453,7 +477,7 @@ fallback.
    - Capped managed policy: reviewer targets the configured cap for deterministic quality gate behavior.
    - Managed `Uncapped`: no reviewer target exists; use base/unpinned reviewer fallback and log `selectionMode=no-review-target`, `selectedValue=null`, and `effort_axis=provider-default`.
    - Inherit/default: no reviewer target exists; use base/unpinned reviewer fallback and log `selectionMode=inherit-default`, `selectedValue=null`, and `effort_axis=provider-default`.
-8. Codex payload-first assertion applies whenever the resolver returns a materialized model+effort target. If `providers.codex.dispatchArgs.variant` is present, the actual `spawn_agent` payload MUST use it as `agent_type`; when that variant came from a Codex model+effort target, log `model_axis=selected:<model>` and `effort_axis=selected:<effort>` from resolver output. If a concrete managed target has no usable variant, use the explicitly pinned fresh-child route or block. Use the base role and log provider-default only for explicit inherit/default behavior or the documented managed-uncapped reviewer exception. Always derive `model_axis` and `effort_axis` from resolver output, not from legacy role-name parsing.
+8. Codex payload-first assertion applies whenever the resolver returns a materialized model+effort target. If `providers.codex.dispatchArgs.variant` is present, the actual `spawn_agent` payload MUST first use it as native `agent_type`; when that variant came from a Codex model+effort target, log `model_axis=selected:<model>` and `effort_axis=selected:<effort>` from resolver output and the constructed launcher payload. Spawn acceptance is sufficient configured invocation evidence. Missing telemetry or self-report does not make the variant unusable. If native role selection explicitly rejects the variant, use the explicitly pinned fresh-child route or block. Use the base role and log provider-default only for explicit inherit/default behavior or the documented managed-uncapped reviewer exception. Always derive `model_axis` and `effort_axis` from resolver output, not from legacy role-name parsing or agent self-report.
 9. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent.
 
 Claude rules:
@@ -486,6 +510,11 @@ Payload-first invariant:
 
 - Build the actual host dispatch argument map before logging.
 - Do not emit `selected:<value>` unless the host invocation contains the corresponding role/model selection.
+- For every coordinator, task-worker, fix, and review launch, record `target`,
+  `model_axis`, and `effort_axis` from resolver output and the actual launcher
+  payload after payload construction.
+- Those fields are launcher-owned. Agent self-report cannot populate or
+  overwrite them; it may only be retained separately as optional diagnostics.
 - Derive `Dispatch target` and `Effort axis` / `Model axis` from the payload.
 - After the payload is built, append the compatibility stamp returned from
   `formatDispatchStamp(dispatchReport)` to Dispatch Notes for every
@@ -1068,10 +1097,15 @@ coordinator_target: {resolver-selected coordinator target}
 
 Tier 1 uses the already resolved exact coordinator role/model payload and sends
 the Phase Scope. A concrete Codex coordinator uses
-`providers.codex.dispatchArgs.variant`; when the registered role cannot be
-selected, use the fresh child pinned to the resolver's model and effort with
-canonical coordinator instructions. Claude and Cursor coordinator calls pass
-their exact resolver model argument.
+`providers.codex.dispatchArgs.variant` first as native `agent_type`. After the
+host accepts the spawn, record the coordinator `target`, `model_axis`, and
+`effort_axis` from resolver output and that constructed launcher payload; do not
+wait for or accept a coordinator self-report as proof. Only an actual native
+role-selection rejection permits the fresh child pinned to the resolver's model
+and effort with canonical coordinator instructions. An accepted coordinator
+that later returns `BLOCKED` has produced a coordinator outcome and cannot
+trigger fallback. Claude and Cursor coordinator calls pass their exact resolver
+model argument.
 
 Tier 2 may run the coordinator instructions in the current context only when
 that context can still dispatch every exact task worker. Tier 2 never permits
@@ -1104,14 +1138,19 @@ For each task in dependency order, the coordinator must:
    is read-only and must never persist its override.
 
 3. Build the actual provider invocation before logging:
-   - Codex uses `providers.codex.dispatchArgs.variant` as `agent_type`, or the
-     exact fresh pinned-child model/effort route when native role selection is
-     unavailable.
+   - Codex first uses `providers.codex.dispatchArgs.variant` as native
+     `agent_type`. Spawn acceptance establishes the configured invocation; only
+     a native role-selection rejection permits the exact fresh pinned-child
+     model/effort route.
    - Claude passes `providers.claude.dispatchArgs.model` as the actual Task
      `model`.
    - Cursor passes `providers.cursor.dispatchArgs.model` byte-for-byte as the
      actual invocation model. Treat the string as opaque and never normalize or
      infer capability from it.
+   - After construction, record the task-worker `target`, `model_axis`, and
+     `effort_axis` from resolver output and the launcher payload. Missing worker
+     telemetry or self-report is not unavailability, and self-report cannot
+     replace those launcher-owned values.
 4. Send one bounded Task Scope, never the full phase task list:
 
    ```yaml
@@ -1162,8 +1201,8 @@ After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness co
 **Dispatch:**
 
 - Use the same tier that was selected at start.
-- For Codex with a capped managed policy, dispatch the materialized reviewer role returned in `providers.codex.dispatchArgs.variant` for deterministic quality gates.
-- If that exact registered reviewer role is not selectable in the current host session, launch a fresh Codex child with explicit model, reasoning effort, and canonical role instructions from `.agents/agents/oat-reviewer.md`; never substitute the managed base role and never require restart/hot reload.
+- For Codex with a capped managed policy, first dispatch the materialized reviewer role returned in `providers.codex.dispatchArgs.variant` as native `agent_type` for deterministic quality gates. After spawn acceptance, record the review `target`, `model_axis`, and `effort_axis` from resolver output and the constructed launcher payload; reviewer self-report cannot populate or overwrite them.
+- Only if the exact registered reviewer role receives a native role-selection rejection may the launcher start a fresh Codex child with explicit model, reasoning effort, and canonical role instructions from `.agents/agents/oat-reviewer.md`; never substitute the managed base role and never require restart/hot reload. Missing reviewer telemetry or self-report is not a rejection, and an accepted reviewer that later returns `BLOCKED` cannot trigger fallback.
 - For Codex with managed `Uncapped` or inherit/default mode, no reviewer target exists; use base `oat-reviewer`, log `effort_axis=provider-default`, and explain that the base role follows the provider default.
 - For Claude Code with a capped managed policy, require `providers.claude.dispatchArgs.model` and pass that exact value as the review `model`; managed `Uncapped` or inherit/default mode omits `model` because no reviewer target exists. Always keep `effort_axis=not-applicable`.
 - For Cursor with a concrete managed reviewer target, require `providers.cursor.dispatchArgs.model` and pass that exact opaque, unnormalized string as the actual review invocation's `model` argument.
@@ -1192,7 +1231,7 @@ After the implementer returns DONE (or DONE_WITH_CONCERNS without correctness co
   - For Codex Tier 1 dispatches, send the Review Scope block as a self-contained packet and keep fresh context (`fork_context: false`). The reviewer is expected to reconstruct context from git state and the OAT artifacts listed above.
   - For Codex Tier 1 review dispatches, use the materialized Codex role name from `providers.codex.dispatchArgs.variant` only when the resolver returns a reviewer variant for a capped managed policy. A Codex materialized reviewer role selected from a model+effort target must carry `model_axis=selected:<model>` and `effort_axis=selected:<effort>` from resolver output. Use base `oat-reviewer` only when the resolver returns no `dispatchArgs.variant` for managed `Uncapped`, inherit/default mode, or provider-default fallback, and log `effort_axis=provider-default`. For Claude Code, pass `model: providers.claude.dispatchArgs.model` for a concrete managed reviewer and never pass a per-review effort override. For Cursor, pass `model: providers.cursor.dispatchArgs.model` byte-for-byte for a concrete managed reviewer.
   - Treat the commit range as authoritative for review scope. `files_changed` is optional orientation metadata only.
-  - If a reviewer does not return a terminal result on the first wait, poll once more. If it still has not concluded, send one concise nudge to return immediately with current findings. If the reviewer still does not conclude, treat the target-preserving review dispatch as failed for this phase. Retry the same exact role, pinned fresh-child route, or complete Claude/Cursor invocation payload within the retry bound, preserving the exact model argument; never downgrade a timed-out managed reviewer to unpinned inline execution.
+  - If a reviewer does not return a terminal result on the first wait, poll once more. If it still has not concluded, send one concise nudge to return immediately with current findings. If the reviewer still does not conclude, treat the target-preserving review dispatch as failed for this phase. When the original native reviewer spawn was accepted, retry the same already-selected native `agent_type` route within the retry bound; do not switch that timed-out reviewer to a fresh pinned child. The fresh pinned-child route is eligible only when the original native attempt received explicit pre-start role-selection rejection. Retry an already-selected pinned fresh-child route or complete Claude/Cursor invocation payload without changing routes, preserving the exact model argument; never downgrade a timed-out managed reviewer to unpinned inline execution.
 
 - Tier 2: read `.agents/agents/oat-reviewer.md` and review inline only with verified equivalent current-host model and effort controls, explicit inherit/default behavior, or the documented managed-uncapped reviewer behavior. Otherwise block.
 
@@ -1202,6 +1241,9 @@ Parse the reviewer's confirmation for verdict + finding severities. Map to pass
 
 - **pass:** zero Critical and zero Important findings.
 - **fail:** one or more Critical or Important findings.
+- **blocked:** An accepted reviewer `BLOCKED` terminal blocks this phase review.
+  It does not invoke fallback and must not be interpreted as a pass due to
+  absent findings. Stop and surface the review target and blocker reason.
 
 Medium / Minor findings do not block the phase but are recorded.
 
@@ -1212,7 +1254,7 @@ On reviewer verdict `fail`, run a bounded fix loop.
 1. Read `oat_orchestration_retry_limit` from `state.md` frontmatter (default: `2`, range 0–5).
 2. For each retry (up to the limit):
    a. Convert Critical/Important findings into bounded fix scopes associated with one planned task/file boundary at a time. Do not hand one worker the full phase finding list.
-   b. Reuse the phase coordinator in `fix` mode. It selects an exact candidate under the same project or phase named ceiling with `--ceiling-tier`, then emits one Task Scope per bounded fix. Codex uses `providers.codex.dispatchArgs.variant`; Claude and Cursor pass their exact `providers.<provider>.dispatchArgs.model` value on the actual invocation. Every fix worker writes the formal `Dispatch: scope=<phase-or-task> action=fix role=fix producer=<slug|unknown> provenance=<declared|observed|inferred|unknown> model_axis=<axis> effort_axis=<axis> dispatch_policy=<policy|unknown> dispatch_ceiling=<value|none> target=<target|unknown>` stamp before execution.
+   b. Reuse the phase coordinator in `fix` mode. It selects an exact candidate under the same project or phase named ceiling with `--ceiling-tier`, then emits one Task Scope per bounded fix. Codex first uses `providers.codex.dispatchArgs.variant` as native `agent_type`; only a native role-selection rejection permits the exact fresh-child fallback. Claude and Cursor pass their exact `providers.<provider>.dispatchArgs.model` value on the actual invocation. After constructing the launcher payload, record the fix `target`, `model_axis`, and `effort_axis` from that payload and resolver output. Missing fix-worker telemetry or self-report is not unavailability, and an accepted fix worker — including one that returns `BLOCKED` — cannot trigger fallback. Every fix worker writes the formal `Dispatch: scope=<phase-or-task> action=fix role=fix producer=<slug|unknown> provenance=<declared|observed|inferred|unknown> model_axis=<axis> effort_axis=<axis> dispatch_policy=<policy|unknown> dispatch_ceiling=<value|none> target=<target|unknown>` stamp before execution.
    c. Receive and verify each fix result and commit. The coordinator must not apply fixes itself, and Tier 2 does not authorize inline task edits.
    d. Re-dispatch the reviewer with the updated commit range.
    e. Parse the new verdict.
@@ -1655,6 +1697,10 @@ All must pass before proceeding.
 
 **At the final plan phase boundary, a code review is required before PR.**
 
+An accepted reviewer `BLOCKED` terminal blocks final review. It does not invoke
+fallback and must not be interpreted as a pass due to absent findings. Stop and
+surface the review target and blocker reason.
+
 Before requesting final review, ensure the latest project-artifact bookkeeping is already committed. Review should evaluate the implementation state as it actually stands on the branch, not a half-tracked working tree.
 
 Check if final review already completed (preferred source of truth: plan.md Reviews table):
@@ -1681,13 +1727,22 @@ echo "$FINAL_ROW"
 **Workflow preference check (before prompting):**
 
 First resolve the final reviewer target with the same target-first contract as
-per-phase review. A concrete managed Codex target must use its exact registered
-reviewer or an explicitly pinned fresh child. A concrete managed Claude or
-Cursor target must put `providers.claude.dispatchArgs.model` or
+per-phase review. A concrete managed Codex target must first send its exact
+registered reviewer as native `agent_type`; only a native role-selection
+rejection permits an explicitly pinned fresh child. Spawn acceptance plus the
+launcher payload supplies configured invocation evidence, so missing telemetry,
+missing self-report, or a later `BLOCKED` result cannot trigger fallback. Record
+the final review `target`, `model_axis`, and `effort_axis` from resolver output
+and the constructed launcher payload, never from reviewer self-report. A
+concrete managed Claude or Cursor target must put
+`providers.claude.dispatchArgs.model` or
 `providers.cursor.dispatchArgs.model` respectively into the actual provider
 invocation as the exact `model` argument; Cursor strings remain opaque. On
-timeout or retry, preserve the same exact role or complete invocation payload,
-including the model argument. If the host cannot apply the required role or
+timeout or retry, preserve the already-selected route as well as its complete
+invocation payload: an accepted native reviewer retries the same native
+`agent_type`, while a fresh pinned-child route is eligible only when the
+original native attempt received explicit pre-start role-selection rejection.
+Preserve the exact model argument. If the host cannot apply the required role or
 model argument, fail closed or block unless verified equivalent current-host
 controls permit inline execution. The preference below chooses only among
 routes that preserve that target; it cannot authorize generic inline or base