@snarkipus/opencode-beads 0.9.4 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
 
-`@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.
+`@snarkipus/opencode-beads` is a maintained OpenCode adapter that provides full `bd prime` context injection 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.
 
@@ -24,64 +24,127 @@ git init # only when the directory is not already a Git worktree
 bd init
 ```
 
-`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.
+`bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. It also writes a minimal Beads section to `AGENTS.md` that points to `bd prime`, the same pointer Beads gives Claude Code in `CLAUDE.md`. This plugin has no separate skill lifecycle and does not write startup files.
 
-Add the version-pinned plugin to `~/.config/opencode/opencode.json`:
+**Do not run `bd setup opencode`.** That recipe is for OpenCode without this plugin: because Beads assumes OpenCode has no hooks, it replaces the minimal pointer with the full command reference (about 2 kB more on every request). With this plugin, `bd prime` arrives through OpenCode's hooks instead, as it does for Claude Code. If you already ran it, `bd setup opencode --remove` deletes that section, or simply leave it: while prime is attached, the plugin replaces it in the request with a one-line pointer.
+
+Installing the plugin gives OpenCode the same integration that `bd setup claude` gives Claude Code:
+
+| `bd setup claude` (Claude Code) | This plugin (OpenCode 2) |
+| --- | --- |
+| `SessionStart` hook runs `bd prime --hook-json`, also on resume and after compaction | The session context hook attaches `bd prime` to each request; it is refreshed after compaction |
+| Minimal `CLAUDE.md` pointer to `bd prime` | `bd init`'s minimal `AGENTS.md` pointer; bd's full or Codex sections are reduced to a pointer while prime is attached |
+| `--global` or project install | Global `~/.config/opencode/opencode.json` or project `opencode.json` `plugins` entry |
+| `--remove` | Remove the `plugins` entry |
+| `--check` | `opencode debug agents` lists `beads-task-agent`; a session's agent sees a `<beads-context>` block |
+
+The [Claude Code parity matrix](docs/claude-code-parity.md) records every `bd setup claude` behavior, its OpenCode equivalent and live evidence, the OpenCode-only capabilities, and the deliberate divergences.
+
+This plugin requires OpenCode 2 and `bd` 1.3.0 or later. Add the version-pinned plugin to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugins": ["@snarkipus/opencode-beads@1.0.0"]
+}
+```
+
+Plugin options use the object form:
 
 ```json
 {
-  "plugin": ["@snarkipus/opencode-beads@0.9.4"]
+  "plugins": [
+    {
+      "package": "@snarkipus/opencode-beads@1.0.0",
+      "options": { "luna": true, "autoMigrate": false }
+    }
+  ]
 }
 ```
 
-Restart OpenCode. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible.
+| Option | Default | Effect |
+| --- | --- | --- |
+| `luna` | `false` | Also register the `beads-task-agent-luna` profile. |
+| `stealth` | `false` | Run `bd prime --stealth` (no git operations in the session-close protocol), like `bd setup claude --stealth`. `bd config set no-git-ops true` is the project-level equivalent. |
+| `taskAgentSteps` | `100` | Hard cap on task-agent steps per invocation, a backstop for "one bead, then return". `0` removes the cap. |
+| `refreshAfterIdleMinutes` | `30` | Re-run `bd prime` when a session resumes after this much inactivity, as Claude Code does on resume. `0` disables idle refresh. |
+| `autoMigrate` | `false` | Let automatic `bd prime` open a store that may need a schema migration. See [Schema migration guard](#schema-migration-guard). |
+
+OpenCode loads configuration changes automatically. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible. OpenCode 1.x plugins are not supported; use 0.10.x or earlier there.
 
 ### 0.9.3 recovery notice
 
-Version 0.9.3 contained command guidance from the withdrawn upstream Beads v1.2.1 release. This plugin did not bundle the `bd` binary or implement database migrations, but it could invoke a consumer-installed v1.2.1 binary through `bd prime`. Even one v1.2.1 execution could migrate the database. Upgrade the plugin package to 0.9.4; if v1.2.1 was installed and may have run, also follow the [upstream database recovery guidance](https://github.com/gastownhall/beads/blob/v1.2.2/docs/RECOVERY-1.2.1.md).
+Version 0.9.3 contained command guidance from the withdrawn upstream Beads v1.2.1 release. This plugin did not bundle the `bd` binary or implement database migrations, but it could invoke a consumer-installed v1.2.1 binary through `bd prime`. Even one v1.2.1 execution could migrate the database. Upgrade the plugin package to 0.9.4 or later; if v1.2.1 was installed and may have run, also follow the [upstream database recovery guidance](https://github.com/gastownhall/beads/blob/v1.2.2/docs/RECOVERY-1.2.1.md).
 
 ## Context injection
 
-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.
+The plugin runs full `bd prime` in the project directory and attaches its output to each model request through OpenCode's session context hook. The output is cached per session, so prime runs once per session rather than per request. It runs again after compaction (automatic or manual), when a session resumes after `refreshAfterIdleMinutes` of inactivity, and when the plugin reloads, mirroring the `startup`, `resume`, `clear`, and `compact` sources of Claude Code's `SessionStart` hook. Steady work keeps the same text, which keeps provider prompt caches warm. Attached context is not stored in the conversation, so compaction cannot drop it. Prime supplies the canonical current workflow, command guidance, and persistent memories; the plugin adds only compact OpenCode-specific safety and delegation guidance.
 
-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.
+While prime is attached, bd's full-profile `AGENTS.md` section and its Codex section (the blocks `bd init` and `bd setup opencode` manage) only repeat it. The plugin replaces those marked blocks in the outgoing request with a one-line pointer, matching the minimal `CLAUDE.md` pointer Beads uses for Claude Code. Your `AGENTS.md` file and any text outside those markers are not changed, and nothing is replaced when prime is withheld or unavailable.
 
-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.
+Known regular subagents remain excluded, including `explore` and `general`, while `beads-task-agent` and `beads-task-agent-luna` remain eligible. If agent lookup fails, context injection fails open to preserve compatibility with unknown custom primary agents.
 
-## Commands
+If `bd` is unavailable or the project is uninitialized, nothing is added. If `bd prime` fails or times out, the agent gets a short `<beads-notice>` saying context is unavailable and to run `bd prime`, as Beads' Codex hooks report refresh failures. Either way the plugin retries after 30 seconds, and failures are also logged as `[opencode-beads]` warnings. The task agent retains a bounded standalone quick reference for `ready`, `show`, atomic claim, discovered follow-up, validate before closure, and close.
 
-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.
+## Schema migration guard
 
-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.
+Beads 1.3 migrates an embedded store in place, irreversibly, the first time any command opens it, and `bd --readonly` does not prevent that. Because this plugin runs `bd prime` automatically, it would otherwise be the unattended first command after you upgrade `bd`.
+
+Before running prime, the plugin checks `bd version` and `bd where --json`, which never open the store, and reads `.beads/.local_version`. If the installed `bd` is older than 1.3.0, or the store was last opened by an older `bd`, the plugin withholds prime and gives the agent a notice telling it not to run `bd` and to ask you to act. To proceed, back up the `.beads` directory and run `bd migrate schema`; the plugin picks up the change on its next retry. Setting the `autoMigrate` option skips the store-version check.
+
+`bd prime` itself does not update `.beads/.local_version`. A store migrated only by prime keeps the old marker until you run `bd migrate schema` (or any ordinary `bd` command), which is safe and idempotent.
+
+## Beads workflows
+
+The plugin registers no `/beads:*` commands. Earlier versions vendored upstream's Claude Code command templates; they duplicated `bd prime` and the canonical Beads skill that `bd init` installs at `.agents/skills/beads`, which OpenCode discovers natively. Ask the agent to work with Beads, load the skill with `@beads`, or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly.
+
+## Agent configuration
+
+Entries under `agents` in OpenCode configuration override the plugin's task-agent fields one by one, so a partial override (for example only `description`) keeps the bounded `system` prompt and subagent `mode`. Fields you set explicitly, such as `system`, `model`, or `permissions`, win. OpenCode V2 does not expose configuration-only agents to plugins, so the plugin no longer warns about overrides.
 
 ## Task agent
 
 `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.
 
-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.
+Its prompt and description are fork-owned. Upstream Beads ships a task agent only for Claude Code, as an autonomous multi-task loop; this adapter deliberately keeps the bounded one-Bead contract instead, so it no longer vendors that artifact.
+
+OpenCode lets the plugin enforce parts of that contract, beyond what Claude Code's hooks can do:
+
+- **No automatic commit, push, or sync.** The task agents' permissions require approval (`ask`) for `git commit`, `git push`, `bd dolt push`, `bd dolt pull`, and `bd sync`, on top of OpenCode's defaults. Compound commands are checked per command. A non-interactive run rejects them. Set the agent's `permissions` in OpenCode configuration to replace these rules.
+- **Step cap.** `taskAgentSteps` (default 100) limits a worker invocation; on its final step OpenCode removes tools and asks for a summary.
+- **Context in the worker.** The worker runs in its own child session and receives `bd prime` there too; Claude Code's `SessionStart` hooks do not reach subagents.
+- **Beads state across compaction.** Compaction requests in sessions with Beads context ask the summarizer to keep bead IDs, claim and status changes, discovered follow-ups, blockers, and pending validation.
+
+### Opt-in Luna Max profile
+
+The default `beads-task-agent` leaves its model unset, so a subagent inherits the parent session's model. Set the plugin option `"luna": true` to also register `beads-task-agent-luna`, which uses `openai/gpt-6-luna#max` with exactly the same prompt, subagent mode, and default permissions. Per-agent overrides remain independent: customizations to `beads-task-agent` are not copied to Luna. Both profiles receive full prime context and retain the same exact-one-Bead workflow.
+
+Ask the primary agent to delegate to `beads-task-agent-luna` by name through the `subagent` tool. Default delegation guidance still names `beads-task-agent`; enabling Luna does not reroute existing calls or change the primary agent's model. Remove the option to unregister the profile.
+
+Luna requires access to `openai/gpt-6-luna` and its `max` variant in your OpenCode provider setup. The plugin does not install models, configure authentication, or silently fall back to another model.
 
-## Vendored content
+## Tracking upstream Beads
 
-[`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.
+The package vendors nothing from upstream. It depends on the installed `bd` CLI at runtime: `bd prime` supplies the current workflow, and the schema migration guard enforces the supported `bd` range.
 
-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.
+[`scripts/bd-contract.ts`](scripts/bd-contract.ts) checks a real `bd` against everything the plugin relies on: version parsing, `bd where --json`, the `.beads/.local_version` behavior the guard depends on (written by `bd init`, untouched by `bd prime`, refreshed by `bd migrate schema`), and every command the task-agent prompt names. CI runs it against the validated release from `package.json` (`beads.validated`). The scheduled `beads-contract` workflow runs it daily against the latest stable Beads release, and fails if that release breaks the contract or is newer than the validated one. When a new release appears, review its upgrade notes, then update `beads.validated` and the compatibility table. The [artifact policy](docs/beads-artifact-policy.md) records why upstream artifacts are not vendored.
 
 ## Compatibility
 
 | Component | Expected range | Validated baseline |
 | --- | --- | --- |
-| OpenCode | 1.18.3 through 1.x | 1.18.15 |
-| `bd` CLI | 1.0.5 through 1.x | 1.2.2 |
-| Bun | >=1.3.14 | 1.3.14 |
+| OpenCode | 2.0.26 through 2.x | 2.0.26 |
+| `bd` CLI | 1.3.0 through 1.x | 1.3.1 |
+| Bun (OpenCode host runtime) | >=1.3.14 | 1.4.2 |
 
-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.2 at commit `6c124203e771433a3550c348771a5b5e27fd3c21`.
+The adapter type-checks against `@opencode/plugin` 2.0.26 and declares it as an optional peer from 2.0.26 through 2.x; the import is type-only, so OpenCode's own runtime is used. See the [OpenCode V2 contract](docs/opencode-sdk-contract.md). The `bd` baseline was reviewed against Beads v1.3.1 (commit `c1c4b642ac1c08d8c828007a1c2f96e47e43ef7c`).
 
 ## Troubleshooting
 
 - **No Beads context:** Run `bd prime`. Install `bd` if missing or run `bd init` if the project has no Beads workspace.
+- **Agent reports that `bd prime` failed or timed out:** Run `bd prime` in the project to see the error; the plugin retries every 30 seconds.
+- **Agent reports a Beads notice instead of context:** The schema migration guard withheld prime. Back up `.beads`, run `bd migrate schema`, and continue; or upgrade `bd` if the notice says it is older than 1.3.0.
 - **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.
+- **Unexpected definition:** Check OpenCode configuration for a colliding `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.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "0.9.4",
+  "version": "1.0.0",
   "type": "module",
-  "description": "A maintained OpenCode integration for the Beads issue tracker, including context injection, vendored workflows, and a task agent.",
+  "description": "A maintained OpenCode V2 integration for the Beads issue tracker: bd prime context injection with a schema-migration guard, and a bounded task agent.",
   "author": "Matt Jackson",
   "contributors": [
     {
@@ -35,11 +35,14 @@
     ".": {
       "types": "./src/plugin.ts",
       "import": "./src/plugin.ts"
+    },
+    "./server": {
+      "types": "./src/plugin.ts",
+      "import": "./src/plugin.ts"
     }
   },
   "files": [
     "src",
-    "vendor",
     "README.md",
     "LICENSE"
   ],
@@ -47,26 +50,24 @@
     "test": "bun test",
     "test:docs": "bun test tests/docs.test.ts",
     "test:package": "bun scripts/test-package.ts",
-    "test:provenance": "bun test tests/provenance.test.ts",
     "test:release": "bun test tests/release.test.ts",
-    "test:vendor": "bun scripts/validate-vendor.ts vendor",
+    "test:bd-contract": "bun scripts/bd-contract.ts",
     "typecheck": "tsc --noEmit"
   },
+  "beads": {
+    "minimum": "1.3.0",
+    "validated": "1.3.1"
+  },
   "peerDependencies": {
-    "@opencode-ai/plugin": ">=1.18.3 <2",
-    "@opencode-ai/sdk": ">=1.18.3 <2"
+    "@opencode/plugin": ">=2.0.26 <3"
   },
   "peerDependenciesMeta": {
-    "@opencode-ai/plugin": {
-      "optional": true
-    },
-    "@opencode-ai/sdk": {
+    "@opencode/plugin": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "1.18.15",
-    "@opencode-ai/sdk": "1.18.15",
+    "@opencode/plugin": "2.0.26",
     "@types/bun": "1.3.4",
     "@types/node": "^22.0.0",
     "typescript": "5.9.3"

package/src/agents.ts

@@ -0,0 +1,82 @@
+import type { Plugin } from "@opencode/plugin";
+import { BEADS_TASK_AGENT_DESCRIPTION, BEADS_TASK_AGENT_PROMPT } from "./guidance";
+
+export const BEADS_TASK_AGENT = "beads-task-agent";
+export const BEADS_TASK_AGENT_LUNA = "beads-task-agent-luna";
+export const BEADS_TASK_AGENTS: ReadonlySet<string> = new Set([
+  BEADS_TASK_AGENT,
+  BEADS_TASK_AGENT_LUNA,
+]);
+
+/** Default hard cap on worker steps; a backstop for "one bead, then return", not a target. */
+export const DEFAULT_TASK_AGENT_STEPS = 100;
+
+/**
+ * Enforce the no-automatic-commit/push/sync policy with OpenCode permissions rather than prompt
+ * text alone. Appended after OpenCode's defaults, so these `ask` rules win; compound commands are
+ * checked per command, so `cd x && git push` is caught too.
+ */
+export const TASK_AGENT_PERMISSIONS = [
+  { action: "shell", resource: "git commit *", effect: "ask" },
+  { action: "shell", resource: "git push *", effect: "ask" },
+  { action: "shell", resource: "bd dolt push *", effect: "ask" },
+  { action: "shell", resource: "bd dolt pull *", effect: "ask" },
+  { action: "shell", resource: "bd sync *", effect: "ask" },
+] as const;
+
+/** Routing for the opt-in Luna profile, `provider/model#variant` in OpenCode terms. */
+export const LUNA_MODEL = { providerID: "openai", id: "gpt-6-luna", variant: "max" } as const;
+
+export interface BeadsAgentDefinition {
+  description: string;
+  system: string;
+  model?: typeof LUNA_MODEL;
+  steps?: number;
+}
+
+export interface BeadsAgentOptions {
+  /** Register the Luna Max profile alongside the default task agent. */
+  luna?: boolean;
+  /** Hard cap on worker steps; 0 removes the cap. */
+  steps?: number;
+}
+
+/** Build the task-agent definitions from plugin options. */
+export function beadsAgents(options: BeadsAgentOptions = {}): Record<string, BeadsAgentDefinition> {
+  const base: BeadsAgentDefinition = {
+    description: BEADS_TASK_AGENT_DESCRIPTION,
+    system: BEADS_TASK_AGENT_PROMPT,
+  };
+  const steps = options.steps ?? DEFAULT_TASK_AGENT_STEPS;
+  if (Number.isInteger(steps) && steps > 0) base.steps = steps;
+  const agents: Record<string, BeadsAgentDefinition> = { [BEADS_TASK_AGENT]: base };
+  if (options.luna) agents[BEADS_TASK_AGENT_LUNA] = { ...base, model: LUNA_MODEL };
+  return agents;
+}
+
+type AgentEditor = Parameters<Parameters<Plugin.Context["agent"]["transform"]>[0]>[0];
+
+/**
+ * Register task agents. `update` creates unknown agents from OpenCode defaults (including the
+ * default permission ruleset); user `agents` config entries still override these fields one by one.
+ */
+export function applyBeadsAgents(
+  editor: AgentEditor,
+  agents: Record<string, BeadsAgentDefinition>
+): void {
+  for (const [id, definition] of Object.entries(agents)) {
+    editor.update(id, (agent) => {
+      // DeepMutable widens branded string IDs into object types; the runtime values are strings.
+      agent.name = id as unknown as typeof agent.name;
+      agent.description = definition.description;
+      agent.system = definition.system;
+      agent.mode = "subagent";
+      if (definition.model) agent.model = { ...definition.model } as unknown as typeof agent.model;
+      if (definition.steps !== undefined) agent.steps = definition.steps;
+      agent.permissions = [
+        ...(agent.permissions ?? []),
+        ...TASK_AGENT_PERMISSIONS.map((rule) => ({ ...rule })),
+      ] as unknown as typeof agent.permissions;
+    });
+  }
+}

package/src/context.ts

@@ -0,0 +1,148 @@
+import { BEADS_TASK_AGENTS } from "./agents";
+import { guardNotice, type GuardResult } from "./guard";
+import { PrimeTimeoutError } from "./prime";
+import { beadsGuidance, primeFailureNotice } from "./guidance";
+
+/** Retry window for withheld or failed context, so model steps do not respawn `bd` each time. */
+export const DEFAULT_CONTEXT_RETRY_MS = 30_000;
+
+/**
+ * Re-run prime when a session resumes after this much inactivity. Claude Code's SessionStart hook
+ * re-primes on resume; OpenCode has no resume event, so an idle gap stands in for it. Continuous
+ * work keeps identical prime text, which keeps provider prompt caches warm.
+ */
+export const DEFAULT_IDLE_REFRESH_MS = 30 * 60_000;
+
+export type AgentMode = "primary" | "subagent" | "all";
+export type ContextAudience = "primary" | "task-agent";
+export type ContextDiagnostic = "agent_lookup_failed" | "prime_failed" | "prime_timeout";
+
+export interface ContextRuntime {
+  guard(directory: string): Promise<GuardResult>;
+  prime(directory: string): Promise<string>;
+  /** Resolve an agent's mode; undefined when the agent is unknown. */
+  agentMode(agentID: string): Promise<AgentMode | undefined>;
+  diagnose?(code: ContextDiagnostic, sessionID: string): void;
+}
+
+export interface ContextControllerOptions {
+  retryMs?: number;
+  /** Refresh prime after this much session inactivity; 0 disables idle refresh. */
+  idleRefreshMs?: number;
+  now?: () => number;
+}
+
+export interface ContextController {
+  /** System text for one model request, or undefined when nothing should be added. */
+  systemFor(sessionID: string, agentID: string): Promise<string | undefined>;
+  /** Refresh prime on the next request, e.g. after compaction changed the session. */
+  invalidate(sessionID: string): void;
+  /** Drop all state for a deleted session. */
+  forget(sessionID: string): void;
+}
+
+type CacheEntry = { value: Promise<string | undefined>; expiresAt?: number; lastUsed: number };
+
+/** Wrap prime output in the envelope and shared guidance for one audience. */
+export function renderBeadsContext(prime: string, audience: ContextAudience): string {
+  return `<beads-context audience="${audience}">\n${prime}\n</beads-context>\n\n${beadsGuidance(audience)}`;
+}
+
+/**
+ * Supply Beads context through the per-request session context hook.
+ *
+ * OpenCode V2 attaches system parts to every model request without storing them, so context
+ * survives compaction on its own. The rendered text is cached per session to keep it stable
+ * across requests; compaction invalidates it so persistent memories can refresh.
+ */
+export function createContextController(
+  runtime: ContextRuntime,
+  directory: string,
+  options: ContextControllerOptions = {}
+): ContextController {
+  const retryMs = options.retryMs ?? DEFAULT_CONTEXT_RETRY_MS;
+  const idleRefreshMs = options.idleRefreshMs ?? DEFAULT_IDLE_REFRESH_MS;
+  const now = options.now ?? Date.now;
+  const cache = new Map<string, CacheEntry>();
+  const modes = new Map<string, Promise<AgentMode | undefined>>();
+
+  async function audienceFor(
+    sessionID: string,
+    agentID: string
+  ): Promise<ContextAudience | undefined> {
+    if (BEADS_TASK_AGENTS.has(agentID)) return "task-agent";
+
+    let pending = modes.get(agentID);
+    if (!pending) {
+      pending = runtime.agentMode(agentID).catch(() => {
+        modes.delete(agentID);
+        runtime.diagnose?.("agent_lookup_failed", sessionID);
+        return undefined;
+      });
+      modes.set(agentID, pending);
+    }
+    // Unknown agents fail open so custom primary agents keep receiving context.
+    return (await pending) === "subagent" ? undefined : "primary";
+  }
+
+  async function load(
+    sessionID: string,
+    audience: ContextAudience,
+    entry: CacheEntry
+  ): Promise<string | undefined> {
+    const retryLater = (value: string | undefined) => {
+      entry.expiresAt = now() + retryMs;
+      return value;
+    };
+
+    let guard: GuardResult;
+    try {
+      guard = await runtime.guard(directory);
+    } catch {
+      return retryLater(undefined);
+    }
+    if (guard.kind !== "ready") return retryLater(guardNotice(guard));
+
+    let output: string;
+    try {
+      output = (await runtime.prime(directory)).trim();
+    } catch (error) {
+      const timedOut = error instanceof PrimeTimeoutError;
+      runtime.diagnose?.(timedOut ? "prime_timeout" : "prime_failed", sessionID);
+      return retryLater(primeFailureNotice(timedOut ? "timed out" : "failed"));
+    }
+    if (!output) return retryLater(undefined);
+    return renderBeadsContext(output, audience);
+  }
+
+  function dropSession(sessionID: string): void {
+    for (const key of cache.keys()) {
+      if (key.startsWith(`${sessionID}\0`)) cache.delete(key);
+    }
+  }
+
+  return {
+    async systemFor(sessionID, agentID) {
+      const audience = await audienceFor(sessionID, agentID);
+      if (!audience) return undefined;
+
+      const key = `${sessionID}\0${audience}`;
+      const current = now();
+      const cached = cache.get(key);
+      const fresh = cached && (cached.expiresAt === undefined || cached.expiresAt > current);
+      const resumed = cached && idleRefreshMs > 0 && current - cached.lastUsed > idleRefreshMs;
+      if (cached && fresh && !resumed) {
+        cached.lastUsed = current;
+        return cached.value;
+      }
+
+      const entry: CacheEntry = { value: Promise.resolve(undefined), lastUsed: current };
+      entry.value = load(sessionID, audience, entry);
+      cache.set(key, entry);
+      return entry.value;
+    },
+
+    invalidate: dropSession,
+    forget: dropSession,
+  };
+}

package/src/guard.ts

@@ -0,0 +1,138 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Oldest Beads release this adapter supports. */
+export const MINIMUM_BD_VERSION = "1.3.0";
+
+export type Version = readonly [number, number, number];
+
+/** Outcome of checking whether automatic `bd prime` may open the project store. */
+export type GuardResult =
+  | { kind: "ready" }
+  | { kind: "uninitialized" }
+  | { kind: "unavailable" }
+  | { kind: "unsupported"; installed: string }
+  | { kind: "migration-pending"; installed: string; store: string | undefined };
+
+export interface GuardRuntime {
+  /** Run `bd` with arguments in the project directory and return stdout. */
+  bd(directory: string, args: readonly string[]): Promise<string>;
+  /** Read a UTF-8 file, resolving undefined when it does not exist. */
+  readText(path: string): Promise<string | undefined>;
+}
+
+export interface GuardOptions {
+  /** Let automatic prime apply pending schema migrations instead of withholding context. */
+  autoMigrate?: boolean;
+}
+
+/** Parse the leading `major.minor.patch` triple; pre-release suffixes are ignored. */
+export function parseVersion(text: string): Version | undefined {
+  const match = text.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return undefined;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/** Compare two parsed versions; negative when `left` is older. */
+export function compareVersions(left: Version, right: Version): number {
+  for (let index = 0; index < 3; index++) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+function formatVersion(version: Version): string {
+  return version.join(".");
+}
+
+async function readTextIfPresent(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * Decide whether automatic `bd prime` is safe without opening the store.
+ *
+ * Beads 1.3+ migrates an embedded store in place, irreversibly, on the first command that opens
+ * it, and `--readonly` does not prevent that. `bd version` and `bd where --json` do not open the
+ * store. `.beads/.local_version` records the newest binary that opened the store through an
+ * ordinary command (but not `bd prime`), so an older or missing value means a migration may be
+ * pending. `bd migrate schema` is idempotent and updates it, clearing a stale marker.
+ */
+export async function checkBeadsStore(
+  directory: string,
+  runtime: GuardRuntime,
+  options: GuardOptions = {}
+): Promise<GuardResult> {
+  let installedOutput: string;
+  try {
+    installedOutput = await runtime.bd(directory, ["version"]);
+  } catch {
+    return { kind: "unavailable" };
+  }
+  const installed = parseVersion(installedOutput);
+  if (!installed) return { kind: "unavailable" };
+  const minimum = parseVersion(MINIMUM_BD_VERSION) as Version;
+  if (compareVersions(installed, minimum) < 0) {
+    return { kind: "unsupported", installed: formatVersion(installed) };
+  }
+
+  let location: unknown;
+  try {
+    location = JSON.parse(await runtime.bd(directory, ["where", "--json"]));
+  } catch {
+    // `bd where` exits non-zero without a workspace; treat every failure as no usable store.
+    return { kind: "uninitialized" };
+  }
+  const beadsPath =
+    typeof location === "object" && location !== null && "path" in location
+      ? (location as { path: unknown }).path
+      : undefined;
+  if (typeof beadsPath !== "string" || !beadsPath) return { kind: "uninitialized" };
+
+  if (options.autoMigrate) return { kind: "ready" };
+
+  let marker: string | undefined;
+  try {
+    marker = await runtime.readText(join(beadsPath, ".local_version"));
+  } catch {
+    marker = undefined;
+  }
+  const store = marker === undefined ? undefined : parseVersion(marker);
+  if (!store || compareVersions(store, installed) < 0) {
+    return {
+      kind: "migration-pending",
+      installed: formatVersion(installed),
+      store: store ? formatVersion(store) : undefined,
+    };
+  }
+  return { kind: "ready" };
+}
+
+/** Build the guard runtime from a bounded `bd` runner and the local filesystem. */
+export function createGuardRuntime(bd: GuardRuntime["bd"]): GuardRuntime {
+  return { bd, readText: readTextIfPresent };
+}
+
+/** Explain withheld context to the agent so it neither migrates the store nor guesses. */
+export function guardNotice(result: GuardResult): string | undefined {
+  switch (result.kind) {
+    case "unsupported":
+      return `<beads-notice>
+Beads workflow context was not loaded: the installed bd ${result.installed} is older than ${MINIMUM_BD_VERSION}, the minimum this OpenCode integration supports. Tell the user to upgrade bd before relying on Beads in this session.
+</beads-notice>`;
+    case "migration-pending": {
+      const store = result.store ? `bd ${result.store}` : "an unknown bd version";
+      return `<beads-notice>
+Beads workflow context was withheld: this project's Beads store was last opened by ${store}, and the installed bd ${result.installed} may apply irreversible schema migrations on first use. Do not run bd commands in this session. Tell the user to back up the .beads directory and then run \`bd migrate schema\`, or to set the opencode-beads plugin option "autoMigrate": true to allow automatic migration.
+</beads-notice>`;
+    }
+    default:
+      return undefined;
+  }
+}