@open-agent-toolkit/cli 0.1.52 → 0.1.53

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

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

@@ -0,0 +1,100 @@
+# Dispatch Record Schema
+
+Load this reference only when constructing or validating dispatch evidence.
+Use neutral scope, action, role, and authority fields. Calling workflows may
+add namespaced metadata without redefining these fields.
+
+## Request
+
+```yaml
+request_id: dispatch-unique-id
+caller: oat-repo-improve
+scope: repo:packages/cli
+objective: Audit CLI correctness hotspots
+action: analysis
+role:
+  name: repo-audit-scout
+  class: recon
+provider: codex
+dispatch_context: root-native
+dispatch_policy: economy
+dispatch_ceiling: high
+authority: read-only
+expected_output: structured-findings
+verification_evidence: file-line-references
+deadline_seconds: 300
+retry_limit: 1
+authorization_scope: this-audit-run
+fallback:
+  mode: explicit-downgrade
+  target: reduced-quick-audit
+escalate_when:
+  - evidence requires cross-package reconciliation
+  - security impact is consequential
+```
+
+`dispatch_policy` and `dispatch_ceiling` are optional resolved inputs. The
+general engine does not resolve their source.
+
+## Record
+
+```yaml
+request_id: dispatch-unique-id
+caller: oat-repo-improve
+scope: repo:packages/cli
+objective: Audit CLI correctness hotspots
+action: analysis
+role_name: repo-audit-scout
+role_class: recon
+provider: codex
+dispatch_context: root-native
+dispatch_policy: economy
+dispatch_ceiling: high
+catalog_snapshot:
+  id: root-native-1
+  source: tool-schema
+  observed_at: 2026-07-12T00:00:00Z
+authority: read-only
+role_selector: oat-recon-worker
+model_selector: opaque-provider-selector
+model_selector_granularity: opaque
+effort_selector: economical
+selection_source: explicit-call
+candidates_considered:
+  - opaque-provider-selector
+selection_reason: native-catalog
+selected_route: native
+deadline_seconds: 300
+retry_limit: 1
+payload: {}
+launch_status: accepted
+child_outcome: completed
+configured_invocation_evidence: []
+runtime_confirmation: not-reported
+diagnostics: []
+continuation_events: []
+```
+
+`role_selector` is the exact provider or harness agent-type selector, when that
+surface exists. Preserve opaque selectors byte-for-byte.
+
+## Recon Wave
+
+```yaml
+wave_id: repo-audit-wave-1
+scope: repo:packages/cli
+shared_dispatch_record: dispatch-unique-id
+lanes:
+  - lane_id: correctness
+    scope: packages/cli/src
+    launch_status: accepted
+    child_outcome: completed
+  - lane_id: security
+    scope: packages/cli/src
+    launch_status: accepted
+    child_outcome: completed
+```
+
+The wave scope is the aggregate boundary. Lane scope may narrow it. Use one
+shared record only when every dispatch axis listed in the main skill is
+identical.