@ryan_nookpi/pi-extension-subagent 0.3.1 → 0.3.2

package/README.md

@@ -238,6 +238,28 @@ Confirm the environment used to start pi has valid Anthropic authentication, suc
 
 That is intentional. Hidden `>` runs are human-only UI jobs. Inspect them with `/sub:peek`, `<>runId`, or `/sub:open`.
 
+### Debug runner termination
+
+The extension records process lifecycle diagnostics as `subagent-runner-diagnostic` custom entries in the parent session JSONL. They include run/batch IDs, parent and child PID/PGID, abort reason, internal kill cause, `exit`/`close` code and signal, settle reason, shutdown reason, and process-error stacks. Custom entries are not sent to the LLM and remain hidden unless an entry renderer is registered, as documented by pi's [`appendEntry` API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md#piappendentrycustomtype-data).
+
+Run `/session` to find the current session file, set `SESSION_FILE` to that path, then extract only the diagnostic entries:
+
+```bash
+jq -c 'select(.type == "custom" and .customType == "subagent-runner-diagnostic") | {timestamp, data}' "$SESSION_FILE"
+```
+
+For batch failures, compare entries by `batchId` and `runId`, then follow each run from `spawn` through `kill_intent`, `exit`, `close`, and `settled`. Share only the selected diagnostic lines—not the full session file, which may contain prompts or tool output.
+
+To report a reproducible extension bug, create `subagent-issue.md` with the pi and extension versions, OS and Node version, launch mode/command, reproduction steps, expected and actual behavior, and the sanitized diagnostic lines. Then submit it with:
+
+```bash
+gh issue create --repo Jonghakseo/pi-extension \
+  --title "subagent: unexpected child termination" \
+  --body-file subagent-issue.md
+```
+
+Without GitHub CLI, use the repository's [new issue page](https://github.com/Jonghakseo/pi-extension/issues/new). Remove secrets and sensitive paths before attaching diagnostics.
+
 ## Security and trust boundary
 
 - Claude SDK execution uses `permissionMode: "bypassPermissions"` with `allowDangerouslySkipPermissions`; Claude CLI execution uses `--dangerously-skip-permissions`.

package/claude-sdk-runner.ts

@@ -115,7 +115,7 @@ export async function runClaudeAgentViaSdk(
 
 	const forwardAbort = () => {
 		externalAbortRequested = true;
-		abortController.abort();
+		abortController.abort(signal?.reason);
 	};
 
 	if (signal?.aborted) {

package/commands.ts

@@ -26,6 +26,7 @@ import {
 	SUBVIEW_OVERLAY_MAX_HEIGHT,
 	SUBVIEW_OVERLAY_WIDTH,
 } from "./constants.js";
+import { createRunDiagnosticSink } from "./diagnostics.js";
 import {
 	buildSubagentDisplayTaskFallback,
 	createDisplayTaskRefreshToken,
@@ -1434,6 +1435,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 										resumeSessionId: runState.claudeSessionId,
 										sidecarSessionFile: runState.sessionFile,
 										persistedSessionBaseOffset: runState.persistedSessionBaseOffset,
+										onDiagnostic: createRunDiagnosticSink(pi, runState),
 									},
 								),
 							);
@@ -1907,7 +1909,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 			if (!controller) return false;
 			run.lastLine = "Aborting by user...";
 			run.lastOutput = run.lastLine;
-			controller.abort();
+			controller.abort({ source: "sub_abort_command", runId: run.id });
 			return true;
 		};
 
@@ -2187,7 +2189,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentReg
 			if (run.status === "running" && shortcutController) {
 				run.lastLine = "Aborting by user...";
 				run.lastOutput = run.lastLine;
-				shortcutController.abort();
+				shortcutController.abort({ source: "sub_abort_shortcut", runId: id });
 				aborted++;
 			} else if (run.status !== "running") {
 				const result = removeRun(store, id, {

package/diagnostics.ts

@@ -0,0 +1,145 @@
+import * as childProcess from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentRuntime } from "./agents.js";
+import type { CommandRunState } from "./types.js";
+
+export const RUNNER_DIAGNOSTIC_CUSTOM_TYPE = "subagent-runner-diagnostic";
+export const RUNNER_DIAGNOSTIC_SCHEMA_VERSION = 1;
+
+export type RunnerDiagnosticEventName =
+	| "spawn"
+	| "abort_received"
+	| "kill_intent"
+	| "kill_result"
+	| "process_error"
+	| "exit"
+	| "close"
+	| "settled"
+	| "session_shutdown";
+
+export interface RunnerDiagnosticEvent {
+	event: RunnerDiagnosticEventName;
+	runtime?: AgentRuntime;
+	parentPid?: number;
+	parentProcessGroupId?: number;
+	childPid?: number;
+	childParentPid?: number;
+	childProcessGroupId?: number;
+	processGroupMode?: "inherited";
+	code?: number | null;
+	signal?: NodeJS.Signals | null;
+	cause?: string;
+	abortReason?: unknown;
+	killSent?: boolean;
+	settleReason?: string;
+	stopReason?: string;
+	activeRunIds?: number[];
+	sessionShutdownReason?: string;
+	error?: DiagnosticError;
+}
+
+export type RunnerDiagnosticSink = (event: RunnerDiagnosticEvent) => void;
+
+interface DiagnosticError {
+	name?: string;
+	message: string;
+	stack?: string;
+}
+
+interface ProcessIdentity {
+	pid: number;
+	parentPid?: number;
+	processGroupId?: number;
+}
+
+function asFiniteInteger(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const parsed = Number(value);
+	return Number.isInteger(parsed) ? parsed : undefined;
+}
+
+/** Best-effort POSIX process identity lookup. Diagnostics must never affect execution. */
+export function readProcessIdentity(pid: number | undefined): ProcessIdentity | undefined {
+	if (!pid || !Number.isInteger(pid) || pid <= 0) return undefined;
+	if (process.platform === "win32") return { pid };
+
+	try {
+		const result = childProcess.spawnSync("ps", ["-o", "pid=,ppid=,pgid=", "-p", String(pid)], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		const fields = result.stdout?.trim().split(/\s+/);
+		if (!fields || fields.length < 3) return { pid };
+		return {
+			pid: asFiniteInteger(fields[0]) ?? pid,
+			parentPid: asFiniteInteger(fields[1]),
+			processGroupId: asFiniteInteger(fields[2]),
+		};
+	} catch {
+		return { pid };
+	}
+}
+
+export function serializeDiagnosticValue(value: unknown): unknown {
+	if (value instanceof Error) {
+		return {
+			name: value.name,
+			message: value.message,
+			stack: value.stack,
+		};
+	}
+	if (value === undefined || value === null) return value;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+
+	try {
+		return JSON.parse(JSON.stringify(value));
+	} catch {
+		return String(value);
+	}
+}
+
+export function toDiagnosticError(error: unknown): DiagnosticError {
+	if (error instanceof Error) {
+		return { name: error.name, message: error.message, stack: error.stack };
+	}
+	return { message: String(error) };
+}
+
+/** Emit best-effort diagnostics without allowing logging failures to affect a run. */
+export function emitRunnerDiagnostic(sink: RunnerDiagnosticSink | undefined, event: RunnerDiagnosticEvent): void {
+	if (!sink) return;
+	try {
+		sink(event);
+	} catch {
+		// Diagnostics must never alter subagent execution or completion delivery.
+	}
+}
+
+export function appendRunnerDiagnostic(pi: Pick<ExtensionAPI, "appendEntry">, data: Record<string, unknown>): void {
+	try {
+		pi.appendEntry(RUNNER_DIAGNOSTIC_CUSTOM_TYPE, {
+			schemaVersion: RUNNER_DIAGNOSTIC_SCHEMA_VERSION,
+			recordedAt: new Date().toISOString(),
+			...data,
+		});
+	} catch {
+		// Session teardown may invalidate the old extension runtime.
+	}
+}
+
+export function createRunDiagnosticSink(
+	pi: Pick<ExtensionAPI, "appendEntry">,
+	runState: CommandRunState,
+): RunnerDiagnosticSink {
+	return (event) => {
+		appendRunnerDiagnostic(pi, {
+			runId: runState.id,
+			agent: runState.agent,
+			batchId: runState.batchId,
+			pipelineId: runState.pipelineId,
+			pipelineStepIndex: runState.pipelineStepIndex,
+			...event,
+			abortReason: serializeDiagnosticValue(event.abortReason),
+		});
+	};
+}

package/lifecycle.ts

@@ -7,6 +7,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { HANG_TIMEOUT_MS } from "./constants.js";
+import { appendRunnerDiagnostic } from "./diagnostics.js";
 import { getSessionFileMtimeMs, readPersistedSessionSnapshot } from "./persisted-session.js";
 import { getLastNonEmptyLine } from "./runner.js";
 import type { SubagentStore } from "./store.js";
@@ -59,6 +60,16 @@ export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, rea
 	for (const [runId, run] of store.commandRuns) activeRuns.set(runId, run);
 	for (const [runId, entry] of store.globalLiveRuns) activeRuns.set(runId, entry.runState);
 
+	const activeRunIds = Array.from(activeRuns)
+		.filter(([, run]) => run.status === "running")
+		.map(([runId]) => runId);
+	appendRunnerDiagnostic(pi, {
+		event: "session_shutdown",
+		parentPid: process.pid,
+		sessionShutdownReason: reason,
+		activeRunIds,
+	});
+
 	for (const [runId, run] of activeRuns) {
 		if (run.status !== "running") continue;
 		const message = `Aborted because the parent pi session ${reason} is shutting down.`;
@@ -70,7 +81,7 @@ export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, rea
 		run.removed = true;
 
 		const controller = run.abortController ?? store.globalLiveRuns.get(runId)?.abortController;
-		controller?.abort();
+		controller?.abort({ source: "session_shutdown", reason, runId, activeRunIds });
 		run.abortController = undefined;
 
 		if (run.deliveryMode === "humanOnly") continue;
@@ -141,7 +152,7 @@ export function checkForHungRuns(store: SubagentStore, _pi: ExtensionAPI): void
 		run.autoAbortReason = reason;
 
 		if (controller) {
-			controller.abort();
+			controller.abort({ source: "hang_timeout", runId, idleMs, reason });
 		}
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
     "config.ts",
     "constants.ts",
     "context-limits.ts",
+    "diagnostics.ts",
     "display-task.ts",
     "escalation.ts",
     "format.ts",

package/run-utils.ts

@@ -92,7 +92,7 @@ export function removeRun(store: SubagentStore, runId: number, options: RemoveRu
 		const reason = options.reason ?? "Aborting by remove...";
 		run.lastLine = reason;
 		run.lastOutput = reason;
-		controller.abort();
+		controller.abort({ source: "remove_run", runId, reason, removalReason: options.removalReason });
 		aborted = true;
 	}
 

package/runner.ts

@@ -17,6 +17,13 @@ import {
 } from "./claude-stream-parser.js";
 import { resolveClaudeRuntimeMode } from "./config.js";
 import { CONTEXT_GUARD_SIGNATURE, resolveContextGuardCeiling, shouldTripContextGuard } from "./context-limits.js";
+import {
+	emitRunnerDiagnostic,
+	type RunnerDiagnosticSink,
+	readProcessIdentity,
+	serializeDiagnosticValue,
+	toDiagnosticError,
+} from "./diagnostics.js";
 import { formatToolCallPlain } from "./format.js";
 import {
 	extractActivityPreviewFromTextDelta,
@@ -39,6 +46,7 @@ export interface RunSingleAgentSessionConfig {
 	resumeSessionId?: string;
 	sidecarSessionFile?: string;
 	persistedSessionBaseOffset?: number;
+	onDiagnostic?: RunnerDiagnosticSink;
 }
 
 function isUuidLikeSessionId(value: string | undefined): boolean {
@@ -199,6 +207,7 @@ export async function runSingleAgent(
 	const resumeSessionId = normalizedSessionConfig.resumeSessionId;
 	const sidecarSessionFile = normalizedSessionConfig.sidecarSessionFile ?? sessionFile;
 	const persistedSessionBaseOffset = normalizedSessionConfig.persistedSessionBaseOffset ?? 0;
+	const onDiagnostic = normalizedSessionConfig.onDiagnostic;
 	const agent = agents.find((a) => a.name === agentName);
 
 	if (!agent) {
@@ -240,6 +249,7 @@ export async function runSingleAgent(
 			makeDetails,
 			resumeSessionId,
 			sidecarSessionFile,
+			onDiagnostic,
 		);
 	}
 
@@ -254,6 +264,7 @@ export async function runSingleAgent(
 		makeDetails,
 		sessionFile,
 		persistedSessionBaseOffset,
+		onDiagnostic,
 	);
 }
 
@@ -267,6 +278,7 @@ async function runClaudeAgent(
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
 	resumeSessionId?: string,
 	sidecarSessionFile?: string,
+	onDiagnostic?: RunnerDiagnosticSink,
 ): Promise<SingleResult> {
 	try {
 		validateClaudeRuntimeModel(agent.model);
@@ -315,6 +327,10 @@ async function runClaudeAgent(
 	let completionMarkerWritten = false;
 	let wasAborted = false;
 
+	const diagnose = (event: Parameters<RunnerDiagnosticSink>[0]) => {
+		emitRunnerDiagnostic(onDiagnostic, { runtime: "claude", ...event });
+	};
+
 	const emitUpdate = () => {
 		if (!onUpdate) return;
 		const text = streamState.liveText ?? getFinalOutput(streamState.messages) ?? "(running...)";
@@ -362,9 +378,57 @@ async function runClaudeAgent(
 			let exitFallbackTimer: ReturnType<typeof setTimeout> | undefined;
 			let resultLingerTimer: ReturnType<typeof setTimeout> | undefined;
 			let lastExitCode = 0;
+			let lastProcessSignal: NodeJS.Signals | null = null;
 			let settleReason = "unknown";
 			let unparsedStdoutCount = 0;
 			const unparsedStdoutTail: string[] = [];
+			const parentIdentity = onDiagnostic ? readProcessIdentity(process.pid) : undefined;
+			const childIdentity = onDiagnostic ? readProcessIdentity(proc.pid) : undefined;
+
+			diagnose({
+				event: "spawn",
+				parentPid: process.pid,
+				parentProcessGroupId: parentIdentity?.processGroupId,
+				childPid: proc.pid,
+				childParentPid: childIdentity?.parentPid,
+				childProcessGroupId: childIdentity?.processGroupId,
+				processGroupMode: "inherited",
+			});
+
+			const terminateProcess = (terminationSignal: NodeJS.Signals, cause: string): boolean => {
+				diagnose({
+					event: "kill_intent",
+					childPid: proc.pid,
+					signal: terminationSignal,
+					cause,
+					stopReason: streamState.stopReason,
+				});
+				try {
+					const killSent = proc.kill(terminationSignal);
+					diagnose({
+						event: "kill_result",
+						childPid: proc.pid,
+						signal: terminationSignal,
+						cause,
+						killSent,
+					});
+					return killSent;
+				} catch (error) {
+					diagnose({
+						event: "process_error",
+						childPid: proc.pid,
+						cause: `kill:${cause}`,
+						error: toDiagnosticError(error),
+					});
+					return false;
+				}
+			};
+
+			const scheduleKillEscalation = (cause: string) => {
+				setTimeout(() => {
+					if (!procExited && proc.exitCode === null) terminateProcess("SIGKILL", `${cause}:grace_timeout`);
+				}, 5000);
+			};
 
 			const processLine = (line: string) => {
 				if (!line.trim()) return;
@@ -440,6 +504,14 @@ async function runClaudeAgent(
 						stderrBuf += `[runner] ${tail}\n`;
 					}
 				}
+				diagnose({
+					event: "settled",
+					childPid: proc.pid,
+					code: finalCode,
+					signal: lastProcessSignal,
+					settleReason,
+					stopReason: wasAborted ? "aborted" : streamState.stopReason,
+				});
 				resolve(finalCode);
 			};
 
@@ -452,10 +524,8 @@ async function runClaudeAgent(
 				if (resultLingerTimer) clearTimeout(resultLingerTimer);
 				resultLingerTimer = setTimeout(() => {
 					if (settled || procExited) return;
-					proc.kill("SIGTERM");
-					setTimeout(() => {
-						if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-					}, 5000);
+					terminateProcess("SIGTERM", "result_linger_timeout");
+					scheduleKillEscalation("result_linger_timeout");
 					settleReason = "result_linger_timeout";
 					resolveOnce(0);
 				}, 3000);
@@ -472,9 +542,11 @@ async function runClaudeAgent(
 				stderrBuf += data.toString();
 			});
 
-			proc.on("exit", (code) => {
+			proc.on("exit", (code, terminationSignal) => {
 				procExited = true;
 				lastExitCode = code ?? 0;
+				lastProcessSignal = terminationSignal;
+				diagnose({ event: "exit", childPid: proc.pid, code, signal: terminationSignal });
 				if (streamState.resultReceived) {
 					settleReason = "exit_after_result";
 					resolveOnce(0);
@@ -486,8 +558,10 @@ async function runClaudeAgent(
 				}, 1500);
 			});
 
-			proc.on("close", (code) => {
+			proc.on("close", (code, terminationSignal) => {
 				procExited = true;
+				lastProcessSignal = terminationSignal ?? lastProcessSignal;
+				diagnose({ event: "close", childPid: proc.pid, code, signal: terminationSignal });
 				if (!settled) {
 					settleReason = "close";
 					resolveOnce(streamState.resultReceived ? 0 : (code ?? lastExitCode ?? 0));
@@ -497,6 +571,12 @@ async function runClaudeAgent(
 			proc.on("error", (error) => {
 				procExited = true;
 				stderrBuf += `[runner] process error: ${error?.message || String(error)}\n`;
+				diagnose({
+					event: "process_error",
+					childPid: proc.pid,
+					cause: "child_process_event",
+					error: toDiagnosticError(error),
+				});
 				settleReason = "process_error";
 				resolveOnce(1);
 			});
@@ -505,10 +585,13 @@ async function runClaudeAgent(
 				const killProc = () => {
 					wasAborted = true;
 					settleReason = "aborted_by_signal";
-					proc.kill("SIGTERM");
-					setTimeout(() => {
-						if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-					}, 5000);
+					diagnose({
+						event: "abort_received",
+						childPid: proc.pid,
+						abortReason: serializeDiagnosticValue(signal.reason),
+					});
+					terminateProcess("SIGTERM", "abort_signal");
+					scheduleKillEscalation("abort_signal");
 				};
 				if (signal.aborted) killProc();
 				else signal.addEventListener("abort", killProc, { once: true });
@@ -549,6 +632,7 @@ async function runPiAgent(
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
 	sessionFile?: string,
 	persistedSessionBaseOffset = 0,
+	onDiagnostic?: RunnerDiagnosticSink,
 ): Promise<SingleResult> {
 	const args: string[] = ["--mode", "json", "-p"];
 	if (sessionFile) args.push("--session", sessionFile);
@@ -578,6 +662,10 @@ async function runPiAgent(
 	let contextGuardTripped = false;
 	let peakContextTokens = 0;
 
+	const diagnose = (event: Parameters<RunnerDiagnosticSink>[0]) => {
+		emitRunnerDiagnostic(onDiagnostic, { runtime: "pi", ...event });
+	};
+
 	const emitUpdate = () => {
 		if (onUpdate) {
 			onUpdate({
@@ -617,11 +705,59 @@ async function runPiAgent(
 			let terminalMessageFallbackTimer: ReturnType<typeof setTimeout> | undefined;
 			let sessionPollTimer: ReturnType<typeof setInterval> | undefined;
 			let lastExitCode = 0;
+			let lastProcessSignal: NodeJS.Signals | null = null;
 			let lastEventAt = Date.now();
 			let sawAgentEnd = false;
 			let settleReason = "unknown";
 			let unparsedStdoutCount = 0;
 			const unparsedStdoutTail: string[] = [];
+			const parentIdentity = onDiagnostic ? readProcessIdentity(process.pid) : undefined;
+			const childIdentity = onDiagnostic ? readProcessIdentity(proc.pid) : undefined;
+
+			diagnose({
+				event: "spawn",
+				parentPid: process.pid,
+				parentProcessGroupId: parentIdentity?.processGroupId,
+				childPid: proc.pid,
+				childParentPid: childIdentity?.parentPid,
+				childProcessGroupId: childIdentity?.processGroupId,
+				processGroupMode: "inherited",
+			});
+
+			const terminateProcess = (terminationSignal: NodeJS.Signals, cause: string): boolean => {
+				diagnose({
+					event: "kill_intent",
+					childPid: proc.pid,
+					signal: terminationSignal,
+					cause,
+					stopReason: currentResult.stopReason,
+				});
+				try {
+					const killSent = proc.kill(terminationSignal);
+					diagnose({
+						event: "kill_result",
+						childPid: proc.pid,
+						signal: terminationSignal,
+						cause,
+						killSent,
+					});
+					return killSent;
+				} catch (error) {
+					diagnose({
+						event: "process_error",
+						childPid: proc.pid,
+						cause: `kill:${cause}`,
+						error: toDiagnosticError(error),
+					});
+					return false;
+				}
+			};
+
+			const scheduleKillEscalation = (cause: string) => {
+				setTimeout(() => {
+					if (!procExited && proc.exitCode === null) terminateProcess("SIGKILL", `${cause}:grace_timeout`);
+				}, 5000);
+			};
 
 			const syncFromPersistedSession = (allowResolve: boolean): boolean => {
 				if (!sessionFile) return false;
@@ -640,11 +776,12 @@ async function runPiAgent(
 					snapshot.completionMarker?.exitCode ??
 					(snapshot.terminalStopReason === "error" || snapshot.terminalStopReason === "aborted" ? 1 : 0);
 				writeCompletionMarkerOnce(forcedCode);
-				proc.kill("SIGTERM");
-				setTimeout(() => {
-					if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-				}, 5000);
-				settleReason = snapshot.completionMarker ? "session_done_marker_fallback" : "session_terminal_message_fallback";
+				const fallbackReason = snapshot.completionMarker
+					? "session_done_marker_fallback"
+					: "session_terminal_message_fallback";
+				terminateProcess("SIGTERM", fallbackReason);
+				scheduleKillEscalation(fallbackReason);
+				settleReason = fallbackReason;
 				resolveOnce(forcedCode);
 				return true;
 			};
@@ -776,10 +913,8 @@ async function runPiAgent(
 							currentResult.errorMessage =
 								`${CONTEXT_GUARD_SIGNATURE} stopped at ${peakContextTokens} tokens ` +
 								`(ceiling ${contextGuardCeiling}) to preserve partial findings before provider context overflow.`;
-							proc.kill("SIGTERM");
-							setTimeout(() => {
-								if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-							}, 5000);
+							terminateProcess("SIGTERM", "context_guard");
+							scheduleKillEscalation("context_guard");
 							settleReason = "context_guard";
 							resolveOnce(1);
 							return;
@@ -858,6 +993,14 @@ async function runPiAgent(
 						);
 					}
 				}
+				diagnose({
+					event: "settled",
+					childPid: proc.pid,
+					code: finalCode,
+					signal: lastProcessSignal,
+					settleReason,
+					stopReason: wasAborted ? "aborted" : currentResult.stopReason,
+				});
 				resolve(finalCode);
 			};
 
@@ -870,10 +1013,8 @@ async function runPiAgent(
 
 					const forcedCode = currentResult.stopReason === "error" || currentResult.stopReason === "aborted" ? 1 : 0;
 
-					proc.kill("SIGTERM");
-					setTimeout(() => {
-						if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-					}, 5000);
+					terminateProcess("SIGTERM", "terminal_message_fallback_timeout");
+					scheduleKillEscalation("terminal_message_fallback_timeout");
 
 					settleReason = "terminal_message_fallback_timeout";
 					resolveOnce(forcedCode);
@@ -894,10 +1035,8 @@ async function runPiAgent(
 
 					const forcedCode = currentResult.stopReason === "error" || currentResult.stopReason === "aborted" ? 1 : 0;
 
-					proc.kill("SIGTERM");
-					setTimeout(() => {
-						if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-					}, 5000);
+					terminateProcess("SIGTERM", "agent_end_fallback_timeout");
+					scheduleKillEscalation("agent_end_fallback_timeout");
 
 					settleReason = "agent_end_fallback_timeout";
 					resolveOnce(forcedCode);
@@ -921,9 +1060,11 @@ async function runPiAgent(
 				currentResult.stderr += data.toString();
 			});
 
-			proc.on("exit", (code) => {
+			proc.on("exit", (code, terminationSignal) => {
 				procExited = true;
 				lastExitCode = code ?? 0;
+				lastProcessSignal = terminationSignal;
+				diagnose({ event: "exit", childPid: proc.pid, code, signal: terminationSignal });
 				// In rare cases stdout/stderr pipes may stay open after process exit.
 				// Use a short fallback so runs cannot stay "running" forever.
 				exitFallbackTimer = setTimeout(() => {
@@ -932,8 +1073,10 @@ async function runPiAgent(
 				}, 1500);
 			});
 
-			proc.on("close", (code) => {
+			proc.on("close", (code, terminationSignal) => {
 				procExited = true;
+				lastProcessSignal = terminationSignal ?? lastProcessSignal;
+				diagnose({ event: "close", childPid: proc.pid, code, signal: terminationSignal });
 				settleReason = "close";
 				resolveOnce(code ?? lastExitCode ?? 0);
 			});
@@ -941,6 +1084,12 @@ async function runPiAgent(
 			proc.on("error", (error) => {
 				procExited = true;
 				appendStderrDiagnostic(currentResult, `process error: ${error?.message || String(error)}`);
+				diagnose({
+					event: "process_error",
+					childPid: proc.pid,
+					cause: "child_process_event",
+					error: toDiagnosticError(error),
+				});
 				settleReason = "process_error";
 				resolveOnce(1);
 			});
@@ -949,10 +1098,13 @@ async function runPiAgent(
 				const killProc = () => {
 					wasAborted = true;
 					settleReason = "aborted_by_signal";
-					proc.kill("SIGTERM");
-					setTimeout(() => {
-						if (!procExited && proc.exitCode === null) proc.kill("SIGKILL");
-					}, 5000);
+					diagnose({
+						event: "abort_received",
+						childPid: proc.pid,
+						abortReason: serializeDiagnosticValue(signal.reason),
+					});
+					terminateProcess("SIGTERM", "abort_signal");
+					scheduleKillEscalation("abort_signal");
 				};
 				if (signal.aborted) killProc();
 				else signal.addEventListener("abort", killProc, { once: true });

package/tool-execute.ts

@@ -22,6 +22,7 @@ import {
 	SUBAGENT_STRONG_WAIT_MESSAGE,
 } from "./constants.js";
 import { isContextOverflowText } from "./context-limits.js";
+import { createRunDiagnosticSink } from "./diagnostics.js";
 import {
 	buildSubagentDisplayTaskFallback,
 	createDisplayTaskRefreshToken,
@@ -956,7 +957,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 
 					run.lastLine = "Aborting by subagent tool...";
 					run.lastOutput = run.lastLine;
-					abortCtrl.abort();
+					abortCtrl.abort({ source: "subagent_tool_abort", runId });
 					aborting.push(runId);
 				}
 
@@ -1080,7 +1081,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 			clearParentAbortListener(runId);
 			if (!signal || shouldRunAsync) return;
 
-			const abortFromParent = () => abortController.abort();
+			const abortFromParent = () => abortController.abort({ source: "parent_tool_abort", runId });
 			if (signal.aborted) {
 				abortFromParent();
 				return;
@@ -1201,6 +1202,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 						resumeSessionId: runState.claudeSessionId,
 						sidecarSessionFile: runState.sessionFile,
 						persistedSessionBaseOffset: runState.persistedSessionBaseOffset,
+						onDiagnostic: createRunDiagnosticSink(pi, runState),
 					},
 				),
 			).then((result) => finalizeRunState(runState, result));