opencode-swarm-plugin 0.36.1 → 0.38.0

package/dist/swarm.d.ts

@@ -488,9 +488,24 @@ export declare const swarmTools: {
         description: string;
         args: {
             response: import("zod").ZodString;
+            project_path: import("zod").ZodOptional<import("zod").ZodString>;
+            task: import("zod").ZodOptional<import("zod").ZodString>;
+            context: import("zod").ZodOptional<import("zod").ZodString>;
+            strategy: import("zod").ZodOptional<import("zod").ZodEnum<{
+                "file-based": "file-based";
+                "feature-based": "feature-based";
+                "risk-based": "risk-based";
+                auto: "auto";
+            }>>;
+            epic_id: import("zod").ZodOptional<import("zod").ZodString>;
         };
         execute(args: {
             response: string;
+            project_path?: string | undefined;
+            task?: string | undefined;
+            context?: string | undefined;
+            strategy?: "file-based" | "feature-based" | "risk-based" | "auto" | undefined;
+            epic_id?: string | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
     };
     swarm_delegate_planning: {

package/dist/swarm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../src/swarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AASjC;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMtB,CAAC"}
+{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../src/swarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AASjC;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMtB,CAAC"}

package/evals/README.md

@@ -5,14 +5,12 @@ TypeScript-native evaluation framework for testing swarm task decomposition qual
 ## Quick Start
 
 ```bash
-# Watch mode for development
-pnpm eval:dev
-
 # Run all evals once
-pnpm eval:run
+bun run eval:run
 
-# CI mode with 80% threshold
-pnpm eval:ci
+# Run specific eval suite
+bun run eval:decomposition
+bun run eval:coordinator
 ```
 
 ## Structure
@@ -134,13 +132,32 @@ Scores coordinator discipline during swarm sessions.
 bunx evalite run evals/coordinator-session.eval.ts
 ```
 
-## Data Loaders
+## Data Capture
+
+### What Gets Captured
+
+**Decomposition Eval Data:**
+- Task input (user's original request)
+- Generated CellTree JSON (epic + subtasks)
+- Timestamp and context
+- Stored in: `.opencode/eval-data.jsonl`
+
+**Coordinator Session Data:**
+- Real swarm sessions captured during `/swarm` runs
+- Includes: decomposition, spawn events, reviews, violations
+- Stored in: `~/.config/swarm-tools/sessions/*.jsonl`
+
+**Subtask Outcome Data:**
+- Duration, success/failure, error count, retry count
+- Files touched, strategy used
+- Used for learning and pattern maturity
+- Stored in: swarm-mail database (libSQL)
 
-### lib/data-loader.ts
+### Data Loaders
 
-Loads eval data from multiple sources:
+**lib/data-loader.ts** provides utilities to load eval data:
 
-- `loadEvalCases()` - PGlite eval_records table
+- `loadEvalCases()` - Load eval records from swarm-mail database
 - `loadCapturedSessions()` - Real coordinator sessions from `~/.config/swarm-tools/sessions/`
 - `hasRealEvalData()` - Check if enough real data exists
 - `getEvalDataSummary()` - Stats about available eval data

package/examples/plugin-wrapper-template.ts

@@ -305,6 +305,34 @@ const hive_sync = tool({
   execute: (args, ctx) => execTool("hive_sync", args, ctx),
 });
 
+const hive_cells = tool({
+  description: `Query cells from the hive database with flexible filtering.
+
+USE THIS TOOL TO:
+- List all open cells: hive_cells()
+- Find cells by status: hive_cells({ status: "in_progress" })
+- Find cells by type: hive_cells({ type: "bug" })
+- Get a specific cell by partial ID: hive_cells({ id: "mjkmd" })
+- Get the next ready (unblocked) cell: hive_cells({ ready: true })
+- Combine filters: hive_cells({ status: "open", type: "task" })
+
+RETURNS: Array of cells with id, title, status, priority, type, parent_id, created_at, updated_at
+
+PREFER THIS OVER hive_query when you need to:
+- See what work is available
+- Check status of multiple cells
+- Find cells matching criteria
+- Look up a cell by partial ID`,
+  args: {
+    id: tool.schema.string().optional().describe("Partial or full cell ID to look up"),
+    status: tool.schema.enum(["open", "in_progress", "blocked", "closed"]).optional().describe("Filter by status"),
+    type: tool.schema.enum(["task", "bug", "feature", "epic", "chore"]).optional().describe("Filter by type"),
+    ready: tool.schema.boolean().optional().describe("If true, return only the next unblocked cell"),
+    limit: tool.schema.number().optional().describe("Max cells to return (default 20)"),
+  },
+  execute: (args, ctx) => execTool("hive_cells", args, ctx),
+});
+
 const beads_link_thread = tool({
   description: "Add metadata linking bead to Agent Mail thread",
   args: {
@@ -1202,9 +1230,18 @@ ${JSON.stringify(snapshot, null, 2)}
 
 Generate a prompt following this structure:
 
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│             🐝  YOU ARE THE COORDINATOR  🐝                 │
+│                                                             │
+│             NOT A WORKER. NOT AN IMPLEMENTER.               │
+│                  YOU ORCHESTRATE.                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
 # 🐝 Swarm Continuation - [Epic Title or "Unknown"]
 
-You are resuming coordination of an active swarm that was interrupted by context compaction.
+**NON-NEGOTIABLE: YOU ARE THE COORDINATOR.** You resumed after context compaction.
 
 ## Epic State
 
@@ -1231,15 +1268,29 @@ You are resuming coordination of an active swarm that was interrupted by context
 
 [List 3-5 concrete actions with actual commands, using real IDs from the state]
 
-## Coordinator Reminders
+## 🎯 COORDINATOR MANDATES (NON-NEGOTIABLE)
+
+**YOU ARE THE COORDINATOR. NOT A WORKER.**
+
+### ⛔ FORBIDDEN - NEVER do these:
+- ❌ NEVER use \`edit\`, \`write\`, or \`bash\` for implementation - SPAWN A WORKER
+- ❌ NEVER fetch directly with \`repo-crawl_*\`, \`repo-autopsy_*\`, \`webfetch\`, \`fetch_fetch\` - SPAWN A RESEARCHER
+- ❌ NEVER use \`context7_*\` or \`pdf-brain_*\` directly - SPAWN A RESEARCHER
+- ❌ NEVER reserve files - Workers reserve files
+
+### ✅ ALWAYS do these:
+- ✅ ALWAYS check \`swarm_status\` and \`swarmmail_inbox\` first
+- ✅ ALWAYS use \`swarm_spawn_subtask\` for implementation work
+- ✅ ALWAYS use \`swarm_spawn_researcher\` for external data fetching
+- ✅ ALWAYS review worker output with \`swarm_review\` → \`swarm_review_feedback\`
+- ✅ ALWAYS monitor actively - Check messages every ~10 minutes
+- ✅ ALWAYS unblock aggressively - Resolve dependencies immediately
+
+**If you need external data:** Use \`swarm_spawn_researcher\` with a clear research task. The researcher will fetch, summarize, and return findings.
 
-- **You are the coordinator** - Don't wait for instructions, orchestrate
-- **Monitor actively** - Check messages every ~10 minutes
-- **Unblock aggressively** - Resolve dependencies immediately
-- **Review thoroughly** - 3-strike rule enforced
-- **Ship it** - When all subtasks done, close the epic
+**3-strike rule enforced:** Workers get 3 review attempts. After 3 rejections, escalate to human.
 
-Keep the prompt concise but actionable. Use actual data from the snapshot, not placeholders.`;
+Keep the prompt concise but actionable. Use actual data from the snapshot, not placeholders. Include the ASCII header and ALL coordinator mandates.`;
 
     logCompaction("debug", "generate_compaction_prompt_calling_llm", {
       session_id: snapshot.sessionID,
@@ -1896,6 +1947,7 @@ const SwarmPlugin: Plugin = async (
       hive_close,
       hive_start,
       hive_ready,
+      hive_cells,
       hive_sync,
       beads_link_thread,
       // Swarm Mail (Embedded)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.36.1",
+  "version": "0.38.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,9 @@
     "test:all": "bun test --timeout 60000 src/",
     "test:watch": "bun test --watch src/",
     "typecheck": "tsc --noEmit",
+    "eval:run": "bunx evalite run evals/",
+    "eval:decomposition": "bunx evalite run evals/swarm-decomposition.eval.ts",
+    "eval:coordinator": "bunx evalite run evals/coordinator-session.eval.ts",
     "postinstall": "node -e \"console.log('\\n\\x1b[33m  Run \\x1b[36mswarm setup\\x1b[33m to configure OpenCode integration\\x1b[0m\\n')\""
   },
   "dependencies": {

package/src/compaction-hook.test.ts

@@ -64,7 +64,7 @@ describe("Compaction Hook", () => {
   describe("SWARM_COMPACTION_CONTEXT", () => {
     it("contains coordinator instructions", () => {
       expect(SWARM_COMPACTION_CONTEXT).toContain("COORDINATOR");
-      expect(SWARM_COMPACTION_CONTEXT).toContain("You Are The COORDINATOR");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("YOU ARE THE COORDINATOR");
     });
 
     it("contains prohibition-first anti-patterns", () => {
@@ -136,7 +136,7 @@ describe("Compaction Hook", () => {
     it("HIGH confidence triggers full context", async () => {
       // This would need proper mocking of active reservations
       // For now, just verify the context strings exist
-      expect(SWARM_COMPACTION_CONTEXT).toContain("SWARM ACTIVE");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("YOU ARE THE COORDINATOR");
     });
 
     it("LOW confidence triggers fallback prompt", async () => {
@@ -145,6 +145,101 @@ describe("Compaction Hook", () => {
     });
   });
 
+  describe("Forbidden tools anti-pattern (TDD red phase)", () => {
+    it("SWARM_COMPACTION_CONTEXT includes 'NEVER fetch directly' rule", () => {
+      // Should warn against direct fetching
+      expect(SWARM_COMPACTION_CONTEXT).toContain("NEVER");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("repo-crawl");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("webfetch");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("fetch_fetch");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("context7");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("pdf-brain");
+    });
+
+    it("SWARM_COMPACTION_CONTEXT instructs to spawn researcher instead", () => {
+      expect(SWARM_COMPACTION_CONTEXT).toContain("SPAWN A RESEARCHER");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("swarm_spawn_researcher");
+    });
+
+    it("lists all forbidden repo-crawl tools", () => {
+      const forbiddenTools = [
+        "repo-crawl_file",
+        "repo-crawl_readme", 
+        "repo-crawl_search",
+        "repo-crawl_structure",
+        "repo-crawl_tree"
+      ];
+      
+      for (const tool of forbiddenTools) {
+        expect(SWARM_COMPACTION_CONTEXT).toContain(tool);
+      }
+    });
+
+    it("lists all forbidden repo-autopsy tools", () => {
+      expect(SWARM_COMPACTION_CONTEXT).toContain("repo-autopsy");
+    });
+
+    it("lists all forbidden context7 tools", () => {
+      const forbiddenTools = [
+        "context7_resolve-library-id",
+        "context7_get-library-docs"
+      ];
+      
+      for (const tool of forbiddenTools) {
+        expect(SWARM_COMPACTION_CONTEXT).toContain(tool);
+      }
+    });
+
+    it("lists all forbidden pdf-brain tools", () => {
+      const forbiddenTools = [
+        "pdf-brain_search",
+        "pdf-brain_read"
+      ];
+      
+      for (const tool of forbiddenTools) {
+        expect(SWARM_COMPACTION_CONTEXT).toContain(tool);
+      }
+    });
+  });
+
+  describe("Coordinator identity reinforcement (TDD red phase)", () => {
+    it("includes ASCII header for coordinator identity", () => {
+      // Should have prominent visual indicator
+      expect(SWARM_COMPACTION_CONTEXT).toMatch(/[╔═╗║╚╝]|[┌─┐│└┘]|[█▀▄]/);
+    });
+
+    it("repeats 'YOU ARE THE COORDINATOR' multiple times", () => {
+      const matches = SWARM_COMPACTION_CONTEXT.match(/YOU ARE THE COORDINATOR/gi);
+      expect(matches).toBeDefined();
+      expect(matches!.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it("uses strong imperative language NEVER/ALWAYS/NON-NEGOTIABLE", () => {
+      expect(SWARM_COMPACTION_CONTEXT).toContain("NEVER");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("ALWAYS");
+      expect(SWARM_COMPACTION_CONTEXT).toContain("NON-NEGOTIABLE");
+    });
+
+    it("makes role unmistakable with multiple strong statements", () => {
+      // Check for strong coordinator identity statements
+      const identityPatterns = [
+        /YOU ARE THE COORDINATOR/i,
+        /NOT A WORKER/i,
+        /ORCHESTRATE/i,
+        /DO NOT IMPLEMENT/i
+      ];
+
+      let matchCount = 0;
+      for (const pattern of identityPatterns) {
+        if (pattern.test(SWARM_COMPACTION_CONTEXT)) {
+          matchCount++;
+        }
+      }
+
+      expect(matchCount).toBeGreaterThanOrEqual(3);
+    });
+  });
+
   describe("Specific swarm state injection (TDD red phase)", () => {
     it("includes specific epic ID when in_progress epic exists", async () => {
       // Mock hive with an in_progress epic

package/src/compaction-hook.ts

@@ -68,9 +68,21 @@ function getLog() {
  * This is NOT about preserving state for a human - it's about the swarm continuing
  * autonomously after context compression.
  */
-export const SWARM_COMPACTION_CONTEXT = `## 🐝 SWARM ACTIVE - You Are The COORDINATOR
+export const SWARM_COMPACTION_CONTEXT = `
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│             🐝  YOU ARE THE COORDINATOR  🐝                 │
+│                                                             │
+│             NOT A WORKER. NOT AN IMPLEMENTER.               │
+│                  YOU ORCHESTRATE.                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
 
-Context was compacted but the swarm is still running. You are the **COORDINATOR**.
+## 🎯 NON-NEGOTIABLE: YOU ARE THE COORDINATOR
+
+Context was compacted but the swarm is still running. **YOU ARE THE COORDINATOR.**
+
+Your role is ORCHESTRATION, not implementation. When you catch yourself about to do work directly, STOP.
 
 ### ⛔ NEVER DO THESE (Coordinator Anti-Patterns)
 
@@ -81,9 +93,27 @@ Context was compacted but the swarm is still running. You are the **COORDINATOR*
 - ❌ **NEVER** implement features yourself - SPAWN A WORKER
 - ❌ **NEVER** "just do it myself to save time" - NO. SPAWN A WORKER.
 - ❌ **NEVER** reserve files with \`swarmmail_reserve\` - Workers reserve files
+- ❌ **NEVER** fetch files/docs directly - SPAWN A RESEARCHER
 
 **If you catch yourself about to edit a file, STOP. Use \`swarm_spawn_subtask\` instead.**
 
+### 🚫 FORBIDDEN TOOLS (Coordinators MUST delegate these)
+
+**NEVER use these tools directly. ALWAYS spawn a researcher worker via \`swarm_spawn_researcher\`:**
+
+**Repository fetching:**
+- \`repo-crawl_file\`, \`repo-crawl_readme\`, \`repo-crawl_search\`, \`repo-crawl_structure\`, \`repo-crawl_tree\`
+- \`repo-autopsy_*\` (all repo-autopsy tools)
+
+**Web/documentation fetching:**
+- \`webfetch\`, \`fetch_fetch\`
+- \`context7_resolve-library-id\`, \`context7_get-library-docs\`
+
+**Knowledge base:**
+- \`pdf-brain_search\`, \`pdf-brain_read\`
+
+**If you need external data:** Use \`swarm_spawn_researcher\` with a clear research task. The researcher will fetch, summarize, and return findings.
+
 ### ✅ ALWAYS DO THESE (Coordinator Checklist)
 
 On resume, execute this checklist IN ORDER:

package/src/hive.integration.test.ts

@@ -1895,6 +1895,154 @@ describe("beads integration", () => {
     });
   });
 
+  describe("hive_cells", () => {
+    let testCellId: string;
+
+    beforeEach(async () => {
+      // Create a test cell for hive_cells tests
+      const result = await hive_create.execute(
+        { title: "Cells tool test", type: "task" },
+        mockContext,
+      );
+      const cell = parseResponse<Cell>(result);
+      testCellId = cell.id;
+      createdBeadIds.push(testCellId);
+    });
+
+    it("lists all cells with no filters", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({}, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      expect(cells.length).toBeGreaterThan(0);
+    });
+
+    it("filters by status", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ status: "open" }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      expect(cells.every((c) => c.status === "open")).toBe(true);
+    });
+
+    it("filters by type", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      // Create a bug cell
+      const bugResult = await hive_create.execute(
+        { title: "Bug for cells test", type: "bug" },
+        mockContext,
+      );
+      const bug = parseResponse<Cell>(bugResult);
+      createdBeadIds.push(bug.id);
+
+      const result = await hive_cells.execute({ type: "bug" }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      expect(cells.every((c) => c.issue_type === "bug")).toBe(true);
+    });
+
+    it("returns next ready cell when ready=true", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ ready: true }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(Array.isArray(cells)).toBe(true);
+      // Should return 0 or 1 cells (the next ready one)
+      expect(cells.length).toBeLessThanOrEqual(1);
+      if (cells.length === 1) {
+        expect(["open", "in_progress"]).toContain(cells[0].status);
+      }
+    });
+
+    it("looks up cell by partial ID", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      // Extract hash from full ID (6-char segment before the last hyphen)
+      const lastHyphenIndex = testCellId.lastIndexOf("-");
+      const beforeLast = testCellId.substring(0, lastHyphenIndex);
+      const secondLastHyphenIndex = beforeLast.lastIndexOf("-");
+      const hash = testCellId.substring(secondLastHyphenIndex + 1, lastHyphenIndex);
+      
+      // Use last 6 chars of hash (or full hash if short)
+      const shortHash = hash.substring(Math.max(0, hash.length - 6));
+
+      try {
+        const result = await hive_cells.execute({ id: shortHash }, mockContext);
+        const cells = parseResponse<Cell[]>(result);
+
+        // Should return exactly one cell matching the ID
+        expect(cells).toHaveLength(1);
+        expect(cells[0].id).toBe(testCellId);
+      } catch (error) {
+        // If ambiguous, verify error message is helpful
+        if (error instanceof Error && error.message.includes("Ambiguous")) {
+          expect(error.message).toMatch(/ambiguous.*multiple/i);
+          expect(error.message).toContain(shortHash);
+        } else {
+          throw error;
+        }
+      }
+    });
+
+    it("looks up cell by full ID", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ id: testCellId }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(cells).toHaveLength(1);
+      expect(cells[0].id).toBe(testCellId);
+      expect(cells[0].title).toBe("Cells tool test");
+    });
+
+    it("throws error for non-existent ID", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      await expect(
+        hive_cells.execute({ id: "nonexistent999" }, mockContext),
+      ).rejects.toThrow(/not found|no cell|nonexistent999/i);
+    });
+
+    it("respects limit parameter", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      const result = await hive_cells.execute({ limit: 2 }, mockContext);
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(cells.length).toBeLessThanOrEqual(2);
+    });
+
+    it("combines filters (status + type + limit)", async () => {
+      const { hive_cells } = await import("./hive");
+      
+      // Create some task cells
+      for (let i = 0; i < 3; i++) {
+        const r = await hive_create.execute(
+          { title: `Task ${i}`, type: "task" },
+          mockContext,
+        );
+        const c = parseResponse<Cell>(r);
+        createdBeadIds.push(c.id);
+      }
+
+      const result = await hive_cells.execute(
+        { status: "open", type: "task", limit: 2 },
+        mockContext,
+      );
+      const cells = parseResponse<Cell[]>(result);
+
+      expect(cells.length).toBeLessThanOrEqual(2);
+      expect(cells.every((c) => c.status === "open" && c.issue_type === "task")).toBe(true);
+    });
+  });
+
   describe("bigint to Date conversion", () => {
     it("should handle PGLite bigint timestamps correctly in hive_query", async () => {
       const { mkdirSync, rmSync } = await import("node:fs");

package/src/hive.ts

@@ -1092,6 +1092,94 @@ export const hive_ready = tool({
   },
 });
 
+/**
+ * Query cells from the hive database with flexible filtering
+ */
+export const hive_cells = tool({
+  description: `Query cells from the hive database with flexible filtering.
+
+USE THIS TOOL TO:
+- List all open cells: hive_cells()
+- Find cells by status: hive_cells({ status: "in_progress" })
+- Find cells by type: hive_cells({ type: "bug" })
+- Get a specific cell by partial ID: hive_cells({ id: "mjkmd" })
+- Get the next ready (unblocked) cell: hive_cells({ ready: true })
+- Combine filters: hive_cells({ status: "open", type: "task" })
+
+RETURNS: Array of cells with id, title, status, priority, type, parent_id, created_at, updated_at
+
+PREFER THIS OVER hive_query when you need to:
+- See what work is available
+- Check status of multiple cells
+- Find cells matching criteria
+- Look up a cell by partial ID`,
+  args: {
+    id: tool.schema.string().optional().describe("Partial or full cell ID to look up"),
+    status: tool.schema.enum(["open", "in_progress", "blocked", "closed"]).optional().describe("Filter by status"),
+    type: tool.schema.enum(["task", "bug", "feature", "epic", "chore"]).optional().describe("Filter by type"),
+    ready: tool.schema.boolean().optional().describe("If true, return only the next unblocked cell"),
+    limit: tool.schema.number().optional().describe("Max cells to return (default 20)"),
+  },
+  async execute(args, ctx) {
+    const projectKey = getHiveWorkingDirectory();
+    const adapter = await getHiveAdapter(projectKey);
+    
+    try {
+      // If specific ID requested, resolve and return single cell
+      if (args.id) {
+        const fullId = await resolvePartialId(adapter, projectKey, args.id) || args.id;
+        const cell = await adapter.getCell(projectKey, fullId);
+        if (!cell) {
+          throw new HiveError(`No cell found matching ID '${args.id}'`, "hive_cells");
+        }
+        const formatted = formatCellForOutput(cell);
+        return JSON.stringify([formatted], null, 2);
+      }
+      
+      // If ready flag, return next unblocked cell
+      if (args.ready) {
+        const ready = await adapter.getNextReadyCell(projectKey);
+        if (!ready) {
+          return JSON.stringify([], null, 2);
+        }
+        const formatted = formatCellForOutput(ready);
+        return JSON.stringify([formatted], null, 2);
+      }
+      
+      // Query with filters
+      const cells = await adapter.queryCells(projectKey, {
+        status: args.status,
+        type: args.type,
+        limit: args.limit || 20,
+      });
+      
+      const formatted = cells.map(c => formatCellForOutput(c));
+      return JSON.stringify(formatted, null, 2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      
+      // Provide helpful error messages
+      if (message.includes("Ambiguous hash")) {
+        throw new HiveError(
+          `Ambiguous ID '${args.id}': multiple cells match. Please provide more characters.`,
+          "hive_cells",
+        );
+      }
+      if (message.includes("Bead not found") || message.includes("Cell not found")) {
+        throw new HiveError(
+          `No cell found matching ID '${args.id || "unknown"}'`,
+          "hive_cells",
+        );
+      }
+      
+      throw new HiveError(
+        `Failed to query cells: ${message}`,
+        "hive_cells",
+      );
+    }
+  },
+});
+
 /**
  * Sync hive to git and push
  */
@@ -1345,6 +1433,7 @@ export const hiveTools = {
   hive_close,
   hive_start,
   hive_ready,
+  hive_cells,
   hive_sync,
   hive_link_thread,
 };