@oh-my-pi/pi-coding-agent 16.1.15 → 16.1.16

package/src/internal-urls/local-protocol.ts

@@ -157,7 +157,7 @@ export function resolveLocalUrlToPath(
 }
 
 /**
- * On-disk roots the eval helpers (`read`/`write`/`append`) substitute for
+ * On-disk roots the eval helpers (`read`/`write`) substitute for
  * internal-URL schemes so e.g. `write("local://x.md")` lands where a later
  * `read local://x.md` resolves — instead of a literal `local:/` directory under
  * the cwd (a stdlib `pathlib.Path`/`path.resolve` collapses `local://` to
@@ -169,6 +169,96 @@ export function buildEvalUrlRoots(options: LocalProtocolOptions): Record<string,
 	return { local: resolveLocalRoot(options) };
 }
 
+const LOCAL_WRITE_NOTE = "Use write path local://<file> to persist large intermediate artifacts across turns.";
+
+type ResolvedLocalTarget =
+	| { kind: "listing"; root: string }
+	| { kind: "directory"; path: string }
+	| { kind: "file"; path: string; size: number };
+
+/**
+ * Resolve a local:// URL to its on-disk target with realpath + containment
+ * checks on the root, parent, and target so symlinks cannot escape the session
+ * local root. Does NOT read or decode file contents — callers decide how to
+ * consume the resolved path. Shared by {@link LocalProtocolHandler.resolve} and
+ * {@link resolveLocalUrlToFile}.
+ */
+async function resolveLocalTarget(url: InternalUrl, opts: LocalProtocolOptions): Promise<ResolvedLocalTarget> {
+	const localRoot = path.resolve(resolveLocalRoot(opts));
+	await fs.mkdir(localRoot, { recursive: true });
+
+	let resolvedRoot: string;
+	try {
+		resolvedRoot = await fs.realpath(localRoot);
+	} catch (error) {
+		if (isEnoent(error)) {
+			throw new Error("Unable to initialize local:// root");
+		}
+		throw error;
+	}
+
+	const relativePath = extractRelativePath(url);
+	const targetPath = relativePath ? path.resolve(resolvedRoot, relativePath) : resolvedRoot;
+	ensureWithinRoot(targetPath, resolvedRoot);
+
+	if (targetPath === resolvedRoot) {
+		return { kind: "listing", root: resolvedRoot };
+	}
+
+	const parentDir = path.dirname(targetPath);
+	try {
+		const realParent = await fs.realpath(parentDir);
+		ensureWithinRoot(realParent, resolvedRoot);
+	} catch (error) {
+		if (!isEnoent(error)) throw error;
+	}
+
+	let realTargetPath: string;
+	try {
+		realTargetPath = await fs.realpath(targetPath);
+	} catch (error) {
+		if (isEnoent(error)) {
+			throw new Error(`Local file not found: ${url.href}`);
+		}
+		throw error;
+	}
+
+	ensureWithinRoot(realTargetPath, resolvedRoot);
+
+	const stat = await fs.stat(realTargetPath);
+	if (stat.isDirectory()) {
+		return { kind: "directory", path: realTargetPath };
+	}
+	if (!stat.isFile()) {
+		throw new Error(`local:// URL must resolve to a file or directory: ${url.href}`);
+	}
+	return { kind: "file", path: realTargetPath, size: stat.size };
+}
+
+/**
+ * Resolve a local:// URL to a regular on-disk file, applying the same
+ * realpath + containment guarantees as {@link LocalProtocolHandler.resolve}
+ * but WITHOUT reading or UTF-8-decoding its contents. Returns null when there
+ * is no active session or when the URL targets the root listing or a directory;
+ * throws the handler's not-found and "escapes local root" errors for missing
+ * files and symlink escapes.
+ *
+ * Options are resolved via {@link LocalProtocolHandler.resolveOptions} so the
+ * caller-options → override → registry order matches router resolution exactly.
+ * The read tool uses this to detect and emit image files from their real path
+ * before the text-only resource contract would decode the binary into mojibake.
+ */
+export async function resolveLocalUrlToFile(
+	input: string | InternalUrl,
+	context?: ResolveContext,
+): Promise<{ path: string; size: number } | null> {
+	const opts = LocalProtocolHandler.resolveOptions(context);
+	if (!opts) return null;
+	const url = typeof input === "string" ? parseLocalUrl(input) : input;
+	const resolved = await resolveLocalTarget(url, opts);
+	return resolved.kind === "file" ? { path: resolved.path, size: resolved.size } : null;
+}
+
 /**
  * Protocol handler for local:// URLs.
  *
@@ -238,65 +328,22 @@ export class LocalProtocolHandler implements ProtocolHandler {
 			throw new Error("No session - local:// unavailable");
 		}
 
-		const localRoot = path.resolve(resolveLocalRoot(opts));
-		await fs.mkdir(localRoot, { recursive: true });
-
-		let resolvedRoot: string;
-		try {
-			resolvedRoot = await fs.realpath(localRoot);
-		} catch (error) {
-			if (isEnoent(error)) {
-				throw new Error("Unable to initialize local:// root");
-			}
-			throw error;
-		}
-
-		const relativePath = extractRelativePath(url);
-		const targetPath = relativePath ? path.resolve(resolvedRoot, relativePath) : resolvedRoot;
-		ensureWithinRoot(targetPath, resolvedRoot);
-
-		if (targetPath === resolvedRoot) {
-			return buildListing(url, resolvedRoot);
-		}
-
-		const parentDir = path.dirname(targetPath);
-		try {
-			const realParent = await fs.realpath(parentDir);
-			ensureWithinRoot(realParent, resolvedRoot);
-		} catch (error) {
-			if (!isEnoent(error)) throw error;
-		}
-
-		let realTargetPath: string;
-		try {
-			realTargetPath = await fs.realpath(targetPath);
-		} catch (error) {
-			if (isEnoent(error)) {
-				throw new Error(`Local file not found: ${url.href}`);
-			}
-			throw error;
-		}
-
-		ensureWithinRoot(realTargetPath, resolvedRoot);
-
-		const stat = await fs.stat(realTargetPath);
-		if (stat.isDirectory()) {
-			return buildDirectoryResource(url.href, realTargetPath, [
-				"Use write path local://<file> to persist large intermediate artifacts across turns.",
-			]);
+		const resolved = await resolveLocalTarget(url, opts);
+		if (resolved.kind === "listing") {
+			return buildListing(url, resolved.root);
 		}
-		if (!stat.isFile()) {
-			throw new Error(`local:// URL must resolve to a file or directory: ${url.href}`);
+		if (resolved.kind === "directory") {
+			return buildDirectoryResource(url.href, resolved.path, [LOCAL_WRITE_NOTE]);
 		}
 
-		const content = await Bun.file(realTargetPath).text();
+		const content = await Bun.file(resolved.path).text();
 		return {
 			url: url.href,
 			content,
-			contentType: getContentType(realTargetPath),
+			contentType: getContentType(resolved.path),
 			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: realTargetPath,
-			notes: ["Use write path local://<file> to persist large intermediate artifacts across turns."],
+			sourcePath: resolved.path,
+			notes: [LOCAL_WRITE_NOTE],
 		};
 	}
 

package/src/main.ts

@@ -945,6 +945,7 @@ async function buildSessionOptions(
 interface RunRootCommandDependencies {
 	createAgentSession?: typeof createAgentSession;
 	discoverAuthStorage?: typeof discoverAuthStorage;
+	selectSession?: typeof selectSession;
 	runAcpMode?: RunAcpMode;
 	settings?: Settings;
 	forceSetupWizard?: boolean;
@@ -1131,7 +1132,8 @@ export async function runRootCommand(
 	// (see issue #1668).
 	if (typeof parsedArgs.resume === "string" && !sessionManager) {
 		writeStartupNotice(parsedArgs, `${chalk.dim("Resume cancelled: session is in another project.")}\n`);
-		return;
+		stopStartupWatchdog();
+		process.exit(0);
 	}
 
 	// Handle --resume (no value): show session picker
@@ -1147,17 +1149,26 @@ export async function runRootCommand(
 			preloadedAllSessions = await logger.time("SessionManager.listAll", SessionManager.listAll);
 			if (preloadedAllSessions.length === 0) {
 				writeStartupNotice(parsedArgs, `${chalk.dim("No sessions found")}\n`);
-				return;
+				stopStartupWatchdog();
+				process.exit(0);
 			}
 		}
 		pauseStartupWatchdog();
-		const selected = await logger.time("selectSession", selectSession, folderSessions, {
+		const selected = await logger.time("selectSession", deps.selectSession ?? selectSession, folderSessions, {
 			allSessions: preloadedAllSessions,
 		});
 		resumeStartupWatchdog();
 		if (!selected) {
 			writeStartupNotice(parsedArgs, `${chalk.dim("No session selected")}\n`);
-			return;
+			// Quit instead of returning: startup already armed long-lived handles
+			// (theme watcher + SIGWINCH/macOS appearance listeners via initTheme,
+			// settings save timer, model registry) that keep the event loop alive,
+			// so a bare return hangs the process after the picker leaves the alt
+			// screen. No session was built here, so there is nothing to flush. The
+			// in-session `/resume` picker (selector-controller.ts) takes a different
+			// onCancel that just closes the overlay — only this startup path exits.
+			stopStartupWatchdog();
+			process.exit(0);
 		}
 		// Resuming a session from another project: switch the process into that
 		// project's directory and refresh cwd-derived caches before the session is

package/src/modes/acp/acp-event-mapper.ts

@@ -468,8 +468,13 @@ function buildEvalStartText(args: unknown): string | undefined {
 	if (typeof args !== "object" || args === null || Array.isArray(args)) {
 		return undefined;
 	}
-	const cells = (args as EvalCellContainer).cells;
-	if (!Array.isArray(cells) || cells.length === 0) {
+	const container = args as EvalCellContainer & EvalCellLike;
+	const cells = Array.isArray(container.cells)
+		? container.cells
+		: typeof container.code === "string"
+			? [container]
+			: [];
+	if (cells.length === 0) {
 		return undefined;
 	}
 	const lines: string[] = [];

package/src/modes/components/plugin-settings.ts

@@ -11,6 +11,7 @@
 import {
 	Container,
 	Input,
+	matchesKey,
 	type SelectItem,
 	SelectList,
 	type SettingItem,
@@ -36,13 +37,18 @@ import { DynamicBorder } from "./dynamic-border";
 
 /**
  * Forwards a keystroke to `input`, but cancels via `onCancel` when the user presses Escape.
+ *
+ * Escape is decoded via `matchesKey` rather than a raw `\x1b` compare: inside the
+ * fullscreen settings overlay the kitty keyboard protocol is active (ghostty/kitty),
+ * where the Escape key arrives as the CSI-u sequence `\x1b[27u`, not a bare `\x1b`.
+ * The literal fallbacks preserve legacy single/double-escape on terminals without it.
  */
 export function handleInputOrEscape(
 	data: string,
 	input: { handleInput(data: string): void },
 	onCancel: () => void,
 ): void {
-	if (data === "\x1b" || data === "\x1b\x1b") {
+	if (data === "\x1b" || data === "\x1b\x1b" || matchesKey(data, "escape")) {
 		onCancel();
 		return;
 	}

package/src/modes/components/session-selector.ts

@@ -5,6 +5,7 @@ import {
 	Input,
 	matchesKey,
 	padding,
+	parseSgrMouse,
 	replaceTabs,
 	ScrollView,
 	Spacer,
@@ -161,6 +162,12 @@ export function mergeSessionRanking(
 class SessionList implements Component {
 	#filteredSessions: SessionInfo[] = [];
 	#selectedIndex: number = 0;
+	// Maps a 0-based line within this list's own render to a filtered-session
+	// index, or undefined for chrome rows (search line, blanks, scrollbar gap).
+	// Rebuilt every render so the picker's mouse hit-testing tracks the live
+	// scroll window. Only consulted while the picker holds the alternate screen
+	// (where the overlay enables mouse tracking and paints from screen row 0).
+	#hitRows: (number | undefined)[] = [];
 	readonly #searchInput: Input;
 	onSelect?: (session: SessionInfo) => void;
 	onCancel?: () => void;
@@ -257,12 +264,32 @@ class SessionList implements Component {
 		}
 	}
 
+	/** Resolve a list-local rendered-line index to a filtered-session index. */
+	hitTestSession(line: number): number | undefined {
+		return this.#hitRows[line];
+	}
+
+	/** Wheel notch: move the selection one step (clamped, no wrap). */
+	handleWheel(delta: -1 | 1): void {
+		if (this.#filteredSessions.length === 0) return;
+		this.#selectedIndex = Math.max(0, Math.min(this.#filteredSessions.length - 1, this.#selectedIndex + delta));
+	}
+
+	/** Mouse click: select the session under the pointer and resume it. */
+	selectAndConfirm(index: number): void {
+		const session = this.#filteredSessions[index];
+		if (!session) return;
+		this.#selectedIndex = index;
+		this.onSelect?.(session);
+	}
+
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
 
 	render(width: number): readonly string[] {
 		const lines: string[] = [];
+		this.#hitRows = [];
 
 		// Render search input
 		lines.push(...this.#searchInput.render(width));
@@ -311,9 +338,11 @@ class SessionList implements Component {
 		// Each session block is built into sessionLines, then wrapped by ScrollView
 		// so the right-edge scrollbar is proportional at the physical-line level.
 		const sessionLines: string[] = [];
+		const sessionRowIndex: number[] = [];
 		const overflow = this.#filteredSessions.length > maxVisible;
 		const rowWidth = Math.max(0, width - (overflow ? 1 : 0));
 		for (let i = startIndex; i < endIndex; i++) {
+			const blockStart = sessionLines.length;
 			const session = this.#filteredSessions[i];
 			const isSelected = i === this.#selectedIndex;
 
@@ -363,6 +392,7 @@ class SessionList implements Component {
 
 			sessionLines.push(metadataLine);
 			sessionLines.push(""); // Blank line between sessions
+			for (let k = blockStart; k < sessionLines.length; k++) sessionRowIndex[k] = i;
 		}
 
 		// Wrap the rendered window in a ScrollView for a proportional right-edge bar.
@@ -375,16 +405,10 @@ class SessionList implements Component {
 			theme: { track: t => theme.fg("muted", t), thumb: t => theme.fg("accent", t) },
 		});
 		sv.setScrollOffset(Math.round(startIndex * linesPerItem));
-		lines.push(...sv.render(width));
-
-		// Add keybinding hint
-		lines.push("");
-		lines.push(
-			theme.fg(
-				"muted",
-				`  [Del delete · Enter select · Tab ${this.#showCwd ? "current folder" : "all projects"} · Esc cancel]`,
-			),
-		);
+		const sessionRegionStart = lines.length;
+		const svLines = sv.render(width);
+		for (let k = 0; k < svLines.length; k++) this.#hitRows[sessionRegionStart + k] = sessionRowIndex[k];
+		lines.push(...svLines);
 
 		return lines;
 	}
@@ -462,6 +486,13 @@ export interface SessionSelectorOptions {
 	 * Omitted only in tests; defaults to a conservative 24 rows.
 	 */
 	getTerminalRows?: () => number;
+	/**
+	 * Fill the whole viewport and pin the footer (hint + bottom border) to the
+	 * last rows, so the footer stops drifting as the list window changes height.
+	 * Set by the standalone `--resume` picker (fullscreen alternate screen); the
+	 * in-editor selector leaves it off and renders compactly.
+	 */
+	fillHeight?: boolean;
 }
 
 /**
@@ -470,6 +501,13 @@ export interface SessionSelectorOptions {
 export class SessionSelectorComponent extends Container {
 	#sessionList: SessionList;
 	#confirmationDialog: HookSelectorComponent | null = null;
+	// Hosts whichever of `#sessionList` / `#confirmationDialog` is live this
+	// frame. The delete dialog REPLACES the list in this slot rather than being
+	// appended below the picker chrome, so the picker is always
+	// `chrome + max(list, dialog) + chrome` and never overflows the viewport
+	// (issue #3283: an overflowing dialog frame committed the header into
+	// scrollback, stranding it above the viewport once the dialog closed).
+	#contentSlot: Container;
 	#messageContainer: Container;
 	#headerText: Text;
 	#onDelete?: (session: SessionInfo) => Promise<boolean>;
@@ -479,6 +517,18 @@ export class SessionSelectorComponent extends Container {
 	#globalSessions: SessionInfo[] | null = null;
 	#scope: "folder" | "all" = "folder";
 	#toggling = false;
+	// 0-based line where the session list begins within this component's own
+	// render, captured each frame. The fullscreen picker overlay paints from
+	// screen row 0, so a mouse row maps to `row - #listLineOffset` inside the
+	// list. Only meaningful while the picker holds the alternate screen.
+	#listLineOffset = 0;
+	// 0-based line where the pinned footer begins; clicks at or below it never
+	// hit-test the list, so a footer click on a cramped (trimmed) frame can't
+	// resume a session scrolled off-screen.
+	#footerStart = 0;
+	readonly #getTerminalRows: () => number;
+	readonly #fillHeight: boolean;
+	readonly #bottomBorder = new DynamicBorder();
 
 	constructor(
 		sessions: SessionInfo[],
@@ -494,6 +544,8 @@ export class SessionSelectorComponent extends Container {
 		this.#loadAllSessions = options.loadAllSessions;
 		this.#folderSessions = sessions;
 		this.#globalSessions = options.allSessions ?? null;
+		this.#getTerminalRows = options.getTerminalRows ?? (() => 24);
+		this.#fillHeight = options.fillHeight ?? false;
 		// Add header
 		this.addChild(new Spacer(1));
 		this.#headerText = new Text(this.#headerLabel(), 1, 0);
@@ -517,11 +569,9 @@ export class SessionSelectorComponent extends Container {
 				void this.#toggleScope();
 			};
 		}
-		this.addChild(this.#sessionList);
-
-		// Add bottom border
-		this.addChild(new Spacer(1));
-		this.addChild(new DynamicBorder());
+		this.#contentSlot = new Container();
+		this.#contentSlot.addChild(this.#sessionList);
+		this.addChild(this.#contentSlot);
 	}
 
 	#headerLabel(): string {
@@ -582,6 +632,15 @@ export class SessionSelectorComponent extends Container {
 
 	#showDeleteConfirmation(session: SessionInfo): void {
 		const displayName = session.title || session.firstMessage.slice(0, 40) || session.id;
+		const closeDialog = () => {
+			this.#confirmationDialog = null;
+			// Restore the SessionList into the content slot so the picker is back
+			// to its normal layout on the very next render — the same frame the
+			// dialog disappears.
+			this.#contentSlot.clear();
+			this.#contentSlot.addChild(this.#sessionList);
+			this.#onRequestRender?.();
+		};
 		this.#confirmationDialog = new HookSelectorComponent(
 			`Delete session?\n${displayName}`,
 			["Yes", "No"],
@@ -597,25 +656,61 @@ export class SessionSelectorComponent extends Container {
 						this.#showError(err instanceof Error ? err.message : String(err));
 					}
 				}
-				// Close confirmation dialog
-				this.removeChild(this.#confirmationDialog!);
-				this.#confirmationDialog = null;
-				// Request rerender
-				this.#onRequestRender?.();
-			},
-			() => {
-				// Cancel - close confirmation dialog
-				this.removeChild(this.#confirmationDialog!);
-				this.#confirmationDialog = null;
-				// Request rerender
-				this.#onRequestRender?.();
+				closeDialog();
 			},
+			closeDialog,
 		);
-		// Show confirmation dialog
-		this.addChild(this.#confirmationDialog);
+		// Swap the SessionList out of the content slot and mount the dialog in its
+		// place: the dialog competes only with the SessionList's rendered budget,
+		// never the SessionList AND the picker chrome, so the picker frame stays
+		// inside the terminal viewport and the TUI never commits the header into
+		// scrollback (issue #3283).
+		this.#contentSlot.clear();
+		this.#contentSlot.addChild(this.#confirmationDialog);
+		this.#onRequestRender?.();
+	}
+
+	/**
+	 * Concatenate the children's renders (like {@link Container}) while recording
+	 * the line where the session list begins, so the fullscreen picker can hit-
+	 * test mouse rows against the live list window. SessionList rebuilds its lines
+	 * every frame, so Container's reference-memoization never applied here.
+	 *
+	 * In fill-height mode the body is padded (or, on a cramped terminal, trimmed)
+	 * to leave exactly enough room for the footer at the screen bottom, so the
+	 * footer is always visible and never drifts as the list window resizes. The
+	 * in-editor selector just appends the footer directly.
+	 */
+	render(width: number): readonly string[] {
+		const lines: string[] = [];
+		for (const child of this.children) {
+			const childLines = child.render(width);
+			if (child === this.#contentSlot) this.#listLineOffset = lines.length;
+			for (const line of childLines) lines.push(line);
+		}
+		const footer = this.#footerLines(width);
+		if (this.#fillHeight) {
+			const target = Math.max(0, this.#getTerminalRows() - footer.length);
+			if (lines.length > target) lines.length = target;
+			else for (let i = lines.length; i < target; i++) lines.push("");
+		}
+		this.#footerStart = lines.length;
+		for (const line of footer) lines.push(line);
+		return lines;
+	}
+
+	/** Blank · keybinding hint · bottom border. Rendered by {@link render}. */
+	#footerLines(width: number): string[] {
+		const scopeHint = this.#scope === "all" ? "current folder" : "all projects";
+		const hint = theme.fg("muted", `  [Del delete · Enter select · Tab ${scopeHint} · Esc cancel]`);
+		return ["", hint, "", ...this.#bottomBorder.render(width)];
 	}
 
 	handleInput(keyData: string): void {
+		if (keyData.startsWith("\x1b[<")) {
+			this.#handleMouse(keyData);
+			return;
+		}
 		if (this.#confirmationDialog) {
 			this.#confirmationDialog.handleInput(keyData);
 		} else {
@@ -623,6 +718,25 @@ export class SessionSelectorComponent extends Container {
 		}
 	}
 
+	/**
+	 * SGR mouse reports, delivered only while the picker holds the alternate
+	 * screen (the fullscreen overlay enables tracking and paints from screen row
+	 * 0). Wheel scrolls the list; a left click resumes the session under the
+	 * pointer. Mouse is inert while the delete-confirmation dialog is open.
+	 */
+	#handleMouse(data: string): void {
+		if (this.#confirmationDialog) return;
+		const event = parseSgrMouse(data);
+		if (!event) return;
+		if (event.wheel !== null) {
+			this.#sessionList.handleWheel(event.wheel);
+			return;
+		}
+		if (!event.leftClick || event.row >= this.#footerStart) return;
+		const index = this.#sessionList.hitTestSession(event.row - this.#listLineOffset);
+		if (index !== undefined) this.#sessionList.selectAndConfirm(index);
+	}
+
 	getSessionList(): SessionList {
 		return this.#sessionList;
 	}

package/src/modes/controllers/command-controller.ts

@@ -1172,6 +1172,11 @@ export class CommandController {
 	}
 
 	async handleHandoffCommand(customInstructions?: string): Promise<void> {
+		if (this.ctx.session.isStreaming) {
+			this.ctx.showWarning("Wait for the current response to finish or abort it before handing off.");
+			return;
+		}
+
 		const entries = this.ctx.sessionManager.getEntries();
 		const messageCount = entries.filter(e => e.type === "message").length;
 

package/src/modes/rpc/rpc-mode.ts

@@ -1008,6 +1008,12 @@ export async function runRpcMode(
 			}
 
 			case "handoff": {
+				// Resetting the agent mid-stream lets the live turn keep emitting into a
+				// session that handoff has already torn down. Refuse while a prompt is in
+				// flight (mirrors the TUI /handoff guard).
+				if (session.isStreaming) {
+					return error(id, "handoff", "Cannot hand off while a response is in progress");
+				}
 				const result = await session.handoff(command.customInstructions);
 				return success(id, "handoff", result ? { savedPath: result.savedPath } : null);
 			}

package/src/modes/utils/copy-targets.ts

@@ -127,8 +127,13 @@ export function extractQuoteBlocks(text: string): QuoteBlock[] {
 
 function extractEvalCode(args: unknown): { code: string; language: string } | undefined {
 	if (!args || typeof args !== "object") return undefined;
-	const cells = (args as { cells?: unknown }).cells;
-	if (!Array.isArray(cells)) return undefined;
+	const argsObj = args as { cells?: unknown; code?: unknown };
+	const cells = Array.isArray(argsObj.cells)
+		? argsObj.cells
+		: typeof argsObj.code === "string"
+			? [argsObj]
+			: undefined;
+	if (!cells) return undefined;
 
 	const codeBlocks: string[] = [];
 	let language = "python";

package/src/prompts/system/system-prompt.md

@@ -109,9 +109,9 @@ You MUST use the specialized tool over its shell equivalent:
 {{#has tools "lsp"}}- Code intelligence → `{{toolRefs.lsp}}`.{{/has}}
 {{#has tools "search"}}- Regex search → `{{toolRefs.search}}`, not `grep`, `rg`, or `awk`.{{/has}}
 {{#has tools "find"}}- Globbing → `{{toolRefs.find}}`, not `ls **/*.ext` or `fd`.{{/has}}
-{{#has tools "eval"}}- Quick compute → `{{toolRefs.eval}}`; you SHOULD go step by step.{{/has}}
-{{#has tools "bash"}}- Use `{{toolRefs.bash}}` for terminal work—builds, tests, git, package managers—and pipelines that COMPUTE a fact: `wc -l`, `sort | uniq -c`, `comm`, `diff a b`, checksums. Commands shadowing the tools above are blocked.
-- Litmus: produces a count, frequency, set difference, or checksum no tool returns → bash. Merely moves, pages, or trims bytes a tool can fetch → use the tool.{{/has}}
+{{#has tools "eval"}}- Default for any compute: `{{toolRefs.eval}}` cells. Bash is the EXCEPTION — only single binary calls or short fact-computing pipelines (`wc -l`, `sort | uniq -c`, `diff`, checksums). The moment a command grows a loop, conditional, heredoc, `-e`/`-c` script, `$(…)` nesting, or >2 pipe stages, it's a program → `{{toolRefs.eval}}`. NEVER write multiline or inline-script bash.{{/has}}
+{{#has tools "bash"}}- `{{toolRefs.bash}}`: real binaries and short fact pipelines only. Commands shadowing the specialized tools above are blocked.{{/has}}
+{{#has tools "bash"}}- Litmus: one external-CLI call or short pipeline returning a count, frequency, set difference, or checksum → bash.{{#has tools "eval"}} Needs control flow, state, or fights shell quoting → `{{toolRefs.eval}}`.{{/has}} Merely moves, pages, or trims bytes a tool can fetch → use the tool.{{/has}}
 
 {{#has tools "report_tool_issue"}}
 <critical>

package/src/prompts/system/workflow-notice.md

@@ -11,16 +11,16 @@ Worth it when the task benefits from decomposition + parallel coverage, or from
 </when>
 
 <helpers>
-State persists across cells, so scout in one cell and fan out in the next. Every cell has:
+State persists across eval calls, so scout in one call and fan out in the next. Every eval call has:
 
-- `agent(prompt, *, agent_type="task", model=None, label=None, schema=None)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent_type` picks a discovered agent ("explore", "reviewer", "oracle", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes; eval-spawned agents nest at most 3 deep.
+- `agent(prompt, *, agent="task", model=None, label=None, schema=None, isolated=None, apply=None, merge=None, handle=False)` — run ONE subagent; returns its final text, or the validated object when `schema` (a JSON Schema dict) is given. With `schema` the subagent is forced to emit structured output that is validated for you — branch on the object, not on parsed prose. `agent` picks a discovered agent ("explore", "reviewer", "oracle", …); `label` names the artifact. Shared background goes in a `local://` file referenced from each prompt, not a parameter. Subagents are told their final text IS the return value, so they hand back raw data. `agent()` blocks until the subagent finishes; eval-spawned agents nest at most 3 deep. Pass `isolated=True` to run the spawn in a copy-on-write worktree so parallel `agent()` calls can edit overlapping files safely — strict opt-in, mirrors the `task` tool, defaults off regardless of `task.isolation.mode`; `isolated=True` while the setting is `"none"` errors out instead of silently downgrading. With isolation, `apply=False` keeps changes in the worktree, and `merge=False` forces patch mode even when the setting is `"branch"`. Captured root patch path, branch name, nested repo patches, and apply summary reach the workflow through `handle=True` — combine it with `apply=False` (or `apply=False, schema=…`) and read `node["patch_path"]`, `node["branch_name"]`, `node["nested_patches"]`, `node["changes_applied"]`, `node["isolation_summary"]` (JS: same keys camelCased) to recover artifacts.
 - `parallel(thunks)` — run zero-arg callables concurrently through a bounded pool, preserving input order; returns once all finish. The pool is bounded by the session's `task` concurrency — don't hand-tune it; fan out as wide as the work divides. A thunk that raises propagates — wrap risky work in `try/except` inside the thunk to keep partial results. In a loop, bind each closure's value with a default arg (`lambda d=d: …`) or every thunk captures the last one.
 - `pipeline(items, *stages)` — map items through `stages` left-to-right. There is a BARRIER between stages: ALL items clear stage N before stage N+1 begins. Each stage is a one-arg callable; stage 1 gets the original item, later stages get the previous result. Same pool width as `parallel()`.
 - `completion(prompt, *, model="default", system=None, schema=None)` — oneshot, stateless model call (no tools, no history). Tiers: "smol", "default", "slow". Cheap classification/scoring inside a fan-out.
 - `log(message)` — emit a progress line above the status tree. `phase(title)` — start a phase; the status lines that follow group under it.
 - `budget` — `budget.total` (output-token ceiling, or `None` when none is set), `budget.spent()` (tokens spent this turn — main loop + eval subagents), `budget.remaining()` (`math.inf` when total is `None`), `budget.hard` (whether it's enforced). A ceiling is set by the user: `+Nk` in their message is advisory (you self-limit via `budget.remaining()`), `+Nk!` (or Goal Mode) is hard — `agent()` refuses to spawn once spent reaches it. Gate loops on `budget.total` first, since it's `None` when the user set no budget.
 
-Everything runs INLINE and synchronously inside the eval call — no background mode, no resume, no separate progress app. Each eval call is one well-scoped fan-out; chain several across cells and turns for multi-phase work, reading each result before you decide the next phase.
+Everything runs INLINE and synchronously inside the eval call — no background mode, no resume, no separate progress app. Each eval call is one well-scoped fan-out; chain several across calls and turns for multi-phase work, reading each result before you decide the next phase.
 </helpers>
 
 <structure>

package/src/prompts/tools/bash.md

@@ -1,5 +1,19 @@
 Runs bash in a shell session — terminal ops: git, bun, cargo, python.
 
+# When to use bash — and when not to
+
+Bash invokes **real binaries** with simple args. It is NOT a scripting surface.
+
+Use bash ONLY for: a single binary call, or one short pipeline that COMPUTES a fact (`wc -l`, `sort | uniq -c`, `comm`, `diff`, a checksum, `git status`).
+
+Anything below → `eval` cell, not bash:
+- Inline interpreter scripts (`-e`/`-c`/`--eval`) when an eval runtime exists for that language
+- Heredocs (`<<EOF`), `while`/`for`/`if`/`case` shell control flow
+- `$(…)` command substitution nested inside another command
+- Pipelines with more than two stages, or stages that need control flow or quote/JSON escaping
+- Multiline commands, `&&`-chains mixing control flow
+- Quote/JSON escaping that fights the shell
+
 <instruction>
 - `cwd` sets the working dir, not `cd dir && …`
 - `env: { NAME: "…" }` for multiline / quote-heavy / untrusted values; reference `$NAME`
@@ -14,7 +28,9 @@ Runs bash in a shell session — terminal ops: git, bun, cargo, python.
 </instruction>
 
 <critical>
+- Bash invokes real binaries with simple args; it is NOT a scripting surface. Loops, conditionals, heredocs, inline interpreter scripts (`-e`/`-c`/`--eval`) when an eval runtime exists, several piped stages, or quote/JSON escaping mean you're writing a program → use `eval` cells: restartable, stateful, and free of shell-quoting traps.
 - NEVER shell out to search content or files: `grep/rg` → `search`.
+- NEVER use `ls` or `find` to list or locate files — `ls` → `read` (a directory path lists entries), `find` → the `find` tool (globbing). This is non-negotiable, even for a single quick listing.
 - Avoid head/tail/redirections: stderr already merged; long output auto-truncated, FULL capture kept at `artifact://<id>`.
 </critical>