opencode-codeops 1.10.2 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.11.0 — 2026-10-04
+
+### Features
+
+- effort: map missing levels to the nearest exposed variant
+
+### Documentation
+
+- effort: note the exposed model variant set
+- trace: record live verification and close T-03
+
+## 1.10.3 — 2026-10-04
+
+### Fixes
+
+- effort: prefer the model variant over the reasoning-support flag
+
 ## 1.10.2 — 2026-10-04
 
 ### Fixes

package/README.md

@@ -166,8 +166,10 @@ Reasoning-heavy skills also accept `--auto-effort` (use the skill's recommended
 `--auto-effort=high` (explicit level), announce it, and clear it before the final run summary.
 Resolution order: dispatch marker, then session `--auto-effort`, then
 `routing.roles.<agent>.reasoning` in `codeops/codeops.json`, then the inherited parent variant.
-The levels are suggestions: no permission, verification step, or review gate ever reads them. The
-full contract is in `_shared/reasoning-effort.md`.
+A level the active model does not expose resolves to the nearest exposed variant (`medium`
+becomes `high` on a `low`/`high`/`max` model). The levels are suggestions: no permission,
+verification step, or review gate ever reads them. The full contract is in
+`_shared/reasoning-effort.md`.
 
 ## Project specialists
 

package/_shared/reasoning-effort.md

@@ -16,13 +16,18 @@ contract consumed by the plugin and the skills. It is advisory by design and nev
 | `high` | Correctness- or security-sensitive, cross-cutting, or planning/review work | Requirements, planning, correctness/security review, ambiguous implementation |
 | `max` | Adversarial or high-risk analysis where a missed detail is costly | Thorough preflight, complex or sensitive phases |
 
-The four levels are the complete suggestion vocabulary. A level is applied only when the
-runtime model exposes a matching variant, or when the model reports reasoning support but has no
-variant record (the level is then written directly as the provider reasoning option). A level
-the model does not expose leaves the request unchanged and never raises a provider error.
-Routing policy is project configuration, not a suggestion:
-`routing.roles.<agent>.reasoning` may name any value from the provider enum
-(`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`).
+The four levels are the complete suggestion vocabulary. A level is applied through the model's
+own variant record: the exact variant when it exists, otherwise the nearest exposed level on the
+provider scale, with ties resolving to the higher level. `none` stays exact-match only, because
+mapping it to a reasoning level would enable reasoning the caller disabled. When no variant can
+be chosen — or when the model exposes no variants and does not report reasoning support — the
+request is left unchanged, and it never raises a provider error. Routing policy is project
+configuration, not a suggestion: `routing.roles.<agent>.reasoning` may name any value from the
+provider enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`).
+
+The deepseek flash model in this environment exposes `low`, `high`, and `max`, so a `medium`
+suggestion resolves to `high` there. Confirm the active model's set by enabling
+`CODEOPS_EFFORT_TRACE=1` and reading `variantLevels` on an apply line.
 
 ## Marker grammar
 
@@ -99,6 +104,9 @@ already records:
 | Docs/config/rename-only phase with deterministic verification | `low` |
 | Any other non-trivial phase | `medium` |
 
+The runtime maps a missing level to the nearest exposed variant, so the four levels remain valid
+suggestions on every reasoning-capable model.
+
 The line is written as `> **Reasoning**: <level> — <one-line reason>`. It is a suggestion: the
 user may edit or delete it, and `exec-plan` never blocks on it. A plan without the line keeps
 the inherited behavior.
@@ -135,9 +143,9 @@ forces that level for the whole run, including every dispatch marker composed du
 Set `CODEOPS_EFFORT_TRACE=1` (or `true`) in the environment that starts OpenCode to record what
 the plugin does. One content-free JSON line is appended per marker capture and per request to
 `reasoning-effort-trace.jsonl` inside the session's scratch directory. Lines carry only a
-timestamp, event name, message id, agent name, level, source, and applied flag — never prompt
-text or file content. The trace lives with the rest of the session scratch and is removed with
-it. Tracing is off by default and never affects a request.
+timestamp, event name, message id, agent name, level, source, chosen variant, and applied flag —
+never prompt text or file content. The trace lives with the rest of the session scratch and is
+removed with it. Tracing is off by default and never affects a request.
 
 ## Suggestion-only guarantee
 

package/bin/lib/reasoning-effort.d.mts

@@ -84,6 +84,12 @@ export declare function extractModelVariants(
 /** Check whether a model advertises reasoning support. */
 export declare function modelSupportsReasoning(model: unknown): boolean
 
+/** Choose the model variant key to apply for a requested level. */
+export declare function selectEffortVariant(
+  level: unknown,
+  model: unknown
+): RoutingReasoning | undefined
+
 /** Merge the model's variant options for a level into the request options. */
 export declare function applyEffort(
   options: Record<string, unknown>,

package/bin/lib/reasoning-effort.mjs

@@ -303,15 +303,89 @@ export function modelSupportsReasoning(model) {
   return capabilities.reasoning === true
 }
 
+/**
+ * Order of provider reasoning levels, weakest to strongest.
+ *
+ * The scale is used only to pick the nearest exposed variant when a model
+ * does not offer the exact requested level.
+ */
+const EFFORT_RANK = Object.freeze({
+  none: 0,
+  minimal: 1,
+  low: 2,
+  medium: 3,
+  high: 4,
+  xhigh: 5,
+  max: 6,
+})
+
+/**
+ * Choose the model variant key to apply for a requested level.
+ *
+ * The exact level wins when the model exposes it. Otherwise the nearest
+ * exposed level on the provider scale is chosen, and ties resolve to the
+ * higher level so ordinary work is never under-powered. `none` is
+ * exact-match only: mapping it to a reasoning level would enable reasoning
+ * the caller explicitly disabled. Keys whose value is not a plain object are
+ * ignored, so a malformed variant can never reach the request options.
+ *
+ * @param level - Requested level (any routing enum value)
+ * @param model - Model object from the hook input
+ * @returns The variant key to apply, or `undefined` when none applies
+ *
+ * @example
+ * selectEffortVariant("medium", { variants: { low: {}, high: {} } }) // "high"
+ */
+export function selectEffortVariant(level, model) {
+  if (!isRoutingReasoning(level)) return undefined
+  const variants = extractModelVariants(model)
+  if (variants === undefined) return undefined
+
+  if (level === "none") {
+    return isPlainObject(variants.none) ? "none" : undefined
+  }
+
+  const candidates = Object.keys(variants).filter(
+    (key) =>
+      key !== "none" &&
+      Object.prototype.hasOwnProperty.call(EFFORT_RANK, key) &&
+      isPlainObject(variants[key])
+  )
+  if (candidates.includes(level)) return level
+
+  let best
+  for (const key of candidates) {
+    if (best === undefined) {
+      best = key
+      continue
+    }
+    const distance = Math.abs(EFFORT_RANK[key] - EFFORT_RANK[level])
+    const bestDistance = Math.abs(EFFORT_RANK[best] - EFFORT_RANK[level])
+    if (
+      distance < bestDistance ||
+      (distance === bestDistance && EFFORT_RANK[key] > EFFORT_RANK[best])
+    ) {
+      best = key
+    }
+  }
+  return best
+}
+
 /**
  * Merge the model's variant options for a level into the request options.
  *
  * The runtime model carries a `variants` record whose entries are the exact
  * provider options for each level (for example `reasoningEffort`, or a nested
  * `reasoning.effort`). This function is the only place that mapping is
- * consumed, so the plugin never hardcodes a provider key. The function is
- * pure: it returns a new object when a change applies and the original object
- * reference otherwise.
+ * consumed, so the plugin never hardcodes a provider key. The applied key is
+ * chosen by {@link selectEffortVariant}: exact match first, then the nearest
+ * exposed level. A matching variant applies even when the model's reasoning
+ * capability flag is absent or false, because the variant itself is the
+ * provider-known option set and the host applies inherited variants the same
+ * way. Only when no variants record exists does the documented
+ * `reasoningEffort` passthrough require an explicit reasoning capability. The
+ * function is pure: it returns a new object when a change applies and the
+ * original object reference otherwise.
  *
  * @param options - Current provider options
  * @param level - Candidate level from {@link resolveEffort}
@@ -320,16 +394,15 @@ export function modelSupportsReasoning(model) {
  */
 export function applyEffort(options, level, model) {
   if (!isRoutingReasoning(level)) return options
-  if (!modelSupportsReasoning(model)) return options
 
   const variants = extractModelVariants(model)
   if (variants !== undefined) {
-    if (!Object.prototype.hasOwnProperty.call(variants, level)) return options
-    const variantOptions = variants[level]
-    if (!isPlainObject(variantOptions)) return options
-    return deepMergePlain(options, variantOptions)
+    const variantKey = selectEffortVariant(level, model)
+    if (variantKey === undefined) return options
+    return deepMergePlain(options, variants[variantKey])
   }
 
+  if (!modelSupportsReasoning(model)) return options
   return { ...options, reasoningEffort: level }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {

package/plugin/index.ts

@@ -12,13 +12,16 @@ import {
 import {
   appendEffortTrace,
   applyEffort,
+  extractModelVariants,
   findEffortMarker,
   isEffortLevel,
   isEffortTraceEnabled,
   isRoutingReasoning,
+  modelSupportsReasoning,
   readRoutingReasoning,
   readSessionEffort,
   resolveEffort,
+  selectEffortVariant,
 } from "../bin/lib/reasoning-effort.mjs"
 import type { EffortLevel } from "../bin/lib/reasoning-effort.mjs"
 
@@ -348,6 +351,9 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
           level,
           source,
           applied: changed,
+          variant: selectEffortVariant(level, input.model) ?? null,
+          reasoningSupported: modelSupportsReasoning(input.model),
+          variantLevels: Object.keys(extractModelVariants(input.model) ?? {}),
         })
         if (!changed) {
           if (marker !== undefined) {

package/skills/setup-routing/routing.md

@@ -45,10 +45,15 @@ comes from an execution plan's per-phase suggestion; a session level comes from
 when a role entry exists — with no entry the child inherits the parent variant.
 
 The suggestion vocabulary is `low`, `medium`, `high`, and `max`, while the routing field accepts
-the wider provider enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). The deepseek
-flash model exposes `low`/`medium`/`high`/`max`; prefer `low` for mechanical work, `medium` for
-bounded implementation, `high` for planning and review, and `max` only for adversarial analysis.
-An unsupported value is skipped at runtime, so a routing entry never produces a provider error.
+the wider provider enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). A level the
+model does not expose resolves to the nearest exposed variant (ties choose the higher level);
+`none` is exact-match only. On the deepseek flash model in this environment
+(`low`/`high`/`max`), `medium` therefore resolves to `high`. Confirm the active set with
+`CODEOPS_EFFORT_TRACE=1` and `variantLevels` on an apply line (see
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md)). Prefer `low` for
+mechanical work, `medium` (or the nearest exposed level) for bounded implementation, `high` for
+planning and review, and `max` only for adversarial analysis. A value that cannot be mapped is
+skipped, so a routing entry never produces a provider error.
 
 Model pins are optional per role. When omitted, OpenCode resolves the model from the explicit spawn, project defaults, and parent session. A missing pin must never block the workflow.