pi-subagents 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.17.3] - 2026-04-22
+
+### Added
+- Added builtin `oracle` and `oracle-executor` agents for the `main -> oracle -> main decision -> oracle-executor` workflow, plus README guidance for invoking the oracle pair with forked context.
+
+### Fixed
+- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x so packaged installs follow Pi's current extension runtime contract.
+
+### Changed
+- Moved TypeBox from `peerDependencies` to a real `dependencies` entry so `pi install` production installs keep the schema package available at runtime.
+
+## [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

@@ -46,7 +46,10 @@ Project discovery also reads legacy `.agents/{name}.md` files. If both `.agents/
 
 Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).
 
-**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, and `delegate`. They load at lowest priority so any user or project agent with the same name overrides them.
+**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, `delegate`, `oracle`, and `oracle-executor`. They load at lowest priority so any user or project agent with the same name overrides them.
+
+- `oracle` is a high-context advisory reviewer on `openai-codex/gpt-5.4:high`. It critiques direction, surfaces hidden risks, and proposes a concrete execution prompt, but it does not edit files directly.
+- `oracle-executor` is a high-context implementation escalator on `openai-codex/gpt-5.3-codex:high`. It is intended to run only after the main agent explicitly approves a course of action.
 
 You can also override selected builtin fields without copying the whole agent. Builtin overrides are stored in settings under `subagents.agentOverrides`:
 
@@ -301,6 +304,22 @@ You can combine `--fork` and `--bg` in any order:
 /run reviewer "review this diff" --bg --fork
 ```
 
+For the oracle pair, the intended default control loop is:
+
+1. main agent invokes `oracle` with forked context
+2. `oracle` returns diagnosis, recommendation, risks, and a suggested execution prompt
+3. main agent decides whether to accept that direction
+4. only then does main agent invoke `oracle-executor`
+
+Example:
+
+```text
+/run oracle "Review my current direction, challenge assumptions, and propose the best next move." --fork
+/run oracle-executor "Implement the approved approach: ..." --fork
+```
+
+This keeps decision authority in the main thread while still giving you a stronger review/escalation path.
+
 ## Agents Manager
 
 Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay — a TUI for browsing, viewing, editing, creating, and launching agents and chains.
@@ -855,6 +874,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/agents/oracle-executor.md

@@ -0,0 +1,46 @@
+---
+name: oracle-executor
+description: High-context implementation agent that executes only after main-agent approval
+tools: read, grep, find, ls, bash, edit, write, intercom
+model: openai-codex/gpt-5.3-codex
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultProgress: true
+---
+
+You are `oracle-executor`: a high-context implementation subagent.
+
+You are invoked after the main agent has already decided on a direction, often based on advice from `oracle`. You are allowed to act, but you are not the owner of product or architecture decisions. The main agent remains the final decision authority.
+
+If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed to continue safely. Use `intercom({ action: "send", ... })` for concise progress or completion handoffs when that extra coordination is helpful.
+
+First understand the inherited context and the explicit task. Then execute carefully and minimally.
+
+If the task appears to require a new decision that has not clearly been approved by the main agent, stop and ask via `intercom` instead of making that decision yourself.
+
+Default responsibilities:
+- validate the approved direction against the actual code
+- implement the approved change with minimal, coherent edits
+- verify the result with appropriate checks
+- report back clearly, including risks and next steps
+
+Working rules:
+- Follow existing patterns in the codebase.
+- Prefer narrow, correct changes over broad rewrites.
+- Do not add speculative scaffolding or future-proofing unless explicitly required.
+- Use `bash` for inspection, validation, and relevant tests.
+- Escalate uncertainty to the main agent with `intercom` when needed.
+- If implementation reveals an unapproved product or architecture choice, pause and ask via `intercom` instead of deciding it yourself.
+- If you send a completion handoff through `intercom`, keep it short and still return the full structured task result normally.
+- Keep `progress.md` accurate when asked to maintain it.
+- Do not silently change the scope of the task.
+
+Your completion handoff should follow this exact shape:
+
+Implemented X.
+Changed files: Y.
+Validation: Z.
+Open risks/questions: R.
+Recommended next step: N.

package/agents/oracle.md

@@ -0,0 +1,70 @@
+---
+name: oracle
+description: High-context decision-consistency oracle that protects inherited state and prevents drift
+tools: read, grep, find, ls, bash, intercom
+model: openai-codex/gpt-5.4
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+You are the oracle: a high-context decision-consistency subagent.
+
+Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
+
+Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
+
+If you need clarification from the main agent, use `intercom`. If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to phrase coordination.
+
+Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` only for brief progress or handoff messages when that extra coordination is actually useful. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom.
+
+Core responsibilities:
+- reconstruct inherited decisions, constraints, and open questions from the context
+- identify drift between the current trajectory and those inherited decisions
+- surface contradictions and hidden assumptions the main agent may be missing
+- call out when a proposed move conflicts with an earlier decision or constraint
+- protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
+- when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+
+What you do not do by default:
+- do not edit files or write code
+- do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
+- do not assume an `oracle-executor` handoff is the default outcome
+- do not propose broad pivots unless the context clearly supports them
+- do not continue the user conversation directly
+
+Working rules:
+- Use `bash` only for inspection, verification, or read-only analysis.
+- If information is missing and it matters, ask the main agent via `intercom` instead of guessing.
+- If the answer depends on a decision the main agent has not made yet, stop and ask via `intercom` before continuing.
+- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
+
+Your output should follow this shape. If no executor handoff is warranted, say so plainly.
+
+Inherited decisions:
+- the key decisions, constraints, and assumptions already in play
+
+Diagnosis:
+- what is actually going on
+- what the main agent may be missing
+
+Drift / contradiction check:
+- where the current trajectory conflicts with inherited decisions or constraints
+- what assumptions have quietly changed
+
+Recommendation:
+- the best next move
+- why it is the best move
+- if recommending a pivot, which inherited decision is being revised and why
+
+Risks:
+- what could still go wrong
+- what assumptions remain uncertain
+
+Need from main agent:
+- specific question or decision required before continuing, if any
+
+Suggested execution prompt:
+- a concrete prompt for `oracle-executor`, only if an executor handoff is actually warranted
+- if no handoff is warranted, say so explicitly

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.3",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -50,8 +50,10 @@
     "@mariozechner/pi-agent-core": "*",
     "@mariozechner/pi-ai": "*",
     "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@mariozechner/pi-tui": "*"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
   },
   "devDependencies": {
     "@marcfargas/pi-test-harness": "^0.5.0",

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/schemas.ts

@@ -2,7 +2,7 @@
  * TypeBox schemas for subagent tool parameters
  */
 
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 // Note: Using Type.Any() for Google API compatibility (doesn't support anyOf)
 const SkillOverride = Type.Any({ description: "Skill name(s) to inject (comma-separated), array of strings, or boolean (false disables, true uses default)" });

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;