pi-pier 0.2.7 → 0.3.0

package/src/core/subagent.ts

@@ -7,35 +7,30 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import { Type } from 'typebox';
-import { randomUUID } from 'node:crypto';
-import { basename, join, dirname } from 'node:path';
+import { join, dirname } from 'node:path';
 import type { PiSurface } from '../pi-surface.ts';
 import type { HerdrClientLike } from '../herdr-client.ts';
-import { Semaphore, SUBS_CUSTOM_TYPE, agoText, buildAliveNotice, buildBlockedGateNotice, buildIsolatePreamble, classifyWorktreeZone, foldSubsRegistry, formatSubagentResult, isAlive, isPathUnder, makeProgressUpdate, makeRegistry, planIsolateWorktree, tabNameForTask, type AliveProbe, type SubEntry } from '../subagent-core.ts';
+import { Semaphore, buildAliveNotice, isAlive, tabNameForTask, type SubEntry } from '../subagent-core.ts';
 import { applyReportedSessionFile, appendHistory, preferredHistoryFile, inheritOutcome, latestGeneration, readHistory, type HistoryEntry } from '../history-store.ts';
-import { runtimePolicy } from '../runtime-policy.ts';
 import { platformPaths } from '../platform-paths.ts';
 import type { SubagentPort, SubagentPortBox } from '../subagent-port.ts';
-import {
-  FOREGROUND_POLL_MS,
-  planForegroundTick,
-  planIsolateRepoGuard,
-  planLaunchValidation,
-  planPatienceExpiry,
-} from '../subagent-launch.ts';
-import { mkdirSync, stat as statCb } from 'node:fs';
-import { resolve as pathResolve } from 'node:path';
-import { promisify } from 'node:util';
-const statAsync = promisify(statCb);
+import { toolError } from '../tool-error.ts'
+
+/** Raw tool arguments: every field is validated inside the action handlers. */
+type ToolParams = Record<string, unknown> | undefined;;
 import { pipeNameFor, pipeRequestTo } from '../pipe-channel.ts';
-import { composeForRole } from '../manifest-compose.ts';
 import type { TerminalStateSlot } from './terminal.ts';
 import { createGitIo } from '../subagent-git-io.ts';
 import { createSessionIo } from '../subagent-session-io.ts';
 import { createSpawner } from '../subagent-spawn.ts';
 import { createPoller } from '../subagent-poll-loop.ts';
 import { createGcController } from '../subagent-gc.ts';
-
+import { createSubagentRegistry } from '../subagent-registry.ts';
+import { createSpawnAction } from '../subagent-execute.ts';
+import type { SubagentOutputCursor } from '../subagent-output-core.ts';
+import { executeSubagentList } from '../subagent-list-action.ts';
+import { executeSubagentOutput } from '../subagent-output-action.ts';
+import { resolveTaskIdPrefix } from '../subagent-resolution.ts';
 
 interface SubagentEnv {
   paneId: string;
@@ -68,7 +63,7 @@ interface SubagentDeps {
 
 const SUBAGENT_DESCRIPTION = [
   'Delegate a self-contained subtask to an isolated subagent that runs in its own herdr pane as an interactive pi session (separate context window; it does NOT see this conversation). A human can also open that pane and talk to the subagent directly.',
-  '`action` (optional, default "spawn"): spawn | resume | list | send | interrupt.',
+  '`action` (optional, default "spawn"): spawn | resume | list | send | interrupt | output.',
   '[spawn] `description`: short display label for the pane; `prompt`: the COMPLETE task — include all needed context, since only the prompt reaches the subagent. The description also doubles as the todo-reconcile key: when delegating a todo entry, use the entry content WITHOUT its ` <sub>` marker as the description, and the entry is auto-completed when this subagent settles.',
   '[spawn] The subagent shares this workspace and works independently; the result is its final text answer.',
   '[spawn] Concurrent delegation is supported: several spawn calls in one message run in parallel (at most 4 at once). Use this for well-scoped, independent subtasks; do not delegate the current step itself.',
@@ -80,12 +75,11 @@ const SUBAGENT_DESCRIPTION = [
   '[list] no extra parameters: list background subagents with live state (running / idle), pane ids, last activity, role, and descriptions. Foreground one-shot panes are not listed.',
   '[send] `agentId` + `message`: follow-up to a background subagent. If working, delivered at next tool-call gap (steer, seconds); if idle, wakes a new turn. After settle, send to wake it; do not spawn a duplicate.',
   '[interrupt] `agentId`: abort the current turn (fire-and-return). The pane stays; you can send again.',
+  '[output] `agentId` (required, the subagent pane id): view incremental output of a running or background subagent since the last output call. Text returned to the model is bounded (default 6000 chars) with status metadata (running/idle/blocked/settled), revision, truncated flag, and whether the buffer reset/scrolled (restart: true). Use this to observe subagent progress before settlement.',
 ].join(' ');
 
 /** Subagent concurrency limit (max parallel delegations) */
 const SUBAGENT_CONCURRENCY = 4;
-const SUBAGENT_TIMEOUT_MS = runtimePolicy.subagentTimeoutMs;
-const SUB_READY_TIMEOUT_MS = runtimePolicy.readinessTimeoutMs;
 
 function defaultAgentSessionsDir(): string {
   const base = process.env.PI_CODING_AGENT_DIR || platformPaths.agentDataDir;
@@ -96,6 +90,8 @@ function agentRootDir(): string {
   return dirname(defaultAgentSessionsDir());
 }
 
+
+
 export default function subagentPlugin(ctx: Context): void {
   const surface = ctx.get('pi-herdr.surface') as PiSurface<object>;
   const d = ctx.get('pi-herdr.subagent-deps') as SubagentDeps;
@@ -116,25 +112,15 @@ export default function subagentPlugin(ctx: Context): void {
   const lastMachineInjectAt = new Map<string, number>();
   /* Persist the subagent registry as custom branch state so parent restarts can rebuild it. */
   const subs = new Map<string, SubEntry>();
+  /** In-memory cursor for incremental subagent output observation. */
+  const outputCursors = new Map<string, SubagentOutputCursor>();
   /** D98 excludes branches during worktree-add-to-registry races from orphan collection. */
   const pendingIsolateBranches = new Set<string>();
   /** D50 tracks the latest machine request per pane for interrupt claims and poll deduplication. */
   const lastRequestIdByPane = new Map<string, string>();
 
-  /** O1 suppresses duplicate snapshots because 01a03c0d found 48% of session rows were heartbeat repeats. */
-  let lastSubsSnapshot = '';
-
-  function persistSubs(): void {
-    try {
-      const reg = makeRegistry([...subs.values()]);
-      const snap = JSON.stringify(reg);
-      if (snap === lastSubsSnapshot) return; // Avoid duplicate writes from the 1s/5s observation loops.
-      lastSubsSnapshot = snap;
-      pi.appendEntry?.(SUBS_CUSTOM_TYPE, reg);
-    } catch {
-      /* Persistence is best-effort so session logging cannot break delegation. */
-    }
-  }
+  const registry = createSubagentRegistry({ pi, client, subs, writeHistory });
+  const { persist: persistSubs } = registry;
   /** E2 deduplicates gate notices while blocked but permits a later, distinct human question. */
   const blockedGateNotified = new Set<string>();
   const git = createGitIo();
@@ -167,53 +153,22 @@ export default function subagentPlugin(ctx: Context): void {
   ctx.effect(() => () => {
     if (port.current === boundPort) port.current = null;
   }, 'subagent-port');
-  function rebuildSubs(eventCtx: unknown): void {
-    try {
-      const entries = (eventCtx as { sessionManager?: { getBranch?: () => readonly unknown[] } })
-        ?.sessionManager?.getBranch?.() ?? [];
-      const reg = foldSubsRegistry(entries as Parameters<typeof foldSubsRegistry>[0]);
-      for (const sub of reg.subs) subs.set(sub.paneId, sub);
-      lastSubsSnapshot = ''; // Force persistence because branch replay replaced live state.
-    } catch {
-      /* Registry recovery failure must not block the live session. */
-    }
-  }
-
-  /** B6 closes crash-stale running rows only after herdr confirms their pane is gone; 01a03c0d
-   * showed p6/p7 otherwise remained permanently running. */
-  async function sweepZombieRunning(): Promise<void> {
-    if (!client.available || subs.size === 0) return;
-    let livePaneIds: ReadonlySet<string>;
-    try {
-      livePaneIds = new Set((await client.listPanes()).map((p) => p.paneId));
-    } catch {
-      return; // Do not close agents when liveness lookup itself failed.
-    }
-    let changed = false;
-    for (const [paneId, e] of subs) {
-      if (e.status !== 'running' || livePaneIds.has(paneId)) continue;
-      e.status = 'closed';
-      writeHistory(e, { status: 'closed', closedAt: Date.now() }, 'zombie-sweep');
-      changed = true;
-    }
-    if (changed) persistSubs();
-  }
-
   scoped.on('session_start', async (_event: unknown, eventCtx: unknown) => {
-    rebuildSubs(eventCtx);
-    await sweepZombieRunning();
+    registry.rebuild(eventCtx);
+    await registry.sweepZombieRunning();
   });
   scoped.on('session_tree', async (_event: unknown, eventCtx: unknown) => {
-    rebuildSubs(eventCtx);
-    await sweepZombieRunning();
+    registry.rebuild(eventCtx);
+    await registry.sweepZombieRunning();
   });
 
   /* ── B1 liveness rewrite for subagent errors ─────────────────────
    * A false no-output result caused the model to seize work from a healthy subagent. Probe
    * agent.list and session mtime before the tool result enters model context; if alive, emit the
    * same notice as A2 backgrounding. This hook enforces what prompting alone could not. */
-  scoped.on('tool_result', async (event: { toolName?: string; toolCallId?: string; isError?: boolean; content?: Array<{ type: string; text?: string }> }) => {
-    if (event?.toolName !== 'subagent' || !event.isError) return;
+  scoped.on('tool_result', async (rawEvent: unknown) => {
+    const event = (rawEvent ?? {}) as { toolName?: string; isError?: boolean; content?: Array<{ type: string; text?: string }> };
+    if (event.toolName !== 'subagent' || !event.isError) return;
     // Extract only pane ids carried by our own errors; leave unrelated errors untouched.
     const errText = (event.content ?? []).map((c) => c.text ?? '').join(' ');
     const paneId = [...subs.keys()].find((id) => errText.includes(id))
@@ -311,11 +266,9 @@ export default function subagentPlugin(ctx: Context): void {
   gc.startTicker(ctx);
   scoped.on('turn_start', () => gc.onTurnStart());
 
-  const { resolveSessionFile, collectFinalText, readAskFlag, probeAlive, subSessionState } = session;
+  const { readAskFlag, probeAlive } = session;
   const { spawnPaneInTaskTab, launchLine, approveFor, waitSubReady, findExistingPane } = spawn;
   const { startPoller, pollers } = poller;
-  const runGit = (...args: Parameters<typeof git.runGit>) => git.runGit(...args);
-  const listWorktrees = (...args: Parameters<typeof git.listWorktrees>) => git.listWorktrees(...args);
 
   /** Revive a closed task; resume and automatic send_message revival share this path. */
   async function reviveEntry(entry: SubEntry): Promise<SubEntry> {
@@ -334,7 +287,7 @@ export default function subagentPlugin(ctx: Context): void {
       launchLine(resumeFile, null, approve),
     );
     const ready = await waitSubReady(entry.cwd, spawned.paneId);
-    if (!ready) throw new Error(`revived pane ${spawned.paneId} pipe not ready`);
+    if (!ready.ok) throw new Error(ready.message);
     entry.paneId = spawned.paneId;
     entry.tabId = spawned.tabId;
     entry.tabName = spawned.tabName;
@@ -349,21 +302,32 @@ export default function subagentPlugin(ctx: Context): void {
   }
 
 
-  async function executeSubagentResume(params, toolCtx) {
+  async function executeSubagentResume(params: Record<string, unknown> | undefined, toolCtx: unknown) {
       if (!client.available) {
-        return {
-          content: [{ type: 'text', text: 'Error: requires a herdr-managed pane.' }],
-          details: {},
-        };
+        return toolError('requires a herdr-managed pane.');
       }
       const cwd = (toolCtx as { cwd?: string }).cwd ?? process.cwd();
-      const taskId = String(params?.taskId ?? '');
-      const latest = latestGeneration(readHistory(histFile(cwd)), taskId);
+      const rawTaskId = String(params?.taskId ?? params?.agentId ?? '').trim();
+      if (!rawTaskId) {
+        return toolError('missing taskId for resume (see action list or delegation ledger).');
+      }
+      const history = readHistory(histFile(cwd));
+      const resolution = resolveTaskIdPrefix(rawTaskId, history.map((e) => e.taskId));
+      if (resolution.kind === 'too_short') {
+        return toolError(`Error: task id prefix "${rawTaskId}" is too short (minimum 4 characters).`);
+      }
+      if (resolution.kind === 'ambiguous') {
+        const list = resolution.candidates.slice(0, 5).join(', ');
+        const more = resolution.candidates.length > 5 ? `, ... (+${resolution.candidates.length - 5} more)` : '';
+        return toolError(`Error: ambiguous task id "${rawTaskId}" matches ${resolution.candidates.length} tasks: ${list}${more}`);
+      }
+      if (resolution.kind === 'not_found') {
+        return toolError(`Error: no history for task "${rawTaskId}" in this workspace.`);
+      }
+      const taskId = resolution.taskId;
+      const latest = latestGeneration(history, taskId);
       if (!latest) {
-        return {
-          content: [{ type: 'text', text: `Error: no history for task "${taskId}" in this workspace.` }],
-          details: {},
-        };
+        return toolError(`Error: no history for task "${taskId}" in this workspace.`);
       }
       const release = await subSemaphore.acquire();
       try {
@@ -380,7 +344,7 @@ export default function subagentPlugin(ctx: Context): void {
             description: latest.description,
             background: true,
             status: 'running',
-            sessionFile: latest.sessionFile,
+            sessionFile: latest.sessionFile ?? null,
             launchCommand: latest.launchCommand,
             createdAt: Date.now(),
             revivedFrom: latest.paneId,
@@ -427,64 +391,90 @@ export default function subagentPlugin(ctx: Context): void {
           details: { paneId: entry.paneId, taskId },
         };
       } catch (err) {
-        return {
-          content: [{ type: 'text', text: `Error: failed to resume task "${taskId}": ${(err as Error).message}` }],
-          details: {},
-        };
+        return toolError(`Error: failed to resume task "${taskId}": ${(err as Error).message}`);
       } finally {
         release();
       }
   }
 
-  async function executeSubagentList() {
-      const listed = [...subs.values()].filter((s) => s.background);
-      if (listed.length === 0) {
-        return { content: [{ type: 'text', text: 'No background subagents started (from this session branch).' }], details: {} };
-      }
-      // Deduplicate by taskId so only the newest generation appears after revival; old paneIds do not repeat.
-      const byTask = new Map<string, SubEntry>();
-      for (const sub of listed) {
-        const prev = byTask.get(sub.taskId);
-        if (!prev || sub.createdAt >= prev.createdAt) byTask.set(sub.taskId, sub);
-      }
-      // C1: Probe liveness in real time (pane status and session activity) so the master can distinguish work from a true hang.
-      const probes = new Map<string, AliveProbe>();
-      await Promise.all([...byTask.values()].map(async (sub) => {
-        if (sub.status === 'closed') return;
-        try { probes.set(sub.paneId, await probeAlive(sub.paneId, sub.cwd)); } catch { /* Best effort for display. */ }
-      }));
-      const lines: string[] = [];
-      for (const sub of byTask.values()) {
-        const tabTag = sub.tabName ? ` [tab: ${sub.tabName}]` : '';
-        // D98: Include the worktree branch on isolate entries, including closed ones; settlement stats already report merge state.
-        const wtTag = sub.isolate ? ` [wt: ${sub.isolate.branch}]` : '';
-        if (sub.status === 'closed') {
-          lines.push(`${sub.taskId.slice(0, 8)} [idle] (${sub.kind}, closed; action send revives)${tabTag}${wtTag} ${sub.description}`);
-          continue;
-        }
-        // The registry is authoritative: settled is idle, everything else is running, including blocked human gates (DSH mapping).
-        const state = sub.status === 'settled' ? 'idle' : 'running';
-        // D94: Mark when the user has taken over.
-        const takeoverMark = sub.userTakeover ? ', user-controlled' : '';
-        const probe = probes.get(sub.paneId);
-        const statusTag = probe?.agentStatus ? ` ${probe.agentStatus}` : '';
-        const activityTag = probe?.lastActivityMs != null ? `, active ${agoText(probe.lastActivityMs, Date.now())}` : '';
-        // E: For blocked agents, include the gate-question summary so the master sends the user to that pane instead of taking over.
-        let gateTag = '';
-        if (probe?.agentStatus === 'blocked') {
-          const q = await readAskFlag(sub.paneId);
-          gateTag = q ? ` — AWAITING HUMAN: "${q}"` : ' — AWAITING HUMAN decision';
+  const listActionDeps = {
+    subs: () => subs.values(),
+    probeAlive,
+    readAskFlag,
+  };
+  function resolveSubEntry(
+    rawId: string,
+    cwd?: string,
+  ): { entry: SubEntry } | { error: string } {
+    if (!rawId) {
+      return { error: 'Error: unknown subagent id "" (see action list)' };
+    }
+    const direct = subs.get(rawId);
+    if (direct) return { entry: direct };
+
+    const byTaskId = new Map<string, SubEntry>();
+    for (const sub of subs.values()) {
+      const prev = byTaskId.get(sub.taskId);
+      if (!prev || sub.createdAt >= prev.createdAt) byTaskId.set(sub.taskId, sub);
+    }
+    const res = resolveTaskIdPrefix(rawId, byTaskId.keys());
+    if (res.kind === 'resolved') {
+      return { entry: byTaskId.get(res.taskId)! };
+    }
+    if (res.kind === 'ambiguous') {
+      const list = res.candidates.slice(0, 5).join(', ');
+      const more = res.candidates.length > 5 ? `, ... (+${res.candidates.length - 5} more)` : '';
+      return { error: `Error: ambiguous subagent id "${rawId}" matches ${res.candidates.length} tasks: ${list}${more}` };
+    }
+    if (res.kind === 'too_short') {
+      return { error: `Error: subagent id prefix "${rawId}" is too short (minimum 4 characters).` };
+    }
+
+    if (cwd) {
+      const hist = readHistory(histFile(cwd));
+      const histTaskIds = Array.from(new Set(hist.map((e) => e.taskId)));
+      const histRes = resolveTaskIdPrefix(rawId, histTaskIds);
+      if (histRes.kind === 'resolved') {
+        const latest = latestGeneration(hist, histRes.taskId);
+        if (latest) {
+          const entry: SubEntry = {
+            taskId: latest.taskId,
+            kind: latest.kind,
+            paneId: latest.paneId,
+            tabId: latest.tabId,
+            tabName: latest.tabName ?? '',
+            cwd: latest.cwd,
+            description: latest.description,
+            background: true,
+            status: 'closed',
+            sessionFile: latest.sessionFile,
+            launchCommand: latest.launchCommand,
+            createdAt: latest.createdAt,
+            consumedAt: latest.consumedAt ?? null,
+            revivedFrom: latest.paneId,
+          };
+          subs.set(entry.paneId, entry);
+          return { entry };
         }
-        lines.push(`${sub.paneId} [${state}${takeoverMark}${statusTag}${activityTag}${gateTag}] (${sub.kind})${tabTag}${wtTag} ${sub.description}`);
       }
-      return { content: [{ type: 'text', text: lines.join('\n') }], details: {} };
+      if (histRes.kind === 'ambiguous') {
+        const list = histRes.candidates.slice(0, 5).join(', ');
+        const more = histRes.candidates.length > 5 ? `, ... (+${histRes.candidates.length - 5} more)` : '';
+        return { error: `Error: ambiguous subagent id "${rawId}" matches ${histRes.candidates.length} tasks: ${list}${more}` };
+      }
+    }
+
+    return { error: `Error: unknown subagent id "${rawId}" (see action list)` };
   }
 
-  async function executeSubagentSend(params) {
-      const entry = subs.get(String(params?.agentId ?? ''));
-      if (!entry) {
-        return { content: [{ type: 'text', text: `Error: unknown subagent id "${params?.agentId}" (see action list)` }], details: {} };
+  async function executeSubagentSend(params: Record<string, unknown> | undefined, toolCtx?: unknown) {
+      const rawId = String(params?.agentId ?? params?.taskId ?? '').trim();
+      const cwd = (toolCtx as { cwd?: string })?.cwd ?? process.cwd();
+      const resolved = resolveSubEntry(rawId, cwd);
+      if ('error' in resolved) {
+        return toolError(resolved.error);
       }
+      const entry = resolved.entry;
       const spawnedAt = Date.now();
       try {
         // A closed task is revived automatically because the pane is only a temporary host.
@@ -496,7 +486,7 @@ export default function subagentPlugin(ctx: Context): void {
         // M11 (D46): follow_up uses the extension pipe. B3 adds steering so supplemental instructions reach a long-running worker
         // within seconds during a tool-call gap; the old followUp queue waited for the entire run and caused 20-minute rework (01a03c0d).
         const ready = await waitSubReady(entry.cwd, entry.paneId);
-        if (!ready) throw new Error(`subagent pane ${entry.paneId} pipe not ready`);
+        if (!ready.ok) throw new Error(ready.message);
         const fuId = `fu-${Date.now()}`;
         const res = await pipeRequestTo(entry.cwd, entry.paneId, {
           type: 'follow_up',
@@ -525,15 +515,18 @@ export default function subagentPlugin(ctx: Context): void {
         }
         return { content: [{ type: 'text', text: `Message sent to subagent ${entry.paneId}.` }], details: { paneId: entry.paneId } };
       } catch (err) {
-        return { content: [{ type: 'text', text: `Error: failed to reach subagent ${entry.paneId}: ${(err as Error).message}` }], details: {} };
+        return toolError(`Error: failed to reach subagent ${entry.paneId}: ${(err as Error).message}`);
       }
   }
 
-  async function executeSubagentInterrupt(params) {
-      const entry = subs.get(String(params?.agentId ?? ''));
-      if (!entry) {
-        return { content: [{ type: 'text', text: `Error: unknown subagent id "${params?.agentId}" (see action list)` }], details: {} };
+  async function executeSubagentInterrupt(params: Record<string, unknown> | undefined, toolCtx?: unknown) {
+      const rawId = String(params?.agentId ?? params?.taskId ?? '').trim();
+      const cwd = (toolCtx as { cwd?: string })?.cwd ?? process.cwd();
+      const resolved = resolveSubEntry(rawId, cwd);
+      if ('error' in resolved) {
+        return toolError(resolved.error);
       }
+      const entry = resolved.entry;
       if (entry.status === 'closed') {
         // DSH alignment: an idle or finished target is an idempotent no-op.
         return { content: [{ type: 'text', text: `Interrupt accepted for subagent ${entry.paneId} (already idle/closed; no-op).` }], details: {} };
@@ -551,13 +544,47 @@ export default function subagentPlugin(ctx: Context): void {
         if (lastId) d.claimSettleNotice(`${entry.paneId}:${lastId}`);
         return { content: [{ type: 'text', text: `Interrupt accepted for subagent ${entry.paneId} (fire-and-return).` }], details: { paneId: entry.paneId } };
       } catch (err) {
-        return { content: [{ type: 'text', text: `Error: failed to reach subagent ${entry.paneId}: ${(err as Error).message}` }], details: {} };
+        return toolError(`Error: failed to reach subagent ${entry.paneId}: ${(err as Error).message}`);
       }
   }
+  const outputActionDeps = {
+    client,
+    resolveEntry: (rawId: string, cwd: string) => resolveSubEntry(rawId, cwd),
+    readAskFlag,
+    outputCursors,
+    getCwd: (toolCtx: unknown): string => (toolCtx as { cwd?: string })?.cwd ?? process.cwd(),
+  };
+  const executeSubagentSpawn = createSpawnAction({
+    client,
+    env,
+    subSemaphore,
+    subs,
+    persistSubs,
+    writeHistory,
+    pendingIsolateBranches,
+    lastMachineInjectAt,
+    lastRequestIdByPane,
+    git,
+    session,
+    spawn,
+    poller,
+  });
+
 
   scoped.registerTool({
     name: 'subagent',
     label: 'Subagent',
+    // B4: the model picks tools from the system prompt's snippet/guideline surface; this tool is the
+    // one place where delegation decisions are made, so state them here rather than hoping for recall.
+    promptSnippet: 'subagent: delegate a self-contained task to a pi worker pane (spawn/isolate/background/send/output/interrupt/resume/list).',
+    promptGuidelines: [
+      'Use subagent when the work is self-contained and the result is what matters: pipelines that would flood this context, long builds/test runs, or independent parts of a bigger change that can proceed in parallel.',
+      'Prefer run_in_background: true for work that will not finish in a few tool calls, then collect with action: "output" — a foreground subagent blocks this turn.',
+      'Use isolate: true when the worker will write files for a task you (or another worker) are editing at the same time, or when you want its own reviewable branch; use cwd to send work into an existing worktree (create it with git worktree add first).',
+      'Keep the prompt complete and self-contained: the worker does not see this conversation, so include paths, acceptance criteria, the test command, and what to report back.',
+      'Do not poll with action: "output" in a tight loop: the pane pushes a settlement notice when it finishes. Check once, then continue other work.',
+      'Send follow-up instructions with action: "send" (delivered as a steer between tool calls) instead of spawning a second worker for the same task.',
+    ],
     description: SUBAGENT_DESCRIPTION,
     parameters: Type.Object({
       action: Type.Optional(Type.Union([
@@ -566,6 +593,7 @@ export default function subagentPlugin(ctx: Context): void {
         Type.Literal('list'),
         Type.Literal('send'),
         Type.Literal('interrupt'),
+        Type.Literal('output'),
       ], { description: 'Operation to perform (default: spawn)' })),
       description: Type.Optional(Type.String({ description: '[spawn] Short label for this subtask (pane title)' })),
       prompt: Type.Optional(Type.String({ description: '[spawn] The complete self-contained task for the subagent' })),
@@ -576,264 +604,30 @@ export default function subagentPlugin(ctx: Context): void {
       tab: Type.Optional(Type.String({ description: '[spawn] Name of a task tab to place the subagent into (join if exists, otherwise create). Default placement groups by git worktree.' })),
       allowed_tools: Type.Optional(Type.Array(Type.String(), { description: '[spawn] Additional tools for role composition (union with role baseline)' })),
       taskId: Type.Optional(Type.String({ description: '[resume] The task id to revive from the delegation ledger' })),
-      agentId: Type.Optional(Type.String({ description: '[send|interrupt] The subagent id (herdr pane id)' })),
+      agentId: Type.Optional(Type.String({ description: '[send|interrupt|output] The subagent id (herdr pane id)' })),
       message: Type.Optional(Type.String({ description: '[send] The follow-up message' })),
+      max_chars: Type.Optional(Type.Integer({ description: '[output] Maximum characters of output delta to return (default 6000, 100-16000)' })),
     }),
-    async execute(toolCallId, params, signal, onUpdate, toolCtx) {
+    // B2: 23/38 real spawns omitted `action` even though it is optional; normalize so the schema the
+    // model is validated against and the code path never disagree, and so `spawn` is explicit in logs.
+    prepareArguments: (args: unknown) => {
+      const rec = (args && typeof args === 'object' ? args : {}) as Record<string, unknown>;
+      const hasAction = typeof rec.action === 'string' && rec.action.trim() !== '';
+      return hasAction ? rec : { ...rec, action: 'spawn' };
+    },
+    async execute(toolCallId: string, params: ToolParams, signal: AbortSignal | undefined, onUpdate: ((update: unknown) => void) | undefined, toolCtx: unknown) {
       void toolCallId;
       void signal;
       const action = typeof params?.action === 'string' && params.action.trim() ? params.action.trim() : 'spawn';
       if (action === 'resume') return executeSubagentResume(params, toolCtx);
-      if (action === 'list') return executeSubagentList();
-      if (action === 'send') return executeSubagentSend(params);
-      if (action === 'interrupt') return executeSubagentInterrupt(params);
+      if (action === 'list') return executeSubagentList(listActionDeps);
+      if (action === 'send') return executeSubagentSend(params, toolCtx);
+      if (action === 'interrupt') return executeSubagentInterrupt(params, toolCtx);
+      if (action === 'output') return executeSubagentOutput(params, toolCtx, outputActionDeps);
       if (action !== 'spawn') {
-        return { content: [{ type: 'text', text: `Error: unknown action "${action}" (valid: spawn, resume, list, send, interrupt)` }], details: {} };
-      }
-      const launch = planLaunchValidation(params, client.available);
-      if (launch.kind === 'error') {
-        return { content: [{ type: 'text', text: launch.text }], details: {} };
-      }
-      const { spec, background, isolate, cwdParam, roleKind: kind, suggested, manifestRole, tab } = launch;
-      const masterCwd = (toolCtx as { cwd?: string }).cwd ?? process.cwd();
-      // Move taskId generation above the original spawn section because isolate planning needs taskHex; this is behavior-neutral.
-      const taskId = randomUUID();
-      // D98 2c: Create the isolate through pier's execFile git path (decision 1), not herdr's
-      // socket worktree.create, which has bootstrap races, missing root-pane env, worker/master
-      // workspace separation, and linked_worktree_source rejection. The model makes the decision; do not infer it.
-      let isolateMeta: SubEntry['isolate'] | null = null;
-      let cwd = masterCwd;
-      if (isolate) {
-        const baseSha = await runGit(masterCwd, ['rev-parse', 'HEAD']);
-        const isoGuard = planIsolateRepoGuard(baseSha);
-        if (isoGuard.kind === 'error') {
-          return { content: [{ type: 'text', text: isoGuard.text }], details: {} };
-        }
-        const sha = isoGuard.sha.trim();
-        const pierBranches = new Set(
-          ((await runGit(masterCwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/pier/'])) ?? '')
-            .split('\n').filter(Boolean),
-        );
-        const worktrees = await listWorktrees(masterCwd);
-        const repoName = basename(worktrees[0] ?? masterCwd);
-        const plan = planIsolateWorktree({
-          description: spec.description,
-          taskHex: taskId.slice(0, 6),
-          existingPierBranches: pierBranches,
-        });
-        const wtPath = join(platformPaths.worktreeBaseDir, repoName, plan.worktreeDirName);
-        try {
-          mkdirSync(dirname(wtPath), { recursive: true }); // git worktree add does not create its parent directory, so a first run would fail.
-        } catch { /* Existing directory or permissions failure is handled by worktree add. */ }
-        // Keep the branch pending between worktree add and subs.set: the 2–3s readiness wait lets the ticker
-        // scan, and without this guard it could reclaim a new clean =HEAD-ancestor worktree as an orphan.
-        pendingIsolateBranches.add(plan.branch);
-        const added = await runGit(masterCwd, ['worktree', 'add', '-b', plan.branch, wtPath, sha]);
-        if (added === null) {
-          pendingIsolateBranches.delete(plan.branch);
-          return {
-            content: [{ type: 'text', text: `Error: failed to create worktree ${wtPath} (branch ${plan.branch}) — run \`git worktree prune\` and retry if it reports stale entries` }],
-            details: {},
-          };
-        }
-        git.invalidateWorktreesCache(); // Invalidate the 5s cache so the zone classifier sees the new worktree immediately.
-        cwd = wtPath;
-        isolateMeta = { worktreePath: wtPath, branch: plan.branch, baseSha: sha, releasedAt: null, retainNotified: false };
-        spec.prompt = `${buildIsolatePreamble({ worktreePath: wtPath, branch: plan.branch, baseShort: sha.slice(0, 7) })}\n\n${spec.prompt}`;
-      } else if (cwdParam) {
-        cwd = pathResolve(masterCwd, cwdParam);
-        try {
-          const st = await statAsync(cwd);
-          if (!st.isDirectory()) throw new Error('not a directory');
-        } catch {
-          return {
-            content: [{ type: 'text', text: `Error: \`cwd\` is not an existing directory: ${cwdParam}` }],
-            details: {},
-          };
-        }
-      }
-      // D86 R1: Group by the git worktree containing cwd (main checkout → main tab; other worktree → directory-named tab).
-      const zone = classifyWorktreeZone({
-        cwd,
-        masterCwd,
-        worktrees: await listWorktrees(masterCwd),
-      });
-      // D86 trust: pass -a only for the master's checkout/worktrees; external directories remain behind pi's Trust dialog.
-      const approve = isPathUnder(cwd, masterCwd) || zone.zone === 'worktree';
-      let roleManifestEnv: Record<string, string> = {};
-      let roleModel: string | null = null;
-      try {
-        const { role, manifest } = composeForRole(manifestRole, suggested, { loadRoleOpts: { baseDir: masterCwd } });
-        roleManifestEnv = {
-          PI_HERDR_ROLE_MANIFEST: JSON.stringify({
-            role: role.role,
-            version: role.version,
-            tools: manifest.tools,
-            permissions: manifest.permissions,
-            unknownTools: manifest.unknownTools,
-            services: role.services ?? {},
-          }),
-        };
-        // WS-D10: Route the model by role; omission intentionally uses the process default.
-        if (typeof role.model === 'string' && role.model.trim()) roleModel = role.model.trim();
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{ type: 'text', text: `Error: role "${manifestRole}" manifest invalid — ${msg}` }],
-          details: {},
-        };
-      }
-      const release = await subSemaphore.acquire();
-      let paneId = '';
-      try {
-        const spawnedAt = Date.now();
-        const spawned = await spawnPaneInTaskTab(
-          { desiredTab: tab, description: spec.description, zone },
-          cwd,
-          { PI_HERDR_SUBAGENT: '1', ...roleManifestEnv },
-          launchLine(null, roleModel, approve),
-        );
-        paneId = spawned.paneId;
-        const entry: SubEntry = {
-          taskId,
-          kind,
-          paneId,
-          tabId: spawned.tabId,
-          tabName: spawned.tabName,
-          cwd,
-          description: spec.description,
-          background,
-          status: 'running',
-          sessionFile: null,
-          launchCommand: [launchLine(null, roleModel, approve)],
-          createdAt: Date.now(),
-          revivedFrom: null,
-          ...(isolateMeta ? { isolate: isolateMeta } : {}),
-        };
-        const ready = await waitSubReady(cwd, paneId);
-        if (!ready) throw new Error(`subagent pane ${paneId} pipe not ready within ${SUB_READY_TIMEOUT_MS}ms`);
-        entry.sessionFile = await resolveSessionFile(paneId, cwd);
-        subs.set(paneId, entry);
-        persistSubs();
-        onUpdate?.(makeProgressUpdate(`subagent ready in pane ${paneId}; injecting prompt via pipe…`));
-        // M11 (D45/D46): Inject through the extension pipe to the child extension's sendUserMessage(followUp);
-        // reserve the PTY keyboard channel entirely for the person, with no soft-lock window or mixed input.
-        // Regression evidence (session 01a03bf0): ecc0bc4's foreground-wait rewrite once removed this block,
-        // leaving the prompt uninjected and injectTs undefined (ReferenceError → spawn-failed, with a ghost
-        // running ledger entry). Keep injection and injectTs together in future refactors.
-        const injectTs = Date.now();
-        const injected = await pipeRequestTo(cwd, paneId, {
-          type: 'prompt',
-          id: `prompt-${taskId}`,
-          text: spec.prompt,
-          from: pipeNameFor(cwd, env?.paneId ?? ''),
-          push: background,
-        });
-        if (injected.type !== 'ok') {
-          throw new Error(`pipe prompt rejected: ${injected.type === 'error' ? injected.message : 'unknown response'}`);
-        }
-        lastMachineInjectAt.set(paneId, injectTs); // B4: attribute working state during the observation window.
-        // A1+A2 (user-verified fix): foreground waiting uses a content gate plus a patience threshold before backgrounding.
-        // Treating idle as settled with a hard 90s window misclassified real 4–6 minute working periods as no-output;
-        // three healthy subagents were observed becoming consumed at 101s while producing results four minutes later.
-        const PATIENCE_MS = runtimePolicy.foregroundPatienceMs;
-        const patienceDeadline = Date.now() + PATIENCE_MS;
-        let text: string | null = null;
-        let settledKind: 'settled' | 'timeout' = 'timeout';
-        while (Date.now() < Math.min(patienceDeadline, spawnedAt + SUBAGENT_TIMEOUT_MS)) {
-          const state = await client.waitAgent(paneId, ['idle', 'done', 'blocked'], 30_000);
-          const session = (state === 'idle' || state === 'done')
-            ? await subSessionState(paneId, cwd, injectTs)
-            : { text: null, pendingTool: false, activity: false };
-          const tick = planForegroundTick({ state, session });
-          if (tick.kind === 'blocked') {
-            const question = await readAskFlag(paneId);
-            entry.background = true;
-            lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
-            startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
-            persistSubs();
-            writeHistory(entry, undefined, 'to-background');
-            return {
-              content: [{ type: 'text', text: buildBlockedGateNotice({ paneId, description: spec.description, question }) }],
-              details: { paneId, taskId, background: true, blocked: true, role: kind },
-            };
-          }
-          if (tick.kind === 'settled') {
-            text = tick.text;
-            settledKind = 'settled';
-            break;
-          }
-          if (tick.kind === 'wait') {
-            await new Promise((r) => setTimeout(r, tick.delayMs));
-            continue;
-          }
-          if (tick.kind === 'collect-final') {
-            text = await collectFinalText(paneId, cwd, injectTs, 6);
-            if (text) { settledKind = 'settled'; break; }
-            await new Promise((r) => setTimeout(r, FOREGROUND_POLL_MS));
-            continue;
-          }
-        }
-        if (!text && settledKind !== 'blocked') {
-          const probe = await probeAlive(paneId, cwd);
-          if (planPatienceExpiry(isAlive(probe, Date.now())) === 'move-to-background') {
-            entry.background = true;
-            lastRequestIdByPane.set(paneId, `prompt-${taskId}`);
-            startPoller(paneId, cwd, spawnedAt, injectTs, spec.description, `prompt-${taskId}`);
-            persistSubs();
-            const notice = buildAliveNotice(
-              { paneId, description: spec.description, scenario: 'moved-to-bg', probe },
-              Date.now(),
-            );
-            return {
-              content: [{ type: 'text', text: notice }],
-              details: { paneId, taskId, background: true, movedToBackground: true, role: kind },
-            };
-          }
-          settledKind = 'timeout';
-        }
-        const outcome =
-          settledKind === 'timeout' ? { kind: 'timeout' as const, text: text ?? '' }
-          : text ? { kind: 'completed' as const, text }
-          : { kind: 'no-output' as const, text: '' };
-        entry.status = 'consumed';
-        entry.consumedAt = Date.now();
-        persistSubs();
-        writeHistory(entry, { outcome: outcome.kind === 'completed' ? text : null }, 'fg-settle');
-        return {
-          content: [{ type: 'text', text: formatSubagentResult(outcome, spec.description) }],
-          details: { paneId, taskId, background, role: kind },
-        };
-      } catch (err) {
-        // Regression fix (session 01a03bf0): a mid-spawn failure must remove the ledger entry and close its pane,
-        // otherwise a ghost running entry never settles, causing D96 reminder storms and send_message calls
-        // to land in an empty session with no task context. Pane closure is best effort; GC covers board exceptions.
-        if (paneId) {
-          subs.delete(paneId);
-          persistSubs();
-          void client.closePane(paneId).catch(() => { /* Best effort only. */ });
-        }
-        // D98 2d: If isolate startup never becomes ready, best-effort remove the new worktree and branch (no work
-        // exists to preserve); failure stays silent because the branch is harmless and remains visible to git worktree list.
-        if (isolateMeta) {
-          void runGit(masterCwd, ['worktree', 'remove', '--force', isolateMeta.worktreePath])
-            .then(() => runGit(masterCwd, ['branch', '-D', isolateMeta!.branch]))
-            .catch(() => { /* Best effort only. */ });
-        }
-        return {
-          content: [{
-            type: 'text',
-            text: formatSubagentResult(
-              { kind: 'spawn-failed', text: String((err as Error)?.message ?? err) },
-              spec.description,
-            ),
-          }],
-          details: {},
-        };
-      } finally {
-        release();
-        if (isolateMeta) pendingIsolateBranches.delete(isolateMeta.branch); // D98: release the creation-window guard on every success/failure path.
+        return toolError(`Error: unknown action "${action}" (valid: spawn, resume, list, send, interrupt, output)`);
       }
+      return executeSubagentSpawn(params, toolCtx, onUpdate);
     },
   });
 }