@oh-my-pi/pi-coding-agent 15.0.0 → 15.0.2

package/src/session/agent-session.ts

@@ -16,7 +16,7 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-
+import { scheduler } from "node:timers/promises";
 import {
 	type Agent,
 	AgentBusyError,
@@ -47,14 +47,20 @@ import {
 	calculateRateLimitBackoffMs,
 	getSupportedEfforts,
 	isContextOverflow,
-	isUnexpectedSocketCloseMessage,
 	isUsageLimitError,
 	modelsAreEqual,
 	parseRateLimitReason,
 	streamSimple,
 } from "@oh-my-pi/pi-ai";
 import { MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
-import { abortableSleep, getAgentDbPath, isEnoent, logger, prompt, Snowflake } from "@oh-my-pi/pi-utils";
+import {
+	getAgentDbPath,
+	isEnoent,
+	isUnexpectedSocketCloseMessage,
+	logger,
+	prompt,
+	Snowflake,
+} from "@oh-my-pi/pi-utils";
 import { type AsyncJob, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
 import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
@@ -104,6 +110,8 @@ import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
+import { GoalRuntime } from "../goals/runtime";
+import type { Goal, GoalModeState } from "../goals/state";
 import type { HindsightSessionState } from "../hindsight/state";
 import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import {
@@ -174,6 +182,8 @@ import {
 	convertToLlm,
 	type FileMentionMessage,
 	type PythonExecutionMessage,
+	readPendingDisplayTag,
+	SILENT_ABORT_MARKER,
 } from "./messages";
 import { formatSessionDumpText } from "./session-dump-format";
 import type {
@@ -208,7 +218,9 @@ export type AgentSessionEvent =
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
 	| { type: "todo_auto_clear" }
 	| { type: "irc_message"; message: CustomMessage }
-	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string };
+	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string }
+	| { type: "thinking_level_changed"; thinkingLevel: ThinkingLevel | undefined }
+	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
@@ -594,6 +606,13 @@ function extractPermissionLocations(args: unknown, cwd: string): { path: string;
 // AgentSession Class
 // ============================================================================
 
+/** Internal record stored in the steering/followUp display queues. The optional
+ *  `tag` is set only by `enqueueCustomMessageDisplay` (used for skill-prompt
+ *  custom messages queued during streaming) and is matched by the custom-role
+ *  `message_start` dequeue branch; user-message pushes leave it undefined and
+ *  rely on the existing text-equality match. */
+type QueuedDisplayEntry = { text: string; tag?: string };
+
 export class AgentSession {
 	readonly agent: Agent;
 	readonly sessionManager: SessionManager;
@@ -612,14 +631,22 @@ export class AgentSession {
 	#unsubscribeAgent?: () => void;
 	#eventListeners: AgentSessionEventListener[] = [];
 
-	/** Tracks pending steering messages for UI display. Removed when delivered. */
-	#steeringMessages: string[] = [];
-	/** Tracks pending follow-up messages for UI display. Removed when delivered. */
-	#followUpMessages: string[] = [];
+	/** Tracks pending steering messages for UI display. Removed when delivered.
+	 *  Entry shape: `{ text }` for plain-text steers (user-message dequeue
+	 *  matches by `.text`); `{ text, tag }` for queued custom messages (skill
+	 *  invocations dispatched while streaming) — the custom-role dequeue
+	 *  matches by `.tag` so duplicate-args queued skills cannot collide. */
+	#steeringMessages: QueuedDisplayEntry[] = [];
+	/** Tracks pending follow-up messages for UI display. Removed when delivered.
+	 *  See `#steeringMessages` for entry shape. */
+	#followUpMessages: QueuedDisplayEntry[] = [];
 	/** Messages queued to be included with the next user prompt as context ("asides"). */
 	#pendingNextTurnMessages: CustomMessage[] = [];
 	#scheduledHiddenNextTurnGeneration: number | undefined = undefined;
 	#planModeState: PlanModeState | undefined;
+	#goalModeState: GoalModeState | undefined;
+	#goalRuntime: GoalRuntime;
+	#goalTurnCounter = 0;
 	#planReferenceSent = false;
 	#planReferencePath = "local://PLAN.md";
 	#clientBridge: ClientBridge | undefined;
@@ -729,6 +756,19 @@ export class AgentSession {
 	#ttsrRetryToken = 0;
 	#ttsrResumePromise: Promise<void> | undefined = undefined;
 	#ttsrResumeResolve: (() => void) | undefined = undefined;
+
+	/** One-shot flag set in InteractiveMode.#approvePlan(compactBeforeExecute=true)
+	 *  before the plan-mode → compaction transition. Consumed inside
+	 *  #handleAgentEvent for the matching `message_end` + `stopReason: "aborted"`;
+	 *  cleared unconditionally by the caller's `finally` so it cannot leak into
+	 *  later unrelated aborts (e.g. when compaction returns cancelled/failed
+	 *  without producing an aborted message_end). */
+	#planCompactAbortPending = false;
+
+	/** Monotonic counter for `enqueueCustomMessageDisplay` tag generation;
+	 *  combined with `Date.now()` so tags stay unique even across rapid
+	 *  same-tick enqueues. */
+	#customDisplayTagCounter = 0;
 	#postPromptTasks = new Set<Promise<void>>();
 	#postPromptTasksPromise: Promise<void> | undefined = undefined;
 	#postPromptTasksResolve: (() => void) | undefined = undefined;
@@ -878,6 +918,44 @@ export class AgentSession {
 		this.agent.providerSessionState = this.#providerSessionState;
 		this.#syncAgentSessionId();
 		this.#syncTodoPhasesFromBranch();
+		this.#goalRuntime = new GoalRuntime({
+			getState: () => this.#goalModeState,
+			setState: state => {
+				this.#goalModeState = state;
+			},
+			getCurrentUsage: () => {
+				const usage = this.getSessionStats().tokens;
+				return {
+					input: usage.input,
+					output: usage.output,
+					cacheRead: usage.cacheRead,
+					cacheWrite: usage.cacheWrite,
+				};
+			},
+			emit: event => {
+				if (event.type === "goal_updated") {
+					return this.#emitSessionEvent({ type: "goal_updated", goal: event.goal, state: event.state });
+				}
+			},
+			persist: (mode, state) => {
+				if (mode === "none") {
+					this.sessionManager.appendModeChange("none");
+				} else if (state) {
+					this.sessionManager.appendModeChange(mode, { goal: state.goal });
+				}
+			},
+			sendHiddenMessage: async message => {
+				await this.sendCustomMessage(
+					{
+						customType: message.customType,
+						content: message.content,
+						display: false,
+						attribution: "agent",
+					},
+					{ deliverAs: message.deliverAs },
+				);
+			},
+		});
 
 		// Always subscribe to agent events for internal handling
 		// (session persistence, hooks, auto-compaction, retry logic)
@@ -925,6 +1003,19 @@ export class AgentSession {
 		return this.#toolChoiceQueue.peekInFlightInvoker();
 	}
 
+	/** Standing (long-lived) handler the `resolve` tool falls back to when no
+	 *  queue invoker is in flight. Used by plan mode so the agent can submit
+	 *  approval via `resolve` without forcing the tool choice every turn. */
+	#standingResolveHandler: ((input: unknown) => Promise<unknown> | unknown) | undefined;
+
+	peekStandingResolveHandler(): ((input: unknown) => Promise<unknown> | unknown) | undefined {
+		return this.#standingResolveHandler;
+	}
+
+	setStandingResolveHandler(handler: ((input: unknown) => Promise<unknown> | unknown) | null): void {
+		this.#standingResolveHandler = handler ?? undefined;
+	}
+
 	/** Provider-scoped mutable state store for transport/session caches. */
 	get providerSessionState(): Map<string, ProviderSessionState> {
 		return this.#providerSessionState;
@@ -950,6 +1041,49 @@ export class AgentSession {
 		return this.#ttsrAbortPending;
 	}
 
+	/** Whether the plan-mode → compaction transition's expected internal abort is
+	 *  pending. Consumed by `#handleAgentEvent` to stamp `SILENT_ABORT_MARKER`
+	 *  on the next aborted assistant message_end; cleared unconditionally by
+	 *  `InteractiveMode.#approvePlan`'s `finally` block. */
+	get isPlanCompactAbortPending(): boolean {
+		return this.#planCompactAbortPending;
+	}
+
+	/** Arm the silent-abort marker for the next aborted assistant message_end.
+	 *  Caller MUST clear via `clearPlanCompactAbortPending()` in a `finally`
+	 *  to guarantee no leak. */
+	markPlanCompactAbortPending(): void {
+		this.#planCompactAbortPending = true;
+	}
+
+	/** Unconditionally clear the silent-abort flag. Idempotent: safe when the
+	 *  flag was never set OR was already consumed by `#handleAgentEvent`. */
+	clearPlanCompactAbortPending(): void {
+		this.#planCompactAbortPending = false;
+	}
+
+	/** Register a compact display string for a custom message that the caller is
+	 *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
+	 *  Returns a stable tag the caller MUST embed in
+	 *  `CustomMessage.details.__pendingDisplayTag` so the agent-side
+	 *  `message_start` handler can remove the matching display entry when the
+	 *  queued message is consumed.
+	 *
+	 *  Does NOT push to the agent's steering/followUp queue — that happens
+	 *  separately inside `sendCustomMessage`. */
+	enqueueCustomMessageDisplay(text: string, mode: "steer" | "followUp"): string {
+		const tag = `omp-cmd-${Date.now()}-${++this.#customDisplayTagCounter}`;
+		const displayText = text.trim();
+		if (!displayText) return tag;
+		const entry: QueuedDisplayEntry = { text: displayText, tag };
+		if (mode === "steer") {
+			this.#steeringMessages.push(entry);
+		} else {
+			this.#followUpMessages.push(entry);
+		}
+		return tag;
+	}
+
 	getAsyncJobSnapshot(options?: { recentLimit?: number }): AsyncJobSnapshot | null {
 		const manager = AsyncJobManager.instance();
 		if (!manager) return null;
@@ -1038,13 +1172,13 @@ export class AgentSession {
 		if (event.type === "message_start" && event.message.role === "user") {
 			const messageText = this.#getUserMessageText(event.message);
 			if (messageText) {
-				// Check steering queue first
-				const steeringIndex = this.#steeringMessages.indexOf(messageText);
+				// Check steering queue first (match by .text on tagged records)
+				const steeringIndex = this.#steeringMessages.findIndex(e => e.text === messageText);
 				if (steeringIndex !== -1) {
 					this.#steeringMessages.splice(steeringIndex, 1);
 				} else {
 					// Check follow-up queue
-					const followUpIndex = this.#followUpMessages.indexOf(messageText);
+					const followUpIndex = this.#followUpMessages.findIndex(e => e.text === messageText);
 					if (followUpIndex !== -1) {
 						this.#followUpMessages.splice(followUpIndex, 1);
 					}
@@ -1052,6 +1186,48 @@ export class AgentSession {
 			}
 		}
 
+		// Tag-based dequeue for custom messages (skills queued via promptCustomMessage).
+		// The InputController attached a stable tag via CustomMessage.details when it
+		// registered the display chip; pull it back here to remove the matching entry
+		// from the pending bar atomically with the agent's queue consumption. Match by
+		// tag (not text) — two queued skills with identical args cannot collide.
+		if (event.type === "message_start" && event.message.role === "custom") {
+			const tag = readPendingDisplayTag(event.message.details);
+			if (tag) {
+				const steerIdx = this.#steeringMessages.findIndex(e => e.tag === tag);
+				if (steerIdx !== -1) {
+					this.#steeringMessages.splice(steerIdx, 1);
+				} else {
+					const followUpIdx = this.#followUpMessages.findIndex(e => e.tag === tag);
+					if (followUpIdx !== -1) {
+						this.#followUpMessages.splice(followUpIdx, 1);
+					}
+				}
+			}
+		}
+
+		// Plan-mode → compaction transition: stamp `SILENT_ABORT_MARKER` on the
+		// persisted message BEFORE the obfuscator's display-side copy below.
+		// Invariant (must hold across refactors): this branch precedes the
+		// `let displayEvent = event; ... displayEvent = { ...event, message: { ...message, content: deobfuscated } }`
+		// block. After stamping, both `displayEvent.message` (via the spread)
+		// and `event.message` (in-place mutation, used by SessionManager
+		// persistence) carry the marker, guaranteeing streaming render and
+		// history replay branch identically. The one-shot flag is consumed
+		// here, scoped strictly to this aborted message_end; the caller's
+		// `finally` (in `InteractiveMode.#approvePlan`) clears it again on
+		// every terminal compaction outcome (`ok` / `cancelled` / `failed` /
+		// throw) so a leaked flag cannot silence a later unrelated abort.
+		if (
+			event.type === "message_end" &&
+			event.message.role === "assistant" &&
+			event.message.stopReason === "aborted" &&
+			this.#planCompactAbortPending
+		) {
+			(event.message as AssistantMessage).errorMessage = SILENT_ABORT_MARKER;
+			this.#planCompactAbortPending = false;
+		}
+
 		// Deobfuscate assistant message content for display emission — the LLM echoes back
 		// obfuscated placeholders, but listeners (TUI, extensions, exporters) must see real
 		// values. The original event.message stays obfuscated so the persistence path below
@@ -1067,6 +1243,16 @@ export class AgentSession {
 			}
 		}
 
+		if (event.type === "turn_start") {
+			const usage = this.getSessionStats().tokens;
+			this.#goalRuntime.onTurnStart(`turn-${++this.#goalTurnCounter}`, {
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+			});
+		}
+
 		await this.#emitSessionEvent(displayEvent);
 
 		if (event.type === "turn_start") {
@@ -1090,6 +1276,13 @@ export class AgentSession {
 				this.#toolChoiceQueue.resolve();
 			}
 		}
+		if (event.type === "tool_execution_end") {
+			if (event.toolName === "goal") {
+				await this.#goalRuntime.onGoalToolCompleted();
+			} else {
+				await this.#goalRuntime.onToolCompleted(event.toolName);
+			}
+		}
 		if (event.type === "tool_execution_end" && event.toolName === "yield" && !event.isError) {
 			this.#lastSuccessfulYieldToolCallId = event.toolCallId;
 		}
@@ -1325,6 +1518,15 @@ export class AgentSession {
 
 		// Check auto-retry and auto-compaction after agent completes
 		if (event.type === "agent_end") {
+			const usage = this.getSessionStats().tokens;
+			await this.#goalRuntime.onAgentEnd({
+				currentUsage: {
+					input: usage.input,
+					output: usage.output,
+					cacheRead: usage.cacheRead,
+					cacheWrite: usage.cacheWrite,
+				},
+			});
 			const fallbackAssistant = [...event.messages]
 				.reverse()
 				.find((message): message is AssistantMessage => message.role === "assistant");
@@ -1446,7 +1648,7 @@ export class AgentSession {
 		const scheduled = (async () => {
 			if (delayMs > 0) {
 				try {
-					await abortableSleep(delayMs, signal);
+					await scheduler.wait(delayMs, { signal });
 				} catch {
 					return;
 				}
@@ -1480,7 +1682,10 @@ export class AgentSession {
 				try {
 					await this.#maybeRestoreRetryFallbackPrimary();
 					await this.agent.continue();
-				} catch {
+				} catch (error) {
+					logger.warn("agent.continue failed after scheduling", {
+						error: error instanceof Error ? error.message : String(error),
+					});
 					options?.onError?.();
 				}
 			},
@@ -2180,6 +2385,12 @@ export class AgentSession {
 				attempt: event.attempt,
 				maxAttempts: event.maxAttempts,
 			});
+		} else if (event.type === "goal_updated") {
+			await this.#extensionRunner.emit({
+				type: "goal_updated",
+				goal: event.goal,
+				state: event.state,
+			});
 		}
 	}
 
@@ -2572,7 +2783,7 @@ export class AgentSession {
 
 	/** Collect built-in tools the model can discover via search_tool_bm25. Restricted to tool
 	 *  definitions whose `loadMode === "discoverable"`. This keeps hidden/internal tools
-	 *  (resolve, yield, exit_plan_mode, report_finding, report_tool_issue) out of the index
+	 *  (resolve, yield, report_finding, report_tool_issue) out of the index
 	 *  and avoids mislabeling extension/custom default-inactive tools as built-ins. */
 	#collectDiscoverableBuiltinTools(): DiscoverableTool[] {
 		const activeNames = new Set(this.getActiveToolNames());
@@ -3140,6 +3351,18 @@ export class AgentSession {
 		}
 	}
 
+	getGoalModeState(): GoalModeState | undefined {
+		return this.#goalModeState;
+	}
+
+	setGoalModeState(state: GoalModeState | undefined): void {
+		this.#goalModeState = state;
+	}
+
+	get goalRuntime(): GoalRuntime {
+		return this.#goalRuntime;
+	}
+
 	markPlanReferenceSent(): void {
 		this.#planReferenceSent = true;
 	}
@@ -3191,6 +3414,21 @@ export class AgentSession {
 		);
 	}
 
+	async sendGoalModeContext(options?: { deliverAs?: "steer" | "followUp" | "nextTurn" }): Promise<void> {
+		const message = this.#buildGoalModeMessage();
+		if (!message) return;
+		await this.sendCustomMessage(
+			{
+				customType: message.customType,
+				content: message.content,
+				display: message.display,
+				details: message.details,
+				attribution: message.attribution,
+			},
+			options ? { deliverAs: options.deliverAs } : undefined,
+		);
+	}
+
 	resolveRoleModel(role: string): Model | undefined {
 		return this.#resolveRoleModelFull(role, this.#modelRegistry.getAvailable(), this.model).model;
 	}
@@ -3286,7 +3524,6 @@ export class AgentSession {
 			askToolName: "ask",
 			writeToolName: "write",
 			editToolName: "edit",
-			exitToolName: "exit_plan_mode",
 			reentry: state.reentry ?? false,
 			iterative: state.workflow === "iterative",
 		});
@@ -3301,6 +3538,19 @@ export class AgentSession {
 		};
 	}
 
+	#buildGoalModeMessage(): CustomMessage | null {
+		const content = this.#goalRuntime.buildActivePrompt();
+		if (!content) return null;
+		return {
+			role: "custom",
+			customType: "goal-mode-context",
+			content,
+			display: false,
+			attribution: "agent",
+			timestamp: Date.now(),
+		};
+	}
+
 	/**
 	 * Send a prompt to the agent.
 	 * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
@@ -3476,6 +3726,10 @@ export class AgentSession {
 			if (planModeMessage) {
 				messages.push(planModeMessage);
 			}
+			const goalModeMessage = this.#buildGoalModeMessage();
+			if (goalModeMessage) {
+				messages.push(goalModeMessage);
+			}
 			if (options?.prependMessages) {
 				messages.push(...options.prependMessages);
 			}
@@ -3719,7 +3973,7 @@ export class AgentSession {
 	 */
 	async #queueSteer(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#steeringMessages.push(displayText);
+		this.#steeringMessages.push({ text: displayText });
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -3737,7 +3991,7 @@ export class AgentSession {
 	 */
 	async #queueFollowUp(text: string, images?: ImageContent[]): Promise<void> {
 		const displayText = text || (images && images.length > 0 ? "[Image]" : "");
-		this.#followUpMessages.push(displayText);
+		this.#followUpMessages.push({ text: displayText });
 		const content: (TextContent | ImageContent)[] = [{ type: "text", text }];
 		if (images && images.length > 0) {
 			content.push(...images);
@@ -3973,8 +4227,8 @@ export class AgentSession {
 	 * Useful for restoring to editor when user aborts.
 	 */
 	clearQueue(): { steering: string[]; followUp: string[] } {
-		const steering = [...this.#steeringMessages];
-		const followUp = [...this.#followUpMessages];
+		const steering = this.#steeringMessages.map(e => e.text);
+		const followUp = this.#followUpMessages.map(e => e.text);
 		this.#steeringMessages = [];
 		this.#followUpMessages = [];
 		this.agent.clearAllQueues();
@@ -3986,27 +4240,35 @@ export class AgentSession {
 		return this.#steeringMessages.length + this.#followUpMessages.length + this.#pendingNextTurnMessages.length;
 	}
 
-	/** Get pending messages (read-only) */
+	/** Get pending messages (read-only). Returns the public text-only view;
+	 *  internal `{text, tag?}` records are mapped to `.text` so callers
+	 *  (`updatePendingMessagesDisplay`, `restoreQueuedMessagesToEditor`) see
+	 *  the unchanged historical shape. */
 	getQueuedMessages(): { steering: readonly string[]; followUp: readonly string[] } {
-		return { steering: this.#steeringMessages, followUp: this.#followUpMessages };
+		return {
+			steering: this.#steeringMessages.map(e => e.text),
+			followUp: this.#followUpMessages.map(e => e.text),
+		};
 	}
 
 	/**
 	 * Pop the last queued message (steering first, then follow-up).
 	 * Used by dequeue keybinding to restore messages to editor one at a time.
+	 * Returns the popped entry's `.text`; the tag (if any) dies with the
+	 * record — no orphan state can outlive the queue entry.
 	 */
 	popLastQueuedMessage(): string | undefined {
 		// Pop from steering first (LIFO)
 		if (this.#steeringMessages.length > 0) {
-			const message = this.#steeringMessages.pop();
+			const entry = this.#steeringMessages.pop();
 			this.agent.popLastSteer();
-			return message;
+			return entry?.text;
 		}
 		// Then from follow-up
 		if (this.#followUpMessages.length > 0) {
-			const message = this.#followUpMessages.pop();
+			const entry = this.#followUpMessages.pop();
 			this.agent.popLastFollowUp();
-			return message;
+			return entry?.text;
 		}
 		return undefined;
 	}
@@ -4120,7 +4382,7 @@ export class AgentSession {
 	/**
 	 * Abort current operation and wait for agent to become idle.
 	 */
-	async abort(): Promise<void> {
+	async abort(options?: { goalReason?: "interrupted" | "internal" }): Promise<void> {
 		this.abortRetry();
 		this.#promptGeneration++;
 		this.#scheduledHiddenNextTurnGeneration = undefined;
@@ -4132,6 +4394,7 @@ export class AgentSession {
 		this.agent.abort();
 		await postPromptDrain;
 		await this.agent.waitForIdle();
+		await this.#goalRuntime.onTaskAborted({ reason: options?.goalReason ?? "interrupted" });
 		// Clear prompt-in-flight state: waitForIdle resolves when the agent loop's finally
 		// block runs, but nested prompt setup/finalizers may still be unwinding. Without this,
 		// a subsequent prompt() can incorrectly observe the session as busy after an abort.
@@ -4545,6 +4808,7 @@ export class AgentSession {
 			if (persist && effectiveLevel !== undefined && effectiveLevel !== ThinkingLevel.Off) {
 				this.settings.set("defaultThinkingLevel", effectiveLevel);
 			}
+			this.#emit({ type: "thinking_level_changed", thinkingLevel: effectiveLevel });
 		}
 	}
 
@@ -4678,8 +4942,6 @@ export class AgentSession {
 
 			let hookCompaction: CompactionResult | undefined;
 			let fromExtension = false;
-			let hookContext: string[] | undefined;
-			let hookPrompt: string | undefined;
 			let preserveData: Record<string, unknown> | undefined;
 
 			if (this.#extensionRunner?.hasHandlers("session_before_compact")) {
@@ -4701,23 +4963,7 @@ export class AgentSession {
 				}
 			}
 
-			if (!hookCompaction && this.#extensionRunner?.hasHandlers("session.compacting")) {
-				const compactMessages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
-				const result = (await this.#extensionRunner.emit({
-					type: "session.compacting",
-					sessionId: this.sessionId,
-					messages: compactMessages,
-				})) as { context?: string[]; prompt?: string; preserveData?: Record<string, unknown> } | undefined;
-
-				hookContext = result?.context;
-				hookPrompt = result?.prompt;
-				preserveData = result?.preserveData;
-			}
-
-			const memoryBackendContext = await this.#collectMemoryBackendContext(preparation);
-			if (memoryBackendContext) {
-				hookContext = hookContext ? [...hookContext, memoryBackendContext] : [memoryBackendContext];
-			}
+			const compactionPrep = await this.#prepareCompactionFromHooks(preparation, hookCompaction);
 
 			let summary: string;
 			let shortSummary: string | undefined;
@@ -4725,14 +4971,13 @@ export class AgentSession {
 			let tokensBefore: number;
 			let details: unknown;
 
-			if (hookCompaction) {
-				// Extension provided compaction content
-				summary = hookCompaction.summary;
-				shortSummary = hookCompaction.shortSummary;
-				firstKeptEntryId = hookCompaction.firstKeptEntryId;
-				tokensBefore = hookCompaction.tokensBefore;
-				details = hookCompaction.details;
-				preserveData ??= hookCompaction.preserveData;
+			if (compactionPrep.kind === "fromHook") {
+				summary = compactionPrep.summary;
+				shortSummary = compactionPrep.shortSummary;
+				firstKeptEntryId = compactionPrep.firstKeptEntryId;
+				tokensBefore = compactionPrep.tokensBefore;
+				details = compactionPrep.details;
+				preserveData = compactionPrep.preserveData;
 			} else {
 				// Generate compaction result. Only convert known abort-shaped
 				// rejections (AbortError raised while the abort signal is set,
@@ -4751,8 +4996,8 @@ export class AgentSession {
 						customInstructions,
 						compactionAbortController.signal,
 						{
-							promptOverride: hookPrompt,
-							extraContext: hookContext,
+							promptOverride: compactionPrep.hookPrompt,
+							extraContext: compactionPrep.hookContext,
 							remoteInstructions: this.#baseSystemPrompt.join("\n\n"),
 						},
 					);
@@ -4761,7 +5006,7 @@ export class AgentSession {
 					firstKeptEntryId = result.firstKeptEntryId;
 					tokensBefore = result.tokensBefore;
 					details = result.details;
-					preserveData = { ...(preserveData ?? {}), ...(result.preserveData ?? {}) };
+					preserveData = { ...(compactionPrep.preserveData ?? {}), ...(result.preserveData ?? {}) };
 				} catch (err) {
 					if (err instanceof CompactionCancelledError) {
 						throw err;
@@ -5199,14 +5444,14 @@ export class AgentSession {
 		}
 
 		const calledRequiredTool = assistantMessage.content.some(
-			content => content.type === "toolCall" && (content.name === "ask" || content.name === "exit_plan_mode"),
+			content => content.type === "toolCall" && (content.name === "ask" || content.name === "resolve"),
 		);
 		if (calledRequiredTool) {
 			return;
 		}
-		const hasRequiredTools = this.#toolRegistry.has("ask") && this.#toolRegistry.has("exit_plan_mode");
+		const hasRequiredTools = this.#toolRegistry.has("ask") && this.#toolRegistry.has("resolve");
 		if (!hasRequiredTools) {
-			logger.warn("Plan mode enforcement skipped because ask/exit tools are unavailable", {
+			logger.warn("Plan mode enforcement skipped because ask/resolve tools are unavailable", {
 				activeToolNames: this.agent.state.tools.map(tool => tool.name),
 			});
 			return;
@@ -5214,7 +5459,6 @@ export class AgentSession {
 
 		const reminder = prompt.render(planModeToolDecisionReminderPrompt, {
 			askToolName: "ask",
-			exitToolName: "exit_plan_mode",
 		});
 
 		await this.prompt(reminder, {
@@ -5721,6 +5965,64 @@ export class AgentSession {
 		throw this.#buildCompactionAuthError();
 	}
 
+	async #prepareCompactionFromHooks(
+		preparation: CompactionPreparation,
+		hookCompaction: CompactionResult | undefined,
+	): Promise<
+		| {
+				kind: "fromHook";
+				summary: string;
+				shortSummary: string | undefined;
+				firstKeptEntryId: string;
+				tokensBefore: number;
+				details: unknown;
+				preserveData: Record<string, unknown> | undefined;
+		  }
+		| {
+				kind: "needsLlm";
+				hookContext: string[] | undefined;
+				hookPrompt: string | undefined;
+				preserveData: Record<string, unknown> | undefined;
+		  }
+	> {
+		let hookContext: string[] | undefined;
+		let hookPrompt: string | undefined;
+		let preserveData: Record<string, unknown> | undefined;
+
+		if (!hookCompaction && this.#extensionRunner?.hasHandlers("session.compacting")) {
+			const compactMessages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
+			const result = (await this.#extensionRunner.emit({
+				type: "session.compacting",
+				sessionId: this.sessionId,
+				messages: compactMessages,
+			})) as { context?: string[]; prompt?: string; preserveData?: Record<string, unknown> } | undefined;
+
+			hookContext = result?.context;
+			hookPrompt = result?.prompt;
+			preserveData = result?.preserveData;
+		}
+
+		const memoryBackendContext = await this.#collectMemoryBackendContext(preparation);
+		if (memoryBackendContext) {
+			hookContext = hookContext ? [...hookContext, memoryBackendContext] : [memoryBackendContext];
+		}
+
+		if (hookCompaction) {
+			preserveData ??= hookCompaction.preserveData;
+			return {
+				kind: "fromHook",
+				summary: hookCompaction.summary,
+				shortSummary: hookCompaction.shortSummary,
+				firstKeptEntryId: hookCompaction.firstKeptEntryId,
+				tokensBefore: hookCompaction.tokensBefore,
+				details: hookCompaction.details,
+				preserveData,
+			};
+		}
+
+		return { kind: "needsLlm", hookContext, hookPrompt, preserveData };
+	}
+
 	/**
 	 * Internal: Run auto-compaction with events.
 	 */
@@ -5842,8 +6144,6 @@ export class AgentSession {
 
 			let hookCompaction: CompactionResult | undefined;
 			let fromExtension = false;
-			let hookContext: string[] | undefined;
-			let hookPrompt: string | undefined;
 			let preserveData: Record<string, unknown> | undefined;
 
 			if (this.#extensionRunner?.hasHandlers("session_before_compact")) {
@@ -5872,23 +6172,7 @@ export class AgentSession {
 				}
 			}
 
-			if (!hookCompaction && this.#extensionRunner?.hasHandlers("session.compacting")) {
-				const compactMessages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
-				const result = (await this.#extensionRunner.emit({
-					type: "session.compacting",
-					sessionId: this.sessionId,
-					messages: compactMessages,
-				})) as { context?: string[]; prompt?: string; preserveData?: Record<string, unknown> } | undefined;
-
-				hookContext = result?.context;
-				hookPrompt = result?.prompt;
-				preserveData = result?.preserveData;
-			}
-
-			const memoryBackendContext = await this.#collectMemoryBackendContext(preparation);
-			if (memoryBackendContext) {
-				hookContext = hookContext ? [...hookContext, memoryBackendContext] : [memoryBackendContext];
-			}
+			const compactionPrep = await this.#prepareCompactionFromHooks(preparation, hookCompaction);
 
 			let summary: string;
 			let shortSummary: string | undefined;
@@ -5896,14 +6180,13 @@ export class AgentSession {
 			let tokensBefore: number;
 			let details: unknown;
 
-			if (hookCompaction) {
-				// Extension provided compaction content
-				summary = hookCompaction.summary;
-				shortSummary = hookCompaction.shortSummary;
-				firstKeptEntryId = hookCompaction.firstKeptEntryId;
-				tokensBefore = hookCompaction.tokensBefore;
-				details = hookCompaction.details;
-				preserveData ??= hookCompaction.preserveData;
+			if (compactionPrep.kind === "fromHook") {
+				summary = compactionPrep.summary;
+				shortSummary = compactionPrep.shortSummary;
+				firstKeptEntryId = compactionPrep.firstKeptEntryId;
+				tokensBefore = compactionPrep.tokensBefore;
+				details = compactionPrep.details;
+				preserveData = compactionPrep.preserveData;
 			} else {
 				const candidates = this.#getCompactionModelCandidates(availableModels);
 				const retrySettings = this.settings.getGroup("retry");
@@ -5918,8 +6201,8 @@ export class AgentSession {
 					while (true) {
 						try {
 							compactResult = await compact(preparation, candidate, apiKey, undefined, autoCompactionSignal, {
-								promptOverride: hookPrompt,
-								extraContext: hookContext,
+								promptOverride: compactionPrep.hookPrompt,
+								extraContext: compactionPrep.hookContext,
 								remoteInstructions: this.#baseSystemPrompt.join("\n\n"),
 								metadata: this.agent.metadataForProvider(candidate.provider),
 								initiatorOverride: "agent",
@@ -5976,7 +6259,7 @@ export class AgentSession {
 								error: message,
 								model: `${candidate.provider}/${candidate.id}`,
 							});
-							await abortableSleep(delayMs, autoCompactionSignal);
+							await scheduler.wait(delayMs, { signal: autoCompactionSignal });
 						}
 					}
 
@@ -5997,7 +6280,7 @@ export class AgentSession {
 				firstKeptEntryId = compactResult.firstKeptEntryId;
 				tokensBefore = compactResult.tokensBefore;
 				details = compactResult.details;
-				preserveData = { ...(preserveData ?? {}), ...(compactResult.preserveData ?? {}) };
+				preserveData = { ...(compactionPrep.preserveData ?? {}), ...(compactResult.preserveData ?? {}) };
 			}
 
 			if (autoCompactionSignal.aborted) {
@@ -6148,10 +6431,11 @@ export class AgentSession {
 
 	#isTransientTransportErrorMessage(errorMessage: string): boolean {
 		// Match: overloaded_error, provider returned error, rate limit, 429, 500, 502, 503, 504,
-		// service unavailable, network/connection/socket errors, fetch failed, terminated, retry delay exceeded
+		// service unavailable, provider-suggested retry, network/connection/socket errors, fetch failed,
+		// terminated, retry delay exceeded
 		return (
 			isUnexpectedSocketCloseMessage(errorMessage) ||
-			/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response/i.test(
+			/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|retry your request|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response/i.test(
 				errorMessage,
 			)
 		);
@@ -6501,7 +6785,7 @@ export class AgentSession {
 		this.#retryAbortController?.abort();
 		this.#retryAbortController = retryAbortController;
 		try {
-			await abortableSleep(delayMs, retryAbortController.signal);
+			await scheduler.wait(delayMs, { signal: retryAbortController.signal });
 		} catch {
 			if (this.#retryAbortController !== retryAbortController) {
 				return false;
@@ -7833,21 +8117,11 @@ export class AgentSession {
 	 * @returns Text content, or undefined if no assistant message exists
 	 */
 	getLastAssistantText(): string | undefined {
-		const lastAssistant = this.messages
-			.slice()
-			.reverse()
-			.find(m => {
-				if (m.role !== "assistant") return false;
-				const msg = m as AssistantMessage;
-				// Skip aborted messages with no content
-				if (msg.stopReason === "aborted" && msg.content.length === 0) return false;
-				return true;
-			});
-
+		const lastAssistant = this.#getLastCopyCandidateAssistantMessage();
 		if (!lastAssistant) return undefined;
 
 		let text = "";
-		for (const content of (lastAssistant as AssistantMessage).content) {
+		for (const content of lastAssistant.content) {
 			if (content.type === "text") {
 				text += content.text;
 			}
@@ -7856,6 +8130,54 @@ export class AgentSession {
 		return text.trim() || undefined;
 	}
 
+	hasCopyCandidateAssistantMessage(): boolean {
+		return this.#getLastCopyCandidateAssistantMessage() !== undefined;
+	}
+
+	#getLastCopyCandidateAssistantMessage(): AssistantMessage | undefined {
+		for (let i = this.messages.length - 1; i >= 0; i--) {
+			const message = this.messages[i];
+			if (message.role !== "assistant") continue;
+
+			const assistantMessage = message as AssistantMessage;
+			// Skip aborted messages with no content
+			if (assistantMessage.stopReason === "aborted" && assistantMessage.content.length === 0) continue;
+
+			return assistantMessage;
+		}
+
+		return undefined;
+	}
+	/**
+	 * Get text content of the most recent visible handoff message.
+	 * Fresh handoff sessions store the handoff context as a custom message, not
+	 * an assistant message, so callers that copy the "last" message can use this
+	 * as a fallback before the new session has an assistant response.
+	 */
+	getLastVisibleHandoffText(): string | undefined {
+		for (let i = this.messages.length - 1; i >= 0; i--) {
+			const message = this.messages[i];
+			if (message.role !== "custom") continue;
+
+			const customMessage = message as CustomMessage;
+			if (customMessage.customType !== "handoff" || !customMessage.display) continue;
+
+			if (typeof customMessage.content === "string") {
+				return customMessage.content.trim() || undefined;
+			}
+
+			let text = "";
+			for (const content of customMessage.content) {
+				if (content.type === "text") {
+					text += content.text;
+				}
+			}
+			return text.trim() || undefined;
+		}
+
+		return undefined;
+	}
+
 	/**
 	 * Format the entire session as plain text for clipboard export.
 	 * Includes user messages, assistant text, thinking blocks, tool calls, and tool results.