@open-agent-toolkit/cli 0.2.13 → 0.2.15

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.1.0
+version: 1.1.1
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -97,7 +97,7 @@ These messages get a direct response, not a workflow takeover. If the model has
 
 - Free-form exploratory conversation, one question at a time, multiple-choice when possible, 2-3 distinct approaches with a recommendation.
 - Per-question visual-companion routing (browser for visual content, terminal for text).
-- Pack and active-project detection at convergence time (`oat config get tools.<pack>` / `oat config get activeProject`).
+- Pack and active-project detection at convergence time (`oat tools has <pack>` / `oat config get activeProject`).
 - Reading downstream skill files (`oat-idea-*`, `oat-pjm-add-backlog-item`, `oat-project-*`) and following their process inline using the synthesized payload as pre-filled answers.
 - Rendering the doc-to-path artifact from `templates/brainstorm-doc.md`.
 - Active-project fold-back: appending synthesis to the chosen upstream artifact and committing — only after the safety contract (preflight, scoped staging, conditional handoff print) is satisfied.
@@ -135,7 +135,7 @@ These indicators apply only on Hard Activation (see `## Activation Contract`). O
   - `Activating brainstorm mode…`
   - `Asserting mode (blocked / allowed)…`
   - `Assessing visual need…`
-  - `Detecting installed packs and active project…`
+  - `Detecting available packs and active project…`
   - `Free brainstorming (Superpowers cadence)…`
   - `Watching for destination signals…`
   - `Satisfaction check…`
@@ -156,7 +156,7 @@ Apply the **Activation Contract**. The full Process flow (Steps 2-9) only runs o
 
 When Hard Activation triggers, the user has not already named a destination skill or artifact type. Do not route those blank-slate brainstorms to `oat-idea-ideate` merely because they may later become an idea, backlog item, project, or document.
 
-There are no preconditions to check at activation — pack detection and active-project detection happen at step 4, after visual-need assessment, so this skill works in any repo regardless of which OAT packs are installed.
+There are no preconditions to check at activation — pack detection and active-project detection happen at step 4, after visual-need assessment, so this skill works in any repo regardless of which OAT packs are available.
 
 **Soft Exploratory Path** (per Activation Contract): respond conversationally with brainstorm-quality structure (options, tradeoffs, open questions, no premature implementation, no destination guess). Do not print the banner, assert mode, run pack detection, or offer the visual companion. Track an exploratory-turn counter for the thread; on the 2nd+ consecutive exploratory turn with no concrete action requested, append the soft offer once: "If you want, I can switch into structured brainstorm mode for this." If the user accepts, transition to Hard Activation and re-enter Step 2.
 
@@ -216,9 +216,9 @@ The `active`, `declined`, and `unavailable` decisions apply for the rest of the
 Run pack-detection and active-project resolution **once** per session, before the conversation starts. Mirrors the convention used by `oat-project-document`.
 
 ```bash
-IDEAS_INSTALLED=$(oat config get tools.ideas 2>/dev/null || echo "false")
-PJM_INSTALLED=$(oat config get tools.project-management 2>/dev/null || echo "false")
-WORKFLOWS_INSTALLED=$(oat config get tools.workflows 2>/dev/null || echo "false")
+IDEAS_INSTALLED=$(oat tools has ideas 2>/dev/null || echo "false")
+PJM_INSTALLED=$(oat tools has project-management 2>/dev/null || echo "false")
+WORKFLOWS_INSTALLED=$(oat tools has workflows 2>/dev/null || echo "false")
 ACTIVE_PROJECT=$(oat config get activeProject 2>/dev/null || echo "")
 
 ACTIVE_PROJECT_VALID="false"
@@ -626,7 +626,7 @@ End mode assertion when the split handoff completes or reports its own blocker.
 - ✅ Phase banner `OAT ▸ BRAINSTORM` is printed exactly once at activation; mode assertion follows immediately.
 - ✅ Visual-companion offer is conditional on visual need, not Node availability alone. Text-likely brainstorms set `VISUAL_COMPANION = "deferred"` and continue without mentioning the companion.
 - ✅ When a visual-companion offer is made, it is its own message with no other content. The offer is suppressed entirely (no message printed) when `node` is not on PATH.
-- ✅ Pack and active-project detection (`oat config get tools.<pack>` and `oat config get activeProject`) runs once per session at step 4, before the conversation starts.
+- ✅ Pack and active-project detection (`oat tools has <pack>` and `oat config get activeProject`) runs once per session at step 4, before the conversation starts.
 - ✅ Conversation cadence holds the Superpowers contract: one question at a time, multiple-choice preferred, 2-3 distinct approaches with a recommendation, per-question visual-companion routing.
 - ✅ Destination is identified via either trigger-phrase opportunistic surfacing (loose substring + paraphrase tolerance, not regex; ambiguity → ask) or convergence cue (pack-filtered terminal-state picker).
 - ✅ The terminal-state picker conditionally includes `Promote to N projects` only when `oat project split evaluate-signals` reports `triggered: true`; small-scope convergence keeps the option hidden.

package/assets/skills/oat-brainstorm/references/destinations.md

@@ -47,7 +47,7 @@ Always honor an explicit user-supplied path over the suggestion. Brainstorm docs
 
 ### Destination: Capture as new idea
 
-**Pack required:** `ideas` (i.e., `oat config get tools.ideas` returns `true`)
+**Pack required:** `ideas` (i.e., `oat tools has ideas` returns `true`)
 **Trigger phrases:** "capture as an idea", "this is an idea worth keeping", "let's track this as an idea", "save this as an idea", "make a new idea for this".
 **Required template fields:** `title` (slug-friendly), `summary`, `motivation` (Why Is It Interesting?), `vision` (What Would It Look Like?), `transcriptSessionNote`. Template: `.oat/templates/ideas/idea-discovery.md` (consumed via `oat-idea-new`).
 **Optional template fields:** `approachesConsidered`, `chosenDirection`, `openQuestions`, `nextSteps`.
@@ -83,7 +83,7 @@ Always honor an explicit user-supplied path over the suggestion. Brainstorm docs
 
 ### Destination: Scoped backlog item
 
-**Pack required:** `project-management` (i.e., `oat config get tools.project-management` returns `true`)
+**Pack required:** `project-management` (i.e., `oat tools has project-management` returns `true`)
 **Trigger phrases:** "track this as a backlog item", "make a ticket", "log this", "open a backlog entry", "add this to the backlog", "create a backlog item for this".
 **Required template fields:** `title` (1-line summary), `description` (problem + proposed approach), `acceptance criteria` (bullet list), `scope` (xs / s / m / l / xl), `priority` (p0 / p1 / p2 / p3). Template: `.oat/templates/backlog-item.md` (consumed via `oat-pjm-add-backlog-item`).
 **Optional template fields:** related items, target release, owner.
@@ -112,7 +112,7 @@ Confirm to write this to a new backlog item file, or tell me what to change.
 
 ### Destination: Promote to new OAT project
 
-**Pack required:** `workflows` (i.e., `oat config get tools.workflows` returns `true`)
+**Pack required:** `workflows` (i.e., `oat tools has workflows` returns `true`)
 **Trigger phrases:** "let's make this a project", "promote this to a project", "scaffold a project for this", "this is project-sized — let's start one".
 **Required template fields:** `title`, `summary` (Initial Request), `approachesConsidered` (Solution Space), `chosenDirection` (Chosen Direction), key decisions, `openQuestions`. Template: `.oat/templates/discovery.md` (consumed via `oat project new`).
 **Optional template fields:** `motivation`, `vision`, `nextSteps`.

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-cursor-cloud-projects
-version: 1.0.1
+version: 1.0.2
 description: Use when OAT work is mentioned in a Cursor Cloud environment. Orients agents to cloud detection, repo-rooted project homes, user-first assets, CLI availability, and Cursor dispatch context without owning lifecycle execution.
 disable-model-invocation: false
 user-invocable: true
@@ -236,10 +236,17 @@ For Cursor review/worker dispatch:
 
 1. Read `references/cursor-cloud-mechanics.md`.
 2. Resolve and read the selected user-scope
-   `oat-dispatch-subagents/references/provider-cursor.md` by absolute path,
-   falling back to repo/bundled tiers only when the user skill is absent.
-3. Let `oat-project-dispatch-subagents` adapt lifecycle scope and policy.
-4. Let `oat-dispatch-subagents` own capability, catalog, route, launch,
+   `oat-dispatch-subagents/SKILL.md` by absolute path, falling back to
+   repo/bundled tiers only when the user skill is absent.
+3. Resolve and read the selected user-scope
+   `subagent-orchestration/references/model-selection-principles.md` and
+   `subagent-orchestration/references/provider-cursor.md` by absolute path,
+   with the same fallback rule.
+4. Resolve and read the selected user-scope
+   `oat-dispatch-subagents/references/provider-cursor.md` mechanics reference
+   by absolute path, with the same fallback rule.
+5. Let `oat-project-dispatch-subagents` adapt lifecycle scope and policy.
+6. Let `oat-dispatch-subagents` own capability, catalog, route, launch,
    recovery, and generic evidence.
 
 This skill supplies identity and catalog context only. Do not restate or alter

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

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.1.5
+version: 1.2.1
 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
@@ -39,7 +39,7 @@ This skill owns:
 
 - capability and authorization probing;
 - live catalog evidence and candidate intersection;
-- model, effort, role, route, authority, and deadline selection;
+- model, effort, reasoning mode, service tier, 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,
@@ -49,16 +49,35 @@ 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.
+Model-selection policy lives in the `subagent-orchestration` skill (same
+pack); this skill owns launch mechanics. Read this file before every
+OAT-managed subagent dispatch, then read
+`.agents/skills/subagent-orchestration/references/model-selection-principles.md`.
+Resolve the active provider and read exactly one selection reference from
+that skill plus the matching mechanics reference from this one:
+
+- Claude: `subagent-orchestration/references/provider-claude.md`, then
+  `references/provider-claude.md`
+- Codex or direct OpenAI: `subagent-orchestration/references/provider-codex.md`,
+  then `references/provider-codex.md`
+- Cursor: `subagent-orchestration/references/provider-cursor.md`, then
+  `references/provider-cursor.md`
+
+Do not merge provider references into one policy. The principles file contains
+the durable task-class contract; the selection reference contains dated model
+mappings; the mechanics reference contains surface-specific launch controls.
+For an unsupported provider, apply the provider-neutral contract and fail
+closed when exact launch controls cannot be established.
+
+If the `subagent-orchestration` skill is not installed, treat model guidance
+as unresolved: fail closed for class-constrained dispatch, and for
+unconstrained dispatch select only through active user and repository
+instructions intersected with the live catalog.
+
+Read `subagent-orchestration/references/evidence-and-refresh.md` when
+selection guidance is review-required or stale, when a newer model or unknown
+control is observed, or when a consequential dispatch depends on evidence that
+is not current.
 
 Read `references/record-schema.md` only when constructing or validating a
 dispatch request, dispatch record, or homogeneous recon-wave record.
@@ -150,10 +169,17 @@ Keep these controls independent in selection and evidence:
   workflow, gate, or blocked;
 - role or agent definition;
 - model selector and selector granularity;
-- effort or reasoning selector, when exposed;
+- provider-native effort or reasoning selector, when exposed;
+- reasoning mode when exposed independently of effort;
+- service tier, including fast or priority variants;
 - inheritance source and context-fork controls;
 - authority, writable roots, deadline, and retry limit;
-- route and fallback policy.
+- route and fallback policy;
+- provider-guidance version, verification date, and freshness state.
+
+Do not normalize effort labels across providers. A fast or priority tier is a
+latency control unless current provider documentation explicitly establishes a
+capability difference; it never satisfies a higher task-class floor.
 
 A materialized role may package defaults, but its record must preserve each
 configured axis separately.
@@ -226,10 +252,35 @@ 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.
+first, then the active-provider selection reference and live catalog, all
+constrained by the supplied policy and ceiling. Named models in the guidance
+layer are dated examples, not canonical requirements. Select an exact eligible
+target at or above the requested floor; never silently downgrade.
+
+## Dated Guidance and Candidate Qualification
+
+Task-class contracts are durable. Named models in the selection references are
+dated examples. A newer model is a candidate, not an automatic upgrade.
+
+Before using a provider mapping, determine its guidance state from the
+selection-reference frontmatter and
+`subagent-orchestration/references/evidence-and-refresh.md`:
+
+- `fresh`: use the mapping after live catalog intersection;
+- `review-required`: inspect current official controls and relevant evidence
+  before changing the incumbent;
+- `stale`: do not rely on the named mapping without requalification. Retain a
+  known-good incumbent only when still available and floor-satisfying, or route
+  one class up.
+
+A replacement must satisfy the class floor, be exactly selectable in the
+launching harness, have understood effort and service-tier semantics, avoid a
+material regression on relevant evidence, and fit the route's cost, latency,
+tool, context, and safeguard requirements. When evidence is incomplete, keep
+the incumbent or route one class up. Never silently select below the floor.
+
+Record the guidance version, verification date, freshness state, and the reason
+for any incumbent change.
 
 ## Catalog Evidence
 
@@ -265,7 +316,8 @@ For every dispatch:
    or blocked route before launch.
 6. Build the complete redacted payload.
 7. Record route, selection source, selection reason, candidates, catalog
-   source, authority, and deadline.
+   source, model, effort, reasoning mode, service tier, guidance version,
+   authority, and deadline.
 8. Launch once.
 9. Record launch acceptance separately from child outcome and runtime identity.
 
@@ -294,11 +346,16 @@ 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, 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.
+selected route, role class, role selector, model, effort, reasoning mode
+(`reasoning_mode_selector`), service tier (`service_tier_selector`), guidance
+reference (`guidance_reference`), guidance version (`guidance_version`),
+guidance verification date (`guidance_verified_at`), guidance status
+(`guidance_status`), authority, deadline, retry limit, fallback, `task_class`,
+and `model_class_floor`. Optional model-guidance fields must be identically
+present or absent across all lanes and, when present, have identical values.
+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

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

@@ -1,7 +1,8 @@
-# Claude Subagent Dispatch
+# Claude Dispatch Mechanics
 
-Load this reference only when the active provider is Claude. Current
-user-level or repository instructions override model examples in this file.
+Load this reference only when the active provider is Claude. Model-selection
+policy for this provider lives in
+`subagent-orchestration/references/provider-claude.md`; read it first.
 
 ## Control Surfaces
 
@@ -33,10 +34,10 @@ 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:
+Apply active user and repository instructions first, then the dated class
+guidance from the active provider selection reference. Intersect the resulting
+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;
@@ -59,7 +60,9 @@ prohibited. Record the exact selector and `floor_satisfaction`.
   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`.
+- Record service tier separately; fast Claude routes are latency purchases.
 - Keep acceptance, outcome, runtime identity, and continuation separate.
+- Record the provider-guidance version and freshness state.
 
 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

@@ -1,20 +1,23 @@
-# Codex Subagent Dispatch
+# Codex Dispatch Mechanics
 
-Load this reference only when the active provider is Codex. Current user-level
-or repository instructions override model examples in this file.
+Load this reference only when the active provider is Codex or a direct OpenAI
+API route. Model-selection policy for this provider lives in
+`subagent-orchestration/references/provider-codex.md`; read it first.
 
 ## Independent Controls
 
 Codex may expose independent native controls for:
 
 - registered agent type;
-- model and reasoning effort;
+- exact model and `reasoning.effort`;
+- `reasoning.mode`, including `pro` where supported;
 - 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.
+reasoning mode, service tier, fork behavior, and authority as separate
+configured axes.
 
 ## Native Topology
 
@@ -28,13 +31,14 @@ grant filesystem authority.
 
 ## Exact Native Selection
 
-1. Read live registered roles and model/effort selectors.
+1. Read live registered roles and model, effort, service-tier, and reasoning-mode 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.
+7. Record the provider-guidance version and freshness state.
 
 Prefer economical high-effort workers for narrow, independently verifiable
 recon. Move to a context-heavier worker when success depends on reconciling
@@ -44,10 +48,10 @@ 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:
+Apply active user and repository instructions first, then the dated class
+guidance from the active provider selection 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;
@@ -102,6 +106,7 @@ codex exec \
   '<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.
+Add a service tier or reasoning mode only through controls shown by the current
+CLI/schema. Honor the caller's authorization boundary. Record every selector
+as configured invocation evidence; do not infer runtime identity from process
+success alone.

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

@@ -1,8 +1,10 @@
-# Cursor Subagent Dispatch
+# Cursor Dispatch Mechanics
 
-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.
+Load this reference only when the active provider is Cursor. Cursor IDE, CLI,
+and SDK are related but distinct dispatch contexts. Model-selection policy for
+this provider lives in `subagent-orchestration/references/provider-cursor.md`;
+read it first. Treat every observed catalog as a volatile snapshot, never a
+durable inventory.
 
 ## Control Surfaces
 
@@ -10,17 +12,21 @@ volatile snapshot, never a durable inventory.
 | ---------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
 | Native Task/Subagent schema  | Agent types available for that dispatcher invocation           | CLI account eligibility or another dispatcher's native catalog |
 | `cursor-agent --list-models` | Opaque flat model IDs accepted by the account CLI and resolver | Native Task eligibility or definition-pin acceptance           |
+| Cursor SDK catalog/schema    | Models accepted by that SDK context                            | IDE or nested-native 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.
 
+Record the model selector and the service tier separately even when Cursor
+encodes both in one opaque alias.
+
 ## 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:
+Apply active user and repository instructions first, then the dated class
+guidance from the active provider selection 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;
@@ -55,8 +61,8 @@ reconstruct either model string.
    fallback or replacement.
 6. Treat an omitted variant as deliberate parent inheritance only when the
    resolver selected no managed target.
-7. Record selected variant, mapped target, acceptance, outcome, and runtime
-   identity separately.
+7. Record selected variant, mapped target, service tier, acceptance, outcome,
+   runtime identity, and guidance version separately.
 
 ## Reviewer-Local Nested Selection
 
@@ -68,7 +74,7 @@ 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
+   model-class instructions, the selection 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.
@@ -83,8 +89,8 @@ 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
-mechanical recon on economical explicit targets. Stronger lanes use a
+Do not infer Cursor IDE behavior from a headless CLI or SDK surface. Keep
+bounded 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
@@ -108,14 +114,15 @@ liveness, stat that specific file's mtime and size rather than inferring from a
 directory. Metadata change is observable activity evidence, not a health
 verdict.
 
-## Pre-Start CLI Routes
+## Pre-Start CLI or SDK Routes
 
 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:
+unsatisfactory, a caller may use a deliberate pre-start CLI or SDK route only
+when:
 
 - the caller's fallback policy allows it;
 - the exact CLI selector exists in the account catalog;
@@ -123,7 +130,7 @@ unsatisfactory, a caller may use a deliberate pre-start CLI route only when:
   candidates are recorded before launch;
 - the prompt is self-contained and authority-bounded.
 
-Verify current CLI help before use. A typical shape is:
+Verify current CLI or SDK help/schema before use. A typical CLI shape is:
 
 ```sh
 cursor-agent \
@@ -133,13 +140,13 @@ cursor-agent \
   '<self-contained bounded prompt>'
 ```
 
-CLI completion proves configured invocation completion. It does not prove an
-inner native selection or runtime model identity.
+CLI or SDK 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.
+Report configured candidates missing from the current catalog, nearby native
+candidates, the selected route, and the exact observation boundary. Do not
+remove CLI- or SDK-capable candidates solely because another native surface
+cannot pin them. Do not persist an observed catalog without explicit user
+choice.

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

@@ -19,6 +19,8 @@ provider: codex
 dispatch_context: root-native
 dispatch_policy: economy
 dispatch_ceiling: high
+service_tier: standard
+reasoning_mode: null
 authority: read-only
 expected_output: structured-findings
 verification_evidence: file-line-references
@@ -34,6 +36,14 @@ escalate_when:
   - security impact is consequential
 ```
 
+`reasoning_mode` and `service_tier` are normalized caller-intent fields. During
+selection, map `reasoning_mode` to the resolved
+`reasoning_mode_selector` record field and `service_tier` to the resolved
+`service_tier_selector` record field. The selector fields are launch evidence,
+not blind copies of request values: they must contain the exact
+provider-native controls actually selected, or `null` when no independent
+control was selected or exposed.
+
 `dispatch_policy` and `dispatch_ceiling` are optional resolved inputs. The
 general engine does not resolve their source.
 
@@ -59,6 +69,47 @@ 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.
 
+## Legacy Record
+
+This baseline Record remains valid without optional model-guidance evidence:
+
+```yaml
+request_id: dispatch-legacy-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-legacy-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: native-default
+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: []
+```
+
 ## Record
 
 ```yaml
@@ -82,6 +133,12 @@ role_selector: oat-recon-worker
 model_selector: opaque-provider-selector
 model_selector_granularity: opaque
 effort_selector: economical
+reasoning_mode_selector: null
+service_tier_selector: standard
+guidance_reference: subagent-orchestration/references/provider-codex.md
+guidance_version: 2026-07-21
+guidance_verified_at: 2026-07-21
+guidance_status: fresh
 selection_source: native-default
 candidates_considered:
   - opaque-provider-selector
@@ -171,5 +228,32 @@ 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,
 `task_class`, and `model_class_floor` are identical. Lane entries do not
-redefine the shared class fields. Mixed classes require separate records and
-waves.
+redefine the shared class fields. In particular, `reasoning_mode_selector`,
+`service_tier_selector`, `guidance_reference`, `guidance_version`,
+`guidance_verified_at`, and `guidance_status` must be identically present or
+absent across lanes and, when present, have identical values. Mixed classes or
+different model-guidance controls require separate records and waves.
+
+## Optional Model-Guidance Evidence
+
+The following fields are optional for legacy callers and required when the
+launch surface exposes the corresponding control or when dated provider
+mapping influenced selection:
+
+```yaml
+reasoning_mode_selector: null # e.g. pro, when independent of effort
+service_tier_selector: standard # e.g. standard, fast, priority
+guidance_reference: subagent-orchestration/references/provider-codex.md
+guidance_version: 2026-07-21
+guidance_verified_at: 2026-07-21
+guidance_status: fresh # fresh | review-required | stale
+```
+
+Keep `model_selector`, `effort_selector`, `reasoning_mode_selector`, and
+`service_tier_selector` separate even when a provider encodes several axes in
+one opaque alias. Preserve that exact alias in `model_selector` and also record
+the interpreted service tier when known.
+
+A service tier never changes `model_class_floor` or `floor_satisfaction`.
+Unknown tier semantics must be recorded as a diagnostic and may block a
+consequential route.