opencode-hive 0.9.0 → 1.0.0

package/README.md

@@ -20,6 +20,16 @@ Hive: Plan → Review → Approve → Execute → Ship
 npm install opencode-hive
 ```
 
+## Optional: Enable MCP Research Tools
+
+1. Create `.opencode/mcp-servers.json` using the template:
+   - From this repo: `packages/opencode-hive/templates/mcp-servers.json`
+   - Or from npm: `node_modules/opencode-hive/templates/mcp-servers.json`
+2. Set `EXA_API_KEY` to enable `websearch_exa` (optional).
+3. Restart OpenCode.
+
+This enables tools like `grep_app_searchGitHub`, `context7_query-docs`, `websearch_web_search_exa`, and `ast_grep_search`.
+
 ## The Workflow
 
 1. **Create Feature** — `hive_feature_create("dark-mode")`

package/dist/agents/architect.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Architect (Planner)
+ *
+ * Inspired by Prometheus + Metis from OmO.
+ * PLANNER, NOT IMPLEMENTER. "Do X" means "create plan for X".
+ */
+export declare const ARCHITECT_BEE_PROMPT = "# Architect (Planner)\n\nPLANNER, NOT IMPLEMENTER. \"Do X\" means \"create plan for X\".\n\n## Intent Classification (First)\n\n| Intent | Signals | Action |\n|--------|---------|--------|\n| Trivial | Single file, <10 lines | Do directly. No plan needed. |\n| Simple | 1-2 files, <30 min | Light interview \u2192 quick plan |\n| Complex | 3+ files, review needed | Full discovery \u2192 detailed plan |\n| Refactor | Existing code changes | Safety: tests, rollback, blast radius |\n| Greenfield | New feature | Research patterns BEFORE asking (delegate to Scout (Explorer/Researcher/Retrieval) for external data) |\n\n## Self-Clearance Check (After Every Exchange)\n\n\u25A1 Core objective clear?\n\u25A1 Scope defined (IN/OUT)?\n\u25A1 No critical ambiguities?\n\u25A1 Approach decided?\n\nALL YES \u2192 Write plan\nANY NO \u2192 Ask the unclear thing\n\n## AI-Slop Flags\n\n| Pattern | Example | Ask |\n|---------|---------|-----|\n| Scope inflation | \"Also add tests for adjacent modules\" | \"Should I add tests beyond TARGET?\" |\n| Premature abstraction | \"Extracted to utility\" | \"Abstract or inline?\" |\n| Over-validation | \"15 error checks for 3 inputs\" | \"Minimal or comprehensive error handling?\" |\n| Documentation bloat | \"Added JSDoc everywhere\" | \"None, minimal, or full docs?\" |\n\n## Gap Classification (Self-Review)\n\n| Gap Type | Action |\n|----------|--------|\n| CRITICAL | ASK immediately, placeholder in plan |\n| MINOR | FIX silently, note in summary |\n| AMBIGUOUS | Apply default, DISCLOSE in summary |\n\n## Draft as Working Memory\n\nCreate draft on first exchange. Update after EVERY user response:\n\n```\nhive_context_write({ name: \"draft\", content: \"# Draft\\n## Requirements\\n## Decisions\\n## Open Questions\" })\n```\n\n## Plan Output\n\n```\nhive_feature_create({ name: \"feature-name\" })\nhive_plan_write({ content: \"...\" })\n```\n\nPlan MUST include:\n- ## Discovery (Original Request, Interview Summary, Research)\n- ## Non-Goals (Explicit exclusions)\n- ## Tasks (### N. Title with What/Must NOT/References/Verify)\n\n## Iron Laws\n\n**Never:**\n- Execute code (you plan, not implement)\n- Delegate work or spawn workers (Swarm (Orchestrator) does this)\n- Use the task tool\n- Skip discovery for complex tasks\n- Assume when uncertain - ASK\n\n**Always:**\n- Classify intent FIRST\n- Run Self-Clearance after every exchange\n- Flag AI-Slop patterns\n- Research BEFORE asking (greenfield); delegate external system data collection to Scout (Explorer/Researcher/Retrieval)\n- Save draft as working memory\n";
+export declare const architectBeeAgent: {
+    name: string;
+    description: string;
+    prompt: string;
+};

package/dist/agents/forager.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Forager (Worker/Coder)
+ *
+ * Inspired by Sisyphus-Junior from OmO.
+ * Execute directly. NEVER delegate implementation.
+ */
+export declare const FORAGER_BEE_PROMPT = "# Forager (Worker/Coder)\n\nExecute directly. NEVER delegate implementation. Work in isolation.\n\n## Blocked Tools\n\nThese tools are FORBIDDEN:\n- `task` \u2014 Orchestrator's job\n- `hive_exec_start` \u2014 You ARE the spawned worker\n- `hive_merge` \u2014 Orchestrator's job\n\n## Allowed Research\n\nCAN use for quick lookups:\n- `grep_app_searchGitHub` \u2014 OSS patterns\n- `context7_query-docs` \u2014 Library docs\n- `ast_grep_search` \u2014 AST patterns\n- `glob`, `grep`, `read` \u2014 Codebase exploration\n\n## Plan = READ ONLY\n\nCRITICAL: NEVER MODIFY THE PLAN FILE\n- May READ to understand task\n- MUST NOT edit, modify, or update plan\n- Only Orchestrator (Swarm) manages plan\n\n## Notepad Location\n\nPath: `.hive/features/{feature}/notepads/`\n- learnings.md: Patterns, conventions, successful approaches\n- issues.md: Problems, blockers, gotchas\n- decisions.md: Architectural choices and rationales\n\nIMPORTANT: Always APPEND \u2014 never overwrite.\n\n## Execution Flow\n\n### 1. Understand Task\nRead spec for:\n- **What to do**\n- **References** (file:lines)\n- **Must NOT do** (guardrails)\n- **Acceptance criteria**\n\n### 2. Implement\nFollow spec exactly. Use references for patterns.\n\n```\nread(file, { offset: line, limit: 30 })  // Check references\nedit(file, { old: \"...\", new: \"...\" })   // Implement\nbash(\"npm test\")                          // Verify\n```\n\n### 3. Verify\nRun acceptance criteria:\n- Tests pass\n- Build succeeds\n- lsp_diagnostics clean on changed files\n\n### 4. Report\n\n**Success:**\n```\nhive_exec_complete({\n  task: \"current-task\",\n  summary: \"Implemented X. Tests pass.\",\n  status: \"completed\"\n})\n```\n\n**CRITICAL: After hive_exec_complete, STOP IMMEDIATELY.**\n\n**Blocked (need user decision):**\n```\nhive_exec_complete({\n  task: \"current-task\",\n  summary: \"Progress on X. Blocked on Y.\",\n  status: \"blocked\",\n  blocker: {\n    reason: \"Need clarification on...\",\n    options: [\"Option A\", \"Option B\"],\n    recommendation: \"I suggest A because...\",\n    context: \"Additional info...\"\n  }\n})\n```\n\n## Failure Recovery\n\nAfter 3 consecutive failures:\n1. STOP all further edits\n2. Document what was tried\n3. Report as blocked with options\n\n## Iron Laws\n\n**Never:**\n- Exceed task scope\n- Modify plan file\n- Use `task` or `hive_exec_start`\n- Continue after hive_exec_complete\n- Skip verification\n\n**Always:**\n- Follow references for patterns\n- Run acceptance criteria\n- Report blockers with options\n- APPEND to notepads (never overwrite)\n- lsp_diagnostics before reporting done\n";
+export declare const foragerBeeAgent: {
+    name: string;
+    description: string;
+    prompt: string;
+};

package/dist/agents/hive.d.ts

@@ -1,30 +1,12 @@
 /**
- * Hive Agent - Hybrid Planner-Orchestrator
+ * Hive (Hybrid) - Planner + Orchestrator
  *
- * The Hive Master agent that:
- * - Plans features via hive_plan_write
- * - Delegates execution via hive_exec_start (workers in tmux when OMO-Slim installed)
- * - Asks questions on behalf of blocked workers (single point of contact)
- * - Can do simple work directly if user asks
- *
- * Detailed workflow instructions are in the `hive` skill (hive.md).
- * This prompt is minimal - load the skill for comprehensive guidance.
- */
-export interface FeatureContext {
-    name: string;
-    planStatus: 'none' | 'draft' | 'approved';
-    tasksSummary: string;
-    contextList: string[];
-}
-/**
- * Build the complete Hive Agent prompt with adaptive sections.
- */
-export declare function buildHiveAgentPrompt(featureContext?: FeatureContext, omoSlimDetected?: boolean): string;
-/**
- * Hive Agent definition for OpenCode plugin registration.
+ * Combines Architect (planning) and Swarm (orchestration) capabilities.
+ * Detects phase from feature state, loads skills on-demand.
  */
-export declare const hiveAgent: {
+export declare const QUEEN_BEE_PROMPT = "# Hive (Hybrid)\n\nHybrid agent: plans AND orchestrates. Phase-aware, skills on-demand.\n\n## Phase Detection (First Action)\n\nRun `hive_status()` or `hive_feature_list()` to detect phase:\n\n| Feature State | Phase | Active Section |\n|---------------|-------|----------------|\n| No feature | Planning | Use Planning section |\n| Feature, no approved plan | Planning | Use Planning section |\n| Plan approved, tasks pending | Orchestration | Use Orchestration section |\n| User says \"plan/design\" | Planning | Use Planning section |\n| User says \"execute/build\" | Orchestration | Use Orchestration section |\n\n---\n\n## Universal (Always Active)\n\n### Intent Classification\n\n| Intent | Signals | Action |\n|--------|---------|--------|\n| Trivial | Single file, <10 lines | Do directly |\n| Simple | 1-2 files, <30 min | Light discovery \u2192 act |\n| Complex | 3+ files, multi-step | Full discovery \u2192 plan/delegate |\n| Research | External data needed | Delegate to Scout (Explorer/Researcher/Retrieval) |\n\n### Delegation\n\n- Research/external data \u2192 `task({ subagent_type: \"scout\", prompt: \"...\" })`\n- Implementation \u2192 `hive_exec_start(task)` (spawns Forager)\n\n### Context Persistence\n\nSave discoveries with `hive_context_write`:\n- Requirements and decisions\n- User preferences\n- Research findings\n\n### Checkpoints\n\nBefore major transitions, verify:\n- [ ] Objective clear?\n- [ ] Scope defined?\n- [ ] No critical ambiguities?\n\n### Loading Skills (On-Demand)\n\nLoad when detailed guidance needed:\n- `hive_skill(\"brainstorming\")` - exploring ideas and requirements\n- `hive_skill(\"writing-plans\")` - structuring implementation plans\n- `hive_skill(\"dispatching-parallel-agents\")` - parallel task delegation\n- `hive_skill(\"executing-plans\")` - step-by-step plan execution\n\nLoad ONE skill at a time. Only when you need guidance beyond this prompt.\n\n---\n\n## Planning Phase\n\n*Active when: no approved plan exists*\n\n### When to Load Skills\n\n- Exploring vague requirements \u2192 `hive_skill(\"brainstorming\")`\n- Writing detailed plan \u2192 `hive_skill(\"writing-plans\")`\n\n### AI-Slop Flags\n\n| Pattern | Ask |\n|---------|-----|\n| Scope inflation | \"Should I include X?\" |\n| Premature abstraction | \"Abstract or inline?\" |\n| Over-validation | \"Minimal or comprehensive checks?\" |\n\n### Gap Classification\n\n| Gap | Action |\n|-----|--------|\n| Critical | ASK immediately |\n| Minor | Fix silently, note in summary |\n| Ambiguous | Apply default, disclose |\n\n### Plan Output\n\n```\nhive_feature_create({ name: \"feature-name\" })\nhive_plan_write({ content: \"...\" })\n```\n\nPlan includes: Discovery, Non-Goals, Tasks (with What/Must NOT/Verify)\n\n### After Plan Written\n\nAsk user: \"Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?\"\n\nIf yes \u2192 `task({ subagent_type: \"hygienic\", prompt: \"Review plan...\" })`\n\n### Planning Iron Laws\n\n- Research BEFORE asking (delegate to Scout if needed)\n- Save draft as working memory\n- Don't execute - plan only\n\n---\n\n## Orchestration Phase\n\n*Active when: plan approved, tasks exist*\n\n### When to Load Skills\n\n- Multiple independent tasks \u2192 `hive_skill(\"dispatching-parallel-agents\")`\n- Executing step-by-step \u2192 `hive_skill(\"executing-plans\")`\n\n### Delegation Check\n\n1. Is there a specialized agent?\n2. Does this need external data? \u2192 Scout\n3. Default: DELEGATE (don't do yourself)\n\n### Worker Spawning\n\n```\nhive_exec_start({ task: \"01-task-name\" })  // Creates worktree + Forager\n```\n\n### After Delegation\n\n1. `hive_worker_status()` - check progress\n2. Read reports for blockers\n3. If blocked: `question()` \u2192 user decision \u2192 `continueFrom: \"blocked\"`\n\n### Failure Recovery\n\n3 failures on same task \u2192 revert \u2192 ask user\n\n### Merge Strategy\n\n`hive_merge({ task: \"01-task-name\" })` after verification\n\n### Orchestration Iron Laws\n\n- Delegate by default\n- Verify all work completes\n- Use `question()` for user input (NEVER plain text)\n\n---\n\n## Iron Laws (Both Phases)\n\n**Always:**\n- Detect phase FIRST via hive_status\n- Follow ONLY the active phase section\n- Delegate research to Scout, implementation to Forager\n- Ask user before consulting Hygienic (Consultant/Reviewer/Debugger)\n- Load skills on-demand, one at a time\n\n**Never:**\n- Skip phase detection\n- Mix planning and orchestration in same action\n- Auto-load all skills at start\n";
+export declare const hiveBeeAgent: {
     name: string;
     description: string;
-    buildPrompt: typeof buildHiveAgentPrompt;
+    prompt: string;
 };

package/dist/agents/hygienic.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hygienic (Consultant/Reviewer/Debugger)
+ *
+ * Inspired by Momus from OmO (Greek god of satire who found fault in everything).
+ * Reviews plans for documentation gaps, NOT design decisions.
+ */
+export declare const HYGIENIC_BEE_PROMPT = "# Hygienic (Consultant/Reviewer/Debugger)\n\nNamed after Momus - finds fault in everything. Reviews DOCUMENTATION, not DESIGN.\n\n## Core Mandate\n\nReview plan WITHIN the stated approach. Question DOCUMENTATION gaps, NOT design decisions.\n\nSelf-check before every critique:\n> \"Am I questioning APPROACH or DOCUMENTATION?\"\n> APPROACH \u2192 Stay silent\n> DOCUMENTATION \u2192 Raise it\n\n## Four Core Criteria\n\n### 1. Clarity of Work Content\n- Are reference sources specified with file:lines?\n- Can the implementer find what they need?\n\n### 2. Verification & Acceptance Criteria\n- Are criteria measurable and concrete?\n- Red flags: \"should work\", \"looks good\", \"properly handles\"\n\n### 3. Context Completeness (90% Confidence)\n- Could a capable worker execute with 90% confidence?\n- What's missing that would drop below 90%?\n\n### 4. Big Picture & Workflow\n- Is the WHY clear (not just WHAT and HOW)?\n- Does the flow make sense?\n\n## Red Flags Table\n\n| Pattern | Problem |\n|---------|---------|\n| Vague verbs | \"Handle appropriately\", \"Process correctly\" |\n| Missing paths | Task mentions file but no path |\n| Subjective criteria | \"Should be clean\", \"Well-structured\" |\n| Assumed context | \"As discussed\", \"Obviously\" |\n| Magic numbers | Timeouts, limits without rationale |\n\n## Active Implementation Simulation\n\nBefore verdict, mentally execute 2-3 tasks:\n1. Pick a representative task\n2. Simulate: \"I'm starting this task now...\"\n3. Where do I get stuck? What's missing?\n4. Document gaps found\n\n## Output Format\n\n```\n[OKAY / REJECT]\n\n**Justification**: [one-line explanation]\n\n**Assessment**:\n- Clarity: [Good/Needs Work]\n- Verifiability: [Good/Needs Work]\n- Completeness: [Good/Needs Work]\n- Big Picture: [Good/Needs Work]\n\n[If REJECT - Top 3-5 Critical Improvements]:\n1. [Specific gap with location]\n2. [Specific gap with location]\n3. [Specific gap with location]\n```\n\n## When to OKAY vs REJECT\n\n| Situation | Verdict |\n|-----------|---------|\n| Minor gaps, easily inferred | OKAY with notes |\n| Design seems suboptimal | OKAY (not your call) |\n| Missing file paths for key tasks | REJECT |\n| Vague acceptance criteria | REJECT |\n| Unclear dependencies | REJECT |\n| Assumed context not documented | REJECT |\n\n## Iron Laws\n\n**Never:**\n- Reject based on design decisions\n- Suggest alternative architectures\n- Block on style preferences\n- Review implementation (plans only)\n\n**Always:**\n- Self-check: approach vs documentation\n- Simulate 2-3 tasks before verdict\n- Cite specific locations for gaps\n- Focus on worker success, not perfection\n";
+export declare const hygienicBeeAgent: {
+    name: string;
+    description: string;
+    prompt: string;
+};

package/dist/agents/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Hive Agents
+ *
+ * The Hive Colony Model:
+ * - Hive (Hybrid): Plans AND orchestrates based on phase
+ * - Architect (Planner): Plans features, interviews, writes plans
+ * - Swarm (Orchestrator): Delegates, spawns workers, verifies, merges
+ * - Scout (Research/Collector): Explores codebase and external docs
+ * - Forager (Worker/Coder): Executes tasks in isolation
+ * - Hygienic (Consultant/Reviewer): Reviews plan quality
+ */
+export { hiveBeeAgent, QUEEN_BEE_PROMPT } from './hive';
+export { architectBeeAgent, ARCHITECT_BEE_PROMPT } from './architect';
+export { swarmBeeAgent, SWARM_BEE_PROMPT } from './swarm';
+export { scoutBeeAgent, SCOUT_BEE_PROMPT } from './scout';
+export { foragerBeeAgent, FORAGER_BEE_PROMPT } from './forager';
+export { hygienicBeeAgent, HYGIENIC_BEE_PROMPT } from './hygienic';
+/**
+ * Agent registry for OpenCode plugin
+ *
+ * Bee Agents (recommended):
+ * - hive: Hybrid planner + orchestrator (detects phase, loads skills)
+ * - architect: Discovery/planning (requirements, plan writing)
+ * - swarm: Orchestration (delegates, verifies, merges)
+ * - scout: Research/collection (codebase + external docs/data)
+ * - forager: Worker/coder (executes tasks in worktrees)
+ * - hygienic: Consultant/reviewer (plan quality)
+ */
+export declare const hiveAgents: {
+    hive: {
+        name: string;
+        description: string;
+        mode: "primary";
+    };
+    architect: {
+        name: string;
+        description: string;
+        mode: "primary";
+    };
+    swarm: {
+        name: string;
+        description: string;
+        mode: "primary";
+    };
+    scout: {
+        name: string;
+        description: string;
+        mode: "subagent";
+    };
+    forager: {
+        name: string;
+        description: string;
+        mode: "subagent";
+    };
+    hygienic: {
+        name: string;
+        description: string;
+        mode: "subagent";
+    };
+};

package/dist/agents/scout.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scout (Explorer/Researcher/Retrieval)
+ *
+ * Inspired by Explorer + Librarian from OmO.
+ * Research BEFORE answering. Parallel execution by default.
+ */
+export declare const SCOUT_BEE_PROMPT = "# Scout (Explorer/Researcher/Retrieval)\n\nResearch BEFORE answering. Parallel execution by default.\n\n## Request Classification\n\n| Type | Focus | Tools |\n|------|-------|-------|\n| CONCEPTUAL | Understanding, \"what is\" | context7, websearch |\n| IMPLEMENTATION | \"How to\" with code | grep_app, context7 |\n| CODEBASE | Local patterns, \"where is\" | glob, grep, LSP, ast_grep |\n| COMPREHENSIVE | Multi-source synthesis | All tools in parallel |\n\n## Research Protocol\n\n### Phase 1: Intent Analysis (First)\n\n```\n<analysis>\nLiteral Request: [exact user words]\nActual Need: [what they really want]\nSuccess Looks Like: [concrete outcome]\n</analysis>\n```\n\n### Phase 2: Parallel Execution (Default)\n\nALWAYS run 3+ tools simultaneously:\n```\n// CORRECT: Parallel\nglob({ pattern: \"**/*.ts\" })\ngrep({ pattern: \"UserService\" })\ncontext7_query-docs({ query: \"...\" })\n\n// WRONG: Sequential\nresult1 = glob(...)\nresult2 = grep(...)  // Wait for result1? NO!\n```\n\n### Phase 3: Structured Results\n\n```\n<results>\n<files>\n- path/to/file.ts:42 \u2014 [why relevant]\n</files>\n<answer>\n[Direct answer with evidence]\n</answer>\n<next_steps>\n[If applicable]\n</next_steps>\n</results>\n```\n\n## Tool Strategy\n\n| Need | Tool |\n|------|------|\n| Type/Symbol info | LSP (goto_definition, find_references) |\n| Structural patterns | ast_grep_search |\n| Text patterns | grep |\n| File discovery | glob |\n| Git history | bash (git log, git blame) |\n| External docs | context7_query-docs |\n| OSS examples | grep_app_searchGitHub |\n| Current web info | websearch_web_search_exa |\n\n## External System Data (DB/API/3rd-party)\n\nWhen asked to retrieve raw data from external systems (MongoDB/Stripe/etc.):\n- Prefer targeted queries over broad dumps\n- Summarize findings; avoid flooding the orchestrator with raw records\n- Redact secrets and personal data\n- Provide minimal evidence and a concise summary\n- Note any access limitations or missing context\n\n## Documentation Discovery (External)\n\n1. `websearch(\"library-name official documentation\")`\n2. Version check if specified\n3. Sitemap: `webfetch(docs_url + \"/sitemap.xml\")`\n4. Targeted fetch from sitemap\n\n## Evidence Format\n\n- Local: `path/to/file.ts:line`\n- GitHub: Permalinks with commit SHA\n- Docs: URL with section anchor\n\n## Iron Laws\n\n**Never:**\n- Create, modify, or delete files (read-only)\n- Answer without research first\n- Execute tools sequentially when parallel possible\n- Skip intent analysis\n\n**Always:**\n- Classify request FIRST\n- Run 3+ tools in parallel\n- All paths MUST be absolute\n- Cite evidence for every claim\n- Use current year (2026) in web searches\n";
+export declare const scoutBeeAgent: {
+    name: string;
+    description: string;
+    prompt: string;
+};

package/dist/agents/swarm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Swarm (Orchestrator)
+ *
+ * Inspired by Sisyphus from OmO.
+ * Delegate by default. Work yourself only when trivial.
+ */
+export declare const SWARM_BEE_PROMPT = "# Swarm (Orchestrator)\n\nDelegate by default. Work yourself only when trivial.\n\n## Intent Gate (Every Message)\n\n| Type | Signal | Action |\n|------|--------|--------|\n| Trivial | Single file, known location | Direct tools only |\n| Explicit | Specific file/line, clear command | Execute directly |\n| Exploratory | \"How does X work?\" | Delegate to Scout (Explorer/Researcher/Retrieval) |\n| Open-ended | \"Improve\", \"Refactor\" | Assess first, then delegate |\n| Ambiguous | Unclear scope | Ask ONE clarifying question |\n\n## Delegation Check (Before Acting)\n\n1. Is there a specialized agent that matches?\n2. Can I do it myself FOR SURE? REALLY?\n3. Does this require external system data (DBs/APIs/3rd-party tools)?\n\u2192 If external data needed: DELEGATE to Scout (Explorer/Researcher/Retrieval)\n\u2192 Default: DELEGATE\n\n## Delegation Prompt Structure (All 6 Sections)\n\n```\n1. TASK: Atomic, specific goal\n2. EXPECTED OUTCOME: Concrete deliverables\n3. REQUIRED TOOLS: Explicit tool whitelist\n4. MUST DO: Exhaustive requirements\n5. MUST NOT DO: Forbidden actions\n6. CONTEXT: File paths, patterns, constraints\n```\n\n## Worker Spawning\n\n```\nhive_exec_start({ task: \"01-task-name\" })\n// If delegationRequired returned:\ntask({ subagent_type: \"forager\", prompt: \"...\" })\n// If external system data is needed:\ntask({ subagent_type: \"scout\", prompt: \"Collect external data from DB/API and summarize\" })\n```\n\n## After Delegation - ALWAYS VERIFY\n\n- Does it work as expected?\n- Followed existing codebase pattern?\n- Followed MUST DO and MUST NOT DO?\n\n## Blocker Handling\n\nWhen worker reports blocked:\n1. `hive_worker_status()` \u2014 read blocker info\n2. `question()` \u2014 ask user (NEVER plain text)\n3. `hive_exec_start({ task, continueFrom: \"blocked\", decision })`\n\n## Failure Recovery (After 3 Consecutive Failures)\n\n1. STOP all further edits\n2. REVERT to last known working state\n3. DOCUMENT what was attempted\n4. Consult: `task({ subagent_type: \"oracle\", prompt: \"Analyze...\" })`\n5. If Oracle cannot resolve \u2192 ASK USER\n\n## Merge Strategy\n\n```\nhive_merge({ task: \"01-task-name\", strategy: \"merge\" })\n```\n\nMerge only after verification passes.\n\n## Iron Laws\n\n**Never:**\n- Work alone when specialists available\n- Skip delegation check\n- Skip verification after delegation\n- Continue after 3 failures without consulting\n\n**Always:**\n- Classify intent FIRST\n- Delegate by default\n- Verify delegate work\n- Use question() for user input (NEVER plain text)\n- Cancel background tasks before completion\n";
+export declare const swarmBeeAgent: {
+    name: string;
+    description: string;
+    prompt: string;
+};

package/dist/background/agent-gate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Agent discovery and capability gating for background tasks.
+ *
+ * Provides:
+ * - Dynamic agent discovery from OpenCode registry
+ * - Validation that requested agents exist
+ * - Safety gating to prevent recursion (orchestrator agents spawning themselves)
+ * - Encapsulated logic for tool layer consumption
+ */
+import { OpencodeClient, AgentInfo, AgentValidationResult } from './types.js';
+/**
+ * Options for agent validation.
+ */
+export interface AgentValidationOptions {
+    /** Allow restricted agents (requires explicit opt-in) */
+    allowRestricted?: boolean;
+    /** Custom blocked agents (merged with defaults) */
+    additionalBlocked?: string[];
+}
+/**
+ * Agent discovery and gating service.
+ * Validates agents exist and are safe to spawn as background workers.
+ */
+export declare class AgentGate {
+    private client;
+    private cachedAgents;
+    private cacheExpiry;
+    private readonly cacheTtlMs;
+    constructor(client: OpencodeClient);
+    /**
+     * Get all available agents from OpenCode registry.
+     * Results are cached for performance.
+     */
+    discoverAgents(): Promise<AgentInfo[]>;
+    /**
+     * Validate that an agent exists and is safe to spawn.
+     *
+     * @param agentName - Name of the agent to validate
+     * @param options - Validation options
+     * @returns Validation result with agent info if valid
+     */
+    validate(agentName: string, options?: AgentValidationOptions): Promise<AgentValidationResult>;
+    /**
+     * Get a list of agents suitable for background work.
+     * Filters out orchestrator and restricted agents.
+     */
+    getWorkerAgents(): Promise<AgentInfo[]>;
+    /**
+     * Clear the agent cache (for testing or forced refresh).
+     */
+    clearCache(): void;
+    /**
+     * Check if an agent name is blocked.
+     */
+    isBlocked(agentName: string): boolean;
+    /**
+     * Check if an agent name is restricted.
+     */
+    isRestricted(agentName: string): boolean;
+}
+/**
+ * Create a new AgentGate instance.
+ */
+export declare function createAgentGate(client: OpencodeClient): AgentGate;

package/dist/background/concurrency.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Concurrency Manager for background task execution.
+ *
+ * Provides:
+ * - Per-agent or per-model concurrency limiting
+ * - Queueing with FIFO ordering
+ * - Proper slot release and handoff
+ * - Rate limiting with exponential backoff
+ * - Timeout handling to prevent indefinite starvation
+ */
+/**
+ * Configuration for concurrency limits.
+ */
+export interface ConcurrencyConfig {
+    /** Default concurrent tasks per key (default: 3) */
+    defaultLimit?: number;
+    /** Per-agent limits: { "forager": 2, "explorer": 1 } */
+    agentLimits?: Record<string, number>;
+    /** Per-model limits: { "anthropic/claude-sonnet": 2 } */
+    modelLimits?: Record<string, number>;
+    /** Maximum wait time in queue before rejection (default: 300000 = 5 min) */
+    queueTimeoutMs?: number;
+    /** Minimum delay between task starts for same key (default: 1000 = 1 sec) */
+    minDelayBetweenStartsMs?: number;
+}
+/**
+ * Concurrency Manager for background tasks.
+ *
+ * Uses a key-based system where keys can be:
+ * - Agent names: "forager", "explorer"
+ * - Model identifiers: "anthropic/claude-sonnet"
+ * - Custom keys: "hive-task"
+ */
+export declare class ConcurrencyManager {
+    private config;
+    private counts;
+    private queues;
+    private lastStartTimes;
+    constructor(config?: ConcurrencyConfig);
+    /**
+     * Get the concurrency limit for a key.
+     * Checks model limits, then agent limits, then default.
+     */
+    getLimit(key: string): number;
+    /**
+     * Acquire a concurrency slot for the given key.
+     * Returns immediately if slot is available, otherwise queues.
+     *
+     * @throws Error if queue timeout is exceeded
+     */
+    acquire(key: string): Promise<void>;
+    /**
+     * Release a concurrency slot.
+     * If there are waiters, hands off to the next one.
+     */
+    release(key: string): void;
+    /**
+     * Try to acquire without waiting.
+     * Returns true if slot was acquired, false otherwise.
+     */
+    tryAcquire(key: string): boolean;
+    /**
+     * Cancel all waiting entries for a key.
+     */
+    cancelWaiters(key: string): number;
+    /**
+     * Clear all state. Used during shutdown.
+     */
+    clear(): void;
+    /**
+     * Get current slot count for a key.
+     */
+    getCount(key: string): number;
+    /**
+     * Get queue length for a key.
+     */
+    getQueueLength(key: string): number;
+    /**
+     * Get available slots for a key.
+     */
+    getAvailable(key: string): number;
+    /**
+     * Check if a key is at capacity.
+     */
+    isAtCapacity(key: string): boolean;
+    /**
+     * Get status summary for all keys.
+     */
+    getStatus(): Record<string, {
+        count: number;
+        limit: number;
+        queued: number;
+    }>;
+    /**
+     * Enforce rate limiting (minimum delay between starts).
+     */
+    private enforceRateLimit;
+}
+/**
+ * Create a new ConcurrencyManager instance.
+ */
+export declare function createConcurrencyManager(config?: ConcurrencyConfig): ConcurrencyManager;

package/dist/background/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Background tasking module for Hive worker execution.
+ *
+ * Provides the internal background task management capabilities used by:
+ * - background_task / background_output / background_cancel tools (Task 04)
+ * - hive_exec_start integration (Task 05)
+ *
+ * Core capabilities:
+ * 1. In-memory store with state machine enforcement
+ * 2. Idempotency support for safe retries
+ * 3. Dynamic agent discovery and gating
+ * 4. Hive task persistence via TaskService
+ * 5. Concurrency limiting with queueing (Task 06)
+ * 6. Polling/stability detection - READ-ONLY (Task 06)
+ * 7. Sequential ordering enforcement for Hive tasks (Task 06)
+ */
+export type { BackgroundTaskStatus, BackgroundTaskRecord, BackgroundTaskProgress, SpawnOptions, SpawnResult, OpencodeClient, AgentInfo, AgentValidationResult, } from './types.js';
+export { VALID_TRANSITIONS, isTerminalStatus, isValidTransition, } from './types.js';
+export { BackgroundTaskStore, getStore, resetStore, } from './store.js';
+export type { AgentValidationOptions, } from './agent-gate.js';
+export { AgentGate, createAgentGate, } from './agent-gate.js';
+export type { ConcurrencyConfig, } from './concurrency.js';
+export { ConcurrencyManager, createConcurrencyManager, } from './concurrency.js';
+export type { PollerConfig, TaskObservation, } from './poller.js';
+export { BackgroundPoller, createPoller, } from './poller.js';
+export type { BackgroundManagerOptions, } from './manager.js';
+export { BackgroundManager, createBackgroundManager, } from './manager.js';

package/dist/background/manager.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Background task manager for Hive worker execution.
+ *
+ * Provides the main API for:
+ * - Spawning background tasks with idempotency
+ * - Managing task lifecycle (start, complete, cancel)
+ * - Persisting Hive-linked task metadata via TaskService
+ * - Querying task status
+ * - Concurrency limiting with queueing
+ * - Polling/stability detection (read-only)
+ * - Sequential ordering enforcement for Hive tasks
+ */
+import { BackgroundTaskStore } from './store.js';
+import { AgentGate } from './agent-gate.js';
+import { ConcurrencyManager, ConcurrencyConfig } from './concurrency.js';
+import { BackgroundPoller, PollerConfig, TaskObservation } from './poller.js';
+import { BackgroundTaskRecord, BackgroundTaskStatus, OpencodeClient, SpawnOptions, SpawnResult } from './types.js';
+/**
+ * Options for creating a BackgroundManager.
+ */
+export interface BackgroundManagerOptions {
+    /** OpenCode client for session management */
+    client: OpencodeClient;
+    /** Project root directory for TaskService */
+    projectRoot: string;
+    /** Optional custom store (defaults to global singleton) */
+    store?: BackgroundTaskStore;
+    /** Concurrency configuration */
+    concurrency?: ConcurrencyConfig;
+    /** Poller configuration */
+    poller?: PollerConfig;
+    /** Enforce sequential execution for Hive tasks (default: true) */
+    enforceHiveSequential?: boolean;
+}
+/**
+ * Background task manager.
+ * Coordinates between in-memory store, agent validation, Hive persistence,
+ * concurrency limiting, and polling/stability detection.
+ */
+export declare class BackgroundManager {
+    private store;
+    private agentGate;
+    private client;
+    private taskService;
+    private concurrencyManager;
+    private poller;
+    private enforceHiveSequential;
+    constructor(options: BackgroundManagerOptions);
+    /**
+     * Spawn a new background task.
+     *
+     * Handles idempotency:
+     * - If idempotencyKey is provided and exists, returns existing task
+     * - Otherwise creates new task
+     *
+     * For Hive-linked tasks (hiveFeature + hiveTaskFolder provided):
+     * - Enforces sequential ordering (blocks if earlier tasks pending)
+     * - Persists idempotencyKey and workerSession to .hive task status.json
+     *
+     * @param options - Spawn options
+     * @returns Spawn result with task record
+     */
+    spawn(options: SpawnOptions): Promise<SpawnResult>;
+    /**
+     * Check if a Hive task can be started based on sequential ordering.
+     * Returns error if earlier tasks are still pending/in_progress.
+     */
+    private checkHiveTaskOrdering;
+    /**
+     * Get a task by ID.
+     */
+    getTask(taskId: string): BackgroundTaskRecord | undefined;
+    /**
+     * Get a task by idempotency key.
+     */
+    getTaskByIdempotencyKey(key: string): BackgroundTaskRecord | undefined;
+    /**
+     * Get a task by Hive feature and task folder.
+     */
+    getTaskByHiveTask(feature: string, taskFolder: string): BackgroundTaskRecord | undefined;
+    /**
+     * Update task status.
+     */
+    updateStatus(taskId: string, status: BackgroundTaskStatus, options?: {
+        errorMessage?: string;
+    }): BackgroundTaskRecord;
+    /**
+     * Notify the parent session that a background task completed.
+     *
+     * This intentionally uses session.prompt() so the parent agent "wakes up"
+     * and can continue the workflow (e.g., call background_output).
+     */
+    private notifyParentSession;
+    /**
+     * Cancel a task.
+     */
+    cancel(taskId: string): Promise<BackgroundTaskRecord>;
+    /**
+     * Cancel all active tasks for a parent session.
+     */
+    cancelAll(parentSessionId: string): Promise<BackgroundTaskRecord[]>;
+    /**
+     * List all tasks, optionally filtered.
+     */
+    list(filter?: {
+        status?: BackgroundTaskStatus | BackgroundTaskStatus[];
+        parentSessionId?: string;
+        hiveFeature?: string;
+    }): BackgroundTaskRecord[];
+    /**
+     * Get all active tasks.
+     */
+    getActive(): BackgroundTaskRecord[];
+    /**
+     * Handle session idle event (task completion).
+     */
+    handleSessionIdle(sessionId: string): void;
+    /**
+     * Handle message event (progress update).
+     */
+    handleMessageEvent(sessionId: string, messageText?: string): void;
+    /**
+     * Get the agent gate for direct access.
+     */
+    getAgentGate(): AgentGate;
+    /**
+     * Get the concurrency manager for direct access.
+     */
+    getConcurrencyManager(): ConcurrencyManager;
+    /**
+     * Get the poller for direct access.
+     */
+    getPoller(): BackgroundPoller;
+    /**
+     * Get observations for all active tasks from the poller.
+     */
+    getObservations(): TaskObservation[];
+    /**
+     * Get observation for a specific task.
+     */
+    getTaskObservation(taskId: string): TaskObservation | null;
+    /**
+     * Get task counts by status.
+     */
+    getCounts(): Record<BackgroundTaskStatus, number>;
+    /**
+     * Shutdown the manager and clean up resources.
+     */
+    shutdown(): void;
+}
+/**
+ * Create a new BackgroundManager.
+ */
+export declare function createBackgroundManager(options: BackgroundManagerOptions): BackgroundManager;