opencode-goal-mode 0.3.10 → 0.4.0

package/ARCHITECTURE.md

@@ -66,7 +66,7 @@ Verified against `@opencode-ai/plugin@1.15.13` source.
 | `chat.message` | Capture the user's goal text (drives contextual review gates). |
 | `chat.params` | Track the current agent; activate goal sessions. |
 | `experimental.chat.system.transform` | Inject the live Goal Guard state block. |
-| `tool.execute.before` | Block destructive / remote-exec bash by throwing. |
+| `tool.execute.before` | Block destructive / remote-exec bash, and block non-Goal agents from invoking `goal-*` subagents, by throwing. |
 | `tool.execute.after` | Record edits, verification, mutations, and review verdicts. |
 | `experimental.text.complete` | Rewrite premature `Goal Completed` claims. |
 | `experimental.session.compacting` | Preserve guard state across compaction. |
@@ -166,18 +166,23 @@ hooks still load.
 ## TUI companion (experimental)
 
 `plugins/goal-sidebar.tsx` is a TUI plugin module — default-exporting `{ id, tui }`
-— distinct from the server plugin. It waits until the persisted state contains an
-active Goal session, then registers a `sidebar_content` slot via
-`api.slots.register({ slots: { sidebar_content } })` and renders the short goal
-label, gate/status line, and structured Goal todos derived from acceptance
-criteria, evidence freshness, dirty state, and missing gates. It starts with a
-brief rainbow foreground effect, then returns to the configured running colour
-(`#FFD700` by default). When there is no active Goal session it does not register
-the slot, so Build and other modes keep OpenCode's native todo section in place.
+— distinct from the server plugin. It registers a `sidebar_content` slot via
+`api.slots.register({ slots: { sidebar_content } })` (matching the canonical
+OpenCode TUI-plugin pattern), and the slot renders content **only** for the active
+session, and **only** when that exact session is an active Goal session. It is
+keyed strictly by `props.session_id`: there is no most-recently-touched global
+fallback, so a Build (or any non-Goal) session in the same worktree never inherits
+another session's goal — it renders nothing and keeps OpenCode's native todo
+section. When it does render, it shows the short goal label, gate/status line, and
+structured Goal todos derived from acceptance criteria, evidence freshness, dirty
+state, and missing gates, starting with a brief per-line rainbow foreground effect
+and then settling to the configured running colour (`#FFD700` by default; red when
+done).
 
 It is *paired* with the server plugin only through the persisted state file:
 `sidebar-data.js` recomputes the same `stateBaseDir`/`projectKey` path the guard
-writes to and projects the active session via `summary.sidebarView`. That keeps
+writes to and projects the requested session via `summary.sidebarView` (the same
+per-session rule, so the Node tests and the real component agree). That keeps
 the pure projection logic Node-testable (`tests/sidebar.test.mjs`) even though the
 JSX renderer itself can only run inside OpenCode's (Bun) TUI runtime. Everything
 in the `tui` entry is wrapped so a missing slot API, missing JSX runtime, or read

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## v0.4.0
+
+### Goal-only subagents
+
+- The `goal-*` specialist subagents are now mechanically locked to Goal Mode.
+  OpenCode resolves subagents globally, so a Build, Plan, or custom agent could
+  previously invoke a Goal reviewer directly. The guard now blocks any `task` call
+  targeting a `goal-*` subagent unless it comes from an active Goal session, and a
+  poach attempt never turns the calling session into a Goal. General-purpose
+  subagents (`explore`/`general`/`scout`) are unaffected. New `restrictSubagents` /
+  `GOAL_GUARD_RESTRICT_SUBAGENTS` option (default on) toggles it.
+
+### Per-session sidebar isolation (not global)
+
+- The TUI Goal todo section is now strictly per-session. Both the live component
+  (`goal-sidebar.tsx`) and the Node-testable projection (`sidebar-data.js`) resolve
+  state by the exact `props.session_id` and only when that session is an active Goal
+  session — the "most-recently-touched active session" global fallback is gone in
+  both. A Build (or any non-Goal) session in the same worktree can no longer inherit
+  a sibling session's goal.
+- The slot now always registers and decides per-session inside the render (matching
+  the canonical OpenCode TUI-plugin pattern) instead of conditionally registering.
+- Added node + headless-visual coverage proving two active goals in one worktree
+  each render only their own goal.
+
+### Goal-mode-only tools
+
+- Every `goal_*` tool is Goal-mode-only: non-Goal/Build sessions get a clear refusal
+  instead of any Goal status, evidence map, memory, contract, evidence, or reset.
+
+### Documentation & visuals (accuracy pass)
+
+- Corrected the sidebar wording from "replaces the native todo area" to "adds a
+  Goal-owned todo section" (the slot contributes content; it does not replace native
+  todos), and removed the stale "waits to register the slot" description.
+- Regenerated the README hero image (`docs/sidebar-demo.svg`) to match what actually
+  renders: a bold `Goal todos` label (no orb), the first-display per-line rainbow,
+  the running/done colour states, and the native-todo-stays behavior. The old image
+  showed a removed `◆ GOAL` orb and a removed grey "No goal" state.
+- Made the benchmark "remaining misses" description accurate (all are plain `rm`
+  without `-r`/`-f`, intentionally permitted) and documented Goal-only subagents and
+  `restrictSubagents` in the README config table and ARCHITECTURE hook table.
+
+## v0.3.11
+
+- Fixed Goal sidebar/status isolation so an explicit Build or other non-Goal
+  session never falls back to another active Goal session in the same worktree.
+- Blocked mutating `goal_*` tools from activating Goal Guard state in non-Goal
+  sessions; read-only tools remain strictly scoped to the current session.
+- Added regression coverage for mixed Goal/Build persisted snapshots, session-scoped
+  status/evidence/memory reads, and Build-mode tool calls.
+
 ## v0.3.10
 
 - Clarified the recommended install command to use a persistent global npm install

package/README.md

@@ -140,10 +140,13 @@ Reproduce with `npm run bench` or `node benchmarks/external.mjs`.
 
 Honest caveats, because the point of this rewrite was to stop overclaiming:
 
-- The ~7 remaining "misses" are almost all un-flagged single-target `rm <file>`,
-  which the guard **intentionally permits** (plain `rm` is common and the guard
-  blocks `rm -r`/`rm -f`, `$(rm …)`, `bash -c`, interpreters, etc.). Under a
-  strict every-`rm`-is-destructive labeling those count against it.
+- The 7 remaining "misses" are all plain `rm` invocations without `-r`/`-f`
+  (single- or multi-target, a few with `-i`/`-v`/`-d`), which the guard
+  **intentionally permits**: bare `rm` is extremely common, so the guard marks it
+  dirty but lets the host's own `rm *` permission decide, while still blocking the
+  irreversible forms (`rm -r`/`rm -f`, wildcard/root, `$(rm …)`, `bash -c`,
+  `/bin/rm`, interpreters, etc.). Under a strict every-`rm`-is-destructive
+  labeling those count against it.
 - The single counted false positive (`git filter-repo …`) actually *is* a
   history-rewriting command, so the real-world false-positive rate is effectively
   zero. `node benchmarks/external.mjs --json` lists every miss and false positive
@@ -182,7 +185,8 @@ second) — negligible for a per-tool-call guard:
   discovery, verification planning, and reviews to subagents. **`goal` is the only
   user-selectable agent** — every specialist (security, diff, verifier, …) is a
   `mode: subagent` that the Goal agent invokes via the task tool; the user never
-  picks one directly. They surface with friendly names (e.g. "Security Reviewer",
+  picks one directly, and the guard blocks any other agent from invoking them (see
+  **Goal-only subagents** below). They surface with friendly names (e.g. "Security Reviewer",
   "API Reviewer") rather than raw ids.
 - Strict review gates for prompt compliance, diff review, verification, security,
   UX, operations, data, API, performance, tests, docs, quality, and final audit.
@@ -197,6 +201,12 @@ second) — negligible for a per-tool-call guard:
     `Goal Not Completed` with the exact missing review gates.
   - **Contextual gating**: the goal text and changed files determine which
     specialist reviewers are required.
+  - **Goal-only subagents**: the `goal-*` specialist subagents are mechanically
+    locked to Goal Mode. OpenCode resolves subagents globally, so the guard blocks
+    any Build, Plan, or custom agent that tries to invoke a `goal-*` reviewer via
+    the task tool — they run only under the Goal agent (toggle with
+    `restrictSubagents`). General-purpose subagents (`explore`/`general`/`scout`)
+    are never restricted.
   - **Reviewer Memory**: blocking reviewer findings are carried across cycles,
     surfaced in status/system context, and marked resolved by fresh PASS verdicts.
   - **Disk persistence**: review ledgers and Reviewer Memory survive OpenCode restarts.
@@ -208,9 +218,9 @@ second) — negligible for a per-tool-call guard:
     reviewer's friendly name, and a single "completion unlocked" toast the moment
     the last required gate clears.
 - An **experimental** companion TUI plugin (`plugins/goal-sidebar.tsx`) that, in
-  Goal sessions only, replaces the native todo sidebar area with a Goal-owned,
-  evidence-aware todo section. It shows a brief rainbow effect the first time it
-  appears, then normal goal colours. See [TUI integration](#tui-integration).
+  Goal sessions only, adds a Goal-owned, evidence-aware todo section to the
+  sidebar. It shows a brief rainbow effect the first time it appears, then normal
+  goal colours. See [TUI integration](#tui-integration).
 - A test suite validating the analyzer, plugin hooks, state store, install
   safety, and config compatibility.
 
@@ -220,26 +230,29 @@ Goal Mode is a **plugin pair**: the server-side `goal-guard` plugin owns
 enforcement and writes its state to disk, and an experimental TUI plugin
 (`plugins/goal-sidebar.tsx`) reads that same state to render a live todo section.
 
-- **Goal-mode todo replacement.** In a `goal` session, the sidebar content/todo
-  area is replaced by a Goal-owned todo section: short goal title, gate progress,
-  lifecycle status, and structured todo rows derived from acceptance criteria,
-  evidence freshness, dirty state, and missing review gates. It starts with a
-  brief rainbow foreground effect (`sidebarRainbowMs`) so the replacement is
-  visible, then returns to the normal lifecycle colours:
+- **Goal-owned todo section.** In a `goal` session, the sidebar gains a Goal-owned
+  todo section: short goal title, gate progress, lifecycle status, and structured
+  todo rows derived from acceptance criteria, evidence freshness, dirty state, and
+  missing review gates. It starts with a brief rainbow foreground effect
+  (`sidebarRainbowMs`) so it is immediately visible, then returns to the normal
+  lifecycle colours:
   - **yellow** — a goal is set and running;
   - **red** — the goal is done (all required gates pass and the tree is clean);
-  - **no render** — Build and every non-Goal mode keep OpenCode's native todo
-    section in the same sidebar position instead of being classified as a goal.
+  - **no render** — Build and every non-Goal mode render nothing here, so they
+    keep OpenCode's native todo section instead of being classified as a goal. The
+    section is scoped to the session that owns the goal: a Build session in the
+    same worktree never inherits another session's goal.
 
   Toggle/recolour with `sidebarBanner`, `sidebarColor` (running), `sidebarDoneColor`
   (done), `sidebarMutedColor`, `sidebarRainbowMs`, or the `GOAL_GUARD_SIDEBAR_*`
   env vars.
 
   **How it loads — important.** TUI plugins are **not** loaded from the `plugins/`
-  dir; OpenCode loads them from `tui.json`. The Goal sidebar waits to register its
-  `sidebar_content` slot until a real Goal session exists, so non-Goal modes do not
-  get a blank replacement slot. With `--global`, the installer writes
-  `~/.config/opencode/tui.json` for you (merge-safe):
+  dir; OpenCode loads them from `tui.json`. The Goal sidebar registers a
+  `sidebar_content` slot that renders content **only** for the active session when
+  that session is a Goal session; for any other session it renders nothing, so
+  non-Goal modes keep their native todo section. With `--global`, the installer
+  writes `~/.config/opencode/tui.json` for you (merge-safe):
 
   ```json
   { "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-goal-mode"] }
@@ -299,6 +312,7 @@ Or via environment variables (`GOAL_GUARD_*`):
 | `injectSystemState` / `GOAL_GUARD_INJECT_SYSTEM_STATE` | `true` | Inject live state into the prompt. |
 | `persist` / `GOAL_GUARD_PERSIST` | `true` | Persist state under the XDG state dir. |
 | `contextualGates` / `GOAL_GUARD_CONTEXTUAL_GATES` | `true` | Require specialist gates by goal keywords. |
+| `restrictSubagents` / `GOAL_GUARD_RESTRICT_SUBAGENTS` | `true` | Block non-Goal agents from invoking the `goal-*` subagents via the task tool. |
 | `maxSessions` / `GOAL_GUARD_MAX_SESSIONS` | `200` | Session cache size. |
 | `sessionTtlMs` / `GOAL_GUARD_SESSION_TTL_MS` | `86400000` | Idle session TTL. |
 | `toastOnBlock` / `GOAL_GUARD_TOAST_ON_BLOCK` | `true` | Toast when something is blocked. |

package/docs/sidebar-demo.svg

@@ -1,54 +1,69 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="760" height="280" viewBox="0 0 760 280" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" role="img" aria-label="OpenCode Goal Mode sidebar banner: the active goal in yellow with a gate-status line, and a grey No goal state.">
+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="360" viewBox="0 0 1000 360" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" role="img" aria-label="OpenCode Goal Mode sidebar: a Goal session shows a bold 'Goal todos' section with a first-display rainbow (running), turning red when done, with gate progress and todo rows. Build and other modes render no Goal section and keep OpenCode's native todo list.">
   <defs>
     <style>
       .win { fill: #0d1117; stroke: #30363d; stroke-width: 1; }
       .bar { fill: #161b22; }
       .dot { stroke-width: 0; }
       .title { fill: #8b949e; font-size: 12px; }
-      .label { fill: #8b949e; font-size: 12px; }
-      .goal { fill: #FFD700; font-size: 13px; }
-      .goalb { fill: #FFD700; font-size: 13px; font-weight: 700; }
-      .status { fill: #FFD700; font-size: 12px; }
-      .muted { fill: #808080; font-size: 13px; }
+      .label { fill: #8b949e; font-size: 11px; letter-spacing: 0.5px; }
+      .lbl  { font-size: 13px; font-weight: 700; }
+      .ln   { font-size: 13px; }
+      .sm   { font-size: 12px; }
       .chat { fill: #c9d1d9; font-size: 12px; }
       .dim { fill: #6e7681; font-size: 12px; }
       .ok { fill: #2da44e; font-size: 12px; }
+      .nat { fill: #8b949e; font-size: 12px; }
       .div { stroke: #30363d; stroke-width: 1; }
+      /* first-display rainbow: the guard colours each sidebar line with a
+         successive rainbow hue (RAINBOW[index]) before settling to yellow. */
+      .r0 { fill: #FF5555; } .r1 { fill: #FFAA00; } .r2 { fill: #FFFF55; }
+      .red { fill: #FF5555; }
     </style>
   </defs>
 
   <!-- window -->
-  <rect class="win" x="1" y="1" width="758" height="278" rx="8"/>
-  <rect class="bar" x="1" y="1" width="758" height="30" rx="8"/>
-  <rect class="bar" x="1" y="20" width="758" height="11"/>
+  <rect class="win" x="1" y="1" width="998" height="358" rx="8"/>
+  <rect class="bar" x="1" y="1" width="998" height="30" rx="8"/>
+  <rect class="bar" x="1" y="20" width="998" height="11"/>
   <circle class="dot" cx="20" cy="16" r="5" fill="#ff5f56"/>
   <circle class="dot" cx="38" cy="16" r="5" fill="#ffbd2e"/>
   <circle class="dot" cx="56" cy="16" r="5" fill="#27c93f"/>
   <text class="title" x="86" y="20">opencode — goal mode</text>
 
   <!-- vertical divider between chat and sidebar -->
-  <line class="div" x1="470" y1="31" x2="470" y2="279"/>
+  <line class="div" x1="470" y1="31" x2="470" y2="359"/>
 
   <!-- chat pane (left) -->
-  <text class="dim" x="20" y="58">▌ goal</text>
+  <text class="dim"  x="20" y="58">▌ goal</text>
   <text class="chat" x="20" y="82">▸ Goal Contract recorded (4 acceptance criteria)</text>
   <text class="chat" x="20" y="104">▸ implementing… running verification</text>
   <text class="ok"   x="20" y="126">✓ Security Reviewer → PASS</text>
   <text class="ok"   x="20" y="148">✓ Verifier → PASS</text>
   <text class="dim"  x="20" y="170">▸ Diff Reviewer running…</text>
+  <text class="dim"  x="20" y="206">Build / Plan / custom agents cannot</text>
+  <text class="dim"  x="20" y="224">invoke the goal-* reviewers — they are</text>
+  <text class="dim"  x="20" y="242">locked to the Goal agent.</text>
 
   <!-- sidebar pane (right) -->
-  <text class="label" x="490" y="58">SESSION</text>
-  <line class="div" x1="490" y1="68" x2="740" y2="68"/>
+  <!-- Goal session, RUNNING (first-display rainbow: line 0 red, 1 orange, 2 yellow) -->
+  <text class="label" x="490" y="56">GOAL SESSION · running · first-display rainbow</text>
+  <line class="div" x1="490" y1="64" x2="980" y2="64"/>
+  <text x="490" y="86"><tspan class="lbl r0">Goal todos</tspan><tspan class="ln r0">  Ship the OAuth refactor</tspan></text>
+  <text class="sm r1" x="490" y="104">0/5 gates · in progress</text>
+  <text class="sm r2" x="490" y="122">□ Clear review gates: goal-prompt-auditor,</text>
+  <text class="sm r2" x="490" y="138">goal-reviewer, goal-diff-reviewer…</text>
+  <text class="dim" x="490" y="156">↳ then settles to yellow while running</text>
 
-  <!-- goal banner (active) -->
-  <text x="490" y="98"><tspan class="goal">◆ </tspan><tspan class="goalb">GOAL</tspan><tspan class="goal">  Ship the OAuth</tspan></text>
-  <text class="goal"   x="490" y="116">refactor</text>
-  <text class="status" x="490" y="138">3/5 gates · dirty</text>
+  <!-- Goal session, DONE (red) -->
+  <text class="label" x="490" y="196">GOAL SESSION · done</text>
+  <line class="div" x1="490" y1="204" x2="980" y2="204"/>
+  <text x="490" y="226"><tspan class="lbl red">Goal todos</tspan><tspan class="ln red">  Fix the parser bug</tspan></text>
+  <text class="sm red" x="490" y="244">5/5 gates · completed · 2 review cycles</text>
+  <text class="sm red" x="490" y="262">✓ Record Goal Contract acceptance criteria</text>
 
-  <line class="div" x1="490" y1="170" x2="740" y2="170"/>
-
-  <!-- no-goal state -->
-  <text class="label" x="490" y="196">when no goal is set</text>
-  <text class="muted" x="490" y="222">No goal</text>
+  <!-- Build / non-Goal: native todos remain (no Goal section, no "No goal") -->
+  <text class="label" x="490" y="300">BUILD / OTHER MODE</text>
+  <line class="div" x1="490" y1="308" x2="980" y2="308"/>
+  <text class="nat" x="490" y="330">▢ OpenCode's native todo section</text>
+  <text class="dim" x="490" y="348">(no Goal section is rendered here)</text>
 </svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-mode",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "description": "Strict Goal Mode agents, commands, and guard plugin for OpenCode.",
   "type": "module",
   "main": "plugins/goal-sidebar.tsx",

package/plugins/goal-guard/config.js

@@ -20,6 +20,8 @@ export const DEFAULT_CONFIG = Object.freeze({
   persist: true,
   /** Require the contextual specialist gates derived from goal text / changed files. */
   contextualGates: true,
+  /** Block non-Goal agents from invoking the goal-* subagents via the task tool. */
+  restrictSubagents: true,
   /** Maximum tracked sessions before LRU eviction. */
   maxSessions: 200,
   /** Idle TTL (ms) after which a session's state may be dropped. 0 disables TTL. */
@@ -68,6 +70,7 @@ function fromEnv(env) {
     GOAL_GUARD_INJECT_SYSTEM_STATE: ["injectSystemState", coerceBool],
     GOAL_GUARD_PERSIST: ["persist", coerceBool],
     GOAL_GUARD_CONTEXTUAL_GATES: ["contextualGates", coerceBool],
+    GOAL_GUARD_RESTRICT_SUBAGENTS: ["restrictSubagents", coerceBool],
     GOAL_GUARD_MAX_SESSIONS: ["maxSessions", coerceInt],
     GOAL_GUARD_SESSION_TTL_MS: ["sessionTtlMs", coerceInt],
     GOAL_GUARD_TOAST_ON_BLOCK: ["toastOnBlock", coerceBool],

package/plugins/goal-guard/guard.js

@@ -23,7 +23,7 @@ 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 { isPrimaryAgent, isReviewAgent, isGoalAgent, 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";
@@ -41,6 +41,11 @@ function commandOf(input, output) {
   return String(output?.args?.command ?? input?.args?.command ?? "");
 }
 
+/** The subagent a `task` call targets (args live on the output in tool.execute.before). */
+function taskTarget(input, output) {
+  return String(output?.args?.subagent_type ?? input?.args?.subagent_type ?? output?.args?.agent ?? input?.args?.agent ?? "").trim();
+}
+
 function partsText(parts) {
   if (!Array.isArray(parts)) return "";
   return parts
@@ -130,6 +135,29 @@ export function createGuard(input = {}, options = {}, overrides = {}) {
 
     async "tool.execute.before"(inp, out) {
       const state = store.stateFor(inp?.sessionID);
+
+      // The goal-* subagents belong to Goal Mode. OpenCode resolves subagents
+      // globally, so without this a Build/Plan/custom agent could invoke a Goal
+      // reviewer directly. Only a Goal session (the `goal` primary, or a session
+      // the guard has already marked active) may spawn them. Non-goal targets
+      // (explore/general/scout) are never restricted.
+      if (inp?.tool === "task" && config.restrictSubagents) {
+        const target = taskTarget(inp, out);
+        if (target && isGoalAgent(target)) {
+          const caller = state.currentAgent;
+          const callerIsGoal = isPrimaryAgent(caller) || state.active;
+          if (!callerIsGoal) {
+            state.dirtyReasons.push(`blocked non-Goal invocation of subagent ${target}`);
+            if (config.toastOnBlock) logger.toast(`Goal Guard blocked ${prettyAgentName(target)} (Goal-only subagent)`, "error");
+            persist();
+            throw new Error(
+              `Goal Guard: "${target}" is a Goal Mode subagent and can only be invoked by the Goal agent. ` +
+                `The "${caller || "current"}" agent cannot call it — start with /goal or switch to the goal agent.`,
+            );
+          }
+        }
+      }
+
       if (inp?.tool === "bash") {
         const command = commandOf(inp, out);
         const analysis = analyzeCommand(command);

package/plugins/goal-guard/sidebar-data.js

@@ -30,22 +30,20 @@ function normalize(record) {
 }
 
 /**
- * Choose which session's goal to show: the most-recently-touched ACTIVE session
- * (optionally preferring an explicit sessionId when it is present and active).
+ * Resolve the guard state for EXACTLY this session id, and only when it is an
+ * active Goal session. There is deliberately NO "most-recently-touched" global
+ * fallback: a Build or other session in the same worktree must never inherit a
+ * Goal from a sibling session. This mirrors goal-sidebar.tsx's pickSession so the
+ * Node-testable projection and the real TUI component behave identically.
  */
 export function pickSession(snapshot, sessionId) {
-  if (!snapshot || !Array.isArray(snapshot.sessions)) return null;
-  const records = snapshot.sessions
-    .filter((e) => Array.isArray(e) && e.length === 2)
-    .map(([key, st]) => [key, normalize(st)]);
-  if (sessionId) {
-    const direct = records.find(([key, st]) => key === sessionId && st.active);
-    if (direct) return direct[1];
+  if (!snapshot || !Array.isArray(snapshot.sessions) || !sessionId) return null;
+  for (const entry of snapshot.sessions) {
+    if (!Array.isArray(entry) || entry.length !== 2) continue;
+    const [key, st] = entry;
+    if (key === sessionId && st && typeof st === "object" && st.active) return normalize(st);
   }
-  const active = records.filter(([, st]) => st.active);
-  if (active.length === 0) return null;
-  active.sort((a, b) => (b[1].touchedAt || 0) - (a[1].touchedAt || 0));
-  return active[0][1];
+  return null;
 }
 
 /**

package/plugins/goal-guard/tools.js

@@ -16,6 +16,7 @@ import { evidenceMapReport, reviewerMemoryReport, statusReport } from "./summary
 import { recordEvidence } from "./events.js";
 import { refreshStickyGates } from "./gates.js";
 import { createState } from "./state.js";
+import { isPrimaryAgent } from "./agents.js";
 
 const s = tool.schema;
 
@@ -28,6 +29,18 @@ const s = tool.schema;
 export function createGoalTools({ store, config, persist }) {
   const save = typeof persist === "function" ? persist : () => {};
 
+  function requireGoalMode(state) {
+    return Boolean(state?.active || isPrimaryAgent(state?.currentAgent));
+  }
+
+  function goalModeOnlyResult() {
+    return {
+      title: "Goal Mode required",
+      output: "This goal_* tool can only mutate Goal Guard state from an active Goal session. Switch to the `goal` agent or start with /goal.",
+      metadata: { blocked: true, reason: "not_goal_mode" },
+    };
+  }
+
   return {
     goal_status: tool({
       description:
@@ -37,6 +50,7 @@ export function createGoalTools({ store, config, persist }) {
       args: {},
       async execute(_args, ctx) {
         const state = store.stateFor(ctx.sessionID);
+        if (!requireGoalMode(state)) return goalModeOnlyResult();
         const report = statusReport(state, config);
         const goal = report.goal ? `“${report.goal}” — ` : "";
         return {
@@ -60,6 +74,7 @@ export function createGoalTools({ store, config, persist }) {
       args: {},
       async execute(_args, ctx) {
         const state = store.stateFor(ctx.sessionID);
+        if (!requireGoalMode(state)) return goalModeOnlyResult();
         const report = evidenceMapReport(state, config);
         const covered = report.criteria.filter((item) => item.status === "covered").length;
         return {
@@ -77,6 +92,7 @@ export function createGoalTools({ store, config, persist }) {
       args: {},
       async execute(_args, ctx) {
         const state = store.stateFor(ctx.sessionID);
+        if (!requireGoalMode(state)) return goalModeOnlyResult();
         const report = reviewerMemoryReport(state);
         return {
           title: `Reviewer Memory: ${report.open.length} open findings`,
@@ -109,6 +125,7 @@ export function createGoalTools({ store, config, persist }) {
       },
       async execute(args, ctx) {
         const state = store.stateFor(ctx.sessionID);
+        if (!requireGoalMode(state)) return goalModeOnlyResult();
         state.active = true;
         state.contract = {
           title: String(args.title || "").replace(/\s+/g, " ").trim(),
@@ -145,6 +162,7 @@ export function createGoalTools({ store, config, persist }) {
       },
       async execute(args, ctx) {
         const state = store.stateFor(ctx.sessionID);
+        if (!requireGoalMode(state)) return goalModeOnlyResult();
         state.active = true;
         recordEvidence(store, state, args.command, args.result, args.criteria);
         save();
@@ -164,6 +182,8 @@ export function createGoalTools({ store, config, persist }) {
         confirm: s.boolean().describe("Must be true to actually reset."),
       },
       async execute(args, ctx) {
+        const state = store.stateFor(ctx.sessionID);
+        if (!requireGoalMode(state)) return goalModeOnlyResult();
         if (!args.confirm) {
           return { title: "Reset not confirmed", output: "Pass confirm=true to reset Goal Guard state." };
         }

package/plugins/goal-sidebar.tsx

@@ -2,9 +2,11 @@
 /**
  * Goal Mode — TUI sidebar todo section.
  *
- * In Goal agent sessions this replaces the native-looking todo area with a
- * Goal-owned, evidence-aware todo section. Non-Goal sessions render nothing here
- * so Build and other modes keep OpenCode's normal todo section in the same slot.
+ * In Goal agent sessions this adds a Goal-owned, evidence-aware todo section to
+ * the sidebar. Non-Goal sessions render nothing here so Build and other modes
+ * keep OpenCode's normal todo section. The section is strictly per-session: it is
+ * keyed by props.session_id, so a Build session in the same worktree never
+ * inherits another session's goal.
  *
  * How OpenCode loads this: TUI plugins are listed in `~/.config/opencode/tui.json`
  * (NOT the plugins/ dir) and resolved via the package's `exports["./tui"]`. The
@@ -60,21 +62,21 @@ function readSnapshot(worktree) {
   }
 }
 
-/** Most-recently-touched active session, preferring an explicit active sessionId. */
+/**
+ * Resolve the guard state for EXACTLY this session id, and only when it is an
+ * active Goal session. There is deliberately NO "most-recently-touched" global
+ * fallback: a Build or other session in the same worktree must never inherit a
+ * Goal from a sibling session. (Mirrors the reference OpenCode TUI plugin's
+ * explicit per-session rule — do not fall back to the latest state.)
+ */
 function pickSession(snapshot, sessionId) {
-  if (!snapshot || !Array.isArray(snapshot.sessions)) return null;
-  const records = snapshot.sessions
-    .filter((e) => Array.isArray(e) && e.length === 2)
-    .map(([key, st]) => [key, st && typeof st === "object" ? st : {}]);
-  if (sessionId) {
-    const direct = records.find(([key, st]) => key === sessionId && st.active);
-    if (direct) return direct[1];
-    return null;
+  if (!snapshot || !Array.isArray(snapshot.sessions) || !sessionId) return null;
+  for (const entry of snapshot.sessions) {
+    if (!Array.isArray(entry) || entry.length !== 2) continue;
+    const [key, st] = entry;
+    if (key === sessionId && st && typeof st === "object" && st.active) return st;
   }
-  const active = records.filter(([, st]) => st.active);
-  if (active.length === 0) return null;
-  active.sort((a, b) => (b[1].touchedAt || 0) - (a[1].touchedAt || 0));
-  return active[0][1];
+  return null;
 }
 
 function readModel(worktree, sessionId) {
@@ -100,11 +102,7 @@ const tui = async (api, options) => {
 
     const worktree = api.state?.path?.worktree || api.state?.path?.directory;
 
-    let registered = false;
-    const register = () => {
-      if (registered) return;
-      registered = true;
-      api.slots.register({
+    api.slots.register({
         order: 50,
         slots: {
           sidebar_content(_ctx, props) {
@@ -143,19 +141,7 @@ const tui = async (api, options) => {
             );
           },
         },
-      });
-    };
-
-    if (readModel(worktree).state !== "none") {
-      register();
-    } else {
-      const registrationTimer = setInterval(() => {
-        if (readModel(worktree).state !== "none") {
-          clearInterval(registrationTimer);
-          register();
-        }
-      }, POLL_MS);
-    }
+    });
   } catch {
     /* TUI runtime missing or API drift — render nothing rather than crash. */
   }