@oh-my-pi/pi-coding-agent 13.9.2 → 13.9.4

package/src/session/agent-session.ts

@@ -24,15 +24,17 @@ import {
 	type AgentState,
 	type AgentTool,
 	INTENT_FIELD,
+	ThinkingLevel,
 } from "@oh-my-pi/pi-agent-core";
 import type {
 	AssistantMessage,
+	Effort,
 	ImageContent,
 	Message,
 	Model,
 	ProviderSessionState,
+	ServiceTier,
 	TextContent,
-	ThinkingLevel,
 	ToolCall,
 	ToolChoice,
 	Usage,
@@ -40,11 +42,10 @@ import type {
 } from "@oh-my-pi/pi-ai";
 import {
 	calculateRateLimitBackoffMs,
-	getAvailableThinkingLevels,
+	getSupportedEfforts,
 	isContextOverflow,
 	modelsAreEqual,
 	parseRateLimitReason,
-	supportsXhigh,
 } from "@oh-my-pi/pi-ai";
 import { abortableSleep, getAgentDbPath, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import type { AsyncJob, AsyncJobManager } from "../async";
@@ -87,6 +88,7 @@ import { executePython as executePythonCommand, type PythonResult } from "../ipy
 import { getCurrentThemeName, theme } from "../modes/theme/theme";
 import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../patch";
 import type { PlanModeState } from "../plan-mode/state";
+import autoHandoffThresholdFocusPrompt from "../prompts/system/auto-handoff-threshold-focus.md" with { type: "text" };
 import planModeActivePrompt from "../prompts/system/plan-mode-active.md" with { type: "text" };
 import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
 import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool-decision-reminder.md" with {
@@ -94,6 +96,7 @@ import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool
 };
 import ttsrInterruptTemplate from "../prompts/system/ttsr-interrupt.md" with { type: "text" };
 import type { SecretObfuscator } from "../secrets/obfuscator";
+import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import type { CheckpointState } from "../tools/checkpoint";
 import { outputMeta } from "../tools/output-meta";
 import { resolveToCwd } from "../tools/path-utils";
@@ -105,6 +108,7 @@ import { extractFileMentions, generateFileMentionMessages } from "../utils/file-
 import {
 	type CompactionResult,
 	calculateContextTokens,
+	calculatePromptTokens,
 	collectEntriesForBranchSummary,
 	compact,
 	estimateTokens,
@@ -130,9 +134,10 @@ import { getLatestCompactionEntry } from "./session-manager";
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent =
 	| AgentEvent
-	| { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
+	| { type: "auto_compaction_start"; reason: "threshold" | "overflow"; action: "context-full" | "handoff" }
 	| {
 			type: "auto_compaction_end";
+			action: "context-full" | "handoff";
 			result: CompactionResult | undefined;
 			aborted: boolean;
 			willRetry: boolean;
@@ -163,7 +168,9 @@ export interface AgentSessionConfig {
 	/** Async background jobs launched by tools */
 	asyncJobManager?: AsyncJobManager;
 	/** Models to cycle through with Ctrl+P (from --models flag) */
-	scopedModels?: Array<{ model: Model; thinkingLevel: ThinkingLevel }>;
+	scopedModels?: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
+	/** Initial session thinking selector. */
+	thinkingLevel?: ThinkingLevel;
 	/** Prompt templates for expansion */
 	promptTemplates?: PromptTemplate[];
 	/** File-based slash commands for expansion */
@@ -205,12 +212,14 @@ export interface PromptOptions {
 	toolChoice?: ToolChoice;
 	/** Send as developer/system message instead of user. Providers that support it use the developer role; others fall back to user. */
 	synthetic?: boolean;
+	/** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
+	skipCompactionCheck?: boolean;
 }
 
 /** Result from cycleModel() */
 export interface ModelCycleResult {
 	model: Model;
-	thinkingLevel: ThinkingLevel;
+	thinkingLevel: ThinkingLevel | undefined;
 	/** Whether cycling through scoped models (--models flag) or all available */
 	isScoped: boolean;
 }
@@ -218,7 +227,7 @@ export interface ModelCycleResult {
 /** Result from cycleRoleModels() */
 export interface RoleModelCycleResult {
 	model: Model;
-	thinkingLevel: ThinkingLevel;
+	thinkingLevel: ThinkingLevel | undefined;
 	role: ModelRole;
 }
 
@@ -245,6 +254,12 @@ export interface SessionStats {
 /** Result from handoff() */
 export interface HandoffResult {
 	document: string;
+	savedPath?: string;
+}
+
+interface HandoffOptions {
+	autoTriggered?: boolean;
+	signal?: AbortSignal;
 }
 
 /** Internal marker for hook messages queued through the agent loop */
@@ -254,6 +269,8 @@ export interface HandoffResult {
 
 /** Standard thinking levels */
 
+const AUTO_HANDOFF_THRESHOLD_FOCUS = renderPromptTemplate(autoHandoffThresholdFocusPrompt);
+
 const noOpUIContext: ExtensionUIContext = {
 	select: async (_title, _options, _dialogOptions) => undefined,
 	confirm: async (_title, _message, _dialogOptions) => false,
@@ -292,7 +309,8 @@ export class AgentSession {
 	readonly settings: Settings;
 
 	#asyncJobManager: AsyncJobManager | undefined = undefined;
-	#scopedModels: Array<{ model: Model; thinkingLevel: ThinkingLevel }>;
+	#scopedModels: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
+	#thinkingLevel: ThinkingLevel | undefined;
 	#promptTemplates: PromptTemplate[];
 	#slashCommands: FileSlashCommand[];
 
@@ -393,6 +411,7 @@ export class AgentSession {
 		this.settings = config.settings;
 		this.#asyncJobManager = config.asyncJobManager;
 		this.#scopedModels = config.scopedModels ?? [];
+		this.#thinkingLevel = config.thinkingLevel;
 		this.#promptTemplates = config.promptTemplates ?? [];
 		this.#slashCommands = config.slashCommands ?? [];
 		this.#extensionRunner = config.extensionRunner;
@@ -1395,10 +1414,15 @@ export class AgentSession {
 			};
 			await this.#extensionRunner.emit(extensionEvent);
 		} else if (event.type === "auto_compaction_start") {
-			await this.#extensionRunner.emit({ type: "auto_compaction_start", reason: event.reason });
+			await this.#extensionRunner.emit({
+				type: "auto_compaction_start",
+				reason: event.reason,
+				action: event.action,
+			});
 		} else if (event.type === "auto_compaction_end") {
 			await this.#extensionRunner.emit({
 				type: "auto_compaction_end",
+				action: event.action,
 				result: event.result,
 				aborted: event.aborted,
 				willRetry: event.willRetry,
@@ -1526,8 +1550,12 @@ export class AgentSession {
 	}
 
 	/** Current thinking level */
-	get thinkingLevel(): ThinkingLevel {
-		return this.agent.state.thinkingLevel;
+	get thinkingLevel(): ThinkingLevel | undefined {
+		return this.#thinkingLevel;
+	}
+
+	get serviceTier(): ServiceTier | undefined {
+		return this.agent.serviceTier;
 	}
 
 	/** Whether agent is currently streaming a response */
@@ -1702,7 +1730,7 @@ export class AgentSession {
 	}
 
 	/** Scoped models for cycling (from --models flag) */
-	get scopedModels(): ReadonlyArray<{ model: Model; thinkingLevel: ThinkingLevel }> {
+	get scopedModels(): ReadonlyArray<{ model: Model; thinkingLevel?: ThinkingLevel }> {
 		return this.#scopedModels;
 	}
 
@@ -1967,7 +1995,9 @@ export class AgentSession {
 	async #promptWithMessage(
 		message: AgentMessage,
 		expandedText: string,
-		options?: Pick<PromptOptions, "toolChoice" | "images"> & { skipPostPromptRecoveryWait?: boolean },
+		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck"> & {
+			skipPostPromptRecoveryWait?: boolean;
+		},
 	): Promise<void> {
 		this.#promptInFlight = true;
 		const generation = this.#promptGeneration;
@@ -1999,7 +2029,7 @@ export class AgentSession {
 
 			// Check if we need to compact before sending (catches aborted responses)
 			const lastAssistant = this.#findLastAssistantMessage();
-			if (lastAssistant) {
+			if (lastAssistant && !options?.skipCompactionCheck) {
 				await this.#checkCompaction(lastAssistant, false);
 			}
 
@@ -2520,6 +2550,7 @@ export class AgentSession {
 		this.#pendingNextTurnMessages = [];
 
 		this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
+		this.sessionManager.appendServiceTierChange(this.serviceTier ?? null);
 
 		this.#todoReminderCount = 0;
 		this.#planReferenceSent = false;
@@ -2629,7 +2660,7 @@ export class AgentSession {
 		this.settings.setModelRole(role, this.#formatRoleModelValue(role, model));
 		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
 
-		// Re-clamp thinking level for new model's capabilities without persisting settings
+		// Re-apply the current thinking level for the newly selected model
 		this.setThinkingLevel(this.thinkingLevel);
 	}
 
@@ -2648,7 +2679,7 @@ export class AgentSession {
 		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, "temporary");
 		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
 
-		// Re-clamp thinking level for new model's capabilities without persisting settings
+		// Re-apply the current thinking level for the newly selected model
 		this.setThinkingLevel(this.thinkingLevel);
 	}
 
@@ -2733,9 +2764,9 @@ export class AgentSession {
 		return { model: next.model, thinkingLevel: this.thinkingLevel, role: next.role };
 	}
 
-	async #getScopedModelsWithApiKey(): Promise<Array<{ model: Model; thinkingLevel: ThinkingLevel }>> {
+	async #getScopedModelsWithApiKey(): Promise<Array<{ model: Model; thinkingLevel?: ThinkingLevel }>> {
 		const apiKeysByProvider = new Map<string, string | undefined>();
-		const result: Array<{ model: Model; thinkingLevel: ThinkingLevel }> = [];
+		const result: Array<{ model: Model; thinkingLevel?: ThinkingLevel }> = [];
 
 		for (const scoped of this.#scopedModels) {
 			const provider = scoped.model.provider;
@@ -2773,7 +2804,7 @@ export class AgentSession {
 		this.settings.setModelRole("default", this.#formatRoleModelValue("default", next.model));
 		this.settings.getStorage()?.recordModelUsage(`${next.model.provider}/${next.model.id}`);
 
-		// Apply thinking level (setThinkingLevel clamps to model capabilities)
+		// Apply the scoped model's configured thinking level
 		this.setThinkingLevel(next.thinkingLevel);
 
 		return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
@@ -2801,7 +2832,7 @@ export class AgentSession {
 		this.settings.setModelRole("default", this.#formatRoleModelValue("default", nextModel));
 		this.settings.getStorage()?.recordModelUsage(`${nextModel.provider}/${nextModel.id}`);
 
-		// Re-clamp thinking level for new model's capabilities without persisting settings
+		// Re-apply the current thinking level for the newly selected model
 		this.setThinkingLevel(this.thinkingLevel);
 
 		return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
@@ -2820,21 +2851,18 @@ export class AgentSession {
 
 	/**
 	 * Set thinking level.
-	 * Clamps to model capabilities based on available thinking levels.
-	 * Saves to session and settings only if the level actually changes.
+	 * Saves the effective metadata-clamped level to session and settings only if it changes.
 	 */
-	setThinkingLevel(level: ThinkingLevel, persist: boolean = false): void {
-		const availableLevels = this.getAvailableThinkingLevels();
-		const effectiveLevel = availableLevels.includes(level) ? level : this.#clampThinkingLevel(level, availableLevels);
-
-		// Only persist if actually changing
-		const isChanging = effectiveLevel !== this.agent.state.thinkingLevel;
+	setThinkingLevel(level: ThinkingLevel | undefined, persist: boolean = false): void {
+		const effectiveLevel = resolveThinkingLevelForModel(this.model, level);
+		const isChanging = effectiveLevel !== this.#thinkingLevel;
 
-		this.agent.setThinkingLevel(effectiveLevel);
+		this.#thinkingLevel = effectiveLevel;
+		this.agent.setThinkingLevel(toReasoningEffort(effectiveLevel));
 
 		if (isChanging) {
 			this.sessionManager.appendThinkingLevelChange(effectiveLevel);
-			if (persist) {
+			if (persist && effectiveLevel !== undefined && effectiveLevel !== ThinkingLevel.Off) {
 				this.settings.set("defaultThinkingLevel", effectiveLevel);
 			}
 		}
@@ -2844,57 +2872,48 @@ export class AgentSession {
 	 * Cycle to next thinking level.
 	 * @returns New level, or undefined if model doesn't support thinking
 	 */
-	cycleThinkingLevel(): ThinkingLevel | undefined {
-		if (!this.supportsThinking()) return undefined;
+	cycleThinkingLevel(): Effort | undefined {
+		if (!this.model?.reasoning) return undefined;
 
 		const levels = this.getAvailableThinkingLevels();
-		const currentIndex = levels.indexOf(this.thinkingLevel);
+		const currentIndex =
+			this.thinkingLevel && this.thinkingLevel !== ThinkingLevel.Off && this.thinkingLevel !== ThinkingLevel.Inherit
+				? levels.indexOf(this.thinkingLevel)
+				: -1;
 		const nextIndex = (currentIndex + 1) % levels.length;
 		const nextLevel = levels[nextIndex];
+		if (!nextLevel) return undefined;
 
 		this.setThinkingLevel(nextLevel);
 		return nextLevel;
 	}
 
-	/**
-	 * Get available thinking levels for current model.
-	 * The provider will clamp to what the specific model supports internally.
-	 */
-	getAvailableThinkingLevels(): ReadonlyArray<ThinkingLevel> {
-		if (!this.supportsThinking()) return ["off"];
-		return getAvailableThinkingLevels(this.supportsXhighThinking());
+	isFastModeEnabled(): boolean {
+		return this.serviceTier === "priority";
 	}
 
-	/**
-	 * Check if current model supports xhigh thinking level.
-	 */
-	supportsXhighThinking(): boolean {
-		return this.model ? supportsXhigh(this.model) : false;
+	setServiceTier(serviceTier: ServiceTier | undefined): void {
+		if (this.serviceTier === serviceTier) return;
+		this.agent.serviceTier = serviceTier;
+		this.sessionManager.appendServiceTierChange(serviceTier ?? null);
 	}
 
-	/**
-	 * Check if current model supports thinking/reasoning.
-	 */
-	supportsThinking(): boolean {
-		return !!this.model?.reasoning;
+	setFastMode(enabled: boolean): void {
+		this.setServiceTier(enabled ? "priority" : undefined);
 	}
 
-	#clampThinkingLevel(level: ThinkingLevel, availableLevels: ReadonlyArray<ThinkingLevel>): ThinkingLevel {
-		const ordered = getAvailableThinkingLevels(true);
-		const available = new Set(availableLevels);
-		const requestedIndex = ordered.indexOf(level);
-		if (requestedIndex === -1) {
-			return availableLevels[0] ?? "off";
-		}
-		for (let i = requestedIndex; i < ordered.length; i++) {
-			const candidate = ordered[i];
-			if (available.has(candidate)) return candidate;
-		}
-		for (let i = requestedIndex - 1; i >= 0; i--) {
-			const candidate = ordered[i];
-			if (available.has(candidate)) return candidate;
-		}
-		return availableLevels[0] ?? "off";
+	toggleFastMode(): boolean {
+		const enabled = !this.isFastModeEnabled();
+		this.setFastMode(enabled);
+		return enabled;
+	}
+
+	/**
+	 * Get available thinking levels for current model.
+	 */
+	getAvailableThinkingLevels(): ReadonlyArray<Effort> {
+		if (!this.model) return [];
+		return getSupportedEfforts(this.model);
 	}
 
 	// =========================================================================
@@ -3042,13 +3061,14 @@ export class AgentSession {
 					apiKey,
 					customInstructions,
 					this.#compactionAbortController.signal,
-					{ promptOverride: hookPrompt, extraContext: hookContext },
+					{ promptOverride: hookPrompt, extraContext: hookContext, remoteInstructions: this.#baseSystemPrompt },
 				);
 				summary = result.summary;
 				shortSummary = result.shortSummary;
 				firstKeptEntryId = result.firstKeptEntryId;
 				tokensBefore = result.tokensBefore;
 				details = result.details;
+				preserveData = { ...(preserveData ?? {}), ...(result.preserveData ?? {}) };
 			}
 
 			if (this.#compactionAbortController.signal.aborted) {
@@ -3104,11 +3124,12 @@ export class AgentSession {
 	}
 
 	/**
-	 * Cancel in-progress compaction (manual or auto).
+	 * Cancel in-progress context maintenance (manual compaction, auto-compaction, or auto-handoff).
 	 */
 	abortCompaction(): void {
 		this.#compactionAbortController?.abort();
 		this.#autoCompactionAbortController?.abort();
+		this.#handoffAbortController?.abort();
 	}
 
 	/**
@@ -3139,9 +3160,10 @@ export class AgentSession {
 	 * waits for completion, then starts a fresh session with the handoff as context.
 	 *
 	 * @param customInstructions Optional focus for the handoff document
+	 * @param options Handoff execution options
 	 * @returns The handoff document text, or undefined if cancelled/failed
 	 */
-	async handoff(customInstructions?: string): Promise<HandoffResult | undefined> {
+	async handoff(customInstructions?: string, options?: HandoffOptions): Promise<HandoffResult | undefined> {
 		const entries = this.sessionManager.getBranch();
 		const messageCount = entries.filter(e => e.type === "message").length;
 
@@ -3152,6 +3174,24 @@ export class AgentSession {
 		this.#skipPostTurnMaintenanceAssistantTimestamp = undefined;
 
 		this.#handoffAbortController = new AbortController();
+		const handoffAbortController = this.#handoffAbortController;
+		const handoffSignal = handoffAbortController.signal;
+		const sourceSignal = options?.signal;
+		const onHandoffAbort = () => {
+			this.agent.abort();
+		};
+		handoffSignal.addEventListener("abort", onHandoffAbort, { once: true });
+		const onSourceAbort = () => {
+			if (!handoffSignal.aborted) {
+				handoffAbortController.abort();
+			}
+		};
+		if (sourceSignal) {
+			sourceSignal.addEventListener("abort", onSourceAbort, { once: true });
+			if (sourceSignal.aborted) {
+				onSourceAbort();
+			}
+		}
 
 		// Build the handoff prompt
 		let handoffPrompt = `Write a comprehensive handoff document that will allow another instance of yourself to seamlessly continue this work. The document should capture everything needed to resume without access to this conversation.
@@ -3192,42 +3232,58 @@ Be thorough - include exact file paths, function names, error messages, and tech
 
 		// Create a promise that resolves when the agent completes
 		let handoffText: string | undefined;
-		const completionPromise = new Promise<void>((resolve, reject) => {
-			const unsubscribe = this.subscribe(event => {
-				if (this.#handoffAbortController?.signal.aborted) {
-					unsubscribe();
-					reject(new Error("Handoff cancelled"));
-					return;
-				}
-
-				if (event.type === "agent_end") {
-					unsubscribe();
-					// Extract text from the last assistant message
-					const messages = this.agent.state.messages;
-					for (let i = messages.length - 1; i >= 0; i--) {
-						const msg = messages[i];
-						if (msg.role === "assistant") {
-							const content = (msg as AssistantMessage).content;
-							const textParts = content
-								.filter((c): c is { type: "text"; text: string } => c.type === "text")
-								.map(c => c.text);
-							if (textParts.length > 0) {
-								handoffText = textParts.join("\n");
-								break;
-							}
+		const { promise: completionPromise, resolve: resolveCompletion } = Promise.withResolvers<void>();
+		let handoffCancelled = false;
+		let unsubscribe: (() => void) | undefined;
+		const onCompletionAbort = () => {
+			unsubscribe?.();
+			handoffCancelled = true;
+			resolveCompletion();
+		};
+		if (handoffSignal.aborted) {
+			onCompletionAbort();
+		} else {
+			handoffSignal.addEventListener("abort", onCompletionAbort, { once: true });
+		}
+		unsubscribe = this.subscribe(event => {
+			if (event.type === "agent_end") {
+				unsubscribe?.();
+				handoffSignal.removeEventListener("abort", onCompletionAbort);
+				// Extract text from the last assistant message
+				const messages = this.agent.state.messages;
+				for (let i = messages.length - 1; i >= 0; i--) {
+					const msg = messages[i];
+					if (msg.role === "assistant") {
+						const content = (msg as AssistantMessage).content;
+						const textParts = content
+							.filter((c): c is { type: "text"; text: string } => c.type === "text")
+							.map(c => c.text);
+						if (textParts.length > 0) {
+							handoffText = textParts.join("\n");
+							break;
 						}
 					}
-					resolve();
 				}
-			});
+				resolveCompletion();
+			}
 		});
 
 		try {
 			// Send the prompt and wait for completion
-			await this.prompt(handoffPrompt, { expandPromptTemplates: false, synthetic: true });
+			if (handoffSignal.aborted) {
+				throw new Error("Handoff cancelled");
+			}
+			await this.prompt(handoffPrompt, {
+				expandPromptTemplates: false,
+				synthetic: true,
+				skipCompactionCheck: true,
+			});
 			await completionPromise;
 
-			if (!handoffText || this.#handoffAbortController.signal.aborted) {
+			if (handoffCancelled || handoffSignal.aborted) {
+				throw new Error("Handoff cancelled");
+			}
+			if (!handoffText) {
 				return undefined;
 			}
 
@@ -3245,26 +3301,49 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			// Inject the handoff document as a custom message
 			const handoffContent = `<handoff-context>\n${handoffText}\n</handoff-context>\n\nThe above is a handoff document from a previous session. Use this context to continue the work seamlessly.`;
 			this.sessionManager.appendCustomMessageEntry("handoff", handoffContent, true, undefined, "agent");
+			let savedPath: string | undefined;
+			if (options?.autoTriggered && this.settings.get("compaction.handoffSaveToDisk")) {
+				const artifactsDir = this.sessionManager.getArtifactsDir();
+				if (artifactsDir) {
+					const fileTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+					const handoffFilePath = path.join(artifactsDir, `handoff-${fileTimestamp}.md`);
+					try {
+						await Bun.write(handoffFilePath, `${handoffText}\n`);
+						savedPath = handoffFilePath;
+					} catch (error) {
+						logger.warn("Failed to save handoff document to disk", {
+							path: handoffFilePath,
+							error: error instanceof Error ? error.message : String(error),
+						});
+					}
+				} else {
+					logger.debug("Skipping handoff document save because session is not persisted");
+				}
+			}
 
 			// Rebuild agent messages from session
 			const sessionContext = this.sessionManager.buildSessionContext();
 			this.agent.replaceMessages(sessionContext.messages);
 			this.#syncTodoPhasesFromBranch();
 
-			return { document: handoffText };
+			return { document: handoffText, savedPath };
 		} finally {
+			unsubscribe?.();
+			handoffSignal.removeEventListener("abort", onCompletionAbort);
+			handoffSignal.removeEventListener("abort", onHandoffAbort);
+			sourceSignal?.removeEventListener("abort", onSourceAbort);
 			this.#handoffAbortController = undefined;
 		}
 	}
 
 	/**
-	 * Check if compaction or context promotion is needed and run it.
+	 * Check if context maintenance or promotion is needed and run it.
 	 * Called after agent_end and before prompt submission.
 	 *
 	 * Three cases (in order):
-	 * 1. Overflow + promotion: promote to larger model, retry without compacting
-	 * 2. Overflow + no promotion target: compact, auto-retry on same model
-	 * 3. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
+	 * 1. Overflow + promotion: promote to larger model, retry without maintenance
+	 * 2. Overflow + no promotion target: run context maintenance, auto-retry on same model
+	 * 3. Threshold: Context over threshold, run context maintenance (no auto-retry)
 	 *
 	 * @param assistantMessage The assistant message to check
 	 * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
@@ -3305,13 +3384,13 @@ Be thorough - include exact file paths, function names, error messages, and tech
 
 			// No promotion target available fall through to compaction
 			const compactionSettings = this.settings.getGroup("compaction");
-			if (compactionSettings.enabled) {
+			if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
 				await this.#runAutoCompaction("overflow", true);
 			}
 			return;
 		}
 		const compactionSettings = this.settings.getGroup("compaction");
-		if (!compactionSettings.enabled) return;
+		if (!compactionSettings.enabled || compactionSettings.strategy === "off") return;
 
 		// Case 2: Threshold - turn succeeded but context is getting large
 		// Skip if this was an error (non-overflow errors don't have usage data)
@@ -3654,8 +3733,11 @@ Be thorough - include exact file paths, function names, error messages, and tech
 	async #runAutoCompaction(reason: "overflow" | "threshold", willRetry: boolean): Promise<void> {
 		const compactionSettings = this.settings.getGroup("compaction");
 
+		if (!compactionSettings.enabled || compactionSettings.strategy === "off") return;
 		const generation = this.#promptGeneration;
-		await this.#emitSessionEvent({ type: "auto_compaction_start", reason });
+		let action: "context-full" | "handoff" =
+			compactionSettings.strategy === "handoff" && reason !== "overflow" ? "handoff" : "context-full";
+		await this.#emitSessionEvent({ type: "auto_compaction_start", reason, action });
 		// Properly abort and null existing controller before replacing
 		if (this.#autoCompactionAbortController) {
 			this.#autoCompactionAbortController.abort();
@@ -3663,9 +3745,45 @@ Be thorough - include exact file paths, function names, error messages, and tech
 		this.#autoCompactionAbortController = new AbortController();
 
 		try {
+			if (compactionSettings.strategy === "handoff" && reason !== "overflow") {
+				const handoffFocus = AUTO_HANDOFF_THRESHOLD_FOCUS;
+				const handoffResult = await this.handoff(handoffFocus, {
+					autoTriggered: true,
+					signal: this.#autoCompactionAbortController.signal,
+				});
+				if (!handoffResult) {
+					const aborted = this.#autoCompactionAbortController.signal.aborted;
+					if (aborted) {
+						await this.#emitSessionEvent({
+							type: "auto_compaction_end",
+							action,
+							result: undefined,
+							aborted: true,
+							willRetry: false,
+						});
+						return;
+					}
+					logger.warn("Auto-handoff returned no document; falling back to context-full maintenance", {
+						reason,
+					});
+					action = "context-full";
+				}
+				if (handoffResult) {
+					await this.#emitSessionEvent({
+						type: "auto_compaction_end",
+						action,
+						result: undefined,
+						aborted: false,
+						willRetry: false,
+					});
+					return;
+				}
+			}
+
 			if (!this.model) {
 				await this.#emitSessionEvent({
 					type: "auto_compaction_end",
+					action,
 					result: undefined,
 					aborted: false,
 					willRetry: false,
@@ -3677,6 +3795,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			if (availableModels.length === 0) {
 				await this.#emitSessionEvent({
 					type: "auto_compaction_end",
+					action,
 					result: undefined,
 					aborted: false,
 					willRetry: false,
@@ -3690,10 +3809,18 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			if (!preparation) {
 				await this.#emitSessionEvent({
 					type: "auto_compaction_end",
+					action,
 					result: undefined,
 					aborted: false,
 					willRetry: false,
 				});
+				if (!willRetry && this.agent.hasQueuedMessages()) {
+					this.#scheduleAgentContinue({
+						delayMs: 100,
+						generation,
+						shouldContinue: () => this.agent.hasQueuedMessages(),
+					});
+				}
 				return;
 			}
 
@@ -3715,6 +3842,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 				if (hookResult?.cancel) {
 					await this.#emitSessionEvent({
 						type: "auto_compaction_end",
+						action,
 						result: undefined,
 						aborted: true,
 						willRetry: false,
@@ -3774,7 +3902,11 @@ Be thorough - include exact file paths, function names, error messages, and tech
 								apiKey,
 								undefined,
 								this.#autoCompactionAbortController.signal,
-								{ promptOverride: hookPrompt, extraContext: hookContext },
+								{
+									promptOverride: hookPrompt,
+									extraContext: hookContext,
+									remoteInstructions: this.#baseSystemPrompt,
+								},
 							);
 							break;
 						} catch (error) {
@@ -3843,11 +3975,13 @@ Be thorough - include exact file paths, function names, error messages, and tech
 				firstKeptEntryId = compactResult.firstKeptEntryId;
 				tokensBefore = compactResult.tokensBefore;
 				details = compactResult.details;
+				preserveData = { ...(preserveData ?? {}), ...(compactResult.preserveData ?? {}) };
 			}
 
 			if (this.#autoCompactionAbortController.signal.aborted) {
 				await this.#emitSessionEvent({
 					type: "auto_compaction_end",
+					action,
 					result: undefined,
 					aborted: true,
 					willRetry: false,
@@ -3891,7 +4025,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 				details,
 				preserveData,
 			};
-			await this.#emitSessionEvent({ type: "auto_compaction_end", result, aborted: false, willRetry });
+			await this.#emitSessionEvent({ type: "auto_compaction_end", action, result, aborted: false, willRetry });
 
 			if (!willRetry && compactionSettings.autoContinue !== false) {
 				await this.#promptWithMessage(
@@ -3927,6 +4061,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			if (this.#autoCompactionAbortController?.signal.aborted) {
 				await this.#emitSessionEvent({
 					type: "auto_compaction_end",
+					action,
 					result: undefined,
 					aborted: true,
 					willRetry: false,
@@ -3936,6 +4071,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			const errorMessage = error instanceof Error ? error.message : "compaction failed";
 			await this.#emitSessionEvent({
 				type: "auto_compaction_end",
+				action,
 				result: undefined,
 				aborted: false,
 				willRetry: false,
@@ -3954,11 +4090,14 @@ Be thorough - include exact file paths, function names, error messages, and tech
 	 */
 	setAutoCompactionEnabled(enabled: boolean): void {
 		this.settings.set("compaction.enabled", enabled);
+		if (enabled && this.settings.get("compaction.strategy") === "off") {
+			this.settings.set("compaction.strategy", "context-full");
+		}
 	}
 
 	/** Whether auto-compaction is enabled */
 	get autoCompactionEnabled(): boolean {
-		return this.settings.get("compaction.enabled");
+		return this.settings.get("compaction.enabled") && this.settings.get("compaction.strategy") !== "off";
 	}
 
 	// =========================================================================
@@ -4488,18 +4627,22 @@ Be thorough - include exact file paths, function names, error messages, and tech
 		}
 
 		const hasThinkingEntry = this.sessionManager.getBranch().some(entry => entry.type === "thinking_level_change");
-		const defaultThinkingLevel = (this.settings.get("defaultThinkingLevel") ?? "off") as ThinkingLevel;
+		const hasServiceTierEntry = this.sessionManager.getBranch().some(entry => entry.type === "service_tier_change");
+		const defaultThinkingLevel = this.settings.get("defaultThinkingLevel");
 
 		if (hasThinkingEntry) {
-			// Restore thinking level if saved (setThinkingLevel clamps to model capabilities)
-			this.setThinkingLevel(sessionContext.thinkingLevel as ThinkingLevel);
+			this.setThinkingLevel(sessionContext.thinkingLevel as ThinkingLevel | undefined);
 		} else {
-			const availableLevels = this.getAvailableThinkingLevels();
-			const effectiveLevel = availableLevels.includes(defaultThinkingLevel)
-				? defaultThinkingLevel
-				: this.#clampThinkingLevel(defaultThinkingLevel, availableLevels);
-			this.agent.setThinkingLevel(effectiveLevel);
-			this.sessionManager.appendThinkingLevelChange(effectiveLevel);
+			const effectiveDefaultThinkingLevel = resolveThinkingLevelForModel(this.model, defaultThinkingLevel);
+			this.#thinkingLevel = effectiveDefaultThinkingLevel;
+			this.agent.setThinkingLevel(toReasoningEffort(effectiveDefaultThinkingLevel));
+			this.sessionManager.appendThinkingLevelChange(effectiveDefaultThinkingLevel);
+		}
+
+		if (hasServiceTierEntry) {
+			this.agent.serviceTier = sessionContext.serviceTier;
+		} else {
+			this.sessionManager.appendServiceTierChange(this.serviceTier ?? null);
 		}
 
 		this.#reconnectToAgent();
@@ -4934,7 +5077,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 			};
 		}
 
-		const usageTokens = calculateContextTokens(lastUsage);
+		const usageTokens = calculatePromptTokens(lastUsage);
 		let trailingTokens = 0;
 		for (let i = lastUsageIndex + 1; i < messages.length; i++) {
 			trailingTokens += estimateTokens(messages[i]);
@@ -5016,7 +5159,7 @@ Be thorough - include exact file paths, function names, error messages, and tech
 
 		// Include model and thinking level
 		const model = this.agent.state.model;
-		const thinkingLevel = this.agent.state.thinkingLevel;
+		const thinkingLevel = this.#thinkingLevel;
 		lines.push("## Configuration\n");
 		lines.push(`Model: ${model.provider}/${model.id}`);
 		lines.push(`Thinking Level: ${thinkingLevel}`);