@oh-my-pi/pi-coding-agent 16.3.6 → 16.3.8

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();
@@ -2614,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 {
@@ -2676,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();
@@ -3904,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

@@ -182,3 +182,17 @@ export function resolveAssistantErrorPresentation(
 	}
 	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,6 +50,7 @@ import { buildSkillCommandPrompt, invokeSkillCommandFromText, isKnownSkillComman
 import { createAssistantMessageComponent } from "./interactive-context-helpers";
 import {
 	assistantHasVisibleContent,
+	assistantUsageIsBilled,
 	buildAsyncResultBlock,
 	buildFileMentionBlock,
 	buildIrcMessageCard,
@@ -463,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`.

package/src/sdk.ts

@@ -31,14 +31,17 @@ import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { bucketRules } from "./capability/rule-buckets";
 import { shouldEnableAppendOnlyContext } from "./config/append-only-context-mode";
 import { shouldInlineToolDescriptors } from "./config/inline-tool-descriptors-mode";
-import { ModelRegistry } from "./config/model-registry";
+import { isAuthenticated, kNoAuth, ModelRegistry } from "./config/model-registry";
 import {
+	formatModelSelectorValue,
 	formatModelString,
+	formatModelStringWithRouting,
 	getModelMatchPreferences,
 	parseModelPattern,
 	parseModelString,
 	pickDefaultAvailableModel,
 	resolveAllowedModels,
+	resolveConfiguredModelPatterns,
 	resolveModelRoleValue,
 } from "./config/model-resolver";
 import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate } from "./config/prompt-templates";
@@ -391,9 +394,13 @@ export interface CreateAgentSessionOptions {
 
 	/** Model to use. Default: from settings, else first available */
 	model?: Model;
-	/** Raw model pattern string (e.g. from --model CLI flag) to resolve after extensions load.
+	/** Raw model pattern(s) (e.g. from --model CLI flag) to resolve after extensions load.
 	 * Used when model lookup is deferred because extension-provided models aren't registered yet. */
-	modelPattern?: string;
+	modelPattern?: string | string[];
+	/** Authenticated fallback selector for deferred subagent model patterns. */
+	modelPatternAuthFallback?: string;
+	/** Role name used to install retry fallbacks after deferred subagent patterns resolve. */
+	modelPatternFallbackRole?: string;
 	/** Thinking selector. Default: from settings, else unset */
 	thinkingLevel?: ConfiguredThinkingLevel;
 	/** Models available for cycling (Ctrl+P in interactive mode) */
@@ -1246,7 +1253,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const hasThinkingEntry = existingBranch.some(entry => entry.type === "thinking_level_change");
 	const hasServiceTierEntry = existingBranch.some(entry => entry.type === "service_tier_change");
 
-	const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
+	const deferredModelPatterns = Array.isArray(options.modelPattern)
+		? options.modelPattern.map(pattern => pattern.trim()).filter(Boolean)
+		: options.modelPattern?.trim()
+			? [options.modelPattern.trim()]
+			: [];
+	const hasExplicitModel = options.model !== undefined || deferredModelPatterns.length > 0;
 	const modelMatchPreferences = getModelMatchPreferences(settings);
 	const allowedModels = await logger.time("resolveAllowedModels", () =>
 		resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
@@ -1958,23 +1970,111 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				}
 			}
 		}
-		// Resolve deferred --model pattern now that extension models are registered.
-		if (!model && options.modelPattern) {
+		// Resolve deferred --model/subagent patterns now that extension models are
+		// registered. Expand role aliases (`pi/smol`) and comma chains to concrete
+		// selectors first so deferred resolution accepts everything the immediate
+		// path (resolveModelOverride → resolveModelRoleValue) accepts.
+		if (!model && deferredModelPatterns.length > 0) {
+			const expandedModelPatterns = resolveConfiguredModelPatterns(deferredModelPatterns, settings);
 			const availableModels = modelRegistry.getAll();
 			const matchPreferences = getModelMatchPreferences(settings);
-			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences);
-			if (resolved) {
-				model = resolved;
+			for (let patternIndex = 0; patternIndex < expandedModelPatterns.length; patternIndex += 1) {
+				const pattern = expandedModelPatterns[patternIndex];
+				const primary = parseModelPattern(pattern, availableModels, matchPreferences);
+				if (!primary.model) continue;
+				let selectedModel = primary.model;
+				let selectedThinkingLevel = primary.thinkingLevel;
+				let selectedExplicitThinkingLevel = primary.explicitThinkingLevel;
+				let authFallbackUsed = false;
+				if (options.modelPatternAuthFallback) {
+					const primaryKey = await modelRegistry.getApiKey(primary.model);
+					if (primaryKey !== kNoAuth && !isAuthenticated(primaryKey)) {
+						const fallback = parseModelPattern(
+							options.modelPatternAuthFallback,
+							availableModels,
+							matchPreferences,
+						);
+						if (fallback.model) {
+							const fallbackKey = await modelRegistry.getApiKey(fallback.model);
+							if (isAuthenticated(fallbackKey)) {
+								selectedModel = fallback.model;
+								selectedThinkingLevel = fallback.thinkingLevel;
+								selectedExplicitThinkingLevel = fallback.explicitThinkingLevel;
+								authFallbackUsed = true;
+							}
+						}
+					}
+				}
+				if (!authFallbackUsed && options.modelPatternFallbackRole) {
+					const primarySelector = formatModelSelectorValue(
+						formatModelStringWithRouting(primary.model),
+						primary.thinkingLevel,
+					);
+					const seenSelectors = new Set<string>([primarySelector]);
+					const fallbackSelectors: string[] = [];
+					for (const fallbackPattern of expandedModelPatterns.slice(patternIndex + 1)) {
+						const fallback = parseModelPattern(fallbackPattern, availableModels, matchPreferences);
+						if (!fallback.model) continue;
+						const fallbackSelector = formatModelSelectorValue(
+							formatModelStringWithRouting(fallback.model),
+							fallback.thinkingLevel,
+						);
+						if (seenSelectors.has(fallbackSelector)) continue;
+						seenSelectors.add(fallbackSelector);
+						fallbackSelectors.push(fallbackSelector);
+					}
+					if (fallbackSelectors.length > 0) {
+						const modelRoles: Record<string, string> = {};
+						const existingRoles = settings.getModelRoles();
+						for (const role in existingRoles) {
+							const selector = existingRoles[role];
+							if (selector) {
+								modelRoles[role] = selector;
+							}
+						}
+						modelRoles[options.modelPatternFallbackRole] = primarySelector;
+						settings.override("modelRoles", modelRoles);
+						const fallbackChains: Record<string, string[]> = {
+							[options.modelPatternFallbackRole]: fallbackSelectors,
+						};
+						const existingFallbackChains = settings.get("retry.fallbackChains");
+						for (const role in existingFallbackChains) {
+							if (role !== options.modelPatternFallbackRole) {
+								fallbackChains[role] = existingFallbackChains[role];
+							}
+						}
+						settings.override("retry.fallbackChains", fallbackChains);
+					}
+				}
+				model = selectedModel;
 				modelFallbackMessage = undefined;
-			} else {
-				modelFallbackMessage = `Model "${options.modelPattern}" not found`;
+				if (selectedExplicitThinkingLevel) {
+					restoredSessionThinkingLevel = selectedThinkingLevel;
+				}
+				thinkingLevel = pickInitialThinkingLevel(selectedModel);
+				autoThinking = thinkingLevel === AUTO_THINKING;
+				effectiveThinkingLevel = concreteThinkingLevel(thinkingLevel);
+				effectiveThinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
+					autoThinking
+						? resolveProvisionalAutoLevel(selectedModel)
+						: resolveThinkingLevelForModel(selectedModel, effectiveThinkingLevel),
+				);
+				preconnectModelHost(selectedModel.baseUrl);
+				break;
+			}
+			if (!model) {
+				const requested =
+					deferredModelPatterns.length === 1
+						? `"${deferredModelPatterns[0]}"`
+						: `one of ${deferredModelPatterns.map(pattern => `"${pattern}"`).join(", ")}`;
+				modelFallbackMessage = `Model ${requested} not found`;
 			}
 		}
 
 		// Fall back to first available model with a valid API key, honoring the
 		// path-scoped `enabledModels` allow-list when configured. Skip when the
 		// user explicitly requested a model via --model that wasn't found.
-		if (!model && !options.modelPattern) {
+		if (!model && deferredModelPatterns.length === 0) {
 			// 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);