opencode-hive 1.0.7 → 1.2.0

package/skills/parallel-exploration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parallel-exploration
-description: Use when you need parallel, read-only exploration with hive_background_* or task() (Scout fan-out)
+description: Use when you need parallel, read-only exploration with task() (Scout fan-out)
 ---
 
 # Parallel Exploration (Scout Fan-Out)
@@ -13,11 +13,7 @@ When you need to answer "where/how does X work?" across multiple domains (codeba
 
 **Safe in Planning mode:** This is read-only exploration. It is OK to use during exploratory research even when there is no feature, no plan, and no approved tasks.
 
-**This skill is for read-only research.** For parallel implementation work, use `hive_skill("dispatching-parallel-agents")` with `hive_exec_start`.
-
-**Two valid execution paths:**
-- **Path A (Hive background tools):** Use `hive_background_task`, `hive_background_output`, `hive_background_cancel` when available.
-- **Path B (Task mode):** Use native `task()` for delegation when background tools are not registered.
+**This skill is for read-only research.** For parallel implementation work, use `hive_skill("dispatching-parallel-agents")` with `hive_worktree_create`.
 
 ## When to Use
 
@@ -56,51 +52,16 @@ Split your investigation into 2-4 independent sub-questions. Good decomposition:
 - "What is X?" then "How is X used?" (second depends on first)
 - "Find the bug" then "Fix the bug" (not read-only)
 
-### 2. Spawn Background Tasks (Fan-Out)
+### 2. Spawn Tasks (Fan-Out)
 
 Launch all tasks before waiting for any results:
 
 ```typescript
-// Path A: Hive background tools (when available)
-// Fan-out: spawn all tasks first
-hive_background_task({
-  agent: "scout-researcher",
-  description: "Find hive_background_task implementation",
-  prompt: `Where is hive_background_task implemented and registered?
-    - Find the tool definition
-    - Find the plugin registration
-    - Return file paths with line numbers`,
-  sync: false
-})
-
-hive_background_task({
-  agent: "scout-researcher",
-  description: "Analyze background task concurrency",
-  prompt: `How does background task concurrency/queueing work?
-    - Find the manager/scheduler code
-    - Document the concurrency model
-    - Return file paths with evidence`,
-  sync: false
-})
-
-hive_background_task({
-  agent: "scout-researcher",
-  description: "Find parent notification mechanism",
-  prompt: `How does parent notification work for background tasks?
-    - Where is the notification built?
-    - How is it sent to the parent session?
-    - Return file paths with evidence`,
-  sync: false
-})
-```
-
-```typescript
-// Path B: Task mode (native task tool)
 // Parallelize by issuing multiple task() calls in the same assistant message.
 task({
   subagent_type: 'scout-researcher',
-  description: 'Find hive_background_task implementation',
-  prompt: `Where is hive_background_task implemented and registered?
+  description: 'Find API route implementation',
+  prompt: `Where are API routes implemented and registered?
     - Find the tool definition
     - Find the plugin registration
     - Return file paths with line numbers`,
@@ -126,8 +87,7 @@ task({
 ```
 
 **Key points:**
-- Use `agent: "scout-researcher"` for read-only exploration
-- Use `sync: false` to return immediately (non-blocking)
+- Use `subagent_type: 'scout-researcher'` for read-only exploration
 - Give each task a clear, focused `description`
 - Make prompts specific about what evidence to return
 
@@ -142,35 +102,7 @@ You'll receive a `<system-reminder>` notification when each task completes.
 
 ### 4. Collect Results
 
-When notified of completion, retrieve results:
-
-```typescript
-// Path A: Hive background tools
-// Get output from completed task
-hive_background_output({
-  task_id: "task-abc123",
-  block: false  // Don't wait, task already done
-})
-```
-
-**For incremental output (long-running tasks):**
-
-```typescript
-// First call - get initial output
-hive_background_output({
-  task_id: "task-abc123",
-  block: true,      // Wait for output
-  timeout: 30000    // 30 second timeout
-})
-// Returns: { output: "...", cursor: "5" }
-
-// Later call - get new output since cursor
-hive_background_output({
-  task_id: "task-abc123",
-  cursor: "5",      // Resume from message 5
-  block: true
-})
-```
+When each task completes, its result is returned directly. Collect the outputs from each task and proceed to synthesis.
 
 ### 5. Synthesize Findings
 
@@ -181,16 +113,7 @@ Combine results from all tasks:
 
 ### 6. Cleanup (If Needed)
 
-Cancel tasks that are no longer needed:
-
-```typescript
-// Path A: Hive background tools
-// Cancel specific task
-hive_background_cancel({ task_id: "task-abc123" })
-
-// Cancel all your background tasks
-hive_background_cancel({ all: true })
-```
+No manual cancellation is required in task mode.
 
 ## Prompt Templates
 
@@ -238,48 +161,20 @@ Return:
 
 ## Real Example
 
-**Investigation:** "How does the background task system work?"
+**Investigation:** "How does the API routing system work?"
 
 **Decomposition:**
-1. Implementation: Where is `hive_background_task` tool defined?
-2. Concurrency: How does task scheduling/queueing work?
-3. Notifications: How does parent session get notified?
+1. Implementation: Where are API routes defined?
+2. Routing: How does route registration work?
+3. Notifications: How are errors surfaced to the caller?
 
 **Fan-out:**
 ```typescript
-// Path A: Hive background tools
-// Task 1: Implementation
-hive_background_task({
-  agent: "scout-researcher",
-  description: "Find hive_background_task implementation",
-  prompt: "Where is hive_background_task implemented? Find tool definition and registration.",
-  sync: false
-})
-
-// Task 2: Concurrency
-hive_background_task({
-  agent: "scout-researcher",
-  description: "Analyze concurrency model",
-  prompt: "How does background task concurrency work? Find the manager/scheduler.",
-  sync: false
-})
-
-// Task 3: Notifications
-hive_background_task({
-  agent: "scout-researcher",
-  description: "Find notification mechanism",
-  prompt: "How are parent sessions notified of task completion?",
-  sync: false
-})
-```
-
-```typescript
-// Path B: Task mode (native task tool)
 // Parallelize by issuing multiple task() calls in the same assistant message.
 task({
   subagent_type: 'scout-researcher',
-  description: 'Find hive_background_task implementation',
-  prompt: 'Where is hive_background_task implemented? Find tool definition and registration.',
+  description: 'Find API route implementation',
+  prompt: 'Where are API routes implemented? Find tool definition and registration.',
 });
 
 task({
@@ -307,20 +202,12 @@ task({
 **Spawning sequentially (defeats the purpose):**
 ```typescript
 // BAD: Wait for each before spawning next
-const result1 = await hive_background_task({ ..., sync: true })
-const result2 = await hive_background_task({ ..., sync: true })
-```
-
-```typescript
-// GOOD: Spawn all, then collect
-hive_background_task({ ..., sync: false })  // Returns immediately
-hive_background_task({ ..., sync: false })  // Returns immediately
-hive_background_task({ ..., sync: false })  // Returns immediately
-// ... later, collect results with hive_background_output
+await task({ ... });
+await task({ ... });
 ```
 
 ```typescript
-// GOOD (task mode): Spawn all in the same assistant message
+// GOOD: Spawn all in the same assistant message
 task({ ... });
 task({ ... });
 task({ ... });
@@ -349,7 +236,5 @@ task({ ... });
 
 After using this pattern, verify:
 - [ ] All tasks spawned before collecting any results (true fan-out)
-- [ ] Received notifications for completed tasks (Path A)
-- [ ] Successfully retrieved output with `hive_background_output` (Path A)
-- [ ] Verified `task()` fan-out pattern used when in task mode (Path B)
+- [ ] Verified `task()` fan-out pattern used for parallel exploration
 - [ ] Synthesized findings into coherent answer

package/skills/test-driven-development/SKILL.md

@@ -356,7 +356,7 @@ Never fix bugs without a test.
 
 ## Testing Anti-Patterns
 
-When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
+When adding mocks or test utilities, avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies

package/skills/writing-plans/SKILL.md

@@ -111,6 +111,12 @@ Always include **Depends on** for each task. Use `none` to enable parallel start
 **Verify**:
 - [ ] Run: `{command}` → {expected}
 - [ ] {Additional acceptance criteria}
+
+All verification MUST be agent-executable (no human intervention):
+✅ `bun test` → all pass
+✅ `curl -X POST /api/x` → 201
+❌ "User manually tests..."
+❌ "Visually confirm..."
 ````
 
 ## Remember
@@ -119,6 +125,7 @@ Always include **Depends on** for each task. Use `none` to enable parallel start
 - Exact commands with expected output
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
+- All acceptance criteria must be agent-executable (zero human intervention)
 
 ## Execution Handoff
 

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

@@ -1,64 +0,0 @@
-/**
- * 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

@@ -1,102 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,169 +0,0 @@
-/**
- * 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 dependency constraints.
-     *
-     * Hybrid enforcement:
-     * 1. If task has explicit dependsOn array, check all deps have status 'done'
-     * 2. If task has no dependsOn (legacy/undefined), fall back to numeric sequential ordering
-     *
-     * Only 'done' status satisfies a dependency - cancelled/failed/blocked/partial do NOT.
-     */
-    private checkHiveTaskOrdering;
-    /**
-     * Check if all dependencies are satisfied (status === 'done').
-     * Only 'done' counts as satisfied - cancelled/failed/blocked/partial do NOT.
-     */
-    private checkDependencies;
-    /**
-     * Legacy numeric sequential ordering check.
-     * Used when task has no dependsOn field (backwards compatibility).
-     */
-    private checkNumericOrdering;
-    /**
-     * 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;