@ryan_nookpi/pi-extension-subagent 0.3.0 → 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,
@@ -42,6 +43,7 @@ import {
 } from "./group-pending.js";
 import { enqueueSubagentInvocation } from "./invocation-queue.js";
 import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session.js";
+import { SUBAGENT_COMMANDS, type SubagentCommandName } from "./registration-manifest.js";
 import { readSessionReplayItems, SubagentSessionReplayOverlay } from "./replay.js";
 import { invokeWithAutoRetry, MAX_SUBAGENT_AUTO_RETRIES } from "./retry.js";
 import { getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
@@ -890,7 +892,18 @@ function finalizeHumanOnlyCompletion(
 	store.globalLiveRuns.delete(runId);
 }
 
-export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
+export type SubagentCommandDefinition = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+export interface SubagentRegistrations {
+	commands: ReadonlyMap<SubagentCommandName, SubagentCommandDefinition>;
+}
+
+export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentRegistrations {
+	const commandDefinitions = new Map<SubagentCommandName, SubagentCommandDefinition>();
+	const defineCommand = (name: SubagentCommandName, definition: SubagentCommandDefinition): void => {
+		commandDefinitions.set(name, definition);
+	};
+
 	pi.registerTool({
 		name: "list-agents",
 		label: "List Agents",
@@ -958,8 +971,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	const subCommand = {
-		description:
-			"Run a subagent in a dedicated sub-session: /sub:isolate <agent|alias> <task>, /sub:isolate <runId> <task>, /sub:isolate <task> (uses configured defaultAgent)",
+		description: SUBAGENT_COMMANDS["sub:isolate"],
 		getArgumentCompletions: (argumentPrefix: string) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1423,6 +1435,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 										resumeSessionId: runState.claudeSessionId,
 										sidecarSessionFile: runState.sessionFile,
 										persistedSessionBaseOffset: runState.persistedSessionBaseOffset,
+										onDiagnostic: createRunDiagnosticSink(pi, runState),
 									},
 								),
 							);
@@ -1574,10 +1587,10 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	};
 
-	pi.registerCommand("sub:isolate", subCommand);
+	defineCommand("sub:isolate", subCommand);
 
-	pi.registerCommand("sub:main", {
-		description: "Run a subagent with main-session context inheritance: /sub:main <agent|alias> <task>",
+	defineCommand("sub:main", {
+		description: SUBAGENT_COMMANDS["sub:main"],
 		getArgumentCompletions: subCommand.getArgumentCompletions,
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
@@ -1586,8 +1599,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("subagents", {
-		description: "List available subagents and offer the starter pack when none are configured",
+	defineCommand("subagents", {
+		description: SUBAGENT_COMMANDS.subagents,
 		handler: async (_args, ctx) => {
 			captureSwitchSession(store, ctx);
 			const starterPack = await offerStarterPackIfEmpty(ctx);
@@ -1619,8 +1632,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:peek", {
-		description: "Show the latest response from a subagent in an overlay: /sub:peek [runId]",
+	defineCommand("sub:peek", {
+		description: SUBAGENT_COMMANDS["sub:peek"],
 		getArgumentCompletions: (argumentPrefix) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1643,8 +1656,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:open", {
-		description: "Open a subagent session replay overlay: /sub:open [runId]",
+	defineCommand("sub:open", {
+		description: SUBAGENT_COMMANDS["sub:open"],
 		getArgumentCompletions: (argumentPrefix) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1735,8 +1748,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:history", {
-		description: "Show all subagent run history (including removed) in an overlay: /sub:history",
+	defineCommand("sub:history", {
+		description: SUBAGENT_COMMANDS["sub:history"],
 		handler: async (_args, ctx) => {
 			captureSwitchSession(store, ctx);
 
@@ -1787,8 +1800,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:rm", {
-		description: "Remove one /sub job entry (aborts it if running): /sub:rm [runId]",
+	defineCommand("sub:rm", {
+		description: SUBAGENT_COMMANDS["sub:rm"],
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
 			const raw = (args ?? "").trim();
@@ -1871,8 +1884,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify(`Cleared ${removed} finished subagent job(s).`, "info");
 	};
 
-	pi.registerCommand("sub:clear", {
-		description: "Clear /sub job widget entries. /sub:clear (finished only) or /sub:clear all",
+	defineCommand("sub:clear", {
+		description: SUBAGENT_COMMANDS["sub:clear"],
 		handler: async (args, ctx) => {
 			await handleSubClear(args, ctx);
 		},
@@ -1896,7 +1909,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 			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;
 		};
 
@@ -1947,23 +1960,16 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify("Usage: /sub:abort [runId|all]", "info");
 	};
 
-	pi.registerCommand("sub:abort", {
-		description: "Abort running subagent job(s). /sub:abort [runId|all]",
+	defineCommand("sub:abort", {
+		description: SUBAGENT_COMMANDS["sub:abort"],
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
 			await handleSubAbort(args, ctx);
 		},
 	});
 
-	// Only actual keyboard shortcuts appear in the /hotkeys Extensions section.
-	// NOTE: plain ">" is a real keybinding and hijacks editor text input,
-	// so the hidden subagent prefix is documented via footer/status hints instead.
-	pi.registerShortcut(">>" as any, {
-		description: "Run subagent task",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
+	// Text-prefix shortcuts are registered synchronously in index.ts for
+	// /hotkeys visibility. Their actual routing remains in the input handlers below.
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
@@ -2073,13 +2079,6 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	// #<runId> shortcut: resume a subagent run (e.g. #42 keep going)
-	pi.registerShortcut("#<runId>" as any, {
-		description: "Resume subagent run: #<runId> <task>",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
 			return { action: "continue" as const };
@@ -2126,20 +2125,6 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	// << shortcut: abort running jobs or clear finished jobs
-	pi.registerShortcut("<<" as any, {
-		description: "Abort or clear subagent runs",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
-	pi.registerShortcut("<<<" as any, {
-		description: "Clear finished subagent jobs (= /sub:clear). <<< all to clear all",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
 			return { action: "continue" as const };
@@ -2204,7 +2189,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 			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, {
@@ -2226,6 +2211,15 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify(parts.join(", ") || "Nothing to do.", parts.length ? (aborted ? "warning" : "info") : "info");
 		return { action: "handled" as const };
 	});
+
+	const missingCommands = (Object.keys(SUBAGENT_COMMANDS) as SubagentCommandName[]).filter(
+		(name) => !commandDefinitions.has(name),
+	);
+	if (missingCommands.length > 0) {
+		throw new Error(`Missing subagent command definitions: ${missingCommands.join(", ")}`);
+	}
+
+	return { commands: commandDefinitions };
 }
 
 // ── onTerminalInput hack: auto-redirect <>7 to /sub:peek 7 ───────────

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

@@ -29,10 +29,12 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { HANG_CHECK_INTERVAL_MS } from "./constants.js";
+import { SUBAGENT_COMMANDS, SUBAGENT_SHORTCUTS, type SubagentCommandName } from "./registration-manifest.js";
 
 interface SubagentCore {
 	store: import("./store.js").SubagentStore;
 	commands: typeof import("./commands.js");
+	registrations: import("./commands.js").SubagentRegistrations;
 	escalation: typeof import("./escalation.js");
 	lifecycle: typeof import("./lifecycle.js");
 }
@@ -52,10 +54,13 @@ export default function (pi: ExtensionAPI) {
 				import("./store.js"),
 			]);
 			const store = storeMod.createStore();
-			commands.registerAll(pi, store);
-			core = { store, commands, escalation, lifecycle };
+			const registrations = commands.registerAll(pi, store);
+			core = { store, commands, registrations, escalation, lifecycle };
 			return core;
-		})();
+		})().catch((error) => {
+			corePromise = null;
+			throw error;
+		});
 		return corePromise;
 	};
 
@@ -69,6 +74,39 @@ export default function (pi: ExtensionAPI) {
 		return chain;
 	};
 
+	const getCommandDefinition = async (name: SubagentCommandName) => {
+		const loaded = await loadCore();
+		await chain;
+		const definition = loaded.registrations.commands.get(name);
+		if (!definition) throw new Error(`Subagent command definition not found: ${name}`);
+		return definition;
+	};
+
+	// Register lightweight proxies synchronously so Pi's initial autocomplete
+	// and command registry contain every subagent command before lazy core load.
+	for (const [name, description] of Object.entries(SUBAGENT_COMMANDS) as Array<[SubagentCommandName, string]>) {
+		pi.registerCommand(name, {
+			description,
+			getArgumentCompletions: async (prefix) => {
+				const definition = await getCommandDefinition(name);
+				return definition.getArgumentCompletions?.(prefix) ?? null;
+			},
+			handler: async (args, ctx) => {
+				const definition = await getCommandDefinition(name);
+				return definition.handler(args, ctx);
+			},
+		});
+	}
+
+	// These entries document text-prefix shortcuts in /hotkeys. Actual routing
+	// remains in commands.ts input handlers after the lazy core is loaded.
+	for (const [shortcut, description] of Object.entries(SUBAGENT_SHORTCUTS)) {
+		pi.registerShortcut(shortcut as never, {
+			description,
+			handler: async () => {},
+		});
+	}
+
 	// Start loading in the background without blocking extension boot.
 	// setTimeout keeps the load out of the boot path's microtask drains.
 	setTimeout(() => {

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,98 +1,100 @@
 {
-	"name": "@ryan_nookpi/pi-extension-subagent",
-	"version": "0.3.0",
-	"description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Jonghakseo/pi-extension.git",
-		"directory": "packages/subagent"
-	},
-	"bugs": {
-		"url": "https://github.com/Jonghakseo/pi-extension/issues"
-	},
-	"homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
-	"type": "module",
-	"keywords": [
-		"pi-package",
-		"subagent",
-		"delegation"
-	],
-	"files": [
-		"above-widget.ts",
-		"agents.ts",
-		"claude-args.ts",
-		"claude-sdk-runner.ts",
-		"claude-sdk-stream-adapter.ts",
-		"claude-sidecar-writer.ts",
-		"claude-stream-parser.ts",
-		"cli.ts",
-		"commands.ts",
-		"config.ts",
-		"constants.ts",
-		"context-limits.ts",
-		"display-task.ts",
-		"escalation.ts",
-		"format.ts",
-		"group-pending.ts",
-		"index.ts",
-		"lifecycle.ts",
-		"invocation-queue.ts",
-		"live-preview.ts",
-		"persisted-session.ts",
-		"replay.ts",
-		"retry.ts",
-		"run-utils.ts",
-		"runner.ts",
-		"session.ts",
-		"starter-pack.ts",
-		"store.ts",
-		"tool-execute.ts",
-		"tool-render.ts",
-		"types.ts",
-		"widget.ts",
-		"utils/agent-utils.ts",
-		"utils/short-label.ts",
-		"utils/string-utils.ts",
-		"utils/format-utils.ts",
-		"utils/time-utils.ts",
-		"seeds",
-		"README.md"
-	],
-	"pi": {
-		"extensions": [
-			"./index.ts"
-		]
-	},
-	"dependencies": {
-		"@anthropic-ai/claude-agent-sdk": "^0.2.98",
-		"yaml": "^2.9.0"
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-agent-core": "*",
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
-		"typebox": "*"
-	},
-	"peerDependenciesMeta": {
-		"@earendil-works/pi-ai": {
-			"optional": true
-		},
-		"@earendil-works/pi-agent-core": {
-			"optional": true
-		},
-		"@earendil-works/pi-coding-agent": {
-			"optional": true
-		},
-		"@earendil-works/pi-tui": {
-			"optional": true
-		},
-		"typebox": {
-			"optional": true
-		}
-	},
-	"publishConfig": {
-		"access": "public"
-	}
-}
+  "name": "@ryan_nookpi/pi-extension-subagent",
+  "version": "0.3.2",
+  "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jonghakseo/pi-extension.git",
+    "directory": "packages/subagent"
+  },
+  "bugs": {
+    "url": "https://github.com/Jonghakseo/pi-extension/issues"
+  },
+  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "subagent",
+    "delegation"
+  ],
+  "files": [
+    "above-widget.ts",
+    "agents.ts",
+    "claude-args.ts",
+    "claude-sdk-runner.ts",
+    "claude-sdk-stream-adapter.ts",
+    "claude-sidecar-writer.ts",
+    "claude-stream-parser.ts",
+    "cli.ts",
+    "commands.ts",
+    "config.ts",
+    "constants.ts",
+    "context-limits.ts",
+    "diagnostics.ts",
+    "display-task.ts",
+    "escalation.ts",
+    "format.ts",
+    "group-pending.ts",
+    "index.ts",
+    "lifecycle.ts",
+    "invocation-queue.ts",
+    "live-preview.ts",
+    "persisted-session.ts",
+    "replay.ts",
+    "registration-manifest.ts",
+    "retry.ts",
+    "run-utils.ts",
+    "runner.ts",
+    "session.ts",
+    "starter-pack.ts",
+    "store.ts",
+    "tool-execute.ts",
+    "tool-render.ts",
+    "types.ts",
+    "widget.ts",
+    "utils/agent-utils.ts",
+    "utils/short-label.ts",
+    "utils/string-utils.ts",
+    "utils/format-utils.ts",
+    "utils/time-utils.ts",
+    "seeds",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.98",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/registration-manifest.ts

@@ -0,0 +1,23 @@
+export const SUBAGENT_COMMANDS = {
+	"sub:isolate":
+		"Run a subagent in a dedicated sub-session: /sub:isolate <agent|alias> <task>, /sub:isolate <runId> <task>, /sub:isolate <task> (uses configured defaultAgent)",
+	"sub:main": "Run a subagent with main-session context inheritance: /sub:main <agent|alias> <task>",
+	subagents: "List available subagents and offer the starter pack when none are configured",
+	"sub:peek": "Show the latest response from a subagent in an overlay: /sub:peek [runId]",
+	"sub:open": "Open a subagent session replay overlay: /sub:open [runId]",
+	"sub:history": "Show all subagent run history (including removed) in an overlay: /sub:history",
+	"sub:rm": "Remove one /sub job entry (aborts it if running): /sub:rm [runId]",
+	"sub:clear": "Clear /sub job widget entries. /sub:clear (finished only) or /sub:clear all",
+	"sub:abort": "Abort running subagent job(s). /sub:abort [runId|all]",
+} as const;
+
+export type SubagentCommandName = keyof typeof SUBAGENT_COMMANDS;
+
+export const SUBAGENT_SHORTCUTS = {
+	">>": "Run subagent task",
+	"#<runId>": "Resume subagent run: #<runId> <task>",
+	"<<": "Abort or clear subagent runs",
+	"<<<": "Clear finished subagent jobs (= /sub:clear). <<< all to clear all",
+} as const;
+
+export type SubagentShortcutName = keyof typeof SUBAGENT_SHORTCUTS;

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));