opencode-goal-mode 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v0.3.5
+
+- Verified the package against the **current** OpenCode plugin API
+  (`@opencode-ai/plugin@1.17.6`, matching OpenCode 1.17.6, now the dev pin): all
+  guard hooks (`chat.message`/`params`, `tool.execute.before`/`after`,
+  `experimental.chat.system.transform`/`text.complete`/`session.compacting`)
+  exist; the guard plugin loads with zero errors; and in a real OpenCode the
+  agent list shows `goal` as the only user-selectable agent with 26 subagents and
+  reviewer `edit`/`task: deny` applied. The enforcement core is unchanged and
+  fully intact.
+- Declared `@opentui/solid`, `solid-js`, `@opencode-ai/plugin` as **optional**
+  peer dependencies (the TUI runtime the sidebar uses).
+- Docs: stated the sidebar's verification status honestly — the experimental TUI
+  banner is verified to load and to render in a real headless OpenTUI test, but
+  its live in-session render depends on your OpenCode build's file-based
+  TUI-plugin support; it never errors and never affects the enforcement core.
+
+## v0.3.4
+
+Critical fixes found by testing against a real OpenCode (1.17.6) install — the
+prior releases did not actually work end-to-end.
+
+- **FIX: the guard plugin did not load.** OpenCode loads *every* export of a
+  plugin file as a plugin factory, so `goal-guard.js` exporting a test helper and
+  extra factories made OpenCode fail with `Plugin export is not a function` — the
+  entire enforcement layer was silently dead. The entry now exports **only** the
+  default plugin; the factory and test surface moved to
+  `plugins/goal-guard/guard.js` (nested, so OpenCode does not load it directly).
+- **FIX: 14 of 27 agents had invalid YAML frontmatter** (an invalid `\.` escape in
+  `external_directory` globs, and an unquoted `: ` in one description). OpenCode
+  silently dropped those agents to `mode: all` with **no permissions applied** —
+  they became user-selectable and the review gates' `edit: deny` / `task: deny`
+  were ignored. Fixed; verified in OpenCode that `goal` is the only `primary`
+  agent and all 26 specialists are `subagent` with their deny-permissions applied.
+- **Hardened the validator** so this can't regress: it now parses each agent's
+  frontmatter as real YAML (not regex), enforces reviewer `edit`/`task: deny` from
+  parsed values, and asserts the plugin entry exports only a default function.
+- `goal-sidebar.js` now `export default { id, tui }` only (the supported TUI
+  plugin shape), matching working OpenCode TUI plugins.
+- README: a "Quick start" (install → verify → use) at the top.
+
 ## v0.3.3
 
 - Release notes: the GitHub Release body is now generated from the matching

package/README.md

@@ -18,7 +18,34 @@ npm install -g opencode-goal-mode && opencode-goal-mode-install --global
 
 ![OpenCode Goal Mode sidebar banner](docs/sidebar-demo.svg)
 
-**[Install](#install) · [Why it's different](#why-its-different) · [Benchmarks](#benchmarks-honest-edition) · [TUI integration](#tui-integration) · [Configuration](#configuration) · [Releasing](#releasing) · [Architecture](ARCHITECTURE.md)**
+**[Quick start](#quick-start) · [Install](#install) · [Why it's different](#why-its-different) · [Benchmarks](#benchmarks-honest-edition) · [TUI integration](#tui-integration) · [Configuration](#configuration) · [Releasing](#releasing) · [Architecture](ARCHITECTURE.md)**
+
+## Quick start
+
+```bash
+# 1. Install (needs Node 20.11+ and OpenCode)
+npm install -g opencode-goal-mode
+opencode-goal-mode-install --global
+
+# 2. Restart OpenCode, then verify it loaded — you should see ONLY `goal (primary)`,
+#    with every specialist as a (subagent):
+opencode agent list | grep goal
+```
+
+3. In OpenCode, start a goal:
+
+   ```
+   /goal add rate limiting to the login endpoint and prove it works
+   ```
+
+   The `goal` agent writes a contract, delegates research/review to subagents, and
+   **cannot** answer `Goal Completed` until every required review gate passes — the
+   guard rewrites a premature claim to `Goal Not Completed`. Try a destructive
+   command mid-session (e.g. `rm -rf build`) and watch it get blocked. If your
+   OpenCode build supports TUI plugins, the active goal also appears in the sidebar
+   in yellow (experimental — see [TUI integration](#tui-integration)).
+
+That's it. Everything below is detail.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for the design and [research/](research/)
 for the platform reference, comparison, and threat model.
@@ -148,14 +175,21 @@ enforcement and writes its state to disk, and an experimental TUI plugin
 - **Sidebar goal banner (experimental).** The current goal renders in shining
   yellow in the sidebar (`sidebar_content` slot), with a `passing/total gates ·
   dirty/ready` status line, and updates as reviews land. When a task is running
-  but **no goal is set**, it shows a clean grey `No goal` and nothing else. It
-  requires a TUI-plugin-capable OpenCode (one exposing `api.slots.register`); on
-  any older runtime it silently no-ops, so it can never break your TUI. Set
+  but **no goal is set**, it shows a clean grey `No goal`. Set
   `sidebarBanner: false` (or `GOAL_GUARD_SIDEBAR_BANNER=0`) to disable,
   `sidebarColor` to recolour the goal, or `sidebarMutedColor` for the "No goal"
-  line. It is rendered-and-asserted headlessly by the
-  [visual test](tools/visual-test/README.md) (`npm run test:visual`); still worth
-  a glance in your own TUI.
+  line.
+
+  **Verification status, honestly:** the component is rendered and asserted
+  (text + exact colours) by a real headless OpenTUI renderer in the
+  [visual test](tools/visual-test/README.md) (`npm run test:visual`, 17/17), and
+  OpenCode discovers and boots it as a plugin without error. It needs a recent
+  OpenCode that mounts file-based TUI plugins into the `sidebar_content` slot and
+  provides the `@opentui/solid` runtime; on a build without that, it simply does
+  not appear (it never errors or breaks the TUI — the enforcement core is a
+  separate server plugin and is unaffected). The banner appears in a **session**
+  view, not the home screen. If it doesn't show, that's the TUI-plugin runtime,
+  not Goal Mode's enforcement.
 - **Toasts.** Review verdicts and completion-unlock events surface as toasts
   (`toastOnReview`), and blocked destructive commands / premature completions
   toast as before (`toastOnBlock`).

package/agents/goal-deep-researcher.md

@@ -20,7 +20,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: allow
   webfetch: allow

package/agents/goal-diff-reviewer.md

@@ -24,7 +24,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-doc-reviewer.md

@@ -14,7 +14,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-doc-writer.md

@@ -1,5 +1,5 @@
 ---
-description: Use proactively for generating, updating, and improving documentation: READMEs, API docs, manuals, runbooks, inline help, release notes, and ADRs.
+description: "Use proactively for generating, updating, and improving documentation: READMEs, API docs, manuals, runbooks, inline help, release notes, and ADRs."
 mode: subagent
 temperature: 0
 color: info

package/agents/goal-final-auditor.md

@@ -14,7 +14,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-ops-reviewer.md

@@ -14,7 +14,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-prompt-auditor.md

@@ -14,7 +14,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-reviewer.md

@@ -28,7 +28,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-security-reviewer.md

@@ -14,7 +14,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-test-reviewer.md

@@ -23,7 +23,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-ux-reviewer.md

@@ -14,7 +14,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-verifier.md

@@ -23,7 +23,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: ask
   webfetch: allow

package/agents/goal-web-researcher.md

@@ -20,7 +20,7 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
+    "~/.config/opencode/**": allow
   todowrite: deny
   question: allow
   webfetch: allow

package/agents/goal.md

@@ -26,8 +26,8 @@ permission:
   external_directory:
     "*": ask
     "/projects/**": allow
-    "~/\.config/opencode/**": allow
-    "~/\.local/share/opencode/tool-output/**": allow
+    "~/.config/opencode/**": allow
+    "~/.local/share/opencode/tool-output/**": allow
   todowrite: allow
   question: allow
   webfetch: allow

package/docs/benchmarks/latency.svg

@@ -4,10 +4,10 @@
 <text x="20" y="47" font-size="12" fill="#656d76">Microseconds to classify one command. Both are negligible for a tool-call guard.</text>
 <text x="218" y="87" font-size="12" text-anchor="end" fill="#1f2328">Legacy regex guard</text>
 <rect x="230" y="70" width="420" height="22" rx="3" fill="#eaeef2"/>
-<rect x="230" y="70" width="214.5" height="22" rx="3" fill="#9aa0a6"/>
-<text x="452.5" y="87" font-size="12" font-weight="600" fill="#1f2328">0.79 µs</text>
+<rect x="230" y="70" width="217.1" height="22" rx="3" fill="#9aa0a6"/>
+<text x="455.1" y="87" font-size="12" font-weight="600" fill="#1f2328">0.75 µs</text>
 <text x="218" y="125" font-size="12" text-anchor="end" fill="#1f2328">Goal Mode analyzer</text>
 <rect x="230" y="108" width="420" height="22" rx="3" fill="#eaeef2"/>
 <rect x="230" y="108" width="300.0" height="22" rx="3" fill="#2da44e"/>
-<text x="538.0" y="125" font-size="12" font-weight="600" fill="#1f2328">1.11 µs</text>
+<text x="538.0" y="125" font-size="12" font-weight="600" fill="#1f2328">1.03 µs</text>
 </svg>

package/docs/benchmarks/results.json

@@ -75,8 +75,8 @@
           "safeFalsePos": 5
         }
       },
-      "opsPerSec": 1260371,
-      "usPerCommand": 0.79
+      "opsPerSec": 1341168,
+      "usPerCommand": 0.75
     },
     "current": {
       "detectionRate": 100,
@@ -111,8 +111,8 @@
           "safeFalsePos": 0
         }
       },
-      "opsPerSec": 901050,
-      "usPerCommand": 1.11
+      "opsPerSec": 970526,
+      "usPerCommand": 1.03
     }
   },
   "completionFixtures": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "engines": {
@@ -82,7 +82,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.15.13",
-    "fast-check": "^4.8.0"
+    "@opencode-ai/plugin": "1.17.6",
+    "fast-check": "^4.8.0",
+    "yaml": "^2.6.1"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.15.0",
+    "@opentui/solid": "*",
+    "solid-js": "*"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": { "optional": true },
+    "@opentui/solid": { "optional": true },
+    "solid-js": { "optional": true }
   }
 }

package/plugins/goal-guard/guard.js

@@ -0,0 +1,329 @@
+/**
+ * Goal Guard — OpenCode plugin entry point.
+ *
+ * This thin module wires the focused modules under `goal-guard/` into the
+ * OpenCode plugin hooks. All real logic (shell analysis, gating, verdicts,
+ * persistence, completion enforcement) lives in those modules and is unit
+ * tested in isolation; the entry is just orchestration.
+ *
+ * Design notes (verified against @opencode-ai/plugin@1.15.13 source):
+ *  - State is created PER PLUGIN INSTANCE (no module globals), so concurrent
+ *    projects cannot cross-contaminate, and is persisted to the XDG state dir
+ *    so it survives OpenCode restarts.
+ *  - Destructive bash is blocked by THROWING in `tool.execute.before` (the
+ *    `permission.ask` hook is dormant in this version and cannot be relied on).
+ *  - `chat.message` captures the goal text that drives contextual review gates;
+ *    `file.edited` events catch edits made inside subagent child sessions.
+ *  - `experimental.chat.system.transform` injects live gate state into the
+ *    prompt; custom `goal_*` tools give the model structured control.
+ */
+
+import { resolveConfig } from "./config.js";
+import { createStore, createState } from "./state.js";
+import { createPersistence } from "./persistence.js";
+import { createLogger } from "./logger.js";
+import { analyzeCommand, looksLikeDestructiveBash, looksLikeMutatingBash, isVerification } from "./shell.js";
+import { isPrimaryAgent, isReviewAgent, CYCLE_CLOSING_AGENT, prettyAgentName } from "./agents.js";
+import { textOf, parseVerdict, recordVerdict } from "./verdicts.js";
+import { completionAllowed, missingGates, refreshStickyGates } from "./gates.js";
+import { evaluateCompletionClaim } from "./completion.js";
+import { summarizeState } from "./summary.js";
+import { buildSystemInjection } from "./system.js";
+import { markEdit, markVerification, markFileChanged, maybeClearDirtyOnFinalPass } from "./events.js";
+
+function normalizedSubagent(input) {
+  if (!input) return undefined;
+  const agent = String(input.agent || input.args?.subagent_type || "").trim();
+  return agent || undefined;
+}
+
+function commandOf(input, output) {
+  return String(output?.args?.command ?? input?.args?.command ?? "");
+}
+
+function partsText(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts
+    .filter((p) => p && (p.type === "text" || typeof p.text === "string"))
+    .map((p) => p.text || "")
+    .join(" ")
+    .trim();
+}
+
+/**
+ * Build a guard instance. Exposed for tests; the default export wraps it.
+ *
+ * @param {object} input  PluginInput ({ client, directory, worktree, ... }).
+ * @param {object} options  Plugin options (2nd factory arg).
+ * @param {object} overrides  Test seams: { config, store, persistence, env, clock, setTimer, clearTimer }.
+ */
+export function createGuard(input = {}, options = {}, overrides = {}) {
+  const config = overrides.config || resolveConfig(options, overrides.env);
+  const store =
+    overrides.store ||
+    createStore({ maxSessions: config.maxSessions, ttlMs: config.sessionTtlMs, clock: overrides.clock });
+  const logger = createLogger(input.client);
+  const persistence =
+    overrides.persistence ||
+    createPersistence({
+      worktree: input.worktree || input.directory,
+      enabled: config.persist,
+      env: overrides.env,
+      setTimer: overrides.setTimer,
+      clearTimer: overrides.clearTimer,
+    });
+
+  // Rehydrate any prior state for this project.
+  try {
+    const data = persistence.load();
+    if (data) store.restore(data);
+  } catch {
+    /* ignore corrupt state */
+  }
+
+  const persist = () => persistence.save(() => store.snapshot());
+
+  const hooks = {
+    async "chat.message"(inp, out) {
+      try {
+        if (!inp?.sessionID) return;
+        const state = store.stateFor(inp.sessionID);
+        if (isPrimaryAgent(inp.agent)) state.active = true;
+        const text = partsText(out?.parts);
+        if (text && state.active) {
+          // Accumulate goal text (bounded) so contextual gates can be derived.
+          state.goalText = `${state.goalText} ${text}`.trim().slice(-8000);
+          // Resolve contextual gates eagerly into the sticky set so truncating
+          // the rolling buffer later cannot drop an already-required gate.
+          refreshStickyGates(state);
+          persist();
+        }
+      } catch {
+        /* never break a turn */
+      }
+    },
+
+    async "chat.params"(inp) {
+      try {
+        if (!inp?.sessionID || typeof inp.sessionID !== "string") return;
+        const normalized = inp.sessionID.trim();
+        if (!normalized) return;
+        const state = store.stateFor(normalized);
+        state.currentAgent = inp.agent;
+        if (isPrimaryAgent(inp.agent)) state.active = true;
+      } catch {
+        /* ignore */
+      }
+    },
+
+    async "experimental.chat.system.transform"(inp, out) {
+      try {
+        if (!config.injectSystemState) return;
+        if (!inp?.sessionID || !out || !Array.isArray(out.system)) return;
+        const state = store.stateFor(inp.sessionID);
+        const block = buildSystemInjection(state, config);
+        if (block) out.system.push(block);
+      } catch {
+        /* ignore */
+      }
+    },
+
+    async "tool.execute.before"(inp, out) {
+      const state = store.stateFor(inp?.sessionID);
+      if (inp?.tool === "bash") {
+        const command = commandOf(inp, out);
+        const analysis = analyzeCommand(command);
+        const blockDestructive = config.blockDestructive && analysis.destructive;
+        const blockNetwork = config.blockNetworkExec && analysis.networkExec;
+        if (blockDestructive || blockNetwork) {
+          state.active = true;
+          state.dirtyReasons.push(`blocked risky bash: ${analysis.reasons.join("; ") || "destructive"}`);
+          if (config.toastOnBlock) logger.toast("Goal Guard blocked a destructive command", "error");
+          persist();
+          throw new Error(
+            `Goal Guard blocked a destructive or high-risk bash command (${analysis.reasons.join("; ") || "destructive"}). ` +
+              "Use a safer, reversible command or ask the user to confirm.",
+          );
+        }
+      }
+    },
+
+    async "tool.execute.after"(inp, out) {
+      try {
+        const state = store.stateFor(inp?.sessionID);
+        const tool = inp?.tool;
+        const isReviewing = isReviewAgent(state.currentAgent);
+
+        // Edits dirty the session (a read-only reviewer never edits, but guard
+        // symmetrically with the bash path so review-time writes don't dirty it).
+        if ((tool === "write" || tool === "edit" || tool === "apply_patch") && !isReviewing) {
+          markEdit(store, state, `${tool} at ${store.nowIso()}`);
+        }
+
+        if (tool === "bash") {
+          const command = String(inp?.args?.command || "");
+          const analysis = analyzeCommand(command);
+          if (analysis.verification && !isReviewing) {
+            markVerification(store, state);
+          }
+          if ((analysis.destructive || analysis.mutating) && !isReviewing) {
+            markEdit(store, state, `bash mutation: ${analysis.reasons.join("; ") || "mutation"}`);
+          }
+        }
+
+        // Verdict capture. The PRIMARY mechanism is the task path: when the goal
+        // agent spawns a reviewer via the task tool, the parent session sees the
+        // subagent's result here and the verdict is recorded against the parent
+        // goal — correct cross-session attribution. The agent path is a fallback
+        // for a reviewer's verdict surfacing in its own session's tool output; it
+        // records against that same session (never another), so it can neither
+        // mis-credit a sibling session nor break the parent goal, which the task
+        // path already covers. Split by tool type so the two never double-count.
+        const wasAllowed = completionAllowed(state, config);
+        let recordedAgent = null;
+        let recordedVerdict = null;
+        if (tool === "task") {
+          const sub = normalizedSubagent(inp);
+          if (isReviewAgent(sub)) {
+            const text = textOf(out);
+            const verdict = parseVerdict(text);
+            if (verdict) {
+              recordVerdict(store, state, sub, verdict, text);
+              recordedAgent = sub;
+              recordedVerdict = verdict;
+            }
+          }
+        } else if (isReviewAgent(state.currentAgent)) {
+          const text = textOf(out);
+          const verdict = parseVerdict(text);
+          if (verdict) {
+            recordVerdict(store, state, state.currentAgent, verdict, text);
+            recordedAgent = state.currentAgent;
+            recordedVerdict = verdict;
+          }
+        }
+
+        if (recordedAgent === CYCLE_CLOSING_AGENT) {
+          maybeClearDirtyOnFinalPass(state, config);
+        }
+
+        // Surface review progress in the TUI: a toast per recorded verdict, and a
+        // single celebratory toast the moment the last required gate clears.
+        if (recordedAgent && recordedVerdict && config.toastOnReview) {
+          logger.toast(`${prettyAgentName(recordedAgent)} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
+          if (!wasAllowed && completionAllowed(state, config)) {
+            logger.toast("All required gates passed — completion unlocked", "success");
+          }
+        }
+        persist();
+      } catch {
+        /* never break a turn */
+      }
+    },
+
+    async "experimental.text.complete"(inp, out) {
+      try {
+        if (!config.enforceCompletion) return;
+        if (!inp?.sessionID || !out || typeof out.text !== "string") return;
+        const state = store.stateFor(inp.sessionID);
+        const decision = evaluateCompletionClaim(state, config, out.text);
+        if (decision.blocked) {
+          state.completedBlocked += 1;
+          state.lastCompletionRejectAt = store.nowIso();
+          state.completionRejections.push({ at: state.lastCompletionRejectAt, reason: decision.reason });
+          out.text = decision.replacement;
+          if (config.toastOnBlock) logger.toast(`Goal Guard blocked premature completion: ${decision.reason}`, "warning");
+          persist();
+        }
+      } catch {
+        /* ignore */
+      }
+    },
+
+    async "experimental.session.compacting"(inp, out) {
+      try {
+        if (!inp?.sessionID || !out || !Array.isArray(out.context)) return;
+        const state = store.stateFor(inp.sessionID);
+        out.context.push(
+          `Goal Guard state: ${summarizeState(state, config)}. Preserve Goal Contract, Verification Ledger, ` +
+            `Review Ledger, Reviewer Memory, review cycle count, dirty state, and open findings across compaction.`,
+        );
+      } catch {
+        /* ignore */
+      }
+    },
+
+    async event({ event } = {}) {
+      try {
+        if (!event) return;
+        if (event.type === "file.edited") {
+          const file = event.properties?.file || event.properties?.path || event.properties?.filename;
+          if (!file) return;
+          // The event is project-scoped and carries no sessionID, so attribute
+          // it to every active goal session in this project (a subagent edit in
+          // a child session must still dirty the goal it serves).
+          let touched = false;
+          for (const st of store.sessions.values()) {
+            if (st.active) {
+              markFileChanged(store, st, file);
+              refreshStickyGates(st);
+              touched = true;
+            }
+          }
+          if (touched) persist();
+          return;
+        }
+        if (event.type === "session.idle" && event.properties?.sessionID) {
+          const state = store.stateFor(event.properties.sessionID);
+          persistence.flush(() => store.snapshot());
+          if (state.dirty) {
+            await logger.warn("Goal session idle while dirty or review-stale", { state: summarizeState(state, config) });
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    },
+
+    async dispose() {
+      try {
+        persistence.flush(() => store.snapshot());
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+
+  return { hooks, store, config, persistence, logger, persist };
+}
+
+/** OpenCode plugin factory (default export). */
+export async function GoalGuardPlugin(input, options) {
+  const guard = createGuard(input || {}, options || {});
+  // Register custom goal_* tools, isolated so a resolution failure of
+  // @opencode-ai/plugin cannot prevent the core guard hooks from loading.
+  try {
+    const { createGoalTools } = await import("./tools.js");
+    guard.hooks.tool = createGoalTools({ store: guard.store, config: guard.config, persist: guard.persist });
+  } catch {
+    /* tools are optional */
+  }
+  return guard.hooks;
+}
+
+export default GoalGuardPlugin;
+
+/** Stable test surface. */
+export const __test = {
+  createGuard,
+  createStore,
+  createState,
+  resolveConfig,
+  analyzeCommand,
+  looksLikeDestructiveBash,
+  looksLikeMutatingBash,
+  isVerification,
+  summarizeState,
+  completionAllowed,
+  missingGates,
+};

package/plugins/goal-guard.js

@@ -1,329 +1,15 @@
 /**
  * Goal Guard — OpenCode plugin entry point.
  *
- * This thin module wires the focused modules under `goal-guard/` into the
- * OpenCode plugin hooks. All real logic (shell analysis, gating, verdicts,
- * persistence, completion enforcement) lives in those modules and is unit
- * tested in isolation; the entry is just orchestration.
- *
- * Design notes (verified against @opencode-ai/plugin@1.15.13 source):
- *  - State is created PER PLUGIN INSTANCE (no module globals), so concurrent
- *    projects cannot cross-contaminate, and is persisted to the XDG state dir
- *    so it survives OpenCode restarts.
- *  - Destructive bash is blocked by THROWING in `tool.execute.before` (the
- *    `permission.ask` hook is dormant in this version and cannot be relied on).
- *  - `chat.message` captures the goal text that drives contextual review gates;
- *    `file.edited` events catch edits made inside subagent child sessions.
- *  - `experimental.chat.system.transform` injects live gate state into the
- *    prompt; custom `goal_*` tools give the model structured control.
- */
-
-import { resolveConfig } from "./goal-guard/config.js";
-import { createStore, createState } from "./goal-guard/state.js";
-import { createPersistence } from "./goal-guard/persistence.js";
-import { createLogger } from "./goal-guard/logger.js";
-import { analyzeCommand, looksLikeDestructiveBash, looksLikeMutatingBash, isVerification } from "./goal-guard/shell.js";
-import { isPrimaryAgent, isReviewAgent, CYCLE_CLOSING_AGENT, prettyAgentName } from "./goal-guard/agents.js";
-import { textOf, parseVerdict, recordVerdict } from "./goal-guard/verdicts.js";
-import { completionAllowed, missingGates, refreshStickyGates } from "./goal-guard/gates.js";
-import { evaluateCompletionClaim } from "./goal-guard/completion.js";
-import { summarizeState } from "./goal-guard/summary.js";
-import { buildSystemInjection } from "./goal-guard/system.js";
-import { markEdit, markVerification, markFileChanged, maybeClearDirtyOnFinalPass } from "./goal-guard/events.js";
-
-function normalizedSubagent(input) {
-  if (!input) return undefined;
-  const agent = String(input.agent || input.args?.subagent_type || "").trim();
-  return agent || undefined;
-}
-
-function commandOf(input, output) {
-  return String(output?.args?.command ?? input?.args?.command ?? "");
-}
-
-function partsText(parts) {
-  if (!Array.isArray(parts)) return "";
-  return parts
-    .filter((p) => p && (p.type === "text" || typeof p.text === "string"))
-    .map((p) => p.text || "")
-    .join(" ")
-    .trim();
-}
-
-/**
- * Build a guard instance. Exposed for tests; the default export wraps it.
- *
- * @param {object} input  PluginInput ({ client, directory, worktree, ... }).
- * @param {object} options  Plugin options (2nd factory arg).
- * @param {object} overrides  Test seams: { config, store, persistence, env, clock, setTimer, clearTimer }.
+ * OpenCode loads a plugin file by importing it and treating EVERY export as a
+ * plugin factory (see @opencode-ai/plugin's example: `export const X = async …`).
+ * A non-function export (or a second factory) makes OpenCode fail with
+ * "Plugin export is not a function" / double-register. So this entry exports
+ * EXACTLY ONE thing — the default plugin factory. All implementation and the
+ * test surface live in ./goal-guard/guard.js, which is nested one level deeper
+ * and therefore not matched by OpenCode's `{plugin,plugins}/*.{ts,js}` glob.
  */
-export function createGuard(input = {}, options = {}, overrides = {}) {
-  const config = overrides.config || resolveConfig(options, overrides.env);
-  const store =
-    overrides.store ||
-    createStore({ maxSessions: config.maxSessions, ttlMs: config.sessionTtlMs, clock: overrides.clock });
-  const logger = createLogger(input.client);
-  const persistence =
-    overrides.persistence ||
-    createPersistence({
-      worktree: input.worktree || input.directory,
-      enabled: config.persist,
-      env: overrides.env,
-      setTimer: overrides.setTimer,
-      clearTimer: overrides.clearTimer,
-    });
-
-  // Rehydrate any prior state for this project.
-  try {
-    const data = persistence.load();
-    if (data) store.restore(data);
-  } catch {
-    /* ignore corrupt state */
-  }
-
-  const persist = () => persistence.save(() => store.snapshot());
-
-  const hooks = {
-    async "chat.message"(inp, out) {
-      try {
-        if (!inp?.sessionID) return;
-        const state = store.stateFor(inp.sessionID);
-        if (isPrimaryAgent(inp.agent)) state.active = true;
-        const text = partsText(out?.parts);
-        if (text && state.active) {
-          // Accumulate goal text (bounded) so contextual gates can be derived.
-          state.goalText = `${state.goalText} ${text}`.trim().slice(-8000);
-          // Resolve contextual gates eagerly into the sticky set so truncating
-          // the rolling buffer later cannot drop an already-required gate.
-          refreshStickyGates(state);
-          persist();
-        }
-      } catch {
-        /* never break a turn */
-      }
-    },
-
-    async "chat.params"(inp) {
-      try {
-        if (!inp?.sessionID || typeof inp.sessionID !== "string") return;
-        const normalized = inp.sessionID.trim();
-        if (!normalized) return;
-        const state = store.stateFor(normalized);
-        state.currentAgent = inp.agent;
-        if (isPrimaryAgent(inp.agent)) state.active = true;
-      } catch {
-        /* ignore */
-      }
-    },
-
-    async "experimental.chat.system.transform"(inp, out) {
-      try {
-        if (!config.injectSystemState) return;
-        if (!inp?.sessionID || !out || !Array.isArray(out.system)) return;
-        const state = store.stateFor(inp.sessionID);
-        const block = buildSystemInjection(state, config);
-        if (block) out.system.push(block);
-      } catch {
-        /* ignore */
-      }
-    },
 
-    async "tool.execute.before"(inp, out) {
-      const state = store.stateFor(inp?.sessionID);
-      if (inp?.tool === "bash") {
-        const command = commandOf(inp, out);
-        const analysis = analyzeCommand(command);
-        const blockDestructive = config.blockDestructive && analysis.destructive;
-        const blockNetwork = config.blockNetworkExec && analysis.networkExec;
-        if (blockDestructive || blockNetwork) {
-          state.active = true;
-          state.dirtyReasons.push(`blocked risky bash: ${analysis.reasons.join("; ") || "destructive"}`);
-          if (config.toastOnBlock) logger.toast("Goal Guard blocked a destructive command", "error");
-          persist();
-          throw new Error(
-            `Goal Guard blocked a destructive or high-risk bash command (${analysis.reasons.join("; ") || "destructive"}). ` +
-              "Use a safer, reversible command or ask the user to confirm.",
-          );
-        }
-      }
-    },
-
-    async "tool.execute.after"(inp, out) {
-      try {
-        const state = store.stateFor(inp?.sessionID);
-        const tool = inp?.tool;
-        const isReviewing = isReviewAgent(state.currentAgent);
-
-        // Edits dirty the session (a read-only reviewer never edits, but guard
-        // symmetrically with the bash path so review-time writes don't dirty it).
-        if ((tool === "write" || tool === "edit" || tool === "apply_patch") && !isReviewing) {
-          markEdit(store, state, `${tool} at ${store.nowIso()}`);
-        }
-
-        if (tool === "bash") {
-          const command = String(inp?.args?.command || "");
-          const analysis = analyzeCommand(command);
-          if (analysis.verification && !isReviewing) {
-            markVerification(store, state);
-          }
-          if ((analysis.destructive || analysis.mutating) && !isReviewing) {
-            markEdit(store, state, `bash mutation: ${analysis.reasons.join("; ") || "mutation"}`);
-          }
-        }
-
-        // Verdict capture. The PRIMARY mechanism is the task path: when the goal
-        // agent spawns a reviewer via the task tool, the parent session sees the
-        // subagent's result here and the verdict is recorded against the parent
-        // goal — correct cross-session attribution. The agent path is a fallback
-        // for a reviewer's verdict surfacing in its own session's tool output; it
-        // records against that same session (never another), so it can neither
-        // mis-credit a sibling session nor break the parent goal, which the task
-        // path already covers. Split by tool type so the two never double-count.
-        const wasAllowed = completionAllowed(state, config);
-        let recordedAgent = null;
-        let recordedVerdict = null;
-        if (tool === "task") {
-          const sub = normalizedSubagent(inp);
-          if (isReviewAgent(sub)) {
-            const text = textOf(out);
-            const verdict = parseVerdict(text);
-            if (verdict) {
-              recordVerdict(store, state, sub, verdict, text);
-              recordedAgent = sub;
-              recordedVerdict = verdict;
-            }
-          }
-        } else if (isReviewAgent(state.currentAgent)) {
-          const text = textOf(out);
-          const verdict = parseVerdict(text);
-          if (verdict) {
-            recordVerdict(store, state, state.currentAgent, verdict, text);
-            recordedAgent = state.currentAgent;
-            recordedVerdict = verdict;
-          }
-        }
-
-        if (recordedAgent === CYCLE_CLOSING_AGENT) {
-          maybeClearDirtyOnFinalPass(state, config);
-        }
-
-        // Surface review progress in the TUI: a toast per recorded verdict, and a
-        // single celebratory toast the moment the last required gate clears.
-        if (recordedAgent && recordedVerdict && config.toastOnReview) {
-          logger.toast(`${prettyAgentName(recordedAgent)} → ${recordedVerdict}`, recordedVerdict === "PASS" ? "success" : "warning");
-          if (!wasAllowed && completionAllowed(state, config)) {
-            logger.toast("All required gates passed — completion unlocked", "success");
-          }
-        }
-        persist();
-      } catch {
-        /* never break a turn */
-      }
-    },
-
-    async "experimental.text.complete"(inp, out) {
-      try {
-        if (!config.enforceCompletion) return;
-        if (!inp?.sessionID || !out || typeof out.text !== "string") return;
-        const state = store.stateFor(inp.sessionID);
-        const decision = evaluateCompletionClaim(state, config, out.text);
-        if (decision.blocked) {
-          state.completedBlocked += 1;
-          state.lastCompletionRejectAt = store.nowIso();
-          state.completionRejections.push({ at: state.lastCompletionRejectAt, reason: decision.reason });
-          out.text = decision.replacement;
-          if (config.toastOnBlock) logger.toast(`Goal Guard blocked premature completion: ${decision.reason}`, "warning");
-          persist();
-        }
-      } catch {
-        /* ignore */
-      }
-    },
-
-    async "experimental.session.compacting"(inp, out) {
-      try {
-        if (!inp?.sessionID || !out || !Array.isArray(out.context)) return;
-        const state = store.stateFor(inp.sessionID);
-        out.context.push(
-          `Goal Guard state: ${summarizeState(state, config)}. Preserve Goal Contract, Verification Ledger, ` +
-            `Review Ledger, Reviewer Memory, review cycle count, dirty state, and open findings across compaction.`,
-        );
-      } catch {
-        /* ignore */
-      }
-    },
-
-    async event({ event } = {}) {
-      try {
-        if (!event) return;
-        if (event.type === "file.edited") {
-          const file = event.properties?.file || event.properties?.path || event.properties?.filename;
-          if (!file) return;
-          // The event is project-scoped and carries no sessionID, so attribute
-          // it to every active goal session in this project (a subagent edit in
-          // a child session must still dirty the goal it serves).
-          let touched = false;
-          for (const st of store.sessions.values()) {
-            if (st.active) {
-              markFileChanged(store, st, file);
-              refreshStickyGates(st);
-              touched = true;
-            }
-          }
-          if (touched) persist();
-          return;
-        }
-        if (event.type === "session.idle" && event.properties?.sessionID) {
-          const state = store.stateFor(event.properties.sessionID);
-          persistence.flush(() => store.snapshot());
-          if (state.dirty) {
-            await logger.warn("Goal session idle while dirty or review-stale", { state: summarizeState(state, config) });
-          }
-        }
-      } catch {
-        /* ignore */
-      }
-    },
-
-    async dispose() {
-      try {
-        persistence.flush(() => store.snapshot());
-      } catch {
-        /* ignore */
-      }
-    },
-  };
-
-  return { hooks, store, config, persistence, logger, persist };
-}
-
-/** OpenCode plugin factory (default export). */
-export async function GoalGuardPlugin(input, options) {
-  const guard = createGuard(input || {}, options || {});
-  // Register custom goal_* tools, isolated so a resolution failure of
-  // @opencode-ai/plugin cannot prevent the core guard hooks from loading.
-  try {
-    const { createGoalTools } = await import("./goal-guard/tools.js");
-    guard.hooks.tool = createGoalTools({ store: guard.store, config: guard.config, persist: guard.persist });
-  } catch {
-    /* tools are optional */
-  }
-  return guard.hooks;
-}
+import { GoalGuardPlugin } from "./goal-guard/guard.js";
 
 export default GoalGuardPlugin;
-
-/** Stable test surface. */
-export const __test = {
-  createGuard,
-  createStore,
-  createState,
-  resolveConfig,
-  analyzeCommand,
-  looksLikeDestructiveBash,
-  looksLikeMutatingBash,
-  isVerification,
-  summarizeState,
-  completionAllowed,
-  missingGates,
-};

package/plugins/goal-sidebar.js

@@ -95,10 +95,10 @@ function readModel(worktree, sessionId) {
   }
 }
 
-export const id = "goal-mode-sidebar";
+const id = "goal-mode-sidebar";
 
 /** @type {import("@opencode-ai/plugin/tui").TuiPlugin} */
-export const tui = async (api, options) => {
+const tui = async (api, options) => {
   try {
     const { enabled, color, muted } = resolveOptions(options, typeof process !== "undefined" ? process.env : {});
     if (!enabled) return;