@yusukeshib/pi-babysit 0.6.21 → 0.6.23

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,19 +44,22 @@ 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`
 (text or named keys) and read the rendered screen with
-`babysit_check { screen: true }` — a capability neither retired extension had.
+`babysit_check { description, screen: true }` — a capability neither retired extension had.
 
 ## Tools (LLM-callable)
 
+All five tools require a short, non-blank `description` explaining the purpose
+of that call.
+
 | 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 +74,36 @@ 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 operation
+
+Every babysit tool call requires a non-blank `description`. Explain the purpose
+briefly in language the user can understand. For `babysit_run`, `name` remains
+a stable session identifier, while `command` / `task` contains the execution
+instructions. Its description is trimmed and saved with the session. For
+`babysit_check`, `babysit_send`, `babysit_wait`, and `babysit_kill`, the description
+explains only that operation and never overwrites the session description.
+Descriptions are display metadata, not shell code, stdin, 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 }
+babysit_check { description: "Inspect build errors", id: "build", pattern: "ERROR" }
+babysit_wait { description: "Wait for the build to finish", id: "build" }
+babysit_send { description: "Ask the reviewer to check authorization too", id: "review", text: "Also check authorization." }
+babysit_kill { description: "Stop the unused development server", id: "dev-server" }
+```
+
+In Pi's main transcript the description is the prominent yellow heading, with
+the tool name and execution kind in muted gray. The full command or task (or
+all other operation arguments, including target IDs and input) is always visible
+in gray beneath it, even when tool results are collapsed. Session lists, the
+widget, and completion notifications show the session's original description.
+Older saved sessions and tool calls without descriptions remain readable,
+falling back to their command, task, or other arguments. Callers must supply a
+description for every new call; blank or missing values are rejected before
+execution.
+
 ## Remote processes over SSH
 
 Install a `babysit` CLI with `--host` support on both machines (tested with
@@ -79,11 +112,11 @@ 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_check { id: "remote-repl", screen: true }
-babysit_send { id: "remote-repl", text: "print(42)" }
-babysit_kill { id: "remote-repl" }
+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 { description: "Read the remote REPL screen", id: "remote-repl", screen: true }
+babysit_send { description: "Evaluate a value in the remote REPL", id: "remote-repl", text: "print(42)" }
+babysit_kill { description: "Close the remote REPL", id: "remote-repl" }
 ```
 
 `host` omitted (or `"local"`) preserves local behavior. `cwd` is process-only:
@@ -132,9 +165,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
@@ -183,8 +216,8 @@ 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 }
-babysit_check { id: "cargo-test", pattern: "FAIL|ERROR", lines: 50 }
+babysit_check { description: "Inspect the recent test output", id: "cargo-test", lines: 50 }
+babysit_check { description: "Find test failures", id: "cargo-test", pattern: "FAIL|ERROR", lines: 50 }
 ```
 
 Tail and search results are capped at 200 lines and default to a 4 KB total
@@ -269,7 +302,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 +313,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

@@ -51,6 +51,18 @@ import { Type, type TSchema } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents";
 
+const descriptionSchema = Type.String({
+	minLength: 1,
+	pattern: "\\S",
+	description: "Required short human-readable purpose for this operation. Explain what it does and why; shown prominently to the user.",
+});
+
+function requireDescription(value: unknown): void {
+	if (typeof value !== "string" || !value.trim()) {
+		throw new Error("`description` is required and must be a non-blank string for every babysit tool call.");
+	}
+}
+
 // Dedicated babysit state root so pi-managed sessions never collide with the
 // user's own manual `babysit` sessions. The base is namespaced per pi session
 // on session_start (BABYSIT_DIR=<base>/<session-id>), so each pi session only
@@ -127,7 +139,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 +172,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 +533,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 +582,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);
@@ -1366,6 +1385,17 @@ function escapeCommandForDisplay(command: string): string {
 		);
 }
 
+function renderOperationCall(name: string, args: Record<string, unknown> | undefined, theme: Theme) {
+	const { description, ...operationArgs } = args ?? {};
+	const purpose = typeof description === "string" ? description.trim() : "";
+	const title = theme.fg("muted", theme.bold(name));
+	const heading = purpose
+		? `${title}  ${theme.fg("warning", theme.bold(escapeCommandForDisplay(purpose)))}`
+		: title;
+	const raw = Object.keys(operationArgs).length ? JSON.stringify(operationArgs) : "";
+	return new Text(heading + (raw ? `\n${theme.fg("muted", escapeCommandForDisplay(raw))}` : ""), 0, 0);
+}
+
 export function readableLaunchCommand(command: string): string {
 	// Older sessions quoted every argv element, including safe paths and flags.
 	if (!command.startsWith("'") || !command.endsWith("'") || !command.includes("' '")) return command;
@@ -1397,6 +1427,7 @@ export interface ProcessCompletionNotice {
 	status: CompletionStatus;
 	runtime: string;
 	summary: string;
+	description?: string;
 	command: string | undefined;
 	logPath: string;
 	output: string;
@@ -1414,6 +1445,7 @@ interface ProcessCompletionMessage {
 		runtime?: string;
 		logPath?: string;
 		command?: string;
+		description?: string;
 		count: number;
 		totalCount: number;
 		remainingCount: number;
@@ -1424,6 +1456,7 @@ interface ProcessCompletionMessage {
 			status: CompletionStatus;
 			runtime: string;
 			command: string | undefined;
+			description?: string;
 			logPath: string;
 		}>;
 	};
@@ -1465,9 +1498,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 +1527,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 +1568,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 +1584,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 +2146,7 @@ async function reserveUniqueSessionId(name: string): Promise<string> {
 }
 
 interface ProcOpts {
+	description: string;
 	name?: string;
 	command: string;
 	cwd?: string;
@@ -2161,7 +2199,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 +2234,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 +2290,7 @@ function discardDelivery(delivery: DeliverableMessage): void {
 }
 
 interface SubagentOpts {
+	description: string;
 	name?: string;
 	agent?: AgentConfig;
 	task: string;
@@ -2381,6 +2421,7 @@ async function spawnSubagent(
 	writeMeta(id, {
 		kind: "subagent",
 		name: opts.name ?? id,
+		description: opts.description,
 		task: opts.task,
 		launchCommand,
 		notified: true,
@@ -2470,6 +2511,7 @@ async function spawnSubagent(
 	writeMeta(id, {
 		kind: "subagent",
 		name: opts.name ?? id,
+		description: opts.description,
 		task: opts.task,
 		launchCommand,
 		promptOffset: resp.offset,
@@ -2566,6 +2608,7 @@ export interface WidgetSessionListState {
 
 export interface WidgetSessionDisplay {
 	id: string;
+	description?: string;
 	header: string;
 	tail: string[];
 	viewable: boolean;
@@ -2603,7 +2646,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 +2732,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);
@@ -3265,7 +3309,7 @@ async function waitForTask(
 				ok: completed.ok,
 				text:
 					`Subagent ${id} finished its task (${stats}).\n` +
-					`${subagentReuseHint(readMeta(id)?.reapAfter)} Follow-up: babysit_send { id: "${id}" }, ` +
+					`${subagentReuseHint(readMeta(id)?.reapAfter)} Follow-up: babysit_send { description: "Assign a follow-up task", id: "${id}" }, ` +
 					`or babysit_kill when done.\n\n${completed.body}`,
 				status: st,
 				progress: prog,
@@ -3540,7 +3584,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 ?? "?"}`) +
@@ -3693,7 +3737,14 @@ export default function (pi: ExtensionAPI) {
 		const execute = tool.execute;
 		pi.registerTool({
 			...tool,
+			description: tool.description + " Always provide a short human-readable `description` explaining the purpose of this operation.",
+			promptGuidelines: [
+				"Every babysit tool call requires a short description explaining its purpose for the user. Operation descriptions for check/send/wait/kill do not change the session's original description.",
+				...(tool.promptGuidelines ?? []),
+			],
+			renderCall: tool.renderCall ?? ((args, theme) => renderOperationCall(tool.name, args as Record<string, unknown>, theme)),
 			async execute(toolCallId, params, signal, onUpdate, ctx) {
+				requireDescription((params as { description?: unknown }).description);
 				const result = await execute(toolCallId, params, signal, onUpdate, ctx);
 				if ((result as typeof result & { isError?: boolean }).isError === true) {
 					declaredToolErrors.add(toolCallId);
@@ -3852,6 +3903,7 @@ export default function (pi: ExtensionAPI) {
 				runtime,
 				summary,
 				command: meta.command,
+				description: meta.description,
 				logPath: logPath(session.id),
 				output,
 			});
@@ -3873,7 +3925,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 +3949,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 +3972,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 +3986,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 +4044,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 +4061,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 +4077,7 @@ export default function (pi: ExtensionAPI) {
 					theme,
 				),
 				details,
+				description,
 				// Only read/parse visible sessions on demand.
 				get tail() {
 					try {
@@ -4115,25 +4173,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 +4341,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;
@@ -4289,8 +4349,8 @@ export default function (pi: ExtensionAPI) {
 			block: true,
 			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)} }).`,
+				"Inspect an existing session log with babysit_check { description, id, lines, pattern? }. " +
+				`Retry with a short purpose description as babysit_run({ description: "Explain the purpose of this command", command: ${JSON.stringify(command)} }).`,
 		};
 	});
 
@@ -4318,6 +4378,7 @@ export default function (pi: ExtensionAPI) {
 			return prepareBabysitRunArguments(args) as never;
 		},
 		parameters: Type.Object({
+			description: descriptionSchema,
 			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 +4509,7 @@ export default function (pi: ExtensionAPI) {
 
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const description = params.description.trim();
 			await requireBabysit();
 			const isSubagent = params.profile === "subagent";
 			validateProcessHost(params.host);
@@ -4555,6 +4617,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 +4668,7 @@ export default function (pi: ExtensionAPI) {
 							kind: "process",
 							command: params.command,
 							logPath: logPath(res.id),
+							description,
 							retried,
 							status: outcomeStatus(outcome),
 						},
@@ -4641,6 +4705,7 @@ export default function (pi: ExtensionAPI) {
 							kind: "process",
 							command: params.command,
 							logPath: logPath(res.id),
+							description,
 							retried,
 							status: outcomeStatus(outcome),
 						},
@@ -4657,9 +4722,9 @@ 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` +
-								`Inspect: babysit_check { id: "${res.id}" } (screen: true for TUIs) · ` +
-								`Wait: babysit_wait { id: "${res.id}" } · Kill: babysit_kill { id: "${res.id}" }\n` +
+								`Process started (id: ${res.id}). ${NOTIFY_MARKER}\nDescription: ${escapeCommandForDisplay(description)}\nLog: ${logPath(res.id)}\n${nextStep}\n` +
+								`Inspect: babysit_check { description: "Inspect session output", id: "${res.id}" } (screen: true for TUIs) · ` +
+								`Wait: babysit_wait { description: "Wait for completion", id: "${res.id}" } · Kill: babysit_kill { description: "Stop this session", id: "${res.id}" }\n` +
 								`Human can watch/take over: /babysit`,
 						},
 					],
@@ -4667,6 +4732,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 +4768,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 +4817,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,9 +4830,9 @@ 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` +
-							`Progress: babysit_check { id: "${res.id}" } (only when inspection is needed)\n` +
-							`Collect:  babysit_wait  { id: "${res.id}" }\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 { description: "Inspect agent progress", id: "${res.id}" } (only when inspection is needed)\n` +
+							`Collect:  babysit_wait  { description: "Collect the agent result", id: "${res.id}" }\n` +
 							`Human can watch/steer: /babysit (pick ${res.id})`,
 					},
 				],
@@ -4775,25 +4843,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 {
@@ -4843,6 +4916,7 @@ export default function (pi: ExtensionAPI) {
 			"Do NOT poll this while merely waiting for a process to end — the exit notification is automatic.",
 		promptSnippet: "Check status/progress of babysit sessions (processes and subagents)",
 		parameters: Type.Object({
+			description: descriptionSchema,
 			id: Type.Optional(Type.String({ description: "Session id. Omit to list sessions." })),
 			state: Type.Optional(
 				StringEnum(["running", "terminal", "all"] as const, {
@@ -4932,7 +5006,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 +5074,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 +5120,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)}`);
@@ -5081,11 +5157,12 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Send input to a babysit session. Process: `text` types a line into its stdin (PTY), " +
 			"`keys` presses named keys (Enter, Tab, Esc, Up/Down/Left/Right, C-c, F1…) — use with " +
-			"babysit_check { screen: true } to drive interactive programs. Subagent: `text` is " +
+			"babysit_check { description, screen: true } to drive interactive programs. Subagent: `text` is " +
 			"STEERING while it works, or a NEW TASK after the current task settles (mode: auto/steer/task) — this " +
 			"is how you resume a finished subagent with full context.",
 		promptSnippet: "Send text/keys to a process, or steering/follow-up tasks to a subagent",
 		parameters: Type.Object({
+			description: descriptionSchema,
 			id: Type.String({ description: "Session id." }),
 			text: Type.Optional(
 				Type.String({ description: "Text to send (a line for processes; a message for subagents)." }),
@@ -5157,7 +5234,7 @@ export default function (pi: ExtensionAPI) {
 					content: [
 						{
 							type: "text",
-							text: `Sent to ${params.id}. Read the reaction with babysit_check { id: "${params.id}"${params.keys?.length ? ", screen: true" : ""} } — don't expect the echo of your own input.`,
+							text: `Sent to ${params.id}. Read the reaction with babysit_check { description: "Inspect the response to input", id: "${params.id}"${params.keys?.length ? ", screen: true" : ""} } — don't expect the echo of your own input.`,
 						},
 					],
 					details: { kind: "process" },
@@ -5274,6 +5351,11 @@ export default function (pi: ExtensionAPI) {
 				// New task → new bookkeeping window, so check/wait track THIS task.
 				writeMeta(params.id, {
 					kind: "subagent",
+					name: meta?.name,
+					description: meta?.description,
+					launchCommand: meta?.launchCommand,
+					reapAfter: meta?.reapAfter,
+					startedAt: meta?.startedAt,
 					task: params.text,
 					// Start after the prompt-acceptance response. This excludes a
 					// preceding run that settled between `send` and RPC acceptance.
@@ -5335,6 +5417,7 @@ export default function (pi: ExtensionAPI) {
 			"the exit notification will resume you.",
 		promptSnippet: "Block until session(s) finish — process exit / output pattern / subagent task done",
 		parameters: Type.Object({
+			description: descriptionSchema,
 			id: Type.Optional(Type.String({ description: "Session id (single wait)." })),
 			ids: Type.Optional(
 				Type.Array(Type.String(), {
@@ -5481,7 +5564,10 @@ export default function (pi: ExtensionAPI) {
 		label: "Babysit: kill",
 		description: "Terminate a babysit session (process or subagent).",
 		promptSnippet: "Terminate a babysit session",
-		parameters: Type.Object({ id: Type.String({ description: "Session id." }) }),
+		parameters: Type.Object({
+			description: descriptionSchema,
+			id: Type.String({ description: "Session id." }),
+		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			await requireBabysit();
 			// Prevent the exit poller racing a requested kill, but restore delivery
@@ -5593,9 +5679,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.23",
   "description": "Run any shell command and pi subagents under babysit, with context-safe captured output.",
   "keywords": [
     "pi-package",