@gajae-code/coding-agent 0.11.1 → 0.11.3

package/src/sdk/session.ts

@@ -114,7 +114,7 @@ import { AgentSession, type ForkContextSeed } from "../session/agent-session";
 import { resolveAuthBrokerConfig } from "../session/auth-broker-config";
 import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "../session/auth-storage";
 import { type CustomMessage, convertToLlm } from "../session/messages";
-import { SessionManager } from "../session/session-manager";
+import { createReadonlySessionManager, SessionManager } from "../session/session-manager";
 import { formatNoModelsAvailableFallback } from "../setup/model-onboarding-guidance";
 import { closeAllConnections } from "../ssh/connection-manager";
 import { unmountAll } from "../ssh/sshfs-mount";
@@ -126,12 +126,7 @@ import {
 } from "../system-prompt";
 import { AgentOutputManager } from "../task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
-import {
-	collectDiscoverableTools,
-	type DiscoverableTool,
-	isMCPBridgeTool,
-	isMCPToolName,
-} from "../tool-discovery/tool-index";
+import { isMCPBridgeTool } from "../tool-discovery/tool-index";
 import {
 	applyConfiguredSearchTimeout,
 	BashTool,
@@ -150,7 +145,6 @@ import {
 	loadSshTool,
 	ReadTool,
 	ResolveTool,
-	renderSearchToolBm25Description,
 	SearchTool,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
@@ -396,6 +390,8 @@ export interface CreateAgentSessionOptions {
 	hasUI?: boolean;
 	/** Whether this host mode can own a notification session endpoint. Default: true. */
 	notificationHostModeSupported?: boolean;
+	/** Whether this host mode can own the root SDK endpoint. Default: true. */
+	sdkHostModeSupported?: boolean;
 
 	/**
 	 * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
@@ -498,7 +494,16 @@ export async function discoverAuthStorage(agentDir: string = getDefaultAgentDir(
 			sourceLabel: `broker ${brokerConfig.url}`,
 			credentialRankingMode,
 		});
-		await storage.reload();
+		try {
+			await storage.reload();
+		} catch (error) {
+			try {
+				storage.close();
+			} catch {
+				// Preserve the initial reload failure.
+			}
+			throw error;
+		}
 		return storage;
 	}
 	const dbPath = getAgentDbPath(agentDir);
@@ -507,7 +512,16 @@ export async function discoverAuthStorage(agentDir: string = getDefaultAgentDir(
 		sourceLabel: `local ${dbPath}`,
 		credentialRankingMode,
 	});
-	await storage.reload();
+	try {
+		await storage.reload();
+	} catch (error) {
+		try {
+			storage.close();
+		} catch {
+			// Preserve the initial reload failure.
+		}
+		throw error;
+	}
 	return storage;
 }
 
@@ -629,9 +643,6 @@ function isCustomTool(tool: CustomTool | ToolDefinition): tool is CustomTool {
 
 const TOOL_DEFINITION_MARKER = Symbol("__isToolDefinition");
 
-/** Matches the truncation applied to per-server instructions inside `rebuildSystemPrompt`. */
-const MAX_MCP_INSTRUCTIONS_LENGTH = 4000;
-
 let sshCleanupRegistered = false;
 
 async function cleanupSshResources(): Promise<void> {
@@ -976,6 +987,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	// Pin authStorage to modelRegistry.authStorage: ModelRegistry.getApiKey() routes refresh
 	// failures through that instance, so any divergent storage handed to the bridge / mcpManager
 	// / session would silently miss credential_disabled events.
+	const ownsAuthStorage = options.modelRegistry === undefined && options.authStorage === undefined;
 	const modelRegistry =
 		options.modelRegistry ??
 		new ModelRegistry(options.authStorage ?? (await logger.time("discoverModels", discoverAuthStorage, agentDir)));
@@ -985,409 +997,424 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			"options.authStorage and options.modelRegistry.authStorage must be the same instance when both are provided",
 		);
 	}
-	// Subscribe before any getApiKey() call so startup model probes can't fire a
-	// credential_disabled event past us. An embedder's constructor handler makes the
-	// listener set non-empty from construction, which defeats AuthStorage's no-listener
-	// buffer — so we can't rely on it to catch startup events for the extension runner.
-	const startupCredentialDisabledEvents: CredentialDisabledEvent[] = [];
-	let credentialDisabledTarget: ExtensionRunner | undefined;
-	let unsubscribeCredentialDisabled: (() => void) | undefined = authStorage.onCredentialDisabled(event => {
-		if (credentialDisabledTarget) {
-			// Discard return: any handler error is routed through runner.onError listeners.
-			void credentialDisabledTarget.emitCredentialDisabled(event);
-		} else {
-			startupCredentialDisabledEvents.push(event);
-		}
-	});
-	let runtimeCredentialSelectorInstalled = false;
-	const installRuntimeCredentialSelector = (provider: string): void => {
-		if (!options.credentialSelector || runtimeCredentialSelectorInstalled) return;
-		authStorage.setRuntimeCredentialSelector(provider, options.credentialSelector.selector);
-		runtimeCredentialSelectorInstalled = true;
+	let agent: Agent;
+	let session!: AgentSession;
+	let hasSession = false;
+	let hasRegistered = false;
+	let cleanupOwnedMcpManager: (() => Promise<void>) | undefined;
+	const agentRegistry = options.agentRegistry ?? AgentRegistry.global();
+	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
+	const resolvedAgentDisplayName = options.agentDisplayName ?? (isCanonicalSubSession ? "sub" : "main");
+	const resolvedAgentRosterLabel = resolveAgentRosterLabel(
+		options.agentRosterLabel,
+		resolvedAgentId,
+		resolvedAgentDisplayName,
+	);
+	const evalKernelOwnerId = `agent-session:${Snowflake.next()}`;
+	let disposeLocalProtocolOverride: (() => void) | undefined;
+	let localProtocolOverrideReleased = false;
+	const releaseLocalProtocolOverride = (): void => {
+		if (localProtocolOverrideReleased) return;
+		localProtocolOverrideReleased = true;
+		disposeLocalProtocolOverride?.();
+	};
+	const enableLsp = options.enableLsp ?? true;
+	let authStorageClosed = false;
+	const closeOwnedAuthStorage = (): void => {
+		if (!ownsAuthStorage || authStorageClosed) return;
+		authStorageClosed = true;
+		authStorage.close();
+	};
+	let unsubscribeCredentialDisabled: (() => void) | undefined;
+	const releaseCredentialDisabledSubscription = (): void => {
+		const unsubscribe = unsubscribeCredentialDisabled;
+		unsubscribeCredentialDisabled = undefined;
+		unsubscribe?.();
 	};
-	const earlyCredentialSelectorProvider = options.credentialSelector?.provider ?? options.model?.provider;
-	if (earlyCredentialSelectorProvider) {
-		installRuntimeCredentialSelector(earlyCredentialSelectorProvider);
-	}
-	const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
-	modelRegistry.applyConfiguredModelBindings(settings);
-	logger.time("initializeWithSettings", initializeWithSettings, settings);
-	const canRefreshModelsBeforeCredentialSelector =
-		!options.credentialSelector || runtimeCredentialSelectorInstalled || options.modelRegistry !== undefined;
-	if (!options.modelRegistry && canRefreshModelsBeforeCredentialSelector) {
-		modelRegistry.refreshInBackground();
-	}
-	// Kick off workspace tree discovery early. The native workspace scan returns
-	// both the rendered-tree input and the AGENTS.md directory-context index, so
-	// startup does not perform a second recursive filesystem search. Subagents
-	// inherit the parent's resolved values via options.
-	const STARTUP_SCAN_DEADLINE_MS = 5000;
-	const workspaceTreePromise: Promise<WorkspaceTree> = options.workspaceTree
-		? Promise.resolve(options.workspaceTree)
-		: logger.time("buildWorkspaceTree", () => buildWorkspaceTree(cwd, { timeoutMs: STARTUP_SCAN_DEADLINE_MS }));
-	workspaceTreePromise.catch(() => {});
-
-	// Independent discoveries that depend only on cwd/agentDir — kicked off in parallel and awaited
-	// at their respective consumer sites. Their work can overlap with model resolution, secret loading,
-	// session-context build, tool creation, MCP discovery, and extension discovery.
-	const contextFilesPromise = options.contextFiles
-		? Promise.resolve(options.contextFiles)
-		: logger.time("discoverContextFiles", discoverContextFiles, cwd, agentDir);
-	contextFilesPromise.catch(() => {});
-	const promptTemplatesPromise = options.promptTemplates
-		? Promise.resolve(options.promptTemplates)
-		: logger.time("discoverPromptTemplates", discoverPromptTemplates, cwd, agentDir);
-	promptTemplatesPromise.catch(() => {});
-	const slashCommandsPromise = options.slashCommands ? Promise.resolve(options.slashCommands) : Promise.resolve([]);
-	slashCommandsPromise.catch(() => {});
-
-	// Initialize provider preferences from settings
-	const webSearchProvider = getConfiguredSearchProviderPreference(settings);
-	setPreferredSearchProvider(webSearchProvider);
-	const webSearchFallback = settings.get("web_search.fallback");
-	if (Array.isArray(webSearchFallback)) {
-		setSearchFallbackProviders(
-			webSearchFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
-		);
-	}
-	applyConfiguredSearchTimeout(settings);
-
-	const imageProvider = settings.get("providers.image");
-	if (
-		imageProvider === "auto" ||
-		imageProvider === "openai" ||
-		imageProvider === "gemini" ||
-		imageProvider === "openrouter" ||
-		imageProvider === "antigravity"
-	) {
-		setPreferredImageProvider(imageProvider);
-	}
 
-	const sessionManager =
-		options.sessionManager ??
-		logger.time("sessionManager", () =>
-			SessionManager.create(cwd, SessionManager.getDefaultSessionDir(cwd, agentDir)),
-		);
-	const logicalSessionId = sessionManager.getSessionId();
-	const providerSessionId = options.providerSessionId ?? options.forkContextSeed?.cacheIdentity ?? logicalSessionId;
-	const modelApiKeyAvailability = new Map<string, boolean>();
-	const getModelAvailabilityKey = (candidate: Model): string =>
-		`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
-	const hasModelApiKey = async (candidate: Model): Promise<boolean> => {
-		const availabilityKey = getModelAvailabilityKey(candidate);
-		const cached = modelApiKeyAvailability.get(availabilityKey);
-		if (cached !== undefined) {
-			return cached;
+	try {
+		// Subscribe before any getApiKey() call so startup model probes can't fire a
+		// credential_disabled event past us. An embedder's constructor handler makes the
+		// listener set non-empty from construction, which defeats AuthStorage's no-listener
+		// buffer — so we can't rely on it to catch startup events for the extension runner.
+		const startupCredentialDisabledEvents: CredentialDisabledEvent[] = [];
+		let credentialDisabledTarget: ExtensionRunner | undefined;
+		unsubscribeCredentialDisabled = authStorage.onCredentialDisabled(event => {
+			if (credentialDisabledTarget) {
+				// Discard return: any handler error is routed through runner.onError listeners.
+				void credentialDisabledTarget.emitCredentialDisabled(event);
+			} else {
+				startupCredentialDisabledEvents.push(event);
+			}
+		});
+		let runtimeCredentialSelectorInstalled = false;
+		const installRuntimeCredentialSelector = (provider: string): void => {
+			if (!options.credentialSelector || runtimeCredentialSelectorInstalled) return;
+			authStorage.setRuntimeCredentialSelector(provider, options.credentialSelector.selector);
+			runtimeCredentialSelectorInstalled = true;
+		};
+		const earlyCredentialSelectorProvider = options.credentialSelector?.provider ?? options.model?.provider;
+		if (earlyCredentialSelectorProvider) {
+			installRuntimeCredentialSelector(earlyCredentialSelectorProvider);
 		}
+		const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
+		modelRegistry.applyConfiguredModelBindings(settings);
+		logger.time("initializeWithSettings", initializeWithSettings, settings);
+		const canRefreshModelsBeforeCredentialSelector =
+			!options.credentialSelector || runtimeCredentialSelectorInstalled || options.modelRegistry !== undefined;
+		if (!options.modelRegistry && canRefreshModelsBeforeCredentialSelector) {
+			modelRegistry.refreshInBackground();
+		}
+		// Kick off workspace tree discovery early. The native workspace scan returns
+		// both the rendered-tree input and the AGENTS.md directory-context index, so
+		// startup does not perform a second recursive filesystem search. Subagents
+		// inherit the parent's resolved values via options.
+		const STARTUP_SCAN_DEADLINE_MS = 5000;
+		const workspaceTreePromise: Promise<WorkspaceTree> = options.workspaceTree
+			? Promise.resolve(options.workspaceTree)
+			: logger.time("buildWorkspaceTree", () => buildWorkspaceTree(cwd, { timeoutMs: STARTUP_SCAN_DEADLINE_MS }));
+		workspaceTreePromise.catch(() => {});
+
+		// Independent discoveries that depend only on cwd/agentDir — kicked off in parallel and awaited
+		// at their respective consumer sites. Their work can overlap with model resolution, secret loading,
+		// session-context build, tool creation, MCP discovery, and extension discovery.
+		const contextFilesPromise = options.contextFiles
+			? Promise.resolve(options.contextFiles)
+			: logger.time("discoverContextFiles", discoverContextFiles, cwd, agentDir);
+		contextFilesPromise.catch(() => {});
+		const promptTemplatesPromise = options.promptTemplates
+			? Promise.resolve(options.promptTemplates)
+			: logger.time("discoverPromptTemplates", discoverPromptTemplates, cwd, agentDir);
+		promptTemplatesPromise.catch(() => {});
+		const slashCommandsPromise = options.slashCommands ? Promise.resolve(options.slashCommands) : Promise.resolve([]);
+		slashCommandsPromise.catch(() => {});
+
+		// Initialize provider preferences from settings
+		const webSearchProvider = getConfiguredSearchProviderPreference(settings);
+		setPreferredSearchProvider(webSearchProvider);
+		const webSearchFallback = settings.get("web_search.fallback");
+		if (Array.isArray(webSearchFallback)) {
+			setSearchFallbackProviders(
+				webSearchFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
+			);
+		}
+		applyConfiguredSearchTimeout(settings);
 
-		const credentialSelector =
-			options.credentialSelector && !runtimeCredentialSelectorInstalled
-				? options.credentialSelector.provider === undefined ||
-					options.credentialSelector.provider === candidate.provider
-					? options.credentialSelector.selector
-					: undefined
-				: undefined;
-		if (options.credentialSelector?.provider && options.credentialSelector.provider !== candidate.provider) {
-			modelApiKeyAvailability.set(availabilityKey, false);
-			return false;
+		const imageProvider = settings.get("providers.image");
+		if (
+			imageProvider === "auto" ||
+			imageProvider === "openai" ||
+			imageProvider === "gemini" ||
+			imageProvider === "openrouter" ||
+			imageProvider === "antigravity"
+		) {
+			setPreferredImageProvider(imageProvider);
 		}
-		const key = await modelRegistry.getApiKey(candidate, providerSessionId, { credentialSelector }).catch(error => {
-			if (credentialSelector) {
-				logger.debug("Credential selector did not match model availability candidate", {
-					provider: candidate.provider,
-					model: candidate.id,
-					error: error instanceof Error ? error.message : String(error),
-				});
-				return undefined;
+
+		const sessionManager =
+			options.sessionManager ??
+			(await logger.time("sessionManager", async () => {
+				const sessionDir = SessionManager.getDefaultSessionDir(cwd, agentDir);
+				return SessionManager.create(cwd, sessionDir);
+			}));
+		const logicalSessionId = sessionManager.getSessionId();
+		const providerSessionId = options.providerSessionId ?? options.forkContextSeed?.cacheIdentity ?? logicalSessionId;
+		const modelApiKeyAvailability = new Map<string, boolean>();
+		const getModelAvailabilityKey = (candidate: Model): string =>
+			`${candidate.provider}\u0000${candidate.baseUrl ?? ""}`;
+		const hasModelApiKey = async (candidate: Model): Promise<boolean> => {
+			const availabilityKey = getModelAvailabilityKey(candidate);
+			const cached = modelApiKeyAvailability.get(availabilityKey);
+			if (cached !== undefined) {
+				return cached;
 			}
-			throw error;
-		});
-		const hasKey = Boolean(key) && (!credentialSelector || key !== kNoAuth);
-		modelApiKeyAvailability.set(availabilityKey, hasKey);
-		return hasKey;
-	};
 
-	// Load and create secret obfuscator early so resumed session state and prompt warnings
-	// reflect actual loaded secrets, not just the setting toggle.
-	let obfuscator: SecretObfuscator | undefined;
-	if (settings.get("secrets.enabled")) {
-		const fileEntries = await logger.time("loadSecrets", loadSecrets, cwd, agentDir);
-		const envEntries = collectEnvSecrets();
-		const allEntries = [...envEntries, ...fileEntries];
-		if (allEntries.length > 0) {
-			obfuscator = new SecretObfuscator(allEntries);
+			const credentialSelector =
+				options.credentialSelector && !runtimeCredentialSelectorInstalled
+					? options.credentialSelector.provider === undefined ||
+						options.credentialSelector.provider === candidate.provider
+						? options.credentialSelector.selector
+						: undefined
+					: undefined;
+			if (options.credentialSelector?.provider && options.credentialSelector.provider !== candidate.provider) {
+				modelApiKeyAvailability.set(availabilityKey, false);
+				return false;
+			}
+			const key = await modelRegistry
+				.getApiKey(candidate, providerSessionId, { credentialSelector })
+				.catch(error => {
+					if (credentialSelector) {
+						logger.debug("Credential selector did not match model availability candidate", {
+							provider: candidate.provider,
+							model: candidate.id,
+							error: error instanceof Error ? error.message : String(error),
+						});
+						return undefined;
+					}
+					throw error;
+				});
+			const hasKey = Boolean(key) && (!credentialSelector || key !== kNoAuth);
+			modelApiKeyAvailability.set(availabilityKey, hasKey);
+			return hasKey;
+		};
+
+		// Load and create secret obfuscator early so resumed session state and prompt warnings
+		// reflect actual loaded secrets, not just the setting toggle.
+		let obfuscator: SecretObfuscator | undefined;
+		if (settings.get("secrets.enabled")) {
+			const fileEntries = await logger.time("loadSecrets", loadSecrets, cwd, agentDir);
+			const envEntries = collectEnvSecrets();
+			const allEntries = [...envEntries, ...fileEntries];
+			if (allEntries.length > 0) {
+				obfuscator = new SecretObfuscator(allEntries);
+			}
 		}
-	}
-	const secretsEnabled = obfuscator?.hasSecrets() === true;
+		const secretsEnabled = obfuscator?.hasSecrets() === true;
 
-	// Check if session has existing data to restore
-	const existingSession = logger.time("loadSessionContext", () =>
-		deobfuscateSessionContext(sessionManager.buildSessionContext(), obfuscator),
-	);
-	const existingBranch = logger.time("getSessionBranch", () => sessionManager.getBranch());
-	const hasExistingSession = existingBranch.length > 0;
-	const hasThinkingEntry = existingBranch.some(entry => entry.type === "thinking_level_change");
-	const hasServiceTierEntry = existingBranch.some(entry => entry.type === "service_tier_change");
-
-	const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
-	const modelMatchPreferences = {
-		usageOrder: settings.getStorage()?.getModelUsageOrder(),
-	};
-	const allowedModels = await logger.time("resolveAllowedModels", () =>
-		resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
-	);
-	const defaultRoleSpec = logger.time("resolveDefaultModelRole", () =>
-		resolveModelRoleValue(settings.getModelRole("default"), allowedModels, {
-			settings,
-			matchPreferences: modelMatchPreferences,
-			modelRegistry,
-		}),
-	);
-	let model = options.model;
-	let modelFallbackMessage: string | undefined;
-	const persistedDefaultChain = existingSession.configuredModelChains.default?.entries;
-	const defaultModelEntries =
-		persistedDefaultChain && persistedDefaultChain.length > 0
-			? persistedDefaultChain
-			: existingSession.models.default
-				? [existingSession.models.default]
-				: [];
-	// If session has data, restore its configured default chain rather than the
-	// scalar runtime model, which may be a stale fallback from the prior run.
-	if (!hasExplicitModel && !model && hasExistingSession && defaultModelEntries.length > 0) {
-		await logger.time("restoreSessionModel", async () => {
-			const restoredDefaultResolution = await resolveModelChainWithAuth(
-				defaultModelEntries,
-				modelRegistry,
+		// Check if session has existing data to restore
+		const existingSession = logger.time("loadSessionContext", () =>
+			deobfuscateSessionContext(sessionManager.buildSessionContext(), obfuscator),
+		);
+		const existingBranch = logger.time("getSessionBranch", () => sessionManager.getBranch());
+		const hasExistingSession = existingBranch.length > 0;
+		const hasThinkingEntry = existingBranch.some(entry => entry.type === "thinking_level_change");
+		const hasServiceTierEntry = existingBranch.some(entry => entry.type === "service_tier_change");
+
+		const hasExplicitModel = options.model !== undefined || options.modelPattern !== undefined;
+		const modelMatchPreferences = {
+			usageOrder: settings.getStorage()?.getModelUsageOrder(),
+		};
+		const allowedModels = await logger.time("resolveAllowedModels", () =>
+			resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
+		);
+		const defaultRoleSpec = logger.time("resolveDefaultModelRole", () =>
+			resolveModelRoleValue(settings.getModelRole("default"), allowedModels, {
 				settings,
-				providerSessionId,
-				{ managedFallback: defaultModelEntries.length > 1 },
-			);
-			model = restoredDefaultResolution.model;
-			if (!model) modelFallbackMessage = `Could not restore model ${defaultModelEntries.join(" -> ")}`;
-		});
-	}
-
-	// If still no model, try settings default.
-	// Skip settings fallback when an explicit model was requested.
-	if (!hasExplicitModel && !model && defaultRoleSpec.model) {
-		const settingsDefaultModel = defaultRoleSpec.model;
-		logger.time("resolveSettingsDefaultModel", () => {
-			// defaultRoleSpec.model already comes from modelRegistry.getAvailable(),
-			// so re-validating auth here just repeats the expensive lookup path.
-			model = settingsDefaultModel;
-		});
-	}
-
-	const taskDepth = options.taskDepth ?? 0;
+				matchPreferences: modelMatchPreferences,
+				modelRegistry,
+			}),
+		);
+		let model = options.model;
+		let modelFallbackMessage: string | undefined;
+		const persistedDefaultChain = existingSession.configuredModelChains.default?.entries;
+		const defaultModelEntries =
+			persistedDefaultChain && persistedDefaultChain.length > 0
+				? persistedDefaultChain
+				: existingSession.models.default
+					? [existingSession.models.default]
+					: [];
+		// If session has data, restore its configured default chain rather than the
+		// scalar runtime model, which may be a stale fallback from the prior run.
+		if (!hasExplicitModel && !model && hasExistingSession && defaultModelEntries.length > 0) {
+			await logger.time("restoreSessionModel", async () => {
+				const restoredDefaultResolution = await resolveModelChainWithAuth(
+					defaultModelEntries,
+					modelRegistry,
+					settings,
+					providerSessionId,
+					{ managedFallback: defaultModelEntries.length > 1 },
+				);
+				model = restoredDefaultResolution.model;
+				if (!model) modelFallbackMessage = `Could not restore model ${defaultModelEntries.join(" -> ")}`;
+			});
+		}
 
-	let thinkingLevel = options.thinkingLevel;
-	const hasExplicitDefaultThinkingLevel = settings.has("defaultThinkingLevel");
-	let thinkingLevelFromSchemaDefault = false;
+		// If still no model, try settings default.
+		// Skip settings fallback when an explicit model was requested.
+		if (!hasExplicitModel && !model && defaultRoleSpec.model) {
+			const settingsDefaultModel = defaultRoleSpec.model;
+			logger.time("resolveSettingsDefaultModel", () => {
+				// defaultRoleSpec.model already comes from modelRegistry.getAvailable(),
+				// so re-validating auth here just repeats the expensive lookup path.
+				model = settingsDefaultModel;
+			});
+		}
 
-	// If session has data and includes a thinking entry, restore an explicit session
-	// override. A persisted inherit marker deliberately re-enters the normal
-	// default-role/global/model resolution path instead of resolving to `undefined`.
-	const restoredThinkingLevel =
-		hasExistingSession && hasThinkingEntry ? parseThinkingLevel(existingSession.thinkingLevel) : undefined;
-	if (thinkingLevel === undefined && restoredThinkingLevel !== ThinkingLevel.Inherit) {
-		thinkingLevel = restoredThinkingLevel;
-	}
+		const taskDepth = options.taskDepth ?? 0;
 
-	if (thinkingLevel === undefined && !hasExplicitModel && defaultRoleSpec.explicitThinkingLevel) {
-		thinkingLevel = defaultRoleSpec.thinkingLevel;
-	}
+		let thinkingLevel = options.thinkingLevel;
+		const hasExplicitDefaultThinkingLevel = settings.has("defaultThinkingLevel");
+		let thinkingLevelFromSchemaDefault = false;
 
-	// An explicit user/project default should win over the model's bundled
-	// defaultLevel. The schema default is only a final fallback so model metadata
-	// can keep driving first-run behavior until the user chooses "Set as default".
-	if (thinkingLevel === undefined && hasExplicitDefaultThinkingLevel) {
-		thinkingLevel = settings.get("defaultThinkingLevel");
-	}
+		// If session has data and includes a thinking entry, restore an explicit session
+		// override. A persisted inherit marker deliberately re-enters the normal
+		// default-role/global/model resolution path instead of resolving to `undefined`.
+		const restoredThinkingLevel =
+			hasExistingSession && hasThinkingEntry ? parseThinkingLevel(existingSession.thinkingLevel) : undefined;
+		if (thinkingLevel === undefined && restoredThinkingLevel !== ThinkingLevel.Inherit) {
+			thinkingLevel = restoredThinkingLevel;
+		}
 
-	if (thinkingLevel === undefined && model?.thinking?.defaultLevel !== undefined) {
-		thinkingLevel = model.thinking.defaultLevel;
-	}
+		if (thinkingLevel === undefined && !hasExplicitModel && defaultRoleSpec.explicitThinkingLevel) {
+			thinkingLevel = defaultRoleSpec.thinkingLevel;
+		}
 
-	if (thinkingLevel === undefined) {
-		thinkingLevel = settings.get("defaultThinkingLevel");
-		thinkingLevelFromSchemaDefault = true;
-	}
-	if (model) {
-		const resolvedModel = model;
-		thinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
-			resolveThinkingLevelForModel(resolvedModel, thinkingLevel),
-		);
-		// Fire-and-forget TLS+H2 handshake to the model's host so it overlaps
-		// with the rest of session setup (extension/skill load, tool registry,
-		// system prompt build). Without this, the first `fetch(...)` pays the
-		// full handshake serially — 100–300 ms transcontinental for
-		// api.anthropic.com from a residential IP. Every session frontend benefits
-		// (interactive, print, SDK, ACP).
-		preconnectModelHost(model.baseUrl);
-	}
+		// An explicit user/project default should win over the model's bundled
+		// defaultLevel. The schema default is only a final fallback so model metadata
+		// can keep driving first-run behavior until the user chooses "Set as default".
+		if (thinkingLevel === undefined && hasExplicitDefaultThinkingLevel) {
+			thinkingLevel = settings.get("defaultThinkingLevel");
+		}
 
-	let skills: Skill[];
-	let skillWarnings: SkillWarning[];
-	if (options.skills !== undefined) {
-		// The four public GJC workflow skills are a product invariant, not
-		// ordinary filesystem-discovered skills. Keep them available even for
-		// explicit SDK skill lists so startup and command routing survive
-		// accidental `.gjc` deletion or overzealous caller filtering.
-		skills = withEmbeddedDefaultGjcSkills(options.skills);
-		skillWarnings = [];
-	} else if (settings.get("skills.enabled")) {
-		const skillsResult = await logger.time("loadSkills", loadSkills, {
-			...settings.getGroup("skills"),
-			cwd,
-			disabledExtensions: settings.get("disabledExtensions"),
-		});
-		skills = withEmbeddedDefaultGjcSkills(skillsResult.skills);
-		skillWarnings = skillsResult.warnings;
-	} else {
-		// GJC's four public workflow skills are bundled into the binary so the
-		// default workflow surface survives accidental .gjc deletion. Arbitrary
-		// filesystem skill discovery remains gated by skills.enabled above.
-		skills = getEmbeddedDefaultGjcSkills();
-		skillWarnings = [];
-	}
+		if (thinkingLevel === undefined && model?.thinking?.defaultLevel !== undefined) {
+			thinkingLevel = model.thinking.defaultLevel;
+		}
 
-	// Discover rules and bucket them in one pass to avoid repeated scans over large rule sets.
-	const { ttsrManager, rulebookRules, alwaysApplyRules } = await logger.time("discoverTtsrRules", async () => {
-		const ttsrSettings = settings.getGroup("ttsr");
-		const ttsrManager = new TtsrManager(ttsrSettings);
-		const rulesResult =
-			options.rules !== undefined
-				? { items: options.rules, warnings: undefined }
-				: await loadCapability<Rule>(ruleCapability.id, { cwd });
-		const rulebookRules: Rule[] = [];
-		const alwaysApplyRules: Rule[] = [];
-		for (const rule of rulesResult.items) {
-			const isTtsrRule = rule.condition && rule.condition.length > 0 ? ttsrManager.addRule(rule) : false;
-			if (isTtsrRule) {
-				continue;
-			}
-			if (rule.alwaysApply === true) {
-				alwaysApplyRules.push(rule);
-				continue;
-			}
-			if (rule.description) {
-				rulebookRules.push(rule);
-			}
+		if (thinkingLevel === undefined) {
+			thinkingLevel = settings.get("defaultThinkingLevel");
+			thinkingLevelFromSchemaDefault = true;
 		}
-		if (ttsrManager.getSettings().enabled !== false) {
-			if ((existingSession.ttsrMessageCount ?? 0) > 0) {
-				ttsrManager.restoreMessageCount(existingSession.ttsrMessageCount ?? 0);
-			}
-			if (existingSession.injectedTtsrRuleRecords && existingSession.injectedTtsrRuleRecords.length > 0) {
-				ttsrManager.restoreInjected(existingSession.injectedTtsrRuleRecords);
-			} else if (existingSession.injectedTtsrRules.length > 0) {
-				ttsrManager.restoreInjected(existingSession.injectedTtsrRules);
-			}
+		if (model) {
+			const resolvedModel = model;
+			thinkingLevel = logger.time("resolveThinkingLevelForModel", () =>
+				resolveThinkingLevelForModel(resolvedModel, thinkingLevel),
+			);
+			// Fire-and-forget TLS+H2 handshake to the model's host so it overlaps
+			// with the rest of session setup (extension/skill load, tool registry,
+			// system prompt build). Without this, the first `fetch(...)` pays the
+			// full handshake serially — 100–300 ms transcontinental for
+			// api.anthropic.com from a residential IP. Every session frontend benefits
+			// (interactive, print, SDK, ACP).
+			preconnectModelHost(model.baseUrl);
 		}
-		return { ttsrManager, rulebookRules, alwaysApplyRules };
-	});
 
-	// Resolve contextFiles up-front (it's needed before tool creation). The
-	// workspace tree scan is slow on large repos and we MUST NOT block startup on
-	// it. On timeout we forward `undefined` to ToolSession; buildSystemPromptInternal
-	// will re-race the same promise through its own withDeadline path. Background
-	// work continues so caches still warm.
-	const raceWithDeadline = async <T>(name: string, work: Promise<T>): Promise<T | undefined> => {
-		let timedOut = false;
-		const result = await Promise.race([
-			work,
-			Bun.sleep(STARTUP_SCAN_DEADLINE_MS).then(() => {
-				timedOut = true;
-				return undefined;
-			}),
-		]);
-		if (timedOut) {
-			logger.warn("Startup scan exceeded deadline; deferring to system prompt fallback", {
-				name,
-				timeoutMs: STARTUP_SCAN_DEADLINE_MS,
+		let skills: Skill[];
+		let skillWarnings: SkillWarning[];
+		if (options.skills !== undefined) {
+			// The four public GJC workflow skills are a product invariant, not
+			// ordinary filesystem-discovered skills. Keep them available even for
+			// explicit SDK skill lists so startup and command routing survive
+			// accidental `.gjc` deletion or overzealous caller filtering.
+			skills = withEmbeddedDefaultGjcSkills(options.skills);
+			skillWarnings = [];
+		} else if (settings.get("skills.enabled")) {
+			const skillsResult = await logger.time("loadSkills", loadSkills, {
+				...settings.getGroup("skills"),
 				cwd,
+				disabledExtensions: settings.get("disabledExtensions"),
 			});
+			skills = withEmbeddedDefaultGjcSkills(skillsResult.skills);
+			skillWarnings = skillsResult.warnings;
+		} else {
+			// GJC's four public workflow skills are bundled into the binary so the
+			// default workflow surface survives accidental .gjc deletion. Arbitrary
+			// filesystem skill discovery remains gated by skills.enabled above.
+			skills = getEmbeddedDefaultGjcSkills();
+			skillWarnings = [];
 		}
-		return result;
-	};
-	const [contextFiles, resolvedWorkspaceTree] = await Promise.all([
-		contextFilesPromise,
-		raceWithDeadline("buildWorkspaceTree", workspaceTreePromise),
-	]);
 
-	let agent: Agent;
-	let session!: AgentSession;
-	let hasSession = false;
-	let hasRegistered = false;
-	let cleanupOwnedMcpManager: (() => Promise<void>) | undefined;
-	const enableLsp = options.enableLsp ?? true;
-	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;
-	const formatAsyncResultForFollowUp = async (result: string): Promise<string> => {
-		if (result.length <= ASYNC_INLINE_RESULT_MAX_CHARS) {
+		// Discover rules and bucket them in one pass to avoid repeated scans over large rule sets.
+		const { ttsrManager, rulebookRules, alwaysApplyRules } = await logger.time("discoverTtsrRules", async () => {
+			const ttsrSettings = settings.getGroup("ttsr");
+			const ttsrManager = new TtsrManager(ttsrSettings);
+			const rulesResult =
+				options.rules !== undefined
+					? { items: options.rules, warnings: undefined }
+					: await loadCapability<Rule>(ruleCapability.id, { cwd });
+			const rulebookRules: Rule[] = [];
+			const alwaysApplyRules: Rule[] = [];
+			for (const rule of rulesResult.items) {
+				const isTtsrRule = rule.condition && rule.condition.length > 0 ? ttsrManager.addRule(rule) : false;
+				if (isTtsrRule) {
+					continue;
+				}
+				if (rule.alwaysApply === true) {
+					alwaysApplyRules.push(rule);
+					continue;
+				}
+				if (rule.description) {
+					rulebookRules.push(rule);
+				}
+			}
+			if (ttsrManager.getSettings().enabled !== false) {
+				if ((existingSession.ttsrMessageCount ?? 0) > 0) {
+					ttsrManager.restoreMessageCount(existingSession.ttsrMessageCount ?? 0);
+				}
+				if (existingSession.injectedTtsrRuleRecords && existingSession.injectedTtsrRuleRecords.length > 0) {
+					ttsrManager.restoreInjected(existingSession.injectedTtsrRuleRecords);
+				} else if (existingSession.injectedTtsrRules.length > 0) {
+					ttsrManager.restoreInjected(existingSession.injectedTtsrRules);
+				}
+			}
+			return { ttsrManager, rulebookRules, alwaysApplyRules };
+		});
+
+		// Resolve contextFiles up-front (it's needed before tool creation). The
+		// workspace tree scan is slow on large repos and we MUST NOT block startup on
+		// it. On timeout we forward `undefined` to ToolSession; buildSystemPromptInternal
+		// will re-race the same promise through its own withDeadline path. Background
+		// work continues so caches still warm.
+		const raceWithDeadline = async <T>(name: string, work: Promise<T>): Promise<T | undefined> => {
+			let timedOut = false;
+			const result = await Promise.race([
+				work,
+				Bun.sleep(STARTUP_SCAN_DEADLINE_MS).then(() => {
+					timedOut = true;
+					return undefined;
+				}),
+			]);
+			if (timedOut) {
+				logger.warn("Startup scan exceeded deadline; deferring to system prompt fallback", {
+					name,
+					timeoutMs: STARTUP_SCAN_DEADLINE_MS,
+					cwd,
+				});
+			}
 			return result;
-		}
+		};
+		const [contextFiles, resolvedWorkspaceTree] = await Promise.all([
+			contextFilesPromise,
+			raceWithDeadline("buildWorkspaceTree", workspaceTreePromise),
+		]);
 
-		const preview = `${result.slice(0, ASYNC_PREVIEW_MAX_CHARS)}\n\n[Output truncated. Showing first ${ASYNC_PREVIEW_MAX_CHARS.toLocaleString()} characters.]`;
-		try {
-			const { path: artifactPath, id: artifactId } = await sessionManager.allocateArtifactPath("async");
-			if (artifactPath && artifactId) {
-				await Bun.write(artifactPath, result);
-				return `${preview}\nFull output: artifact://${artifactId}`;
+		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;
+		const formatAsyncResultForFollowUp = async (result: string): Promise<string> => {
+			if (result.length <= ASYNC_INLINE_RESULT_MAX_CHARS) {
+				return result;
 			}
-		} catch (error) {
-			logger.warn("Failed to persist async follow-up artifact", {
-				error: error instanceof Error ? error.message : String(error),
-			});
-		}
 
-		return preview;
-	};
-	// Only top-level sessions own an AsyncJobManager. Subagents reach the
-	// parent's manager via `AsyncJobManager.instance()` (set below), so creating
-	// a second instance here just to leave it orphaned wastes a constructor and
-	// risks accidental disposal of the parent's manager on subagent teardown.
-	const asyncJobManager =
-		backgroundJobsEnabled && !options.parentTaskPrefix
-			? new AsyncJobManager({
-					maxRunningJobs: asyncMaxJobs,
-					onJobComplete: async (jobId, result, job) => {
-						if (!session || asyncJobManager!.isDeliverySuppressed(jobId)) return;
-						const formattedResult = await formatAsyncResultForFollowUp(result);
-						if (asyncJobManager!.isDeliverySuppressed(jobId)) return;
-
-						const durationMs = job ? jobElapsedMs(job) : undefined;
-						session.yieldQueue.enqueue<AsyncResultEntry>("async-result", {
-							jobId,
-							result: formattedResult,
-							job,
-							durationMs,
-						});
-					},
-				})
-			: undefined;
+			const preview = `${result.slice(0, ASYNC_PREVIEW_MAX_CHARS)}\n\n[Output truncated. Showing first ${ASYNC_PREVIEW_MAX_CHARS.toLocaleString()} characters.]`;
+			try {
+				const { path: artifactPath, id: artifactId } = await sessionManager.allocateArtifactPath("async");
+				if (artifactPath && artifactId) {
+					await Bun.write(artifactPath, result);
+					return `${preview}\nFull output: artifact://${artifactId}`;
+				}
+			} catch (error) {
+				logger.warn("Failed to persist async follow-up artifact", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
 
-	const agentRegistry = options.agentRegistry ?? AgentRegistry.global();
-	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
-	const resolvedAgentDisplayName = options.agentDisplayName ?? (isCanonicalSubSession ? "sub" : "main");
-	const resolvedAgentRosterLabel = resolveAgentRosterLabel(
-		options.agentRosterLabel,
-		resolvedAgentId,
-		resolvedAgentDisplayName,
-	);
-	const evalKernelOwnerId = `agent-session:${Snowflake.next()}`;
-	let disposeLocalProtocolOverride: (() => void) | undefined;
-	let localProtocolOverrideReleased = false;
-	const releaseLocalProtocolOverride = (): void => {
-		if (localProtocolOverrideReleased) return;
-		localProtocolOverrideReleased = true;
-		disposeLocalProtocolOverride?.();
-	};
+			return preview;
+		};
+		// Only top-level sessions own an AsyncJobManager. Subagents reach the
+		// parent's manager via `AsyncJobManager.instance()` (set below), so creating
+		// a second instance here just to leave it orphaned wastes a constructor and
+		// risks accidental disposal of the parent's manager on subagent teardown.
+		const asyncJobManager =
+			backgroundJobsEnabled && !options.parentTaskPrefix
+				? new AsyncJobManager({
+						maxRunningJobs: asyncMaxJobs,
+						onJobComplete: async (jobId, result, job) => {
+							if (!session || asyncJobManager!.isDeliverySuppressed(jobId)) return;
+							const formattedResult = await formatAsyncResultForFollowUp(result);
+							if (asyncJobManager!.isDeliverySuppressed(jobId)) return;
+
+							const durationMs = job ? jobElapsedMs(job) : undefined;
+							session.yieldQueue.enqueue<AsyncResultEntry>("async-result", {
+								jobId,
+								result: formattedResult,
+								job,
+								durationMs,
+							});
+						},
+					})
+				: undefined;
 
-	try {
 		let promptMetadataModel: Model | undefined;
 		const getActiveModelString = (): string | undefined => {
 			const activeModel = promptMetadataModel ?? agent?.state.model;
@@ -1454,11 +1481,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			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),
 			// Generic tool discovery (unified — covers built-in + MCP + extension)
 			isToolDiscoveryEnabled: () => session.isToolDiscoveryEnabled(),
 			getDiscoverableTools: filter => session.getDiscoverableTools(filter),
@@ -1743,7 +1765,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				currentAgentType: options.currentAgentType,
 				spawnedByGjc,
 			}) ||
-			shouldHostSdk(notificationCfg, isTopLevelSdkSession)
+			(shouldHostSdk(notificationCfg, isTopLevelSdkSession) && (options.sdkHostModeSupported ?? true))
 		) {
 			inlineExtensions.push(async api => {
 				try {
@@ -1754,6 +1776,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						settings,
 						controller: notificationSessionController,
 						spawnedByGjc,
+						sdkHostModeSupported: options.sdkHostModeSupported,
+						runEphemeralTurn: async (promptText, signal) => {
+							if (!session) throw new Error("Ephemeral turns are unavailable.");
+							const { replyText } = await session.runEphemeralTurn({ promptText, signal });
+							return { replyText };
+						},
 					});
 				} catch (error) {
 					lifecycleStartupCapability?.settleFailure(
@@ -1904,12 +1932,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// No runner to forward to; release our subscription. The embedder's own
 			// onCredentialDisabled (if any) keeps firing through its own subscription.
 			startupCredentialDisabledEvents.length = 0;
-			unsubscribeCredentialDisabled?.();
-			unsubscribeCredentialDisabled = undefined;
+			releaseCredentialDisabledSubscription();
 		}
 
 		const getSessionContext = () => ({
-			sessionManager,
+			sessionManager: createReadonlySessionManager(sessionManager),
 			modelRegistry,
 			model: agent.state.model,
 			isIdle: () => !session.isStreaming,
@@ -1938,7 +1965,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// Without extension runner: wrap CustomTools directly with CustomToolAdapter
 			// ToolDefinition items require ExtensionContext and cannot be used without a runner
 			const customToolContext = (): CustomToolContext => ({
-				sessionManager,
+				sessionManager: createReadonlySessionManager(sessionManager),
 				modelRegistry,
 				model: agent?.state.model,
 				isIdle: () => !session?.isStreaming,
@@ -2040,36 +2067,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			candidateModel?: Model,
 		): Promise<BuildSystemPromptResult> => {
 			toolContextStore.setToolNames(toolNames);
-			const { discoverableBuiltinTools, discoverableMCPTools, promptTools } = (() => {
+			const promptTools = (() => {
 				const previousPromptMetadataModel = promptMetadataModel;
 				promptMetadataModel = candidateModel;
 				try {
-					const activeToolNames = new Set(toolNames);
-					const discoverableBuiltinTools: DiscoverableTool[] =
-						effectiveDiscoveryMode === "all"
-							? collectDiscoverableTools(
-									Array.from(tools.values()).filter(
-										tool => tool.loadMode === "discoverable" && !activeToolNames.has(tool.name),
-									),
-									{ source: "builtin" },
-								)
-							: [];
-					const discoverableMCPTools: DiscoverableTool[] = mcpDiscoveryEnabled
-						? collectDiscoverableTools(
-								Array.from(tools.values()).filter(
-									tool => isMCPToolName(tool.name) && !activeToolNames.has(tool.name),
-								),
-								{ source: "mcp" },
-							)
-						: [];
-					const discoverableToolsForDesc: DiscoverableTool[] = [
-						...discoverableBuiltinTools,
-						...discoverableMCPTools,
-					];
-					const promptTools = buildSystemPromptToolMetadata(tools, {
-						search_tool_bm25: { description: renderSearchToolBm25Description(discoverableToolsForDesc) },
-					});
-					return { discoverableBuiltinTools, discoverableMCPTools, promptTools };
+					return buildSystemPromptToolMetadata(tools);
 				} finally {
 					promptMetadataModel = previousPromptMetadataModel;
 				}
@@ -2080,25 +2082,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				session,
 			);
 
-			// Build combined append prompt: memory instructions + MCP server instructions
-			const serverInstructions =
-				explicitMcpConfigPath === undefined ? mcpManager?.getServerInstructions() : undefined;
-			let appendPrompt: string | undefined = memoryInstructions ?? undefined;
-			if (serverInstructions && serverInstructions.size > 0) {
-				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_MCP_INSTRUCTIONS_LENGTH
-							? `${srvInstructions.slice(0, MAX_MCP_INSTRUCTIONS_LENGTH)}\n[truncated]`
-							: srvInstructions;
-					parts.push(`### ${srvName}\n${truncated}`);
-				}
-				appendPrompt = parts.join("\n\n");
-			}
+			const appendPrompt: string | undefined = memoryInstructions ?? undefined;
 			let pluginSystemAppendices = "";
 			try {
 				pluginSystemAppendices = await renderAlwaysOnSystemAppendices({ cwd });
@@ -2118,12 +2102,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				pluginAppendices: pluginSystemAppendices,
 				repeatToolDescriptions,
 				intentField,
-				mcpDiscoveryMode: false,
-				mcpDiscoveryServerSummaries: [],
 				toolDiscoveryActive: effectiveDiscoveryMode === "all" || mcpDiscoveryEnabled,
-				discoverableTools: [...discoverableBuiltinTools, ...discoverableMCPTools]
-					.map(tool => ({ name: tool.name, summary: tool.summary }))
-					.sort((a, b) => a.name.localeCompare(b.name)),
 				eagerTasks,
 				secretsEnabled,
 				workspaceTree: workspaceTreePromise,
@@ -2152,12 +2131,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			: toolNamesFromRegistry;
 		const normalizedRequested = requestedToolNames.filter(name => toolRegistry.has(name));
 		const requestedToolNameSet = new Set(normalizedRequested);
-		// Generic tool discovery hides non-essential built-ins behind search_tool_bm25.
-		// Legacy MCP discovery remains separately controlled by mcp.discoveryMode so
-		// loaded MCP catalogs can be searched without enabling every hidden built-in.
+		// Normalize the user-facing mcp.discoveryMode alias once at session construction.
 		const toolsDiscoveryModeSetting = settings.get("tools.discoveryMode");
-		const effectiveDiscoveryMode: "off" | "all" = toolsDiscoveryModeSetting === "all" ? "all" : "off";
-		const mcpDiscoveryEnabled = settings.get("mcp.discoveryMode") === true;
+		const effectiveDiscoveryMode: "off" | "mcp-only" | "all" =
+			toolsDiscoveryModeSetting !== "off"
+				? (toolsDiscoveryModeSetting as "mcp-only" | "all")
+				: settings.get("mcp.discoveryMode") || explicitMcpConfigPath !== undefined
+					? "mcp-only"
+					: "off";
+		const mcpDiscoveryEnabled = effectiveDiscoveryMode !== "off";
 		const defaultInactiveToolNames = new Set(
 			registeredTools.filter(tool => tool.definition.defaultInactive).map(tool => tool.definition.name),
 		);
@@ -2190,7 +2172,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				toolRegistry.has(name),
 			);
 			defaultSelectedMCPToolNames = [
-				...new Set([...discoveryDefaultServerToolNames, ...explicitlyRequestedMCPToolNames]),
+				...new Set([
+					...discoveryDefaultServerToolNames,
+					...explicitlyRequestedMCPToolNames,
+					...(explicitMcpConfigPath !== undefined ? exactMcpToolNames : []),
+				]),
 			];
 			initialSelectedMCPToolNames = existingSession.hasPersistedMCPToolSelection
 				? restoredSelectedMCPToolNames
@@ -2303,11 +2289,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (!obfuscator?.hasSecrets()) return converted;
 			return obfuscateMessages(obfuscator, converted);
 		};
-		const transformContext = extensionRunner
-			? async (messages: AgentMessage[], _signal?: AbortSignal) => {
-					return await extensionRunner.emitContext(messages);
-				}
-			: undefined;
+		const transformContext = async (messages: AgentMessage[], _signal?: AbortSignal) => {
+			// External Agent events dispatch listeners without awaiting them. The
+			// session-owned barrier makes any pre-admission artifact transformation
+			// visible before this provider context is normalized.
+			await session?.awaitPendingContextTransformations();
+			return extensionRunner ? await extensionRunner.emitContext(messages) : messages;
+		};
 		const onPayload = extensionRunner
 			? async (payload: unknown, _model?: Model) => {
 					return await extensionRunner.emitBeforeProviderRequest(payload);
@@ -2524,28 +2512,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			onResponse,
 			convertToLlm: convertToLlmFinal,
 			rebuildSystemPrompt,
+			getMcpServerInstructions:
+				explicitMcpConfigPath === undefined && mcpManager ? () => mcpManager.getServerInstructions() : undefined,
 			workspaceTree: resolvedWorkspaceTree,
 			reloadSshTool,
 			requestedToolNames: requestedToolNameSet,
 			discoverableToolAllowedNames: options.discoverableToolAllowedNames,
-			getMcpServerInstructions:
-				mcpManager && explicitMcpConfigPath === undefined
-					? () => {
-							const raw = mcpManager.getServerInstructions();
-							if (!raw || raw.size === 0) return raw;
-							const out = new Map<string, string>();
-							for (const [name, text] of raw) {
-								out.set(
-									name,
-									text.length > MAX_MCP_INSTRUCTIONS_LENGTH
-										? text.slice(0, MAX_MCP_INSTRUCTIONS_LENGTH)
-										: text,
-								);
-							}
-							return out;
-						}
-					: undefined,
 			mcpDiscoveryEnabled,
+			discoveryMode: effectiveDiscoveryMode,
 			initialSelectedMCPToolNames,
 			defaultSelectedMCPToolNames,
 			persistInitialMCPToolSelection: !hasExistingSession,
@@ -2580,9 +2554,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				try {
 					await originalDispose();
 				} finally {
-					agentRegistry.unregister(resolvedAgentId);
-					unsubscribeCredentialDisabled?.();
-					releaseLocalProtocolOverride();
+					try {
+						agentRegistry.unregister(resolvedAgentId);
+						releaseCredentialDisabledSubscription();
+						releaseLocalProtocolOverride();
+					} finally {
+						closeOwnedAuthStorage();
+					}
 				}
 			};
 		}
@@ -2697,9 +2675,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		};
 	} catch (error) {
 		// Release the subscription if the throw happened after install but before the
-		// dispose-wrap took ownership. Idempotent with dispose() — Set.delete is a no-op
-		// for already-removed listeners.
-		unsubscribeCredentialDisabled?.();
+		// dispose-wrap took ownership.
+		releaseCredentialDisabledSubscription();
 		try {
 			if (hasSession) {
 				await session.dispose();
@@ -2713,6 +2690,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			logger.warn("Failed to clean up createAgentSession resources after startup error");
 		} finally {
 			releaseLocalProtocolOverride();
+			try {
+				closeOwnedAuthStorage();
+			} catch {
+				logger.warn("Failed to close owned auth storage after startup error");
+			}
 		}
 		throw error;
 	}