@oh-my-pi/pi-coding-agent 14.0.5 → 14.1.1

package/src/sdk.ts

@@ -11,7 +11,6 @@ import {
 	getOpenAICodexTransportDetails,
 	prewarmOpenAICodexResponses,
 } from "@oh-my-pi/pi-ai/providers/openai-codex-responses";
-import { SearchDb } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
 import {
 	$env,
@@ -19,13 +18,13 @@ import {
 	getAgentDbPath,
 	getAgentDir,
 	getProjectDir,
-	getSearchDbDir,
 	logger,
 	postmortem,
 	prompt,
+	Snowflake,
 } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
-import { AsyncJobManager } from "./async";
+import { AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
 import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability } from "./capability/rule";
@@ -73,7 +72,7 @@ import {
 	RuleProtocolHandler,
 	SkillProtocolHandler,
 } from "./internal-urls";
-import { disposeAllKernelSessions } from "./ipy/executor";
+import { disposeAllKernelSessions, disposeKernelSessionsByOwner } from "./ipy/executor";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
 import { discoverAndLoadMCPTools, type MCPManager, type MCPToolsLoadResult } from "./mcp";
 import {
@@ -148,8 +147,6 @@ export interface CreateAgentSessionOptions {
 	authStorage?: AuthStorage;
 	/** Model registry. Default: discoverModels(authStorage, agentDir) */
 	modelRegistry?: ModelRegistry;
-	/** Shared native search DB for grep/glob/fuzzyFind-backed workflows. */
-	searchDb?: SearchDb;
 
 	/** Model to use. Default: from settings, else first available */
 	model?: Model;
@@ -202,6 +199,8 @@ export interface CreateAgentSessionOptions {
 	enableLsp?: boolean;
 	/** Skip Python kernel availability check and prelude warmup */
 	skipPythonPreflight?: boolean;
+	/** Force Python prelude warmup even when test env would normally skip it */
+	forcePythonWarmup?: boolean;
 
 	/** Tool names explicitly requested (enables disabled-by-default tools) */
 	toolNames?: string[];
@@ -402,7 +401,6 @@ function createCustomToolContext(ctx: ExtensionContext): CustomToolContext {
 		sessionManager: ctx.sessionManager,
 		modelRegistry: ctx.modelRegistry,
 		model: ctx.model,
-		searchDb: ctx.searchDb,
 		isIdle: ctx.isIdle,
 		hasQueuedMessages: ctx.hasPendingMessages,
 		abort: ctx.abort,
@@ -728,6 +726,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		resolveModelRoleValue(settings.getModelRole("default"), modelRegistry.getAvailable(), {
 			settings,
 			matchPreferences: modelMatchPreferences,
+			modelRegistry,
 		}),
 	);
 	let model = options.model;
@@ -834,10 +833,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	);
 
 	let agent: Agent;
-	let session: AgentSession;
-
+	let session!: AgentSession;
+	let hasSession = false;
 	const enableLsp = options.enableLsp ?? true;
-	const asyncEnabled = settings.get("async.enabled");
+	const backgroundJobsEnabled = isBackgroundJobSupportEnabled(settings);
 	const asyncMaxJobs = Math.min(100, Math.max(1, settings.get("async.maxJobs") ?? 100));
 	const ASYNC_INLINE_RESULT_MAX_CHARS = 12_000;
 	const ASYNC_PREVIEW_MAX_CHARS = 4_000;
@@ -861,12 +860,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		return preview;
 	};
-	const asyncJobManager = asyncEnabled
+	const asyncJobManager = backgroundJobsEnabled
 		? new AsyncJobManager({
 				maxRunningJobs: asyncMaxJobs,
 				onJobComplete: async (jobId, result, job) => {
-					if (!session) return;
+					if (!session || asyncJobManager!.isDeliverySuppressed(jobId)) return;
 					const formattedResult = await formatAsyncResultForFollowUp(result);
+					if (asyncJobManager!.isDeliverySuppressed(jobId)) return;
+
 					const message = prompt.render(asyncResultTemplate, { jobId, result: formattedResult });
 					const durationMs = job ? Math.max(0, Date.now() - job.startTime) : undefined;
 					await session.sendCustomMessage(
@@ -888,435 +889,423 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			})
 		: undefined;
 
-	const searchDb = options.searchDb ?? new SearchDb(getSearchDbDir(agentDir));
-	const toolSession: ToolSession = {
-		cwd,
-		hasUI: options.hasUI ?? false,
-		enableLsp,
-		get hasEditTool() {
-			return !options.toolNames || options.toolNames.includes("edit");
-		},
-		skipPythonPreflight: options.skipPythonPreflight,
-		contextFiles,
-		skills,
-		eventBus,
-		outputSchema: options.outputSchema,
-		requireSubmitResultTool: options.requireSubmitResultTool,
-		taskDepth: options.taskDepth ?? 0,
-		getSessionFile: () => sessionManager.getSessionFile() ?? null,
-		getSessionId: () => sessionManager.getSessionId?.() ?? null,
-		getSessionSpawns: () => options.spawns ?? "*",
-		getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
-		getActiveModelString: () => {
+	const pythonKernelOwnerId = `agent-session:${Snowflake.next()}`;
+
+	try {
+		const getActiveModelString = (): string | undefined => {
 			const activeModel = agent?.state.model;
 			if (activeModel) return formatModelString(activeModel);
-			// Fall back to initial model during tool creation (before agent exists)
 			if (model) return formatModelString(model);
 			return undefined;
-		},
-		getPlanModeState: () => session.getPlanModeState(),
-		getCompactContext: () => session.formatCompactContext(),
-		getTodoPhases: () => session.getTodoPhases(),
-		setTodoPhases: phases => session.setTodoPhases(phases),
-		isMCPDiscoveryEnabled: () => session.isMCPDiscoveryEnabled(),
-		getDiscoverableMCPTools: () => session.getDiscoverableMCPTools(),
-		getDiscoverableMCPSearchIndex: () => session.getDiscoverableMCPSearchIndex(),
-		getSelectedMCPToolNames: () => session.getSelectedMCPToolNames(),
-		activateDiscoveredMCPTools: toolNames => session.activateDiscoveredMCPTools(toolNames),
-		getCheckpointState: () => session.getCheckpointState(),
-		setCheckpointState: state => session.setCheckpointState(state ?? undefined),
-		getToolChoiceQueue: () => session.toolChoiceQueue,
-		buildToolChoice: name => {
-			const m = session.model;
-			return m ? buildNamedToolChoice(name, m) : undefined;
-		},
-		steer: msg =>
-			session.agent.steer({
-				role: "custom",
-				customType: msg.customType,
-				content: msg.content,
-				display: false,
-				details: msg.details,
-				attribution: "agent",
-				timestamp: Date.now(),
-			}),
-		peekQueueInvoker: () => session.peekQueueInvoker(),
-		allocateOutputArtifact: async toolType => {
-			try {
-				return await sessionManager.allocateArtifactPath(toolType);
-			} catch {
-				return {};
-			}
-		},
-		settings,
-		authStorage,
-		modelRegistry,
-		asyncJobManager,
-		searchDb,
-	};
-
-	// Initialize internal URL router for internal protocols (agent://, artifact://, memory://, skill://, rule://, mcp://, local://)
-	const internalRouter = new InternalUrlRouter();
-	const getArtifactsDir = () => sessionManager.getArtifactsDir();
-	internalRouter.register(new AgentProtocolHandler({ getArtifactsDir }));
-	internalRouter.register(new ArtifactProtocolHandler({ getArtifactsDir }));
-	internalRouter.register(
-		new MemoryProtocolHandler({
-			getMemoryRoot: () => getMemoryRoot(agentDir, settings.getCwd()),
-		}),
-	);
-	internalRouter.register(
-		new LocalProtocolHandler({
-			getArtifactsDir,
-			getSessionId: () => sessionManager.getSessionId(),
-		}),
-	);
-	internalRouter.register(
-		new SkillProtocolHandler({
-			getSkills: () => skills,
-		}),
-	);
-	internalRouter.register(
-		new RuleProtocolHandler({
-			getRules: () => [...rulebookRules, ...alwaysApplyRules],
-		}),
-	);
-	internalRouter.register(new PiProtocolHandler());
-	internalRouter.register(new JobsProtocolHandler({ getAsyncJobManager: () => asyncJobManager }));
-	internalRouter.register(new McpProtocolHandler({ getMcpManager: () => mcpManager }));
-	toolSession.internalRouter = internalRouter;
-	toolSession.getArtifactsDir = getArtifactsDir;
-	toolSession.agentOutputManager = new AgentOutputManager(
-		getArtifactsDir,
-		options.parentTaskPrefix ? { parentPrefix: options.parentTaskPrefix } : undefined,
-	);
-
-	// Create built-in tools (already wrapped with meta notice formatting)
-	const builtinTools = await logger.time("createAllTools", createTools, toolSession, options.toolNames);
-
-	// Discover MCP tools from .mcp.json files
-	let mcpManager: MCPManager | undefined;
-	const enableMCP = options.enableMCP ?? true;
-	const customTools: CustomTool[] = [];
-	if (enableMCP) {
-		const mcpResult = await logger.time("discoverAndLoadMCPTools", discoverAndLoadMCPTools, cwd, {
-			onConnecting: serverNames => {
-				if (options.hasUI && serverNames.length > 0) {
-					process.stderr.write(`${chalk.gray(`Connecting to MCP servers: ${serverNames.join(", ")}…`)}\n`);
+		};
+		const toolSession: ToolSession = {
+			cwd,
+			hasUI: options.hasUI ?? false,
+			enableLsp,
+			get hasEditTool() {
+				const requestedToolNames = options.toolNames
+					? [...new Set(options.toolNames.map(name => name.toLowerCase()))]
+					: undefined;
+				return !requestedToolNames || requestedToolNames.includes("edit");
+			},
+			skipPythonPreflight: options.skipPythonPreflight,
+			forcePythonWarmup: options.forcePythonWarmup,
+			contextFiles,
+			skills,
+			eventBus,
+			outputSchema: options.outputSchema,
+			requireSubmitResultTool: options.requireSubmitResultTool,
+			taskDepth: options.taskDepth ?? 0,
+			getSessionFile: () => sessionManager.getSessionFile() ?? null,
+			getPythonKernelOwnerId: () => pythonKernelOwnerId,
+			assertPythonExecutionAllowed: () => session?.assertPythonExecutionAllowed(),
+			trackPythonExecution: (execution, abortController) =>
+				session ? session.trackPythonExecution(execution, abortController) : execution,
+			getSessionId: () => sessionManager.getSessionId?.() ?? null,
+			getSessionSpawns: () => options.spawns ?? "*",
+			getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
+			getActiveModelString,
+			getPlanModeState: () => session.getPlanModeState(),
+			getCompactContext: () => session.formatCompactContext(),
+			getTodoPhases: () => session.getTodoPhases(),
+			setTodoPhases: phases => session.setTodoPhases(phases),
+			isMCPDiscoveryEnabled: () => session.isMCPDiscoveryEnabled(),
+			getDiscoverableMCPTools: () => session.getDiscoverableMCPTools(),
+			getDiscoverableMCPSearchIndex: () => session.getDiscoverableMCPSearchIndex(),
+			getSelectedMCPToolNames: () => session.getSelectedMCPToolNames(),
+			activateDiscoveredMCPTools: toolNames => session.activateDiscoveredMCPTools(toolNames),
+			getCheckpointState: () => session.getCheckpointState(),
+			setCheckpointState: state => session.setCheckpointState(state ?? undefined),
+			getToolChoiceQueue: () => session.toolChoiceQueue,
+			buildToolChoice: name => {
+				const m = session.model;
+				return m ? buildNamedToolChoice(name, m) : undefined;
+			},
+			steer: msg =>
+				session.agent.steer({
+					role: "custom",
+					customType: msg.customType,
+					content: msg.content,
+					display: false,
+					details: msg.details,
+					attribution: "agent",
+					timestamp: Date.now(),
+				}),
+			peekQueueInvoker: () => session.peekQueueInvoker(),
+			allocateOutputArtifact: async toolType => {
+				try {
+					return await sessionManager.allocateArtifactPath(toolType);
+				} catch {
+					return {};
 				}
 			},
-			enableProjectConfig: settings.get("mcp.enableProjectConfig") ?? true,
-			// Always filter Exa - we have native integration
-			filterExa: true,
-			// Filter browser MCP servers when builtin browser tool is active
-			filterBrowser: settings.get("browser.enabled") ?? false,
-			cacheStorage: settings.getStorage(),
+			settings,
 			authStorage,
-		});
-		mcpManager = mcpResult.manager;
-		toolSession.mcpManager = mcpManager;
-
-		if (settings.get("mcp.notifications")) {
-			mcpManager.setNotificationsEnabled(true);
-		}
-		// If we extracted Exa API keys from MCP configs and EXA_API_KEY isn't set, use the first one
-		if (mcpResult.exaApiKeys.length > 0 && !$env.EXA_API_KEY) {
-			Bun.env.EXA_API_KEY = mcpResult.exaApiKeys[0];
-		}
+			modelRegistry,
+			asyncJobManager,
+		};
 
-		// Log MCP errors
-		for (const { path, error } of mcpResult.errors) {
-			logger.error("MCP tool load failed", { path, error });
-		}
+		// Initialize internal URL router for internal protocols (agent://, artifact://, memory://, skill://, rule://, mcp://, local://)
+		const internalRouter = new InternalUrlRouter();
+		const getArtifactsDir = () => sessionManager.getArtifactsDir();
+		internalRouter.register(new AgentProtocolHandler({ getArtifactsDir }));
+		internalRouter.register(new ArtifactProtocolHandler({ getArtifactsDir }));
+		internalRouter.register(
+			new MemoryProtocolHandler({
+				getMemoryRoot: () => getMemoryRoot(agentDir, settings.getCwd()),
+			}),
+		);
+		internalRouter.register(
+			new LocalProtocolHandler({
+				getArtifactsDir,
+				getSessionId: () => sessionManager.getSessionId(),
+			}),
+		);
+		internalRouter.register(
+			new SkillProtocolHandler({
+				getSkills: () => skills,
+			}),
+		);
+		internalRouter.register(
+			new RuleProtocolHandler({
+				getRules: () => [...rulebookRules, ...alwaysApplyRules],
+			}),
+		);
+		internalRouter.register(new PiProtocolHandler());
+		internalRouter.register(new JobsProtocolHandler({ getAsyncJobManager: () => asyncJobManager }));
+		internalRouter.register(new McpProtocolHandler({ getMcpManager: () => mcpManager }));
+		toolSession.internalRouter = internalRouter;
+		toolSession.getArtifactsDir = getArtifactsDir;
+		toolSession.agentOutputManager = new AgentOutputManager(
+			getArtifactsDir,
+			options.parentTaskPrefix ? { parentPrefix: options.parentTaskPrefix } : undefined,
+		);
 
-		if (mcpResult.tools.length > 0) {
-			// MCP tools are LoadedCustomTool, extract the tool property
-			customTools.push(...mcpResult.tools.map(loaded => loaded.tool));
-		}
-	}
+		// Create built-in tools (already wrapped with meta notice formatting)
+		const builtinTools = await logger.time("createAllTools", createTools, toolSession, options.toolNames);
+
+		// Discover MCP tools from .mcp.json files
+		let mcpManager: MCPManager | undefined;
+		const enableMCP = options.enableMCP ?? true;
+		const customTools: CustomTool[] = [];
+		if (enableMCP) {
+			const mcpResult = await logger.time("discoverAndLoadMCPTools", discoverAndLoadMCPTools, cwd, {
+				onConnecting: serverNames => {
+					if (options.hasUI && serverNames.length > 0) {
+						process.stderr.write(`${chalk.gray(`Connecting to MCP servers: ${serverNames.join(", ")}…`)}\n`);
+					}
+				},
+				enableProjectConfig: settings.get("mcp.enableProjectConfig") ?? true,
+				// Always filter Exa - we have native integration
+				filterExa: true,
+				// Filter browser MCP servers when builtin browser tool is active
+				filterBrowser: settings.get("browser.enabled") ?? false,
+				cacheStorage: settings.getStorage(),
+				authStorage,
+			});
+			mcpManager = mcpResult.manager;
+			toolSession.mcpManager = mcpManager;
 
-	// Add Gemini image tools if GEMINI_API_KEY (or GOOGLE_API_KEY) is available
-	const geminiImageTools = await logger.time("getGeminiImageTools", getGeminiImageTools);
-	if (geminiImageTools.length > 0) {
-		customTools.push(...(geminiImageTools as unknown as CustomTool[]));
-	}
+			if (settings.get("mcp.notifications")) {
+				mcpManager.setNotificationsEnabled(true);
+			}
+			// If we extracted Exa API keys from MCP configs and EXA_API_KEY isn't set, use the first one
+			if (mcpResult.exaApiKeys.length > 0 && !$env.EXA_API_KEY) {
+				Bun.env.EXA_API_KEY = mcpResult.exaApiKeys[0];
+			}
 
-	// Add web search tools
-	if (options.toolNames?.includes("web_search")) {
-		customTools.push(...getSearchTools());
-	}
+			// Log MCP errors
+			for (const { path, error } of mcpResult.errors) {
+				logger.error("MCP tool load failed", { path, error });
+			}
 
-	// Discover and load custom tools from .omp/tools/, .claude/tools/, etc.
-	const builtInToolNames = builtinTools.map(t => t.name);
-	const discoveredCustomTools = await logger.time(
-		"discoverAndLoadCustomTools",
-		discoverAndLoadCustomTools,
-		[],
-		cwd,
-		builtInToolNames,
-		action => queueResolveHandler(toolSession, action),
-	);
-	for (const { path, error } of discoveredCustomTools.errors) {
-		logger.error("Custom tool load failed", { path, error });
-	}
-	if (discoveredCustomTools.tools.length > 0) {
-		customTools.push(...discoveredCustomTools.tools.map(loaded => loaded.tool));
-	}
+			if (mcpResult.tools.length > 0) {
+				// MCP tools are LoadedCustomTool, extract the tool property
+				customTools.push(...mcpResult.tools.map(loaded => loaded.tool));
+			}
+		}
 
-	const inlineExtensions: ExtensionFactory[] = options.extensions ? [...options.extensions] : [];
-	inlineExtensions.push(createAutoresearchExtension);
-	if (customTools.length > 0) {
-		inlineExtensions.push(createCustomToolsExtension(customTools));
-	}
+		// Add Gemini image tools if GEMINI_API_KEY (or GOOGLE_API_KEY) is available
+		const geminiImageTools = await logger.time("getGeminiImageTools", getGeminiImageTools);
+		if (geminiImageTools.length > 0) {
+			customTools.push(...(geminiImageTools as unknown as CustomTool[]));
+		}
 
-	// Load extensions (discovers from standard locations + configured paths)
-	let extensionsResult: LoadExtensionsResult;
-	if (options.disableExtensionDiscovery) {
-		const configuredPaths = options.additionalExtensionPaths ?? [];
-		extensionsResult = await logger.time("loadExtensions", loadExtensions, configuredPaths, cwd, eventBus);
-		for (const { path, error } of extensionsResult.errors) {
-			logger.error("Failed to load extension", { path, error });
+		// Add web search tools
+		if (options.toolNames?.includes("web_search")) {
+			customTools.push(...getSearchTools());
 		}
-	} else if (options.preloadedExtensions) {
-		extensionsResult = options.preloadedExtensions;
-	} else {
-		// Merge CLI extension paths with settings extension paths
-		const configuredPaths = [...(options.additionalExtensionPaths ?? []), ...(settings.get("extensions") ?? [])];
-		const disabledExtensionIds = settings.get("disabledExtensions") ?? [];
-		extensionsResult = await logger.time(
-			"discoverAndLoadExtensions",
-			discoverAndLoadExtensions,
-			configuredPaths,
+
+		// Discover and load custom tools from .omp/tools/, .claude/tools/, etc.
+		const builtInToolNames = builtinTools.map(t => t.name);
+		const discoveredCustomTools = await logger.time(
+			"discoverAndLoadCustomTools",
+			discoverAndLoadCustomTools,
+			[],
 			cwd,
-			eventBus,
-			disabledExtensionIds,
+			builtInToolNames,
+			action => queueResolveHandler(toolSession, action),
 		);
-		for (const { path, error } of extensionsResult.errors) {
-			logger.error("Failed to load extension", { path, error });
+		for (const { path, error } of discoveredCustomTools.errors) {
+			logger.error("Custom tool load failed", { path, error });
+		}
+		if (discoveredCustomTools.tools.length > 0) {
+			customTools.push(...discoveredCustomTools.tools.map(loaded => loaded.tool));
 		}
-	}
 
-	// Load inline extensions from factories
-	if (inlineExtensions.length > 0) {
-		for (let i = 0; i < inlineExtensions.length; i++) {
-			const factory = inlineExtensions[i];
-			const loaded = await loadExtensionFromFactory(
-				factory,
+		const inlineExtensions: ExtensionFactory[] = options.extensions ? [...options.extensions] : [];
+		inlineExtensions.push(createAutoresearchExtension);
+		if (customTools.length > 0) {
+			inlineExtensions.push(createCustomToolsExtension(customTools));
+		}
+
+		// Load extensions (discovers from standard locations + configured paths)
+		let extensionsResult: LoadExtensionsResult;
+		if (options.disableExtensionDiscovery) {
+			const configuredPaths = options.additionalExtensionPaths ?? [];
+			extensionsResult = await logger.time("loadExtensions", loadExtensions, configuredPaths, cwd, eventBus);
+			for (const { path, error } of extensionsResult.errors) {
+				logger.error("Failed to load extension", { path, error });
+			}
+		} else if (options.preloadedExtensions) {
+			extensionsResult = options.preloadedExtensions;
+		} else {
+			// Merge CLI extension paths with settings extension paths
+			const configuredPaths = [...(options.additionalExtensionPaths ?? []), ...(settings.get("extensions") ?? [])];
+			const disabledExtensionIds = settings.get("disabledExtensions") ?? [];
+			extensionsResult = await logger.time(
+				"discoverAndLoadExtensions",
+				discoverAndLoadExtensions,
+				configuredPaths,
 				cwd,
 				eventBus,
-				extensionsResult.runtime,
-				`<inline-${i}>`,
+				disabledExtensionIds,
 			);
-			extensionsResult.extensions.push(loaded);
+			for (const { path, error } of extensionsResult.errors) {
+				logger.error("Failed to load extension", { path, error });
+			}
 		}
-	}
 
-	// Process provider registrations queued during extension loading.
-	// This must happen before the runner is created so that models registered by
-	// extensions are available for model selection on session resume / fallback.
-	const activeExtensionSources = extensionsResult.extensions.map(extension => extension.path);
-	modelRegistry.syncExtensionSources(activeExtensionSources);
-	for (const sourceId of new Set(activeExtensionSources)) {
-		modelRegistry.clearSourceRegistrations(sourceId);
-	}
-	if (extensionsResult.runtime.pendingProviderRegistrations.length > 0) {
-		for (const { name, config, sourceId } of extensionsResult.runtime.pendingProviderRegistrations) {
-			modelRegistry.registerProvider(name, config, sourceId);
+		// Load inline extensions from factories
+		if (inlineExtensions.length > 0) {
+			for (let i = 0; i < inlineExtensions.length; i++) {
+				const factory = inlineExtensions[i];
+				const loaded = await loadExtensionFromFactory(
+					factory,
+					cwd,
+					eventBus,
+					extensionsResult.runtime,
+					`<inline-${i}>`,
+				);
+				extensionsResult.extensions.push(loaded);
+			}
 		}
-		extensionsResult.runtime.pendingProviderRegistrations = [];
-	}
 
-	// Resolve deferred --model pattern now that extension models are registered.
-	if (!model && options.modelPattern) {
-		const availableModels = modelRegistry.getAll();
-		const matchPreferences = {
-			usageOrder: settings.getStorage()?.getModelUsageOrder(),
-		};
-		const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences);
-		if (resolved) {
-			model = resolved;
-			modelFallbackMessage = undefined;
-		} else {
-			modelFallbackMessage = `Model "${options.modelPattern}" not found`;
+		// Process provider registrations queued during extension loading.
+		// This must happen before the runner is created so that models registered by
+		// extensions are available for model selection on session resume / fallback.
+		const activeExtensionSources = extensionsResult.extensions.map(extension => extension.path);
+		modelRegistry.syncExtensionSources(activeExtensionSources);
+		for (const sourceId of new Set(activeExtensionSources)) {
+			modelRegistry.clearSourceRegistrations(sourceId);
+		}
+		if (extensionsResult.runtime.pendingProviderRegistrations.length > 0) {
+			for (const { name, config, sourceId } of extensionsResult.runtime.pendingProviderRegistrations) {
+				modelRegistry.registerProvider(name, config, sourceId);
+			}
+			extensionsResult.runtime.pendingProviderRegistrations = [];
 		}
-	}
 
-	// Fall back to first available model with a valid API key.
-	// Skip fallback if the user explicitly requested a model via --model that wasn't found.
-	if (!model && !options.modelPattern) {
-		const allModels = modelRegistry.getAll();
-		for (const candidate of allModels) {
-			if (await hasModelApiKey(candidate)) {
-				model = candidate;
-				break;
+		// Resolve deferred --model pattern now that extension models are registered.
+		if (!model && options.modelPattern) {
+			const availableModels = modelRegistry.getAll();
+			const matchPreferences = {
+				usageOrder: settings.getStorage()?.getModelUsageOrder(),
+			};
+			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences, {
+				modelRegistry,
+			});
+			if (resolved) {
+				model = resolved;
+				modelFallbackMessage = undefined;
+			} else {
+				modelFallbackMessage = `Model "${options.modelPattern}" not found`;
 			}
 		}
-		if (model) {
-			if (modelFallbackMessage) {
-				modelFallbackMessage += `. Using ${model.provider}/${model.id}`;
+
+		// Fall back to first available model with a valid API key.
+		// Skip fallback if the user explicitly requested a model via --model that wasn't found.
+		if (!model && !options.modelPattern) {
+			const allModels = modelRegistry.getAll();
+			for (const candidate of allModels) {
+				if (await hasModelApiKey(candidate)) {
+					model = candidate;
+					break;
+				}
+			}
+			if (model) {
+				if (modelFallbackMessage) {
+					modelFallbackMessage += `. Using ${model.provider}/${model.id}`;
+				}
+			} else {
+				modelFallbackMessage =
+					"No models available. Use /login or set an API key environment variable. Then use /model to select a model.";
 			}
-		} else {
-			modelFallbackMessage =
-				"No models available. Use /login or set an API key environment variable. Then use /model to select a model.";
 		}
-	}
 
-	// Discover custom commands (TypeScript slash commands)
-	const customCommandsResult: CustomCommandsLoadResult = options.disableExtensionDiscovery
-		? { commands: [], errors: [] }
-		: await logger.time("discoverCustomCommands", loadCustomCommandsInternal, { cwd, agentDir });
-	if (!options.disableExtensionDiscovery) {
-		for (const { path, error } of customCommandsResult.errors) {
-			logger.error("Failed to load custom command", { path, error });
+		// Discover custom commands (TypeScript slash commands)
+		const customCommandsResult: CustomCommandsLoadResult = options.disableExtensionDiscovery
+			? { commands: [], errors: [] }
+			: await logger.time("discoverCustomCommands", loadCustomCommandsInternal, { cwd, agentDir });
+		if (!options.disableExtensionDiscovery) {
+			for (const { path, error } of customCommandsResult.errors) {
+				logger.error("Failed to load custom command", { path, error });
+			}
 		}
-	}
 
-	let extensionRunner: ExtensionRunner | undefined;
-	if (extensionsResult.extensions.length > 0) {
-		extensionRunner = new ExtensionRunner(
-			extensionsResult.extensions,
-			extensionsResult.runtime,
-			cwd,
-			sessionManager,
-			modelRegistry,
-		);
-	}
+		let extensionRunner: ExtensionRunner | undefined;
+		if (extensionsResult.extensions.length > 0) {
+			extensionRunner = new ExtensionRunner(
+				extensionsResult.extensions,
+				extensionsResult.runtime,
+				cwd,
+				sessionManager,
+				modelRegistry,
+			);
+		}
 
-	const getSessionContext = () => ({
-		sessionManager,
-		modelRegistry,
-		model: agent.state.model,
-		isIdle: () => !session.isStreaming,
-		hasQueuedMessages: () => session.queuedMessageCount > 0,
-		abort: () => {
-			session.abort();
-		},
-		settings,
-	});
-	const toolContextStore = new ToolContextStore(getSessionContext);
-
-	const registeredTools = extensionRunner?.getAllRegisteredTools() ?? [];
-	let wrappedExtensionTools: Tool[];
-
-	if (extensionRunner) {
-		// With extension runner: convert CustomTools to ToolDefinitions and wrap all together
-		const allCustomTools = [
-			...registeredTools,
-			...(options.customTools?.map(tool => {
-				const definition = isCustomTool(tool) ? customToolToDefinition(tool) : tool;
-				return { definition, extensionPath: "<sdk>" };
-			}) ?? []),
-		];
-		wrappedExtensionTools = wrapRegisteredTools(allCustomTools, extensionRunner);
-	} else {
-		// Without extension runner: wrap CustomTools directly with CustomToolAdapter
-		// ToolDefinition items require ExtensionContext and cannot be used without a runner
-		const customToolContext = (): CustomToolContext => ({
+		const getSessionContext = () => ({
 			sessionManager,
 			modelRegistry,
-			model: agent?.state.model,
-			searchDb,
-			isIdle: () => !session?.isStreaming,
-			hasQueuedMessages: () => (session?.queuedMessageCount ?? 0) > 0,
-			abort: () => session?.abort(),
+			model: agent.state.model,
+			isIdle: () => !session.isStreaming,
+			hasQueuedMessages: () => session.queuedMessageCount > 0,
+			abort: () => {
+				session.abort();
+			},
 			settings,
 		});
-		wrappedExtensionTools = (options.customTools ?? [])
-			.filter(isCustomTool)
-			.map(tool => CustomToolAdapter.wrap(tool, customToolContext));
-	}
-
-	// All built-in tools are active (conditional tools like git/ask return null from factory if disabled)
-	const toolRegistry = new Map<string, Tool>();
-	for (const tool of builtinTools) {
-		toolRegistry.set(tool.name, tool);
-	}
-	for (const tool of wrappedExtensionTools) {
-		toolRegistry.set(tool.name, tool);
-	}
-	if (extensionRunner) {
-		for (const tool of toolRegistry.values()) {
-			toolRegistry.set(tool.name, new ExtensionToolWrapper(tool, extensionRunner));
+		const toolContextStore = new ToolContextStore(getSessionContext);
+
+		const registeredTools = extensionRunner?.getAllRegisteredTools() ?? [];
+		let wrappedExtensionTools: Tool[];
+
+		if (extensionRunner) {
+			// With extension runner: convert CustomTools to ToolDefinitions and wrap all together
+			const allCustomTools = [
+				...registeredTools,
+				...(options.customTools?.map(tool => {
+					const definition = isCustomTool(tool) ? customToolToDefinition(tool) : tool;
+					return { definition, extensionPath: "<sdk>" };
+				}) ?? []),
+			];
+			wrappedExtensionTools = wrapRegisteredTools(allCustomTools, extensionRunner);
+		} else {
+			// Without extension runner: wrap CustomTools directly with CustomToolAdapter
+			// ToolDefinition items require ExtensionContext and cannot be used without a runner
+			const customToolContext = (): CustomToolContext => ({
+				sessionManager,
+				modelRegistry,
+				model: agent?.state.model,
+				isIdle: () => !session?.isStreaming,
+				hasQueuedMessages: () => (session?.queuedMessageCount ?? 0) > 0,
+				abort: () => session?.abort(),
+				settings,
+			});
+			wrappedExtensionTools = (options.customTools ?? [])
+				.filter(isCustomTool)
+				.map(tool => CustomToolAdapter.wrap(tool, customToolContext));
 		}
-	}
-	if (model?.provider === "cursor") {
-		toolRegistry.delete("edit");
-	}
 
-	const hasDeferrableTools = Array.from(toolRegistry.values()).some(tool => tool.deferrable === true);
-	if (!hasDeferrableTools) {
-		toolRegistry.delete("resolve");
-	} else if (!toolRegistry.has("resolve")) {
-		const resolveTool = await logger.time("createTools:resolve:session", HIDDEN_TOOLS.resolve, toolSession);
-		if (resolveTool) {
-			toolRegistry.set(resolveTool.name, wrapToolWithMetaNotice(resolveTool));
+		// All built-in tools are active (conditional tools like git/ask return null from factory if disabled)
+		const toolRegistry = new Map<string, Tool>();
+		for (const tool of builtinTools) {
+			toolRegistry.set(tool.name, tool);
+		}
+		for (const tool of wrappedExtensionTools) {
+			toolRegistry.set(tool.name, tool);
+		}
+		if (extensionRunner) {
+			for (const tool of toolRegistry.values()) {
+				toolRegistry.set(tool.name, new ExtensionToolWrapper(tool, extensionRunner));
+			}
+		}
+		if (model?.provider === "cursor") {
+			toolRegistry.delete("edit");
 		}
-	}
-
-	let cursorEventEmitter: ((event: AgentEvent) => void) | undefined;
-	const cursorExecHandlers = new CursorExecHandlers({
-		cwd,
-		tools: toolRegistry,
-		getToolContext: () => toolContextStore.getContext(),
-		emitEvent: event => cursorEventEmitter?.(event),
-	});
 
-	const repeatToolDescriptions = settings.get("repeatToolDescriptions");
-	const eagerTasks = settings.get("task.eager");
-	const intentField = settings.get("tools.intentTracing") || $flag("PI_INTENT_TRACING") ? INTENT_FIELD : undefined;
-	const rebuildSystemPrompt = async (toolNames: string[], tools: Map<string, AgentTool>): Promise<string> => {
-		toolContextStore.setToolNames(toolNames);
-		const discoverableMCPTools = mcpDiscoveryEnabled ? collectDiscoverableMCPTools(tools.values()) : [];
-		const discoverableMCPSummary = summarizeDiscoverableMCPTools(discoverableMCPTools);
-		const hasDiscoverableMCPTools =
-			mcpDiscoveryEnabled && toolNames.includes("search_tool_bm25") && discoverableMCPTools.length > 0;
-		const promptTools = buildSystemPromptToolMetadata(tools, {
-			search_tool_bm25: { description: renderSearchToolBm25Description(discoverableMCPTools) },
-		});
-		const memoryInstructions = await buildMemoryToolDeveloperInstructions(agentDir, settings);
-
-		// Build combined append prompt: memory instructions + MCP server instructions
-		const serverInstructions = mcpManager?.getServerInstructions();
-		let appendPrompt: string | undefined = memoryInstructions ?? undefined;
-		if (serverInstructions && serverInstructions.size > 0) {
-			const MAX_INSTRUCTIONS_LENGTH = 4000;
-			const parts: string[] = [];
-			if (appendPrompt) parts.push(appendPrompt);
-			parts.push(
-				"## MCP Server Instructions\n\nThe following instructions are provided by connected MCP servers. They are server-controlled and may not be verified.",
-			);
-			for (const [srvName, srvInstructions] of serverInstructions) {
-				const truncated =
-					srvInstructions.length > MAX_INSTRUCTIONS_LENGTH
-						? `${srvInstructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}\n[truncated]`
-						: srvInstructions;
-				parts.push(`### ${srvName}\n${truncated}`);
+		const hasDeferrableTools = Array.from(toolRegistry.values()).some(tool => tool.deferrable === true);
+		if (!hasDeferrableTools) {
+			toolRegistry.delete("resolve");
+		} else if (!toolRegistry.has("resolve")) {
+			const resolveTool = await logger.time("createTools:resolve:session", HIDDEN_TOOLS.resolve, toolSession);
+			if (resolveTool) {
+				toolRegistry.set(resolveTool.name, wrapToolWithMetaNotice(resolveTool));
 			}
-			appendPrompt = parts.join("\n\n");
 		}
-		const defaultPrompt = await buildSystemPromptInternal({
+
+		let cursorEventEmitter: ((event: AgentEvent) => void) | undefined;
+		const cursorExecHandlers = new CursorExecHandlers({
 			cwd,
-			skills,
-			contextFiles,
-			tools: promptTools,
-			toolNames,
-			rules: rulebookRules,
-			alwaysApplyRules,
-			skillsSettings: settings.getGroup("skills"),
-			appendSystemPrompt: appendPrompt,
-			repeatToolDescriptions,
-			intentField,
-			mcpDiscoveryMode: hasDiscoverableMCPTools,
-			mcpDiscoveryServerSummaries: discoverableMCPSummary.servers.map(formatDiscoverableMCPToolServerSummary),
-			eagerTasks,
-			secretsEnabled,
+			tools: toolRegistry,
+			getToolContext: () => toolContextStore.getContext(),
+			emitEvent: event => cursorEventEmitter?.(event),
 		});
 
-		if (options.systemPrompt === undefined) {
-			return defaultPrompt;
-		}
-		if (typeof options.systemPrompt === "string") {
-			return await buildSystemPromptInternal({
+		const repeatToolDescriptions = settings.get("repeatToolDescriptions");
+		const eagerTasks = settings.get("task.eager");
+		const intentField = settings.get("tools.intentTracing") || $flag("PI_INTENT_TRACING") ? INTENT_FIELD : undefined;
+		const rebuildSystemPrompt = async (toolNames: string[], tools: Map<string, AgentTool>): Promise<string> => {
+			toolContextStore.setToolNames(toolNames);
+			const discoverableMCPTools = mcpDiscoveryEnabled ? collectDiscoverableMCPTools(tools.values()) : [];
+			const discoverableMCPSummary = summarizeDiscoverableMCPTools(discoverableMCPTools);
+			const hasDiscoverableMCPTools =
+				mcpDiscoveryEnabled && toolNames.includes("search_tool_bm25") && discoverableMCPTools.length > 0;
+			const promptTools = buildSystemPromptToolMetadata(tools, {
+				search_tool_bm25: { description: renderSearchToolBm25Description(discoverableMCPTools) },
+			});
+			const memoryInstructions = await buildMemoryToolDeveloperInstructions(agentDir, settings);
+
+			// Build combined append prompt: memory instructions + MCP server instructions
+			const serverInstructions = mcpManager?.getServerInstructions();
+			let appendPrompt: string | undefined = memoryInstructions ?? undefined;
+			if (serverInstructions && serverInstructions.size > 0) {
+				const MAX_INSTRUCTIONS_LENGTH = 4000;
+				const parts: string[] = [];
+				if (appendPrompt) parts.push(appendPrompt);
+				parts.push(
+					"## MCP Server Instructions\n\nThe following instructions are provided by connected MCP servers. They are server-controlled and may not be verified.",
+				);
+				for (const [srvName, srvInstructions] of serverInstructions) {
+					const truncated =
+						srvInstructions.length > MAX_INSTRUCTIONS_LENGTH
+							? `${srvInstructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}\n[truncated]`
+							: srvInstructions;
+					parts.push(`### ${srvName}\n${truncated}`);
+				}
+				appendPrompt = parts.join("\n\n");
+			}
+			const defaultPrompt = await buildSystemPromptInternal({
 				cwd,
 				skills,
 				contextFiles,
@@ -1325,7 +1314,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				rules: rulebookRules,
 				alwaysApplyRules,
 				skillsSettings: settings.getGroup("skills"),
-				customPrompt: options.systemPrompt,
 				appendSystemPrompt: appendPrompt,
 				repeatToolDescriptions,
 				intentField,
@@ -1334,362 +1322,407 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				eagerTasks,
 				secretsEnabled,
 			});
-		}
-		return options.systemPrompt(defaultPrompt);
-	};
 
-	const toolNamesFromRegistry = Array.from(toolRegistry.keys());
-	const requestedToolNames = options.toolNames?.map(name => name.toLowerCase()) ?? toolNamesFromRegistry;
-	const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
-	const includeExitPlanMode = requestedToolNames.includes("exit_plan_mode");
-	const mcpDiscoveryEnabled = settings.get("mcp.discoveryMode") ?? false;
-	const defaultInactiveToolNames = new Set(
-		registeredTools.filter(tool => tool.definition.defaultInactive).map(tool => tool.definition.name),
-	);
-	const requestedActiveToolNames = includeExitPlanMode
-		? normalizedRequested
-		: normalizedRequested.filter(name => name !== "exit_plan_mode");
-	const initialRequestedActiveToolNames = options.toolNames
-		? requestedActiveToolNames
-		: requestedActiveToolNames.filter(name => !defaultInactiveToolNames.has(name));
-	const explicitlyRequestedMCPToolNames = options.toolNames
-		? requestedActiveToolNames.filter(name => name.startsWith("mcp_"))
-		: [];
-	const discoveryDefaultServers = new Set(
-		(settings.get("mcp.discoveryDefaultServers") ?? []).map(serverName => serverName.trim()).filter(Boolean),
-	);
-	const discoveryDefaultServerToolNames = mcpDiscoveryEnabled
-		? selectDiscoverableMCPToolNamesByServer(
-				collectDiscoverableMCPTools(toolRegistry.values()),
-				discoveryDefaultServers,
-			)
-		: [];
-	let initialSelectedMCPToolNames: string[] = [];
-	let defaultSelectedMCPToolNames: string[] = [];
-	let initialToolNames = [...initialRequestedActiveToolNames];
-	if (mcpDiscoveryEnabled) {
-		const restoredSelectedMCPToolNames = existingSession.selectedMCPToolNames.filter(name => toolRegistry.has(name));
-		defaultSelectedMCPToolNames = [
-			...new Set([...discoveryDefaultServerToolNames, ...explicitlyRequestedMCPToolNames]),
-		];
-		initialSelectedMCPToolNames = existingSession.hasPersistedMCPToolSelection
-			? restoredSelectedMCPToolNames
-			: [...new Set([...restoredSelectedMCPToolNames, ...defaultSelectedMCPToolNames])];
-		initialToolNames = [
-			...new Set([
-				...initialRequestedActiveToolNames.filter(name => !name.startsWith("mcp_")),
-				...initialSelectedMCPToolNames,
-			]),
-		];
-	}
+			if (options.systemPrompt === undefined) {
+				return defaultPrompt;
+			}
+			if (typeof options.systemPrompt === "string") {
+				return await buildSystemPromptInternal({
+					cwd,
+					skills,
+					contextFiles,
+					tools: promptTools,
+					toolNames,
+					rules: rulebookRules,
+					alwaysApplyRules,
+					skillsSettings: settings.getGroup("skills"),
+					customPrompt: options.systemPrompt,
+					appendSystemPrompt: appendPrompt,
+					repeatToolDescriptions,
+					intentField,
+					mcpDiscoveryMode: hasDiscoverableMCPTools,
+					mcpDiscoveryServerSummaries: discoverableMCPSummary.servers.map(formatDiscoverableMCPToolServerSummary),
+					eagerTasks,
+					secretsEnabled,
+				});
+			}
+			return options.systemPrompt(defaultPrompt);
+		};
 
-	// Custom tools and extension-registered tools are always included regardless of toolNames filter
-	const alwaysInclude: string[] = [
-		...(options.customTools?.map(t => (isCustomTool(t) ? t.name : t.name)) ?? []),
-		...registeredTools.filter(t => !t.definition.defaultInactive).map(t => t.definition.name),
-	];
-	for (const name of alwaysInclude) {
-		if (mcpDiscoveryEnabled && name.startsWith("mcp_")) {
-			continue;
+		const toolNamesFromRegistry = Array.from(toolRegistry.keys());
+		const requestedToolNames =
+			(options.toolNames ? [...new Set(options.toolNames.map(name => name.toLowerCase()))] : undefined) ??
+			toolNamesFromRegistry;
+		const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
+		const includeExitPlanMode = requestedToolNames.includes("exit_plan_mode");
+		const mcpDiscoveryEnabled = settings.get("mcp.discoveryMode") ?? false;
+		const defaultInactiveToolNames = new Set(
+			registeredTools.filter(tool => tool.definition.defaultInactive).map(tool => tool.definition.name),
+		);
+		const requestedActiveToolNames = includeExitPlanMode
+			? normalizedRequested
+			: normalizedRequested.filter(name => name !== "exit_plan_mode");
+		const initialRequestedActiveToolNames = options.toolNames
+			? requestedActiveToolNames
+			: requestedActiveToolNames.filter(name => !defaultInactiveToolNames.has(name));
+		const explicitlyRequestedMCPToolNames = options.toolNames
+			? requestedActiveToolNames.filter(name => name.startsWith("mcp_"))
+			: [];
+		const discoveryDefaultServers = new Set(
+			(settings.get("mcp.discoveryDefaultServers") ?? []).map(serverName => serverName.trim()).filter(Boolean),
+		);
+		const discoveryDefaultServerToolNames = mcpDiscoveryEnabled
+			? selectDiscoverableMCPToolNamesByServer(
+					collectDiscoverableMCPTools(toolRegistry.values()),
+					discoveryDefaultServers,
+				)
+			: [];
+		let initialSelectedMCPToolNames: string[] = [];
+		let defaultSelectedMCPToolNames: string[] = [];
+		let initialToolNames = [...initialRequestedActiveToolNames];
+		if (mcpDiscoveryEnabled) {
+			const restoredSelectedMCPToolNames = existingSession.selectedMCPToolNames.filter(name =>
+				toolRegistry.has(name),
+			);
+			defaultSelectedMCPToolNames = [
+				...new Set([...discoveryDefaultServerToolNames, ...explicitlyRequestedMCPToolNames]),
+			];
+			initialSelectedMCPToolNames = existingSession.hasPersistedMCPToolSelection
+				? restoredSelectedMCPToolNames
+				: [...new Set([...restoredSelectedMCPToolNames, ...defaultSelectedMCPToolNames])];
+			initialToolNames = [
+				...new Set([
+					...initialRequestedActiveToolNames.filter(name => !name.startsWith("mcp_")),
+					...initialSelectedMCPToolNames,
+				]),
+			];
 		}
-		if (toolRegistry.has(name) && !initialToolNames.includes(name)) {
-			initialToolNames.push(name);
+
+		// Custom tools and extension-registered tools are always included regardless of toolNames filter
+		const alwaysInclude: string[] = [
+			...(options.customTools?.map(t => (isCustomTool(t) ? t.name : t.name)) ?? []),
+			...registeredTools.filter(t => !t.definition.defaultInactive).map(t => t.definition.name),
+		];
+		for (const name of alwaysInclude) {
+			if (mcpDiscoveryEnabled && name.startsWith("mcp_")) {
+				continue;
+			}
+			if (toolRegistry.has(name) && !initialToolNames.includes(name)) {
+				initialToolNames.push(name);
+			}
 		}
-	}
 
-	const systemPrompt = await logger.time("buildSystemPrompt", rebuildSystemPrompt, initialToolNames, toolRegistry);
+		const systemPrompt = await logger.time("buildSystemPrompt", rebuildSystemPrompt, initialToolNames, toolRegistry);
 
-	const promptTemplates =
-		options.promptTemplates ?? (await logger.time("discoverPromptTemplates", discoverPromptTemplates, cwd, agentDir));
-	toolSession.promptTemplates = promptTemplates;
+		const promptTemplates =
+			options.promptTemplates ??
+			(await logger.time("discoverPromptTemplates", discoverPromptTemplates, cwd, agentDir));
+		toolSession.promptTemplates = promptTemplates;
 
-	const slashCommands =
-		options.slashCommands ?? (await logger.time("discoverSlashCommands", discoverSlashCommands, cwd));
+		const slashCommands =
+			options.slashCommands ?? (await logger.time("discoverSlashCommands", discoverSlashCommands, cwd));
 
-	// Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
-	const convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {
-		const converted = convertToLlm(messages);
-		// Check setting dynamically so mid-session changes take effect
-		if (!settings.get("images.blockImages")) {
-			return converted;
-		}
-		// Filter out ImageContent from all messages, replacing with text placeholder
-		return converted.map(msg => {
-			if (msg.role === "user" || msg.role === "toolResult") {
-				const content = msg.content;
-				if (Array.isArray(content)) {
-					const hasImages = content.some(c => c.type === "image");
-					if (hasImages) {
-						const filteredContent = content
-							.map(c => (c.type === "image" ? { type: "text" as const, text: "Image reading is disabled." } : c))
-							.filter((c, i, arr) => {
-								// Dedupe consecutive "Image reading is disabled." texts
-								if (!(c.type === "text" && c.text === "Image reading is disabled." && i > 0)) return true;
-								const prev = arr[i - 1];
-								return !(prev.type === "text" && prev.text === "Image reading is disabled.");
-							});
-						return { ...msg, content: filteredContent };
+		// Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
+		const convertToLlmWithBlockImages = (messages: AgentMessage[]): Message[] => {
+			const converted = convertToLlm(messages);
+			// Check setting dynamically so mid-session changes take effect
+			if (!settings.get("images.blockImages")) {
+				return converted;
+			}
+			// Filter out ImageContent from all messages, replacing with text placeholder
+			return converted.map(msg => {
+				if (msg.role === "user" || msg.role === "toolResult") {
+					const content = msg.content;
+					if (Array.isArray(content)) {
+						const hasImages = content.some(c => c.type === "image");
+						if (hasImages) {
+							const filteredContent = content
+								.map(c =>
+									c.type === "image" ? { type: "text" as const, text: "Image reading is disabled." } : c,
+								)
+								.filter((c, i, arr) => {
+									// Dedupe consecutive "Image reading is disabled." texts
+									if (!(c.type === "text" && c.text === "Image reading is disabled." && i > 0)) return true;
+									const prev = arr[i - 1];
+									return !(prev.type === "text" && prev.text === "Image reading is disabled.");
+								});
+							return { ...msg, content: filteredContent };
+						}
 					}
 				}
-			}
-			return msg;
-		});
-	};
+				return msg;
+			});
+		};
 
-	// Final convertToLlm: chain block-images filter with secret obfuscation
-	const convertToLlmFinal = (messages: AgentMessage[]): Message[] => {
-		const converted = convertToLlmWithBlockImages(messages);
-		if (!obfuscator?.hasSecrets()) return converted;
-		return obfuscateMessages(obfuscator, converted);
-	};
-	const transformContext = extensionRunner
-		? async (messages: AgentMessage[], _signal?: AbortSignal) => {
-				return await extensionRunner.emitContext(messages);
-			}
-		: undefined;
-	const onPayload = extensionRunner
-		? async (payload: unknown, _model?: Model) => {
-				return await extensionRunner.emitBeforeProviderRequest(payload);
-			}
-		: undefined;
+		// Final convertToLlm: chain block-images filter with secret obfuscation
+		const convertToLlmFinal = (messages: AgentMessage[]): Message[] => {
+			const converted = convertToLlmWithBlockImages(messages);
+			if (!obfuscator?.hasSecrets()) return converted;
+			return obfuscateMessages(obfuscator, converted);
+		};
+		const transformContext = extensionRunner
+			? async (messages: AgentMessage[], _signal?: AbortSignal) => {
+					return await extensionRunner.emitContext(messages);
+				}
+			: undefined;
+		const onPayload = extensionRunner
+			? async (payload: unknown, _model?: Model) => {
+					return await extensionRunner.emitBeforeProviderRequest(payload);
+				}
+			: undefined;
 
-	const setToolUIContext = (uiContext: ExtensionUIContext, hasUI: boolean) => {
-		toolContextStore.setUIContext(uiContext, hasUI);
-	};
+		const setToolUIContext = (uiContext: ExtensionUIContext, hasUI: boolean) => {
+			toolContextStore.setUIContext(uiContext, hasUI);
+		};
 
-	const initialTools = initialToolNames
-		.map(name => toolRegistry.get(name))
-		.filter((tool): tool is AgentTool => tool !== undefined);
-
-	const openaiWebsocketSetting = settings.get("providers.openaiWebsockets") ?? "auto";
-	const preferOpenAICodexWebsockets =
-		openaiWebsocketSetting === "on" ? true : openaiWebsocketSetting === "off" ? false : undefined;
-	const serviceTierSetting = settings.get("serviceTier");
-
-	const initialServiceTier = hasServiceTierEntry
-		? existingSession.serviceTier
-		: serviceTierSetting === "none"
-			? undefined
-			: serviceTierSetting;
-
-	agent = new Agent({
-		initialState: {
-			systemPrompt,
-			model,
-			thinkingLevel: toReasoningEffort(thinkingLevel),
-			tools: initialTools,
-		},
-		convertToLlm: convertToLlmFinal,
-		onPayload,
-		sessionId: providerSessionId,
-		transformContext,
-		steeringMode: settings.get("steeringMode") ?? "one-at-a-time",
-		followUpMode: settings.get("followUpMode") ?? "one-at-a-time",
-		interruptMode: settings.get("interruptMode") ?? "immediate",
-		thinkingBudgets: settings.getGroup("thinkingBudgets"),
-		temperature: settings.get("temperature") >= 0 ? settings.get("temperature") : undefined,
-		topP: settings.get("topP") >= 0 ? settings.get("topP") : undefined,
-		topK: settings.get("topK") >= 0 ? settings.get("topK") : undefined,
-		minP: settings.get("minP") >= 0 ? settings.get("minP") : undefined,
-		presencePenalty: settings.get("presencePenalty") >= 0 ? settings.get("presencePenalty") : undefined,
-		repetitionPenalty: settings.get("repetitionPenalty") >= 0 ? settings.get("repetitionPenalty") : undefined,
-		serviceTier: initialServiceTier,
-		kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
-		preferWebsockets: preferOpenAICodexWebsockets,
-		getToolContext: tc => toolContextStore.getContext(tc),
-		getApiKey: async provider => {
-			// Use the provider-facing session id for sticky credential selection so cache keys
-			// and provider auth affinity stay aligned across fresh benchmark sessions.
-			const key = await modelRegistry.getApiKeyForProvider(provider, providerSessionId);
-			if (!key) {
-				throw new Error(`No API key found for provider "${provider}"`);
-			}
-			return key;
-		},
-		cursorExecHandlers,
-		transformToolCallArguments: (args, _toolName) => {
-			let result = args;
-			const maxTimeout = settings.get("tools.maxTimeout");
-			if (maxTimeout > 0 && typeof result.timeout === "number") {
-				result = { ...result, timeout: Math.min(result.timeout, maxTimeout) };
-			}
-			if (obfuscator?.hasSecrets()) {
-				result = obfuscator.deobfuscateObject(result);
-			}
-			return result;
-		},
-		intentTracing: !!intentField,
-		getToolChoice: () => session?.nextToolChoice(),
-	});
+		const initialTools = initialToolNames
+			.map(name => toolRegistry.get(name))
+			.filter((tool): tool is AgentTool => tool !== undefined);
+
+		const openaiWebsocketSetting = settings.get("providers.openaiWebsockets") ?? "off";
+		const preferOpenAICodexWebsockets =
+			openaiWebsocketSetting === "on" ? true : openaiWebsocketSetting === "off" ? false : undefined;
+		const serviceTierSetting = settings.get("serviceTier");
+
+		const initialServiceTier = hasServiceTierEntry
+			? existingSession.serviceTier
+			: serviceTierSetting === "none"
+				? undefined
+				: serviceTierSetting;
+
+		agent = new Agent({
+			initialState: {
+				systemPrompt,
+				model,
+				thinkingLevel: toReasoningEffort(thinkingLevel),
+				tools: initialTools,
+			},
+			convertToLlm: convertToLlmFinal,
+			onPayload,
+			sessionId: providerSessionId,
+			transformContext,
+			steeringMode: settings.get("steeringMode") ?? "one-at-a-time",
+			followUpMode: settings.get("followUpMode") ?? "one-at-a-time",
+			interruptMode: settings.get("interruptMode") ?? "immediate",
+			thinkingBudgets: settings.getGroup("thinkingBudgets"),
+			temperature: settings.get("temperature") >= 0 ? settings.get("temperature") : undefined,
+			topP: settings.get("topP") >= 0 ? settings.get("topP") : undefined,
+			topK: settings.get("topK") >= 0 ? settings.get("topK") : undefined,
+			minP: settings.get("minP") >= 0 ? settings.get("minP") : undefined,
+			presencePenalty: settings.get("presencePenalty") >= 0 ? settings.get("presencePenalty") : undefined,
+			repetitionPenalty: settings.get("repetitionPenalty") >= 0 ? settings.get("repetitionPenalty") : undefined,
+			serviceTier: initialServiceTier,
+			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
+			preferWebsockets: preferOpenAICodexWebsockets,
+			getToolContext: tc => toolContextStore.getContext(tc),
+			getApiKey: async provider => {
+				// Use the provider-facing session id for sticky credential selection so cache keys
+				// and provider auth affinity stay aligned across fresh benchmark sessions.
+				const key = await modelRegistry.getApiKeyForProvider(provider, providerSessionId);
+				if (!key) {
+					throw new Error(`No API key found for provider "${provider}"`);
+				}
+				return key;
+			},
+			cursorExecHandlers,
+			transformToolCallArguments: (args, _toolName) => {
+				let result = args;
+				const maxTimeout = settings.get("tools.maxTimeout");
+				if (maxTimeout > 0 && typeof result.timeout === "number") {
+					result = { ...result, timeout: Math.min(result.timeout, maxTimeout) };
+				}
+				if (obfuscator?.hasSecrets()) {
+					result = obfuscator.deobfuscateObject(result);
+				}
+				return result;
+			},
+			intentTracing: !!intentField,
+			getToolChoice: () => session?.nextToolChoice(),
+		});
 
-	cursorEventEmitter = event => agent.emitExternalEvent(event);
+		cursorEventEmitter = event => agent.emitExternalEvent(event);
 
-	// Restore messages if session has existing data
-	if (hasExistingSession) {
-		agent.replaceMessages(existingSession.messages);
-	} else {
-		// Save initial model and thinking level for new sessions so they can be restored on resume
-		if (model) {
-			sessionManager.appendModelChange(`${model.provider}/${model.id}`);
+		// Restore messages if session has existing data
+		if (hasExistingSession) {
+			agent.replaceMessages(existingSession.messages);
+		} else {
+			// Save initial model and thinking level for new sessions so they can be restored on resume
+			if (model) {
+				sessionManager.appendModelChange(`${model.provider}/${model.id}`);
+			}
+			sessionManager.appendThinkingLevelChange(thinkingLevel);
 		}
-		sessionManager.appendThinkingLevelChange(thinkingLevel);
-	}
-
-	session = new AgentSession({
-		agent,
-		thinkingLevel,
-		sessionManager,
-		settings,
-		scopedModels: options.scopedModels,
-		promptTemplates,
-		slashCommands,
-		extensionRunner,
-		customCommands: customCommandsResult.commands,
-		skills,
-		skillWarnings,
-		skillsSettings: settings.getGroup("skills"),
-		modelRegistry,
-		toolRegistry,
-		transformContext,
-		onPayload,
-		convertToLlm: convertToLlmFinal,
-		rebuildSystemPrompt,
-		mcpDiscoveryEnabled,
-		initialSelectedMCPToolNames,
-		defaultSelectedMCPToolNames,
-		persistInitialMCPToolSelection: !hasExistingSession,
-		defaultSelectedMCPServerNames: [...discoveryDefaultServers],
-		ttsrManager,
-		obfuscator,
-		asyncJobManager,
-		searchDb,
-	});
 
-	if (model?.api === "openai-codex-responses") {
-		const codexModel = model;
-		const codexTransport = getOpenAICodexTransportDetails(codexModel, {
-			sessionId: providerSessionId,
-			baseUrl: codexModel.baseUrl,
-			preferWebsockets: preferOpenAICodexWebsockets,
-			providerSessionState: session.providerSessionState,
+		session = new AgentSession({
+			agent,
+			thinkingLevel,
+			sessionManager,
+			settings,
+			pythonKernelOwnerId,
+			scopedModels: options.scopedModels,
+			promptTemplates,
+			slashCommands,
+			extensionRunner,
+			customCommands: customCommandsResult.commands,
+			skills,
+			skillWarnings,
+			skillsSettings: settings.getGroup("skills"),
+			modelRegistry,
+			toolRegistry,
+			transformContext,
+			onPayload,
+			convertToLlm: convertToLlmFinal,
+			rebuildSystemPrompt,
+			mcpDiscoveryEnabled,
+			initialSelectedMCPToolNames,
+			defaultSelectedMCPToolNames,
+			persistInitialMCPToolSelection: !hasExistingSession,
+			defaultSelectedMCPServerNames: [...discoveryDefaultServers],
+			ttsrManager,
+			obfuscator,
+			asyncJobManager,
 		});
-		if (codexTransport.websocketPreferred) {
-			void (async () => {
-				try {
-					const codexPrewarmApiKey = await modelRegistry.getApiKey(codexModel, providerSessionId);
-					if (!codexPrewarmApiKey) return;
-					await logger.time("prewarmOpenAICodexResponses", prewarmOpenAICodexResponses, codexModel, {
-						apiKey: codexPrewarmApiKey,
-						sessionId: providerSessionId,
-						preferWebsockets: preferOpenAICodexWebsockets,
-						providerSessionState: session.providerSessionState,
-					});
-				} catch (error) {
-					const errorMessage = error instanceof Error ? error.message : String(error);
-					logger.debug("Codex websocket prewarm failed", {
-						error: errorMessage,
-						provider: codexModel.provider,
-						model: codexModel.id,
-					});
-				}
-			})();
+		hasSession = true;
+
+		if (model?.api === "openai-codex-responses") {
+			const codexModel = model;
+			const codexTransport = getOpenAICodexTransportDetails(codexModel, {
+				sessionId: providerSessionId,
+				baseUrl: codexModel.baseUrl,
+				preferWebsockets: preferOpenAICodexWebsockets,
+				providerSessionState: session.providerSessionState,
+			});
+			if (codexTransport.websocketPreferred) {
+				void (async () => {
+					try {
+						const codexPrewarmApiKey = await modelRegistry.getApiKey(codexModel, providerSessionId);
+						if (!codexPrewarmApiKey) return;
+						await logger.time("prewarmOpenAICodexResponses", prewarmOpenAICodexResponses, codexModel, {
+							apiKey: codexPrewarmApiKey,
+							sessionId: providerSessionId,
+							preferWebsockets: preferOpenAICodexWebsockets,
+							providerSessionState: session.providerSessionState,
+						});
+					} catch (error) {
+						const errorMessage = error instanceof Error ? error.message : String(error);
+						logger.debug("Codex websocket prewarm failed", {
+							error: errorMessage,
+							provider: codexModel.provider,
+							model: codexModel.id,
+						});
+					}
+				})();
+			}
 		}
-	}
 
-	// Start LSP warmup in the background so startup does not block on language server initialization.
-	let lspServers: CreateAgentSessionResult["lspServers"];
-	if (enableLsp && settings.get("lsp.diagnosticsOnWrite")) {
-		lspServers = discoverStartupLspServers(cwd);
-		if (lspServers.length > 0) {
-			void (async () => {
-				try {
-					const result = await logger.time("warmupLspServers", warmupLspServers, cwd);
-					const serversByName = new Map(result.servers.map(server => [server.name, server] as const));
-					for (const server of lspServers ?? []) {
-						const next = serversByName.get(server.name);
-						if (!next) continue;
-						server.status = next.status;
-						server.fileTypes = next.fileTypes;
-						server.error = next.error;
-					}
-					const event: LspStartupEvent = {
-						type: "completed",
-						servers: result.servers,
-					};
-					eventBus.emit(LSP_STARTUP_EVENT_CHANNEL, event);
-				} catch (error) {
-					const errorMessage = error instanceof Error ? error.message : String(error);
-					logger.warn("LSP server warmup failed", { cwd, error: errorMessage });
-					for (const server of lspServers ?? []) {
-						server.status = "error";
-						server.error = errorMessage;
+		// Start LSP warmup in the background so startup does not block on language server initialization.
+		let lspServers: CreateAgentSessionResult["lspServers"];
+		if (enableLsp && settings.get("lsp.diagnosticsOnWrite")) {
+			lspServers = discoverStartupLspServers(cwd);
+			if (lspServers.length > 0) {
+				void (async () => {
+					try {
+						const result = await logger.time("warmupLspServers", warmupLspServers, cwd);
+						const serversByName = new Map(result.servers.map(server => [server.name, server] as const));
+						for (const server of lspServers ?? []) {
+							const next = serversByName.get(server.name);
+							if (!next) continue;
+							server.status = next.status;
+							server.fileTypes = next.fileTypes;
+							server.error = next.error;
+						}
+						const event: LspStartupEvent = {
+							type: "completed",
+							servers: result.servers,
+						};
+						eventBus.emit(LSP_STARTUP_EVENT_CHANNEL, event);
+					} catch (error) {
+						const errorMessage = error instanceof Error ? error.message : String(error);
+						logger.warn("LSP server warmup failed", { cwd, error: errorMessage });
+						for (const server of lspServers ?? []) {
+							server.status = "error";
+							server.error = errorMessage;
+						}
+						const event: LspStartupEvent = {
+							type: "failed",
+							error: errorMessage,
+						};
+						eventBus.emit(LSP_STARTUP_EVENT_CHANNEL, event);
 					}
-					const event: LspStartupEvent = {
-						type: "failed",
-						error: errorMessage,
-					};
-					eventBus.emit(LSP_STARTUP_EVENT_CHANNEL, event);
-				}
-			})();
+				})();
+			}
 		}
-	}
 
-	logger.time("startMemoryStartupTask", () =>
-		startMemoryStartupTask({
-			session,
-			settings,
-			modelRegistry,
-			agentDir,
-			taskDepth,
-		}),
-	);
+		logger.time("startMemoryStartupTask", () =>
+			startMemoryStartupTask({
+				session,
+				settings,
+				modelRegistry,
+				agentDir,
+				taskDepth,
+			}),
+		);
 
-	// Wire MCP manager callbacks to session for reactive tool updates
-	if (mcpManager) {
-		mcpManager.setOnToolsChanged(tools => {
-			void session.refreshMCPTools(tools);
-		});
-		// Wire prompt refresh → rebuild MCP prompt slash commands
-		mcpManager.setOnPromptsChanged(serverName => {
-			const promptCommands = buildMCPPromptCommands(mcpManager);
-			session.setMCPPromptCommands(promptCommands);
-			logger.debug("MCP prompt commands refreshed", { path: `mcp:${serverName}` });
-		});
-		const notificationDebounceTimers = new Map<string, Timer>();
-		const clearDebounceTimers = () => {
-			for (const timer of notificationDebounceTimers.values()) clearTimeout(timer);
-			notificationDebounceTimers.clear();
+		// Wire MCP manager callbacks to session for reactive tool updates
+		if (mcpManager) {
+			mcpManager.setOnToolsChanged(tools => {
+				void session.refreshMCPTools(tools);
+			});
+			// Wire prompt refresh → rebuild MCP prompt slash commands
+			mcpManager.setOnPromptsChanged(serverName => {
+				const promptCommands = buildMCPPromptCommands(mcpManager);
+				session.setMCPPromptCommands(promptCommands);
+				logger.debug("MCP prompt commands refreshed", { path: `mcp:${serverName}` });
+			});
+			const notificationDebounceTimers = new Map<string, Timer>();
+			const clearDebounceTimers = () => {
+				for (const timer of notificationDebounceTimers.values()) clearTimeout(timer);
+				notificationDebounceTimers.clear();
+			};
+			postmortem.register("mcp-notification-cleanup", clearDebounceTimers);
+			mcpManager.setOnResourcesChanged((serverName, uri) => {
+				logger.debug("MCP resources changed", { path: `mcp:${serverName}`, uri });
+				if (!settings.get("mcp.notifications")) return;
+				const debounceMs = settings.get("mcp.notificationDebounceMs");
+				const key = `${serverName}:${uri}`;
+				const existing = notificationDebounceTimers.get(key);
+				if (existing) clearTimeout(existing);
+				notificationDebounceTimers.set(
+					key,
+					setTimeout(() => {
+						notificationDebounceTimers.delete(key);
+						// Re-check: user may have disabled notifications during the debounce window
+						if (!settings.get("mcp.notifications")) return;
+						void session.followUp(
+							`[MCP notification] Server "${serverName}" reports resource \`${uri}\` was updated. Use read(path="mcp://${uri}") to inspect if relevant.`,
+						);
+					}, debounceMs),
+				);
+			});
+		}
+
+		logger.time("createAgentSession:return");
+		return {
+			session,
+			extensionsResult,
+			setToolUIContext,
+			mcpManager,
+			modelFallbackMessage,
+			lspServers,
+			eventBus,
 		};
-		postmortem.register("mcp-notification-cleanup", clearDebounceTimers);
-		mcpManager.setOnResourcesChanged((serverName, uri) => {
-			logger.debug("MCP resources changed", { path: `mcp:${serverName}`, uri });
-			if (!settings.get("mcp.notifications")) return;
-			const debounceMs = settings.get("mcp.notificationDebounceMs");
-			const key = `${serverName}:${uri}`;
-			const existing = notificationDebounceTimers.get(key);
-			if (existing) clearTimeout(existing);
-			notificationDebounceTimers.set(
-				key,
-				setTimeout(() => {
-					notificationDebounceTimers.delete(key);
-					// Re-check: user may have disabled notifications during the debounce window
-					if (!settings.get("mcp.notifications")) return;
-					void session.followUp(
-						`[MCP notification] Server "${serverName}" reports resource \`${uri}\` was updated. Use read(path="mcp://${uri}") to inspect if relevant.`,
-					);
-				}, debounceMs),
-			);
-		});
+	} catch (error) {
+		try {
+			if (hasSession) {
+				await session.dispose();
+			} else {
+				await disposeKernelSessionsByOwner(pythonKernelOwnerId);
+			}
+		} catch (cleanupError) {
+			logger.warn("Failed to clean up createAgentSession resources after startup error", {
+				error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+			});
+		}
+		throw error;
 	}
-
-	logger.time("createAgentSession:return");
-	return {
-		session,
-		extensionsResult,
-		setToolUIContext,
-		mcpManager,
-		modelFallbackMessage,
-		lspServers,
-		eventBus,
-	};
 }