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

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/components/status-line/component.ts

@@ -727,10 +727,12 @@ export class StatusLineComponent implements Component {
 
 		let contextWindow = state.model?.contextWindow ?? this.session.model?.contextWindow ?? 0;
 		let contextPercent: number | null = 0;
+		let contextTokens = 0;
 		if (includeContext) {
 			const breakdown = this.getCachedContextBreakdown();
+			contextTokens = breakdown.usedTokens;
 			contextWindow = breakdown.contextWindow || contextWindow;
-			contextPercent = contextWindow > 0 ? (breakdown.usedTokens / contextWindow) * 100 : 0;
+			contextPercent = contextWindow > 0 ? (breakdown.usedTokens / contextWindow) * 100 : null;
 		}
 
 		// Collab guest: context comes from the host's state frames — the local
@@ -738,6 +740,7 @@ export class StatusLineComponent implements Component {
 		const collabState = this.#collabStatus?.stateOverride;
 		if (collabState?.contextUsage) {
 			contextWindow = collabState.contextUsage.contextWindow || contextWindow;
+			contextTokens = collabState.contextUsage.tokens ?? contextTokens;
 			contextPercent = collabState.contextUsage.percent ?? contextPercent;
 		}
 
@@ -756,6 +759,7 @@ export class StatusLineComponent implements Component {
 			collab: this.#collabStatus,
 			usageStats,
 			contextPercent,
+			contextTokens,
 			contextWindow,
 			autoCompactEnabled: this.#autoCompactEnabled,
 			subagentCount: this.#subagentCount,

package/src/modes/components/status-line/context-thresholds.ts

@@ -56,10 +56,18 @@ export function getContextUsageLevel(contextPercent: number, contextWindow: numb
 }
 
 /**
- * Format context usage as `<percent>%/<window>` (e.g. `5.1%/1M`), matching the
- * status line's context gauge so subagent and footer renderers stay in sync.
+ * Format context usage as `<percent>%/<window>` when the model window is known.
+ * Unknown windows render as `<tokens>/?`, because `0.0%/0` suggests a real
+ * empty context instead of missing provider metadata.
  */
-export function formatContextUsage(contextPercent: number | null | undefined, contextWindow: number): string {
+export function formatContextUsage(
+	contextPercent: number | null | undefined,
+	contextWindow: number,
+	usedTokens?: number,
+): string {
+	if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
+		return `${formatNumber(usedTokens ?? 0)}/?`;
+	}
 	const pct = contextPercent === null || contextPercent === undefined ? "?" : `${contextPercent.toFixed(1)}%`;
 	return `${pct}/${formatNumber(contextWindow)}`;
 }

package/src/modes/components/status-line/segments.ts

@@ -375,7 +375,7 @@ const contextPctSegment: StatusLineSegment = {
 		const window = ctx.contextWindow;
 
 		const autoIcon = ctx.autoCompactEnabled && theme.icon.auto ? ` ${theme.icon.auto}` : "";
-		const text = `${formatContextUsage(pct, window)}${autoIcon}`;
+		const text = `${formatContextUsage(pct, window, ctx.contextTokens)}${autoIcon}`;
 
 		const color = getContextUsageThemeColor(getContextUsageLevel(pct ?? 0, window));
 		const content = withIcon(theme.icon.context, theme.fg(color, text));

package/src/modes/components/status-line/types.ts

@@ -73,6 +73,7 @@ export interface SegmentContext {
 	};
 	/** Context usage percent, or null when unknown (e.g. right after compaction). */
 	contextPercent: number | null;
+	contextTokens: number;
 	contextWindow: number;
 	autoCompactEnabled: boolean;
 	subagentCount: number;

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

@@ -217,6 +217,7 @@ export class CommandController {
 		try {
 			const result = await shareSession(this.ctx.session.sessionManager, {
 				serverUrl: this.ctx.settings.get("share.serverUrl"),
+				store: this.ctx.settings.get("share.store"),
 				state: this.ctx.session.state,
 				obfuscator: this.ctx.settings.get("share.redactSecrets") ? this.ctx.session.obfuscator : undefined,
 			});
@@ -1171,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

@@ -102,16 +102,16 @@ Use tools whenever they improve correctness, completeness, or grounding.
 {{#has tools "inspect_image"}}- Image tasks: prefer `{{toolRefs.inspect_image}}` over `{{toolRefs.read}}` to spare session context.{{/has}}
 
 # Specialized Tools
-Dedicated tools add gitignore semantics, structured output, and line anchors a raw shell command lacks — reach for them first when they fit:
+You MUST use the specialized tool over its shell equivalent:
 {{#has tools "read"}}- File or directory reads → `{{toolRefs.read}}` (a directory path lists entries).{{/has}}
 {{#has tools "edit"}}- Surgical edits → `{{toolRefs.edit}}`.{{/has}}
 {{#has tools "write"}}- Create or overwrite → `{{toolRefs.write}}`.{{/has}}
 {{#has tools "lsp"}}- Code intelligence → `{{toolRefs.lsp}}`.{{/has}}
-{{#has tools "search"}}- Regex search → `{{toolRefs.search}}`.{{/has}}
-{{#has tools "find"}}- Globbing → `{{toolRefs.find}}`.{{/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.
-- Litmus: produces a count, frequency, set difference, or checksum no tool returns → bash. Otherwise a dedicated tool usually fits.{{/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"}}- 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,8 +28,10 @@ Runs bash in a shell session — terminal ops: git, bun, cargo, python.
 </instruction>
 
 <critical>
-- NEVER trim or silence output: no `| head -n N`, `| tail -n N`, `| less`, `2>&1`, `2>/dev/null`. stderr already merged; long output auto-truncated, FULL capture kept at `artifact://<id>`.
-- Pipelines that COMPUTE a new fact are correct bash: `wc -l`, `sort | uniq -c`, `comm`, `cut`, `diff a b`, `shasum`. Litmus: produces a count, frequency table, set difference, or checksum no tool returns → bash. Merely moves or trims bytes a tool can fetch → use the tool.
+- 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>
 
 <output>

package/src/prompts/tools/eval.md

@@ -1,21 +1,23 @@
-Run code in a persistent kernel using a list of cells.
+Run one step of code in a persistent kernel.
 
 <instruction>
-Cells run in array order. State persists per language across cells, tool calls, and `task` subagents — stage helpers/datasets/clients once, subagents reuse directly, no re-import/serialize.
+**One eval call = one cell = one logical step.** State persists per language across separate eval calls, tool calls, and `task` subagents — define helpers/datasets/clients in one call, then later calls reuse them directly.
 
-Cell fields:
+Work incrementally: imports in one call, define in the next, test, then use — each its own eval call. Re-run setup ONLY after `reset`, a kernel crash, or a `NameError`/`ReferenceError` proving the state is gone. Parallelize work *within* a cell with the `parallel(thunks)` helper, not by batching steps.
+
+Fields:
 
 - `language` — {{#if py}}`"py"` IPython kernel{{/if}}{{#ifAll py js}}, {{/ifAll}}{{#if js}}`"js"` persistent JavaScript VM{{/if}}{{#if rb}}{{#ifAny py js}}, {{/ifAny}}`"rb"` persistent Ruby kernel{{/if}}{{#if jl}}{{#ifAny py js rb}}, {{/ifAny}}`"jl"` persistent Julia kernel{{/if}}.
 - `code` — cell body, verbatim. Newlines/quotes JSON-encoded; no fences, no headers.
 - `title` (optional) — short transcript label (e.g. `"imports"`).
-- `timeout` (optional) — per-cell seconds. Raise only for heavy compute or long non-agent tool calls.
-- `reset` (optional) — wipe this cell's language kernel first.{{#ifAll py js}} Per-language: a `py` reset never touches the JS VM.{{/ifAll}}
+- `timeout` (optional) — seconds. Raise only for heavy compute or long non-agent tool calls.
+- `reset` (optional) — wipe this language's kernel first.{{#ifAll py js}} Per-language: a `py` reset never touches the JS VM.{{/ifAll}}
 
-Work incrementally — one logical step per cell (imports, define, test, use), many small cells per call; workflow notes in the assistant message or `title`, never in cell code.
 {{#if py}}Live event loop: use top-level `await` directly; `asyncio.run(…)` raises "cannot be called from a running event loop".{{/if}}
-{{#if rb}}Ruby: synchronous; helper options are keyword args (e.g. `tree(".", max_depth: 2)`); the last expression auto-displays unless it is `nil`, an assignment, or a definition (like IRB).{{/if}}
-{{#if jl}}Julia: synchronous; helper options are standard keyword args (e.g. `tree(max_depth=2)`); the last expression auto-displays unless it is an assignment or a definition (like the Julia REPL).{{/if}}
-Errors name the failing cell ("Cell 3 failed") — resubmit the fixed cell + any remaining.
+{{#if js}}JS runs under **Bun**: Bun globals/APIs are available (`Bun.file`, `Bun.write`, `Bun.$`, `fetch`, `Buffer`); top-level `await`/`return` work directly.{{/if}}
+{{#if rb}}Ruby: synchronous; helper options are keyword args (e.g. `output("id", limit: 2)`); the last expression auto-displays unless it is `nil`, an assignment, or a definition (like IRB).{{/if}}
+{{#if jl}}Julia: synchronous; helper options are standard keyword args (e.g. `output("id", limit=2)`); the last expression auto-displays unless it is an assignment or a definition (like the Julia REPL).{{/if}}
+On error, fix and re-run only the failing step — prior calls' state survives.
 </instruction>
 
 <prelude>
@@ -29,12 +31,6 @@ read(path, offset?=1, limit?=None) → str
     File as text; offset/limit 1-indexed lines. Accepts `local://…`.
 write(path, content) → str
     Write file (creates parents) → resolved path. `local://…` persists across turns/subagents.
-append(path, content) → str
-    Append → resolved path. Accepts `local://…`.
-tree(path?=".", max_depth?=3, show_hidden?=False) → str
-    Directory tree.
-diff(a, b) → str
-    Unified diff of two files.
 env(key?=None, value?=None) → str | None | dict
     No args → full env dict; one → value of `key`; two → set `key=value`, return value.
 output(*ids, format?="raw", query?=None, offset?=None, limit?=None) → str | dict | list[dict]
@@ -43,9 +39,9 @@ tool.<name>(args) → unknown
     Invoke any session tool; `args` = its parameter object.
 completion(prompt, model?="default", system?=None, schema?=None) → str | dict
     Oneshot, stateless (no history/tools). `model`: "smol" fast | "default" session | "slow" most capable. `schema` (JSON-Schema) → structured output, parsed object.
-{{#if spawns}}agent(prompt, agent_type?="task", model?=None, label?=None, schema?=None, return_handle?=False) → str | dict
-    Run a subagent → final output. `agent_type`/`agentType` picks another discovered agent; `schema` as in completion(). Background via `local://` files named in the prompt. `return_handle`/`returnHandle` → DAG node dict { text, output, handle: "agent://<id>", id, agent } (parsed under `data` when `schema` set).
-{{#if js}}    JS: options are ONE trailing object — agent(prompt, { agentType, schema, returnHandle }).
+{{#if spawns}}agent(prompt, agent?="task", model?=None, label?=None, schema?=None, handle?=False) → str | dict
+    Run a subagent → final output. `agent` picks another discovered agent; `schema` as in completion(). Background via `local://` files named in the prompt. `handle` → DAG node dict { text, output, handle: "agent://<id>", id, agent } (parsed under `data` when `schema` set).
+{{#if js}}    JS: options are ONE trailing object — agent(prompt, { agent, schema, handle }).
 {{/if}}
 {{/if}}
 parallel(thunks) → list
@@ -63,10 +59,14 @@ budget → per-turn token budget
 {{#if spawns}}
 <dag>
 Pipe handles through stage helpers to build a dependency graph — acyclic waves:
-- **Name nodes.** Capture each `agent(…, {{#if py}}return_handle=True{{/if}}{{#if js}}{ returnHandle: true }{{/if}}{{#if jl}}return_handle=true{{/if}})` result; carries `handle` (`agent://<id>`) + `output`.
+- **Name nodes.** Capture each `agent(…, {{#if py}}handle=True{{/if}}{{#if js}}{ handle: true }{{/if}}{{#if jl}}handle=true{{/if}})` result; carries `handle` (`agent://<id>`) + `output`.
 - **Wire edges by reference.** Put an upstream node's `handle`/`output` in the dependent stage's prompt — large transcript never re-inlined. Bulk: `write("local://<name>.md", …)`, pass the URI.
 - **`pipeline(items, *stages)` = staged waves**, barrier between stages (every item clears stage N before any enters N+1). **`parallel(thunks)` = one wave** of independent nodes.
 - **Isolate failure.** A raising node re-raises the lowest-index error, aborts its wave; wrap risky nodes in try/except so a failure degrades only its dependent subtree, independent branches finish.
 - **Acyclic only.** A node never waits on its own descendant.
 </dag>
 {{/if}}
+
+<critical>
+Prior top-level names (`data`, `sessions`, helpers, imports) survive into the next eval call — reuse them; NEVER re-import, re-require, or re-declare a helper. Re-read a file only if it may have changed since the last read. Re-run setup only after `reset`, a crash, or a `NameError`/`ReferenceError`.
+</critical>

package/src/prompts/tools/search.md

@@ -17,5 +17,6 @@ Searches files using regex.
 </output>
 
 <critical>
+- MUST use built-in `search` for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any CLI search via Bash — not even for one match or a quick check.
 - Open-ended search needing multiple rounds? MUST use the Task tool with the explore subagent, NOT chained `search` calls.
 </critical>

package/src/prompts/tools/todo.md

@@ -1,6 +1,6 @@
 **Tasks referenced by verbatim content string, NEVER an auto-generated ID — no "task-1"/"task-N" exists. Pass the content text in the `task` field.**
 
-Manages a phased task list. Pass `ops`: flat array of operations. Next pending task auto-promotes to `in_progress` on each completion. `pending` is a status, not an `op` — leave not-yet-started tasks implicit in `init`/`append`.
+Next pending task auto-promotes to `in_progress` on each completion.
 
 ## Operations
 

package/src/secrets/obfuscator.ts

@@ -259,9 +259,9 @@ export function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages:
 }
 
 /**
- * Restore placeholders in assistant content: visible text, thinking text, and
- * tool-call arguments/intent/rawBlock. Signatures and redacted-thinking bytes
- * are opaque provider-replay data and pass through byte-identical.
+ * Restore placeholders in assistant content: visible text and tool-call
+ * arguments/intent/rawBlock. Thinking and signatures are opaque
+ * provider-replay/hidden-reasoning data and pass through byte-identical.
  */
 export function deobfuscateAssistantContent(
 	obfuscator: SecretObfuscator,
@@ -276,12 +276,6 @@ export function deobfuscateAssistantContent(
 			changed = true;
 			return { ...block, text };
 		}
-		if (block.type === "thinking") {
-			const thinking = obfuscator.deobfuscate(block.thinking);
-			if (thinking === block.thinking) return block;
-			changed = true;
-			return { ...block, thinking };
-		}
 		if (block.type === "toolCall") {
 			const args = deobfuscateToolArguments(obfuscator, block.arguments);
 			const intent = block.intent === undefined ? undefined : obfuscator.deobfuscate(block.intent);