@snarkipus/opencode-beads 0.9.1 → 0.9.3

package/README.md

@@ -2,124 +2,87 @@
 
 [Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
 
-This maintained fork provides the OpenCode-facing product layer around Beads: full `bd prime` context injection, vendored workflows, an autonomous task agent, and project-scoped runtime integration. It is deliberately an adapter rather than a second issue tracker: the `bd` CLI remains authoritative for issues, project initialization, skills, Dolt synchronization, migrations, and general Beads behavior.
+`@snarkipus/opencode-beads` is a maintained OpenCode adapter that provides full `bd prime` context injection, vendored `/beads:*` workflows, and a bounded task agent. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
 
 The project originated as [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads) and continues under the MIT license. This fork is maintained by Matt Jackson and tracks reviewed upstream Beads releases while adapting their plugin artifacts to OpenCode's CLI-only execution model.
 
-## Installation
-
-Install the `bd` CLI once on the host:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
-```
+## Design
 
-See the [Beads installation guide](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) for alternative methods (Homebrew, Windows, AUR, etc.).
+The plugin's primary design is **context-preserving atomic delegation**:
 
-Add the version-pinned plugin to your OpenCode config (`~/.config/opencode/opencode.json`):
+- The primary OpenCode thread retains planning context, decisions, and control.
+- `beads-task-agent` processes exactly one Bead per invocation, then closes, blocks, or returns.
+- Without an external orchestrator, this intentionally trades broad autonomy for Bead atomicity and context preservation.
+- An orchestrator may repeat `select → delegate one Bead → verify → select next`, but should not weaken the worker boundary.
 
-```json
-{
-  "plugin": ["@snarkipus/opencode-beads@0.9.1"]
-}
-```
-
-Restart OpenCode. OpenCode caches pinned plugins, so update this version explicitly when upgrading. An unpinned `@snarkipus/opencode-beads` entry follows npm updates on startup but is less reproducible.
+## Installation
 
-Initialize every new project separately. Create a Git worktree first if necessary, then run `bd init`:
+Install the [`bd` CLI](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) once on the host, then initialize each project:
 
 ```bash
-git init
+git init # only when the directory is not already a Git worktree
 bd init
 ```
 
-Skip `git init` when the project is already a Git worktree. `bd init` performs the per-project Beads initialization and its automatic Codex project integration creates the canonical shared skill at `.agents/skills/beads`, which OpenCode also discovers. `/beads:init` invokes the same project initialization workflow; this plugin has no separate skill lifecycle or companion CLI.
-
-### Upgrading from 0.8.0
+`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. This plugin has no separate skill lifecycle and does not write startup files.
 
-Version 0.8.0 installed a fork-managed skill under `.opencode/skills/beads`. Remove that old managed skill with the version-pinned 0.8.0 CLI before changing the plugin pin to 0.9.1:
-
-```bash
-bunx @snarkipus/opencode-beads@0.8.0 remove
-```
+Add the version-pinned plugin to `~/.config/opencode/opencode.json`:
 
-If the old skill was installed globally, append `--global` to that exact command. Do not substitute 0.9.1 in the removal command: the companion CLI no longer exists in 0.9.1.
-
-For a repository that has not been initialized with Beads, run `bd init`; it creates the canonical shared skill as part of normal initialization. For an already-initialized repository that is missing the skill, upstream currently has no skill-only setup command. Do not run `bd setup codex` as a substitute because it also installs Codex hooks and generated instructions. Instead, initialize a temporary Git repository with the same `bd` version and copy only its canonical skill directory into the target repository:
-
-```bash
-scratch="$(mktemp -d)"
-git -C "$scratch" init
-(cd "$scratch" && bd init)
-mkdir -p .agents/skills
-cp -R "$scratch/.agents/skills/beads" .agents/skills/beads
-rm -rf "$scratch"
+```json
+{
+  "plugin": ["@snarkipus/opencode-beads@0.9.3"]
+}
 ```
 
-This bounded migration copies only `.agents/skills/beads`; it does not copy `.codex` artifacts or generated instruction files.
+Restart OpenCode. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible.
 
-## Features
+## Context injection
 
-- **Context injection** - Loads the canonical Beads workflow and persistent memories on session start and after compaction
-- **Commands** - Vendored Beads workflows available under the `/beads:*` namespace
-- **Task agent** - Autonomous issue completion via `beads-task-agent` subagent
+The plugin runs full `bd prime` when a primary-agent session first receives a message and after compaction. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
 
-## Usage
+Known regular subagents remain excluded, including `explore` and `general`, while `beads-task-agent` remains eligible. If agent lookup fails, context injection fails open to preserve compatibility with unknown custom primary agents.
 
-This plugin is a thin OpenCode adapter. For Beads workflows, CLI commands, Dolt operations, migrations, backups, and issue-tracking concepts, use the [upstream documentation](https://github.com/gastownhall/beads) or run `bd prime`.
+If `bd` is unavailable, the project is uninitialized, or prime fails or returns no content, injection is silently skipped and remains retryable. Vendored commands stay available, and the task agent retains a bounded standalone quick reference for `ready`, `show`, atomic claim, discovered follow-up, validate before closure, and close.
 
-### Context behavior
+## Commands
 
-The plugin runs full `bd prime` when a primary-agent session first receives a message and after compaction, matching the canonical workflow pattern used by the upstream Claude Code and Codex integrations. The prime output supplies the current workflow, command guidance, and persistent memories; a compact shared layer adds only OpenCode-specific CLI safety and primary-agent delegation. Regular task subagents such as `explore` and `general` are deliberately skipped, while the included `beads-task-agent` remains explicitly eligible.
+Vendored workflows are registered under `/beads:*`, including `/beads:ready`, `/beads:create`, and `/beads:show`. The plugin does not generate a command for every `bd` subcommand; use the CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) for the complete surface.
 
-If `bd` is unavailable, the project is not initialized, or prime fails or returns no content, context injection is silently skipped and remains retryable. Vendored commands remain visible, the runtime does not initialize Beads or write startup files, and the task agent retains a bounded standalone quick reference for `ready`, `show`, atomic claim, discovered follow-up, and close. That fallback tells the agent to run `bd prime` when injected context is missing or stale; it does not duplicate the full live workflow.
+Explicit command and agent definitions in OpenCode configuration take precedence over plugin definitions with the same name. Exact `beads:*` or `beads-task-agent` collisions produce a grouped, rate-limited warning without preventing non-conflicting definitions from loading.
 
-## Commands
+## Task agent
 
-Commands are available as `/beads:<name>`, for example `/beads:ready`, `/beads:create`, and `/beads:show`. The plugin vendors every command template published by the upstream Beads plugin; it does not generate an OpenCode command for every `bd` subcommand. Use the `bd` CLI for the complete command surface and consult the generated [CLI reference](https://beads.gascity.com/cli-reference/index).
+`beads-task-agent` supports read-only status and graph analysis or one-Bead completion. Analysis requests never mutate Beads. Completion requests inspect and process one caller-selected or highest-priority ready Bead, quarantine work discovered during that invocation, validate before closure, and return after closing or blocking the selected Bead.
 
-Explicit command and agent definitions in your OpenCode configuration take precedence over plugin-provided definitions with the same name. The plugin emits a grouped, rate-limited warning for exact `beads:*` or `beads-task-agent` collisions while continuing to register every non-conflicting definition.
+Its runtime prompt is a fork-owned bounded OpenCode adaptation. The vendored upstream task-agent artifact supplies metadata, provenance, and compatibility validation; it is not executed as upstream's autonomous multi-task loop.
 
-## Agent
+## Vendored content
 
-### beads-task-agent
+[`scripts/sync-beads.sh`](scripts/sync-beads.sh) copies the reviewed upstream command templates and task-agent artifact into `vendor/`. [`vendor/manifest.json`](vendor/manifest.json) pins the upstream tag and commit and records source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates reviewed host-specific instructions to OpenCode's CLI-only model.
 
-A subagent for read-only status and graph analysis or one-bead task completion. Analysis requests never mutate beads; completion requests inspect and process one caller-selected or highest-priority ready bead, quarantine work created during that invocation, validate before closure, and return after closing or blocking the selected bead. Its configured prompt is role-specific; session injection supplies compact OpenCode-specific CLI, validation, delegation, and conservative commit/push/sync policy without duplicating `bd prime`.
+Do not edit vendored files directly. Sync and package validation reject provenance, checksum, inventory, schema, or reviewed-transformation drift. Adapter behavior lives in `src/`; general Beads behavior and documentation remain upstream.
 
 ## Compatibility
 
-The compatibility ranges and validated baselines for this release are:
-
 | Component | Expected range | Validated baseline |
 | --- | --- | --- |
-| OpenCode | 1.18.3 through 1.x | 1.18.4 |
-| `bd` CLI | 1.0.5 through 1.x | 1.1.0 |
+| OpenCode | 1.18.3 through 1.x | 1.18.15 |
+| `bd` CLI | 1.0.5 through 1.x | 1.1.2 |
 | Bun | >=1.3.14 | 1.3.14 |
 
-The OpenCode adapter builds against the exact paired `@opencode-ai/plugin` and `@opencode-ai/sdk` `1.18.4` releases and declares compatible optional peers from `1.18.3` through the stable `1.x` line. Both imports are type-only; the package does not install a second OpenCode runtime. Command and agent provenance is currently synced from Beads v1.1.0. Newer compatible releases may work but are not guaranteed until validated; when diagnosing a regression, reproduce it with the baselines above.
-
-## Vendored Content
-
-Files under `vendor/` are copied from the upstream Beads plugin by [`scripts/sync-beads.sh`](scripts/sync-beads.sh). The current inventory includes the complete upstream command-template directory and task agent, rather than a duplicate of the much larger `bd` CLI. [`vendor/manifest.json`](vendor/manifest.json) records the stable upstream tag and commit, source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates known MCP- or Claude-specific instructions to OpenCode's CLI-only model when prompts load; sync fails if provenance, checksums, inventory, or reviewed transformations differ. Do not edit vendored files directly: the next sync replaces them. Adapter behavior lives in `src/`, while general Beads behavior and documentation remain upstream.
-
-The vendor manifest, task agent, and every recorded command file are required package content. Their exact upstream source paths, inventory, byte lengths, and hashes are strict package inputs. Plugin loading fails with the artifact path and validation reason if required content is missing or malformed. Command frontmatter supports `description`, `argument-hint`, `agent`, `model`, and `subtask`; task-agent frontmatter supports `description`, `mode: subagent`, `model`, `temperature`, `top_p`, `disable`, `color`, and `maxSteps`. Unsupported fields or shapes fail validation so upstream changes receive explicit review. Reinstall the package or rerun the sync script from a source checkout rather than repairing generated files by hand.
+The adapter builds against paired `@opencode-ai/plugin` and `@opencode-ai/sdk` 1.18.15 releases and declares compatible optional peers from 1.18.3 through stable 1.x. Command and agent provenance is synced from Beads v1.2.1.
 
 ## Troubleshooting
 
-- **No Beads context:** Run `bd prime` in the project. Install `bd` if the command is missing, or run `bd init` if the project has no Beads workspace.
-- **Canonical skill is missing:** For a repository without a Beads workspace, run `bd init`. For an already-initialized repository, use the bounded manual-copy migration above; upstream currently has no skill-only setup command, and `bd setup codex` installs additional Codex integration artifacts.
-- **Upgrading from 0.8.0:** Run the exact version-pinned removal command in the upgrade section before updating the plugin pin, then use the appropriate fresh-initialization or existing-workspace path above.
-- **Vendor artifact initialization error:** Reinstall the package. If using a source checkout, rerun the vendor sync and validation scripts; the error names the missing or malformed manifest, command, or task-agent file.
-- **Unexpected command or agent definition:** Check the OpenCode configuration for a colliding `beads:*` or `beads-task-agent` entry. Your explicit configuration wins on an exact name collision; OpenCode logs a rate-limited warning naming the collision.
-- **A regular subagent has no Beads context:** This is intentional. Delegate Beads work to `beads-task-agent`, or run the required `bd` command explicitly.
-- **Behavior changed after an upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then check the [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
+- **No Beads context:** Run `bd prime`. Install `bd` if missing or run `bd init` if the project has no Beads workspace.
+- **Canonical skill missing:** For a new workspace, run `bd init`. For an existing workspace, follow current upstream Beads guidance; this plugin does not install or repair skills.
+- **Vendor initialization error:** Reinstall the package. In a source checkout, rerun vendor sync and validation; the error identifies the malformed or missing artifact.
+- **Unexpected definition:** Check OpenCode configuration for a colliding `beads:*` command or `beads-task-agent` definition. Explicit configuration wins.
+- **Regular subagent has no context:** This is intentional. Delegate Beads work to `beads-task-agent` or run the required `bd` command explicitly.
+- **Behavior changed after upgrade:** Compare `opencode --version`, `bd version`, and `bun --version` with the compatibility table, then inspect [Beads releases](https://github.com/gastownhall/beads/releases) and this project's changelog.
 
 ## License
 
-opencode-beads is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.
-
----
-
-opencode-beads is not built by, or affiliated with, the OpenCode team.
+opencode-beads is licensed under the MIT license. See [`LICENSE`](LICENSE).
 
-OpenCode is ©2025 Anomaly.
+opencode-beads is not built by or affiliated with the OpenCode team. OpenCode is ©2025 Anomaly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "type": "module",
   "description": "A maintained OpenCode integration for the Beads issue tracker, including context injection, vendored workflows, and a task agent.",
   "author": "Matt Jackson",
@@ -65,8 +65,8 @@
     }
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.18.4",
-    "@opencode-ai/sdk": "1.18.4",
+    "@opencode-ai/plugin": "1.18.15",
+    "@opencode-ai/sdk": "1.18.15",
     "@types/bun": "1.3.4",
     "@types/node": "^22.0.0",
     "typescript": "5.9.3"

package/src/opencode-runtime.ts

@@ -0,0 +1,156 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { Agent, SessionMessagesResponse } from "@opencode-ai/sdk";
+import type { PluginRuntime } from "./plugin-core";
+import { runBdPrime } from "./prime";
+
+export const DEFAULT_OPENCODE_REQUEST_TIMEOUT_MS = 5_000;
+export const DEFAULT_OPENCODE_DIAGNOSTIC_TIMEOUT_MS = 1_000;
+
+export class OpenCodeTimeoutError extends Error {
+  constructor(readonly operation: string, readonly timeoutMs: number) {
+    super(`OpenCode ${operation} timed out after ${timeoutMs}ms`);
+    this.name = "OpenCodeTimeoutError";
+  }
+}
+
+export interface OpenCodeRuntimeOptions {
+  requestTimeoutMs?: number;
+  diagnosticTimeoutMs?: number;
+  prime?: PluginRuntime["prime"];
+}
+
+async function withDeadline<T>(
+  operation: string,
+  timeoutMs: number,
+  execute: (signal: AbortSignal) => Promise<T>
+): Promise<T> {
+  const controller = new AbortController();
+  let rejectTimeout: (error: OpenCodeTimeoutError) => void = () => {};
+  const timeout = new Promise<never>((_resolve, reject) => {
+    rejectTimeout = reject;
+  });
+  const timer = setTimeout(() => {
+    const error = new OpenCodeTimeoutError(operation, timeoutMs);
+    controller.abort(error);
+    rejectTimeout(error);
+  }, timeoutMs);
+
+  try {
+    return await Promise.race([execute(controller.signal), timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isSessionMessage(value: unknown): boolean {
+  if (
+    !isRecord(value) ||
+    !isRecord(value.info) ||
+    (value.info.role !== "user" && value.info.role !== "assistant") ||
+    (value.info.agent !== undefined && typeof value.info.agent !== "string") ||
+    (value.info.system !== undefined && typeof value.info.system !== "string") ||
+    (value.info.model !== undefined &&
+      (!isRecord(value.info.model) ||
+        typeof value.info.model.providerID !== "string" ||
+        typeof value.info.model.modelID !== "string"))
+  ) {
+    return false;
+  }
+  if (!Array.isArray(value.parts)) return false;
+
+  return value.parts.every(
+    (part) =>
+      isRecord(part) &&
+      typeof part.type === "string" &&
+      (part.text === undefined || typeof part.text === "string") &&
+      (part.synthetic === undefined || typeof part.synthetic === "boolean")
+  );
+}
+
+function isAgent(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    (value.mode === "subagent" || value.mode === "primary" || value.mode === "all")
+  );
+}
+
+/** Adapt the official OpenCode client to the controller's small deterministic boundary. */
+export function createOpenCodeRuntime(
+  client: PluginInput["client"],
+  options: OpenCodeRuntimeOptions = {}
+): PluginRuntime {
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_OPENCODE_REQUEST_TIMEOUT_MS;
+  const diagnosticTimeoutMs =
+    options.diagnosticTimeoutMs ?? DEFAULT_OPENCODE_DIAGNOSTIC_TIMEOUT_MS;
+
+  return {
+    async getMessages(projectDirectory, sessionID, limit) {
+      const response = await withDeadline("session.messages", requestTimeoutMs, (signal) =>
+        client.session.messages({
+          path: { id: sessionID },
+          query: { directory: projectDirectory, limit },
+          signal,
+        })
+      );
+      if (response.error !== undefined) throw response.error;
+      if (!Array.isArray(response.data) || !response.data.every(isSessionMessage)) {
+        throw new Error("OpenCode returned malformed session messages");
+      }
+      return response.data satisfies SessionMessagesResponse;
+    },
+
+    async getAgents(projectDirectory) {
+      const response = await withDeadline("app.agents", requestTimeoutMs, (signal) =>
+        client.app.agents({ query: { directory: projectDirectory }, signal })
+      );
+      if (response.error !== undefined) throw response.error;
+      if (!Array.isArray(response.data) || !response.data.every(isAgent)) {
+        throw new Error("OpenCode returned malformed agents");
+      }
+      return response.data satisfies Agent[];
+    },
+
+    async prompt(projectDirectory, sessionID, body) {
+      const response = await withDeadline("session.prompt", requestTimeoutMs, (signal) =>
+        client.session.prompt({
+          path: { id: sessionID },
+          query: { directory: projectDirectory },
+          body,
+          signal,
+        })
+      );
+      if (response.error !== undefined) throw response.error;
+      if (response.data === undefined) throw new Error("OpenCode returned no prompt result");
+    },
+
+    async prime(projectDirectory) {
+      return (options.prime ?? runBdPrime)(projectDirectory);
+    },
+
+    async diagnose(diagnostic) {
+      const extra =
+        diagnostic.code === "config_collision"
+          ? { surface: diagnostic.surface, names: diagnostic.names }
+          : { sessionID: diagnostic.sessionID };
+      const response = await withDeadline("app.log", diagnosticTimeoutMs, (signal) =>
+        client.app.log({
+          query: { directory: diagnostic.directory },
+          body: {
+            service: "opencode-beads",
+            level: "warn",
+            message: diagnostic.code,
+            extra,
+          },
+          signal,
+        })
+      );
+      if (response.error !== undefined) throw response.error;
+      if (response.data === undefined) throw new Error("OpenCode returned no log result");
+    },
+  };
+}

package/src/plugin-core.ts

@@ -25,7 +25,8 @@ export type SessionMessage = {
   info: Pick<SessionMessageResponse["info"], "role"> &
     Partial<Pick<UserMessage, "agent" | "model" | "system">>;
   parts?: ReadonlyArray<
-    Pick<SessionMessageResponse["parts"][number], "type"> & Partial<Pick<TextPart, "text">>
+    Pick<SessionMessageResponse["parts"][number], "type"> &
+      Partial<Pick<TextPart, "text" | "synthetic">>
   >;
 };
 
@@ -79,9 +80,28 @@ export type MutablePluginConfig = Parameters<NonNullable<Hooks["config"]>>[0];
 export interface BeadsController {
   onMessage(message: MessageContext, sink: ContextSink): Promise<void>;
   onCompacted(sessionID: string): Promise<void>;
+  onSessionDeleted(sessionID: string): void;
   configure(config: MutablePluginConfig): Promise<void>;
 }
 
+type InjectionAudience = "primary" | "task-agent";
+const BEADS_CONTEXT_HEADER = /^<beads-context(?: audience="(primary|task-agent)")?>\n/;
+
+/** Recognize only the complete envelope emitted by this plugin. */
+export function isBeadsContextEnvelope(text: string): boolean {
+  const trimmed = text.trim();
+  return BEADS_CONTEXT_HEADER.test(trimmed) && trimmed.includes("\n</beads-context>");
+}
+
+function beadsContextAudience(text: string): InjectionAudience | undefined {
+  const audience = text.trim().match(BEADS_CONTEXT_HEADER)?.[1];
+  return audience === "primary" || audience === "task-agent" ? audience : undefined;
+}
+
+function injectionAudience(agentName: string | undefined): InjectionAudience {
+  return agentName === BEADS_TASK_AGENT ? "task-agent" : "primary";
+}
+
 /** Resolve OpenCode project scope without falling back to the process directory. */
 export function resolveProjectDirectory(directory: string, worktree: string): string {
   if (directory.trim()) return directory;
@@ -112,8 +132,8 @@ export async function createBeadsController(
   const [loadedCommands, loadedAgents] = await Promise.all([loadCommands(), loadAgent()]);
   const commands = loadedCommands ?? {};
   const agents = loadedAgents ?? {};
-  const injectedSessions = new Set<string>();
-  const injectionAttempts = new Map<string, Promise<void>>();
+  const injectedAudiences = new Map<string, Set<InjectionAudience>>();
+  const injectionAttempts = new Map<string, { promise: Promise<void>; cancelled: boolean }>();
   const diagnosticTimes = new Map<string, number>();
   const diagnosticIntervalMs = options.diagnosticIntervalMs ?? 60_000;
   const now = options.now ?? Date.now;
@@ -124,7 +144,9 @@ export async function createBeadsController(
     if (previousTime !== undefined && currentTime - previousTime < diagnosticIntervalMs) return;
 
     diagnosticTimes.set(key, currentTime);
-    await runtime.diagnose(diagnostic).catch(() => undefined);
+    void Promise.resolve()
+      .then(() => runtime.diagnose(diagnostic))
+      .catch(() => undefined);
   }
 
   async function diagnoseSession(
@@ -162,8 +184,14 @@ export async function createBeadsController(
     }
     if (!output) return undefined;
 
-    const audience = context?.agent === BEADS_TASK_AGENT ? "task-agent" : "primary";
-    return `<beads-context>\n${output}\n</beads-context>\n\n${beadsGuidance(audience)}`;
+    const audience = injectionAudience(context?.agent);
+    return `<beads-context audience="${audience}">\n${output}\n</beads-context>\n\n${beadsGuidance(audience)}`;
+  }
+
+  function markInjected(sessionID: string, audience: InjectionAudience): void {
+    const audiences = injectedAudiences.get(sessionID) ?? new Set<InjectionAudience>();
+    audiences.add(audience);
+    injectedAudiences.set(sessionID, audiences);
   }
 
   async function injectPrompt(
@@ -193,28 +221,41 @@ export async function createBeadsController(
     }
   }
 
-  async function performInitialInjection(message: MessageContext, sink: ContextSink): Promise<void> {
-    if (!(await shouldInject(message.agent, message.sessionID))) {
-      injectedSessions.add(message.sessionID);
-      return;
-    }
+  async function performInitialInjection(
+    message: MessageContext,
+    sink: ContextSink,
+    isActive: () => boolean
+  ): Promise<void> {
+    if (!(await shouldInject(message.agent, message.sessionID))) return;
 
-    try {
-      const existing = await runtime.getMessages(directory, message.sessionID);
-      const hasBeadsContext = existing?.some(
-        (item) =>
-          item.info.system?.includes("<beads-context>") ||
-          item.parts?.some(
-            (part) => part.type === "text" && part.text?.includes("<beads-context>")
-          )
-      );
-      if (hasBeadsContext) {
-        injectedSessions.add(message.sessionID);
-        return;
+    const audience = injectionAudience(message.agent);
+    const knownAudiences = injectedAudiences.get(message.sessionID);
+    if (knownAudiences?.has(audience)) return;
+
+    // On plugin reload there is no local audience state, so consult persisted envelopes.
+    if (!knownAudiences) {
+      try {
+        const existing = await runtime.getMessages(directory, message.sessionID);
+        const hasBeadsContext = existing?.some(
+          (item) =>
+            (item.info.system !== undefined &&
+              beadsContextAudience(item.info.system) === audience) ||
+            item.parts?.some(
+              (part) =>
+                part.type === "text" &&
+                part.synthetic === true &&
+                part.text !== undefined &&
+                beadsContextAudience(part.text) === audience
+            )
+        );
+        if (hasBeadsContext) {
+          if (isActive()) markInjected(message.sessionID, audience);
+          return;
+        }
+      } catch {
+        await diagnoseSession("messages_lookup_failed", message.sessionID);
+        // Message lookup is advisory; injection remains the safe fallback.
       }
-    } catch {
-      await diagnoseSession("messages_lookup_failed", message.sessionID);
-      // Message lookup is advisory; injection remains the safe fallback.
     }
 
     const rendered = await renderContext(message.sessionID, message);
@@ -222,7 +263,7 @@ export async function createBeadsController(
 
     try {
       await sink(rendered);
-      injectedSessions.add(message.sessionID);
+      if (isActive()) markInjected(message.sessionID, audience);
     } catch {
       await diagnoseSession("prompt_failed", message.sessionID);
     }
@@ -230,18 +271,21 @@ export async function createBeadsController(
 
   return {
     async onMessage(message, sink) {
-      if (injectedSessions.has(message.sessionID)) return;
+      const audience = injectionAudience(message.agent);
+      if (injectedAudiences.get(message.sessionID)?.has(audience)) return;
 
-      const pending = injectionAttempts.get(message.sessionID);
-      if (pending) return pending;
+      const attemptKey = `${message.sessionID}\0${audience}`;
+      const pending = injectionAttempts.get(attemptKey);
+      if (pending) return pending.promise;
 
-      const attempt = performInitialInjection(message, sink);
-      injectionAttempts.set(message.sessionID, attempt);
+      const attempt = { promise: Promise.resolve(), cancelled: false };
+      attempt.promise = performInitialInjection(message, sink, () => !attempt.cancelled);
+      injectionAttempts.set(attemptKey, attempt);
       try {
-        await attempt;
+        await attempt.promise;
       } finally {
-        if (injectionAttempts.get(message.sessionID) === attempt) {
-          injectionAttempts.delete(message.sessionID);
+        if (injectionAttempts.get(attemptKey) === attempt) {
+          injectionAttempts.delete(attemptKey);
         }
       }
     },
@@ -257,6 +301,19 @@ export async function createBeadsController(
       }
     },
 
+    onSessionDeleted(sessionID) {
+      injectedAudiences.delete(sessionID);
+      for (const [key, attempt] of injectionAttempts) {
+        if (key.startsWith(`${sessionID}\0`)) {
+          attempt.cancelled = true;
+          injectionAttempts.delete(key);
+        }
+      }
+      for (const key of diagnosticTimes.keys()) {
+        if (key.endsWith(`:${sessionID}`)) diagnosticTimes.delete(key);
+      }
+    },
+
     async configure(config) {
       const commandCollisions = Object.keys(config.command ?? {})
         .filter(

package/src/plugin-hooks.ts

@@ -0,0 +1,56 @@
+import type { Hooks } from "@opencode-ai/plugin";
+import type { Part } from "@opencode-ai/sdk";
+import {
+  createBeadsController,
+  isBeadsContextEnvelope,
+  type PluginRuntime,
+} from "./plugin-core";
+
+/** Prevent the synthetic no-reply prompt from recursively triggering its own injection. */
+function isBeadsContextInjection(parts: ReadonlyArray<Part>): boolean {
+  return parts.some(
+    (part) =>
+      part.type === "text" &&
+      part.synthetic === true &&
+      isBeadsContextEnvelope(part.text)
+  );
+}
+
+/** Build OpenCode hooks around an explicit runtime boundary. */
+export async function createBeadsHooks(
+  runtime: PluginRuntime,
+  projectDirectory: string
+): Promise<Hooks> {
+  const controller = await createBeadsController(runtime, projectDirectory);
+
+  return {
+    "chat.message": async (input, output) => {
+      if (isBeadsContextInjection(output.parts)) return;
+
+      await controller.onMessage(
+        {
+          sessionID: input.sessionID,
+          model: input.model,
+          agent: input.agent,
+        },
+        (context) => {
+          output.message.system = output.message.system
+            ? `${output.message.system}\n\n${context}`
+            : context;
+        }
+      );
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.compacted") {
+        await controller.onCompacted(event.properties.sessionID);
+      } else if (event.type === "session.deleted") {
+        controller.onSessionDeleted(event.properties.info.id);
+      }
+    },
+
+    config: async (config) => {
+      await controller.configure(config);
+    },
+  };
+}