opencode-codeops 1.10.0 → 1.10.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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

package/_shared/reasoning-effort.md

@@ -126,6 +126,15 @@ Semantics:
 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 |

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

@@ -57,6 +57,19 @@ export declare function readSessionEffort(
   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,

package/bin/lib/reasoning-effort.mjs

@@ -19,10 +19,10 @@
  * @module lib/reasoning-effort
  */
 
-import { lstatSync, readFileSync } from "node:fs"
+import { appendFileSync, lstatSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 
-import { sessionTmpDir } from "./tmp-hygiene.mjs"
+import { ensureSessionTmpDir, sessionTmpDir } from "./tmp-hygiene.mjs"
 
 /**
  * The four levels a plan or skill may suggest.
@@ -198,6 +198,58 @@ export function readSessionEffort(sessionID, base) {
   }
 }
 
+/**
+ * Check whether the optional trace environment switch is on.
+ *
+ * Tracing is opt-in and diagnostic: it is enabled only when the value is
+ * exactly `1` or `true`, compared case-insensitively. Every other value,
+ * including `undefined`, disables it.
+ *
+ * @param value - Raw `CODEOPS_EFFORT_TRACE` value
+ * @returns True only for `"1"` or `"true"` in any case
+ */
+export function isEffortTraceEnabled(value) {
+  if (typeof value !== "string") return false
+  const normalized = value.trim().toLowerCase()
+  return normalized === "1" || normalized === "true"
+}
+
+/**
+ * Compute the trace-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-trace.jsonl`
+ */
+export function sessionEffortTracePath(sessionID, base) {
+  return join(sessionTmpDir(sessionID, base), "reasoning-effort-trace.jsonl")
+}
+
+/**
+ * Append one content-free trace entry to the session trace file.
+ *
+ * The entry is serialized as one compact JSON line. Nothing here inspects or
+ * interprets the entry; callers must never pass prompt text, file content, or
+ * secrets. The session directory is created when missing. Any failure — an
+ * unwritable path, an unserializable entry — returns false instead of
+ * throwing, because tracing must never affect a request.
+ *
+ * @param sessionID - Session identifier
+ * @param entry - Plain, content-free record to append
+ * @param base - Base temp directory (injectable for tests)
+ * @returns True when the line was appended, false otherwise
+ */
+export function appendEffortTrace(sessionID, entry, base) {
+  try {
+    const line = `${JSON.stringify(entry)}\n`
+    ensureSessionTmpDir(sessionID, base)
+    appendFileSync(sessionEffortTracePath(sessionID, base), line, "utf-8")
+    return true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Read an agent's explicit reasoning entry from the project routing config.
  *

package/package.json

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

package/plugin/index.ts

@@ -10,8 +10,12 @@ import {
   removeSessionTmpDir,
 } from "../bin/lib/tmp-hygiene.mjs"
 import {
+  appendEffortTrace,
   applyEffort,
   findEffortMarker,
+  isEffortLevel,
+  isEffortTraceEnabled,
+  isRoutingReasoning,
   readRoutingReasoning,
   readSessionEffort,
   resolveEffort,
@@ -172,6 +176,20 @@ function readRoutingConfig(directory: string): unknown {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Helper — append one content-free trace line when the optional
+// CODEOPS_EFFORT_TRACE switch is on. Tracing is diagnostic only: it never
+// affects a request and swallows its own failures.
+// ---------------------------------------------------------------------------
+function traceEffort(
+  enabled: boolean,
+  sessionID: string,
+  entry: Record<string, unknown>
+): void {
+  if (!enabled) return
+  appendEffortTrace(sessionID, { ts: new Date().toISOString(), ...entry })
+}
+
 // ---------------------------------------------------------------------------
 // CodeOps plugin for OpenCode
 // Replaces: hooks/hooks.json + hook_session_context.sh + hook_marker_guard.sh
@@ -182,6 +200,7 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
   // deduplication set for unsupported-level warnings.
   const effortMarkers = new Map<string, { sessionID: string; level: EffortLevel }>()
   const warnedEffortLevels = new Set<string>()
+  const effortTraceEnabled = isEffortTraceEnabled(process.env.CODEOPS_EFFORT_TRACE)
 
   return {
     // -----------------------------------------------------------------------
@@ -280,6 +299,11 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
         const level = findEffortMarker(texts)
         if (level !== undefined) {
           effortMarkers.set(output.message.id, { sessionID: input.sessionID, level })
+          traceEffort(effortTraceEnabled, input.sessionID, {
+            event: "capture",
+            messageID: output.message.id,
+            level,
+          })
         }
       } catch {
         await warnContentFree(client, "Could not scan a message for a reasoning-effort marker.")
@@ -298,10 +322,36 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
         const session = readSessionEffort(input.sessionID)
         const routing = readRoutingReasoning(readRoutingConfig(directory), input.agent)
         const level = resolveEffort({ marker, session, routing })
-        if (level === undefined) return
+        const source = isEffortLevel(marker)
+          ? "marker"
+          : isEffortLevel(session)
+            ? "session"
+            : isRoutingReasoning(routing)
+              ? "routing"
+              : "none"
+        if (level === undefined) {
+          traceEffort(effortTraceEnabled, input.sessionID, {
+            event: "apply",
+            messageID: input.message.id,
+            agent: input.agent,
+            level: null,
+            source,
+            applied: false,
+          })
+          return
+        }
 
         const applied = applyEffort(output.options, level, input.model)
-        if (applied === output.options) {
+        const changed = applied !== output.options
+        traceEffort(effortTraceEnabled, input.sessionID, {
+          event: "apply",
+          messageID: input.message.id,
+          agent: input.agent,
+          level,
+          source,
+          applied: changed,
+        })
+        if (!changed) {
           if (marker !== undefined) {
             const warningKey = `${input.sessionID}:${marker}`
             if (!warnedEffortLevels.has(warningKey)) {