@oh-my-pi/pi-coding-agent 15.10.1 → 15.10.2

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

@@ -26,6 +26,16 @@ type AgentSessionEventKind = AgentSessionEvent["type"];
 
 const IRC_MESSAGE_VISIBLE_TTL_MS = 10_000;
 
+/**
+ * Loader label shown the instant a user interrupt (Esc) is requested, kept until
+ * the agent turn fully unwinds. Esc fires the abort synchronously, but the loop
+ * only stops the spinner at `agent_end`, which it cannot reach until every
+ * in-flight tool settles its abort in `executeToolCalls` (`Promise.allSettled`).
+ * Swapping the steady "Working…" for this acknowledges the keypress instead of
+ * reading as an ignored Esc for the seconds a slow tool takes to tear down.
+ */
+export const INTERRUPTING_WORKING_MESSAGE = "Interrupting…";
+
 // Events that change foreground streaming state, or that reset a turn. The TUI
 // eager native-scrollback rebuild mode is recomputed only on these so unrelated
 // IRC/notices/status refreshes do not toggle scrollback replay policy.
@@ -57,6 +67,7 @@ export class EventController {
 	#backgroundToolCallIds = new Set<string>();
 	#assistantMessageStreaming = false;
 	#agentTurnActive = false;
+	#interrupting = false;
 	#readToolCallArgs = new Map<string, Record<string, unknown>>();
 	#readToolCallAssistantComponents = new Map<string, AssistantMessageComponent>();
 	#lastAssistantComponent: AssistantMessageComponent | undefined = undefined;
@@ -167,6 +178,7 @@ export class EventController {
 		return true;
 	}
 	#updateWorkingMessageFromIntent(intent: unknown): void {
+		if (this.#interrupting) return;
 		// Streamed JSON can deliver non-string `_i` (object, number, boolean) before
 		// schema validation; `?.` only guards null/undefined, so guard the type too.
 		if (typeof intent !== "string") return;
@@ -176,6 +188,19 @@ export class EventController {
 		this.ctx.setWorkingMessage(`${trimmed}${interruptHint()}`);
 	}
 
+	/**
+	 * Acknowledge a user interrupt (Esc) immediately: switch the loader to
+	 * `INTERRUPTING_WORKING_MESSAGE` and freeze intent-driven working-message
+	 * updates for the rest of the turn so a late `tool_execution_start` intent
+	 * cannot repaint a "Working…/<intent>" line over the acknowledgment. Reset at
+	 * the next `agent_start`. No-op outside an active turn or if already set.
+	 */
+	notifyInterrupting(): void {
+		if (!this.#agentTurnActive || this.#interrupting) return;
+		this.#interrupting = true;
+		this.ctx.setWorkingMessage(INTERRUPTING_WORKING_MESSAGE);
+	}
+
 	subscribeToAgent(): void {
 		this.ctx.unsubscribe = this.ctx.session.subscribe(async (event: AgentSessionEvent) => {
 			await this.handleEvent(event);
@@ -220,6 +245,7 @@ export class EventController {
 
 	async #handleAgentStart(_event: Extract<AgentSessionEvent, { type: "agent_start" }>): Promise<void> {
 		this.#agentTurnActive = true;
+		this.#interrupting = false;
 		this.#lastIntent = undefined;
 		this.#readToolCallArgs.clear();
 		this.#readToolCallAssistantComponents.clear();

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

@@ -94,6 +94,7 @@ export class InputController {
 			if (this.ctx.loopModeEnabled) {
 				this.ctx.pauseLoop();
 				if (this.ctx.session.isStreaming) {
+					this.ctx.notifyInterrupting();
 					void this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 				} else {
 					this.ctx.cancelPendingSubmission();
@@ -124,6 +125,7 @@ export class InputController {
 				this.ctx.isPythonMode = false;
 				this.ctx.updateEditorBorderColor();
 			} else if (this.ctx.session.isStreaming) {
+				this.ctx.notifyInterrupting();
 				void this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 			} else if (!this.ctx.editor.getText().trim()) {
 				// Double-interrupt with empty editor triggers /tree, /branch, or nothing based on setting
@@ -499,17 +501,44 @@ export class InputController {
 	}
 
 	handleCtrlZ(): void {
-		// Set up handler to restore TUI when resumed
-		process.once("SIGCONT", () => {
+		// SIGTSTP is POSIX job-control: Windows has no equivalent and
+		// `process.kill(_, "SIGTSTP")` throws `TypeError: Unknown signal:
+		// SIGTSTP` there, taking the whole agent down via an uncaught
+		// exception (issue #2036). No-op on platforms that cannot suspend.
+		if (process.platform === "win32") {
+			this.ctx.showStatus("Suspend (Ctrl+Z) is not supported on this platform");
+			return;
+		}
+
+		// Capture the listener so we can detach it if the signal never
+		// fires; otherwise a failed suspend would leave a stale SIGCONT
+		// handler that fires on the next unrelated continue and tries to
+		// re-`start()` an already-running TUI.
+		const onResume = (): void => {
 			this.ctx.ui.start();
 			this.ctx.ui.requestRender(true);
-		});
+		};
+		process.once("SIGCONT", onResume);
 
-		// Stop the TUI (restore terminal to normal mode)
+		// Stop the TUI (restore terminal to normal mode) before sending the
+		// signal so the parent shell sees a sane terminal state.
 		this.ctx.ui.stop();
 
-		// Send SIGTSTP to process group (pid=0 means all processes in group)
-		process.kill(0, "SIGTSTP");
+		try {
+			// pid=0 → entire foreground process group; the shell receives
+			// SIGTSTP and parks the job.
+			process.kill(0, "SIGTSTP");
+		} catch (err) {
+			// Either the runtime refused the signal or the kernel rejected
+			// it (some sandboxes block sending to pid=0). Tear the resume
+			// hook down and bring the TUI back so the user is not stranded
+			// on a frozen prompt.
+			process.removeListener("SIGCONT", onResume);
+			this.ctx.ui.start();
+			this.ctx.ui.requestRender(true);
+			const reason = err instanceof Error ? err.message : String(err);
+			this.ctx.showError(`Failed to suspend: ${reason}`);
+		}
 	}
 
 	handleDequeue(): void {
@@ -589,7 +618,7 @@ export class InputController {
 
 	/** Send editor text as a follow-up message (queued behind current stream). */
 	async handleFollowUp(): Promise<void> {
-		const text = this.ctx.editor.getText().trim();
+		let text = this.ctx.editor.getText().trim();
 		if (!text) return;
 
 		// Compaction first: while compacting, free text gets queued via
@@ -603,6 +632,16 @@ export class InputController {
 			return;
 		}
 
+		const slashResult = await executeBuiltinSlashCommand(text, {
+			ctx: this.ctx,
+		});
+		if (slashResult === true) {
+			return;
+		}
+		if (typeof slashResult === "string") {
+			text = slashResult;
+		}
+
 		// Skill commands invoke through the custom-message path regardless of
 		// which keybinding submitted them. Enter routes them as `steer`;
 		// Ctrl+Enter (this handler) routes them as `followUp`.

package/src/modes/interactive-mode.ts

@@ -50,7 +50,7 @@ import chalk from "chalk";
 import { reset as resetCapabilities } from "../capability";
 import { KeybindingsManager } from "../config/keybindings";
 import { MODEL_ROLES, type ModelRole } from "../config/model-registry";
-import { isSettingsInitialized, Settings, settings } from "../config/settings";
+import { isSettingsInitialized, onStatusLineSessionAccentChanged, Settings, settings } from "../config/settings";
 import { clearClaudePluginRootsCache } from "../discovery/helpers";
 import type {
 	ContextUsage,
@@ -125,7 +125,7 @@ import {
 import { OAuthManualInputManager } from "./oauth-manual-input";
 import { SessionObserverRegistry } from "./session-observer-registry";
 import { interruptHint } from "./shared";
-import { type ShimmerPalette, shimmerSegments, shimmerText } from "./theme/shimmer";
+import { type ShimmerPalette, shimmerEnabled, shimmerSegments, shimmerText } from "./theme/shimmer";
 import type { Theme } from "./theme/theme";
 import {
 	getEditorTheme,
@@ -157,6 +157,12 @@ interface WorkingMessageAccent {
 	dim: string;
 }
 
+interface WorkingMessageAccentCacheKey {
+	sessionName: string | undefined;
+	accentSurfaceLuminance: number | undefined;
+	sessionAccentEnabled: boolean;
+}
+
 function renderWorkingMessage(message: string, accent?: WorkingMessageAccent): string {
 	const palette = accent
 		? ({
@@ -301,6 +307,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	autoCompactionLoader: Loader | undefined = undefined;
 	retryLoader: Loader | undefined = undefined;
 	#pendingWorkingMessage: string | undefined;
+	#workingMessageAccentCacheKey?: WorkingMessageAccentCacheKey;
+	#workingMessageAccentCacheValue?: WorkingMessageAccent;
+	#workingMessageAccentCacheHasValue = false;
 	get #defaultWorkingMessage(): string {
 		return `Working…${interruptHint()}`;
 	}
@@ -638,9 +647,17 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.session.subscribe(event => {
 				void this.#handleGoalSessionEvent(event);
 			}),
+			this.sessionManager.onSessionNameChanged(() => {
+				this.#handleSessionAccentInputsChanged();
+			}),
+			onStatusLineSessionAccentChanged(() => {
+				this.#syncStatusLineSettings();
+				this.#handleSessionAccentInputsChanged();
+			}),
 		);
 		// Set up theme file watcher
 		onThemeChange(() => {
+			this.#clearWorkingMessageAccentCache();
 			clearRenderCache();
 			this.ui.invalidate();
 			this.updateEditorBorderColor();
@@ -965,9 +982,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.#goalContinuationTurnInFlight = false;
 		}
 		if (this.loadingAnimation) {
-			this.loadingAnimation.stop();
-			this.loadingAnimation = undefined;
-			this.statusContainer.clear();
+			this.#stopLoadingAnimation(true);
 		}
 		if (!submission.customType) {
 			this.pendingImages = submission.images ? [...submission.images] : [];
@@ -1005,9 +1020,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			pendingSubmissionDispose?.();
 			this.#pendingWorkingMessage = undefined;
 			if (this.loadingAnimation) {
-				this.loadingAnimation.stop();
-				this.loadingAnimation = undefined;
-				this.statusContainer.clear();
+				this.#stopLoadingAnimation(true);
 			}
 		}
 	}
@@ -1023,6 +1036,24 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.editor.setMaxHeight(this.#computeEditorMaxHeight());
 	}
 
+	#syncStatusLineSettings(): void {
+		this.statusLine.updateSettings({
+			preset: settings.get("statusLine.preset"),
+			leftSegments: settings.get("statusLine.leftSegments"),
+			rightSegments: settings.get("statusLine.rightSegments"),
+			separator: settings.get("statusLine.separator"),
+			showHookStatus: settings.get("statusLine.showHookStatus"),
+			sessionAccent: settings.get("statusLine.sessionAccent"),
+			segmentOptions: settings.get("statusLine.segmentOptions"),
+		});
+	}
+
+	#handleSessionAccentInputsChanged(): void {
+		this.#clearWorkingMessageAccentCache();
+		this.statusLine.invalidate();
+		this.updateEditorBorderColor();
+	}
+
 	updateEditorBorderColor(): void {
 		if (this.isBashMode) {
 			this.editor.borderColor = theme.getBashModeBorderColor();
@@ -2416,8 +2447,7 @@ export class InteractiveMode implements InteractiveModeContext {
 
 	stop(): void {
 		if (this.loadingAnimation) {
-			this.loadingAnimation.stop();
-			this.loadingAnimation = undefined;
+			this.#stopLoadingAnimation(false);
 		}
 		this.#cleanupMicAnimation();
 		this.#cancelTodoAutoClearTimer();
@@ -2581,9 +2611,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#pendingSubmissionDispose = undefined;
 		this.#pendingWorkingMessage = undefined;
 		if (this.loadingAnimation) {
-			this.loadingAnimation.stop();
-			this.loadingAnimation = undefined;
-			this.statusContainer.clear();
+			this.#stopLoadingAnimation(true);
 		}
 		this.#uiHelpers.showError(message);
 	}
@@ -2646,24 +2674,69 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.ui.requestRender();
 	}
 
+	#clearWorkingMessageAccentCache(): void {
+		this.#workingMessageAccentCacheKey = undefined;
+		this.#workingMessageAccentCacheValue = undefined;
+		this.#workingMessageAccentCacheHasValue = false;
+	}
+
+	#buildWorkingMessageAccentCacheKey(): WorkingMessageAccentCacheKey {
+		const sessionAccentEnabled = !isSettingsInitialized() || settings.get("statusLine.sessionAccent") !== false;
+		return {
+			sessionAccentEnabled,
+			sessionName: sessionAccentEnabled ? this.sessionManager.getSessionName() : undefined,
+			accentSurfaceLuminance: theme.accentSurfaceLuminance,
+		};
+	}
+
+	#workingMessageAccentCacheKeyEquals(a: WorkingMessageAccentCacheKey, b: WorkingMessageAccentCacheKey): boolean {
+		return (
+			a.sessionName === b.sessionName &&
+			a.accentSurfaceLuminance === b.accentSurfaceLuminance &&
+			a.sessionAccentEnabled === b.sessionAccentEnabled
+		);
+	}
+
+	#cacheWorkingMessageAccent(
+		key: WorkingMessageAccentCacheKey,
+		value: WorkingMessageAccent | undefined,
+	): WorkingMessageAccent | undefined {
+		this.#workingMessageAccentCacheKey = key;
+		this.#workingMessageAccentCacheValue = value;
+		this.#workingMessageAccentCacheHasValue = true;
+		return value;
+	}
+
 	#getWorkingMessageAccent(): WorkingMessageAccent | undefined {
-		const accentEnabled = !isSettingsInitialized() || settings.get("statusLine.sessionAccent") !== false;
-		const sessionName = accentEnabled ? this.sessionManager.getSessionName() : undefined;
-		if (!sessionName) return undefined;
-		const hex = getSessionAccentHex(sessionName, theme.accentSurfaceLuminance);
+		const key = this.#buildWorkingMessageAccentCacheKey();
+		if (
+			this.#workingMessageAccentCacheHasValue &&
+			this.#workingMessageAccentCacheKey &&
+			this.#workingMessageAccentCacheKeyEquals(key, this.#workingMessageAccentCacheKey)
+		) {
+			return this.#workingMessageAccentCacheValue;
+		}
+		if (!key.sessionAccentEnabled || !key.sessionName) {
+			return this.#cacheWorkingMessageAccent(key, undefined);
+		}
+		const hex = getSessionAccentHex(key.sessionName, key.accentSurfaceLuminance);
 		const main = getSessionAccentAnsi(hex);
 		const dim = getSessionAccentAnsi(adjustHsv(hex, { s: 0.55, v: 0.65 }));
-		return main && dim ? { main, dim } : undefined;
+		return this.#cacheWorkingMessageAccent(key, main && dim ? { main, dim } : undefined);
 	}
 
 	ensureLoadingAnimation(): void {
 		if (!this.loadingAnimation) {
+			this.#clearWorkingMessageAccentCache();
 			this.statusContainer.clear();
 			const messageColorFn = ((message: string) =>
 				renderWorkingMessage(message, this.#getWorkingMessageAccent())) as LoaderMessageColorFn & {
-				animated: true;
+				animated?: true;
 			};
-			messageColorFn.animated = true;
+			// Shimmer drives the 30fps redraw; when it is disabled the working
+			// message is static, so leave `animated` unset and let the loader use
+			// the spinner-only ~12.5fps cadence instead of repainting a frozen line.
+			if (shimmerEnabled()) messageColorFn.animated = true;
 			this.loadingAnimation = new Loader(
 				this.ui,
 				spinner => {
@@ -2680,6 +2753,16 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.applyPendingWorkingMessage();
 	}
 
+	#stopLoadingAnimation(clearStatusContainer: boolean): void {
+		if (!this.loadingAnimation) return;
+		this.loadingAnimation.stop();
+		this.loadingAnimation = undefined;
+		this.#clearWorkingMessageAccentCache();
+		if (clearStatusContainer) {
+			this.statusContainer.clear();
+		}
+	}
+
 	setWorkingMessage(message?: string): void {
 		if (message === undefined) {
 			this.#pendingWorkingMessage = undefined;
@@ -2707,6 +2790,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.setWorkingMessage(message);
 	}
 
+	notifyInterrupting(): void {
+		this.#eventController.notifyInterrupting();
+	}
+
 	showNewVersionNotification(newVersion: string): void {
 		this.#uiHelpers.showNewVersionNotification(newVersion);
 	}

package/src/modes/magic-keywords.ts

@@ -4,7 +4,7 @@ import { highlightWorkflow } from "./workflow";
 
 /**
  * Gradient-highlight every magic keyword ("ultrathink", "orchestrate",
- * "workflow") that appears as standalone prose, skipping any occurrence inside a
+ * "workflowz") that appears as standalone prose, skipping any occurrence inside a
  * code block, inline code span, or XML/HTML section. Each highlighter paints its
  * own keyword with its own gradient, so chaining is order-independent — the
  * earlier passes only inject zero-width SGR escapes (no backticks or angle

package/src/modes/markdown-prose.ts

@@ -1,6 +1,6 @@
 /**
  * Markdown structure awareness for the magic-keyword affordances
- * ("ultrathink"/"orchestrate"/"workflow").
+ * ("ultrathink"/"orchestrate"/"workflowz").
  *
  * Keyword detection and editor/transcript highlighting must fire only on prose
  * the user is actually addressing to the model — never on a word that happens to

package/src/modes/theme/shimmer.ts

@@ -1,14 +1,20 @@
 import { isSettingsInitialized, settings } from "../../config/settings";
 import type { Theme, ThemeColor } from "./theme";
 
+// ─── Animation velocity ──────────────────────────────────────────────────────
+// Band/head travel speed in border cells per second. Driving position by a fixed
+// velocity — instead of dividing a fixed sweep duration by the (length-derived)
+// period — makes smoothness independent of message length: at the loader's
+// default 30fps redraw cadence the band advances ≤1 cell per frame for any
+// string, so it never visibly steps. Sweep/round-trip durations now scale with
+// length. Keep ≤ the animated redraw fps (loader RENDER_INTERVAL_MS = 1000/30).
+const SHIMMER_SPEED_CELLS_PER_S = 30;
+
 // ─── Classic sweep tunables ──────────────────────────────────────────────────
 const CLASSIC_PADDING = 10;
-const CLASSIC_SWEEP_MS = 1400;
 const CLASSIC_BAND_HALF_WIDTH = 6;
 
 // ─── KITT scanner tunables ───────────────────────────────────────────────────
-// 1.5s round trip ≈ classic 1982 K.I.T.T. scanner cadence (~0.75s per direction).
-const KITT_CYCLE_MS = 1500;
 const KITT_HEAD_HALF = 0.6;
 const KITT_TRAIL_LEN = 7;
 
@@ -103,9 +109,10 @@ function compile(theme: ShimmerTheme, palette: ShimmerPalette): CompiledPalette
 /** Smooth cosine bump sweeping left → right with edge padding. */
 function classicIntensity(time: number, index: number, length: number): number {
 	const period = length + CLASSIC_PADDING * 2;
-	// Fractional position — kept un-floored so the band glides at the host's
-	// frame rate instead of stepping discretely.
-	const pos = ((time % CLASSIC_SWEEP_MS) / CLASSIC_SWEEP_MS) * period;
+	// Fixed-velocity, un-floored band position: advancing at a constant
+	// cells/second (not period / fixed-sweep) keeps the per-frame step ≤1 cell at
+	// the default cadence for any length, so long messages are no steppier.
+	const pos = ((time / 1000) * SHIMMER_SPEED_CELLS_PER_S) % period;
 	const dist = Math.abs(index + CLASSIC_PADDING - pos);
 	if (dist >= CLASSIC_BAND_HALF_WIDTH) return 0;
 	return 0.5 * (1 + Math.cos((Math.PI * dist) / CLASSIC_BAND_HALF_WIDTH));
@@ -119,9 +126,13 @@ function classicIntensity(time: number, index: number, length: number): number {
 function kittIntensity(time: number, index: number, length: number): number {
 	const range = length - 1;
 	if (range <= 0) return 1;
-	const phase = (time % KITT_CYCLE_MS) / KITT_CYCLE_MS;
-	const goingRight = phase < 0.5;
-	const head = goingRight ? phase * 2 * range : (1 - phase) * 2 * range;
+	// Fixed head velocity: a triangle ping-pong over a 2*range round trip at a
+	// constant cells/second, so the bright head advances ≤1 cell per frame at the
+	// default cadence regardless of bar length. Round-trip duration scales with length.
+	const cycleCells = 2 * range;
+	const sweep = ((time / 1000) * SHIMMER_SPEED_CELLS_PER_S) % cycleCells;
+	const goingRight = sweep < range;
+	const head = goingRight ? sweep : cycleCells - sweep;
 	const delta = index - head;
 	const abs = delta < 0 ? -delta : delta;
 	if (abs <= KITT_HEAD_HALF) return 1;

package/src/modes/types.ts

@@ -182,6 +182,9 @@ export interface InteractiveModeContext {
 	flushPendingModelSwitch(): Promise<void>;
 	setWorkingMessage(message?: string): void;
 	applyPendingWorkingMessage(): void;
+	/** Acknowledge a user interrupt (Esc) by switching the loader to an
+	 *  "Interrupting…" label until the agent turn unwinds. */
+	notifyInterrupting(): void;
 	ensureLoadingAnimation(): void;
 	startPendingSubmission(input: {
 		text: string;

package/src/modes/workflow.ts

@@ -3,25 +3,25 @@ import { createGradientHighlighter, type KeywordHighlighter } from "./gradient-h
 import { keywordInProse } from "./markdown-prose";
 
 /**
- * "workflow" keyword support.
+ * "workflowz" keyword support.
  *
  * Typing the standalone word in the input editor paints it with a warm
  * amber→green gradient ({@link highlightWorkflow}); submitting a message that
  * mentions it appends a hidden {@link WORKFLOW_NOTICE} that steers the model to
  * author a deterministic multi-subagent workflow in eval cells (agent/parallel/
  * pipeline). Matching is whitespace-delimited and case-sensitive (lowercase
- * only) — "workflow"/"workflows" trigger, but "workflowed", "Workflow", and
- * "workflow.ts" never do.
+ * only) — "workflowz" triggers, but "workflowzed", "Workflowz", and
+ * "workflowz.ts" never do.
  */
 
-// Detection: lowercase keyword (singular or plural) flanked by whitespace or a string edge. Non-global so `.test` stays stateless.
-const WORKFLOW_WORD = /(?<!\S)workflows?(?!\S)/;
+// Detection: lowercase keyword flanked by whitespace or a string edge. Non-global so `.test` stays stateless.
+const WORKFLOW_WORD = /(?<!\S)workflowz(?!\S)/;
 
-/** Hidden system notice appended after a user message that mentions "workflow". */
+/** Hidden system notice appended after a user message that mentions "workflowz". */
 export const WORKFLOW_NOTICE: string = workflowNotice.trim();
 
 /**
- * Whether `text` contains the standalone keyword "workflow"/"workflows"
+ * Whether `text` contains the standalone keyword "workflowz"
  * (lowercase, whitespace-delimited) in prose — never inside a code block, inline
  * code span, or XML/HTML section.
  */
@@ -30,13 +30,13 @@ export function containsWorkflow(text: string): boolean {
 }
 
 /**
- * Highlight every standalone "workflow"/"workflows" in `text` for editor display
+ * Highlight every standalone "workflowz" in `text` for editor display
  * with a warm amber→green gradient (hue 30..150), visually distinct from
  * ultrathink's rainbow and orchestrate's teal→violet.
  */
 export const highlightWorkflow: KeywordHighlighter = createGradientHighlighter({
-	probe: /workflow/,
-	highlight: /(?<!\S)workflows?(?!\S)/g,
+	probe: /workflowz/,
+	highlight: /(?<!\S)workflowz(?!\S)/g,
 	stops: 14,
 	hue: t => 30 + t * 120,
 });

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

@@ -1,5 +1,5 @@
 <system-notice>
-The user's message above contains the **workflow** keyword: drive this task as a deterministic multi-subagent workflow. Author the orchestration as Python in the `eval` tool and fan out subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
+The user's message above contains the **workflowz** keyword: drive this task as a deterministic multi-subagent workflow. Author the orchestration as Python in the `eval` tool and fan out subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before you commit), or to take on scale one context can't hold (audits, migrations, broad sweeps). This overrides any default tendency to do the whole task inline when fanning out would be more thorough.
 
 <when>
 Worth it when the task benefits from decomposition + parallel coverage, or from independent/adversarial cross-checking before you commit. For a quick lookup or single edit, just do it directly — don't spin up agents. Scout inline FIRST (list the files, scope the diff, find the call sites) to discover the work-list, then fan out over it — you don't need to know the shape before the *task*, only before the *fan-out*. Common shapes, each a well-scoped `eval` call you can chain across turns:

package/src/prompts/tools/bash.md

@@ -31,6 +31,15 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - `async: true` only defers **reporting** of the result — it does NOT disable, extend, or detach the timeout. A daemon started with `async: true` is still killed when `timeout` elapses, regardless of how long the agent waits before reading the result.
 - For long-running daemons (dev servers, watchers): either pass an explicit large `timeout` (up to `3600`), or fully detach the process from this shell using `nohup …  &` / `setsid … &` / `disown` so it survives independent of the bash call's lifecycle.
 {{/if}}
+{{#if autoBackgroundEnabled}}
+
+## Auto-background
+
+- A foreground (non-`async`) call that has not completed within **{{autoBackgroundThresholdSeconds}}s** is automatically converted into a background job and returns a `Background job <id> started: …` notice with the buffered output so far. The command keeps running; the final result is delivered as a follow-up tool call when it completes.
+- This is NOT a failure or a re-queue. Treat the notice as "still running, will report back" — do not retry the same command, and do not wait synchronously for it.
+- Auto-backgrounding does NOT extend `timeout`: the job is still killed at the original deadline.
+- If you need the result inline (e.g. piping into another command), raise `timeout` above the expected duration so it finishes before the threshold matters{{#if asyncEnabled}}, or set `async: true` up front so the contract is explicit{{/if}}.
+{{/if}}
 
 # Output minimizer
 

package/src/prompts/tools/browser.md

@@ -26,7 +26,7 @@ Drives real Chromium tab; full puppeteer access via JS execution.
   - `tab.waitForResponse(pattern, { timeout? })` — pattern substring, `RegExp`, or `(response) => boolean`. Returns raw puppeteer `HTTPResponse` (call `.text()` / `.json()` / `.status()` / `.headers()` on it).
   - `tab.evaluate(fn, …args)` — sugar for `page.evaluate` with abort signal already wired. Use this instead of dropping to `page.evaluate` for ad-hoc DOM reads.
   - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — captures screenshot and **auto-attaches to tool output for you to view** (unless `silent: true`). `save` is **strictly optional**: OMIT when you just want to look at page — downscaled image shown regardless, full-res capture written to temp file automatically. Pass `save` (a path) ONLY when deliberately need to keep full-res copy on disk for later use; `browser.screenshotDir` does same for every shot. NEVER invent `save` path for throwaway/temporal screenshot.
-  - `tab.extract(format = "markdown")` — Readability-extracted page content.
+  - `tab.extract(format = "markdown")` — returns Readability-extracted page content as a string (`"markdown"` or `"text"`). Throws if the page yields no readable content.
 - Selectors accept CSS plus puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`. Playwright-style `p-aria/[name="…"]`, `p-text/…` normalized.
 - Default `tab.observe()` over `tab.screenshot()` for page state. Screenshot only when visual appearance matters.
 </instruction>

package/src/prompts/tools/eval.md

@@ -46,8 +46,9 @@ tool.<name>(args) → unknown
     Invoke any session tool by name. `args` is the tool's parameter object.
 llm(prompt, model?="default", system?=None, schema?=None) → str | dict
     Oneshot, stateless LLM call (no history, no tools). `model` picks a tier: "smol" (fast), "default" (this session's model), "slow" (most capable). Pass `system` for a system prompt. Pass a JSON-Schema `schema` to force structured output and get the parsed object back; otherwise returns the completion text.
-agent(prompt, agent_type?="task", model?=None, context?=None, label?=None, schema?=None) → str | dict
+{{#if spawns}}agent(prompt, agent_type?="task", model?=None, context?=None, label?=None, schema?=None) → str | dict
     Run a subagent and return its final output. Defaults to the bundled "task" agent; pass `agent_type`/`agentType` for another discovered agent. Pass a JSON-Schema `schema` to force structured output and get the parsed object back.
+{{/if}}
 parallel(thunks) → list
     Run thunks (callables) through a bounded pool, preserving input order. The pool is as wide as a `task` tool batch (tracks the `task.maxConcurrency` setting), so fan out as wide as the work divides — don't pre-shrink it. Barrier: returns once all finish; a thunk that throws propagates.
 pipeline(items, ...stages) → list

package/src/prompts/tools/read.md

@@ -18,8 +18,8 @@ Append `:<sel>` to `path`. The bare path falls back to the default mode.
 - `:50` / `:50-` — read from line 50 onward.
 - `:50-200` — lines 50–200 inclusive.
 - `:50+150` — 150 lines starting at line 50.
-- `:20+1` — exactly one line.
-- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).
+- `:20+1` — anchor on line 20 (single-range reads expand by ≤1 leading and ≤3 trailing context lines).
+- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged). Multi-range mode returns exact bounds with no context padding.
 - `:raw` — verbatim text; no anchors, no summary, no line prefixes.
 - `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.
 - `:conflicts` — one-line-per-block index of every unresolved git merge conflict.

package/src/sdk.ts

@@ -41,7 +41,9 @@ import { createApiKeyResolver } from "./config/api-key-resolver";
 import { shouldEnableAppendOnlyContext } from "./config/append-only-context-mode";
 import { ModelRegistry } from "./config/model-registry";
 import {
+	defaultModelPerProvider,
 	formatModelString,
+	getModelMatchPreferences,
 	parseModelPattern,
 	parseModelString,
 	resolveAllowedModels,
@@ -709,6 +711,7 @@ function customToolToDefinition(tool: CustomTool): ToolDefinition {
 		parameters: tool.parameters,
 		hidden: tool.hidden,
 		deferrable: tool.deferrable,
+		approval: typeof tool.approval === "function" ? tool.approval.bind(tool) : tool.approval,
 		mcpServerName: tool.mcpServerName,
 		mcpToolName: tool.mcpToolName,
 		execute: (toolCallId, params, signal, onUpdate, ctx) =>
@@ -1030,9 +1033,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const hasServiceTierEntry = existingBranch.some(entry => entry.type === "service_tier_change");
 
 	const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
-	const modelMatchPreferences = {
-		usageOrder: settings.getStorage()?.getModelUsageOrder(),
-	};
+	const modelMatchPreferences = getModelMatchPreferences(settings);
 	const allowedModels = await logger.time("resolveAllowedModels", () =>
 		resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
 	);
@@ -1553,9 +1554,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Resolve deferred --model pattern now that extension models are registered.
 		if (!model && options.modelPattern) {
 			const availableModels = modelRegistry.getAll();
-			const matchPreferences = {
-				usageOrder: settings.getStorage()?.getModelUsageOrder(),
-			};
+			const matchPreferences = getModelMatchPreferences(settings);
 			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences, {
 				modelRegistry,
 			});
@@ -1574,12 +1573,30 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// Re-resolve the allowed set: extension factories above may have
 			// registered providers/models that weren't visible at startup.
 			const fallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
-			for (const candidate of fallbackCandidates) {
-				if (await hasModelApiKey(candidate)) {
-					model = candidate;
+			// Prefer each provider's configured default model
+			// (DEFAULT_MODEL_PER_PROVIDER) over raw catalog order. Without this the
+			// first-run fallback picks whatever model sorts first in models.json for
+			// the winning provider (e.g. anthropic's claude-3-5-sonnet-20240620)
+			// instead of the intended provider default (claude-sonnet-4-6). Mirrors
+			// findInitialModel's precedence.
+			for (const [provider, defaultId] of Object.entries(defaultModelPerProvider)) {
+				const preferred = fallbackCandidates.find(
+					candidate => candidate.provider === provider && candidate.id === defaultId,
+				);
+				if (preferred && (await hasModelApiKey(preferred))) {
+					model = preferred;
 					break;
 				}
 			}
+			// Otherwise, first available model with a valid API key.
+			if (!model) {
+				for (const candidate of fallbackCandidates) {
+					if (await hasModelApiKey(candidate)) {
+						model = candidate;
+						break;
+					}
+				}
+			}
 			if (model) {
 				if (modelFallbackMessage) {
 					modelFallbackMessage += `. Using ${model.provider}/${model.id}`;