@snarkipus/opencode-beads 0.10.0 → 1.0.1

package/README.md

@@ -1,10 +1,15 @@
 # opencode-beads
 
+[![CI](https://github.com/snarkipus/opencode-beads/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/snarkipus/opencode-beads/actions/workflows/ci.yml)
+[![Release](https://github.com/snarkipus/opencode-beads/actions/workflows/release.yml/badge.svg)](https://github.com/snarkipus/opencode-beads/actions/workflows/release.yml)
+[![npm](https://img.shields.io/npm/v/@snarkipus/opencode-beads)](https://www.npmjs.com/package/@snarkipus/opencode-beads)
+[![zizmor](https://img.shields.io/badge/%F0%9F%8C%88-zizmor-white?labelColor=white)](https://zizmor.sh/)
+
 [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 gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent that completes one Bead per invocation. 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.
+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. It vendors nothing from upstream Beads; instead, every Beads release is checked against the `bd` behavior the plugin relies on (see [Tracking upstream Beads](#tracking-upstream-beads)).
 
 ## Design
 
@@ -17,94 +22,151 @@ The plugin's primary design is **context-preserving atomic delegation**:
 
 ## Installation
 
-Install the [`bd` CLI](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md) once on the host, then initialize each project:
+This plugin requires OpenCode 2 and `bd` 1.3.0 or later.
 
-```bash
-git init # only when the directory is not already a Git worktree
-bd init
-```
+1. 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 # 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. 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.
+
+2. Add the version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
 
-`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.
+   ```json
+   {
+     "plugins": ["@snarkipus/opencode-beads@1.0.1"]
+   }
+   ```
 
-Add the version-pinned plugin to `~/.config/opencode/opencode.json`:
+   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.
+
+3. Check the install: `opencode debug agents` lists `beads-task-agent`.
+
+### Plugin options
+
+Plugin options use the object form:
 
 ```json
 {
-  "plugin": ["@snarkipus/opencode-beads@0.10.0"]
+  "plugins": [
+    {
+      "package": "@snarkipus/opencode-beads@1.0.1",
+      "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). |
 
-### 0.9.3 recovery notice
+### Why not `bd setup opencode`
 
-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).
+**Do not run `bd setup opencode`.** That recipe is for OpenCode without this plugin. Beads assumes OpenCode has no hooks, so it replaces `bd init`'s 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 the Beads section from `AGENTS.md` (prime still arrives through the plugin), or simply leave it: while prime is attached, the plugin replaces it in the request with a one-line pointer.
+
+### Parity with `bd setup claude`
+
+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 and on resume after an idle gap |
+| 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/opencode.json` `plugins` entry |
+| `--stealth` | `stealth` plugin option |
+| `--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.
 
 ## 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.
+
+While prime is attached, two bd-managed `AGENTS.md` blocks only repeat it: the full-profile section `bd setup opencode` writes, and the Codex section `bd init` writes. 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. `bd init`'s minimal section is left as is. Your `AGENTS.md` file and any text outside those markers are not changed, and nothing is replaced when prime is withheld or unavailable.
 
 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.
 
-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.
+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.
+
+## Schema migration guard
 
-## Commands
+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`.
 
-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.
+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.
 
-Explicit command definitions in OpenCode configuration replace plugin commands with the same name. Task-agent overrides merge field-by-field over plugin defaults, so a partial override does not discard the bounded prompt or subagent mode. Explicit fields (including `prompt`, `permission`, `tools`, `model`, `variant`, and `disable`) win; nested fields are replaced, not deep-merged. Conflicting `beads:*` commands or either named task-agent profile produce a grouped, rate-limited warning without preventing definitions from loading. An empty profile opt-in does not warn.
+`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 slash commands; `bd setup claude` installs none either. Ask the agent to work with Beads, have it load the canonical `beads` skill that `bd init` installs at `.agents/skills/beads` (OpenCode lists it and loads it with its `skill` tool), or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly. Versions before 1.0.0 shipped `/beads:*` commands adapted from upstream's Claude Code plugin; they duplicated `bd prime` and the skill.
+
+## 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 cannot detect or warn 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 owned by this project. Upstream Beads ships a task agent only in its Claude Code marketplace plugin, as an autonomous multi-task loop; this adapter deliberately keeps the bounded one-Bead contract instead.
 
-### Opt-in Luna Max profile
-
-The default `beads-task-agent` leaves model and reasoning variant unset, preserving OpenCode's caller inheritance. To add the named Luna Max profile, merge this entry into your project `opencode.json` alongside the plugin entry:
+OpenCode lets the plugin enforce parts of that contract, beyond what Claude Code's hooks can do:
 
-```json
-{
-  "agent": {
-    "beads-task-agent-luna": {}
-  }
-}
-```
+- **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.
 
-The plugin fills this profile with `model: "openai/gpt-5.6-luna"` and `variant: "max"`, using exactly the same shared prompt, subagent mode, and inherited permissions/tools as the vanilla agent. Per-agent overrides remain independent: customizations to `beads-task-agent` are not copied to Luna. Both profiles get full prime context at startup and after compaction and retain the same exact-one-Bead workflow.
+### Opt-in Luna Max profile
 
-Choose `beads-task-agent-luna` explicitly as the task tool's `subagent_type` (or ask the primary agent to delegate to that name). Default delegation guidance still names `beads-task-agent`; enabling Luna does not reroute existing calls or change the primary agent's model/variant. No extra orchestrator or plugin-specific config file is involved.
+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, step cap, and 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.
 
-Omit the Luna entry from the effective configuration to keep it unregistered; set `"disable": true` inside the entry to disable it using OpenCode's normal agent configuration. To undo the opt-in, remove the entry at its source and restart OpenCode; omission in a child project does not remove an ancestor/global entry. Explicit routing or prompt overrides are honored, so changing those fields opts out of the corresponding profile defaults.
+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-5.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. Native Luna Max routing was verified on OpenCode 1.18.29; the plugin's general compatibility range is not a guarantee that every provider account exposes this model.
+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.
+- **Task agent asks before committing or pushing:** This is intentional; see [Task agent](#task-agent). Approve the command, or set the agent's `permissions` in OpenCode configuration.
+- **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.
 
+## Earlier releases
+
+### 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 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).
+
 ## License
 
 opencode-beads is licensed under the MIT license. See [`LICENSE`](LICENSE).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "0.10.0",
+  "version": "1.0.1",
   "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,
+  };
+}