@oh-my-pi/pi-coding-agent 16.0.11 → 16.1.1

package/src/session/agent-session.ts

@@ -35,6 +35,7 @@ import {
 	countTokens,
 	resolveTelemetry,
 	ThinkingLevel,
+	type ToolChoiceDirective,
 } from "@oh-my-pi/pi-agent-core";
 import {
 	AGGRESSIVE_SHAKE_CONFIG,
@@ -102,6 +103,7 @@ import {
 	resolveServiceTier,
 	streamSimple,
 } from "@oh-my-pi/pi-ai";
+import { stripToolDescriptions } from "@oh-my-pi/pi-ai/utils/schema";
 import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
 import { modelsAreEqual } from "@oh-my-pi/pi-catalog/models";
 import { MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
@@ -260,6 +262,7 @@ import type { CheckpointState } from "../tools/checkpoint";
 import { outputMeta, wrapToolWithMetaNotice } from "../tools/output-meta";
 import { normalizeLocalScheme, resolveToCwd } from "../tools/path-utils";
 import { isAutoQaEnabled } from "../tools/report-tool-issue";
+import { buildResolveReminderMessage } from "../tools/resolve";
 import { getLatestTodoPhasesFromEntries, type TodoItem, type TodoPhase } from "../tools/todo";
 import { ToolAbortError, ToolError } from "../tools/tool-errors";
 import { clampTimeout } from "../tools/tool-timeouts";
@@ -367,6 +370,23 @@ const COMPACTION_CHECK_CONTINUATION: CompactionCheckResult = {
 	deferredHandoff: false,
 	continuationScheduled: true,
 };
+
+/**
+ * Per-turn prune cache window. A tool result whose all-message suffix exceeds
+ * this is in the warm, already-sent prompt-cache prefix: re-writing it costs the
+ * cacheWrite premium on the whole suffix. Per-turn passes only reclaim inside
+ * this tail (matches the supersede pass's default `suffixTokenLimit`); deeper
+ * stale/age victims are left to compaction/shake, which rebuild the cache anyway.
+ */
+const PRUNE_CACHE_WARM_SUFFIX_TOKENS = 8_000;
+
+/**
+ * Idle gap after which the supersede pass may flush the whole sent region (the
+ * provider cache is cold, so re-writing it is free). MUST exceed the maximum
+ * Anthropic prompt-cache TTL — "long" retention (the OAuth default) is 1h — or a
+ * still-warm prefix is busted by the flush. 90 min leaves margin over the 1h TTL.
+ */
+const PRUNE_IDLE_FLUSH_MS = 90 * 60_000;
 export type CommandMetadataChangedListener = () => void | Promise<void>;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
 
@@ -516,6 +536,12 @@ export interface AgentSessionConfig {
 	advisorReadOnlyTools?: AgentTool[];
 	/** Preloaded watchdog prompt content for the advisor. */
 	advisorWatchdogPrompt?: string;
+	/**
+	 * Strip tool descriptions from provider-bound tool specs on side requests
+	 * (handoff). Must match the session-start value used to build the system
+	 * prompt so inline descriptors are not also sent through provider schemas.
+	 */
+	pruneToolDescriptions?: boolean;
 	/**
 	 * Disconnect this session's OWNED MCP manager on dispose. Provided only when
 	 * the session created the manager (top-level sessions); subagents reuse a
@@ -1305,6 +1331,8 @@ export class AgentSession {
 	// unchanged — otherwise a mid-turn estimate would survive into idle.
 	#contextUsageRevision = 0;
 	#obfuscator: SecretObfuscator | undefined;
+	/** Session-start value of `inlineToolDescriptors`; drives handoff tool pruning. */
+	#pruneToolDescriptions = false;
 	#checkpointState: CheckpointState | undefined = undefined;
 	#pendingRewindReport: string | undefined = undefined;
 	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
@@ -1316,19 +1344,15 @@ export class AgentSession {
 		if (process.platform !== "darwin") return;
 		if (isBunTestRuntime()) return;
 		if (this.#powerAssertion) return;
-		const idle = this.settings.get("power.preventIdleSleep");
-		const system = this.settings.get("power.preventSystemSleep");
-		const user = this.settings.get("power.declareUserActive");
-		const display = this.settings.get("power.preventDisplaySleep");
-		// All four off → user opted out; do nothing.
-		if (!idle && !system && !user && !display) return;
+		const mode = this.settings.get("power.sleepPrevention");
+		if (mode === "off") return;
 		try {
 			this.#powerAssertion = MacOSPowerAssertion.start({
 				reason: "Oh My Pi agent session",
-				idle,
-				system,
-				user,
-				display,
+				idle: true,
+				display: mode === "display" || mode === "system",
+				system: mode === "system",
+				user: mode === "system",
 			});
 		} catch (error) {
 			logger.warn("Failed to acquire macOS power assertion", { error: String(error) });
@@ -1513,6 +1537,7 @@ export class AgentSession {
 		this.#modelRegistry = config.modelRegistry;
 		this.#advisorReadOnlyTools = config.advisorReadOnlyTools;
 		this.#advisorWatchdogPrompt = config.advisorWatchdogPrompt;
+		this.#pruneToolDescriptions = config.pruneToolDescriptions === true;
 		this.#validateRetryFallbackChains();
 		this.#toolRegistry = config.toolRegistry ?? new Map();
 		this.#requestedToolNames = config.requestedToolNames;
@@ -2124,6 +2149,36 @@ export class AgentSession {
 		return undefined;
 	}
 
+	/**
+	 * The per-turn tool-choice directive for the agent loop's `getToolChoice`. Priority:
+	 *   1. a HARD forced choice from the queue (genuine forces: user-force, eager-todo, …) —
+	 *      consuming, unchanged from `nextToolChoice`;
+	 *   2. else, when a non-forcing preview is pending, a {@link SoftToolRequirement} — a
+	 *      PEEK (advances/pops nothing), so the agent-loop injects the reminder once per head
+	 *      and escalates to a forced `resolve` only if the model declines. A compliant turn
+	 *      pays ZERO tool_choice change (no prompt-cache messages-cache invalidation);
+	 *   3. else undefined.
+	 */
+	nextToolChoiceDirective(): ToolChoiceDirective | undefined {
+		const hard = this.nextToolChoice();
+		if (hard !== undefined) return hard;
+		const head = this.#toolChoiceQueue.peekPendingHead();
+		if (head !== undefined) {
+			return {
+				soft: true,
+				id: head.id,
+				toolName: "resolve",
+				reminder: [buildResolveReminderMessage(head.sourceToolName)],
+			};
+		}
+		return undefined;
+	}
+
+	/** Peek the head non-forcing pending preview invoker, for the `resolve` tool's dispatch. */
+	peekPendingInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined {
+		return this.#toolChoiceQueue.peekPendingInvoker();
+	}
+
 	/**
 	 * Force the next model call to target a specific active tool, then terminate
 	 * the agent loop. Pushes a two-step sequence [forced, "none"] so the model
@@ -4851,7 +4906,7 @@ export class AgentSession {
 	 * cache per-tool strings without preserving this property.
 	 *
 	 * Inputs NOT covered: tool input schemas; memory instructions read from disk;
-	 * and SDK-init-time closure constants in `sdk.ts` (`repeatToolDescriptions`,
+	 * and SDK-init-time closure constants in `sdk.ts` (`inlineToolDescriptors`,
 	 * `eagerTasks`, `intentField`, `mcpDiscoveryEnabled`, `secretsEnabled`). The
 	 * closure-captured ones cannot change at runtime regardless of skip behavior.
 	 * For everything else, callers must explicitly call `refreshBaseSystemPrompt()`
@@ -7299,11 +7354,16 @@ export class AgentSession {
 
 	async #pruneToolOutputs(): Promise<{ prunedCount: number; tokensSaved: number } | undefined> {
 		const branchEntries = this.sessionManager.getBranch();
+		const keepBoundaryId = getLatestCompactionEntry(branchEntries)?.firstKeptEntryId;
 		const result = pruneToolOutputs(
 			branchEntries,
 			this.#withPlanProtection({
 				...DEFAULT_PRUNE_CONFIG,
 				pruneUseless: this.settings.getGroup("compaction").dropUseless,
+				// Cache-stable boundary: never re-write the warm, already-sent prefix
+				// (deep stale/age victims) or summarized-away entries every turn.
+				keepBoundaryId,
+				cacheWarmSuffixTokens: PRUNE_CACHE_WARM_SUFFIX_TOKENS,
 			}),
 		);
 		if (result.prunedCount === 0) {
@@ -7331,12 +7391,17 @@ export class AgentSession {
 		const { supersedeReads, dropUseless } = this.settings.getGroup("compaction");
 		if (!supersedeReads && !dropUseless) return undefined;
 		const branchEntries = this.sessionManager.getBranch();
+		const keepBoundaryId = getLatestCompactionEntry(branchEntries)?.firstKeptEntryId;
 		const result = pruneSupersededToolResults(
 			branchEntries,
 			this.#withPlanProtection({
 				supersedeKey: supersedeReads ? readToolSupersedeKey : undefined,
 				pruneUseless: dropUseless,
 				protectedTools: [...DEFAULT_PRUNE_CONFIG.protectedTools],
+				// Never re-write summarized-away entries; only flush the whole sent
+				// region once the cache is genuinely cold (idle exceeds the 1h TTL).
+				keepBoundaryId,
+				idleFlushMs: PRUNE_IDLE_FLUSH_MS,
 			}),
 		);
 		if (result.prunedCount === 0) {
@@ -7420,8 +7485,14 @@ export class AgentSession {
 			return { mode, toolResultsDropped: 0, blocksDropped: 0, imagesDropped: removed, tokensFreed: 0 };
 		}
 
-		const config = this.#withPlanProtection(opts.config ?? AGGRESSIVE_SHAKE_CONFIG);
-		const regions = collectShakeRegions(this.sessionManager.getBranch(), config);
+		const branchEntries = this.sessionManager.getBranch();
+		const config = this.#withPlanProtection({
+			...(opts.config ?? AGGRESSIVE_SHAKE_CONFIG),
+			// Skip entries summarized away by the latest compaction — shaking them
+			// only churns persisted history with no prompt/cache effect.
+			keepBoundaryId: getLatestCompactionEntry(branchEntries)?.firstKeptEntryId,
+		});
+		const regions = collectShakeRegions(branchEntries, config);
 		if (regions.length === 0) {
 			return { mode, toolResultsDropped: 0, blocksDropped: 0, tokensFreed: 0 };
 		}
@@ -7598,9 +7669,6 @@ export class AgentSession {
 					convertToLlm,
 					model: this.model,
 					shape: snapcompact.resolveShape(this.model, this.settings.get("snapcompact.shape")),
-					// Providers with hard image caps (OpenRouter: 8) silently drop
-					// frames past the cap — keep the archive within budget.
-					maxFrames: snapcompact.providerFrameBudget(this.model?.provider),
 				});
 				const ctxWindow = this.model?.contextWindow ?? 0;
 				const budget =
@@ -7849,7 +7917,10 @@ export class AgentSession {
 				this.#modelRegistry.resolver(model, this.sessionId),
 				{
 					systemPrompt: this.#obfuscateForProvider(this.#baseSystemPrompt),
-					tools: obfuscateProviderTools(this.#obfuscator, this.agent.state.tools),
+					tools: obfuscateProviderTools(
+						this.#obfuscator,
+						this.#pruneToolDescriptions ? stripToolDescriptions(this.agent.state.tools) : this.agent.state.tools,
+					),
 					customInstructions: this.#obfuscateTextForProvider(customInstructions),
 					convertToLlm: messages => this.#convertToLlmForSideRequest(messages),
 					initiatorOverride: "agent",
@@ -9154,14 +9225,15 @@ export class AgentSession {
 	 */
 	#projectSnapcompactContextTokens(preparation: CompactionPreparation, result: snapcompact.CompactionResult): number {
 		const archive = snapcompact.getPreservedArchive(result.preserveData);
-		const frames = archive ? snapcompact.images(archive) : undefined;
+		const blocks = archive ? snapcompact.historyBlocks(archive) : undefined;
 		const summaryMessage = createCompactionSummaryMessage(
 			result.summary,
 			result.tokensBefore,
 			new Date().toISOString(),
 			result.shortSummary,
 			undefined,
-			frames,
+			undefined,
+			blocks,
 		);
 		let tokens = computeNonMessageTokens(this) + estimateTokens(summaryMessage);
 		for (const message of preparation.recentMessages) {
@@ -9389,15 +9461,15 @@ export class AgentSession {
 			let details: unknown;
 
 			// Snapcompact runs locally first; if its frame archive plus the kept
-			// history still overflows the model window (frames are capped by the
-			// image budget and cost ~FRAME_TOKEN_ESTIMATE each), an LLM summary is
-			// far cheaper — downgrade to context-full and take the summarizer path.
+			// history still overflows the model window (frames default to
+			// MAX_FRAMES_DEFAULT and cost ~FRAME_TOKEN_ESTIMATE each), an LLM
+			// summary is far cheaper — downgrade to context-full and take the
+			// summarizer path.
 			let snapcompactResult: snapcompact.CompactionResult | undefined;
 			if (action === "snapcompact" && compactionPrep.kind !== "fromHook") {
 				snapcompactResult = await snapcompact.compact(preparation, {
 					convertToLlm,
 					model: this.model,
-					maxFrames: snapcompact.providerFrameBudget(this.model?.provider),
 				});
 				const ctxWindow = this.model?.contextWindow ?? 0;
 				const budget =
@@ -12236,6 +12308,7 @@ export class AgentSession {
 			model: this.agent.state.model,
 			thinkingLevel: this.#thinkingLevel,
 			tools: this.agent.state.tools,
+			inlineToolDescriptors: this.#pruneToolDescriptions,
 		});
 	}
 

package/src/session/messages.ts

@@ -204,16 +204,14 @@ function wrapSteeringUserMessage(message: UserMessage): UserMessage {
 }
 
 export function wrapSteeringForModel(messages: AgentMessage[]): AgentMessage[] {
-	const last = messages[messages.length - 1];
-	if (!isSteeringUserMessage(last)) return messages;
-
-	let firstSteer = messages.length - 1;
-	while (firstSteer > 0 && isSteeringUserMessage(messages[firstSteer - 1])) {
-		firstSteer--;
-	}
-
+	// Wrap EVERY steering message, not just a trailing run. The wire bytes of a
+	// steering message must be a pure function of the message itself, independent
+	// of its position in the array. When only the trailing steer was wrapped, the
+	// same persisted message was sent enveloped while it was the tail and raw once
+	// the assistant's reply buried it — rewriting already-cached prefix bytes and
+	// busting the provider prompt cache from that message onward on the next turn.
 	let wrappedMessages: AgentMessage[] | undefined;
-	for (let i = firstSteer; i < messages.length; i++) {
+	for (let i = 0; i < messages.length; i++) {
 		const message = messages[i];
 		if (!isSteeringUserMessage(message)) continue;
 		const wrappedMessage = wrapSteeringUserMessage(message);

package/src/session/session-context.ts

@@ -20,6 +20,13 @@ export interface SessionContext {
 	mode: string;
 	/** Mode-specific data from the last mode_change entry */
 	modeData?: Record<string, unknown>;
+	/**
+	 * Array parallel to messages, indicating which assistant turns should
+	 * have their prompt-cache misses suppressed/explained (because a model,
+	 * compaction, or plan-mode transition directly preceded them).
+	 * Only populated in transcript mode.
+	 */
+	cacheMissExplainedAt?: boolean[];
 }
 
 /** Lists session model strings to try when restoring, in fallback order. */
@@ -191,12 +198,45 @@ export function buildSessionContext(
 	// 2. Emit kept messages (from firstKeptEntryId up to compaction)
 	// 3. Emit messages after compaction
 	const messages: AgentMessage[] = [];
+	const cacheMissExplainedAt: boolean[] = [];
+	let pendingReset = false;
+	let currentMode = "none";
+	let lastAssistantModel: string | undefined;
+
+	const handleEntryResetTracking = (entry: SessionEntry) => {
+		if (entry.type === "compaction") {
+			pendingReset = true;
+		} else if (entry.type === "model_change") {
+			pendingReset = true;
+		} else if (entry.type === "mode_change") {
+			const isPlanTransition = (entry.mode === "plan") !== (currentMode === "plan");
+			if (isPlanTransition) {
+				pendingReset = true;
+			}
+			currentMode = entry.mode;
+		}
+	};
+
+	const pushMessage = (msg: AgentMessage) => {
+		messages.push(msg);
+		if (!options?.transcript) return;
+		if (msg.role === "assistant") {
+			const currentModel = `${msg.provider}/${msg.model}`;
+			const modelChanged = lastAssistantModel !== undefined && lastAssistantModel !== currentModel;
+			lastAssistantModel = currentModel;
+			cacheMissExplainedAt.push(pendingReset || modelChanged);
+			pendingReset = false;
+		} else {
+			cacheMissExplainedAt.push(false);
+		}
+	};
 
 	const appendMessage = (entry: SessionEntry) => {
+		handleEntryResetTracking(entry);
 		if (entry.type === "message") {
-			messages.push(entry.message);
+			pushMessage(entry.message);
 		} else if (entry.type === "custom_message") {
-			messages.push(
+			pushMessage(
 				createCustomMessage(
 					entry.customType,
 					entry.content,
@@ -207,7 +247,7 @@ export function buildSessionContext(
 				),
 			);
 		} else if (entry.type === "branch_summary" && entry.summary) {
-			messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
+			pushMessage(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
 		}
 	};
 
@@ -217,16 +257,18 @@ export function buildSessionContext(
 		// TUI) at the point it fired, with any snapcompact frames re-attached so
 		// the component can report them.
 		for (const entry of path) {
+			handleEntryResetTracking(entry);
 			if (entry.type === "compaction") {
 				const snapcompactArchive = snapcompact.getPreservedArchive(entry.preserveData);
-				messages.push(
+				pushMessage(
 					createCompactionSummaryMessage(
 						entry.summary,
 						entry.tokensBefore,
 						entry.timestamp,
 						entry.shortSummary,
 						undefined,
-						snapcompactArchive ? snapcompact.images(snapcompactArchive) : undefined,
+						undefined,
+						snapcompactArchive ? snapcompact.historyBlocks(snapcompactArchive) : undefined,
 					),
 				);
 			} else {
@@ -251,14 +293,15 @@ export function buildSessionContext(
 		// Emit summary first; re-attach any archived snapcompact frames so the
 		// model can keep reading the archived history after every context rebuild.
 		const snapcompactArchive = snapcompact.getPreservedArchive(compaction.preserveData);
-		messages.push(
+		pushMessage(
 			createCompactionSummaryMessage(
 				compaction.summary,
 				compaction.tokensBefore,
 				compaction.timestamp,
 				compaction.shortSummary,
 				providerPayload,
-				snapcompactArchive ? snapcompact.images(snapcompactArchive) : undefined,
+				undefined,
+				snapcompactArchive ? snapcompact.historyBlocks(snapcompactArchive) : undefined,
 			),
 		);
 
@@ -333,6 +376,9 @@ export function buildSessionContext(
 			);
 		if (normalized.length === 0) {
 			messages.splice(i, 1);
+			if (options?.transcript) {
+				cacheMissExplainedAt.splice(i, 1);
+			}
 		} else {
 			messages[i] = { ...message, content: normalized };
 		}
@@ -340,6 +386,7 @@ export function buildSessionContext(
 
 	return {
 		messages,
+		cacheMissExplainedAt: options?.transcript ? cacheMissExplainedAt : undefined,
 		thinkingLevel,
 		serviceTier,
 		models,

package/src/session/session-dump-format.ts

@@ -38,6 +38,7 @@ export interface FormatSessionDumpTextOptions {
 	model?: Model | null;
 	thinkingLevel?: ThinkingLevel | string | null;
 	tools?: readonly SessionDumpToolInfo[];
+	inlineToolDescriptors?: boolean;
 }
 
 interface InventoryTool {
@@ -78,7 +79,8 @@ function renderDumpHeader(options: FormatSessionDumpTextOptions, inventoryTools:
 	lines.push(`Thinking Level: ${options.thinkingLevel ?? ""}`);
 	lines.push("\n");
 
-	if (inventoryTools.length > 0) {
+	const hasSystemPromptToolInventory = options.inlineToolDescriptors === true;
+	if (inventoryTools.length > 0 && !hasSystemPromptToolInventory) {
 		lines.push("## Available Tools\n");
 		lines.push(renderToolInventory(inventoryTools, model?.id ?? ""));
 		lines.push("\n");

package/src/session/snapcompact-inline.ts

@@ -46,8 +46,8 @@ export type SnapcompactSavingsSink = (
 // Per-provider image-count budgets live in @oh-my-pi/snapcompact
 // (`providerImageBudget`): snapcompact frames are 1568px (<2000px) so
 // dimension/size limits never bind; only COUNT does. Once the budget is
-// spent (e.g. OpenRouter's hard 8-image cap, already consumed by archive
-// frames), tool results ship verbatim as text.
+// spent by already-attached archive/system-prompt images, tool results ship
+// verbatim as text.
 const MAX_SYSTEM_PROMPT_FRAMES = 6;
 /** Tool results under this many tokens are never rasterized — the swap can't
  *  save enough to justify trading crisp text for an image. */

package/src/session/tool-choice-queue.ts

@@ -65,6 +65,20 @@ interface InFlight {
 	invoked: boolean;
 }
 
+/**
+ * A non-forcing pending preview invoker. Registered by `queueResolveHandler`
+ * (resolve previews) so the `resolve` tool can dispatch to a staged action
+ * WITHOUT this queue forcing `tool_choice`. The agent-loop's
+ * SoftToolRequirement lifecycle (remind-then-escalate) owns any forcing.
+ */
+interface PendingInvoker {
+	/** Unique id for this staged preview; never reused (never clobbered by label). */
+	id: string;
+	/** Source tool that staged the preview (e.g. "ast_edit"), for the reminder. */
+	sourceToolName: string;
+	onInvoked: (input: unknown) => Promise<unknown> | unknown;
+}
+
 // ── Queue ───────────────────────────────────────────────────────────────────
 
 export class ToolChoiceQueue {
@@ -75,6 +89,12 @@ export class ToolChoiceQueue {
 	 * Consumers (e.g. todo reminder suppression) read via consumeLastServedLabel().
 	 */
 	#lastResolvedLabel: string | undefined;
+	/**
+	 * Non-forcing pending preview invokers, stacked by UNIQUE id. The `resolve`
+	 * tool dispatches to the head; the agent-loop's soft-tool-requirement
+	 * lifecycle drives resolution without this queue forcing `tool_choice`.
+	 */
+	#pendingInvokers: PendingInvoker[] = [];
 
 	// ── Push ──────────────────────────────────────────────────────────────
 
@@ -190,6 +210,44 @@ export class ToolChoiceQueue {
 		};
 	}
 
+	// ── Non-forcing pending invokers ──────────────────────────────────────
+	// Preview producers (queueResolveHandler) register here so `resolve` can
+	// dispatch to a staged action WITHOUT a forced tool_choice (no messages-cache
+	// bust). Stacked by UNIQUE id: a re-register replaces only the same id, so
+	// concurrent/sequential previews each survive and resolve independently.
+
+	/** Register (or replace by exact id) a non-forcing pending preview invoker. */
+	registerPendingInvoker(
+		id: string,
+		sourceToolName: string,
+		onInvoked: (input: unknown) => Promise<unknown> | unknown,
+	): void {
+		this.removePendingInvoker(id);
+		this.#pendingInvokers.push({ id, sourceToolName, onInvoked });
+	}
+
+	/** Drop the pending invoker with this id (e.g. after it resolves). */
+	removePendingInvoker(id: string): void {
+		this.#pendingInvokers = this.#pendingInvokers.filter(p => p.id !== id);
+	}
+
+	/** True when at least one non-forcing pending preview is registered. */
+	get hasPendingInvoker(): boolean {
+		return this.#pendingInvokers.length > 0;
+	}
+
+	/** The head (most-recently registered) pending invoker's handler, for resolve dispatch. */
+	peekPendingInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined {
+		return this.#pendingInvokers.at(-1)?.onInvoked;
+	}
+
+	/** The head pending preview's stable id + source tool, for building the agent-level
+	 *  SoftToolRequirement (the id drives reminder re-injection when the head changes). */
+	peekPendingHead(): { id: string; sourceToolName: string } | undefined {
+		const head = this.#pendingInvokers.at(-1);
+		return head ? { id: head.id, sourceToolName: head.sourceToolName } : undefined;
+	}
+
 	// ── Cleanup ───────────────────────────────────────────────────────────
 
 	/** Remove all directives with the given label. Rejects in-flight if it matches. */
@@ -206,6 +264,7 @@ export class ToolChoiceQueue {
 			this.reject("cleared");
 		}
 		this.#queue = [];
+		this.#pendingInvokers = [];
 		this.#lastResolvedLabel = undefined;
 	}
 

package/src/system-prompt.ts

@@ -373,11 +373,11 @@ export interface BuildSystemPromptOptions {
 	toolNames?: string[];
 	/** Text to append to system prompt. */
 	appendSystemPrompt?: string;
-	/** Repeat full tool descriptions in system prompt. Default: false */
-	repeatToolDescriptions?: boolean;
+	/** Inline full tool descriptors in the system prompt. Default: true */
+	inlineToolDescriptors?: boolean;
 	/**
 	 * Whether provider-native tool calling is active (no owned/in-band syntax).
-	 * When true and `repeatToolDescriptions` is false, the inventory renders as a
+	 * When true and `inlineToolDescriptors` is false, the inventory renders as a
 	 * compact tool-name list; otherwise it renders full `# Tool:` sections. Default: true
 	 */
 	nativeTools?: boolean;
@@ -433,7 +433,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		customPrompt,
 		tools,
 		appendSystemPrompt,
-		repeatToolDescriptions = false,
+		inlineToolDescriptors: providedInlineToolDescriptors,
 		nativeTools = true,
 		skillsSettings,
 		toolNames: providedToolNames,
@@ -454,6 +454,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		model,
 		personality = "default",
 	} = options;
+	const inlineToolDescriptors = providedInlineToolDescriptors ?? true;
 	const resolvedCwd = cwd ?? getProjectDir();
 
 	const prepDefaults = {
@@ -599,10 +600,10 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 			examples: meta?.examples,
 		};
 	});
-	// List mode shows a compact tool-name list; it only applies when descriptions
-	// are not repeated AND native tool calling is active (the model already has the
-	// schemas). Otherwise render full `# Tool:` sections.
-	const toolListMode = !repeatToolDescriptions && nativeTools;
+	// List mode shows a compact tool-name list; it only applies when descriptors
+	// stay in provider-native tool schemas AND native tool calling is active.
+	// Otherwise render full `# Tool:` sections inline in the system prompt.
+	const toolListMode = !inlineToolDescriptors && nativeTools;
 	const toolInventory = toolListMode ? "" : renderToolInventory(inventoryTools, model ?? "");
 
 	// Filter skills for the rendered system prompt:
@@ -632,7 +633,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		tools: toolNames,
 		toolInfo,
 		toolInventory,
-		repeatToolDescriptions,
+		inlineToolDescriptors,
 		toolListMode,
 		toolRefs,
 		environment,

package/src/tools/bash-interactive.ts

@@ -274,16 +274,16 @@ class BashInteractiveOverlayComponent implements Component {
 				: truncateToWidth(this.uiTheme.fg("dim", "session finished"), innerWidth);
 		const visibleLines = this.#readViewport(innerWidth, maxContentRows);
 		const content = visibleLines.length > 0 ? visibleLines : [padding(innerWidth)];
-		const borderHorizontal = this.uiTheme.fg("border", this.uiTheme.boxSharp.horizontal.repeat(innerWidth));
-		const borderVertical = this.uiTheme.fg("border", this.uiTheme.boxSharp.vertical);
+		const borderHorizontal = this.uiTheme.fg("border", this.uiTheme.boxRound.horizontal.repeat(innerWidth));
+		const borderVertical = this.uiTheme.fg("border", this.uiTheme.boxRound.vertical);
 		const boxLine = (line: string) =>
 			`${borderVertical}${line}${padding(Math.max(0, innerWidth - visibleWidth(line)))}${borderVertical}`;
 		return [
-			`${this.uiTheme.fg("border", this.uiTheme.boxSharp.topLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxSharp.topRight)}`,
+			`${this.uiTheme.fg("border", this.uiTheme.boxRound.topLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxRound.topRight)}`,
 			boxLine(header),
 			...content.map(boxLine),
 			boxLine(footer),
-			`${this.uiTheme.fg("border", this.uiTheme.boxSharp.bottomLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxSharp.bottomRight)}`,
+			`${this.uiTheme.fg("border", this.uiTheme.boxRound.bottomLeft)}${borderHorizontal}${this.uiTheme.fg("border", this.uiTheme.boxRound.bottomRight)}`,
 		];
 	}
 

package/src/tools/index.ts

@@ -312,6 +312,10 @@ export interface ToolSession {
 	steer?(message: { customType: string; content: string; details?: unknown }): void;
 	/** Peek the currently in-flight tool-choice queue directive's invocation handler. Used by the `resolve` tool to dispatch to the pending action. */
 	peekQueueInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+	/** Peek the most-recently registered non-forcing pending preview invoker. The `resolve`
+	 *  tool dispatches to it so a staged preview resolves WITHOUT forcing tool_choice — the
+	 *  agent-loop's SoftToolRequirement lifecycle owns reminder injection and escalation. */
+	peekPendingInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
 	/** Peek the long-lived "standing" resolve handler registered by a mode (e.g. plan mode).
 	 *  Consulted by the `resolve` tool as a fallback when no queue invoker is in flight,
 	 *  letting modes accept `resolve` invocations without forcing the tool choice every turn. */