fix: scope worker plugin to Ralph worker sessions (no pollution of normal sessions)

The plugin loads for every session in a project. Its worker system prompt,
edit/bash context gate, and compaction context were applied to ALL sessions —
breaking normal OpenCode usage (gated edit/bash, injected worker prompt). Now
scoped to rlm-worker-attempt-* sessions only; ralph_/rlm_ tools are inert
elsewhere. +5 tests (102 total).

Author: doeixd

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.3.6] - 2026-06-24
+
+### Fixed
+
+- **Worker plugin no longer pollutes normal OpenCode sessions.** The plugin loads for every session in a project, but its worker system prompt, the edit/bash **context gate**, and compaction context were being applied to *all* sessions — which injected worker instructions into normal chats and blocked `edit`/`bash` until `ralph_load_context()` (a call a normal session never makes). These now apply **only to Ralph worker sessions** (identified by the `rlm-worker-attempt-*` session title). In normal sessions the `ralph_*` / `rlm_*` tools are inert (they error if invoked) and `edit`/`bash` are never gated.
+
 ## [0.3.5] - 2026-06-24
 
 ### Changed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doeixd/opencode-ralph-rlm",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Ralph RLM v0.2: OpenCode supervisor provider + loop engine + worker plugin",
   "type": "module",
   "workspaces": [

packages/engine/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@doeixd/opencode-ralph-rlm-engine",
   "private": true,
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Ralph RLM loop engine — verify, rollover, OpenCode SDK worker lifecycle",
   "license": "MIT",
   "repository": {

packages/provider/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@doeixd/opencode-ralph-rlm-provider",
   "private": true,
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Ralph RLM OpenAI-compatible supervisor provider (Nitro)",
   "license": "MIT",
   "repository": {

packages/provider/server/routes/api/health.get.ts

@@ -16,7 +16,7 @@ export default defineHandler(async () => {
   return {
     healthy: true,
     provider: "@doeixd/opencode-ralph-rlm",
-    version: "0.3.5",
+    version: "0.3.6",
     opencode: {
       baseUrl: runtime.baseUrl,
       ...opencode,

packages/worker-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@doeixd/opencode-ralph-rlm-worker-plugin",
   "private": true,
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Thin Ralph RLM worker plugin — file-first tools and context gating",
   "license": "MIT",
   "repository": {

packages/worker-plugin/src/ralph-worker.ts

@@ -25,7 +25,7 @@ import {
   type PlanContext,
   type ResolvedConfig,
 } from "@doeixd/opencode-ralph-rlm/engine";
-import { shouldGateDestructiveTool } from "./gate.js";
+import { SAFE_TOOLS, shouldGateDestructiveTool } from "./gate.js";
 import { freshWorkerSession, type WorkerSessionState } from "./session-state.js";
 import { loadWorkerPluginTemplates } from "./templates.js";
 
@@ -48,6 +48,30 @@ export const RalphWorkerPlugin: Plugin = async ({ client, worktree }) => {
     return resolvePlanContext(root, cfg.plans);
   }
 
+  // This plugin loads for EVERY session in the project. Ralph behavior (worker
+  // system prompt, the edit/bash context gate, compaction context, and the
+  // ralph_/rlm_ tools) must only apply to Ralph worker sessions — never to a
+  // user's normal OpenCode sessions. Worker sessions are titled
+  // `rlm-worker-attempt-N` by the engine; we scope by that title.
+  const workerSessionCache = new Map<string, boolean>();
+  async function isRalphWorkerSession(sessionID: string): Promise<boolean> {
+    const cached = workerSessionCache.get(sessionID);
+    if (cached !== undefined) return cached;
+    try {
+      const res = await client.session.get({
+        path: { id: sessionID },
+        query: { directory: worktree },
+      });
+      const title = ((res as { data?: { title?: string } })?.data?.title ?? "") as string;
+      const isWorker = title.startsWith("rlm-worker-attempt-");
+      workerSessionCache.set(sessionID, isWorker); // cache only confirmed results
+      return isWorker;
+    } catch {
+      // Transient failure — don't cache; retry on the next call.
+      return false;
+    }
+  }
+
   /** Worktree-relative path to CONTEXT_FOR_RLM.md for the active plan. */
   function rlmCtxRel(pctx: PlanContext): string {
     return pctx.protocolRel
@@ -573,27 +597,43 @@ export const RalphWorkerPlugin: Plugin = async ({ client, worktree }) => {
     },
 
     "experimental.chat.system.transform": async (input: { sessionID?: string }, output: { system?: string[] }) => {
+      const sessionID = input.sessionID;
+      // Only inject the worker system prompt into Ralph worker sessions —
+      // never into the user's normal OpenCode sessions.
+      if (!sessionID || !(await isRalphWorkerSession(sessionID))) return;
       output.system = output.system ?? [];
       output.system.push(templates.workerSystemPrompt);
-      const sessionID = input.sessionID;
-      if (sessionID) {
-        await syncSessionAttempt(sessionID, worktree);
-      }
+      await syncSessionAttempt(sessionID, worktree);
     },
 
-    "experimental.session.compacting": async (_input: unknown, output: { context?: string[] }) => {
+    "experimental.session.compacting": async (
+      input: { sessionID?: string },
+      output: { context?: string[] }
+    ) => {
+      if (!input.sessionID || !(await isRalphWorkerSession(input.sessionID))) return;
       output.context = output.context ?? [];
       output.context.push(templates.compactionContext);
     },
 
     "tool.execute.before": async (input: { sessionID?: string; tool?: string; call?: { name?: string } }) => {
-      const cfg = await getConfig();
       const sessionID = input.sessionID;
       if (!sessionID) return;
+      const toolName = input.tool ?? input.call?.name ?? "";
+
+      // In a normal (non-worker) session, the plugin's tools are present but
+      // must stay inert, and we must NOT gate the user's edit/bash.
+      if (!(await isRalphWorkerSession(sessionID))) {
+        if (SAFE_TOOLS.has(toolName)) {
+          throw new Error(
+            "This Ralph RLM tool only runs inside a Ralph worker session (created by the loop), not a normal OpenCode session."
+          );
+        }
+        return;
+      }
 
+      const cfg = await getConfig();
       await syncSessionAttempt(sessionID, worktree);
       const st = getSession(sessionID);
-      const toolName = input.tool ?? input.call?.name ?? "";
       if (
         shouldGateDestructiveTool({
           gateEnabled: cfg.gateDestructiveToolsUntilContextLoaded,

packages/worker-plugin/src/test/session-scope.test.ts

@@ -0,0 +1,88 @@
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "bun:test";
+import { RalphWorkerPlugin } from "../ralph-worker.js";
+
+function mockClient(title: string) {
+  return {
+    session: { get: async () => ({ data: { title } }) },
+    tui: { showToast: async () => {} },
+  };
+}
+
+async function loadHooks(title: string) {
+  const worktree = await mkdtemp(path.join(tmpdir(), "ralph-scope-"));
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const hooks = await RalphWorkerPlugin({ client: mockClient(title), worktree } as any);
+  return { hooks: hooks as any, worktree };
+}
+
+describe("plugin scoping: normal vs worker sessions", () => {
+  test("worker system prompt is injected only in worker sessions", async () => {
+    const worker = await loadHooks("rlm-worker-attempt-1");
+    const normal = await loadHooks("My normal chat");
+    try {
+      const wOut: { system?: string[] } = {};
+      await worker.hooks["experimental.chat.system.transform"]({ sessionID: "w" }, wOut);
+      expect(wOut.system?.length).toBe(1);
+
+      const nOut: { system?: string[] } = {};
+      await normal.hooks["experimental.chat.system.transform"]({ sessionID: "n" }, nOut);
+      expect(nOut.system ?? []).toEqual([]);
+    } finally {
+      await rm(worker.worktree, { recursive: true, force: true });
+      await rm(normal.worktree, { recursive: true, force: true });
+    }
+  });
+
+  test("normal session: edit/bash are NOT gated", async () => {
+    const { hooks, worktree } = await loadHooks("Just a chat");
+    try {
+      // Must not throw — the gate must not apply to non-worker sessions.
+      await hooks["tool.execute.before"]({ sessionID: "n", tool: "edit" });
+      await hooks["tool.execute.before"]({ sessionID: "n", tool: "bash" });
+    } finally {
+      await rm(worktree, { recursive: true, force: true });
+    }
+  });
+
+  test("normal session: Ralph tools are blocked (inert)", async () => {
+    const { hooks, worktree } = await loadHooks("Just a chat");
+    try {
+      await expect(
+        hooks["tool.execute.before"]({ sessionID: "n", tool: "ralph_load_context" })
+      ).rejects.toThrow(/Ralph/);
+    } finally {
+      await rm(worktree, { recursive: true, force: true });
+    }
+  });
+
+  test("worker session: edit is gated until ralph_load_context", async () => {
+    const { hooks, worktree } = await loadHooks("rlm-worker-attempt-2");
+    try {
+      await expect(
+        hooks["tool.execute.before"]({ sessionID: "w", tool: "edit" })
+      ).rejects.toThrow();
+    } finally {
+      await rm(worktree, { recursive: true, force: true });
+    }
+  });
+
+  test("compaction context only added in worker sessions", async () => {
+    const worker = await loadHooks("rlm-worker-attempt-1");
+    const normal = await loadHooks("chat");
+    try {
+      const wOut: { context?: string[] } = {};
+      await worker.hooks["experimental.session.compacting"]({ sessionID: "w" }, wOut);
+      expect(wOut.context?.length).toBe(1);
+
+      const nOut: { context?: string[] } = {};
+      await normal.hooks["experimental.session.compacting"]({ sessionID: "n" }, nOut);
+      expect(nOut.context ?? []).toEqual([]);
+    } finally {
+      await rm(worker.worktree, { recursive: true, force: true });
+      await rm(normal.worktree, { recursive: true, force: true });
+    }
+  });
+});