opencode-swarm-plugin 0.1.0

package/src/swarm.ts

@@ -0,0 +1,1411 @@
+/**
+ * Swarm Module - High-level swarm coordination
+ *
+ * Orchestrates beads, Agent Mail, and structured validation for parallel task execution.
+ * The actual agent spawning happens via OpenCode's Task tool - this module provides
+ * the primitives and prompts that /swarm command uses.
+ *
+ * Key responsibilities:
+ * - Task decomposition into bead trees with file assignments
+ * - Swarm status tracking via beads + Agent Mail
+ * - Progress reporting and completion handling
+ * - Prompt templates for decomposition, subtasks, and evaluation
+ */
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import {
+  BeadTreeSchema,
+  SwarmStatusSchema,
+  AgentProgressSchema,
+  EvaluationSchema,
+  BeadSchema,
+  type SwarmStatus,
+  type AgentProgress,
+  type Evaluation,
+  type SpawnedAgent,
+  type Bead,
+} from "./schemas";
+import { mcpCall } from "./agent-mail";
+import {
+  OutcomeSignalsSchema,
+  scoreImplicitFeedback,
+  outcomeToFeedback,
+  type OutcomeSignals,
+  type ScoredOutcome,
+  type FeedbackEvent,
+  DEFAULT_LEARNING_CONFIG,
+} from "./learning";
+
+// ============================================================================
+// Conflict Detection
+// ============================================================================
+
+/**
+ * Marker words that indicate positive directives
+ */
+const POSITIVE_MARKERS = [
+  "always",
+  "must",
+  "required",
+  "ensure",
+  "use",
+  "prefer",
+];
+
+/**
+ * Marker words that indicate negative directives
+ */
+const NEGATIVE_MARKERS = [
+  "never",
+  "dont",
+  "don't",
+  "avoid",
+  "forbid",
+  "no ",
+  "not ",
+];
+
+/**
+ * A detected conflict between subtask instructions
+ */
+export interface InstructionConflict {
+  subtask_a: number;
+  subtask_b: number;
+  directive_a: string;
+  directive_b: string;
+  conflict_type: "positive_negative" | "contradictory";
+  description: string;
+}
+
+/**
+ * Extract directives from text based on marker words
+ */
+function extractDirectives(text: string): {
+  positive: string[];
+  negative: string[];
+} {
+  const sentences = text.split(/[.!?\n]+/).map((s) => s.trim().toLowerCase());
+  const positive: string[] = [];
+  const negative: string[] = [];
+
+  for (const sentence of sentences) {
+    if (!sentence) continue;
+
+    const hasPositive = POSITIVE_MARKERS.some((m) => sentence.includes(m));
+    const hasNegative = NEGATIVE_MARKERS.some((m) => sentence.includes(m));
+
+    if (hasPositive && !hasNegative) {
+      positive.push(sentence);
+    } else if (hasNegative) {
+      negative.push(sentence);
+    }
+  }
+
+  return { positive, negative };
+}
+
+/**
+ * Check if two directives conflict
+ *
+ * Simple heuristic: look for common subjects with opposite polarity
+ */
+function directivesConflict(positive: string, negative: string): boolean {
+  // Extract key nouns/concepts (simple word overlap check)
+  const positiveWords = new Set(
+    positive.split(/\s+/).filter((w) => w.length > 3),
+  );
+  const negativeWords = negative.split(/\s+/).filter((w) => w.length > 3);
+
+  // If they share significant words, they might conflict
+  const overlap = negativeWords.filter((w) => positiveWords.has(w));
+  return overlap.length >= 2;
+}
+
+/**
+ * Detect conflicts between subtask instructions
+ *
+ * Looks for cases where one subtask says "always use X" and another says "avoid X".
+ *
+ * @param subtasks - Array of subtask descriptions
+ * @returns Array of detected conflicts
+ *
+ * @see https://github.com/Dicklesworthstone/cass_memory_system/blob/main/src/curate.ts#L36-L89
+ */
+export function detectInstructionConflicts(
+  subtasks: Array<{ title: string; description?: string }>,
+): InstructionConflict[] {
+  const conflicts: InstructionConflict[] = [];
+
+  // Extract directives from each subtask
+  const subtaskDirectives = subtasks.map((s, i) => ({
+    index: i,
+    title: s.title,
+    ...extractDirectives(`${s.title} ${s.description || ""}`),
+  }));
+
+  // Compare each pair of subtasks
+  for (let i = 0; i < subtaskDirectives.length; i++) {
+    for (let j = i + 1; j < subtaskDirectives.length; j++) {
+      const a = subtaskDirectives[i];
+      const b = subtaskDirectives[j];
+
+      // Check if A's positive conflicts with B's negative
+      for (const posA of a.positive) {
+        for (const negB of b.negative) {
+          if (directivesConflict(posA, negB)) {
+            conflicts.push({
+              subtask_a: i,
+              subtask_b: j,
+              directive_a: posA,
+              directive_b: negB,
+              conflict_type: "positive_negative",
+              description: `Subtask ${i} says "${posA}" but subtask ${j} says "${negB}"`,
+            });
+          }
+        }
+      }
+
+      // Check if B's positive conflicts with A's negative
+      for (const posB of b.positive) {
+        for (const negA of a.negative) {
+          if (directivesConflict(posB, negA)) {
+            conflicts.push({
+              subtask_a: j,
+              subtask_b: i,
+              directive_a: posB,
+              directive_b: negA,
+              conflict_type: "positive_negative",
+              description: `Subtask ${j} says "${posB}" but subtask ${i} says "${negA}"`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+// ============================================================================
+// Prompt Templates
+// ============================================================================
+
+/**
+ * Prompt for decomposing a task into parallelizable subtasks.
+ *
+ * Used by swarm:decompose to instruct the agent on how to break down work.
+ * The agent responds with a BeadTree that gets validated.
+ */
+export const DECOMPOSITION_PROMPT = `You are decomposing a task into parallelizable subtasks for a swarm of agents.
+
+## Task
+{task}
+
+{context_section}
+
+## Requirements
+
+1. **Break into 2-{max_subtasks} independent subtasks** that can run in parallel
+2. **Assign files** - each subtask must specify which files it will modify
+3. **No file overlap** - files cannot appear in multiple subtasks (they get exclusive locks)
+4. **Order by dependency** - if subtask B needs subtask A's output, A must come first in the array
+5. **Estimate complexity** - 1 (trivial) to 5 (complex)
+
+## Response Format
+
+Respond with a JSON object matching this schema:
+
+\`\`\`typescript
+{
+  epic: {
+    title: string,        // Epic title for the beads tracker
+    description?: string  // Brief description of the overall goal
+  },
+  subtasks: [
+    {
+      title: string,              // What this subtask accomplishes
+      description?: string,       // Detailed instructions for the agent
+      files: string[],            // Files this subtask will modify (globs allowed)
+      dependencies: number[],     // Indices of subtasks this depends on (0-indexed)
+      estimated_complexity: 1-5   // Effort estimate
+    },
+    // ... more subtasks
+  ]
+}
+\`\`\`
+
+## Guidelines
+
+- **Prefer smaller, focused subtasks** over large complex ones
+- **Include test files** in the same subtask as the code they test
+- **Consider shared types** - if multiple files share types, handle that first
+- **Think about imports** - changes to exported APIs affect downstream files
+
+## File Assignment Examples
+
+- Schema change: \`["src/schemas/user.ts", "src/schemas/index.ts"]\`
+- Component + test: \`["src/components/Button.tsx", "src/components/Button.test.tsx"]\`
+- API route: \`["src/app/api/users/route.ts"]\`
+
+Now decompose the task:`;
+
+/**
+ * Prompt template for spawned subtask agents.
+ *
+ * Each agent receives this prompt with their specific subtask details filled in.
+ * The prompt establishes context, constraints, and expectations.
+ */
+export const SUBTASK_PROMPT = `You are a swarm agent working on a subtask of a larger epic.
+
+## Your Identity
+- **Agent Name**: {agent_name}
+- **Bead ID**: {bead_id}
+- **Epic ID**: {epic_id}
+
+## Your Subtask
+**Title**: {subtask_title}
+
+{subtask_description}
+
+## File Scope
+You have exclusive reservations for these files:
+{file_list}
+
+**CRITICAL**: Only modify files in your reservation. If you need to modify other files, 
+send a message to the coordinator requesting the change.
+
+## Shared Context
+{shared_context}
+
+## Coordination Protocol
+
+1. **Start**: Your bead is already marked in_progress
+2. **Progress**: Use swarm:progress to report status updates
+3. **Blocked**: If you hit a blocker, report it - don't spin
+4. **Complete**: Use swarm:complete when done - it handles:
+   - Closing your bead with a summary
+   - Releasing file reservations
+   - Notifying the coordinator
+
+## Self-Evaluation
+
+Before calling swarm:complete, evaluate your work:
+- Type safety: Does it compile without errors?
+- No obvious bugs: Did you handle edge cases?
+- Follows patterns: Does it match existing code style?
+- Readable: Would another developer understand it?
+
+If evaluation fails, fix the issues before completing.
+
+## Communication
+
+To message other agents or the coordinator:
+\`\`\`
+agent-mail:send(
+  to: ["coordinator_name" or other agent],
+  subject: "Brief subject",
+  body: "Message content",
+  thread_id: "{epic_id}"
+)
+\`\`\`
+
+Begin work on your subtask now.`;
+
+/**
+ * Prompt for self-evaluation before completing a subtask.
+ *
+ * Agents use this to assess their work quality before marking complete.
+ */
+export const EVALUATION_PROMPT = `Evaluate the work completed for this subtask.
+
+## Subtask
+**Bead ID**: {bead_id}
+**Title**: {subtask_title}
+
+## Files Modified
+{files_touched}
+
+## Evaluation Criteria
+
+For each criterion, assess passed/failed and provide brief feedback:
+
+1. **type_safe**: Code compiles without TypeScript errors
+2. **no_bugs**: No obvious bugs, edge cases handled
+3. **patterns**: Follows existing codebase patterns and conventions
+4. **readable**: Code is clear and maintainable
+
+## Response Format
+
+\`\`\`json
+{
+  "passed": boolean,        // Overall pass/fail
+  "criteria": {
+    "type_safe": { "passed": boolean, "feedback": string },
+    "no_bugs": { "passed": boolean, "feedback": string },
+    "patterns": { "passed": boolean, "feedback": string },
+    "readable": { "passed": boolean, "feedback": string }
+  },
+  "overall_feedback": string,
+  "retry_suggestion": string | null  // If failed, what to fix
+}
+\`\`\`
+
+If any criterion fails, the overall evaluation fails and retry_suggestion 
+should describe what needs to be fixed.`;
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class SwarmError extends Error {
+  constructor(
+    message: string,
+    public readonly operation: string,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "SwarmError";
+  }
+}
+
+export class DecompositionError extends SwarmError {
+  constructor(
+    message: string,
+    public readonly zodError?: z.ZodError,
+  ) {
+    super(message, "decompose", zodError?.issues);
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Format the decomposition prompt with actual values
+ */
+function formatDecompositionPrompt(
+  task: string,
+  maxSubtasks: number,
+  context?: string,
+): string {
+  const contextSection = context
+    ? `## Additional Context\n${context}`
+    : "## Additional Context\n(none provided)";
+
+  return DECOMPOSITION_PROMPT.replace("{task}", task)
+    .replace("{max_subtasks}", maxSubtasks.toString())
+    .replace("{context_section}", contextSection);
+}
+
+/**
+ * Format the subtask prompt for a specific agent
+ */
+export function formatSubtaskPrompt(params: {
+  agent_name: string;
+  bead_id: string;
+  epic_id: string;
+  subtask_title: string;
+  subtask_description: string;
+  files: string[];
+  shared_context?: string;
+}): string {
+  const fileList = params.files.map((f) => `- \`${f}\``).join("\n");
+
+  return SUBTASK_PROMPT.replace("{agent_name}", params.agent_name)
+    .replace("{bead_id}", params.bead_id)
+    .replace(/{epic_id}/g, params.epic_id)
+    .replace("{subtask_title}", params.subtask_title)
+    .replace("{subtask_description}", params.subtask_description || "(none)")
+    .replace("{file_list}", fileList || "(no files assigned)")
+    .replace("{shared_context}", params.shared_context || "(none)");
+}
+
+/**
+ * Format the evaluation prompt
+ */
+export function formatEvaluationPrompt(params: {
+  bead_id: string;
+  subtask_title: string;
+  files_touched: string[];
+}): string {
+  const filesList = params.files_touched.map((f) => `- \`${f}\``).join("\n");
+
+  return EVALUATION_PROMPT.replace("{bead_id}", params.bead_id)
+    .replace("{subtask_title}", params.subtask_title)
+    .replace("{files_touched}", filesList || "(no files recorded)");
+}
+
+/**
+ * Query beads for subtasks of an epic
+ */
+async function queryEpicSubtasks(epicId: string): Promise<Bead[]> {
+  const result = await Bun.$`bd list --parent ${epicId} --json`
+    .quiet()
+    .nothrow();
+
+  if (result.exitCode !== 0) {
+    throw new SwarmError(
+      `Failed to query subtasks: ${result.stderr.toString()}`,
+      "query_subtasks",
+    );
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout.toString());
+    return z.array(BeadSchema).parse(parsed);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      throw new SwarmError(
+        `Invalid bead data: ${error.message}`,
+        "query_subtasks",
+        error.issues,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Query Agent Mail for swarm thread messages
+ */
+async function querySwarmMessages(
+  projectKey: string,
+  threadId: string,
+): Promise<number> {
+  try {
+    interface ThreadSummary {
+      summary: { total_messages: number };
+    }
+    const summary = await mcpCall<ThreadSummary>("summarize_thread", {
+      project_key: projectKey,
+      thread_id: threadId,
+      llm_mode: false, // Just need the count
+    });
+    return summary.summary.total_messages;
+  } catch {
+    // Thread might not exist yet
+    return 0;
+  }
+}
+
+/**
+ * Format a progress message for Agent Mail
+ */
+function formatProgressMessage(progress: AgentProgress): string {
+  const lines = [
+    `**Status**: ${progress.status}`,
+    progress.progress_percent !== undefined
+      ? `**Progress**: ${progress.progress_percent}%`
+      : null,
+    progress.message ? `**Message**: ${progress.message}` : null,
+    progress.files_touched && progress.files_touched.length > 0
+      ? `**Files touched**:\n${progress.files_touched.map((f) => `- \`${f}\``).join("\n")}`
+      : null,
+    progress.blockers && progress.blockers.length > 0
+      ? `**Blockers**:\n${progress.blockers.map((b) => `- ${b}`).join("\n")}`
+      : null,
+  ];
+
+  return lines.filter(Boolean).join("\n\n");
+}
+
+// ============================================================================
+// CASS History Integration
+// ============================================================================
+
+/**
+ * CASS search result from similar past tasks
+ */
+interface CassSearchResult {
+  query: string;
+  results: Array<{
+    source_path: string;
+    line: number;
+    agent: string;
+    preview: string;
+    score: number;
+  }>;
+}
+
+/**
+ * Query CASS for similar past tasks
+ *
+ * @param task - Task description to search for
+ * @param limit - Maximum results to return
+ * @returns Search results or null if CASS unavailable
+ */
+async function queryCassHistory(
+  task: string,
+  limit: number = 3,
+): Promise<CassSearchResult | null> {
+  try {
+    const result = await Bun.$`cass search ${task} --limit ${limit} --json`
+      .quiet()
+      .nothrow();
+
+    if (result.exitCode === 127) {
+      // CASS not installed
+      return null;
+    }
+
+    if (result.exitCode !== 0) {
+      return null;
+    }
+
+    const output = result.stdout.toString();
+    if (!output.trim()) {
+      return { query: task, results: [] };
+    }
+
+    try {
+      const parsed = JSON.parse(output);
+      return {
+        query: task,
+        results: Array.isArray(parsed) ? parsed : parsed.results || [],
+      };
+    } catch {
+      return { query: task, results: [] };
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format CASS history for inclusion in decomposition prompt
+ */
+function formatCassHistoryForPrompt(history: CassSearchResult): string {
+  if (history.results.length === 0) {
+    return "";
+  }
+
+  const lines = [
+    "## Similar Past Tasks",
+    "",
+    "These similar tasks were found in agent history:",
+    "",
+    ...history.results.slice(0, 3).map((r, i) => {
+      const preview = r.preview.slice(0, 200).replace(/\n/g, " ");
+      return `${i + 1}. [${r.agent}] ${preview}...`;
+    }),
+    "",
+    "Consider patterns that worked in these past tasks.",
+    "",
+  ];
+
+  return lines.join("\n");
+}
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+/**
+ * Decompose a task into a bead tree
+ *
+ * This is a PROMPT tool - it returns a prompt for the agent to respond to.
+ * The agent's response (JSON) should be validated with BeadTreeSchema.
+ *
+ * Optionally queries CASS for similar past tasks to inform decomposition.
+ */
+export const swarm_decompose = tool({
+  description:
+    "Generate decomposition prompt for breaking task into parallelizable subtasks. Optionally queries CASS for similar past tasks.",
+  args: {
+    task: tool.schema.string().min(1).describe("Task description to decompose"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .default(5)
+      .describe("Maximum number of subtasks (default: 5)"),
+    context: tool.schema
+      .string()
+      .optional()
+      .describe("Additional context (codebase info, constraints, etc.)"),
+    query_cass: tool.schema
+      .boolean()
+      .optional()
+      .describe("Query CASS for similar past tasks (default: true)"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("Max CASS results to include (default: 3)"),
+  },
+  async execute(args) {
+    // Query CASS for similar past tasks
+    let cassContext = "";
+    let cassResult: CassSearchResult | null = null;
+
+    if (args.query_cass !== false) {
+      cassResult = await queryCassHistory(args.task, args.cass_limit ?? 3);
+      if (cassResult && cassResult.results.length > 0) {
+        cassContext = formatCassHistoryForPrompt(cassResult);
+      }
+    }
+
+    // Combine user context with CASS history
+    const fullContext = [args.context, cassContext]
+      .filter(Boolean)
+      .join("\n\n");
+
+    const prompt = formatDecompositionPrompt(
+      args.task,
+      args.max_subtasks ?? 5,
+      fullContext || undefined,
+    );
+
+    // Return the prompt and schema info for the caller
+    return JSON.stringify(
+      {
+        prompt,
+        expected_schema: "BeadTree",
+        schema_hint: {
+          epic: { title: "string", description: "string?" },
+          subtasks: [
+            {
+              title: "string",
+              description: "string?",
+              files: "string[]",
+              dependencies: "number[]",
+              estimated_complexity: "1-5",
+            },
+          ],
+        },
+        validation_note:
+          "Parse agent response as JSON and validate with BeadTreeSchema from schemas/bead.ts",
+        cass_history: cassResult
+          ? {
+              queried: true,
+              results_found: cassResult.results.length,
+              included_in_context: cassResult.results.length > 0,
+            }
+          : { queried: false, reason: "disabled or unavailable" },
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Validate a decomposition response from an agent
+ *
+ * Use this after the agent responds to swarm:decompose to validate the structure.
+ */
+export const swarm_validate_decomposition = tool({
+  description: "Validate a decomposition response against BeadTreeSchema",
+  args: {
+    response: tool.schema
+      .string()
+      .describe("JSON response from agent (BeadTree format)"),
+  },
+  async execute(args) {
+    try {
+      const parsed = JSON.parse(args.response);
+      const validated = BeadTreeSchema.parse(parsed);
+
+      // Additional validation: check for file conflicts
+      const allFiles = new Set<string>();
+      const conflicts: string[] = [];
+
+      for (const subtask of validated.subtasks) {
+        for (const file of subtask.files) {
+          if (allFiles.has(file)) {
+            conflicts.push(file);
+          }
+          allFiles.add(file);
+        }
+      }
+
+      if (conflicts.length > 0) {
+        return JSON.stringify(
+          {
+            valid: false,
+            error: `File conflicts detected: ${conflicts.join(", ")}`,
+            hint: "Each file can only be assigned to one subtask",
+          },
+          null,
+          2,
+        );
+      }
+
+      // Check dependency indices are valid
+      for (let i = 0; i < validated.subtasks.length; i++) {
+        const deps = validated.subtasks[i].dependencies;
+        for (const dep of deps) {
+          if (dep >= i) {
+            return JSON.stringify(
+              {
+                valid: false,
+                error: `Invalid dependency: subtask ${i} depends on ${dep}, but dependencies must be earlier in the array`,
+                hint: "Reorder subtasks so dependencies come before dependents",
+              },
+              null,
+              2,
+            );
+          }
+        }
+      }
+
+      // Check for instruction conflicts between subtasks
+      const instructionConflicts = detectInstructionConflicts(
+        validated.subtasks,
+      );
+
+      return JSON.stringify(
+        {
+          valid: true,
+          bead_tree: validated,
+          stats: {
+            subtask_count: validated.subtasks.length,
+            total_files: allFiles.size,
+            total_complexity: validated.subtasks.reduce(
+              (sum, s) => sum + s.estimated_complexity,
+              0,
+            ),
+          },
+          // Include conflicts as warnings (not blocking)
+          warnings:
+            instructionConflicts.length > 0
+              ? {
+                  instruction_conflicts: instructionConflicts,
+                  hint: "Review these potential conflicts between subtask instructions",
+                }
+              : undefined,
+        },
+        null,
+        2,
+      );
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return JSON.stringify(
+          {
+            valid: false,
+            error: "Schema validation failed",
+            details: error.issues,
+          },
+          null,
+          2,
+        );
+      }
+      if (error instanceof SyntaxError) {
+        return JSON.stringify(
+          {
+            valid: false,
+            error: "Invalid JSON",
+            details: error.message,
+          },
+          null,
+          2,
+        );
+      }
+      throw error;
+    }
+  },
+});
+
+/**
+ * Get status of a swarm by epic ID
+ *
+ * Requires project_key to query Agent Mail for message counts.
+ */
+export const swarm_status = tool({
+  description: "Get status of a swarm by epic ID",
+  args: {
+    epic_id: tool.schema.string().describe("Epic bead ID (e.g., bd-abc123)"),
+    project_key: tool.schema
+      .string()
+      .describe("Project path (for Agent Mail queries)"),
+  },
+  async execute(args) {
+    // Query subtasks from beads
+    const subtasks = await queryEpicSubtasks(args.epic_id);
+
+    // Count statuses
+    const statusCounts = {
+      running: 0,
+      completed: 0,
+      failed: 0,
+      blocked: 0,
+    };
+
+    const agents: SpawnedAgent[] = [];
+
+    for (const bead of subtasks) {
+      // Map bead status to agent status
+      let agentStatus: SpawnedAgent["status"] = "pending";
+      switch (bead.status) {
+        case "in_progress":
+          agentStatus = "running";
+          statusCounts.running++;
+          break;
+        case "closed":
+          agentStatus = "completed";
+          statusCounts.completed++;
+          break;
+        case "blocked":
+          agentStatus = "pending"; // Blocked treated as pending for swarm
+          statusCounts.blocked++;
+          break;
+        default:
+          // open = pending
+          break;
+      }
+
+      agents.push({
+        bead_id: bead.id,
+        agent_name: "", // We don't track this in beads
+        status: agentStatus,
+        files: [], // Would need to parse from description
+      });
+    }
+
+    // Query Agent Mail for message activity
+    const messageCount = await querySwarmMessages(
+      args.project_key,
+      args.epic_id,
+    );
+
+    const status: SwarmStatus = {
+      epic_id: args.epic_id,
+      total_agents: subtasks.length,
+      running: statusCounts.running,
+      completed: statusCounts.completed,
+      failed: statusCounts.failed,
+      blocked: statusCounts.blocked,
+      agents,
+      last_update: new Date().toISOString(),
+    };
+
+    // Validate and return
+    const validated = SwarmStatusSchema.parse(status);
+
+    return JSON.stringify(
+      {
+        ...validated,
+        message_count: messageCount,
+        progress_percent:
+          subtasks.length > 0
+            ? Math.round((statusCounts.completed / subtasks.length) * 100)
+            : 0,
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Report progress on a subtask
+ *
+ * Takes explicit agent identity since tools don't have persistent state.
+ */
+export const swarm_progress = tool({
+  description: "Report progress on a subtask to coordinator",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    agent_name: tool.schema.string().describe("Your Agent Mail name"),
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    status: tool.schema
+      .enum(["in_progress", "blocked", "completed", "failed"])
+      .describe("Current status"),
+    message: tool.schema
+      .string()
+      .optional()
+      .describe("Progress message or blockers"),
+    progress_percent: tool.schema
+      .number()
+      .min(0)
+      .max(100)
+      .optional()
+      .describe("Completion percentage"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified so far"),
+  },
+  async execute(args) {
+    // Build progress report
+    const progress: AgentProgress = {
+      bead_id: args.bead_id,
+      agent_name: args.agent_name,
+      status: args.status,
+      progress_percent: args.progress_percent,
+      message: args.message,
+      files_touched: args.files_touched,
+      timestamp: new Date().toISOString(),
+    };
+
+    // Validate
+    const validated = AgentProgressSchema.parse(progress);
+
+    // Update bead status if needed
+    if (args.status === "blocked" || args.status === "in_progress") {
+      const beadStatus = args.status === "blocked" ? "blocked" : "in_progress";
+      await Bun.$`bd update ${args.bead_id} --status ${beadStatus} --json`
+        .quiet()
+        .nothrow();
+    }
+
+    // Extract epic ID from bead ID (e.g., bd-abc123.1 -> bd-abc123)
+    const epicId = args.bead_id.includes(".")
+      ? args.bead_id.split(".")[0]
+      : args.bead_id;
+
+    // Send progress message to thread
+    await mcpCall("send_message", {
+      project_key: args.project_key,
+      sender_name: args.agent_name,
+      to: [], // Coordinator will pick it up from thread
+      subject: `Progress: ${args.bead_id} - ${args.status}`,
+      body_md: formatProgressMessage(validated),
+      thread_id: epicId,
+      importance: args.status === "blocked" ? "high" : "normal",
+    });
+
+    return `Progress reported: ${args.status}${args.progress_percent !== undefined ? ` (${args.progress_percent}%)` : ""}`;
+  },
+});
+
+/**
+ * UBS scan result schema
+ */
+interface UbsScanResult {
+  exitCode: number;
+  bugs: Array<{
+    file: string;
+    line: number;
+    severity: string;
+    message: string;
+    category: string;
+  }>;
+  summary: {
+    total: number;
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+  };
+}
+
+/**
+ * Run UBS scan on files before completion
+ *
+ * @param files - Files to scan
+ * @returns Scan result or null if UBS not available
+ */
+async function runUbsScan(files: string[]): Promise<UbsScanResult | null> {
+  if (files.length === 0) {
+    return null;
+  }
+
+  try {
+    // Run UBS scan with JSON output
+    const result = await Bun.$`ubs scan ${files.join(" ")} --json`
+      .quiet()
+      .nothrow();
+
+    if (result.exitCode === 127) {
+      // UBS not installed
+      return null;
+    }
+
+    const output = result.stdout.toString();
+    if (!output.trim()) {
+      return {
+        exitCode: result.exitCode,
+        bugs: [],
+        summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+      };
+    }
+
+    try {
+      const parsed = JSON.parse(output);
+      return {
+        exitCode: result.exitCode,
+        bugs: parsed.bugs || [],
+        summary: parsed.summary || {
+          total: 0,
+          critical: 0,
+          high: 0,
+          medium: 0,
+          low: 0,
+        },
+      };
+    } catch {
+      // UBS output wasn't JSON, return basic result
+      return {
+        exitCode: result.exitCode,
+        bugs: [],
+        summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+      };
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Mark a subtask as complete
+ *
+ * Closes bead, releases reservations, notifies coordinator.
+ * Optionally runs UBS scan on modified files before completion.
+ */
+export const swarm_complete = tool({
+  description:
+    "Mark subtask complete, release reservations, notify coordinator. Runs UBS bug scan if files_touched provided.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    agent_name: tool.schema.string().describe("Your Agent Mail name"),
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    summary: tool.schema.string().describe("Brief summary of work done"),
+    evaluation: tool.schema
+      .string()
+      .optional()
+      .describe("Self-evaluation JSON (Evaluation schema)"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified - will be scanned by UBS for bugs"),
+    skip_ubs_scan: tool.schema
+      .boolean()
+      .optional()
+      .describe("Skip UBS bug scan (default: false)"),
+  },
+  async execute(args) {
+    // Run UBS scan on modified files if provided
+    let ubsResult: UbsScanResult | null = null;
+    if (
+      args.files_touched &&
+      args.files_touched.length > 0 &&
+      !args.skip_ubs_scan
+    ) {
+      ubsResult = await runUbsScan(args.files_touched);
+
+      // Block completion if critical bugs found
+      if (ubsResult && ubsResult.summary.critical > 0) {
+        return JSON.stringify(
+          {
+            success: false,
+            error: "UBS found critical bugs - fix before completing",
+            ubs_scan: {
+              critical_count: ubsResult.summary.critical,
+              bugs: ubsResult.bugs.filter((b) => b.severity === "critical"),
+            },
+            hint: "Fix the critical bugs and try again, or use skip_ubs_scan=true to bypass",
+          },
+          null,
+          2,
+        );
+      }
+    }
+
+    // Parse and validate evaluation if provided
+    let parsedEvaluation: Evaluation | undefined;
+    if (args.evaluation) {
+      try {
+        parsedEvaluation = EvaluationSchema.parse(JSON.parse(args.evaluation));
+      } catch (error) {
+        return JSON.stringify(
+          {
+            success: false,
+            error: "Invalid evaluation format",
+            details: error instanceof z.ZodError ? error.issues : String(error),
+          },
+          null,
+          2,
+        );
+      }
+
+      // If evaluation failed, don't complete
+      if (!parsedEvaluation.passed) {
+        return JSON.stringify(
+          {
+            success: false,
+            error: "Self-evaluation failed",
+            retry_suggestion: parsedEvaluation.retry_suggestion,
+            feedback: parsedEvaluation.overall_feedback,
+          },
+          null,
+          2,
+        );
+      }
+    }
+
+    // Close the bead
+    const closeResult =
+      await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`
+        .quiet()
+        .nothrow();
+
+    if (closeResult.exitCode !== 0) {
+      throw new SwarmError(
+        `Failed to close bead: ${closeResult.stderr.toString()}`,
+        "complete",
+      );
+    }
+
+    // Release file reservations for this agent
+    await mcpCall("release_file_reservations", {
+      project_key: args.project_key,
+      agent_name: args.agent_name,
+    });
+
+    // Extract epic ID
+    const epicId = args.bead_id.includes(".")
+      ? args.bead_id.split(".")[0]
+      : args.bead_id;
+
+    // Send completion message
+    const completionBody = [
+      `## Subtask Complete: ${args.bead_id}`,
+      "",
+      `**Summary**: ${args.summary}`,
+      "",
+      parsedEvaluation
+        ? `**Self-Evaluation**: ${parsedEvaluation.passed ? "PASSED" : "FAILED"}`
+        : "",
+      parsedEvaluation?.overall_feedback
+        ? `**Feedback**: ${parsedEvaluation.overall_feedback}`
+        : "",
+    ]
+      .filter(Boolean)
+      .join("\n");
+
+    await mcpCall("send_message", {
+      project_key: args.project_key,
+      sender_name: args.agent_name,
+      to: [], // Thread broadcast
+      subject: `Complete: ${args.bead_id}`,
+      body_md: completionBody,
+      thread_id: epicId,
+      importance: "normal",
+    });
+
+    return JSON.stringify(
+      {
+        success: true,
+        bead_id: args.bead_id,
+        closed: true,
+        reservations_released: true,
+        message_sent: true,
+        ubs_scan: ubsResult
+          ? {
+              ran: true,
+              bugs_found: ubsResult.summary.total,
+              summary: ubsResult.summary,
+              warnings: ubsResult.bugs.filter((b) => b.severity !== "critical"),
+            }
+          : {
+              ran: false,
+              reason: args.skip_ubs_scan
+                ? "skipped"
+                : "no files or ubs unavailable",
+            },
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Record outcome signals from a completed subtask
+ *
+ * Tracks implicit feedback (duration, errors, retries) to score
+ * decomposition quality over time. This data feeds into criterion
+ * weight calculations.
+ *
+ * @see src/learning.ts for scoring logic
+ */
+export const swarm_record_outcome = tool({
+  description:
+    "Record subtask outcome for implicit feedback scoring. Tracks duration, errors, retries to learn decomposition quality.",
+  args: {
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    duration_ms: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .describe("Duration in milliseconds"),
+    error_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .default(0)
+      .describe("Number of errors encountered"),
+    retry_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .default(0)
+      .describe("Number of retry attempts"),
+    success: tool.schema.boolean().describe("Whether the subtask succeeded"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files that were modified"),
+    criteria: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe(
+        "Criteria to generate feedback for (default: all default criteria)",
+      ),
+  },
+  async execute(args) {
+    // Build outcome signals
+    const signals: OutcomeSignals = {
+      bead_id: args.bead_id,
+      duration_ms: args.duration_ms,
+      error_count: args.error_count ?? 0,
+      retry_count: args.retry_count ?? 0,
+      success: args.success,
+      files_touched: args.files_touched ?? [],
+      timestamp: new Date().toISOString(),
+    };
+
+    // Validate signals
+    const validated = OutcomeSignalsSchema.parse(signals);
+
+    // Score the outcome
+    const scored: ScoredOutcome = scoreImplicitFeedback(
+      validated,
+      DEFAULT_LEARNING_CONFIG,
+    );
+
+    // Generate feedback events for each criterion
+    const criteriaToScore = args.criteria ?? [
+      "type_safe",
+      "no_bugs",
+      "patterns",
+      "readable",
+    ];
+    const feedbackEvents: FeedbackEvent[] = criteriaToScore.map((criterion) =>
+      outcomeToFeedback(scored, criterion),
+    );
+
+    return JSON.stringify(
+      {
+        success: true,
+        outcome: {
+          signals: validated,
+          scored: {
+            type: scored.type,
+            decayed_value: scored.decayed_value,
+            reasoning: scored.reasoning,
+          },
+        },
+        feedback_events: feedbackEvents,
+        summary: {
+          feedback_type: scored.type,
+          duration_seconds: Math.round(args.duration_ms / 1000),
+          error_count: args.error_count ?? 0,
+          retry_count: args.retry_count ?? 0,
+          success: args.success,
+        },
+        note: "Feedback events should be stored for criterion weight calculation. Use learning.ts functions to apply weights.",
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * Generate subtask prompt for a spawned agent
+ */
+export const swarm_subtask_prompt = tool({
+  description: "Generate the prompt for a spawned subtask agent",
+  args: {
+    agent_name: tool.schema.string().describe("Agent Mail name for the agent"),
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Detailed subtask instructions"),
+    files: tool.schema
+      .array(tool.schema.string())
+      .describe("Files assigned to this subtask"),
+    shared_context: tool.schema
+      .string()
+      .optional()
+      .describe("Context shared across all agents"),
+  },
+  async execute(args) {
+    const prompt = formatSubtaskPrompt({
+      agent_name: args.agent_name,
+      bead_id: args.bead_id,
+      epic_id: args.epic_id,
+      subtask_title: args.subtask_title,
+      subtask_description: args.subtask_description || "",
+      files: args.files,
+      shared_context: args.shared_context,
+    });
+
+    return prompt;
+  },
+});
+
+/**
+ * Generate self-evaluation prompt
+ */
+export const swarm_evaluation_prompt = tool({
+  description: "Generate self-evaluation prompt for a completed subtask",
+  args: {
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .describe("Files that were modified"),
+  },
+  async execute(args) {
+    const prompt = formatEvaluationPrompt({
+      bead_id: args.bead_id,
+      subtask_title: args.subtask_title,
+      files_touched: args.files_touched,
+    });
+
+    return JSON.stringify(
+      {
+        prompt,
+        expected_schema: "Evaluation",
+        schema_hint: {
+          passed: "boolean",
+          criteria: {
+            type_safe: { passed: "boolean", feedback: "string" },
+            no_bugs: { passed: "boolean", feedback: "string" },
+            patterns: { passed: "boolean", feedback: "string" },
+            readable: { passed: "boolean", feedback: "string" },
+          },
+          overall_feedback: "string",
+          retry_suggestion: "string | null",
+        },
+      },
+      null,
+      2,
+    );
+  },
+});
+
+// ============================================================================
+// Export all tools
+// ============================================================================
+
+export const swarmTools = {
+  swarm_decompose: swarm_decompose,
+  swarm_validate_decomposition: swarm_validate_decomposition,
+  swarm_status: swarm_status,
+  swarm_progress: swarm_progress,
+  swarm_complete: swarm_complete,
+  swarm_record_outcome: swarm_record_outcome,
+  swarm_subtask_prompt: swarm_subtask_prompt,
+  swarm_evaluation_prompt: swarm_evaluation_prompt,
+};