opencode-codeops 1.10.3 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 2.0.0 — 2026-10-06
+
+### Breaking Changes
+
+- port plugin to the OpenCode 2 plugin API
+
+### Fixes
+
+- docs: use a placeholder version in the plugin CLI example
+
+## 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

package/README.md

@@ -46,8 +46,8 @@ npx -y opencode-codeops@latest update    # alias of install
 ```
 
 `install`/`update` writes the skills and subagents onto the filesystem (OpenCode discovers those
-only from disk), then registers the plugin in the OpenCode config by calling OpenCode's own
-`opencode plugin` command, so standards injection and `CODEOPS_PLUGIN_ROOT` are enabled. Restart
+only from disk), then registers the plugin in the OpenCode config by calling OpenCode 2's own
+`opencode plugin add` command, so standards injection and `CODEOPS_PLUGIN_ROOT` are enabled. Restart
 OpenCode after installing for the plugin to load. Pass `--no-plugin` to manage the config yourself.
 
 The installer also places the shared `_shared/` and `references/` documents beside the installed
@@ -56,16 +56,18 @@ them resolve at their installed location. An existing directory with either name
 with `--force`.
 
 The scope is auto-detected: inside a CodeOps project (a git repo with `.opencode/` or
-`codeops/.codeops.yml`) it installs into `./.opencode`, and registers the plugin in the project
+`codeops/.codeops.yml`) it installs into `./.opencode` and registers the plugin in the project
 config; anywhere else it installs globally into `~/.config/opencode` and the global config. Pass
-`--project` or `--global` to force one.
+`--project` or `--global` to force one. OpenCode 2's CLI manages package plugins globally, so a
+project-scope install registers the plugin globally with a note while the skills and agents stay
+project-scoped.
 
-If you prefer to register the plugin manually instead, add it to your `opencode.json`:
+If you prefer to register the plugin manually instead, add it to your `opencode.jsonc`:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-codeops"]
+  "plugins": ["opencode-codeops"]
 }
 ```
 
@@ -92,23 +94,26 @@ npx -y opencode-codeops@latest uninstall
 `status` reports the installed skills and agents versions and the configured plugin entry, so a
 mismatch is visible. Use `--dry-run` to preview an install; a same-named file the package does not
 own is skipped with a warning, and `--force` replaces it. `uninstall` removes the skills and
-subagents but leaves the plugin entry in your config; remove `opencode-codeops` from the `plugin`
+subagents but leaves the plugin entry in your config; remove `opencode-codeops` from the `plugins`
 array by hand to fully disable it.
 
 ### Local development
 
-Symlink the plugin into your OpenCode plugin directory and link the installed files to a checkout,
-so edits are picked up without reinstalling. Pass `--no-plugin` so the checkout is not overwritten
-by a registered npm plugin:
+OpenCode 2's `opencode plugin add` accepts npm or Git package specifiers only, so a checkout is
+loaded through a local plugin file. Place a one-line re-export in a plugin directory and link the
+installed files to the checkout so edits are picked up without reinstalling:
 
 ```bash
-# Plugin (project or global plugin directory)
-ln -s /path/to/opencode-codeops/plugin/index.ts ~/.config/opencode/plugins/codeops.ts
+# Plugin — project scope (use ~/.config/opencode/plugins/ for every project)
+mkdir -p .opencode/plugins
+printf 'export { default } from "%s/plugin/index.ts"\n' "$PWD" > .opencode/plugins/codeops.ts
 
 # Skills and agents — link instead of copy
-node /path/to/opencode-codeops/bin/index.mjs install --link --global --no-plugin
+node bin/index.mjs install --link --global --no-plugin
 ```
 
+Pass `--no-plugin` so the checkout entry is not overwritten by a registered npm plugin.
+
 ## Setup
 
 After installing the plugin and the files, initialize CodeOps in your project:
@@ -128,7 +133,8 @@ git commit -m "chore: initialize CodeOps"
 
 ## What the plugin does automatically
 
-On every OpenCode session start and after every compaction, the plugin injects:
+The plugin adds the CodeOps standards to every model request as system instructions, and also to
+every compaction summary, so they are always active:
 - `standards/coding-standards.md` — coding quality, security, testing, and working-style rules
 - `standards/output-style.md` — how to report findings, format tables, and recommend next steps
 
@@ -136,17 +142,24 @@ These standards are active without any user action. They do not need to be copie
 
 The plugin also warns (non-blocking) if any tool attempts to edit `codeops/.codeops.yml` directly — that file is managed exclusively by the `setup-codeops` skill — and if the installed skills version differs from the plugin version, so a stale install is visible.
 
-Every session also gets a workspace-hygiene guard: the plugin exports `CODEOPS_TMPDIR`, a per-session scratch directory under the OS temp directory. Skills and agents put temporary files there and delete them when the run completes; the plugin removes the directory when the session is deleted and sweeps directories abandoned by interrupted runs at session start, so CodeOps does not accumulate scratch data. The full protocol is in `_shared/workspace-hygiene.md`.
+Every session also gets a workspace-hygiene guard: the plugin exports `CODEOPS_TMPDIR`, a scratch
+directory under the OS temp directory that belongs to the running OpenCode plugin instance. Skills
+and agents put temporary files there and delete them when the run completes; the plugin removes the
+directory when it unloads and sweeps directories abandoned by interrupted runs at startup, so
+CodeOps does not accumulate scratch data. Because OpenCode 2 does not expose a session id to shell
+hooks, concurrent sessions served by one instance share this directory. The full protocol is in
+`_shared/workspace-hygiene.md`.
 
 ## Agent model configuration
 
 All CodeOps subagents inherit the model of the primary agent that invoked them. No provider-specific configuration is required out of the box.
 
-To pin specific models per role, use the `setup-routing` skill or add overrides directly in `opencode.json`:
+To pin specific models per role, use the `setup-routing` skill or add overrides directly in
+`opencode.jsonc`:
 
 ```json
 {
-  "agent": {
+  "agents": {
     "demanding-executor": { "model": "anthropic/claude-opus-4-5" },
     "executor":           { "model": "anthropic/claude-haiku-4" }
   }
@@ -166,8 +179,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
 
@@ -202,7 +217,8 @@ updates the index.
 
 ## Requirements
 
-- OpenCode (current)
+- OpenCode 2.0+ (this release uses the OpenCode 2 plugin API; on OpenCode 1, use
+  `opencode-codeops@1`)
 - Bash
 - Python 3.8+
 - Git

package/_shared/reasoning-effort.md

@@ -16,13 +16,20 @@ 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 options: the exact variant when it exists, otherwise the nearest exposed level on the
+provider scale, with ties resolving to the higher level. On OpenCode 2 the plugin reads those
+options from the registered model's `variants` collection and merges the chosen entry's settings
+into the request. `none` stays exact-match only, because mapping it to a reasoning level would
+enable reasoning the caller disabled. When no variant can be chosen — the model exposes no
+matching variant — 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 +106,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.
@@ -119,10 +129,12 @@ invalid `=<level>` is an argument error.
 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`.
+2. Record the level for the run in the runtime scratch directory through
+   `scripts/codeops_effort.py`. When one runtime serves more than one concurrent session, the
+   most recently recorded level applies to all of them.
 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
+5. Fail-open: when the runtime scratch 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.
@@ -134,10 +146,10 @@ 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.
+`reasoning-effort-trace.jsonl` inside the runtime's scratch directory. Lines carry only a
+timestamp, session id, 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 runtime
+scratch and is removed with it. Tracing is off by default and never affects a request.
 
 ## Suggestion-only guarantee
 

package/_shared/workspace-hygiene.md

@@ -15,13 +15,17 @@ outputs are deliverables — not temporary artifacts — and they are never dele
 
 ## Where temporary artifacts live
 
-1. `$CODEOPS_TMPDIR` when the CodeOps plugin exports it (one directory per session). Use it for
-   every scratch file.
+1. `$CODEOPS_TMPDIR` when the CodeOps plugin exports it (one directory per OpenCode runtime).
+   Use it for every scratch file.
 2. Otherwise, the operating system's temp directory.
 3. Never inside the repository. A repository path is durable space; scratch does not belong there.
 
 Create subdirectories under the temp root lazily, only when the task needs them.
 
+OpenCode 2 does not expose a session identifier to shell hooks, so the plugin owns one scratch
+directory per runtime instead of one per session. Sessions served by the same runtime share it;
+keep scratch file names specific to the run to avoid collisions.
+
 ## Lifecycle
 
 1. **Create lazily** — write a temporary file only when the task needs it.
@@ -47,7 +51,7 @@ Create subdirectories under the temp root lazily, only when the task needs them.
 
 ## Automatic safety net
 
-The CodeOps plugin exports `$CODEOPS_TMPDIR` for each session and removes that session's directory
-when the session is deleted. At session start it also removes CodeOps temp directories older than
-seven days, so an interrupted run cannot leak storage forever. The safety net is a fallback, not a
-substitute: the run itself still performs the cleanup pass above.
+The CodeOps plugin exports `$CODEOPS_TMPDIR` for each runtime and removes that runtime's
+directory when the plugin unloads. At startup it also removes CodeOps temp directories older
+than seven days, so an interrupted run cannot leak storage forever. The safety net is a
+fallback, not a substitute: the run itself still performs the cleanup pass above.

package/bin/index.mjs

@@ -135,11 +135,17 @@ async function runCombined(command, rest, io) {
     const result = registerPlugin({ scope, version, cwd, run: io.run })
     if (result.ok) {
       console.log(`Plugin: registered ${result.spec} in the ${scope} OpenCode config.`)
+      if (scope === "project" && result.dialect === "add") {
+        console.log(
+          "Note: the OpenCode 2 CLI manages package plugins globally; " +
+            "skills and agents remain project-scoped."
+        )
+      }
       console.log("Restart OpenCode to load the plugin.")
     } else {
       console.log(
         `Plugin: not registered (${result.reason}). ` +
-          `Add "${PLUGIN_NAME}" to the "plugin" array in your opencode.json.`
+          `Add "${PLUGIN_NAME}" to the "plugins" array in your opencode.jsonc.`
       )
     }
   }

package/bin/lib/opencode-plugin.mjs

@@ -2,13 +2,16 @@
 /**
  * Registers (or inspects) the CodeOps plugin in OpenCode's own config.
  *
- * OpenCode ships a command that installs a plugin and updates the config
- * safely, including JSON/JSONC formatting and version replacement:
+ * OpenCode 2 ships a command that installs a plugin and updates the config
+ * safely, including JSON/JSONC formatting and version replacement. Two CLI
+ * shapes exist across releases:
  *
- *   opencode plugin <module> [--global] [--force]
+ *   opencode plugin add <module>        (OpenCode 2 subcommand form)
+ *   opencode plugin <module> [--global] (older form; still used by some builds)
  *
- * The installer delegates to that command instead of editing `opencode.json`
- * itself, so it never has to parse JSONC or risk clobbering a user's config.
+ * The installer probes the installed CLI once and uses the shape it accepts.
+ * This CodeOps version requires OpenCode 2; running it against OpenCode 1
+ * fails with a direct pointer to the 1.x line, because the plugin API changed.
  * All calls are best-effort: if the `opencode` executable is missing or the
  * command fails, the caller still completes the file install and tells the user
  * how to register the plugin manually.
@@ -21,6 +24,9 @@ import { spawnSync } from "node:child_process"
 /** The npm package name of the plugin. */
 export const PLUGIN_NAME = "opencode-codeops"
 
+/** The OpenCode major version this package requires. */
+export const REQUIRED_OPENCODE_MAJOR = 2
+
 /**
  * Runs a command and normalizes the result.
  *
@@ -39,37 +45,84 @@ export function defaultRun(command, args, options = {}) {
   }
 }
 
+/**
+ * Extract the OpenCode major version from `opencode --version` output.
+ *
+ * @param versionText - Raw version output
+ * @returns The major version, or `undefined` when no semver is present
+ *
+ * @example
+ * parseOpenCodeMajor("2.0.24") // 2
+ */
+export function parseOpenCodeMajor(versionText) {
+  const match = /(\d+)\.\d+\.\d+/.exec(String(versionText ?? ""))
+  return match ? Number(match[1]) : undefined
+}
+
 /**
  * Builds the arguments for `opencode plugin`.
  *
  * @param details - Plugin registration inputs
- * @param details.scope - `"global"` adds `--global`; `"project"` omits it
+ * @param details.scope - `"global"` adds `--global` when the CLI supports it
  * @param details.version - Exact version to pin, or `undefined` for the bare name
+ * @param details.dialect - `"add"` for `plugin add <spec>`, `"positional"` otherwise
+ * @param details.supportsGlobal - Whether the chosen dialect accepts `--global`
  * @returns Arguments after the `opencode` executable
+ *
  * @example
- * buildPluginArgs({ scope: "global", version: "1.0.0" })
- * // ["plugin", "opencode-codeops@1.0.0", "--global", "--force"]
+ * buildPluginArgs({ scope: "global", version: "1.2.3", dialect: "add", supportsGlobal: true })
+ * // ["plugin", "add", "opencode-codeops@1.2.3", "--global"]
  */
-export function buildPluginArgs({ scope, version }) {
+export function buildPluginArgs({ scope, version, dialect = "positional", supportsGlobal = true }) {
   const module = version ? `${PLUGIN_NAME}@${version}` : PLUGIN_NAME
+  const global = scope === "global" && supportsGlobal
+
+  if (dialect === "add") {
+    const args = ["plugin", "add", module]
+    if (global) args.push("--global")
+    return args
+  }
+
   const args = ["plugin", module]
-  if (scope === "global") args.push("--global")
+  if (global) args.push("--global")
   args.push("--force")
   return args
 }
 
+/**
+ * Detect which `opencode plugin` shape the installed CLI accepts.
+ *
+ * The subcommand form answers `opencode plugin add --help`; older builds treat
+ * `add` as a module name and fail. The help text also tells whether the
+ * subcommand accepts an explicit `--global` flag.
+ *
+ * @param details - Detection inputs
+ * @param details.cwd - Working directory
+ * @param details.run - Command runner, injectable for tests
+ * @returns The dialect and whether it supports `--global`
+ */
+export function detectPluginDialect({ cwd, run = defaultRun }) {
+  const help = run("opencode", ["plugin", "add", "--help"], { cwd })
+  if (!help.error && help.status === 0) {
+    const text = `${help.stdout}\n${help.stderr}`
+    return { dialect: "add", supportsGlobal: /--global\b/.test(text) }
+  }
+  return { dialect: "positional", supportsGlobal: true }
+}
+
 /**
  * Registers the plugin in the OpenCode config.
  *
- * Tries the exact version first so plugin and files stay in sync; if the CLI
- * rejects the versioned spec, falls back to the bare package name. Never throws.
+ * Requires OpenCode 2. Tries the exact version first so plugin and files stay
+ * in sync; if the CLI rejects the versioned spec, falls back to the bare
+ * package name. Never throws.
  *
  * @param details - Registration inputs
  * @param details.scope - `"global"` or `"project"`
  * @param details.version - Version to pin
  * @param details.cwd - Working directory (used for project scope)
  * @param details.run - Command runner, injectable for tests
- * @returns Whether registration succeeded, the spec used, and a reason on failure
+ * @returns Whether registration succeeded, the spec used, the dialect, and a reason on failure
  */
 export function registerPlugin({ scope, version, cwd, run = defaultRun }) {
   try {
@@ -78,30 +131,69 @@ export function registerPlugin({ scope, version, cwd, run = defaultRun }) {
       return { ok: false, spec: null, reason: "opencode CLI not found on PATH" }
     }
 
-    const pinned = run("opencode", buildPluginArgs({ scope, version }), { cwd })
-    if (!pinned.error && pinned.status === 0) {
-      return { ok: true, spec: `${PLUGIN_NAME}@${version}` }
+    const major = parseOpenCodeMajor(probe.stdout)
+    if (major !== undefined && major < REQUIRED_OPENCODE_MAJOR) {
+      return {
+        ok: false,
+        spec: null,
+        reason:
+          `OpenCode ${REQUIRED_OPENCODE_MAJOR} is required (found ${probe.stdout.trim()}); ` +
+          "on OpenCode 1, use opencode-codeops@1",
+      }
     }
 
-    const bare = run("opencode", buildPluginArgs({ scope, version: null }), { cwd })
-    if (!bare.error && bare.status === 0) {
-      return { ok: true, spec: PLUGIN_NAME }
+    const { dialect, supportsGlobal } = detectPluginDialect({ cwd, run })
+    let lastMessage = "opencode plugin command failed"
+
+    for (const candidate of [version, null]) {
+      const args = buildPluginArgs({ scope, version: candidate, dialect, supportsGlobal })
+      const result = run("opencode", args, { cwd })
+      if (!result.error && result.status === 0) {
+        return {
+          ok: true,
+          spec: candidate ? `${PLUGIN_NAME}@${candidate}` : PLUGIN_NAME,
+          dialect,
+        }
+      }
+      const message = (result.stderr || result.stdout || "").trim()
+      lastMessage = message.split("\n").pop() || lastMessage
     }
 
-    const message = (bare.stderr || bare.stdout || pinned.stderr || pinned.stdout || "").trim()
-    return { ok: false, spec: null, reason: message.split("\n").pop() || "opencode plugin failed" }
+    return { ok: false, spec: null, reason: lastMessage }
   } catch (caught) {
     return { ok: false, spec: null, reason: caught.message }
   }
 }
 
 /**
- * Reads the resolved `plugin` list from OpenCode's effective config.
+ * Normalize one configured plugin entry to its package spec.
+ *
+ * OpenCode accepts plain spec strings, `[spec, options]` tuples, and
+ * `{ package, options }` objects across versions, so the status readout must
+ * understand all three.
+ *
+ * @param item - Raw config entry
+ * @returns The spec string, or `undefined` when the entry is unusable
+ */
+function entrySpec(item) {
+  if (typeof item === "string") return item
+  if (Array.isArray(item) && typeof item[0] === "string") return item[0]
+  if (item && typeof item === "object" && typeof item.package === "string") {
+    return item.package
+  }
+  return undefined
+}
+
+/**
+ * Reads the resolved plugin list from OpenCode's effective config.
+ *
+ * OpenCode 2 uses `plugins`; the legacy singular `plugin` key is still read as
+ * a fallback so mixed configs are reported correctly.
  *
  * @param details - Inspection inputs
  * @param details.cwd - Working directory
  * @param details.run - Command runner, injectable for tests
- * @returns The plugin entries, or `undefined` when the config cannot be read
+ * @returns The plugin spec strings, or `undefined` when the config cannot be read
  */
 export function readConfiguredPlugin({ cwd, run = defaultRun } = {}) {
   try {
@@ -109,7 +201,13 @@ export function readConfiguredPlugin({ cwd, run = defaultRun } = {}) {
     if (result.error || result.status !== 0) return undefined
 
     const config = JSON.parse(result.stdout)
-    return Array.isArray(config.plugin) ? config.plugin : []
+    const raw = Array.isArray(config.plugins)
+      ? config.plugins
+      : Array.isArray(config.plugin)
+        ? config.plugin
+        : []
+
+    return raw.map(entrySpec).filter((spec) => typeof spec === "string")
   } catch {
     return undefined
   }

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

@@ -81,9 +81,20 @@ export declare function extractModelVariants(
   model: unknown
 ): Record<string, unknown> | undefined
 
+/** Normalize a host variant collection (v2 array or v1 record) into a record. */
+export declare function normalizeModelVariants(
+  variants: unknown
+): Record<string, unknown>
+
 /** 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>,