bloby-bot 0.70.9 → 0.70.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.70.9",
+  "version": "0.70.10",
   "releaseNotes": [
     "1. Fix: agent self-update ",
     "1",

package/supervisor/harnesses/pi/index.ts

@@ -16,6 +16,8 @@ import { log } from '../../../shared/logger.js';
 import { WORKSPACE_DIR } from '../../../shared/paths.js';
 import type { SavedFile } from '../../file-saver.js';
 import { assembleSystemPrompt } from '../../../worker/prompts/prompt-assembler.js';
+import { buildAgents } from '../../agents/index.js';
+import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import type {
@@ -34,6 +36,7 @@ import { readPiAuth } from './auth-storage.js';
 import { streamProvider } from './providers/stream.js';
 import type { PiMessage } from './providers/types.js';
 import { toolDefsForProvider } from './tools/registry.js';
+import type { PiTaskHost } from './tools/types.js';
 
 // ── Live conversation state ────────────────────────────────────────────────
 
@@ -49,9 +52,29 @@ interface LiveConversation {
   pendingCount: number;
   /** 60ms micro-batcher for bot:token — collapses per-delta WS frame floods. */
   batcher: TokenBatcher;
+  /** Running background sub-agent tasks (Phase B). While non-empty, the
+   *  conversation reports idle:false (recycling deferred) and counts as busy
+   *  (backend restarts / self-updates deferred) so a task is never killed
+   *  mid-flight by housekeeping. */
+  tasks: Map<string, RunningTask>;
+  /** Set when a completed background task used file tools — OR'd into the next
+   *  bot:turn-complete (the continuation turn) so the backend restarts right
+   *  after the user hears "Done!", mirroring claude's usedTools capture of
+   *  sub-agent tool_use blocks. */
+  taskUsedFileTools: boolean;
   loopDone: Promise<void> | null;
 }
 
+interface RunningTask {
+  id: string;
+  description: string;
+  subagentType: string;
+  abortController: AbortController;
+  /** True when stopped via user:stop-task or conversation teardown. */
+  stopped: boolean;
+  startedAt: number;
+}
+
 const liveConversations = new Map<string, LiveConversation>();
 
 /**
@@ -227,6 +250,182 @@ function resolveAuth(): { ok: true; auth: PiSessionAuth } | { ok: false; error:
   };
 }
 
+// ── Background sub-agents (Phase B — audit D4-1) ───────────────────────────
+
+/** Inject a system-originated message into the parent's queue (task completion).
+ *  Mirrors the Claude SDK's self-prompted continuation turn: no routing target
+ *  is enqueued (channelManager only wraps USER pushes), so the continuation's
+ *  bot:response meets an empty routing FIFO and falls through to the dashboard
+ *  broadcast — exactly claude's behavior. pendingCount/busy are maintained so
+ *  idle stays accurate and the recycler can't fire mid-continuation. No
+ *  bot:typing (claude's continuation turns emit none either). */
+function pushSyntheticMessage(conv: LiveConversation, text: string): void {
+  conv.busy = true;
+  conv.pendingCount += 1;
+  conv.inputQueue.push({ role: 'user', content: [{ type: 'text', text }] });
+}
+
+/** coder.txt advertises the claude toolset ("Read, Write, Edit, Bash, Glob,
+ *  Grep") — swap in the child's REAL pi toolset so the sub-agent never chases
+ *  tools it doesn't have (audit D4-4). claude keeps its richer line. */
+function rewriteToolAccessLine(prompt: string, toolNames: string[]): string {
+  return prompt.replace(/You have full tool access:[^\n]*/i, `You have full tool access: ${toolNames.join(', ')}.`);
+}
+
+/** Compact human-readable descriptor of a child tool call for bot:task-progress. */
+function toolCallSummary(name: string, input: any): string {
+  const tail = (p: any) => (typeof p === 'string' ? p.split('/').slice(-2).join('/') : '');
+  switch (name.toLowerCase()) {
+    case 'bash': return `Bash: ${String(input?.description || input?.command || '').slice(0, 80)}`;
+    case 'read': return `Reading ${tail(input?.file_path)}`;
+    case 'write': return `Writing ${tail(input?.file_path)}`;
+    case 'edit': return `Editing ${tail(input?.file_path)}`;
+    default: return name;
+  }
+}
+
+/**
+ * Per-conversation task host: spawns an in-process child `createPiSession`
+ * per Task call, translates child events into the `bot:task-*` vocabulary
+ * (payload fields exactly as claude.ts:443-484 emits them), and injects the
+ * completion back into the parent's queue for the "Done!" continuation turn.
+ */
+function createTaskHost(conv: LiveConversation, getAuth: () => PiSessionAuth): PiTaskHost {
+  return {
+    spawn(req) {
+      const agents = buildAgents();
+      const cfg = agents[req.subagentType];
+      if (!cfg) {
+        return {
+          ok: false,
+          error: `Unknown subagent_type "${req.subagentType}". Available: ${Object.keys(agents).join(', ') || 'none'}.`,
+        };
+      }
+
+      const taskId = crypto.randomUUID().slice(0, 8);
+      const abortController = new AbortController();
+      const task: RunningTask = {
+        id: taskId,
+        description: req.description,
+        subagentType: req.subagentType,
+        abortController,
+        stopped: false,
+        startedAt: Date.now(),
+      };
+      conv.tasks.set(taskId, task);
+
+      // Honor the agent config's tool restrictions (claude applies these via
+      // the SDK's tools/disallowedTools options — e.g. a future researcher
+      // agent with disallowedTools: ['Write','Edit']).
+      let childTools = toolDefsForProvider({ forSubagent: true });
+      if (Array.isArray(cfg.tools) && cfg.tools.length > 0) {
+        childTools = childTools.filter((t) => cfg.tools.includes(t.name));
+      }
+      if (Array.isArray(cfg.disallowedTools) && cfg.disallowedTools.length > 0) {
+        childTools = childTools.filter((t) => !cfg.disallowedTools.includes(t.name));
+      }
+      const systemPrompt = rewriteToolAccessLine(String(cfg.prompt || ''), childTools.map((t) => t.name));
+
+      let summaryText = '';
+      let errorText = '';
+      let usedFileTools = false;
+      let toolUses = 0;
+      let lastUsage: { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheCreationTokens?: number } | undefined;
+
+      const session = createPiSession({
+        getAuth,
+        systemPrompt,
+        tools: childTools,
+        cwd: WORKSPACE_DIR,
+        abortController,
+        maxToolRounds: typeof cfg.maxTurns === 'number' ? cfg.maxTurns : 50,
+        onEvent: (evt: PiSessionEvent) => {
+          switch (evt.type) {
+            case 'tool_use':
+              toolUses += 1;
+              conv.batcher.flush();
+              conv.onMessage('bot:task-progress', {
+                conversationId: conv.id,
+                taskId,
+                summary: toolCallSummary(evt.name, evt.input),
+                lastTool: evt.name,
+                usage: { tool_uses: toolUses, duration_ms: Date.now() - task.startedAt },
+              });
+              break;
+            case 'text_end':
+              summaryText = evt.text;
+              break;
+            case 'error':
+              errorText = evt.error;
+              break;
+            case 'turn_complete':
+              usedFileTools = usedFileTools || evt.usedFileTools;
+              if (evt.usage) lastUsage = evt.usage;
+              break;
+          }
+        },
+      });
+
+      const queue = createAsyncQueue<PiMessage>();
+      queue.push({ role: 'user', content: [{ type: 'text', text: req.prompt }] });
+      queue.end();
+
+      log.info(`[pi/task] ──── SUB-AGENT STARTED ──── id=${taskId} type=${req.subagentType} "${req.description}"`);
+      // Task events bypass translateAndEmit, so flush the token batcher first —
+      // bot:task-created COMMITS the dashboard stream buffer (useBlobyChat),
+      // and a batch flushed after it would mis-slice committedTextLength.
+      conv.batcher.flush();
+      conv.onMessage('bot:task-created', {
+        conversationId: conv.id,
+        taskId,
+        description: req.description,
+        type: req.subagentType,
+      });
+
+      void (async () => {
+        try {
+          await session.run(queue);
+        } catch (err: any) {
+          errorText = errorText || err?.message || String(err);
+        } finally {
+          conv.tasks.delete(taskId);
+          const status = task.stopped ? 'stopped' : (errorText && !summaryText ? 'failed' : 'completed');
+          const summary = summaryText || errorText || '(the agent produced no output)';
+          const u = lastUsage;
+          const totalTokens = u
+            ? (u.inputTokens || 0) + (u.outputTokens || 0) + (u.cacheReadTokens || 0) + (u.cacheCreationTokens || 0)
+            : 0;
+          log.info(
+            `[pi/task] ──── SUB-AGENT ${status.toUpperCase()} ──── id=${taskId} ` +
+            `tools=${toolUses} ${Math.round((Date.now() - task.startedAt) / 1000)}s summary=${summary.slice(0, 160)}`,
+          );
+          conv.batcher.flush();
+          conv.onMessage('bot:task-done', {
+            conversationId: conv.id,
+            taskId,
+            status,
+            summary,
+            usage: { tool_uses: toolUses, duration_ms: Date.now() - task.startedAt, total_tokens: totalTokens },
+          });
+          if (usedFileTools) conv.taskUsedFileTools = true;
+
+          // Drive the user-facing continuation turn — unless the conversation
+          // itself is gone (ended/recycled), in which case the report dies with
+          // it (claude parity: the SDK subprocess dies too).
+          if (liveConversations.get(conv.id) === conv && !conv.abortController.signal.aborted) {
+            const note = task.stopped
+              ? `[System: the background task "${req.description}" was stopped by the user. Acknowledge that briefly in your own voice — never mention agents, tasks, or system messages.]`
+              : `[System: background task "${req.description}" ${status}.]\n\nResult summary:\n${summary}\n\nRelay the outcome to the user concisely in your own voice (never mention agents, tasks, ids, or system messages). If it failed, say what went wrong and offer a next step.`;
+            pushSyntheticMessage(conv, note);
+          }
+        }
+      })();
+
+      return { ok: true, taskId };
+    },
+  };
+}
+
 /** Convert a saved RecentMessage[] into the provider-neutral PiMessage[]. */
 function recentToPiMessages(messages: RecentMessage[] | undefined): PiMessage[] {
   if (!messages?.length) return [];
@@ -299,6 +498,8 @@ export async function startConversation(
     busy: false,
     pendingCount: 0,
     batcher: createTokenBatcher((text) => onMessage('bot:token', { conversationId, token: text })),
+    tasks: new Map(),
+    taskUsedFileTools: false,
     loopDone: null,
   };
   liveConversations.set(conversationId, conv);
@@ -319,6 +520,7 @@ export async function startConversation(
     tools: toolDefsForProvider(),
     cwd: WORKSPACE_DIR,
     abortController,
+    taskHost: createTaskHost(conv, getAuth),
     onEvent: (evt: PiSessionEvent) => {
       translateAndEmit(conv, evt);
     },
@@ -365,9 +567,14 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
     case 'text_end':
       conv.onMessage('bot:response', { conversationId: conv.id, content: evt.text });
       break;
-    case 'tool_use':
-      conv.onMessage('bot:tool', { conversationId: conv.id, name: evt.name, input: evt.input });
+    case 'tool_use': {
+      // House vocabulary: claude's delegation tool is named Task; the pi
+      // prompt's 'Agent' alias resolves to the same tool — normalize the
+      // event so consumers see one name.
+      const toolName = evt.name === 'Agent' || evt.name === 'agent' ? 'Task' : evt.name;
+      conv.onMessage('bot:tool', { conversationId: conv.id, name: toolName, input: evt.input });
       break;
+    }
     case 'tool_result':
       // Not surfaced yet (Phase D: translate to a bot:tool progress pulse).
       break;
@@ -375,9 +582,16 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
       conv.busy = false;
       // One turn-complete per pushed message (D1-1 restored that invariant);
       // idle gates the supervisor's proactive recycling so it never fires with
-      // a message still queued — claude.ts pendingCount semantics exactly.
+      // a message still queued OR a background task still running — recycling
+      // mid-task would kill the task (claude has the same teardown semantics,
+      // but its idle flag doesn't guard tasks; this is strictly safer).
       conv.pendingCount = Math.max(0, conv.pendingCount - 1);
-      const idle = conv.pendingCount === 0;
+      const idle = conv.pendingCount === 0 && conv.tasks.size === 0;
+      // A finished background task's file edits restart the backend on the
+      // very next turn boundary (the continuation turn) — claude captures
+      // sub-agent tool_use blocks into the parent's usedTools the same way.
+      const usedFileTools = evt.usedFileTools || conv.taskUsedFileTools;
+      conv.taskUsedFileTools = false;
       // Prompt occupancy of the last provider round — input + cache reads +
       // cache writes, exactly claude.ts's contextTokens math. Output tokens
       // are NOT added (claude doesn't either; the recycler's 70% threshold
@@ -387,12 +601,12 @@ function translateAndEmit(conv: LiveConversation, evt: PiSessionEvent) {
         : 0;
       conv.onMessage('bot:turn-complete', {
         conversationId: conv.id,
-        usedFileTools: evt.usedFileTools,
+        usedFileTools,
         contextTokens,
         contextWindow: evt.contextWindow || 0,
         idle,
       });
-      log.info(`[pi/conversation] ──── TURN COMPLETE ────  busy=false ctx=${contextTokens}/${evt.contextWindow || 'n/a'} idle=${idle}`);
+      log.info(`[pi/conversation] ──── TURN COMPLETE ────  busy=false ctx=${contextTokens}/${evt.contextWindow || 'n/a'} idle=${idle} tasks=${conv.tasks.size}`);
       break;
     }
     case 'error': {
@@ -445,6 +659,14 @@ export function endConversation(conversationId: string): void {
   if (!conv) return;
 
   log.info(`[pi/conversation] ──── ENDING CONVERSATION ${conversationId} ────`);
+  // Background tasks die with the conversation (claude parity — the SDK
+  // subprocess takes its tasks down too). Their finallys still emit
+  // bot:task-done {status:'stopped'} so dashboard task cards don't spin
+  // forever; the completion injection is skipped (conv gone).
+  for (const task of conv.tasks.values()) {
+    task.stopped = true;
+    task.abortController.abort();
+  }
   conv.batcher.discard();
   conv.inputQueue.end();
   conv.abortController.abort();
@@ -455,16 +677,29 @@ export function isConversationBusy(conversationId: string): boolean {
   return liveConversations.get(conversationId)?.busy || false;
 }
 
-/** True if ANY live conversation in this harness is mid-turn. Used by the supervisor to defer
- *  backend restarts during channel/Alexa turns (which don't set the dashboard's agentQueryActive). */
+/** True if ANY live conversation in this harness is mid-turn OR has a background
+ *  sub-agent running. Used by the supervisor to defer backend restarts and
+ *  self-updates — a restart mid-task would kill the task's work in flight. */
 export function anyConversationBusy(): boolean {
-  for (const c of liveConversations.values()) if (c.busy) return true;
+  for (const c of liveConversations.values()) {
+    if (c.busy || c.tasks.size > 0) return true;
+  }
   return false;
 }
 
-/** Pi has no sub-agents yet; provided for interface compatibility. */
-export async function stopSubAgentTask(_conversationId: string, _taskId: string): Promise<void> {
-  // no-op for Phase 1
+/** Stop a specific background sub-agent task (dashboard user:stop-task). The
+ *  child's teardown emits bot:task-done {status:'stopped'} and injects a brief
+ *  acknowledgement turn into the parent. */
+export async function stopSubAgentTask(conversationId: string, taskId: string): Promise<void> {
+  const conv = liveConversations.get(conversationId);
+  const task = conv?.tasks.get(taskId);
+  if (!task) {
+    log.warn(`[pi/task] Cannot stop task ${taskId} — not running in conversation ${conversationId}`);
+    return;
+  }
+  log.info(`[pi/task] Stopping sub-agent task ${taskId}`);
+  task.stopped = true;
+  task.abortController.abort();
 }
 
 /** Pi has no pre-warm step (no subprocess), but the interface requires this. */

package/supervisor/harnesses/pi/session.ts

@@ -38,7 +38,7 @@ import type { PiMessage, PiStreamEvent, PiToolDef, PiContentBlock, PiUsage, PiEr
 import { sleep } from './providers/retry.js';
 import type { AsyncQueue } from './async-queue.js';
 import { findTool } from './tools/registry.js';
-import type { PiTool } from './tools/types.js';
+import type { PiTool, PiTaskHost } from './tools/types.js';
 
 export type PiSessionEvent =
   | { type: 'turn_started' }
@@ -78,6 +78,17 @@ export interface PiSessionInit {
   tools?: PiToolDef[];
   /** Resolved every time a tool fires (registry → run). */
   cwd: string;
+  /**
+   * Background sub-agent host (Phase B). Set only on PARENT live sessions —
+   * threaded into PiToolContext so the Task tool can spawn; child sessions
+   * leave it unset (no grandchildren, Claude SDK parity).
+   */
+  taskHost?: PiTaskHost;
+  /**
+   * Per-turn tool-round budget. Parents keep the default; sub-agent children
+   * get their agent config's maxTurns (e.g. coder: 50).
+   */
+  maxToolRounds?: number;
   /** Used to interrupt in-flight provider calls when the session ends. */
   abortController: AbortController;
   /** Caller's event sink — translated to bloby's `bot:*` events one layer up. */
@@ -199,7 +210,7 @@ export function createPiSession(init: PiSessionInit): PiSession {
       };
     }
     try {
-      return await tool.run(call.input, { cwd: init.cwd, signal: init.abortController.signal });
+      return await tool.run(call.input, { cwd: init.cwd, signal: init.abortController.signal, tasks: init.taskHost });
     } catch (err: any) {
       return { output: `Tool ${call.name} threw: ${err?.message || err}`, isError: true };
     }
@@ -218,7 +229,8 @@ export function createPiSession(init: PiSessionInit): PiSession {
     let turnErrorMsg: string | undefined;
     let turnErrorKind: PiErrorKind | undefined;
 
-    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+    const maxRounds = Math.max(1, init.maxToolRounds ?? MAX_TOOL_ROUNDS);
+    for (let round = 0; round < maxRounds; round++) {
       if (init.abortController.signal.aborted) break;
       // The separator condition is decided BEFORE the round so the round can
       // emit it ahead of its first token (claude.ts ordering — see runOneRound).

package/supervisor/harnesses/pi/tools/registry.ts

@@ -1,8 +1,10 @@
 /**
  * Tool registry — the bag of tools the pi session passes to the model.
  *
- * Phase 2 ships the four core coding tools. Phase 3 or later will add Grep,
- * Glob, LS, NotebookEdit, etc. so the surface fully matches Claude SDK's.
+ * Read/Write/Edit/Bash mirror the Claude SDK tools; Task is the background
+ * sub-agent delegator (Phase B of the parity plan). Grep, Glob, LS,
+ * NotebookEdit etc. are still pending (Phase D) to fully match Claude SDK's
+ * surface.
  */
 import type { PiTool } from './types.js';
 import type { PiToolDef } from '../providers/types.js';
@@ -10,8 +12,9 @@ import { readTool } from './read.js';
 import { writeTool } from './write.js';
 import { editTool } from './edit.js';
 import { bashTool } from './bash.js';
+import { taskTool, taskToolDef } from './task.js';
 
-export const PI_TOOLS: PiTool[] = [readTool, writeTool, editTool, bashTool];
+export const PI_TOOLS: PiTool[] = [readTool, writeTool, editTool, bashTool, taskTool];
 
 const TOOL_BY_NAME = new Map<string, PiTool>();
 for (const t of PI_TOOLS) {
@@ -20,15 +23,28 @@ for (const t of PI_TOOLS) {
   // common aliases so we don't 404 a legitimate call over a casing nit.
   TOOL_BY_NAME.set(t.name.toLowerCase(), t);
 }
+// The pi system prompt calls background delegation "the Agent tool" (claude
+// heritage) — alias it so a model following the prompt verbatim still lands
+// on the Task implementation.
+TOOL_BY_NAME.set('Agent', taskTool);
+TOOL_BY_NAME.set('agent', taskTool);
 
 export function findTool(name: string): PiTool | undefined {
   return TOOL_BY_NAME.get(name) || TOOL_BY_NAME.get(name.toLowerCase());
 }
 
-export function toolDefsForProvider(): PiToolDef[] {
-  return PI_TOOLS.map((t) => ({
-    name: t.name,
-    description: t.description,
-    inputSchema: t.inputSchema,
-  }));
+export function toolDefsForProvider(opts?: { forSubagent?: boolean }): PiToolDef[] {
+  const defs: PiToolDef[] = [];
+  for (const t of PI_TOOLS) {
+    if (t.name === 'Task') {
+      // Children cannot spawn grandchildren (Claude SDK parity) — a child that
+      // hallucinates a Task call still fails gracefully (ctx.tasks is unset).
+      if (opts?.forSubagent) continue;
+      // Rebuilt fresh so agent-roster/prompt edits apply per session start.
+      defs.push(taskToolDef());
+      continue;
+    }
+    defs.push({ name: t.name, description: t.description, inputSchema: t.inputSchema });
+  }
+  return defs;
 }

package/supervisor/harnesses/pi/tools/task.ts

@@ -0,0 +1,108 @@
+/**
+ * Task tool — background sub-agent delegation (audit D4-1, Phase B).
+ *
+ * Mirrors the Claude Agent SDK's Task tool contract and feel:
+ *   - the model calls Task({description, prompt, subagent_type})
+ *   - the tool returns IMMEDIATELY with an acknowledgement, so the parent turn
+ *     ends in seconds and the chat stays fully conversational
+ *   - the child runs as an in-process `createPiSession` (Bloby owns the agent
+ *     loop, so no subprocess is needed — unlike upstream pi's subagent
+ *     extension, which must spawn the pi CLI)
+ *   - completion is injected back into the parent's input queue as a synthetic
+ *     message that drives the user-facing "Done!" continuation turn
+ *
+ * Also registered under the alias 'Agent' (registry.ts): the pi system prompt
+ * sells "the Agent tool" — with this tool live, those sections are true as
+ * written, closing the audit's D4-2 finding without a prompt edit.
+ *
+ * Agent definitions come from `supervisor/agents/index.ts:buildAgents()` —
+ * the same roster the Claude harness uses, so both harnesses stay in sync.
+ */
+import type { PiTool } from './types.js';
+import type { PiToolDef } from '../providers/types.js';
+import { buildAgents } from '../../../agents/index.js';
+
+/**
+ * Tool definition with a FRESH subagent enum — built per session start (not at
+ * module load) so prompt-file/roster edits apply without a supervisor restart,
+ * and so the workspace is guaranteed to exist when prompts are read.
+ */
+export function taskToolDef(): PiToolDef {
+  const agents = buildAgents();
+  const names = Object.keys(agents);
+  return {
+    name: 'Task',
+    description:
+      'Delegate heavy work to a background sub-agent and keep chatting while it runs. ' +
+      'Returns immediately — you will automatically receive the result when the agent finishes, ' +
+      'so acknowledge the user briefly and end your turn. ' +
+      'Available agents: ' +
+      (names.map((n) => `${n} (${agents[n].description})`).join('; ') || 'none configured'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: 'Short (3-5 word) description of the task, shown to the user as a progress card.',
+        },
+        prompt: {
+          type: 'string',
+          description: 'Complete, self-contained instructions for the sub-agent. It cannot ask follow-up questions — include every detail it needs.',
+        },
+        subagent_type: {
+          type: 'string',
+          ...(names.length > 0 ? { enum: names } : {}),
+          description: 'Which sub-agent to delegate to.',
+        },
+      },
+      required: ['description', 'prompt', 'subagent_type'],
+    },
+  };
+}
+
+export const taskTool: PiTool = {
+  name: 'Task',
+  description: 'Delegate heavy work to a background sub-agent.',
+  // Static placeholder (no file I/O at module load) — providers receive the
+  // dynamic enum schema from taskToolDef() via registry.toolDefsForProvider.
+  inputSchema: {
+    type: 'object',
+    properties: {
+      description: { type: 'string' },
+      prompt: { type: 'string' },
+      subagent_type: { type: 'string' },
+    },
+    required: ['description', 'prompt', 'subagent_type'],
+  },
+
+  async run(input, ctx) {
+    if (!ctx.tasks) {
+      return {
+        output:
+          'The Task tool is not available in this context — do the work yourself with your other tools.',
+        isError: true,
+      };
+    }
+    const description = typeof input?.description === 'string' ? input.description.trim() : '';
+    const prompt = typeof input?.prompt === 'string' ? input.prompt.trim() : '';
+    const subagentType = typeof input?.subagent_type === 'string' ? input.subagent_type.trim() : '';
+    if (!prompt) {
+      return { output: 'Task requires `prompt` — complete instructions for the sub-agent.', isError: true };
+    }
+
+    const res = ctx.tasks.spawn({
+      description: description || prompt.slice(0, 60),
+      prompt,
+      subagentType: subagentType || 'coder',
+    });
+    if (!res.ok) return { output: res.error, isError: true };
+
+    return {
+      output:
+        `Background task started (id: ${res.taskId}). It is now running while you keep chatting. ` +
+        `Tell the user in ONE short sentence that you're on it (your usual voice — never mention ` +
+        `agents, tasks, or ids), then end your turn. You will automatically receive the result ` +
+        `when it finishes.`,
+    };
+  },
+};

package/supervisor/harnesses/pi/tools/types.ts

@@ -14,11 +14,26 @@ export interface PiToolResult {
   isError?: boolean;
 }
 
+/**
+ * Host interface a live conversation exposes to the Task tool so it can spawn
+ * background sub-agents (audit D4-1). Only PARENT sessions provide it — child
+ * sessions get `ctx.tasks` undefined, so a sub-agent cannot spawn
+ * grandchildren (Claude SDK parity).
+ */
+export interface PiTaskHost {
+  /** Spawn a background sub-agent. Returns synchronously; the child runs detached. */
+  spawn(req: { description: string; prompt: string; subagentType: string }):
+    | { ok: true; taskId: string }
+    | { ok: false; error: string };
+}
+
 export interface PiToolContext {
   /** Workspace root — every tool resolves paths against this. */
   cwd: string;
   /** Aborted when the session ends so long-running tools stop fast. */
   signal?: AbortSignal;
+  /** Present only in live parent sessions — lets the Task tool spawn sub-agents. */
+  tasks?: PiTaskHost;
 }
 
 export interface PiTool {

package/supervisor/shell.ts

@@ -170,7 +170,7 @@ export const SHELL_HTML = `<!DOCTYPE html>
             // preload=auto so the clip is fetched (and SW-cached) while the supervisor is
             // still up — by the time we show this, the origin is unreachable.
             '<video autoplay loop muted playsinline preload="auto" style="position:relative;width:100%;height:100%;object-fit:contain;border-radius:50%">' +
-              '<source src="/morphy_sad.mov" type=\'video/mp4; codecs="hvc1"\'><source src="/morphy_sad.webm" type="video/webm">' +
+              '<source src="/morphy_sad.webm" type="video/webm"><source src="/morphy_sad.mov" type="video/mp4">' +
             '</video>' +
           '</div>' +
           '<h1 style="font-size:1.5rem;font-weight:700;margin:0 0 .6rem;background:linear-gradient(135deg,#0166FF,#009AFE,#4AEEFF);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text">Workspace is restarting&hellip;</h1>' +

package/supervisor/workspace-guard.js

@@ -562,7 +562,7 @@
         '<div style="position:relative;width:160px;height:160px;margin:0 auto 1.2rem">' +
           '<div style="position:absolute;inset:-18px;background:radial-gradient(circle,rgba(1,102,255,.18) 0%,transparent 60%);filter:blur(18px)"></div>' +
           '<video autoplay loop muted playsinline style="position:relative;width:100%;height:100%;object-fit:contain;border-radius:50%">' +
-            '<source src="/morphy_sad.mov" type=\'video/mp4; codecs="hvc1"\'><source src="/morphy_sad.webm" type="video/webm">' +
+            '<source src="/morphy_sad.webm" type="video/webm"><source src="/morphy_sad.mov" type="video/mp4">' +
           '</video>' +
         '</div>' +
         '<h1 style="font-size:1.5rem;font-weight:700;margin:0 0 .6rem;background:linear-gradient(135deg,#0166FF,#009AFE,#4AEEFF);-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text">Workspace error</h1>' +