@open-agent-toolkit/cli 0.1.55 → 0.1.60

package/assets/docs/workflows/projects/orchestration-model.md

@@ -0,0 +1,190 @@
+---
+title: Orchestration Model
+description: Root-owned phase execution, optional nested work, independent reviews, and provider-neutral dispatch in OAT projects.
+---
+
+# Orchestration Model
+
+OAT separates lifecycle ownership from implementation ownership:
+
+- the project root owns sequencing, reviews, fix routing, checkpoints, fan-in,
+  and bookkeeping;
+- one phase implementer owns all planned tasks for one phase; and
+- optional nested agents provide bounded help only when useful.
+
+This topology keeps model control at the meaningful phase boundary without
+making every task pay another dispatch and context-loading round.
+
+## Default Topology
+
+```mermaid
+flowchart TD
+  Root["Project root\nlifecycle owner"]
+  Adapter["Project dispatch adapter"]
+  Engine["Provider-neutral dispatch engine"]
+
+  Root --> Adapter --> Engine
+  Engine --> P["Phase implementer\none per phase"]
+  P --> T1["Planned task commit"]
+  P --> T2["Planned task commit"]
+  P -. optional .-> Recon["Recon / specialist / isolated fanout"]
+
+  Root -. independent review lane .-> Adapter
+  Engine -. exact reviewer route .-> R["Phase reviewer"]
+  R -->|blocking findings| Root
+  Root -->|resume bounded fix| P
+
+  Root -. external gate lane .-> G["Configured cross-runtime gate"]
+```
+
+The solid implementation lane is mandatory. The dotted nested lane is
+benefit-driven. A run does not fail merely because the phase agent cannot or
+does not launch a third tier.
+
+## Role Boundaries
+
+| Role                  | Generic class       | Owns                                                                                      | Must not                                                                                       |
+| --------------------- | ------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Project root          | lifecycle caller    | Phase schedule, dispatch policy, phase review, fixes, worktrees, checkpoints, bookkeeping | Take over an accepted child scope or silently replace an accepted launch                       |
+| Phase implementer     | `worker`            | One whole phase, ordered task execution, per-task commits, phase verification             | Dispatch the phase reviewer, alter plan sequencing, own project checkpoints                    |
+| Optional nested child | `worker` or `recon` | Explicit bounded objective, files/read scope, output, verification                        | Become mandatory for ordinary tasks, widen phase authority, commit in place of the phase agent |
+| Phase reviewer        | `reviewer`          | Independent review of one phase commit range                                              | Inherit a below-ceiling producer silently or mutate implementation                             |
+| External gate         | `reviewer`          | Configured producer-independent lifecycle decision                                        | Substitute same-context self-review when independence is required                              |
+
+## Dispatch Layers
+
+Every lifecycle launch flows through two contracts:
+
+1. `oat-project-dispatch-subagents` resolves project state, role policy,
+   ceilings, scope, files, commits, worktrees, and checkpoints.
+2. `oat-dispatch-subagents` resolves capabilities, catalogs, exact routes,
+   launch acceptance, continuation, and generic evidence.
+
+The lifecycle workflow remains authoritative for synthesis and state mutation.
+The dispatch engine does not edit `plan.md`, `implementation.md`, or project
+state.
+
+```mermaid
+sequenceDiagram
+  participant Root as Project root
+  participant Adapter as Project adapter
+  participant Engine as Dispatch engine
+  participant Phase as Phase implementer
+
+  Root->>Adapter: Phase + lifecycle authority
+  Adapter->>Engine: Provider-neutral dispatch request
+  Engine-->>Root: Exact route + request ID
+  Root->>Phase: Phase Scope
+  Phase-->>Root: Phase report + commits
+```
+
+## Phase Execution
+
+The phase implementer reads its artifact set once and executes tasks serially in
+plan order. Each task retains its file boundary, verification, and one-commit
+contract. The phase agent self-checks before committing and runs phase-wide
+verification before returning.
+
+The root verifies the report against Git rather than trusting child prose:
+
+- phase base and final HEAD;
+- one commit per planned task;
+- declared file boundaries;
+- task and phase verification;
+- clean worktree; and
+- optional child records, if any.
+
+See [Implementation Execution](implementation-execution.md) for the executable
+contract.
+
+## Independent Phase Review
+
+After a phase report is accepted, the root resolves and launches the reviewer
+at the configured review ceiling. Review ownership does not sit inside a
+possibly below-ceiling phase agent.
+
+Blocking findings return to the original phase handle in fix mode. If that
+completed handle cannot resume, one fresh same-target phase agent may receive
+the bounded fix scope, with `continuation_events` linking the new request to the
+original `request_id`.
+
+This preserves continuity without allowing replacement after an accepted failed
+launch.
+
+## Optional Third Tier
+
+Nested work is appropriate when the work itself benefits:
+
+- read-only reconnaissance that can run independently;
+- analysis fanout across separate concerns;
+- safely isolated implementation lanes; or
+- a specialist capability the phase agent does not provide efficiently.
+
+Before launch, the phase agent defines objective, authority, exact target,
+output, verification, deadline, retry policy, and fallback. The parent retains
+phase ownership and task commit authority.
+
+Do not use nested dispatch merely to mirror task granularity. The smoke fixture
+intentionally proves successful execution with no task workers.
+
+## Catalogs and Exact Selection
+
+Native model catalogs are per-dispatch-context snapshots. A root catalog does
+not prove what a nested agent can launch, and a provider CLI catalog does not
+prove native eligibility.
+
+The full-information selection order is:
+
+1. inspect the current dispatch context's native catalog;
+2. intersect it with configured candidates under the named ceiling;
+3. prefer a satisfying exact native route;
+4. otherwise select a policy-authorized CLI/programmatic route before launch;
+5. record the reason and ordered candidates; and
+6. fail closed if no exact authorized route exists.
+
+Configured values remain opaque where the provider defines them that way.
+Never infer capabilities from Cursor selector spelling.
+
+## Accepted-Launch Terminality
+
+Pre-start rejection and accepted child failure are different states:
+
+- **Pre-start rejection:** no child owns the scope; another configured route may
+  be selected.
+- **Accepted launch:** the child owns the scope; its completed, failed,
+  interrupted, timed-out, or `BLOCKED` result is authoritative.
+
+`invalid-run-abort` is cancellation of a proven-invalid run, not a child outcome
+and not permission to launch a replacement.
+
+## Parallel Phases
+
+Plan-declared phase groups run in separate worktrees. The root creates and
+registers worktrees, verifies the common base, dispatches one phase implementer
+per worktree, owns each review/fix loop, then merges passing phases in plan
+order.
+
+Task-level concurrency inside one worktree remains disallowed unless an
+optional child has explicitly isolated write authority.
+
+## Provider Shapes
+
+- **Codex:** root uses the exact materialized phase implementer and reviewer
+  roles. Depth one supports the default topology; depth two enables optional
+  nested work.
+- **Claude:** root uses native Agent dispatch for phase implementation and
+  review. Nested Agent work is optional and evidenced per run.
+- **Cursor IDE:** operator starts the root session. Native and CLI routes use
+  full-information selection, with deliberate pre-start CLI choice when the
+  native catalog is unsatisfying.
+- **Cursor CLI:** treated as a separate harness with its own catalog and event
+  evidence.
+
+## Related
+
+- [Implementation Execution](implementation-execution.md)
+- [Dispatch Policy](dispatch-ceiling.md)
+- [Review Flavors](review-flavors.md)
+- [Programmatic Execution](programmatic-execution.md)
+- [Evidence Layers](evidence-layers.md)
+- [Workflow Smoke Testing](../../contributing/smoke-testing.md)

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

@@ -0,0 +1,137 @@
+---
+title: Programmatic Execution
+description: 'How OAT launches agents through provider CLI/headless surfaces — per-harness execution shapes, cross-runtime gate exec targets, credential isolation, and the launcher-owned evidence they share.'
+---
+
+# Programmatic Execution
+
+**Programmatic execution** is launching an agent through a provider's CLI or
+headless surface — a fresh child process — rather than a native same-runtime
+dispatch through the harness's own subagent tool. OAT reaches for it in exactly
+three places:
+
+1. **Cross-runtime gate reviews** — a workflow gate dispatches an independent
+   reviewer to a different runtime/family than the one that produced the work.
+2. **Policy-resolved CLI dispatch** — a phase implementer, optional nested
+   worker, or reviewer route that the native same-runtime catalog cannot
+   satisfy, resolved to a provider CLI before launch.
+3. **Operator smoke sessions** — the smoke runner drives each harness through
+   its headless flavor to capture per-harness evidence.
+
+Programmatic execution is **never an improvised fallback**. Route authorization
+comes from configured dispatch policy or a configured cross-family gate
+(standing, scope-bound), or from explicit user approval for the current run.
+Availability of a provider CLI is capability evidence, not authorization. See
+the route tiers in
+[Orchestration Model](orchestration-model.md#route-tiers-and-terminality) for
+how native, policy-resolved, and improvised routes are ranked, and why an
+accepted launch is terminal for automatic replacement.
+
+## Per-harness execution surfaces
+
+Each harness exposes different controllable axes. Verify the current CLI help
+before constructing any route; the shapes below are the verified skeletons, not
+a fixed flag inventory. Model strings are placeholders — provider catalogs are
+volatile, so never hard-code a model name as a durable fact.
+
+| Harness    | Verified headless shape                                                                                          | Controllable axes                                                                                                      | Caveats                                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Codex      | `codex exec --ephemeral --sandbox read-only --model '<model>' -c 'model_reasoning_effort="<effort>"' '<prompt>'` | agent type, model + reasoning effort, service tier, forked context, max nesting depth, sandbox + scoped writable roots | Model and effort are separate configured axes; native nesting grants no filesystem authority         |
+| Claude     | `claude -p --model '<model-alias-or-id>' '<prompt>'`                                                             | agent type, model (alias or full ID), CLI effort when exposed                                                          | No effort axis on the native Agent surface — record it as `not-exposed`, not `not-applicable`        |
+| Cursor CLI | `cursor-agent --trust --print --model '<exact-opaque-model>' '<prompt>'`                                         | opaque model selector from the account catalog                                                                         | Opaque strings pass byte-for-byte; distinct flavor from Cursor IDE — do not infer one from the other |
+| Cursor IDE | (native session; no headless CLI shape)                                                                          | native Task/Subagent schema, UI role configuration                                                                     | Any CLI task dispatch from an IDE root is a recorded pre-start selection                             |
+
+Notes per harness:
+
+- **Codex** treats registered agent type, model, reasoning effort, service
+  tier, fork behavior, sandbox, and scoped writable roots as independent
+  configured axes. Use the CLI route only when native dispatch cannot express
+  the complete target and the route is selected before launch. Record model,
+  effort, sandbox, and route as configured-invocation evidence; a successful
+  process alone does not prove runtime identity.
+- **Claude** has three native control surfaces — the native Agent tool (agent
+  type plus optional model), agent-definition frontmatter (default model), and
+  `claude -p` (alias or full model ID plus CLI effort). Model resolution follows
+  explicit-call model > agent-definition model > parent/session inheritance.
+  Never omit a worker model unless inheritance is the recorded policy.
+- **Cursor** keeps three control surfaces that must not be conflated: the native
+  Task/Subagent schema, the account CLI catalog (`cursor-agent --list-models`),
+  and Cursor UI role configuration. IDE and CLI are separate harness contexts;
+  an observed catalog is a volatile snapshot, and equality in one run does not
+  establish equality in another run or nesting boundary. Opaque model selectors
+  are passed byte-for-byte.
+
+## Cross-runtime gate execution
+
+Workflow gates use programmatic execution to run a producer-independent
+reviewer. `oat gate cross-provider-exec` (and the review-specific
+`oat gate review`) choose from `workflow.gates.execTargets` — targets keyed by
+opaque id with a declared runtime, argv `baseCommand`, priority, and optional
+`models` list. OAT does not infer provider semantics from the target id.
+
+Gate dispatch defaults to `--avoid same-family`: it detects the current runtime
+via host-detection commands and picks the highest-priority available non-host,
+different-family target. This **host-avoidance** is why gate targets are
+independent of the harness's native subagent catalog — the point of a gate is a
+route the producing context could not have selected for itself. The
+lifecycle/final gate is the one flavor that may spawn a **nested managed
+reviewer child inside the gate exec target**; see
+[Review Flavors](review-flavors.md) for which flavor fires when and how
+independent each must be.
+
+Gates **fail closed**. If no different-family target is available, OAT records
+the degraded achieved level rather than pretending diversity was achieved, and
+an unavailable required-independent target blocks the gate instead of quietly
+downgrading to a same-context self-review. Only summarize the execution-surface
+angle here — see [Workflow Gates](../../cli-utilities/workflow-gates.md) for the
+gate envelope, exec-target configuration, receive-eligibility, and completion
+contract. The cross-runtime `gates.execTargets` design (host-avoidance and
+independence from native catalogs) is the smoke fixture's cross-runtime gate
+leg.
+
+## Credential isolation
+
+Some gate and smoke routes must launch a Cursor child while the driving process
+is a sandboxed Codex process whose tool shells redact provider credentials. OAT
+resolves this with a **runner-owned mailbox broker** rather than by threading
+the secret through the child.
+
+The disposable local gate target invokes only a committed worktree-mailbox
+client; the parent broker — outside the sandbox — is what launches
+`cursor-agent` with the retained key. Operator handoffs wrap Codex in the same
+broker launcher. The rule is absolute: the `CURSOR_API_KEY` value must never
+enter config, manifests, the mailbox, logs, prompts, or evidence. This keeps
+the secret out of every sandboxed child process and every durable artifact while
+still allowing a cross-runtime launch. (Conceptual only; the broker mechanics
+live with the smoke runner contract.)
+
+## Evidence
+
+Every programmatic launch produces the **same launcher-owned dispatch record**
+as a native dispatch: the selected route, exact target/model/effort axes,
+selection reason, ordered candidates considered, and launch acceptance. Because
+the launcher constructs the payload itself, this evidence does not depend on any
+child cooperation. Runtime-observed identity is optional corroboration —
+recorded as `reported` or `not-reported`, and its absence never invalidates the
+configured-invocation record. See [Evidence Layers](evidence-layers.md) for the
+three-layer model and how assertions bind to the launcher-owned layer.
+
+Where relevant to a run: optional Claude phase-agent nesting and Cursor CLI
+subagent-event observability are **validated per run by live smoke evidence**,
+not asserted here as settled facts. Successful default execution does not
+require either capability.
+
+## Related
+
+- [Orchestration Model](orchestration-model.md) — route tiers, native-first
+  selection, and per-harness topology.
+- [Review Flavors](review-flavors.md) — the four review flavors and which one
+  may spawn a nested managed reviewer inside a gate.
+- [Evidence Layers](evidence-layers.md) — the three-layer dispatch evidence
+  model these launches feed.
+- [Dispatch Policy](dispatch-ceiling.md) — candidate ladders, named ceilings,
+  and the dispatch report.
+- [Workflow Gates](../../cli-utilities/workflow-gates.md) — gate envelope,
+  exec-target configuration, and completion contract.
+- [Smoke Testing](../../contributing/smoke-testing.md) — per-harness drive
+  protocols and live evidence.

package/assets/docs/workflows/projects/review-flavors.md

@@ -0,0 +1,129 @@
+---
+title: Review Flavors
+description: 'The four OAT project review flavors, when each fires in the lifecycle, and who resolves its reviewer target.'
+---
+
+# Review Flavors
+
+OAT projects run reviews at several different lifecycle points, and those points
+have different independence requirements. A self-review that checks a freshly
+written plan does not need the same producer isolation as a lifecycle gate that
+signs off on the final artifact. Rather than force one reviewer-selection rule
+onto every point, OAT recognizes **four review flavors**, each with its own
+target-resolution policy layered on the shared reviewer role class.
+
+The distinguishing question is always _"who resolves this review's target, and
+how independent must that target be from whatever produced the work?"_ The four
+flavors answer it differently while preserving one invariant: the reviewer runs
+**at or above the ceiling** (see [Dispatch Policy](dispatch-ceiling.md)). Gate
+independence is project policy layered on the generic reviewer role class
+described in the `oat-project-dispatch-subagents` lifecycle-role table; this page
+covers _which_ flavor fires _when_ and _who_ resolves its target, and links out
+for the deep review request/receive mechanics.
+
+## Quick Look
+
+- What it does: names the four review flavors and states who resolves each
+  one's reviewer target.
+- When to use it: when you need to know which review fires at a lifecycle point
+  and whether it inherits, pins the ceiling, or requires an independent gate.
+- Primary sources: `oat-project-implement` phase-execution mechanics, the
+  `oat-project-dispatch-subagents` lifecycle-role table, and project design
+  Decision #11.
+
+## Flow map
+
+```mermaid
+flowchart TD
+  subgraph Planning
+    PL["Planning-phase\nartifact self-review"] --> PLR["Inherit planning parent"]
+    PLR --> PLT["Parent model\n(root already at/above ceiling)"]
+  end
+
+  subgraph Implementation
+    IM["Root-owned phase\nself-review"] --> IMR["Resolve dispatch ceiling"]
+    IMR --> IMPIN["At-ceiling pin\n(ceiling final candidate)"]
+    IMR --> IMINH["Inherit\n(only if dispatcher known at/above ceiling)"]
+    IMR --> IMCLI["Exact CLI reviewer\n(selected pre-launch)"]
+  end
+
+  subgraph Gates
+    PG["Phase review gate\n(external)"] --> PGR["Configured cross-family\nexec target (gates.execTargets)"]
+    PGR --> PGT["Independent CLI/exec target\n(host-avoidance; fail closed)"]
+
+    LG["Lifecycle / final gate"] --> LGR["Cross-runtime CLI\nexec target"]
+    LGR --> LGT["Producer-independent target\n(fail closed, no self-review substitute)"]
+    LGT -. may spawn .-> LGN["Nested managed\nreviewer child inside gate"]
+  end
+```
+
+The dotted branch marks the only flavor that may **spawn a nested managed
+reviewer child** inside the gate exec target: the lifecycle/final gate.
+
+## The four flavors
+
+| Flavor                              | Lifecycle point                                                    | Target resolution                                                                                                                                                                                              |
+| ----------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Planning-phase artifact self-review | Auto artifact-review loop for plan/spec/design                     | Inherit the planning parent by default (root is already at/above ceiling)                                                                                                                                      |
+| Implementation-phase self-review    | Phase and final code reviews dispatched by `oat-project-implement` | Resolve the dispatch ceiling; pin the ceiling's final candidate (at-ceiling pin); inherit only when the review-owning dispatcher is known to be at/above ceiling; else select an exact CLI reviewer pre-launch |
+| Phase review gate (external)        | Optional non-pausing gate after a phase passes its self-review     | Independent configured cross-family CLI/exec target (`gates.execTargets`), host-avoidance, unconstrained by native catalog; fail closed if unavailable                                                         |
+| Lifecycle / final gate              | End-of-lifecycle sign-off                                          | Cross-runtime CLI exec target, independent of producer context; fails closed rather than substituting same-context self-review; may spawn a nested managed reviewer child inside the gate exec target          |
+
+The first two flavors are **self-reviews**. Planning review inherits its
+producing parent by default; implementation phase review is dispatched by the
+project root after the phase producer returns. The last two are **gates** — an
+external, configured, producer-independent target. Phase implementation may run
+_below_ the review ceiling for cost reasons, but review must never silently
+inherit the below-ceiling phase agent.
+
+## Independence and fail-closed semantics
+
+The invariant across all four flavors is that the reviewer runs **at or above
+the ceiling**. What changes between flavors is the required _independence from
+the producer_, and that independence is enforced by failing closed rather than
+silently downgrading:
+
+- **Planning self-review** needs the least independence. The planning root
+  already runs at or above the review ceiling, so inheriting the parent model
+  satisfies the invariant without managed re-pinning. Pinning is _possible_
+  once the ceiling is resolved during planning, but it is not the default.
+- **Implementation self-review** needs ceiling-level capability but not
+  cross-family isolation. The root resolves the dispatch ceiling and pins the
+  tier's final candidate after the phase report. Inheritance is allowed only
+  when the root dispatcher is _known_ to be at or above the ceiling; otherwise
+  an exact provider CLI reviewer is selected before launch. Reviewer selection
+  is never delegated to the phase implementer.
+- **Phase review gate** adds cross-family independence. It uses a configured
+  independent exec target from `gates.execTargets` with host-avoidance,
+  unconstrained by the harness's native subagent catalog. If the required
+  independent target cannot be enforced, the gate **fails closed** — it does
+  not downgrade to producer-context review.
+- **Lifecycle / final gate** requires the strongest independence: a
+  cross-runtime CLI exec target chosen independently of the producer context.
+  It fails closed rather than substituting a same-context self-review, and it is
+  the one flavor permitted to spawn a nested managed reviewer child _inside_ the
+  gate exec target when the gate's own contract calls for it.
+
+Gate independence is not a property of the generic reviewer class; it is project
+policy layered on top of it. The dispatch adapter resolves the configured gate
+target before launch and passes it as exact selection input. Fail-closed
+behavior for both gate flavors is deliberate: an unavailable independent target
+blocks the gate instead of quietly reusing whatever produced the work. For the
+gate configuration keys and non-pausing behavior, see
+[Workflow gates](../../cli-utilities/workflow-gates.md) and the
+[phase review gate](reviews.md#phase-review-gate) section of the review doc.
+
+## Related
+
+- [Reviews](reviews.md) — the review request/receive flows and the deep review
+  contract these flavors plug into.
+- [Dispatch Policy](dispatch-ceiling.md) — named ceilings, at-ceiling reviewer
+  selection, and the Dispatch Report V1 / producer-provenance record.
+- [HiLL Checkpoints](hill-checkpoints.md) — how the non-pausing phase review gate
+  relates to pauseable lifecycle checkpoints.
+- [Orchestration Model](orchestration-model.md) — the native-first dispatch
+  topology these reviewer roles run inside.
+- [Workflow gates](../../cli-utilities/workflow-gates.md) — gate configuration
+  and exec-target selection.
+- [Smoke testing](../../contributing/smoke-testing.md) — how the fixture makes
+  these flavors observable and assertable.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.55",
-  "docs-config": "0.1.55",
-  "docs-theme": "0.1.55",
-  "docs-transforms": "0.1.55"
+  "cli": "0.1.60",
+  "docs-config": "0.1.60",
+  "docs-theme": "0.1.60",
+  "docs-transforms": "0.1.60"
 }

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

@@ -220,8 +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.
+- OAT's default topology is root → phase implementer and needs depth `1`.
+  Configure `[agents] max_depth = 2` or higher for optional nested work.
 - Define role(s) in config:
   - `[agents.oat-reviewer]` (or role names your workflow dispatches)
 - Dispatch by role name using `agent_type` (not `subagent_type`).
@@ -234,8 +234,9 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
   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.
+- Sync and direct materialization merge an `agents.max_depth` floor of `2` as
+  optional nested-work capacity without lowering a higher project or inherited
+  user value. Default managed preflight accepts missing depth or depth `1`.
 
 ### Other Codex Resources
 

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

@@ -220,8 +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.
+- OAT's default topology is root → phase implementer and needs depth `1`.
+  Configure `[agents] max_depth = 2` or higher for optional nested work.
 - Define role(s) in config:
   - `[agents.oat-reviewer]` (or role names your workflow dispatches)
 - Dispatch by role name using `agent_type` (not `subagent_type`).
@@ -234,8 +234,9 @@ The package manager for the agent skills ecosystem. Installs skills across 27+ a
   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.
+- Sync and direct materialization merge an `agents.max_depth` floor of `2` as
+  optional nested-work capacity without lowering a higher project or inherited
+  user value. Default managed preflight accepts missing depth or depth `1`.
 
 ### Other Codex Resources
 

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.1.0
+version: 1.1.2
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
@@ -238,6 +238,11 @@ aggregate wave boundary; each lane may narrow that boundary.
   policy.
 - Continuing the same accepted child through its valid handle is allowed.
   Record continuation separately and preserve selectors and route.
+- A caller may cancel accepted handles only after it proves that the enclosing
+  run itself is invalid under caller-owned containment or integrity policy.
+  Record `invalid-run-abort` and the invalidating evidence. Cancellation never
+  makes another route eligible and never authorizes replacement, fallback, or
+  a successful child outcome.
 - Operator-authorized recovery is a new explicit action, never automatic
   fallback.
 - Runtime identity is optional corroboration. Missing runtime identity does not

package/assets/skills/oat-dispatch-subagents/references/record-schema.md

@@ -79,6 +79,11 @@ continuation_events: []
 `role_selector` is the exact provider or harness agent-type selector, when that
 surface exists. Preserve opaque selectors byte-for-byte.
 
+Use the stable selection reasons `native-catalog`,
+`native-catalog-unsatisfying`, `pre-start-rejection`, `inherit`, and
+`gate-target`. Calling adapters may add a more specific diagnostic, but must
+not replace or rename these shared values.
+
 Use `selection_source: native-default` for the preferred same-runtime native
 route, `policy-resolved` for a CLI/programmatic or cross-runtime route selected
 by configured project/workflow/gate policy, and `explicit-user` for an

package/assets/skills/oat-project-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-dispatch-subagents
-version: 1.1.0
+version: 1.1.2
 description: Use when an OAT project lifecycle skill needs to translate project state, phase or task scope, gates, and write authority into a provider-neutral subagent dispatch.
 disable-model-invocation: true
 user-invocable: false
@@ -108,19 +108,25 @@ conversational approval are never project policy.
 
 Map each lifecycle role to a generic baseline class and add project policy:
 
-| Lifecycle role             | Generic class | Project-specific contract                                                                                                                |
-| -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Phase coordinator          | `coordinator` | Own one phase dossier. Prefer an explicit suitable native target; inherit only when the root/session target is deliberately suitable.    |
-| Task worker                | `worker`      | Own one task and bounded files. Use an explicit native or pre-selected alternate target; never silently inherit an expensive root model. |
-| Fix worker                 | `worker`      | Own listed findings and bounded files. Preserve retry/fix-loop limits and original task context.                                         |
-| Planning self-review       | `reviewer`    | Inherit the planning parent by default unless the plan-writing contract requires an exact independent reviewer.                          |
-| Implementation self-review | `reviewer`    | Target the resolved reviewer ceiling; inherit only when the review-owning dispatcher is known to satisfy it.                             |
-| Phase gate                 | `reviewer`    | Use the configured independent target and fail closed when unavailable.                                                                  |
-| Lifecycle gate             | `reviewer`    | Stay independent of producer context and fail closed rather than substituting same-context self-review.                                  |
+| Lifecycle role                         | Generic class       | Project-specific contract                                                                                               |
+| -------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Phase implementer                      | `worker`            | Own one complete phase, execute tasks directly in order, preserve per-task commits, and return phase verification.      |
+| Optional task/recon/specialist child   | `worker` or `recon` | Launch only when benefit justifies nesting; keep objective, files, authority, target, output, and verification bounded. |
+| Phase fix continuation                 | `worker`            | Resume the original phase handle when possible; preserve retry limits, phase context, and original request linkage.     |
+| Planning self-review                   | `reviewer`          | Inherit the planning parent by default unless the plan-writing contract requires an exact independent reviewer.         |
+| Root-owned implementation phase review | `reviewer`          | Target the resolved reviewer ceiling independently of the phase producer.                                               |
+| Phase gate                             | `reviewer`          | Use the configured independent target and fail closed when unavailable.                                                 |
+| Lifecycle gate                         | `reviewer`          | Stay independent of producer context and fail closed rather than substituting same-context self-review.                 |
 
 The calling lifecycle skill remains authoritative when its reviewed contract
 is stricter than this table.
 
+The root owns implementation phase-review selection. A native catalog that
+cannot satisfy the resolved review ceiling must use a policy-resolved
+pre-start CLI reviewer route when available. Record the native mismatch, exact
+target, selection reason, and ordered candidates; never delegate reviewer
+selection to a below-ceiling phase implementer or silently downgrade.
+
 ## Adapt the Request
 
 For every lifecycle dispatch:
@@ -171,12 +177,22 @@ project:
   worktree: root
 ```
 
-## Coordinator and Worker Topology
+## Phase-Agent Topology
+
+The default implementation topology is root → phase implementer plus
+root → phase reviewer. The phase implementer directly owns the planned phase
+tasks. Per-task dispatch is not required.
+
+Optional nested workers or recon agents are benefit-driven and remain subject
+to exact bounded scopes and launcher-owned evidence. They must not widen task
+boundaries, alter plan sequencing, take over phase commits, dispatch the phase
+reviewer, or own user checkpoints.
 
-Use a phase coordinator only when the lifecycle workflow declares that
-topology. A coordinator may dispatch task workers when nesting and authority
-permit it, but it must not widen task boundaries, alter plan sequencing, or
-take over user checkpoints.
+When review findings require fixes, resume the original phase request when the
+host supports continuation. If a completed phase handle is unavailable, allow
+at most one fresh same-target phase implementer for the bounded fix scope and
+link its generic record to the original `request_id` through existing
+`continuation_events`.
 
 For parallel groups, preserve plan-declared isolation. Each worktree receives
 only its assigned phase/task boundaries and must not mutate sibling worktrees.
@@ -229,6 +245,12 @@ fields inside the lifecycle extension.
   engine.
 - Accepted child failure: return the terminal outcome to the lifecycle caller;
   do not select a replacement automatically.
+- A tracked smoke marker makes containment, ownership registration, expected
+  base, and fixture readiness run-validity conditions. Failure of any condition
+  triggers `invalid-run-abort`: terminate accepted child and gate handles owned
+  by that run, preserve the invalidating evidence, clean only journal-owned
+  resources, and stop before any later launch. Never replace an aborted handle
+  or degrade the invalid smoke run to sequential execution.
 - Required gate target unavailable: fail closed.
 - Verification or commit failure after worker completion: lifecycle caller owns
   repair and bookkeeping; do not falsify the child outcome.