@open-agent-toolkit/cli 0.1.51 → 0.1.53

package/assets/docs/cli-utilities/configuration.md

@@ -453,7 +453,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
-- `workflow.postImplementSequence` — `wait`, `summary`, `pr`, or `docs-pr`. Controls what `oat-project-implement` chains after final review passes. `wait` stops without auto-chaining, `summary` runs only `oat-project-summary`, `pr` runs `oat-project-pr-final` (which auto-generates summary), `docs-pr` runs `oat-project-document` then `oat-project-pr-final`. When unset, the skill prompts.
+- `workflow.postImplementSequence` — legacy `wait`, `summary`, `pr`, or `docs-pr`, or `{ "preApproval": [...], "postApproval": [...] }`. Legacy values remain strings; structured arrays contain ordered, globally unique `summary`, `document`, and `pr` steps. Pre-approval steps run after final review and before final HiLL approval; post-approval steps run only after that approval. Plain retrieval keeps legacy strings and prints structured values as compact JSON; `--json` returns the raw value.
 - `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
 - `workflow.autoReviewAtHillCheckpoints` — boolean. Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase `oat-reviewer` gates, which run after each phase in Tier 1 regardless of this setting. When unset, the skill prompts.
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.

package/assets/docs/cli-utilities/tool-packs.md

@@ -17,13 +17,34 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 
 - `core` - foundational diagnostics and docs access (`oat-doctor`, `oat-docs`)
 - `docs` - docs and agent-instructions governance workflows
-- `workflows` - project lifecycle skills, wrap-up reporting, reviewer agents, and core project templates
+- `workflows` - project lifecycle skills, the project subagent-dispatch adapter, wrap-up reporting, reviewer agents, and core project templates
 - `ideas` - lightweight ideation and promotion flows
-- `utility` - review and repo-maintenance helpers
+- `utility` - review and repo-maintenance helpers plus the provider-neutral subagent-dispatch engine
 - `project-management` - file-backed backlog/reference skills plus backlog, roadmap, current-state, file-per-record decision, and AGENTS-guide templates
 - `research` - research, analysis, comparison, and synthesis skills
 - `brainstorm` - always-on brainstorming entry point with visual companion
 
+### Cross-pack dispatch dependency
+
+The reusable dispatch contracts intentionally span two packs:
+
+- `utility` owns `oat-dispatch-subagents`, the provider-neutral engine for
+  capability checks, catalog-aware selection, launch evidence, and recovery.
+- `workflows` owns `oat-project-dispatch-subagents`, the adapter that adds OAT
+  project lifecycle context without duplicating provider mechanics.
+
+Install both packs when project lifecycle skills need the adapter:
+
+```bash
+oat tools install utility
+oat tools install workflows
+```
+
+The packs remain independently installable. If the workflows adapter is
+present without the utility engine, it fails closed and reports the missing
+dependency instead of inventing a fallback route. Non-project analytical
+skills can use the utility engine directly.
+
 ## `oat tools` command group
 
 The `oat tools` command group provides a unified interface for managing installed tools (skills and agents) across scopes.

package/assets/docs/contributing/skills.md

@@ -75,6 +75,22 @@ At minimum, the skill contract should:
 - Stop before side effects if delegation is required for correctness and authorization remains unresolved.
 - Document the fallback path and any quality or independence tradeoff.
 
+OAT-specific skills should compose with the internal
+`oat-dispatch-subagents` contract instead of copying provider selection and
+recovery rules. The caller still owns decomposition, user interaction,
+verification of load-bearing claims, cross-lane synthesis, and artifact
+writes. The dispatch contract owns capability and authorization checks, live
+catalog evidence, route/model/effort selection, launch acceptance, recovery,
+and the neutral dispatch record.
+
+Keep project lifecycle policy out of that general layer. A lifecycle caller
+loads `oat-project-dispatch-subagents` to resolve project, phase/task, gate,
+write-boundary, commit, and worktree context, then passes a generic request to
+`oat-dispatch-subagents`. Analytical callers such as repository audits can use
+the general contract directly without requiring an active project. In either
+case, resolve the provider first and load exactly one provider-specific
+reference rather than merging provider mechanics into a universal catalog.
+
 Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both include the current delegation guidance and optional capability-detection template.
 
 ## Gate-aware skills

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

@@ -66,7 +66,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. For `artifact_validation_failed`, correct the artifact and rerun the gate for successful revalidation before receive. `targeting_correlation_failed` sets `receiveEligible: false`; do not run review-receive even if it reports an artifact path. Orchestrators should read the structured result rather than poll the filesystem. The command runs standalone (for example, `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
@@ -92,7 +92,7 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `workflow.hillCheckpointDefault` (`every` | `final`) — default HiLL checkpoint behavior in `oat-project-implement`
 - `workflow.archiveOnComplete` (`boolean`) — skip the archive prompt in `oat-project-complete`
 - `workflow.createPrOnComplete` (`boolean`) — skip the "Open a PR?" prompt in `oat-project-complete`
-- `workflow.postImplementSequence` (`wait` | `summary` | `pr` | `docs-pr`) — post-implementation chaining behavior
+- `workflow.postImplementSequence` (legacy `wait` | `summary` | `pr` | `docs-pr`, or structured `{preApproval, postApproval}` arrays) — approval-aware post-implementation chaining
 - `workflow.reviewExecutionModel` (`subagent` | `inline` | `fresh-session`) — default final-review execution model
 - `workflow.autoReviewAtHillCheckpoints` (`boolean`) — auto-run the extra lifecycle review at HiLL checkpoints
 - `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -10,7 +10,7 @@ OAT supports two checkpoint classes:
 - Workflow phase checkpoints
 - Plan phase checkpoints
 
-The [phase review gate](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
+The [Phase gate review](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
 
 ## Workflow checkpoints (`state.md`)
 

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

@@ -25,6 +25,26 @@ ceiling.
 
 ## Execution Layers
 
+### Reusable dispatch boundary
+
+OAT ships two internal contracts for lifecycle skills that need subagents:
+
+- `oat-project-dispatch-subagents` translates resolved project, phase/task,
+  gate, write-boundary, commit, and worktree policy into a generic dispatch
+  request.
+- `oat-dispatch-subagents` performs provider-neutral capability and
+  authorization checks, catalog-aware selection, launch evidence, and
+  recovery.
+
+The project adapter composes with the general engine; the engine never reads
+project state. Lifecycle callers remain responsible for phase scheduling,
+task boundaries, review and fix-loop policy, project artifacts, commits, and
+worktree fan-in. This is the extension contract for lifecycle dispatch—not a
+license for the general engine to mutate project bookkeeping or reinterpret
+worker results. Individual lifecycle skills may adopt the contract
+incrementally; their own reviewed process contracts remain authoritative until
+that wiring is explicit.
+
 ### Orchestrator
 
 The root `oat-project-implement` workflow resolves project state, chooses Tier
@@ -374,6 +394,11 @@ context. An unresolved or verification-failing conflict stops fan-in.
 
 ## Phase Review Gate and HiLL
 
+Phase gate review is independent from HiLL: a configured passing gate continues
+automatically, while a HiLL checkpoint pauses for human approval. For the final
+phase, approval-aware post-implementation sequences run pre-approval work only
+after final review and post-approval work only after the recorded approval.
+
 After standard review passes and bookkeeping is committed, an enabled
 `oat_phase_review_gate` may run a target-neutral external review for the phase.
 Passing artifacts are still received for durable disposition; blocking

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

@@ -84,6 +84,15 @@ This distinction matters during completion: `oat-project-complete` can skip the
 
 ### Auto-review at HiLL checkpoints
 
+### Approval-aware post-implementation sequencing
+
+`workflow.postImplementSequence` can use the legacy string values or a structured
+`{ preApproval, postApproval }` value. After the final review passes, OAT
+snapshots the effective sequence, runs ordered pre-approval steps, records final
+HiLL approval, and only then runs post-approval steps. The snapshot is
+restart-safe: an incomplete sequence routes back to implementation and resumes
+from its first incomplete step.
+
 When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (minors auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
 
 ### Phase-review setup during planning

package/assets/public-package-versions.json

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

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

@@ -0,0 +1,222 @@
+---
+name: oat-dispatch-subagents
+version: 1.0.0
+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
+allowed-tools: Read
+---
+
+# Dispatching OAT Subagents
+
+Use this internal contract to delegate bounded work while keeping judgment in
+the calling skill. It standardizes provider selection and launch evidence. It
+does not decide what work should be delegated or synthesize worker results.
+
+## Progress Indicators (User-Facing)
+
+This skill is an internal dependency; the calling skill owns the user-facing
+mode and decides whether a sub-banner is useful. When surfacing a distinct
+dispatch wave, use:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ SUBAGENT DISPATCH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Do not repeat the banner for every lane. Return a compact selection or blocking
+summary for the caller to incorporate.
+
+## Ownership Boundary
+
+The calling skill owns:
+
+- decomposition, lane boundaries, and output schemas;
+- user-facing progress, authorization context, and decisions;
+- verification of load-bearing worker claims;
+- cross-lane synthesis, prioritization, and artifact writes.
+
+This skill owns:
+
+- capability and authorization probing;
+- live catalog evidence and candidate intersection;
+- model, effort, role, route, authority, and deadline selection;
+- launch acceptance, continuation, recovery, and dispatch records.
+
+Do not read OAT project state, interpret `pNN-tNN` identifiers, or add phase,
+gate, commit, or worktree policy here. Project workflows must load
+`oat-project-dispatch-subagents`, which adapts those concerns into this
+contract.
+
+## Required Loading
+
+Read this file before every OAT-managed subagent dispatch. Resolve the active
+provider first, then read exactly one provider reference:
+
+- Claude: `references/provider-claude.md`
+- Codex: `references/provider-codex.md`
+- Cursor: `references/provider-cursor.md`
+
+Do not merge provider references into one policy. For an unsupported provider,
+apply this provider-neutral contract and fail closed when exact launch controls
+cannot be established.
+
+Read `references/record-schema.md` only when constructing or validating a
+dispatch request, dispatch record, or homogeneous recon-wave record.
+
+## Caller Request Contract
+
+Require the caller to provide:
+
+- a unique request ID and calling skill;
+- bounded objective and scope;
+- action and role name mapped to a baseline role class;
+- expected output and verification evidence;
+- authority, deadline, escalation conditions, and retry limit;
+- fallback policy and authorization scope;
+- optional resolved dispatch policy or named ceiling.
+
+Reject an over-broad request before selection. Every nontrivial request must
+state the exact objective, scope, expected output, verification evidence, and
+conditions that require escalation. Model routing never repairs poor
+decomposition.
+
+The optional policy and ceiling are already-resolved inputs. Do not infer where
+they came from or resolve project state to obtain them.
+
+## Capability and Authorization
+
+Classify delegation before launch:
+
+| State                       | Meaning                                                         | Action                                                                  |
+| --------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `available`                 | The host exposes a usable launch surface now.                   | Continue to catalog observation and selection.                          |
+| `authorization-required`    | A usable surface exists but needs user approval or scope grant. | Ask once, preserve the approved scope, then re-probe.                   |
+| `unresolved-or-unsupported` | No exact usable surface can be established in this environment. | Use only a pre-approved alternate route or block; do not invent syntax. |
+
+Authorization-required is not unavailability. Do not silently reduce coverage
+or run expensive work inline merely because one approval question is needed.
+The caller owns the user interaction; this skill returns the question and
+required scope.
+
+## Dispatch Axes
+
+Keep these controls independent in selection and evidence:
+
+- dispatch context: root native, nested native, provider CLI, workflow, gate,
+  or blocked;
+- role or agent definition;
+- model selector and selector granularity;
+- effort or reasoning selector, when exposed;
+- inheritance source and context-fork controls;
+- authority, writable roots, deadline, and retry limit;
+- route and fallback policy.
+
+A materialized role may package defaults, but its record must preserve each
+configured axis separately.
+
+## Baseline Role Classes
+
+Specific role names are extensible, but map every dispatch to one class:
+
+| Class          | Default contract                                                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `recon`        | Read-only, bounded evidence collection. Select an explicit economical target; never silently inherit an expensive root model.     |
+| `dossier-lead` | Reconcile dispersed evidence within one declared scope. May coordinate bounded recon only when nesting is supported and approved. |
+| `generator`    | Produce a self-contained artifact within caller-declared authority.                                                               |
+| `worker`       | Execute bounded work with explicit authority, outputs, and verification.                                                          |
+| `reviewer`     | Perform independent or inherited review exactly as caller policy specifies.                                                       |
+| `coordinator`  | Coordinate a caller-defined topology without taking over caller synthesis or user dialogue.                                       |
+
+Use stronger workers when context, ambiguity, or consequence requires them,
+not merely because many files exist. Keep coherence-critical synthesis and
+cross-scope judgment in the root caller.
+
+## Catalog Evidence
+
+A catalog snapshot belongs to one dispatch context. A root native catalog does
+not establish a nested coordinator's catalog, and a provider CLI account
+catalog does not establish native eligibility.
+
+Before explicit selection:
+
+1. Observe selectors exposed to the dispatcher that will launch the child.
+2. Observe role or agent-type selectors when exposed before selection.
+3. Record catalog source, context, and observation time.
+4. Intersect configured candidates allowed by policy and ceiling with that
+   catalog, preserving exact provider strings.
+5. Keep volatile observations out of durable configuration unless the user
+   explicitly changes the owning configuration.
+
+Do not launch a diagnostic child solely to obtain a catalog the provider
+cannot expose before selection. Record the visibility timing instead.
+
+## Full-Information Selection
+
+For every dispatch:
+
+1. Validate the caller request and capability state.
+2. Resolve provider, context, role class, policy, ceiling, and candidates.
+3. Observe the launching dispatcher's relevant catalogs.
+4. Compute the exact native intersection.
+5. Select one native, inherited, provider-CLI, workflow, gate, or blocked route
+   before launch.
+6. Build the complete redacted payload.
+7. Record route, selection reason, candidates, catalog source, authority, and
+   deadline.
+8. Launch once.
+9. Record launch acceptance separately from child outcome and runtime identity.
+
+```mermaid
+flowchart TD
+  A[Validate bounded request] --> B[Observe dispatcher catalogs]
+  B --> C[Intersect policy candidates with live selectors]
+  C --> D{Satisfactory native target?}
+  D -->|Yes| E[Build exact native payload]
+  D -->|No| F{Deliberate inheritance allowed?}
+  F -->|Yes| G[Build inherited payload]
+  F -->|No| H{Exact alternate route selected pre-start?}
+  H -->|Yes| I[Build external payload]
+  H -->|No| J[Block]
+  E --> K[Record then launch once]
+  G --> K
+  I --> K
+  K --> L{Accepted?}
+  L -->|No| M[Record pre-start rejection]
+  L -->|Yes| N[Record outcome; no replacement]
+```
+
+## Homogeneous Recon Waves
+
+Multiple read-only recon lanes may share one selection record only when all of
+these axes are identical: provider, dispatch context, catalog snapshot,
+selected route, role class, role selector, model, effort, authority, deadline,
+retry limit, and fallback. Include a lane manifest with lane-specific scope,
+acceptance, and outcome.
+
+If any axis differs, create separate records. The record-level scope is the
+aggregate wave boundary; each lane may narrow that boundary.
+
+## Acceptance and Recovery
+
+- An accepted launch is terminal for automatic replacement eligibility.
+- Completion, failure, timeout, interruption, `BLOCKED`, and contract refusal
+  are post-acceptance outcomes; none makes another route eligible.
+- A wrapper failure or payload rejection before child start is a pre-start
+  rejection. A new recorded selection is allowed only within caller retry
+  policy.
+- Continuing the same accepted child through its valid handle is allowed.
+  Record continuation separately and preserve selectors and route.
+- Operator-authorized recovery is a new explicit action, never automatic
+  fallback.
+- Runtime identity is optional corroboration. Missing runtime identity does not
+  invalidate launcher-owned configured invocation evidence.
+
+## Return Contract
+
+Return the structured record plus the child output or blocking diagnostic to
+the caller. Do not write caller artifacts, reinterpret results, or make user
+decisions. The caller verifies claims before depending on them.
+
+Use the schema in `references/record-schema.md`. Existing parseable dispatch
+stamps may remain for compatibility, but they do not replace the structured
+record.

package/assets/skills/oat-dispatch-subagents/references/provider-claude.md

@@ -0,0 +1,44 @@
+# Claude Subagent Dispatch
+
+Load this reference only when the active provider is Claude. Current
+user-level or repository instructions override model examples in this file.
+
+## Control Surfaces
+
+| Surface           | Controls                                   | Qualification                                          |
+| ----------------- | ------------------------------------------ | ------------------------------------------------------ |
+| Native agent tool | Agent type plus optional model             | Effort may not be exposed on this surface.             |
+| Agent definition  | Default model in frontmatter               | Between explicit call selection and inheritance.       |
+| Workflow agent    | Agent type, model, and effort when exposed | Use only controls present in the live schema.          |
+| `claude -p`       | Alias or full model ID plus CLI effort     | Verify current CLI help before constructing a route.   |
+| Continuation      | Existing child handle through message send | Preserves context; a new launch creates another child. |
+
+Native model resolution commonly follows explicit call model, agent-definition
+model, then parent/session inheritance. Treat omission as a deliberate
+inheritance selection. Never omit a worker model when inheritance is not the
+recorded policy.
+
+## Native Topology
+
+Use economical workers for bounded reconnaissance and stronger workers for
+context-heavy dossiers or subtle decisions. Keep cross-dossier synthesis and
+user dialogue in the root caller. A dossier lead may coordinate bounded recon
+only when the live host supports nesting and the caller declared it.
+
+The current nested model enum may be visible before selection while nested
+agent types become visible later. Read what the dispatcher exposes, use only a
+known role from the active contract when a pre-call role list is unavailable,
+and record visibility timing. Do not launch a diagnostic child solely to
+satisfy a universal catalog rule.
+
+## Surface-Aware Selection
+
+- Select an exact accepted alias from the native enum for native dispatch.
+- Select a CLI route before launch when a full model ID or explicit effort is
+  required and native controls cannot express it.
+- Record selector granularity such as `tier-alias` or `exact-model-id`.
+- Record native effort as `not-exposed`, not globally `not-applicable`.
+- Keep acceptance, outcome, runtime identity, and continuation separate.
+
+Verify current `claude --help` before using a CLI route. Preserve the caller's
+authority and construct a self-contained bounded prompt.

package/assets/skills/oat-dispatch-subagents/references/provider-codex.md

@@ -0,0 +1,69 @@
+# Codex Subagent Dispatch
+
+Load this reference only when the active provider is Codex. Current user-level
+or repository instructions override model examples in this file.
+
+## Independent Controls
+
+Codex may expose independent native controls for:
+
+- registered agent type;
+- model and reasoning effort;
+- service tier and forked context;
+- maximum nesting depth;
+- sandbox and scoped writable roots.
+
+A materialized role may package defaults, but preserve role, model, effort,
+service tier, fork behavior, and authority as separate configured axes.
+
+## Native Topology
+
+When subagents are available, keep judgment in the root caller and delegate
+bounded volume. A dossier lead may dispatch its own recon workers only when the
+effective nesting depth permits it and the caller declared that topology.
+
+Before a write-capable launch, verify the minimum scoped writable roots needed
+for the task, shared Git metadata, and managed output. Native nesting does not
+grant filesystem authority.
+
+## Exact Native Selection
+
+1. Read live registered roles and model/effort selectors.
+2. Read effective depth and sandbox configuration.
+3. Resolve one configured candidate allowed by policy and ceiling.
+4. Use the exact registered role as `agent_type` only when guaranteed by the
+   live host.
+5. Use the fork mode allowed by the live schema for explicit overrides.
+6. Record materialized configuration and live schema as distinct sources.
+
+Prefer economical high-effort workers for narrow, independently verifiable
+recon. Move to a context-heavier worker when success depends on reconciling
+dispersed evidence, and to a stronger reasoning route when ambiguity,
+consequence, or adversarial analysis dominates. Do not escalate merely because
+many files must be searched.
+
+Native spawn acceptance is configured-invocation evidence. Missing runtime
+model identity does not invalidate an accepted configured payload.
+
+Only an actual role-selection rejection before child start permits another
+recorded route. Timeout, interruption, `BLOCKED`, or task failure after
+acceptance does not.
+
+## CLI Route
+
+When native dispatch cannot express the complete target and the route is
+selected before launch, use current `codex exec --help` to construct a
+self-contained invocation. A typical read-only shape is:
+
+```sh
+codex exec \
+  --ephemeral \
+  --sandbox read-only \
+  --model '<model>' \
+  -c 'model_reasoning_effort="<effort>"' \
+  '<self-contained bounded prompt>'
+```
+
+Honor the caller's authorization boundary. Record model, effort, sandbox, and
+route as configured invocation evidence; do not infer runtime identity from a
+successful process alone.

package/assets/skills/oat-dispatch-subagents/references/provider-cursor.md

@@ -0,0 +1,61 @@
+# Cursor Subagent Dispatch
+
+Load this reference only when the active provider is Cursor. Cursor IDE and
+Cursor CLI are separate harness contexts. Treat every observed catalog as a
+volatile snapshot, never a durable inventory.
+
+## Control Surfaces
+
+| Source                       | Establishes                                               | Does not establish                                             |
+| ---------------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
+| Native Task/Subagent schema  | Roles and opaque selectors for that dispatcher invocation | CLI account eligibility or another dispatcher's native catalog |
+| `cursor-agent --list-models` | Opaque selectors accepted by the account CLI              | Native Task eligibility                                        |
+| Cursor UI role configuration | User-selected defaults and role settings                  | Live root or nested schema without a new observation           |
+
+Root and nested catalogs are independent, volatile observations. Equality in
+one run does not establish equality in another run or nesting boundary.
+
+## Native Selection
+
+1. Read the native model enum from the dispatcher that will launch the child.
+2. Intersect configured candidates with that exact snapshot.
+3. Pass the selected opaque string byte-for-byte.
+4. Treat an omitted model as deliberate parent inheritance, not generic
+   defaulting or evidence that a target was unavailable.
+5. Record requested selector, acceptance, outcome, and runtime identity
+   separately.
+
+Do not infer Cursor IDE behavior from a headless CLI surface. Keep bounded
+recon on economical explicit targets and reserve stronger targets for
+context-heavy or consequential work.
+
+## Pre-Start CLI Routes
+
+When the current native intersection is absent or unsatisfactory, a caller may
+use a deliberate pre-start CLI route only when:
+
+- the caller's fallback policy allows it;
+- the exact CLI selector exists in the account catalog;
+- native mismatch, route, reason, and candidates are recorded before launch;
+- the prompt is self-contained and authority-bounded.
+
+Verify current CLI help before use. A typical shape is:
+
+```sh
+cursor-agent \
+  --trust \
+  --print \
+  --model '<exact-opaque-model>' \
+  '<self-contained bounded prompt>'
+```
+
+CLI completion proves configured invocation completion. It does not prove an
+inner native selection or runtime model identity.
+
+## Catalog-Mismatch Advisory
+
+Report configured candidates missing from the current native catalog, nearby
+native candidates as possible ladder additions, selected route, and the exact
+observation boundary. Do not remove CLI-capable candidates solely because the
+native surface cannot pin them, and do not write observed catalogs into durable
+configuration without explicit user choice.