@oh-my-pi/pi-coding-agent 16.3.5 → 16.3.7

package/src/modes/interactive-mode.ts

@@ -6,6 +6,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
 	type Agent,
+	AgentBusyError,
 	type AgentMessage,
 	type AgentToolResult,
 	EventLoopKeepalive,
@@ -205,29 +206,37 @@ interface WorkingMessageAccentCacheKey {
 	sessionAccentEnabled: boolean;
 }
 
+/**
+ * Intern the shimmer palettes for each `WorkingMessageAccent` so `compile()`
+ * inside `shimmerSegments` sees a stable palette object between animation
+ * ticks. Allocating fresh palette literals every frame guaranteed a cache miss
+ * on the Symbol-keyed compiled-ANSI slot and forced `resolveTierAnsi` to walk
+ * every tier open/close for the ~30fps loader redraw (issue #4377).
+ */
+const workingMessagePaletteCache = new WeakMap<WorkingMessageAccent, { main: ShimmerPalette; hint: ShimmerPalette }>();
+
+function workingMessagePalettes(accent: WorkingMessageAccent): { main: ShimmerPalette; hint: ShimmerPalette } {
+	let entry = workingMessagePaletteCache.get(accent);
+	if (!entry) {
+		entry = {
+			main: { low: "dim", mid: { ansi: accent.main }, high: { ansi: accent.main }, bold: true },
+			hint: { low: "dim", mid: { ansi: accent.dim }, high: { ansi: accent.dim } },
+		};
+		workingMessagePaletteCache.set(accent, entry);
+	}
+	return entry;
+}
+
 function renderWorkingMessage(message: string, accent?: WorkingMessageAccent): string {
-	const palette = accent
-		? ({
-				low: "dim",
-				mid: { ansi: accent.main },
-				high: { ansi: accent.main },
-				bold: true,
-			} satisfies ShimmerPalette)
-		: undefined;
+	const palettes = accent ? workingMessagePalettes(accent) : undefined;
+	const palette = palettes?.main;
 	const hint = interruptHint();
 	if (!message.endsWith(hint)) return shimmerText(message, theme, palette);
 	const header = message.slice(0, -hint.length);
-	const hintPalette = accent
-		? ({
-				low: "dim",
-				mid: { ansi: accent.dim },
-				high: { ansi: accent.dim },
-			} satisfies ShimmerPalette)
-		: HINT_SHIMMER_PALETTE;
 	return shimmerSegments(
 		[
 			{ text: header, palette },
-			{ text: hint, palette: hintPalette },
+			{ text: hint, palette: palettes?.hint ?? HINT_SHIMMER_PALETTE },
 		],
 		theme,
 	);
@@ -635,7 +644,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		// unless the user opts in, and never emits raw escapes on other terminals.
 		setTerminalTextSizing(settings.get("tui.textSizing") && TERMINAL.textSizing);
 		this.chatContainer = new TranscriptContainer();
-		this.pendingMessagesContainer = new Container();
+		this.pendingMessagesContainer = new AnchoredLiveContainer();
 		this.statusContainer = new AnchoredLiveContainer();
 		this.todoContainer = new AnchoredLiveContainer();
 		this.subagentContainer = new AnchoredLiveContainer();
@@ -930,6 +939,17 @@ export class InteractiveMode implements InteractiveModeContext {
 		pushTerminalTitle();
 		setSessionTerminalTitle(this.sessionManager.getSessionName(), this.sessionManager.getCwd());
 		this.updateEditorBorderColor();
+		// Single side-effect point for title changes: every setSessionName caller
+		// (first-input titling, /rename, extension renames, plan seeding, replan
+		// refresh) gets the terminal title + accent updates from here. Registered
+		// before initHooksAndCustomTools/#reconcileModeFromSession/#enterPlanMode —
+		// all of which can reach setSessionName during init.
+		this.#eventBusUnsubscribers.push(
+			this.sessionManager.onSessionNameChanged(() => {
+				setSessionTerminalTitle(this.sessionManager.getSessionName(), this.sessionManager.getCwd());
+				this.#handleSessionAccentInputsChanged();
+			}),
+		);
 		this.#syncEditorMaxHeight();
 		this.isInitialized = true;
 		this.ui.requestRender(true);
@@ -986,9 +1006,6 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.session.subscribe(event => {
 				void this.#handleGoalSessionEvent(event);
 			}),
-			this.sessionManager.onSessionNameChanged(() => {
-				this.#handleSessionAccentInputsChanged();
-			}),
 			onStatusLineSessionAccentChanged(() => {
 				this.#syncStatusLineSettings();
 				this.#handleSessionAccentInputsChanged();
@@ -2606,8 +2623,16 @@ export class InteractiveMode implements InteractiveModeContext {
 				// the try/finally is idempotent and kept for the !compactBeforeExecute
 				// branch.
 				this.session.setPlanReferencePath(options.planFilePath);
-				compactOutcome = await this.handleCompactCommand(compactionPrompt, undefined, outcome =>
-					this.#applyDeferredPlanModelTransition(outcome, options.executionModel),
+				// Ride the plan-mode distillation prompt through as `internalGuidance`
+				// so it reaches native summarization without leaking into the public
+				// `customInstructions` channel on `session_before_compact` — extensions
+				// there treat that field as user focus and would query-bias the
+				// summary toward the plan boilerplate (issue #4359).
+				compactOutcome = await this.handleCompactCommand(
+					undefined,
+					undefined,
+					outcome => this.#applyDeferredPlanModelTransition(outcome, options.executionModel),
+					compactionPrompt,
 				);
 			}
 		} finally {
@@ -2658,11 +2683,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		// when the user has already chosen a name (preserveContext paths).
 		const seededName = humanizePlanTitle(options.title);
 		if (seededName && !this.sessionManager.getSessionName()) {
-			const applied = await this.sessionManager.setSessionName(seededName, "auto");
-			if (applied) {
-				setSessionTerminalTitle(this.sessionManager.getSessionName(), this.sessionManager.getCwd());
-				this.updateEditorBorderColor();
-			}
+			await this.sessionManager.setSessionName(seededName, "auto");
 		}
 
 		// markPlanReferenceSent fires only on the dispatch path so the synthetic
@@ -2672,16 +2693,24 @@ export class InteractiveMode implements InteractiveModeContext {
 			planFilePath: options.planFilePath,
 			contextPreserved: options.preserveContext === true,
 		});
-		// The executor's first turn must start on an idle session. The agent may still
-		// be streaming the post-`resolve` continuation (Agent.#emit is fire-and-forget)
-		// or a turn kicked off by the compaction/clear above; prompt() would then throw
-		// AgentBusyError ("Failed to finalize approved plan"). Abort the now-irrelevant
-		// in-flight turn first — abort() bumps the prompt generation and cancels pending
-		// continuations, so nothing re-streams in the synchronous gap before prompt().
+		// A user turn queued during compaction was already fired by
+		// `flushCompactionQueue` before we returned from `handleCompactCommand`; the
+		// old abort-then-prompt path would have discarded that operator turn AND
+		// still surfaced `AgentBusyError` when the queued turn kicked off in the
+		// synchronous gap. Preserve the in-flight work and queue the hidden
+		// execution directive behind it as a synthetic follow-up. If `isStreaming`
+		// flips true between the check and dispatch (the same fire-and-forget race
+		// noted below), catch `AgentBusyError` and fall back to the same queue.
 		if (this.session.isStreaming) {
-			await this.#abortPlanApprovalTurnSilently();
+			await this.session.followUp(planModePrompt, undefined, { synthetic: true });
+			return;
+		}
+		try {
+			await this.session.prompt(planModePrompt, { synthetic: true });
+		} catch (error) {
+			if (!(error instanceof AgentBusyError)) throw error;
+			await this.session.followUp(planModePrompt, undefined, { synthetic: true });
 		}
-		await this.session.prompt(planModePrompt, { synthetic: true });
 	}
 	async #abortPlanApprovalTurnSilently(): Promise<void> {
 		this.session.markPlanInternalAbortPending();
@@ -3900,8 +3929,9 @@ export class InteractiveMode implements InteractiveModeContext {
 		customInstructions?: string,
 		mode?: CompactMode,
 		beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>,
+		internalGuidance?: string,
 	): Promise<CompactionOutcome> {
-		return this.#commandController.handleCompactCommand(customInstructions, mode, beforeFlush);
+		return this.#commandController.handleCompactCommand(customInstructions, mode, beforeFlush, internalGuidance);
 	}
 
 	handleHandoffCommand(customInstructions?: string): Promise<void> {

package/src/modes/prompt-action-autocomplete.ts

@@ -2,6 +2,7 @@ import {
 	type AutocompleteItem,
 	type AutocompleteProvider,
 	CombinedAutocompleteProvider,
+	findLeadingSlashCommandStart,
 	getKeybindings,
 	type SlashCommand,
 } from "@oh-my-pi/pi-tui";
@@ -94,11 +95,13 @@ function getPromptActionPrefix(textBeforeCursor: string): string | null {
 }
 
 export class PromptActionAutocompleteProvider implements AutocompleteProvider {
+	#commands: SlashCommand[];
 	#baseProvider: CombinedAutocompleteProvider;
 	#actions: PromptActionDefinition[];
 	#basePath: string;
 
 	constructor(commands: SlashCommand[], basePath: string, actions: PromptActionDefinition[]) {
+		this.#commands = commands;
 		this.#baseProvider = new CombinedAutocompleteProvider(commands, basePath);
 		this.#basePath = basePath;
 		this.#actions = actions;
@@ -111,6 +114,21 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 	): Promise<{ items: AutocompleteItem[]; prefix: string } | null> {
 		const currentLine = lines[cursorLine] || "";
 		const textBeforeCursor = currentLine.slice(0, cursorCol);
+		const leadingSlashStart = findLeadingSlashCommandStart(textBeforeCursor);
+		const hasPromptTextBeforeCursorLine = lines.slice(0, cursorLine).some(line => (line || "").trim() !== "");
+		const commandText =
+			leadingSlashStart !== null && !hasPromptTextBeforeCursorLine
+				? textBeforeCursor.slice(leadingSlashStart)
+				: null;
+		const spaceIndex = commandText?.indexOf(" ") ?? -1;
+		if (commandText !== null && spaceIndex !== -1) {
+			const commandName = commandText.slice(1, spaceIndex);
+			const command = this.#commands.find(cmd => cmd.name === commandName || cmd.aliases?.includes(commandName));
+			if (command && (!("allowArgs" in command) || command.allowArgs !== false)) {
+				return this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol);
+			}
+		}
+
 		const promptActionPrefix = getPromptActionPrefix(textBeforeCursor);
 		if (promptActionPrefix) {
 			const query = promptActionPrefix.slice(1).toLowerCase();

package/src/modes/theme/shimmer.ts

@@ -207,6 +207,14 @@ export function shimmerSegments(segments: readonly ShimmerSegment[], theme: Shim
 	const time = Date.now();
 	const intensityFn = mode === "kitt" ? kittIntensity : classicIntensity;
 
+	// Fast-path window: outside `[bandLo, bandHi]` the intensity is guaranteed
+	// zero (tier "low"), so we can skip `intensityFn` + `tierFor` entirely for
+	// the prefix/suffix of every segment. On the typical ~60-char working
+	// message the classic band spans ~12 cells, so ~80% of the per-char loop
+	// disappears — the intensity call and the tier compare were the residual
+	// per-frame cost after #4353 removed the allocation hotspot (issue #4377).
+	const { lo: bandLo, hi: bandHi } = activeBand(mode, time, total);
+
 	let out = "";
 	let index = 0;
 	for (const { text, palette } of perSeg) {
@@ -224,7 +232,7 @@ export function shimmerSegments(segments: readonly ShimmerSegment[], theme: Shim
 				const c2 = text.charCodeAt(i + 1);
 				if (c2 >= 0xdc00 && c2 <= 0xdfff) step = 2;
 			}
-			const tier = tierFor(intensityFn(time, index, total));
+			const tier: Tier = index < bandLo || index > bandHi ? "low" : tierFor(intensityFn(time, index, total));
 			if (tier !== runTier) {
 				if (runTier !== null && runEnd > runStart) {
 					const seq = compiled[runTier];
@@ -245,6 +253,34 @@ export function shimmerSegments(segments: readonly ShimmerSegment[], theme: Shim
 	return out;
 }
 
+/**
+ * Sweep window (code-point indices) outside which the intensity is guaranteed
+ * zero for `mode` at `time` over `total` cells. Widening the window is safe —
+ * the per-char intensity call still runs inside the window and reports 0 for
+ * off-band code points — but narrower windows skip more of the per-char loop.
+ */
+function activeBand(mode: "classic" | "kitt", time: number, total: number): { lo: number; hi: number } {
+	if (mode === "classic") {
+		const period = total + CLASSIC_PADDING * 2;
+		const pos = ((time / 1000) * SHIMMER_SPEED_CELLS_PER_S) % period;
+		return {
+			lo: pos - CLASSIC_PADDING - CLASSIC_BAND_HALF_WIDTH,
+			hi: pos - CLASSIC_PADDING + CLASSIC_BAND_HALF_WIDTH,
+		};
+	}
+	const range = total - 1;
+	if (range <= 0) return { lo: 0, hi: total };
+	const cycleCells = 2 * range;
+	const sweep = ((time / 1000) * SHIMMER_SPEED_CELLS_PER_S) % cycleCells;
+	const goingRight = sweep < range;
+	const head = goingRight ? sweep : cycleCells - sweep;
+	// The trail always lies behind the head for the current direction — chars
+	// ahead of the head are dark. See {@link kittIntensity} for the exact rule.
+	return goingRight
+		? { lo: head - KITT_HEAD_HALF - KITT_TRAIL_LEN, hi: head + KITT_HEAD_HALF }
+		: { lo: head - KITT_HEAD_HALF, hi: head + KITT_HEAD_HALF + KITT_TRAIL_LEN };
+}
+
 function countCodePoints(text: string): number {
 	let n = 0;
 	let i = 0;

package/src/modes/utils/transcript-render-helpers.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test";
+import type { AssistantMessage, Usage } from "@oh-my-pi/pi-ai";
+import { assistantUsageIsBilled } from "./transcript-render-helpers";
+
+function usage(overrides: Partial<Usage> = {}): Usage {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		...overrides,
+	};
+}
+
+describe("assistantUsageIsBilled", () => {
+	it("suppresses the token badge only for turns that consumed nothing", () => {
+		expect(assistantUsageIsBilled(usage())).toBe(false);
+	});
+
+	it("preserves cost transparency for empty replies whose prompt still cost input tokens", () => {
+		expect(assistantUsageIsBilled(usage({ input: 321 }))).toBe(true);
+		expect(assistantUsageIsBilled(usage({ output: 0, cacheRead: 512 }))).toBe(true);
+		expect(assistantUsageIsBilled(usage({ cacheWrite: 128 }))).toBe(true);
+		expect(assistantUsageIsBilled(usage({ premiumRequests: 1 }))).toBe(true);
+	});
+
+	// Documents the live/resume parity contract for #4532: both paths ask
+	// `assistantUsageIsBilled` about `message.usage`, so an empty automated
+	// reply that still cost input tokens renders identically on both surfaces.
+	it("matches whether the assistant carrier renders visible content", () => {
+		const emptyBilledMessage: Pick<AssistantMessage, "usage"> = { usage: usage({ input: 321 }) };
+		const emptyFreeMessage: Pick<AssistantMessage, "usage"> = { usage: usage() };
+		expect(assistantUsageIsBilled(emptyBilledMessage.usage)).toBe(true);
+		expect(assistantUsageIsBilled(emptyFreeMessage.usage)).toBe(false);
+	});
+});

package/src/modes/utils/transcript-render-helpers.ts

@@ -7,8 +7,14 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { formatBytes, formatDuration } from "@oh-my-pi/pi-utils";
-import { type CustomMessage, type FileMentionMessage, isSilentAbort, resolveAbortLabel } from "../../session/messages";
+import {
+	type CustomMessage,
+	type FileMentionMessage,
+	resolveAbortLabel,
+	shouldRenderAbortReason,
+} from "../../session/messages";
 import { createIrcMessageCard } from "../../tools/irc";
+import { replaceTabs, TRUNCATE_LENGTHS, truncateToWidth } from "../../tools/render-utils";
 import { canonicalizeMessage } from "../../utils/thinking-display";
 import { TranscriptBlock } from "../components/transcript-container";
 import { theme } from "../theme/theme";
@@ -138,20 +144,55 @@ export function normalizeToolArgs(args: unknown): Record<string, unknown> {
 	return args && typeof args === "object" && !Array.isArray(args) ? (args as Record<string, unknown>) : {};
 }
 
+export type AssistantErrorPresentation =
+	| { kind: "none" }
+	| { kind: "full"; text: string; isError: true }
+	| { kind: "compact-recovered"; text: string; isError: false };
+
+function sanitizeRecoveredRetryNote(note: string): string {
+	const normalized = replaceTabs(note).replace(/\s+/g, " ").trim();
+	return truncateToWidth(normalized || "retried", TRUNCATE_LENGTHS.CONTENT);
+}
+
 /**
- * Resolve the inline error label, if any, for a turn-ending assistant message.
- * Silent aborts yield no label. `retryAttempt` tunes the abort label wording.
+ * Resolve the turn-ending assistant error presentation, if any.
+ * Silent and user-interrupt aborts yield no label. Recovered auto-retry errors
+ * collapse to a single non-error note; terminal errors keep the full red presentation.
  */
-export function resolveAssistantErrorMessage(
+export function resolveAssistantErrorPresentation(
 	message: AssistantAgentMessage,
 	retryAttempt = 0,
-): { hasErrorStop: boolean; errorMessage: string | null } {
-	const isAbortedSilently = message.stopReason === "aborted" && isSilentAbort(message);
-	const hasErrorStop = !isAbortedSilently && (message.stopReason === "aborted" || message.stopReason === "error");
-	const errorMessage = hasErrorStop
-		? message.stopReason === "aborted"
-			? resolveAbortLabel(message, retryAttempt)
-			: message.errorMessage || "Error"
-		: null;
-	return { hasErrorStop, errorMessage };
+): AssistantErrorPresentation {
+	if (message.retryRecovery?.status === "recovered") {
+		return {
+			kind: "compact-recovered",
+			text: sanitizeRecoveredRetryNote(message.retryRecovery.note),
+			isError: false,
+		};
+	}
+	if (message.stopReason === "aborted") {
+		if (!shouldRenderAbortReason(message)) return { kind: "none" };
+		return { kind: "full", text: resolveAbortLabel(message, retryAttempt), isError: true };
+	}
+	if (message.stopReason === "error") {
+		return { kind: "full", text: message.errorMessage || "Error", isError: true };
+	}
+	if (message.errorMessage && shouldRenderAbortReason(message)) {
+		return { kind: "full", text: message.errorMessage, isError: true };
+	}
+	return { kind: "none" };
+}
+
+/**
+ * Whether an assistant turn's `usage` reflects work the operator was billed
+ * for. Empty automated turns from providers that emit `usage: 0` collapse to
+ * `false`, but any input, output, cache, or premium request keeps the row so
+ * cost transparency survives — the live path and the resume/rebuild path
+ * agree turn-by-turn.
+ */
+export function assistantUsageIsBilled(usage: AssistantAgentMessage["usage"]): boolean {
+	if (usage.input > 0 || usage.output > 0) return true;
+	if (usage.cacheRead > 0 || usage.cacheWrite > 0) return true;
+	if ((usage.premiumRequests ?? 0) > 0) return true;
+	return false;
 }

package/src/modes/utils/ui-helpers.ts

@@ -50,11 +50,12 @@ import { buildSkillCommandPrompt, invokeSkillCommandFromText, isKnownSkillComman
 import { createAssistantMessageComponent } from "./interactive-context-helpers";
 import {
 	assistantHasVisibleContent,
+	assistantUsageIsBilled,
 	buildAsyncResultBlock,
 	buildFileMentionBlock,
 	buildIrcMessageCard,
 	normalizeToolArgs,
-	resolveAssistantErrorMessage,
+	resolveAssistantErrorPresentation,
 } from "./transcript-render-helpers";
 
 type TextBlock = { type: "text"; text: string };
@@ -317,7 +318,11 @@ export class UiHelpers {
 			const previous = waitingPoll;
 			if (!previous) return;
 			waitingPoll = null;
-			if (nextToolName === "job" && previous.isDisplaceableBlock()) {
+			if (
+				nextToolName === "job" &&
+				previous.isDisplaceableBlock() &&
+				this.ctx.chatContainer.isBlockUncommitted(previous)
+			) {
 				this.ctx.chatContainer.removeChild(previous);
 			}
 			// Sealing freezes the block and stops the waiting-poll spinner that
@@ -334,7 +339,9 @@ export class UiHelpers {
 			}
 			if (previous.canBeDisplacedBy(nextToolName)) {
 				todoSnapshot = null;
-				this.ctx.chatContainer.removeChild(previous);
+				if (this.ctx.chatContainer.isBlockUncommitted(previous)) {
+					this.ctx.chatContainer.removeChild(previous);
+				}
 				previous.seal();
 				return;
 			}
@@ -372,10 +379,9 @@ export class UiHelpers {
 					readGroup?.seal();
 					readGroup = null;
 				}
-				const { hasErrorStop, errorMessage } = resolveAssistantErrorMessage(
-					message,
-					this.ctx.viewSession.retryAttempt,
-				);
+				const errorPresentation = resolveAssistantErrorPresentation(message, this.ctx.viewSession.retryAttempt);
+				const hasErrorStop = errorPresentation.kind === "full";
+				const errorMessage = hasErrorStop ? errorPresentation.text : null;
 
 				// Render tool call components
 				for (const content of message.content) {
@@ -458,7 +464,10 @@ export class UiHelpers {
 						this.ctx.pendingTools.set(content.id, component);
 					}
 				}
-				pendingUsage = this.ctx.settings.get("display.showTokenUsage") ? message.usage : undefined;
+				pendingUsage =
+					this.ctx.settings.get("display.showTokenUsage") && assistantUsageIsBilled(message.usage)
+						? message.usage
+						: undefined;
 				pendingUsageDuration = message.duration;
 				pendingUsageTtft = message.ttft;
 			} else if (message.role === "toolResult") {

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

@@ -13,7 +13,7 @@ Worth it when the task benefits from decomposition + parallel coverage, or from
 <helpers>
 State persists across eval calls, so scout in one call and fan out in the next. Every eval call has:
 
-- `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", …); `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.
+- `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", …); `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. Recursion follows `task.maxRecursionDepth` (default 2; `-1` uses eval's hard cap 3): main agent depth = 0, each `agent()` child increments depth by 1, and a spawner may call `agent()` only while its current `taskDepth < effective cap`. 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.

package/src/prompts/tools/bash.md

@@ -1,10 +1,10 @@
-Runs bash in a shell session — terminal ops: git, bun, cargo, python.
+Runs commands in the embedded shell — 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.
+The shell invokes **real binaries** with simple args. It is NOT full GNU Bash.
 
-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`).
+Use bash ONLY for: a single binary call, or one short pipeline that COMPUTES a fact and does not depend on shell-specific regex/quoting (`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
@@ -13,6 +13,7 @@ Anything below → `eval` cell, not bash:
 - 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
+- GNU grep BRE extensions are not guaranteed in the embedded shell: use `grep -E 'json|tool'` for alternation instead of `grep 'json\|tool'`; use the built-in `grep` tool with `pattern: "json|tool"` (Rust regex, so `\bword\b` works there), or `eval` for exact text processing.
 
 <instruction>
 - `cwd` sets the working dir, not `cd dir && …`
@@ -22,13 +23,14 @@ Anything below → `eval` cell, not bash:
 - `;` only when later commands should run despite earlier failures
 - Multiple bash calls per message run concurrently. NEVER split order-dependent commands across parallel calls — chain with `&&` in one call.
 - Internal URIs (`skill://`, `agent://`, …) auto-resolve to FS paths
+- Need exact pipeline semantics (`cmd | head`, multi-stage filtering) or output truncation? Prefer `eval` and process the stream directly.
 {{#if asyncEnabled}}
 - `async: true` for long-running commands when you don't need immediate output: returns a background job ID; result delivered as a follow-up.
 {{/if}}
 </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.
+- The embedded shell invokes real binaries with simple args; it is NOT full GNU Bash. Loops, conditionals, heredocs, inline interpreter scripts (`-e`/`-c`/`--eval`) when an eval runtime exists, several piped stages, exact pipeline semantics, or quote/JSON escaping mean you're writing a program → use `eval` cells: restartable, stateful, and free of shell-quoting traps.
 </critical>
 
 <output>
@@ -39,9 +41,9 @@ Anything below → `eval` cell, not bash:
 {{#if asyncEnabled}}
 # Timeout and async
 
-- `timeout` (seconds) caps wall-clock duration; the process is killed on elapse.
-- `async: true` defers only reporting — it does NOT extend the timeout; a daemon run with `async: true` is still killed when `timeout` elapses.
-- Long-running daemons (dev servers, watchers): pass a large explicit `timeout`. The shell session persists across calls, so `cmd &` keeps running between bash calls.
+- `timeout` is seconds, clamped to `1..3600`; the process is killed on elapse.
+- `async: true` defers only reporting — it does NOT extend the timeout; a daemon with `async: true` is still killed at the clamped timeout.
+- Need >3600s? Detach/manage lifecycle yourself (`cmd &`, supervisor, self-restarting script). The shell session persists across calls.
 {{/if}}
 {{#if autoBackgroundEnabled}}
 

package/src/prompts/tools/grep.md

@@ -1,7 +1,7 @@
 Greps files using regex.
 
 <instruction>
-- Rust regex (RE2-style) — no lookaround/backreferences; use line anchors or post-filters instead of (?!…)/(?<!…).
+- Rust regex (RE2-style): alternation is `foo|bar`, not GNU BRE-style `foo\|bar`; Rust word boundaries like `\bword\b` are supported. Use line anchors or post-filters instead of lookaround/backreferences.
 - `path`: SHOULD scope to a known path (e.g. `src`); pass several as a delimited list (`src; tests`).
 - Cross-line patterns detected from literal `\n` or `\\n` in `pattern`.
 </instruction>

package/src/prompts/tools/memory-edit.md

@@ -6,3 +6,5 @@ Use only with ids returned by the `recall` tool. Operations:
 - `invalidate`: softly supersede a working or episodic memory, optionally pointing at `replacement_id`.
 
 Prefer `invalidate` when a memory became stale but its history may still be useful. Use `forget` only for content that should be hard-deleted.
+
+**Always read the full memory before `update`.** Recall results are clipped previews (the trailing `…` marks a truncation and `full_length` reports the original size); `update` replaces content wholesale, so overwriting the preview would delete the unseen tail. Fetch the row first with `read memory://<id>`, then pass the merged content in `content`.

package/src/prompts/tools/recall.md

@@ -3,3 +3,5 @@ Search long-term memory for relevant information. Returns raw matching entries r
 Use proactively — before answering questions about past conversations, user preferences, project decisions, or any topic where prior context would help accuracy. When in doubt, recall first.
 
 Prefer `recall` when you need specific facts or entries. Use `reflect` instead when you need a synthesized answer across many memories.
+
+Content in each result is a preview. A trailing `…` marks a truncation (`truncated: true`, `full_length` gives the original size). Fetch the full row with `read memory://<id>` — required before any `memory_edit update`.