@oh-my-pi/pi-coding-agent 16.3.14 → 16.4.0

package/src/session/session-context.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import * as snapcompact from "@oh-my-pi/snapcompact";
+import type { CompactionSummaryMessage } from "./messages";
+import { buildSessionContext } from "./session-context";
+import type { SessionEntry } from "./session-entries";
+
+const timestamp = "2026-07-09T00:00:00.000Z";
+
+const compactedEntries = [
+	{
+		type: "message",
+		id: "m1",
+		parentId: null,
+		timestamp,
+		message: { role: "user", content: [{ type: "text", text: "before compaction" }], timestamp: 1 },
+	},
+	{
+		type: "compaction",
+		id: "c1",
+		parentId: "m1",
+		timestamp,
+		summary: "summary",
+		firstKeptEntryId: "m1",
+		tokensBefore: 123,
+		preserveData: {
+			[snapcompact.PRESERVE_KEY]: {
+				frames: [{ data: "base64-frame", mimeType: "image/png", cols: 10, rows: 10, chars: 100 }],
+				totalChars: 100,
+				truncatedChars: 0,
+				textHead: "head",
+				textTail: "tail",
+			},
+		},
+	},
+	{
+		type: "message",
+		id: "m2",
+		parentId: "c1",
+		timestamp,
+		message: { role: "user", content: [{ type: "text", text: "after compaction" }], timestamp: 2 },
+	},
+] satisfies SessionEntry[];
+
+function compactionSummary(messages: AgentMessage[]): CompactionSummaryMessage {
+	const summary = messages.find(
+		(message): message is CompactionSummaryMessage => message.role === "compactionSummary",
+	);
+	if (!summary) throw new Error("Expected a compaction summary message");
+	return summary;
+}
+
+describe("buildSessionContext snapcompact archives", () => {
+	it("omits snapcompact archive blocks from collapsed transcript summaries", () => {
+		const context = buildSessionContext(compactedEntries, undefined, undefined, {
+			transcript: true,
+			collapseCompactedHistory: true,
+		});
+
+		const summary = compactionSummary(context.messages);
+
+		expect(summary.images).toBeUndefined();
+		expect(summary.blocks).toBeUndefined();
+	});
+
+	it("keeps snapcompact archive blocks in full transcript summaries", () => {
+		const context = buildSessionContext(compactedEntries, undefined, undefined, { transcript: true });
+
+		const summary = compactionSummary(context.messages);
+
+		expect(summary.images?.map(image => image.data)).toEqual(["base64-frame"]);
+		expect(summary.blocks?.map(block => block.type)).toEqual(["text", "image", "text"]);
+	});
+
+	it("keeps snapcompact archive blocks in provider context summaries", () => {
+		const context = buildSessionContext(compactedEntries);
+
+		const summary = compactionSummary(context.messages);
+
+		expect(summary.images?.map(image => image.data)).toEqual(["base64-frame"]);
+		expect(summary.blocks?.map(block => block.type)).toEqual(["text", "image", "text"]);
+	});
+});

package/src/session/session-context.ts

@@ -132,6 +132,7 @@ function snapcompactHistoryBlocksForContext(
 	options: BuildSessionContextOptions | undefined,
 ) {
 	if (!archive) return undefined;
+	if (options?.transcript && options.collapseCompactedHistory) return undefined;
 	return snapcompact.historyBlocks(archive, snapcompactHistoryBlockOptions(archive, options));
 }
 

package/src/session/session-entries.ts

@@ -32,10 +32,14 @@ export interface SessionHeader {
 	timestamp: string;
 	cwd: string;
 	parentSession?: string;
+	/** Provider prompt-cache identity inherited by exact-route full forks. */
+	providerPromptCacheKey?: string;
 }
 
 export interface NewSessionOptions {
 	parentSession?: string;
+	/** Provider prompt-cache identity to seed on the new session header. */
+	providerPromptCacheKey?: string;
 	/** Skip flushing the current session and delete it instead of saving. */
 	drop?: boolean;
 }

package/src/session/session-manager.ts

@@ -783,6 +783,7 @@ export class SessionManager {
 			timestamp,
 			cwd: this.#cwd,
 			parentSession: options?.parentSession,
+			providerPromptCacheKey: options?.providerPromptCacheKey,
 		};
 		this.#titleUpdatedAt = timestamp;
 
@@ -1050,6 +1051,7 @@ export class SessionManager {
 			timestamp,
 			cwd: this.#cwd,
 			parentSession: parentSessionId,
+			providerPromptCacheKey: this.#header.providerPromptCacheKey ?? parentSessionId,
 		};
 		this.#sessionName = this.#header.title;
 		this.#titleSource = this.#header.titleSource;
@@ -1888,7 +1890,13 @@ export class SessionManager {
 
 		const sourceHeader = sourceEntries.find(entry => entry.type === "session") as SessionHeader | undefined;
 		const history = sourceEntries.filter(entry => entry.type !== "session") as SessionEntry[];
-		manager.#resetToNewSession({ parentSession: sourceHeader?.id }, options?.sessionFile);
+		manager.#resetToNewSession(
+			{
+				parentSession: sourceHeader?.id,
+				providerPromptCacheKey: sourceHeader?.providerPromptCacheKey ?? sourceHeader?.id,
+			},
+			options?.sessionFile,
+		);
 		manager.#header.title = sourceHeader?.title;
 		manager.#header.titleSource = sourceHeader?.titleSource;
 		manager.#sessionName = manager.#header.title;

package/src/system-prompt.test.ts

@@ -123,29 +123,36 @@ describe.skipIf(process.platform !== "linux")("system prompt GPU probe", () => {
 	}, 15_000);
 
 	it("kills the GPU probe at the prep deadline", async () => {
-		const result = await runProbeScenario({ runs: 1, sleepSeconds: 7, holdStdoutOpen: true });
+		const result = await runProbeScenario({ runs: 1, sleepSeconds: 12, holdStdoutOpen: true });
 
 		expect(result.cached).toEqual({ gpu: null });
+		// Probe is SIGKILLed at ~4.5s and the drain wait is bounded, so in-child
+		// time sits near the deadline; waiting on the descendant would push it
+		// past the 12s sleep.
 		expect(result.elapsedMs).toBeLessThan(6500);
-		// Codex#3838: the child process MUST exit shortly after the deadline,
-		// not linger until a descendant holding stdout (sleep 7) exits on its own.
-		expect(result.childElapsedMs).toBeLessThan(6500);
-	}, 15_000);
+		// Codex#3838: the child process MUST exit shortly after the deadline, not
+		// linger until a descendant holding stdout (sleep 12) exits on its own.
+		// The bound over in-child time budgets bun spawn/startup on loaded runners
+		// while staying far below the descendant's 12s exit.
+		expect(result.childElapsedMs).toBeLessThan(9000);
+	}, 20_000);
 
 	it("does not wait on stdout held by a descendant after a successful probe", async () => {
-		const result = await runProbeScenario({ runs: 1, sleepSeconds: 3, descendantHoldsStdout: true });
+		const result = await runProbeScenario({ runs: 1, sleepSeconds: 8, descendantHoldsStdout: true });
 
 		expect(result.cached).toEqual({ gpu: null });
 		// Probe exits 0 immediately but leaves a backgrounded sleep holding the stdout
 		// pipe. The success path MUST bound the drain wait, not block until sleep exits.
 		expect(result.elapsedMs).toBeLessThan(2000);
-		expect(result.childElapsedMs).toBeLessThan(2000);
-	}, 15_000);
+		// Budgets bun spawn/startup overhead; blocking on the descendant would
+		// take at least the 8s sleep.
+		expect(result.childElapsedMs).toBeLessThan(5000);
+	}, 20_000);
 
 	it("keeps probe output captured before a descendant delays EOF", async () => {
 		const result = await runProbeScenario({
 			runs: 1,
-			sleepSeconds: 3,
+			sleepSeconds: 8,
 			descendantHoldsStdout: true,
 			validOutput: "00:02.0 VGA compatible controller: NVIDIA TestGPU",
 		});
@@ -154,8 +161,10 @@ describe.skipIf(process.platform !== "linux")("system prompt GPU probe", () => {
 		// Captured stdout MUST be cached, not discarded as if the probe failed.
 		expect(result.cached).toEqual({ gpu: "02.0 VGA compatible controller: NVIDIA TestGPU" });
 		expect(result.elapsedMs).toBeLessThan(2000);
-		expect(result.childElapsedMs).toBeLessThan(2000);
-	}, 15_000);
+		// Budgets bun spawn/startup overhead; blocking on the descendant would
+		// take at least the 8s sleep.
+		expect(result.childElapsedMs).toBeLessThan(5000);
+	}, 20_000);
 });
 
 describe.skipIf(process.platform !== "linux")("system prompt CPU model", () => {

package/src/task/agents.ts

@@ -7,15 +7,13 @@ import { Effort } from "@oh-my-pi/pi-ai";
 import { parseFrontmatter, prompt } from "@oh-my-pi/pi-utils";
 import { parseAgentFields } from "../discovery/helpers";
 import designerMd from "../prompts/agents/designer.md" with { type: "text" };
-import exploreMd from "../prompts/agents/explore.md" with { type: "text" };
 // Embed agent markdown files at build time
 import agentFrontmatterTemplate from "../prompts/agents/frontmatter.md" with { type: "text" };
 import librarianMd from "../prompts/agents/librarian.md" with { type: "text" };
-
 import planMd from "../prompts/agents/plan.md" with { type: "text" };
 import reviewerMd from "../prompts/agents/reviewer.md" with { type: "text" };
+import scoutMd from "../prompts/agents/scout.md" with { type: "text" };
 import taskMd from "../prompts/agents/task.md" with { type: "text" };
-import testerMd from "../prompts/agents/tester.md" with { type: "text" };
 
 import type { AgentDefinition, AgentSource } from "./types";
 
@@ -42,12 +40,11 @@ function buildAgentContent(def: EmbeddedAgentDef): string {
 }
 
 const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
-	{ fileName: "explore.md", template: exploreMd },
+	{ fileName: "scout.md", template: scoutMd },
 	{ fileName: "plan.md", template: planMd },
 	{ fileName: "designer.md", template: designerMd },
 	{ fileName: "reviewer.md", template: reviewerMd },
 	{ fileName: "librarian.md", template: librarianMd },
-	{ fileName: "tester.md", template: testerMd },
 	{
 		fileName: "task.md",
 		frontmatter: {

package/src/task/executor.ts

@@ -88,7 +88,7 @@ const MCP_CALL_TIMEOUT_MS = 60_000;
  * `task.softRequestBudgetNotice`.
  */
 export const SOFT_REQUEST_BUDGET: Record<string, number> = {
-	explore: 40,
+	scout: 40,
 	sonic: 40,
 	default: 90,
 };
@@ -254,14 +254,18 @@ function withAbortTimeout<T>(
 	return wrappedPromise;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	if (!value || typeof value !== "object") return false;
+	return !Array.isArray(value);
+}
+
 function getReportFindingKey(value: unknown): string | null {
-	if (!value || typeof value !== "object") return null;
-	const record = value as Record<string, unknown>;
-	const title = typeof record.title === "string" ? record.title : null;
-	const filePath = typeof record.file_path === "string" ? record.file_path : null;
-	const lineStart = typeof record.line_start === "number" ? record.line_start : null;
-	const lineEnd = typeof record.line_end === "number" ? record.line_end : null;
-	const priority = typeof record.priority === "string" ? record.priority : null;
+	if (!isRecord(value)) return null;
+	const title = typeof value.title === "string" ? value.title : null;
+	const filePath = typeof value.file_path === "string" ? value.file_path : null;
+	const lineStart = typeof value.line_start === "number" ? value.line_start : null;
+	const lineEnd = typeof value.line_end === "number" ? value.line_end : null;
+	const priority = typeof value.priority === "string" ? value.priority : null;
 	if (!title || !filePath || lineStart === null || lineEnd === null) {
 		return null;
 	}
@@ -908,6 +912,7 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 	const abortSignal = abortController.signal;
 	let activeSession: AgentSession | null = null;
 	let yieldCalled = false;
+	let yieldCallPending = false;
 
 	// Accumulate usage incrementally from message_end events (no memory for streaming events)
 	const accumulatedUsage: Usage = {
@@ -1062,17 +1067,17 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 	};
 
 	const getMessageContent = (message: unknown): unknown => {
-		if (message && typeof message === "object" && "content" in message) {
-			return (message as { content?: unknown }).content;
+		if (!isRecord(message) || !("content" in message)) {
+			return undefined;
 		}
-		return undefined;
+		return message.content;
 	};
 
 	const getMessageUsage = (message: unknown): unknown => {
-		if (message && typeof message === "object" && "usage" in message) {
-			return (message as { usage?: unknown }).usage;
+		if (!isRecord(message) || !("usage" in message)) {
+			return undefined;
 		}
-		return undefined;
+		return message.usage;
 	};
 
 	const updateRecentOutputLines = () => {
@@ -1136,6 +1141,27 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 		});
 	};
 
+	const recordExtractedToolData = (toolName: string, data: unknown): void => {
+		progress.extractedToolData = progress.extractedToolData || {};
+		const existing = progress.extractedToolData[toolName] || [];
+		const findingKey = toolName === "report_finding" ? getReportFindingKey(data) : null;
+		if (findingKey) {
+			const existingIndex = existing.findIndex(item => getReportFindingKey(item) === findingKey);
+			if (existingIndex >= 0) {
+				existing[existingIndex] = data;
+			} else {
+				existing.push(data);
+			}
+		} else {
+			existing.push(data);
+		}
+		progress.extractedToolData[toolName] = existing;
+		if (toolName === "yield") {
+			yieldCalled = true;
+			yieldCallPending = false;
+		}
+	};
+
 	const processEvent = (event: AgentEvent) => {
 		if (resolved) return;
 		const now = Date.now();
@@ -1151,14 +1177,21 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 			case "tool_execution_start": {
 				progress.toolCount++;
 				progress.currentTool = event.toolName;
-				progress.currentToolArgs = extractToolArgsPreview(
-					(event as { toolArgs?: Record<string, unknown> }).toolArgs || event.args || {},
-				);
+				let startArgs: Record<string, unknown> = {};
+				if ("toolArgs" in event && isRecord(event.toolArgs)) {
+					startArgs = event.toolArgs;
+				} else if (isRecord(event.args)) {
+					startArgs = event.args;
+				}
+				progress.currentToolArgs = extractToolArgsPreview(startArgs);
 				progress.currentToolStartMs = now;
 				const intent = event.intent?.trim();
 				if (intent) {
 					progress.lastIntent = intent;
 				}
+				if (event.toolName === "yield" && !yieldCalled) {
+					yieldCallPending = true;
+				}
 				// Reset any prior in-flight task snapshot so we don't show stale
 				// nested progress when the agent enters a fresh `task` call.
 				if (event.toolName === "task") {
@@ -1191,7 +1224,8 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 
 				// Check for registered subagent tool handler
 				const handler = subprocessToolRegistry.getHandler(event.toolName);
-				const eventArgs = (event as { args?: Record<string, unknown> }).args ?? {};
+				const eventRecord: unknown = event;
+				const eventArgs = isRecord(eventRecord) && isRecord(eventRecord.args) ? eventRecord.args : {};
 				if (handler) {
 					// Extract data using handler
 					if (handler.extractData) {
@@ -1203,26 +1237,14 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 							isError: event.isError,
 						});
 						if (data !== undefined) {
-							progress.extractedToolData = progress.extractedToolData || {};
-							const existing = progress.extractedToolData[event.toolName] || [];
-							const findingKey = event.toolName === "report_finding" ? getReportFindingKey(data) : null;
-							if (findingKey) {
-								const existingIndex = existing.findIndex(item => getReportFindingKey(item) === findingKey);
-								if (existingIndex >= 0) {
-									existing[existingIndex] = data;
-								} else {
-									existing.push(data);
-								}
-							} else {
-								existing.push(data);
-							}
-							progress.extractedToolData[event.toolName] = existing;
-							if (event.toolName === "yield") {
-								yieldCalled = true;
-							}
+							recordExtractedToolData(event.toolName, data);
 						}
 					}
 
+					if (event.toolName === "yield") {
+						yieldCallPending = false;
+					}
+
 					// Check if handler wants to terminate the session
 					if (
 						handler.shouldTerminate?.({
@@ -1284,7 +1306,23 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 				const role = event.message?.role;
 				if (role === "assistant") {
 					progress.requests += 1;
-					if (softRequestBudget > 0 && !abortSent) {
+					const eventContent = isRecord(event) && "content" in event ? event.content : undefined;
+					const messageContent = getMessageContent(event.message) || eventContent;
+					if (messageContent && Array.isArray(messageContent)) {
+						for (const block of messageContent) {
+							if (!isRecord(block)) continue;
+							if (block.type === "text" && typeof block.text === "string") {
+								outputChunks.push(block.text);
+								continue;
+							}
+							if (block.type !== "toolCall" || typeof block.name !== "string") continue;
+							if (block.name === "yield" && !yieldCalled) {
+								yieldCallPending = true;
+								flushProgress = true;
+							}
+						}
+					}
+					if (softRequestBudget > 0 && !abortSent && !yieldCallPending) {
 						if (progress.requests >= softRequestBudget * 1.5) {
 							requestAbort("budget");
 						} else if (softRequestBudgetNotice && !budgetSteerSent && progress.requests >= softRequestBudget) {
@@ -1302,32 +1340,21 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 						}
 					}
 				}
-				if (role === "assistant") {
-					const messageContent =
-						getMessageContent(event.message) || (event as AgentEvent & { content?: unknown }).content;
-					if (messageContent && Array.isArray(messageContent)) {
-						for (const block of messageContent) {
-							if (block.type === "text" && block.text) {
-								outputChunks.push(block.text);
-							}
-						}
-					}
-				}
 				// Extract and accumulate usage (prefer message.usage, fallback to event.usage)
-				const messageUsage = getMessageUsage(event.message) || (event as AgentEvent & { usage?: unknown }).usage;
-				if (messageUsage && typeof messageUsage === "object") {
+				const eventUsage = isRecord(event) && "usage" in event ? event.usage : undefined;
+				const messageUsage = getMessageUsage(event.message) || eventUsage;
+				if (isRecord(messageUsage)) {
 					// Only count assistant messages (not tool results, etc.)
 					if (role === "assistant") {
-						const usageRecord = messageUsage as Record<string, unknown>;
-						const costRecord = (messageUsage as { cost?: Record<string, unknown> }).cost;
+						const costRecord = isRecord(messageUsage.cost) ? messageUsage.cost : undefined;
 						hasUsage = true;
-						accumulatedUsage.input += getNumberField(usageRecord, "input") ?? 0;
-						accumulatedUsage.output += getNumberField(usageRecord, "output") ?? 0;
-						accumulatedUsage.cacheRead += getNumberField(usageRecord, "cacheRead") ?? 0;
-						accumulatedUsage.cacheWrite += getNumberField(usageRecord, "cacheWrite") ?? 0;
-						accumulatedUsage.totalTokens += getNumberField(usageRecord, "totalTokens") ?? 0;
+						accumulatedUsage.input += getNumberField(messageUsage, "input") ?? 0;
+						accumulatedUsage.output += getNumberField(messageUsage, "output") ?? 0;
+						accumulatedUsage.cacheRead += getNumberField(messageUsage, "cacheRead") ?? 0;
+						accumulatedUsage.cacheWrite += getNumberField(messageUsage, "cacheWrite") ?? 0;
+						accumulatedUsage.totalTokens += getNumberField(messageUsage, "totalTokens") ?? 0;
 						accumulatedUsage.reasoningTokens =
-							(accumulatedUsage.reasoningTokens ?? 0) + (getNumberField(usageRecord, "reasoningTokens") ?? 0);
+							(accumulatedUsage.reasoningTokens ?? 0) + (getNumberField(messageUsage, "reasoningTokens") ?? 0);
 						if (costRecord) {
 							accumulatedUsage.cost.input += getNumberField(costRecord, "input") ?? 0;
 							accumulatedUsage.cost.output += getNumberField(costRecord, "output") ?? 0;
@@ -1342,7 +1369,7 @@ function createSubagentRunMonitor(args: RunMonitorArgs): SubagentRunMonitor {
 					// Track latest per-turn context size so the UI can show
 					// "current context", not just cumulative billing volume.
 					if (role === "assistant") {
-						const perTurnTotal = getNumberField(messageUsage as Record<string, unknown>, "totalTokens");
+						const perTurnTotal = getNumberField(messageUsage, "totalTokens");
 						if (perTurnTotal !== undefined && perTurnTotal > 0) {
 							progress.contextTokens = perTurnTotal;
 						}
@@ -1587,35 +1614,45 @@ async function driveSessionToYield(
 			}
 		}
 
-		await awaitAbortable(session.waitForIdle());
+		if (monitor.yieldCalled()) {
+			await session.waitForIdle();
+		} else {
+			await awaitAbortable(session.waitForIdle());
+		}
 
 		const lastAssistant = session.getLastAssistantMessage();
 		if (lastAssistant) {
 			if (lastAssistant.stopReason === "aborted") {
-				aborted = monitor.isAbortedRun();
-				if (aborted) {
-					// A real caller signal or the wall-clock timer carries a precise
-					// reason (signal.reason / "runtime limit exceeded"). An internal
-					// turn abort does NOT — prefer the assistant message's own
-					// errorMessage ("Request was aborted" or a specific stream error)
-					// over the misleading "Cancelled by caller".
-					abortReasonText ??= monitor.hasExplicitAbortReason()
-						? monitor.resolveAbortReasonText()
-						: lastAssistant.errorMessage?.trim() || monitor.resolveAbortReasonText();
+				if (!monitor.yieldCalled() || monitor.runtimeLimitExceeded()) {
+					aborted = monitor.isAbortedRun();
+					if (aborted) {
+						// A real caller signal or the wall-clock timer carries a precise
+						// reason (signal.reason / "runtime limit exceeded"). An internal
+						// turn abort does NOT — prefer the assistant message's own
+						// errorMessage ("Request was aborted" or a specific stream error)
+						// over the misleading "Cancelled by caller".
+						abortReasonText ??= monitor.hasExplicitAbortReason()
+							? monitor.resolveAbortReasonText()
+							: lastAssistant.errorMessage?.trim() || monitor.resolveAbortReasonText();
+					}
+					exitCode = 1;
 				}
-				exitCode = 1;
 			} else if (lastAssistant.stopReason === "error") {
 				exitCode = 1;
 				error ??= lastAssistant.errorMessage || "Subagent failed";
 			}
 		}
 	} catch (err) {
-		exitCode = 1;
-		if (!abortSignal.aborted) {
-			error = err instanceof Error ? err.stack || err.message : String(err);
+		if (abortSignal.aborted && monitor.yieldCalled() && !monitor.runtimeLimitExceeded()) {
+			exitCode = 0;
+		} else {
+			exitCode = 1;
+			if (!abortSignal.aborted) {
+				error = err instanceof Error ? err.stack || err.message : String(err);
+			}
 		}
 	} finally {
-		if (abortSignal.aborted) {
+		if (abortSignal.aborted && (!monitor.yieldCalled() || monitor.runtimeLimitExceeded())) {
 			aborted = monitor.isAbortedRun();
 			if (aborted) {
 				abortReasonText ??= monitor.resolveAbortReasonText();

package/src/thinking.ts

@@ -33,7 +33,12 @@ const THINKING_LEVEL_METADATA: Record<ThinkingLevel, ThinkingLevelMetadata> = {
 	[ThinkingLevel.XHigh]: {
 		value: ThinkingLevel.XHigh,
 		label: "xhigh",
-		description: "Maximum reasoning (~32k tokens)",
+		description: "Extended reasoning (~32k tokens)",
+	},
+	[ThinkingLevel.Max]: {
+		value: ThinkingLevel.Max,
+		label: "max",
+		description: "Maximum reasoning the model supports",
 	},
 };
 
@@ -43,7 +48,7 @@ const EFFORT_BY_SELECTOR: Readonly<Record<string, Effort>> = {
 	[Effort.Medium]: Effort.Medium,
 	[Effort.High]: Effort.High,
 	[Effort.XHigh]: Effort.XHigh,
-	max: Effort.XHigh,
+	[Effort.Max]: Effort.Max,
 };
 const THINKING_LEVEL_BY_SELECTOR: Readonly<Record<string, ThinkingLevel>> = {
 	[ThinkingLevel.Inherit]: ThinkingLevel.Inherit,
@@ -53,6 +58,7 @@ const THINKING_LEVEL_BY_SELECTOR: Readonly<Record<string, ThinkingLevel>> = {
 	[ThinkingLevel.Medium]: ThinkingLevel.Medium,
 	[ThinkingLevel.High]: ThinkingLevel.High,
 	[ThinkingLevel.XHigh]: ThinkingLevel.XHigh,
+	[ThinkingLevel.Max]: ThinkingLevel.Max,
 };
 
 function getOwnSelector<T>(selectors: Readonly<Record<string, T>>, value: string | null | undefined): T | undefined {
@@ -149,7 +155,6 @@ const AUTO_THINKING_METADATA: ConfiguredThinkingLevelMetadata = {
  */
 export function parseConfiguredThinkingLevel(value: string | null | undefined): ConfiguredThinkingLevel | undefined {
 	if (value === AUTO_THINKING) return AUTO_THINKING;
-	if (value === "max") return ThinkingLevel.XHigh;
 	return parseThinkingLevel(value);
 }
 
@@ -160,7 +165,7 @@ export function getConfiguredThinkingLevelMetadata(level: ConfiguredThinkingLeve
 
 /**
  * Thinking selectors accepted by the `--thinking` CLI flag, in display order:
- * `off`, every concrete effort (`minimal`..`xhigh`), then `auto`. Single source
+ * `off`, every concrete effort (`minimal`..`max`), then `auto`. Single source
  * for the flag's `options` list, shell completions, and the "invalid level"
  * warning so all three stay in sync.
  */
@@ -168,7 +173,7 @@ export const CLI_THINKING_LEVELS: readonly string[] = [ThinkingLevel.Off, ...THI
 
 /**
  * Parses a `--thinking` CLI value. Accepts every {@link parseConfiguredThinkingLevel}
- * selector (`off`, `auto`, `minimal`..`xhigh`, plus the `max` alias) but rejects
+ * selector (`off`, `auto`, `minimal`..`max`) but rejects
  * `inherit`: an explicit `inherit` on the command line would suppress the
  * settings/scoped-model fallback during startup resolution only to resolve back
  * to the provider default, which is never what the user means.
@@ -211,9 +216,13 @@ export function clampAutoThinkingEffort(model: Model | undefined, effort: Effort
 /**
  * The provisional concrete level shown while `auto` is configured but before a
  * turn has been classified. Prefers the model's `defaultLevel`, otherwise High,
- * clamped into the auto range. Returns `undefined` for non-reasoning models.
+ * clamped into the auto range. Auto never provisions {@link Effort.Max} (the
+ * classifier ceiling is XHigh; only an explicit user request reaches Max), so a
+ * `defaultLevel` of `max` is capped at XHigh before clamping. Returns
+ * `undefined` for non-reasoning models.
  */
 export function resolveProvisionalAutoLevel(model: Model | undefined): Effort | undefined {
 	if (!model?.reasoning) return undefined;
-	return clampAutoThinkingEffort(model, model.thinking?.defaultLevel ?? Effort.High);
+	const preferred = model.thinking?.defaultLevel ?? Effort.High;
+	return clampAutoThinkingEffort(model, preferred === Effort.Max ? Effort.XHigh : preferred);
 }