killeros 1.4.6 → 1.4.8

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to KillerOS are documented here.
 
+## [1.4.8] - 2026-08-02
+
+### Changed
+
+- Parallel batches with write-capable roles now run through a shared pool by default; `writerConcurrency` caps the entire batch and setting it to `1` serializes the writer-containing batch. Reader-only batches reject `writerConcurrency` because it does not apply.
+
+## [1.4.7] - 2026-08-01
+
+### Fixed
+
+- Serialized every write-capable task in a parallel batch in input order instead of rejecting batches with multiple writers.
+- Added opt-in `writerConcurrency` scheduling for independent batches while keeping serialization as the safe default and documenting shared-worktree conflict responsibility.
+- Parent tool-call aborts now settle only queued tasks; active children finish naturally, and session directories remain until child exit is confirmed.
+- Settled queued tasks on interrupted parallel batches and documented the shared-worktree execution model.
+- Restricted the `message` parameter to `action: "steer"` and added focused regression coverage.
+
 ## [1.4.6] - 2026-08-01
 
 ### Fixed

package/README.md

@@ -33,7 +33,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.6
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v1.4.8
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -97,13 +97,13 @@ KillerOS ships `planner`, `reviewer`, `scout`, and `security` as read-only roles
 
 The default `agentScope: "user"` uses bundled and personal roles. Use `"project"` or `"both"` to opt into trusted project roles; a selected project override requires interactive confirmation. Role frontmatter requires `name`, `description`, `access`, and an explicit `tools` list. Optional fields are `model`, `thinking`, and `timeoutMs`. Every bundled role shows `model: inherit` and `thinking: inherit` as editable placeholders. Replace them with an available `provider/model` and a separate thinking level when you want to pin a role; `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` are checked against that model’s supported capabilities.
 
-The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model. For example:
+The tool supports a single `agent` + `task`, parallel `tasks`, or a sequential `chain` whose task text may include `{previous}`. Read-only-only batches run concurrently, up to four at a time. Batches with write-capable roles use one shared pool by default, up to ten tasks at once; set `writerConcurrency` to choose a smaller cap, or set it to `1` to serialize the entire batch. Reader-only batches reject `writerConcurrency` because it does not apply. All children share the parent worktree, so concurrent writers must avoid file conflicts. A call can also set `model` and `thinking` for every task, overriding role settings; use `inherit` to fall back to each role and then the active parent model. The `message` field is only valid with `action: "steer"`. For example:
 
 ```json
 {"agent":"reviewer","task":"Review the change","model":"provider/model","thinking":"high"}
 ```
 
-Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output execution quota. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks and four parallel readers and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. Esc cancellation terminates active children and escalates after five seconds.
+Use the separate `model` and `thinking` fields for new configuration. The older `provider/model:thinking` model form remains accepted. Children run as isolated `pi --mode json -p` processes with a private `--session-dir` and `--session-id`, plus explicit local tools and `web_search`, `source_check`, `fetch_content`, and `get_search_content`. Steering restarts the same child session, so the child keeps its prior conversation. Each child explicitly loads `npm:pi-web-access`, discovers available skills, and keeps arbitrary extensions and prompt templates disabled; project-local skills load only when the parent project is trusted. Every bundled role is instructed to load the most relevant `SKILL.md` and report useful evidence. Children have no default token, dollar, turn, tool-call, research, wall-time, JSONL-line, trace, stderr, or returned-output execution quota. KillerOS bounds retained trace, stderr, and returned text and spills a large JSONL line to temporary storage; retention never stops a child or marks it `limited`. The parent limits each request to ten tasks, read-only-only batches to four concurrent readers, and bounds role files, task input, and combined parent output. An embedding caller may opt into named child resource guards. A parent tool-call abort cancels queued tasks but lets already-running children finish; explicit `interrupt` actions and session shutdown terminate active children and escalate after five seconds.
 
 ### Thread lifecycle
 
@@ -113,7 +113,7 @@ Threads move through `queued`, `active`, `done`, `failed`, `stopped`, and `close
 
 The parent can inspect a thread’s prompt, role, model, tools, trace, usage, and handoff; steer an active thread with one bounded follow-up; interrupt one child or all active children; collect a concise handoff into parent context; and close a finished or stopped thread. An interrupt preserves the partial trace, states the reason, and reports the handoff as partial rather than successful.
 
-A child completes naturally when it returns a final answer. The default path has no per-child execution quota. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Explicit user interruptions and real child-process failures remain visible. Esc cancellation terminates active children and escalates after five seconds.
+A child completes naturally when it returns a final answer. The default path has no per-child execution quota. Explicit embedding options can add wall-time, output, trace, stderr, JSONL, token, or cost guards; those guards report their cause and return partial work clearly. The parent still bounds task count, reader concurrency, role files, task input, and combined parent output. Parent tool-call aborts leave active children running while queued work is settled as cancelled; explicit `interrupt` actions and real child-process failures remain visible. Session shutdown still terminates active children and escalates after five seconds.
 
 The replacement lifecycle has nine phases:
 
@@ -163,7 +163,7 @@ The package manifest lists Pi’s built-in modules as peer dependencies, so npm
 
 The [`pi-package`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) keyword makes a published npm release visible in Pi’s package catalog.
 
-For release `1.4.6`, publish after the validation checks pass:
+For release `1.4.8`, publish after the validation checks pass:
 
 ```bash
 npm login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "1.4.6",
+  "version": "1.4.8",
   "description": "A production-hardened TUI and workflow extension for the Pi coding agent.",
   "type": "module",
   "keywords": [

package/subagent-process.ts

@@ -96,6 +96,10 @@ export interface SubagentProcessRetention {
 
 export interface SubagentProcessHandle {
   readonly pid: number | undefined;
+  /** True after the child close event, or when no child was spawned. */
+  readonly hasExited: boolean;
+  /** Resolves after the child close event, or when no child was spawned. */
+  readonly exited: Promise<void>;
   readonly result: Promise<SubagentProcessResult>;
   /** Stop this child and retain any work received before it exits. */
   stop(reason?: string): void;
@@ -324,6 +328,7 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
     durationMs: 0,
   };
   let child: SubagentProcessChild | undefined;
+  let processExited = false;
   let closed = false;
   let finishing = false;
   let requestedStatus: Exclude<SubagentProcessStatus, "running" | "complete"> | undefined;
@@ -338,7 +343,14 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   let settleTimer: NodeJS.Timeout | undefined;
   let timeoutTimer: NodeJS.Timeout | undefined;
   let resolveResult!: (result: SubagentProcessResult) => void;
+  let resolveExited!: () => void;
   const result = new Promise<SubagentProcessResult>((resolve) => { resolveResult = resolve; });
+  const exited = new Promise<void>((resolve) => { resolveExited = resolve; });
+  const markExited = (): void => {
+    if (processExited) return;
+    processExited = true;
+    resolveExited();
+  };
 
   const clearStdoutLine = (): void => {
     if (stdoutLineSpoolDescriptor !== undefined) {
@@ -385,6 +397,7 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
   const finish = (code: number | null): void => {
     if (closed || finishing) return;
     finishing = true;
+    if (!child || processExited) markExited();
     if (stdoutLineBytes && !requestedStatus) processLine(readStdoutLine());
     else clearStdoutLine();
     closed = true;
@@ -559,7 +572,10 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
         }
       });
       child.on("error", (error) => requestTermination("failed", "spawn_error", error.message));
-      child.once("close", finish);
+      child.once("close", (code) => {
+        markExited();
+        finish(code);
+      });
       if (limits.wallTimeMs !== undefined) timeoutTimer = setTimeout(() => requestTermination("limited", "wall_time_limit"), limits.wallTimeMs);
       options.signal?.addEventListener("abort", abortHandler, { once: true });
       if (options.signal?.aborted) abortHandler();
@@ -570,6 +586,8 @@ export function runSubagentProcess(options: SubagentProcessOptions): SubagentPro
 
   return {
     get pid() { return child?.pid; },
+    get hasExited() { return processExited; },
+    exited,
     result,
     stop(reason = "stopped") { requestTermination("cancelled", reason); },
     snapshot: () => cloneResult(state),

package/subagents.ts

@@ -113,6 +113,7 @@ export interface SubagentDetails {
   mode: "single" | "parallel" | "chain";
   agentScope: AgentScope;
   projectAgentsDir: string | null;
+  executionNote?: string;
   results: SubagentTaskResult[];
   aggregateUsage: SubagentUsage;
   parentId?: string;
@@ -712,7 +713,23 @@ async function mapReadTasks<T>(items: T[], concurrency: number, run: (item: T, i
   await Promise.all(workers);
 }
 
-function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "taskCharacters">) {
+function waitForConfirmedProcessExit(handle: SubagentProcessHandle, timeoutMs = 1_000): Promise<boolean> {
+  if (handle.hasExited) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    let settled = false;
+    let timeout: NodeJS.Timeout | undefined;
+    const finish = (exited: boolean): void => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve(exited);
+    };
+    timeout = setTimeout(() => finish(handle.hasExited), timeoutMs);
+    void handle.exited.then(() => finish(true));
+  });
+}
+
+function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "maxReadConcurrency" | "taskCharacters">) {
   const taskSchema = Type.Object({
     agent: Type.String({ minLength: 1, maxLength: 64, description: "Agent role name" }),
     task: Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Bounded task for the role" }),
@@ -727,11 +744,12 @@ function createSubagentParams(limits: Pick<SubagentLimits, "maxTasks" | "taskCha
       description: "Thread lifecycle action",
     })),
     threadId: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Stable child thread ID" })),
-    message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Bounded steering message" })),
+    message: Type.Optional(Type.String({ minLength: 1, maxLength: 4_000, description: "Bounded steering message; only valid with action steer" })),
     all: Type.Optional(Type.Boolean({ description: "Interrupt every active child thread" })),
     agent: Type.Optional(Type.String({ minLength: 1, maxLength: 64, description: "Agent role for single mode" })),
     task: Type.Optional(Type.String({ minLength: 1, maxLength: limits.taskCharacters, description: "Task for single mode" })),
-    tasks: Type.Optional(Type.Array(taskSchema, { minItems: 1, maxItems: limits.maxTasks, description: "Parallel role tasks" })),
+    tasks: Type.Optional(Type.Array(taskSchema, { minItems: 1, maxItems: limits.maxTasks, description: `Parallel role tasks: read-only batches run concurrently up to ${limits.maxReadConcurrency}; batches with writers use a shared pool by default up to ${limits.maxTasks}. Set writerConcurrency to cap that pool, or set it to 1 to serialize the entire writer-containing batch; concurrent writers share the parent worktree, so callers must avoid file conflicts` })),
+    writerConcurrency: Type.Optional(Type.Integer({ minimum: 1, maximum: limits.maxTasks, description: `Optional shared-pool cap for parallel tasks that include writers. Defaults to ${limits.maxTasks}; set 1 to serialize the entire writer-containing batch. Concurrent writers share the parent worktree, so callers must avoid file conflicts` })),
     chain: Type.Optional(Type.Array(chainTaskSchema, { minItems: 1, maxItems: limits.maxTasks, description: "Sequential role tasks; {previous} inserts the prior result" })),
     model: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Model for every task as provider/model; inherit uses each role setting or the active parent" })),
     thinking: Type.Optional(Type.String({ minLength: 1, maxLength: 16, description: "Thinking effort for every task: off, minimal, low, medium, high, xhigh, max, or inherit" })),
@@ -804,6 +822,7 @@ function statusIcon(status: SubagentStatus): string {
 interface ActiveThreadRuntime {
   controller: AbortController;
   handle?: SubagentProcessHandle;
+  handles: Set<SubagentProcessHandle>;
   steering: string[];
   restarting: boolean;
   traceCount: number;
@@ -1029,11 +1048,11 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
   pi.registerTool({
     name: "subagent",
     label: "Subagents",
-    description: "Spawn and manage named child threads. Children finish naturally; explicit execution guards, task count, and concurrency are the hard edges. Retention only bounds stored detail. Use action list, inspect, steer, interrupt, collect, and close to manage active and completed handoffs.",
+    description: `Spawn and manage named child threads. Children finish naturally. Parallel tasks with write-capable roles use one shared pool by default, up to ${limits.maxTasks}; read-only batches run concurrently up to ${limits.maxReadConcurrency}. Set writerConcurrency to cap the shared pool, or set it to 1 to serialize the entire writer-containing batch. Concurrent writers share the parent worktree, so callers must avoid file conflicts. The message parameter is only valid with action steer. Use action list, inspect, steer, interrupt, collect, and close to manage active and completed handoffs.`,
     promptSnippet: "Delegate bounded specialist work to isolated KillerOS subagents",
     promptGuidelines: [
       "Use subagent for clearly separable specialist work; prefer read-only scout, planner, reviewer, or security roles before a writer.",
-      "Do not request multiple write-capable subagents in one parallel batch.",
+      `Parallel tasks with write-capable roles use one shared pool by default because all children share the parent worktree. Set writerConcurrency to cap the pool, or set it to 1 to serialize the entire writer-containing batch; callers remain responsible for file conflicts.`,
       "Every child can load relevant skills with read and can use web_search, source_check, fetch_content, and get_search_content for external research.",
       "When the user names a model or thinking effort, pass model and thinking separately; use inherit when the active parent or role setting should decide.",
       "Keep completed and stopped threads inspectable until the parent explicitly closes them.",
@@ -1043,6 +1062,9 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const action = params.action ?? "spawn";
+      if (params.message !== undefined && action !== "steer") {
+        throw new Error("message is only valid with action steer");
+      }
       const parentId = parentThreadId(ctx);
       const actionDetails = (selectedThreadId?: string): SubagentDetails => detailsFor(parentId, "single", params.agentScope ?? "user", null, selectedThreadId);
       const actionResult = (text: string, selectedThreadId?: string) => {
@@ -1130,6 +1152,12 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         || hasChain && params.chain!.length === 0) {
         throw new Error("Provide exactly one subagent mode: agent + task, tasks, or chain");
       }
+      if (params.writerConcurrency !== undefined) {
+        if (!hasParallel) throw new Error("writerConcurrency is only valid with parallel tasks");
+        if (!Number.isSafeInteger(params.writerConcurrency) || params.writerConcurrency < 1 || params.writerConcurrency > limits.maxTasks) {
+          throw new Error(`writerConcurrency must be a positive integer no greater than ${limits.maxTasks}`);
+        }
+      }
 
       const discovery = discoverAgentRoles(ctx.cwd, scope, ctx.isProjectTrusted(), options);
       const roles = new Map(discovery.agents.map((agent) => [agent.name, agent]));
@@ -1161,10 +1189,22 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         ? [{ agent: params.agent!, task: params.task! }]
         : hasParallel ? params.tasks! : params.chain!;
       if (inputs.length > limits.maxTasks) throw new Error(`At most ${limits.maxTasks} subagent tasks are allowed`);
-      if (hasParallel) {
-        const writers = inputs.filter((input) => roles.get(input.agent)!.access === "write");
-        if (writers.length > 1) throw new Error("Parallel batches may contain at most one write-capable subagent; writers are serialized");
+      const readIndexes = hasParallel
+        ? inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "read")
+        : [];
+      const writerIndexes = hasParallel
+        ? inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "write").map(({ index }) => index)
+        : [];
+      if (params.writerConcurrency !== undefined && hasParallel && writerIndexes.length === 0) {
+        throw new Error("writerConcurrency requires at least one write-capable role");
       }
+      const writerConcurrency = params.writerConcurrency ?? limits.maxTasks;
+      const useSharedParallelPool = hasParallel && writerIndexes.length > 0;
+      const executionNote = hasParallel
+        ? writerIndexes.length
+          ? `Parallel schedule: all tasks run through a shared pool of up to ${writerConcurrency}${params.writerConcurrency === undefined ? " (default)" : ""}; concurrent write-capable tasks share the parent worktree, so callers must avoid file conflicts.`
+          : `Parallel schedule: read-only tasks run concurrently up to ${limits.maxReadConcurrency}.`
+        : undefined;
 
       const inFlight = threads.listAll().filter((thread) => ["queued", "active"].includes(thread.state)).length;
       if (inFlight + inputs.length > limits.maxTasks) {
@@ -1187,7 +1227,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
         const currentResults = results.map(cloneResult);
         (onUpdate as ToolUpdate | undefined)?.({
           content: [{ type: "text", text: message }],
-          details: { ...board, results: currentResults, aggregateUsage: aggregateUsage(currentResults) },
+          details: { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) },
         });
       };
       const runAt = async (index: number, task: string): Promise<void> => {
@@ -1228,10 +1268,21 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           emit();
           return;
         }
+        const controller = new AbortController();
+        const runtime: ActiveThreadRuntime = {
+          controller,
+          handles: new Set(),
+          steering: [],
+          restarting: false,
+          traceCount: 0,
+          startedAt: Date.now(),
+        };
+        activeRuntimes.set(threadId, runtime);
         let sessionDirectory: string;
         try {
           sessionDirectory = await mkdtemp(path.join(os.tmpdir(), "killeros-subagent-session-"));
         } catch (error) {
+          activeRuntimes.delete(threadId);
           const message = error instanceof Error ? error.message : String(error);
           results[index] = {
             ...results[index]!,
@@ -1244,15 +1295,22 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           emit();
           return;
         }
-        const sessionId = `killeros-${threadId.replace(/[^A-Za-z0-9_.-]/gu, "_")}`;
-        const controller = new AbortController();
-        const abortParent = (): void => controller.abort();
-        if (signal) {
-          if (signal.aborted) controller.abort();
-          else signal.addEventListener("abort", abortParent, { once: true });
+        const currentThread = threads.inspect(threadId);
+        if (controller.signal.aborted || threads.isDisposed || currentThread?.state !== "active") {
+          activeRuntimes.delete(threadId);
+          try {
+            await rm(sessionDirectory, { recursive: true, force: true });
+          } catch {
+            // Temporary child session cleanup is best effort before process startup.
+          }
+          const reason = runtime.requestedReason ?? currentThread?.stopReason ?? (threads.isDisposed ? "session_shutdown" : "interrupted");
+          results[index] = { ...results[index]!, status: "cancelled", terminationReason: reason };
+          if (!threads.isDisposed && currentThread?.state === "active") threads.stop(threadId, { reason });
+          savedResults.set(threadId, cloneResult(results[index]!));
+          emit();
+          return;
         }
-        const runtime: ActiveThreadRuntime = { controller, steering: [], restarting: false, traceCount: 0, startedAt: Date.now() };
-        activeRuntimes.set(threadId, runtime);
+        const sessionId = `killeros-${threadId.replace(/[^A-Za-z0-9_.-]/gu, "_")}`;
         const agent = roles.get(input.agent)!;
         const queuedSteering = initialThread.steering.map((entry) => entry.message);
         let currentTask = queuedSteering.length ? buildSteeredTask(task, queuedSteering, limits.taskCharacters) : task;
@@ -1331,7 +1389,10 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
                 ...(limits.quotaUsd === undefined ? {} : { quotaUsd: limits.quotaUsd - usedCost }),
               },
               timeoutMs: remainingWallTimeMs,
-              onHandle: (handle) => { runtime.handle = handle; },
+              onHandle: (handle) => {
+                runtime.handle = handle;
+                runtime.handles.add(handle);
+              },
               onChange: (changed) => {
                 results[index] = syncThread(threadId, changed, runtime);
                 emit();
@@ -1344,6 +1405,9 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
             savedResults.set(threadId, cloneResult(runtime.aggregate));
             const shouldRestart = runtime.steering.length > 0 && !controller.signal.aborted && (runtime.restarting || next.status === "complete" || next.status === "cancelled");
             if (!shouldRestart) break;
+            const previousHandle = runtime.handle;
+            if (previousHandle && !(await waitForConfirmedProcessExit(previousHandle))) break;
+            if (controller.signal.aborted || threads.isDisposed) break;
             const steering = runtime.steering.splice(0);
             runtime.restarting = false;
             runtime.requestedReason = undefined;
@@ -1358,16 +1422,39 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           }
         } finally {
           activeRuntimes.delete(threadId);
-          signal?.removeEventListener("abort", abortParent);
-          try {
-            await rm(sessionDirectory, { recursive: true, force: true });
-          } catch {
-            // Temporary child session cleanup is best effort after process termination.
-          }
+          const removeSessionDirectory = async (): Promise<void> => {
+            try {
+              await rm(sessionDirectory, { recursive: true, force: true });
+            } catch {
+              // Temporary child session cleanup is best effort after process termination.
+            }
+          };
+          const pendingExits = [...runtime.handles]
+            .filter((handle) => !handle.hasExited)
+            .map((handle) => handle.exited);
+          if (!pendingExits.length) await removeSessionDirectory();
+          else void Promise.all(pendingExits).then(removeSessionDirectory);
         }
         emit();
       };
 
+      const settleQueued = (reason: string): void => {
+        for (let index = 0; index < results.length; index += 1) {
+          const result = results[index]!;
+          if (result.status !== "queued") continue;
+          const thread = threads.inspect(threadRecords[index]!.id);
+          const alreadyStopped = thread?.state === "stopped";
+          result.status = signal?.aborted || alreadyStopped ? "cancelled" : "failed";
+          result.terminationReason = alreadyStopped
+            ? thread.stopReason ?? "interrupted"
+            : signal?.aborted ? "abort" : reason;
+          if (thread?.state === "queued" || thread?.state === "active") {
+            threads.stop(threadRecords[index]!.id, { reason: result.terminationReason });
+          }
+          savedResults.set(threadRecords[index]!.id, cloneResult(result));
+        }
+      };
+
       emit(`${mode}: ${results.length} queued`);
       if (hasChain) {
         let previous = "";
@@ -1377,33 +1464,26 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           if (results[index]!.status !== "complete") break;
           previous = results[index]!.output;
         }
-        for (let index = 0; index < results.length; index += 1) {
-          const result = results[index]!;
-          if (result.status === "queued") {
-            const thread = threads.inspect(threadRecords[index]!.id);
-            const alreadyStopped = thread?.state === "stopped";
-            result.status = signal?.aborted || alreadyStopped ? "cancelled" : "failed";
-            result.terminationReason = alreadyStopped
-              ? thread.stopReason ?? "interrupted"
-              : signal?.aborted ? "abort" : "chain_stopped";
-            if (thread?.state === "queued" || thread?.state === "active") {
-              threads.stop(threadRecords[index]!.id, { reason: result.terminationReason });
-            }
-            savedResults.set(threadRecords[index]!.id, cloneResult(result));
+        settleQueued("chain_stopped");
+      } else if (hasParallel) {
+        try {
+          if (useSharedParallelPool) {
+            const indexes = inputs.map((_, index) => index);
+            await mapReadTasks(indexes, writerConcurrency, async (index) => runAt(index, inputs[index]!.task));
+          } else {
+            await mapReadTasks(readIndexes, limits.maxReadConcurrency, async ({ index }) => runAt(index, inputs[index]!.task));
+            for (const index of writerIndexes) await runAt(index, inputs[index]!.task);
           }
+        } finally {
+          settleQueued("parallel_stopped");
         }
-      } else if (hasParallel) {
-        const readIndexes = inputs.map((input, index) => ({ input, index })).filter(({ input }) => roles.get(input.agent)!.access === "read");
-        const writerIndex = inputs.findIndex((input) => roles.get(input.agent)!.access === "write");
-        await mapReadTasks(readIndexes, limits.maxReadConcurrency, async ({ index }) => runAt(index, inputs[index]!.task));
-        if (writerIndex >= 0) await runAt(writerIndex, inputs[writerIndex]!.task);
       } else {
         await runAt(0, inputs[0]!.task);
       }
 
       const board = detailsFor(parentId, mode, scope, discovery.projectAgentsDir);
       const currentResults = results.map(cloneResult);
-      const details: SubagentDetails = { ...board, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
+      const details: SubagentDetails = { ...board, executionNote, results: currentResults, aggregateUsage: aggregateUsage(currentResults) };
       return {
         content: [{ type: "text", text: buildToolContent(mode, details.results, limits.toolOutputBytes) }],
         details,
@@ -1414,7 +1494,10 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
     renderCall(args, theme) {
       const scope = args.agentScope ?? "user";
       if (args.action && args.action !== "spawn") return new Text(`${theme.fg("toolTitle", theme.bold("threads "))}${theme.fg("accent", args.action)}${theme.fg("dim", args.threadId ? ` · ${args.threadId}` : "")}`, 0, 0);
-      if (args.tasks?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `parallel ${args.tasks.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
+      if (args.tasks?.length) {
+        const schedule = args.writerConcurrency === undefined ? "parallel default" : `shared pool ${args.writerConcurrency}`;
+        return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `parallel ${args.tasks.length} · ${schedule}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
+      }
       if (args.chain?.length) return new Text(`${theme.fg("toolTitle", theme.bold("subagents "))}${theme.fg("accent", `chain ${args.chain.length}`)}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
       return new Text(`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "…")}${theme.fg("dim", ` · ${scope}`)}`, 0, 0);
     },
@@ -1437,6 +1520,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
           theme.fg("toolTitle", theme.bold(`Done (${board.done.length})`)),
           ...board.done.map((task) => `${theme.fg(task.state.status === "complete" ? "success" : "warning", `${task.state.label}`)} ${theme.fg("toolTitle", theme.bold(task.agent))}${theme.fg("dim", ` · ${task.id} · ${task.usage.text}`)}`),
         ];
+        if (details.executionNote) lines.push(theme.fg("dim", details.executionNote));
         lines.push(theme.fg("dim", `Total · ${formatUsage(details.aggregateUsage)} · Ctrl+O to expand`));
         return new Text(lines.join("\n"), 0, 0);
       }
@@ -1444,6 +1528,7 @@ export function registerSubagentTool(pi: ExtensionAPI, options: SubagentRuntimeO
       const container = new Container();
       container.addChild(new Text(theme.fg("toolTitle", theme.bold(`Subagents · ${details.mode}`)), 0, 0));
       container.addChild(new Text(theme.fg("dim", `Active ${board.active.length} · Done ${board.done.length} · Controls: Inspect · Steer · Interrupt · Collect · Close`), 0, 0));
+      if (details.executionNote) container.addChild(new Text(theme.fg("dim", details.executionNote), 0, 0));
       if (board.selected) {
         const inspection = formatThreadInspection(threadBoardRecord(details.results.find((task) => task.id === board.selected!.id)!));
         container.addChild(new Spacer(1));