opencode-codeops 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.10.0 — 2026-10-04
+
+### Documentation
+
+- agents: refresh managed project facts
+- routing: clarify runtime variant validation
+- plan: fix phase 3 review wording gaps
+
+### Fixes
+
+- effort: tolerate malformed message parts in marker scan
+- effort: correct phase 2 review findings
+- effort: harden helper totality and contract wording
+
+### Features
+
+- docs: add auto-effort flags and reasoning documentation
+- plan: carry reasoning suggestions through plan skills
+- effort: add session CLI and plugin runtime hooks
+- effort: add reasoning-effort contract and helper
+
+### Tests
+
+- effort: add implementation tests for reasoning-effort helper
+
 ## 1.9.0 — 2026-10-04
 
 ### Features

package/README.md

@@ -153,6 +153,22 @@ To pin specific models per role, use the `setup-routing` skill or add overrides
 }
 ```
 
+### Adaptive reasoning effort
+
+CodeOps can pick a reasoning level per dispatch instead of always inheriting the parent session's
+variant. A dispatch packet may carry one standalone marker line:
+
+```text
+[codeops-effort: medium]
+```
+
+Reasoning-heavy skills also accept `--auto-effort` (use the skill's recommended level) or
+`--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`.
+
 ## Project specialists
 
 CodeOps can recommend project-specific specialist subagents when repository evidence shows a

package/_shared/quality-profile.md

@@ -147,6 +147,10 @@ Resolution order is:
 3. project `[agents]` defaults in `opencode.json`;
 4. the parent session's model and effort.
 
+For the runtime reasoning-effort override (a dispatch marker, a session `--auto-effort` level, or
+a routing role default), see [reasoning-effort.md](reasoning-effort.md); the static resolution
+order above is unchanged.
+
 Use `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/install_agents.py" --project . --roles ...` to create optional project agents. Generated agent files carry a CodeOps marker. The installer owns only marked files and preserves every hand-authored file. Use `--check` to detect missing or stale generated agents and `--dry-run` to preview changes. Project specialists are generated with `--custom <role>` from `codeops/specialists/<role>.md` and indexed into `AGENTS.md` with `--sync-agents-md`; their routing policy may also set `reasoning`.
 
 Dynamic packets are the correctness baseline. If a named agent is missing or a model pin is unavailable, spawn a generic subagent with the complete packet or run inline. Report the fallback and preserve required reviewer independence, sandbox intent, and every ambiguity/readiness/verification gate.

package/_shared/reasoning-effort.md

@@ -0,0 +1,135 @@
+# Reasoning effort (shared contract)
+
+> **CodeOps Artifact Schema**: 1
+
+CodeOps subagents normally inherit the parent session's model variant, so a top-tier parent
+would pay top-tier reasoning cost for every child dispatch. Adaptive reasoning effort lets an
+explicit source pick a level per dispatch or per skill run. This document is the shipped
+contract consumed by the plugin and the skills. It is advisory by design and never a gate.
+
+## Levels
+
+| Level | Meaning | Typical work |
+| ----- | ------- | ------------ |
+| `low` | Mechanical, fully specified, deterministic verification | Docs and formatting edits, renames, config updates |
+| `medium` | Ordinary bounded feature work with known patterns | Standard implementation phases, recon, single-file reviews |
+| `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`).
+
+## Marker grammar
+
+A dispatch marker is one standalone line in a dispatch message:
+
+```text
+[codeops-effort: <level>]
+```
+
+- The whole trimmed line must match `^\[codeops-effort:\s*(low|medium|high|max)\]\s*$`.
+- The level is exactly lower-case. Unknown or malformed markers are ignored, never errors.
+- Only user-role text parts of a message are scanned; tool output, diffs, and quoted documents
+  are never scanned.
+- The first valid marker in message order wins; additional markers are ignored.
+- The marker is deliberately distinct from the human-readable plan line
+  `> **Reasoning**: ...`, so a quoted plan line can never act as a machine directive.
+
+For quality-agent packets the marker follows the dispatch header; for packet kinds without a
+header it is the first line. `exec-plan` owns the composition rule.
+
+## Precedence
+
+The most specific source wins:
+
+```text
+dispatch marker  >  session auto-effort  >  routing.roles[<agent>].reasoning  >  inherit parent variant
+```
+
+| Source | Scope | Owner |
+| ------ | ----- | ----- |
+| Dispatch marker | One child dispatch | `exec-plan` composes it from the phase suggestion or the run's forced level |
+| Session auto-effort | One skill run in the user's session | `--auto-effort` through `scripts/codeops_effort.py` |
+| Routing role default | Project policy for one agent name | `codeops/codeops.json` → `routing.roles.<agent>.reasoning` |
+| Inherit | Everything else | The child keeps the parent model and variant |
+
+Routing lookup applies only when the dispatching agent's name has an explicit `routing.roles`
+entry. There are no built-in catalog defaults, hand-authored agents are untouched, and
+generated specialists keep their embedded value unless the project adds a routing entry.
+
+## Skill recommendation table
+
+Used for suggestions and for a bare `--auto-effort`:
+
+| Skill | Recommended level | Notes |
+| ----- | ----------------- | ----- |
+| `make-requirements` | `high` | Structured discovery and gap expansion |
+| `make-plan` | `high` | Decomposition plus the Zero-Ambiguity Gate |
+| `preflight` | `high`; `max` with `--thorough` | Adversarial multi-dimension audit |
+| `grill-me` | `high` | Branch-by-branch disambiguation |
+| `exec-plan` | current phase's `Reasoning:` level | Bare flag follows the phase; `=<level>` forces a constant |
+| `retro-requirements` | `high` | Nine-phase archaeology |
+| `upgrade-plan` | `high` | Content gate plus structural migration |
+| `setup-codeops`, `setup-routing` | `high` (reference only) | Structure and policy authoring |
+| `techdocs`, `analyze-project`, `clean-comments`, `outcome-review` | `medium` (reference only) | Structured but bounded |
+| `roadmap`, `git-commit`, `github-issues` | `low` (reference only) | Mechanical bookkeeping |
+
+Skills that accept `--auto-effort` are `make-requirements`, `make-plan`, `preflight`,
+`grill-me`, `exec-plan`, `retro-requirements`, and `upgrade-plan`. Other skills document their
+recommended levels for reference only and do not implement the flag.
+
+## Plan suggestion derivation
+
+`make-plan` derives an advisory level for every phase and every task mini-plan from signals it
+already records:
+
+| Signal | Suggested level |
+| ------ | --------------- |
+| Phase carries a complexity escalation approval, or a complex/sensitive tag | `max` |
+| Phase carries a security, financial-integrity, concurrency, performance-critical, compiler-semantics, or migration lens/risk tag | `high` |
+| Docs/config/rename-only phase with deterministic verification | `low` |
+| Any other non-trivial phase | `medium` |
+
+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.
+
+## Auto-effort option
+
+Skills listed above accept the flag. Parsing follows the existing standalone-token pattern
+(`--auto-design`, `--explore-scope`): exactly one occurrence before the first `--` sentinel,
+removed before resolving targets, paths, or modes; zero means advise-only; more than one or an
+invalid `=<level>` is an argument error.
+
+| Flag | Behavior |
+| ---- | -------- |
+| *(absent)* | Print `Suggested reasoning: <level> — <reason>` once at start (`exec-plan`: before each phase); change nothing |
+| `--auto-effort` | Use the skill's recommended level (`exec-plan`: the current phase level) |
+| `--auto-effort=<level>` | Use the named level; reject values outside the four-level set |
+
+Semantics:
+
+1. Announce `Auto-effort active — reasoning <level> applied for this run`.
+2. Record the level for the session run through `scripts/codeops_effort.py`.
+3. Clear it at run completion, before the final summary.
+4. Run-scoped: the level applies from the point it is set until cleared or the session ends.
+5. Fail-open: when the session temp directory is unavailable or the helper fails, print an
+   advise-only note and continue; the skill never blocks.
+6. Never a gate: effort affects cost and latency only. No readiness check, verification step,
+   reviewer requirement, or finding gate may read it.
+
+For `exec-plan`, a bare flag follows each phase's suggestion, while `--auto-effort=<level>`
+forces that level for the whole run, including every dispatch marker composed during it.
+
+## Suggestion-only guarantee
+
+| Allowed | Forbidden |
+| ------- | --------- |
+| Printing a suggested level and its reason | Blocking a run because a level is missing or unsupported |
+| Applying a level when a marker, flag, or routing entry explicitly asks | Overriding an explicit user plan edit with a derived default |
+| Reporting the applied level and its source | Treating effort as an acceptance, review, or security control |

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

@@ -0,0 +1,85 @@
+/**
+ * Type declarations for the CodeOps adaptive reasoning-effort helper.
+ *
+ * The helper is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entry point typed access.
+ */
+
+/** A level from the four-level suggestion vocabulary. */
+export type EffortLevel = "low" | "medium" | "high" | "max"
+
+/** A reasoning value accepted by `routing.roles.<agent>.reasoning`. */
+export type RoutingReasoning =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max"
+
+/** The four levels a plan or skill may suggest. */
+export declare const EFFORT_LEVELS: readonly EffortLevel[]
+
+/** Check whether a value is one of the four suggestion levels. */
+export declare function isEffortLevel(value: unknown): value is EffortLevel
+
+/** The reasoning values accepted by routing role entries. */
+export declare const ROUTING_REASONING_VALUES: readonly RoutingReasoning[]
+
+/** Check whether a value is a valid routing reasoning entry. */
+export declare function isRoutingReasoning(value: unknown): value is RoutingReasoning
+
+/** Find the first valid dispatch marker across message text parts. */
+export declare function findEffortMarker(texts: unknown): EffortLevel | undefined
+
+/** Candidate sources for {@link resolveEffort}. */
+export interface ResolveEffortInput {
+  marker?: unknown
+  session?: unknown
+  routing?: unknown
+}
+
+/** Resolve the effective level from the explicit sources, most specific first. */
+export declare function resolveEffort(
+  input?: ResolveEffortInput
+): EffortLevel | RoutingReasoning | undefined
+
+/** Compute the session state-file path inside the session temp directory. */
+export declare function sessionEffortPath(sessionID?: string, base?: string): string
+
+/** Parse session state-file text into a validated level. */
+export declare function parseStateFile(text: string): EffortLevel | undefined
+
+/** Read the session's reasoning-effort state file. */
+export declare function readSessionEffort(
+  sessionID?: string,
+  base?: string
+): EffortLevel | undefined
+
+/** Read an agent's explicit reasoning entry from the project routing config. */
+export declare function readRoutingReasoning(
+  config: unknown,
+  agent: unknown
+): RoutingReasoning | undefined
+
+/** Extract the model's runtime variant record, when the host exposes one. */
+export declare function extractModelVariants(
+  model: unknown
+): Record<string, unknown> | undefined
+
+/** Check whether a model advertises reasoning support. */
+export declare function modelSupportsReasoning(model: unknown): boolean
+
+/** Merge the model's variant options for a level into the request options. */
+export declare function applyEffort(
+  options: Record<string, unknown>,
+  level: unknown,
+  model: unknown
+): Record<string, unknown>
+
+/** Recursively merge plain objects into a new object. */
+export declare function deepMergePlain(
+  target: unknown,
+  source: unknown
+): Record<string, unknown>

package/bin/lib/reasoning-effort.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * Adaptive reasoning-effort helper for CodeOps sessions.
+ *
+ * The plugin needs one place to answer a simple question per request: "which
+ * reasoning level should this request use, if any?" This module answers it
+ * without any framework dependency so `node --test` can exercise every edge:
+ *
+ * - marker scanning over message text parts;
+ * - source precedence (dispatch marker, session flag, routing default);
+ * - routing-config lookup with hostile-shape tolerance;
+ * - provider-option application through the model's own variant record; and
+ * - reading the per-session state file written by the skills.
+ *
+ * Every function is deliberately total: malformed input yields "no override",
+ * never a thrown error. The plugin hooks sit on the request path, where a
+ * crash would break the user's session, so safety beats strictness here.
+ *
+ * @module lib/reasoning-effort
+ */
+
+import { lstatSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { sessionTmpDir } from "./tmp-hygiene.mjs"
+
+/**
+ * The four levels a plan or skill may suggest.
+ *
+ * These are the only values accepted in dispatch markers, session flags, and
+ * plan suggestions. Routing policy is project configuration and may name the
+ * wider provider enum instead.
+ */
+export const EFFORT_LEVELS = Object.freeze(["low", "medium", "high", "max"])
+
+/**
+ * The reasoning values accepted by `routing.roles.<agent>.reasoning` in the
+ * project configuration.
+ *
+ * The list mirrors the CodeOps config schema, which passes provider-native
+ * values through so a project can ask for `minimal` or `xhigh` even though the
+ * suggestion vocabulary only offers the four common levels.
+ */
+export const ROUTING_REASONING_VALUES = Object.freeze([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+])
+
+/**
+ * Largest state file accepted by {@link readSessionEffort}.
+ *
+ * The real file is a few dozen bytes. The cap keeps a hostile or corrupt file
+ * from being slurped into memory if the temp directory is ever tampered with.
+ */
+const MAX_STATE_FILE_BYTES = 4096
+
+/**
+ * One standalone marker line, anchored to the whole line.
+ *
+ * The marker is intentionally different from the human-readable plan line
+ * `> **Reasoning**: ...`, so quoting a plan can never act as a machine
+ * directive. Whitespace inside the brackets is tolerated; text before or after
+ * is not.
+ */
+const MARKER_PATTERN = /^\[codeops-effort:\s*(low|medium|high|max)\]\s*$/
+
+/**
+ * Check whether a value is one of the four suggestion levels.
+ *
+ * @param value - Value to inspect
+ * @returns True only for `"low"`, `"medium"`, `"high"`, or `"max"`
+ *
+ * @example
+ * isEffortLevel("high") // true
+ * isEffortLevel("xhigh") // false
+ */
+export function isEffortLevel(value) {
+  return typeof value === "string" && EFFORT_LEVELS.includes(value)
+}
+
+/**
+ * Check whether a value is a valid routing reasoning entry.
+ *
+ * @param value - Value to inspect
+ * @returns True for any value in the routing enum
+ */
+export function isRoutingReasoning(value) {
+  return typeof value === "string" && ROUTING_REASONING_VALUES.includes(value)
+}
+
+/**
+ * Find the first valid dispatch marker across a list of message text parts.
+ *
+ * Only string entries are inspected; non-string entries (tool parts, images,
+ * malformed structures) are skipped so a hostile part can never break the
+ * request path. Lines are split on `\n`, `\r\n`, and `\r`, then trimmed before
+ * the anchored pattern is applied, so surrounding whitespace is tolerated.
+ *
+ * @param texts - Candidate text parts (usually the text of a message's parts)
+ * @returns The first valid level, or `undefined` when none is present
+ *
+ * @example
+ * findEffortMarker(["run the task", "[codeops-effort: medium]"]) // "medium"
+ */
+export function findEffortMarker(texts) {
+  if (!Array.isArray(texts)) return undefined
+  for (const text of texts) {
+    if (typeof text !== "string") continue
+    for (const line of text.split(/\r\n|\r|\n/)) {
+      const match = MARKER_PATTERN.exec(line.trim())
+      if (match) return match[1]
+    }
+  }
+  return undefined
+}
+
+/**
+ * Resolve the effective level from the three explicit sources.
+ *
+ * Precedence is "most specific wins": a dispatch marker beats a session
+ * flag, which beats a routing default. Each source is validated before it is
+ * accepted, so an invalid value is ignored rather than propagated. A
+ * non-object argument yields `undefined` instead of throwing.
+ *
+ * @param input - Candidate sources; all optional
+ * @returns The first valid value, or `undefined` when no source applies
+ *
+ * @example
+ * resolveEffort({ session: "high", routing: "low" }) // "high"
+ */
+export function resolveEffort(input) {
+  if (!isPlainObject(input)) return undefined
+  const { marker, session, routing } = input
+  if (isEffortLevel(marker)) return marker
+  if (isEffortLevel(session)) return session
+  if (isRoutingReasoning(routing)) return routing
+  return undefined
+}
+
+/**
+ * Compute the session state-file path inside the session temp directory.
+ *
+ * @param sessionID - Session identifier
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Absolute path to `reasoning-effort.json` for the session
+ */
+export function sessionEffortPath(sessionID, base) {
+  return join(sessionTmpDir(sessionID, base), "reasoning-effort.json")
+}
+
+/**
+ * Parse session state-file text into a validated level.
+ *
+ * The expected payload is `{"schema":1,"reasoning":"<level>"}` with any
+ * unknown keys ignored. Anything else — malformed JSON, the wrong schema, a
+ * level outside the four-level allowlist — yields `undefined`.
+ *
+ * @param text - Raw file contents
+ * @returns The validated level, or `undefined`
+ */
+export function parseStateFile(text) {
+  try {
+    const value = JSON.parse(text)
+    if (!isPlainObject(value)) return undefined
+    if (value.schema !== 1) return undefined
+    return isEffortLevel(value.reasoning) ? value.reasoning : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read the session's reasoning-effort state file.
+ *
+ * The file is written by `scripts/codeops_effort.py` for `--auto-effort`
+ * runs. Only a small regular file is accepted: a missing file, a non-regular
+ * file (symlinks are never followed), an oversized file, and any read or parse
+ * failure all mean "no session effort" and return `undefined`.
+ *
+ * @param sessionID - Session identifier
+ * @param base - Base temp directory (injectable for tests)
+ * @returns The session level, or `undefined`
+ */
+export function readSessionEffort(sessionID, base) {
+  try {
+    const path = sessionEffortPath(sessionID, base)
+    const info = lstatSync(path)
+    if (!info.isFile()) return undefined
+    if (info.size > MAX_STATE_FILE_BYTES) return undefined
+    return parseStateFile(readFileSync(path, "utf-8"))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read an agent's explicit reasoning entry from the project routing config.
+ *
+ * Only an own `routing.roles.<agent>.reasoning` property counts; unknown
+ * agents, missing sections, inherited properties, and malformed shapes all
+ * return `undefined` instead of throwing.
+ *
+ * @param config - Parsed `codeops/codeops.json` content (any shape)
+ * @param agent - Dispatching agent name
+ * @returns The configured routing value, or `undefined`
+ */
+export function readRoutingReasoning(config, agent) {
+  if (!isPlainObject(config)) return undefined
+  const routing = config.routing
+  if (!isPlainObject(routing)) return undefined
+  const roles = routing.roles
+  if (!isPlainObject(roles)) return undefined
+  if (typeof agent !== "string" || agent.length === 0) return undefined
+  if (!Object.prototype.hasOwnProperty.call(roles, agent)) return undefined
+  const entry = roles[agent]
+  if (!isPlainObject(entry)) return undefined
+  return isRoutingReasoning(entry.reasoning) ? entry.reasoning : undefined
+}
+
+/**
+ * Extract the model's runtime variant record, when the host exposes one.
+ *
+ * The installed SDK type does not declare `variants`, but the running host
+ * attaches it to every model. The `in` check keeps this graceful when the
+ * property is absent, and a cast is never used.
+ *
+ * @param model - Model object from the hook input
+ * @returns The variants record when it is a plain object, else `undefined`
+ */
+export function extractModelVariants(model) {
+  if (!isPlainObject(model)) return undefined
+  if (!("variants" in model)) return undefined
+  return isPlainObject(model.variants) ? model.variants : undefined
+}
+
+/**
+ * Check whether a model advertises reasoning support.
+ *
+ * @param model - Model object from the hook input
+ * @returns True only when `capabilities.reasoning` is exactly `true`
+ */
+export function modelSupportsReasoning(model) {
+  if (!isPlainObject(model)) return false
+  const capabilities = model.capabilities
+  if (!isPlainObject(capabilities)) return false
+  return capabilities.reasoning === true
+}
+
+/**
+ * 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.
+ *
+ * @param options - Current provider options
+ * @param level - Candidate level from {@link resolveEffort}
+ * @param model - Model object from the hook input
+ * @returns The original options, or a new merged object when a change applies
+ */
+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)
+  }
+
+  return { ...options, reasoningEffort: level }
+}
+
+/**
+ * Recursively merge plain objects into a new object.
+ *
+ * Values that are not plain objects — arrays, class instances, primitives —
+ * are replaced, not merged. Neither input is mutated. The result is created
+ * with data properties, so a hostile `__proto__` key in a variant can never
+ * change the result's prototype chain.
+ *
+ * @param target - Base object
+ * @param source - Overrides to merge on top
+ * @returns A new merged plain object
+ */
+export function deepMergePlain(target, source) {
+  const result = isPlainObject(target) ? { ...target } : {}
+  if (!isPlainObject(source)) return result
+
+  for (const key of Object.keys(source)) {
+    const incoming = source[key]
+    const current = Object.prototype.hasOwnProperty.call(result, key)
+      ? result[key]
+      : undefined
+    const merged =
+      isPlainObject(incoming) && isPlainObject(current)
+        ? deepMergePlain(current, incoming)
+        : incoming
+    Object.defineProperty(result, key, {
+      value: merged,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
+  }
+
+  return result
+}
+
+/**
+ * Check whether a value is a plain object (not an array, class instance, or
+ * `null`).
+ *
+ * @param value - Value to inspect
+ * @returns True for `{}`-shaped objects and objects with a null prototype
+ */
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}

package/package.json

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

package/plugin/index.ts

@@ -9,6 +9,14 @@ import {
   ensureSessionTmpDir,
   removeSessionTmpDir,
 } from "../bin/lib/tmp-hygiene.mjs"
+import {
+  applyEffort,
+  findEffortMarker,
+  readRoutingReasoning,
+  readSessionEffort,
+  resolveEffort,
+} from "../bin/lib/reasoning-effort.mjs"
+import type { EffortLevel } from "../bin/lib/reasoning-effort.mjs"
 
 // ---------------------------------------------------------------------------
 // Package root — resolved at module load time so it is always the plugin's
@@ -137,11 +145,44 @@ async function warnOnVersionSkew(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Helper — log one content-free warning. Logging is best effort: a failed log
+// must never break a request.
+// ---------------------------------------------------------------------------
+async function warnContentFree(
+  client: Parameters<Plugin>[0]["client"],
+  message: string
+): Promise<void> {
+  try {
+    await client.app.log({ body: { service: "codeops", level: "warn", message } })
+  } catch {
+    // Best effort only.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper — read the project routing config fresh on every request, so an edit
+// applies without restarting the session. Any failure means "no routing".
+// ---------------------------------------------------------------------------
+function readRoutingConfig(directory: string): unknown {
+  try {
+    return JSON.parse(readFileSync(join(directory, "codeops", "codeops.json"), "utf8"))
+  } catch {
+    return {}
+  }
+}
+
 // ---------------------------------------------------------------------------
 // CodeOps plugin for OpenCode
 // Replaces: hooks/hooks.json + hook_session_context.sh + hook_marker_guard.sh
 // ---------------------------------------------------------------------------
 export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
+  // Reasoning-effort state lives for the lifetime of this plugin instance:
+  // one entry per user message that carried a dispatch marker, plus a
+  // deduplication set for unsupported-level warnings.
+  const effortMarkers = new Map<string, { sessionID: string; level: EffortLevel }>()
+  const warnedEffortLevels = new Set<string>()
+
   return {
     // -----------------------------------------------------------------------
     // Hook 1 & 2: inject standards on session.created and session.compacted.
@@ -160,6 +201,13 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
       } else if (event.type === "session.deleted") {
         const info = (event.properties as { info: { id: string } }).info
         removeSessionTmpDir(info.id)
+        try {
+          for (const [messageID, entry] of effortMarkers) {
+            if (entry.sessionID === info.id) effortMarkers.delete(messageID)
+          }
+        } catch {
+          await warnContentFree(client, "Could not clear captured reasoning-effort markers.")
+        }
       } else if (event.type === "session.compacted") {
         const sessionId: string = (event.properties as { sessionID: string }).sessionID
         await injectStandards(client, sessionId)
@@ -218,5 +266,59 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
         )
       }
     },
+
+    // -----------------------------------------------------------------------
+    // Hook 6: capture a dispatch marker from an incoming user message. The
+    // marker travels in the dispatch packet text; storing it by message id
+    // lets the later chat.params hook apply it to the same request.
+    // -----------------------------------------------------------------------
+    "chat.message": async (input, output) => {
+      try {
+        const texts = output.parts.map((part) =>
+          part?.type === "text" ? part.text : undefined
+        )
+        const level = findEffortMarker(texts)
+        if (level !== undefined) {
+          effortMarkers.set(output.message.id, { sessionID: input.sessionID, level })
+        }
+      } catch {
+        await warnContentFree(client, "Could not scan a message for a reasoning-effort marker.")
+      }
+    },
+
+    // -----------------------------------------------------------------------
+    // Hook 7: resolve the request's reasoning level (dispatch marker, then
+    // session flag, then routing default) and merge the model's own variant
+    // options. Any failure leaves the request unchanged.
+    // -----------------------------------------------------------------------
+    "chat.params": async (input, output) => {
+      try {
+        const stored = effortMarkers.get(input.message.id)
+        const marker = stored && stored.sessionID === input.sessionID ? stored.level : undefined
+        const session = readSessionEffort(input.sessionID)
+        const routing = readRoutingReasoning(readRoutingConfig(directory), input.agent)
+        const level = resolveEffort({ marker, session, routing })
+        if (level === undefined) return
+
+        const applied = applyEffort(output.options, level, input.model)
+        if (applied === output.options) {
+          if (marker !== undefined) {
+            const warningKey = `${input.sessionID}:${marker}`
+            if (!warnedEffortLevels.has(warningKey)) {
+              warnedEffortLevels.add(warningKey)
+              await warnContentFree(
+                client,
+                `Reasoning effort ${marker} is not available for agent ${input.agent}; ` +
+                  "request left unchanged."
+              )
+            }
+          }
+          return
+        }
+        output.options = applied
+      } catch {
+        await warnContentFree(client, "Could not apply a reasoning-effort level to a request.")
+      }
+    },
   }
 }

package/scripts/codeops_effort.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Record and clear the opt-in reasoning-effort level for a CodeOps session run.
+
+The skills call this helper when a user passes `--auto-effort`. It writes one
+small JSON file inside the session's CodeOps temp directory; the plugin reads
+that file on every request and applies the level. The command fails closed:
+an invalid level or a directory outside the CodeOps temp root exits with
+status 2 and writes nothing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+#: The only levels a session flag may record.
+EFFORT_LEVELS = ("low", "medium", "high", "max")
+
+#: Name of the state file the plugin reads.
+STATE_FILE_NAME = "reasoning-effort.json"
+
+
+def codeops_tmp_root() -> Path:
+    """Return the CodeOps-owned temp root for the active temp directory.
+
+    The root mirrors the layout `bin/lib/tmp-hygiene.mjs` owns, so the helper
+    and the plugin resolve the same per-session directory.
+
+    Returns:
+        Resolved path of the CodeOps temp root.
+    """
+    return Path(tempfile.gettempdir()).resolve() / "opencode" / "codeops"
+
+
+def resolve_session_dir(raw_dir: str) -> Path | None:
+    """Validate a session directory argument against the CodeOps temp root.
+
+    A directory is accepted only when it exists, resolves strictly inside the
+    CodeOps temp root, and is not the root itself. Symlinks are resolved, so a
+    link that points outside the root is rejected.
+
+    Args:
+        raw_dir: The `--dir` argument as provided by the caller.
+
+    Returns:
+        The resolved session directory, or None when it is not acceptable.
+    """
+    try:
+        resolved = Path(raw_dir).resolve(strict=True)
+    except (OSError, RuntimeError):
+        # RuntimeError covers a symlink loop on Python 3.12, which the
+        # filesystem reports as ELOOP rather than a plain OSError.
+        return None
+    root = codeops_tmp_root()
+    if resolved == root or root not in resolved.parents:
+        return None
+    if not resolved.is_dir():
+        return None
+    return resolved
+
+
+def state_path(session_dir: Path) -> Path:
+    """Return the state-file path inside a validated session directory.
+
+    Args:
+        session_dir: A directory accepted by `resolve_session_dir`.
+
+    Returns:
+        Path of the reasoning-effort state file.
+    """
+    return session_dir / STATE_FILE_NAME
+
+
+def set_level(session_dir: Path, level: str) -> int:
+    """Write the session level atomically and report it.
+
+    The payload is written to a temporary file in the same directory and then
+    moved over the final name with `os.replace`, so a reader never observes a
+    partially written file.
+
+    Args:
+        session_dir: A validated session directory.
+        level: One of `EFFORT_LEVELS`.
+
+    Returns:
+        Process exit code 0.
+    """
+    payload = {
+        "schema": 1,
+        "reasoning": level,
+        "setAt": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+    }
+    path = state_path(session_dir)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f"{STATE_FILE_NAME}.", suffix=".tmp", dir=session_dir
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, separators=(",", ":"), sort_keys=True)
+            handle.write("\n")
+        os.replace(temporary_name, path)
+    except OSError:
+        try:
+            os.unlink(temporary_name)
+        except OSError:
+            pass
+        print("Error: could not write the reasoning-effort state file.", file=sys.stderr)
+        return 2
+    print(f"Reasoning effort set: {level} for this session run.")
+    return 0
+
+
+def clear_level(session_dir: Path) -> int:
+    """Remove the session level when present and report the cleanup.
+
+    Args:
+        session_dir: A validated session directory.
+
+    Returns:
+        Process exit code 0.
+    """
+    try:
+        state_path(session_dir).unlink()
+    except FileNotFoundError:
+        pass
+    except OSError:
+        print("Error: could not remove the reasoning-effort state file.", file=sys.stderr)
+        return 2
+    print("Reasoning effort cleared.")
+    return 0
+
+
+def show_status(session_dir: Path) -> int:
+    """Print the stored session level, or the empty-state message.
+
+    Args:
+        session_dir: A validated session directory.
+
+    Returns:
+        Process exit code 0.
+    """
+    level = None
+    try:
+        payload = json.loads(state_path(session_dir).read_text(encoding="utf-8"))
+        if (
+            isinstance(payload, dict)
+            and payload.get("schema") == 1
+            and payload.get("reasoning") in EFFORT_LEVELS
+        ):
+            level = payload["reasoning"]
+    except (OSError, json.JSONDecodeError):
+        level = None
+    if level is None:
+        print("No session reasoning effort set.")
+    else:
+        print(f"Session reasoning effort: {level}")
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse the command-line arguments.
+
+    Returns:
+        The parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    set_parser = sub.add_parser("set", help="record a session reasoning level")
+    set_parser.add_argument("--dir", required=True, help="session temp directory")
+    set_parser.add_argument("--reasoning", required=True, help="level to record")
+
+    clear_parser = sub.add_parser("clear", help="remove the session reasoning level")
+    clear_parser.add_argument("--dir", required=True, help="session temp directory")
+
+    status_parser = sub.add_parser("status", help="print the session reasoning level")
+    status_parser.add_argument("--dir", required=True, help="session temp directory")
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Run the requested command.
+
+    Returns:
+        Process exit code: 0 on success, 2 on invalid input.
+    """
+    args = parse_args()
+    session_dir = resolve_session_dir(args.dir)
+    if session_dir is None:
+        print(
+            "Error: --dir must be an existing session directory inside the CodeOps temp root.",
+            file=sys.stderr,
+        )
+        return 2
+    if args.command == "set":
+        if args.reasoning not in EFFORT_LEVELS:
+            print(
+                "Error: --reasoning must be one of: " + ", ".join(EFFORT_LEVELS) + ".",
+                file=sys.stderr,
+            )
+            return 2
+        return set_level(session_dir, args.reasoning)
+    if args.command == "clear":
+        return clear_level(session_dir)
+    return show_status(session_dir)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/exec-plan/SKILL.md

@@ -36,6 +36,18 @@ do not report or implement optional additions raised during execution or review.
 Exploration may create `SE-*` proposals, but only the user may choose `Keep` and authorize a plan
 update.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means each phase's `Reasoning:` level is printed as a suggestion only, more than one
+or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. A bare
+flag follows each phase's suggestion; `--auto-effort=<level>` forces that level for the whole run,
+including every dispatch marker composed during it. The run clears the level before its final
+summary.
+
 Execute the implementation plan at `plans/$ARGUMENTS/99-execution-plan.md`. The first
 argument is the feature name; an optional flag selects the commit mode.
 

package/skills/exec-plan/execution-protocol.md

@@ -70,6 +70,10 @@ scope baseline; missing mode context fails closed to strict scope.
 When opt-in outcome metrics are enabled, record only a content-free execution-stage event through
 `codeops_outcomes.py`; metrics never gate execution.
 
+When the phase header carries `> **Reasoning**: <level> — <reason>`, record it as the phase's
+advisory level for dispatch markers, inline reporting, and applied-level reporting. It is a
+suggestion: no gate reads it, and its absence means "inherit".
+
 **Spec-author dispatch (profile-gated).** Tasks marked `[spec-author]` dispatch the
 spec-test-author agent — packet per `_shared/quality-profile.md` — BEFORE any implementation
 task of that phase, and the red phase is confirmed from its report. A spec test that cannot be
@@ -300,12 +304,46 @@ receives nothing else and must not need anything else:
 - the scope mode (`strict` or `explore`) and confirmed product scope baseline; missing or invalid
   scope context fails closed to strict mode. Missing or invalid original-goal or smallest-design
   context blocks dispatch;
-- the target file paths and the project's verify command.
+- the target file paths and the project's verify command;
+- the phase's reasoning marker line (`[codeops-effort: <level>]`), resolved from the run's forced
+  `--auto-effort=<level>` level, else the phase's `Reasoning:` suggestion; omitted when neither
+  exists.
 
 Excerpting owned content into a packet is the intended retrieval mechanism, not restatement. The
 quoted AR/ST/spec content is context for the executor's *understanding* — it must not surface as a
 citation in shipped code (the executor carries the same doc-standard ban and self-check).
 
+**Reasoning marker.** Every dispatched unit — executor, reviewer, auditor, spec-test author,
+specialist, or scout — receives one standalone marker line in its packet:
+
+```text
+[codeops-effort: medium]
+```
+
+Place it immediately after the `[codeops-dispatch …]` header for quality agents, or as the first
+line for packets without a header. When neither the forced run level nor the phase suggestion
+exists, add no marker: routing policy still applies, otherwise the child inherits the parent
+variant. The marker is packet context; it never appears in shipped code comments. The
+complexity-gate design challenger is excluded because its independence contract forbids extra
+packet shaping.
+
+**Applied-level reporting.** For every dispatch, report the level and its source in the dispatch
+commentary, for example `Dispatch: executor — reasoning: medium (phase suggestion)`,
+`— reasoning: high (routing default)`, or `— inherited`. Reporting is observational; it never
+gates a dispatch.
+
+**Inline phases.** When a phase runs inline (the default):
+
+1. Print `Suggested reasoning: <level> — <reason>` before the phase's first task when the phase
+   header carries the line.
+2. Without `--auto-effort`, change nothing else — the session keeps its own variant.
+3. With `--auto-effort`, set the session level for the phase through
+   `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_effort.py" set --dir "$CODEOPS_TMPDIR" --reasoning <level>`
+   and update it when the next phase's suggestion differs; with `--auto-effort=<level>`, set that
+   level once and keep it for the whole run. A phase without a `Reasoning:` line leaves the
+   session level unchanged.
+4. When `$CODEOPS_TMPDIR` is empty or the helper fails, print an advise-only note and continue.
+
 **Division of labor.** The PARENT — never the executor — updates `99-execution-plan.md`
 (two-stage marks), the Progress header, and the roadmap. The executor implements task-by-task,
 runs verify per the Verify-output capture rule, and reports per task. Mark `[~]` as the executor
@@ -404,8 +442,10 @@ otherwise still `[~]` — with the progress counter and Last Updated stamp curre
 2. **🚨 First: update `99-execution-plan.md`** with ALL completed tasks (before anything else).
 3. Run the verify command (output captured per the Verify-output capture rule).
 4. Handle the commit per the active commit mode (see [commit-modes.md](commit-modes.md)).
-5. Report the session summary (must include `Execution Plan Updated: ✅`).
-6. **Cleanup:** delete every temporary artifact this session created — verify logs under
+5. If this run set a session level through `--auto-effort`, clear it before the summary:
+   `python3 "${CODEOPS_PLUGIN_ROOT}/scripts/codeops_effort.py" clear --dir "$CODEOPS_TMPDIR"`.
+6. Report the session summary (must include `Execution Plan Updated: ✅`).
+7. **Cleanup:** delete every temporary artifact this session created — verify logs under
    `$CODEOPS_TMPDIR`, scratch directories, temporary diffs — per
    `_shared/workspace-hygiene.md`, and report `Cleanup: done` or name what was kept and why.
 

package/skills/grill-me/SKILL.md

@@ -21,6 +21,16 @@ implementation work begins.
 
 > **CodeOps Artifact Schema**: 1
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 ## Core Directive
 
 > **Interview the user relentlessly about every aspect of the topic until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.**

package/skills/make-plan/SKILL.md

@@ -24,6 +24,16 @@ If `$ARGUMENTS` contains exactly one exact standalone `--explore-scope` token be
 do not report or plan optional additions. Exploration may propose `SE-*` items but
 never accepts them; only the user may choose `Keep`.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 ## Plan readiness proof
 
 A plan is not ready merely because its documents exist. Before presenting it as executable,
@@ -106,6 +116,7 @@ Mini-plan shape:
 
 > **Type**: Task (lightweight) · **Feature**: search · **CodeOps Artifact Schema**: 1
 > **Progress**: 0/3 tasks (0%)
+> **Reasoning**: medium — bounded UI change reusing existing patterns
 
 ## Objective
 Debounce the search box to 300ms to cut redundant queries.
@@ -121,6 +132,12 @@ shared debounce subsystem.
 **Verify**: [project verify command]
 ```
 
+Every phase and every task mini-plan carries the same advisory
+`> **Reasoning**: <level> — <reason>` line. Derive the level from the signals the plan already
+records, using [../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Plan
+suggestion derivation, and keep the reason a short plain-language phrase. The line is a
+suggestion: no gate reads it, deleting it is valid, and its absence means "inherit".
+
 Everything below is the **full feature** pipeline; skip it for tasks.
 
 ## Project configuration

package/skills/make-plan/templates.md

@@ -458,6 +458,8 @@ task-size criteria in [quality-checklist.md](quality-checklist.md))
 > committed, staged, unstaged, and untracked phase-start state)_
 > **Lenses**: [add-on lenses — include this line only when the target repo carries a quality
 > profile; informational: activation stays profile-driven]
+> **Reasoning**: [advisory level — `low`, `medium`, `high`, or `max`, with a one-line reason;
+> derivation in `../../_shared/reasoning-effort.md` §Plan suggestion derivation]
 
 ### Step 1.1: [Step Objective]
 

package/skills/make-requirements/SKILL.md

@@ -27,6 +27,16 @@ requirements decisions under that policy and propagate its downward-only context
 invoked supported children; an unsupported child fails closed. This mode does not grant action permission or scope expansion. **Normal mode:** without the exact token, every material choice
 still requires an explicit user decision; historical delegated records must not infer delegated authority.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 Transform a rough project idea into a structured, complete set of formal
 **requirement documents (RDs)**. This skill is upstream of, and independent
 from, the make-plan skill — neither requires the other.

package/skills/preflight/SKILL.md

@@ -33,6 +33,16 @@ If `$ARGUMENTS` contains exactly one exact standalone `--explore-scope` token be
 do not report optional additions as findings or suggestions. Exploration records them
 as separate `SE-*` proposals; finding resolution never chooses `Keep`.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`, or `max` with `--thorough`) is printed
+as a suggestion only, more than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 Run a rigorous quality audit of the artifact named in `$ARGUMENTS`, **grounded in the actual
 codebase**. Find every issue, ambiguity, contradiction, gap, and risk; verify every claim and
 assumption against the real code; present each finding with options + a recommendation; iterate

package/skills/retro-requirements/SKILL.md

@@ -20,6 +20,16 @@ description: >-
 
 > **CodeOps Artifact Schema**: 1
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 Analyze an existing codebase — any language, any framework — and produce a
 structured **reconstruction brief** that can be fed to the make-requirements
 skill to generate formal requirement documents capable of rebuilding the entire

package/skills/setup-routing/SKILL.md

@@ -50,6 +50,8 @@ Present:
 
 - detected domains and concrete evidence;
 - phase tag → capability/effort policy;
+- reasoning-effort defaults per role when risk signals justify them (see
+  [routing.md](routing.md) §Reasoning effort policy);
 - required specialist reviewers;
 - proposed concurrency limit;
 - whether custom TOML agents add value over dynamic packets; and

package/skills/setup-routing/routing.md

@@ -27,7 +27,7 @@ CodeOps routing lives under the optional `routing` and `quality` fields in `code
 
 Allowed effort values follow the active OpenCode release. Prefer `medium` for bounded reconnaissance, `high` for correctness/security review, and higher supported levels only for genuinely demanding semantic or architectural work.
 
-An optional per-role `reasoning` field sets the provider reasoning-effort passthrough (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). Generated project specialists default to `max` through their brief or the embedded `reasoningEffort`; a routing value wins over the brief. A model that rejects the option is overridden here — there is no automatic provider-capability detection.
+An optional per-role `reasoning` field sets the provider reasoning-effort passthrough (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). Generated project specialists default to `max` through their brief or the embedded `reasoningEffort`; a routing value wins over the brief and is embedded without provider-capability detection. At runtime the plugin applies a level only when the active model exposes a matching variant; an unsupported value leaves the request unchanged (see the policy below).
 
 ```json
 "roles": {
@@ -35,6 +35,21 @@ An optional per-role `reasoning` field sets the provider reasoning-effort passth
 }
 ```
 
+## Reasoning effort policy
+
+A role's `reasoning` entry is a project default, not the only source. The runtime resolution
+order is `dispatch marker > session auto-effort > routing role default > inherit parent variant`
+(see [../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md)). A dispatch marker
+comes from an execution plan's per-phase suggestion; a session level comes from an explicit
+`--auto-effort` run. Both override the routing default for their scope, and routing applies only
+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.
+
 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.
 
 Reviewer selection is driven by risk tags:

package/skills/upgrade-plan/SKILL.md

@@ -7,6 +7,16 @@ description: Upgrade an existing CodeOps requirements set, specification, plan,
 
 The current CodeOps artifact schema is `1`. Historical Claude CodeOps `3.x` stamps describe the producing skill release, not this schema. Treat them as legacy input requiring assessment, not as numeric predecessors of schema 1.
 
+## Auto-effort option
+
+If `$ARGUMENTS` contains exactly one exact standalone `--auto-effort` or `--auto-effort=<level>`
+token before the first `--` sentinel, remove it before resolving targets, paths, or modes; zero
+occurrences means this skill's recommended level (`high`) is printed as a suggestion only, more
+than one or an invalid level is an argument error; announce
+`Auto-effort active — reasoning <level> applied for this run`; then read and apply
+[../../_shared/reasoning-effort.md](../../_shared/reasoning-effort.md) §Auto-effort option. The
+run clears the level before its final summary.
+
 ## Scope
 
 Upgrade content and structure in place. Layout moves belong to `setup-codeops`. Never combine a layout migration and semantic/schema upgrade into one irreversible operation.