@open-agent-toolkit/cli 0.2.2 → 0.2.4

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

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.1.4
+version: 1.1.5
 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
@@ -76,6 +76,19 @@ Require the caller to provide:
 - route-selection source for any non-native route;
 - optional resolved dispatch policy or named ceiling.
 
+The caller may also provide `task_class`, `classification_source`, and
+`classification_reason`. This task-class metadata is optional for existing
+generic callers. When supplied, all three fields are required:
+
+- `task_class`: `mechanical-recon`, `intelligent-recon`,
+  `default-implementation`, `hard-reasoning`, or `consequential`;
+- `classification_source`: the literal `caller`; and
+- `classification_reason`: a non-empty artifact-informed rationale.
+
+The caller owns classification. `oat-reviewer` requires these fields for every
+reviewer-local reconnaissance lane; other callers that omit them retain
+role-based selection behavior and records without class-floor fields.
+
 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
@@ -169,19 +182,55 @@ or a second launch.
 
 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.                                       |
+| Class          | Default contract                                                                                                                                                                                                                          |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `recon`        | Read-only, bounded evidence collection. Meet any supplied `task_class` / `model_class_floor` at or above the floor; select an explicit economical target only when no task-class floor was supplied. Never silently inherit a 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.
 
+## Task Classes and Model Floors
+
+Role class and task class are independent. Role class controls authority and
+output ownership; task class is the minimum model-capability floor for one
+bounded objective. A `role.class: recon` worker remains read-only and advisory
+at every task class.
+
+Classify by deterministic verifiability, silent-miss risk, dispersed context,
+ambiguity, and consequence, in that order. File count alone never justifies
+escalation:
+
+| Task class               | Minimum capability contract                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `mechanical-recon`       | Deterministic inventories, parity checks, or test/lint/format/build execution whose misses are visible. |
+| `intelligent-recon`      | Interpretation, unfamiliar-code auditing, or policy/semantic evidence where a miss could be silent.     |
+| `default-implementation` | Retain and reconcile dispersed context inside one independently bounded scope.                          |
+| `hard-reasoning`         | Ambiguity, novelty, architecture analysis, or competing interpretations dominate.                       |
+| `consequential`          | Security, release safety, irreversible impact, adversarial analysis, or expensive failure dominates.    |
+
+Mechanical workers may execute checks and return exact output. Interpretation
+and policy judgment require a stronger class or stay with the root caller. When
+uncertain between classes, use the stronger floor.
+
+For unconstrained legacy recon with no `task_class` supplied, select an
+explicit economical target rather than silently inheriting the root model.
+Class-constrained recon must select a target at or above the supplied
+`model_class_floor`; otherwise set `floor_satisfaction: unsatisfied` and return
+the lane through `caller-inline`. An economical target is not a universal
+baseline for the `recon` role.
+
+Resolve current class examples through active user and repository instructions
+first, then the active-provider reference and live catalog, all constrained by
+the supplied policy and ceiling. Provider-reference model names are dated
+examples, not canonical requirements. Select an exact eligible target at or
+above the requested floor; never silently downgrade.
+
 ## Catalog Evidence
 
 A catalog snapshot belongs to one dispatch context. A root native catalog does
@@ -206,9 +255,11 @@ cannot expose before selection. Record the visibility timing instead.
 For every dispatch:
 
 1. Validate the caller request and capability state.
-2. Resolve provider, context, role class, policy, ceiling, and candidates.
+2. Resolve provider, context, role class, optional task class and model-class
+   floor, policy, ceiling, and candidates.
 3. Observe the launching dispatcher's relevant catalogs.
-4. Compute the exact native intersection.
+4. Compute the exact native intersection at or above the supplied task-class
+   floor, when present.
 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.
@@ -239,14 +290,38 @@ flowchart TD
 
 ## Homogeneous Recon Waves
 
+A homogeneous wave may share one record only when `task_class` and
+`model_class_floor` match in addition to every existing dispatch axis.
 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.
+retry limit, fallback, `task_class`, and `model_class_floor`. Include a lane
+manifest with lane-specific scope, acceptance, and outcome. A recon-wave record
+repeats the shared `task_class` and `model_class_floor` beside
+`shared_dispatch_record`; lane entries do not redefine them.
+
+If any axis differs or either class field does not match, create separate
+records and waves. The record-level scope is the aggregate wave boundary; each
+lane may narrow that boundary.
+
+## Class-Constrained Fallback
+
+For a request with task-class metadata, record `model_class_floor` equal to
+`task_class` and set `floor_satisfaction` to `satisfied` or `unsatisfied`.
+An unsatisfied floor blocks launch and returns control to the caller; it never
+records a weaker selection as success.
+
+Reviewer-local requests use:
+
+```yaml
+fallback:
+  mode: caller-inline
+  allow_below_task_class_floor: false
+```
 
-If any axis differs, create separate records. The record-level scope is the
-aggregate wave boundary; each lane may narrow that boundary.
+Below-floor selection is prohibited. The legacy `explicit-downgrade` fallback
+remains available only to unconstrained callers without task-class metadata or
+a declared class floor.
 
 ## Acceptance and Recovery
 

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

@@ -31,6 +31,27 @@ 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.
 
+## Task-Class Resolution
+
+Apply active user and repository instructions first; they override the dated
+model-family examples in this provider reference. Intersect the resulting
+class guidance with the live native model enum and the supplied policy and
+ceiling. Select one exact accepted alias at or above the requested floor:
+
+- `mechanical-recon`: the fastest economical class suitable for deterministic
+  inventories, parity, and command execution;
+- `intelligent-recon`: a stronger fast class that can interpret unfamiliar
+  code, semantics, and silent-miss-prone evidence;
+- `default-implementation`: a context-retentive implementation class for
+  independently bounded dossier work;
+- `hard-reasoning`: a strong reasoning class for ambiguity or architecture;
+- `consequential`: the strongest allowed class for security, release safety,
+  irreversible impact, or expensive failure.
+
+A stale or unavailable named example requires a newer eligible model meeting
+the same class floor or a route one class up. Selection below the floor is
+prohibited. Record the exact selector and `floor_satisfaction`.
+
 ## Surface-Aware Selection
 
 - Select an exact accepted alias from the native enum for native dispatch.

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

@@ -42,6 +42,28 @@ 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.
 
+## Task-Class Resolution
+
+Apply active user and repository instructions first; they override the dated
+model-family examples in this provider reference. Intersect that guidance with
+the live model/effort selectors, registered roles, supplied policy and ceiling,
+and requested class floor:
+
+- `mechanical-recon`: an economical class and effort suitable for
+  deterministic inventories, parity, and command execution;
+- `intelligent-recon`: a stronger fast class for interpretation,
+  unfamiliar-code auditing, and silent-miss-prone evidence;
+- `default-implementation`: a context-retentive implementation class for an
+  independently bounded dossier;
+- `hard-reasoning`: a strong reasoning class for ambiguity or architecture;
+- `consequential`: the strongest allowed class for security, release safety,
+  irreversible impact, or expensive failure.
+
+A stale or unavailable named example requires a newer eligible model meeting
+the same class floor or a route one class up. Selection below the floor is
+prohibited. Keep model and reasoning effort as separate recorded axes, and
+record `floor_satisfaction`.
+
 Native spawn acceptance is configured-invocation evidence. Missing runtime
 model identity does not invalidate an accepted configured payload.
 

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

@@ -15,15 +15,37 @@ volatile snapshot, never a durable inventory.
 Root and nested catalogs are independent, volatile observations. Equality in
 one run does not establish equality in another run or nesting boundary.
 
-## Native Selection
-
-Managed Cursor dispatch resolves an opaque flat model ID through OAT's explicit
-mapping and returns `providers.cursor.dispatchArgs.variant`. The mapping owns
-the bracket-form model pin inside the materialized definition; skills must
-never parse, normalize, or reconstruct either model string.
-
-1. Require a non-empty `providers.cursor.dispatchArgs.variant`.
-2. Launch that exact resolver-selected native agent type first.
+## Task-Class Resolution
+
+Apply active user and repository instructions first; they override the dated
+model-family examples in this provider reference. Intersect that guidance with
+the exact model choices advertised by the dispatcher, the supplied policy and
+ceiling, and the requested class floor:
+
+- `mechanical-recon`: the fastest economical class suitable for deterministic
+  inventories, parity, and command execution;
+- `intelligent-recon`: a stronger fast class for interpretation,
+  unfamiliar-code auditing, and silent-miss-prone evidence;
+- `default-implementation`: a context-retentive implementation class for an
+  independently bounded dossier;
+- `hard-reasoning`: a strong reasoning class for ambiguity or architecture;
+- `consequential`: the strongest allowed class for security, release safety,
+  irreversible impact, or expensive failure.
+
+A stale or unavailable example requires a newer eligible model meeting the
+same class floor or a route one class up. Selection below the floor is
+prohibited.
+
+## Outer Lifecycle Native Selection
+
+Outer lifecycle implementer and reviewer dispatch uses the exact
+`providers.cursor.dispatchArgs.variant` returned by the lifecycle resolver.
+The resolver maps an opaque flat model ID and owns the bracket-form model pin
+inside the materialized definition; skills never parse, normalize, or
+reconstruct either model string.
+
+1. Require a non-empty resolver-returned variant for managed dispatch.
+2. Launch that exact native agent type first.
 3. Treat native launch acceptance plus the complete launcher payload as
    configured-invocation evidence, not observed runtime model identity.
 4. Permit a replacement route only after a recorded pre-start native
@@ -36,9 +58,34 @@ never parse, normalize, or reconstruct either model string.
 7. Record selected variant, mapped target, acceptance, outcome, and runtime
    identity separately.
 
+## Reviewer-Local Nested Selection
+
+Reviewer-local recon uses `generalPurpose` with an
+`exact-native-model-choice` selector.
+Reviewer-local reconnaissance is a separate nested native surface. It does not
+use the lifecycle resolver because no materialized lifecycle `recon` role
+exists.
+
+1. Read the model choices advertised by the nested Task/Subagent dispatcher.
+2. Intersect those advertised model choices with active user and repository
+   model-class instructions, this provider reference, the supplied
+   policy/ceiling, and the requested `model_class_floor`.
+3. Use the native `generalPurpose` agent type and pass the exact model choice
+   advertised by the current nested dispatcher byte-for-byte.
+4. Record the selector as `model_selector` with
+   `model_selector_granularity: exact-native-model-choice`.
+5. Treat an omitted model as deliberate parent inheritance only for an
+   unconstrained caller whose recorded policy permits inheritance. A
+   class-constrained reviewer lane never omits the model.
+
+This nested path does not call the lifecycle resolver, parse bracket-form
+model pins, or reconstruct a lifecycle variant. If no exact nested selector
+satisfies the floor, record `floor_satisfaction: unsatisfied` and return the
+lane for caller-inline coverage without launching a weaker worker.
+
 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.
+mechanical recon on economical explicit targets. Stronger lanes use a
+floor-satisfying target when advertised or stay with the primary reviewer.
 
 ## Dispatch Mode and Liveness
 
@@ -63,13 +110,17 @@ verdict.
 
 ## Pre-Start CLI Routes
 
-When exact native role selection rejects the resolver-selected variant before
-launch, a caller may use a deliberate pre-start CLI route only when:
+Any native mismatch is recorded before launch with the route, reason, and
+candidate set.
+
+When exact outer lifecycle role selection rejects the resolver-selected
+variant before launch, or a generic caller's current native intersection is
+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;
-- the native mismatch, rejected variant, route, reason, and candidates are
-  recorded before launch;
+- the native mismatch, rejected variant when applicable, 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:

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

@@ -37,6 +37,28 @@ escalate_when:
 `dispatch_policy` and `dispatch_ceiling` are optional resolved inputs. The
 general engine does not resolve their source.
 
+Task-class metadata is also generic-optional. A class-constrained caller adds
+all of these fields; `oat-reviewer` requires them for reviewer-local recon:
+
+```yaml
+task_class: intelligent-recon
+classification_source: caller
+classification_reason: >-
+  Determining whether semantic tests pin safety boundaries requires
+  interpretation, and a silent miss would survive mechanical checks.
+fallback:
+  mode: caller-inline
+  allow_below_task_class_floor: false
+```
+
+`task_class` is one of `mechanical-recon`, `intelligent-recon`,
+`default-implementation`, `hard-reasoning`, or `consequential`.
+`classification_source` is the literal `caller`, and
+`classification_reason` is non-empty. Legacy callers may omit all three and
+retain the original role-based selection and fallback behavior. The legacy
+`explicit-downgrade` example above is valid only for an unconstrained request
+without task-class metadata or a declared class floor.
+
 ## Record
 
 ```yaml
@@ -76,6 +98,41 @@ diagnostics: []
 continuation_events: []
 ```
 
+For a class-constrained dispatch, the record also includes:
+
+```yaml
+task_class: intelligent-recon
+model_class_floor: intelligent-recon
+classification_source: caller
+classification_reason: Semantic contract interpretation has silent-miss risk.
+floor_satisfaction: satisfied
+```
+
+`model_class_floor` equals the requested `task_class`.
+`floor_satisfaction` is `satisfied` or `unsatisfied`. An unsatisfied floor
+blocks launch and records no weaker selection as success. These five fields
+remain absent when a legacy request omits task-class metadata.
+
+For a Cursor reviewer-local request whose advertised nested model choices do
+not satisfy the class floor, record the blocked selection without inventing a
+selector:
+
+```yaml
+role_selector: generalPurpose
+model_selector: null
+model_selector_granularity: exact-native-model-choice
+floor_satisfaction: unsatisfied
+fallback:
+  mode: caller-inline
+  allow_below_task_class_floor: false
+launch_status: blocked-before-start
+child_outcome: caller-inline-completed
+```
+
+`exact-native-model-choice` means an exact model choice advertised by the
+current nested dispatcher. It does not imply a stable enum or authorize
+reconstruction of a materialized lifecycle variant.
+
 `role_selector` is the exact provider or harness agent-type selector, when that
 surface exists. Preserve opaque selectors byte-for-byte.
 
@@ -98,6 +155,8 @@ selection source.
 wave_id: repo-audit-wave-1
 scope: repo:packages/cli
 shared_dispatch_record: dispatch-unique-id
+task_class: intelligent-recon
+model_class_floor: intelligent-recon
 lanes:
   - lane_id: correctness
     scope: packages/cli/src
@@ -110,5 +169,7 @@ lanes:
 ```
 
 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.
+shared record only when every dispatch axis listed in the main skill,
+`task_class`, and `model_class_floor` are identical. Lane entries do not
+redefine the shared class fields. Mixed classes require separate records and
+waves.