@open-agent-toolkit/cli 0.1.54 → 0.1.59

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/docs/workflows/skills/repo-improve.md

@@ -19,6 +19,20 @@ Use `oat-repo-improve` when the desired output is an executable implementation p
 
 With no source argument, the skill probes for available review and backlog artifacts, annotates all five options, and asks which source to use.
 
+## Set repo-audit boundaries
+
+Fresh repo audits exclude agent-configuration directories from findings and plan candidates by default. The canonical default directory names are `.agents/`, `.claude/`, `.codex/`, and `.cursor/` at any depth. These locations commonly contain provider configuration, generated views, or externally sourced skills rather than the product surfaces being reviewed.
+
+Before reconnaissance, improve shows that default and asks whether to:
+
+- Keep all four exclusions.
+- Include selected directory names.
+- Include all four directory names.
+
+It then asks whether any other repo-relative directories should be excluded and suggests other recognizable provider directories when present. The resolved scope is shown before work begins and is applied consistently to direct searches and delegated audit lanes.
+
+These are findings exclusions, not absolute read prohibitions. Improve may read bounded instruction, convention, or intent files inside an excluded directory to understand the repository, but it does not turn those files into findings or plan candidates unless the user includes or explicitly targets that directory. A file cited by an artifact-backed source can still be verified after scope confirmation; symlinked provider views are never followed outside the repository.
+
 ## Output boundary
 
 External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no OAT phase/task IDs or lifecycle bookkeeping.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.54",
-  "docs-config": "0.1.54",
-  "docs-theme": "0.1.54",
-  "docs-transforms": "0.1.54"
+  "cli": "0.1.59",
+  "docs-config": "0.1.59",
+  "docs-theme": "0.1.59",
+  "docs-transforms": "0.1.59"
 }

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