pi-subagents 0.17.1 → 0.17.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.17.2] - 2026-04-21
+
+### Added
+- Added `forceTopLevelAsync` so depth-0 delegated runs can be forced into background mode with `clarify: false`, while nested runs keep their existing behavior.
+
+### Fixed
+- Background completion notifications now render `(no output)` instead of a blank body when a completion summary is empty or whitespace-only.
+- Async status and token reporting now rerender more reliably when cleanup state changes, read token usage from `message.usage`, and prefer the newest session file when multiple async session files exist.
+- Async/background startup now fails fast for invalid resolved `cwd` values and spawn failures instead of reporting false launch success.
+- Sync and async runner paths now drain stuck child processes in bounded time, covering both post-exit stdio holders and children that emit a final message but never exit.
+
 ## [0.17.1] - 2026-04-20
 
 ### Added

package/README.md

@@ -855,6 +855,33 @@ This aggregated output becomes `{previous}` for the next step.
 
 `pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`.
 
+### `asyncByDefault`
+
+`asyncByDefault` makes top-level subagent calls use background execution when the request does not explicitly set `async`.
+
+```json
+{
+  "asyncByDefault": true
+}
+```
+
+This only changes the default. Callers can still force foreground execution by setting `async: false` unless `forceTopLevelAsync` is also enabled.
+
+### `forceTopLevelAsync`
+
+`forceTopLevelAsync` forces depth-0 subagent execution into background mode. This is useful for automation setups that never want the top-level orchestrator to block on child runs.
+
+```json
+{
+  "forceTopLevelAsync": true
+}
+```
+
+When enabled:
+- top-level single, parallel, and chain runs are forced to `async: true`
+- top-level clarify UI is bypassed by forcing `clarify: false`
+- nested subagent calls still follow their own inherited depth and async settings
+
 ### `parallel`
 
 `parallel` controls top-level `tasks` mode defaults and limits.

package/async-execution.ts

@@ -114,22 +114,39 @@ export function isAsyncAvailable(): boolean {
 /**
  * Spawn the async runner process
  */
-function spawnRunner(cfg: object, suffix: string, cwd: string): number | undefined {
-	if (!jitiCliPath) return undefined;
-	
+function spawnRunner(cfg: object, suffix: string, cwd: string): { pid?: number; error?: string } {
+	if (!jitiCliPath) {
+		return { error: "jiti for TypeScript execution could not be found" };
+	}
+
+	try {
+		const cwdStats = fs.statSync(cwd);
+		if (!cwdStats.isDirectory()) {
+			return { error: `cwd is not a directory: ${cwd}` };
+		}
+	} catch {
+		return { error: `cwd does not exist: ${cwd}` };
+	}
+
 	fs.mkdirSync(TEMP_ROOT_DIR, { recursive: true });
 	const cfgPath = getAsyncConfigPath(suffix);
 	fs.writeFileSync(cfgPath, JSON.stringify(cfg));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
-	
+
 	const proc = spawn(process.execPath, [jitiCliPath, runner, cfgPath], {
 		cwd,
 		detached: true,
 		stdio: "ignore",
 		windowsHide: true,
 	});
+	proc.on("error", (error) => {
+		console.error(`[pi-subagents] async spawn failed: ${error.message}`);
+	});
+	if (typeof proc.pid !== "number") {
+		return { error: `async runner did not produce a pid for cwd: ${cwd}` };
+	}
 	proc.unref();
-	return proc.pid;
+	return { pid: proc.pid };
 }
 
 function formatAsyncStartError(mode: "single" | "chain", message: string): AsyncExecutionResult {
@@ -260,9 +277,9 @@ export function executeAsyncChain(
 		return buildSeqStep(s as SequentialStep, nextSessionFile());
 	});
 
-	let pid: number | undefined;
+	let spawnResult: { pid?: number; error?: string } = {};
 	try {
-		pid = spawnRunner(
+		spawnResult = spawnRunner(
 			{
 				id,
 				steps,
@@ -289,14 +306,18 @@ export function executeAsyncChain(
 		return formatAsyncStartError("chain", `Failed to start async chain '${id}': ${message}`);
 	}
 
-	if (pid) {
+	if (spawnResult.error) {
+		return formatAsyncStartError("chain", `Failed to start async chain '${id}': ${spawnResult.error}`);
+	}
+
+	if (spawnResult.pid) {
 		const firstStep = chain[0];
 		const firstAgents = isParallelStep(firstStep)
 			? firstStep.parallel.map((t) => t.agent)
 			: [(firstStep as SequentialStep).agent];
 		ctx.pi.events.emit("subagent:started", {
 			id,
-			pid,
+			pid: spawnResult.pid,
 			agent: firstAgents[0],
 			task: isParallelStep(firstStep)
 				? firstStep.parallel[0]?.task?.slice(0, 50)
@@ -368,9 +389,9 @@ export function executeAsyncSingle(
 
 	const outputPath = resolveSingleOutputPath(params.output, ctx.cwd, runnerCwd);
 	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
-	let pid: number | undefined;
+	let spawnResult: { pid?: number; error?: string } = {};
 	try {
-		pid = spawnRunner(
+		spawnResult = spawnRunner(
 			{
 				id,
 				steps: [
@@ -418,10 +439,14 @@ export function executeAsyncSingle(
 		return formatAsyncStartError("single", `Failed to start async run '${id}': ${message}`);
 	}
 
-	if (pid) {
+	if (spawnResult.error) {
+		return formatAsyncStartError("single", `Failed to start async run '${id}': ${spawnResult.error}`);
+	}
+
+	if (spawnResult.pid) {
 		ctx.pi.events.emit("subagent:started", {
 			id,
-			pid,
+			pid: spawnResult.pid,
 			agent,
 			task: task?.slice(0, 50),
 			cwd: runnerCwd,

package/async-job-tracker.ts

@@ -7,18 +7,42 @@ import {
 } from "./types.ts";
 import { readStatus } from "./utils.ts";
 
-export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string): {
+interface AsyncJobTrackerOptions {
+	completionRetentionMs?: number;
+	pollIntervalMs?: number;
+}
+
+export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string, options: AsyncJobTrackerOptions = {}): {
 	ensurePoller: () => void;
 	handleStarted: (data: unknown) => void;
 	handleComplete: (data: unknown) => void;
 	resetJobs: (ctx?: ExtensionContext) => void;
 } {
+	const completionRetentionMs = options.completionRetentionMs ?? 10000;
+	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
+		renderWidget(ctx, jobs);
+		ctx.ui.requestRender?.();
+	};
+	const scheduleCleanup = (asyncId: string) => {
+		const existingTimer = state.cleanupTimers.get(asyncId);
+		if (existingTimer) clearTimeout(existingTimer);
+		const timer = setTimeout(() => {
+			state.cleanupTimers.delete(asyncId);
+			state.asyncJobs.delete(asyncId);
+			if (state.lastUiContext) {
+				rerenderWidget(state.lastUiContext);
+			}
+		}, completionRetentionMs);
+		state.cleanupTimers.set(asyncId, timer);
+	};
+
 	const ensurePoller = () => {
 		if (state.poller) return;
 		state.poller = setInterval(() => {
 			if (!state.lastUiContext || !state.lastUiContext.hasUI) return;
 			if (state.asyncJobs.size === 0) {
-				renderWidget(state.lastUiContext, []);
+				rerenderWidget(state.lastUiContext, []);
 				if (state.poller) {
 					clearInterval(state.poller);
 					state.poller = null;
@@ -27,12 +51,10 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 			}
 
 			for (const job of state.asyncJobs.values()) {
-				if (job.status === "complete" || job.status === "failed") {
-					continue;
-				}
 				try {
 					const status = readStatus(job.asyncDir);
 					if (status) {
+						const previousStatus = job.status;
 						job.status = status.state;
 						job.mode = status.mode;
 						job.currentStep = status.currentStep ?? job.currentStep;
@@ -46,6 +68,9 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 						job.outputFile = status.outputFile ?? job.outputFile;
 						job.totalTokens = status.totalTokens ?? job.totalTokens;
 						job.sessionFile = status.sessionFile ?? job.sessionFile;
+						if ((job.status === "complete" || job.status === "failed") && previousStatus !== job.status) {
+							scheduleCleanup(job.asyncId);
+						}
 						continue;
 					}
 					job.status = job.status === "queued" ? "running" : job.status;
@@ -57,8 +82,8 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 				}
 			}
 
-			renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
-		}, POLL_INTERVAL_MS);
+			rerenderWidget(state.lastUiContext);
+		}, pollIntervalMs);
 		state.poller.unref?.();
 	};
 
@@ -84,7 +109,7 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 			updatedAt: now,
 		});
 		if (state.lastUiContext) {
-			renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
+			rerenderWidget(state.lastUiContext);
 			ensurePoller();
 		}
 	};
@@ -100,16 +125,9 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 			if (result.asyncDir) job.asyncDir = result.asyncDir;
 		}
 		if (state.lastUiContext) {
-			renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
+			rerenderWidget(state.lastUiContext);
 		}
-		const timer = setTimeout(() => {
-			state.cleanupTimers.delete(asyncId);
-			state.asyncJobs.delete(asyncId);
-			if (state.lastUiContext) {
-				renderWidget(state.lastUiContext, Array.from(state.asyncJobs.values()));
-			}
-		}, 10000);
-		state.cleanupTimers.set(asyncId, timer);
+		scheduleCleanup(asyncId);
 	};
 
 	const resetJobs = (ctx?: ExtensionContext) => {
@@ -121,7 +139,7 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 		state.resultFileCoalescer.clear();
 		if (ctx?.hasUI) {
 			state.lastUiContext = ctx;
-			renderWidget(ctx, []);
+			rerenderWidget(ctx, []);
 		}
 	};
 

package/execution.ts

@@ -34,6 +34,7 @@ import {
 import { buildSkillInjection, resolveSkillsWithFallback } from "./skills.ts";
 import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { createJsonlWriter } from "./jsonl-writer.ts";
+import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "./pi-args.ts";
 import { captureSingleOutputSnapshot, resolveSingleOutput, type SingleOutputSnapshot } from "./single-output.ts";
 import {
@@ -188,6 +189,42 @@ async function runSingleAttempt(
 			finish(-2);
 		};
 
+		// If the child emits its final assistant message but never exits,
+		// start a bounded drain window and force termination if needed.
+		const FINAL_DRAIN_MS = 5000;
+		const HARD_KILL_MS = 3000;
+		let childExited = false;
+		let forcedTerminationSignal = false;
+		let finalDrainTimer: NodeJS.Timeout | undefined;
+		let finalHardKillTimer: NodeJS.Timeout | undefined;
+		const clearFinalDrainTimers = () => {
+			if (finalDrainTimer) {
+				clearTimeout(finalDrainTimer);
+				finalDrainTimer = undefined;
+			}
+			if (finalHardKillTimer) {
+				clearTimeout(finalHardKillTimer);
+				finalHardKillTimer = undefined;
+			}
+		};
+		const startFinalDrain = () => {
+			if (childExited || finalDrainTimer || settled || processClosed || detached) return;
+			finalDrainTimer = setTimeout(() => {
+				if (settled || processClosed || detached) return;
+				const termSent = trySignalChild(proc, "SIGTERM");
+				if (!termSent) return;
+				forcedTerminationSignal = true;
+				result.error = result.error
+					?? `Subagent process did not exit within ${FINAL_DRAIN_MS}ms after its final message. Forcing termination.`;
+				finalHardKillTimer = setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					forcedTerminationSignal = trySignalChild(proc, "SIGKILL") || forcedTerminationSignal;
+				}, HARD_KILL_MS);
+				finalHardKillTimer.unref?.();
+			}, FINAL_DRAIN_MS);
+			finalDrainTimer.unref?.();
+		};
+
 		const unsubscribeIntercomDetach = options.intercomEvents?.on?.(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
 			if (!options.allowIntercomDetach || detached || processClosed) return;
 			if (!payload || typeof payload !== "object") return;
@@ -202,6 +239,8 @@ async function runSingleAttempt(
 		const finish = (code: number) => {
 			if (settled) return;
 			settled = true;
+			clearFinalDrainTimers();
+			clearStdioGuard();
 			unsubscribeIntercomDetach?.();
 			removeAbortListener?.();
 			resolve(code);
@@ -279,6 +318,13 @@ async function runSingleAttempt(
 					if (!result.model && evt.message.model) result.model = evt.message.model;
 					if (evt.message.errorMessage) result.error = evt.message.errorMessage;
 					appendRecentOutput(progress, extractTextFromContent(evt.message.content).split("\n").slice(-10));
+					// Final assistant message: start the exit drain window.
+					const stopReason = (evt.message as { stopReason?: string }).stopReason;
+					const hasToolCall = Array.isArray(evt.message.content)
+						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
+					if (stopReason === "stop" && !hasToolCall) {
+						startFinalDrain();
+					}
 				}
 				fireUpdate();
 			}
@@ -292,6 +338,7 @@ async function runSingleAttempt(
 
 		let stderrBuf = "";
 
+		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
 		proc.stdout.on("data", (d) => {
 			buf += d.toString();
 			const lines = buf.split("\n");
@@ -301,7 +348,13 @@ async function runSingleAttempt(
 		proc.stderr.on("data", (d) => {
 			stderrBuf += d.toString();
 		});
-		proc.on("close", (code) => {
+		proc.on("exit", () => {
+			childExited = true;
+			clearFinalDrainTimers();
+		});
+		proc.on("close", (code, signal) => {
+			clearFinalDrainTimers();
+			clearStdioGuard();
 			void jsonlWriter.close().catch(() => {
 				// JSONL artifact flush is best effort.
 			});
@@ -315,9 +368,12 @@ async function runSingleAttempt(
 			if (code !== 0 && stderrBuf.trim() && !result.error) {
 				result.error = stderrBuf.trim();
 			}
-			finish(code ?? 0);
+			const finalCode = forcedTerminationSignal || signal ? (code ?? 1) : (code ?? 0);
+			finish(finalCode);
 		});
 		proc.on("error", (error) => {
+			clearFinalDrainTimers();
+			clearStdioGuard();
 			void jsonlWriter.close().catch(() => {
 				// JSONL artifact flush is best effort.
 			});

package/index.ts

@@ -9,7 +9,7 @@
  * Toggle: async parameter (default: false, configurable via config.json)
  *
  * Config file: ~/.pi/agent/extensions/subagent/config.json
- *   { "asyncByDefault": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
+ *   { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
  */
 
 import * as fs from "node:fs";

package/notify.ts

@@ -54,10 +54,11 @@ export default function registerSubagentNotify(pi: ExtensionAPI): void {
 			extra.push(`Session file: ${result.sessionFile}`);
 		}
 
+		const summary = result.summary.trim() ? result.summary : "(no output)";
 		const content = [
 			`Background task ${status}: **${agent}**${taskInfo}`,
 			"",
-			result.summary,
+			summary,
 			extra.length ? "" : undefined,
 			extra.length ? extra.join("\n") : undefined,
 		]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/post-exit-stdio-guard.ts

@@ -0,0 +1,85 @@
+import type { ChildProcess } from "node:child_process";
+
+interface PostExitStdioGuardOptions {
+	idleMs: number;
+	hardMs: number;
+}
+
+interface ChildWithPipedStdio {
+	stdout: ChildProcess["stdout"];
+	stderr: ChildProcess["stderr"];
+	on: ChildProcess["on"];
+}
+
+interface ChildWithKill {
+	kill(signal?: NodeJS.Signals | number): boolean;
+}
+
+export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
+	try {
+		return child.kill(signal);
+	} catch {
+		return false;
+	}
+}
+
+export function attachPostExitStdioGuard(
+	child: ChildWithPipedStdio,
+	options: PostExitStdioGuardOptions,
+): () => void {
+	const { idleMs, hardMs } = options;
+	let exited = false;
+	let stdoutEnded = false;
+	let stderrEnded = false;
+	let idleTimer: NodeJS.Timeout | undefined;
+	let hardTimer: NodeJS.Timeout | undefined;
+
+	const destroyUnendedStdio = () => {
+		if (!stdoutEnded) {
+			try { child.stdout?.destroy(); } catch {}
+		}
+		if (!stderrEnded) {
+			try { child.stderr?.destroy(); } catch {}
+		}
+	};
+
+	const clearTimers = () => {
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+		if (hardTimer) {
+			clearTimeout(hardTimer);
+			hardTimer = undefined;
+		}
+	};
+
+	const armIdleTimer = () => {
+		if (!exited) return;
+		if (idleTimer) clearTimeout(idleTimer);
+		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
+		idleTimer.unref?.();
+	};
+
+	child.stdout?.on("data", armIdleTimer);
+	child.stderr?.on("data", armIdleTimer);
+	child.stdout?.on("end", () => {
+		stdoutEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.stderr?.on("end", () => {
+		stderrEnded = true;
+		if (stdoutEnded && stderrEnded) clearTimers();
+	});
+	child.on("exit", () => {
+		exited = true;
+		armIdleTimer();
+		if (hardTimer) return;
+		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
+		hardTimer.unref?.();
+	});
+	child.on("close", clearTimers);
+	child.on("error", clearTimers);
+
+	return clearTimers;
+}

package/session-tokens.ts

@@ -0,0 +1,48 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface TokenUsage {
+	input: number;
+	output: number;
+	total: number;
+}
+
+function findLatestSessionFile(sessionDir: string): string | null {
+	try {
+		const files = fs.readdirSync(sessionDir)
+			.filter((f) => f.endsWith(".jsonl"))
+			.map((f) => path.join(sessionDir, f));
+		if (files.length === 0) return null;
+		files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+		return files[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+
+export function parseSessionTokens(sessionDir: string): TokenUsage | null {
+	const sessionFile = findLatestSessionFile(sessionDir);
+	if (!sessionFile) return null;
+	try {
+		const content = fs.readFileSync(sessionFile, "utf-8");
+		let input = 0;
+		let output = 0;
+		for (const line of content.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const entry = JSON.parse(line);
+				const usage = entry.usage ?? entry.message?.usage;
+				if (usage) {
+					input += usage.inputTokens ?? usage.input ?? 0;
+					output += usage.outputTokens ?? usage.output ?? 0;
+				}
+			} catch {
+				// Ignore malformed lines while scanning usage entries.
+			}
+		}
+		return { input, output, total: input + output };
+	} catch {
+		// Usage extraction should not fail the run.
+		return null;
+	}
+}

package/subagent-executor.ts

@@ -26,6 +26,7 @@ import { createForkContextResolver } from "./fork-context.ts";
 import { applyIntercomBridgeToAgent, resolveIntercomBridge, resolveIntercomSessionTarget } from "./intercom-bridge.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, resolveChildCwd } from "./utils.ts";
+import { applyForceTopLevelAsyncOverride } from "./top-level-async.ts";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -1209,32 +1210,38 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		if (normalized.error) return normalized.error;
 		const normalizedParams = normalized.params!;
 
-		const scope: AgentScope = resolveExecutionAgentScope(normalizedParams.agentScope);
-		const effectiveCwd = normalizedParams.cwd ?? ctx.cwd;
+		const effectiveParams = applyForceTopLevelAsyncOverride(
+			normalizedParams,
+			depth,
+			deps.config.forceTopLevelAsync === true,
+		);
+
+		const scope: AgentScope = resolveExecutionAgentScope(effectiveParams.agentScope);
+		const effectiveCwd = effectiveParams.cwd ?? ctx.cwd;
 		const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
 		deps.state.currentSessionId = parentSessionFile ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		const discoveredAgents = deps.discoverAgents(effectiveCwd, scope).agents;
 		const sessionName = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
 		const intercomBridge = resolveIntercomBridge({
 			config: deps.config.intercomBridge,
-			context: normalizedParams.context,
+			context: effectiveParams.context,
 			orchestratorTarget: sessionName,
 		});
 		const agents = intercomBridge.active
 			? discoveredAgents.map((agent) => applyIntercomBridgeToAgent(agent, intercomBridge))
 			: discoveredAgents;
 		const runId = randomUUID().slice(0, 8);
-		const shareEnabled = normalizedParams.share === true;
-		const hasChain = (normalizedParams.chain?.length ?? 0) > 0;
-		const hasTasks = (normalizedParams.tasks?.length ?? 0) > 0;
-		const hasSingle = Boolean(normalizedParams.agent && normalizedParams.task);
+		const shareEnabled = effectiveParams.share === true;
+		const hasChain = (effectiveParams.chain?.length ?? 0) > 0;
+		const hasTasks = (effectiveParams.tasks?.length ?? 0) > 0;
+		const hasSingle = Boolean(effectiveParams.agent && effectiveParams.task);
 		const allowClarifyTaskPrompt = hasChain
-			&& normalizedParams.clarify === true
+			&& effectiveParams.clarify === true
 			&& ctx.hasUI
-			&& !(normalizedParams.chain?.some(isParallelStep) ?? false);
+			&& !(effectiveParams.chain?.some(isParallelStep) ?? false);
 
 		const validationError = validateExecutionInput(
-			normalizedParams,
+			effectiveParams,
 			agents,
 			hasChain,
 			hasTasks,
@@ -1245,25 +1252,24 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 
 		let sessionFileForIndex: (idx?: number) => string | undefined = () => undefined;
 		try {
-			sessionFileForIndex = createForkContextResolver(ctx.sessionManager, normalizedParams.context).sessionFileForIndex;
+			sessionFileForIndex = createForkContextResolver(ctx.sessionManager, effectiveParams.context).sessionFileForIndex;
 		} catch (error) {
-			return toExecutionErrorResult(normalizedParams, error);
+			return toExecutionErrorResult(effectiveParams, error);
 		}
-
-		const requestedAsync = normalizedParams.async ?? deps.asyncByDefault;
-		const backgroundRequestedWhileClarifying = hasTasks && requestedAsync && normalizedParams.clarify === true;
+		const requestedAsync = effectiveParams.async ?? deps.asyncByDefault;
+		const backgroundRequestedWhileClarifying = hasTasks && requestedAsync && effectiveParams.clarify === true;
 		const effectiveAsync = requestedAsync
-			&& (hasChain ? normalizedParams.clarify === false : normalizedParams.clarify !== true);
+			&& (hasChain ? effectiveParams.clarify === false : effectiveParams.clarify !== true);
 
 		const artifactConfig: ArtifactConfig = {
 			...DEFAULT_ARTIFACT_CONFIG,
-			enabled: normalizedParams.artifacts !== false,
+			enabled: effectiveParams.artifacts !== false,
 		};
 		const artifactsDir = effectiveAsync ? deps.tempArtifactsDir : getArtifactsDir(parentSessionFile);
 
 		let sessionRoot: string;
-		if (normalizedParams.sessionDir) {
-			sessionRoot = path.resolve(deps.expandTilde(normalizedParams.sessionDir));
+		if (effectiveParams.sessionDir) {
+			sessionRoot = path.resolve(deps.expandTilde(effectiveParams.sessionDir));
 		} else {
 			const baseSessionRoot = deps.config.defaultSessionDir
 				? path.resolve(deps.expandTilde(deps.config.defaultSessionDir))
@@ -1275,7 +1281,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			return toExecutionErrorResult(
-				normalizedParams,
+				effectiveParams,
 				new Error(`Failed to create session directory '${sessionRoot}': ${message}`),
 			);
 		}
@@ -1283,11 +1289,11 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			path.join(sessionRoot, `run-${idx ?? 0}`);
 
 		const onUpdateWithContext = onUpdate
-			? (r: AgentToolResult<Details>) => onUpdate(withForkContext(r, normalizedParams.context))
+			? (r: AgentToolResult<Details>) => onUpdate(withForkContext(r, effectiveParams.context))
 			: undefined;
 
 		const execData: ExecutionContextData = {
-			params: normalizedParams,
+			params: effectiveParams,
 			effectiveCwd,
 			ctx,
 			signal,
@@ -1306,18 +1312,18 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 
 		try {
 			const asyncResult = runAsyncPath(execData, deps);
-			if (asyncResult) return withForkContext(asyncResult, normalizedParams.context);
+			if (asyncResult) return withForkContext(asyncResult, effectiveParams.context);
 
-			if (hasChain && normalizedParams.chain) {
-				return withForkContext(await runChainPath(execData, deps), normalizedParams.context);
+			if (hasChain && effectiveParams.chain) {
+				return withForkContext(await runChainPath(execData, deps), effectiveParams.context);
 			}
 
-			if (hasTasks && normalizedParams.tasks) {
-				return withForkContext(await runParallelPath(execData, deps), normalizedParams.context);
+			if (hasTasks && effectiveParams.tasks) {
+				return withForkContext(await runParallelPath(execData, deps), effectiveParams.context);
 			}
 
 			if (hasSingle) {
-				return withForkContext(await runSinglePath(execData, deps), normalizedParams.context);
+				return withForkContext(await runSinglePath(execData, deps), effectiveParams.context);
 			}
 		} catch (error) {
 			return toExecutionErrorResult(normalizedParams, error);
@@ -1327,7 +1333,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			content: [{ type: "text", text: "Invalid params" }],
 			isError: true,
 			details: { mode: "single" as const, results: [] },
-		}, normalizedParams.context);
+		}, effectiveParams.context);
 	};
 
 	return { execute };

package/subagent-runner.ts

@@ -28,7 +28,9 @@ import {
 } from "./parallel-utils.ts";
 import { buildPiArgs, cleanupTempDir } from "./pi-args.ts";
 import { formatModelAttemptNote, isRetryableModelFailure } from "./model-fallback.ts";
+import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
 import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "./utils.ts";
+import { parseSessionTokens, type TokenUsage } from "./session-tokens.ts";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -89,38 +91,6 @@ function findLatestSessionFile(sessionDir: string): string | null {
 	}
 }
 
-interface TokenUsage {
-	input: number;
-	output: number;
-	total: number;
-}
-
-function parseSessionTokens(sessionDir: string): TokenUsage | null {
-	const sessionFile = findLatestSessionFile(sessionDir);
-	if (!sessionFile) return null;
-	try {
-		const content = fs.readFileSync(sessionFile, "utf-8");
-		let input = 0;
-		let output = 0;
-		for (const line of content.split("\n")) {
-			if (!line.trim()) continue;
-			try {
-				const entry = JSON.parse(line);
-				if (entry.usage) {
-					input += entry.usage.inputTokens ?? entry.usage.input ?? 0;
-					output += entry.usage.outputTokens ?? entry.usage.output ?? 0;
-				}
-			} catch {
-				// Ignore malformed lines while scanning usage entries.
-			}
-		}
-		return { input, output, total: input + output };
-	} catch {
-		// Usage extraction should not fail the run.
-		return null;
-	}
-}
-
 function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
@@ -248,13 +218,18 @@ function runPiStreaming(
 				if (event.message.model) model = event.message.model;
 				if (event.message.errorMessage) error = event.message.errorMessage;
 				const eventUsage = event.message.usage;
-				if (!eventUsage) return;
-				usage.turns++;
-				usage.input += eventUsage.input ?? eventUsage.inputTokens ?? 0;
-				usage.output += eventUsage.output ?? eventUsage.outputTokens ?? 0;
-				usage.cacheRead += eventUsage.cacheRead ?? 0;
-				usage.cacheWrite += eventUsage.cacheWrite ?? 0;
-				usage.cost += eventUsage.cost?.total ?? 0;
+				if (eventUsage) {
+					usage.turns++;
+					usage.input += eventUsage.input ?? eventUsage.inputTokens ?? 0;
+					usage.output += eventUsage.output ?? eventUsage.outputTokens ?? 0;
+					usage.cacheRead += eventUsage.cacheRead ?? 0;
+					usage.cacheWrite += eventUsage.cacheWrite ?? 0;
+					usage.cost += eventUsage.cost?.total ?? 0;
+				}
+				const stopReason = (event.message as { stopReason?: string }).stopReason;
+				const hasToolCall = Array.isArray(event.message.content)
+					&& event.message.content.some((part) => (part as { type?: string }).type === "toolCall");
+				if (stopReason === "stop" && !hasToolCall) startFinalDrain();
 			}
 		};
 
@@ -271,6 +246,16 @@ function runPiStreaming(
 			}
 		};
 
+		// Guard both cases that can leave the parent waiting on `close` forever:
+		// a lingering stdio holder after `exit`, or a child that never exits.
+		const FINAL_DRAIN_MS = 5000;
+		const HARD_KILL_MS = 3000;
+		let childExited = false;
+		let forcedTerminationSignal = false;
+		let finalDrainTimer: NodeJS.Timeout | undefined;
+		let finalHardKillTimer: NodeJS.Timeout | undefined;
+		let settled = false;
+		const clearStdioGuard = attachPostExitStdioGuard(child, { idleMs: 2000, hardMs: 8000 });
 		child.stdout.on("data", (chunk: Buffer) => {
 			const text = chunk.toString();
 			stdoutBuf += text;
@@ -282,16 +267,61 @@ function runPiStreaming(
 		child.stderr.on("data", (chunk: Buffer) => {
 			processStderrText(chunk.toString());
 		});
-
-		child.on("close", (exitCode) => {
+		const clearDrainTimers = () => {
+			if (finalDrainTimer) {
+				clearTimeout(finalDrainTimer);
+				finalDrainTimer = undefined;
+			}
+			if (finalHardKillTimer) {
+				clearTimeout(finalHardKillTimer);
+				finalHardKillTimer = undefined;
+			}
+		};
+		function startFinalDrain(): void {
+			if (childExited || finalDrainTimer || settled) return;
+			finalDrainTimer = setTimeout(() => {
+				if (settled) return;
+				const termSent = trySignalChild(child, "SIGTERM");
+				if (!termSent) return;
+				forcedTerminationSignal = true;
+				if (!error) {
+					error = `Subagent process did not exit within ${FINAL_DRAIN_MS}ms after its final message. Forcing termination.`;
+				}
+				finalHardKillTimer = setTimeout(() => {
+					if (settled) return;
+					forcedTerminationSignal = trySignalChild(child, "SIGKILL") || forcedTerminationSignal;
+				}, HARD_KILL_MS);
+				finalHardKillTimer.unref?.();
+			}, FINAL_DRAIN_MS);
+			finalDrainTimer.unref?.();
+		}
+		child.on("exit", () => {
+			childExited = true;
+			clearDrainTimers();
+		});
+		child.on("close", (exitCode, signal) => {
+			settled = true;
+			clearDrainTimers();
+			clearStdioGuard();
 			if (stdoutBuf.trim()) processStdoutLine(stdoutBuf);
 			if (stderrBuf.trim()) appendChildLine("subagent.child.stderr", stderrBuf);
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
-			resolve({ stderr, exitCode, messages, usage, model, error, finalOutput });
+			resolve({
+				stderr,
+				exitCode: forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
+				messages,
+				usage,
+				model,
+				error,
+				finalOutput,
+			});
 		});
 
 		child.on("error", (spawnError) => {
+			settled = true;
+			clearDrainTimers();
+			clearStdioGuard();
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);

package/top-level-async.ts

@@ -0,0 +1,13 @@
+export interface AsyncOverrideParams {
+	async?: boolean;
+	clarify?: boolean;
+}
+
+export function applyForceTopLevelAsyncOverride<T extends AsyncOverrideParams>(
+	params: T,
+	depth: number,
+	forceTopLevelAsync: boolean,
+): T {
+	if (!(depth === 0 && forceTopLevelAsync)) return params;
+	return { ...params, async: true, clarify: false };
+}

package/types.ts

@@ -288,6 +288,7 @@ export interface TopLevelParallelConfig {
 
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
+	forceTopLevelAsync?: boolean;
 	defaultSessionDir?: string;
 	maxSubagentDepth?: number;
 	parallel?: TopLevelParallelConfig;