opencode-beads 0.5.4 → 0.6.0

package/README.md

@@ -33,7 +33,7 @@ Optionally, pin to a specific version for stability:
 
 ```json
 {
-  "plugin": ["opencode-beads@0.5.4"]
+  "plugin": ["opencode-beads@0.6.0"]
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-beads",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "type": "module",
   "description": "A plugin for OpenCode that provides integration with the beads issue tracker.",
   "author": "Josh Thomas <josh@joshthomas.dev>",

package/src/plugin.ts

@@ -14,6 +14,9 @@ import { BEADS_GUIDANCE, loadAgent, loadCommands } from "./vendor";
 
 type OpencodeClient = PluginInput["client"];
 
+/** Name of the plugin's own task agent. Always receives beads context. */
+const BEADS_TASK_AGENT = "beads-task-agent";
+
 /**
  * Get the current model/agent context for a session by querying messages.
  *
@@ -94,6 +97,34 @@ export const BeadsPlugin: Plugin = async ({ client, $ }) => {
 
   const injectedSessions = new Set<string>();
 
+  /**
+   * Check if an agent should receive beads context injection.
+   *
+   * Queries the agent list from OpenCode and checks whether the agent is a
+   * subagent. Subagents (like `explore` and `general`) are invoked for
+   * specific tasks and shouldn't be polluted with beads context — it wastes
+   * tokens and can cause them to attempt pointless bd/git operations.
+   *
+   * Primary agents (`build`, `plan`) are user-facing and benefit from issue
+   * awareness. The plugin's own `beads-task-agent` is an explicit exception.
+   *
+   * Queries fresh each time rather than caching, since agents can change
+   * mid-session (config edits, other plugins). This only runs once per
+   * session (gated by injectedSessions), so the overhead is negligible.
+   */
+  async function shouldInject(agentName: string | undefined): Promise<boolean> {
+    if (!agentName || agentName === BEADS_TASK_AGENT) return true;
+
+    const response = await client.app.agents().catch(() => undefined);
+    const agent = response?.data?.find((a) => a.name === agentName);
+    if (agent) {
+      return agent.mode === "primary" || agent.mode === "all";
+    }
+
+    // Query failed or agent not in the list — inject as safe fallback
+    return true;
+  }
+
   return {
     "chat.message": async (_input, output) => {
       const sessionID = output.message.sessionID;
@@ -101,6 +132,13 @@ export const BeadsPlugin: Plugin = async ({ client, $ }) => {
       // Skip if already injected this session
       if (injectedSessions.has(sessionID)) return;
 
+      // Skip subagents — they're invoked for specific tasks and shouldn't
+      // waste tokens on beads context (except our own beads-task-agent)
+      if (!(await shouldInject(output.message.agent))) {
+        injectedSessions.add(sessionID);
+        return;
+      }
+
       // Check if beads-context was already injected (handles plugin reload/reconnection)
       try {
         const existing = await client.session.messages({
@@ -140,6 +178,10 @@ export const BeadsPlugin: Plugin = async ({ client, $ }) => {
       if (event.type === "session.compacted") {
         const sessionID = event.properties.sessionID;
         const context = await getSessionContext(client, sessionID);
+
+        // Skip re-injection for subagents
+        if (!(await shouldInject(context?.agent))) return;
+
         await injectBeadsContext(client, $, sessionID, context);
       }
     },

package/vendor/agents/task-agent.md

@@ -13,7 +13,7 @@ You are a task-completion agent for beads. Your goal is to find ready work and c
 
 2. **Claim the Task**
    - Use the `show` tool to get full task details
-   - Use the `update` tool to set status to `in_progress`
+   - Use the `claim` tool for atomic start-work semantics
    - Report what you're working on
 
 3. **Execute the Task**
@@ -39,7 +39,7 @@ You are a task-completion agent for beads. Your goal is to find ready work and c
 
 # Important Guidelines
 
-- Always claim before working (MCP: set status to `in_progress`; CLI: `--claim` for atomic assignee + status) and close when done
+- Always claim before working (MCP: `claim`; CLI: `--claim`) and close when done
 - Link discovered work with `discovered-from` dependencies
 - Don't close issues unless work is actually complete
 - If blocked, use `update` to set status to `blocked` and explain why
@@ -50,6 +50,7 @@ You are a task-completion agent for beads. Your goal is to find ready work and c
 Via beads MCP server:
 - `ready` - Find unblocked tasks
 - `show` - Get task details
+- `claim` - Atomically claim task for work
 - `update` - Update task status/fields
 - `create` - Create new issues
 - `dep` - Manage dependencies

package/vendor/commands/audit.md

@@ -23,6 +23,6 @@ Each line is one event. Labeling is done by appending a new `"label"` event refe
 ## Notes
 
 - Audit entries are **append-only** (no in-place edits).
-- `bd sync` includes `.beads/interactions.jsonl` in the commit allowlist (like `issues.jsonl`).
+- `bd dolt push` includes `.beads/interactions.jsonl` in the commit allowlist.
 
 

package/vendor/commands/export.md

@@ -13,12 +13,9 @@ Export all issues to JSON Lines format (one JSON object per line).
 
 Issues are sorted by ID for consistent diffs, making git diffs readable.
 
-## Automatic Export
+## When to Use
 
-The Dolt server automatically exports to `.beads/issues.jsonl` after any CRUD operation (5-second debounce). Manual export is rarely needed unless you need a custom output location or filtered export.
-
-Export is used for:
-- Git version control
-- Backup
-- Sharing issues between repositories
-- Data migration
+Dolt is the primary storage backend, so manual export is rarely needed. Use `bd export` when you need:
+- A JSONL snapshot for backup
+- Data migration to another system
+- Sharing issues outside the Dolt workflow

package/vendor/commands/import.md

@@ -1,36 +1,18 @@
 ---
-description: Import issues from JSONL format
-argument-hint: [-i input-file]
+description: Import issues from JSONL format (removed)
+argument-hint: (removed)
 ---
 
-Import issues from JSON Lines format (one JSON object per line).
+`bd import` has been **removed**.
 
-## Usage
+## Migration
 
-- **From stdin**: `bd import` (reads from stdin)
-- **From file**: `bd import -i issues.jsonl`
-- **Preview**: `bd import -i issues.jsonl --dry-run`
-
-## Behavior
-
-- **Existing issues** (same ID): Updated with new data
-- **New issues**: Created
-- **Same-ID scenarios**: With hash-based IDs (v0.20.1+), same ID = same issue being updated (not a collision)
-
-## Preview Changes
-
-Use `--dry-run` to see what will change before importing:
+If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag:
 
 ```bash
-bd import -i issues.jsonl --dry-run
-# Shows: new issues, updates, exact matches
+bd init <prefix> --from-jsonl issues.jsonl
 ```
 
-## Automatic Import
-
-The Dolt server automatically imports from `.beads/issues.jsonl` when it's newer than the database (e.g., after `git pull`). Manual import is rarely needed.
-
-## Options
+## Note
 
-- **--skip-existing**: Skip updates to existing issues
-- **--strict**: Fail on dependency errors instead of warnings
+Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command.

package/vendor/commands/ready.md

@@ -10,6 +10,6 @@ Call the `ready` tool to get a list of unblocked issues. Then present them to th
 - Priority
 - Issue type
 
-If there are ready tasks, ask the user which one they'd like to work on. If they choose one, use the `update` tool to set its status to `in_progress`.
+If there are ready tasks, ask the user which one they'd like to work on. If they choose one, use the `claim` tool to start work atomically.
 
 If there are no ready tasks, suggest checking `blocked` issues or creating a new issue with the `create` tool.

package/vendor/commands/restore.md

@@ -8,10 +8,9 @@ Restore full history of a compacted issue from git version control.
 When an issue is compacted, the git commit hash is saved. This command:
 
 1. Reads the compacted_at_commit from the database
-2. Checks out that commit temporarily
-3. Reads the full issue from JSONL at that point in history
-4. Displays the full issue history (description, events, etc.)
-5. Returns to the current git state
+2. Retrieves the full issue from Dolt history at that point
+3. Displays the full issue history (description, events, etc.)
+4. Returns to the current state
 
 ## Usage
 

package/vendor/commands/sync.md

@@ -1,54 +1,17 @@
 ---
-description: Synchronize issues with git remote
-argument-hint: [--dry-run] [--message] [--status] [--merge]
+description: Synchronize issues (deprecated — use bd dolt push/pull)
+argument-hint: (deprecated)
 ---
 
-Synchronize issues with git remote in a single operation.
+`bd sync` is **deprecated** and is now a no-op.
 
-## Sync Steps
+## Use Dolt commands instead
 
-1. Export pending changes to JSONL
-2. Commit changes to git
-3. Pull from remote (with conflict resolution)
-4. Import updated JSONL
-5. Push local commits to remote
-
-Wraps the entire git-based sync workflow for multi-device use.
-
-## Usage
-
-- **Basic sync**: `bd sync`
-- **Preview**: `bd sync --dry-run`
-- **Custom message**: `bd sync --message "Closed sprint issues"`
-- **Pull only**: `bd sync --no-push`
-- **Push only**: `bd sync --no-pull`
-- **Flush only**: `bd sync --flush-only` (export to JSONL without git operations)
-- **Import only**: `bd sync --import-only` (import from JSONL without git operations)
-
-## Separate Branch Workflow
-
-When using a separate sync branch (configured via `sync.branch`), additional commands are available:
-
-- **Check status**: `bd sync --status` - Show diff between sync branch and main
-- **Merge to main**: `bd sync --merge` - Merge sync branch back to main branch
-- **Preview merge**: `bd sync --merge --dry-run` - Preview what would be merged
-
-### Merge Workflow
-
-When working with a protected main branch and separate sync branch:
-
-1. Beads commits go to the sync branch (e.g., `beads-metadata`)
-2. Use `bd sync --status` to review pending changes
-3. When ready, use `bd sync --merge` to merge back to main
-4. After merge, run `bd import` to update the database
-5. Run `bd sync` to push changes to remote
-
-The merge command includes safety checks:
-- Verifies you're not on the sync branch
-- Checks for uncommitted changes in working tree
-- Detects and reports merge conflicts with resolution steps
-- Uses `--no-ff` to create a merge commit for clear history
+- **Push to remote**: `bd dolt push`
+- **Pull from remote**: `bd dolt pull`
+- **Commit pending changes**: `bd dolt commit`
+- **Check connection**: `bd dolt show`
 
 ## Note
 
-Most users should rely on the Dolt server's automatic sync (with `dolt.auto-commit` enabled) instead of running manual sync. This command is useful for one-off syncs or when not using the Dolt server.
+Most users should rely on the Dolt server's automatic sync (with `dolt.auto-commit` enabled) instead of running manual sync commands.

package/vendor/commands/workflow.md

@@ -14,7 +14,7 @@ Use `/beads:ready` or the `ready` MCP tool to see tasks with no blockers.
 ## 2. Claim Your Task
 Claim the issue atomically (assignee + `in_progress` in one step):
 - Via command: `/beads:update <id> --claim`
-- Via MCP tool: `update` with `status: "in_progress"`
+- Via MCP tool: `claim` with `issue_id: "<id>"`
 
 ## 3. Work on It
 Implement, test, and document the feature or fix.
@@ -39,8 +39,7 @@ After closing, check if other work became ready:
 - **Priority levels**: 0=critical, 1=high, 2=medium, 3=low, 4=backlog
 - **Issue types**: bug, feature, task, epic, chore
 - **Dependencies**: Use `blocks` for hard dependencies, `related` for soft links
-- **Auto-sync**: Changes automatically export to `.beads/issues.jsonl` (5-second debounce)
-- **Git workflow**: After `git pull`, JSONL auto-imports if newer than DB
+- **Auto-sync**: Changes are stored in Dolt and synced via `bd dolt push` / `bd dolt pull`
 
 ## Available Commands
 - `/beads:ready` - Find unblocked work
@@ -52,7 +51,7 @@ After closing, check if other work became ready:
 
 ## MCP Tools Available
 Use these via the beads MCP server:
-- `ready`, `list`, `show`, `create`, `update`, `close`
+- `ready`, `list`, `show`, `create`, `claim`, `update`, `close`
 - `dep` (manage dependencies), `blocked`, `stats`
 - `init` (initialize bd in a project)