opencode-swarm-plugin 0.11.3 → 0.12.0

package/.beads/issues.jsonl

@@ -678,6 +678,12 @@
 {"id":"opencode-swarm-plugin-fmkz8.1","title":"Step 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:43.192563-08:00","updated_at":"2025-12-08T11:12:43.285206-08:00","closed_at":"2025-12-08T11:12:43.285206-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fmkz8.1","depends_on_id":"opencode-swarm-plugin-fmkz8","type":"parent-child","created_at":"2025-12-08T11:12:43.192901-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-fmkz8.2","title":"Step 2","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:43.229469-08:00","updated_at":"2025-12-08T11:12:43.340511-08:00","closed_at":"2025-12-08T11:12:43.340511-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fmkz8.2","depends_on_id":"opencode-swarm-plugin-fmkz8","type":"parent-child","created_at":"2025-12-08T11:12:43.229808-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-fmte","title":"Thread link test bead","description":"[thread:test-thread-456]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:14:30.118389-08:00","updated_at":"2025-12-08T08:14:31.757071-08:00","closed_at":"2025-12-08T08:14:31.757071-08:00"}
+{"id":"opencode-swarm-plugin-fn2a3","title":"CLI-based plugin wrapper for OpenCode","description":"Replace broken npm import plugin with thin wrapper that shells out to `swarm tool` CLI. Fixes bun: protocol crash.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-09T12:44:59.286448-08:00","updated_at":"2025-12-09T12:53:22.927803-08:00","closed_at":"2025-12-09T12:53:22.927803-08:00"}
+{"id":"opencode-swarm-plugin-fn2a3.1","title":"Add CLI tool subcommand with JSON interface","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.380582-08:00","updated_at":"2025-12-09T12:48:28.655484-08:00","closed_at":"2025-12-09T12:48:28.655484-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.1","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.381424-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.2","title":"Add file-based session state for Agent Mail","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.452126-08:00","updated_at":"2025-12-09T12:50:05.569927-08:00","closed_at":"2025-12-09T12:50:05.569927-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.2","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.452571-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.3","title":"Create plugin wrapper template generator","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.511026-08:00","updated_at":"2025-12-09T12:52:13.47915-08:00","closed_at":"2025-12-09T12:52:13.47915-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.3","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.511712-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.4","title":"Update setup command to generate new plugin wrapper","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-09T12:44:59.559682-08:00","updated_at":"2025-12-09T12:53:13.282356-08:00","closed_at":"2025-12-09T12:53:13.282356-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.4","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.560036-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-fn2a3.5","title":"Export tool registry from source modules","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-09T12:44:59.609125-08:00","updated_at":"2025-12-09T12:46:18.092813-08:00","closed_at":"2025-12-09T12:46:18.092813-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-fn2a3.5","depends_on_id":"opencode-swarm-plugin-fn2a3","type":"parent-child","created_at":"2025-12-09T12:44:59.609492-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-fo9z","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:53:43.635138-08:00","updated_at":"2025-12-08T07:53:46.190181-08:00","closed_at":"2025-12-08T07:53:46.190181-08:00"}
 {"id":"opencode-swarm-plugin-foht","title":"New feature request","description":"","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-08T11:11:07.341455-08:00","updated_at":"2025-12-08T11:11:10.086863-08:00","closed_at":"2025-12-08T11:11:10.086863-08:00"}
 {"id":"opencode-swarm-plugin-fomf","title":"Limit test bead 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:25.714274-08:00","updated_at":"2025-12-08T11:12:28.097683-08:00","closed_at":"2025-12-08T11:12:28.097683-08:00"}

package/bin/swarm.ts

@@ -457,9 +457,32 @@ async function checkAllDependencies(): Promise<CheckResult[]> {
 // File Templates
 // ============================================================================
 
-const PLUGIN_WRAPPER = `import { SwarmPlugin } from "opencode-swarm-plugin"
+/**
+ * Get the plugin wrapper template
+ *
+ * Reads from examples/plugin-wrapper-template.ts which contains a self-contained
+ * plugin that shells out to the `swarm` CLI for all tool execution.
+ */
+function getPluginWrapper(): string {
+  const templatePath = join(
+    __dirname,
+    "..",
+    "examples",
+    "plugin-wrapper-template.ts",
+  );
+  try {
+    return readFileSync(templatePath, "utf-8");
+  } catch (error) {
+    // Fallback to minimal wrapper if template not found (shouldn't happen in normal install)
+    console.warn(
+      `[swarm] Could not read plugin template from ${templatePath}, using minimal wrapper`,
+    );
+    return `// Minimal fallback - install opencode-swarm-plugin globally for full functionality
+import { SwarmPlugin } from "opencode-swarm-plugin"
 export default SwarmPlugin
 `;
+  }
+}
 
 const SWARM_COMMAND = `---
 description: Decompose task into parallel subtasks and coordinate agents
@@ -961,7 +984,7 @@ async function setup() {
     }
   }
 
-  writeFileSync(pluginPath, PLUGIN_WRAPPER);
+  writeFileSync(pluginPath, getPluginWrapper());
   p.log.success("Plugin: " + pluginPath);
 
   writeFileSync(commandPath, SWARM_COMMAND);
@@ -1180,8 +1203,14 @@ ${cyan("Commands:")}
   swarm config    Show paths to generated config files
   swarm update    Update to latest version
   swarm version   Show version and banner
+  swarm tool      Execute a tool (for plugin wrapper)
   swarm help      Show this help
 
+${cyan("Tool Execution:")}
+  swarm tool --list                    List all available tools
+  swarm tool <name>                    Execute tool with no args
+  swarm tool <name> --json '<args>'    Execute tool with JSON args
+
 ${cyan("Usage in OpenCode:")}
   /swarm "Add user authentication with OAuth"
   @swarm-planner "Decompose this into parallel tasks"
@@ -1202,6 +1231,150 @@ ${dim("Docs: https://github.com/joelhooks/opencode-swarm-plugin")}
   if (updateInfo) showUpdateNotification(updateInfo);
 }
 
+// ============================================================================
+// Tool Execution (for plugin wrapper)
+// ============================================================================
+
+/**
+ * Execute a tool by name with JSON args
+ *
+ * This is the bridge between the plugin wrapper and the actual tool implementations.
+ * The plugin wrapper shells out to `swarm tool <name> --json '<args>'` and this
+ * function executes the tool and returns JSON.
+ *
+ * Exit codes:
+ * - 0: Success
+ * - 1: Tool execution error (error details in JSON output)
+ * - 2: Unknown tool name
+ * - 3: Invalid JSON args
+ */
+async function executeTool(toolName: string, argsJson?: string) {
+  // Lazy import to avoid loading all tools on every CLI invocation
+  const { allTools } = await import("../src/index");
+
+  // Validate tool name
+  if (!(toolName in allTools)) {
+    const availableTools = Object.keys(allTools).sort();
+    console.log(
+      JSON.stringify({
+        success: false,
+        error: {
+          code: "UNKNOWN_TOOL",
+          message: `Unknown tool: ${toolName}`,
+          available_tools: availableTools,
+        },
+      }),
+    );
+    process.exit(2);
+  }
+
+  // Parse args
+  let args: Record<string, unknown> = {};
+  if (argsJson) {
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      console.log(
+        JSON.stringify({
+          success: false,
+          error: {
+            code: "INVALID_JSON",
+            message: `Invalid JSON args: ${e instanceof Error ? e.message : String(e)}`,
+            raw_input: argsJson.slice(0, 200),
+          },
+        }),
+      );
+      process.exit(3);
+    }
+  }
+
+  // Create mock context for tools that need sessionID
+  // This mimics what OpenCode provides to plugins
+  const mockContext = {
+    sessionID: process.env.OPENCODE_SESSION_ID || `cli-${Date.now()}`,
+    messageID: process.env.OPENCODE_MESSAGE_ID || `msg-${Date.now()}`,
+    agent: process.env.OPENCODE_AGENT || "cli",
+    abort: new AbortController().signal,
+  };
+
+  // Get the tool
+  const toolDef = allTools[toolName as keyof typeof allTools];
+
+  // Execute tool
+  // Note: We cast args to any because the CLI accepts arbitrary JSON
+  // The tool's internal Zod validation will catch type errors
+  try {
+    const result = await toolDef.execute(args as any, mockContext);
+
+    // If result is already valid JSON, try to parse and re-wrap it
+    // Otherwise wrap the string result
+    try {
+      const parsed = JSON.parse(result);
+      // If it's already a success/error response, pass through
+      if (typeof parsed === "object" && "success" in parsed) {
+        console.log(JSON.stringify(parsed));
+      } else {
+        console.log(JSON.stringify({ success: true, data: parsed }));
+      }
+    } catch {
+      // Result is a plain string, wrap it
+      console.log(JSON.stringify({ success: true, data: result }));
+    }
+    process.exit(0);
+  } catch (error) {
+    console.log(
+      JSON.stringify({
+        success: false,
+        error: {
+          code: error instanceof Error ? error.name : "TOOL_ERROR",
+          message: error instanceof Error ? error.message : String(error),
+          details:
+            error instanceof Error && "zodError" in error
+              ? (error as { zodError?: unknown }).zodError
+              : undefined,
+        },
+      }),
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * List all available tools
+ */
+async function listTools() {
+  const { allTools } = await import("../src/index");
+  const tools = Object.keys(allTools).sort();
+
+  console.log(yellow(BANNER));
+  console.log(dim("  " + TAGLINE + " v" + VERSION));
+  console.log();
+  console.log(cyan("Available tools:") + ` (${tools.length} total)`);
+  console.log();
+
+  // Group by prefix
+  const groups: Record<string, string[]> = {};
+  for (const tool of tools) {
+    const prefix = tool.split("_")[0];
+    if (!groups[prefix]) groups[prefix] = [];
+    groups[prefix].push(tool);
+  }
+
+  for (const [prefix, toolList] of Object.entries(groups)) {
+    console.log(green(`  ${prefix}:`));
+    for (const t of toolList) {
+      console.log(`    ${t}`);
+    }
+    console.log();
+  }
+
+  console.log(dim("Usage: swarm tool <name> [--json '<args>']"));
+  console.log(dim("Example: swarm tool beads_ready"));
+  console.log(
+    dim('Example: swarm tool beads_create --json \'{"title": "Fix bug"}\''),
+  );
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -1224,6 +1397,19 @@ switch (command) {
   case "update":
     await update();
     break;
+  case "tool": {
+    const toolName = process.argv[3];
+    if (!toolName || toolName === "--list" || toolName === "-l") {
+      await listTools();
+    } else {
+      // Look for --json flag
+      const jsonFlagIndex = process.argv.indexOf("--json");
+      const argsJson =
+        jsonFlagIndex !== -1 ? process.argv[jsonFlagIndex + 1] : undefined;
+      await executeTool(toolName, argsJson);
+    }
+    break;
+  }
   case "version":
   case "--version":
   case "-v":

package/dist/index.js

@@ -22590,6 +22590,15 @@ async function getRateLimiter() {
 }
 
 // src/agent-mail.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  writeFileSync,
+  unlinkSync
+} from "fs";
+import { join as join2 } from "path";
+import { tmpdir } from "os";
 var AGENT_MAIL_URL = "http://127.0.0.1:8765";
 var DEFAULT_TTL_SECONDS = 3600;
 var MAX_INBOX_LIMIT = 5;
@@ -22605,6 +22614,34 @@ var RECOVERY_CONFIG = {
   restartCooldownMs: 30000,
   enabled: process.env.OPENCODE_AGENT_MAIL_AUTO_RESTART !== "false"
 };
+var SESSION_STATE_DIR = process.env.SWARM_STATE_DIR || join2(tmpdir(), "swarm-sessions");
+function getSessionStatePath(sessionID) {
+  const safeID = sessionID.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join2(SESSION_STATE_DIR, `${safeID}.json`);
+}
+function loadSessionState(sessionID) {
+  const path = getSessionStatePath(sessionID);
+  try {
+    if (existsSync2(path)) {
+      const data = readFileSync(path, "utf-8");
+      return JSON.parse(data);
+    }
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not load session state: ${error45}`);
+  }
+  return null;
+}
+function saveSessionState(sessionID, state) {
+  try {
+    if (!existsSync2(SESSION_STATE_DIR)) {
+      mkdirSync2(SESSION_STATE_DIR, { recursive: true });
+    }
+    const path = getSessionStatePath(sessionID);
+    writeFileSync(path, JSON.stringify(state, null, 2));
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not save session state: ${error45}`);
+  }
+}
 var sessionStates = new Map;
 
 class AgentMailError extends Error {
@@ -22908,7 +22945,13 @@ async function mcpCall(toolName, args) {
   throw lastError || new Error("Unknown error in mcpCall");
 }
 function requireState(sessionID) {
-  const state = sessionStates.get(sessionID);
+  let state = sessionStates.get(sessionID);
+  if (!state) {
+    state = loadSessionState(sessionID) ?? undefined;
+    if (state) {
+      sessionStates.set(sessionID, state);
+    }
+  }
   if (!state) {
     throw new AgentMailNotInitializedError;
   }
@@ -22916,6 +22959,7 @@ function requireState(sessionID) {
 }
 function setState(sessionID, state) {
   sessionStates.set(sessionID, state);
+  saveSessionState(sessionID, state);
 }
 var agentmail_init = tool({
   description: "Initialize Agent Mail session (ensure project + register agent)",
@@ -25554,6 +25598,12 @@ var SwarmPlugin = async (input) => {
   };
 };
 var src_default = SwarmPlugin;
+var allTools = {
+  ...beadsTools,
+  ...agentMailTools,
+  ...structuredTools,
+  ...swarmTools
+};
 export {
   withToolFallback,
   warnMissingTool,
@@ -25592,6 +25642,7 @@ export {
   beads_create,
   beads_close,
   beadsTools,
+  allTools,
   agentMailTools,
   WeightedEvaluationSchema,
   WeightedCriterionEvaluationSchema,

package/dist/plugin.js

@@ -22564,6 +22564,15 @@ async function getRateLimiter() {
 }
 
 // src/agent-mail.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  writeFileSync,
+  unlinkSync
+} from "fs";
+import { join as join2 } from "path";
+import { tmpdir } from "os";
 var AGENT_MAIL_URL = "http://127.0.0.1:8765";
 var DEFAULT_TTL_SECONDS = 3600;
 var MAX_INBOX_LIMIT = 5;
@@ -22579,6 +22588,34 @@ var RECOVERY_CONFIG = {
   restartCooldownMs: 30000,
   enabled: process.env.OPENCODE_AGENT_MAIL_AUTO_RESTART !== "false"
 };
+var SESSION_STATE_DIR = process.env.SWARM_STATE_DIR || join2(tmpdir(), "swarm-sessions");
+function getSessionStatePath(sessionID) {
+  const safeID = sessionID.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join2(SESSION_STATE_DIR, `${safeID}.json`);
+}
+function loadSessionState(sessionID) {
+  const path = getSessionStatePath(sessionID);
+  try {
+    if (existsSync2(path)) {
+      const data = readFileSync(path, "utf-8");
+      return JSON.parse(data);
+    }
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not load session state: ${error45}`);
+  }
+  return null;
+}
+function saveSessionState(sessionID, state) {
+  try {
+    if (!existsSync2(SESSION_STATE_DIR)) {
+      mkdirSync2(SESSION_STATE_DIR, { recursive: true });
+    }
+    const path = getSessionStatePath(sessionID);
+    writeFileSync(path, JSON.stringify(state, null, 2));
+  } catch (error45) {
+    console.warn(`[agent-mail] Could not save session state: ${error45}`);
+  }
+}
 var sessionStates = new Map;
 
 class AgentMailError extends Error {
@@ -22882,7 +22919,13 @@ async function mcpCall(toolName, args) {
   throw lastError || new Error("Unknown error in mcpCall");
 }
 function requireState(sessionID) {
-  const state = sessionStates.get(sessionID);
+  let state = sessionStates.get(sessionID);
+  if (!state) {
+    state = loadSessionState(sessionID) ?? undefined;
+    if (state) {
+      sessionStates.set(sessionID, state);
+    }
+  }
   if (!state) {
     throw new AgentMailNotInitializedError;
   }
@@ -22890,6 +22933,7 @@ function requireState(sessionID) {
 }
 function setState(sessionID, state) {
   sessionStates.set(sessionID, state);
+  saveSessionState(sessionID, state);
 }
 var agentmail_init = tool({
   description: "Initialize Agent Mail session (ensure project + register agent)",
@@ -25203,6 +25247,12 @@ var SwarmPlugin = async (input) => {
     }
   };
 };
+var allTools = {
+  ...beadsTools,
+  ...agentMailTools,
+  ...structuredTools,
+  ...swarmTools
+};
 export {
   SwarmPlugin
 };

package/examples/plugin-wrapper-template.ts

@@ -0,0 +1,723 @@
+/**
+ * OpenCode Swarm Plugin Wrapper
+ *
+ * This is a thin wrapper that shells out to the `swarm` CLI for all tool execution.
+ * Generated by: swarm setup
+ *
+ * The plugin only depends on @opencode-ai/plugin (provided by OpenCode).
+ * All tool logic lives in the npm package - this just bridges to it.
+ *
+ * Environment variables:
+ * - OPENCODE_SESSION_ID: Passed to CLI for session state persistence
+ * - OPENCODE_MESSAGE_ID: Passed to CLI for context
+ * - OPENCODE_AGENT: Passed to CLI for context
+ */
+import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { spawn } from "child_process";
+
+const SWARM_CLI = "swarm";
+
+// =============================================================================
+// CLI Execution Helper
+// =============================================================================
+
+/**
+ * Execute a swarm tool via CLI
+ *
+ * Spawns `swarm tool <name> --json '<args>'` and returns the result.
+ * Passes session context via environment variables.
+ */
+async function execTool(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: { sessionID: string; messageID: string; agent: string },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const hasArgs = Object.keys(args).length > 0;
+    const cliArgs = hasArgs
+      ? ["tool", name, "--json", JSON.stringify(args)]
+      : ["tool", name];
+
+    const proc = spawn(SWARM_CLI, cliArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        OPENCODE_SESSION_ID: ctx.sessionID,
+        OPENCODE_MESSAGE_ID: ctx.messageID,
+        OPENCODE_AGENT: ctx.agent,
+      },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data;
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data;
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        // Success - return the JSON output
+        try {
+          const result = JSON.parse(stdout);
+          if (result.success && result.data !== undefined) {
+            // Unwrap the data for cleaner tool output
+            resolve(
+              typeof result.data === "string"
+                ? result.data
+                : JSON.stringify(result.data, null, 2),
+            );
+          } else if (!result.success && result.error) {
+            // Tool returned an error in JSON format
+            reject(new Error(result.error.message || "Tool execution failed"));
+          } else {
+            resolve(stdout);
+          }
+        } catch {
+          resolve(stdout);
+        }
+      } else if (code === 2) {
+        reject(new Error(`Unknown tool: ${name}`));
+      } else if (code === 3) {
+        reject(new Error(`Invalid JSON args: ${stderr}`));
+      } else {
+        // Tool returned error
+        try {
+          const result = JSON.parse(stdout);
+          if (!result.success && result.error) {
+            reject(
+              new Error(
+                result.error.message || `Tool failed with code ${code}`,
+              ),
+            );
+          } else {
+            reject(
+              new Error(stderr || stdout || `Tool failed with code ${code}`),
+            );
+          }
+        } catch {
+          reject(
+            new Error(stderr || stdout || `Tool failed with code ${code}`),
+          );
+        }
+      }
+    });
+
+    proc.on("error", (err) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        reject(
+          new Error(
+            `swarm CLI not found. Install with: npm install -g opencode-swarm-plugin`,
+          ),
+        );
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+// =============================================================================
+// Beads Tools
+// =============================================================================
+
+const beads_create = tool({
+  description: "Create a new bead with type-safe validation",
+  args: {
+    title: tool.schema.string().describe("Bead title"),
+    type: tool.schema
+      .enum(["bug", "feature", "task", "epic", "chore"])
+      .optional()
+      .describe("Issue type (default: task)"),
+    priority: tool.schema
+      .number()
+      .min(0)
+      .max(3)
+      .optional()
+      .describe("Priority 0-3 (default: 2)"),
+    description: tool.schema.string().optional().describe("Bead description"),
+    parent_id: tool.schema
+      .string()
+      .optional()
+      .describe("Parent bead ID for epic children"),
+  },
+  execute: (args, ctx) => execTool("beads_create", args, ctx),
+});
+
+const beads_create_epic = tool({
+  description: "Create epic with subtasks in one atomic operation",
+  args: {
+    epic_title: tool.schema.string().describe("Epic title"),
+    epic_description: tool.schema
+      .string()
+      .optional()
+      .describe("Epic description"),
+    subtasks: tool.schema
+      .array(
+        tool.schema.object({
+          title: tool.schema.string(),
+          priority: tool.schema.number().min(0).max(3).optional(),
+          files: tool.schema.array(tool.schema.string()).optional(),
+        }),
+      )
+      .describe("Subtasks to create under the epic"),
+  },
+  execute: (args, ctx) => execTool("beads_create_epic", args, ctx),
+});
+
+const beads_query = tool({
+  description: "Query beads with filters (replaces bd list, bd ready, bd wip)",
+  args: {
+    status: tool.schema
+      .enum(["open", "in_progress", "blocked", "closed"])
+      .optional()
+      .describe("Filter by status"),
+    type: tool.schema
+      .enum(["bug", "feature", "task", "epic", "chore"])
+      .optional()
+      .describe("Filter by type"),
+    ready: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only show unblocked beads"),
+    limit: tool.schema
+      .number()
+      .optional()
+      .describe("Max results (default: 20)"),
+  },
+  execute: (args, ctx) => execTool("beads_query", args, ctx),
+});
+
+const beads_update = tool({
+  description: "Update bead status/description",
+  args: {
+    id: tool.schema.string().describe("Bead ID"),
+    status: tool.schema
+      .enum(["open", "in_progress", "blocked", "closed"])
+      .optional()
+      .describe("New status"),
+    description: tool.schema.string().optional().describe("New description"),
+    priority: tool.schema
+      .number()
+      .min(0)
+      .max(3)
+      .optional()
+      .describe("New priority"),
+  },
+  execute: (args, ctx) => execTool("beads_update", args, ctx),
+});
+
+const beads_close = tool({
+  description: "Close a bead with reason",
+  args: {
+    id: tool.schema.string().describe("Bead ID"),
+    reason: tool.schema.string().describe("Completion reason"),
+  },
+  execute: (args, ctx) => execTool("beads_close", args, ctx),
+});
+
+const beads_start = tool({
+  description: "Mark a bead as in-progress",
+  args: {
+    id: tool.schema.string().describe("Bead ID"),
+  },
+  execute: (args, ctx) => execTool("beads_start", args, ctx),
+});
+
+const beads_ready = tool({
+  description: "Get the next ready bead (unblocked, highest priority)",
+  args: {},
+  execute: (args, ctx) => execTool("beads_ready", args, ctx),
+});
+
+const beads_sync = tool({
+  description: "Sync beads to git and push (MANDATORY at session end)",
+  args: {
+    auto_pull: tool.schema.boolean().optional().describe("Pull before sync"),
+  },
+  execute: (args, ctx) => execTool("beads_sync", args, ctx),
+});
+
+const beads_link_thread = tool({
+  description: "Add metadata linking bead to Agent Mail thread",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    thread_id: tool.schema.string().describe("Agent Mail thread ID"),
+  },
+  execute: (args, ctx) => execTool("beads_link_thread", args, ctx),
+});
+
+// =============================================================================
+// Agent Mail Tools
+// =============================================================================
+
+const agentmail_init = tool({
+  description: "Initialize Agent Mail session",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to the project"),
+    agent_name: tool.schema.string().optional().describe("Custom agent name"),
+    task_description: tool.schema
+      .string()
+      .optional()
+      .describe("Task description"),
+  },
+  execute: (args, ctx) => execTool("agentmail_init", args, ctx),
+});
+
+const agentmail_send = tool({
+  description: "Send message to other agents",
+  args: {
+    to: tool.schema
+      .array(tool.schema.string())
+      .describe("Recipient agent names"),
+    subject: tool.schema.string().describe("Message subject"),
+    body: tool.schema.string().describe("Message body"),
+    thread_id: tool.schema
+      .string()
+      .optional()
+      .describe("Thread ID for grouping"),
+    importance: tool.schema
+      .enum(["low", "normal", "high", "urgent"])
+      .optional()
+      .describe("Message importance"),
+    ack_required: tool.schema
+      .boolean()
+      .optional()
+      .describe("Require acknowledgment"),
+  },
+  execute: (args, ctx) => execTool("agentmail_send", args, ctx),
+});
+
+const agentmail_inbox = tool({
+  description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, limit 5)",
+  args: {
+    limit: tool.schema
+      .number()
+      .max(5)
+      .optional()
+      .describe("Max messages (max 5)"),
+    urgent_only: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only urgent messages"),
+    since_ts: tool.schema
+      .string()
+      .optional()
+      .describe("Messages since timestamp"),
+  },
+  execute: (args, ctx) => execTool("agentmail_inbox", args, ctx),
+});
+
+const agentmail_read_message = tool({
+  description: "Fetch ONE message body by ID",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("agentmail_read_message", args, ctx),
+});
+
+const agentmail_summarize_thread = tool({
+  description: "Summarize thread (PREFERRED over fetching all messages)",
+  args: {
+    thread_id: tool.schema.string().describe("Thread ID"),
+    include_examples: tool.schema
+      .boolean()
+      .optional()
+      .describe("Include example messages"),
+  },
+  execute: (args, ctx) => execTool("agentmail_summarize_thread", args, ctx),
+});
+
+const agentmail_reserve = tool({
+  description: "Reserve file paths for exclusive editing",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .describe("File paths/patterns"),
+    ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
+    exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
+    reason: tool.schema.string().optional().describe("Reservation reason"),
+  },
+  execute: (args, ctx) => execTool("agentmail_reserve", args, ctx),
+});
+
+const agentmail_release = tool({
+  description: "Release file reservations",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Paths to release"),
+    reservation_ids: tool.schema
+      .array(tool.schema.number())
+      .optional()
+      .describe("Reservation IDs"),
+  },
+  execute: (args, ctx) => execTool("agentmail_release", args, ctx),
+});
+
+const agentmail_ack = tool({
+  description: "Acknowledge a message",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("agentmail_ack", args, ctx),
+});
+
+const agentmail_search = tool({
+  description: "Search messages by keyword",
+  args: {
+    query: tool.schema.string().describe("Search query"),
+    limit: tool.schema.number().optional().describe("Max results"),
+  },
+  execute: (args, ctx) => execTool("agentmail_search", args, ctx),
+});
+
+const agentmail_health = tool({
+  description: "Check if Agent Mail server is running",
+  args: {},
+  execute: (args, ctx) => execTool("agentmail_health", args, ctx),
+});
+
+// =============================================================================
+// Structured Tools
+// =============================================================================
+
+const structured_extract_json = tool({
+  description: "Extract JSON from markdown/text response",
+  args: {
+    text: tool.schema.string().describe("Text containing JSON"),
+  },
+  execute: (args, ctx) => execTool("structured_extract_json", args, ctx),
+});
+
+const structured_validate = tool({
+  description: "Validate agent response against a schema",
+  args: {
+    response: tool.schema.string().describe("Agent response to validate"),
+    schema_name: tool.schema
+      .enum(["evaluation", "task_decomposition", "bead_tree"])
+      .describe("Schema to validate against"),
+    max_retries: tool.schema
+      .number()
+      .min(1)
+      .max(5)
+      .optional()
+      .describe("Max retries"),
+  },
+  execute: (args, ctx) => execTool("structured_validate", args, ctx),
+});
+
+const structured_parse_evaluation = tool({
+  description: "Parse and validate evaluation response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_evaluation", args, ctx),
+});
+
+const structured_parse_decomposition = tool({
+  description: "Parse and validate task decomposition response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_decomposition", args, ctx),
+});
+
+const structured_parse_bead_tree = tool({
+  description: "Parse and validate bead tree response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_bead_tree", args, ctx),
+});
+
+// =============================================================================
+// Swarm Tools
+// =============================================================================
+
+const swarm_init = tool({
+  description: "Initialize swarm session and check tool availability",
+  args: {
+    project_path: tool.schema.string().optional().describe("Project path"),
+  },
+  execute: (args, ctx) => execTool("swarm_init", args, ctx),
+});
+
+const swarm_select_strategy = tool({
+  description: "Analyze task and recommend decomposition strategy",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to analyze"),
+    codebase_context: tool.schema
+      .string()
+      .optional()
+      .describe("Codebase context"),
+  },
+  execute: (args, ctx) => execTool("swarm_select_strategy", args, ctx),
+});
+
+const swarm_plan_prompt = tool({
+  description: "Generate strategy-specific decomposition prompt",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to decompose"),
+    strategy: tool.schema
+      .enum(["file-based", "feature-based", "risk-based", "auto"])
+      .optional()
+      .describe("Decomposition strategy"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .optional()
+      .describe("Max subtasks"),
+    context: tool.schema.string().optional().describe("Additional context"),
+    query_cass: tool.schema
+      .boolean()
+      .optional()
+      .describe("Query CASS for similar tasks"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("CASS limit"),
+  },
+  execute: (args, ctx) => execTool("swarm_plan_prompt", args, ctx),
+});
+
+const swarm_decompose = tool({
+  description: "Generate decomposition prompt for breaking task into subtasks",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to decompose"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .optional()
+      .describe("Max subtasks"),
+    context: tool.schema.string().optional().describe("Additional context"),
+    query_cass: tool.schema.boolean().optional().describe("Query CASS"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("CASS limit"),
+  },
+  execute: (args, ctx) => execTool("swarm_decompose", args, ctx),
+});
+
+const swarm_validate_decomposition = tool({
+  description: "Validate a decomposition response against BeadTreeSchema",
+  args: {
+    response: tool.schema.string().describe("Decomposition response"),
+  },
+  execute: (args, ctx) => execTool("swarm_validate_decomposition", args, ctx),
+});
+
+const swarm_status = tool({
+  description: "Get status of a swarm by epic ID",
+  args: {
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    project_key: tool.schema.string().describe("Project key"),
+  },
+  execute: (args, ctx) => execTool("swarm_status", args, ctx),
+});
+
+const swarm_progress = tool({
+  description: "Report progress on a subtask to coordinator",
+  args: {
+    project_key: tool.schema.string().describe("Project key"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Bead ID"),
+    status: tool.schema
+      .enum(["in_progress", "blocked", "completed", "failed"])
+      .describe("Status"),
+    message: tool.schema.string().optional().describe("Progress message"),
+    progress_percent: tool.schema
+      .number()
+      .min(0)
+      .max(100)
+      .optional()
+      .describe("Progress %"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_progress", args, ctx),
+});
+
+const swarm_complete = tool({
+  description:
+    "Mark subtask complete, release reservations, notify coordinator",
+  args: {
+    project_key: tool.schema.string().describe("Project key"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Bead ID"),
+    summary: tool.schema.string().describe("Completion summary"),
+    evaluation: tool.schema.string().optional().describe("Self-evaluation"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+    skip_ubs_scan: tool.schema.boolean().optional().describe("Skip UBS scan"),
+  },
+  execute: (args, ctx) => execTool("swarm_complete", args, ctx),
+});
+
+const swarm_record_outcome = tool({
+  description: "Record subtask outcome for implicit feedback scoring",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    duration_ms: tool.schema.number().int().min(0).describe("Duration in ms"),
+    error_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Error count"),
+    retry_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Retry count"),
+    success: tool.schema.boolean().describe("Whether task succeeded"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+    criteria: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Evaluation criteria"),
+    strategy: tool.schema
+      .enum(["file-based", "feature-based", "risk-based"])
+      .optional()
+      .describe("Strategy used"),
+  },
+  execute: (args, ctx) => execTool("swarm_record_outcome", args, ctx),
+});
+
+const swarm_subtask_prompt = tool({
+  description: "Generate the prompt for a spawned subtask agent",
+  args: {
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Bead ID"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Description"),
+    files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+    shared_context: tool.schema.string().optional().describe("Shared context"),
+  },
+  execute: (args, ctx) => execTool("swarm_subtask_prompt", args, ctx),
+});
+
+const swarm_spawn_subtask = tool({
+  description: "Prepare a subtask for spawning with Task tool",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Description"),
+    files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+    shared_context: tool.schema.string().optional().describe("Shared context"),
+  },
+  execute: (args, ctx) => execTool("swarm_spawn_subtask", args, ctx),
+});
+
+const swarm_complete_subtask = tool({
+  description: "Handle subtask completion after Task agent returns",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    task_result: tool.schema.string().describe("Task result JSON"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_complete_subtask", args, ctx),
+});
+
+const swarm_evaluation_prompt = tool({
+  description: "Generate self-evaluation prompt for a completed subtask",
+  args: {
+    bead_id: tool.schema.string().describe("Bead ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_evaluation_prompt", args, ctx),
+});
+
+// =============================================================================
+// Plugin Export
+// =============================================================================
+
+export const SwarmPlugin: Plugin = async (
+  _input: PluginInput,
+): Promise<Hooks> => {
+  return {
+    tool: {
+      // Beads
+      beads_create,
+      beads_create_epic,
+      beads_query,
+      beads_update,
+      beads_close,
+      beads_start,
+      beads_ready,
+      beads_sync,
+      beads_link_thread,
+      // Agent Mail
+      agentmail_init,
+      agentmail_send,
+      agentmail_inbox,
+      agentmail_read_message,
+      agentmail_summarize_thread,
+      agentmail_reserve,
+      agentmail_release,
+      agentmail_ack,
+      agentmail_search,
+      agentmail_health,
+      // Structured
+      structured_extract_json,
+      structured_validate,
+      structured_parse_evaluation,
+      structured_parse_decomposition,
+      structured_parse_bead_tree,
+      // Swarm
+      swarm_init,
+      swarm_select_strategy,
+      swarm_plan_prompt,
+      swarm_decompose,
+      swarm_validate_decomposition,
+      swarm_status,
+      swarm_progress,
+      swarm_complete,
+      swarm_record_outcome,
+      swarm_subtask_prompt,
+      swarm_spawn_subtask,
+      swarm_complete_subtask,
+      swarm_evaluation_prompt,
+    },
+  };
+};
+
+export default SwarmPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/agent-mail.ts

@@ -62,9 +62,83 @@ export interface AgentMailState {
 // Module-level state (keyed by sessionID)
 // ============================================================================
 
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+/**
+ * Directory for persisting session state across CLI invocations
+ * This allows `swarm tool` commands to share state
+ */
+const SESSION_STATE_DIR =
+  process.env.SWARM_STATE_DIR || join(tmpdir(), "swarm-sessions");
+
+/**
+ * Get the file path for a session's state
+ */
+function getSessionStatePath(sessionID: string): string {
+  // Sanitize sessionID to be filesystem-safe
+  const safeID = sessionID.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return join(SESSION_STATE_DIR, `${safeID}.json`);
+}
+
+/**
+ * Load session state from disk
+ */
+function loadSessionState(sessionID: string): AgentMailState | null {
+  const path = getSessionStatePath(sessionID);
+  try {
+    if (existsSync(path)) {
+      const data = readFileSync(path, "utf-8");
+      return JSON.parse(data) as AgentMailState;
+    }
+  } catch (error) {
+    // File might be corrupted or inaccessible - ignore and return null
+    console.warn(`[agent-mail] Could not load session state: ${error}`);
+  }
+  return null;
+}
+
+/**
+ * Save session state to disk
+ */
+function saveSessionState(sessionID: string, state: AgentMailState): void {
+  try {
+    // Ensure directory exists
+    if (!existsSync(SESSION_STATE_DIR)) {
+      mkdirSync(SESSION_STATE_DIR, { recursive: true });
+    }
+    const path = getSessionStatePath(sessionID);
+    writeFileSync(path, JSON.stringify(state, null, 2));
+  } catch (error) {
+    // Non-fatal - state just won't persist
+    console.warn(`[agent-mail] Could not save session state: ${error}`);
+  }
+}
+
+/**
+ * Delete session state from disk
+ */
+function deleteSessionState(sessionID: string): void {
+  const path = getSessionStatePath(sessionID);
+  try {
+    if (existsSync(path)) {
+      unlinkSync(path);
+    }
+  } catch {
+    // Ignore errors on cleanup
+  }
+}
+
 /**
  * State storage keyed by sessionID.
- * Since ToolContext doesn't have persistent state, we use a module-level map.
+ * In-memory cache that also persists to disk for CLI usage.
  */
 const sessionStates = new Map<string, AgentMailState>();
 
@@ -691,9 +765,23 @@ export async function mcpCall<T>(
 
 /**
  * Get Agent Mail state for a session, or throw if not initialized
+ *
+ * Checks in-memory cache first, then falls back to disk storage.
+ * This allows CLI invocations to share state across calls.
  */
 function requireState(sessionID: string): AgentMailState {
-  const state = sessionStates.get(sessionID);
+  // Check in-memory cache first
+  let state = sessionStates.get(sessionID);
+
+  // If not in memory, try loading from disk
+  if (!state) {
+    state = loadSessionState(sessionID) ?? undefined;
+    if (state) {
+      // Cache in memory for subsequent calls in same process
+      sessionStates.set(sessionID, state);
+    }
+  }
+
   if (!state) {
     throw new AgentMailNotInitializedError();
   }
@@ -702,23 +790,38 @@ function requireState(sessionID: string): AgentMailState {
 
 /**
  * Store Agent Mail state for a session
+ *
+ * Saves to both in-memory cache and disk for CLI persistence.
  */
 function setState(sessionID: string, state: AgentMailState): void {
   sessionStates.set(sessionID, state);
+  saveSessionState(sessionID, state);
 }
 
 /**
  * Get state if exists (for cleanup hooks)
+ *
+ * Checks in-memory cache first, then falls back to disk storage.
  */
 function getState(sessionID: string): AgentMailState | undefined {
-  return sessionStates.get(sessionID);
+  let state = sessionStates.get(sessionID);
+  if (!state) {
+    state = loadSessionState(sessionID) ?? undefined;
+    if (state) {
+      sessionStates.set(sessionID, state);
+    }
+  }
+  return state;
 }
 
 /**
  * Clear state for a session
+ *
+ * Removes from both in-memory cache and disk.
  */
 function clearState(sessionID: string): void {
   sessionStates.delete(sessionID);
+  deleteSessionState(sessionID);
 }
 
 // ============================================================================

package/src/index.ts

@@ -280,6 +280,28 @@ export {
   type StrategyDefinition,
 } from "./swarm";
 
+// =============================================================================
+// Unified Tool Registry for CLI
+// =============================================================================
+
+/**
+ * All tools in a single registry for CLI tool execution
+ *
+ * This is used by `swarm tool <name>` command to dynamically execute tools.
+ * Each tool has an `execute` function that takes (args, ctx) and returns a string.
+ */
+export const allTools = {
+  ...beadsTools,
+  ...agentMailTools,
+  ...structuredTools,
+  ...swarmTools,
+} as const;
+
+/**
+ * Type for CLI tool names (all available tools)
+ */
+export type CLIToolName = keyof typeof allTools;
+
 /**
  * Re-export storage module
  *