@open-agent-toolkit/cli 0.1.52 → 0.1.54

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/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

package/assets/docs/workflows/skills/index.md

@@ -11,6 +11,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 - [Writing Skills](../../contributing/skills.md) - Contributor guide to skill authoring, contracts, and governance.
 - [Docs Workflows](../../docs-tooling/workflows.md) - How docs CLI helpers and docs skills work together.
+- [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
 
 ## Key Skills by Use Case
 
@@ -23,6 +24,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
+- Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
 - Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Research a topic in depth: `deep-research`
@@ -99,6 +101,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-review-receive-remote`
     - `oat-repo-knowledge-index`
     - `oat-repo-maintainability-review`
+    - `oat-repo-improve`
     - `oat-pjm-add-backlog-item`
     - `oat-pjm-update-repo-reference`
     - `oat-pjm-review-backlog`

package/assets/docs/workflows/skills/repo-improve.md

@@ -0,0 +1,45 @@
+---
+title: Repo Improve
+description: 'Turn repository audits, maintainability reviews, and backlog sources into standalone external implementation plans.'
+---
+
+# Repo Improve
+
+Use `oat-repo-improve` when the desired output is an executable implementation plan rather than another analysis report. Every successful run writes one or more standalone plans under `.oat/repo/reference/external-plans/`.
+
+## Choose a source
+
+| Source                 | Use it when                                                                                                                                          |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Repo audit             | You need fresh repository reconnaissance and vetted improvement findings.                                                                            |
+| Maintainability review | A file-backed `oat-repo-maintainability-review` already identifies candidates. Improve verifies selected evidence without repeating the broad audit. |
+| Backlog review         | A living backlog review and optional priority alignment already establish value, dependencies, and sequencing.                                       |
+| Backlog directory      | You want to start from active items. Substantive backlogs should pass through backlog review and alignment before plan generation.                   |
+| Backlog item           | One existing item needs enough repository investigation to become executable.                                                                        |
+
+With no source argument, the skill probes for available review and backlog artifacts, annotates all five options, and asks which source to use.
+
+## 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.
+
+After generation, choose either execution path:
+
+- Execute a plan directly as a standalone handoff.
+- Run `oat-project-import-plan <external-plan-path>` to preserve and normalize one plan for tracked OAT execution.
+
+Project-sized candidates are split when possible. If inseparable work needs multiple design decisions or lacks one coherent verification boundary, improve recommends an OAT project workflow instead of emitting a mega-plan.
+
+## Optional tracking
+
+Plans are always the primary output. Tracking is optional and source-aware:
+
+- `--backlog-items` creates missing PJM items for repo-audit or maintainability-review plans. Backlog-backed sources reuse their existing items and add `external_plans` reverse links.
+- `--issues` previews one GitHub issue per plan, checks repository visibility and sensitive content, and requires explicit confirmation before publication. It is useful as a fallback when PJM is not installed.
+- Request both modifiers explicitly to create both forms. Neither implies the other.
+
+Failure to publish a backlog item or issue does not invalidate a successfully written plan; the skill reports partial tracking results precisely.
+
+## Orchestration
+
+Full repository audits use `oat-dispatch-subagents` for bounded read-only reconnaissance while the root agent retains vetting, prioritization, and plan writing. Dispatch is native-first. Configured project/workflow policy may authorize required CLI or cross-runtime routes; an agent-improvised alternate route requires explicit current-run approval.

package/assets/public-package-versions.json

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

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

@@ -0,0 +1,254 @@
+---
+name: oat-dispatch-subagents
+version: 1.1.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;
+- route-selection source for any non-native route;
+- 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.
+
+## Native-First Route Selection
+
+Use these route tiers:
+
+1. **Native same-runtime:** Always the preferred default when it can satisfy
+   the resolved role, model, effort, authority, and isolation requirements. It
+   needs no additional authorization.
+2. **Policy-resolved CLI/programmatic or cross-runtime:** Permitted without a
+   per-run prompt when configured dispatch policy selected the route. Project
+   policy resolved by `oat-project-dispatch-subagents` and configured
+   cross-family gates are standing, scope-bound authorization. Some harnesses
+   require this tier—for example Cursor task subagents when native model
+   availability cannot satisfy the resolved project target.
+3. **Agent-improvised CLI/programmatic or cross-runtime:** Prohibited unless
+   the user explicitly approves the named target and scope for the current
+   run. Approval from a prior run, task, branch reset, or materially different
+   scope does not carry forward.
+
+Availability of a provider CLI, SDK, API, or other programmatic surface is
+capability evidence, not route authorization. The engine must distinguish a
+policy-resolved alternate route from one proposed by the agent. If neither
+configured policy nor current explicit approval authorizes the alternate
+route, use an eligible native route or block.
+
+Do not re-prompt for each task or gate when the caller provides a complete
+policy-resolved route and scope. Record `selection_source: policy-resolved`
+with the owning configuration evidence. Use
+`selection_source: explicit-user` for a current-run operator grant and
+`selection_source: native-default` for the preferred native route.
+
+## Dispatch Axes
+
+Keep these controls independent in selection and evidence:
+
+- dispatch context: root native, nested native, provider CLI/programmatic,
+  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. Prefer an eligible native route. Otherwise select one policy-resolved or
+   explicitly authorized inherited, provider-CLI/programmatic, workflow, gate,
+   or blocked route before launch.
+6. Build the complete redacted payload.
+7. Record route, selection source, 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.