@open-agent-toolkit/cli 0.1.39 → 0.1.40

package/assets/docs/cli-utilities/configuration.md

@@ -232,6 +232,8 @@ reading config keys directly:
 
 ```bash
 oat project dispatch-ceiling resolve --provider codex --json
+oat project dispatch-ceiling resolve --provider codex --role implementer --preferred medium --json
+oat project dispatch-ceiling resolve --provider claude --role implementer --preferred sonnet --orchestrator-tier sonnet --json
 oat project dispatch-ceiling resolve --provider claude --orchestrator-tier sonnet --json
 ```
 

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -61,11 +61,20 @@ Before dispatching a subagent, the orchestrator calls:
 oat project dispatch-ceiling resolve --provider <provider> --role <implementer|reviewer> --preflight --json
 ```
 
+For implementer or fix dispatch, pass the runtime classification too. In Codex
+this is the preferred effort; in Claude it is the preferred model tier:
+
+```bash
+oat project dispatch-ceiling resolve --provider codex --role implementer --preferred medium --json
+oat project dispatch-ceiling resolve --provider claude --role implementer --preferred sonnet --json
+```
+
 The resolver:
 
 1. reads the concrete `providers.<provider>` value (config precedence, then project state) — **never the preset label**;
 2. looks up that provider's **adapter** in the provider ceiling registry;
-3. returns a per-provider result: `{ value, mode, mechanism, dispatchArgs }`.
+3. applies `--preferred` for implementer/fix dispatch, capping it against the ceiling;
+4. returns a per-provider result: `{ value, mode, mechanism, dispatchArgs, selection }`.
 
 `mode` is the honest enforcement status, computed right there and never persisted:
 
@@ -89,8 +98,8 @@ The same ceiling intent produces different — but honest — behavior per provi
 
 ### Why the mechanisms differ
 
-- **Codex** dispatches through **pinned, sync-time role variants**. Per-call reasoning-effort proved unreliable in practice, so OAT generates committed `oat-phase-implementer-{low..xhigh}` / `oat-reviewer-{low..xhigh}` role files and dispatches the variant matching the resolved effort.
-- **Claude** uses the **per-call Task `model` parameter**, which is reliable and bidirectional (a Sonnet orchestrator can dispatch an Opus subagent and vice-versa) and overrides agent frontmatter — so OAT simply passes `model` at dispatch and needs no variant files.
+- **Codex** dispatches through **pinned, sync-time role variants**. Per-call reasoning-effort proved unreliable in practice, so OAT generates committed `oat-phase-implementer-{low..xhigh}` / `oat-reviewer-{low..xhigh}` role files. Implementer/fix dispatch passes `--preferred` so `dispatchArgs.variant` matches the selected capped effort; reviewer dispatch uses the variant matching the resolved ceiling.
+- **Claude** uses the **per-call Task `model` parameter**, which is reliable and bidirectional (a Sonnet orchestrator can dispatch an Opus subagent and vice-versa) and overrides agent frontmatter. Implementer/fix dispatch passes `--preferred` as the preferred model tier and receives the capped selected `model`; reviewer dispatch uses the ceiling model. OAT needs no variant files.
 - **Unsupported providers** (any without a registered adapter) resolve to `unsupported` with `dispatchArgs: null`. The resolve command **returns cleanly and never blocks** — the ceiling is recorded as intent and applied if/when an adapter ships, while the provider runs at its own capabilities.
 
 A **provider adapter registry** is what lets these genuinely different mechanisms sit behind one resolver, so the lifecycle skills consume `dispatchArgs` without ever branching on provider.
@@ -104,6 +113,8 @@ The ceiling means slightly different things for the two dispatch roles:
 
 Both providers honor this distinction (Codex selects the matching variant; Claude passes the matching model).
 
+Generic sidecars such as built-in `explorer` are outside this implementer/reviewer/fix contract. They may run at provider default when they are read-only advisory helpers. In that case, dispatch logs should say `Preferred effort: provider-default`, `Selected effort: provider-default`, and `Effort axis: provider-default`; only log a concrete selected effort when the actual sidecar payload pins a reliable provider control.
+
 ## Verify-on-upgrade
 
 Only a request for a tier **above** the orchestrator's current tier risks a silent plan/entitlement fallback. So the adapter verifies the actually-dispatched model **only** on that upgrade path; capping down or staying lateral needs no check. OAT never logs `enforced` unless the requested control was actually honored.

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

@@ -108,9 +108,9 @@ Model and effort are separate axes. Each axis logs one of these states:
 - `not-applicable` — this host/API has no meaningful per-dispatch concept for that axis.
 - `host-auto` — exceptional; the host uses that axis internally but the orchestrator cannot read or pin it.
 
-In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and select `min(preferred, resolved_ceiling)`. The selected effort maps to the matching pinned role: `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, or `oat-phase-implementer-xhigh`. Reviewer dispatch uses the reviewer variant matching the resolved ceiling (`oat-reviewer-low|medium|high|xhigh`) for deterministic quality gates. Base/unpinned Codex roles are provider-default fallbacks; they should be logged as `provider-default`, not as inherited parent-session ceiling.
+In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and pass it to `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <effort>`. The resolver selects `min(preferred, resolved_ceiling)` and returns the matching pinned role: `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, or `oat-phase-implementer-xhigh`. Reviewer dispatch uses the reviewer variant matching the resolved ceiling (`oat-reviewer-low|medium|high|xhigh`) for deterministic quality gates. Base/unpinned Codex roles are provider-default fallbacks; they should be logged as `provider-default`, not as inherited parent-session ceiling.
 
-In Claude Code, subagent model selection is a model axis when available and is capped by `workflow.dispatchCeiling.providers.claude` (or the compiled concrete value from a preset) or project `oat_dispatch_ceiling`. The separate effort axis is `not-applicable`.
+In Claude Code, implementation and fix dispatch classify a preferred model tier (`haiku`, `sonnet`, or `opus`) and pass it to `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <model> --orchestrator-tier <current-orchestrator-tier>`. The resolver selects `min(preferred, resolved_ceiling)` and returns the `model` argument to pass at dispatch. Reviewer dispatch targets the resolved Claude ceiling directly. The separate effort axis is `not-applicable`.
 
 Dispatch logs use a consistent structured block so provider behavior is comparable without flattening the model and effort axes:
 
@@ -151,10 +151,24 @@ Model axis: host-auto
 Effort axis: host-auto
 Dispatch target: host default
 Rationale: host does not expose readable or pinnable dispatch controls; rationale maps to standard effort.
+
+OAT Dispatch: p02-t10 sidecar exploration
+Host: Codex
+Preferred effort: provider-default
+Dispatch ceiling: xhigh
+Selected effort: provider-default
+Ceiling source: project state
+Provider default effort: xhigh
+Model axis: inherited
+Effort axis: provider-default
+Dispatch target: explorer
+Rationale: read-only sidecar exploration; generic explorer payload does not pin an OAT-managed effort variant.
 ```
 
 Phase and review scope packets include dispatch context when the orchestrator has resolved it: `model_axis`, `effort_axis`, `dispatch_ceiling`, `ceiling_source`, `provider_default_effort`, and `dispatch_rationale`.
 
+Generic sidecars such as built-in `explorer` are not OAT-managed implementer, reviewer, or fix roles. If a sidecar payload does not pin a reliable effort/model control, log it as provider-default rather than classifying the task complexity as a selected effort. Sidecar results are advisory context; implementation and review/fix gates still follow the OAT-managed dispatch rules above.
+
 ### Dispatch Profile overrides
 
 `plan.md` should omit `## Dispatch Profile` by default. Missing dispatch rows are normal, because runtime selection has fresher phase context and host capability information at execution time.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.39",
-  "docs-config": "0.1.39",
-  "docs-theme": "0.1.39",
-  "docs-transforms": "0.1.39"
+  "cli": "0.1.40",
+  "docs-config": "0.1.40",
+  "docs-theme": "0.1.40",
+  "docs-transforms": "0.1.40"
 }

package/assets/skills/oat-project-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.23
+version: 2.0.24
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
 oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'
@@ -204,7 +204,13 @@ Resolution order:
       "mode": "enforced",
       "mechanism": "pinned-variant",
       "dispatchArgs": { "variant": "oat-phase-implementer-high" },
-      "verifyOnDispatch": false
+      "verifyOnDispatch": false,
+      "selection": {
+        "role": "implementer",
+        "preferredValue": null,
+        "selectedValue": "high",
+        "capped": false
+      }
     }
   }
 }
@@ -212,8 +218,10 @@ Resolution order:
 
 Read `providers.<active-provider>` for the concrete dispatch controls. The
 `dispatchArgs` field carries the provider-specific argument to pass through
-(Codex: `variant` name; Claude: `model` string). Never re-derive these from the
-preset label — the resolver is the single compilation/join point.
+(Codex: `variant` name; Claude: `model` string). For implementer/fix dispatch,
+pass `--preferred <preferred-effort>` and use `selection.selectedValue` as the
+selected axis value. Never re-derive these from the preset label or a ceiling-only
+variant — the resolver is the single compilation/join point.
 
 Print before phase work:
 
@@ -311,7 +319,7 @@ Codex rules:
    - `high`: broad architecture, security/auth/redaction boundaries, subtle state behavior, or repeated substantive review failures
    - `xhigh`: highest-risk work that requires the configured ceiling to allow xhigh
 3. Selected effort is `min(preferred, resolved_ceiling)` for implementer/fix work.
-4. For implementer/fix dispatch: call `oat project dispatch-ceiling resolve --provider codex --role implementer`; read `providers.codex.dispatchArgs.variant` for the role name (e.g., `oat-phase-implementer-high`). Pass that variant name directly — do not re-derive it from the ceiling value.
+4. For implementer/fix dispatch: call `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <preferred-effort>`; read `providers.codex.selection.selectedValue` and `providers.codex.dispatchArgs.variant` for the selected role name (e.g., `oat-phase-implementer-medium`). The resolver caps the preferred effort against the ceiling; never pass a ceiling-only implementer variant when `selection.selectedValue` is lower.
 5. For review dispatch: call `oat project dispatch-ceiling resolve --provider codex --role reviewer`; read `providers.codex.dispatchArgs.variant` for the reviewer role name (e.g., `oat-reviewer-high`). Reviewer always targets the ceiling for deterministic quality gate behavior.
 6. Use base/unpinned Codex roles only as a fallback or explicit provider-default choice. Log `Selected effort: provider-default`, display provider default effort when known, and do not describe this as parent-ceiling inheritance.
 7. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent.
@@ -319,9 +327,9 @@ Codex rules:
 Claude rules:
 
 - Claude ceiling is model-based: `haiku < sonnet < opus`.
-- Implementer dispatch: select the lowest sufficient model capped by the resolved Claude ceiling (`min(preferred, ceiling)`).
+- Implementer/fix dispatch: classify the preferred model (`haiku`, `sonnet`, or `opus`) and pass it to the resolver as `--preferred <preferred-model>`. The resolver selects the lowest sufficient model capped by the resolved Claude ceiling (`min(preferred, ceiling)`).
 - Review dispatch: target the resolved Claude ceiling directly.
-- Call `oat project dispatch-ceiling resolve --provider claude --role implementer --orchestrator-tier <current-orchestrator-tier>` (or `--role reviewer`); read `providers.claude.dispatchArgs.model` for the model string to pass. Pass `--orchestrator-tier` so the resolver can flag above-orchestrator upgrade requests and set `verifyOnDispatch` correctly.
+- For implementer/fix dispatch, call `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <preferred-model> --orchestrator-tier <current-orchestrator-tier>`; for review dispatch, call the same resolver with `--role reviewer` and no `--preferred`. Read `providers.claude.selection.selectedValue` and `providers.claude.dispatchArgs.model` for the selected model string to pass. Pass `--orchestrator-tier` so the resolver can flag above-orchestrator upgrade requests and set `verifyOnDispatch` correctly.
 - Pass `model: "<value>"` when `model_axis=selected:<value>` on the Task tool call.
 - Keep `effort_axis=not-applicable`; Claude Code has no separate per-dispatch effort axis.
 
@@ -336,7 +344,7 @@ Structured dispatch log:
 ```text
 OAT Dispatch: Phase {phase_id} {implementation | fix | review}
 Host: {Claude Code | Codex | Cursor | other host}
-Preferred effort: {low | medium | high | xhigh | not-applicable}
+Preferred effort: {low | medium | high | xhigh | provider-default | not-applicable}
 Dispatch ceiling: {resolved ceiling value}
 Selected effort: {low | medium | high | xhigh | provider-default | not-applicable}
 Ceiling source: {repo config | project state | preflight prompt}
@@ -395,6 +403,29 @@ Dispatch target: oat-reviewer
 Rationale: base unpinned role fallback; effective effort follows Codex provider default.
 ```
 
+Generic sidecar/explorer dispatch:
+
+- Built-in or generic sidecars such as `explorer` are not OAT-managed implementer, reviewer, or fix roles.
+- If a sidecar spawn payload does not explicitly pin a reliable effort/model control, log `Preferred effort: provider-default`, `Selected effort: provider-default`, and `Effort axis: provider-default`.
+- Do not classify a generic sidecar as `Preferred effort: low|medium|high|xhigh` unless the actual host invocation contains the corresponding reliable selection. If the host has no reliable effort control for that sidecar, use provider-default wording instead.
+- Sidecar outputs are advisory context only. Implementation work and review/fix gates still follow the OAT-managed dispatch rules above.
+
+Codex generic explorer example:
+
+```text
+OAT Dispatch: p02-t10 sidecar exploration
+Host: Codex
+Preferred effort: provider-default
+Dispatch ceiling: xhigh
+Selected effort: provider-default
+Ceiling source: project state
+Provider default effort: xhigh
+Model axis: inherited
+Effort axis: provider-default
+Dispatch target: explorer
+Rationale: read-only sidecar exploration; generic explorer payload does not pin an OAT-managed effort variant.
+```
+
 Include resolved dispatch context in scope packets when known:
 
 ```yaml
@@ -740,8 +771,8 @@ For each phase `pNN` in the plan (or each phase in the current parallel group),
 
 2. Perform a pre-dispatch assertion against the host invocation parameters. The Phase Scope fields are audit/context fields; selected axes must also be represented in the actual host dispatch call.
    - Codex implementer/fix dispatch:
-     - Before building the `spawn_agent` argument map, classify the phase complexity and choose preferred effort (`low`, `medium`, `high`, or `xhigh`), then cap it to the resolved Codex dispatch ceiling.
-     - Build the `spawn_agent` argument map before logging the dispatch. If `effort_axis=selected:low|medium|high|xhigh`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, `"oat-phase-implementer-high"`, or `"oat-phase-implementer-xhigh"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
+     - Before building the `spawn_agent` argument map, classify the phase complexity and choose preferred effort (`low`, `medium`, `high`, or `xhigh`), then call `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <preferred-effort>`.
+     - Build the `spawn_agent` argument map from `providers.codex.selection.selectedValue` and `providers.codex.dispatchArgs.variant` before logging the dispatch. If `effort_axis=selected:low|medium|high|xhigh`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, `"oat-phase-implementer-high"`, or `"oat-phase-implementer-xhigh"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
      - Example selected low payload shape: `agent_type: "oat-phase-implementer-low"` and a Phase Scope message containing `effort_axis: selected:low`.
      - Immediately after spawning, compare the returned Codex status line with the selected effort before waiting on the agent. If the spawned status reports a different effort than the selected value (for example, the log says `effort_axis=selected:medium` but the spawn result reports `gpt-5.5 high`), treat this as an orchestration deviation. Stop, record the deviation in `implementation.md`, and redispatch with corrected parameters before continuing. Do not use work from the mismatched dispatch.
      - If `effort_axis=provider-default`, use base `agent_type: "oat-phase-implementer"` and omit `reasoning_effort`. The dispatch rationale MUST say this is a base/unpinned fallback and include provider default effort when known.

package/dist/commands/project/dispatch-ceiling/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch-ceiling/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAEL,KAAK,uBAAuB,EAG7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAggBD,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAiDT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch-ceiling/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAEL,KAAK,uBAAuB,EAG7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAknBD,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAqDT"}

package/dist/commands/project/dispatch-ceiling/index.js

@@ -173,12 +173,67 @@ function readResolvedConfigCeiling(provider, resolvedConfig) {
 function normalizeRole(value) {
     return value === 'reviewer' ? 'reviewer' : 'implementer';
 }
+function providerValueOrder(provider) {
+    if (provider === 'codex') {
+        return CODEX_VALUES;
+    }
+    if (provider === 'claude') {
+        return CLAUDE_VALUES;
+    }
+    return null;
+}
+function normalizePreferredValue(provider, value) {
+    if (!value) {
+        return null;
+    }
+    const normalized = value.trim();
+    if (!normalized) {
+        return null;
+    }
+    const order = providerValueOrder(provider);
+    if (!order) {
+        return null;
+    }
+    if (!isValidProviderValue(provider, normalized)) {
+        const validValues = order.join(', ');
+        throw new Error(`Invalid preferred dispatch value "${normalized}" for ${provider}. Valid values: ${validValues}.`);
+    }
+    return normalized;
+}
+function selectDispatchValue(provider, role, ceilingValue, preferredValue) {
+    if (role === 'reviewer' || preferredValue === null) {
+        return {
+            role,
+            preferredValue,
+            selectedValue: ceilingValue,
+            capped: false,
+        };
+    }
+    const order = providerValueOrder(provider);
+    const preferredIndex = order?.indexOf(preferredValue) ?? -1;
+    const ceilingIndex = order?.indexOf(ceilingValue) ?? -1;
+    if (!order || preferredIndex < 0 || ceilingIndex < 0) {
+        return {
+            role,
+            preferredValue,
+            selectedValue: ceilingValue,
+            capped: false,
+        };
+    }
+    const selectedIndex = Math.min(preferredIndex, ceilingIndex);
+    return {
+        role,
+        preferredValue,
+        selectedValue: order[selectedIndex],
+        capped: preferredIndex > ceilingIndex,
+    };
+}
 /**
  * Join a resolved ceiling value with the active provider's adapter to compute
  * the enforcement mode, mechanism, dispatch args, and verify-on-upgrade flag.
  * Mode is computed here at call time — it is never read from persisted state.
  */
-function buildProviderResolution(provider, value, role, orchestratorTier) {
+function buildProviderResolution(provider, value, role, orchestratorTier, preferredValue) {
     const adapter = getCeilingAdapter(provider);
     if (value === null) {
         return {
@@ -187,9 +242,17 @@ function buildProviderResolution(provider, value, role, orchestratorTier) {
             mechanism: adapter.mechanism,
             dispatchArgs: null,
             verifyOnDispatch: false,
+            selection: {
+                role,
+                preferredValue,
+                selectedValue: null,
+                capped: false,
+            },
         };
     }
-    const dispatchArgs = adapter.compileToDispatchArgs(value, role, {
+    const selection = selectDispatchValue(provider, role, value, preferredValue);
+    const dispatchValue = selection.selectedValue ?? value;
+    const dispatchArgs = adapter.compileToDispatchArgs(dispatchValue, role, {
         orchestratorTier,
     });
     let mode;
@@ -207,7 +270,10 @@ function buildProviderResolution(provider, value, role, orchestratorTier) {
         mode,
         mechanism: adapter.mechanism,
         dispatchArgs,
-        verifyOnDispatch: adapter.verifyOnDispatch(value, { orchestratorTier }),
+        verifyOnDispatch: adapter.verifyOnDispatch(dispatchValue, {
+            orchestratorTier,
+        }),
+        selection,
     };
 }
 function readCodexDefaultFromToml(content) {
@@ -257,8 +323,9 @@ async function resolveDispatchCeiling(context, dependencies, options) {
     const providerDefaultEffort = provider === 'codex'
         ? await resolveCodexProviderDefaultEffort(repoRoot, context, dependencies)
         : 'not-applicable';
+    const preferredValue = normalizePreferredValue(provider, options.preferred);
     const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies);
-    const providerResolution = buildProviderResolution(provider, resolvedValue?.value ?? null, role, orchestratorTier);
+    const providerResolution = buildProviderResolution(provider, resolvedValue?.value ?? null, role, orchestratorTier, preferredValue);
     const providers = {
         [provider]: providerResolution,
     };
@@ -332,9 +399,17 @@ function writeHumanResolution(context, resolution) {
     if (resolution.provider === 'codex') {
         context.logger.info(`Codex provider default effort: ${resolution.providerDefaultEffort}`);
         context.logger.info(`Note: OAT will use pinned subagent variants up to ${resolution.value ?? 'the resolved ceiling'}. Base/unpinned roles resolve through the provider default.`);
+        if (providerResolution?.selection.selectedValue &&
+            providerResolution.selection.preferredValue) {
+            context.logger.info(`Selected Codex effort: ${providerResolution.selection.selectedValue}`);
+        }
     }
     else {
         context.logger.info('Effort axis: not-applicable');
+        if (providerResolution?.selection.selectedValue &&
+            providerResolution.selection.preferredValue) {
+            context.logger.info(`Selected dispatch value: ${providerResolution.selection.selectedValue}`);
+        }
     }
 }
 async function runDispatchCeilingResolve(context, dependencies, options) {
@@ -370,6 +445,7 @@ export function createProjectDispatchCeilingCommand(overrides = {}) {
         .requiredOption('--provider <provider>', 'Provider name: codex or claude are enforced; any other provider resolves as advisory (unsupported)')
         .option('--role <role>', 'Dispatch role for variant compilation: implementer (default) or reviewer')
         .option('--orchestrator-tier <tier>', 'Orchestrator tier, used to flag verify-on-upgrade for above-orchestrator requests')
+        .option('--preferred <value>', 'Preferred implementer/fix dispatch value before capping by the resolved ceiling')
         .option('--project-path <path>', 'Read project-state ceiling from an explicit project path')
         .option('--preflight', 'Treat unresolved non-interactive resolution as an implementation block')
         .option('--non-interactive', 'Force non-interactive block behavior when the ceiling is unresolved')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.39"
+    "@open-agent-toolkit/control-plane": "0.1.40"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",