opencode-swarm 4.3.2 → 4.5.0

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-4.3.1-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-4.5.0-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
   <img src="https://img.shields.io/badge/agents-8-orange" alt="Agents">
-  <img src="https://img.shields.io/badge/tests-483-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-622-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -313,37 +313,47 @@ Each architect automatically delegates to its own swarm's agents.
 ## Installation
 
 ```bash
-# Add to opencode.json
-{
-  "plugin": ["opencode-swarm"]
-}
-
-# Or install via CLI
+# Install via CLI (recommended)
 bunx opencode-swarm install
 ```
 
+### Uninstall
+
+```bash
+# Remove from opencode.json
+bunx opencode-swarm uninstall
+
+# Remove from opencode.json + clean up config files
+bunx opencode-swarm uninstall --clean
+```
+
 ---
 
-## What's New in v4.3.0
+## What's New
 
-### 🔧 Hooks Pipeline
-- **`safeHook()`** — Crash-safe wrapper for all hooks. Errors are caught and logged, never crash the plugin.
-- **`composeHandlers()`** — Compose multiple handlers for the same hook type (Plugin API allows only one handler per type).
+### v4.5.0 — Tech Debt + New Commands
+- **Lint cleanup** — Replaced string concatenation with template literals, documented `as any` casts with biome-ignore comments.
+- **Code deduplication** — Extracted `stripSwarmPrefix()` utility to eliminate 3 duplicate prefix-stripping blocks.
+- **`/swarm diagnose`** — Health check for `.swarm/` files, plan structure, and plugin configuration.
+- **`/swarm export`** — Export plan.md and context.md as portable JSON.
+- **`/swarm reset --confirm`** — Clear swarm state files with safety confirmation.
 
-### 📊 Context Pruning
-- **Token budget tracking** — Estimates context window usage and injects warnings at 70% and 90% thresholds.
-- **Enhanced session compaction** — Guides OpenCode's built-in compaction with plan.md phases and context.md decisions.
-- **System prompt enhancement** — Injects current phase, task, and key decisions to keep agents focused post-compaction.
+### v4.4.0 — DX & Quality
+- **CLI `uninstall` command** — Remove plugin with optional `--clean` flag.
+- **Custom error classes** — `SwarmError` hierarchy with actionable `guidance` messages.
+- **`/swarm history`** — View completed phases from plan.md.
+- **`/swarm config`** — View current resolved plugin configuration.
 
-### ⚡ Slash Commands
-- **`/swarm status`** — Current phase, progress, and agent count.
-- **`/swarm plan [N]`** — View full plan or a specific phase.
-- **`/swarm agents`** — List all registered agents with models and permissions.
+### v4.3.2 — Security Hardening
+- **Path validation** — `validateSwarmPath()` prevents directory traversal in `.swarm/` file operations.
+- **Fetch hardening** — 10s timeout, 5MB limit, retry logic for gitingest tool.
+- **Config limits** — Deep merge depth limit (10), config file size limit (100KB).
 
-### 🤖 Agent Awareness
-- **Activity tracking** — Tool usage tracked per agent via `tool.execute.before/after` hooks. Activity summary flushed to context.md every 20 events.
-- **Delegation tracking** — Active agent per session tracked via `chat.message` hook. Optional delegation chain logging.
-- **Cross-agent context** — System enhancer injects relevant context from other agents' activity into system prompts.
+### v4.3.0 — Hooks & Agent Awareness
+- **Hooks pipeline** — `safeHook()` crash-safe wrapper, `composeHandlers()` for multi-handler composition.
+- **Context pruning** — Token budget tracking with 70%/90% threshold warnings.
+- **Slash commands** — `/swarm status`, `/swarm plan`, `/swarm agents`.
+- **Agent awareness** — Activity tracking, delegation tracking, cross-agent context injection.
 
 All features are opt-in via configuration. See [Installation Guide](docs/installation.md) for config options.
 
@@ -380,6 +390,21 @@ All features are opt-in via configuration. See [Installation Guide](docs/install
 
 ---
 
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/swarm status` | Current phase, task progress, and agent count |
+| `/swarm plan [N]` | View full plan or filter by phase number |
+| `/swarm agents` | List all registered agents with models and permissions |
+| `/swarm history` | View completed phases with status icons |
+| `/swarm config` | View current resolved plugin configuration |
+| `/swarm diagnose` | Health check for .swarm/ files and config |
+| `/swarm export` | Export plan and context as portable JSON |
+| `/swarm reset --confirm` | Clear swarm state files (with safety gate) |
+
+---
+
 ## Configuration
 
 Create `~/.config/opencode/opencode-swarm.json`:
@@ -448,7 +473,22 @@ bun test
 bun test tests/unit/config/schema.test.ts
 ```
 
-447 unit tests across 21 files covering config, tools, agents, hooks, commands, and state. Uses Bun's built-in test runner — zero additional test dependencies.
+622 unit tests across 29 files covering config, tools, agents, hooks, commands, and state. Uses Bun's built-in test runner — zero additional test dependencies.
+
+## Troubleshooting
+
+### Plugin not loading
+1. Verify `opencode-swarm` is listed in your `opencode.json` plugins array
+2. Run `bunx opencode-swarm install` to auto-configure
+3. Run `/swarm diagnose` to check health status
+
+### Commands not working
+- Ensure you're using `/swarm <command>`, not `/swarm/<command>`
+- Run `/swarm` with no arguments to see available commands
+
+### Resuming a project
+- Swarm automatically detects `.swarm/plan.md` and resumes where you left off
+- If you get unexpected behavior, run `/swarm export` to backup, then `/swarm reset --confirm` to start fresh
 
 ---
 

package/dist/agents/index.d.ts

@@ -2,6 +2,12 @@ import type { AgentConfig as SDKAgentConfig } from '@opencode-ai/sdk';
 import { type PluginConfig } from '../config';
 import { type AgentDefinition } from './architect';
 export type { AgentDefinition } from './architect';
+/**
+ * Strip the swarm prefix from an agent name to get the base name.
+ * e.g., "local_coder" with prefix "local" → "coder"
+ * Returns the name unchanged if no prefix matches.
+ */
+export declare function stripSwarmPrefix(agentName: string, swarmPrefix?: string): string;
 /**
  * Create all agent definitions with configuration applied
  */

package/dist/cli/index.js

@@ -96,6 +96,66 @@ Next steps:`);
   console.log("   what expertise is needed and requests it dynamically.");
   return 0;
 }
+async function uninstall() {
+  try {
+    console.log(`\uD83D\uDC1D Uninstalling OpenCode Swarm...
+`);
+    const opencodeConfig = loadJson(OPENCODE_CONFIG_PATH);
+    if (!opencodeConfig) {
+      if (fs.existsSync(OPENCODE_CONFIG_PATH)) {
+        console.log(`\u2717 Could not parse opencode config at: ${OPENCODE_CONFIG_PATH}`);
+        return 1;
+      } else {
+        console.log(`\u26A0 No opencode config found at: ${OPENCODE_CONFIG_PATH}`);
+        console.log("Nothing to uninstall.");
+        return 0;
+      }
+    }
+    if (!opencodeConfig.plugin || opencodeConfig.plugin.length === 0) {
+      console.log("\u26A0 opencode-swarm is not installed (no plugins configured).");
+      return 0;
+    }
+    const pluginName = "opencode-swarm";
+    const filteredPlugins = opencodeConfig.plugin.filter((p) => p !== pluginName && !p.startsWith(`${pluginName}@`));
+    if (filteredPlugins.length === opencodeConfig.plugin.length) {
+      console.log("\u26A0 opencode-swarm is not installed.");
+      return 0;
+    }
+    opencodeConfig.plugin = filteredPlugins;
+    if (opencodeConfig.agent) {
+      delete opencodeConfig.agent.explore;
+      delete opencodeConfig.agent.general;
+      if (Object.keys(opencodeConfig.agent).length === 0) {
+        delete opencodeConfig.agent;
+      }
+    }
+    saveJson(OPENCODE_CONFIG_PATH, opencodeConfig);
+    console.log("\u2713 Removed opencode-swarm from OpenCode plugins");
+    console.log("\u2713 Re-enabled default OpenCode agents (explore, general)");
+    if (process.argv.includes("--clean")) {
+      let cleaned = false;
+      if (fs.existsSync(PLUGIN_CONFIG_PATH)) {
+        fs.unlinkSync(PLUGIN_CONFIG_PATH);
+        console.log(`\u2713 Removed plugin config: ${PLUGIN_CONFIG_PATH}`);
+        cleaned = true;
+      }
+      if (fs.existsSync(PROMPTS_DIR)) {
+        fs.rmSync(PROMPTS_DIR, { recursive: true });
+        console.log(`\u2713 Removed custom prompts: ${PROMPTS_DIR}`);
+        cleaned = true;
+      }
+      if (!cleaned) {
+        console.log("\u2713 No config files to clean up");
+      }
+    }
+    console.log(`
+\u2705 Uninstall complete!`);
+    return 0;
+  } catch (error) {
+    console.log("\u2717 Uninstall failed: " + (error instanceof Error ? error.message : String(error)));
+    return 1;
+  }
+}
 function printHelp() {
   console.log(`
 opencode-swarm - Architect-centric agentic swarm plugin for OpenCode
@@ -104,8 +164,10 @@ Usage: bunx opencode-swarm [command] [OPTIONS]
 
 Commands:
   install     Install and configure the plugin (default)
+  uninstall   Remove the plugin from OpenCode config
 
 Options:
+  --clean     Also remove config files and custom prompts (with uninstall)
   -h, --help  Show this help message
 
 Configuration:
@@ -122,6 +184,8 @@ Custom Prompts:
 
 Examples:
   bunx opencode-swarm install
+  bunx opencode-swarm uninstall
+  bunx opencode-swarm uninstall --clean
   bunx opencode-swarm --help
 `);
 }
@@ -135,6 +199,9 @@ async function main() {
   if (command === "install") {
     const exitCode = await install();
     process.exit(exitCode);
+  } else if (command === "uninstall") {
+    const exitCode = await uninstall();
+    process.exit(exitCode);
   } else {
     console.error(`Unknown command: ${command}`);
     console.error("Run with --help for usage information");

package/dist/commands/config.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm config command.
+ * Loads and displays the current resolved plugin configuration.
+ */
+export declare function handleConfigCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/diagnose.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm diagnose command.
+ * Performs health checks on swarm state files and configuration.
+ */
+export declare function handleDiagnoseCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/export.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm export command.
+ * Exports plan.md and context.md as a portable JSON object.
+ */
+export declare function handleExportCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/history.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm history command.
+ * Reads plan.md and displays a summary of all phases and their status.
+ */
+export declare function handleHistoryCommand(directory: string, _args: string[]): Promise<string>;

package/dist/commands/index.d.ts

@@ -1,6 +1,11 @@
 import type { AgentDefinition } from '../agents';
 export { handleAgentsCommand } from './agents';
+export { handleConfigCommand } from './config';
+export { handleDiagnoseCommand } from './diagnose';
+export { handleExportCommand } from './export';
+export { handleHistoryCommand } from './history';
 export { handlePlanCommand } from './plan';
+export { handleResetCommand } from './reset';
 export { handleStatusCommand } from './status';
 /**
  * Creates a command.execute.before handler for /swarm commands.

package/dist/commands/reset.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Handles the /swarm reset command.
+ * Clears plan.md and context.md from .swarm/ directory.
+ * Requires --confirm flag as a safety gate.
+ */
+export declare function handleResetCommand(directory: string, args: string[]): Promise<string>;

package/dist/index.js

@@ -14246,28 +14246,28 @@ ${customAppendPrompt}`;
 }
 
 // src/agents/index.ts
-function getModelForAgent(agentName, swarmAgents, swarmPrefix) {
-  let baseAgentName = agentName;
-  if (swarmPrefix && agentName.startsWith(`${swarmPrefix}_`)) {
-    baseAgentName = agentName.substring(swarmPrefix.length + 1);
+function stripSwarmPrefix(agentName, swarmPrefix) {
+  if (!swarmPrefix || !agentName)
+    return agentName;
+  const prefixWithUnderscore = `${swarmPrefix}_`;
+  if (agentName.startsWith(prefixWithUnderscore)) {
+    return agentName.substring(prefixWithUnderscore.length);
   }
+  return agentName;
+}
+function getModelForAgent(agentName, swarmAgents, swarmPrefix) {
+  const baseAgentName = stripSwarmPrefix(agentName, swarmPrefix);
   const explicit = swarmAgents?.[baseAgentName]?.model;
   if (explicit)
     return explicit;
   return DEFAULT_MODELS[baseAgentName] ?? DEFAULT_MODELS.default;
 }
 function isAgentDisabled(agentName, swarmAgents, swarmPrefix) {
-  let baseAgentName = agentName;
-  if (swarmPrefix && agentName.startsWith(`${swarmPrefix}_`)) {
-    baseAgentName = agentName.substring(swarmPrefix.length + 1);
-  }
+  const baseAgentName = stripSwarmPrefix(agentName, swarmPrefix);
   return swarmAgents?.[baseAgentName]?.disabled === true;
 }
 function getTemperatureOverride(agentName, swarmAgents, swarmPrefix) {
-  let baseAgentName = agentName;
-  if (swarmPrefix && agentName.startsWith(`${swarmPrefix}_`)) {
-    baseAgentName = agentName.substring(swarmPrefix.length + 1);
-  }
+  const baseAgentName = stripSwarmPrefix(agentName, swarmPrefix);
   return swarmAgents?.[baseAgentName]?.temperature;
 }
 function applyOverrides(agent, swarmAgents, swarmPrefix) {
@@ -14410,9 +14410,46 @@ function handleAgentsCommand(agents) {
 `);
 }
 
-// src/hooks/utils.ts
+// src/commands/config.ts
+import * as os2 from "os";
 import * as path2 from "path";
+function getUserConfigDir2() {
+  return process.env.XDG_CONFIG_HOME || path2.join(os2.homedir(), ".config");
+}
+async function handleConfigCommand(directory, _args) {
+  const config2 = loadPluginConfig(directory);
+  const userConfigPath = path2.join(getUserConfigDir2(), "opencode", "opencode-swarm.json");
+  const projectConfigPath = path2.join(directory, ".opencode", "opencode-swarm.json");
+  const lines = [
+    "## Swarm Configuration",
+    "",
+    "### Config Files",
+    `- User: \`${userConfigPath}\``,
+    `- Project: \`${projectConfigPath}\``,
+    "",
+    "### Resolved Config",
+    "```json",
+    JSON.stringify(config2, null, 2),
+    "```"
+  ];
+  return lines.join(`
+`);
+}
+
+// src/hooks/utils.ts
+import * as path3 from "path";
 
+// src/utils/errors.ts
+class SwarmError extends Error {
+  code;
+  guidance;
+  constructor(message, code, guidance) {
+    super(message);
+    this.name = "SwarmError";
+    this.code = code;
+    this.guidance = guidance;
+  }
+}
 // src/utils/logger.ts
 var DEBUG = process.env.OPENCODE_SWARM_DEBUG === "1";
 function log(message, data) {
@@ -14440,7 +14477,12 @@ function safeHook(fn) {
       await fn(input, output);
     } catch (_error) {
       const functionName = fn.name || "unknown";
-      warn(`Hook function '${functionName}' failed:`, _error);
+      if (_error instanceof SwarmError) {
+        warn(`Hook '${functionName}' failed: ${_error.message}
+  \u2192 ${_error.guidance}`);
+      } else {
+        warn(`Hook function '${functionName}' failed:`, _error);
+      }
     }
   };
 }
@@ -14462,14 +14504,14 @@ function validateSwarmPath(directory, filename) {
   if (/\.\.[/\\]/.test(filename)) {
     throw new Error("Invalid filename: path traversal detected");
   }
-  const baseDir = path2.normalize(path2.resolve(directory, ".swarm"));
-  const resolved = path2.normalize(path2.resolve(baseDir, filename));
+  const baseDir = path3.normalize(path3.resolve(directory, ".swarm"));
+  const resolved = path3.normalize(path3.resolve(baseDir, filename));
   if (process.platform === "win32") {
-    if (!resolved.toLowerCase().startsWith((baseDir + path2.sep).toLowerCase())) {
+    if (!resolved.toLowerCase().startsWith((baseDir + path3.sep).toLowerCase())) {
       throw new Error("Invalid filename: path escapes .swarm directory");
     }
   } else {
-    if (!resolved.startsWith(baseDir + path2.sep)) {
+    if (!resolved.startsWith(baseDir + path3.sep)) {
       throw new Error("Invalid filename: path escapes .swarm directory");
     }
   }
@@ -14492,6 +14534,143 @@ function estimateTokens(text) {
   return Math.ceil(text.length * 0.33);
 }
 
+// src/commands/diagnose.ts
+async function handleDiagnoseCommand(directory, _args) {
+  const checks3 = [];
+  const planContent = await readSwarmFileAsync(directory, "plan.md");
+  const contextContent = await readSwarmFileAsync(directory, "context.md");
+  if (planContent) {
+    const hasPhases = /^## Phase \d+/m.test(planContent);
+    const hasTasks = /^- \[[ x]\]/m.test(planContent);
+    if (hasPhases && hasTasks) {
+      checks3.push({
+        name: "plan.md",
+        status: "\u2705",
+        detail: "Found with valid phase structure"
+      });
+    } else {
+      checks3.push({
+        name: "plan.md",
+        status: "\u274C",
+        detail: "Found but missing phase/task structure"
+      });
+    }
+  } else {
+    checks3.push({ name: "plan.md", status: "\u274C", detail: "Not found" });
+  }
+  if (contextContent) {
+    checks3.push({ name: "context.md", status: "\u2705", detail: "Found" });
+  } else {
+    checks3.push({ name: "context.md", status: "\u274C", detail: "Not found" });
+  }
+  try {
+    const config2 = loadPluginConfig(directory);
+    if (config2) {
+      checks3.push({
+        name: "Plugin config",
+        status: "\u2705",
+        detail: "Valid configuration loaded"
+      });
+    } else {
+      checks3.push({
+        name: "Plugin config",
+        status: "\u2705",
+        detail: "Using defaults (no custom config)"
+      });
+    }
+  } catch {
+    checks3.push({
+      name: "Plugin config",
+      status: "\u274C",
+      detail: "Invalid configuration"
+    });
+  }
+  const passCount = checks3.filter((c) => c.status === "\u2705").length;
+  const totalCount = checks3.length;
+  const allPassed = passCount === totalCount;
+  const lines = [
+    "## Swarm Health Check",
+    "",
+    ...checks3.map((c) => `- ${c.status} **${c.name}**: ${c.detail}`),
+    "",
+    `**Result**: ${allPassed ? "\u2705 All checks passed" : `\u26A0\uFE0F ${passCount}/${totalCount} checks passed`}`
+  ];
+  return lines.join(`
+`);
+}
+
+// src/commands/export.ts
+async function handleExportCommand(directory, _args) {
+  const planContent = await readSwarmFileAsync(directory, "plan.md");
+  const contextContent = await readSwarmFileAsync(directory, "context.md");
+  const exportData = {
+    version: "4.5.0",
+    exported: new Date().toISOString(),
+    plan: planContent,
+    context: contextContent
+  };
+  const lines = [
+    "## Swarm Export",
+    "",
+    "```json",
+    JSON.stringify(exportData, null, 2),
+    "```"
+  ];
+  return lines.join(`
+`);
+}
+
+// src/commands/history.ts
+async function handleHistoryCommand(directory, _args) {
+  const planContent = await readSwarmFileAsync(directory, "plan.md");
+  if (!planContent) {
+    return "No history available.";
+  }
+  const phaseRegex = /^## Phase (\d+):?\s*(.+?)(?:\s*\[(COMPLETE|IN PROGRESS|PENDING)\])?\s*$/gm;
+  const phases = [];
+  const lines = planContent.split(`
+`);
+  for (let match = phaseRegex.exec(planContent);match !== null; match = phaseRegex.exec(planContent)) {
+    const num = parseInt(match[1], 10);
+    const name = match[2].trim();
+    const status = match[3] || "PENDING";
+    const headerLineIndex = lines.indexOf(match[0]);
+    let completed = 0;
+    let total = 0;
+    if (headerLineIndex !== -1) {
+      for (let i = headerLineIndex + 1;i < lines.length; i++) {
+        const line = lines[i];
+        if (/^## Phase \d+/.test(line) || line.trim() === "---" && total > 0) {
+          break;
+        }
+        if (/^- \[x\]/.test(line)) {
+          completed++;
+          total++;
+        } else if (/^- \[ \]/.test(line)) {
+          total++;
+        }
+      }
+    }
+    phases.push({ num, name, status, completed, total });
+  }
+  if (phases.length === 0) {
+    return "No history available.";
+  }
+  const tableLines = [
+    "## Swarm History",
+    "",
+    "| Phase | Name | Status | Tasks |",
+    "|-------|------|--------|-------|"
+  ];
+  for (const phase of phases) {
+    const statusIcon = phase.status === "COMPLETE" ? "\u2705" : phase.status === "IN PROGRESS" ? "\uD83D\uDD04" : "\u23F3";
+    const tasks = phase.total > 0 ? `${phase.completed}/${phase.total}` : "-";
+    tableLines.push(`| ${phase.num} | ${phase.name} | ${statusIcon} ${phase.status} | ${tasks} |`);
+  }
+  return tableLines.join(`
+`);
+}
+
 // src/commands/plan.ts
 async function handlePlanCommand(directory, args) {
   const planContent = await readSwarmFileAsync(directory, "plan.md");
@@ -14535,6 +14714,47 @@ async function handlePlanCommand(directory, args) {
 `).trim();
 }
 
+// src/commands/reset.ts
+import * as fs2 from "fs";
+async function handleResetCommand(directory, args) {
+  const hasConfirm = args.includes("--confirm");
+  if (!hasConfirm) {
+    return [
+      "## Swarm Reset",
+      "",
+      "\u26A0\uFE0F This will delete plan.md and context.md from .swarm/",
+      "",
+      "**Tip**: Run `/swarm export` first to backup your state.",
+      "",
+      "To confirm, run: `/swarm reset --confirm`"
+    ].join(`
+`);
+  }
+  const filesToReset = ["plan.md", "context.md"];
+  const results = [];
+  for (const filename of filesToReset) {
+    try {
+      const resolvedPath = validateSwarmPath(directory, filename);
+      if (fs2.existsSync(resolvedPath)) {
+        fs2.unlinkSync(resolvedPath);
+        results.push(`- \u2705 Deleted ${filename}`);
+      } else {
+        results.push(`- \u23ED\uFE0F ${filename} not found (skipped)`);
+      }
+    } catch {
+      results.push(`- \u274C Failed to delete ${filename}`);
+    }
+  }
+  return [
+    "## Swarm Reset Complete",
+    "",
+    ...results,
+    "",
+    "Swarm state has been cleared. Start fresh with a new plan."
+  ].join(`
+`);
+}
+
 // src/hooks/extractors.ts
 function extractCurrentPhase(planContent) {
   if (!planContent) {
@@ -14709,7 +14929,12 @@ var HELP_TEXT = [
   "",
   "- `/swarm status` \u2014 Show current swarm state",
   "- `/swarm plan [phase]` \u2014 Show plan (optionally filter by phase number)",
-  "- `/swarm agents` \u2014 List registered agents"
+  "- `/swarm agents` \u2014 List registered agents",
+  "- `/swarm history` \u2014 Show completed phases summary",
+  "- `/swarm config` \u2014 Show current resolved configuration",
+  "- `/swarm diagnose` \u2014 Run health check on swarm state",
+  "- `/swarm export` \u2014 Export plan and context as JSON",
+  "- `/swarm reset --confirm` \u2014 Clear swarm state files"
 ].join(`
 `);
 function createSwarmCommandHandler(directory, agents) {
@@ -14730,6 +14955,21 @@ function createSwarmCommandHandler(directory, agents) {
       case "agents":
         text = handleAgentsCommand(agents);
         break;
+      case "history":
+        text = await handleHistoryCommand(directory, args);
+        break;
+      case "config":
+        text = await handleConfigCommand(directory, args);
+        break;
+      case "diagnose":
+        text = await handleDiagnoseCommand(directory, args);
+        break;
+      case "export":
+        text = await handleExportCommand(directory, args);
+        break;
+      case "reset":
+        text = await handleResetCommand(directory, args);
+        break;
       default:
         text = HELP_TEXT;
         break;
@@ -14817,8 +15057,8 @@ async function doFlush(directory) {
     const activitySection = renderActivitySection();
     const updated = replaceOrAppendSection(existing, "## Agent Activity", activitySection);
     const flushedCount = swarmState.pendingEvents;
-    const path3 = `${directory}/.swarm/context.md`;
-    await Bun.write(path3, updated);
+    const path4 = `${directory}/.swarm/context.md`;
+    await Bun.write(path4, updated);
     swarmState.pendingEvents = Math.max(0, swarmState.pendingEvents - flushedCount);
   } catch (error49) {
     warn("Agent activity flush failed:", error49);
@@ -14844,19 +15084,19 @@ function renderActivitySection() {
 function replaceOrAppendSection(content, heading, newSection) {
   const headingIndex = content.indexOf(heading);
   if (headingIndex === -1) {
-    return content.trimEnd() + `
+    return `${content.trimEnd()}
 
-` + newSection + `
+${newSection}
 `;
   }
   const afterHeading = content.substring(headingIndex + heading.length);
   const nextHeadingMatch = afterHeading.match(/\n## /);
   if (nextHeadingMatch && nextHeadingMatch.index !== undefined) {
     const endIndex = headingIndex + heading.length + nextHeadingMatch.index;
-    return content.substring(0, headingIndex) + newSection + `
-` + content.substring(endIndex + 1);
+    return `${content.substring(0, headingIndex)}${newSection}
+${content.substring(endIndex + 1)}`;
   }
-  return content.substring(0, headingIndex) + newSection + `
+  return `${content.substring(0, headingIndex)}${newSection}
 `;
 }
 // src/hooks/compaction-customizer.ts
@@ -15104,7 +15344,7 @@ ${activitySection}`;
       break;
   }
   if (contextSummary.length > maxChars) {
-    return contextSummary.substring(0, maxChars - 3) + "...";
+    return `${contextSummary.substring(0, maxChars - 3)}...`;
   }
   return contextSummary;
 }
@@ -15837,10 +16077,10 @@ function mergeDefs2(...defs) {
 function cloneDef2(schema) {
   return mergeDefs2(schema._zod.def);
 }
-function getElementAtPath2(obj, path3) {
-  if (!path3)
+function getElementAtPath2(obj, path4) {
+  if (!path4)
     return obj;
-  return path3.reduce((acc, key) => acc?.[key], obj);
+  return path4.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject2(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -16199,11 +16439,11 @@ function aborted2(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues2(path3, issues) {
+function prefixIssues2(path4, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path3);
+    iss.path.unshift(path4);
     return iss;
   });
 }
@@ -16371,7 +16611,7 @@ function treeifyError2(error49, _mapper) {
     return issue3.message;
   };
   const result = { errors: [] };
-  const processError = (error50, path3 = []) => {
+  const processError = (error50, path4 = []) => {
     var _a2, _b;
     for (const issue3 of error50.issues) {
       if (issue3.code === "invalid_union" && issue3.errors.length) {
@@ -16381,7 +16621,7 @@ function treeifyError2(error49, _mapper) {
       } else if (issue3.code === "invalid_element") {
         processError({ issues: issue3.issues }, issue3.path);
       } else {
-        const fullpath = [...path3, ...issue3.path];
+        const fullpath = [...path4, ...issue3.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue3));
           continue;
@@ -16413,8 +16653,8 @@ function treeifyError2(error49, _mapper) {
 }
 function toDotPath2(_path) {
   const segs = [];
-  const path3 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path3) {
+  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path4) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -27609,8 +27849,8 @@ Use these as DOMAIN values when delegating to @sme.`;
   }
 });
 // src/tools/file-extractor.ts
-import * as fs2 from "fs";
-import * as path3 from "path";
+import * as fs3 from "fs";
+import * as path4 from "path";
 var EXT_MAP = {
   python: ".py",
   py: ".py",
@@ -27672,8 +27912,8 @@ var extract_code_blocks = tool({
   execute: async (args) => {
     const { content, output_dir, prefix } = args;
     const targetDir = output_dir || process.cwd();
-    if (!fs2.existsSync(targetDir)) {
-      fs2.mkdirSync(targetDir, { recursive: true });
+    if (!fs3.existsSync(targetDir)) {
+      fs3.mkdirSync(targetDir, { recursive: true });
     }
     const pattern = /```(\w*)\n([\s\S]*?)```/g;
     const matches = [...content.matchAll(pattern)];
@@ -27688,16 +27928,16 @@ var extract_code_blocks = tool({
       if (prefix) {
         filename = `${prefix}_${filename}`;
       }
-      let filepath = path3.join(targetDir, filename);
-      const base = path3.basename(filepath, path3.extname(filepath));
-      const ext = path3.extname(filepath);
+      let filepath = path4.join(targetDir, filename);
+      const base = path4.basename(filepath, path4.extname(filepath));
+      const ext = path4.extname(filepath);
       let counter = 1;
-      while (fs2.existsSync(filepath)) {
-        filepath = path3.join(targetDir, `${base}_${counter}${ext}`);
+      while (fs3.existsSync(filepath)) {
+        filepath = path4.join(targetDir, `${base}_${counter}${ext}`);
         counter++;
       }
       try {
-        fs2.writeFileSync(filepath, code.trim(), "utf-8");
+        fs3.writeFileSync(filepath, code.trim(), "utf-8");
         savedFiles.push(filepath);
       } catch (error93) {
         errors5.push(`Failed to save ${filename}: ${error93 instanceof Error ? error93.message : String(error93)}`);

package/dist/utils/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Base error class for all swarm errors.
+ * Includes a machine-readable `code` and a user-facing `guidance` string.
+ */
+export declare class SwarmError extends Error {
+    readonly code: string;
+    readonly guidance: string;
+    constructor(message: string, code: string, guidance: string);
+}
+/**
+ * Error thrown when configuration loading or validation fails.
+ */
+export declare class ConfigError extends SwarmError {
+    constructor(message: string, guidance: string);
+}
+/**
+ * Error thrown when a hook execution fails.
+ */
+export declare class HookError extends SwarmError {
+    constructor(message: string, guidance: string);
+}
+/**
+ * Error thrown when a tool execution fails.
+ */
+export declare class ToolError extends SwarmError {
+    constructor(message: string, guidance: string);
+}
+/**
+ * Error thrown when CLI operations fail.
+ */
+export declare class CLIError extends SwarmError {
+    constructor(message: string, guidance: string);
+}

package/dist/utils/index.d.ts

@@ -1 +1,2 @@
-export { log, warn, error } from './logger';
+export { CLIError, ConfigError, HookError, SwarmError, ToolError, } from './errors';
+export { error, log, warn } from './logger';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "4.3.2",
+	"version": "4.5.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -35,12 +35,12 @@
 		"prepublishOnly": "bun run build"
 	},
 	"dependencies": {
-		"@opencode-ai/plugin": "^1.1.19",
-		"@opencode-ai/sdk": "^1.1.19",
+		"@opencode-ai/plugin": "^1.1.53",
+		"@opencode-ai/sdk": "^1.1.53",
 		"zod": "^4.1.8"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.11",
+		"@biomejs/biome": "2.3.14",
 		"bun-types": "latest",
 		"typescript": "^5.7.3"
 	}