@yusukeshib/pi-babysit 0.6.21 → 0.6.22

package/README.md

@@ -32,8 +32,8 @@ 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`), 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_settled` in the RPC event stream (worker remains reusable during its idle grace) | `foreground: true` returns the answer and nested usage in the same tool call; background workers must be collected with `babysit_wait` before the parent finishes, and remain reusable until self-reap |
+| **process** | `babysit_run { description, 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 { description, profile: "subagent", task }` | `agent_settled` in the RPC event stream (worker remains reusable during its idle grace) | `foreground: true` returns the answer and nested usage in the same tool call; background workers must be collected with `babysit_wait` before the parent finishes, and remain reusable until self-reap |
 
 The **profile is a tool parameter, not a separate tool set**: domain knowledge
 (RPC bookkeeping, per-task byte offsets, parked-turn detection, PTY-safe
@@ -44,8 +44,8 @@ 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.
+Normal `babysit_run { description, 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`
@@ -56,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`/`notificationGroup`/`lifecycle`). Set `foreground: true` for one process or subagent whose result is needed in the same tool call; use `returnPattern`/`returnLines`/`maxBytes` to keep noisy process output bounded. Foreground and non-interactive process waits default to lifecycle `attached`, which terminates the process tree if that owning tool call is interrupted; background starts default to `detached`. Or start a named background subagent (`profile: "subagent"`, `task`, optional `name`/`agent`/`model`/`tools`/`maxDepth` and budget fields), then always collect it with `babysit_wait`. `maxDepth` defaults to 1. Subagent `continueAfterStart: true` is accepted as a compatibility alias for this default background behavior. Quick commands return inline; longer process runs notify in the background |
+| `babysit_run` | Run any command (`description` + `command`, optional `name`/`pty`/`timeout`/`idleTimeout`/`retryOnWorkerDeath`/`notificationGroup`/`lifecycle`). Set `foreground: true` for one process or subagent whose result is needed in the same tool call; use `returnPattern`/`returnLines`/`maxBytes` to keep noisy process output bounded. Foreground and non-interactive process waits default to lifecycle `attached`, which terminates the process tree if that owning tool call is interrupted; background starts default to `detached`. Or start a named background subagent (`description`, `profile: "subagent"`, `task`, optional `name`/`agent`/`model`/`tools`/`maxDepth` and budget fields), then always collect it with `babysit_wait`. `maxDepth` defaults to 1. Subagent `continueAfterStart: true` is accepted as a compatibility alias for this default background behavior. Quick commands return inline; longer process runs notify in the background |
 | `babysit_check` | Without an id, list sessions with state/kind filters. With an id, inspect bounded output, search with `pattern`, or capture a TUI with `screen: true`; `maxBytes` overrides the 4 KB default up to 24 KB |
 | `babysit_send` | Process: type `text` / press `keys` into the PTY. Subagent: steer mid-run, or send a follow-up task when confirmed settled (`mode: auto/steer/task`); explicit task mode rejects busy, parked, or unknown state |
 | `babysit_wait` | Block until done: process exit (or `expect: "regex"` readiness marker), subagent task completion. Multi-wait: up to 32 unique `ids` + `mode: "any"\|"all"` |
@@ -71,6 +71,27 @@ calls if another extension or preset re-enables `bash`, including shell
 backgrounding (`… &`, `nohup`, `setsid`, `disown`). Set
 `PI_BABYSIT_ALLOW_BASH=1` to retain direct `bash` explicitly.
 
+## Describe every run
+
+Every `babysit_run` requires a non-blank `description`, for both commands and
+subagents. Explain the purpose briefly in language the user can understand;
+`name` remains a stable session identifier, while `command` / `task` contains
+the actual execution instructions. Descriptions are trimmed before saving and
+are display metadata, not shell code or instructions sent to the subagent.
+
+```text
+babysit_run { description: "Run regression tests", command: "bun test", foreground: true }
+babysit_run { description: "Review the authentication changes", profile: "subagent", task: "Review the authentication diff for security regressions", maxTurns: 5 }
+```
+
+In Pi's main transcript the description is the prominent yellow heading, with
+the execution kind in muted gray. The full command or task is always visible
+in gray beneath it, even when tool results are collapsed. Session lists, the
+widget, and completion notifications also show the description. Older saved sessions and tool calls
+without one remain readable, falling back to their command or task. Callers
+must supply a description for new runs; blank or missing values are rejected
+before launch.
+
 ## Remote processes over SSH
 
 Install a `babysit` CLI with `--host` support on both machines (tested with
@@ -79,8 +100,8 @@ SSH aliases, keys, known hosts, and ProxyJump are handled by babysit/SSH;
 pi-babysit does not install remote software or copy credentials.
 
 ```text
-babysit_run { host: "yusuke-t4", cwd: "/home/yusuke/project", command: "bun test", foreground: true, returnLines: 30 }
-babysit_run { host: "user@server", command: "python3 -i", name: "remote-repl", continueAfterStart: true }
+babysit_run { description: "Run tests on Linux", host: "yusuke-t4", cwd: "/home/yusuke/project", command: "bun test", foreground: true, returnLines: 30 }
+babysit_run { description: "Open a remote Python REPL", host: "user@server", command: "python3 -i", name: "remote-repl", continueAfterStart: true }
 babysit_check { id: "remote-repl", screen: true }
 babysit_send { id: "remote-repl", text: "print(42)" }
 babysit_kill { id: "remote-repl" }
@@ -132,9 +153,9 @@ summary counts use `RUNNING` / `IDLE`, and every row is labeled
 Click the header to toggle to `babysits(n all)`, which also shows finished and failed
 sessions, and click again to return to running-only. Both modes show newest first,
 ten per page; `< 1/4 >` shows the current/total page when needed. Click the
-arrows to page. Rows occupy one line, previewing the command for processes and
-the task for agents (with `…` when clipped). Click an AGENT or PROCESS row to
-replace the list with a tall **log viewer in the same widget area**, not an
+arrows to page. Rows occupy one line, previewing the description (or the command
+for older processes and task for older agents), with `…` when clipped. Click an
+AGENT or PROCESS row to replace the list with a tall **log viewer in the same widget area**, not an
 overlay or separate screen. `Esc` or the right-hand **Close** button restores
 the list, preserving its mode and page. The viewer uses Pi's `ScrollView` for
 scroll position and follow behavior, with a widget-local scrollbar styled using
@@ -269,7 +290,7 @@ because blindly rerunning an arbitrary command can duplicate side effects.
   must still call `babysit_wait` so the answer and nested usage are persisted.
   Unlike `agent_end`, `agent_settled` cannot precede an automatic retry,
   compaction retry, or queued continuation. A settled run containing a
-  **parked** toolResult — a `babysit_run { command }` result carrying the
+  **parked** toolResult — a `babysit_run { description, command }` result carrying the
   `[notify-on-exit]` marker (or the legacy `process` tool) — only means "turn
   parked awaiting a process-exit notification; pi resumes on its own", so the
   wait continues. The marker-bearing result may be followed by a short
@@ -280,7 +301,7 @@ because blindly rerunning an arbitrary command can duplicate side effects.
 Subagents load `self-reap.ts`, which exits an idle finished subagent after a
 grace window using the same parked-turn rule, so a subagent waiting on a long
 build is never false-killed. Callers can set `reapAfter: "5m"` on
-`babysit_run { profile: "subagent", task, reapAfter: "5m" }`. Omission uses
+`babysit_run { description, profile: "subagent", task, reapAfter: "5m" }`. Omission uses
 `PI_BABYSIT_REAP_AFTER`, then `PI_SUBAGENT_REAP_AFTER`, then 120s.
 `reapAfter: "none"` (also `"off"` or `"0"`) disables idle reaping; the absolute
 `timeout` still applies. Follow-up tasks cancel the idle timer. This differs

package/index.ts

@@ -127,7 +127,7 @@ export function planSubagentSpawn(
 			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.`,
+				`babysit_run { description, profile: "subagent", task, maxDepth: ${childDepth} } when creating the first worker.`,
 		};
 	}
 	return { allowed: true, childDepth, maxDepth };
@@ -160,7 +160,7 @@ export function subagentGuidance(
 	const shellGuidance = directBashAvailable
 		? "Direct bash is available, and babysit_run can supervise longer commands."
 		: babysitRunAvailable
-			? "Direct bash is unavailable; run shell commands with babysit_run { command }."
+			? "Direct bash is unavailable; run shell commands with babysit_run { description, command }."
 			: "No shell execution tool is available in this task's tool allowlist; do not attempt shell commands.";
 	const nestingGuidance = depth >= maxDepth
 		? `You are at the inherited subagent depth limit (${depth}/${maxDepth}); do not attempt to spawn another subagent.`
@@ -521,6 +521,8 @@ interface Meta {
 	remoteId?: string;
 	remoteTerminalState?: string;
 	kind: "process" | "subagent";
+	/** Human-facing purpose. Optional only for metadata written by older versions. */
+	description?: string;
 	// process
 	name?: string;
 	command?: string;
@@ -568,6 +570,11 @@ interface Meta {
 }
 
 const metaDir = () => path.join(ROOT, "meta");
+
+/** Prefer the human-facing purpose while preserving previews for old sessions. */
+export function sessionPreview(meta: Pick<Meta, "description" | "kind" | "task" | "command"> | undefined): string {
+	return meta?.description?.trim() || (meta?.kind === "subagent" ? meta.task : meta?.command) || "";
+}
 const localLogPath = (id: string) => path.join(ROOT, "sessions", id, "output.log");
 const logPath = (id: string) => {
 	const meta = readMeta(id);
@@ -1397,6 +1404,7 @@ export interface ProcessCompletionNotice {
 	status: CompletionStatus;
 	runtime: string;
 	summary: string;
+	description?: string;
 	command: string | undefined;
 	logPath: string;
 	output: string;
@@ -1414,6 +1422,7 @@ interface ProcessCompletionMessage {
 		runtime?: string;
 		logPath?: string;
 		command?: string;
+		description?: string;
 		count: number;
 		totalCount: number;
 		remainingCount: number;
@@ -1424,6 +1433,7 @@ interface ProcessCompletionMessage {
 			status: CompletionStatus;
 			runtime: string;
 			command: string | undefined;
+			description?: string;
 			logPath: string;
 		}>;
 	};
@@ -1465,9 +1475,11 @@ export function buildProcessCompletionMessage(
 		count < totalCount
 			? `\n\n${totalCount - count} completion${totalCount - count === 1 ? "" : "s"} deferred to the next poll.`
 			: "";
+	const noticeSummary = (notice: ProcessCompletionNotice) =>
+		notice.summary + (notice.description ? `\nDescription: ${summarizeNotificationCommand(notice.description)}` : "");
 	const renderCompact = (batch: ProcessCompletionNotice[]) =>
 		header(batch.length) +
-		batch.map((notice) => `${notice.summary}\nLog: ${notice.logPath}`).join("\n\n") +
+		batch.map((notice) => `${noticeSummary(notice)}\nLog: ${notice.logPath}`).join("\n\n") +
 		deferred(batch.length) +
 		footer;
 
@@ -1492,7 +1504,7 @@ export function buildProcessCompletionMessage(
 	}
 
 	const blockBase = (notice: ProcessCompletionNotice) =>
-		`${notice.summary}\nCommand: ${summarizeNotificationCommand(notice.command)}\nLog: ${notice.logPath}`;
+		`${noticeSummary(notice)}\nCommand: ${summarizeNotificationCommand(notice.command)}\nLog: ${notice.logPath}`;
 	const outputs = batch.map((notice) =>
 		notice.output.startsWith("\n\nOutput:") ? AGGREGATE_OUTPUT_OMISSION : notice.output,
 	);
@@ -1533,6 +1545,7 @@ export function buildProcessCompletionMessage(
 		status: notice.status,
 		runtime: notice.runtime,
 		command: notice.command,
+		description: notice.description,
 		logPath: notice.logPath,
 	}));
 	const single = totalCount === 1 ? batch[0] : undefined;
@@ -1548,6 +1561,7 @@ export function buildProcessCompletionMessage(
 			runtime: single?.runtime,
 			logPath: single?.logPath,
 			command: single?.command,
+			description: single?.description,
 			count: batch.length,
 			totalCount,
 			remainingCount: totalCount - batch.length,
@@ -2109,6 +2123,7 @@ async function reserveUniqueSessionId(name: string): Promise<string> {
 }
 
 interface ProcOpts {
+	description: string;
 	name?: string;
 	command: string;
 	cwd?: string;
@@ -2161,7 +2176,7 @@ async function spawnProcess(opts: ProcOpts): Promise<{ id: string } | { error: s
 	const reservedId = remote ? await reserveUniqueSessionId(opts.name ?? "remote-proc") : opts.name ? await reserveUniqueSessionId(opts.name) : undefined;
 	const remoteId = remote ? remoteProcessId(ROOT) : undefined;
 	if (reservedId) bsArgs.push("--id", remoteId ?? reservedId);
-	if (remote && !writeMeta(reservedId!, { kind: "process", host: opts.host, remoteId, name: opts.name ?? reservedId, command: opts.command, notificationGroup: opts.notificationGroup, notified: false, startedAt: Date.now() })) {
+	if (remote && !writeMeta(reservedId!, { kind: "process", host: opts.host, remoteId, name: opts.name ?? reservedId, description: opts.description, command: opts.command, notificationGroup: opts.notificationGroup, notified: false, startedAt: Date.now() })) {
 		reservedSessionIds.delete(reservedId!);
 		return { error: "Cannot persist remote identity; process was not started." };
 	}
@@ -2196,6 +2211,7 @@ async function spawnProcess(opts: ProcOpts): Promise<{ id: string } | { error: s
 	writeMeta(id, {
 		kind: "process",
 		name: opts.name ?? id,
+		description: opts.description,
 		command: opts.command,
 		notificationGroup: opts.notificationGroup,
 		notified: false,
@@ -2251,6 +2267,7 @@ function discardDelivery(delivery: DeliverableMessage): void {
 }
 
 interface SubagentOpts {
+	description: string;
 	name?: string;
 	agent?: AgentConfig;
 	task: string;
@@ -2381,6 +2398,7 @@ async function spawnSubagent(
 	writeMeta(id, {
 		kind: "subagent",
 		name: opts.name ?? id,
+		description: opts.description,
 		task: opts.task,
 		launchCommand,
 		notified: true,
@@ -2470,6 +2488,7 @@ async function spawnSubagent(
 	writeMeta(id, {
 		kind: "subagent",
 		name: opts.name ?? id,
+		description: opts.description,
 		task: opts.task,
 		launchCommand,
 		promptOffset: resp.offset,
@@ -2566,6 +2585,7 @@ export interface WidgetSessionListState {
 
 export interface WidgetSessionDisplay {
 	id: string;
+	description?: string;
 	header: string;
 	tail: string[];
 	viewable: boolean;
@@ -2603,7 +2623,7 @@ export function createWidgetComponent(
 			const pushSession = (session: WidgetSessionDisplay) => {
 				const target = session.viewable ? { type: "session" as const, id: session.id } : undefined;
 				const detail = session.details?.[0];
-				const preview = detail?.startsWith("task: ") ? detail.slice(6) : detail ?? session.tail.at(-1);
+				const preview = session.description ?? (detail?.startsWith("task: ") ? detail.slice(6) : detail ?? session.tail.at(-1));
 				push(`${session.header}${preview ? ` ${preview}` : ""}`, target, "…");
 			};
 
@@ -2689,8 +2709,9 @@ export function createSessionWidget(options: {
 		const log = options.readLog(selectedId);
 		const session = displays.find((session) => session.id === selectedId);
 		const header = session?.header ?? selectedId;
-		const detail = session?.details?.[0] ?? "";
-		const context = detail.startsWith("task: ") ? detail.slice(6) : detail;
+		const context = (session?.details ?? [])
+			.map((detail) => detail.startsWith("task: ") ? detail.slice(6) : detail)
+			.join("\n");
 		if (log.file) {
 			if (!source || source.file !== log.file || source.isAgent !== log.isAgent)
 				source = new FileLogSource(log.file, log.isAgent);
@@ -3540,7 +3561,7 @@ async function waitForExit(
 		kind: "exited",
 		ok,
 		text:
-			`Process ${id}${meta?.command ? ` (${summarizeNotificationCommand(meta.command)})` : ""} ` +
+			`Process ${id}${sessionPreview(meta) ? ` (${summarizeNotificationCommand(sessionPreview(meta))})` : ""} ` +
 			(workerDead
 				? "worker-dead: the babysit supervisor disappeared without an exit status"
 				: ok ? "completed successfully" : `exited with code ${st.exit_code ?? "?"}`) +
@@ -3852,6 +3873,7 @@ export default function (pi: ExtensionAPI) {
 				runtime,
 				summary,
 				command: meta.command,
+				description: meta.description,
 				logPath: logPath(session.id),
 				output,
 			});
@@ -3873,7 +3895,7 @@ export default function (pi: ExtensionAPI) {
 			if (!latest || latest.transportError || latest.state === "running") return [];
 			if (!isNotificationGroupReady(current, finalSessions, readMeta)) return [];
 			metadataById.set(notice.id, current);
-			return [{ ...notice, command: current.command }];
+			return [{ ...notice, command: current.command, description: current.description }];
 		});
 		// Output collection above yields to the event loop. Re-check idleness so a
 		// newly-started agent turn cannot receive a duplicate completion mid-turn.
@@ -3897,7 +3919,7 @@ export default function (pi: ExtensionAPI) {
 	): Promise<void> {
 		if (shouldDeferCompletionNotification(ctx.isIdle())) return;
 		const sessions = snapshot ?? (await listSessions()).sessions;
-		const ready: Array<{ id: string; offset: number; state: string; summary: string }> = [];
+		const ready: Array<{ id: string; offset: number; state: string; summary: string; description?: string }> = [];
 		for (const session of sessions) {
 			const meta = readMeta(session.id);
 			if (!shouldDeliverSubagentCompletion(meta)) continue;
@@ -3920,7 +3942,7 @@ export default function (pi: ExtensionAPI) {
 			const summary = progress.done
 				? `task settled; ${progress.turns} turns, ${progress.toolCallCount} tools, $${progress.cost.toFixed(4)}`
 				: `worker ${session.state} with exit code ${session.exit_code ?? "?"}; partial usage $${progress.cost.toFixed(4)}`;
-			ready.push({ id: session.id, offset, state: session.state, summary });
+			ready.push({ id: session.id, offset, state: session.state, summary, description: meta.description });
 		}
 		if (ready.length === 0 || shouldDeferCompletionNotification(ctx.isIdle())) return;
 
@@ -3934,10 +3956,10 @@ export default function (pi: ExtensionAPI) {
 				customType: "pi-babysit-subagent-ready",
 				content:
 					`${deliverable.length === 1 ? "A background subagent is" : `${deliverable.length} background subagents are`} ready to collect:\n` +
-					deliverable.map(({ id, summary }) => `- ${id}: ${summary}`).join("\n") +
+					deliverable.map(({ id, summary, description }) => `- ${id}${description ? ` (${summarizeNotificationCommand(description)})` : ""}: ${summary}`).join("\n") +
 					"\nCall babysit_wait now to retrieve the answer and charge nested usage before finishing the parent task.",
 				display: true,
-				details: { subagents: deliverable.map(({ id, state }) => ({ id, state })) },
+				details: { subagents: deliverable.map(({ id, state, description }) => ({ id, state, description })) },
 			},
 			{ triggerTurn: true, deliverAs: "steer" },
 		);
@@ -3992,12 +4014,16 @@ export default function (pi: ExtensionAPI) {
 			const id = session.id;
 			const meta = readMeta(id);
 			const isSubagent = meta?.kind === "subagent";
+			const description = meta?.description?.trim()
+				? theme.fg("warning", theme.bold(escapeCommandForDisplay(meta.description.trim())))
+				: undefined;
 			const details = isSubagent
 				? [
-					...(meta?.task ? [`task: ${escapeCommandForDisplay(meta.task)}`] : []),
-					...(meta?.launchCommand ? [theme.bold(escapeCommandForDisplay(readableLaunchCommand(meta.launchCommand)))] : []),
+					...(meta?.task ? [theme.fg("muted", `task: ${escapeCommandForDisplay(meta.task)}`)] : []),
+					...(meta?.launchCommand ? [theme.fg("muted", escapeCommandForDisplay(readableLaunchCommand(meta.launchCommand)))] : []),
 				]
-				: meta?.command ? [theme.bold(escapeCommandForDisplay(meta.command))] : [];
+				: meta?.command ? [theme.fg("muted", escapeCommandForDisplay(meta.command))] : [];
+			if (description) details.unshift(description);
 			if (meta?.host) details.unshift(`host: ${meta.host}${session.transportError ? " (status unknown)" : ""} · ${attachCmd(id)}`);
 			if (session.state === "running") {
 				const state: WidgetSessionState = isSubagent && progressById.get(id)?.done ? "idle" : "running";
@@ -4005,6 +4031,7 @@ export default function (pi: ExtensionAPI) {
 					id,
 					header: renderWidgetSessionHeader(id, isSubagent ? "agent" : "process", state, elapsedOf(id), theme) + (session.transportError ? " · status unknown" : ""),
 					tail: activeTails.get(id) ?? [],
+					description,
 					viewable: true,
 					active: true,
 					details,
@@ -4020,6 +4047,7 @@ export default function (pi: ExtensionAPI) {
 					theme,
 				),
 				details,
+				description,
 				// Only read/parse visible sessions on demand.
 				get tail() {
 					try {
@@ -4115,25 +4143,27 @@ export default function (pi: ExtensionAPI) {
 				success?: boolean;
 				exitCode?: number | null;
 				command?: string;
+				description?: string;
 				count?: number;
 			};
 			const status =
 				d.status ??
 				(d.success ? "success" : d.exitCode == null ? "terminated" : "failed");
-			const payload = d.command
-				? `  ${summarizeNotificationCommand(d.command)}`
-				: d.count && d.count > 1
-					? `  ×${d.count}`
-					: "";
-			const header = theme.fg(
-				"warning",
-				theme.bold(`babysit_run COMMAND${payload}`),
-			);
+			const payload = d.description?.trim()
+				? theme.fg("warning", theme.bold(summarizeNotificationCommand(d.description)))
+				: d.command
+					? theme.fg("muted", summarizeNotificationCommand(d.command))
+					: d.count && d.count > 1
+						? theme.fg("muted", `×${d.count}`)
+						: "";
+			const header = theme.fg("muted", theme.bold("babysit_run COMMAND")) + (payload ? `  ${payload}` : "");
 			const box = new Box(1, 1, (t) => theme.bg("toolSuccessBg", t));
 			box.addChild(new Text(header, 0, 0));
 			box.addChild(new Text(renderStatus(status, theme), 0, 0));
 			if (expanded && content) {
-				box.addChild(new Text(theme.fg("toolOutput", content), 0, 0));
+				box.addChild(new Text(content.split("\n").map((line) =>
+					theme.fg(line.startsWith("Command: ") ? "muted" : "toolOutput", line),
+				).join("\n"), 0, 0));
 			}
 			return box;
 		},
@@ -4281,7 +4311,7 @@ export default function (pi: ExtensionAPI) {
 				block: true,
 				reason:
 					`This bash command tries to run in the background. Use babysit_run instead, e.g. ` +
-					`babysit_run({ name: "background-process", command: ${JSON.stringify(command.replace(/\s*&\s*$/, ""))} })`,
+					`babysit_run({ description: "Describe this background process's purpose", name: "background-process", command: ${JSON.stringify(command.replace(/\s*&\s*$/, ""))} })`,
 			};
 		}
 		if (isAllowedDirectBash(command)) return;
@@ -4290,7 +4320,7 @@ export default function (pi: ExtensionAPI) {
 			reason:
 				"Use babysit_run for shell commands so output is supervised and captured outside model context. " +
 				"Inspect an existing session log with babysit_check { id, lines, pattern? }. " +
-				`Retry as babysit_run({ command: ${JSON.stringify(command)} }).`,
+				`Retry with a short purpose description as babysit_run({ description: "Explain the purpose of this command", command: ${JSON.stringify(command)} }).`,
 		};
 	});
 
@@ -4300,11 +4330,13 @@ export default function (pi: ExtensionAPI) {
 		label: "Babysit: run",
 		description:
 			"Run a supervised shell command, or start a reusable pi subagent with `profile: \"subagent\"`. " +
+			"Always provide a short human-readable `description` of what this run does and why. " +
 			"Use `foreground` for results needed now; otherwise long commands notify on exit. Full logs stay on disk. " +
 			"`returnPattern`/`returnLines` bound foreground output. Sessions support check, wait, send, and kill.",
 		promptSnippet: "Run supervised commands or bounded pi subagents with context-safe logs",
 		promptGuidelines: [
 			"Use babysit_run for shell commands and give meaningful sessions a stable name; bundle tiny related read-only observations into one command.",
+			"Every babysit_run requires a short description explaining its purpose for the user, for both commands and subagents. Describe the actual work, not a generic 'run command' or 'start agent'.",
 			"Use babysit_run foreground mode for one process or subagent whose result is needed now; never issue sibling foreground runs in parallel. For parallel process checks, start background runs with continueAfterStart and collect them with one multi-session babysit_wait.",
 			"Use returnPattern/returnLines for noisy commands. During edit/fix loops run targeted checks first and one full validation suite at the end instead of repeating every full gate.",
 			"After a background process starts, stop the turn for its automatic notification; never poll or sleep. Use continueAfterStart only for specific non-polling process work.",
@@ -4318,6 +4350,11 @@ export default function (pi: ExtensionAPI) {
 			return prepareBabysitRunArguments(args) as never;
 		},
 		parameters: Type.Object({
+			description: Type.String({
+				minLength: 1,
+				pattern: "\\S",
+				description: "Required short human-readable purpose for this command or subagent. Explain what it does and why; shown prominently to the user.",
+			}),
 			host: Type.Optional(Type.String({ description: "Process SSH destination/config alias (default local). Remote subagents are unsupported." })),
 			cwd: Type.Optional(Type.String({ description: "Process working directory. Remote default is login home; never inferred from local cwd." })),
 			command: Type.Optional(
@@ -4448,6 +4485,10 @@ export default function (pi: ExtensionAPI) {
 
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
+			if (typeof params.description !== "string" || !params.description.trim()) {
+				throw new Error("`description` is required and must be a non-blank string for both commands and subagents.");
+			}
+			const description = params.description.trim();
 			await requireBabysit();
 			const isSubagent = params.profile === "subagent";
 			validateProcessHost(params.host);
@@ -4555,6 +4596,7 @@ export default function (pi: ExtensionAPI) {
 						? { pattern: params.returnPattern, lines: params.returnLines, maxBytes: params.maxBytes }
 						: undefined;
 				const spawnOpts: ProcOpts = {
+					description,
 					name: params.name,
 					command: params.command as string,
 					host: params.host,
@@ -4605,6 +4647,7 @@ export default function (pi: ExtensionAPI) {
 							kind: "process",
 							command: params.command,
 							logPath: logPath(res.id),
+							description,
 							retried,
 							status: outcomeStatus(outcome),
 						},
@@ -4641,6 +4684,7 @@ export default function (pi: ExtensionAPI) {
 							kind: "process",
 							command: params.command,
 							logPath: logPath(res.id),
+							description,
 							retried,
 							status: outcomeStatus(outcome),
 						},
@@ -4657,7 +4701,7 @@ export default function (pi: ExtensionAPI) {
 							type: "text",
 							text:
 								`${retried ? "Retried once after external worker death.\n" : ""}` +
-								`Process started (id: ${res.id}). ${NOTIFY_MARKER}\nLog: ${logPath(res.id)}\n${nextStep}\n` +
+								`Process started (id: ${res.id}). ${NOTIFY_MARKER}\nDescription: ${escapeCommandForDisplay(description)}\nLog: ${logPath(res.id)}\n${nextStep}\n` +
 								`Inspect: babysit_check { id: "${res.id}" } (screen: true for TUIs) · ` +
 								`Wait: babysit_wait { id: "${res.id}" } · Kill: babysit_kill { id: "${res.id}" }\n` +
 								`Human can watch/take over: /babysit`,
@@ -4667,6 +4711,7 @@ export default function (pi: ExtensionAPI) {
 						id: res.id,
 						kind: "process",
 						command: params.command,
+						description,
 						logPath: logPath(res.id),
 						retried,
 						status: "started" satisfies DisplayStatus,
@@ -4702,6 +4747,7 @@ 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({
+				description,
 				name: params.name,
 				agent,
 				task: params.task as string,
@@ -4750,6 +4796,7 @@ export default function (pi: ExtensionAPI) {
 						agent: agent?.name,
 						model: res.model,
 						task: params.task,
+						description,
 						depth: subagentNesting.childDepth,
 						maxDepth: subagentNesting.maxDepth,
 						status: outcomeStatus(outcome),
@@ -4762,7 +4809,7 @@ export default function (pi: ExtensionAPI) {
 						type: "text",
 						text:
 							`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. You MUST collect it with babysit_wait before finishing the parent task; use foreground: true next time when no independent work is available.\n` +
+							`Description: ${escapeCommandForDisplay(description)}\nTask accepted — running in the background. You MUST collect it with babysit_wait before finishing the parent task; use foreground: true next time when no independent work is available.\n` +
 							`Progress: babysit_check { id: "${res.id}" } (only when inspection is needed)\n` +
 							`Collect:  babysit_wait  { id: "${res.id}" }\n` +
 							`Human can watch/steer: /babysit (pick ${res.id})`,
@@ -4775,25 +4822,30 @@ export default function (pi: ExtensionAPI) {
 					agent: agent?.name,
 					model: res.model,
 					task: params.task,
+					description,
 					depth: subagentNesting.childDepth,
 					maxDepth: subagentNesting.maxDepth,
 					status: "started" satisfies DisplayStatus,
 				},
 			};
 		},
-		// Make the execution kind and payload identifiable before the result arrives.
-		// Use semantic theme colors rather than the fallback gray tool-call text.
+		// The human-readable purpose is primary; the executable payload is secondary.
+		// Legacy calls without descriptions still render their original payload safely.
 		renderCall(args, theme) {
 			const isSubagent = args.profile === "subagent";
 			const kind = isSubagent ? "AGENT" : "COMMAND";
 			const payload = isSubagent ? args.task : args.command;
-			const agent = isSubagent && args.agent ? ` [${args.agent}]` : "";
-			const title = theme.bold(`babysit_run ${kind}`);
-			const detail =
-				typeof payload === "string" && payload.length > 0
-					? `  ${escapeCommandForDisplay(payload)}`
-					: "";
-			return new Text(theme.fg("warning", `${title}${agent}${detail}`), 0, 0);
+			const agent = isSubagent && args.agent ? ` [${escapeCommandForDisplay(args.agent)}]` : "";
+			const title = theme.fg("muted", `${theme.bold(`babysit_run ${kind}`)}${agent}`);
+			const description = typeof args.description === "string" ? args.description.trim() : "";
+			const raw = typeof payload === "string" ? escapeCommandForDisplay(payload) : "";
+			const heading = description
+				? `${title}  ${theme.fg("warning", theme.bold(escapeCommandForDisplay(description)))}`
+				: `${title}${raw ? theme.fg("muted", `  ${raw}`) : ""}`;
+			const detail = description && raw
+				? `\n${theme.fg("muted", raw)}`
+				: "";
+			return new Text(heading + detail, 0, 0);
 		},
 		renderResult(result, { expanded, isPartial }, theme, context) {
 			const details = (result.details ?? {}) as {
@@ -4932,7 +4984,7 @@ export default function (pi: ExtensionAPI) {
 						kind === "subagent" && meta?.depth != null
 							? ` depth=${meta.depth}/${meta.maxDepth ?? "?"}`
 							: "";
-					const what = (kind === "subagent" ? meta?.task : meta?.command) ?? "";
+					const what = escapeCommandForDisplay(sessionPreview(meta));
 					const preview = what.length > 60 ? `${what.slice(0, 57)}…` : what;
 					return `${s.id}  [${kind}${s.host ? ` host=${s.host}` : ""}] ${s.transportError ? "unknown" : s.state}${ec}${depth}${flag}${preview ? `  — ${preview}` : ""}`;
 				});
@@ -5000,6 +5052,7 @@ export default function (pi: ExtensionAPI) {
 					if (el) header += ` elapsed=${el}`;
 				}
 				if (st.exit_code != null) header += ` exit_code=${st.exit_code}`;
+				if (meta?.description) header += `\ndescription: ${escapeCommandForDisplay(meta.description)}`;
 				if (meta?.command) header += `\ncommand: ${summarizeNotificationCommand(meta.command)}`;
 				header += `\nlog: ${logPath(params.id)}`;
 				if (st.note) header += ` ⚑ ${st.note}`;
@@ -5045,6 +5098,7 @@ export default function (pi: ExtensionAPI) {
 			if (prog.tokens != null) header += ` ctx=${prog.tokens}`;
 			if (prog.modelCalls > 0) header += ` usage=${prog.usageTokens} $${prog.cost.toFixed(4)}`;
 			if (st.note) header += ` ⚑ ${st.note}`;
+			if (meta.description) header += `\ndescription: ${escapeCommandForDisplay(meta.description)}`;
 			parts.push(header);
 
 			if (prog.errorMsg) parts.push(`⚠ error: ${clip(prog.errorMsg, ANSWER_MAX_BYTES)}`);
@@ -5593,9 +5647,7 @@ export default function (pi: ExtensionAPI) {
 
 			const whatOf = (s: BsSession): string => {
 				const meta = readMeta(s.id);
-				return ((meta?.kind === "subagent" ? meta.task : meta?.command) ?? "")
-					.replace(/\s+/g, " ")
-					.trim();
+				return escapeCommandForDisplay(sessionPreview(meta).replace(/\s+/g, " ").trim());
 			};
 
 			// Labels must be unique for index mapping; the id makes them unique.

package/package.json

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