@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/session/agent-session.ts

@@ -1,7 +1,7 @@
 /**
  * AgentSession - Core abstraction for agent lifecycle and session management.
  *
- * This class is shared between all run modes (interactive, print, rpc).
+ * This class is shared by interactive, print, ACP, and SDK-hosted session callers.
  * It encapsulates:
  * - Agent state access
  * - Event subscription with automatic session persistence
@@ -13,6 +13,7 @@
  * Modes use this class and add their own I/O layer on top.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -22,13 +23,18 @@ import {
 	type AfterToolCallResult,
 	type Agent,
 	AgentBusyError,
+	type AgentContext,
 	type AgentEvent,
+	type AgentLoopConfig,
 	type AgentMessage,
 	type AgentState,
 	type AgentTool,
 	assertImagePlaceholdersHavePayload,
 	canContinuePersistedHistory,
-	type ResolvedThinkingLevel,
+	type ManagedAttemptContinuationOwnership,
+	type ManagedAttemptDecision,
+	type ManagedAttemptOutcome,
+	type MidRunMaintenanceOutcome,
 	resolveTelemetry,
 	type StablePrefixSnapshot,
 	ThinkingLevel,
@@ -75,20 +81,20 @@ import type {
 	TextContent,
 	ToolCall,
 	ToolChoice,
+	TransportFailureFacts,
 	Usage,
 	UsageReport,
 } from "@gajae-code/ai";
 import {
-	calculateRateLimitBackoffMs,
 	clearAnthropicFastModeFallback,
 	getSupportedEfforts,
 	isContextOverflow,
 	isUsageLimitError,
 	modelsAreEqual,
-	parseRateLimitReason,
 	resolveServiceTier,
 	streamSimple,
 } from "@gajae-code/ai";
+import { beginAttempt, classifyFallbackTrigger } from "@gajae-code/ai/utils/fallback-transport";
 
 export interface ForkContextSeedMetadata {
 	sourceSessionId: string;
@@ -138,19 +144,28 @@ import { createAppendOnlyContextManager, resolveAppendOnlyMode } from "../append
 import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import { reset as resetCapabilities } from "../capability";
 import type { Rule } from "../capability/rule";
-import { GJC_MODEL_ASSIGNMENT_TARGETS, MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
+import {
+	GJC_MODEL_ASSIGNMENT_TARGETS,
+	isAuthenticated,
+	MODEL_ROLE_IDS,
+	type ModelRegistry,
+} from "../config/model-registry";
 import {
 	extractExplicitThinkingSelector,
 	formatModelSelectorValue,
 	formatModelString,
+	managedCursorFallbackUnavailableReason,
 	parseModelString,
 	type ResolvedModelRoleValue,
+	resolveModelChainWithAuth,
 	resolveModelRoleValue,
 	type ScopedModelSelection,
 } from "../config/model-resolver";
+import { normalizeModelSelectorValue } from "../config/model-selector-value";
 import { expandPromptTemplate, type PromptTemplate } from "../config/prompt-templates";
-import type { Settings, SkillsSettings } from "../config/settings";
+import type { GlobalDefaultModelRoleCommit, Settings, SkillsSettings } from "../config/settings";
 import { onAppendOnlyModeChanged } from "../config/settings";
+import { getDefault } from "../config/settings-schema";
 import { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
 import { loadCapability } from "../discovery";
 import { expandApplyPatchToEntries, normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../edit";
@@ -187,12 +202,15 @@ import type {
 } from "../extensibility/extensions";
 import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
 import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
-import type { LoadedSubskillActivation } from "../extensibility/gjc-plugins";
+import {
+	type LoadedSubskillActivation,
+	resolveSubskillActivationForSkillInvocation,
+} from "../extensibility/gjc-plugins";
 import { resolveCurrentPhaseForParent } from "../extensibility/gjc-plugins/injection";
 import { readActiveSubskillsForParent, toActiveSubskillEntry } from "../extensibility/gjc-plugins/state";
 import { loadActiveSubskillTools } from "../extensibility/gjc-plugins/tools";
 import type { HookCommandContext } from "../extensibility/hooks/types";
-import type { Skill, SkillWarning } from "../extensibility/skills";
+import { buildSkillPromptMessage, type Skill, type SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { buildGjcRuntimeSessionEnv, consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
 import {
@@ -213,7 +231,12 @@ import { ensureWorkflowSkillActivationState } from "../hooks/skill-state";
 import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { shutdownAll as shutdownAllLspClients } from "../lsp/client";
 import { resolveMemoryBackend } from "../memory-backend";
-import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
+import {
+	BrokerWorkflowGateEmitter,
+	FileGateStore,
+	MemoryGateStore,
+	type WorkflowGateEmitter,
+} from "../modes/shared/agent-wire/workflow-gate-broker";
 import { getCurrentThemeName, theme } from "../modes/theme/theme";
 import type { PlanModeState } from "../plan-mode/state";
 import autoContinuePrompt from "../prompts/system/auto-continue.md" with { type: "text" };
@@ -238,6 +261,7 @@ import {
 	selectDiscoverableMCPToolNamesByServer,
 } from "../runtime-mcp/discoverable-tool-metadata";
 import { MCPManager } from "../runtime-mcp/manager";
+import type { NotificationSessionController } from "../sdk/bus/session-control";
 import { deobfuscateSessionContext, type SecretObfuscator } from "../secrets/obfuscator";
 import { formatNoCredentialOnboardingError, formatNoModelOnboardingError } from "../setup/model-onboarding-guidance";
 import {
@@ -279,7 +303,26 @@ import { buildNamedToolChoice, buildNamedToolChoiceResult } from "../utils/tool-
 import { buildWorkflowIntentDiff, WORKFLOW_INTENT_DIFF_CUSTOM_TYPE } from "../workflow/workflow-intent-diff";
 import { buildWorkspaceTree, type WorkspaceTree } from "../workspace-tree";
 import type { AuthStorage } from "./auth-storage";
-import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome } from "./client-bridge";
+import {
+	DefaultModelSelectionRecoveryError,
+	type DefaultModelSelectionResult,
+	type DefaultModelSelectionRollbackStage,
+} from "./default-model-selection";
+import {
+	type ConfiguredFallbackChain,
+	effectiveFallbackDelay,
+	FallbackChainController,
+	type FallbackTriggerClass,
+} from "./fallback-chain-controller";
+
+export { DefaultModelSelectionRecoveryError } from "./default-model-selection";
+
+import type {
+	ClientBridge,
+	ClientBridgePermissionOption,
+	ClientBridgePermissionOutcome,
+	ClientBridgePermissionToolCall,
+} from "./client-bridge";
 import { computeNonMessageTokens } from "./context-estimation";
 import {
 	type ContributionPrepOptions,
@@ -303,6 +346,7 @@ import { formatSessionDumpText } from "./session-dump-format";
 import type {
 	BranchSummaryEntry,
 	CompactionEntry,
+	DefaultModelSelectionStage,
 	NewSessionOptions,
 	SessionContext,
 	SessionManager,
@@ -342,8 +386,18 @@ export type AgentSessionEvent =
 			unbounded?: boolean;
 	  }
 	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
-	| { type: "retry_fallback_applied"; from: string; to: string; role: string }
-	| { type: "retry_fallback_succeeded"; model: string; role: string }
+	| {
+			type: "model_fallback_switched";
+			eventId: string;
+			from: string;
+			to: string;
+			reason: string;
+			role: string;
+			scope: string;
+			activeIndex: number;
+			chainLength: number;
+			attemptsUsed: number;
+	  }
 	| { type: "ttsr_triggered"; rules: Rule[] }
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
 	| { type: "todo_auto_clear" }
@@ -384,6 +438,8 @@ export interface AgentSessionConfig {
 	agent: Agent;
 	sessionManager: SessionManager;
 	settings: Settings;
+	/** Shared Gate-A-eligible notification session controller, when this host supports it. */
+	notificationSessionController?: NotificationSessionController;
 	/** Models to cycle through with Alt+N (from --models flag) */
 	scopedModels?: ScopedModelSelection[];
 	/** Initial session thinking selector. */
@@ -394,6 +450,7 @@ export interface AgentSessionConfig {
 	slashCommands?: FileSlashCommand[];
 	/** Extension runner (created in main.ts with wrapped tools) */
 	extensionRunner?: ExtensionRunner;
+
 	/** Loaded skills (already discovered by SDK) */
 	skills?: Skill[];
 	/** Skill loading warnings (already captured by SDK) */
@@ -422,7 +479,11 @@ export interface AgentSessionConfig {
 	/** Current session message-to-LLM conversion pipeline */
 	convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	/** System prompt builder that can consider tool availability. Returns ordered provider-facing blocks. */
-	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{ systemPrompt: string[] }>;
+	rebuildSystemPrompt?: (
+		toolNames: string[],
+		tools: Map<string, AgentTool>,
+		candidateModel?: Model,
+	) => Promise<{ systemPrompt: string[] }>;
 	/** Initial workspace tree snapshot used for the first volatile per-turn context message. */
 	workspaceTree?: WorkspaceTree;
 	/** Rebuild the SSH tool from current capability discovery results. */
@@ -487,6 +548,14 @@ export interface AgentSessionConfig {
 	providerCacheSessionId?: string;
 }
 
+type MidRunMaintenanceLifecycle = Parameters<NonNullable<AgentLoopConfig["maintainContext"]>>[1];
+
+type AutoCompactionTerminalStatus =
+	| { kind: "compacted" }
+	| { kind: "aborted"; source: "signal" | "hook" }
+	| { kind: "skipped" }
+	| { kind: "failed" };
+
 /** Options for AgentSession.prompt() */
 export interface PromptOptions {
 	/** Whether to expand file-based prompt templates (default: true) */
@@ -505,6 +574,21 @@ export interface PromptOptions {
 	attribution?: MessageAttribution;
 	/** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
 	skipCompactionCheck?: boolean;
+	/**
+	 * Invoked after all prompt preflight checks pass and immediately before agent execution begins.
+	 * Cancellation before this callback rejects the prompt.
+	 */
+	onPreflightAccepted?: () => void;
+}
+
+function promptPreflightCancelledError(): Error {
+	const error = Object.assign(new Error("Prompt preflight was cancelled before execution."), { code: "busy" });
+	error.name = "PromptPreflightCancelledError";
+	return error;
+}
+
+function isPromptPreflightCancelledError(error: unknown): boolean {
+	return error instanceof Error && error.name === "PromptPreflightCancelledError";
 }
 
 /** Result from a handoff operation. */
@@ -526,6 +610,37 @@ export interface ModelCycleResult {
 	isScoped: boolean;
 }
 
+export type ModelChangeCause =
+	| "user-selection"
+	| "profile-activation"
+	| "fallback-switch"
+	| "restore"
+	| "rollback"
+	| "startup-override"
+	| "temporary-operation";
+
+export type TemporaryModelReason =
+	| "plan-mode"
+	| "context-promotion"
+	| "temporary-cycle"
+	| "profile-preview"
+	| "extension-temporary"
+	| "other";
+
+/** Opaque handle for a non-destructive temporary provider-session scope. */
+export interface TemporaryProviderSessionScope {
+	readonly reason: TemporaryModelReason;
+}
+
+interface TemporaryProviderSessionScopeRecord {
+	token: TemporaryProviderSessionScope;
+	autoOwned: boolean;
+	model: Model | undefined;
+	thinkingLevel: ThinkingLevel | undefined;
+	fallbackController: FallbackChainController | undefined;
+	providerSessionState: Map<string, ProviderSessionState>;
+}
+
 /** Result from cycleRoleModels() */
 export interface RoleModelCycleResult {
 	model: Model;
@@ -533,12 +648,6 @@ export interface RoleModelCycleResult {
 	role: string;
 }
 
-export interface DefaultModelSelectionResult {
-	readonly provider: string;
-	readonly modelId: string;
-	readonly thinkingLevel: ResolvedThinkingLevel;
-}
-
 /** Session statistics for /session command */
 export interface SessionStats {
 	sessionFile: string | undefined;
@@ -567,9 +676,6 @@ export interface SessionStats {
 
 /** Standard thinking levels */
 
-type RetryFallbackChains = Record<string, string[]>;
-
-type RetryFallbackRevertPolicy = "never" | "cooldown-expiry";
 type RetryErrorClassification =
 	| "none"
 	| "overflow"
@@ -580,42 +686,6 @@ type RetryErrorClassification =
 	| "local_unavailable"
 	| "unknown";
 
-interface RetryFallbackSelector {
-	raw: string;
-	provider: string;
-	id: string;
-	thinkingLevel: ThinkingLevel | undefined;
-}
-
-interface ActiveRetryFallbackState {
-	role: string;
-	originalSelector: string;
-	originalThinkingLevel: ThinkingLevel | undefined;
-	lastAppliedFallbackThinkingLevel: ThinkingLevel | undefined;
-}
-
-function parseRetryFallbackSelector(selector: string): RetryFallbackSelector | undefined {
-	const trimmed = selector.trim();
-	if (!trimmed) return undefined;
-	const parsed = parseModelString(trimmed);
-	if (!parsed) return undefined;
-	return {
-		raw: trimmed,
-		provider: parsed.provider,
-		id: parsed.id,
-		thinkingLevel: parsed.thinkingLevel,
-	};
-}
-
-function formatRetryFallbackSelector(model: Model, thinkingLevel: ThinkingLevel | undefined): string {
-	const selector = formatModelString(model);
-	return thinkingLevel ? `${selector}:${thinkingLevel}` : selector;
-}
-
-function formatRetryFallbackBaseSelector(selector: RetryFallbackSelector): string {
-	return `${selector.provider}/${selector.id}`;
-}
-
 function isLocalModelEndpoint(model: Model | undefined): boolean {
 	if (!model) return false;
 	if (model.provider === "ollama" || model.provider === "lm-studio" || model.provider === "llama.cpp") {
@@ -1175,10 +1245,24 @@ export class StreamingEditFileCache {
 		return this.#totalBytes;
 	}
 }
+type SessionAdmissionKind = "prompt" | "selection";
+
+type SessionAdmissionEntry = {
+	kind: SessionAdmissionKind;
+	ready: PromiseWithResolvers<void>;
+	settled: PromiseWithResolvers<void>;
+	released: boolean;
+};
+
+type SessionAdmissionLease = {
+	release(): void;
+};
+
 export class AgentSession {
 	readonly agent: Agent;
 	readonly sessionManager: SessionManager;
 	readonly settings: Settings;
+	readonly notificationSessionController: NotificationSessionController | undefined;
 	readonly taskDepth: number;
 	readonly yieldQueue: YieldQueue;
 
@@ -1189,7 +1273,11 @@ export class AgentSession {
 	#scopedModels: ScopedModelSelection[];
 	#thinkingLevel: ThinkingLevel | undefined;
 	#activeModelProfile: string | undefined;
-	#defaultModelSelectionTail: Promise<void> = Promise.resolve();
+	#sessionAdmissionQueue: SessionAdmissionEntry[] = [];
+	#activeSessionAdmission: SessionAdmissionEntry | undefined;
+	#sessionAdmissionClosed = false;
+	#sessionAdmissionContext = new AsyncLocalStorage<SessionAdmissionEntry>();
+	#defaultModelSelectionMutationRevision = 0;
 	#promptTemplates: PromptTemplate[];
 	#slashCommands: FileSlashCommand[];
 
@@ -1200,6 +1288,8 @@ export class AgentSession {
 	#lastAppendOnlyResolution?: { enable: boolean; providerId: string | undefined };
 	#eventListeners: AgentSessionEventListener[] = [];
 	#eventListenerSnapshot: readonly AgentSessionEventListener[] = Object.freeze([]);
+	/** Resolution-time switches that occur before a consumer can subscribe. */
+	#pendingFallbackSwitches: Extract<AgentSessionEvent, { type: "model_fallback_switched" }>[] = [];
 
 	#rebuildEventListenerSnapshot(): void {
 		this.#eventListenerSnapshot = Object.freeze([...this.#eventListeners]);
@@ -1233,12 +1323,36 @@ export class AgentSession {
 	#allowAcpAgentInitiatedTurns = false;
 	/** Per-session memory of allow_always / reject_always decisions for gated tools. */
 	#acpPermissionDecisions: Map<string, "allow_always" | "reject_always"> = new Map();
+	/** SDK-controlled permission policy applied before ACP client prompting. Defaults to `allow` so callers
+	 * without a reverse permission provider (TUI, print/headless) run guarded tools; ACP/SDK set this explicitly. */
+	#sdkPermissionMode: "prompt" | "allow" | "deny" = "allow";
+	/** Permission provider registered by a live SDK reverse lease. */
+	#sdkPermissionProvider:
+		| ((
+				toolCall: ClientBridgePermissionToolCall,
+				options: ClientBridgePermissionOption[],
+				signal?: AbortSignal,
+		  ) => Promise<ClientBridgePermissionOutcome>)
+		| undefined;
+
 	#guardedToolWrapperCache = new WeakMap<AgentTool, Map<string, AgentTool>>();
 	#acpPermissionWrapperVersion = 0;
 
 	// Compaction state
 	#compactionAbortController: AbortController | undefined = undefined;
 	#autoCompactionAbortController: AbortController | undefined = undefined;
+
+	/** Invocation-scoped EventStream drain barriers owned by active maintenance calls. */
+	#activeMidRunBarrierControllers = new Set<AbortController>();
+	/** Maintenance invocations that must settle before resources are torn down. */
+	#activeMidRunMaintenancePromises = new Set<Promise<MidRunMaintenanceOutcome>>();
+	// Anti-loop guard (#1662): signature of the assistant response that last
+	// anchored a mid-run maintenance attempt. A given provider response drives at
+	// most one attempt, so a compaction that cannot shrink further can't wedge the
+	// loop into interrupt → resume → interrupt; a NEW response (fresh signature) is
+	// required to re-trigger. A content signature (not object identity) is used so
+	// it survives the message-array rebuild that compaction/prune perform.
+	#lastMidRunMaintenanceAnchorSignature: string | undefined = undefined;
 	#resourceSampler: () => EmergencyCompactionSample = () => this.#defaultResourceSample();
 	#retainedMemorySampler: (() => RetainedMemorySample) | undefined;
 	#prePromptContextCheckPromise: Promise<void> | undefined = undefined;
@@ -1261,7 +1375,9 @@ export class AgentSession {
 	#retryAttempt = 0;
 	#retryPromise: Promise<void> | undefined = undefined;
 	#retryResolve: (() => void) | undefined = undefined;
-	#activeRetryFallback: ActiveRetryFallbackState | undefined = undefined;
+	#defaultFallbackController: FallbackChainController | undefined;
+	#defaultFallbackExhaustedLastTurn = false;
+	#fallbackInvocationId = 0;
 	// Todo completion reminder state
 	#todoReminderCount = 0;
 	#lastGoalReminderAssistantTimestamp: number | undefined = undefined;
@@ -1302,8 +1418,10 @@ export class AgentSession {
 	#providerSessionId: string | undefined;
 	#providerCacheSessionId: string | undefined;
 	#isDisposed = false;
+	#disposePromise: Promise<void> | undefined;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
+
 	#turnIndex = 0;
 	#workerIntegrationScheduler = new WorkerIntegrationRequestScheduler(async () => {
 		await requestGjcWorkerIntegrationAttempt(this.sessionManager.getCwd(), process.env).catch(error => {
@@ -1336,7 +1454,11 @@ export class AgentSession {
 	#onSseEvent: SimpleStreamOptions["onSseEvent"] | undefined;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#rebuildSystemPrompt:
-		| ((toolNames: string[], tools: Map<string, AgentTool>) => Promise<{ systemPrompt: string[] }>)
+		| ((
+				toolNames: string[],
+				tools: Map<string, AgentTool>,
+				candidateModel?: Model,
+		  ) => Promise<{ systemPrompt: string[] }>)
 		| undefined;
 	#getMcpServerInstructions: (() => Map<string, string> | undefined) | undefined;
 	#reloadSshTool: (() => Promise<AgentTool | null>) | undefined;
@@ -1353,6 +1475,9 @@ export class AgentSession {
 	 * the dominant cause of prompt-cache invalidation in long sessions.
 	 */
 	#lastAppliedToolSignature: string | undefined;
+	#pendingAppliedToolSignature: string | undefined;
+	#baseSystemPromptGeneration = 0;
+	#pendingBaseSystemPromptRebuilds = new Set<Promise<void>>();
 	#mcpDiscoveryEnabled = false;
 	#discoverableMCPTools = new Map<string, DiscoverableMCPTool>();
 	#discoverableMCPSearchIndex: DiscoverableMCPSearchIndex | null = null;
@@ -1361,7 +1486,6 @@ export class AgentSession {
 	#discoverableToolSearchIndex: DiscoverableToolSearchIndex | null = null;
 	#selectedDiscoveredToolNames = new Set<string>();
 	#discoverableToolAllowedNames: ReadonlySet<string> | undefined;
-	#rpcHostToolNames = new Set<string>();
 	#gjcSubskillToolNames = new Set<string>();
 	#gjcSubskillToolSignature: string | undefined;
 	#defaultSelectedMCPServerNames = new Set<string>();
@@ -1431,15 +1555,17 @@ export class AgentSession {
 		nonEditDeterminations: 0,
 	};
 	#promptInFlightCount = 0;
-	// Wire-level agent_end emission deferred until #promptInFlightCount drops to 0.
-	// Local subscribers and extension hooks both receive the deferred event from
-	// #flushPendingAgentEnd(), preserving the local-before-extension ordering used
-	// by #emitSessionEvent while still preventing external clients from resuming
-	// before #promptWithMessage's finally decrements #promptInFlightCount. Without
-	// this, a client that resumes on `agent_end` can fire its next `prompt` while
-	// the session still reports busy and hit AgentBusyError. Flushed from both
-	// #endInFlight (normal) and #resetInFlight (abort).
+	#agentEventHandlersInFlight = 0;
+	#queuedExtensionEventCount = 0;
+	// Wire-level agent_end emission is deferred until both the prompt finalizer and
+	// async event handlers settle. Subscribers treat agent_end as readiness, so
+	// publishing it earlier lets a successor corrupt the prior prompt's lifecycle.
 	#pendingAgentEndEmit: AgentSessionEvent | undefined;
+	// A scheduled continuation owns this terminal boundary until it either starts
+	// the successor or proves it cannot. Holds prevent a false idle event while
+	// preserving the predecessor for cancellation and preflight failures.
+	#pendingAgentEndContinuationHolds = new Map<symbol, AgentSessionEvent>();
+
 	#obfuscator: SecretObfuscator | undefined;
 	#checkpointState: CheckpointState | undefined = undefined;
 	#providerReplaySourceCache = new WeakMap<AgentMessage, ProviderReplaySourceCacheEntry>();
@@ -1448,7 +1574,11 @@ export class AgentSession {
 	#pendingRewindReport: string | undefined = undefined;
 	#lastSuccessfulYieldToolCallId: string | undefined = undefined;
 	#promptGeneration = 0;
+	#promptPreflightAbortController = new AbortController();
+
 	#providerSessionState = new Map<string, ProviderSessionState>();
+	#temporaryProviderSessionScopes: TemporaryProviderSessionScopeRecord[] = [];
+
 	/**
 	 * Provider keys for which the Anthropic fast-mode auto-fallback fired this
 	 * session (the provider rejected `speed:"fast"` and we retried without it).
@@ -1495,6 +1625,75 @@ export class AgentSession {
 		}
 	}
 
+	#sessionAdmissionBusyError(): AgentBusyError {
+		return Object.assign(new AgentBusyError("Agent session admission is busy due to same-session reentrancy."), {
+			code: "busy",
+		});
+	}
+
+	#activateNextSessionAdmission(): void {
+		if (this.#activeSessionAdmission || this.#sessionAdmissionClosed) return;
+		const next = this.#sessionAdmissionQueue.shift();
+		if (!next) return;
+		this.#activeSessionAdmission = next;
+		next.ready.resolve();
+	}
+
+	async #withSessionAdmission<T>(
+		kind: SessionAdmissionKind,
+		body: (lease: SessionAdmissionLease) => Promise<T>,
+	): Promise<T> {
+		const owner = this.#sessionAdmissionContext.getStore();
+		if (owner && !owner.released) throw this.#sessionAdmissionBusyError();
+		if (this.#sessionAdmissionClosed || this.#isDisposed) throw this.#sessionAdmissionBusyError();
+
+		const entry: SessionAdmissionEntry = {
+			kind,
+			ready: Promise.withResolvers<void>(),
+			settled: Promise.withResolvers<void>(),
+			released: false,
+		};
+		this.#sessionAdmissionQueue.push(entry);
+		this.#activateNextSessionAdmission();
+		await entry.ready.promise;
+		if (this.#sessionAdmissionClosed || this.#isDisposed) {
+			entry.released = true;
+			entry.settled.resolve();
+			if (this.#activeSessionAdmission === entry) this.#activeSessionAdmission = undefined;
+			this.#activateNextSessionAdmission();
+			throw this.#sessionAdmissionBusyError();
+		}
+
+		const release = () => {
+			if (entry.released) return;
+			entry.released = true;
+			entry.settled.resolve();
+			if (this.#activeSessionAdmission === entry) this.#activeSessionAdmission = undefined;
+			this.#activateNextSessionAdmission();
+		};
+		try {
+			return await this.#sessionAdmissionContext.run(entry, () => body({ release }));
+		} finally {
+			release();
+		}
+	}
+
+	async #closeSessionAdmission(): Promise<void> {
+		this.#sessionAdmissionClosed = true;
+		const queued = this.#sessionAdmissionQueue.splice(0);
+		for (const entry of queued) {
+			entry.released = true;
+			entry.ready.reject(this.#sessionAdmissionBusyError());
+			entry.settled.resolve();
+		}
+		const active = this.#activeSessionAdmission;
+		if (active?.kind === "prompt") {
+			this.#promptGeneration++;
+			this.#promptPreflightAbortController.abort();
+		}
+		if (active) await active.settled.promise;
+	}
+
 	#beginInFlight(): void {
 		this.#promptInFlightCount++;
 		if (this.#promptInFlightCount === 1) {
@@ -1502,6 +1701,75 @@ export class AgentSession {
 		}
 	}
 
+	#isPromptPreflightCancelled(generation: number, signal: AbortSignal): boolean {
+		return signal.aborted || this.#promptGeneration !== generation;
+	}
+
+	#throwIfPromptPreflightCancelled(generation: number, signal: AbortSignal): void {
+		if (this.#isPromptPreflightCancelled(generation, signal)) {
+			throw promptPreflightCancelledError();
+		}
+	}
+
+	async #awaitPromptPreflight<T>(generation: number, signal: AbortSignal, pending: Promise<T>): Promise<T> {
+		this.#throwIfPromptPreflightCancelled(generation, signal);
+		const cancellation = Promise.withResolvers<never>();
+		const cancel = () => cancellation.reject(promptPreflightCancelledError());
+		signal.addEventListener("abort", cancel, { once: true });
+		try {
+			const result = await Promise.race([pending, cancellation.promise]);
+			this.#throwIfPromptPreflightCancelled(generation, signal);
+			return result;
+		} finally {
+			signal.removeEventListener("abort", cancel);
+		}
+	}
+
+	#reserveDeferredAgentEndForContinuation(): symbol | undefined {
+		const pending = this.#pendingAgentEndEmit;
+		if (!pending) return undefined;
+		const hold = Symbol("deferred-agent-end-continuation");
+		this.#pendingAgentEndContinuationHolds.set(hold, pending);
+		return hold;
+	}
+
+	#claimDeferredAgentEndForContinuation(hold: symbol | undefined): AgentSessionEvent | undefined {
+		if (!hold) return undefined;
+		const pending = this.#pendingAgentEndContinuationHolds.get(hold);
+		this.#pendingAgentEndContinuationHolds.delete(hold);
+		if (pending && this.#pendingAgentEndEmit === pending) {
+			this.#pendingAgentEndEmit = undefined;
+			for (const [candidate, candidatePending] of this.#pendingAgentEndContinuationHolds) {
+				if (candidatePending === pending) this.#pendingAgentEndContinuationHolds.delete(candidate);
+			}
+		}
+		return pending;
+	}
+
+	#restoreDeferredAgentEndAfterContinuationFailure(pending: AgentSessionEvent | undefined): void {
+		if (pending && !this.#pendingAgentEndEmit) {
+			this.#pendingAgentEndEmit = pending;
+		}
+		this.#flushPendingAgentEnd();
+	}
+
+	#releaseDeferredAgentEndContinuation(hold: symbol | undefined): void {
+		if (!hold) return;
+		const pending = this.#pendingAgentEndContinuationHolds.get(hold);
+		this.#pendingAgentEndContinuationHolds.delete(hold);
+		this.#restoreDeferredAgentEndAfterContinuationFailure(pending);
+	}
+
+	#releaseDeferredAgentEndContinuations(): void {
+		let pending: AgentSessionEvent | undefined;
+		for (const candidate of this.#pendingAgentEndContinuationHolds.values()) {
+			pending = candidate;
+			break;
+		}
+		this.#pendingAgentEndContinuationHolds.clear();
+		this.#restoreDeferredAgentEndAfterContinuationFailure(pending);
+	}
+
 	#endInFlight(): void {
 		this.#promptInFlightCount = Math.max(0, this.#promptInFlightCount - 1);
 		if (this.#promptInFlightCount === 0) {
@@ -1511,17 +1779,21 @@ export class AgentSession {
 		}
 	}
 
-	#resetInFlight(): void {
-		this.#promptInFlightCount = 0;
-		this.#releasePowerAssertion();
-		this.#flushPendingBackgroundExchanges();
-		this.#flushPendingAgentEnd();
-	}
-
 	#flushPendingAgentEnd(): void {
+		if (
+			this.#promptInFlightCount > 0 ||
+			this.#agentEventHandlersInFlight > 0 ||
+			this.#queuedExtensionEventCount > 0 ||
+			this.#pendingAgentEndContinuationHolds.size > 0
+		)
+			return;
 		const pending = this.#pendingAgentEndEmit;
 		if (!pending) return;
 		this.#pendingAgentEndEmit = undefined;
+		// Persist before notifying synchronous subscribers: a subscriber may start a
+		// successor prompt from agent_end, whose running state must serialize after
+		// this terminal boundary rather than be overwritten by it.
+		this.#persistRuntimeStateInBackground(pending);
 		this.#emit(pending);
 		void this.#queueExtensionEvent(pending);
 	}
@@ -1530,6 +1802,7 @@ export class AgentSession {
 		this.agent = config.agent;
 		this.sessionManager = config.sessionManager;
 		this.settings = config.settings;
+		this.notificationSessionController = config.notificationSessionController;
 		this.taskDepth = config.taskDepth ?? 0;
 		// Register this session with the process-wide resource GC (idle/RSS browser-tab eviction
 		// + stale screenshot cleanup). Session-keyed so concurrent sessions share one timer safely.
@@ -1563,7 +1836,6 @@ export class AgentSession {
 		if (config.providerSessionState) {
 			this.#providerSessionState = config.providerSessionState;
 		}
-		this.#validateRetryFallbackChains();
 		this.#toolRegistry = config.toolRegistry ?? new Map();
 		this.#workflowGateToolSession = config.workflowGateToolSession;
 		this.#requestedToolNames = config.requestedToolNames;
@@ -1595,13 +1867,18 @@ export class AgentSession {
 		this.agent.setProviderResponseInterceptor(this.#onResponse);
 		this.agent.setRawSseEventInterceptor(this.#onSseEvent);
 		this.#setGuardedAgentTools(this.agent.state.tools);
+		this.#bindWorkflowGateEmitter();
 		this.yieldQueue = new YieldQueue({
 			isStreaming: () => this.isStreaming,
 			injectStreaming: message => this.agent.followUp(message),
 			injectIdle: async messages => {
 				const first = messages[0];
 				if (!first) return;
-				await this.agent.prompt(messages.length === 1 ? first : messages);
+				if (messages.length === 1) {
+					await this.agent.prompt(first, this.#managedFallbackPromptOptions());
+				} else {
+					await this.agent.prompt(messages, this.#managedFallbackPromptOptions());
+				}
 			},
 			scheduleIdleFlush: run => {
 				this.#schedulePostPromptTask(
@@ -1613,6 +1890,9 @@ export class AgentSession {
 			},
 		});
 		this.agent.setOnBeforeYield(() => this.yieldQueue.flush("streaming"));
+		this.agent.setMaintainContext((context, lifecycle) =>
+			this.#trackMidRunMaintenance(this.#runMidRunMaintenance(context, lifecycle)),
+		);
 		this.#convertToLlm = config.convertToLlm ?? convertToLlm;
 		this.#rebuildSystemPrompt = config.rebuildSystemPrompt;
 		this.#getMcpServerInstructions = config.getMcpServerInstructions;
@@ -1695,9 +1975,16 @@ export class AgentSession {
 
 		// Always subscribe to agent events for internal handling
 		// (session persistence, hooks, auto-compaction, retry logic)
-		this.#unsubscribeAgent = this.agent.subscribe(this.#handleAgentEvent);
+		this.#unsubscribeAgent = this.agent.subscribe(this.#trackAgentEvent);
+
 		// Re-evaluate append-only context mode when the setting changes at runtime.
 		this.#unsubscribeAppendOnly = onAppendOnlyModeChanged(_value => this.#syncAppendOnlyContext(this.model));
+		// SDK ToolSession callbacks capture the just-constructed session. Defer the
+		// initial ask-tool attachment until that capture has been assigned by the
+		// session factory, while retaining the durable emitter created above.
+		queueMicrotask(() => {
+			if (!this.#isDisposed) this.#ensureWorkflowGateAskTool();
+		});
 	}
 
 	/** Model registry for API key resolution and model discovery */
@@ -1795,6 +2082,90 @@ export class AgentSession {
 		return this.#providerSessionState;
 	}
 
+	/** Suspend provider state without closing it while a temporary model is active. */
+	beginTemporaryProviderSessionScope(reason: TemporaryModelReason): TemporaryProviderSessionScope {
+		return this.#beginTemporaryProviderSessionScope(reason, false);
+	}
+
+	#beginTemporaryProviderSessionScope(
+		reason: TemporaryModelReason,
+		autoOwned: boolean,
+	): TemporaryProviderSessionScope {
+		const token: TemporaryProviderSessionScope = Object.freeze({ reason });
+		this.#temporaryProviderSessionScopes.push({
+			token,
+			autoOwned,
+			model: this.model,
+			thinkingLevel: this.#thinkingLevel,
+			fallbackController: this.#defaultFallbackController,
+			providerSessionState: this.#providerSessionState,
+		});
+		this.#rebindProviderSessionState(new Map());
+		const temporaryModel = this.model;
+		this.#defaultFallbackController = new FallbackChainController(
+			{
+				role: "default",
+				entries: temporaryModel ? [formatModelString(temporaryModel)] : [],
+				origin: "temporary-provider-scope",
+				explicitHead: true,
+			},
+			this.settings.get("fallback.maxAttempts"),
+		);
+		return token;
+	}
+
+	/** Returns the topmost auto-owned scope without retaining a separate ownership handle. */
+	#currentAutoTemporaryProviderSessionScope(): TemporaryProviderSessionScopeRecord | undefined {
+		return this.#temporaryProviderSessionScopes.findLast(scope => scope.autoOwned);
+	}
+
+	/** Restore a temporary scope, unwinding any auto-owned scopes above it. */
+	restoreTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): boolean {
+		const scopeIndex = this.#temporaryProviderSessionScopes.findLastIndex(scope => scope.token === token);
+		if (
+			scopeIndex < 0 ||
+			this.#temporaryProviderSessionScopes.slice(scopeIndex + 1).some(scope => !scope.autoOwned)
+		) {
+			return false;
+		}
+		while (this.#temporaryProviderSessionScopes.length > scopeIndex) {
+			this.#restoreTopTemporaryProviderSessionScope();
+		}
+		return true;
+	}
+
+	#restoreTopTemporaryProviderSessionScope(): void {
+		const scope = this.#temporaryProviderSessionScopes.pop();
+		if (!scope) return;
+		this.#closeProviderSessionMap(this.#providerSessionState, "temporary scope restore");
+		this.#rebindProviderSessionState(scope.providerSessionState);
+		this.#defaultFallbackController = scope.fallbackController;
+		const previousEditMode = this.#resolveActiveEditMode();
+		if (scope.model) {
+			this.agent.setModel(scope.model);
+			this.#syncAppendOnlyContext(scope.model);
+		}
+		this.#thinkingLevel = scope.thinkingLevel;
+		this.agent.setThinkingLevel(toReasoningEffort(scope.thinkingLevel));
+		void this.#syncEditToolModeAfterModelChange(previousEditMode);
+	}
+
+	/** Promote a temporary scope. The suspended provider state is permanently closed. */
+	commitTemporaryProviderSessionScope(token: TemporaryProviderSessionScope): boolean {
+		const scope = this.#temporaryProviderSessionScopes.at(-1);
+		if (!scope || scope.token !== token) return false;
+		this.#temporaryProviderSessionScopes.pop();
+		this.#closeProviderSessionMap(scope.providerSessionState, "temporary scope commit");
+		return true;
+	}
+
+	/** Permanently discard every suspended map while retaining the active map. */
+	#commitAllTemporaryProviderSessionScopes(): void {
+		const scopes = this.#temporaryProviderSessionScopes;
+		this.#temporaryProviderSessionScopes = [];
+		for (const scope of scopes) this.#closeProviderSessionMap(scope.providerSessionState, "permanent model change");
+	}
+
 	async buildForkContextSeed(options: ForkContextSeedOptions): Promise<ForkContextSeed> {
 		const maxMessages = Math.min(500, Math.max(0, Math.trunc(options.maxMessages)));
 		const maxTokens = Math.max(0, Math.trunc(options.maxTokens));
@@ -2107,14 +2478,32 @@ export class AgentSession {
 	#queuedExtensionEvents: Promise<void> = Promise.resolve();
 
 	#queueExtensionEvent(event: AgentSessionEvent): Promise<void> {
+		this.#queuedExtensionEventCount++;
 		const emit = async () => {
 			await this.#emitExtensionEvent(event);
 		};
 		const queued = this.#queuedExtensionEvents.then(emit, emit);
 		this.#queuedExtensionEvents = queued.catch(() => {});
+		const settled = () => {
+			this.#queuedExtensionEventCount = Math.max(0, this.#queuedExtensionEventCount - 1);
+			this.#flushPendingAgentEnd();
+		};
+		void queued.then(settled, settled);
 		return queued;
 	}
 
+	#trackAgentEvent = async (event: AgentEvent): Promise<void> => {
+		this.#agentEventHandlersInFlight++;
+		try {
+			await this.#handleAgentEvent(event);
+		} catch (error) {
+			logger.warn("Agent event handler failed", { event: event.type, error: String(error) });
+		} finally {
+			this.#agentEventHandlersInFlight = Math.max(0, this.#agentEventHandlersInFlight - 1);
+			this.#flushPendingAgentEnd();
+		}
+	};
+
 	#persistRuntimeStateInBackground(event: AgentSessionEvent): void {
 		void persistCoordinatorRuntimeStateFromEvent(event, {
 			sessionId: this.sessionId,
@@ -2136,21 +2525,34 @@ export class AgentSession {
 			}
 			return;
 		}
+		// A maintenance agent_end is an internal checkpoint only while another
+		// continuation will follow. An aborted maintenance run is its terminal
+		// settlement and must reach public subscribers.
+		if (event.type === "agent_end" && event.stopReason === "maintenance" && event.maintenanceOutcome !== "aborted")
+			return;
+
 		const persistRuntimeState = () => this.#persistRuntimeStateInBackground(event);
-		// Hold the wire-level agent_end until in-flight prompts unwind. Subscribers
-		// (rpc-mode, ACP, Cursor) treat agent_end as the "session is idle" signal;
-		// emitting while #promptInFlightCount > 0 lets a client fire its next
-		// `prompt` into a session that still reports isStreaming === true. Flush
-		// happens in #endInFlight / #resetInFlight. A later agent_end (e.g. from
-		// an auto-compaction turn that starts before the original prompt unwinds)
-		// supersedes the pending one, which is what subscribers want — they only
-		// care about the final settle.
-		if (event.type === "agent_end" && this.#promptInFlightCount > 0) {
-			void persistRuntimeState();
+		// Hold agent_end until the prompt's finally and all earlier async event work
+		// have unwound. Subscribers treat this event as the ready signal; flushing it
+		// from abort while either barrier is active permits a successor to race the
+		// prior prompt's cleanup.
+		if (
+			event.type === "agent_end" &&
+			(this.#promptInFlightCount > 0 || this.#agentEventHandlersInFlight > 0 || this.#queuedExtensionEventCount > 0)
+		) {
 			this.#pendingAgentEndEmit = event;
 			return;
 		}
 
+		if (event.type === "agent_end") {
+			// Start the durable terminal write before synchronous subscribers can
+			// re-enter prompt(), so a successor's running transition serializes after it.
+			void persistRuntimeState();
+			this.#emit(event);
+			await this.#emitExtensionEvent(event);
+			return;
+		}
+
 		// Local subscribers are part of the AgentSession control path: retryNow(),
 		// auto-continuation gates, goal reminders, and tests all observe these events
 		// synchronously. Coordinator sidecar writes and extension hooks are secondary
@@ -2165,6 +2567,18 @@ export class AgentSession {
 
 	/** Internal handler for agent events - shared by subscribe and reconnect */
 	#handleAgentEvent = async (event: AgentEvent): Promise<void> => {
+		// Record a successful final yield before any asynchronous extension work so a
+		// concurrently delivered agent_end cannot start post-turn maintenance first.
+		if (event.type === "tool_execution_end" && event.toolName === "yield" && !event.isError) {
+			this.#lastSuccessfulYieldToolCallId = event.toolCallId;
+		}
+
+		// Agent listeners run synchronously, but this handler yields while emitting
+		// session events. Capture the maintenance run identity before that yield so
+		// a later raw listener cannot revive a cancelled/replaced continuation.
+		const maintenanceGeneration =
+			event.type === "agent_end" && event.stopReason === "maintenance" ? this.#promptGeneration : undefined;
+		const maintenanceWasDisposed = this.#isDisposed;
 		// When a user message starts, check if it's from either queue and remove it BEFORE emitting
 		// This ensures the UI sees the updated queue state
 		if (event.type === "message_start" && event.message.role === "user") {
@@ -2229,9 +2643,36 @@ export class AgentSession {
 			this.#silentAbortPending = false;
 		}
 
+		// Canonical persistence must happen synchronously before listener work can
+		// await: the EventStream FIFO drain then guarantees tool results and every
+		// steering message are in the branch before a maintenance rewrite starts.
+		if (event.type === "message_end") {
+			if (event.message.role === "hookMessage" || event.message.role === "custom") {
+				const isRosterReminder = event.message.role === "custom" && event.message.customType === "irc-peer-roster";
+				if (!isRosterReminder) {
+					this.sessionManager.appendCustomMessageEntry(
+						event.message.customType,
+						event.message.content,
+						event.message.display,
+						event.message.details,
+						event.message.attribution ?? "agent",
+						getSessionMessageObservationId(event.message),
+					);
+				}
+			} else if (
+				event.message.role === "user" ||
+				event.message.role === "developer" ||
+				event.message.role === "assistant" ||
+				event.message.role === "toolResult" ||
+				event.message.role === "fileMention"
+			) {
+				this.sessionManager.appendMessage(event.message);
+			}
+		}
+
 		// 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
+		// values. The original event.message stays obfuscated so the canonical persistence path above
 		// writes `#HASH#` tokens to the session file; convertToLlm re-obfuscates outbound
 		// traffic on the next turn. Walks text, thinking, and toolCall arguments/intent.
 		let displayEvent: AgentEvent = event;
@@ -2298,9 +2739,6 @@ export class AgentSession {
 				await this.#activatePendingGjcGoalModeRequest();
 			}
 		}
-		if (event.type === "tool_execution_end" && event.toolName === "yield" && !event.isError) {
-			this.#lastSuccessfulYieldToolCallId = event.toolCallId;
-		}
 		if (event.type === "turn_end" && this.#pendingRewindReport) {
 			const report = this.#pendingRewindReport;
 			this.#pendingRewindReport = undefined;
@@ -2431,38 +2869,11 @@ export class AgentSession {
 			this.#maybeAbortStreamingEdit(event, this.#promptGeneration);
 		}
 
-		// Handle session persistence
+		// Handle post-persistence message side effects.
 		if (event.type === "message_end") {
-			// Check if this is a hook/custom message
-			if (event.message.role === "hookMessage" || event.message.role === "custom") {
-				// Roster reminders are request-context-only: never persist them, or a
-				// reload would resurrect stale rosters into agent history.
-				const isRosterReminder = event.message.role === "custom" && event.message.customType === "irc-peer-roster";
-				if (!isRosterReminder) {
-					// Persist as CustomMessageEntry
-					this.sessionManager.appendCustomMessageEntry(
-						event.message.customType,
-						event.message.content,
-						event.message.display,
-						event.message.details,
-						event.message.attribution ?? "agent",
-						getSessionMessageObservationId(event.message),
-					);
-				}
-				if (event.message.role === "custom" && event.message.customType === "ttsr-injection") {
-					this.#markTtsrInjected(this.#extractTtsrRuleNames(event.message.details));
-				}
-			} else if (
-				event.message.role === "user" ||
-				event.message.role === "developer" ||
-				event.message.role === "assistant" ||
-				event.message.role === "toolResult" ||
-				event.message.role === "fileMention"
-			) {
-				// Regular LLM message - persist as SessionMessageEntry
-				this.sessionManager.appendMessage(event.message);
+			if (event.message.role === "custom" && event.message.customType === "ttsr-injection") {
+				this.#markTtsrInjected(this.#extractTtsrRuleNames(event.message.details));
 			}
-			// Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
 
 			// Track assistant message for auto-compaction (checked on agent_end)
 			if (event.message.role === "assistant") {
@@ -2500,13 +2911,6 @@ export class AgentSession {
 					assistantMsg.stopReason !== "aborted" &&
 					this.#retryAttempt > 0
 				) {
-					if (this.#activeRetryFallback && this.model) {
-						await this.#emitSessionEvent({
-							type: "retry_fallback_succeeded",
-							model: formatRetryFallbackSelector(this.model, this.thinkingLevel),
-							role: this.#activeRetryFallback.role,
-						});
-					}
 					await this.#emitSessionEvent({
 						type: "auto_retry_end",
 						success: true,
@@ -2580,6 +2984,29 @@ export class AgentSession {
 
 		// Check auto-retry and auto-compaction after agent completes
 		if (event.type === "agent_end") {
+			// Cooperative mid-run maintenance interruption (issue #2035). The loop
+			// ended the run losslessly after #runMidRunMaintenance did prune/
+			// compact/promote; this handler is the SINGLE continuation owner. Resume
+			// the same run on the rewritten context (no synthetic prompt), skipping
+			// the goal-runtime / skill-state / retry / compaction finalization a
+			// normal agent_end runs — none of that applies to an in-progress run.
+			// "aborted" settles without resuming; the generation guard drops the
+			// continuation if a newer prompt/abort has moved the run on.
+			if (event.stopReason === "maintenance") {
+				this.#lastAssistantMessage = undefined;
+				const outcome = event.maintenanceOutcome;
+				if (
+					outcome &&
+					outcome !== "aborted" &&
+					!maintenanceWasDisposed &&
+					!this.#isDisposed &&
+					maintenanceGeneration !== undefined &&
+					this.#promptGeneration === maintenanceGeneration
+				) {
+					this.#scheduleAgentContinue({ generation: maintenanceGeneration, skipCompactionCheck: true });
+				}
+				return;
+			}
 			const usage = this.getSessionStats().tokens;
 			await this.#goalRuntime.onAgentEnd({
 				currentUsage: {
@@ -2606,6 +3033,7 @@ export class AgentSession {
 			this.#lastAssistantMessage = undefined;
 			if (!msg) {
 				this.#lastSuccessfulYieldToolCallId = undefined;
+				this.#resolveRetry();
 				return;
 			}
 
@@ -2736,6 +3164,7 @@ export class AgentSession {
 				try {
 					await scheduler.wait(delayMs, { signal });
 				} catch {
+					options?.onSkip?.();
 					return;
 				}
 			}
@@ -2757,40 +3186,82 @@ export class AgentSession {
 		delayMs?: number;
 		generation?: number;
 		skipCompactionCheck?: boolean;
+		suppressPredecessorAgentEnd?: boolean;
 		shouldContinue?: () => boolean;
 		onSkip?: (reason: "generation_changed" | "aborted_signal" | "queue_drained") => void;
 		onError?: (error: unknown) => void;
 	}): Promise<void> {
+		const predecessorAgentEndHold = options?.suppressPredecessorAgentEnd
+			? this.#reserveDeferredAgentEndForContinuation()
+			: undefined;
+		let terminalized = false;
+		const skip = (reason: "generation_changed" | "aborted_signal" | "queue_drained") => {
+			if (terminalized) return;
+			terminalized = true;
+			this.#releaseDeferredAgentEndContinuation(predecessorAgentEndHold);
+			options?.onSkip?.(reason);
+		};
+		const fail = (error: unknown) => {
+			if (terminalized) return;
+			terminalized = true;
+			this.#releaseDeferredAgentEndContinuation(predecessorAgentEndHold);
+			logger.warn("agent.continue failed after scheduling", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			options?.onError?.(error);
+		};
 		const scheduledGeneration = options?.generation;
 		const signal = this.#postPromptTasksAbortController.signal;
 		return this.#schedulePostPromptTask(
 			async () => {
-				if (signal.aborted) {
-					options?.onSkip?.("aborted_signal");
-					return;
-				}
-				if (scheduledGeneration !== undefined && this.#promptGeneration !== scheduledGeneration) {
-					options?.onSkip?.("generation_changed");
-					return;
-				}
-				if (options?.shouldContinue && !options.shouldContinue()) {
-					options.onSkip?.("queue_drained");
-					return;
-				}
+				const canContinue = (): boolean => {
+					if (signal.aborted || this.#isDisposed) {
+						skip("aborted_signal");
+						return false;
+					}
+					if (scheduledGeneration !== undefined && this.#promptGeneration !== scheduledGeneration) {
+						skip("generation_changed");
+						return false;
+					}
+					if (options?.shouldContinue && !options.shouldContinue()) {
+						skip("queue_drained");
+						return false;
+					}
+					return true;
+				};
+				if (!canContinue()) return;
 				try {
-					await this.#maybeRestoreRetryFallbackPrimary();
 					if (!options?.skipCompactionCheck) {
 						await this.#checkEstimatedContextBeforePrompt();
+						if (!canContinue()) return;
+					}
+					if (signal.aborted) {
+						skip("aborted_signal");
+						return;
+					}
+					if (scheduledGeneration !== undefined && this.#promptGeneration !== scheduledGeneration) {
+						skip("generation_changed");
+						return;
+					}
+					if (options?.shouldContinue && !options.shouldContinue()) {
+						skip("queue_drained");
+						return;
+					}
+					const predecessorAgentEnd = this.#claimDeferredAgentEndForContinuation(predecessorAgentEndHold);
+					try {
+						await this.agent.continue(this.#managedFallbackPromptOptions());
+					} catch (error) {
+						this.#restoreDeferredAgentEndAfterContinuationFailure(predecessorAgentEnd);
+						throw error;
 					}
-					await this.agent.continue();
 				} catch (error) {
-					logger.warn("agent.continue failed after scheduling", {
-						error: error instanceof Error ? error.message : String(error),
-					});
-					options?.onError?.(error);
+					fail(error);
 				}
 			},
-			{ delayMs: options?.delayMs },
+			{
+				delayMs: options?.delayMs,
+				onSkip: () => skip("aborted_signal"),
+			},
 		);
 	}
 
@@ -2838,6 +3309,8 @@ export class AgentSession {
 			this.#scheduleAgentContinue({
 				delayMs: 100,
 				generation,
+				suppressPredecessorAgentEnd: true,
+
 				onSkip: reason => this.#logCompactionContinuationSkipped("overflow_retry", reason),
 				onError: error => this.#logCompactionContinuationError("overflow_retry", error),
 			});
@@ -2854,6 +3327,7 @@ export class AgentSession {
 	}
 
 	#scheduleAutoContinuePrompt(generation: number): void {
+		const predecessorAgentEndHold = this.#reserveDeferredAgentEndForContinuation();
 		const continuePrompt = async () => {
 			await this.#promptWithMessage(
 				{
@@ -2863,26 +3337,32 @@ export class AgentSession {
 					timestamp: Date.now(),
 				},
 				autoContinuePrompt,
-				{ skipPostPromptRecoveryWait: true, skipCompactionCheck: true },
+				{
+					skipPostPromptRecoveryWait: true,
+					skipCompactionCheck: true,
+					predecessorAgentEndHold,
+				},
 			);
 		};
 		const scheduledGeneration = generation;
 		const signal = this.#postPromptTasksAbortController.signal;
 		this.#trackPostPromptTask(
 			(async () => {
-				await Promise.resolve();
-				if (signal.aborted) {
-					this.#logCompactionContinuationSkipped("auto_continue_prompt", "aborted_signal");
-					return;
-				}
-				if (this.#promptGeneration !== scheduledGeneration) {
-					this.#logCompactionContinuationSkipped("auto_continue_prompt", "generation_changed");
-					return;
-				}
 				try {
+					await Promise.resolve();
+					if (signal.aborted) {
+						this.#logCompactionContinuationSkipped("auto_continue_prompt", "aborted_signal");
+						return;
+					}
+					if (this.#promptGeneration !== scheduledGeneration) {
+						this.#logCompactionContinuationSkipped("auto_continue_prompt", "generation_changed");
+						return;
+					}
 					await continuePrompt();
 				} catch (error) {
 					this.#logCompactionContinuationError("auto_continue_prompt", error);
+				} finally {
+					this.#releaseDeferredAgentEndContinuation(predecessorAgentEndHold);
 				}
 			})(),
 		);
@@ -2895,11 +3375,13 @@ export class AgentSession {
 
 		const pendingTasks = Array.from(this.#postPromptTasks);
 		if (pendingTasks.length === 0) {
+			this.#releaseDeferredAgentEndContinuations();
 			this.#resolvePostPromptTasks();
 			return;
 		}
 
 		await Promise.allSettled(pendingTasks);
+		this.#releaseDeferredAgentEndContinuations();
 		if (this.#postPromptTasks.size === 0) {
 			this.#resolvePostPromptTasks();
 		}
@@ -2909,6 +3391,7 @@ export class AgentSession {
 		this.#postPromptTasksAbortController.abort();
 		this.#postPromptTasksAbortController = new AbortController();
 		this.#postPromptTasks.clear();
+		this.#releaseDeferredAgentEndContinuations();
 		this.#resolveTtsrResume();
 		this.#resolvePostPromptTasks();
 	}
@@ -3733,6 +4216,7 @@ export class AgentSession {
 	subscribe(listener: AgentSessionEventListener): () => void {
 		this.#eventListeners.push(listener);
 		this.#rebuildEventListenerSnapshot();
+		for (const event of this.#pendingFallbackSwitches.splice(0)) listener(event);
 
 		// Return unsubscribe function for this specific listener
 		return () => {
@@ -3750,6 +4234,7 @@ export class AgentSession {
 	 * Used internally during operations that need to pause event processing.
 	 */
 	#disconnectFromAgent(): void {
+		this.#abortActiveMidRunBarriers();
 		if (this.#unsubscribeAgent) {
 			this.#unsubscribeAgent();
 			this.#unsubscribeAgent = undefined;
@@ -3762,7 +4247,7 @@ export class AgentSession {
 	 */
 	#reconnectToAgent(): void {
 		if (this.#unsubscribeAgent) return; // Already connected
-		this.#unsubscribeAgent = this.agent.subscribe(this.#handleAgentEvent);
+		this.#unsubscribeAgent = this.agent.subscribe(this.#trackAgentEvent);
 	}
 
 	/**
@@ -3803,12 +4288,51 @@ export class AgentSession {
 	 * Remove all listeners, flush pending writes, and disconnect from agent.
 	 * Call this when completely done with the session.
 	 */
-	async dispose(): Promise<void> {
+	dispose(): Promise<void> {
+		this.#evalExecutionDisposing = true;
+		if (this.#disposePromise) return this.#disposePromise;
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		this.#disposePromise = promise;
+		void this.#dispose().then(resolve, reject);
+		return promise;
+	}
+
+	async #dispose(): Promise<void> {
+		const admissionClosed = this.#closeSessionAdmission();
 		this.#isDisposed = true;
+		// Reject new direct Python starts as soon as disposal begins (synchronously,
+		// before any await) so callers cannot race a start against teardown.
+		this.#evalExecutionDisposing = true;
+		this.#abortActiveMidRunBarriers();
+		this.abortCompaction();
+		this.agent.abort();
+		// Disconnect the Agent event bridge NOW — before the maintenance join and the
+		// bounded idle / forceAbort below — so no agent_end emitted during teardown
+		// (including the one forceAbort emits) can re-enter #handleAgentEvent and start
+		// fresh post-turn maintenance or mutate the closing session. Maintenance promises
+		// are joined directly (not via events), so this does not affect the join.
+		this.#disconnectFromAgent();
+		// R2-5: join any in-flight mid-run maintenance invocation before teardown so the
+		// abort-aware maintenance promise (already aborted above) settles and cannot touch
+		// torn-down state afterward.
+		await this.#waitForActiveMidRunMaintenance();
+		// R2-5: give the aborted Agent run a bounded chance to settle, then force-
+		// invalidate its run id so an abort-ignoring provider/tool cannot emit a late
+		// message_end after teardown. Mirrors AgentSession.abort({ timeoutMs }).
+		const disposeIdleSettled = await Promise.race([
+			this.agent.waitForIdle().then(
+				() => true,
+				() => true,
+			),
+			Bun.sleep(2_000).then(() => false),
+		]);
+		if (!disposeIdleSettled) this.agent.forceAbort("Session disposed");
+		await admissionClosed;
+		this.#workflowGateEmitter?.fence?.();
 		this.#pendingBackgroundExchanges = [];
 		this.yieldQueue.clear();
+
 		this.agent.setOnBeforeYield(undefined);
-		this.#evalExecutionDisposing = true;
 		try {
 			if (this.#extensionRunner?.hasHandlers("session_shutdown")) {
 				await this.#extensionRunner.emit({ type: "session_shutdown" });
@@ -3868,12 +4392,14 @@ export class AgentSession {
 		await disposeKernelSessionsByOwner(this.#evalKernelOwnerId);
 		await disposeVmContextsByOwner(this.#evalKernelOwnerId);
 		this.#releasePowerAssertion();
+		// Disconnect the agent event listener BEFORE closing session resources so a late
+		// provider/tool message_end cannot append to the closing SessionManager.
+		this.#disconnectFromAgent();
 		await this.sessionManager.close();
 		this.#closeAllProviderSessions("dispose");
 		const hindsightState = this.setHindsightSessionState(undefined);
 		await hindsightState?.flushRetainQueue();
 		hindsightState?.dispose();
-		this.#disconnectFromAgent();
 		if (this.#unsubscribeAppendOnly) {
 			this.#unsubscribeAppendOnly();
 			this.#unsubscribeAppendOnly = undefined;
@@ -3926,20 +4452,27 @@ export class AgentSession {
 		await Promise.race([work, Bun.sleep(timeoutMs)]);
 	}
 
-	#closeAllProviderSessions(reason: string): void {
-		for (const [providerKey, state] of this.#providerSessionState) {
+	#rebindProviderSessionState(providerSessionState: Map<string, ProviderSessionState>): void {
+		this.#providerSessionState = providerSessionState;
+		this.agent.providerSessionState = providerSessionState;
+	}
+
+	#closeProviderSessionMap(providerSessionState: Map<string, ProviderSessionState>, reason: string): void {
+		for (const [providerKey, state] of providerSessionState) {
 			try {
 				state.close();
 			} catch (error) {
-				logger.warn("Failed to close provider session state", {
-					providerKey,
-					reason,
-					error: String(error),
-				});
+				logger.warn("Failed to close provider session state", { providerKey, reason, error: String(error) });
 			}
 		}
+		providerSessionState.clear();
+	}
 
-		this.#providerSessionState.clear();
+	#closeAllProviderSessions(reason: string): void {
+		const maps = new Set<Map<string, ProviderSessionState>>([this.#providerSessionState]);
+		for (const scope of this.#temporaryProviderSessionScopes) maps.add(scope.providerSessionState);
+		this.#temporaryProviderSessionScopes = [];
+		for (const providerSessionState of maps) this.#closeProviderSessionMap(providerSessionState, reason);
 	}
 
 	// =========================================================================
@@ -4031,8 +4564,8 @@ export class AgentSession {
 	}
 
 	/** Single point for invalidating cached discovery indices. Call after any change that can
-	 *  affect which tools should be discoverable: registry mutations (refreshMCPTools,
-	 *  refreshRpcHostTools) or active-tool mutations (#applyActiveToolsByName). */
+	 *  affect which tools should be discoverable: registry mutations (refreshMCPTools)
+	 *  or active-tool mutations (#applyActiveToolsByName). */
 	#invalidateDiscoveryCaches(): void {
 		this.#discoverableMCPSearchIndex = null;
 		this.#discoverableToolSearchIndex = null;
@@ -4136,6 +4669,35 @@ export class AgentSession {
 		return this.#foregroundBashBackgroundRequestHandler !== undefined;
 	}
 
+	/** Set the SDK permission policy used by guarded ACP tool execution. */
+	setSdkPermissionMode(mode: "prompt" | "allow" | "deny"): void {
+		this.#sdkPermissionMode = mode;
+	}
+
+	/** Current SDK permission policy for guarded ACP tool execution. */
+	get sdkPermissionMode(): "prompt" | "allow" | "deny" {
+		return this.#sdkPermissionMode;
+	}
+
+	/** Register or clear the SDK reverse permission provider for this session. */
+	setSdkPermissionProvider(
+		provider:
+			| ((
+					toolCall: ClientBridgePermissionToolCall,
+					options: ClientBridgePermissionOption[],
+					signal?: AbortSignal,
+			  ) => Promise<ClientBridgePermissionOutcome>)
+			| undefined,
+	): void {
+		this.#sdkPermissionProvider = provider;
+		this.#acpPermissionDecisions.clear();
+		this.#acpPermissionWrapperVersion++;
+		const activeTools = this.getActiveToolNames()
+			.map(name => this.#toolRegistry.get(name))
+			.filter((tool): tool is AgentTool => tool !== undefined);
+		this.#setGuardedAgentTools(activeTools);
+	}
+
 	/**
 	 * Ask the active managed foreground bash call to return as a background job.
 	 * Returns false when no supported foreground tool is currently backgroundable.
@@ -4165,6 +4727,55 @@ export class AgentSession {
 		return resolveEditMode(this.#getEditModeSession());
 	}
 
+	#resolveEditModeForModel(model: Model): EditMode {
+		return resolveEditMode({
+			settings: this.settings,
+			getActiveModelString: () => formatModelString(model),
+		});
+	}
+
+	async #prepareDefaultModelSelectionPrompt(model: Model): Promise<string[] | undefined> {
+		if (!this.#rebuildSystemPrompt) return undefined;
+		if (!this.getActiveToolNames().includes("edit")) return undefined;
+		if (this.#resolveActiveEditMode() === this.#resolveEditModeForModel(model)) return undefined;
+		const built = await this.#rebuildSystemPrompt(this.getActiveToolNames(), this.#toolRegistry, model);
+		return built.systemPrompt;
+	}
+
+	#reserveBaseSystemPromptGeneration(): number {
+		this.#baseSystemPromptGeneration++;
+		return this.#baseSystemPromptGeneration;
+	}
+
+	async #runAdmittedBaseSystemPromptRebuild<T>(build: () => Promise<T>): Promise<T> {
+		const completion = Promise.withResolvers<void>();
+		this.#pendingBaseSystemPromptRebuilds.add(completion.promise);
+		try {
+			return await build();
+		} finally {
+			completion.resolve();
+			this.#pendingBaseSystemPromptRebuilds.delete(completion.promise);
+		}
+	}
+
+	async #waitForAdmittedBaseSystemPromptRebuilds(): Promise<void> {
+		while (this.#pendingBaseSystemPromptRebuilds.size > 0) {
+			await Promise.all(this.#pendingBaseSystemPromptRebuilds);
+		}
+	}
+
+	#applyPreparedDefaultModelSelectionPrompt(systemPrompt: string[] | undefined): void {
+		if (!systemPrompt) return;
+		this.#reserveBaseSystemPromptGeneration();
+		this.#baseSystemPrompt = systemPrompt;
+		this.agent.setSystemPrompt(this.#baseSystemPrompt);
+		const activeToolNames = this.getActiveToolNames();
+		const activeTools = activeToolNames
+			.map(name => this.#toolRegistry.get(name))
+			.filter((tool): tool is AgentTool => tool != null);
+		this.#lastAppliedToolSignature = this.#computeAppliedToolSignature(activeToolNames, activeTools);
+	}
+
 	async #syncEditToolModeAfterModelChange(previousEditMode: EditMode): Promise<void> {
 		const currentEditMode = this.#resolveActiveEditMode();
 		if (previousEditMode !== currentEditMode && this.getActiveToolNames().includes("edit")) {
@@ -4335,16 +4946,20 @@ export class AgentSession {
 		return [...new Set(activated)];
 	}
 
-	/**
-	 * Wrap a tool with a permission-gate proxy when an ACP client is connected.
-	 * Only wraps tools whose name is in PERMISSION_REQUIRED_TOOLS and only when
-	 * the bridge exposes `requestPermission`. No-ops for all other cases.
-	 */
+	/** Wrap guarded tools so SDK permission modes remain fail-closed without a reverse provider. */
 	#wrapToolForAcpPermission<T extends AgentTool>(tool: T): T {
 		const bridge = this.#clientBridge;
-		// Match the capability+method gating pattern used by read/write/bash.
-		if (!bridge?.capabilities.requestPermission || !bridge.requestPermission) return tool;
+		const requestPermission =
+			this.#sdkPermissionProvider ??
+			(bridge?.capabilities.requestPermission && bridge.requestPermission
+				? (
+						toolCall: ClientBridgePermissionToolCall,
+						options: ClientBridgePermissionOption[],
+						signal?: AbortSignal,
+					) => bridge.requestPermission!(toolCall, options, signal)
+				: undefined);
 		if (!PERMISSION_REQUIRED_TOOLS.has(tool.name)) return tool;
+
 		return new Proxy(tool, {
 			get: (target, prop) => {
 				if (prop !== "execute") return Reflect.get(target, prop, target);
@@ -4367,6 +4982,17 @@ export class AgentSession {
 					const commandContent = command
 						? [{ type: "content" as const, content: { type: "text" as const, text: `$ ${command}` } }]
 						: undefined;
+					if (this.#sdkPermissionMode === "allow") {
+						return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
+					}
+					if (this.#sdkPermissionMode === "deny") {
+						throw new ToolError(`Tool call rejected by session permission policy (${target.name})`);
+					}
+					if (!requestPermission) {
+						throw new ToolError(
+							`Tool call rejected because no permission provider is connected (${target.name})`,
+						);
+					}
 					// Short-circuit on persisted decisions.
 					const persisted = this.#acpPermissionDecisions.get(permissionIntent.cacheKey);
 					if (persisted === "allow_always") {
@@ -4386,7 +5012,7 @@ export class AgentSession {
 					signal?.addEventListener("abort", onAbort, { once: true });
 					let raced: PermissionRaceResult;
 					try {
-						const permissionPromise = bridge.requestPermission!(
+						const permissionPromise = requestPermission(
 							{
 								toolCallId,
 								toolName: target.name,
@@ -4465,13 +5091,14 @@ export class AgentSession {
 	#guardedToolWrapperCacheKey(): string {
 		const bridge = this.#clientBridge;
 		const acpEnabled = Boolean(bridge?.capabilities.requestPermission && bridge.requestPermission);
+		const sdkEnabled = this.#sdkPermissionProvider !== undefined;
 		const activeSkill = this.#activeSkillState?.skill ?? "";
 		const activeSkillSession = this.#activeSkillState?.sessionId ?? "";
 		return [
 			"deep-interview-mutation-v1",
 			"ultragoal-ask-v1",
 			`active=${activeSkill}:${activeSkillSession}`,
-			`acp=${acpEnabled ? "on" : "off"}:${this.#acpPermissionWrapperVersion}`,
+			`acp=${acpEnabled ? "on" : "off"}:sdk=${sdkEnabled ? "on" : "off"}:${this.#acpPermissionWrapperVersion}`,
 		].join("|");
 	}
 
@@ -4532,6 +5159,13 @@ export class AgentSession {
 				this.#selectedDiscoveredToolNames.delete(name);
 			}
 		}
+		const signature = this.#computeAppliedToolSignature(validToolNames, tools);
+		const promptRelevantToolsChanged =
+			signature !== (this.#pendingAppliedToolSignature ?? this.#lastAppliedToolSignature);
+		if (promptRelevantToolsChanged) {
+			this.#defaultModelSelectionMutationRevision++;
+			this.#pendingAppliedToolSignature = signature;
+		}
 		this.#setGuardedAgentTools(tools);
 
 		// Active tool set changed → discoverable tool list (which excludes already-active tools)
@@ -4543,14 +5177,27 @@ export class AgentSession {
 		// `refreshMCPTools` -> `#applyActiveToolsByName` even though the resulting
 		// tool list is byte-identical. Skipping the rebuild keeps the system prompt
 		// stable, which is required for Anthropic prompt caching to keep hitting.
-		if (this.#rebuildSystemPrompt) {
-			const signature = this.#computeAppliedToolSignature(validToolNames, tools);
-			if (signature !== this.#lastAppliedToolSignature) {
-				const built = await this.#rebuildSystemPrompt(validToolNames, this.#toolRegistry);
-				this.#baseSystemPrompt = built.systemPrompt;
-				this.agent.setSystemPrompt(this.#baseSystemPrompt);
-				this.#lastAppliedToolSignature = signature;
+		if (promptRelevantToolsChanged && this.#rebuildSystemPrompt) {
+			const generation = this.#reserveBaseSystemPromptGeneration();
+			try {
+				const built = await this.#runAdmittedBaseSystemPromptRebuild(() =>
+					this.#rebuildSystemPrompt!(validToolNames, this.#toolRegistry),
+				);
+				if (generation === this.#baseSystemPromptGeneration) {
+					this.#baseSystemPrompt = built.systemPrompt;
+					this.agent.setSystemPrompt(this.#baseSystemPrompt);
+					this.#lastAppliedToolSignature = signature;
+					this.#pendingAppliedToolSignature = undefined;
+				}
+			} catch (error) {
+				if (generation === this.#baseSystemPromptGeneration) {
+					this.#pendingAppliedToolSignature = undefined;
+				}
+				throw error;
 			}
+		} else if (promptRelevantToolsChanged) {
+			this.#lastAppliedToolSignature = signature;
+			this.#pendingAppliedToolSignature = undefined;
 		}
 		if (options?.persistMCPSelection !== false) {
 			this.#persistSelectedMCPToolNamesIfChanged(previousSelectedMCPToolNames);
@@ -4629,7 +5276,20 @@ export class AgentSession {
 	async refreshBaseSystemPrompt(): Promise<void> {
 		if (!this.#rebuildSystemPrompt) return;
 		const activeToolNames = this.getActiveToolNames();
-		const built = await this.#rebuildSystemPrompt(activeToolNames, this.#toolRegistry);
+		const generation = this.#reserveBaseSystemPromptGeneration();
+		this.#defaultModelSelectionMutationRevision++;
+		let built: { systemPrompt: string[] };
+		try {
+			built = await this.#runAdmittedBaseSystemPromptRebuild(() =>
+				this.#rebuildSystemPrompt!(activeToolNames, this.#toolRegistry),
+			);
+		} catch (error) {
+			if (generation === this.#baseSystemPromptGeneration) {
+				this.#pendingAppliedToolSignature = undefined;
+			}
+			throw error;
+		}
+		if (generation !== this.#baseSystemPromptGeneration) return;
 		this.#baseSystemPrompt = built.systemPrompt;
 		this.agent.setSystemPrompt(this.#baseSystemPrompt);
 		// Refresh the cached signature so a subsequent `#applyActiveToolsByName` with
@@ -4639,6 +5299,7 @@ export class AgentSession {
 			.map(name => this.#toolRegistry.get(name))
 			.filter((tool): tool is AgentTool => tool != null);
 		this.#lastAppliedToolSignature = this.#computeAppliedToolSignature(activeToolNames, activeTools);
+		this.#pendingAppliedToolSignature = undefined;
 	}
 
 	async #buildSystemPromptForAgentStart(promptText: string): Promise<string[]> {
@@ -4686,7 +5347,7 @@ export class AgentSession {
 	 * cache per-tool strings without preserving this property.
 	 *
 	 * Inputs NOT covered: tool input schemas; memory instructions read from disk;
-	 * and SDK-init-time closure constants in `sdk.ts` (`repeatToolDescriptions`,
+	 * and SDK-init-time closure constants in `sdk/session.ts` (`repeatToolDescriptions`,
 	 * `eagerTasks`, `intentField`, `mcpDiscoveryEnabled`, `secretsEnabled`). The
 	 * closure-captured ones cannot change at runtime regardless of skip behavior.
 	 * For everything else, callers must explicitly call `refreshBaseSystemPrompt()`
@@ -4784,57 +5445,6 @@ export class AgentSession {
 		await this.#applyActiveToolsByName(nextActive, { previousSelectedMCPToolNames });
 	}
 
-	/**
-	 * Replace RPC host-owned tools and refresh the active tool set before the next model call.
-	 */
-	async refreshRpcHostTools(rpcTools: AgentTool[]): Promise<void> {
-		const nextToolNames = rpcTools.map(tool => tool.name);
-		const uniqueToolNames = new Set(nextToolNames);
-		if (uniqueToolNames.size !== nextToolNames.length) {
-			throw new Error("RPC host tool names must be unique");
-		}
-		if (uniqueToolNames.has("ask")) {
-			throw new Error('RPC host tool "ask" is reserved and cannot be supplied by the host');
-		}
-
-		for (const name of uniqueToolNames) {
-			if (this.#toolRegistry.has(name) && !this.#rpcHostToolNames.has(name)) {
-				throw new Error(`RPC host tool "${name}" conflicts with an existing tool`);
-			}
-		}
-
-		const previousRpcHostToolNames = new Set(this.#rpcHostToolNames);
-		const previousActiveToolNames = this.getActiveToolNames();
-		for (const name of previousRpcHostToolNames) {
-			this.#toolRegistry.delete(name);
-		}
-		this.#rpcHostToolNames.clear();
-
-		for (const tool of rpcTools) {
-			const finalTool = (
-				this.#extensionRunner ? new ExtensionToolWrapper(tool, this.#extensionRunner) : tool
-			) as AgentTool;
-			this.#toolRegistry.set(finalTool.name, finalTool);
-			this.#rpcHostToolNames.add(finalTool.name);
-		}
-
-		// Registry contents changed — invalidate discovery caches so the next BM25 lookup sees
-		// the new RPC-host tool set. (#applyActiveToolsByName below also invalidates, but doing
-		// it here too keeps the contract local to "registry mutated".)
-		this.#invalidateDiscoveryCaches();
-
-		const activeNonRpcToolNames = previousActiveToolNames.filter(name => !previousRpcHostToolNames.has(name));
-		const preservedRpcToolNames = previousActiveToolNames.filter(
-			name => previousRpcHostToolNames.has(name) && this.#rpcHostToolNames.has(name),
-		);
-		const autoActivatedRpcToolNames = rpcTools
-			.filter(tool => !tool.hidden && !previousRpcHostToolNames.has(tool.name))
-			.map(tool => tool.name);
-		await this.#applyActiveToolsByName(
-			Array.from(new Set([...activeNonRpcToolNames, ...preservedRpcToolNames, ...autoActivatedRpcToolNames])),
-		);
-	}
-
 	async #hasActiveGjcSubskillTools(parent: string, sessionId: string | undefined): Promise<boolean> {
 		if (!parent.trim()) return false;
 		const cwd = this.sessionManager.getCwd();
@@ -4979,7 +5589,13 @@ export class AgentSession {
 		if (!canContinuePersistedHistory(this.agent.state.messages)) {
 			throw new Error("Cannot continue from persisted message history");
 		}
-		await this.agent.continue();
+		this.#beginInFlight();
+		try {
+			await this.agent.continue(this.#managedFallbackPromptOptions());
+			await this.#waitForPostPromptRecovery();
+		} finally {
+			this.#endInFlight();
+		}
 	}
 
 	buildDisplaySessionContext(): SessionContext {
@@ -5090,6 +5706,19 @@ export class AgentSession {
 		return this.#planModeState;
 	}
 
+	/** Live SDK configuration values exposed through the session query surface. */
+	getSdkConfigItems(): Record<string, string> {
+		const model = this.model;
+		return {
+			mode: this.#planModeState?.enabled ? "plan" : "default",
+			...(model ? { model: `${model.provider}/${model.id}` } : {}),
+			thinking: this.#thinkingLevel ?? "off",
+			steeringMode: this.steeringMode,
+			followUpMode: this.followUpMode,
+			interruptMode: this.interruptMode,
+		};
+	}
+
 	setPlanModeState(state: PlanModeState | undefined): void {
 		this.#planModeState = state;
 		if (state?.enabled) {
@@ -5098,6 +5727,114 @@ export class AgentSession {
 		}
 	}
 
+	async invokeSkill(
+		name: string,
+		args = "",
+	): Promise<{ name: string; path: string; args?: string; lineCount?: number }> {
+		const skillName = name.trim();
+		if (!skillName) throw Object.assign(new Error("skill.invoke requires a skill name."), { code: "invalid_input" });
+		if (typeof args !== "string")
+			throw Object.assign(new Error("skill.invoke args must be a string."), { code: "invalid_input" });
+		const skill = this.skills.find(candidate => candidate.name === skillName);
+		if (!skill) throw Object.assign(new Error(`Skill ${skillName} was not found.`), { code: "invalid_input" });
+		const activation = await resolveSubskillActivationForSkillInvocation({
+			cwd: this.sessionManager.getCwd(),
+			sessionId: this.sessionId,
+			skillName: skill.name,
+			args,
+		});
+		const built = await buildSkillPromptMessage(skill, activation.cleanedArgs, {
+			subskillActivation: activation.activation,
+			subskillActivationSet: activation.activeSubskillsToPersist,
+			cwd: this.sessionManager.getCwd(),
+			sessionId: this.sessionId,
+		});
+		await this.promptCustomMessage({
+			customType: SKILL_PROMPT_MESSAGE_TYPE,
+			content: built.message,
+			display: true,
+			details: built.details,
+			attribution: "user",
+		});
+		return {
+			name: skill.name,
+			path: skill.filePath,
+			args: activation.cleanedArgs || undefined,
+			lineCount: built.details.lineCount,
+		};
+	}
+
+	setSdkPlanMode(on: boolean): PlanModeState | undefined {
+		if (typeof on !== "boolean")
+			throw Object.assign(new Error("mode.plan.set requires a boolean on value."), { code: "invalid_input" });
+		if (!on) {
+			this.setPlanModeState(undefined);
+			return undefined;
+		}
+		const state: PlanModeState = { enabled: true, planFilePath: "local://PLAN.md", workflow: "parallel" };
+		this.setPlanModeState(state);
+		return state;
+	}
+
+	async operateGoal(
+		op: "create" | "get" | "resume" | "pause" | "complete" | "drop",
+		objective?: string,
+	): Promise<unknown> {
+		try {
+			switch (op) {
+				case "create":
+					return await this.#goalRuntime.createGoal({ objective: objective ?? "" });
+				case "get":
+					return this.getGoalModeState();
+				case "resume":
+					return await this.#goalRuntime.resumeGoal();
+				case "pause":
+					return await this.#goalRuntime.pauseGoal();
+				case "complete":
+					return await this.#goalRuntime.completeGoalFromTool();
+				case "drop":
+					return await this.#goalRuntime.dropGoal();
+			}
+		} catch (error) {
+			throw Object.assign(new Error(error instanceof Error ? error.message : "Goal operation failed."), {
+				code: "invalid_input",
+			});
+		}
+	}
+
+	getTranscript(): Array<{ id: string; role: string; textSummary: string; ts: string; body: string }> {
+		return this.sessionManager.getEntries().flatMap(entry => {
+			if (entry.type !== "message") return [];
+			const message = entry.message as unknown as { role?: unknown; content?: unknown };
+			const body =
+				typeof message.content === "string"
+					? message.content
+					: Array.isArray(message.content)
+						? message.content
+								.map(part =>
+									typeof part === "object" && part !== null && "text" in part && typeof part.text === "string"
+										? part.text
+										: "",
+								)
+								.filter(Boolean)
+								.join("\n")
+						: "";
+			return [
+				{
+					id: entry.id,
+					role: typeof message.role === "string" ? message.role : "unknown",
+					textSummary: body.slice(0, 500),
+					ts: entry.timestamp,
+					body,
+				},
+			];
+		});
+	}
+
+	getTranscriptBody(entryId: string): string | undefined {
+		return this.getTranscript().find(entry => entry.id === entryId)?.body;
+	}
+
 	getGoalModeState(): GoalModeState | undefined {
 		return this.#goalModeState;
 	}
@@ -5114,6 +5851,36 @@ export class AgentSession {
 		return getAskAnswerSourceFromRegistry(this.sessionId);
 	}
 
+	#bindWorkflowGateEmitter(previousSessionId?: string, previousEmitter = this.#workflowGateEmitter): void {
+		const sessionId = this.sessionManager.getSessionId();
+		assertNonEmptyGjcSessionId(sessionId, "AgentSession workflow-gate session");
+		const gateStore = this.sessionManager.isPersisted()
+			? new FileGateStore(path.join(sessionStateDir(this.sessionManager.getCwd(), sessionId), "workflow-gates.json"))
+			: new MemoryGateStore();
+		const successorEmitter = new BrokerWorkflowGateEmitter(sessionId, gateStore);
+		previousEmitter?.fence?.();
+		if (previousEmitter && !previousEmitter.fence) {
+			for (const gate of previousEmitter.listPendingGates?.() ?? []) previousEmitter.quarantineGate?.(gate.gate_id);
+		}
+		if (previousSessionId) notifyWorkflowGateEmitterChanged(previousSessionId, undefined);
+		this.setWorkflowGateEmitter(successorEmitter);
+	}
+
+	#suspendWorkflowGateEmitter(sessionId: string): WorkflowGateEmitter | undefined {
+		const emitter = this.#workflowGateEmitter;
+		if (!emitter) return undefined;
+		emitter.suspend?.();
+		this.#workflowGateEmitter = undefined;
+		notifyWorkflowGateEmitterChanged(sessionId, undefined);
+		return emitter;
+	}
+
+	#restoreWorkflowGateEmitter(emitter: WorkflowGateEmitter | undefined): void {
+		if (!emitter) return;
+		emitter.resume?.();
+		this.setWorkflowGateEmitter(emitter);
+	}
+
 	setWorkflowGateEmitter(emitter: WorkflowGateEmitter | undefined): void {
 		this.#workflowGateEmitter = emitter;
 		notifyWorkflowGateEmitterChanged(this.sessionId, emitter);
@@ -5504,48 +6271,60 @@ export class AgentSession {
 			if (workflowIntentDiff) {
 				this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
 			}
+			options?.onPreflightAccepted?.();
 			return;
 		}
 
-		if (workflowIntentDiff) {
-			this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
-		}
+		const admissionGeneration = this.#promptGeneration;
+		const admissionSignal = this.#promptPreflightAbortController.signal;
+		await this.#withSessionAdmission("prompt", async admission => {
+			this.#throwIfPromptPreflightCancelled(admissionGeneration, admissionSignal);
+			if (workflowIntentDiff) {
+				this.sessionManager.appendCustomEntry(WORKFLOW_INTENT_DIFF_CUSTOM_TYPE, workflowIntentDiff);
+			}
 
-		// Skip eager todo prelude when the user has already queued a directive
-		const hasPendingUserDirective = this.#toolChoiceQueue.inspect().includes("user-force");
-		const eagerTodoPrelude =
-			!options?.synthetic && !hasPendingUserDirective ? this.#createEagerTodoPrelude(expandedText) : undefined;
+			// Skip eager todo prelude when the user has already queued a directive
+			const hasPendingUserDirective = this.#toolChoiceQueue.inspect().includes("user-force");
+			const eagerTodoPrelude =
+				!options?.synthetic && !hasPendingUserDirective ? this.#createEagerTodoPrelude(expandedText) : undefined;
 
-		const userContent: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
-		if (options?.images) {
-			userContent.push(...options.images);
-		}
+			const userContent: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
+			if (options?.images) {
+				userContent.push(...options.images);
+			}
 
-		const promptAttribution = options?.attribution ?? (options?.synthetic ? "agent" : "user");
-		const message = options?.synthetic
-			? { role: "developer" as const, content: userContent, attribution: promptAttribution, timestamp: Date.now() }
-			: { role: "user" as const, content: userContent, attribution: promptAttribution, timestamp: Date.now() };
-		await this.refreshGjcSubskillTools();
+			const promptAttribution = options?.attribution ?? (options?.synthetic ? "agent" : "user");
+			const message = options?.synthetic
+				? {
+						role: "developer" as const,
+						content: userContent,
+						attribution: promptAttribution,
+						timestamp: Date.now(),
+					}
+				: { role: "user" as const, content: userContent, attribution: promptAttribution, timestamp: Date.now() };
+			await this.refreshGjcSubskillTools();
 
-		if (eagerTodoPrelude?.toolChoice) {
-			this.#toolChoiceQueue.pushOnce(eagerTodoPrelude.toolChoice, {
-				label: "eager-todo",
-			});
-		}
+			if (eagerTodoPrelude?.toolChoice) {
+				this.#toolChoiceQueue.pushOnce(eagerTodoPrelude.toolChoice, {
+					label: "eager-todo",
+				});
+			}
 
-		try {
-			await this.#promptWithMessage(message, expandedText, {
-				...options,
-				prependMessages: eagerTodoPrelude ? [eagerTodoPrelude.message] : undefined,
-			});
-		} finally {
-			// Clean up residual eager-todo directive if the prompt never consumed it
-			// (e.g., compaction aborted, validation failed).
-			this.#toolChoiceQueue.removeByLabel("eager-todo");
-		}
-		if (!options?.synthetic) {
-			await this.#enforcePlanModeToolDecision();
-		}
+			try {
+				await this.#promptWithMessage(message, expandedText, {
+					...options,
+					prependMessages: eagerTodoPrelude ? [eagerTodoPrelude.message] : undefined,
+					admissionLease: admission,
+				});
+			} finally {
+				// Clean up residual eager-todo directive if the prompt never consumed it
+				// (e.g., compaction aborted, validation failed).
+				this.#toolChoiceQueue.removeByLabel("eager-todo");
+			}
+			if (!options?.synthetic) {
+				await this.#enforcePlanModeToolDecision();
+			}
+		});
 	}
 
 	async #syncSkillPromptActiveState(
@@ -5636,36 +6415,53 @@ export class AgentSession {
 			return;
 		}
 
-		const customMessage: CustomMessage<T> = {
-			role: "custom",
-			customType: message.customType,
-			content: message.content,
-			display: message.display,
-			details: message.details,
-			attribution: message.attribution ?? "agent",
-			timestamp: Date.now(),
-		};
+		const admissionGeneration = this.#promptGeneration;
+		const admissionSignal = this.#promptPreflightAbortController.signal;
+		await this.#withSessionAdmission("prompt", async admission => {
+			this.#throwIfPromptPreflightCancelled(admissionGeneration, admissionSignal);
+			const customMessage: CustomMessage<T> = {
+				role: "custom",
+				customType: message.customType,
+				content: message.content,
+				display: message.display,
+				details: message.details,
+				attribution: message.attribution ?? "agent",
+				timestamp: Date.now(),
+			};
 
-		await this.#syncSkillPromptActiveStateSafely(customMessage, true);
-		try {
-			await this.#promptWithMessage(customMessage, textContent, options);
-		} finally {
-			await this.#syncSkillPromptActiveStateSafely(customMessage, false);
-		}
+			await this.#syncSkillPromptActiveStateSafely(customMessage, true);
+			try {
+				await this.#promptWithMessage(customMessage, textContent, { ...options, admissionLease: admission });
+			} finally {
+				await this.#syncSkillPromptActiveStateSafely(customMessage, false);
+			}
+		});
 	}
 
 	async #promptWithMessage(
 		message: AgentMessage,
 		expandedText: string,
-		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck"> & {
+		options?: Pick<PromptOptions, "toolChoice" | "images" | "skipCompactionCheck" | "onPreflightAccepted"> & {
 			prependMessages?: AgentMessage[];
 			skipPostPromptRecoveryWait?: boolean;
+			predecessorAgentEndHold?: symbol;
+			admissionLease?: SessionAdmissionLease;
 		},
 	): Promise<void> {
 		this.#beginInFlight();
+		const predecessorAgentEndHold =
+			options?.predecessorAgentEndHold ?? this.#reserveDeferredAgentEndForContinuation();
 		const generation = this.#promptGeneration;
+		const preflightSignal = this.#promptPreflightAbortController.signal;
 		const rosterClaim = this.#claimIrcRosterCandidate();
 		try {
+			this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
+			if (message.role === "user") {
+				await this.#resetDefaultFallbackForNewTurn();
+				await this.#ensureDefaultFallbackResolution();
+				this.#defaultFallbackChain().resetAttemptBudget();
+				this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
+			}
 			// Flush any pending bash messages before the new prompt
 			this.#flushPendingBashMessages();
 			this.#flushPendingPythonMessages();
@@ -5674,8 +6470,6 @@ export class AgentSession {
 			// Reset todo reminder count on new user prompt
 			this.#todoReminderCount = 0;
 
-			await this.#maybeRestoreRetryFallbackPrimary();
-
 			// Validate model
 			if (!this.model) {
 				throw new Error(formatNoModelOnboardingError());
@@ -5727,10 +6521,14 @@ export class AgentSession {
 
 			messages.push(message);
 
-			// Early bail-out: if a newer abort/prompt cycle started during setup,
-			// return before mutating shared state (nextTurn messages, system prompt).
-			if (this.#promptGeneration !== generation) {
+			// Early bail-out: a generation change or cancellation during setup must
+			// terminate preflight rather than retaining SDK prompt authority.
+			if (this.#isPromptPreflightCancelled(generation, preflightSignal)) {
 				this.#resetInjectedContextSignatures();
+				// A newer abort/prompt cycle superseded this preflight. Callers awaiting
+				// acceptance (onPreflightAccepted) must be told it never ran; direct
+				// callers (e.g. prompt() aborted during a TTSR wait) resolve gracefully.
+				if (options?.onPreflightAccepted) throw promptPreflightCancelledError();
 				return;
 			}
 
@@ -5774,12 +6572,13 @@ export class AgentSession {
 			const promptAttribution: "user" | "agent" | undefined =
 				"attribution" in message ? message.attribution : undefined;
 
-			// Emit before_agent_start extension event
+			// Emit before_agent_start extension event. Race hook completion with prompt
+			// cancellation so a wedged hook cannot retain SDK prompt authority.
 			if (this.#extensionRunner) {
-				const result = await this.#extensionRunner.emitBeforeAgentStart(
-					expandedText,
-					options?.images,
-					beforeAgentStartSystemPrompt,
+				const result = await this.#awaitPromptPreflight(
+					generation,
+					preflightSignal,
+					this.#extensionRunner.emitBeforeAgentStart(expandedText, options?.images, beforeAgentStartSystemPrompt),
 				);
 				if (result?.messages) {
 					this.#appendBeforeAgentStartCustomMessages(messages, result.messages, promptAttribution, message.role);
@@ -5801,30 +6600,43 @@ export class AgentSession {
 				const contributed: BeforeAgentStartInternalMessage[] = [];
 				for (const contributor of this.#beforeAgentStartContributors) {
 					try {
-						const msg = await contributor({
-							prompt: expandedText,
-							images: options?.images,
-							sessionId: this.sessionId,
-						});
+						const msg = await this.#awaitPromptPreflight(
+							generation,
+							preflightSignal,
+							contributor({
+								prompt: expandedText,
+								images: options?.images,
+								sessionId: this.sessionId,
+							}),
+						);
 						if (msg) contributed.push(msg);
 					} catch (err) {
+						if (this.#isPromptPreflightCancelled(generation, preflightSignal))
+							throw promptPreflightCancelledError();
 						logger.debug("before_agent_start contributor failed", { error: String(err) });
 					}
 				}
 				this.#appendBeforeAgentStartCustomMessages(messages, contributed, promptAttribution, message.role);
 			}
 
-			// Bail out if a newer abort/prompt cycle has started since we began setup.
-			// The injection signatures were consumed while building the automatic
-			// goal/plan context above, but the message is not delivered on this
-			// aborted turn, so reset them here so the next real turn re-injects once.
-			if (this.#promptGeneration !== generation) {
+			// Abort can race asynchronous preflight work. The injection signatures were
+			// consumed while building context, but no prompt was accepted, so reset them.
+			if (this.#isPromptPreflightCancelled(generation, preflightSignal)) {
 				this.#resetInjectedContextSignatures();
+				// Ack-waiting callers are told the preflight never ran; direct callers
+				// (aborted after setup) resolve gracefully as before f24f46ff5.
+				if (options?.onPreflightAccepted) throw promptPreflightCancelledError();
 				return;
 			}
 
-			const agentPromptOptions = options?.toolChoice ? { toolChoice: options.toolChoice } : undefined;
-			await this.#promptAgentWithIdleRetry(messages, agentPromptOptions);
+			const agentPromptOptions = {
+				...(options?.toolChoice ? { toolChoice: options.toolChoice } : undefined),
+				...this.#managedFallbackPromptOptions(),
+				...(options?.admissionLease ? { onRunAccepted: options.admissionLease.release } : undefined),
+			};
+			options?.onPreflightAccepted?.();
+			this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
+			await this.#promptAgentWithIdleRetry(messages, agentPromptOptions, predecessorAgentEndHold);
 			const terminalAssistant = this.#findLastAssistantMessage();
 			if (
 				rosterClaim &&
@@ -5837,6 +6649,12 @@ export class AgentSession {
 			if (!options?.skipPostPromptRecoveryWait) {
 				await this.#waitForPostPromptRecovery();
 			}
+		} catch (error) {
+			// Session identity changes historically cancel local setup silently. Only SDK
+			// submissions provide an acceptance callback and require an explicit terminal
+			// preflight failure for their remote request authority.
+			if (isPromptPreflightCancelledError(error) && !options?.onPreflightAccepted) return;
+			throw error;
 		} finally {
 			if (rosterClaim) {
 				this.agent.replaceMessages(
@@ -5846,6 +6664,7 @@ export class AgentSession {
 				);
 				this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
 			}
+			this.#releaseDeferredAgentEndContinuation(predecessorAgentEndHold);
 			this.#endInFlight();
 		}
 	}
@@ -5898,6 +6717,50 @@ export class AgentSession {
 				void this.abort();
 			},
 			hasPendingMessages: () => this.queuedMessageCount > 0,
+			getPendingMessageCounts: () => this.pendingMessageCounts,
+			getTranscript: () => this.getTranscript(),
+			getTranscriptBody: entryId => this.getTranscriptBody(entryId),
+			getGoalState: () => this.getGoalModeState(),
+			getTodoState: () => this.getTodoPhases(),
+			getQueuedMessages: () => this.getQueuedMessageEntries(),
+			getActiveTools: () => this.getActiveToolNames(),
+			getAllTools: () => this.getAllToolNames(),
+			cycleModel: () => this.cycleModel(),
+			cycleThinkingLevel: () => this.cycleThinkingLevel(),
+			setQueueMode: (kind, mode) => {
+				if (kind === "steering" && (mode === "all" || mode === "one-at-a-time")) {
+					this.setSteeringMode(mode);
+					return true;
+				}
+				if (kind === "follow_up" && (mode === "all" || mode === "one-at-a-time")) {
+					this.setFollowUpMode(mode);
+					return true;
+				}
+				if (kind === "interrupt" && (mode === "immediate" || mode === "wait")) {
+					this.setInterruptMode(mode);
+					return true;
+				}
+				return false;
+			},
+			invokeSkill: (name, args) => this.invokeSkill(name, args),
+			setPlanMode: on => this.setSdkPlanMode(on),
+			operateGoal: (op, objective) => this.operateGoal(op, objective),
+			getSkillState: () => this.skills.map(skill => ({ name: skill.name, description: skill.description })),
+			getConfigItems: () => this.getSdkConfigItems(),
+			getBranchCandidates: () => this.sessionManager.getTree(),
+			getExtensions: () => this.#extensionRunner?.getExtensionPaths() ?? [],
+			getArtifact: () => undefined,
+			getJobs: () => undefined,
+			sdkBindings: () => [
+				"cycleModel",
+				"cycleThinkingLevel",
+				"setQueueMode",
+				"getSkillState",
+				"getConfigItems",
+				"getBranchCandidates",
+				"getExtensions",
+			],
+			clearContext: () => this.clearContext(),
 			shutdown: () => {
 				void this.dispose();
 				process.exit(0);
@@ -6354,7 +7217,7 @@ export class AgentSession {
 	 */
 	async sendUserMessage(
 		content: string | (TextContent | ImageContent)[],
-		options?: { deliverAs?: "steer" | "followUp" },
+		options?: { deliverAs?: "steer" | "followUp"; onPreflightAccepted?: () => void },
 	): Promise<void> {
 		// Normalize content to text string + optional images
 		let text: string;
@@ -6378,10 +7241,12 @@ export class AgentSession {
 
 		if (options?.deliverAs === "followUp") {
 			await this.#queueFollowUp(text, images);
+			options.onPreflightAccepted?.();
 			return;
 		}
 		if (options?.deliverAs === "steer") {
 			await this.#queueSteer(text, images);
+			options.onPreflightAccepted?.();
 			return;
 		}
 
@@ -6392,6 +7257,7 @@ export class AgentSession {
 		// the message in the steering queue with no turn to consume it.
 		if (this.isStreaming) {
 			await this.#queueSteer(text, images);
+			options?.onPreflightAccepted?.();
 			return;
 		}
 
@@ -6399,6 +7265,7 @@ export class AgentSession {
 		await this.prompt(text, {
 			expandPromptTemplates: false,
 			images,
+			onPreflightAccepted: options?.onPreflightAccepted,
 		});
 	}
 
@@ -6419,6 +7286,14 @@ export class AgentSession {
 	get queuedMessageCount(): number {
 		return this.#steeringMessages.length + this.#followUpMessages.length + this.#pendingNextTurnMessages.length;
 	}
+	/** Typed pending-message counts per queue (steering, follow-up, next-turn). */
+	get pendingMessageCounts(): { steering: number; followUp: number; nextTurn: number } {
+		return {
+			steering: this.#steeringMessages.length,
+			followUp: this.#followUpMessages.length,
+			nextTurn: this.#pendingNextTurnMessages.length,
+		};
+	}
 
 	/** Whether the agent has queued steering messages that a `user_interrupt`
 	 *  abort would resume into (steer-on-interrupt). Drives the Esc-on-steer UX:
@@ -6596,6 +7471,32 @@ export class AgentSession {
 		return this.#applyCompactionPostAppend(compactionEntryId, firstKeptEntryId, fromExtension);
 	}
 
+	/** Read-only test seam for active mid-run EventStream drain barriers. */
+	get activeMidRunBarrierCountForTests(): number {
+		return this.#activeMidRunBarrierControllers.size;
+	}
+
+	/** Read-only test seam for active mid-run maintenance invocations. */
+	get activeMidRunMaintenanceCountForTests(): number {
+		return this.#activeMidRunMaintenancePromises.size;
+	}
+
+	/** Test seam: drive the cooperative mid-run maintenance checkpoint directly. */
+	runMidRunMaintenanceForTests(
+		context: AgentContext,
+		lifecycle: MidRunMaintenanceLifecycle = {
+			signal: new AbortController().signal,
+			awaitEventDrain: async () => {},
+		},
+	): Promise<MidRunMaintenanceOutcome> {
+		return this.#trackMidRunMaintenance(this.#runMidRunMaintenance(context, lifecycle));
+	}
+
+	/** Test seam: estimate mid-run context tokens for a given context view. */
+	estimateMidRunContextTokensForTests(messages: readonly AgentMessage[]): number {
+		return this.#estimateMidRunContextTokens(messages);
+	}
+
 	#cloneTodoPhases(phases: TodoPhase[]): TodoPhase[] {
 		return phases.map(phase => ({
 			name: phase.name,
@@ -6633,6 +7534,7 @@ export class AgentSession {
 		 *  hand-off rather than a failure. */
 		silent?: boolean;
 	}): Promise<void> {
+		this.#abortActiveMidRunBarriers();
 		if (options?.silent) {
 			this.#silentAbortPending = true;
 		} else {
@@ -6640,12 +7542,16 @@ export class AgentSession {
 		}
 		this.abortRetry();
 		this.#promptGeneration++;
+		this.#promptPreflightAbortController.abort();
+		this.#promptPreflightAbortController = new AbortController();
 		this.#scheduledHiddenNextTurnGeneration = undefined;
 		this.abortCompaction();
 		this.abortHandoff();
 		this.abortBash();
 		this.abortEval();
 		const postPromptDrain = this.#cancelPostPromptTasks();
+		const managedLogicalRunId =
+			this.#defaultFallbackChain().chain.entries.length > 1 ? this.agent.currentManagedLogicalRunId : undefined;
 		this.agent.abort();
 		const cleanup = Promise.all([postPromptDrain, this.agent.waitForIdle()]).then(
 			() => ({ type: "settled" as const }),
@@ -6673,10 +7579,16 @@ export class AgentSession {
 			}
 		}
 		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.
-		this.#resetInFlight();
+		if (managedLogicalRunId !== undefined) {
+			// Agent-core owns terminalization for the logical managed run, which
+			// remains stable across fallback attempt retries.
+			this.agent.requestRunTerminal(managedLogicalRunId, { stopReason: "cancelled" });
+		}
+		// waitForIdle resolves before #promptWithMessage's finally and asynchronous
+		// event handlers necessarily unwind. Keep their counters intact: #endInFlight
+		// and the event barrier publish deferred readiness only when they actually settle.
+		this.#flushPendingBackgroundExchanges();
+		this.#flushPendingAgentEnd();
 		// Safety net: clear the silent-abort flag if it was never consumed (the
 		// abort produced no aborted assistant message_end to stamp). Prevents the
 		// marker from leaking onto a later, unrelated abort.
@@ -6711,6 +7623,7 @@ export class AgentSession {
 	 */
 	async newSession(options?: NewSessionOptions): Promise<boolean> {
 		const previousSessionFile = this.sessionFile;
+		const previousWorkflowGateSessionId = this.sessionId;
 		const nextDiscoverySessionToolNames = this.#mcpDiscoveryEnabled
 			? [
 					...this.#getActiveNonMCPToolNames(),
@@ -6734,6 +7647,7 @@ export class AgentSession {
 		await this.abort();
 		this.#cancelOwnAsyncJobs();
 		this.#closeAllProviderSessions("new session");
+		this.#rebindProviderSessionState(new Map());
 		this.agent.reset();
 		if (options?.drop && previousSessionFile) {
 			try {
@@ -6747,6 +7661,7 @@ export class AgentSession {
 		await this.sessionManager.newSession(options);
 		this.setTodoPhases([]);
 		this.#syncAgentSessionId();
+		this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#resetHindsightConversationTrackingIfHindsight();
 		this.#steeringMessages = [];
@@ -6754,7 +7669,10 @@ export class AgentSession {
 		this.#pendingNextTurnMessages = [];
 		this.#scheduledHiddenNextTurnGeneration = undefined;
 
-		this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
+		const inheritedThinkingLevel = resolveThinkingLevelForModel(this.model, this.#getInheritedThinkingLevel());
+		this.#thinkingLevel = inheritedThinkingLevel;
+		this.agent.setThinkingLevel(toReasoningEffort(inheritedThinkingLevel));
+		this.sessionManager.appendThinkingLevelChange(ThinkingLevel.Inherit);
 		if (this.model) {
 			this.sessionManager.appendModelChange(`${this.model.provider}/${this.model.id}`);
 		}
@@ -6839,6 +7757,7 @@ export class AgentSession {
 	 */
 	async fork(): Promise<boolean> {
 		const previousSessionFile = this.sessionFile;
+		const previousWorkflowGateSessionId = this.sessionId;
 
 		// Emit session_before_switch event with reason "fork" (can be cancelled)
 		if (this.#extensionRunner?.hasHandlers("session_before_switch")) {
@@ -6882,6 +7801,7 @@ export class AgentSession {
 
 		// Update agent session ID
 		this.#syncAgentSessionId();
+		this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 
 		this.#resetIrcRosterDeliveryState();
@@ -6910,7 +7830,7 @@ export class AgentSession {
 	async setModel(
 		model: Model,
 		role: string = "default",
-		options?: { selector?: string; thinkingLevel?: ThinkingLevel },
+		options?: { selector?: string; thinkingLevel?: ThinkingLevel; cause?: ModelChangeCause },
 	): Promise<void> {
 		const previousEditMode = this.#resolveActiveEditMode();
 		const apiKey = await this.#modelRegistry.getApiKey(model, this.sessionId);
@@ -6918,15 +7838,39 @@ export class AgentSession {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
 
-		this.#clearActiveRetryFallback();
-		this.#setModelWithProviderSessionReset(model);
+		this.#setModelAuthoritatively(model, options?.cause ?? "user-selection");
 		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, role);
 		this.settings.setModelRole(
 			role,
 			this.#formatRoleModelValue(role, model, options?.selector, options?.thinkingLevel),
 		);
+		if (role === "default") {
+			this.#defaultFallbackController = undefined;
+			this.#defaultFallbackExhaustedLastTurn = false;
+		}
 		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
 
+		// Persist configured intent rather than a transient controller index. A pick
+		// inside an existing chain keeps its deterministic suffix; a different
+		// thinking choice for the same concrete model becomes the new head followed
+		// by that concrete entry's tail. Picks outside the chain are one-entry intent.
+		const configuredChain = this.getConfiguredModelChain(role);
+		if (configuredChain) {
+			const selectedSelector = this.#canonicalSelector(model, options?.selector, options?.thinkingLevel);
+			const exactIndex = configuredChain.indexOf(selectedSelector);
+			const concreteIndex = configuredChain.findIndex(entry => {
+				const parsed = parseModelString(entry);
+				return parsed?.provider === model.provider && parsed.id === model.id;
+			});
+			const entries =
+				exactIndex !== -1
+					? configuredChain.slice(exactIndex)
+					: concreteIndex !== -1
+						? [selectedSelector, ...configuredChain.slice(concreteIndex + 1)]
+						: [selectedSelector];
+			this.setConfiguredModelChain(role, entries, "model_selection");
+		}
+
 		// Apply the explicitly selected thinking level when the selector supplies one;
 		// otherwise prefer the model's configured defaultLevel, then preserve the current level.
 		this.setThinkingLevel(options?.thinkingLevel ?? model.thinking?.defaultLevel ?? this.thinkingLevel);
@@ -6941,21 +7885,67 @@ export class AgentSession {
 		return this.#activeModelProfile;
 	}
 
-	/**
-	 * The model selector ("provider/id") that resume restores as the session
-	 * default — the latest session-log `model_change` with role="default".
-	 * Model-profile activation snapshots this before mutating the session so a
-	 * failed-activation rollback can restore the pre-activation resume default
-	 * instead of promoting a transient runtime model to the resume default.
-	 */
-	getSessionDefaultModelSelector(): string | undefined {
-		return this.sessionManager.buildSessionContext().models.default;
+	/** Return the persisted configured fallback selectors for a model role. */
+	getConfiguredModelChain(role: string): readonly string[] | undefined {
+		return this.sessionManager.buildSessionContext().configuredModelChains[role]?.entries;
 	}
 
-	/**
-	 * Re-assert the session resume default ("provider/id") in the session log
-	 * WITHOUT touching the live runtime model. Appends a `model_change` with
-	 * role="default"; never writes to global settings (apply-for-this-session
+	/** Persist the configured fallback selectors for a model role. */
+	setConfiguredModelChain(
+		role: string,
+		entries: readonly string[],
+		origin: string,
+		identity?: string,
+		explicitHead = true,
+	): void {
+		this.sessionManager.appendConfiguredModelChain({
+			role,
+			entries: [...entries],
+			origin,
+			identity,
+			explicitHead,
+			cleared: entries.length === 0,
+		});
+	}
+
+	/**
+	 * Replace only the in-memory default fallback controller. Used when startup
+	 * falls through an unavailable persisted chain to the global default, which
+	 * must not mutate the persisted configured intent.
+	 */
+	setDefaultFallbackRuntimeModel(selector: string): void {
+		this.#defaultFallbackController = new FallbackChainController(
+			{ role: "default", entries: [selector], origin: "runtime", explicitHead: true },
+			this.settings.get("fallback.maxAttempts"),
+		);
+		this.#defaultFallbackExhaustedLastTurn = false;
+	}
+
+	/**
+	 * Seed default fallback state after guarded auth-aware model resolution skips chain entries.
+	 * The configured chain's role, origin, and identity are retained by the controller.
+	 */
+	seedDefaultFallbackResolution(activeIndex: number, skips: Array<{ selector: string; reason: string }>): void {
+		const controller = this.#defaultFallbackChain();
+		controller.seedResolution(activeIndex, skips);
+		this.#emitResolutionFallbackSwitch(controller);
+	}
+
+	/**
+	 * The model selector ("provider/id") that resume restores as the session
+	 * default — the latest session-log `model_change` with role="default".
+	 * Model-profile activation snapshots this before mutating the session so a
+	 * failed-activation rollback can restore the pre-activation resume default
+	 * instead of promoting a transient runtime model to the resume default.
+	 */
+	getSessionDefaultModelSelector(): string | undefined {
+		return this.sessionManager.buildSessionContext().models.default;
+	}
+
+	/**
+	 * Re-assert the session resume default ("provider/id") in the session log
+	 * WITHOUT touching the live runtime model. Appends a `model_change` with
+	 * role="default"; never writes to global settings (apply-for-this-session
 	 * semantics). Used by model-profile activation rollback to neutralize the
 	 * profile main model the failed activation already recorded as the default.
 	 */
@@ -6979,37 +7969,179 @@ export class AgentSession {
 	async setModelTemporary(
 		model: Model,
 		thinkingLevel?: ThinkingLevel,
-		options?: { persistAsSessionDefault?: boolean },
-	): Promise<void> {
+		options?: {
+			persistAsSessionDefault?: boolean;
+			cause?: ModelChangeCause;
+			reason?: TemporaryModelReason;
+			providerSessionScope?: TemporaryProviderSessionScope;
+			signal?: AbortSignal;
+		},
+		// biome-ignore lint/suspicious/noConfusingVoidType: Existing session adapters return Promise<void>; a scope is optional.
+	): Promise<TemporaryProviderSessionScope | void> {
+		if (options?.signal?.aborted) return;
+		const suppliedScope = options?.providerSessionScope;
+		if (suppliedScope && this.#temporaryProviderSessionScopes.at(-1)?.token !== suppliedScope) return;
 		const previousEditMode = this.#resolveActiveEditMode();
-		const apiKey = await this.#modelRegistry.getApiKey(model, this.sessionId);
+		const expectedSessionId = this.sessionId;
+		const apiKey = await this.#modelRegistry.getApiKey(model, expectedSessionId);
+		if (options?.signal?.aborted) return;
+		if (this.sessionId !== expectedSessionId) {
+			throw new Error("Session changed while selecting model");
+		}
 		if (!apiKey) {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
+		if (suppliedScope && this.#temporaryProviderSessionScopes.at(-1)?.token !== suppliedScope) return;
+
+		const isTemporaryOperation = options?.cause === undefined || options.cause === "temporary-operation";
+		const autoCreateScope = isTemporaryOperation && !suppliedScope;
+		const currentAutoScope = this.#currentAutoTemporaryProviderSessionScope();
+		const replaceAutoScope =
+			autoCreateScope &&
+			currentAutoScope !== undefined &&
+			this.#temporaryProviderSessionScopes.at(-1) === currentAutoScope;
+		if (replaceAutoScope && currentAutoScope) {
+			this.#restoreTopTemporaryProviderSessionScope();
+		}
+		const scope = isTemporaryOperation
+			? (suppliedScope ??
+				(replaceAutoScope && this.model && modelsAreEqual(this.model, model)
+					? undefined
+					: this.#beginTemporaryProviderSessionScope(options?.reason ?? "other", true)))
+			: undefined;
+		const ownsScope = scope !== undefined && !suppliedScope;
+		try {
+			if (isTemporaryOperation) {
+				this.agent.setModel(model);
+				this.#syncAppendOnlyContext(model);
+			} else {
+				this.#setModelAuthoritatively(model, options?.cause ?? "temporary-operation");
+			}
+			this.sessionManager.appendModelChange(
+				`${model.provider}/${model.id}`,
+				options?.persistAsSessionDefault ? "default" : "temporary",
+			);
+			this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
+
+			// Apply explicit thinking level if given; otherwise prefer the model's
+			// configured defaultLevel; otherwise re-clamp the current level.
+			this.setThinkingLevel(thinkingLevel ?? model.thinking?.defaultLevel ?? this.thinkingLevel);
+			await this.#syncEditToolModeAfterModelChange(previousEditMode);
+		} catch (error) {
+			if (ownsScope) this.restoreTemporaryProviderSessionScope(scope);
+			throw error;
+		}
+		return scope;
+	}
 
-		this.#clearActiveRetryFallback();
-		this.#setModelWithProviderSessionReset(model);
-		this.sessionManager.appendModelChange(
-			`${model.provider}/${model.id}`,
-			options?.persistAsSessionDefault ? "default" : "temporary",
+	async #restoreDefaultModelSelectionCommit(
+		commit: GlobalDefaultModelRoleCommit,
+	): Promise<{ readonly stage: DefaultModelSelectionRollbackStage; readonly message: string } | undefined> {
+		try {
+			if (await this.settings.restoreGlobalDefaultModelRoleIfCurrent(commit)) return undefined;
+			return {
+				stage: "durable",
+				message: "A newer default selection prevented durable recovery.",
+			};
+		} catch {
+			logger.warn("Failed to restore durable default model selection after session promotion failure", {
+				code: "default_model_selection_recovery_failed",
+				rollbackStage: "durable",
+			});
+			return {
+				stage: "durable",
+				message: "Durable default selection recovery could not be completed.",
+			};
+		}
+	}
+
+	async #discardDefaultModelSelectionStage(
+		stage: DefaultModelSelectionStage,
+	): Promise<{ readonly stage: DefaultModelSelectionRollbackStage; readonly message: string } | undefined> {
+		try {
+			await this.sessionManager.discardDefaultModelSelectionStage(stage);
+			return undefined;
+		} catch {
+			logger.warn("Failed to discard staged default model selection after session promotion failure", {
+				code: "default_model_selection_recovery_failed",
+				rollbackStage: "session",
+			});
+			return {
+				stage: "session",
+				message: "Session replacement recovery could not be completed.",
+			};
+		}
+	}
+
+	async #throwDefaultModelSelectionRecovery(
+		error: Error,
+		stage: DefaultModelSelectionStage,
+		commit: GlobalDefaultModelRoleCommit,
+	): Promise<never> {
+		const sessionFailure = await this.#discardDefaultModelSelectionStage(stage);
+		const durableFailure = await this.#restoreDefaultModelSelectionCommit(commit);
+		const failures = [sessionFailure, durableFailure].filter(
+			(failure): failure is { readonly stage: DefaultModelSelectionRollbackStage; readonly message: string } =>
+				failure !== undefined,
 		);
-		this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
+		throw new DefaultModelSelectionRecoveryError(error.message, {
+			message: error.message,
+			rollback: {
+				disposition: failures.length === 0 ? "restored" : "partial",
+				failures,
+			},
+		});
+	}
 
-		// Apply explicit thinking level if given; otherwise prefer the model's
-		// configured defaultLevel; otherwise re-clamp the current level.
-		this.setThinkingLevel(thinkingLevel ?? model.thinking?.defaultLevel ?? this.thinkingLevel);
-		await this.#syncEditToolModeAfterModelChange(previousEditMode);
+	#publishDefaultModelSelection(model: Model, thinkingLevel: ThinkingLevel, systemPrompt: string[] | undefined): void {
+		this.#clearActiveRetryFallback();
+		this.#setModelWithProviderSessionReset(model);
+		const thinkingLevelChanged = this.#thinkingLevel !== thinkingLevel;
+		this.#thinkingLevel = thinkingLevel;
+		this.agent.setThinkingLevel(toReasoningEffort(thinkingLevel));
+		if (thinkingLevelChanged) {
+			const event: AgentSessionEvent = { type: "thinking_level_changed", thinkingLevel };
+			for (const listener of this.#eventListenerSnapshot) {
+				try {
+					listener(event);
+				} catch {
+					logger.warn("Default model selection event listener failed", {
+						code: "default_model_selection_listener_failed",
+						disposition: "continue",
+					});
+				}
+			}
+		}
+		this.#applyPreparedDefaultModelSelectionPrompt(systemPrompt);
+		try {
+			this.settings.getStorage()?.recordModelUsage(`${model.provider}/${model.id}`);
+		} catch {
+			logger.warn("Failed to record model usage after default model selection", {
+				code: "default_model_selection_model_usage_record_failed",
+				disposition: "continue",
+			});
+		}
 	}
 
+	/** Set a durable per-session model from a control surface without exposing credential errors. */
+	async setModelTemporaryForControl(model: Model, expectedSessionId: string = this.sessionId): Promise<boolean> {
+		if (expectedSessionId !== this.sessionId) return false;
+		try {
+			await this.setModelTemporary(model, undefined, {
+				persistAsSessionDefault: true,
+				cause: "user-selection",
+			});
+			return expectedSessionId === this.sessionId;
+		} catch {
+			logger.warn("session: model control failed");
+			return false;
+		}
+	}
 	async setDefaultModelSelection(
 		model: Model,
 		thinkingLevel: ThinkingLevel | undefined,
 	): Promise<DefaultModelSelectionResult> {
-		const predecessor = this.#defaultModelSelectionTail;
-		const transaction = Promise.withResolvers<void>();
-		this.#defaultModelSelectionTail = transaction.promise;
-		try {
-			await predecessor;
+		return this.#withSessionAdmission("selection", async () => {
 			if (thinkingLevel === ThinkingLevel.Inherit) {
 				throw new Error("Default model selection cannot inherit a thinking level");
 			}
@@ -7023,72 +8155,64 @@ export class AgentSession {
 				resolveThinkingLevelForModel(model, model.thinking?.defaultLevel ?? this.thinkingLevel) ??
 				ThinkingLevel.Off;
 			await this.waitForIdle();
-			const previousDefaultModelRole = this.settings.getGlobal("modelRoles")?.default;
 			await this.sessionManager.flush();
-			const previousSessionState = this.sessionManager.captureState();
-			const previousModel = this.model;
-			const previousThinkingLevel = this.thinkingLevel;
-			const previousActiveRetryFallback = this.#activeRetryFallback ? { ...this.#activeRetryFallback } : undefined;
-			await this.settings.setGlobalModelRoleAndFlush(
-				"default",
-				formatModelSelectorValue(`${model.provider}/${model.id}`, effectiveLevel),
+			await this.#waitForAdmittedBaseSystemPromptRebuilds();
+			const expectedMutationRevision = this.#defaultModelSelectionMutationRevision;
+			const preparedSystemPrompt = await this.#prepareDefaultModelSelectionPrompt(model);
+			const stage = await this.sessionManager.stageDefaultModelSelection(
+				`${model.provider}/${model.id}`,
+				effectiveLevel,
+				{ appendThinkingLevel: true },
 			);
+			let durableCommit: GlobalDefaultModelRoleCommit;
 			try {
-				await this.setModelTemporary(model, effectiveLevel);
-				if (this.thinkingLevel === previousThinkingLevel) {
-					this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
-				}
-				this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, "default");
+				durableCommit = await this.settings.setGlobalModelRoleAndFlush(
+					"default",
+					formatModelSelectorValue(`${model.provider}/${model.id}`, effectiveLevel),
+				);
 			} catch (error) {
-				await this.settings.setGlobalModelRoleAndFlush("default", previousDefaultModelRole).catch(rollbackError => {
-					logger.warn("Failed to restore durable default model selection after live apply failure", {
-						error: String(rollbackError),
-					});
-				});
-				let restoredLiveState = false;
-				try {
-					const failedEditMode = this.#resolveActiveEditMode();
-					const currentModel = this.model;
-					const hasCompatibleModelTransport =
-						currentModel !== undefined &&
-						previousModel !== undefined &&
-						currentModel.provider === previousModel.provider &&
-						currentModel.id === previousModel.id &&
-						currentModel.api === previousModel.api;
-					if (hasCompatibleModelTransport) {
-						this.agent.setModel(previousModel);
-						this.#syncAppendOnlyContext(previousModel);
-					} else {
-						this.#setModelWithProviderSessionReset(previousModel);
-					}
-					this.#thinkingLevel = previousThinkingLevel;
-					this.agent.setThinkingLevel(toReasoningEffort(previousThinkingLevel));
-					await this.#syncEditToolModeAfterModelChange(failedEditMode);
-					restoredLiveState = true;
-				} catch (rollbackError) {
-					logger.warn("Failed to restore live default model selection after live apply failure", {
-						error: String(rollbackError),
-					});
+				await this.sessionManager.discardDefaultModelSelectionStage(stage);
+				throw error;
+			}
+			if (this.#defaultModelSelectionMutationRevision !== expectedMutationRevision) {
+				await this.#throwDefaultModelSelectionRecovery(
+					new Error("Default model selection was superseded before session promotion"),
+					stage,
+					durableCommit,
+				);
+			}
+			const promotion = this.sessionManager.promoteDefaultModelSelection(stage);
+			switch (promotion.kind) {
+				case "promoted": {
+					this.#publishDefaultModelSelection(model, effectiveLevel, preparedSystemPrompt);
+					break;
 				}
-				if (restoredLiveState) {
-					this.#activeRetryFallback = previousActiveRetryFallback;
+				case "not_promoted": {
+					return this.#throwDefaultModelSelectionRecovery(
+						promotion.error ?? new Error("Default model selection was superseded before session promotion"),
+						stage,
+						durableCommit,
+					);
 				}
-				try {
-					this.sessionManager.restoreState(previousSessionState);
-					await this.sessionManager.rewriteEntries();
-				} catch (rollbackError) {
-					logger.warn("Failed to restore session state after live default model selection failure", {
-						error: String(rollbackError),
+				case "unknown": {
+					const message = "Session replacement outcome could not be determined.";
+					throw new DefaultModelSelectionRecoveryError(message, {
+						message,
+						rollback: {
+							disposition: "unknown",
+							failures: [
+								{
+									stage: "session",
+									message: "Session replacement outcome could not be determined.",
+								},
+							],
+						},
 					});
 				}
-				throw error;
 			}
 			return { provider: model.provider, modelId: model.id, thinkingLevel: effectiveLevel };
-		} finally {
-			transaction.resolve();
-		}
+		});
 	}
-
 	/**
 	 * Cycle to next/previous model.
 	 * Uses scoped models (from --models flag) if available, otherwise all available models.
@@ -7160,9 +8284,12 @@ export class AgentSession {
 		const next = roleModels[nextIndex];
 
 		if (options?.temporary) {
-			await this.setModelTemporary(next.model, next.explicitThinkingLevel ? next.thinkingLevel : undefined);
+			await this.setModelTemporary(next.model, next.explicitThinkingLevel ? next.thinkingLevel : undefined, {
+				cause: "temporary-operation",
+				reason: "temporary-cycle",
+			});
 		} else {
-			await this.setModel(next.model, next.role);
+			await this.setModel(next.model, next.role, { cause: "user-selection" });
 			if (next.explicitThinkingLevel && next.thinkingLevel !== undefined) {
 				this.setThinkingLevel(next.thinkingLevel);
 			}
@@ -7194,7 +8321,6 @@ export class AgentSession {
 	}
 
 	async #cycleScopedModel(direction: "forward" | "backward"): Promise<ModelCycleResult | undefined> {
-		const previousEditMode = this.#resolveActiveEditMode();
 		const scopedModels = await this.#getScopedModelsWithApiKey();
 		if (scopedModels.length <= 1) return undefined;
 
@@ -7206,22 +8332,15 @@ export class AgentSession {
 		const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
 		const next = scopedModels[nextIndex];
 
-		// Apply model
-		this.#clearActiveRetryFallback();
-		this.#setModelWithProviderSessionReset(next.model);
-		this.sessionManager.appendModelChange(`${next.model.provider}/${next.model.id}`);
-		this.settings.setModelRole("default", this.#formatRoleModelValue("default", next.model));
-		this.settings.getStorage()?.recordModelUsage(`${next.model.provider}/${next.model.id}`);
+		await this.setModel(next.model, "default", { cause: "user-selection" });
 
 		// Apply the scoped model's configured thinking level
 		this.setThinkingLevel(next.thinkingLevel);
-		await this.#syncEditToolModeAfterModelChange(previousEditMode);
 
 		return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
 	}
 
 	async #cycleAvailableModel(direction: "forward" | "backward"): Promise<ModelCycleResult | undefined> {
-		const previousEditMode = this.#resolveActiveEditMode();
 		const availableModels = this.#modelRegistry.getAvailable();
 		if (availableModels.length <= 1) return undefined;
 
@@ -7238,14 +8357,9 @@ export class AgentSession {
 			throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`);
 		}
 
-		this.#clearActiveRetryFallback();
-		this.#setModelWithProviderSessionReset(nextModel);
-		this.sessionManager.appendModelChange(`${nextModel.provider}/${nextModel.id}`);
-		this.settings.setModelRole("default", this.#formatRoleModelValue("default", nextModel));
-		this.settings.getStorage()?.recordModelUsage(`${nextModel.provider}/${nextModel.id}`);
+		await this.setModel(nextModel, "default", { cause: "user-selection" });
 		// Re-apply the current thinking level for the newly selected model
 		this.setThinkingLevel(this.thinkingLevel);
-		await this.#syncEditToolModeAfterModelChange(previousEditMode);
 
 		return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
 	}
@@ -7261,6 +8375,11 @@ export class AgentSession {
 	// Thinking Level Management
 	// =========================================================================
 
+	#getInheritedThinkingLevel(): ThinkingLevel | undefined {
+		if (this.settings.has("defaultThinkingLevel")) return this.settings.get("defaultThinkingLevel");
+		return this.model?.thinking?.defaultLevel ?? this.settings.get("defaultThinkingLevel");
+	}
+
 	/**
 	 * Set thinking level.
 	 * Saves the effective metadata-clamped level to the session, and to settings when requested.
@@ -7271,9 +8390,11 @@ export class AgentSession {
 
 		this.#thinkingLevel = effectiveLevel;
 		this.agent.setThinkingLevel(toReasoningEffort(effectiveLevel));
+		if (isChanging) this.#defaultModelSelectionMutationRevision++;
 
-		if (persist && effectiveLevel !== undefined) {
-			this.settings.set("defaultThinkingLevel", effectiveLevel);
+		if (persist) {
+			const persistedLevel = level === ThinkingLevel.Inherit ? getDefault("defaultThinkingLevel") : effectiveLevel;
+			if (persistedLevel !== undefined) this.settings.set("defaultThinkingLevel", persistedLevel);
 		}
 
 		if (isChanging) {
@@ -7282,6 +8403,83 @@ export class AgentSession {
 		}
 	}
 
+	/**
+	 * Set thinking level from a control surface. Global changes are durable or rolled back.
+	 */
+	async setThinkingLevelForControl(level: ThinkingLevel, persist: boolean): Promise<void> {
+		const previousThinkingLevel = this.thinkingLevel;
+		const previousScope = this.getThinkingScopeForControl();
+		if (!persist) {
+			this.setThinkingLevel(level === ThinkingLevel.Inherit ? this.#getInheritedThinkingLevel() : level);
+			if (level === ThinkingLevel.Inherit || this.thinkingLevel === previousThinkingLevel) {
+				this.sessionManager.appendThinkingLevelChange(level);
+			}
+			return;
+		}
+
+		const previousDefaultThinkingLevel = this.settings.getGlobal("defaultThinkingLevel");
+		if (level === ThinkingLevel.Inherit) {
+			const defaultLevel = getDefault("defaultThinkingLevel");
+			this.settings.set("defaultThinkingLevel", defaultLevel);
+			this.setThinkingLevel(this.#getInheritedThinkingLevel());
+		} else {
+			this.setThinkingLevel(level, true);
+		}
+		try {
+			await this.settings.flushOrThrow();
+			this.sessionManager.appendThinkingLevelChange(ThinkingLevel.Inherit);
+		} catch {
+			this.settings.set("defaultThinkingLevel", previousDefaultThinkingLevel ?? getDefault("defaultThinkingLevel"));
+			this.setThinkingLevel(previousThinkingLevel);
+			this.sessionManager.appendThinkingLevelChange(
+				previousScope === "global config" ? ThinkingLevel.Inherit : previousThinkingLevel,
+			);
+			await this.settings.flushOrThrow().catch(() => {});
+			throw new Error("Unable to persist reasoning settings.");
+		}
+	}
+
+	getThinkingScopeForControl(): "session" | "global config" {
+		const latest = this.sessionManager
+			.getBranch()
+			.toReversed()
+			.find(entry => entry.type === "thinking_level_change");
+		return latest && latest.thinkingLevel !== ThinkingLevel.Inherit ? "session" : "global config";
+	}
+
+	getThinkingVisibility(): "visible" | "hidden" {
+		return this.agent.hideThinkingSummary ? "hidden" : "visible";
+	}
+
+	setThinkingVisibility(visibility: "visible" | "hidden", persist: boolean = false): void {
+		this.agent.hideThinkingSummary = visibility === "hidden";
+		if (persist) {
+			this.settings.set("hideThinkingBlock", visibility === "hidden");
+		}
+	}
+
+	/**
+	 * Set thinking visibility from a control surface. Global changes are durable or rolled back.
+	 */
+	async setThinkingVisibilityForControl(visibility: "visible" | "hidden", persist: boolean): Promise<void> {
+		if (!persist) {
+			this.setThinkingVisibility(visibility);
+			return;
+		}
+
+		const previousVisibility = this.getThinkingVisibility();
+		const previousHideThinkingBlock = this.settings.getGlobal("hideThinkingBlock");
+		this.setThinkingVisibility(visibility, true);
+		try {
+			await this.settings.flushOrThrow();
+		} catch {
+			this.settings.set("hideThinkingBlock", previousHideThinkingBlock ?? getDefault("hideThinkingBlock"));
+			this.setThinkingVisibility(previousVisibility);
+			await this.settings.flushOrThrow().catch(() => {});
+			throw new Error("Unable to persist reasoning settings.");
+		}
+	}
+
 	/**
 	 * Cycle to next thinking level.
 	 * @returns New level, or undefined if model doesn't support thinking
@@ -7482,7 +8680,7 @@ export class AgentSession {
 	// Compaction
 	// =========================================================================
 
-	async #pruneToolOutputs(): Promise<{ prunedCount: number; tokensSaved: number } | undefined> {
+	async #pruneToolOutputs(signal?: AbortSignal): Promise<{ prunedCount: number; tokensSaved: number } | undefined> {
 		const branchEntries = this.sessionManager.getBranch();
 		const result = pruneToolOutputs(branchEntries, DEFAULT_PRUNE_CONFIG);
 		const argumentResult = pruneAssistantToolArguments(branchEntries, DEFAULT_PRUNE_CONFIG);
@@ -7492,7 +8690,7 @@ export class AgentSession {
 		const tokensSaved =
 			result.tokensSaved + argumentResult.argumentTokensSaved + Math.round(fileMentionResult.bytesSaved / 4);
 		const prunedCount = result.prunedCount + argumentResult.argumentPrunedCount + fileMentionResult.changed.length;
-		if (prunedCount === 0) {
+		if (prunedCount === 0 || signal?.aborted) {
 			return undefined;
 		}
 
@@ -7757,6 +8955,28 @@ export class AgentSession {
 		this.#handoffAbortController?.abort();
 	}
 
+	#abortActiveMidRunBarriers(): void {
+		for (const controller of this.#activeMidRunBarrierControllers) {
+			controller.abort();
+		}
+		this.#activeMidRunBarrierControllers.clear();
+	}
+
+	#trackMidRunMaintenance(maintenance: Promise<MidRunMaintenanceOutcome>): Promise<MidRunMaintenanceOutcome> {
+		this.#activeMidRunMaintenancePromises.add(maintenance);
+		maintenance.then(
+			() => this.#activeMidRunMaintenancePromises.delete(maintenance),
+			() => this.#activeMidRunMaintenancePromises.delete(maintenance),
+		);
+		return maintenance;
+	}
+
+	async #waitForActiveMidRunMaintenance(): Promise<void> {
+		while (this.#activeMidRunMaintenancePromises.size > 0) {
+			await Promise.allSettled([...this.#activeMidRunMaintenancePromises]);
+		}
+	}
+
 	/** Trigger idle compaction through the auto-compaction flow (with UI events). */
 	async runIdleCompaction(): Promise<void> {
 		if (this.isStreaming || this.isCompacting) return;
@@ -7914,6 +9134,13 @@ export class AgentSession {
 			this.#syncTodoPhasesFromBranch();
 
 			this.#resetIrcRosterDeliveryState();
+			if (this.#extensionRunner) {
+				await this.#extensionRunner.emit({
+					type: "session_switch",
+					reason: "new",
+					previousSessionFile,
+				});
+			}
 
 			return { document: handoffText, savedPath };
 		} catch (error) {
@@ -7990,7 +9217,8 @@ export class AgentSession {
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (promoted) {
 				// Retry on the promoted (larger) model without compacting
-				this.#scheduleAgentContinue({ delayMs: 100, generation });
+				this.#scheduleAgentContinue({ delayMs: 100, generation, suppressPredecessorAgentEnd: true });
+
 				return;
 			}
 
@@ -8031,6 +9259,167 @@ export class AgentSession {
 		}
 	}
 
+	/**
+	 * Cooperative mid-run context maintenance (issue #2035).
+	 *
+	 * Invoked by the agent loop (via {@link Agent.setMaintainContext}) at the top
+	 * of each tool-loop iteration — after pending tool-result / steering messages
+	 * are durable and before the model call. Threshold-based auto-compaction was
+	 * previously only evaluated at `agent_end` and before a user prompt, so a
+	 * single long agentic run grew straight through the compaction margin and died
+	 * with provider `context_length_exceeded`. This bounds that run.
+	 *
+	 * Decision input is the last assistant `usage.totalTokens` plus the estimated
+	 * trailing tool/steering deltas (NOT the pre-prompt estimator's prompt-only
+	 * anchor, which drops the last assistant's output). Reuses the existing
+	 * prune → promote → compact machinery and returns an explicit outcome.
+	 *
+	 * A non-"not-needed" outcome ends the current run losslessly
+	 * (`agent_end.stopReason === "maintenance"`); the `agent_end` handler is the
+	 * single continuation owner that resumes the run with no synthetic prompt.
+	 * This method never self-continues, runs goal-runtime hooks, clears skill
+	 * state, or emits a user-facing pause.
+	 */
+	async #runMidRunMaintenance(
+		context: AgentContext,
+		lifecycle: MidRunMaintenanceLifecycle,
+	): Promise<MidRunMaintenanceOutcome> {
+		if (this.#isDisposed) return "aborted";
+		const invocationController = new AbortController();
+		this.#activeMidRunBarrierControllers.add(invocationController);
+		const maintenanceSignal = AbortSignal.any([lifecycle.signal, invocationController.signal]);
+		const isAborted = () => maintenanceSignal.aborted;
+
+		try {
+			try {
+				await lifecycle.awaitEventDrain(invocationController.signal);
+			} catch {
+				return isAborted() ? "aborted" : "failed";
+			}
+			if (isAborted()) return "aborted";
+
+			// In-place context-full maintenance only. "off" defers entirely; "handoff"
+			// keeps its existing agent_end / pre-prompt boundaries (a mid-tool-loop
+			// session swap would be far more disruptive than the overflow it avoids).
+			const compactionSettings = this.settings.getGroup("compaction");
+			if (!compactionSettings.enabled || compactionSettings.strategy !== "context-full") return "not-needed";
+			const contextWindow = this.model?.contextWindow ?? 0;
+			if (contextWindow <= 0) return "not-needed";
+			// A compaction already in flight (overflow recovery, manual, idle) owns the
+			// context; never double-compact underneath it.
+			if (this.isCompacting) return "not-needed";
+
+			// Model maxTokens is a capability ceiling, not a per-turn reservation;
+			// track actual context fullness (mirrors the agent_end / pre-prompt checks).
+			const autoCompactionOutputReserveTokens = 0;
+			const anchor = this.#findMidRunUsageAnchor(context.messages);
+			let contextTokens = this.#estimateMidRunContextTokens(context.messages);
+			if (!shouldCompact(contextTokens, contextWindow, compactionSettings, autoCompactionOutputReserveTokens)) {
+				return "not-needed";
+			}
+			// Anti-loop (#1662): a given provider response anchors at most one
+			// maintenance attempt. Until a NEW response re-anchors usage, repeat checks
+			// on the same anchor are no-ops so a compaction that cannot shrink further
+			// cannot wedge the loop into interrupt → resume → interrupt.
+			const anchorSignature = anchor
+				? `${anchor.message.provider}/${anchor.message.model}#${anchor.message.timestamp}#${calculateContextTokens(anchor.message.usage as Usage)}`
+				: undefined;
+			if (anchorSignature) {
+				if (anchorSignature === this.#lastMidRunMaintenanceAnchorSignature) return "not-needed";
+				this.#lastMidRunMaintenanceAnchorSignature = anchorSignature;
+			}
+
+			// The FIFO consumer barrier made every prior materialized message canonical.
+			// Flush those synchronous branch appends before any history rewrite.
+			if (isAborted()) return "aborted";
+			await this.sessionManager.flush();
+			if (isAborted()) return "aborted";
+
+			// 1) Prune stale tool outputs first — cheaper than compaction, may avert it,
+			//    and (like all history rewrites) resets the codex provider session /
+			//    prompt-cache epoch via #closeCodexProviderSessionsForHistoryRewrite.
+			if (isAborted()) return "aborted";
+			const pruneResult = await this.#pruneToolOutputs(maintenanceSignal);
+			if (isAborted()) return "aborted";
+			if (pruneResult) {
+				contextTokens = Math.max(0, contextTokens - pruneResult.tokensSaved);
+			}
+			if (!shouldCompact(contextTokens, contextWindow, compactionSettings, autoCompactionOutputReserveTokens)) {
+				return pruneResult && pruneResult.prunedCount > 0 ? "pruned" : "not-needed";
+			}
+
+			// 2) Try context promotion (switch to a larger-window model) before compacting.
+			const lastAssistant = this.#findLastAssistantMessage();
+			if (lastAssistant && lastAssistant.stopReason !== "aborted" && lastAssistant.stopReason !== "error") {
+				if (isAborted()) return "aborted";
+				const promoted = await this.#tryContextPromotion(lastAssistant, maintenanceSignal);
+				if (isAborted()) return "aborted";
+				if (promoted) return "promoted";
+			}
+
+			// 3) Compact via the existing auto-compaction machinery. continueAfterMaintenance
+			//    is false so it does NOT schedule its own (synthetic) continuation — the
+			//    agent_end("maintenance") handler owns resumption. The oversized-maintenance
+			//    signature guard and the previous_response_id / prompt-cache-epoch reset
+			//    (#applyCompactionPostAppend) are inherited from #runAutoCompaction.
+			if (isAborted()) return "aborted";
+			const compactionStatus = await this.#runAutoCompaction("threshold", false, false, {
+				continueAfterMaintenance: false,
+				deferHandoffMaintenance: false,
+				signal: maintenanceSignal,
+			});
+			if (isAborted()) return "aborted";
+			if (compactionStatus.kind === "compacted") return "compacted";
+			if (compactionStatus.kind === "aborted") {
+				return compactionStatus.source === "hook" ? "not-needed" : "aborted";
+			}
+			return "failed";
+		} finally {
+			this.#activeMidRunBarrierControllers.delete(invocationController);
+		}
+	}
+
+	/**
+	 * Mid-run context-token estimate for {@link #runMidRunMaintenance}.
+	 *
+	 * Anchors on the last non-error assistant's `usage.totalTokens` — at the top
+	 * of a tool-loop iteration that output is already durable context that will be
+	 * re-sent — plus the inflated script-aware delta (see {@link #estimateMessageCompactionDeltaTokens}) of every trailing tool-result /
+	 * steering message appended since. Operates on the loop's authoritative
+	 * context view (not `this.messages`) so it is independent of listener flush
+	 * timing.
+	 */
+	#estimateMidRunContextTokens(messages: readonly AgentMessage[]): number {
+		const anchor = this.#findMidRunUsageAnchor(messages);
+		if (!anchor) {
+			let estimated = 0;
+			for (const message of messages) estimated += this.#estimateMessageCompactionDeltaTokens(message);
+			return estimated;
+		}
+		let tokens = calculateContextTokens(anchor.message.usage as Usage);
+		for (let i = anchor.index + 1; i < messages.length; i++) {
+			tokens += this.#estimateMessageCompactionDeltaTokens(messages[i]);
+		}
+		return tokens;
+	}
+
+	/**
+	 * Locate the anchor for {@link #estimateMidRunContextTokens}: the most recent
+	 * non-aborted/non-error assistant message that carries provider usage. Also
+	 * keys the anti-loop guard so each provider response drives at most one
+	 * maintenance attempt.
+	 */
+	#findMidRunUsageAnchor(messages: readonly AgentMessage[]): { index: number; message: AssistantMessage } | undefined {
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const msg = messages[i];
+			if (msg.role !== "assistant") continue;
+			const assistantMsg = msg as AssistantMessage;
+			if (assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error") continue;
+			if (assistantMsg.usage) return { index: i, message: assistantMsg };
+		}
+		return undefined;
+	}
+
 	async #checkEstimatedContextBeforePrompt(pendingMessages: readonly AgentMessage[] = []): Promise<void> {
 		if (this.#prePromptContextCheckPromise) {
 			await this.#prePromptContextCheckPromise;
@@ -8407,7 +9796,8 @@ export class AgentSession {
 	 * Attempt context promotion to a larger model.
 	 * Returns true if promotion succeeded (caller should retry without compacting).
 	 */
-	async #tryContextPromotion(assistantMessage: AssistantMessage): Promise<boolean> {
+	async #tryContextPromotion(assistantMessage: AssistantMessage, signal?: AbortSignal): Promise<boolean> {
+		if (signal?.aborted) return false;
 		const promotionSettings = this.settings.getGroup("contextPromotion");
 		if (!promotionSettings.enabled) return false;
 		const currentModel = this.model;
@@ -8416,11 +9806,19 @@ export class AgentSession {
 			return false;
 		const contextWindow = currentModel.contextWindow ?? 0;
 		if (contextWindow <= 0) return false;
-		const targetModel = await this.#resolveContextPromotionTarget(currentModel, contextWindow);
-		if (!targetModel) return false;
+		const targetModel = await this.#resolveContextPromotionTarget(currentModel, contextWindow, signal);
+		if (!targetModel || signal?.aborted) return false;
 
 		try {
-			await this.setModelTemporary(targetModel);
+			const scope = await this.setModelTemporary(targetModel, undefined, {
+				cause: "temporary-operation",
+				reason: "context-promotion",
+				signal,
+			});
+			if (signal?.aborted) {
+				if (scope) this.restoreTemporaryProviderSessionScope(scope);
+				return false;
+			}
 			logger.debug("Context promotion switched model on overflow", {
 				from: `${currentModel.provider}/${currentModel.id}`,
 				to: `${targetModel.provider}/${targetModel.id}`,
@@ -8436,7 +9834,12 @@ export class AgentSession {
 		}
 	}
 
-	async #resolveContextPromotionTarget(currentModel: Model, contextWindow: number): Promise<Model | undefined> {
+	async #resolveContextPromotionTarget(
+		currentModel: Model,
+		contextWindow: number,
+		signal?: AbortSignal,
+	): Promise<Model | undefined> {
+		if (signal?.aborted) return undefined;
 		const availableModels = this.#modelRegistry.getAvailable();
 		if (availableModels.length === 0) return undefined;
 
@@ -8445,18 +9848,37 @@ export class AgentSession {
 		if (modelsAreEqual(candidate, currentModel)) return undefined;
 		if (candidate.contextWindow <= contextWindow) return undefined;
 		const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
-		if (!apiKey) return undefined;
+		if (!apiKey || signal?.aborted) return undefined;
 		return candidate;
 	}
 
+	#canonicalSelector(model: Model, selector?: string, thinkingLevel?: ThinkingLevel): string {
+		const parsed = selector ? parseModelString(selector) : undefined;
+		const base = parsed ? `${parsed.provider}/${parsed.id}` : `${model.provider}/${model.id}`;
+		return thinkingLevel === undefined ? (selector ?? base) : `${base}:${String(thinkingLevel).toLowerCase()}`;
+	}
+
+	#clearActiveRetryFallback(): void {
+		this.#defaultFallbackController = undefined;
+		this.#defaultFallbackExhaustedLastTurn = false;
+	}
+
 	#setModelWithProviderSessionReset(model: Model | undefined): void {
+		this.#defaultModelSelectionMutationRevision++;
 		const currentModel = this.model;
 		if (currentModel) {
 			this.#closeProviderSessionsForModelSwitch(currentModel, model);
 		}
 		this.agent.setModel(model);
+	}
 
-		// Re-evaluate append-only context mode — provider or setting may have changed
+	#setModelAuthoritatively(model: Model, cause: ModelChangeCause): void {
+		// Only a non-temporary cause makes a model switch authoritative: it commits
+		// any suspended provider-session scopes instead of restoring them later.
+		if (cause !== "temporary-operation") this.#commitAllTemporaryProviderSessionScopes();
+		const currentModel = this.model;
+		if (currentModel) this.#closeProviderSessionsForModelSwitch(currentModel, model);
+		this.agent.setModel(model);
 		this.#syncAppendOnlyContext(model);
 	}
 
@@ -8974,13 +10396,18 @@ export class AgentSession {
 		reason: "overflow" | "threshold" | "idle",
 		willRetry: boolean,
 		deferred = false,
-		options?: { continueAfterMaintenance?: boolean; deferHandoffMaintenance?: boolean; force?: boolean },
-	): Promise<void> {
+		options?: {
+			continueAfterMaintenance?: boolean;
+			deferHandoffMaintenance?: boolean;
+			force?: boolean;
+			signal?: AbortSignal;
+		},
+	): Promise<AutoCompactionTerminalStatus> {
 		const compactionSettings = this.settings.getGroup("compaction");
 		// `force` is the non-disableable emergency floor (F6): it bypasses the user's
 		// disabled/off settings so a resource-floor breach still compacts before OOM.
-		if (!options?.force && compactionSettings.strategy === "off") return;
-		if (!options?.force && reason !== "idle" && !compactionSettings.enabled) return;
+		if (!options?.force && compactionSettings.strategy === "off") return { kind: "skipped" };
+		if (!options?.force && reason !== "idle" && !compactionSettings.enabled) return { kind: "skipped" };
 		const generation = this.#promptGeneration;
 		if (
 			options?.deferHandoffMaintenance !== false &&
@@ -8997,27 +10424,44 @@ export class AgentSession {
 				},
 				{ generation },
 			);
-			return;
+			return { kind: "skipped" };
 		}
 
 		let action: "context-full" | "handoff" =
 			compactionSettings.strategy === "handoff" && reason !== "overflow" ? "handoff" : "context-full";
 		const continueAfterMaintenance = options?.continueAfterMaintenance !== false;
-		await this.#emitSessionEvent({ type: "auto_compaction_start", reason, action });
-		// Abort any older auto-compaction before installing this run's controller.
+		// Register the controller before the observable start event so an abort from
+		// a local subscriber, extension, dispose, or caller signal owns this run.
 		this.#autoCompactionAbortController?.abort();
 		const autoCompactionAbortController = new AbortController();
 		this.#autoCompactionAbortController = autoCompactionAbortController;
-		const autoCompactionSignal = autoCompactionAbortController.signal;
+		const autoCompactionSignal = options?.signal
+			? AbortSignal.any([autoCompactionAbortController.signal, options.signal])
+			: autoCompactionAbortController.signal;
 		let maintenanceAttemptSignature: string | undefined;
+		const emitAborted = async (): Promise<AutoCompactionTerminalStatus> => {
+			await this.#emitSessionEvent({
+				type: "auto_compaction_end",
+				action,
+				result: undefined,
+				aborted: true,
+				willRetry: false,
+			});
+			return { kind: "aborted", source: "signal" };
+		};
 
 		try {
+			if (autoCompactionSignal.aborted) return { kind: "aborted", source: "signal" };
+			await this.#emitSessionEvent({ type: "auto_compaction_start", reason, action });
+			if (autoCompactionSignal.aborted) return await emitAborted();
+
 			if (compactionSettings.strategy === "handoff" && reason !== "overflow") {
 				const handoffFocus = AUTO_HANDOFF_THRESHOLD_FOCUS;
 				const handoffResult = await this.handoff(handoffFocus, {
 					autoTriggered: true,
-					signal: this.#autoCompactionAbortController.signal,
+					signal: autoCompactionSignal,
 				});
+
 				if (!handoffResult) {
 					const aborted = autoCompactionSignal.aborted;
 					if (aborted) {
@@ -9028,13 +10472,15 @@ export class AgentSession {
 							aborted: true,
 							willRetry: false,
 						});
-						return;
+						return { kind: "aborted", source: "signal" };
 					}
 					logger.warn("Auto-handoff returned no document; falling back to context-full maintenance", {
 						reason,
 					});
 					action = "context-full";
 				}
+				if (autoCompactionSignal.aborted) return await emitAborted();
+
 				if (handoffResult) {
 					await this.#emitSessionEvent({
 						type: "auto_compaction_end",
@@ -9043,15 +10489,12 @@ export class AgentSession {
 						aborted: false,
 						willRetry: false,
 					});
-					if (
-						continueAfterMaintenance &&
-						!autoCompactionSignal.aborted &&
-						reason !== "idle" &&
-						compactionSettings.autoContinue !== false
-					) {
+					if (autoCompactionSignal.aborted) return { kind: "aborted", source: "signal" };
+					if (continueAfterMaintenance && reason !== "idle" && compactionSettings.autoContinue !== false) {
 						this.#scheduleAutoContinuePrompt(generation);
 					}
-					return;
+					if (autoCompactionSignal.aborted) return { kind: "aborted", source: "signal" };
+					return { kind: "compacted" };
 				}
 			}
 
@@ -9064,7 +10507,7 @@ export class AgentSession {
 					willRetry: false,
 					skipped: true,
 				});
-				return;
+				return { kind: "skipped" };
 			}
 
 			const availableModels = this.#modelRegistry.getAvailable();
@@ -9077,9 +10520,11 @@ export class AgentSession {
 					willRetry: false,
 					skipped: true,
 				});
-				return;
+				return { kind: "skipped" };
 			}
 
+			if (autoCompactionSignal.aborted) return await emitAborted();
+
 			const pathEntries = this.sessionManager.getBranch();
 
 			// Emergency/overflow-recovery compaction is conservative: apply the token
@@ -9089,6 +10534,8 @@ export class AgentSession {
 			const preparation = prepareCompaction(pathEntries, compactionSettings, {
 				tokenCorrectionRatio: overflowRatio !== undefined ? Math.max(1, overflowRatio) : undefined,
 			});
+			if (autoCompactionSignal.aborted) return await emitAborted();
+
 			if (!preparation) {
 				const continuationSkipReason = willRetry ? this.#detectOverflowRetryContinuationSkip() : undefined;
 				await this.#emitSessionEvent({
@@ -9106,6 +10553,8 @@ export class AgentSession {
 					this.#scheduleAgentContinue({
 						delayMs: 100,
 						generation,
+						suppressPredecessorAgentEnd: true,
+
 						shouldContinue: () => this.agent.hasQueuedMessages(),
 						onSkip: skipReason => this.#logCompactionContinuationSkipped("queued_continue", skipReason),
 						onError: error => this.#logCompactionContinuationError("queued_continue", error),
@@ -9113,7 +10562,7 @@ export class AgentSession {
 				} else if (continueAfterMaintenance && reason !== "idle" && compactionSettings.autoContinue !== false) {
 					this.#scheduleAutoContinuePrompt(generation);
 				}
-				return;
+				return { kind: "skipped" };
 			}
 
 			let hookCompaction: CompactionResult | undefined;
@@ -9128,6 +10577,7 @@ export class AgentSession {
 					customInstructions: undefined,
 					signal: autoCompactionSignal,
 				})) as SessionBeforeCompactResult | undefined;
+				if (autoCompactionSignal.aborted) return await emitAborted();
 
 				if (hookResult?.cancel) {
 					await this.#emitSessionEvent({
@@ -9137,7 +10587,7 @@ export class AgentSession {
 						aborted: true,
 						willRetry: false,
 					});
-					return;
+					return { kind: "aborted", source: "hook" };
 				}
 
 				if (hookResult?.compaction) {
@@ -9147,6 +10597,7 @@ export class AgentSession {
 			}
 
 			const compactionPrep = await this.#prepareCompactionFromHooks(preparation, hookCompaction);
+			if (autoCompactionSignal.aborted) return await emitAborted();
 
 			let summary: string;
 			let shortSummary: string | undefined;
@@ -9181,7 +10632,7 @@ export class AgentSession {
 						errorMessage:
 							"Auto-compaction skipped: previous unchanged maintenance request exceeded the model context window; change or reduce the conversation before retrying maintenance.",
 					});
-					return;
+					return { kind: "skipped" };
 				}
 				const retrySettings = this.settings.getGroup("retry");
 				const telemetry = resolveTelemetry(this.agent.telemetry, this.sessionId);
@@ -9195,6 +10646,8 @@ export class AgentSession {
 					let attempt = 0;
 					while (true) {
 						try {
+							if (autoCompactionSignal.aborted) return await emitAborted();
+
 							compactResult = await compact(preparation, candidate, apiKey, undefined, autoCompactionSignal, {
 								...this.#maintenanceProviderTransport(),
 								promptOverride: compactionPrep.hookPrompt,
@@ -9293,7 +10746,7 @@ export class AgentSession {
 					aborted: true,
 					willRetry: false,
 				});
-				return;
+				return { kind: "aborted", source: "signal" };
 			}
 
 			const compactionEntryId = this.sessionManager.appendCompaction(
@@ -9306,6 +10759,7 @@ export class AgentSession {
 				preserveData,
 			);
 			await this.#applyCompactionPostAppend(compactionEntryId, firstKeptEntryId, fromExtension);
+			if (autoCompactionSignal.aborted) return await emitAborted();
 
 			const result: CompactionResult = {
 				summary,
@@ -9326,6 +10780,7 @@ export class AgentSession {
 				willRetry: willRetry && !continuationSkipReason,
 				continuationSkipReason,
 			});
+			if (autoCompactionSignal.aborted) return { kind: "aborted", source: "signal" };
 
 			if (willRetry) {
 				this.#scheduleOverflowRetryContinuation(generation);
@@ -9335,6 +10790,7 @@ export class AgentSession {
 				this.#scheduleAgentContinue({
 					delayMs: 100,
 					generation,
+					suppressPredecessorAgentEnd: true,
 					shouldContinue: () => this.agent.hasQueuedMessages(),
 					onSkip: reason => this.#logCompactionContinuationSkipped("queued_continue", reason),
 					onError: error => this.#logCompactionContinuationError("queued_continue", error),
@@ -9342,6 +10798,7 @@ export class AgentSession {
 			} else if (continueAfterMaintenance && reason !== "idle" && compactionSettings.autoContinue !== false) {
 				this.#scheduleAutoContinuePrompt(generation);
 			}
+			return { kind: "compacted" };
 		} catch (error) {
 			if (autoCompactionSignal.aborted) {
 				await this.#emitSessionEvent({
@@ -9351,7 +10808,7 @@ export class AgentSession {
 					aborted: true,
 					willRetry: false,
 				});
-				return;
+				return { kind: "aborted", source: "signal" };
 			}
 			const errorMessage = error instanceof Error ? error.message : "compaction failed";
 			if (maintenanceAttemptSignature && this.#isOversizedMaintenanceError(errorMessage)) {
@@ -9368,6 +10825,7 @@ export class AgentSession {
 						? `Context overflow recovery failed: ${errorMessage}`
 						: `Auto-compaction failed: ${errorMessage}`,
 			});
+			return { kind: "failed" };
 		} finally {
 			if (this.#autoCompactionAbortController === autoCompactionAbortController) {
 				this.#autoCompactionAbortController = undefined;
@@ -9400,20 +10858,30 @@ export class AgentSession {
 	 * (auth/400/not-found) surface immediately; usage-limit, transient, and
 	 * unknown/no-code errors are retryable.
 	 */
+
 	#isRetryableError(message: AssistantMessage): boolean {
-		const classification = this.#classifyErrorForRetry(message);
-		if (classification === "local_unavailable") {
-			return this.#hasRetryFallbackCandidate({
-				currentSelector: this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined,
-				requireNonLocal: true,
-			});
+		if (message.errorMessage?.startsWith("Model fallback chain exhausted;")) return false;
+		const managedFallback = this.#defaultFallbackChain().chain.entries.length > 1;
+		if (!managedFallback) {
+			const classification = this.#classifyErrorForRetry(message);
+			return (
+				classification === "usage_limit" ||
+				classification === "transient" ||
+				classification === "unknown" ||
+				classification === "first_event_timeout"
+			);
 		}
-		return (
-			classification === "usage_limit" ||
-			classification === "transient" ||
-			classification === "unknown" ||
-			classification === "first_event_timeout"
-		);
+		const trigger = classifyFallbackTrigger({ message: message.errorMessage, status: message.errorStatus });
+		if (
+			trigger.class === "rate_limit" ||
+			trigger.class === "quota" ||
+			trigger.class === "auth" ||
+			trigger.class === "server"
+		) {
+			return true;
+		}
+		const classification = this.#classifyErrorForRetry(message);
+		return classification === "transient" || classification === "unknown" || classification === "first_event_timeout";
 	}
 
 	#isTransientErrorMessage(errorMessage: string): boolean {
@@ -9548,232 +11016,6 @@ export class AgentSession {
 		return "unknown";
 	}
 
-	#getRetryFallbackChains(): RetryFallbackChains {
-		const configuredChains = this.settings.get("retry.fallbackChains");
-		if (!configuredChains || typeof configuredChains !== "object") return {};
-		return configuredChains as RetryFallbackChains;
-	}
-
-	#validateRetryFallbackChains(): void {
-		const configuredChains = this.settings.get("retry.fallbackChains");
-		if (configuredChains === undefined) return;
-		if (!configuredChains || typeof configuredChains !== "object" || Array.isArray(configuredChains)) {
-			const msg = "retry.fallbackChains must be a mapping of role names to selector arrays.";
-			logger.warn(msg);
-			this.configWarnings.push(msg);
-			return;
-		}
-
-		for (const [role, chain] of Object.entries(configuredChains)) {
-			if (!Array.isArray(chain)) {
-				const msg = `Fallback chain for role '${role}' must be an array of selector strings.`;
-				logger.warn(msg);
-				this.configWarnings.push(msg);
-				continue;
-			}
-			for (const selectorStr of chain) {
-				if (typeof selectorStr !== "string") {
-					const msg = `Fallback chain for role '${role}' contains a non-string selector.`;
-					logger.warn(msg);
-					this.configWarnings.push(msg);
-					continue;
-				}
-				const parsed = parseRetryFallbackSelector(selectorStr);
-				if (!parsed) {
-					const msg = `Invalid fallback selector format in role '${role}': ${selectorStr}`;
-					logger.warn(msg);
-					this.configWarnings.push(msg);
-					continue;
-				}
-				const exists = this.#modelRegistry.find(parsed.provider, parsed.id);
-				if (!exists) {
-					const msg = `Fallback chain for role '${role}' references unknown model: ${selectorStr}`;
-					logger.warn(msg);
-					this.configWarnings.push(msg);
-				}
-			}
-		}
-	}
-
-	#getRetryFallbackRevertPolicy(): RetryFallbackRevertPolicy {
-		return this.settings.get("retry.fallbackRevertPolicy") === "never" ? "never" : "cooldown-expiry";
-	}
-
-	#getRetryFallbackPrimarySelector(role: string): RetryFallbackSelector | undefined {
-		const configuredSelector = this.settings.getModelRole(role);
-		return configuredSelector ? parseRetryFallbackSelector(configuredSelector) : undefined;
-	}
-
-	#clearActiveRetryFallback(): void {
-		this.#activeRetryFallback = undefined;
-	}
-
-	#isRetryFallbackSelectorSuppressed(selector: RetryFallbackSelector): boolean {
-		return this.#modelRegistry.isSelectorSuppressed(selector.raw);
-	}
-
-	#noteRetryFallbackCooldown(currentSelector: string, retryAfterMs: number | undefined, errorMessage: string): void {
-		let cooldownMs = retryAfterMs;
-		if (!cooldownMs || cooldownMs <= 0) {
-			const reason = parseRateLimitReason(errorMessage);
-			cooldownMs = reason === "UNKNOWN" ? 5 * 60 * 1000 : calculateRateLimitBackoffMs(reason);
-		}
-		this.#modelRegistry.suppressSelector(currentSelector, Date.now() + cooldownMs);
-	}
-
-	#resolveRetryFallbackRole(currentSelector: string): string | undefined {
-		const parsedCurrent = parseRetryFallbackSelector(currentSelector);
-		if (!parsedCurrent) return undefined;
-		const currentBaseSelector = formatRetryFallbackBaseSelector(parsedCurrent);
-		for (const role of Object.keys(this.#getRetryFallbackChains())) {
-			const primarySelector = this.#getRetryFallbackPrimarySelector(role);
-			if (!primarySelector) continue;
-			if (primarySelector.raw === currentSelector) return role;
-			if (formatRetryFallbackBaseSelector(primarySelector) === currentBaseSelector) return role;
-		}
-		return undefined;
-	}
-
-	#getRetryFallbackEffectiveChain(role: string): RetryFallbackSelector[] {
-		const primarySelector = this.#getRetryFallbackPrimarySelector(role);
-		if (!primarySelector) return [];
-		const chain = [primarySelector];
-		const seen = new Set<string>([primarySelector.raw]);
-		for (const selector of this.#getRetryFallbackChains()[role] ?? []) {
-			const parsed = parseRetryFallbackSelector(selector);
-			if (!parsed || seen.has(parsed.raw)) continue;
-			seen.add(parsed.raw);
-			chain.push(parsed);
-		}
-		return chain;
-	}
-
-	#hasRetryFallbackCandidate(options: { currentSelector: string | undefined; requireNonLocal?: boolean }): boolean {
-		if (!options.currentSelector) return false;
-		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(options.currentSelector);
-		if (!role) return false;
-		for (const selector of this.#findRetryFallbackCandidates(role, options.currentSelector)) {
-			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
-			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
-			if (!candidate) continue;
-			if (options.requireNonLocal && isLocalModelEndpoint(candidate)) continue;
-			return true;
-		}
-		return false;
-	}
-
-	#findRetryFallbackCandidates(role: string, currentSelector: string): RetryFallbackSelector[] {
-		const chain = this.#getRetryFallbackEffectiveChain(role);
-		if (chain.length <= 1) return [];
-		const parsedCurrent = parseRetryFallbackSelector(currentSelector);
-		const currentBaseSelector = parsedCurrent ? formatRetryFallbackBaseSelector(parsedCurrent) : undefined;
-		const exactIndex = chain.findIndex(selector => selector.raw === currentSelector);
-		if (exactIndex >= 0) return chain.slice(exactIndex + 1);
-		const baseIndex = currentBaseSelector
-			? chain.findIndex(selector => formatRetryFallbackBaseSelector(selector) === currentBaseSelector)
-			: -1;
-		if (baseIndex >= 0) return chain.slice(baseIndex + 1);
-		return chain.slice(1);
-	}
-
-	async #applyRetryFallbackCandidate(
-		role: string,
-		selector: RetryFallbackSelector,
-		currentSelector: string,
-	): Promise<void> {
-		const candidate = this.#modelRegistry.find(selector.provider, selector.id);
-		if (!candidate) {
-			throw new Error(`Retry fallback model not found: ${selector.raw}`);
-		}
-		const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
-		if (!apiKey) {
-			throw new Error(`No API key for retry fallback ${selector.raw}`);
-		}
-
-		const currentThinkingLevel = this.thinkingLevel;
-		const nextThinkingLevel = selector.thinkingLevel ?? currentThinkingLevel;
-
-		this.#setModelWithProviderSessionReset(candidate);
-		this.sessionManager.appendModelChange(`${candidate.provider}/${candidate.id}`, "temporary");
-		this.settings.getStorage()?.recordModelUsage(`${candidate.provider}/${candidate.id}`);
-		this.setThinkingLevel(nextThinkingLevel);
-		if (!this.#activeRetryFallback) {
-			this.#activeRetryFallback = {
-				role,
-				originalSelector: currentSelector,
-				originalThinkingLevel: currentThinkingLevel,
-				lastAppliedFallbackThinkingLevel: nextThinkingLevel,
-			};
-		} else {
-			this.#activeRetryFallback.lastAppliedFallbackThinkingLevel = nextThinkingLevel;
-		}
-		await this.#emitSessionEvent({
-			type: "retry_fallback_applied",
-			from: currentSelector,
-			to: selector.raw,
-			role,
-		});
-	}
-
-	async #tryRetryModelFallback(currentSelector: string, options?: { requireNonLocal?: boolean }): Promise<boolean> {
-		const role = this.#activeRetryFallback?.role ?? this.#resolveRetryFallbackRole(currentSelector);
-		if (!role) return false;
-
-		for (const selector of this.#findRetryFallbackCandidates(role, currentSelector)) {
-			if (this.#isRetryFallbackSelectorSuppressed(selector)) continue;
-			const candidate = this.#modelRegistry.find(selector.provider, selector.id);
-			if (!candidate) continue;
-			if (options?.requireNonLocal && isLocalModelEndpoint(candidate)) continue;
-			const apiKey = await this.#modelRegistry.getApiKey(candidate, this.sessionId);
-			if (!apiKey) continue;
-			await this.#applyRetryFallbackCandidate(role, selector, currentSelector);
-			return true;
-		}
-
-		return false;
-	}
-
-	async #maybeRestoreRetryFallbackPrimary(): Promise<void> {
-		if (!this.#activeRetryFallback) return;
-		if (this.#getRetryFallbackRevertPolicy() !== "cooldown-expiry") return;
-
-		const {
-			originalSelector: originalSelectorRaw,
-			originalThinkingLevel,
-			lastAppliedFallbackThinkingLevel,
-		} = this.#activeRetryFallback;
-		const originalSelector = parseRetryFallbackSelector(originalSelectorRaw);
-		if (!originalSelector) {
-			this.#clearActiveRetryFallback();
-			return;
-		}
-
-		const currentModel = this.model;
-		if (!currentModel) return;
-		const currentSelector = formatRetryFallbackSelector(currentModel, this.thinkingLevel);
-		if (currentSelector === originalSelector.raw) {
-			if (!this.#isRetryFallbackSelectorSuppressed(originalSelector)) {
-				this.#clearActiveRetryFallback();
-			}
-			return;
-		}
-		if (this.#isRetryFallbackSelectorSuppressed(originalSelector)) return;
-
-		const primaryModel = this.#modelRegistry.find(originalSelector.provider, originalSelector.id);
-		if (!primaryModel) return;
-		const apiKey = await this.#modelRegistry.getApiKey(primaryModel, this.sessionId);
-		if (!apiKey) return;
-
-		const currentThinkingLevel = this.thinkingLevel;
-		const thinkingToApply =
-			currentThinkingLevel === lastAppliedFallbackThinkingLevel ? originalThinkingLevel : currentThinkingLevel;
-		this.#setModelWithProviderSessionReset(primaryModel);
-		this.sessionManager.appendModelChange(`${primaryModel.provider}/${primaryModel.id}`, "temporary");
-		this.settings.getStorage()?.recordModelUsage(`${primaryModel.provider}/${primaryModel.id}`);
-		this.setThinkingLevel(thinkingToApply);
-		this.#clearActiveRetryFallback();
-	}
-
 	#parseRetryAfterMsFromError(errorMessage: string): number | undefined {
 		const now = Date.now();
 		const retryAfterMsMatch = /retry-after-ms\s*[:=]\s*(\d+)/i.exec(errorMessage);
@@ -9821,149 +11063,394 @@ export class AgentSession {
 			}
 		}
 
-		// Smart Fallback if no exact headers found
+		// No provider retry hint was available.
 		return undefined;
 	}
 
+	#managedFallbackPromptOptions(): {
+		fallbackManaged?: boolean;
+		nextFallbackAttempt?: (model: Model) => ReturnType<typeof beginAttempt>;
+		onManagedAttemptAccepted?: () => void;
+		onManagedAttemptOutcome?: (
+			outcome: ManagedAttemptOutcome,
+		) => ManagedAttemptDecision | Promise<ManagedAttemptDecision>;
+	} {
+		const controller = this.#defaultFallbackChain();
+		if (controller.chain.entries.length < 2) return {};
+		return {
+			fallbackManaged: true,
+			nextFallbackAttempt: model => {
+				controller.onAttemptStarted();
+				return beginAttempt(formatModelString(model), String(++this.#fallbackInvocationId));
+			},
+			onManagedAttemptAccepted: () => controller.resetAttemptBudget(),
+			onManagedAttemptOutcome: outcome => this.#handleManagedAttemptOutcome(outcome),
+		};
+	}
+
+	async #resetDefaultFallbackForNewTurn(): Promise<void> {
+		if (!this.#defaultFallbackExhaustedLastTurn) return;
+		const controller = this.#defaultFallbackChain();
+		this.#defaultFallbackExhaustedLastTurn = false;
+		controller.resetForNewTurn();
+		if (controller.chain.entries.length > 1) {
+			await this.#advanceDefaultFallback(controller, "new_turn", 0);
+		}
+	}
+
+	async #ensureDefaultFallbackResolution(): Promise<void> {
+		const controller = this.#defaultFallbackChain();
+		if (controller.chain.entries.length < 2) return;
+		const resolutionStart = controller.activeIndex;
+		const resolution = await resolveModelChainWithAuth(
+			controller.chain.entries.slice(resolutionStart),
+			this.#modelRegistry,
+			this.settings,
+			this.sessionId,
+			{ managedFallback: true },
+		);
+		const activeIndex = resolutionStart + resolution.activeIndex;
+		if (activeIndex > resolutionStart) {
+			this.seedDefaultFallbackResolution(activeIndex, [...controller.skips, ...resolution.skips]);
+		} else {
+			controller.seedResolution(activeIndex, [...controller.skips, ...resolution.skips]);
+		}
+		if (!resolution.model) throw new Error(this.#fallbackExhaustionError(controller));
+		this.#setModelAuthoritatively(resolution.model, "restore");
+		this.setThinkingLevel(resolution.explicitThinkingLevel ? resolution.thinkingLevel : this.thinkingLevel);
+	}
+
 	/**
-	 * Handle retryable errors with exponential backoff.
-	 * @returns true if retry was initiated, false if max retries exceeded or disabled
+	 * Materialize the default controller from the persisted configured-chain
+	 * metadata. Consumers seed only resolution state; role/origin/identity stay
+	 * intrinsic to controller construction and are never inferred at runtime.
 	 */
-	async #handleRetryableError(message: AssistantMessage): Promise<boolean> {
-		const retrySettings = this.settings.getGroup("retry");
-		if (!retrySettings.enabled) return false;
-		const retryClassification = this.#classifyErrorForRetry(message);
-		const unboundedClass = retryClassification === "transient" || retryClassification === "unknown";
-		const localUnavailable = retryClassification === "local_unavailable";
+	#defaultFallbackChain(): FallbackChainController {
+		const configuredChain = this.sessionManager.buildSessionContext().configuredModelChains.default;
+		const settingsEntries = normalizeModelSelectorValue(
+			this.settings.getModelRole("default") ?? (this.model ? formatModelString(this.model) : undefined),
+		);
+		const materializeSettingsChain =
+			configuredChain?.origin === "legacy_session" &&
+			configuredChain.entries.length === 1 &&
+			settingsEntries.length > 1;
+		if (materializeSettingsChain) {
+			this.setConfiguredModelChain("default", settingsEntries, "modelRoles");
+		}
+		const chain: ConfiguredFallbackChain = materializeSettingsChain
+			? { role: "default", entries: settingsEntries, origin: "modelRoles", explicitHead: true }
+			: configuredChain
+				? { ...configuredChain, entries: [...configuredChain.entries] }
+				: { role: "default", entries: settingsEntries, origin: "session", explicitHead: true };
+		const existing = this.#defaultFallbackController;
+		if (
+			existing &&
+			(existing.chain.origin === "runtime" || existing.chain.entries.join("\u0000") === chain.entries.join("\u0000"))
+		) {
+			return existing;
+		}
+		this.#defaultFallbackController = new FallbackChainController(chain, this.settings.get("fallback.maxAttempts"));
+		return this.#defaultFallbackController;
+	}
 
-		const generation = this.#promptGeneration;
-		this.#retryAttempt++;
+	async #handleManagedAttemptOutcome(outcome: ManagedAttemptOutcome): Promise<ManagedAttemptDecision> {
+		if (outcome.type === "run_terminal") {
+			this.#defaultFallbackChain().resetAttemptBudget();
+			return { type: "terminal", terminal: { stopReason: outcome.reason } };
+		}
+		return this.#handleRetryableError(
+			outcome.failure.message,
+			true,
+			outcome.failure.transportFailure,
+		) as Promise<ManagedAttemptDecision>;
+	}
 
-		// Create retry promise on first attempt so waitForRetry() can await it
-		// Ensure only one promise exists (avoid orphaned promises from concurrent calls)
-		if (!this.#retryPromise) {
-			const { promise, resolve } = Promise.withResolvers<void>();
-			this.#retryPromise = promise;
-			this.#retryResolve = resolve;
+	#managedFallbackExhaustionMessage(discarded: AssistantMessage, errorMessage: string): AssistantMessage {
+		return {
+			...discarded,
+			content: [{ type: "text", text: "" }],
+			stopReason: "error",
+			errorMessage,
+			timestamp: Date.now(),
+		};
+	}
+
+	#managedFallbackExhaustionDecision(discarded: AssistantMessage, errorMessage: string): ManagedAttemptDecision {
+		return {
+			type: "terminal",
+			terminal: {
+				stopReason: "exhausted",
+				messages: [this.#managedFallbackExhaustionMessage(discarded, errorMessage)],
+			},
+		};
+	}
+
+	#fallbackTriggerFor(
+		message: AssistantMessage,
+		allowLegacyUsageLimit: boolean,
+		transportFailure?: TransportFailureFacts,
+	): { class: FallbackTriggerClass; retryAfterMs?: number } | undefined {
+		const transport = classifyFallbackTrigger(transportFailure ?? { status: message.errorStatus });
+		if (transport.class !== "other") return transport;
+		const classification = this.#classifyErrorForRetry(message);
+		if (allowLegacyUsageLimit && classification === "usage_limit") {
+			return { class: "quota" };
+		}
+		if (classification === "transient" || classification === "first_event_timeout" || classification === "unknown") {
+			return { class: "server", retryAfterMs: transport.retryAfterMs };
 		}
+		return undefined;
+	}
 
-		if (!unboundedClass && this.#retryAttempt > retrySettings.maxRetries) {
-			// Max retries exceeded, emit final failure and reset
-			await this.#emitSessionEvent({
-				type: "auto_retry_end",
-				success: false,
-				attempt: this.#retryAttempt - 1,
-				finalError: message.errorMessage,
+	async #advanceDefaultFallback(
+		controller: FallbackChainController,
+		reason: string,
+		attemptsUsed: number,
+	): Promise<boolean> {
+		while (!controller.isExhausted()) {
+			const selector = controller.currentSelector();
+			if (!selector) return false;
+			const resolved = resolveModelRoleValue(selector, this.#modelRegistry.getAvailable(), {
+				settings: this.settings,
+				matchPreferences: { usageOrder: this.settings.getStorage()?.getModelUsageOrder() },
+				modelRegistry: this.#modelRegistry,
 			});
-			this.#retryAttempt = 0;
-			this.#resolveRetry(); // Resolve so waitForRetry() completes
+			if (!resolved.model) {
+				controller.onResolutionSkip("unknown_model");
+				continue;
+			}
+			const managedCursorUnavailable = managedCursorFallbackUnavailableReason(resolved.model, selector);
+			if (managedCursorUnavailable) {
+				controller.onResolutionSkip(managedCursorUnavailable);
+				continue;
+			}
+			const key = await this.#modelRegistry.getApiKey(resolved.model, this.sessionId);
+			if (!key) {
+				controller.onResolutionSkip("unauthenticated");
+				continue;
+			}
+			const from =
+				controller.tried.at(-1)?.selector ?? controller.chain.entries[controller.activeIndex - 1] ?? selector;
+			const to = selector;
+			this.#setModelAuthoritatively(resolved.model, "fallback-switch");
+			this.setThinkingLevel(resolved.explicitThinkingLevel ? resolved.thinkingLevel : this.thinkingLevel);
+			if (from !== to) {
+				this.#emit({
+					type: "model_fallback_switched",
+					eventId: crypto.randomUUID(),
+					from,
+					to,
+					reason,
+					role:
+						controller.chain.origin === "subagent"
+							? (controller.chain.identity ?? controller.chain.role)
+							: controller.chain.role,
+					scope: controller.chain.origin === "subagent" ? "subagent-call" : "session",
+					activeIndex: controller.activeIndex,
+					chainLength: controller.chain.entries.length,
+					attemptsUsed,
+				});
+			}
+			return true;
+		}
+		return false;
+	}
+
+	#emitResolutionFallbackSwitch(controller: FallbackChainController): void {
+		if (controller.activeIndex <= 0) return;
+		const to = controller.currentSelector();
+		const from = controller.chain.entries[controller.activeIndex - 1];
+		if (!from || !to || from === to) return;
+		const event: Extract<AgentSessionEvent, { type: "model_fallback_switched" }> = {
+			type: "model_fallback_switched",
+			eventId: crypto.randomUUID(),
+			from,
+			to,
+			reason: "resolution",
+			role:
+				controller.chain.origin === "subagent"
+					? (controller.chain.identity ?? controller.chain.role)
+					: controller.chain.role,
+			scope: controller.chain.origin === "subagent" ? "subagent-call" : "session",
+			activeIndex: controller.activeIndex,
+			chainLength: controller.chain.entries.length,
+			attemptsUsed: 0,
+		};
+		if (this.#eventListeners.length === 0) {
+			this.#pendingFallbackSwitches.push(event);
+		} else {
+			this.#emit(event);
+		}
+	}
+
+	#fallbackExhaustionError(controller: FallbackChainController): string {
+		const tried = controller.tried.map(failure => `${failure.selector} (${failure.reason})`).join(", ") || "none";
+		const skipped = controller.skips.map(skip => `${skip.selector} (${skip.reason})`).join(", ") || "none";
+		return `Model fallback chain exhausted; models tried: ${tried}; models skipped: ${skipped}`;
+	}
+
+	async #markFailedManagedCredential(trigger: { class: FallbackTriggerClass; retryAfterMs?: number }): Promise<void> {
+		if (!this.model || (trigger.class !== "auth" && trigger.class !== "quota" && trigger.class !== "rate_limit"))
+			return;
+
+		const authStorage = this.#modelRegistry.authStorage;
+		if (trigger.class === "auth") {
+			const apiKey = await this.#modelRegistry.getApiKey(this.model, this.sessionId);
+			if (isAuthenticated(apiKey)) {
+				await authStorage.invalidateCredentialMatching(this.model.provider, apiKey, { sessionId: this.sessionId });
+			}
+			return;
+		}
+
+		await authStorage.markUsageLimitReached(this.model.provider, this.sessionId, {
+			retryAfterMs: trigger.retryAfterMs,
+		});
+	}
+
+	/** Handle retryable errors with exponential backoff. */
+	async #handleRetryableError(
+		message: AssistantMessage,
+		managedOutcome = false,
+		transportFailure?: TransportFailureFacts,
+	): Promise<boolean | ManagedAttemptDecision> {
+		const controller = this.#defaultFallbackChain();
+		const managedFallback = controller.chain.entries.length > 1;
+		const trigger = this.#fallbackTriggerFor(message, !managedFallback, transportFailure);
+		if (!trigger) {
+			return managedOutcome
+				? this.#managedFallbackExhaustionDecision(message, message.errorMessage || "Model fallback attempt failed")
+				: false;
+		}
+		const retrySettings = this.settings.getGroup("retry");
+		const legacyRetryConfigured =
+			this.settings.has("retry.enabled") ||
+			this.settings.has("retry.maxRetries") ||
+			this.settings.has("retry.baseDelayMs") ||
+			this.settings.has("retry.maxDelayMs");
+		// A bare default retry configuration must preserve the historical
+		// fail-closed behavior for generic provider errors. Explicit retry
+		// settings opt into the resilient legacy retry path.
+		if (!managedFallback && (!retrySettings.enabled || !legacyRetryConfigured)) return false;
+		const legacyClassification = managedFallback ? undefined : this.#classifyErrorForRetry(message);
+		const legacyUnbounded = legacyClassification === "transient" || legacyClassification === "unknown";
+		const attemptsUsed = managedFallback ? controller.attemptsUsed || 1 : this.#retryAttempt + 1;
+		const outcome = managedFallback
+			? controller.onAttemptFailure(trigger.class, message.errorMessage || "Unknown error")
+			: !legacyUnbounded && attemptsUsed > retrySettings.maxRetries
+				? "exhausted"
+				: "retry";
+		if (outcome === "exhausted") {
+			if (managedFallback) {
+				const errorMessage = this.#fallbackExhaustionError(controller);
+				this.emitNotice("error", errorMessage, "fallback");
+				this.#defaultFallbackExhaustedLastTurn = true;
+				controller.resetSticky();
+				return managedOutcome ? this.#managedFallbackExhaustionDecision(message, errorMessage) : false;
+			}
 			return false;
 		}
 
+		const generation = this.#promptGeneration;
 		const errorMessage = message.errorMessage || "Unknown error";
-		const parsedRetryAfterMs = this.#parseRetryAfterMsFromError(errorMessage);
-		let delayMs = retrySettings.baseDelayMs * 2 ** (this.#retryAttempt - 1);
-		let switchedCredential = false;
-		let switchedModel = false;
-
-		if (this.model && isUsageLimitError(errorMessage)) {
-			const retryAfterMs = parsedRetryAfterMs ?? calculateRateLimitBackoffMs(parseRateLimitReason(errorMessage));
-			const switched = await this.#modelRegistry.authStorage.markUsageLimitReached(
-				this.model.provider,
-				this.sessionId,
-				{
-					retryAfterMs,
-					baseUrl: this.model.baseUrl,
-				},
-			);
-			if (switched) {
-				switchedCredential = true;
-				delayMs = 0;
-			} else if (retryAfterMs > delayMs) {
-				// No more accounts to switch to — wait out the backoff
-				delayMs = retryAfterMs;
-			}
-		}
-
-		const currentSelector = this.model ? formatRetryFallbackSelector(this.model, this.thinkingLevel) : undefined;
-		if (!switchedCredential && currentSelector) {
-			this.#noteRetryFallbackCooldown(currentSelector, parsedRetryAfterMs, errorMessage);
-			switchedModel = await this.#tryRetryModelFallback(currentSelector, { requireNonLocal: localUnavailable });
-			if (switchedModel) {
-				delayMs = 0;
-			} else if (parsedRetryAfterMs && parsedRetryAfterMs > delayMs) {
-				delayMs = parsedRetryAfterMs;
-			}
-		}
-
-		// Fail-fast cap: if the provider asks us to wait longer than
-		// retry.maxDelayMs and we have no fallback credential or model to
-		// switch to, surface the error instead of sleeping. Defends against
-		// 3-hour Anthropic rate-limit windows that would otherwise leave a
-		// subagent (or interactive session) silently hung. The original
-		// assistant error message is preserved in agent state so the caller
-		// can act on it.
-		const maxDelayMs = retrySettings.maxDelayMs;
-		if (unboundedClass && !switchedCredential && !switchedModel) {
-			// Retry forever: honor a provider-supplied wait, otherwise cap the
-			// exponential backoff at the ceiling instead of giving up.
-			if (parsedRetryAfterMs !== undefined) {
-				delayMs = Math.max(delayMs, parsedRetryAfterMs);
-			} else if (maxDelayMs > 0) {
-				delayMs = Math.min(delayMs, maxDelayMs);
-			}
-		}
-		if (!unboundedClass && maxDelayMs > 0 && delayMs > maxDelayMs && !switchedCredential && !switchedModel) {
-			const attempt = this.#retryAttempt;
+		const retryAfterMs =
+			trigger.retryAfterMs ?? (managedFallback ? undefined : this.#parseRetryAfterMsFromError(errorMessage));
+		const delayMs =
+			outcome === "advance"
+				? 0
+				: managedFallback
+					? effectiveFallbackDelay(retrySettings.baseDelayMs, retrySettings.maxDelayMs, attemptsUsed, retryAfterMs)
+					: retryAfterMs !== undefined
+						? Math.max(retrySettings.baseDelayMs * 2 ** Math.max(0, attemptsUsed - 1), retryAfterMs)
+						: retrySettings.baseDelayMs * 2 ** Math.max(0, attemptsUsed - 1);
+		if (!managedFallback && !legacyUnbounded && retrySettings.maxDelayMs > 0 && delayMs > retrySettings.maxDelayMs) {
 			this.#retryAttempt = 0;
 			await this.#emitSessionEvent({
 				type: "auto_retry_end",
 				success: false,
-				attempt,
-				finalError: `Provider requested ${delayMs}ms wait, exceeds retry.maxDelayMs (${maxDelayMs}ms). Original error: ${errorMessage}`,
+				attempt: attemptsUsed,
+				finalError: `Provider requested ${delayMs}ms wait, exceeds retry.maxDelayMs (${retrySettings.maxDelayMs}ms). Original error: ${errorMessage}`,
 			});
 			this.#resolveRetry();
 			return false;
 		}
 
-		// Create and install the backoff abort controller BEFORE emitting
-		// auto_retry_start, so a synchronous retryNow()/abortRetry() invoked from
-		// an event subscriber (e.g. the TUI Esc handler) is not lost in the gap
-		// between the event and the controller assignment.
-		const retryAbortController = new AbortController();
-		this.#retryAbortController?.abort();
-		this.#retryAbortController = retryAbortController;
-		this.#retryNowRequested = false;
+		const retry = async (ownership?: ManagedAttemptContinuationOwnership): Promise<void> => {
+			if (managedFallback) await this.#markFailedManagedCredential(trigger);
+			let advanced = outcome !== "advance";
+			let resolutionError: unknown;
+			if (outcome === "advance") {
+				try {
+					advanced = await this.#advanceDefaultFallback(controller, trigger.class, attemptsUsed);
+				} catch (error) {
+					resolutionError = error;
+				}
+			}
+			if (!advanced) {
+				const errorMessage = resolutionError
+					? `${this.#fallbackExhaustionError(controller)}; resolution failed: ${resolutionError instanceof Error ? resolutionError.message : String(resolutionError)}`
+					: this.#fallbackExhaustionError(controller);
+				this.emitNotice("error", errorMessage, "fallback");
+				if (managedOutcome && ownership) {
+					this.agent.requestRunTerminal(ownership.logicalRunId, {
+						stopReason: "exhausted",
+						messages: [this.#managedFallbackExhaustionMessage(message, errorMessage)],
+					});
+				}
+				this.#defaultFallbackExhaustedLastTurn = true;
+				controller.resetSticky();
+				this.#retryAttempt = 0;
+				this.#resolveRetry();
+				return;
+			}
 
-		await this.#emitSessionEvent({
-			type: "auto_retry_start",
-			attempt: this.#retryAttempt,
-			maxAttempts: retrySettings.maxRetries,
-			delayMs,
-			errorMessage,
-			unbounded: unboundedClass,
-		});
+			this.#retryAttempt = attemptsUsed;
+			if (!this.#retryPromise) {
+				const { promise, resolve } = Promise.withResolvers<void>();
+				this.#retryPromise = promise;
+				this.#retryResolve = resolve;
+			}
 
-		// Remove error message from agent state (keep in session for history)
-		const messages = this.agent.state.messages;
-		if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-			this.agent.replaceMessages(messages.slice(0, -1));
-		}
+			const retryAbortController = new AbortController();
+			this.#retryAbortController?.abort();
+			this.#retryAbortController = retryAbortController;
+			this.#retryNowRequested = false;
+			await this.#emitSessionEvent({
+				type: "auto_retry_start",
+				attempt: this.#retryAttempt,
+				maxAttempts: managedFallback ? controller.maxAttempts : retrySettings.maxRetries,
+				delayMs,
+				errorMessage,
+				unbounded: !managedFallback && legacyUnbounded,
+			});
 
-		// Wait with exponential backoff (abortable).
-		try {
-			await scheduler.wait(delayMs, { signal: retryAbortController.signal });
-		} catch {
-			if (this.#retryAbortController !== retryAbortController) {
-				return false;
+			const messages = this.agent.state.messages;
+			if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+				this.agent.replaceMessages(messages.slice(0, -1));
 			}
-			this.#retryAbortController = undefined;
-			if (this.#retryNowRequested) {
-				// Retry-now: skip the remaining backoff and fall through to
-				// re-attempt immediately (keeps the retry session alive).
-				this.#retryNowRequested = false;
-			} else {
-				// Aborted during sleep (cancel) - emit end event so UI can clean up
+
+			try {
+				await scheduler.wait(delayMs, { signal: retryAbortController.signal });
+			} catch {
+				if (this.#retryAbortController !== retryAbortController) return;
+				this.#retryAbortController = undefined;
+				if (this.#retryNowRequested) {
+					// Fall through below so the retry continues immediately.
+				} else {
+					const attempt = this.#retryAttempt;
+					this.#retryAttempt = 0;
+					await this.#emitSessionEvent({
+						type: "auto_retry_end",
+						success: false,
+						attempt,
+						finalError: "Retry cancelled",
+					});
+					this.#resolveRetry();
+					return;
+				}
+			}
+			if (retryAbortController.signal.aborted && !this.#retryNowRequested) {
+				if (this.#retryAbortController !== retryAbortController) return;
+				this.#retryAbortController = undefined;
 				const attempt = this.#retryAttempt;
 				this.#retryAttempt = 0;
 				await this.#emitSessionEvent({
@@ -9973,28 +11460,55 @@ export class AgentSession {
 					finalError: "Retry cancelled",
 				});
 				this.#resolveRetry();
-				return false;
+				return;
 			}
-		}
-		if (this.#retryAbortController === retryAbortController) {
-			this.#retryAbortController = undefined;
-		}
+			if (this.#retryAbortController === retryAbortController) this.#retryAbortController = undefined;
+			this.#retryNowRequested = false;
 
-		// Retry via continue() outside the agent_end event callback chain.
-		// If the scheduled continue cannot run — it throws (e.g. AgentBusyError from a
-		// concurrent turn, or "Cannot continue ...") or is skipped because a newer
-		// generation took over — the agent_end that normally resolves #retryPromise
-		// never arrives. Finalize the retry in that case so #waitForPostPromptRecovery
-		// (and the in-flight prompt holding it open) cannot wedge the session as
-		// permanently busy, which would turn every later prompt() into a
-		// non-recoverable AgentBusyError loop.
-		this.#scheduleAgentContinue({
-			delayMs: 1,
-			generation,
-			onError: () => this.#failRetryRecovery("Retry continuation failed to start"),
-			onSkip: () => this.#failRetryRecovery("Retry continuation was superseded"),
-		});
+			if (managedOutcome) {
+				try {
+					await this.#checkEstimatedContextBeforePrompt();
+					if (!ownership?.isCurrent()) {
+						const attempt = this.#retryAttempt;
+						this.#retryAttempt = 0;
+						await this.#emitSessionEvent({
+							type: "auto_retry_end",
+							success: false,
+							attempt,
+							finalError: "Retry continuation was superseded",
+						});
+						this.#resolveRetry();
+						return;
+					}
+					await this.agent.continue(this.#managedFallbackPromptOptions());
+					return;
+				} catch (error) {
+					const attempt = this.#retryAttempt;
+					this.#retryAttempt = 0;
+					try {
+						await this.#emitSessionEvent({
+							type: "auto_retry_end",
+							success: false,
+							attempt,
+							finalError: error instanceof Error ? error.message : String(error),
+						});
+					} finally {
+						this.#resolveRetry();
+					}
+					throw error;
+				}
+			}
+
+			this.#scheduleAgentContinue({
+				delayMs: 1,
+				generation,
+				onError: () => this.#failRetryRecovery("Retry continuation failed to start"),
+				onSkip: () => this.#failRetryRecovery("Retry continuation was superseded"),
+			});
+		};
 
+		if (managedOutcome) return { type: "retry", continuation: retry };
+		await retry();
 		return true;
 	}
 
@@ -10040,12 +11554,26 @@ export class AgentSession {
 		this.#resolveRetry();
 	}
 
-	async #promptAgentWithIdleRetry(messages: AgentMessage[], options?: { toolChoice?: ToolChoice }): Promise<void> {
+	async #promptAgentWithIdleRetry(
+		messages: AgentMessage[],
+		options?: { toolChoice?: ToolChoice; fallbackManaged?: boolean; onRunAccepted?: () => void },
+		predecessorAgentEndHold?: symbol,
+	): Promise<void> {
 		const deadline = Date.now() + 30_000;
+		let continuationHold = predecessorAgentEndHold;
 		for (;;) {
 			try {
-				await this.agent.prompt(messages, options);
-				return;
+				const predecessorAgentEnd = this.#claimDeferredAgentEndForContinuation(
+					continuationHold ?? this.#reserveDeferredAgentEndForContinuation(),
+				);
+				continuationHold = undefined;
+				try {
+					await this.agent.prompt(messages, options);
+					return;
+				} catch (error) {
+					this.#restoreDeferredAgentEndAfterContinuationFailure(predecessorAgentEnd);
+					throw error;
+				}
 			} catch (err) {
 				if (!(err instanceof AgentBusyError)) {
 					throw err;
@@ -11003,6 +12531,10 @@ export class AgentSession {
 		this.#followUpMessages = [];
 		this.#pendingNextTurnMessages = [];
 		this.#scheduledHiddenNextTurnGeneration = undefined;
+		const suspendedWorkflowGateEmitter = switchingToDifferentSession
+			? this.#suspendWorkflowGateEmitter(previousSessionState.sessionId)
+			: undefined;
+		let unavailableDefaultChainMessage: string | undefined;
 
 		try {
 			await this.sessionManager.setSessionFile(sessionPath);
@@ -11016,53 +12548,41 @@ export class AgentSession {
 			const fallbackSelectedMCPToolNames = this.#getSessionDefaultSelectedMCPToolNames(sessionPath);
 			await this.#restoreMCPSelectionsForSessionContext(sessionContext, { fallbackSelectedMCPToolNames });
 
-			// The target session is loaded and MCP selections are restored: the
-			// switch is committed far enough to discard pre-switch delivery queues.
-			// Clear before session_switch hooks, so messages enqueued by hooks belong
-			// to the new session and remain deliverable.
+			// The target session is loaded and MCP selections are restored: discard
+			// pre-switch delivery queues before completing the restored agent state.
 			this.agent.clearAllQueues();
 
-			// Emit session_switch event to hooks
-			if (this.#extensionRunner) {
-				await this.#extensionRunner.emit({
-					type: "session_switch",
-					reason: "resume",
-					previousSessionFile,
-				});
-			}
-
 			this.agent.replaceMessages(sessionContext.messages);
 			this.#resetInjectedContextSignatures();
 			this.#syncTodoPhasesFromBranch();
-			if (switchingToDifferentSession) {
-				this.#closeAllProviderSessions("session switch");
-			} else if (didReloadConversationChange) {
-				this.#closeAllProviderSessions("session reload");
-			}
-
-			// Restore model if saved
-			const defaultModelStr = sessionContext.models.default;
-			if (defaultModelStr) {
-				const slashIdx = defaultModelStr.indexOf("/");
-				if (slashIdx > 0) {
-					const provider = defaultModelStr.slice(0, slashIdx);
-					const modelId = defaultModelStr.slice(slashIdx + 1);
-					const availableModels = this.#modelRegistry.getAvailable();
-					const match = availableModels.find(m => m.provider === provider && m.id === modelId);
-					if (match) {
-						const currentModel = this.model;
-						const shouldResetProviderState =
-							switchingToDifferentSession ||
-							(currentModel !== undefined &&
-								(currentModel.provider !== match.provider ||
-									currentModel.id !== match.id ||
-									currentModel.api !== match.api));
-						if (shouldResetProviderState) {
-							this.#setModelWithProviderSessionReset(match);
-						} else {
-							this.agent.setModel(match);
-						}
-					}
+			if (switchingToDifferentSession || didReloadConversationChange) {
+				this.#closeAllProviderSessions(switchingToDifferentSession ? "session switch" : "session reload");
+				this.#rebindProviderSessionState(new Map());
+			}
+
+			const configuredDefaultChain = sessionContext.configuredModelChains.default?.entries;
+			const defaultEntries =
+				configuredDefaultChain ?? (sessionContext.models.default ? [sessionContext.models.default] : []);
+			this.#defaultFallbackController = undefined;
+			if (defaultEntries.length > 0) {
+				const resolution = await resolveModelChainWithAuth(
+					defaultEntries,
+					this.#modelRegistry,
+					this.settings,
+					this.sessionId,
+					{ managedFallback: true },
+				);
+				const controller = this.#defaultFallbackChain();
+				this.seedDefaultFallbackResolution(resolution.activeIndex, resolution.skips);
+				if (!resolution.model) {
+					unavailableDefaultChainMessage = this.#fallbackExhaustionError(controller);
+					throw new Error(unavailableDefaultChainMessage);
+				}
+				if (!this.model || !modelsAreEqual(this.model, resolution.model)) {
+					this.#setModelAuthoritatively(resolution.model, "restore");
+				}
+				if (resolution.explicitThinkingLevel && resolution.thinkingLevel !== undefined) {
+					this.setThinkingLevel(resolution.thinkingLevel);
 				}
 			}
 
@@ -11072,9 +12592,14 @@ export class AgentSession {
 				.some(entry => entry.type === "service_tier_change");
 			const defaultThinkingLevel = this.settings.get("defaultThinkingLevel");
 			const configuredServiceTier = this.settings.get("serviceTier");
+			const persistedThinkingLevel = hasThinkingEntry
+				? (sessionContext.thinkingLevel as ThinkingLevel | undefined)
+				: defaultThinkingLevel;
 			const nextThinkingLevel = resolveThinkingLevelForModel(
 				this.model,
-				hasThinkingEntry ? (sessionContext.thinkingLevel as ThinkingLevel | undefined) : defaultThinkingLevel,
+				persistedThinkingLevel === ThinkingLevel.Inherit
+					? this.#getInheritedThinkingLevel()
+					: persistedThinkingLevel,
 			);
 			this.#thinkingLevel = nextThinkingLevel;
 			this.agent.setThinkingLevel(toReasoningEffort(nextThinkingLevel));
@@ -11083,6 +12608,9 @@ export class AgentSession {
 				: configuredServiceTier === "none"
 					? undefined
 					: configuredServiceTier;
+			// Establish the successor's durable session identity only after every
+			// restored state facet is live. Identity-bound extension hooks run below.
+			await this.sessionManager.ensureOnDisk();
 
 			if (switchingToDifferentSession) {
 				this.#resetHindsightConversationTrackingIfHindsight();
@@ -11090,10 +12618,24 @@ export class AgentSession {
 			}
 
 			this.#reconnectToAgent();
+			// session_switch is the post-commit identity signal. SDK authority and
+			// other identity-bound integrations must not observe the successor until
+			// messages, model state, MCP selections, and the agent subscription are live.
+			if (this.#extensionRunner) {
+				await this.#extensionRunner.emit({
+					type: "session_switch",
+					reason: "resume",
+					previousSessionFile,
+				});
+			}
+			if (suspendedWorkflowGateEmitter)
+				this.#bindWorkflowGateEmitter(previousSessionState.sessionId, suspendedWorkflowGateEmitter);
 			return true;
 		} catch (error) {
 			this.sessionManager.restoreState(previousSessionState);
+			this.#defaultFallbackController = undefined;
 			this.#syncAgentSessionId(previousSessionState.sessionId);
+			this.#restoreWorkflowGateEmitter(suspendedWorkflowGateEmitter);
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			let restoreMcpError: unknown;
 			try {
@@ -11133,6 +12675,10 @@ export class AgentSession {
 			if (restoreMcpError) {
 				throw restoreMcpError;
 			}
+			if (unavailableDefaultChainMessage) {
+				this.emitNotice("error", `Could not restore session model: ${unavailableDefaultChainMessage}`, "fallback");
+				return false;
+			}
 			throw error;
 		}
 	}
@@ -11151,6 +12697,7 @@ export class AgentSession {
 		cancelled: boolean;
 	}> {
 		const previousSessionFile = this.sessionFile;
+		const previousWorkflowGateSessionId = this.sessionId;
 		const selectedEntry = this.sessionManager.getEntryForFidelity(entryId);
 
 		if (selectedEntry?.type !== "message" || selectedEntry.message.role !== "user") {
@@ -11189,22 +12736,17 @@ export class AgentSession {
 		}
 		this.#syncTodoPhasesFromBranch();
 		this.#syncAgentSessionId();
+		this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#resetHindsightConversationTrackingIfHindsight();
+		this.#closeAllProviderSessions("session branch");
+		this.#rebindProviderSessionState(new Map());
 
 		// Reload messages from entries (works for both file and in-memory mode)
 		const sessionContext = this.buildDisplaySessionContext();
 
 		await this.#restoreMCPSelectionsForSessionContext(sessionContext);
 
-		// Emit session_branch event to hooks (after branch completes)
-		if (this.#extensionRunner) {
-			await this.#extensionRunner.emit({
-				type: "session_branch",
-				previousSessionFile,
-			});
-		}
-
 		if (!skipConversationRestore) {
 			this.agent.replaceMessages(sessionContext.messages);
 			this.#resetInjectedContextSignatures();
@@ -11212,6 +12754,14 @@ export class AgentSession {
 		}
 
 		this.#resetIrcRosterDeliveryState();
+		// session_branch is the post-commit identity signal. Publish it only after
+		// the successor's messages and MCP selections are restored.
+		if (this.#extensionRunner) {
+			await this.#extensionRunner.emit({
+				type: "session_branch",
+				previousSessionFile,
+			});
+		}
 
 		return { selectedText, cancelled: false };
 	}
@@ -11669,6 +13219,15 @@ export class AgentSession {
 		});
 	}
 
+	async fetchUsageReportsForControl(): Promise<UsageReport[] | null> {
+		const authStorage = this.#modelRegistry.authStorage;
+		if (!authStorage.fetchUsageReports) return null;
+		return authStorage.fetchUsageReports({
+			baseUrlResolver: provider => this.#modelRegistry.getProviderBaseUrl?.(provider),
+			logDetails: false,
+		});
+	}
+
 	/**
 	 * Estimate context tokens from messages, using the last assistant usage when available.
 	 */
@@ -11735,9 +13294,9 @@ export class AgentSession {
 
 	/**
 	 * Observed heuristic→actual token correction for the compaction keep window
-	 * (Finding 7). Compares the provider's real prompt tokens against the chars/4
-	 * heuristic estimate of the same content (stable system prefix + history
-	 * before the last usage-bearing assistant turn — that turn's own output is
+	 * (Finding 7). Compares the provider's real prompt tokens against the
+	 * script-aware display-token heuristic estimate of the same content (stable
+	 * system prefix + history before the last usage-bearing assistant turn — that turn's own output is
 	 * the response, not part of the request's prompt, so it belongs on neither
 	 * side of the ratio). Image-bearing content is bucketed out
 	 * of BOTH sides using the identical fixed IMAGE_TOKEN_ESTIMATE so the 1200-token