opencode-codeops 1.9.0 → 1.10.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.10.1 — 2026-10-04
+
+### Features
+
+- effort: add opt-in applied-level trace
+
+## 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,144 @@
+# 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.
+
+## Optional tracing
+
+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.
+
+## 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,98 @@
+/**
+ * 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
+
+/** Check whether the optional trace environment switch is on. */
+export declare function isEffortTraceEnabled(value: unknown): boolean
+
+/** Compute the trace-file path inside the session temp directory. */
+export declare function sessionEffortTracePath(sessionID?: string, base?: string): string
+
+/** Append one content-free trace entry to the session trace file. */
+export declare function appendEffortTrace(
+  sessionID: string | undefined,
+  entry: unknown,
+  base?: string
+): boolean
+
+/** 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>