@open-agent-toolkit/cli 0.2.13 → 0.2.14

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.8
+version: 1.0.9
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -60,7 +60,10 @@ read and follow:
 
 1. `.agents/skills/oat-project-dispatch-subagents/SKILL.md`;
 2. `.agents/skills/oat-dispatch-subagents/SKILL.md`; and
-3. read exactly one active-provider reference from
+3. `.agents/skills/subagent-orchestration/references/model-selection-principles.md`;
+4. read exactly one active-provider selection reference from
+   `.agents/skills/subagent-orchestration/references/`; and
+5. read the matching mechanics reference from
    `.agents/skills/oat-dispatch-subagents/references/`.
 
 Every optional launch must have a bounded objective, explicit read/write

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.8
+version: 1.1.9
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -80,7 +80,7 @@ The primary reviewer must establish the authoritative scope before considering d
 When delegation is eligible:
 
 1. Use one bounded, read-only, non-recursive reconnaissance round with disjoint lane scopes. This is a one-level fan-out limit: lane workers must not spawn additional workers.
-2. Before launching any lane, read `.agents/skills/oat-dispatch-subagents/SKILL.md`, resolve the active provider, and read exactly one matching active-provider reference under `.agents/skills/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load `.agents/skills/oat-project-dispatch-subagents/SKILL.md`; that adapter is reserved for project lifecycle phase/task policy.
+2. Before launching any lane, read `.agents/skills/oat-dispatch-subagents/SKILL.md` and `.agents/skills/subagent-orchestration/references/model-selection-principles.md`. Resolve the active provider, then read exactly one matching selection reference under `.agents/skills/subagent-orchestration/references/` and one matching mechanics reference under `.agents/skills/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load `.agents/skills/oat-project-dispatch-subagents/SKILL.md`; that adapter is reserved for project lifecycle phase/task policy.
 3. Map every lane worker to the shared `recon` role class (`role.class: recon`); role authority stays read-only and advisory. Assign the independent `task_class`, `classification_source: caller`, and non-empty `classification_reason` fields after understanding the artifacts and diff. These task-class fields are required for reviewer-local reconnaissance even though the generic dispatch contract keeps them optional for other callers.
 4. Classify each lane as `mechanical-recon`, `intelligent-recon`, `default-implementation`, `hard-reasoning`, or `consequential`. Use the stronger floor when uncertain. Classification proceeds from deterministic verification to silent-miss risk, then dispersed context, ambiguity, and consequence; file count alone never justifies escalation.
    - `mechanical-recon`: deterministic inventories, parity checks, and test/lint/format/build execution whose misses are visible and cheaply checked.

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

@@ -19,17 +19,35 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 - `docs` - docs and agent-instructions governance workflows
 - `workflows` - project lifecycle skills, wave-program orchestration (`oat-wave-program`, `oat-wave-execute`), 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 plus the provider-neutral subagent-dispatch engine
+- `utility` - review and repo-maintenance helpers plus portable subagent-selection guidance and the provider-neutral 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
+### Orchestration guidance and dispatch dependencies
 
-The reusable dispatch contracts intentionally span two packs:
+The utility pack ships the reusable orchestration pair:
+
+- `subagent-orchestration` owns durable task classes, model-selection
+  principles, dated provider selection matrices, and refresh evidence.
+- `oat-dispatch-subagents` owns capability checks, live catalog intersection,
+  authorized routes, launch acceptance, recovery, and dispatch records.
+
+Provider-aware callers load the generic principles plus exactly one provider
+selection reference, then the dispatch contract plus exactly one matching
+provider mechanics reference. The first reference answers which candidates
+satisfy the task-class floor; the second answers how the active provider can
+launch them. Root callers retain classification, selection judgment,
+cross-lane synthesis, and final authority.
+
+Custom utility selection has a directional dependency: choosing
+`oat-dispatch-subagents` automatically includes `subagent-orchestration`, while
+the self-contained guidance skill may be installed alone. Full utility-pack
+update and removal treat both as explicit members. Removing either skill by
+name does not implicitly remove the other.
+
+The OAT lifecycle adapter intentionally lives in a separate pack:
 
-- `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.
 
@@ -41,9 +59,9 @@ 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
+present without the utility contracts, it fails closed and reports the missing
 dependency instead of inventing a fallback route. Non-project analytical
-skills can use the utility engine directly.
+skills can use the utility guidance and dispatch layers directly.
 
 ### Cross-pack explainer dependency
 

package/assets/docs/contributing/skills.md

@@ -97,21 +97,28 @@ 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.
+Delegation-capable skills should load `subagent-orchestration` instead of
+copying task classes, model-selection principles, dated provider matrices, or
+refresh evidence. Load exactly one active-provider selection reference from
+that skill. The caller applies the guidance and still owns decomposition,
+classification judgment, user interaction, verification of load-bearing
+claims, cross-lane synthesis, and artifact writes.
+
+OAT-specific skills should separately compose with the internal
+`oat-dispatch-subagents` contract instead of copying launch or recovery rules.
+Load exactly one matching provider mechanics reference from that skill. The
+dispatch contract owns capability and authorization checks, live catalog
+evidence, authorized routes, launch acceptance, recovery, and the neutral
+dispatch record. Keep model/effort/reasoning/service-tier axes explicit and do
+not collapse the selection and mechanics references into one provider matrix.
 
 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.
+the guidance and dispatch contracts without requiring an active project. In
+either case, resolve the provider first, then load one selection reference and
+the matching mechanics reference.
 
 Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both include the current delegation guidance and optional capability-detection template.
 

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

@@ -66,7 +66,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. For `targeting_correlation_failed`, do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).

package/assets/docs/workflows/projects/orchestration-model.md

@@ -53,16 +53,23 @@ does not launch a third tier.
 
 ## Dispatch Layers
 
-Every lifecycle launch flows through two contracts:
+Every lifecycle launch composes three responsibilities:
 
 1. `oat-project-dispatch-subagents` resolves project state, role policy,
    ceilings, scope, files, commits, worktrees, and checkpoints.
-2. `oat-dispatch-subagents` resolves capabilities, catalogs, exact routes,
-   launch acceptance, continuation, and generic evidence.
-
-The lifecycle workflow remains authoritative for synthesis and state mutation.
-The dispatch engine does not edit `plan.md`, `implementation.md`, or project
-state.
+2. `subagent-orchestration` supplies the durable task classes and
+   model-selection principles. The caller loads exactly one active-provider
+   selection reference for dated candidates and refresh evidence.
+3. `oat-dispatch-subagents` resolves capabilities, live catalogs, exact
+   routes, launch acceptance, continuation, recovery, and dispatch records. It
+   loads exactly one matching provider mechanics reference.
+
+The selection and mechanics references form a two-reference provider contract:
+the first owns model guidance, while the second owns provider control surfaces.
+They are loaded together for dispatch but never collapsed into one universal
+matrix. The lifecycle workflow remains authoritative for classification,
+selection judgment, synthesis, and state mutation. The dispatch engine does
+not edit `plan.md`, `implementation.md`, or project state.
 
 ```mermaid
 sequenceDiagram

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

@@ -23,7 +23,7 @@ comes from configured dispatch policy or a configured cross-family gate
 (standing, scope-bound), or from explicit user approval for the current run.
 Availability of a provider CLI is capability evidence, not authorization. See
 the route tiers in
-[Orchestration Model](orchestration-model.md#route-tiers-and-terminality) for
+[Orchestration Model](orchestration-model.md#accepted-launch-terminality) for
 how native, policy-resolved, and improvised routes are ranked, and why an
 accepted launch is terminal for automatic replacement.
 

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

@@ -276,8 +276,8 @@ task class sets its minimum model-capability floor:
 File count alone does not justify escalation. Interpretation and policy
 judgment either use an adequate stronger class or remain with the primary
 reviewer. Active user and repository instructions, the active-provider
-guidance, and the live nested catalog resolve current model examples; the
-canonical reviewer does not promise named models.
+selection guidance, and the live nested catalog resolve current model
+examples; the canonical reviewer does not promise named models.
 
 Reviewer-local fan-out is limited to one bounded, read-only, non-recursive
 round. Each worker receives a disjoint scope, cannot modify files or spawn more
@@ -288,15 +288,22 @@ workers, and returns a compact advisory report containing:
 - gaps in the assigned scope; and
 - explicit uncertainty, including uncertainty about absence claims.
 
-Before launching these lanes, the reviewer loads the generic
-`oat-dispatch-subagents` contract and exactly one active-provider reference.
-That shared contract owns nested capability checks, worker catalog resolution,
-model and effort selection, routing, authorization, launch evidence, and
-provider-specific mechanics. It records each lane's task class, model-class
-floor, classification rationale, and floor satisfaction without assuming that
-workers inherit the primary reviewer's target. Lanes may share one wave only
-when their task classes, model floors, and all other dispatch axes match;
-mixed-class reviews use separate waves and records.
+Before launching these lanes, the reviewer loads `subagent-orchestration` for
+durable task classes and model-selection principles, then exactly one
+active-provider selection reference. The reviewer applies that guidance and
+retains the classification, authority, reconciliation, and final finding
+judgment.
+
+The reviewer separately loads the internal `oat-dispatch-subagents` contract
+and exactly one matching provider mechanics reference. That layer owns nested
+capability checks, live worker-catalog resolution, authorized routing, launch
+acceptance, recovery, and dispatch records. Selection guidance owns dated
+provider matrices and refresh evidence; dispatch mechanics do not duplicate
+them. The dispatch record preserves each reviewer-supplied task class,
+model-class floor, classification rationale, selected axes, and floor
+satisfaction without assuming workers inherit the primary reviewer's target.
+Lanes may share one wave only when their task classes, model floors, and all
+other dispatch axes match; mixed-class reviews use separate waves and records.
 
 This generic reviewer-local use is distinct from
 `oat-project-dispatch-subagents`, which is reserved for OAT lifecycle phase and

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

@@ -26,6 +26,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - 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.
+- Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: `subagent-orchestration`. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
 - Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
 - 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`
@@ -123,6 +124,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Scaffolding and utility"
 
+    - `subagent-orchestration`
     - `explainer-kit`
     - `oat-worktree-bootstrap`
     - `oat-worktree-bootstrap-auto`

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

@@ -56,4 +56,16 @@ Failure to publish a backlog item or issue does not invalidate a successfully wr
 
 ## 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.
+Full repository audits use bounded read-only reconnaissance while the root
+agent retains classification, vetting, prioritization, cross-lane synthesis,
+and plan writing. Before launch, the caller loads the durable task classes and
+model-selection principles from `subagent-orchestration` plus exactly one
+active-provider selection reference.
+
+The internal `oat-dispatch-subagents` skill then owns capability checks, live
+catalog intersection, exact route selection, launch acceptance, recovery, and
+dispatch records. It loads exactly one matching provider mechanics reference;
+selection and mechanics references are not merged into one universal provider
+contract. 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.2.13",
-  "docs-config": "0.2.13",
-  "docs-theme": "0.2.13",
-  "docs-transforms": "0.2.13"
+  "cli": "0.2.14",
+  "docs-config": "0.2.14",
+  "docs-theme": "0.2.14",
+  "docs-transforms": "0.2.14"
 }

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.