pi-jar 0.1.5 → 0.1.7

package/src/delegate.ts

@@ -1,5 +1,8 @@
 import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { signalProcessTree } from "./async-process.ts";
+import { CHILD_TOOLS_ENV, RECURSIVE_TOOLS, WEB_TOOLS } from "./subagent-tools.ts";
+import { existsSync, mkdtempSync } from "node:fs";
+import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -30,13 +33,25 @@ export const SUBAGENT_LIMIT_CHOICES = [2, 4, 6, 8, 16] as const;
 /** Read-only subagents also keep jar_todo so their checklist shows in the activity view. */
 export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "jar_todo", "jar_discuss"] as const;
 /** Writable worktree children deliberately have no shell: edits stay inside path-guarded file tools. */
-export const WORKTREE_TOOLS = ["read", "edit", "write", "grep", "find", "ls", "jar_todo", "jar_discuss"] as const;
+export const WORKTREE_TOOLS = ["read", "edit", "write", "multi_file_edit", "grep", "find", "ls", "jar_todo", "jar_discuss"] as const;
+const READ_ONLY_SAFE_TOOLS = new Set<string>([...READ_ONLY_TOOLS, ...WEB_TOOLS, "ffgrep", "fffind", "lsp_diagnostics", "obs_recall"]);
+const WORKTREE_SAFE_TOOLS = new Set<string>([...WORKTREE_TOOLS, ...WEB_TOOLS]);
+const allowedInMode = (mode: DelegateExecutionMode, name: string) => !RECURSIVE_TOOLS.has(name)
+  && (mode === "direct" || (mode === "worktree" ? WORKTREE_SAFE_TOOLS.has(name) : READ_ONLY_SAFE_TOOLS.has(name)));
 export type DelegateMode = "scout" | "fork" | "worktree";
 type DelegateExecutionMode = DelegateMode | "direct";
 const MAX_OUTPUT_CHARS = 12_000;
-const TIMEOUT_MS = 20 * 60_000;
+/** A working child that sends no RPC event for this long is treated as hung and killed. */
+const IDLE_TIMEOUT_MS = 10 * 60_000;
+/** After exit, grandchildren (MCP servers, shells) can hold the stdio pipes open; stop waiting for close. */
+const CLOSE_GRACE_MS = 2000;
+/** How long pause waits for the child to settle after abort before reporting that it has not paused yet. */
+const PAUSE_GRACE_MS = 15_000;
 const STATUS_REFRESH_MS = 20_000;
 const LIVE_UPDATE_MS = 1000;
+/** Visible message that wakes the moderator when a resumed subagent's turn ends. */
+export const SUBAGENT_MESSAGE = "pi-jar.subagent";
+const NOTIFY_COALESCE_MS = 250;
 const MAX_EVENT_TEXT = 16_000;
 /** Transcript entries kept per run; tool output and text are clipped so a run stays well under 2 MiB. */
 const MAX_ENTRIES = 200;
@@ -138,7 +153,7 @@ export interface DelegateForkOptions {
 
 /** CLI arguments for one subagent: fresh ephemeral session or a real Pi session fork. */
 export function delegateArgs(model: string | undefined, thinking: string | undefined, write: boolean, argv = process.argv,
-  fork?: DelegateForkOptions): string[] {
+  fork?: DelegateForkOptions, toolOverride?: readonly string[]): string[] {
   const session = fork ? ["--fork", fork.source, "--session-dir", fork.sessionDir] : ["--no-session"];
   const extensions = extensionFlags(argv);
   // Worktree cwd/session forks do not inherit project extension discovery from the parent.
@@ -149,7 +164,7 @@ export function delegateArgs(model: string | undefined, thinking: string | undef
   const args = ["--mode", "rpc", ...session, ...extensions];
   if (model) args.push("--model", model);
   if (thinking) args.push("--thinking", thinking);
-  const tools = fork?.tools ?? (!write ? READ_ONLY_TOOLS : undefined);
+  const tools = fork?.tools ?? toolOverride ?? (!write ? READ_ONLY_TOOLS : undefined);
   if (tools) args.push("--tools", tools.join(","));
   return args;
 }
@@ -181,6 +196,28 @@ export function delegatePrompt(task: string, write: boolean, mode: DelegateExecu
 const cleanBlock = (value: string, limit: number): string => value.slice(0, limit * 2)
   .replace(ANSI, "").replace(/\r\n?/g, "\n").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, " ").replace(/\n{3,}/g, "\n\n").trim().slice(0, limit);
 
+/** Whether `promise` settles within `ms`; the timer never keeps the process alive. */
+const settlesWithin = (promise: Promise<unknown>, ms: number): Promise<boolean> => {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+    timer.unref?.();
+  });
+  return Promise.race([promise.then(() => true, () => true), timeout]).finally(() => clearTimeout(timer));
+};
+
+/** `promise`, or undefined as soon as `signal` aborts; the work itself continues in the background. */
+const untilAborted = <T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T | undefined> => {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.resolve(undefined);
+  let onAbort = () => {};
+  const aborted = new Promise<undefined>((resolve) => {
+    onAbort = () => resolve(undefined);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  return Promise.race([promise, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
+};
+
 const textOf = (message: { content?: unknown }, limit = MAX_EVENT_TEXT): string => {
   if (typeof message.content === "string") return message.content.slice(0, limit);
   if (!Array.isArray(message.content)) return "";
@@ -256,6 +293,7 @@ interface ChildEvent {
   id?: unknown;
   command?: unknown;
   success?: unknown;
+  data?: { disposition?: unknown };
   error?: unknown;
   method?: unknown;
   toolCallId?: unknown;
@@ -308,8 +346,8 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
     let child: ChildProcess;
     try {
       const env = { ...process.env };
-      for (const key of [CHILD_BASELINE_ENV, CHILD_WORKTREE_ENV, DISCUSSION_FILE_ENV, SUBAGENT_KEY_ENV, SUBAGENT_NAME_ENV]) delete env[key];
-      child = spawnProcess(invocation.command, invocation.args, { cwd, shell: false, stdio: ["pipe", "pipe", "pipe"], env: { ...env, ...hooks.env, [CHILD_ENV]: "1" } });
+      for (const key of [CHILD_BASELINE_ENV, CHILD_WORKTREE_ENV, CHILD_TOOLS_ENV, DISCUSSION_FILE_ENV, SUBAGENT_KEY_ENV, SUBAGENT_NAME_ENV]) delete env[key];
+      child = spawnProcess(invocation.command, invocation.args, { cwd, shell: false, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"], env: { ...env, ...hooks.env, [CHILD_ENV]: "1" } });
     } catch (error) {
       run.state = "failed"; run.error = error instanceof Error ? error.message : String(error); run.endedAt = Date.now(); update();
       firstResolved = true; resolveFirst(); resolveClosed(); return;
@@ -335,28 +373,56 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
     let askBusy = false;
     let killTimer: ReturnType<typeof setTimeout> | undefined;
     let turnTimer: ReturnType<typeof setTimeout> | undefined;
+    let closeTimer: NodeJS.Timeout | undefined;
+    /** Last RPC event while working; the watchdog only fires after this much silence. */
+    let activityAt = Date.now();
     const settleWaiters: Array<() => void> = [];
 
     const send = (command: object): boolean => {
       const stdin = child.stdin;
       if (!alive || !stdin || stdin.destroyed || stdin.writableEnded) return false;
+      // Node queues writes until drain. Bound that queue if a hung RPC child stops reading;
+      // accepted commands remain complete JSONL records, never partial/manual framing.
+      if (stdin.writableLength > 256 * 1024) return false;
       try { stdin.write(JSON.stringify(command) + "\n"); return true; } catch { return false; }
     };
     const clearTurnTimer = () => { if (turnTimer) clearTimeout(turnTimer); turnTimer = undefined; };
     const hardStop = () => {
       if (!alive) return;
-      child.kill("SIGTERM");
-      killTimer ??= setTimeout(() => { if (alive) child.kill("SIGKILL"); }, 3000);
+      signalProcessTree(child, "SIGTERM");
+      killTimer ??= setTimeout(() => {
+        // Kill the group even if its leader exited: descendants can ignore SIGTERM and keep pipes.
+        signalProcessTree(child, "SIGKILL");
+        child.stdout?.destroy?.();
+        child.stderr?.destroy?.();
+        exited(child.exitCode);
+      }, 3000);
       killTimer.unref?.();
     };
-    const armTurnTimer = () => {
+    const armTurnTimer = (delay = IDLE_TIMEOUT_MS) => {
       clearTurnTimer();
       turnTimer = setTimeout(() => {
+        turnTimer = undefined;
+        const quiet = Date.now() - activityAt;
+        if (quiet < IDLE_TIMEOUT_MS) { armTurnTimer(IDLE_TIMEOUT_MS - quiet); return; }
         hardStop();
-        finish("failed", "timed out");
-      }, TIMEOUT_MS);
+        finish("failed", `timed out: no activity for ${duration(IDLE_TIMEOUT_MS)}`);
+      }, delay);
       turnTimer.unref?.();
     };
+    /** High-frequency stream events repaint at most every LIVE_REPAINT_MS. */
+    const repaint = () => {
+      const now = Date.now();
+      if (now - liveAt >= LIVE_REPAINT_MS) {
+        liveAt = now;
+        if (liveTimer) { clearTimeout(liveTimer); liveTimer = undefined; }
+        update();
+        return;
+      }
+      if (liveTimer) return;
+      liveTimer = setTimeout(() => { liveTimer = undefined; liveAt = Date.now(); if (!finished) update(); }, LIVE_REPAINT_MS - (now - liveAt));
+      liveTimer.unref?.();
+    };
     const resolveSettled = () => {
       for (const waiter of settleWaiters.splice(0)) waiter();
     };
@@ -375,7 +441,7 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
       for (const entry of run.transcript) if (entry.kind === "tool" && entry.status === "running") { entry.status = "error"; entry.endedAt = Date.now(); entry.rev++; }
       run.endedAt = Date.now();
       resolveSettled();
-      if (!alive && !firstResolved) { firstResolved = true; resolveFirst(); }
+      if (!firstResolved) { firstResolved = true; resolveFirst(); }
       update();
     };
     const abort = () => { hardStop(); finish("failed", signal?.reason === STOP_REASON ? "stopped" : "aborted"); };
@@ -396,21 +462,48 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
       run.resumes++;
       run.endedAt = undefined;
       run.activity = "resuming";
+      activityAt = Date.now();
       armTurnTimer();
       update();
       return true;
     };
 
     const running = new Map<string, { entry: ToolEntry; path?: string }>();
+    const settleTurn = () => {
+      if (settled || finished) return;
+      settled = true;
+      clearTurnTimer();
+      for (const call of running.values()) {
+        call.entry.status = "error";
+        call.entry.endedAt = Date.now();
+        call.entry.rev++;
+      }
+      running.clear();
+      run.live = "";
+      run.activity = undefined;
+      run.endedAt = Date.now();
+      run.state = run.error ? "failed" : pauseRequested ? "paused" : "idle";
+      pauseRequested = false;
+      if (!firstResolved && !run.error) { firstResolved = true; resolveFirst(); }
+      resolveSettled();
+      update();
+      if (run.error) { hardStop(); finish("failed", run.error); }
+      else if (!persistent && child.stdin && !child.stdin.writableEnded) child.stdin.end();
+    };
     const line = (raw: string) => {
       if (finished || !raw.trim()) return;
       let parsed: unknown;
       try { parsed = JSON.parse(raw); } catch { return; }
       if (!parsed || typeof parsed !== "object") return;
       const event = parsed as ChildEvent;
+      activityAt = Date.now();
       switch (event.type) {
         case "response":
-          if (event.success !== false) return;
+          // A handled prompt starts no run, so Pi deliberately sends no agent_settled event.
+          if (event.success !== false) {
+            if (event.command === "prompt" && event.data?.disposition === "handled") settleTurn();
+            return;
+          }
           if (event.command === "prompt") { hardStop(); finish("failed", cleanText(String(event.error ?? "prompt rejected"), 300)); return; }
           pushEntry(run, { kind: "note", rev: 0, text: `${cleanText(String(event.command ?? "command"), 24)} rejected: ${cleanText(String(event.error ?? ""), 200)}` });
           update();
@@ -423,14 +516,9 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
           if (delta?.type === "text_delta" && typeof delta.delta === "string") {
             run.live = (run.live + delta.delta).slice(-MAX_LIVE_CHARS);
             run.activity = "writing";
-            const now = Date.now();
-            if (now - liveAt >= LIVE_REPAINT_MS) { liveAt = now; update(); }
-            else if (!liveTimer) {
-              liveTimer = setTimeout(() => { liveTimer = undefined; liveAt = Date.now(); if (!finished) update(); }, LIVE_REPAINT_MS - (now - liveAt));
-              liveTimer.unref?.();
-            }
-          } else if (delta?.type === "thinking_start" || delta?.type === "thinking_delta") {
-            if (run.activity !== "thinking") run.activity = "thinking";
+            repaint();
+          } else if ((delta?.type === "thinking_start" || delta?.type === "thinking_delta") && run.activity !== "thinking") {
+            run.activity = "thinking";
             update();
           }
           return;
@@ -455,7 +543,7 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
           if (!call || !event.partialResult) return;
           call.entry.output = cleanBlock(textOf(event.partialResult, MAX_ENTRY_TEXT * 2), MAX_ENTRY_TEXT);
           call.entry.rev++;
-          update();
+          repaint();
           return;
         }
         case "tool_execution_end": {
@@ -491,30 +579,9 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
           update();
           return;
         }
-        case "agent_settled": {
-          settled = true;
-          clearTurnTimer();
-          for (const call of running.values()) {
-            call.entry.status = "error";
-            call.entry.endedAt = Date.now();
-            call.entry.rev++;
-          }
-          running.clear();
-          run.live = "";
-          run.activity = undefined;
-          run.endedAt = Date.now();
-          run.state = run.error ? "failed" : pauseRequested ? "paused" : "idle";
-          pauseRequested = false;
-          if (!firstResolved && !run.error) {
-            firstResolved = true;
-            resolveFirst();
-          }
-          resolveSettled();
-          update();
-          if (run.error) { hardStop(); finish("failed", run.error); }
-          else if (!persistent && child.stdin && !child.stdin.writableEnded) child.stdin.end();
+        case "agent_settled":
+          settleTurn();
           return;
-        }
       }
     };
 
@@ -524,7 +591,7 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
       let start = 0;
       for (let end = text.indexOf("\n", start); end >= 0; end = text.indexOf("\n", start)) {
         const item = buffer + text.slice(start, end);
-        if (!overflow) line(item.endsWith("\r") ? item.slice(0, -1) : item);
+        if (!overflow && item.length <= MAX_LINE_CHARS) line(item.endsWith("\r") ? item.slice(0, -1) : item);
         buffer = "";
         overflow = false;
         start = end + 1;
@@ -534,28 +601,50 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
       if (buffer.length > MAX_LINE_CHARS) { buffer = ""; overflow = true; }
     });
     child.stderr?.on("data", (chunk) => { stderr = (stderr + String(chunk)).slice(-4000); });
+    let closedOnce = false;
     const exited = (code: number | null) => {
+      if (closedOnce) return;
+      closedOnce = true;
       alive = false;
+      if (killTimer) signalProcessTree(child, "SIGKILL");
       clearTimeout(killTimer);
+      clearTimeout(closeTimer);
       if (buffer && !overflow) { line(buffer); buffer = ""; }
-      if (code === 0 && settled && !run.error) finish("done");
+      if ((closing || (code === 0 && settled)) && !run.error) finish("done");
       else finish("failed", run.error ?? (cleanText(stderr, 300) || (settled ? `exited ${code}` : `exited ${code} before finishing`)));
       if (!firstResolved) { firstResolved = true; resolveFirst(); }
       resolveClosed();
     };
-    child.on("error", (error) => { hardStop(); finish("failed", error.message); });
+    // A grandchild that inherited stdout/stderr keeps them open after the child is gone, and 'close'
+    // then never fires; stop waiting after a short drain so stop/shutdown can never hang on it.
+    const drainThenClose = (code: number | null) => {
+      if (closedOnce || closeTimer) return;
+      closeTimer = setTimeout(() => {
+        signalProcessTree(child, "SIGKILL");
+        child.stdout?.destroy?.();
+        child.stderr?.destroy?.();
+        exited(code);
+      }, CLOSE_GRACE_MS);
+      closeTimer.unref?.();
+    };
+    child.on("error", (error) => {
+      hardStop();
+      finish("failed", error.message);
+      // A process that never spawned has no exit event to wait for.
+      if (child.pid === undefined) { alive = false; drainThenClose(null); }
+    });
     // Exit retires control immediately, but finalization waits for close so stdio drains first.
     child.once("exit", (code) => {
       alive = false;
       clearTurnTimer();
-      clearTimeout(killTimer);
       if (!finished) {
-        run.state = code === 0 && settled && !run.error ? "done" : "failed";
+        run.state = (closing || (code === 0 && settled)) && !run.error ? "done" : "failed";
         if (run.state === "failed") run.error ??= `exited ${code}`;
         run.activity = undefined;
         resolveSettled();
         update();
       }
+      drainThenClose(code);
     });
     child.once("close", exited);
 
@@ -585,7 +674,8 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
         return false;
       }
       update();
-      await waiting;
+      // A child that ignores abort must not hang the moderator; it still pauses when it settles.
+      if (!await settlesWithin(waiting, PAUSE_GRACE_MS)) return false;
       return (run.state as DelegateState) === "paused";
     };
     resume = (text) => {
@@ -603,13 +693,7 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
         if (run.state === "working" && !await pause()) return undefined;
         const instruction = "Moderator BTW: answer only this question in one compact paragraph. Preserve your assigned task scope for the next resume. Question: " + question;
         if (!beginPrompt(instruction, wasPaused)) return undefined;
-        let timer: ReturnType<typeof setTimeout> | undefined;
-        const timeout = new Promise<boolean>((resolve) => {
-          timer = setTimeout(() => resolve(false), 2 * 60_000);
-          timer.unref?.();
-        });
-        const answered = await Promise.race([waitSettled().then(() => true), timeout]);
-        clearTimeout(timer);
+        const answered = await settlesWithin(waitSettled(), 2 * 60_000);
         if (!answered) { void pause(); return undefined; }
         return !finished && !run.error ? run.output || undefined : undefined;
       } finally { askBusy = false; }
@@ -623,13 +707,7 @@ export function startDelegate(run: DelegateRun, args: string[], prompt: string,
         const waiting = waitSettled();
         send({ type: "clear_queue" });
         if (send({ type: "abort" })) {
-          let settledInTime = false;
-          const grace = new Promise<void>((resolve) => {
-            const timer = setTimeout(resolve, 3000);
-            timer.unref?.();
-          });
-          await Promise.race([waiting.then(() => { settledInTime = true; }), grace]);
-          if (!settledInTime && !finished) hardStop();
+          if (!await settlesWithin(waiting, 3000) && !finished) hardStop();
         } else hardStop();
       }
       if (child.stdin && !child.stdin.writableEnded) child.stdin.end();
@@ -842,7 +920,10 @@ const Parameters = Type.Object({
     task: Type.String({ description: "Task instruction. scout sees only this task; fork/worktree also inherit the parent's active conversation branch." }),
     name: Type.Optional(Type.String({ description: "Short label, e.g. \"auth scout\"." })),
     role: Type.Optional(Type.String({ description: "pi-jar role override. Defaults by mode: scout→scout, fork→reviewer, worktree→worker; then role fallbacks/current model." })),
-    mode: Type.Optional(DelegateModeSchema)
+    mode: Type.Optional(DelegateModeSchema),
+    tools: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 80 }), { minItems: 1, maxItems: 64, uniqueItems: true,
+      description: "Explicit child tool allowlist. scout/fork remain read-only; worktree accepts only sandbox-aware file tools. Browser/web tools may be enabled when active in the parent." })),
+    inheritTools: Type.Optional(Type.Boolean({ description: "Inherit the parent's currently active tool names, subject to mode safety restrictions. Recursive pi-jar delegation tools are always removed." }))
   }), { minItems: 1, maxItems: 16 }),
   mode: Type.Optional(DelegateModeSchema),
   write: Type.Optional(Type.Boolean({ description: "Deprecated compatibility switch. true keeps the old shared-workspace editing mode; prefer mode=\"worktree\"." }))
@@ -867,9 +948,13 @@ export interface DelegateController {
   list(): SubagentReport[];
   spawnScout(task: string, signal?: AbortSignal): Promise<SubagentReport>;
   resumeScout(id: string, prompt: string, signal?: AbortSignal): Promise<SubagentReport>;
+  /** Retire an agent the orchestration spawned for itself, releasing its pool slot. */
+  stop(id: string): Promise<void>;
 }
 
 export interface DelegateOptions {
+  /** Snapshot names of tools active in the parent session. */
+  getActiveToolNames?: () => readonly string[];
   /** Allowed sizes: 2, 4, 6, 8, 16; defaults to 4. Read on every launch. */
   getMaxSubagents?: () => number;
   /** Shares the delegate lifecycle and capacity with scout orchestration. */
@@ -902,22 +987,24 @@ const controlReport = (report: SubagentStopReport): string => [
   report.last ? `last: ${cleanBlock(report.last, 1200)}` : ""
 ].filter(Boolean).join("\n");
 
+/** Peek is task progress only, read from memory: no git, transcript or report reads. */
 const peekRecord = (record: SubagentRecord): string => {
   const run = record.run;
   const leaves = leafTodos(run.todos);
-  const done = leaves.filter((todo) => todo.status === "completed").length;
-  const changed = (() => { try { return record.changed(); } catch { return run.filesEdited; } })();
-  const remaining = remainingTasks(run);
+  const open = leaves.filter((todo) => todo.status !== "completed");
+  const current = open.find((todo) => todo.status === "in_progress");
+  const next = open.filter((todo) => todo !== current).slice(0, 3).map((todo) => cleanText(todo.title, 80));
+  const more = open.length - (current ? 1 : 0) - next.length;
   return [
-    `${record.key} · ${run.name} · ${run.state} · ${run.role}${run.model ? " · " + run.model : ""} · ${run.mode}`,
-    `task: ${cleanText(run.task, 300)}`,
-    `progress: ${leaves.length ? done + "/" + leaves.length + " tasks" : "no checklist"}${run.activity ? " · " + cleanText(run.activity, 100) : ""}`,
-    `changed: ${changed.length ? fileList(changed, 12) : "none"}`,
-    remaining.length ? `remaining: ${remaining.join("; ")}` : "remaining: none explicitly tracked",
-    run.workspace ? `workspace: ${run.workspace}` : "",
-    run.output ? `last: ${cleanBlock(run.output, 700)}` : ""
+    `${record.key} · ${run.name} · ${run.state}`,
+    `progress: ${leaves.length ? `${leaves.length - open.length}/${leaves.length} tasks` : "no checklist"}`
+      + (current ? ` · now: ${cleanText(current.title, 80)}` : "") + (run.activity ? ` · ${cleanText(run.activity, 60)}` : ""),
+    next.length ? `next: ${next.join("; ")}${more > 0 ? ` (+${more} more)` : ""}` : ""
   ].filter(Boolean).join("\n");
 };
+/** The wake-up after a resumed turn: its progress plus the bounded report the turn produced. */
+const settledRecord = (record: SubagentRecord): string =>
+  peekRecord(record) + (record.run.output ? `\nlast: ${cleanBlock(record.run.output, 1200)}` : "");
 
 /** jar_delegate plus jar_subagent: the parent remains a moderator while retained workers do the work. */
 export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, registry: DelegateRegistry, options: DelegateOptions = {}): void {
@@ -936,25 +1023,23 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     return resolved ? [resolved] : [];
   };
 
-  let moderatorContextDirty = true;
-  registry.subscribe(() => { moderatorContextDirty = true; });
   pi.on?.("before_agent_start", (_event, ctx) => {
     controllerContext = ctx;
-    moderatorContextDirty = true;
     const retained = registry.records().filter((record) => isRetained(record.run.state));
     if (!retained.length) return;
     const fleet = retained.map((record) =>
       `- ${record.key} · ${record.run.name} · ${record.run.state} · ${record.run.role}: ${cleanText(record.run.task, 140)}`).join("\n");
     return { message: { customType: "pi-jar.moderator-context", display: false, content: [
       "[PI-JAR MODERATOR MODE]",
-      "You are the coordinator while retained subagents do delegated work. Decompose and route work, inspect with jar_subagent peek, steer only to correct direction, use ask for terse BTW questions, and use jar_discuss for structured cross-agent Q/A.",
+      "You are the coordinator while retained subagents do delegated work. Decompose and route work, steer only to correct direction, use ask for terse BTW questions, and use jar_discuss for structured cross-agent Q/A.",
+      "Initial/resumed turns and asynchronous ask/pause/stop operations wake you with pi-jar.subagent events. Accepted receipts are not completion: do not poll peek or claim files applied before the final event. Keep responding to user steering or do other work.",
       "Do not duplicate work already owned by a retained subagent. Stop completed workers to obtain their handoff and reconcile worktree changes into /diff. Synthesize the final answer from their reports and evidence.",
       "Retained fleet:",
       fleet
     ].join("\n") } };
   });
+  // Context rewrites apply to one LLM call only, so the stale copies must be pruned on every call.
   pi.on?.("context", (event) => {
-    if (!moderatorContextDirty) return;
     const active = registry.retained() > 0;
     let latest = -1;
     let prune = false;
@@ -963,21 +1048,61 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       if (!active || latest >= 0) prune = true;
       else latest = index;
     }
-    moderatorContextDirty = false;
     if (!prune) return;
     return { messages: event.messages.filter((raw, index) =>
       (raw as { customType?: string }).customType !== "pi-jar.moderator-context" || (active && index === latest)) };
   });
 
+  /** Native RPC drives registry state; Pi's message bus delivers frozen completion events to the moderator. */
+  const eventBusAvailable = typeof pi.sendMessage === "function";
+  const watched = new Map<string, SubagentRecord>();
+  const settledQueue = new Map<string, { record: SubagentRecord; content: string; turn: number }>();
+  const deleteSettled = (key: string) => {
+    for (const [eventKey, event] of settledQueue) if (event.record.key === key) settledQueue.delete(eventKey);
+  };
+  let notifyTimer: NodeJS.Timeout | undefined;
+  const flushSettled = () => {
+    notifyTimer = undefined;
+    const records = [...settledQueue.values()].filter(({ record }) => registry.get(record.key) === record);
+    settledQueue.clear();
+    if (!records.length) return;
+    try {
+      pi.sendMessage?.({
+        customType: SUBAGENT_MESSAGE, display: true, details: {
+          keys: [...new Set(records.map(({ record }) => record.key))],
+          turns: records.map(({ record, turn }) => ({ key: record.key, turn }))
+        },
+        content: ["[PI-JAR SUBAGENT] A subagent turn ended. Review, then resume, ask or stop:", ...records.map(event => event.content)].join("\n\n")
+      }, { triggerTurn: true, deliverAs: "followUp" });
+    } catch (error) { console.error("pi-jar: could not deliver a subagent event", error); }
+  };
+  registry.subscribe(() => {
+    if (!watched.size) return;
+    for (const [key, record] of watched) {
+      if (registry.get(key) !== record) { watched.delete(key); continue; }
+      if (isRunning(record.run.state)) continue;
+      watched.delete(key);
+      if (record.run.state !== "stopped") {
+        // Freeze reports at the settled boundary. A fast resume must not overwrite a queued
+        // initial report, and multiple turns in the coalescing window must each be delivered.
+        settledQueue.set(`${key}:${record.run.resumes}`, { record, turn: record.run.resumes, content: settledRecord(record) });
+      }
+    }
+    if (settledQueue.size && !notifyTimer) {
+      notifyTimer = setTimeout(flushSettled, NOTIFY_COALESCE_MS);
+      notifyTimer.unref?.();
+    }
+  });
+
   const delegateTool: ToolDefinition<typeof Parameters> = {
     name: DELEGATE_TOOL,
     label: "delegate",
-    description: `Spawn retained session-scoped subagents within the configured live pool limit. scout is fresh/read-only and defaults to the scout role; fork inherits the parent conversation read-only and defaults to reviewer; worktree inherits context, defaults to worker, and edits in an isolated Git worktree. Retained agents become idle after a turn and are controlled with jar_subagent. Worktree changes apply only when the moderator stops that agent.`,
-    promptSnippet: "Act as moderator: delegate parallel work, inspect progress with jar_subagent peek, steer only when needed, and synthesize results instead of duplicating subagent work.",
+    description: `Start retained session-scoped subagents within the configured live pool limit and return immediately. scout is fresh/read-only and defaults to the scout role; fork inherits the parent conversation read-only and defaults to reviewer; worktree inherits context, defaults to worker, and edits in an isolated Git worktree. Each task may provide an explicit tools allowlist or inheritTools=true to filter the parent's active tools by mode. Turn completions arrive as pi-jar.subagent event messages; control workers with jar_subagent. Worktree changes apply only when the moderator stops that agent.`,
+    promptSnippet: "Act as moderator: delegate parallel work, then continue responding to the user while subagents run. Their turn completions arrive as pi-jar.subagent event messages; steer, pause or stop them with jar_subagent without polling.",
     promptGuidelines: [
       "When useful work can be delegated, act as the moderator: decompose, assign, monitor, resolve disagreements, and synthesize. Do not redo a delegated implementation yourself while its worker is active.",
-      "Use scout for cheap independent discovery, fork/reviewer for context-aware review, and worktree/worker for implementation. Explicit task.role overrides these mode defaults.",
-      "Retained agents become idle after each turn. Reuse them with jar_subagent resume instead of spawning replacements; pause them when priorities change; stop completed workers to reconcile their worktree into /diff.",
+      "Use scout for cheap independent discovery, fork/reviewer for context-aware review, and worktree/worker for implementation. Explicit task.role overrides these mode defaults. Grant optional task.tools narrowly; task.inheritTools snapshots active parent tools then filters by mode. Scout/fork stay read-only; worktree only accepts path-guarded tools.",
+      "Retained agents become idle after each turn. Initial and resumed turn completions arrive as pi-jar.subagent event messages, so keep responding to user steering while they work; do not poll jar_subagent peek. Reuse them with jar_subagent resume instead of spawning replacements; pause them when priorities change; stop completed workers to reconcile their worktree into /diff.",
       "Use jar_subagent ask for a brief BTW question to one worker. For agent-to-agent questions, have them use the bounded jar_discuss paper so answers stay structured and cheap.",
       "Respect the configured pool limit, including idle and paused agents. Stop agents you no longer need."
     ],
@@ -985,6 +1110,44 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     async execute(_id, params, signal, onUpdate, ctx) {
       controllerContext = ctx;
       const requested = params.tasks;
+      const parentToolNames = (): string[] | undefined => {
+        try {
+          const supplied = options.getActiveToolNames?.();
+          if (supplied) return [...new Set(supplied.filter(name => typeof name === "string" && name.trim()).map(name => name.trim()))];
+          const tools = pi.getActiveTools?.();
+          return tools ? [...new Set(tools.filter(name => typeof name === "string" && name.trim()))] : undefined;
+        } catch { return undefined; }
+      };
+      const activeNames = parentToolNames();
+      const defaultWorktreeTools = WORKTREE_TOOLS.filter(name => name !== "multi_file_edit" || activeNames?.includes(name));
+      for (const [index, item] of requested.entries()) {
+        const mode = item.mode ?? params.mode ?? (params.write === true ? "direct" : "scout");
+        const selected = item.tools ?? (item.inheritTools && activeNames ? activeNames.filter(name =>
+          allowedInMode(mode, name)) : undefined);
+        if ((item.inheritTools || item.tools) && !activeNames) {
+          return { content: [{ type: "text", text: `Task ${index + 1}: this Pi host does not expose active tool names; configurable tools cannot be validated. Use default tools or a host with getActiveTools().` }], details: { runs: [], write: false }, isError: true };
+        }
+        if (item.inheritTools && !selected?.length) {
+          return { content: [{ type: "text", text: `Task ${index + 1}: no active tools remain after applying ${mode} safety filters. Choose explicit safe tools or use the mode defaults.` }], details: { runs: [], write: false }, isError: true };
+        }
+        if (selected) {
+          if (activeNames) {
+            const missing = selected.filter(name => !activeNames.includes(name));
+            if (missing.length) return { content: [{ type: "text", text: `Task ${index + 1}: tools are not currently active in the parent: ${missing.join(", ")}. Enable their extensions/tools first.` }], details: { runs: [], write: false }, isError: true };
+          } else if (item.inheritTools) {
+            return { content: [{ type: "text", text: `Task ${index + 1}: cannot resolve inherited tools from this Pi host.` }], details: { runs: [], write: false }, isError: true };
+          }
+          const recursive = selected.filter(name => RECURSIVE_TOOLS.has(name));
+          if (recursive.length) return { content: [{ type: "text", text: `Task ${index + 1}: recursive delegation tools are never available to subagents: ${recursive.join(", ")}.` }], details: { runs: [], write: false }, isError: true };
+          if ((mode === "scout" || mode === "fork") && selected.some(name => !READ_ONLY_SAFE_TOOLS.has(name))) {
+            return { content: [{ type: "text", text: `Task ${index + 1}: ${mode} is read-only; remove edit/write/shell tools or use mode="worktree" for sandboxed code changes.` }], details: { runs: [], write: false }, isError: true };
+          }
+          if (mode === "worktree") {
+            const unsafe = selected.filter(name => !WORKTREE_SAFE_TOOLS.has(name));
+            if (unsafe.length) return { content: [{ type: "text", text: `Task ${index + 1}: worktree cannot safely use tools outside its path-guarded allowlist: ${unsafe.join(", ")}. Arbitrary extension tools remain disabled unless the worktree boundary validates them.` }], details: { runs: [], write: false }, isError: true };
+          }
+        }
+      }
       const maximum = maxSubagents();
       const releaseReservation = registry.reserve(requested.length, maximum);
       if (!releaseReservation) {
@@ -997,8 +1160,11 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       let available = new Set<string>();
       try { available = new Set(ctx.modelRegistry.getAvailable().map((model) => model.provider + "/" + model.id)); } catch { /* current model remains the fallback */ }
       const thinkingByRun = new Map<number, string | undefined>();
+      const toolsByRun = new Map<number, readonly string[] | undefined>();
       const runs: DelegateRun[] = requested.map((item, index) => {
         const mode: DelegateExecutionMode = item.mode ?? defaultMode;
+        toolsByRun.set(index + 1, item.tools ?? (item.inheritTools && activeNames ? activeNames.filter(name =>
+          allowedInMode(mode, name)) : mode === "worktree" ? defaultWorktreeTools : undefined));
         const role = cleanText(item.role ?? roleForMode(mode), 32) || roleForMode(mode);
         const candidates = [...roleCandidates(role), ...roleCandidates("default")];
         const selected = candidates.find((candidate) => available.has(candidate.provider + "/" + candidate.model));
@@ -1033,13 +1199,18 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         if (baseline !== undefined && tracker.adopt(absolute, baseline)) options.changed?.();
       };
 
+      /** Last footer state per record: child streams fire many updates, the status changes rarely. */
+      const published = new Map<string, string>();
       const publish = () => {
         if (!ctx.hasUI) return;
         for (const { key, run } of records) {
+          const state = run.state === "done" || run.state === "failed" || run.state === "stopped" ? ""
+            : run.state === "queued" || run.state === "paused" ? "waiting" : run.state === "idle" ? "idle" : "working";
+          if (published.get(key) === state) continue;
+          published.set(key, state);
           try {
-            ctx.ui.setStatus(`${ROLE_PREFIX}${key}`, run.state === "done" || run.state === "failed" || run.state === "stopped" ? undefined : JSON.stringify({
-              name: run.name, label: run.name.slice(0, 12),
-              state: run.state === "queued" || run.state === "paused" ? "waiting" : run.state === "idle" ? "idle" : "working",
+            ctx.ui.setStatus(`${ROLE_PREFIX}${key}`, !state ? undefined : JSON.stringify({
+              name: run.name, label: run.name.slice(0, 12), state,
               task: cleanText(run.task, 60), expiresAt: Date.now() + 24 * 60 * 60_000
             }));
           } catch { /* status is decoration */ }
@@ -1074,13 +1245,13 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         firstSettled: Promise.resolve(), closed: Promise.resolve(), steer: () => false, pause: async () => false,
         resume: () => false, ask: async () => undefined, shutdown: async () => {}, alive: () => false
       });
-      const cleanupPrivate = (index: number, discardWorktree: boolean) => {
+      const cleanupPrivate = async (index: number, discardWorktree: boolean) => {
         const dir = sessionDirs.get(index);
-        if (dir) { rmSync(dir, { recursive: true, force: true }); sessionDirs.delete(index); }
+        if (dir) { await rm(dir, { recursive: true, force: true }); sessionDirs.delete(index); }
         if (discardWorktree) {
           const worktree = worktrees.get(index);
           if (worktree) {
-            try { disposeDelegateWorktree(worktree); } catch { /* best effort */ }
+            try { await disposeDelegateWorktree(worktree); } catch { /* best effort */ }
             worktrees.delete(index);
           }
         }
@@ -1093,12 +1264,20 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       };
 
       let discarded = false;
+      const markStartStopped = (run: DelegateRun) => {
+        run.state = "stopped";
+        run.error = undefined;
+        run.endedAt = Date.now();
+        update();
+      };
       handles = runs.map(failedHandle);
+      const started = new Set<number>();
       const readyResolvers: Array<() => void> = [];
       const ready = runs.map(() => new Promise<void>((resolve) => readyResolvers.push(resolve)));
-      const startRuns = () => runs.forEach((run, index) => {
+      const startRuns = async () => Promise.all(runs.map(async (run, index) => {
+        try {
         if (discarded) { run.state = "stopped"; readyResolvers[index]!(); return; }
-        const start = (): DelegateHandle => {
+        const start = async (): Promise<DelegateHandle> => {
         if ((run.mode === "fork" || run.mode === "worktree") && !parentSession) {
           failBeforeStart(run, "fork/worktree mode requires a persisted parent Pi session");
           return failedHandle();
@@ -1109,6 +1288,8 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
           [SUBAGENT_KEY_ENV]: `delegate-${id}-${run.index}`,
           [SUBAGENT_NAME_ENV]: run.name
         };
+        const effectiveTools = toolsByRun.get(run.index) ?? (run.mode === "worktree" ? WORKTREE_TOOLS : run.mode === "direct" ? undefined : READ_ONLY_TOOLS);
+        if (effectiveTools) env[CHILD_TOOLS_ENV] = JSON.stringify(effectiveTools);
         const discussion = options.discussionFile?.();
         if (discussion) env[DISCUSSION_FILE_ENV] = discussion;
         const hooks: DelegateHooks = {};
@@ -1118,7 +1299,9 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
           try {
             const sessionDir = mkdtempSync(join(tmpdir(), "pi-jar-fork-"));
             sessionDirs.set(run.index, sessionDir);
-            fork = { source: parentSession!, sessionDir, ...(run.mode === "worktree" ? { tools: WORKTREE_TOOLS } : {}) };
+            const requestedTools = toolsByRun.get(run.index);
+            fork = { source: parentSession!, sessionDir,
+              ...((run.mode === "worktree" || run.mode === "fork") ? { tools: requestedTools ?? (run.mode === "worktree" ? WORKTREE_TOOLS : READ_ONLY_TOOLS) } : {}) };
           } catch (error) {
             failBeforeStart(run, error);
             return failedHandle();
@@ -1126,14 +1309,15 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         }
         if (run.mode === "worktree") {
           try {
-            const worktree = createDelegateWorktree(ctx.cwd);
+            const worktree = await createDelegateWorktree(ctx.cwd, controllers[index]!.signal);
             worktrees.set(run.index, worktree);
             run.workspace = worktree.root;
             cwd = worktree.cwd;
             env[CHILD_WORKTREE_ENV] = worktree.root;
           } catch (error) {
-            cleanupPrivate(run.index, true);
-            failBeforeStart(run, error);
+            await cleanupPrivate(run.index, true);
+            if (discarded || stopRequested.has(index)) markStartStopped(run);
+            else failBeforeStart(run, error);
             return failedHandle();
           }
         } else if (run.mode === "direct" && baselines) {
@@ -1141,20 +1325,36 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
           hooks.edited = edited;
         }
         hooks.env = env;
-        return startDelegate(run, delegateArgs(run.model, thinkingByRun.get(run.index), write, process.argv, fork),
+        return startDelegate(run, delegateArgs(run.model, thinkingByRun.get(run.index), write, process.argv, fork,
+          run.mode === "scout" ? toolsByRun.get(run.index) : undefined),
           delegatePrompt(run.task, write, run.mode), cwd, controllers[index]!.signal, update, options.spawnProcess, hooks, run.mode !== "direct");
         };
         let handle: DelegateHandle;
-        try { handle = start(); }
-        catch (error) { failBeforeStart(run, error); handle = failedHandle(); }
+        try { handle = await start(); }
+        catch (error) {
+          if (discarded || stopRequested.has(index)) markStartStopped(run);
+          else failBeforeStart(run, error);
+          handle = failedHandle();
+        }
         handles[index] = handle;
+        started.add(index);
         readyResolvers[index]!();
-        void handle.closed.then(() => {
-          cleanupPrivate(run.index, discarded || run.mode !== "worktree");
+        void handle.closed.then(async () => {
+          await cleanupPrivate(run.index, discarded || run.mode !== "worktree");
+          update();
+        }).catch((error) => {
+          run.error ??= "subagent cleanup failed: " + cleanText(error instanceof Error ? error.message : String(error), 240);
           update();
         });
-        if (discarded) void handle.shutdown().finally(() => cleanupPrivate(run.index, true));
-      });
+        if (discarded) void handle.shutdown().finally(() => cleanupPrivate(run.index, true))
+          .catch(error => console.error("pi-jar: subagent cleanup failed", error));
+        } catch (error) {
+          failBeforeStart(run, error);
+        } finally {
+          // Even a filesystem cleanup or decoration failure must release lifecycle waiters.
+          readyResolvers[index]!();
+        }
+      }));
 
       const stopping = new Map<number, Promise<SubagentStopReport>>();
       const stopRequested = new Set<number>();
@@ -1162,10 +1362,13 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         const existing = stopping.get(index);
         if (existing) return existing;
         stopRequested.add(index);
+        // Cancel asynchronous worktree setup as well as an already-running child before waiting
+        // for ready; otherwise stop can queue behind a stalled startup operation.
+        if (!started.has(index)) controllers[index]!.abort(STOP_REASON);
         const promise = finalizeRun(index);
         stopping.set(index, promise);
         // A reconciliation conflict is retryable after the parent drift is resolved.
-        void promise.then(() => { if (worktrees.has(runs[index]!.index)) stopping.delete(index); });
+        void promise.then(() => { if (worktrees.has(runs[index]!.index)) stopping.delete(index); }, () => { stopping.delete(index); });
         return promise;
       };
       const finalizeRun = async (index: number): Promise<SubagentStopReport> => {
@@ -1180,15 +1383,15 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         let changed: string[] = [];
         const worktree = worktrees.get(run.index);
         if (worktree && !discarded) {
-          try { changed = worktreeChangedFiles(worktree); run.filesEdited = changed; }
+          try { changed = await worktreeChangedFiles(worktree, controllers[index]!.signal); run.filesEdited = changed; }
           catch (error) { run.error = "could not inspect isolated changes: " + cleanText(String(error), 240); }
           if (changed.length && !run.error) {
             try {
-              run.appliedFiles = applyDelegateWorktree(worktree, ctx.cwd, changed, options.changes?.());
+              run.appliedFiles = await applyDelegateWorktree(worktree, ctx.cwd, changed, options.changes?.(), controllers[index]!.signal);
               if (run.appliedFiles.length) {
                 try { options.changed?.(); } catch (error) { console.error("pi-jar: could not refresh parent change UI", error); }
               }
-              disposeDelegateWorktree(worktree);
+              await disposeDelegateWorktree(worktree);
               worktrees.delete(run.index);
               run.workspace = undefined;
             } catch (error) {
@@ -1196,12 +1399,13 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
               run.error = "changes not applied: " + cleanText(error instanceof Error ? error.message : String(error), 240);
             }
           } else if (!changed.length) {
-            try { disposeDelegateWorktree(worktree); } catch { /* best effort */ }
+            try { await disposeDelegateWorktree(worktree); } catch { /* best effort */ }
             worktrees.delete(run.index);
             run.workspace = undefined;
           }
         }
-        cleanupPrivate(run.index, false);
+        await cleanupPrivate(run.index, discarded);
+        if (discarded) { run.error = undefined; run.workspace = undefined; }
         run.state = run.error ? "failed" : "stopped";
         run.endedAt ??= Date.now();
         update();
@@ -1214,39 +1418,61 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       records = runs.map((run, index) => ({
         key: `delegate-${id}-${run.index}`, batch: id, run,
         stop: () => stopRun(index),
-        pause: () => discarded || stopRequested.has(index) ? Promise.resolve(false) : handles[index]!.pause(),
+        pause: async () => {
+          await ready[index];
+          return discarded || stopRequested.has(index) ? false : handles[index]!.pause();
+        },
         resume: (text) => !discarded && !stopRequested.has(index) && handles[index]!.resume(text),
         steer: (text) => !discarded && !stopRequested.has(index) && handles[index]!.steer(text),
-        ask: (text) => discarded || stopRequested.has(index) ? Promise.resolve(undefined) : handles[index]!.ask(text),
+        ask: async (text) => {
+          await ready[index];
+          return discarded || stopRequested.has(index) ? undefined : handles[index]!.ask(text);
+        },
         alive: () => handles[index]!.alive(),
         closed: () => ready[index]!.then(() => handles[index]!.closed),
         changed: () => {
           const worktree = worktrees.get(run.index);
           if (!worktree) return [...run.filesEdited];
-          try { return worktreeChangedFiles(worktree); } catch { return [...run.filesEdited]; }
+          return [...run.filesEdited]; // synchronous activity snapshots never launch subprocesses
         },
         discard: () => {
           discarded = true;
           // Cancellation is synchronous: a concurrent stop must never apply discarded edits.
           controllers[index]!.abort(STOP_REASON);
-          void ready[index]!.then(() => handles[index]!.shutdown()).finally(() => cleanupPrivate(run.index, true));
+          void ready[index]!.then(() => handles[index]!.shutdown()).finally(() => cleanupPrivate(run.index, true))
+            .catch(error => console.error("pi-jar: subagent discard failed", error));
         }
       }));
+      // Initial turns are event-driven too: the retained launch returns immediately so the
+      // moderator can act on user messages instead of remaining trapped in this tool call.
+      // The Pi RPC stream continues independently and the registry wakes the moderator on settle.
+      if (eventBusAvailable) for (const record of records) watched.set(record.key, record);
       // Transfer the reservation into queued records before notifying reentrant listeners.
       releaseReservation();
       registry.add(...records);
-      startRuns();
+      const startup = startRuns();
+      if (eventBusAvailable) {
+        void startup.then(async () => {
+          // Legacy direct writers also run off the main tool path. Remove their shared baseline
+          // directory only after all direct streams drained and their edit events were adopted.
+          await Promise.all(handles.map((handle, index) => runs[index]!.mode === "direct" ? handle.closed : Promise.resolve()));
+          if (baselines) await rm(baselines, { recursive: true, force: true });
+        }).catch((error) => console.error("pi-jar: subagent startup/cleanup failed", error));
+        signal?.removeEventListener("abort", abortAll);
+        publish();
+        toolReturned = true;
+        return { content: [{ type: "text", text: runs.map((run) => runReport(run)).join("\n\n") + "\n\nSubagent launch is asynchronous; turn reports arrive as pi-jar.subagent events. You can continue working or steer the fleet with jar_subagent." }], details: details() };
+      }
+      await startup;
       publish();
 
       try {
         await Promise.all(handles.map((handle, index) => runs[index]!.mode === "direct" ? handle.closed : handle.firstSettled));
       } finally {
         signal?.removeEventListener("abort", abortAll);
-        if (baselines) rmSync(baselines, { recursive: true, force: true });
-        for (const run of runs) {
-          if (run.mode === "direct") cleanupPrivate(run.index, true);
-          else if (run.state === "failed") cleanupPrivate(run.index, false);
-        }
+        if (baselines) await rm(baselines, { recursive: true, force: true });
+        await Promise.all(runs.map(run => run.mode === "direct" || run.state === "failed"
+          ? cleanupPrivate(run.index, run.mode === "direct") : Promise.resolve()));
         registry.notify();
         flushUpdate();
         toolReturned = true;
@@ -1285,6 +1511,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
   });
   options.onController?.({
     list: () => registry.records().map(snapshot),
+    async stop(id) { await registry.stop(id); },
     async spawnScout(task, signal) {
       if (!controllerContext) throw new Error("Delegate controller has no active session context");
       if (signal?.aborted) throw new Error("Scout launch aborted");
@@ -1293,7 +1520,25 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       if (!launched) throw new Error(result.content.map((part) => "text" in part ? part.text : "").join("\n"));
       const record = registry.get(`delegate-${launched}-1`);
       if (!record) throw new Error("Scout session was discarded");
-      if (record.run.error || record.run.state !== "idle") throw new Error(record.run.error ?? "Scout failed to settle");
+      // This launch is an internal democracy vote; its caller is already awaiting the result,
+      // so the moderator does not need a duplicate unsolicited completion notification.
+      watched.delete(record.key);
+      deleteSettled(record.key);
+      await new Promise<void>((resolve, reject) => {
+        let unsubscribe = () => {};
+        const cleanup = () => { unsubscribe(); signal?.removeEventListener("abort", abort); };
+        const check = () => {
+          if (registry.get(record.key) !== record) { cleanup(); reject(new Error("Scout session was discarded")); return; }
+          if (isRunning(record.run.state)) return;
+          cleanup();
+          if (record.run.error || record.run.state !== "idle") reject(new Error(record.run.error ?? "Scout failed to settle"));
+          else resolve();
+        };
+        const abort = () => { cleanup(); void registry.stop(record.key); reject(new Error("Scout launch aborted")); };
+        unsubscribe = registry.subscribe(check);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) abort(); else check();
+      });
       return snapshot(record);
     },
     async resumeScout(id, prompt, signal) {
@@ -1321,14 +1566,28 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
     }
   });
 
+  let operationSequence = 0;
+  const pendingControls = new Map<string, { id: string; action: string; message?: string }>();
+  const deliverControl = (record: SubagentRecord, operation: { id: string; action: string }, result: { content: Array<{ text: string }>; details?: unknown; isError?: boolean }) => {
+    // A session switch discards the old fleet. Never wake a new session with stale handoffs.
+    if (registry.get(record.key) !== record) return;
+    try {
+      pi.sendMessage({
+        customType: SUBAGENT_MESSAGE, display: true,
+        details: { operationId: operation.id, action: operation.action, key: record.key, status: result.isError ? "failed" : "completed", report: result.details },
+        content: `[PI-JAR SUBAGENT] ${operation.action} ${operation.id} completed:\n${result.content.map(part => part.text).join("\n")}`
+      }, { triggerTurn: true, deliverAs: "followUp" });
+    } catch (error) { console.error("pi-jar: could not deliver a control event", error); }
+  };
+
   pi.registerTool({
     name: "jar_subagent",
     label: "subagent",
-    description: "Moderator control for retained subagents: peek high-level progress, steer a working agent, ask a brief BTW question, pause without losing context, resume the same agent, or stop it and receive a progress/change/remaining-work handoff. Stopping a worktree agent safely applies reviewable changes to the parent.",
+    description: "Non-blocking moderator control for retained subagents. peek, steer and resume return immediately. ask, pause and stop return an accepted operation receipt; the final answer or handoff arrives as a pi-jar.subagent event. Stop completion safely reconciles worktree changes; acceptance does not mean changes are applied yet.",
     promptSnippet: "Use jar_subagent as the moderator control plane. Prefer peek over rereading transcripts; reuse paused/idle agents with resume; stop finished workers to reconcile their work.",
     promptGuidelines: [
-      "Use peek periodically instead of polling constantly. It returns task progress, current activity, changed files, remaining checklist items and last report.",
-      "Use steer to correct direction while an agent is working. Use ask for a short BTW question; it waits for the agent's next compact answer.",
+      "peek returns only task progress. Do not poll: initial/resumed turns and control completions send pi-jar.subagent events. Stop returns an accepted receipt first, then changed files and the full handoff in its completion event.",
+      "Use steer for active direction and ask for a brief BTW question. ask, pause and stop do not wait on the child; continue responding to the user until their completion event arrives.",
       "Pause when an agent should stop spending tokens but keep its context/workspace. Resume the same agent later instead of spawning a replacement.",
       "Stop when an agent is no longer needed. Stop aborts any active turn, retires the process, reports progress/workspace/changes/remaining work, and reconciles safe worktree changes into /diff."
     ],
@@ -1340,8 +1599,9 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       agent: Type.Optional(Type.String({ description: "Subagent key or unique name. Omit only for peek to show all retained agents." })),
       message: Type.Optional(Type.String({ description: "Direction, BTW question, or resume instruction." }))
     }),
-    async execute(_id, params) {
-      const result = await (async () => {
+    async execute(_id, params, signal) {
+      if (signal?.aborted) return { content: [{ type: "text" as const, text: "Cancelled before accepting the operation." }], details: undefined, isError: true };
+      const work = (async () => {
       if (params.action === "peek") {
         const targets = params.agent ? [registry.resolve(params.agent)].filter((item): item is SubagentRecord => !!item)
           : registry.records().filter((record) => isRetained(record.run.state));
@@ -1351,30 +1611,69 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       const agent = params.agent ?? "";
       const record = registry.resolve(agent);
       if (!record) return { content: [{ type: "text", text: "Subagent not found or name is ambiguous: " + agent }], isError: true };
+      const stopping = pendingControls.get(record.key + ":stop");
+      const controlling = pendingControls.get(record.key + ":control");
+      if (stopping || (controlling && params.action !== "stop")) {
+        const pending = stopping ?? controlling!;
+        if (pending.action === params.action && pending.message === params.message) {
+          return { content: [{ type: "text", text: `${pending.action} already accepted (${pending.id}); completion will arrive as an event.` }], details: { operationId: pending.id, status: "accepted", action: pending.action, key: record.key } };
+        }
+        return { content: [{ type: "text", text: `${record.run.name} has pending ${pending.action} (${pending.id}). Stop may preempt other controls; otherwise wait for its event.` }], isError: true };
+      }
       if (params.action === "steer") {
         const message = cleanBlock(params.message ?? "", MAX_STEER_CHARS);
         if (!message) return { content: [{ type: "text", text: "steer requires message." }], isError: true };
         return { content: [{ type: "text", text: registry.steer(record.key, message) ? "Steered " + record.run.name + "." : "Subagent is not currently working; use resume instead." }] };
       }
+      // The moderator is handling this agent directly now; its settle no longer needs a wake-up.
+      if (params.action !== "resume") watched.delete(record.key);
+      const controlWork = async () => {
       if (params.action === "ask") {
         const message = cleanBlock(params.message ?? "", MAX_STEER_CHARS);
         if (!message) return { content: [{ type: "text", text: "ask requires message." }], isError: true };
         const answer = await registry.ask(record.key, message);
-        return { content: [{ type: "text", text: answer ? record.run.name + ": " + cleanBlock(answer, 2000) : "No answer arrived before the BTW timeout." }] };
+        return { content: [{ type: "text", text: answer ? record.run.name + ": " + cleanBlock(answer, 2000) : "No answer arrived before the BTW timeout or the worker stopped." }], isError: !answer };
       }
       if (params.action === "pause") {
         const paused = await registry.pause(record.key);
-        return { content: [{ type: "text", text: paused ? "Paused " + record.run.name + "; context and workspace are retained." : "Could not pause " + record.run.name + "." }] };
+        if (!paused && isRunning(record.run.state) && !pendingControls.has(record.key + ":stop")) watched.set(record.key, record);
+        const text = paused ? "Paused " + record.run.name + "; context and workspace are retained."
+          : record.run.state === "working" ? record.run.name + " has not settled yet; it pauses when its current turn ends."
+          : "Could not pause " + record.run.name + ".";
+        return { content: [{ type: "text", text }], isError: !paused };
       }
       if (params.action === "resume") {
         const resumed = registry.resume(record.key, params.message);
-        return { content: [{ type: "text", text: resumed ? "Resumed " + record.run.name + "." : record.run.name + " is not idle or paused." }] };
+        if (resumed) watched.set(record.key, record);
+        return { content: [{ type: "text", text: resumed ? "Resumed " + record.run.name + ". You will be woken when its turn ends; do not poll peek." : record.run.name + " is not idle or paused." }] };
       }
       const report = await registry.stop(record.key);
       if (!report) return { content: [{ type: "text", text: "Subagent is already retired: " + record.run.name }] };
-      return { content: [{ type: "text", text: controlReport(report) }], details: report };
+      return { content: [{ type: "text", text: controlReport(report) }], details: report, isError: !!report.error };
+      };
+      // Internal registry APIs remain awaited for shutdown/reconciliation correctness. Only the
+      // external tool boundary is detached, so parent steering never waits on a child turn or Git.
+      if (eventBusAvailable && params.action !== "resume") {
+        if (params.action === "ask" && !params.message?.trim()) return { content: [{ type: "text", text: "ask requires message." }], isError: true };
+        const operation = { id: `subagent-op-${++operationSequence}`, action: params.action, message: params.message };
+        const pendingKey = record.key + (params.action === "stop" ? ":stop" : ":control");
+        pendingControls.set(pendingKey, operation);
+        deleteSettled(record.key);
+        void Promise.resolve().then(controlWork).then(result => {
+          if (pendingControls.get(pendingKey) === operation) pendingControls.delete(pendingKey);
+          deliverControl(record, operation, result);
+        }, error => {
+          if (pendingControls.get(pendingKey) === operation) pendingControls.delete(pendingKey);
+          deliverControl(record, operation, { content: [{ text: error instanceof Error ? error.message : String(error) }], isError: true });
+        });
+        return { content: [{ type: "text", text: `${params.action} accepted for ${record.run.name} (${operation.id}). Completion and any reconciled changes will arrive as an event; keep responding to the user, do not poll.` }], details: { operationId: operation.id, status: "accepted", action: params.action, key: record.key } };
+      }
+      return controlWork();
       })();
-      return { ...result, content: result.content.map((part) => ({ ...part, type: "text" as const })), details: result.details };
+      // Pi waits on a tool until it resolves, so Esc must never be stuck behind a child that ignores abort.
+      const result = await untilAborted(work, signal)
+        ?? { content: [{ type: "text", text: "Cancelled; the subagent keeps its state. Check it with peek." }], isError: true };
+      return { ...result, content: result.content.map((part) => ({ ...part, type: "text" as const })), details: "details" in result ? result.details : undefined };
     }
   });
 }