opencode-codeops 1.10.0 → 1.10.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to CodeOps are recorded here.
 
+## 1.10.2 — 2026-10-04
+
+### Fixes
+
+- effort: remember dispatch markers per session
+
+## 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

@@ -43,6 +43,10 @@ A dispatch marker is one standalone line in a dispatch message:
 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.
 
+A captured marker is remembered for the whole session: every request in that session uses it
+until a newer marker replaces it or the session ends. This is what keeps the marker effective
+when the host passes a later user message to the request hook.
+
 ## Precedence
 
 The most specific source wins:
@@ -126,6 +130,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.2",
   "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,16 +176,31 @@ 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
 // ---------------------------------------------------------------------------
 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 }>()
+  // the latest dispatch-marker level per session, plus a deduplication set
+  // for unsupported-level warnings.
+  const effortMarkers = new Map<string, EffortLevel>()
   const warnedEffortLevels = new Set<string>()
+  const effortTraceEnabled = isEffortTraceEnabled(process.env.CODEOPS_EFFORT_TRACE)
 
   return {
     // -----------------------------------------------------------------------
@@ -202,9 +221,7 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
         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)
-          }
+          effortMarkers.delete(info.id)
         } catch {
           await warnContentFree(client, "Could not clear captured reasoning-effort markers.")
         }
@@ -269,8 +286,9 @@ 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.
+    // marker travels in the dispatch packet text; it is remembered for the
+    // whole session, because the later chat.params hook receives the latest
+    // user message, which can differ from the message that carried it.
     // -----------------------------------------------------------------------
     "chat.message": async (input, output) => {
       try {
@@ -279,7 +297,12 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
         )
         const level = findEffortMarker(texts)
         if (level !== undefined) {
-          effortMarkers.set(output.message.id, { sessionID: input.sessionID, level })
+          effortMarkers.set(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.")
@@ -293,15 +316,40 @@ export const CodeOpsPlugin: Plugin = async ({ client, directory }) => {
     // -----------------------------------------------------------------------
     "chat.params": async (input, output) => {
       try {
-        const stored = effortMarkers.get(input.message.id)
-        const marker = stored && stored.sessionID === input.sessionID ? stored.level : undefined
+        const marker = effortMarkers.get(input.sessionID)
         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)) {