opencode-doom-loop-detector 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 metal-huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# opencode-doom-loop-detector
+
+Doom-loop detection for opencode v2, as an external plugin.
+
+opencode v2 currently has no doom-loop detection: the `doom_loop` action is still accepted by the permission schema, but no code produces it. This plugin restores detection for anyone who installs it, with no changes to the opencode runner.
+
+## What it catches
+
+Four complementary detectors:
+
+1. **Same-message guard** (the v1 behavior, unchanged): the same call emitted 3 times inside one assistant message asks once.
+2. **Signal A** — per-signature identical-output streak (warn 3, block 6). Counting is per signature, so periodic rotations and interleaved calls never reset it. A repeat only counts when the output is byte-identical, so a read-edit-test cycle with real progress never builds a streak.
+3. **Signal B** — line-level information novelty (warn 3/5, surgical ask at 8 only when that signature's A streak is ≥3, circuit breaker at 12). Outputs shorter than 3 lines are exempt.
+4. **Signal C** — per-signature failure-equivalence streak (warn 4, block 6). Volatile error tokens are normalized, and successes of other signatures do not reset it.
+
+Every stop goes through the existing `doom_loop` permission ask, so intentional polling always has an escape hatch. A user message resets A/C as well as B and the breaker (per-turn scope), so a periodic legitimate re-check cannot accumulate into a block over days.
+
+## Install
+
+Either use the CLI:
+
+```bash
+opencode plugin add opencode-doom-loop-detector
+```
+
+Or add the package to your `opencode.jsonc` directly (opencode installs missing npm plugins automatically at startup):
+
+```jsonc
+{
+  "plugin": ["opencode-doom-loop-detector"]
+}
+```
+
+No configuration is required. The default thresholds are the ones above.
+
+## How it works
+
+- The detector is a zero-dependency pure module plus a thin plugin on the public `@opencode/plugin` API.
+- State is kept in memory with bounded maps (LRU caps) and a bounded line store, and is rebuilt from durable session history after a restart.
+- Cost is about 0.1 ms per tool call on a real 199-call incident corpus, with no I/O and no runtime dependencies beyond the opencode plugin/schema packages and Effect.
+- A denial of the circuit-breaker prompt makes the stop sticky (until the user speaks); a rejection with feedback (`Permission.CorrectedError`) returns the feedback to the model instead of stopping.
+
+## Verification
+
+- This package: 45 tests pass (37 detector + 8 integration), `tsc --noEmit` clean.
+- Upstream PR: 67 tests pass, typecheck clean; the review bot confirmed all four threads it raised are fixed.
+- Upstream PR: https://github.com/anomalyco/opencode/pull/61328
+- Incident analysis and call-by-call replays: https://metal-huang.github.io/opencode/doom-loop-report/
+- Prior-art review of 14 harnesses: https://metal-huang.github.io/opencode/doom-loop-report/prior-art.html
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,449 @@
+// src/index.ts
+import { define } from "@opencode/plugin/effect/plugin";
+import { Effect, Exit, Option, Scope, Stream } from "effect";
+import { Tool } from "@opencode/schema/tool";
+
+// src/detector.ts
+var A_WARN = 3;
+var A_BLOCK = 6;
+var B_WARN_LOW = 3;
+var B_WARN_HIGH = 5;
+var B_BLOCK = 8;
+var B_CIRCUIT = 12;
+var B_MIN_LINES = 3;
+var C_WARN = 4;
+var C_BLOCK = 6;
+var GUARD_TRIGGER = 3;
+var UNOBSERVED_PROMPT = 6;
+var LINE_LIMIT = 1e4;
+var LINE_CAP = 1024;
+var TIGHTENED_LINE_KEEP = 1000;
+var SIGNATURE_LIMIT = 4096;
+var FNV_OFFSET = 0xcbf29ce484222325n;
+var FNV_PRIME = 0x100000001b3n;
+var FNV_MASK = 0xffffffffffffffffn;
+function fnv64(text) {
+  let hash = FNV_OFFSET;
+  for (let index = 0;index < text.length; index++) {
+    hash ^= BigInt(text.charCodeAt(index));
+    hash = hash * FNV_PRIME & FNV_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function canonical(value) {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value === undefined ? null : value);
+    return primitive === undefined ? "null" : primitive;
+  }
+  if (Array.isArray(value))
+    return `[${value.map(canonical).join(",")}]`;
+  const record = value;
+  const body = Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(",");
+  return `{${body}}`;
+}
+var signature = (tool, input) => fnv64(`${tool}:${canonical(input)}`);
+var normalizeVolatile = (line) => line.replace(/[0-9a-f]{8,}/gi, "<id>").replace(/\b\d+(?:\.\d+)?(?:ns|us|ms|s|m|h)\b/g, "<duration>").replace(/\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?\b/g, "<timestamp>").replace(/\b\d+(?:\.\d+)?\b/g, "<num>");
+var SEPARATOR = /^[-=_*~ ]{3,}$/;
+var contentLines = (text) => text.split(`
+`).map((line) => line.trim()).filter((line) => line.length > 0 && !SEPARATOR.test(line)).map((line) => normalizeVolatile(line).slice(0, LINE_CAP));
+var stringify = (value) => {
+  if (typeof value === "string")
+    return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+};
+function outputText(content, output) {
+  if (typeof content === "string")
+    return content;
+  if (content !== undefined && content.length > 0)
+    return content.flatMap((item) => item.type === "text" && typeof item.text === "string" ? [item.text] : []).join(`
+`);
+  return stringify(output);
+}
+var copy = {
+  warnA: (tool, streak) => `The ${tool} call with these exact arguments has returned byte-identical output ${streak} times in a row. It is not producing new information. Change approach: inspect the actual current state, or ask the user.`,
+  warnB3: `Your recent tool calls have produced no new information. Before making another call, write down what new information you expect the next call to reveal.`,
+  warnB5: `These repeated calls keep returning nothing new. Choose one: run a falsification check on your current hypothesis, ask the user for the missing input, or conclude based on the evidence you already have.`,
+  warnC: (tool, streak) => `The ${tool} tool has failed ${streak} times in a row with the same error. Stop retrying it unchanged. Inspect the target or ask the user before trying again.`,
+  blockA: (tool, streak) => `This exact ${tool} call has returned identical output ${streak} times in a row and is blocked as a suspected repetition loop. If this repetition is intentional (for example user-requested polling), approve the doom_loop permission to continue.`,
+  blockB: `Recent calls keep producing nothing new, and this exact call has already returned identical output repeatedly. It is blocked as suspected non-progress. Run a falsification check, ask the user for missing input, or conclude with the evidence at hand.`,
+  blockC: (tool, streak) => `The ${tool} tool has failed ${streak} times in a row with the same error and is blocked as a suspected retry loop. Inspect the target state or ask the user before trying again.`,
+  circuit: `Twelve recent tool calls in a row produced no new information. Stop making tool calls entirely. Summarize the current state, the hypotheses you have ruled out, and what input you need from the user, in plain text.`,
+  guard: (count, tool) => `This exact ${tool} call has already been emitted ${count} times within the current assistant message. If the same invocation is repeating without progress, stop and report to the user instead.`,
+  guardMerged: (count, tool, aStreak) => `This exact ${tool} call has been emitted ${count} times within the current assistant message and returned identical output ${aStreak} times before. Stop repeating it and report to the user instead.`,
+  unobserved: `This call's progress cannot be observed from the session output (for example a background shell). If you are running it in a loop: write progress to a file and report from it, report the current status directly to the user, or stop and summarize.`
+};
+var resourceSuffix = { guard: ":repeat", unobserved: ":unobserved", a: "", b: "", c: "" };
+var VALIDATION_PREFIX = "Invalid arguments for tool";
+function injectedWarnings(tool) {
+  const a = copy.warnA(tool, A_WARN);
+  return [a, copy.warnB3, copy.warnB5, `${a}
+
+${copy.warnB3}`, `${a}
+
+${copy.warnB5}`];
+}
+var injectedFailureSuffix = (tool) => `
+
+${copy.warnC(tool, C_WARN)}`;
+var blockedMetadata = { doom_loop: "blocked" };
+var hasBlockedMetadata = (metadata) => metadata?.doom_loop === blockedMetadata.doom_loop;
+function state() {
+  return {
+    signatures: new Map,
+    lines: { set: new Set, order: [] },
+    bStreak: 0,
+    failures: new Map,
+    emitted: { messageID: "", counts: new Map },
+    unobserved: new Map,
+    highTierPrompted: false,
+    circuitBroken: false
+  };
+}
+function beforeCall(current, call) {
+  if (current.circuitBroken)
+    return { kind: "circuit", message: copy.circuit, sticky: true };
+  if (current.bStreak >= B_CIRCUIT)
+    return { kind: "circuit", message: copy.circuit, sticky: false };
+  if (current.emitted.messageID !== call.messageID) {
+    current.emitted = { messageID: call.messageID, counts: new Map };
+  }
+  const emitted = (current.emitted.counts.get(call.sigHash) ?? 0) + 1;
+  current.emitted.counts.set(call.sigHash, emitted);
+  if (emitted === GUARD_TRIGGER) {
+    const entry = current.signatures.get(call.sigHash);
+    const message = entry !== undefined && entry.streak >= A_WARN ? copy.guardMerged(emitted, call.tool, entry.streak) : copy.guard(emitted, call.tool);
+    return { kind: "assert", signal: "guard", message };
+  }
+  const unobserved = current.unobserved.get(call.sigHash) ?? 0;
+  if (unobserved >= UNOBSERVED_PROMPT && !current.highTierPrompted) {
+    current.highTierPrompted = true;
+    return { kind: "assert", signal: "unobserved", message: copy.unobserved };
+  }
+  const entry = current.signatures.get(call.sigHash);
+  if (entry !== undefined && entry.streak >= A_BLOCK) {
+    return { kind: "assert", signal: "a", message: copy.blockA(call.tool, entry.streak) };
+  }
+  if (current.bStreak >= B_BLOCK && entry !== undefined && entry.streak >= A_WARN) {
+    return { kind: "assert", signal: "b", message: copy.blockB };
+  }
+  const failure = current.failures.get(call.sigHash);
+  if (failure !== undefined && failure.streak >= C_BLOCK) {
+    return { kind: "assert", signal: "c", message: copy.blockC(call.tool, failure.streak) };
+  }
+  return { kind: "pass" };
+}
+function lruSet(map, key, value) {
+  map.delete(key);
+  map.set(key, value);
+  if (map.size <= SIGNATURE_LIMIT)
+    return;
+  const oldest = map.keys().next().value;
+  if (oldest !== undefined)
+    map.delete(oldest);
+}
+function recordCompleted(current, call) {
+  current.failures.delete(call.sigHash);
+  const outputHash = fnv64(call.text);
+  const previous = current.signatures.get(call.sigHash);
+  const entry = previous !== undefined && previous.lastOutputHash === outputHash ? { lastOutputHash: outputHash, streak: previous.streak + 1 } : { lastOutputHash: outputHash, streak: 1 };
+  lruSet(current.signatures, call.sigHash, entry);
+  const warnings = [];
+  if (entry.streak === A_WARN)
+    warnings.push(copy.warnA(call.tool, entry.streak));
+  const lines = contentLines(call.text);
+  if (lines.length >= B_MIN_LINES) {
+    const distinct = [...new Set(lines)];
+    let novel = 0;
+    for (const line of distinct) {
+      if (!current.lines.set.has(line))
+        novel++;
+    }
+    const productive = novel >= 2 || novel / lines.length >= 0.5;
+    if (productive) {
+      current.bStreak = 0;
+    } else {
+      current.bStreak++;
+      if (current.bStreak === B_WARN_LOW)
+        warnings.push(copy.warnB3);
+      if (current.bStreak === B_WARN_HIGH)
+        warnings.push(copy.warnB5);
+    }
+    for (const line of distinct)
+      addLine(current, line);
+  }
+  return warnings.length === 0 ? undefined : warnings.join(`
+
+`);
+}
+function addLine(current, line) {
+  if (current.lines.set.has(line))
+    return;
+  current.lines.set.add(line);
+  current.lines.order.push(line);
+  if (current.lines.order.length > LINE_LIMIT) {
+    const evicted = current.lines.order.splice(0, LINE_LIMIT / 2);
+    for (const old of evicted)
+      current.lines.set.delete(old);
+  }
+}
+function recordFailed(current, call) {
+  if (call.validation)
+    return;
+  const failureHash = fnv64(normalizeVolatile(call.errorText));
+  const previous = current.failures.get(call.sigHash);
+  const entry = previous !== undefined && previous.lastFailureHash === failureHash ? { lastFailureHash: failureHash, streak: previous.streak + 1 } : { lastFailureHash: failureHash, streak: 1 };
+  lruSet(current.failures, call.sigHash, entry);
+  if (entry.streak === C_WARN)
+    return copy.warnC(call.tool, entry.streak);
+  return;
+}
+function recordUnobserved(current, sigHash) {
+  lruSet(current.unobserved, sigHash, (current.unobserved.get(sigHash) ?? 0) + 1);
+}
+function compacted(current) {
+  for (const entry of current.signatures.values())
+    entry.streak = 0;
+  current.lines.set.clear();
+  current.lines.order = [];
+  current.bStreak = 0;
+}
+function userMessage(current) {
+  current.signatures.clear();
+  current.failures.clear();
+  current.bStreak = 0;
+  current.circuitBroken = false;
+}
+function filesChanged(current) {
+  current.bStreak = 0;
+}
+function tighten(current) {
+  if (current.lines.order.length <= TIGHTENED_LINE_KEEP)
+    return;
+  const evicted = current.lines.order.splice(0, current.lines.order.length - TIGHTENED_LINE_KEEP);
+  for (const old of evicted)
+    current.lines.set.delete(old);
+}
+// src/fold.ts
+var UNEXECUTED_ERROR_TYPES = new Set(["aborted", "tool.input-json", "tool.input-incomplete"]);
+function fold(state, messages) {
+  for (const message of messages) {
+    if (message.type === "user") {
+      userMessage(state);
+      continue;
+    }
+    if (message.type !== "assistant")
+      continue;
+    for (const part of message.content) {
+      if (part.type !== "tool" || part.name === "execute")
+        continue;
+      if (part.state.status === "error") {
+        if (hasBlockedMetadata(part.state.metadata) || UNEXECUTED_ERROR_TYPES.has(part.state.error.type))
+          continue;
+        const suffix = injectedFailureSuffix(part.name);
+        const message = part.state.error.message;
+        const errorText = message.endsWith(suffix) ? message.slice(0, -suffix.length) : message;
+        recordFailed(state, {
+          tool: part.name,
+          sigHash: signature(part.name, part.state.input),
+          errorText,
+          validation: errorText.startsWith(VALIDATION_PREFIX)
+        });
+        continue;
+      }
+      if (part.state.status !== "completed")
+        continue;
+      const sigHash = signature(part.name, part.state.input);
+      if (part.name === "question" || part.name === "shell" && part.state.metadata?.status === "running") {
+        recordUnobserved(state, sigHash);
+        continue;
+      }
+      const first = part.state.content[0];
+      const content = first !== undefined && first.type === "text" && injectedWarnings(part.name).includes(first.text) ? part.state.content.slice(1) : part.state.content;
+      recordCompleted(state, {
+        tool: part.name,
+        sigHash,
+        text: outputText(content)
+      });
+    }
+  }
+  tighten(state);
+  state.bStreak = 0;
+}
+
+// src/index.ts
+var DEFAULT_MAX_TRACKED_SESSIONS = 64;
+var circuitKey = (sessionID) => `circuit:${sessionID}`;
+function makePlugin(options) {
+  const cap = options?.maxTrackedSessions ?? DEFAULT_MAX_TRACKED_SESSIONS;
+  return define({
+    id: "opencode.doom.loop",
+    effect: Effect.fn(function* (ctx) {
+      const scope = yield* Scope.Scope;
+      const sessions = new Map;
+      const folded = (sessionID) => Effect.runPromise(Effect.gen(function* () {
+        const entry = { state: state() };
+        const messages = yield* ctx.session.context({ sessionID });
+        fold(entry.state, messages);
+        if ((yield* ctx.storage.get(circuitKey(sessionID))) === true)
+          entry.state.circuitBroken = true;
+        return entry;
+      })).catch(() => ({ state: state() }));
+      const session = (sessionID) => {
+        const existing = sessions.get(sessionID);
+        if (existing) {
+          sessions.delete(sessionID);
+          sessions.set(sessionID, existing);
+          return existing;
+        }
+        const created = folded(sessionID);
+        sessions.set(sessionID, created);
+        while (sessions.size > cap) {
+          const oldest = sessions.keys().next().value;
+          if (oldest === undefined)
+            break;
+          sessions.delete(oldest);
+        }
+        return created;
+      };
+      const mutate = (sessionID, fn) => {
+        const existing = sessions.get(sessionID);
+        if (existing)
+          sessions.set(sessionID, existing.then((entry) => {
+            fn(entry.state);
+            return entry;
+          }));
+      };
+      yield* ctx.tool.hook("execute.before", (event) => Effect.gen(function* () {
+        if (event.tool === "execute")
+          return;
+        const current = yield* Effect.promise(() => session(event.sessionID));
+        const sigHash = signature(event.tool, event.input);
+        const verdict = beforeCall(current.state, {
+          tool: event.tool,
+          sigHash,
+          messageID: event.messageID
+        });
+        if (verdict.kind === "pass")
+          return;
+        if (verdict.kind === "circuit") {
+          if (verdict.sticky) {
+            yield* ctx.session.interrupt({ sessionID: event.sessionID }).pipe(Effect.ignore, Effect.forkIn(scope));
+            return yield* new Tool.Error({ message: verdict.message, metadata: blockedMetadata });
+          }
+          const resource = `${event.tool}:${sigHash}${resourceSuffix.b}`;
+          const outcome = yield* Effect.exit(ctx.permission.assert({
+            sessionID: event.sessionID,
+            agent: event.agent,
+            action: "doom_loop",
+            resources: [resource],
+            save: [resource],
+            source: { type: "tool", messageID: event.messageID, id: event.id }
+          }));
+          if (Exit.isSuccess(outcome)) {
+            current.state.bStreak = 0;
+            return;
+          }
+          const error = Option.getOrUndefined(Exit.findErrorOption(outcome));
+          const tagOf = (value) => typeof value === "object" && value !== null && ("_tag" in value) ? value._tag : undefined;
+          const corrected = tagOf(error) === "Permission.CorrectedError" || error instanceof Tool.Error && tagOf(error.error) === "Permission.CorrectedError";
+          if (!corrected) {
+            yield* ctx.storage.set(circuitKey(event.sessionID), true).pipe(Effect.ignore);
+            current.state.circuitBroken = true;
+            yield* ctx.session.interrupt({ sessionID: event.sessionID }).pipe(Effect.ignore, Effect.forkIn(scope));
+          }
+          return yield* new Tool.Error({
+            message: `${verdict.message}
+
+${error?.message ?? "rejected"}`,
+            metadata: blockedMetadata
+          });
+        }
+        const resource = `${event.tool}:${sigHash}${resourceSuffix[verdict.signal]}`;
+        return yield* ctx.permission.assert({
+          sessionID: event.sessionID,
+          agent: event.agent,
+          action: "doom_loop",
+          resources: [resource],
+          save: [resource],
+          source: { type: "tool", messageID: event.messageID, id: event.id }
+        }).pipe(Effect.mapError((error) => new Tool.Error({
+          message: `${verdict.message}
+
+${error.message}`,
+          metadata: blockedMetadata
+        })));
+      }));
+      yield* ctx.tool.hook("execute.after", (event) => Effect.gen(function* () {
+        if (event.tool === "execute")
+          return;
+        const current = yield* Effect.promise(() => session(event.sessionID));
+        const sigHash = signature(event.tool, event.input);
+        if (event.status === "error") {
+          const warning = recordFailed(current.state, {
+            tool: event.tool,
+            sigHash,
+            errorText: event.error.message,
+            validation: event.error.message.startsWith(VALIDATION_PREFIX)
+          });
+          if (warning !== undefined)
+            event.error.message = `${event.error.message}
+
+${warning}`;
+          return;
+        }
+        const unobserved = event.tool === "question" || event.tool === "shell" && event.result.metadata !== undefined && event.result.metadata.status === "running";
+        if (unobserved) {
+          recordUnobserved(current.state, sigHash);
+          return;
+        }
+        const text = outputText(event.result.content, event.result.output);
+        const warning = recordCompleted(current.state, { tool: event.tool, sigHash, text });
+        if (warning === undefined)
+          return;
+        const existing = event.result.content;
+        event.result = {
+          ...event.result,
+          content: [
+            { type: "text", text: warning },
+            ...typeof existing === "string" ? [{ type: "text", text: existing }] : existing ?? []
+          ]
+        };
+      }));
+      yield* ctx.event.subscribe().pipe(Stream.filter((event) => event.type === "session.deleted" || event.type === "session.inbox.enqueued" || event.type === "session.step.ended" || event.type === "session.compaction.ended" || event.type === "session.execution.succeeded" || event.type === "session.execution.failed" || event.type === "session.execution.interrupted"), Stream.runForEach((event) => Effect.gen(function* () {
+        const sessionID = event.data.sessionID;
+        if (event.type === "session.deleted") {
+          sessions.delete(sessionID);
+          yield* ctx.storage.remove(circuitKey(sessionID)).pipe(Effect.ignore);
+          return;
+        }
+        if (event.type === "session.inbox.enqueued") {
+          if (event.data.item.type !== "user")
+            return;
+          yield* ctx.storage.remove(circuitKey(sessionID)).pipe(Effect.ignore);
+          mutate(sessionID, userMessage);
+          return;
+        }
+        if (event.type === "session.step.ended") {
+          if (event.data.files === undefined || event.data.files.length === 0)
+            return;
+          mutate(sessionID, filesChanged);
+          return;
+        }
+        if (event.type === "session.compaction.ended") {
+          mutate(sessionID, compacted);
+          return;
+        }
+        mutate(sessionID, tighten);
+      })), Effect.forkScoped({ startImmediately: true }));
+    })
+  });
+}
+var Plugin = makePlugin();
+export {
+  Plugin,
+  makePlugin
+};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "opencode-doom-loop-detector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Doom-loop detection for opencode v2: catches repeated tool-call loops (consecutive, periodic rotation, failure streaks) and stops them through the existing doom_loop permission ask.",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:metal-huang/opencode-doom-loop-detector",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --external @opencode/plugin --external @opencode/schema --external effect",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": "^2.2.5",
+    "@opencode/schema": "^2.2.5",
+    "effect": "4.0.6"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.2.5",
+    "@opencode/schema": "^2.2.5",
+    "effect": "4.0.6",
+    "typescript": "^5.9.0"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "doom-loop",
+    "loop-detection",
+    "agent"
+  ]
+}

package/src/detector.ts

@@ -0,0 +1,382 @@
+export * as DoomLoopDetector from "./detector.js"
+
+// Pure doom-loop detection core: no Effect, no opencode imports, portable across hosts.
+// Four detectors:
+// - Signal A: per-signature (tool + canonical input) identical-output streak. Warn 3, block 6.
+// - Signal B: global line-level information novelty. Warn 3/5, surgical block 8 (needs A streak >= 3
+//   as corroboration), circuit breaker 12 (hard stop until the user speaks).
+// - Signal C: per-tool failure-equivalence streak (volatile tokens normalized before hashing).
+//   Warn 4, block 6. Interleaved successes of other tools do not reset it; a success of the same
+//   tool does.
+// - Same-message repeat guard: identical (tool, input) emitted 3 times within one assistant message
+//   asks exactly once (== 3, not >= 3, so later high-tier prompts cannot be starved by it).
+// Thresholds are accounted in after hooks and read in before hooks: "block at N" means the call
+// emitted after the Nth accounting (the N+1th emission) is the one challenged in before.
+
+const A_WARN = 3
+const A_BLOCK = 6
+const B_WARN_LOW = 3
+const B_WARN_HIGH = 5
+const B_BLOCK = 8
+const B_CIRCUIT = 12
+const B_MIN_LINES = 3
+const C_WARN = 4
+const C_BLOCK = 6
+const GUARD_TRIGGER = 3
+const UNOBSERVED_PROMPT = 6
+const LINE_LIMIT = 10_000
+const LINE_CAP = 1024
+const TIGHTENED_LINE_KEEP = 1_000
+// Per-session cap for the signature (A) and unobserved maps, each bounded independently. An
+// entry is ~100 bytes, so a session worst-cases at ~400KB per map.
+const SIGNATURE_LIMIT = 4_096
+
+const FNV_OFFSET = 0xcbf29ce484222325n
+const FNV_PRIME = 0x100000001b3n
+const FNV_MASK = 0xffffffffffffffffn
+
+export function fnv64(text: string): string {
+  let hash = FNV_OFFSET
+  for (let index = 0; index < text.length; index++) {
+    hash ^= BigInt(text.charCodeAt(index))
+    hash = (hash * FNV_PRIME) & FNV_MASK
+  }
+  return hash.toString(16).padStart(16, "0")
+}
+
+// Canonical JSON with recursively sorted keys so semantically identical inputs hash identically
+// regardless of key order. Bash AST normalization is deliberately omitted (decided): `ls` vs
+// `ls -la` are distinct signatures and escape A, which signal B covers instead.
+export function canonical(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value === undefined ? null : value)
+    return primitive === undefined ? "null" : primitive
+  }
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`
+  const record = value as Record<string, unknown>
+  const body = Object.keys(record)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`)
+    .join(",")
+  return `{${body}}`
+}
+
+export const signature = (tool: string, input: unknown) => fnv64(`${tool}:${canonical(input)}`)
+
+// Volatile tokens (ids, durations, timestamps, plain numbers) collapse to placeholders so that
+// "in 0.03s" and "in 0.05s" normalize to the same line and the same failure identity.
+const normalizeVolatile = (line: string): string =>
+  line
+    .replace(/[0-9a-f]{8,}/gi, "<id>")
+    .replace(/\b\d+(?:\.\d+)?(?:ns|us|ms|s|m|h)\b/g, "<duration>")
+    .replace(/\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?\b/g, "<timestamp>")
+    .replace(/\b\d+(?:\.\d+)?\b/g, "<num>")
+
+const SEPARATOR = /^[-=_*~ ]{3,}$/
+
+// Lines enter the global novelty store normalized and capped at 1KB each (memory bound).
+const contentLines = (text: string): string[] =>
+  text
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !SEPARATOR.test(line))
+    .map((line) => normalizeVolatile(line).slice(0, LINE_CAP))
+
+const stringify = (value: unknown): string => {
+  if (typeof value === "string") return value
+  try {
+    return JSON.stringify(value) ?? String(value)
+  } catch {
+    return String(value)
+  }
+}
+
+// Mirrors the runtime content normalization: a tool result carries either string content, content
+// parts, or (for output-only tools) falls back to the stringified machine output. Hashing must use
+// this normalized view so output-only tools do not all hash as one constant empty string.
+export function outputText(
+  content: string | ReadonlyArray<{ readonly type: string; readonly text?: string }> | undefined,
+  output?: unknown,
+): string {
+  if (typeof content === "string") return content
+  if (content !== undefined && content.length > 0)
+    return content
+      .flatMap((item) => (item.type === "text" && typeof item.text === "string" ? [item.text] : []))
+      .join("\n")
+  return stringify(output)
+}
+
+export const copy = {
+  warnA: (tool: string, streak: number): string =>
+    `The ${tool} call with these exact arguments has returned byte-identical output ${streak} times in a row. It is not producing new information. Change approach: inspect the actual current state, or ask the user.`,
+  warnB3: `Your recent tool calls have produced no new information. Before making another call, write down what new information you expect the next call to reveal.`,
+  warnB5: `These repeated calls keep returning nothing new. Choose one: run a falsification check on your current hypothesis, ask the user for the missing input, or conclude based on the evidence you already have.`,
+  warnC: (tool: string, streak: number): string =>
+    `The ${tool} tool has failed ${streak} times in a row with the same error. Stop retrying it unchanged. Inspect the target or ask the user before trying again.`,
+  blockA: (tool: string, streak: number): string =>
+    `This exact ${tool} call has returned identical output ${streak} times in a row and is blocked as a suspected repetition loop. If this repetition is intentional (for example user-requested polling), approve the doom_loop permission to continue.`,
+  blockB: `Recent calls keep producing nothing new, and this exact call has already returned identical output repeatedly. It is blocked as suspected non-progress. Run a falsification check, ask the user for missing input, or conclude with the evidence at hand.`,
+  blockC: (tool: string, streak: number): string =>
+    `The ${tool} tool has failed ${streak} times in a row with the same error and is blocked as a suspected retry loop. Inspect the target state or ask the user before trying again.`,
+  circuit: `Twelve recent tool calls in a row produced no new information. Stop making tool calls entirely. Summarize the current state, the hypotheses you have ruled out, and what input you need from the user, in plain text.`,
+  guard: (count: number, tool: string): string =>
+    `This exact ${tool} call has already been emitted ${count} times within the current assistant message. If the same invocation is repeating without progress, stop and report to the user instead.`,
+  guardMerged: (count: number, tool: string, aStreak: number): string =>
+    `This exact ${tool} call has been emitted ${count} times within the current assistant message and returned identical output ${aStreak} times before. Stop repeating it and report to the user instead.`,
+  unobserved: `This call's progress cannot be observed from the session output (for example a background shell). If you are running it in a loop: write progress to a file and report from it, report the current status directly to the user, or stop and summarize.`,
+} as const
+
+// Resource/save strings are `${tool}:${sigHash}` with a per-signal suffix so an "always" answer on
+// one prompt never silently exempts another signal's prompt for the same signature.
+export const resourceSuffix = { guard: ":repeat", unobserved: ":unobserved", a: "", b: "", c: "" } as const
+
+// Host-specific strings that mark argument-validation rejections (the tool never executed).
+// Kept in one place so a host copy change is a one-line fix; an unmatched message is treated as a
+// real failure (conservative: counts into C rather than silently exempting it).
+export const VALIDATION_PREFIX = "Invalid arguments for tool"
+
+// Texts the live after hook can inject into a persisted result: warnings prepend to a completed
+// result's content and append to a failed call's error message. They fire only at fixed streaks,
+// so the complete set is enumerable. The fold strips them to hash the same text the live path
+// accounted — live hashes before injecting.
+export function injectedWarnings(tool: string): ReadonlyArray<string> {
+  const a = copy.warnA(tool, A_WARN)
+  return [a, copy.warnB3, copy.warnB5, `${a}\n\n${copy.warnB3}`, `${a}\n\n${copy.warnB5}`]
+}
+
+export const injectedFailureSuffix = (tool: string): string => `\n\n${copy.warnC(tool, C_WARN)}`
+
+// Marker the plugin attaches to Tool.Errors raised by its before hook. It persists on the error
+// part (runner failTool -> Tool.Failed metadata), letting the fold tell a blocked call — never
+// executed, never accounted live — apart from a real execution failure.
+export const blockedMetadata = { doom_loop: "blocked" } as const
+
+export const hasBlockedMetadata = (metadata: Record<string, unknown> | undefined): boolean =>
+  metadata?.doom_loop === blockedMetadata.doom_loop
+
+export type Verdict =
+  | { readonly kind: "pass" }
+  | { readonly kind: "circuit"; readonly message: string; readonly sticky: boolean }
+  | {
+      readonly kind: "assert"
+      readonly signal: keyof typeof resourceSuffix
+      readonly message: string
+    }
+
+export interface SignatureEntry {
+  lastOutputHash: string
+  streak: number
+}
+
+export interface FailureEntry {
+  lastFailureHash: string
+  streak: number
+}
+
+export interface SessionState {
+  signatures: Map<string, SignatureEntry>
+  lines: { set: Set<string>; order: string[] }
+  bStreak: number
+  failures: Map<string, FailureEntry>
+  // Only the current message's bucket is retained; a new messageID drops the old one.
+  emitted: { messageID: string; counts: Map<string, number> }
+  unobserved: Map<string, number>
+  highTierPrompted: boolean
+  circuitBroken: boolean
+}
+
+export function state(): SessionState {
+  return {
+    signatures: new Map(),
+    lines: { set: new Set(), order: [] },
+    bStreak: 0,
+    failures: new Map(),
+    emitted: { messageID: "", counts: new Map() },
+    unobserved: new Map(),
+    highTierPrompted: false,
+    circuitBroken: false,
+  }
+}
+
+export interface Call {
+  readonly tool: string
+  readonly sigHash: string
+  readonly messageID: string
+}
+
+// Short-circuit order: circuit breaker -> same-message guard (==3, one-shot) -> unobserved-layer
+// one-time prompt -> A >= 6 -> B >= 8 surgical (requires A streak >= 3 corroboration) -> C >= 6.
+// The first hit is the only action for this call. A circuit hit is a permission ask like every
+// other signal: allow resets B and lets the run continue; a denial makes it sticky (hard stop).
+export function beforeCall(current: SessionState, call: Call): Verdict {
+  if (current.circuitBroken) return { kind: "circuit", message: copy.circuit, sticky: true }
+  if (current.bStreak >= B_CIRCUIT) return { kind: "circuit", message: copy.circuit, sticky: false }
+  if (current.emitted.messageID !== call.messageID) {
+    current.emitted = { messageID: call.messageID, counts: new Map() }
+  }
+  const emitted = (current.emitted.counts.get(call.sigHash) ?? 0) + 1
+  current.emitted.counts.set(call.sigHash, emitted)
+  if (emitted === GUARD_TRIGGER) {
+    const entry = current.signatures.get(call.sigHash)
+    const message =
+      entry !== undefined && entry.streak >= A_WARN
+        ? copy.guardMerged(emitted, call.tool, entry.streak)
+        : copy.guard(emitted, call.tool)
+    return { kind: "assert", signal: "guard", message }
+  }
+  const unobserved = current.unobserved.get(call.sigHash) ?? 0
+  if (unobserved >= UNOBSERVED_PROMPT && !current.highTierPrompted) {
+    current.highTierPrompted = true
+    return { kind: "assert", signal: "unobserved", message: copy.unobserved }
+  }
+  const entry = current.signatures.get(call.sigHash)
+  if (entry !== undefined && entry.streak >= A_BLOCK) {
+    return { kind: "assert", signal: "a", message: copy.blockA(call.tool, entry.streak) }
+  }
+  if (current.bStreak >= B_BLOCK && entry !== undefined && entry.streak >= A_WARN) {
+    return { kind: "assert", signal: "b", message: copy.blockB }
+  }
+  const failure = current.failures.get(call.sigHash)
+  if (failure !== undefined && failure.streak >= C_BLOCK) {
+    return { kind: "assert", signal: "c", message: copy.blockC(call.tool, failure.streak) }
+  }
+  return { kind: "pass" }
+}
+
+export interface Completed {
+  readonly tool: string
+  readonly sigHash: string
+  readonly text: string
+}
+
+// LRU write for the signature-keyed maps: a write moves the key to the newest position, and the
+// oldest entry is evicted past SIGNATURE_LIMIT. Eviction is indistinguishable from the
+// output-changed branch — a recurred signature restarts at streak 1 — so the loss is
+// miss-direction only and never a false block. A genuinely looping signature re-fires on every
+// call and stays hot; only one not seen for 4096 distinct others is dropped.
+function lruSet<V>(map: Map<string, V>, key: string, value: V) {
+  map.delete(key)
+  map.set(key, value)
+  if (map.size <= SIGNATURE_LIMIT) return
+  const oldest = map.keys().next().value
+  if (oldest !== undefined) map.delete(oldest)
+}
+
+// Accounts a successful call into A and B. Error events never reach this function: failures feed
+// signal C only, so a run of failed calls cannot masquerade as a run of identical empty outputs.
+// Returns warning text to append to the model-visible output, if any.
+export function recordCompleted(current: SessionState, call: Completed): string | undefined {
+  // Only a success of the same signature proves the retry loop is over.
+  current.failures.delete(call.sigHash)
+
+  const outputHash = fnv64(call.text)
+  const previous = current.signatures.get(call.sigHash)
+  const entry: SignatureEntry =
+    previous !== undefined && previous.lastOutputHash === outputHash
+      ? { lastOutputHash: outputHash, streak: previous.streak + 1 }
+      : { lastOutputHash: outputHash, streak: 1 }
+  lruSet(current.signatures, call.sigHash, entry)
+
+  const warnings: string[] = []
+  if (entry.streak === A_WARN) warnings.push(copy.warnA(call.tool, entry.streak))
+
+  const lines = contentLines(call.text)
+  // Outputs shorter than 3 lines are exempt from B: one-line receipts (edit/write) never streak.
+  if (lines.length >= B_MIN_LINES) {
+    // Novelty counts distinct lines: one new line repeated k times inside a single output is still
+    // one new fact and must not inflate the count. The ratio keeps the total line count as its
+    // denominator — "1 new line out of 4" is a decorator variant, not productivity.
+    const distinct = [...new Set(lines)]
+    let novel = 0
+    for (const line of distinct) {
+      if (!current.lines.set.has(line)) novel++
+    }
+    const productive = novel >= 2 || novel / lines.length >= 0.5
+    if (productive) {
+      current.bStreak = 0
+    } else {
+      current.bStreak++
+      if (current.bStreak === B_WARN_LOW) warnings.push(copy.warnB3)
+      if (current.bStreak === B_WARN_HIGH) warnings.push(copy.warnB5)
+    }
+    for (const line of distinct) addLine(current, line)
+  }
+  return warnings.length === 0 ? undefined : warnings.join("\n\n")
+}
+
+function addLine(current: SessionState, line: string) {
+  if (current.lines.set.has(line)) return
+  current.lines.set.add(line)
+  current.lines.order.push(line)
+  // FIFO eviction of the oldest half at the 10k cap keeps the store bounded.
+  if (current.lines.order.length > LINE_LIMIT) {
+    const evicted = current.lines.order.splice(0, LINE_LIMIT / 2)
+    for (const old of evicted) current.lines.set.delete(old)
+  }
+}
+
+export interface Failed {
+  readonly tool: string
+  readonly sigHash: string
+  readonly errorText: string
+  // Argument-validation rejections that never executed do not count (OpenClaw argument-validation
+  // semantics); the model must be free to fix its arguments.
+  readonly validation: boolean
+}
+
+// Failure equivalence is keyed by signature (tool + canonical input), not by tool name alone:
+// different commands of one tool failing with the same normalized error would otherwise block an
+// unrelated call of that tool. A different error means progress and resets the streak. Interleaved
+// successes of other tools deliberately do not reset it.
+export function recordFailed(current: SessionState, call: Failed): string | undefined {
+  if (call.validation) return undefined
+  const failureHash = fnv64(normalizeVolatile(call.errorText))
+  const previous = current.failures.get(call.sigHash)
+  const entry: FailureEntry =
+    previous !== undefined && previous.lastFailureHash === failureHash
+      ? { lastFailureHash: failureHash, streak: previous.streak + 1 }
+      : { lastFailureHash: failureHash, streak: 1 }
+  lruSet(current.failures, call.sigHash, entry)
+  if (entry.streak === C_WARN) return copy.warnC(call.tool, entry.streak)
+  return undefined
+}
+
+// Unobserved layer (background shell, question): A/B/C abstain; only the accounting for the
+// one-time high-tier prompt happens here.
+export function recordUnobserved(current: SessionState, sigHash: string) {
+  lruSet(current.unobserved, sigHash, (current.unobserved.get(sigHash) ?? 0) + 1)
+}
+
+// Context discontinuity (compaction): A's per-signature streaks reset but keep their output hashes,
+// B's line store and streak reset. C intentionally survives: failure equivalence does not depend on
+// context content.
+export function compacted(current: SessionState) {
+  for (const entry of current.signatures.values()) entry.streak = 0
+  current.lines.set.clear()
+  current.lines.order = []
+  current.bStreak = 0
+}
+
+// User message: the circuit breaker's defined escape hatch and the per-turn scope boundary. B and
+// the breaker reset, and A/C counters reset too — a new user turn opens a fresh observation window,
+// so a periodic legitimate re-check cannot accumulate into a block over days. A real loop
+// re-accumulates within seconds after an interrupt, so detection is preserved.
+export function userMessage(current: SessionState) {
+  current.signatures.clear()
+  current.failures.clear()
+  current.bStreak = 0
+  current.circuitBroken = false
+}
+
+// Files actually changed on disk: the world-observable escape for B.
+export function filesChanged(current: SessionState) {
+  current.bStreak = 0
+}
+
+// Execution-end sweep (memory bound): tighten the line store of the session that just finished.
+// A/C counters are preserved here — they only reset on a new user message (per-turn scoping).
+export function tighten(current: SessionState) {
+  if (current.lines.order.length <= TIGHTENED_LINE_KEEP) return
+  const evicted = current.lines.order.splice(0, current.lines.order.length - TIGHTENED_LINE_KEEP)
+  for (const old of evicted) current.lines.set.delete(old)
+}

package/src/fold.ts

@@ -0,0 +1,90 @@
+export * as DoomLoopFold from "./fold.js"
+
+import type { SessionMessage } from "@opencode/schema/session-message"
+import { DoomLoopDetector } from "./detector.js"
+
+// Rebuilds detector state from durable session history when a session is first touched after a
+// restart. The history read is SessionHistory's "latest" view — it starts at the most recent
+// completed compaction — and only the accounting half is replayed. Two calibrations keep the
+// replay faithful to the live path:
+//
+// - Calls the before hook rejected DID persist (as error parts) but were never accounted live,
+//   because a rejected call never reaches execute.after (tool.ts runs before hooks first). The
+//   plugin marks its own rejections (blockedMetadata) and declines/interrupts/input failures carry
+//   non-execution error types; both are skipped here.
+// - Warnings the after hook injected into results persist with them, while live hashes before
+//   injecting; they are stripped so streaks rebuild exactly.
+//
+// Declared losses: C's failure streaks from before the latest compaction are invisible (miss
+// direction; the streak self-heals within a few calls); B restarts with a rebuilt line store but
+// a zero streak — safe because B's surgical block still requires the corroborating A streak,
+// which IS rebuilt; Code Mode inner calls are invisible (the outer "execute" part is skipped,
+// mirroring the live exemption, but the real tool names it re-entered with are not in history).
+// The circuit breaker cannot be folded from history; the plugin persists it separately.
+
+// Error types a persisted error part can carry without the call ever having executed — the live
+// after hook (and thus signal C) never saw them: declines and interruptions ("aborted" —
+// runner step.ts declines, llm.ts settleStaleToolCalls) and input failures that never reached
+// the tool ("tool.input-json" / "tool.input-incomplete" — runner INPUT_FAILURES).
+const UNEXECUTED_ERROR_TYPES = new Set(["aborted", "tool.input-json", "tool.input-incomplete"])
+
+export function fold(state: DoomLoopDetector.SessionState, messages: ReadonlyArray<SessionMessage.Info>) {
+  for (const message of messages) {
+    if (message.type === "user") {
+      DoomLoopDetector.userMessage(state)
+      continue
+    }
+    // Standalone shell messages are user-run commands (Session.shell), not model tool calls; the
+    // model's background shell arrives as a "shell" tool part with metadata.status "running".
+    if (message.type !== "assistant") continue
+    for (const part of message.content) {
+      // The outer Code Mode tool re-enters with real tool names; its own call is exempt, as live.
+      if (part.type !== "tool" || part.name === "execute") continue
+      if (part.state.status === "error") {
+        if (
+          DoomLoopDetector.hasBlockedMetadata(part.state.metadata) ||
+          UNEXECUTED_ERROR_TYPES.has(part.state.error.type)
+        )
+          continue
+        // The live C warning rides the persisted error message; strip it so the failure hash
+        // matches what live accounted. recordFailed excludes argument-validation rejections via
+        // the same message prefix the live path matches on.
+        const suffix = DoomLoopDetector.injectedFailureSuffix(part.name)
+        const message = part.state.error.message
+        const errorText = message.endsWith(suffix) ? message.slice(0, -suffix.length) : message
+        DoomLoopDetector.recordFailed(state, {
+          tool: part.name,
+          sigHash: DoomLoopDetector.signature(part.name, part.state.input),
+          errorText,
+          validation: errorText.startsWith(DoomLoopDetector.VALIDATION_PREFIX),
+        })
+        continue
+      }
+      if (part.state.status !== "completed") continue
+      const sigHash = DoomLoopDetector.signature(part.name, part.state.input)
+      if (part.name === "question" || (part.name === "shell" && part.state.metadata?.status === "running")) {
+        DoomLoopDetector.recordUnobserved(state, sigHash)
+        continue
+      }
+      // The persisted content carries any injected warning prepended by the live after hook;
+      // strip a leading warning part so the hash matches what live accounted.
+      const first = part.state.content[0]
+      const content =
+        first !== undefined &&
+        first.type === "text" &&
+        DoomLoopDetector.injectedWarnings(part.name).includes(first.text)
+          ? part.state.content.slice(1)
+          : part.state.content
+      DoomLoopDetector.recordCompleted(state, {
+        tool: part.name,
+        sigHash,
+        text: DoomLoopDetector.outputText(content),
+      })
+    }
+  }
+  // Match the live steady state: an execution end tightens the store to the newest 1000 lines,
+  // and a fold from a long history could otherwise fill it to the 10k cap.
+  DoomLoopDetector.tighten(state)
+  // Fresh streak over the rebuilt line store is the self-consistent restart state; see header.
+  state.bStreak = 0
+}

package/src/index.ts

@@ -0,0 +1,278 @@
+import { define } from "@opencode/plugin/effect/plugin"
+import type { Session } from "@opencode/schema/session"
+import type { SessionEvent } from "@opencode/schema/session-event"
+import { Effect, Exit, Option, Scope, Stream } from "effect"
+import { Tool } from "@opencode/schema/tool"
+import { DoomLoopDetector } from "./detector.js"
+import { DoomLoopFold } from "./fold.js"
+
+// Session state is rebuilt lazily from durable history on first tool-hook touch (fold), so a
+// process restart continues A/C streaks instead of silently zeroing them. The one fact history
+// cannot rebuild is a tripped circuit breaker (B's streak restarts at zero), so it is persisted
+// in plugin KV and re-armed only by a real user message.
+//
+// Because every entry can be re-folded, the sessions map is a pure cache: past
+// MAX_TRACKED_SESSIONS the least recently touched entry is dropped and re-folded on its next
+// touch. Every eviction loss is miss-direction — bStreak restarts at zero exactly as after a
+// restart, and calls accounted since the last durable write replay short. The breaker survives
+// in KV, and an executing session touches the map on every hook, so the LRU tail is always a
+// session no hook is touching.
+
+const DEFAULT_MAX_TRACKED_SESSIONS = 64
+
+type Tracked =
+  | SessionEvent.Deleted
+  | SessionEvent.InboxEnqueued
+  | SessionEvent.Step.Ended
+  | SessionEvent.Compaction.Ended
+  | SessionEvent.Execution.Succeeded
+  | SessionEvent.Execution.Failed
+  | SessionEvent.Execution.Interrupted
+
+interface Entry {
+  state: DoomLoopDetector.SessionState
+}
+
+const circuitKey = (sessionID: Session.ID) => `circuit:${sessionID}`
+
+// Factory-injected cap: tests construct a plugin with a small cap instead of mutating shared state.
+export function makePlugin(options?: { maxTrackedSessions?: number }) {
+  const cap = options?.maxTrackedSessions ?? DEFAULT_MAX_TRACKED_SESSIONS
+
+  return define({
+    id: "opencode.doom.loop",
+    effect: Effect.fn(function* (ctx) {
+    const scope = yield* Scope.Scope
+    const sessions = new Map<Session.ID, Promise<Entry>>()
+
+    const folded = (sessionID: Session.ID): Promise<Entry> =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          const entry: Entry = { state: DoomLoopDetector.state() }
+          const messages = yield* ctx.session.context({ sessionID })
+          DoomLoopFold.fold(entry.state, messages)
+          if ((yield* ctx.storage.get(circuitKey(sessionID))) === true) entry.state.circuitBroken = true
+          return entry
+        }),
+        // A history read failure must not fail the tool call: fall back to a fresh state (the
+        // pre-fold behavior) rather than dropping detection entirely.
+      ).catch((): Entry => ({ state: DoomLoopDetector.state() }))
+
+    // The promise enters the map synchronously so concurrent first touches share one fold.
+    const session = (sessionID: Session.ID) => {
+      const existing = sessions.get(sessionID)
+      if (existing) {
+        // LRU touch: Map.set on an existing key does not reorder, so reinsert at the tail.
+        sessions.delete(sessionID)
+        sessions.set(sessionID, existing)
+        return existing
+      }
+      const created = folded(sessionID)
+      sessions.set(sessionID, created)
+      // Eviction is a bare delete: the KV breaker key belongs to the session lifecycle, not to
+      // this cache, and everything else re-folds from durable history on the next touch.
+      while (sessions.size > cap) {
+        const oldest = sessions.keys().next().value
+        if (oldest === undefined) break
+        sessions.delete(oldest)
+      }
+      return created
+    }
+
+    // Event-time mutations chain onto the in-flight fold so they apply after it settles. Sessions
+    // never touched by a hook are not created here: a fresh state is already the zeroed state.
+    const mutate = (sessionID: Session.ID, fn: (state: DoomLoopDetector.SessionState) => void) => {
+      const existing = sessions.get(sessionID)
+      if (existing)
+        sessions.set(
+          sessionID,
+          existing.then((entry) => {
+            fn(entry.state)
+            return entry
+          }),
+        )
+    }
+
+    yield* ctx.tool.hook("execute.before", (event) =>
+      Effect.gen(function* () {
+        // The outer Code Mode tool is built per snapshot and re-enters with real tool names; its
+        // own `execute` call carries no observable signature. Skipping by name also exempts an
+        // MCP/custom tool literally named `execute` — a false-negative, conservative direction.
+        if (event.tool === "execute") return
+        const current = yield* Effect.promise(() => session(event.sessionID))
+        const sigHash = DoomLoopDetector.signature(event.tool, event.input)
+        const verdict = DoomLoopDetector.beforeCall(current.state, {
+          tool: event.tool,
+          sigHash,
+          messageID: event.messageID,
+        })
+        if (verdict.kind === "pass") return
+        if (verdict.kind === "circuit") {
+          // A sticky circuit (a previous denial) stops without re-asking, until the user speaks.
+          if (verdict.sticky) {
+            yield* ctx.session.interrupt({ sessionID: event.sessionID }).pipe(Effect.ignore, Effect.forkIn(scope))
+            return yield* new Tool.Error({ message: verdict.message, metadata: DoomLoopDetector.blockedMetadata })
+          }
+          // The breaker goes through doom_loop like every other signal: allow resets B and lets
+          // the run continue; a denial makes the stop sticky and explains why it happened.
+          const resource = `${event.tool}:${sigHash}${DoomLoopDetector.resourceSuffix.b}`
+          const outcome = yield* Effect.exit(
+            ctx.permission.assert({
+              sessionID: event.sessionID,
+              agent: event.agent,
+              action: "doom_loop",
+              resources: [resource],
+              save: [resource],
+              source: { type: "tool", messageID: event.messageID, id: event.id },
+            }),
+          )
+          if (Exit.isSuccess(outcome)) {
+            current.state.bStreak = 0
+            return
+          }
+          const error = Option.getOrUndefined(Exit.findErrorOption(outcome))
+          // A rule-based denial makes the stop sticky; a CorrectedError carries model feedback and
+          // returns as a plain Tool.Error so the model can act on it (no sticky stop, no interrupt).
+          // Only a CorrectedError returns as plain feedback for the model (no sticky stop).
+          // The public API errors are Tool.Error, so identify a correction by its tag (both a bare
+          // error and the host-wrapped `error` field), rather than by class identity.
+          const tagOf = (value: unknown): string | undefined =>
+            typeof value === "object" && value !== null && "_tag" in value
+              ? (value as { _tag: string })._tag
+              : undefined
+          const corrected =
+            tagOf(error) === "Permission.CorrectedError" ||
+            (error instanceof Tool.Error && tagOf(error.error) === "Permission.CorrectedError")
+          if (!corrected) {
+            yield* ctx.storage.set(circuitKey(event.sessionID), true).pipe(Effect.ignore)
+            current.state.circuitBroken = true
+            yield* ctx.session.interrupt({ sessionID: event.sessionID }).pipe(Effect.ignore, Effect.forkIn(scope))
+          }
+          return yield* new Tool.Error({
+            message: `${verdict.message}\n\n${error?.message ?? "rejected"}`,
+            metadata: DoomLoopDetector.blockedMetadata,
+          })
+        }
+        const resource = `${event.tool}:${sigHash}${DoomLoopDetector.resourceSuffix[verdict.signal]}`
+        // host.ts maps BlockedError/CorrectedError to Tool.Error and keeps a plain rejection a
+        // defect; stacking our copy on the mapped message preserves the "why blocked + what next"
+        // guidance for both typed outcomes. Deliberately no inner `error`: toSessionError unwraps
+        // to the innermost error's message when one is attached, which would discard our copy.
+        // The blockedMetadata marker persists on the error part so the fold skips this call — it
+        // never executed, so the live path never accounted it.
+        return yield* ctx.permission
+          .assert({
+            sessionID: event.sessionID,
+            agent: event.agent,
+            action: "doom_loop",
+            resources: [resource],
+            save: [resource],
+            source: { type: "tool", messageID: event.messageID, id: event.id },
+          })
+          .pipe(
+            Effect.mapError(
+              (error) =>
+                new Tool.Error({
+                  message: `${verdict.message}\n\n${error.message}`,
+                  metadata: DoomLoopDetector.blockedMetadata,
+                }),
+            ),
+          )
+      }),
+    )
+
+    yield* ctx.tool.hook("execute.after", (event) =>
+      Effect.gen(function* () {
+        if (event.tool === "execute") return
+        const current = yield* Effect.promise(() => session(event.sessionID))
+        const sigHash = DoomLoopDetector.signature(event.tool, event.input)
+        if (event.status === "error") {
+          // Failure events feed signal C only — they never enter A/B, or a run of failures with
+          // distinct messages would count as identical empty outputs. The warning lands on the
+          // error message because a failed call has no result content.
+          // Deviation from ⑦, declared: error events carry no metadata, so a background shell's
+          // launch failure cannot be distinguished and is counted into C. Deliberately conservative
+          // direction (detect more; C still only ever asks, never hard-blocks silently).
+          const warning = DoomLoopDetector.recordFailed(current.state, {
+            tool: event.tool,
+            sigHash,
+            errorText: event.error.message,
+            validation: event.error.message.startsWith(DoomLoopDetector.VALIDATION_PREFIX),
+          })
+          if (warning !== undefined) event.error.message = `${event.error.message}\n\n${warning}`
+          return
+        }
+        // Unobserved layer (background shell — registered under the name "shell"; question):
+        // A/B/C abstain — the receipt text is fixed, so counting it would false-positive signal A
+        // immediately.
+        const unobserved =
+          event.tool === "question" ||
+          (event.tool === "shell" && event.result.metadata !== undefined && event.result.metadata.status === "running")
+        if (unobserved) {
+          DoomLoopDetector.recordUnobserved(current.state, sigHash)
+          return
+        }
+        // Hash and account before touching content so our own text never feeds back in.
+        const text = DoomLoopDetector.outputText(event.result.content, event.result.output)
+        const warning = DoomLoopDetector.recordCompleted(current.state, { tool: event.tool, sigHash, text })
+        if (warning === undefined) return
+        // Prepend rather than append: the runner's ToolOutput.truncate keeps the head of oversized
+        // outputs (tool-output.ts), so a tail warning would be cut exactly on the huge outputs of
+        // looping MCP-style tools.
+        const existing = event.result.content
+        event.result = {
+          ...event.result,
+          content: [
+            { type: "text" as const, text: warning },
+            ...(typeof existing === "string" ? [{ type: "text" as const, text: existing }] : (existing ?? [])),
+          ],
+        }
+      }),
+    )
+
+    yield* ctx.event.subscribe().pipe(
+      Stream.filter(
+        (event): event is Tracked =>
+          event.type === "session.deleted" ||
+          event.type === "session.inbox.enqueued" ||
+          event.type === "session.step.ended" ||
+          event.type === "session.compaction.ended" ||
+          event.type === "session.execution.succeeded" ||
+          event.type === "session.execution.failed" ||
+          event.type === "session.execution.interrupted",
+      ),
+      Stream.runForEach((event) =>
+        Effect.gen(function* () {
+          const sessionID = event.data.sessionID
+          if (event.type === "session.deleted") {
+            sessions.delete(sessionID)
+            yield* ctx.storage.remove(circuitKey(sessionID)).pipe(Effect.ignore)
+            return
+          }
+          if (event.type === "session.inbox.enqueued") {
+            // Only real user messages re-arm the breaker; our own synthetic injections must not.
+            // The persisted key clears even when this process never folded the session.
+            if (event.data.item.type !== "user") return
+            yield* ctx.storage.remove(circuitKey(sessionID)).pipe(Effect.ignore)
+            mutate(sessionID, DoomLoopDetector.userMessage)
+            return
+          }
+          if (event.type === "session.step.ended") {
+            if (event.data.files === undefined || event.data.files.length === 0) return
+            mutate(sessionID, DoomLoopDetector.filesChanged)
+            return
+          }
+          if (event.type === "session.compaction.ended") {
+            mutate(sessionID, DoomLoopDetector.compacted)
+            return
+          }
+          mutate(sessionID, DoomLoopDetector.tighten)
+        }),
+      ),
+      Effect.forkScoped({ startImmediately: true }),
+    )
+  }),
+  })
+}
+
+export const Plugin = makePlugin()