opencode-hive 1.3.0 → 1.3.1

package/dist/index.js

@@ -12931,9 +12931,9 @@ Each agent gets:
 
 \`\`\`typescript
 // Using Hive tools for parallel execution
-hive_worktree_create({ task: "01-fix-abort-tests" })
-hive_worktree_create({ task: "02-fix-batch-tests" })
-hive_worktree_create({ task: "03-fix-race-condition-tests" })
+hive_worktree_start({ task: "01-fix-abort-tests" })
+hive_worktree_start({ task: "02-fix-batch-tests" })
+hive_worktree_start({ task: "03-fix-race-condition-tests" })
 // All three run concurrently in isolated worktrees
 \`\`\`
 
@@ -13433,7 +13433,7 @@ Only \`done\` satisfies dependencies (not \`blocked\`, \`failed\`, \`partial\`,
 ### Step 3: Execute Batch
 
 For each task in the batch:
-1. Mark as in_progress via \`hive_worktree_create()\`
+1. Mark as in_progress via \`hive_worktree_start()\`
 2. Follow each step exactly (plan has bite-sized steps)
 3. Run verifications as specified
 4. Mark as completed
@@ -13501,7 +13501,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_worktree_create\`.
+**This skill is for read-only research.** For parallel implementation work, use \`hive_skill("dispatching-parallel-agents")\` with \`hive_worktree_start\`.
 
 ## When to Use
 
@@ -13512,7 +13512,7 @@ When you need to answer "where/how does X work?" across multiple domains (codeba
 - Questions are independent (answer to A doesn't affect B)
 - User asks **3+ independent questions** (often as a numbered list or separate bullets)
 - No edits needed (read-only exploration)
-- User asks for an explorationthat likely spans multiple files/packages
+- User asks for an exploration that likely spans multiple files/packages
 - The work is read-only and the questions can be investigated independently
 
 **Only skip this skill when:**
@@ -14852,7 +14852,7 @@ Intent Verbalization — verbalize before acting:
 ### Delegation
 - Single-scout research → \`task({ subagent_type: "scout-researcher", prompt: "..." })\`
 - Parallel exploration → Load \`hive_skill("parallel-exploration")\` and follow the task mode delegation guidance.
-- Implementation → \`hive_worktree_create({ task: "01-task-name" })\` (creates worktree + Forager)
+- Implementation → \`hive_worktree_start({ task: "01-task-name" })\` (creates worktree + Forager)
 
 During Planning, use \`task({ subagent_type: "scout-researcher", ... })\` for exploration (BLOCKING — returns when done). For parallel exploration, issue multiple \`task()\` calls in the same message.
 
@@ -14945,7 +14945,7 @@ Each task declares dependencies with **Depends on**:
 ### After Plan Written
 Ask user via \`question()\`: "Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?"
 
-If yes → \`task({ subagent_type: "hygienic", prompt: "Review plan..." })\`
+If yes → default to built-in \`hygienic-reviewer\`; choose a configured hygienic-derived reviewer only when its description in \`Configured Custom Subagents\` is a better match. Then run \`task({ subagent_type: "<chosen-reviewer>", prompt: "Review plan..." })\`.
 
 After review decision, offer execution choice (subagent-driven vs parallel session) consistent with writing-plans.
 
@@ -14978,15 +14978,17 @@ Use \`hive_status()\` to see **runnable** tasks (dependencies satisfied) and **b
 
 ### Worker Spawning
 \`\`\`
-hive_worktree_create({ task: "01-task-name" })  // Creates worktree + Forager
+hive_worktree_start({ task: "01-task-name" })  // Creates worktree + Forager
 \`\`\`
 
 ### After Delegation
 1. \`task()\` is blocking — when it returns, the worker is done
-2. Immediately call \`hive_status()\` to check the new task state and find next runnable tasks
-3. The delegated task MUST transition out of \`in_progress\`; if still \`in_progress\`, resume worker with explicit instruction to resolve commit response and retry
-4. If task status is blocked: read blocker info → \`question()\` → user decision → resume with \`continueFrom: "blocked"\`
-5. Skip polling — the result is available when \`task()\` returns
+2. After \`task()\` returns, immediately call \`hive_status()\` to check the new task state and find next runnable tasks before any resume attempt
+3. Use \`continueFrom: "blocked"\` only when status is exactly \`blocked\`
+4. If status is not \`blocked\`, do not use \`continueFrom: "blocked"\`; use \`hive_worktree_start({ feature, task })\` only for normal starts (\`pending\` / \`in_progress\`)
+5. Never loop \`continueFrom: "blocked"\` on non-blocked statuses
+6. If task status is blocked: read blocker info → \`question()\` → user decision → resume with \`continueFrom: "blocked"\`
+7. Skip polling — the result is available when \`task()\` returns
 
 ### Batch Merge + Verify Workflow
 When multiple tasks are in flight, prefer **batch completion** over per-task verification:
@@ -15008,8 +15010,9 @@ When multiple tasks are in flight, prefer **batch completion** over per-task ver
 ### Post-Batch Review (Hygienic)
 After completing and merging a batch:
 1. Ask the user via \`question()\` if they want a Hygienic code review for the batch.
-2. If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\`.
-3. Apply feedback before starting the next batch.
+2. If yes → default to built-in \`hygienic-reviewer\`; choose a configured hygienic-derived reviewer only when its description in \`Configured Custom Subagents\` is a better match.
+3. Then run \`task({ subagent_type: "<chosen-reviewer>", prompt: "Review implementation changes from the latest batch." })\`.
+4. Apply feedback before starting the next batch.
 
 ### AGENTS.md Maintenance
 After feature completion (all tasks merged):
@@ -15219,7 +15222,7 @@ Standard checks: specialized agent? can I do it myself for sure? external system
 ## Worker Spawning
 
 \`\`\`
-hive_worktree_create({ task: "01-task-name" })
+hive_worktree_start({ task: "01-task-name" })
 // If external system data is needed (parallel exploration):
 // Load hive_skill("parallel-exploration") for the full playbook, then:
 // In task mode, use task() for research fan-out.
@@ -15227,8 +15230,10 @@ hive_worktree_create({ task: "01-task-name" })
 
 Delegation guidance:
 - \`task()\` is BLOCKING — returns when the worker is done
-- Call \`hive_status()\` immediately after to check new state and find next runnable tasks
-- Invariant: delegated task must not remain \`in_progress\`; if it does, treat as non-terminal completion and resume/retry worker with explicit commit-result handling
+- After \`task()\` returns, call \`hive_status()\` immediately to check new state and find next runnable tasks before any resume attempt
+- Use \`continueFrom: "blocked"\` only when status is exactly \`blocked\`
+- If status is not \`blocked\`, do not use \`continueFrom: "blocked"\`; use \`hive_worktree_start({ feature, task })\` only for normal starts (\`pending\` / \`in_progress\`)
+- Never loop \`continueFrom: "blocked"\` on non-blocked statuses
 - For parallel fan-out, issue multiple \`task()\` calls in the same message
 
 ## After Delegation - VERIFY
@@ -15256,7 +15261,7 @@ After completing and merging a batch, run full verification on the main branch:
 
 ## Blocker Handling
 
-When worker reports blocked: \`hive_status()\` → read blocker info; \`question()\` → ask user (no plain text); \`hive_worktree_create({ task, continueFrom: "blocked", decision })\`.
+When worker reports blocked: \`hive_status()\` → confirm status is exactly \`blocked\` → read blocker info; \`question()\` → ask user (no plain text); \`hive_worktree_create({ task, continueFrom: "blocked", decision })\`. If status is not \`blocked\`, do not use blocked resume; only use \`hive_worktree_start({ feature, task })\` for normal starts (\`pending\` / \`in_progress\`).
 
 ## Failure Recovery (After 3 Consecutive Failures)
 
@@ -15275,7 +15280,9 @@ Merge after batch completes, then verify the merged result.
 
 ### Post-Batch Review (Hygienic)
 
-After completing and merging a batch: ask via \`question()\` if they want a Hygienic review. If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\` and apply feedback before the next batch.
+After completing and merging a batch: ask via \`question()\` if they want a Hygienic review.
+If yes, default to built-in \`hygienic-reviewer\`; choose a configured hygienic-derived reviewer only when its description in \`Configured Custom Subagents\` is a better match.
+Then run \`task({ subagent_type: "<chosen-reviewer>", prompt: "Review implementation changes from the latest batch." })\` and apply feedback before the next batch.
 
 ### AGENTS.md Maintenance
 
@@ -15289,7 +15296,7 @@ For projects without AGENTS.md:
 
 ## Turn Termination
 
-Valid endings: worker delegation (hive_worktree_create), status check (hive_status), user question (question()), merge (hive_merge).
+Valid endings: worker delegation (hive_worktree_start/hive_worktree_create), status check (hive_status), user question (question()), merge (hive_merge).
 Avoid ending with: "Let me know when you're ready", "When you're ready...", summary without next action, or waiting for something unspecified.
 
 ## Guardrails
@@ -15653,6 +15660,33 @@ Before verdict, mentally execute 2-3 tasks:
 - Focus on worker success, not perfection
 `;
 
+// src/agents/custom-agents.ts
+function buildCustomSubagents({
+  customAgents,
+  baseAgents,
+  autoLoadedSkills = {}
+}) {
+  const derived = {};
+  for (const [agentName, customConfig] of Object.entries(customAgents)) {
+    const baseAgent = baseAgents[customConfig.baseAgent];
+    if (!baseAgent) {
+      continue;
+    }
+    const autoLoadedSkillsContent = autoLoadedSkills[agentName] ?? "";
+    derived[agentName] = {
+      model: customConfig.model ?? baseAgent.model,
+      variant: customConfig.variant ?? baseAgent.variant,
+      temperature: customConfig.temperature ?? baseAgent.temperature,
+      mode: "subagent",
+      description: customConfig.description,
+      prompt: baseAgent.prompt + autoLoadedSkillsContent,
+      tools: baseAgent.tools,
+      permission: baseAgent.permission
+    };
+  }
+  return derived;
+}
+
 // src/mcp/websearch.ts
 var websearchMcp = {
   type: "remote",
@@ -16554,6 +16588,28 @@ var require_dist2 = __commonJS((exports) => {
   exports.createDeferred = deferred;
   exports.default = deferred;
 });
+var BUILT_IN_AGENT_NAMES = [
+  "hive-master",
+  "architect-planner",
+  "swarm-orchestrator",
+  "scout-researcher",
+  "forager-worker",
+  "hygienic-reviewer"
+];
+var CUSTOM_AGENT_BASES = ["forager-worker", "hygienic-reviewer"];
+var CUSTOM_AGENT_RESERVED_NAMES = [
+  ...BUILT_IN_AGENT_NAMES,
+  "hive",
+  "architect",
+  "swarm",
+  "scout",
+  "forager",
+  "hygienic",
+  "receiver",
+  "build",
+  "plan",
+  "code"
+];
 var DEFAULT_AGENT_MODELS = {
   "hive-master": "github-copilot/claude-opus-4.5",
   "architect-planner": "github-copilot/gpt-5.2-codex",
@@ -16569,6 +16625,21 @@ var DEFAULT_HIVE_CONFIG = {
   disableMcps: [],
   agentMode: "unified",
   sandbox: "none",
+  customAgents: {
+    "forager-example-template": {
+      baseAgent: "forager-worker",
+      description: "Example template only: rename or delete this entry before use. Do not expect planners/orchestrators to select this placeholder agent as configured.",
+      model: "anthropic/claude-sonnet-4-20250514",
+      temperature: 0.2,
+      variant: "high",
+      autoLoadSkills: ["test-driven-development"]
+    },
+    "hygienic-example-template": {
+      baseAgent: "hygienic-reviewer",
+      description: "Example template only: rename or delete this entry before use. Do not expect planners/orchestrators to select this placeholder agent as configured.",
+      autoLoadSkills: ["code-reviewer"]
+    }
+  },
   agents: {
     "hive-master": {
       model: DEFAULT_AGENT_MODELS["hive-master"],
@@ -22143,6 +22214,7 @@ ${f.content}`);
 class ConfigService {
   configPath;
   cachedConfig = null;
+  cachedCustomAgentConfigs = null;
   constructor() {
     const homeDir = process.env.HOME || process.env.USERPROFILE || "";
     const configDir = path6.join(homeDir, ".config", "opencode");
@@ -22158,51 +22230,44 @@ class ConfigService {
     try {
       if (!fs10.existsSync(this.configPath)) {
         this.cachedConfig = { ...DEFAULT_HIVE_CONFIG };
+        this.cachedCustomAgentConfigs = null;
         return this.cachedConfig;
       }
       const raw = fs10.readFileSync(this.configPath, "utf-8");
       const stored = JSON.parse(raw);
+      const storedCustomAgents = this.isObjectRecord(stored.customAgents) ? stored.customAgents : {};
+      const mergedBuiltInAgents = BUILT_IN_AGENT_NAMES.reduce((acc, agentName) => {
+        acc[agentName] = {
+          ...DEFAULT_HIVE_CONFIG.agents?.[agentName],
+          ...stored.agents?.[agentName]
+        };
+        return acc;
+      }, {});
       const merged = {
         ...DEFAULT_HIVE_CONFIG,
         ...stored,
         agents: {
           ...DEFAULT_HIVE_CONFIG.agents,
           ...stored.agents,
-          "hive-master": {
-            ...DEFAULT_HIVE_CONFIG.agents?.["hive-master"],
-            ...stored.agents?.["hive-master"]
-          },
-          "architect-planner": {
-            ...DEFAULT_HIVE_CONFIG.agents?.["architect-planner"],
-            ...stored.agents?.["architect-planner"]
-          },
-          "swarm-orchestrator": {
-            ...DEFAULT_HIVE_CONFIG.agents?.["swarm-orchestrator"],
-            ...stored.agents?.["swarm-orchestrator"]
-          },
-          "scout-researcher": {
-            ...DEFAULT_HIVE_CONFIG.agents?.["scout-researcher"],
-            ...stored.agents?.["scout-researcher"]
-          },
-          "forager-worker": {
-            ...DEFAULT_HIVE_CONFIG.agents?.["forager-worker"],
-            ...stored.agents?.["forager-worker"]
-          },
-          "hygienic-reviewer": {
-            ...DEFAULT_HIVE_CONFIG.agents?.["hygienic-reviewer"],
-            ...stored.agents?.["hygienic-reviewer"]
-          }
+          ...mergedBuiltInAgents
+        },
+        customAgents: {
+          ...DEFAULT_HIVE_CONFIG.customAgents,
+          ...storedCustomAgents
         }
       };
       this.cachedConfig = merged;
+      this.cachedCustomAgentConfigs = null;
       return this.cachedConfig;
     } catch {
       this.cachedConfig = { ...DEFAULT_HIVE_CONFIG };
+      this.cachedCustomAgentConfigs = null;
       return this.cachedConfig;
     }
   }
   set(updates) {
     this.cachedConfig = null;
+    this.cachedCustomAgentConfigs = null;
     const current = this.get();
     const merged = {
       ...current,
@@ -22210,7 +22275,11 @@ class ConfigService {
       agents: updates.agents ? {
         ...current.agents,
         ...updates.agents
-      } : current.agents
+      } : current.agents,
+      customAgents: updates.customAgents ? {
+        ...current.customAgents,
+        ...updates.customAgents
+      } : current.customAgents
     };
     const configDir = path6.dirname(this.configPath);
     if (!fs10.existsSync(configDir)) {
@@ -22218,6 +22287,7 @@ class ConfigService {
     }
     fs10.writeFileSync(this.configPath, JSON.stringify(merged, null, 2));
     this.cachedConfig = merged;
+    this.cachedCustomAgentConfigs = null;
     return merged;
   }
   exists() {
@@ -22231,20 +22301,94 @@ class ConfigService {
   }
   getAgentConfig(agent) {
     const config2 = this.get();
-    const agentConfig = config2.agents?.[agent] ?? {};
-    const defaultAutoLoadSkills = DEFAULT_HIVE_CONFIG.agents?.[agent]?.autoLoadSkills ?? [];
-    const userAutoLoadSkills = agentConfig.autoLoadSkills ?? [];
-    const isPlannerAgent = agent === "hive-master" || agent === "architect-planner";
-    const effectiveUserAutoLoadSkills = isPlannerAgent ? userAutoLoadSkills : userAutoLoadSkills.filter((skill) => skill !== "onboarding");
-    const effectiveDefaultAutoLoadSkills = isPlannerAgent ? defaultAutoLoadSkills : defaultAutoLoadSkills.filter((skill) => skill !== "onboarding");
-    const combinedAutoLoadSkills = [...effectiveDefaultAutoLoadSkills, ...effectiveUserAutoLoadSkills];
+    if (this.isBuiltInAgent(agent)) {
+      const agentConfig = config2.agents?.[agent] ?? {};
+      const defaultAutoLoadSkills = DEFAULT_HIVE_CONFIG.agents?.[agent]?.autoLoadSkills ?? [];
+      const effectiveAutoLoadSkills = this.resolveAutoLoadSkills(defaultAutoLoadSkills, agentConfig.autoLoadSkills ?? [], this.isPlannerAgent(agent));
+      return {
+        ...agentConfig,
+        autoLoadSkills: effectiveAutoLoadSkills
+      };
+    }
+    const customAgents = this.getCustomAgentConfigs();
+    return customAgents[agent] ?? {};
+  }
+  getCustomAgentConfigs() {
+    if (this.cachedCustomAgentConfigs !== null) {
+      return this.cachedCustomAgentConfigs;
+    }
+    const config2 = this.get();
+    const customAgents = this.isObjectRecord(config2.customAgents) ? config2.customAgents : {};
+    const resolved = {};
+    for (const [agentName, declaration] of Object.entries(customAgents)) {
+      if (this.isReservedCustomAgentName(agentName)) {
+        console.warn(`[hive:config] Skipping custom agent "${agentName}": reserved name`);
+        continue;
+      }
+      if (!this.isObjectRecord(declaration)) {
+        console.warn(`[hive:config] Skipping custom agent "${agentName}": invalid declaration (expected object)`);
+        continue;
+      }
+      const baseAgent = declaration["baseAgent"];
+      if (typeof baseAgent !== "string" || !this.isSupportedCustomAgentBase(baseAgent)) {
+        console.warn(`[hive:config] Skipping custom agent "${agentName}": unsupported baseAgent "${String(baseAgent)}"`);
+        continue;
+      }
+      const autoLoadSkillsValue = declaration["autoLoadSkills"];
+      const additionalAutoLoadSkills = Array.isArray(autoLoadSkillsValue) ? autoLoadSkillsValue.filter((skill) => typeof skill === "string") : [];
+      const baseAgentConfig = this.getAgentConfig(baseAgent);
+      const effectiveAutoLoadSkills = this.resolveAutoLoadSkills(baseAgentConfig.autoLoadSkills ?? [], additionalAutoLoadSkills, this.isPlannerAgent(baseAgent));
+      const descriptionValue = declaration["description"];
+      const description = typeof descriptionValue === "string" ? descriptionValue.trim() : "";
+      if (!description) {
+        console.warn(`[hive:config] Skipping custom agent "${agentName}": description must be a non-empty string`);
+        continue;
+      }
+      const modelValue = declaration["model"];
+      const temperatureValue = declaration["temperature"];
+      const variantValue = declaration["variant"];
+      const model = typeof modelValue === "string" ? modelValue.trim() || baseAgentConfig.model : baseAgentConfig.model;
+      const variant = typeof variantValue === "string" ? variantValue.trim() || baseAgentConfig.variant : baseAgentConfig.variant;
+      resolved[agentName] = {
+        baseAgent,
+        description,
+        model,
+        temperature: typeof temperatureValue === "number" ? temperatureValue : baseAgentConfig.temperature,
+        variant,
+        autoLoadSkills: effectiveAutoLoadSkills
+      };
+    }
+    this.cachedCustomAgentConfigs = resolved;
+    return this.cachedCustomAgentConfigs;
+  }
+  hasConfiguredAgent(agent) {
+    if (this.isBuiltInAgent(agent)) {
+      return true;
+    }
+    const customAgents = this.getCustomAgentConfigs();
+    return customAgents[agent] !== undefined;
+  }
+  isBuiltInAgent(agent) {
+    return BUILT_IN_AGENT_NAMES.includes(agent);
+  }
+  isReservedCustomAgentName(agent) {
+    return CUSTOM_AGENT_RESERVED_NAMES.includes(agent);
+  }
+  isSupportedCustomAgentBase(baseAgent) {
+    return CUSTOM_AGENT_BASES.includes(baseAgent);
+  }
+  isPlannerAgent(agent) {
+    return agent === "hive-master" || agent === "architect-planner";
+  }
+  isObjectRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+  }
+  resolveAutoLoadSkills(baseAutoLoadSkills, additionalAutoLoadSkills, isPlannerAgent) {
+    const effectiveAdditionalSkills = isPlannerAgent ? additionalAutoLoadSkills : additionalAutoLoadSkills.filter((skill) => skill !== "onboarding");
+    const combinedAutoLoadSkills = [...baseAutoLoadSkills, ...effectiveAdditionalSkills];
     const uniqueAutoLoadSkills = Array.from(new Set(combinedAutoLoadSkills));
-    const disabledSkills = config2.disableSkills ?? [];
-    const effectiveAutoLoadSkills = uniqueAutoLoadSkills.filter((skill) => !disabledSkills.includes(skill));
-    return {
-      ...agentConfig,
-      autoLoadSkills: effectiveAutoLoadSkills
-    };
+    const disabledSkills = this.getDisabledSkills();
+    return uniqueAutoLoadSkills.filter((skill) => !disabledSkills.includes(skill));
   }
   isOmoSlimEnabled() {
     const config2 = this.get();
@@ -23075,23 +23219,28 @@ function writeWorkerPromptFile(feature, task, prompt, hiveDir) {
 }
 
 // src/hooks/variant-hook.ts
-var HIVE_AGENT_NAMES = [
-  "hive-master",
-  "architect-planner",
-  "swarm-orchestrator",
-  "scout-researcher",
-  "forager-worker",
-  "hygienic-reviewer"
-];
-function isHiveAgent(agent) {
-  return agent !== undefined && HIVE_AGENT_NAMES.includes(agent);
-}
 function normalizeVariant(variant) {
   if (variant === undefined)
     return;
   const trimmed2 = variant.trim();
   return trimmed2.length > 0 ? trimmed2 : undefined;
 }
+function createVariantHook(configService) {
+  return async (input, output) => {
+    const { agent } = input;
+    if (!agent)
+      return;
+    if (!configService.hasConfiguredAgent(agent))
+      return;
+    if (output.message.variant !== undefined)
+      return;
+    const agentConfig = configService.getAgentConfig(agent);
+    const configuredVariant = normalizeVariant(agentConfig.variant);
+    if (configuredVariant !== undefined) {
+      output.message.variant = configuredVariant;
+    }
+  };
+}
 
 // src/hooks/system-hook.ts
 var fallbackTurnCounters = {};
@@ -23138,9 +23287,8 @@ function formatSkillsXml(skills) {
 ${skillsXml}
 </available_skills>`;
 }
-async function buildAutoLoadedSkillsContent(agentName, configService, projectRoot) {
-  const agentConfig = configService.getAgentConfig(agentName);
-  const autoLoadSkills = agentConfig.autoLoadSkills ?? [];
+async function buildAutoLoadedSkillsContent(agentName, configService, projectRoot, autoLoadSkillsOverride) {
+  const autoLoadSkills = autoLoadSkillsOverride ?? (configService.getAgentConfig(agentName).autoLoadSkills ?? []);
   if (autoLoadSkills.length === 0) {
     return "";
   }
@@ -23295,6 +23443,392 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
     }
     return { allowed: true };
   };
+  const respond = (payload) => JSON.stringify(payload, null, 2);
+  const buildWorktreeLaunchResponse = async ({
+    feature,
+    task,
+    taskInfo,
+    worktree,
+    continueFrom,
+    decision
+  }) => {
+    taskService.update(feature, task, {
+      status: "in_progress",
+      baseCommit: worktree.commit
+    });
+    const planResult = planService.read(feature);
+    const allTasks = taskService.list(feature);
+    const rawContextFiles = contextService.list(feature).map((f) => ({
+      name: f.name,
+      content: f.content
+    }));
+    const rawPreviousTasks = allTasks.filter((t) => t.status === "done" && t.summary).map((t) => ({ name: t.folder, summary: t.summary }));
+    const taskBudgetResult = applyTaskBudget(rawPreviousTasks, { ...DEFAULT_BUDGET, feature });
+    const contextBudgetResult = applyContextBudget(rawContextFiles, { ...DEFAULT_BUDGET, feature });
+    const contextFiles = contextBudgetResult.files.map((f) => ({
+      name: f.name,
+      content: f.content
+    }));
+    const previousTasks = taskBudgetResult.tasks.map((t) => ({
+      name: t.name,
+      summary: t.summary
+    }));
+    const truncationEvents = [
+      ...taskBudgetResult.truncationEvents,
+      ...contextBudgetResult.truncationEvents
+    ];
+    const droppedTasksHint = taskBudgetResult.droppedTasksHint;
+    const taskOrder = parseInt(taskInfo.folder.match(/^(\d+)/)?.[1] || "0", 10);
+    const status = taskService.getRawStatus(feature, task);
+    const dependsOn = status?.dependsOn ?? [];
+    const specContent = taskService.buildSpecContent({
+      featureName: feature,
+      task: {
+        folder: task,
+        name: taskInfo.planTitle ?? taskInfo.name,
+        order: taskOrder,
+        description: undefined
+      },
+      dependsOn,
+      allTasks: allTasks.map((t) => ({
+        folder: t.folder,
+        name: t.name,
+        order: parseInt(t.folder.match(/^(\d+)/)?.[1] || "0", 10)
+      })),
+      planContent: planResult?.content ?? null,
+      contextFiles,
+      completedTasks: previousTasks
+    });
+    taskService.writeSpec(feature, task, specContent);
+    const workerPrompt = buildWorkerPrompt({
+      feature,
+      task,
+      taskOrder,
+      worktreePath: worktree.path,
+      branch: worktree.branch,
+      plan: planResult?.content || "No plan available",
+      contextFiles,
+      spec: specContent,
+      previousTasks,
+      continueFrom: continueFrom === "blocked" ? {
+        status: "blocked",
+        previousSummary: taskInfo.summary || "No previous summary",
+        decision: decision || "No decision provided"
+      } : undefined
+    });
+    const customAgentConfigs = configService.getCustomAgentConfigs();
+    const defaultAgent = "forager-worker";
+    const eligibleAgents = [
+      {
+        name: defaultAgent,
+        baseAgent: defaultAgent,
+        description: "Default implementation worker"
+      },
+      ...Object.entries(customAgentConfigs).filter(([, config2]) => config2.baseAgent === "forager-worker").sort(([left], [right]) => left.localeCompare(right)).map(([name, config2]) => ({
+        name,
+        baseAgent: config2.baseAgent,
+        description: config2.description
+      }))
+    ];
+    const agent = defaultAgent;
+    const rawStatus = taskService.getRawStatus(feature, task);
+    const attempt = (rawStatus?.workerSession?.attempt || 0) + 1;
+    const idempotencyKey = `hive-${feature}-${task}-${attempt}`;
+    taskService.patchBackgroundFields(feature, task, { idempotencyKey });
+    const contextContent = contextFiles.map((f) => f.content).join(`
+
+`);
+    const previousTasksContent = previousTasks.map((t) => `- **${t.name}**: ${t.summary}`).join(`
+`);
+    const promptMeta = calculatePromptMeta({
+      plan: planResult?.content || "",
+      context: contextContent,
+      previousTasks: previousTasksContent,
+      spec: specContent,
+      workerPrompt
+    });
+    const hiveDir = path8.join(directory, ".hive");
+    const workerPromptPath = writeWorkerPromptFile(feature, task, workerPrompt, hiveDir);
+    const relativePromptPath = normalizePath(path8.relative(directory, workerPromptPath));
+    const PREVIEW_MAX_LENGTH = 200;
+    const workerPromptPreview = workerPrompt.length > PREVIEW_MAX_LENGTH ? workerPrompt.slice(0, PREVIEW_MAX_LENGTH) + "..." : workerPrompt;
+    const taskToolPrompt = `Follow instructions in @${relativePromptPath}`;
+    const taskToolInstructions = `## Delegation Required
+
+Choose one of the eligible forager-derived agents below.
+Default to \`${defaultAgent}\` if no specialist is a better match.
+
+${eligibleAgents.map((candidate) => `- \`${candidate.name}\` — ${candidate.description}`).join(`
+`)}
+
+Use OpenCode's built-in \`task\` tool with the chosen \`subagent_type\` and the provided \`taskToolCall.prompt\` value.
+\`taskToolCall.subagent_type\` is prefilled with the default for convenience; override it when a specialist in \`eligibleAgents\` is a better match.
+
+\`\`\`
+task({
+  subagent_type: "<chosen-agent>",
+  description: "Hive: ${task}",
+  prompt: "${taskToolPrompt}"
+})
+\`\`\`
+
+Use the \`@path\` attachment syntax in the prompt to reference the file. Do not inline the file contents.
+
+`;
+    const responseBase = {
+      success: true,
+      terminal: false,
+      worktreePath: worktree.path,
+      branch: worktree.branch,
+      mode: "delegate",
+      agent,
+      defaultAgent,
+      eligibleAgents,
+      delegationRequired: true,
+      workerPromptPath: relativePromptPath,
+      workerPromptPreview,
+      taskPromptMode: "opencode-at-file",
+      taskToolCall: {
+        subagent_type: agent,
+        description: `Hive: ${task}`,
+        prompt: taskToolPrompt
+      },
+      instructions: taskToolInstructions
+    };
+    const jsonPayload = JSON.stringify(responseBase, null, 2);
+    const payloadMeta = calculatePayloadMeta({
+      jsonPayload,
+      promptInlined: false,
+      promptReferencedByFile: true
+    });
+    const sizeWarnings = checkWarnings(promptMeta, payloadMeta);
+    const budgetWarnings = truncationEvents.map((event) => ({
+      type: event.type,
+      severity: "info",
+      message: event.message,
+      affected: event.affected,
+      count: event.count
+    }));
+    const allWarnings = [...sizeWarnings, ...budgetWarnings];
+    return respond({
+      ...responseBase,
+      promptMeta,
+      payloadMeta,
+      budgetApplied: {
+        maxTasks: DEFAULT_BUDGET.maxTasks,
+        maxSummaryChars: DEFAULT_BUDGET.maxSummaryChars,
+        maxContextChars: DEFAULT_BUDGET.maxContextChars,
+        maxTotalContextChars: DEFAULT_BUDGET.maxTotalContextChars,
+        tasksIncluded: previousTasks.length,
+        tasksDropped: rawPreviousTasks.length - previousTasks.length,
+        droppedTasksHint
+      },
+      warnings: allWarnings.length > 0 ? allWarnings : undefined
+    });
+  };
+  const executeWorktreeStart = async ({
+    task,
+    feature: explicitFeature
+  }) => {
+    const feature = resolveFeature(explicitFeature);
+    if (!feature) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: "No feature specified. Create a feature or provide feature param.",
+        reason: "feature_required",
+        task,
+        hints: [
+          "Create/select a feature first or pass the feature parameter explicitly.",
+          "Use hive_status to inspect the active feature state before retrying."
+        ]
+      });
+    }
+    const blockedMessage = checkBlocked(feature);
+    if (blockedMessage) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: blockedMessage,
+        reason: "feature_blocked",
+        feature,
+        task,
+        hints: [
+          "Wait for the human to unblock the feature before retrying.",
+          `If approved, remove .hive/features/${feature}/BLOCKED and retry hive_worktree_start.`
+        ]
+      });
+    }
+    const taskInfo = taskService.get(feature, task);
+    if (!taskInfo) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `Task "${task}" not found`,
+        reason: "task_not_found",
+        feature,
+        task,
+        hints: [
+          "Check the task folder name in tasks.json or hive_status output.",
+          "Run hive_tasks_sync if the approved plan has changed and tasks need regeneration."
+        ]
+      });
+    }
+    if (taskInfo.status === "done") {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `Task "${task}" is already completed (status: done). It cannot be restarted.`,
+        currentStatus: "done",
+        hints: [
+          "Use hive_merge to integrate the completed task branch if not already merged.",
+          "Use hive_status to see all task states and find the next runnable task."
+        ]
+      });
+    }
+    if (taskInfo.status === "blocked") {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `Task "${task}" is blocked and must be resumed with hive_worktree_create using continueFrom: 'blocked'.`,
+        currentStatus: "blocked",
+        feature,
+        task,
+        hints: [
+          'Ask the user the blocker question, then call hive_worktree_create({ task, continueFrom: "blocked", decision }).',
+          "Use hive_status to inspect blocker details before retrying."
+        ]
+      });
+    }
+    const depCheck = checkDependencies(feature, task);
+    if (!depCheck.allowed) {
+      return respond({
+        success: false,
+        terminal: true,
+        reason: "dependencies_not_done",
+        feature,
+        task,
+        error: depCheck.error,
+        hints: [
+          "Complete the required dependencies before starting this task.",
+          "Use hive_status to see current task states."
+        ]
+      });
+    }
+    const worktree = await worktreeService.create(feature, task);
+    return buildWorktreeLaunchResponse({ feature, task, taskInfo, worktree });
+  };
+  const executeBlockedResume = async ({
+    task,
+    feature: explicitFeature,
+    continueFrom,
+    decision
+  }) => {
+    const feature = resolveFeature(explicitFeature);
+    if (!feature) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: "No feature specified. Create a feature or provide feature param.",
+        reason: "feature_required",
+        task,
+        hints: [
+          "Create/select a feature first or pass the feature parameter explicitly.",
+          "Use hive_status to inspect the active feature state before retrying."
+        ]
+      });
+    }
+    const blockedMessage = checkBlocked(feature);
+    if (blockedMessage) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: blockedMessage,
+        reason: "feature_blocked",
+        feature,
+        task,
+        hints: [
+          "Wait for the human to unblock the feature before retrying.",
+          `If approved, remove .hive/features/${feature}/BLOCKED and retry hive_worktree_create.`
+        ]
+      });
+    }
+    const taskInfo = taskService.get(feature, task);
+    if (!taskInfo) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `Task "${task}" not found`,
+        reason: "task_not_found",
+        feature,
+        task,
+        hints: [
+          "Check the task folder name in tasks.json or hive_status output.",
+          "Run hive_tasks_sync if the approved plan has changed and tasks need regeneration."
+        ]
+      });
+    }
+    if (taskInfo.status === "done") {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `Task "${task}" is already completed (status: done). It cannot be restarted.`,
+        currentStatus: "done",
+        hints: [
+          "Use hive_merge to integrate the completed task branch if not already merged.",
+          "Use hive_status to see all task states and find the next runnable task."
+        ]
+      });
+    }
+    if (continueFrom !== "blocked") {
+      return respond({
+        success: false,
+        terminal: true,
+        error: "hive_worktree_create is only for resuming blocked tasks.",
+        reason: "blocked_resume_required",
+        currentStatus: taskInfo.status,
+        feature,
+        task,
+        hints: [
+          "Use hive_worktree_start({ feature, task }) to start a pending or in-progress task normally.",
+          'Use hive_worktree_create({ task, continueFrom: "blocked", decision }) only after hive_status confirms the task is blocked.'
+        ]
+      });
+    }
+    if (taskInfo.status !== "blocked") {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `continueFrom: 'blocked' was specified but task "${task}" is not in blocked state (current status: ${taskInfo.status}).`,
+        currentStatus: taskInfo.status,
+        hints: [
+          "Use hive_worktree_start({ feature, task }) for normal starts or re-dispatch.",
+          "Use hive_status to verify the current task status before retrying."
+        ]
+      });
+    }
+    const worktree = await worktreeService.get(feature, task);
+    if (!worktree) {
+      return respond({
+        success: false,
+        terminal: true,
+        error: `Cannot resume blocked task "${task}": no existing worktree record found.`,
+        currentStatus: taskInfo.status,
+        hints: [
+          "The worktree may have been removed manually. Use hive_worktree_discard to reset the task to pending, then restart it with hive_worktree_start.",
+          "Use hive_status to inspect the current state of the task and its worktree."
+        ]
+      });
+    }
+    return buildWorktreeLaunchResponse({
+      feature,
+      task,
+      taskInfo,
+      worktree,
+      continueFrom,
+      decision
+    });
+  };
   return {
     "experimental.chat.system.transform": async (input, output) => {
       if (!shouldExecuteHook("experimental.chat.system.transform", configService, turnCounters)) {
@@ -23323,20 +23857,7 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
     "experimental.session.compacting": async (_input, output) => {
       output.context.push(buildCompactionPrompt());
     },
-    "chat.message": async (input, output) => {
-      const { agent } = input;
-      if (!agent)
-        return;
-      if (!isHiveAgent(agent))
-        return;
-      if (output.message.variant !== undefined)
-        return;
-      const agentConfig = configService.getAgentConfig(agent);
-      const configuredVariant = normalizeVariant(agentConfig.variant);
-      if (configuredVariant !== undefined) {
-        output.message.variant = configuredVariant;
-      }
-    },
+    "chat.message": createVariantHook(configService),
     "tool.execute.before": async (input, output) => {
       if (!shouldExecuteHook("tool.execute.before", configService, turnCounters, { safetyCritical: true })) {
         return;
@@ -23529,7 +24050,7 @@ Expand your Discovery section and try again.`;
             return "Error: No feature specified. Create a feature or provide feature param.";
           const folder = taskService.create(feature, name, order);
           return `Manual task created: ${folder}
-Reminder: start work with hive_worktree_create to use its worktree, and ensure any subagents work in that worktree too.`;
+Reminder: start work with hive_worktree_start to use its worktree, and ensure any subagents work in that worktree too.`;
         }
       }),
       hive_task_update: tool({
@@ -23551,198 +24072,26 @@ Reminder: start work with hive_worktree_create to use its worktree, and ensure a
           return `Task "${task}" updated: status=${updated.status}`;
         }
       }),
+      hive_worktree_start: tool({
+        description: "Create worktree and begin work on pending/in-progress task. Spawns Forager worker automatically.",
+        args: {
+          task: tool.schema.string().describe("Task folder name"),
+          feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)")
+        },
+        async execute({ task, feature: explicitFeature }) {
+          return executeWorktreeStart({ task, feature: explicitFeature });
+        }
+      }),
       hive_worktree_create: tool({
-        description: "Create worktree and begin work on task. Spawns Forager worker automatically.",
+        description: "Resume a blocked task in its existing worktree. Spawns Forager worker automatically.",
         args: {
           task: tool.schema.string().describe("Task folder name"),
           feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)"),
           continueFrom: tool.schema.enum(["blocked"]).optional().describe("Resume a blocked task"),
           decision: tool.schema.string().optional().describe("Answer to blocker question when continuing")
         },
-        async execute({ task, feature: explicitFeature, continueFrom, decision }, toolContext) {
-          const feature = resolveFeature(explicitFeature);
-          if (!feature)
-            return "Error: No feature specified. Create a feature or provide feature param.";
-          const blockedMessage = checkBlocked(feature);
-          if (blockedMessage)
-            return blockedMessage;
-          const taskInfo = taskService.get(feature, task);
-          if (!taskInfo)
-            return `Error: Task "${task}" not found`;
-          if (taskInfo.status === "done")
-            return "Error: Task already completed";
-          if (continueFrom === "blocked" && taskInfo.status !== "blocked") {
-            return "Error: Task is not in blocked state. Use without continueFrom.";
-          }
-          if (continueFrom !== "blocked") {
-            const depCheck = checkDependencies(feature, task);
-            if (!depCheck.allowed) {
-              return JSON.stringify({
-                success: false,
-                error: depCheck.error,
-                hints: [
-                  "Complete the required dependencies before starting this task.",
-                  "Use hive_status to see current task states."
-                ]
-              });
-            }
-          }
-          let worktree;
-          if (continueFrom === "blocked") {
-            worktree = await worktreeService.get(feature, task);
-            if (!worktree)
-              return "Error: No worktree found for blocked task";
-          } else {
-            worktree = await worktreeService.create(feature, task);
-          }
-          taskService.update(feature, task, {
-            status: "in_progress",
-            baseCommit: worktree.commit
-          });
-          const planResult = planService.read(feature);
-          const allTasks = taskService.list(feature);
-          const rawContextFiles = contextService.list(feature).map((f) => ({
-            name: f.name,
-            content: f.content
-          }));
-          const rawPreviousTasks = allTasks.filter((t) => t.status === "done" && t.summary).map((t) => ({ name: t.folder, summary: t.summary }));
-          const taskBudgetResult = applyTaskBudget(rawPreviousTasks, { ...DEFAULT_BUDGET, feature });
-          const contextBudgetResult = applyContextBudget(rawContextFiles, { ...DEFAULT_BUDGET, feature });
-          const contextFiles = contextBudgetResult.files.map((f) => ({
-            name: f.name,
-            content: f.content
-          }));
-          const previousTasks = taskBudgetResult.tasks.map((t) => ({
-            name: t.name,
-            summary: t.summary
-          }));
-          const truncationEvents = [
-            ...taskBudgetResult.truncationEvents,
-            ...contextBudgetResult.truncationEvents
-          ];
-          const droppedTasksHint = taskBudgetResult.droppedTasksHint;
-          const taskOrder = parseInt(taskInfo.folder.match(/^(\d+)/)?.[1] || "0", 10);
-          const status = taskService.getRawStatus(feature, task);
-          const dependsOn = status?.dependsOn ?? [];
-          const specContent = taskService.buildSpecContent({
-            featureName: feature,
-            task: {
-              folder: task,
-              name: taskInfo.planTitle ?? taskInfo.name,
-              order: taskOrder,
-              description: undefined
-            },
-            dependsOn,
-            allTasks: allTasks.map((t) => ({
-              folder: t.folder,
-              name: t.name,
-              order: parseInt(t.folder.match(/^(\d+)/)?.[1] || "0", 10)
-            })),
-            planContent: planResult?.content ?? null,
-            contextFiles,
-            completedTasks: previousTasks
-          });
-          taskService.writeSpec(feature, task, specContent);
-          const workerPrompt = buildWorkerPrompt({
-            feature,
-            task,
-            taskOrder: parseInt(taskInfo.folder.match(/^(\d+)/)?.[1] || "0", 10),
-            worktreePath: worktree.path,
-            branch: worktree.branch,
-            plan: planResult?.content || "No plan available",
-            contextFiles,
-            spec: specContent,
-            previousTasks,
-            continueFrom: continueFrom === "blocked" ? {
-              status: "blocked",
-              previousSummary: taskInfo.summary || "No previous summary",
-              decision: decision || "No decision provided"
-            } : undefined
-          });
-          const agent = "forager-worker";
-          const rawStatus = taskService.getRawStatus(feature, task);
-          const attempt = (rawStatus?.workerSession?.attempt || 0) + 1;
-          const idempotencyKey = `hive-${feature}-${task}-${attempt}`;
-          taskService.patchBackgroundFields(feature, task, { idempotencyKey });
-          const contextContent = contextFiles.map((f) => f.content).join(`
-
-`);
-          const previousTasksContent = previousTasks.map((t) => `- **${t.name}**: ${t.summary}`).join(`
-`);
-          const promptMeta = calculatePromptMeta({
-            plan: planResult?.content || "",
-            context: contextContent,
-            previousTasks: previousTasksContent,
-            spec: specContent,
-            workerPrompt
-          });
-          const hiveDir = path8.join(directory, ".hive");
-          const workerPromptPath = writeWorkerPromptFile(feature, task, workerPrompt, hiveDir);
-          const relativePromptPath = normalizePath(path8.relative(directory, workerPromptPath));
-          const PREVIEW_MAX_LENGTH = 200;
-          const workerPromptPreview = workerPrompt.length > PREVIEW_MAX_LENGTH ? workerPrompt.slice(0, PREVIEW_MAX_LENGTH) + "..." : workerPrompt;
-          const taskToolPrompt = `Follow instructions in @${relativePromptPath}`;
-          const taskToolInstructions = `## Delegation Required
-
-Use OpenCode's built-in \`task\` tool to spawn a Forager (Worker/Coder) worker.
-
-\`\`\`
-task({
-  subagent_type: "${agent}",
-  description: "Hive: ${task}",
-  prompt: "${taskToolPrompt}"
-})
-\`\`\`
-
-Use the \`@path\` attachment syntax in the prompt to reference the file. Do not inline the file contents.
-
-`;
-          const responseBase = {
-            worktreePath: worktree.path,
-            branch: worktree.branch,
-            mode: "delegate",
-            agent,
-            delegationRequired: true,
-            workerPromptPath: relativePromptPath,
-            workerPromptPreview,
-            taskPromptMode: "opencode-at-file",
-            taskToolCall: {
-              subagent_type: agent,
-              description: `Hive: ${task}`,
-              prompt: taskToolPrompt
-            },
-            instructions: taskToolInstructions
-          };
-          const jsonPayload = JSON.stringify(responseBase, null, 2);
-          const payloadMeta = calculatePayloadMeta({
-            jsonPayload,
-            promptInlined: false,
-            promptReferencedByFile: true
-          });
-          const sizeWarnings = checkWarnings(promptMeta, payloadMeta);
-          const budgetWarnings = truncationEvents.map((event) => ({
-            type: event.type,
-            severity: "info",
-            message: event.message,
-            affected: event.affected,
-            count: event.count
-          }));
-          const allWarnings = [...sizeWarnings, ...budgetWarnings];
-          return JSON.stringify({
-            ...responseBase,
-            promptMeta,
-            payloadMeta,
-            budgetApplied: {
-              maxTasks: DEFAULT_BUDGET.maxTasks,
-              maxSummaryChars: DEFAULT_BUDGET.maxSummaryChars,
-              maxContextChars: DEFAULT_BUDGET.maxContextChars,
-              maxTotalContextChars: DEFAULT_BUDGET.maxTotalContextChars,
-              tasksIncluded: previousTasks.length,
-              tasksDropped: rawPreviousTasks.length - previousTasks.length,
-              droppedTasksHint
-            },
-            warnings: allWarnings.length > 0 ? allWarnings : undefined
-          }, null, 2);
+        async execute({ task, feature: explicitFeature, continueFrom, decision }) {
+          return executeBlockedResume({ task, feature: explicitFeature, continueFrom, decision });
         }
       }),
       hive_worktree_commit: tool({
@@ -23760,10 +24109,10 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
           feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)")
         },
         async execute({ task, summary, status = "completed", blocker, feature: explicitFeature }) {
-          const respond = (payload) => JSON.stringify(payload, null, 2);
+          const respond2 = (payload) => JSON.stringify(payload, null, 2);
           const feature = resolveFeature(explicitFeature);
           if (!feature) {
-            return respond({
+            return respond2({
               ok: false,
               terminal: false,
               status: "error",
@@ -23776,7 +24125,7 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
           }
           const taskInfo = taskService.get(feature, task);
           if (!taskInfo) {
-            return respond({
+            return respond2({
               ok: false,
               terminal: false,
               status: "error",
@@ -23789,7 +24138,7 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
             });
           }
           if (taskInfo.status !== "in_progress" && taskInfo.status !== "blocked") {
-            return respond({
+            return respond2({
               ok: false,
               terminal: false,
               status: "error",
@@ -23817,7 +24166,7 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
               blocker
             });
             const worktree2 = await worktreeService.get(feature, task);
-            return respond({
+            return respond2({
               ok: true,
               terminal: true,
               status: "blocked",
@@ -23835,7 +24184,7 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
           }
           const commitResult = await worktreeService.commitChanges(feature, task, `hive(${task}): ${summary.slice(0, 50)}`);
           if (status === "completed" && !commitResult.committed && commitResult.message !== "No changes to commit") {
-            return respond({
+            return respond2({
               ok: false,
               terminal: false,
               status: "rejected",
@@ -23887,7 +24236,7 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
           const finalStatus = status === "completed" ? "done" : status;
           taskService.update(feature, task, { status: finalStatus, summary });
           const worktree = await worktreeService.get(feature, task);
-          return respond({
+          return respond2({
             ok: true,
             terminal: true,
             status,
@@ -23977,23 +24326,40 @@ Files changed: ${result.filesChanged?.length || 0}`;
           feature: tool.schema.string().optional().describe("Feature name (defaults to active)")
         },
         async execute({ feature: explicitFeature }) {
+          const respond2 = (payload) => JSON.stringify(payload, null, 2);
           const feature = resolveFeature(explicitFeature);
           if (!feature) {
-            return JSON.stringify({
+            return respond2({
+              success: false,
+              terminal: true,
+              reason: "feature_required",
               error: "No feature specified and no active feature found",
               hint: "Use hive_feature_create to create a new feature"
             });
           }
           const featureData = featureService.get(feature);
           if (!featureData) {
-            return JSON.stringify({
+            return respond2({
+              success: false,
+              terminal: true,
+              reason: "feature_not_found",
               error: `Feature '${feature}' not found`,
               availableFeatures: featureService.list()
             });
           }
           const blocked = checkBlocked(feature);
-          if (blocked)
-            return blocked;
+          if (blocked) {
+            return respond2({
+              success: false,
+              terminal: true,
+              blocked: true,
+              error: blocked,
+              hints: [
+                "Read the blocker details and resolve them before retrying hive_status.",
+                `Remove .hive/features/${feature}/BLOCKED once the blocker is resolved.`
+              ]
+            });
+          }
           const plan = planService.read(feature);
           const tasks = taskService.list(feature);
           const contextFiles = contextService.list(feature);
@@ -24050,7 +24416,7 @@ Files changed: ${result.filesChanged?.length || 0}`;
               return `${runnableTasks.length} tasks are ready to start in parallel: ${runnableTasks.join(", ")}`;
             }
             if (runnableTasks.length === 1) {
-              return `Start next task with hive_worktree_create: ${runnableTasks[0]}`;
+              return `Start next task with hive_worktree_start: ${runnableTasks[0]}`;
             }
             const pending = tasks2.find((t) => t.status === "pending");
             if (pending) {
@@ -24059,7 +24425,7 @@ Files changed: ${result.filesChanged?.length || 0}`;
             return "All tasks complete. Review and merge or complete feature.";
           };
           const planStatus = featureData.status === "planning" ? "draft" : featureData.status === "approved" ? "approved" : featureData.status === "executing" ? "locked" : "none";
-          return JSON.stringify({
+          return respond2({
             feature: {
               name: feature,
               status: featureData.status,
@@ -24152,6 +24518,7 @@ ${result.diff}
           "hive_tasks_sync",
           "hive_task_create",
           "hive_task_update",
+          "hive_worktree_start",
           "hive_worktree_create",
           "hive_worktree_commit",
           "hive_worktree_discard",
@@ -24170,6 +24537,14 @@ ${result.diff}
         return result;
       }
       configService.init();
+      const hiveConfigData = configService.get();
+      const agentMode = hiveConfigData.agentMode ?? "unified";
+      const customAgentConfigs = configService.getCustomAgentConfigs();
+      const customSubagentAppendix = Object.keys(customAgentConfigs).length === 0 ? "" : `
+
+## Configured Custom Subagents
+${Object.entries(customAgentConfigs).sort(([left], [right]) => left.localeCompare(right)).map(([name, config2]) => `- \`${name}\` — derived from \`${config2.baseAgent}\`; ${config2.description}`).join(`
+`)}`;
       const hiveUserConfig = configService.getAgentConfig("hive-master");
       const hiveAutoLoadedSkills = await buildAutoLoadedSkillsContent("hive-master", configService, directory);
       const hiveConfig = {
@@ -24177,7 +24552,7 @@ ${result.diff}
         variant: hiveUserConfig.variant,
         temperature: hiveUserConfig.temperature ?? 0.5,
         description: "Hive (Hybrid) - Plans + orchestrates. Detects phase, loads skills on-demand.",
-        prompt: QUEEN_BEE_PROMPT + hiveAutoLoadedSkills,
+        prompt: QUEEN_BEE_PROMPT + hiveAutoLoadedSkills + (agentMode === "unified" ? customSubagentAppendix : ""),
         permission: {
           question: "allow",
           skill: "allow",
@@ -24192,7 +24567,7 @@ ${result.diff}
         variant: architectUserConfig.variant,
         temperature: architectUserConfig.temperature ?? 0.7,
         description: "Architect (Planner) - Plans features, interviews, writes plans. NEVER executes.",
-        prompt: ARCHITECT_BEE_PROMPT + architectAutoLoadedSkills,
+        prompt: ARCHITECT_BEE_PROMPT + architectAutoLoadedSkills + (agentMode === "dedicated" ? customSubagentAppendix : ""),
         tools: agentTools(["hive_feature_create", "hive_plan_write", "hive_plan_read", "hive_context_write", "hive_status", "hive_skill"]),
         permission: {
           edit: "deny",
@@ -24211,7 +24586,7 @@ ${result.diff}
         variant: swarmUserConfig.variant,
         temperature: swarmUserConfig.temperature ?? 0.5,
         description: "Swarm (Orchestrator) - Orchestrates execution. Delegates, spawns workers, verifies, merges.",
-        prompt: SWARM_BEE_PROMPT + swarmAutoLoadedSkills,
+        prompt: SWARM_BEE_PROMPT + swarmAutoLoadedSkills + (agentMode === "dedicated" ? customSubagentAppendix : ""),
         tools: agentTools([
           "hive_feature_create",
           "hive_feature_complete",
@@ -24220,6 +24595,7 @@ ${result.diff}
           "hive_tasks_sync",
           "hive_task_create",
           "hive_task_update",
+          "hive_worktree_start",
           "hive_worktree_create",
           "hive_worktree_discard",
           "hive_merge",
@@ -24286,21 +24662,44 @@ ${result.diff}
           skill: "allow"
         }
       };
-      const hiveConfigData = configService.get();
-      const agentMode = hiveConfigData.agentMode ?? "unified";
+      const builtInAgentConfigs = {
+        "hive-master": hiveConfig,
+        "architect-planner": architectConfig,
+        "swarm-orchestrator": swarmConfig,
+        "scout-researcher": scoutConfig,
+        "forager-worker": foragerConfig,
+        "hygienic-reviewer": hygienicConfig
+      };
+      const customAutoLoadedSkills = Object.fromEntries(await Promise.all(Object.entries(customAgentConfigs).map(async ([customAgentName, customAgentConfig]) => {
+        const inheritedBaseSkills = customAgentConfig.baseAgent === "forager-worker" ? foragerUserConfig.autoLoadSkills ?? [] : hygienicUserConfig.autoLoadSkills ?? [];
+        const deltaAutoLoadSkills = (customAgentConfig.autoLoadSkills ?? []).filter((skill) => !inheritedBaseSkills.includes(skill));
+        return [
+          customAgentName,
+          await buildAutoLoadedSkillsContent(customAgentName, configService, directory, deltaAutoLoadSkills)
+        ];
+      })));
+      const customSubagents = buildCustomSubagents({
+        customAgents: customAgentConfigs,
+        baseAgents: {
+          "forager-worker": foragerConfig,
+          "hygienic-reviewer": hygienicConfig
+        },
+        autoLoadedSkills: customAutoLoadedSkills
+      });
       const allAgents = {};
       if (agentMode === "unified") {
-        allAgents["hive-master"] = hiveConfig;
-        allAgents["scout-researcher"] = scoutConfig;
-        allAgents["forager-worker"] = foragerConfig;
-        allAgents["hygienic-reviewer"] = hygienicConfig;
+        allAgents["hive-master"] = builtInAgentConfigs["hive-master"];
+        allAgents["scout-researcher"] = builtInAgentConfigs["scout-researcher"];
+        allAgents["forager-worker"] = builtInAgentConfigs["forager-worker"];
+        allAgents["hygienic-reviewer"] = builtInAgentConfigs["hygienic-reviewer"];
       } else {
-        allAgents["architect-planner"] = architectConfig;
-        allAgents["swarm-orchestrator"] = swarmConfig;
-        allAgents["scout-researcher"] = scoutConfig;
-        allAgents["forager-worker"] = foragerConfig;
-        allAgents["hygienic-reviewer"] = hygienicConfig;
+        allAgents["architect-planner"] = builtInAgentConfigs["architect-planner"];
+        allAgents["swarm-orchestrator"] = builtInAgentConfigs["swarm-orchestrator"];
+        allAgents["scout-researcher"] = builtInAgentConfigs["scout-researcher"];
+        allAgents["forager-worker"] = builtInAgentConfigs["forager-worker"];
+        allAgents["hygienic-reviewer"] = builtInAgentConfigs["hygienic-reviewer"];
       }
+      Object.assign(allAgents, customSubagents);
       const configAgent = opencodeConfig.agent;
       if (!configAgent) {
         opencodeConfig.agent = allAgents;