@yusukeshib/pi-babysit 0.3.7 → 0.3.9

package/README.md

@@ -32,7 +32,7 @@ reachable from anywhere (`~/.pi-babysit/<pi-session-id>/`). Two kinds:
 
 | kind | started by | completion | on completion |
 | ---- | ---------- | ---------- | ------------- |
-| **process** | `babysit_run { command }` | process **exit** | automatic notification message (`triggerTurn`) — the agent may end its turn after starting and is resumed on exit, same contract as the old `process` tool |
+| **process** | `babysit_run { command }` | process **exit** | automatic notification message (`triggerTurn`), batched for all exits observed in the same poll — the agent may end its turn after starting and is resumed on exit, same contract as the old `process` tool |
 | **subagent** | `babysit_run { profile: "subagent", task }` | `agent_end` in the RPC event stream (process stays alive) | none — the agent polls `babysit_check` or blocks on `babysit_wait`; the idle session accepts follow-up tasks |
 
 The **profile is a tool parameter, not a separate tool set**: domain knowledge
@@ -40,6 +40,13 @@ The **profile is a tool parameter, not a separate tool set**: domain knowledge
 message delivery, spawn validation) lives in code, while the LLM sees one small
 generic surface.
 
+Subagent recursion is **disabled by default**: a top-level pi may create workers
+(depth 1), but those workers cannot create more workers. A top-level caller can
+explicitly opt in for a specific tree with `maxDepth: 2` (or higher) when it
+creates the first worker. Descendants inherit that ceiling and cannot raise it.
+Normal `babysit_run { command }` process execution remains available at every
+depth.
+
 Because sessions are real PTYs, the agent can also **drive interactive
 programs** (installers, wizards, REPLs): type with `babysit_send`
 (text or named keys) and read the rendered screen with
@@ -49,7 +56,7 @@ programs** (installers, wizards, REPLs): type with `babysit_send`
 
 | Tool | What it does |
 | ---- | ------------ |
-| `babysit_run` | Run any command (`command`, optional `name`/`pty`/`timeout`/`idleTimeout`/`retryOnWorkerDeath`) or start a subagent (`profile: "subagent"`, `task`, optional `agent`/`model`/`tools`). Quick commands return inline; longer ones continue in the background |
+| `babysit_run` | Run any command (`command`, optional `name`/`pty`/`timeout`/`idleTimeout`/`retryOnWorkerDeath`) or start a subagent (`profile: "subagent"`, `task`, optional `agent`/`model`/`tools`/`maxDepth`). `maxDepth` defaults to 1 and can only be set by the top-level caller. Quick commands return inline; longer ones continue in the background |
 | `babysit_check` | List all sessions, inspect one, tail its bounded recent output, or search its raw log with `pattern`; `screen: true` captures TUIs and subagents otherwise show structured live progress |
 | `babysit_send` | Process: type `text` / press `keys` into the PTY. Subagent: steer mid-run, or send a follow-up task when idle (`mode: auto/steer/task`) |
 | `babysit_wait` | Block until done: process exit (or `expect: "regex"` readiness marker), subagent task completion. Multi-wait: `ids` + `mode: "any"\|"all"` |
@@ -72,9 +79,12 @@ A minimal widget above the editor shows live counts
 `babysit_run`, `babysit_wait`, and automatic completion notifications always
 return lifecycle metadata and the absolute path to the complete `output.log`.
 Explicit run/wait results inline complete output up to 8 KB; unsolicited
-completion notifications use a stricter 2 KB cap. Larger output stays out of
-model context. Inspect it through the session id without creating another shell
-session:
+completion notifications use a stricter 2 KB per-process output cap and an 8 KB
+aggregate message cap. Process exits observed in one poll share one message and
+trigger one agent turn. If even the compact summaries and log paths exceed the
+aggregate cap, the largest fitting prefix is delivered and the remainder stays
+pending for the next poll. Larger output stays out of model context. Inspect it
+through the session id without creating another shell session:
 
 ```text
 babysit_check { id: "cargo-test", lines: 50 }
@@ -100,9 +110,10 @@ because blindly rerunning an arbitrary command can duplicate side effects.
 ## How completion detection works
 
 - **Process**: a 2.5s poller watches for running→exited transitions and injects
-  one `pi.sendMessage(…, { triggerTurn: true, deliverAs: "steer" })` per ended
-  session (deduped via `meta/<id>.json`). `babysit_kill` and an exit already
-  reported by `babysit_wait` suppress the notification.
+  one `pi.sendMessage(…, { triggerTurn: true, deliverAs: "steer" })` containing
+  every deliverable exit observed in that poll (deduped via `meta/<id>.json`).
+  `babysit_kill` and an exit already reported by `babysit_wait` suppress the
+  notification.
 - **Subagent**: `babysit_wait` blocks on `babysit expect '"type":"agent_end"'`.
   An `agent_end` whose last message is a **parked** toolResult — a
   `babysit_run { command }` result carrying the `[notify-on-exit]` marker (or
@@ -126,8 +137,9 @@ rule, so a subagent waiting on a long build is never false-killed.
 | `PI_BABYSIT_REAP_AFTER` | `120s` | idle grace before a finished subagent self-exits (`off`/`none`/`0` disables) |
 | `PI_BABYSIT_TAIL_MAX_BYTES` | `8000` | cap for explicit log tails/screens returned by `babysit_check` |
 | `PI_BABYSIT_INLINE_OUTPUT_MAX_BYTES` | `8000` | cap for complete output in explicitly requested run/wait results |
-| `PI_BABYSIT_NOTIFY_OUTPUT_MAX_BYTES` | `2000` | smaller cap for unsolicited process-completion notifications (`0` omits all output) |
-| `PI_BABYSIT_NOTIFY_COMMAND_MAX_BYTES` | `240` | cap for the command preview in completion notifications |
+| `PI_BABYSIT_NOTIFY_OUTPUT_MAX_BYTES` | `2000` | per-process output cap for unsolicited completion notifications (`0` omits all output) |
+| `PI_BABYSIT_NOTIFY_COMMAND_MAX_BYTES` | `240` | cap for each command preview in completion notifications |
+| `PI_BABYSIT_NOTIFY_BATCH_MAX_BYTES` | `8000` | hard cap for one aggregated completion notification |
 | `PI_BABYSIT_ALLOW_BASH` | unset | set to `1` to bypass direct-Bash redirection (emergency escape hatch) |
 
 Requires `babysit` 0.13.0 or newer and `pi` on `PATH`. The extension does **not**

package/index.ts

@@ -52,6 +52,78 @@ let ROOT = ROOT_BASE;
 const PI_BIN = process.env.PI_BABYSIT_BIN ?? "pi";
 const BABYSIT_BIN = process.env.PI_BABYSIT_CLI ?? "babysit";
 const SHELL = process.env.SHELL ?? "sh";
+const SUBAGENT_DEPTH_ENV = "PI_BABYSIT_INTERNAL_SUBAGENT_DEPTH";
+const SUBAGENT_MAX_DEPTH_ENV = "PI_BABYSIT_INTERNAL_SUBAGENT_MAX_DEPTH";
+const DEFAULT_SUBAGENT_MAX_DEPTH = 1;
+
+export type SubagentSpawnPlan =
+	| { allowed: true; childDepth: number; maxDepth: number }
+	| { allowed: false; error: string };
+
+/**
+ * Plan a subagent spawn without letting an already-spawned worker raise its
+ * inherited recursion allowance. Depth 0 is the user-facing pi process; the
+ * first worker is depth 1 and is allowed by default, but that worker cannot
+ * create depth 2 unless its top-level parent explicitly opted in.
+ */
+export function planSubagentSpawn(
+	requestedMaxDepth?: number,
+	env: Record<string, string | undefined> = process.env,
+): SubagentSpawnPlan {
+	if (
+		requestedMaxDepth !== undefined &&
+		(!Number.isInteger(requestedMaxDepth) || requestedMaxDepth < 1)
+	) {
+		return { allowed: false, error: "`maxDepth` must be a positive integer." };
+	}
+
+	const rawDepth = env[SUBAGENT_DEPTH_ENV];
+	let currentDepth = 0;
+	if (rawDepth !== undefined) {
+		currentDepth = Number(rawDepth);
+		if (!Number.isInteger(currentDepth) || currentDepth < 0) {
+			return {
+				allowed: false,
+				error: `Invalid inherited subagent depth ${JSON.stringify(rawDepth)}; refusing to spawn recursively.`,
+			};
+		}
+	}
+
+	const nested = currentDepth > 0;
+	if (nested && requestedMaxDepth !== undefined) {
+		return {
+			allowed: false,
+			error:
+				`Nested subagents cannot override \`maxDepth\` (current depth ${currentDepth}). ` +
+				"Only the top-level parent may opt in when it creates the first subagent.",
+		};
+	}
+
+	let maxDepth = requestedMaxDepth ?? DEFAULT_SUBAGENT_MAX_DEPTH;
+	if (nested) {
+		const rawMaxDepth = env[SUBAGENT_MAX_DEPTH_ENV];
+		// Missing/corrupt inherited state fails closed at the current depth.
+		maxDepth = rawMaxDepth === undefined ? currentDepth : Number(rawMaxDepth);
+		if (!Number.isInteger(maxDepth) || maxDepth < currentDepth) {
+			return {
+				allowed: false,
+				error: `Invalid inherited max subagent depth ${JSON.stringify(rawMaxDepth)}; refusing to spawn recursively.`,
+			};
+		}
+	}
+
+	const childDepth = currentDepth + 1;
+	if (childDepth > maxDepth) {
+		return {
+			allowed: false,
+			error:
+				`Nested subagent creation is disabled at depth ${currentDepth}: spawning would reach depth ${childDepth}, ` +
+				`but the inherited maxDepth is ${maxDepth}. Have the top-level parent explicitly opt in with ` +
+				`babysit_run { profile: "subagent", task, maxDepth: ${childDepth} } when creating the first worker.`,
+		};
+	}
+	return { allowed: true, childDepth, maxDepth };
+}
 
 // Marker embedded in babysit_run's tool RESULT text for kind=process runs.
 // It is how "the turn parked awaiting a process-exit notification" is told
@@ -116,7 +188,11 @@ function normalizeSession(s: BsSession): BsSession {
 // long wait be interrupted (Ctrl-C) by killing the child.
 function bs(
 	args: string[],
-	opts: { cwd?: string; signal?: AbortSignal } = {},
+	opts: {
+		cwd?: string;
+		signal?: AbortSignal;
+		env?: Record<string, string | undefined>;
+	} = {},
 ): Promise<{ stdout: string; stderr: string; code: number }> {
 	return new Promise((resolve) => {
 		if (opts.signal?.aborted) {
@@ -125,7 +201,7 @@ function bs(
 		}
 		const child = spawn(BABYSIT_BIN, args, {
 			cwd: opts.cwd,
-			env: { ...process.env, BABYSIT_DIR: ROOT },
+			env: { ...process.env, ...opts.env, BABYSIT_DIR: ROOT },
 		});
 		let stdout = "";
 		let stderr = "";
@@ -295,6 +371,8 @@ interface Meta {
 	task?: string;
 	promptOffset?: number;
 	model?: string;
+	depth?: number;
+	maxDepth?: number;
 }
 
 const metaDir = () => path.join(ROOT, "meta");
@@ -317,6 +395,16 @@ function readMeta(id: string): Meta | null {
 	}
 }
 
+export function shouldDeliverProcessCompletion(
+	meta: {
+		kind: "process" | "subagent";
+		notified?: boolean;
+		notificationPaused?: boolean;
+	} | null,
+): meta is { kind: "process"; notified?: boolean; notificationPaused?: boolean } {
+	return meta?.kind === "process" && !meta.notified && !meta.notificationPaused;
+}
+
 const kindOf = (id: string): "process" | "subagent" => readMeta(id)?.kind ?? "process";
 
 // Compact elapsed formatting: "42s", "3m12s", "1h04m".
@@ -437,6 +525,7 @@ const TAIL_MAX_BYTES = byteLimitFromEnv("PI_BABYSIT_TAIL_MAX_BYTES", 8_000);
 const INLINE_OUTPUT_MAX_BYTES = byteLimitFromEnv("PI_BABYSIT_INLINE_OUTPUT_MAX_BYTES", 8_000);
 const NOTIFY_OUTPUT_MAX_BYTES = byteLimitFromEnv("PI_BABYSIT_NOTIFY_OUTPUT_MAX_BYTES", 2_000);
 const NOTIFY_COMMAND_MAX_BYTES = byteLimitFromEnv("PI_BABYSIT_NOTIFY_COMMAND_MAX_BYTES", 240);
+const NOTIFY_BATCH_MAX_BYTES = byteLimitFromEnv("PI_BABYSIT_NOTIFY_BATCH_MAX_BYTES", 8_000);
 const ANSWER_MAX_BYTES = 24_000; // subagent answers / error messages
 
 function clip(s: string, maxBytes = TAIL_MAX_BYTES): string {
@@ -560,6 +649,193 @@ export function summarizeNotificationCommand(command: string | undefined): strin
 	return `${prefix}…`;
 }
 
+type CompletionStatus = "success" | "failed" | "terminated";
+
+export interface ProcessCompletionNotice {
+	id: string;
+	exitCode: number | null | undefined;
+	success: boolean;
+	status: CompletionStatus;
+	runtime: string;
+	summary: string;
+	command: string | undefined;
+	logPath: string;
+	output: string;
+}
+
+interface ProcessCompletionMessage {
+	customType: "pi-babysit-process-end";
+	content: string;
+	display: true;
+	details: {
+		id?: string;
+		exitCode?: number | null;
+		success: boolean;
+		status: CompletionStatus;
+		runtime?: string;
+		logPath?: string;
+		count: number;
+		totalCount: number;
+		remainingCount: number;
+		processes: Array<{
+			id: string;
+			exitCode: number | null | undefined;
+			success: boolean;
+			status: CompletionStatus;
+			runtime: string;
+			logPath: string;
+		}>;
+	};
+}
+
+const COMPLETION_FOOTER =
+	"Automatic completion notification. Inspect the bounded log with babysit_check only if needed.";
+const AGGREGATE_OUTPUT_OMISSION = "\nOutput omitted from aggregate notification; inspect log.";
+
+function truncateUtf8End(value: string, maxBytes: number): string {
+	if (maxBytes <= 0) return "";
+	const bytes = Buffer.from(value, "utf8");
+	if (bytes.length <= maxBytes) return value;
+	const suffix = Buffer.from("…", "utf8");
+	if (maxBytes <= suffix.length) return ".".repeat(maxBytes);
+	const prefix = bytes
+		.subarray(0, maxBytes - suffix.length)
+		.toString("utf8")
+		.replace(/\uFFFD+$/, "");
+	return `${prefix}…`;
+}
+
+/** Build one bounded message for as many deliverable completions as fit. */
+export function buildProcessCompletionMessage(
+	notices: ProcessCompletionNotice[],
+	maxBytes = NOTIFY_BATCH_MAX_BYTES,
+): ProcessCompletionMessage {
+	if (notices.length === 0) throw new Error("At least one completion notice is required.");
+
+	const totalCount = notices.length;
+	const footer = `\n\n${COMPLETION_FOOTER}`;
+	const header = (count: number) =>
+		totalCount === 1
+			? ""
+			: count === totalCount
+				? `${count} processes completed:\n\n`
+				: `${count} of ${totalCount} processes completed:\n\n`;
+	const deferred = (count: number) =>
+		count < totalCount
+			? `\n\n${totalCount - count} completion${totalCount - count === 1 ? "" : "s"} deferred to the next poll.`
+			: "";
+	const renderCompact = (batch: ProcessCompletionNotice[]) =>
+		header(batch.length) +
+		batch.map((notice) => `${notice.summary}\nLog: ${notice.logPath}`).join("\n\n") +
+		deferred(batch.length) +
+		footer;
+
+	// If every summary and log path cannot fit, notify the largest fitting prefix
+	// and leave the rest unacknowledged for a later poll. Always make progress for
+	// pathological single ids/paths by delivering one UTF-8-truncated entry.
+	let batch = notices;
+	if (Buffer.byteLength(renderCompact(batch), "utf8") > maxBytes) {
+		let low = 1;
+		let high = notices.length - 1;
+		let fittedCount = 0;
+		while (low <= high) {
+			const mid = Math.floor((low + high) / 2);
+			if (Buffer.byteLength(renderCompact(notices.slice(0, mid)), "utf8") <= maxBytes) {
+				fittedCount = mid;
+				low = mid + 1;
+			} else {
+				high = mid - 1;
+			}
+		}
+		batch = fittedCount > 0 ? notices.slice(0, fittedCount) : [notices[0]];
+	}
+
+	const blockBase = (notice: ProcessCompletionNotice) =>
+		`${notice.summary}\nCommand: ${summarizeNotificationCommand(notice.command)}\nLog: ${notice.logPath}`;
+	const outputs = batch.map((notice) =>
+		notice.output.startsWith("\n\nOutput:") ? AGGREGATE_OUTPUT_OMISSION : notice.output,
+	);
+	const renderDetailed = () =>
+		header(batch.length) +
+		batch.map((notice, i) => blockBase(notice) + outputs[i]).join("\n\n") +
+		deferred(batch.length) +
+		footer;
+
+	let content = renderDetailed();
+	let contentBytes = Buffer.byteLength(content, "utf8");
+	if (contentBytes <= maxBytes) {
+		// Spend the remaining aggregate budget on complete inline outputs without
+		// repeatedly rebuilding the entire batch for every candidate.
+		for (let i = 0; i < batch.length; i++) {
+			if (!batch[i].output.startsWith("\n\nOutput:")) continue;
+			const delta =
+				Buffer.byteLength(batch[i].output, "utf8") - Buffer.byteLength(outputs[i], "utf8");
+			if (contentBytes + delta > maxBytes) continue;
+			outputs[i] = batch[i].output;
+			contentBytes += delta;
+		}
+		content = renderDetailed();
+	} else {
+		content = truncateUtf8End(renderCompact(batch), maxBytes);
+	}
+
+	const statuses = new Set(batch.map((notice) => notice.status));
+	const status: CompletionStatus = statuses.has("failed")
+		? "failed"
+		: statuses.has("terminated")
+			? "terminated"
+			: "success";
+	const processes = batch.map((notice) => ({
+		id: notice.id,
+		exitCode: notice.exitCode,
+		success: notice.success,
+		status: notice.status,
+		runtime: notice.runtime,
+		logPath: notice.logPath,
+	}));
+	const single = totalCount === 1 ? batch[0] : undefined;
+	return {
+		customType: "pi-babysit-process-end",
+		content,
+		display: true,
+		details: {
+			id: single?.id,
+			exitCode: single?.exitCode,
+			success: batch.every((notice) => notice.success),
+			status,
+			runtime: single?.runtime,
+			logPath: single?.logPath,
+			count: batch.length,
+			totalCount,
+			remainingCount: totalCount - batch.length,
+			processes,
+		},
+	};
+}
+
+/** Send once and only acknowledge notices represented in the accepted batch. */
+export function deliverProcessCompletionMessage(
+	notices: ProcessCompletionNotice[],
+	send: (
+		message: ProcessCompletionMessage,
+		options: { triggerTurn: true; deliverAs: "steer" },
+	) => void,
+	onSent: (notice: ProcessCompletionNotice) => void,
+): boolean {
+	if (notices.length === 0) return false;
+	let message: ProcessCompletionMessage;
+	try {
+		message = buildProcessCompletionMessage(notices);
+		send(message, { triggerTurn: true, deliverAs: "steer" });
+	} catch {
+		return false;
+	}
+	const deliveredIds = new Set(message.details.processes.map(({ id }) => id));
+	for (const notice of notices) {
+		if (deliveredIds.has(notice.id)) onSent(notice);
+	}
+	return true;
+}
 
 // ---------------------------------------------------------------------------
 // parked-turn detection (shared rule with self-reap.ts)
@@ -805,6 +1081,8 @@ interface SubagentOpts {
 	model?: string;
 	tools?: string[];
 	cwd: string;
+	depth: number;
+	maxDepth: number;
 	// Idle-timeout is OFF by default: an RPC-mode pi is silent while it works,
 	// so idle detection would false-kill a busy subagent. The absolute timeout
 	// is the safety valve instead.
@@ -852,7 +1130,13 @@ async function spawnSubagent(
 	}
 	bsArgs.push("--", PI_BIN, ...piArgs);
 
-	const r = await bs(bsArgs, { cwd: opts.cwd });
+	const r = await bs(bsArgs, {
+		cwd: opts.cwd,
+		env: {
+			[SUBAGENT_DEPTH_ENV]: String(opts.depth),
+			[SUBAGENT_MAX_DEPTH_ENV]: String(opts.maxDepth),
+		},
+	});
 	if (r.code !== 0) {
 		return { error: r.stderr || r.stdout || `babysit run failed (exit ${r.code}, no output) — check that \`${BABYSIT_BIN}\` works and ${ROOT} is writable` };
 	}
@@ -867,7 +1151,13 @@ async function spawnSubagent(
 	// below fails and we kill the session, the exit poller does NOT mistake it
 	// for an un-notified process and fire a spurious process-end notification.
 	// The success path overwrites this with the full task meta.
-	writeMeta(id, { kind: "subagent", task: opts.task, notified: true });
+	writeMeta(id, {
+		kind: "subagent",
+		task: opts.task,
+		notified: true,
+		depth: opts.depth,
+		maxDepth: opts.maxDepth,
+	});
 
 	// Wait for pi to boot (first JSON event in the log), then inject the task.
 	await bs(["expect", "-s", id, "--timeout", "30s", '\\{"type"']);
@@ -909,6 +1199,8 @@ async function spawnSubagent(
 		task: opts.task,
 		promptOffset: sent.offset,
 		model: resolvedModel,
+		depth: opts.depth,
+		maxDepth: opts.maxDepth,
 		startedAt: Date.now(),
 	});
 	return { id, model: resolvedModel };
@@ -1289,78 +1581,81 @@ export default function (pi: ExtensionAPI) {
 	let pollTimer: ReturnType<typeof setInterval> | undefined;
 
 	// Exit notifications for kind=process sessions: the poller detects
-	// running→exited transitions and injects ONE message (triggerTurn) so an
-	// agent that ended its turn after babysit_run is resumed automatically —
-	// the old `process` tool contract. Kills via babysit_kill and exits already
-	// reported by babysit_wait are suppressed via meta.notified.
+	// running→exited transitions and injects ONE message (triggerTurn) for all
+	// processes that became deliverable in the same poll. This resumes an agent
+	// that ended its turn after babysit_run without spending one turn per exit.
+	// Kills via babysit_kill and exits already reported by babysit_wait are
+	// suppressed via meta.notified.
 	async function notifyEndedProcesses(): Promise<void> {
 		const { sessions } = await listSessions();
-		for (const s of sessions) {
-			if (s.state === "running") continue;
-			const meta = readMeta(s.id);
-			if (!meta || meta.kind !== "process" || meta.notified || meta.notificationPaused) continue;
+		const ready: Array<{ session: BsSession; meta: Meta }> = [];
+		for (const session of sessions) {
+			if (session.state === "running") continue;
+			const meta = readMeta(session.id);
+			if (!shouldDeliverProcessCompletion(meta)) continue;
 			// Delay delivery by one poll interval. This gives an agent that chose
 			// babysit_wait immediately after babysit_run enough time to claim the
 			// completion and suppress the otherwise duplicate automatic message.
 			if (!meta.completionObservedAt) {
 				meta.completionObservedAt = Date.now();
-				writeMeta(s.id, meta);
+				writeMeta(session.id, meta);
 				continue;
 			}
 			if (Date.now() - meta.completionObservedAt < POLL_MS) continue;
-			const ok = s.exit_code === 0;
-			const status: DisplayStatus = ok
+			ready.push({ session, meta });
+		}
+
+		const prepared: ProcessCompletionNotice[] = [];
+		for (const { session, meta } of ready) {
+			const ok = session.exit_code === 0;
+			const status: CompletionStatus = ok
 				? "success"
-				: s.state === "dead" || s.exit_code == null
+				: session.state === "dead" || session.exit_code == null
 					? "terminated"
 					: "failed";
-			const output = await inlineOutput(s.id, s, NOTIFY_OUTPUT_MAX_BYTES);
+			const output = await inlineOutput(session.id, session, NOTIFY_OUTPUT_MAX_BYTES);
 			const runtime = meta.startedAt
 				? `${Math.round((Date.now() - meta.startedAt) / 1000)}s`
 				: "?";
 			const summary = ok
-				? `Process "${s.id}" completed successfully after ${runtime}.`
-				: s.state === "dead" || s.exit_code == null
-					? `Process "${s.id}" was terminated after ${runtime}.`
-					: `Process "${s.id}" exited with code ${s.exit_code} after ${runtime}.`;
-			// Output loading is asynchronous. A kill/wait can claim completion in
-			// that window, so re-read metadata immediately before delivery.
-			const current = readMeta(s.id);
-			if (
-				!current ||
-				current.kind !== "process" ||
-				current.notified ||
-				current.notificationPaused
-			) {
-				continue;
-			}
-			try {
-				pi.sendMessage(
-					{
-						customType: "pi-babysit-process-end",
-						content:
-							`${summary}\nCommand: ${summarizeNotificationCommand(current.command)}\nLog: ${logPath(s.id)}${output}` +
-							"\n\nAutomatic completion notification. Inspect the bounded log with babysit_check only if needed.",
-						display: true,
-						details: {
-							id: s.id,
-							exitCode: s.exit_code,
-							success: ok,
-							status,
-							runtime,
-							logPath: logPath(s.id),
-						},
-					},
-					{ triggerTurn: true, deliverAs: "steer" },
-				);
-			} catch {
-				// Leave it pending so the next poll can retry delivery.
-				continue;
-			}
-			current.notified = true;
-			delete current.notificationPaused;
-			writeMeta(s.id, current);
+				? `Process "${session.id}" completed successfully after ${runtime}.`
+				: session.state === "dead" || session.exit_code == null
+					? `Process "${session.id}" was terminated after ${runtime}.`
+					: `Process "${session.id}" exited with code ${session.exit_code} after ${runtime}.`;
+			prepared.push({
+				id: session.id,
+				exitCode: session.exit_code,
+				success: ok,
+				status,
+				runtime,
+				summary,
+				command: meta.command,
+				logPath: logPath(session.id),
+				output,
+			});
 		}
+
+		// Output loading above is asynchronous. Re-read every candidate together
+		// immediately before the single send so a concurrent kill/wait cannot claim
+		// an early candidate while a later candidate's output is being loaded.
+		const metadataById = new Map<string, Meta>();
+		const notices = prepared.flatMap((notice) => {
+			const current = readMeta(notice.id);
+			if (!shouldDeliverProcessCompletion(current)) return [];
+			metadataById.set(notice.id, current);
+			return [{ ...notice, command: current.command }];
+		});
+		deliverProcessCompletionMessage(
+			notices,
+			(message, options) => pi.sendMessage(message, options),
+			(notice) => {
+				const meta = metadataById.get(notice.id);
+				if (!meta) return;
+				meta.notified = true;
+				delete meta.notificationPaused;
+				writeMeta(notice.id, meta);
+			},
+		);
 	}
 
 	const refreshWidget = async (ctx: ExtensionContext) => {
@@ -1525,7 +1820,8 @@ export default function (pi: ExtensionAPI) {
 			"`retryOnWorkerDeath` can retry one idempotent command once. " +
 			"(2) `profile: \"subagent\"` + `task` — spawn a pi subagent that works on the task in the " +
 			"background; poll with babysit_check, steer with babysit_send, block with babysit_wait, " +
-			"stop with babysit_kill.",
+			"stop with babysit_kill. Subagents cannot recursively spawn more subagents by default; " +
+			"the top-level caller must explicitly raise `maxDepth` when creating the first worker.",
 		promptSnippet:
 			"Run any shell command with context-safe captured output; quick commands return metadata, longer ones continue in background",
 		promptGuidelines: [
@@ -1535,6 +1831,7 @@ export default function (pi: ExtensionAPI) {
 			"If a babysit worker is killed externally, babysit_run reports it as worker-dead rather than hanging. Set retryOnWorkerDeath: true only for safe, idempotent commands; it retries at most once and may otherwise duplicate side effects.",
 			"babysit_run gives full PTY control: drive interactive programs (installers, wizards, REPLs) with babysit_send (text or named keys) and read the rendered screen with babysit_check { screen: true }.",
 			"Delegate self-contained tasks (codebase recon, a parallelizable subtask, work that would pollute your context) with babysit_run { profile: \"subagent\", task }. Launch several for independent subtasks; they run concurrently.",
+			"Subagents cannot create further subagents by default (maximum depth 1). Only the top-level caller can explicitly opt in by setting maxDepth when it creates the first worker; nested workers inherit that limit and cannot raise it.",
 			"After spawning subagents, do not idle-wait and do not end your turn to wait for them: keep making progress, then call babysit_wait (ids + mode any/all) when you need their results. Steer or send follow-up tasks with babysit_send; kill runaways with babysit_kill.",
 		],
 		parameters: Type.Object({
@@ -1563,6 +1860,13 @@ export default function (pi: ExtensionAPI) {
 			tools: Type.Optional(
 				Type.Array(Type.String(), { description: "Tool allowlist for the subagent." }),
 			),
+			maxDepth: Type.Optional(
+				Type.Integer({
+					minimum: 1,
+					description:
+						"Maximum subagent nesting depth. Top-level subagent mode only; default 1 prevents workers from spawning workers. Nested workers inherit this limit and cannot override it.",
+				}),
+			),
 			agentScope: Type.Optional(
 				StringEnum(["user", "project", "both"] as const, {
 					description: "Where to discover named agents. Default 'user'.",
@@ -1625,6 +1929,19 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
+			// Compute nesting only for subagent mode. Ordinary command processes remain
+			// available even when the hosting agent is at its subagent depth limit.
+			const nesting = isSubagent
+				? planSubagentSpawn(params.maxDepth)
+				: undefined;
+			if (nesting && !nesting.allowed) {
+				return {
+					content: [{ type: "text", text: nesting.error }],
+					isError: true,
+					details: {},
+				};
+			}
+
 			// --- process mode ---
 			if (!isSubagent) {
 				const spawnOpts: ProcOpts = {
@@ -1765,12 +2082,16 @@ export default function (pi: ExtensionAPI) {
 				}
 			}
 
+			// The branch above guarantees a successful plan in subagent mode.
+			const subagentNesting = nesting as Extract<SubagentSpawnPlan, { allowed: true }>;
 			const res = await spawnSubagent({
 				agent,
 				task: params.task as string,
 				model: params.model,
 				tools: params.tools,
 				cwd: ctx.cwd,
+				depth: subagentNesting.childDepth,
+				maxDepth: subagentNesting.maxDepth,
 				timeout: params.timeout ?? "15m",
 				idleTimeout: params.idleTimeout,
 			});
@@ -1789,7 +2110,7 @@ export default function (pi: ExtensionAPI) {
 					{
 						type: "text",
 						text:
-							`Subagent started (id: ${res.id})${agent ? ` [agent: ${agent.name}]` : ""}${res.model ? ` [model: ${res.model}]` : ""}.\n` +
+							`Subagent started (id: ${res.id})${agent ? ` [agent: ${agent.name}]` : ""}${res.model ? ` [model: ${res.model}]` : ""} [depth: ${subagentNesting.childDepth}/${subagentNesting.maxDepth}].\n` +
 							`Task accepted — running in the background; keep working (do NOT end your turn just to wait for it).\n` +
 							`Poll:  babysit_check { id: "${res.id}" }\n` +
 							`Wait:  babysit_wait  { id: "${res.id}" }\n` +
@@ -1802,6 +2123,8 @@ export default function (pi: ExtensionAPI) {
 					agent: agent?.name,
 					model: res.model,
 					task: params.task,
+					depth: subagentNesting.childDepth,
+					maxDepth: subagentNesting.maxDepth,
 					status: "started" satisfies DisplayStatus,
 				},
 			};
@@ -1893,9 +2216,13 @@ export default function (pi: ExtensionAPI) {
 					const kind = meta?.kind ?? "process";
 					const flag = s.note ? ` ⚑ ${s.note}` : "";
 					const ec = s.exit_code != null ? ` exit=${s.exit_code}` : "";
+					const depth =
+						kind === "subagent" && meta?.depth != null
+							? ` depth=${meta.depth}/${meta.maxDepth ?? "?"}`
+							: "";
 					const what = (kind === "subagent" ? meta?.task : meta?.command) ?? "";
 					const preview = what.length > 60 ? `${what.slice(0, 57)}…` : what;
-					return `${s.id}  [${kind}] ${s.state}${ec}${flag}${preview ? `  — ${preview}` : ""}`;
+					return `${s.id}  [${kind}] ${s.state}${ec}${depth}${flag}${preview ? `  — ${preview}` : ""}`;
 				});
 				return { content: [{ type: "text", text: lines.join("\n") }], details: { sessions } };
 			}
@@ -1981,6 +2308,7 @@ export default function (pi: ExtensionAPI) {
 
 			const parts: string[] = [];
 			let header = `[subagent] state=${st.state}`;
+			if (meta.depth != null) header += ` depth=${meta.depth}/${meta.maxDepth ?? "?"}`;
 			if (st.state === "running") {
 				const el = elapsedOf(params.id);
 				if (el) header += ` elapsed=${el}`;
@@ -2161,6 +2489,8 @@ export default function (pi: ExtensionAPI) {
 					task: params.text,
 					promptOffset: sent.offset,
 					model: meta?.model,
+					depth: meta?.depth,
+					maxDepth: meta?.maxDepth,
 				});
 			}
 			return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yusukeshib/pi-babysit",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Run any shell command and pi subagents under babysit, with context-safe captured output.",
   "keywords": [
     "pi-package",