@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/sdk/session.ts

@@ -49,6 +49,7 @@ import {
 } from "../append-only-mode";
 import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElapsedMs } from "../async";
 import { asyncJobEndpointId as deriveAsyncJobEndpointId } from "../async/endpoint-id";
+import { formatAsyncResultForFollowUp } from "../async/result-formatting";
 import { resolveBrowserBackend } from "../browser-backend";
 import { loadCapability, reset as resetCapabilities } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
@@ -85,6 +86,7 @@ import { disposeKernelSessionsByOwner } from "../eval/py/executor";
 import type { MasterModeContext } from "../master-mode/context";
 import { describeFoldReceipt } from "../session/fold-coordinator";
 import type { BashRestrictionProfile } from "../tools/bash-allowed-prefixes";
+import { wrapUntrustedContent } from "../tools/fetch";
 import { SearchTool } from "../tools/search";
 import "../discovery";
 import { resolveConfigValue } from "../config/resolve-config-value";
@@ -161,7 +163,8 @@ import {
 	resolveMCPToolCache,
 } from "../runtime-mcp";
 import { createMCPFormInputHandler } from "../runtime-mcp/elicitation";
-import type { MCPLoadResult } from "../runtime-mcp/manager";
+import { type MCPLoadResult, omitUnapprovedProjectStdio } from "../runtime-mcp/manager";
+import { omitPluginMcpNameShadows, retainPluginMcpMandatoryNames } from "../runtime-mcp/plugin-mcp-name-filter";
 import { MCP_STARTUP_WAIT_GRACE_MS } from "../runtime-mcp/startup-policy";
 import type { MCPServerConfig } from "../runtime-mcp/types";
 import {
@@ -187,6 +190,7 @@ import {
 	parsePersistedCredentialSelector,
 	resolveStartupAuthConfig,
 	type StartupAuthConfigSnapshot,
+	startupAuthConfigError,
 } from "../session/startup-auth-config";
 import {
 	isOwnedCompletionEnvelopeAllowed,
@@ -206,7 +210,11 @@ import {
 } from "../system-prompt";
 import { AgentOutputManager } from "../task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
-import { isMCPBridgeTool, selectRestorableDiscoveredBuiltinToolNames } from "../tool-discovery/tool-index";
+import {
+	isMCPBridgeTool,
+	isMCPToolName,
+	selectRestorableDiscoveredBuiltinToolNames,
+} from "../tool-discovery/tool-index";
 import {
 	type AutomationToolName,
 	type AutomationTools,
@@ -215,6 +223,7 @@ import {
 	computeEssentialBuiltinNames,
 	createTools,
 	HIDDEN_TOOLS,
+	type LazyAgentTool,
 	resolveEffectiveDiscoveryMode,
 	type Tool,
 	type ToolSession,
@@ -778,6 +787,7 @@ export async function discoverAuthStorage(
 	const resolvedStartupAuth = startupAuth ?? (await resolveStartupAuthConfig(agentDir));
 	const brokerConfig = resolvedStartupAuth.broker;
 	const credentialRankingMode = resolvedStartupAuth.credentialRankingMode;
+	const credentialPreferences = resolvedStartupAuth.credentialPreferences;
 	if (brokerConfig) {
 		const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
 		const initialResult = await client.fetchSnapshot();
@@ -789,16 +799,18 @@ export async function discoverAuthStorage(
 			configValueResolver: resolveConfigValue,
 			sourceLabel: `broker ${brokerConfig.url}`,
 			credentialRankingMode,
+			credentialPreferences,
 		});
-		return await reloadDiscoveredAuthStorage(storage);
+		return rejectDuplicateCredentialPreferences(await reloadDiscoveredAuthStorage(storage), agentDir);
 	}
 	const dbPath = getAgentDbPath(agentDir);
 	const storage = await AuthStorage.create(dbPath, {
 		configValueResolver: resolveConfigValue,
 		sourceLabel: `local ${dbPath}`,
 		credentialRankingMode,
+		credentialPreferences,
 	});
-	return await reloadDiscoveredAuthStorage(storage);
+	return rejectDuplicateCredentialPreferences(await reloadDiscoveredAuthStorage(storage), agentDir);
 }
 
 async function reloadDiscoveredAuthStorage(storage: AuthStorage): Promise<AuthStorage> {
@@ -815,6 +827,26 @@ async function reloadDiscoveredAuthStorage(storage: AuthStorage): Promise<AuthSt
 	return storage;
 }
 
+/**
+ * Two preference entries can name one stored account through different selectors (`email:` and `account:` for the
+ * same login). Only the loaded rows reveal that, so the startup-config check finishes here and fails closed like any
+ * other invalid preference list.
+ */
+function rejectDuplicateCredentialPreferences(storage: AuthStorage, agentDir: string): AuthStorage {
+	const duplicates = storage.findDuplicateCredentialPreferences();
+	if (duplicates.length === 0) return storage;
+	logger.warn("Configured credential preferences name one account twice", {
+		providers: duplicates.map(({ provider }) => sanitizeProviderForLog(provider)),
+	});
+	const error = startupAuthConfigError(agentDir, "invalid-credential-preferences");
+	try {
+		storage.close();
+	} catch (cleanupError) {
+		throw attachStartupCleanupDiagnostic(error, cleanupError);
+	}
+	throw error;
+}
+
 /** Ranking is resolved as part of the typed startup-auth snapshot. */
 
 /**
@@ -1209,7 +1241,10 @@ function buildMCPPromptCommands(manager: MCPManager): LoadedCustomCommand[] {
 								}
 							}
 						}
-						return parts.join("\n\n");
+						const body = parts.join("\n\n");
+						// A blank body must stay blank so the prompt entry still rejects it.
+						if (body.trim().length === 0) return body;
+						return wrapUntrustedContent(body);
 					},
 				},
 			});
@@ -1309,8 +1344,11 @@ function classifyInheritedMcpToolNames(
 	for (const tool of tools) {
 		const serverName = tool.mcpServerName;
 		if (serverName === undefined) continue;
-		if (pluginServers?.has(serverName)) pluginMcpToolNames.push(tool.name);
-		else if (conventionalServers?.has(serverName)) conventionalMcpToolNames.push(tool.name);
+		// Caller-supplied source metadata is descriptive; only a manager's
+		// validated plugin-server set can grant mandatory-tool authority.
+		if (pluginServers?.has(serverName)) {
+			pluginMcpToolNames.push(tool.name);
+		} else if (conventionalServers?.has(serverName)) conventionalMcpToolNames.push(tool.name);
 	}
 	return { pluginMcpToolNames, conventionalMcpToolNames };
 }
@@ -1549,6 +1587,19 @@ function validateAutomationTools(options: CreateAgentSessionOptions): Automation
 	return automationTools;
 }
 
+/** User/global `mcp.enableProjectConfig` only. A project file cannot set it.
+ *  Unset keeps non-stdio project MCP and does not approve a project stdio spawn.
+ */
+function nativeProjectMcpAutoload(settings: Settings): {
+	enableProjectConfig: boolean;
+	allowProjectStdio: boolean;
+} {
+	const configured = settings.getGlobal("mcp.enableProjectConfig");
+	if (configured === true) return { enableProjectConfig: true, allowProjectStdio: true };
+	if (configured === false) return { enableProjectConfig: false, allowProjectStdio: false };
+	return { enableProjectConfig: true, allowProjectStdio: false };
+}
+
 export async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {
 	const automationTools = validateAutomationTools(options);
 	const primaryControlSurface = primaryControlSurfaceFor(options);
@@ -2215,7 +2266,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			? { aliasIntent: "preset-equivalent" }
 			: undefined;
 		const allowedModels = await logger.time("resolveAllowedModels", () =>
-			resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
+			resolveAllowedModels(modelRegistry, settings, modelMatchPreferences, credentialSessionId),
 		);
 		const defaultRoleSpec = logger.time("resolveDefaultModelRole", () =>
 			resolveModelRoleValue(settings.getModelRole("default"), allowedModels, {
@@ -2243,6 +2294,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					: existingSession.models.default
 						? [existingSession.models.default]
 						: [];
+		if (
+			startupRegistryMutationAuthorized &&
+			!hasExplicitModel &&
+			hasExistingSession &&
+			defaultModelEntries.length > 0
+		) {
+			// Resume skips startup discovery, so refresh a missing saved provider
+			// before resolution when this session owns authority to mutate the registry.
+			await refreshMissingQualifiedModelProviders(defaultModelEntries, modelRegistry, credentialSessionId);
+		}
 		const persistedProfileName =
 			persistedDefaultChain?.origin === "profile-activation" ? persistedDefaultChain.identity : undefined;
 		const resolvedPersistedProfileName = persistedProfileName
@@ -2455,7 +2516,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const rulebookRules: Rule[] = [];
 			const alwaysApplyRules: Rule[] = [];
 			for (const rule of rulesResult.items) {
-				const isTtsrRule = rule.condition && rule.condition.length > 0 ? ttsrManager.addRule(rule) : false;
+				const hasTtsrCondition = (rule.condition?.length ?? 0) > 0 || (rule.astCondition?.length ?? 0) > 0;
+				const isTtsrRule = hasTtsrCondition ? ttsrManager.addRule(rule) : false;
 				if (isTtsrRule) {
 					continue;
 				}
@@ -2515,33 +2577,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		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, allowArtifact = true): Promise<string> => {
-			if (result.length <= ASYNC_INLINE_RESULT_MAX_CHARS) {
-				return result;
-			}
-
-			const preview = `${result.slice(0, ASYNC_PREVIEW_MAX_CHARS)}\n\n[Output truncated. Showing first ${ASYNC_PREVIEW_MAX_CHARS.toLocaleString()} characters.]`;
-			// A delivery already denied by a scope:"owned" gate never reaches the
-			// model: allocating an artifact for it would leave the stopped job's
-			// output in an unreferenced artifact after the flush drops it (review
-			// thread P2). Only the inline preview is produced.
-			if (!allowArtifact) return preview;
-			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),
-				});
-			}
-
-			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
@@ -2599,7 +2634,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 								if (job) asyncJobManager?.retainParkedDelivery(job, result);
 								return;
 							}
-							const formattedResult = await formatAsyncResultForFollowUp(result, !deniedOwnedDelivery);
+							const formattedResult = await formatAsyncResultForFollowUp(
+								sessionManager,
+								result,
+								!deniedOwnedDelivery,
+							);
 							if (
 								foldDisposition.kind === "receipt" &&
 								job &&
@@ -2742,16 +2781,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				ownedMcpManagerTools = [];
 				publishOwnedMcpTools = false;
 				let nextManager: MCPManager | undefined;
+				const projectMcp = nativeProjectMcpAutoload(settings);
 				try {
 					const loaded = await loadAllMCPConfigs(to, {
 						agentDir,
-						enableProjectConfig: settings.has("mcp.enableProjectConfig")
-							? settings.get("mcp.enableProjectConfig")
-							: true,
+						enableProjectConfig: projectMcp.enableProjectConfig,
 						autoloadOnly: true,
 						nativeOnly: true,
 						settings,
 					});
+					omitUnapprovedProjectStdio(loaded.configs, loaded.sources, projectMcp.allowProjectStdio);
 					const { configs: pluginConfigs } = await buildPluginMcpConfigs({ cwd: to });
 					const pluginNames = new Set(Object.keys(pluginConfigs));
 					const mergedConfigs = { ...loaded.configs, ...pluginConfigs };
@@ -2776,6 +2815,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							{
 								sharedPoolIdleMs: settings.get("mcp.sharedPoolIdleMs"),
 								toolCacheServerNames: conventionalCacheServerNames,
+								allowUntrustedProjectStdio: projectMcp.allowProjectStdio,
 							},
 						);
 						nextManager.setAuthStorage(authStorage);
@@ -2814,9 +2854,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						for (const tool of result.tools) {
 							const serverName = tool.mcpServerName;
 							if (serverName === undefined) continue;
-							if (pluginNames.has(serverName)) pluginMcpToolNames.push(tool.name);
-							else conventionalMcpToolNames.push(tool.name);
+							if (!pluginNames.has(serverName)) conventionalMcpToolNames.push(tool.name);
 						}
+						pluginMcpToolNames.push(
+							...retainPluginMcpMandatoryNames(
+								result.tools,
+								result.tools
+									.filter(tool => tool.mcpServerName && pluginNames.has(tool.mcpServerName))
+									.map(tool => tool.name),
+							),
+						);
 					}
 				} catch (error) {
 					logger.warn("Failed to recreate MCP authority after session rescope", {
@@ -2835,7 +2882,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			await session.replaceNamedCustomTools(
 				previousCwdCapturing.filter(name => !nextCustomTools.some(tool => tool.name === name)),
 				nextCustomTools,
-				{ mandatoryMCPToolNames: pluginMcpToolNames },
+				{
+					mandatoryMCPToolNames: pluginMcpToolNames,
+					defaultSelectedConventionalMCPToolNames: deferConventionalMcpAutoload ? [] : conventionalMcpToolNames,
+					inactiveNewToolNames: deferConventionalMcpAutoload ? conventionalMcpToolNames : undefined,
+				},
 			);
 			wireOwnedMcpToolSync();
 		};
@@ -2945,11 +2996,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 										"This session has already been rescoped; only one agent-invoked move is allowed per session.",
 									);
 								}
-								if (session?.getEffectiveActiveWorkflowSkillState()) {
-									throw new Error(
-										"A workflow skill is active in this session; finish or exit it before rescoping.",
-									);
-								}
 								if (options.mcpManager && !ownsMcpManager) {
 									throw new Error(
 										"Cannot rescope a session with caller-owned MCP authority; recreate the session at the target cwd.",
@@ -2961,9 +3007,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 											"This session has already been rescoped; only one agent-invoked move is allowed per session.",
 										);
 									}
-									if (session?.getEffectiveActiveWorkflowSkillState()) {
+									if (await session?.refreshEffectiveActiveWorkflowSkillState()) {
 										throw new Error(
-											"A workflow skill became active while waiting for the cwd transition; finish or exit it before rescoping.",
+											"A workflow skill is active in this session; finish or exit it before rescoping.",
 										);
 									}
 									const from = sessionManager.getCwd();
@@ -3281,6 +3327,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getWorkflowGateEmitter: () => session?.getWorkflowGateEmitter(),
 			getAskAnswerSource: () => session?.getAskAnswerSource(),
 			getGoalRuntime: () => session?.goalRuntime,
+			getSdkPermissionMode: () => session?.sdkPermissionMode ?? "allow",
 			getClientBridge: () => session?.clientBridge,
 			getCompactContext: () => session.formatCompactContext(),
 			getTodoPhases: () => session.getTodoPhases(),
@@ -3400,6 +3447,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			options.toolNames,
 			automationTools,
 		);
+		const taskFacade = builtinTools.find(tool => tool.name === "task") as LazyAgentTool | undefined;
 
 		// A top-level session loads MCP tools from three bounded surfaces: a
 		// caller-supplied exact config (`--mcp-config`), conventional native
@@ -3754,6 +3802,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// `--mcp-config` exact-file sessions never reach here. The owned manager's
 			// tools are surfaced as always-on custom tools (like plugin MCPs), so an
 			// ordinary session exposes them without needing MCP discovery mode.
+			const projectMcp = nativeProjectMcpAutoload(settings);
 			let conventionalConfigs: Record<string, MCPServerConfig> = {};
 			let conventionalSources: Record<string, SourceMeta> = {};
 			if (options.enableMcpAutoload !== false) {
@@ -3763,13 +3812,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						// `gjc mcp add` (user scope) writes; an SDK embedder that runs on
 						// its own agent directory autoloads its own registrations.
 						agentDir,
-						// Project-scope native config loads by default; only an
-						// explicitly configured `mcp.enableProjectConfig: false`
-						// disables it (the legacy schema default stays false for
-						// foreign-format discovery consumers of the capability system).
-						enableProjectConfig: settings.has("mcp.enableProjectConfig")
-							? settings.get("mcp.enableProjectConfig")
-							: true,
+						// Non-stdio project MCP stays on unless the user/global layer
+						// sets `mcp.enableProjectConfig` to false. Project files cannot
+						// set that flag. Project stdio also needs it explicitly true.
+						enableProjectConfig: projectMcp.enableProjectConfig,
 						autoloadOnly: true,
 						// Runtime authority is GJC's native `.gjc` config in both scopes;
 						// Claude Code/Codex MCP files are explicit import sources into
@@ -3777,6 +3823,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						nativeOnly: true,
 						settings,
 					});
+					omitUnapprovedProjectStdio(loaded.configs, loaded.sources, projectMcp.allowProjectStdio);
 					conventionalConfigs = loaded.configs;
 					conventionalSources = loaded.sources;
 					for (const warning of loaded.warnings) {
@@ -3841,6 +3888,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						{
 							sharedPoolIdleMs: settings.get("mcp.sharedPoolIdleMs"),
 							toolCacheServerNames: conventionalCacheServerNames,
+							allowUntrustedProjectStdio: projectMcp.allowProjectStdio,
 							...(maxPluginMcpStartupWaitMs === undefined
 								? {}
 								: { maxStartupTimeoutMs: maxPluginMcpStartupWaitMs }),
@@ -3940,7 +3988,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const inlineExtensions: ExtensionFactory[] = [...(options.extensions ?? [])];
 		const discoveredHookExtensions: Array<{ factory: ExtensionFactory; name: string }> = [];
 		if (customTools.length > 0) {
-			inlineExtensions.push(createCustomToolsExtension(customTools));
+			inlineExtensions.push(createCustomToolsExtension(omitPluginMcpNameShadows(customTools)));
 		}
 		if (!options.disableExtensionDiscovery) {
 			try {
@@ -4092,6 +4140,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 									if (!session) throw new Error("Terminal abort session is not initialized.");
 									return session.pendingToolExecutions(handle);
 								},
+								waitForRunSettlement: handle => {
+									if (!session) throw new Error("Image owner session is not initialized.");
+									return session.agent.resourceLedger.waitForSettlement(handle, { graceMs: null });
+								},
 							},
 							ensureProviderDaemon: options.ensureNotificationProviderDaemon,
 							runBtwTurn: async (question, signal) => {
@@ -4186,6 +4238,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 									if (!session) throw new Error("Terminal abort session is not initialized.");
 									return session.pendingToolExecutions(handle);
 								},
+								waitForRunSettlement: handle => {
+									if (!session) throw new Error("Image owner session is not initialized.");
+									return session.agent.resourceLedger.waitForSettlement(handle, { graceMs: null });
+								},
 							},
 						});
 					}
@@ -4198,18 +4254,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			});
 		}
 
-		// Extension modules are discovered at session startup from the canonical
-		// native locations (`<agentDir>/extensions`, `<cwd>/.gjc/extensions`),
-		// installed plugin bundles, the `extensions` setting, and explicitly
-		// supplied `additionalExtensionPaths`. `disableExtensionDiscovery` keeps its
-		// documented opt-out semantics: explicit paths still load, matching
+		// Extension modules are discovered at session startup from the user agent
+		// directory, installed plugin bundles, the user/global `extensions` setting,
+		// and explicitly supplied `additionalExtensionPaths`. A repository
+		// `.gjc/extensions` tree is not imported. `disableExtensionDiscovery` keeps
+		// its documented opt-out semantics: explicit paths still load, matching
 		// `cli/list-models.ts`. A caller-supplied `preloadedExtensions` result
 		// suppresses discovery entirely.
 		const explicitExtensionPaths = options.additionalExtensionPaths ?? [];
-		// The `extensions` setting is schema-typed as an array of paths, but a
-		// hand-edited config can hold an invalid shape; discovery must degrade to
-		// no extra paths instead of aborting startup for every session.
-		const extensionsSettingPaths = Array.isArray(settings.get("extensions")) ? settings.get("extensions") : [];
+		// The merged `extensions` value includes the project layer, which can name
+		// any module. Only the user/global list is imported. A hand-edited value
+		// with an invalid shape contributes no extra paths.
+		const globalExtensionPaths = settings.getGlobal("extensions");
+		const extensionsSettingPaths = Array.isArray(globalExtensionPaths) ? globalExtensionPaths : [];
 		// Discovery must never block session creation: a filesystem or plugin-registry
 		// failure degrades to the explicit paths and then to no extensions at all, and
 		// the failure stays observable in `extensionsResult.errors`.
@@ -4412,7 +4469,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					startupModelReference.id,
 					startupCredentialSelector,
 				);
-			const currentStartupModel = modelRegistry.find(startupModelReference.provider, startupModelReference.id);
+			const currentStartupModel = modelRegistry.find(
+				startupModelReference.provider,
+				startupModelReference.id,
+				credentialSessionId,
+			);
 			const providerMismatchRejectsTarget =
 				startupCredentialProviderMismatch &&
 				modelRegistry.requiresStoredLiteralCredentialCacheAdmission(
@@ -4437,7 +4498,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		// Resolve deferred --model pattern now that extension models are registered.
 		if (!model && options.modelPattern && !startupCredentialModelRejected) {
-			const availableModels = modelRegistry.getAll();
+			const availableModels = modelRegistry.getAll(credentialSessionId);
 			const matchPreferences = {
 				usageOrder: settings.getStorage()?.getModelUsageOrder(),
 			};
@@ -4479,7 +4540,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		) {
 			// Re-resolve the allowed set: extension factories above may have
 			// registered providers/models that weren't visible at startup.
-			const allowedFallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
+			const allowedFallbackCandidates = await resolveAllowedModels(
+				modelRegistry,
+				settings,
+				modelMatchPreferences,
+				credentialSessionId,
+			);
 			// Candidate order is not a quality signal: catalogs sort retired models
 			// ahead of current ones whenever their IDs carry older date suffixes, so
 			// an unconfigured install would otherwise start on a model its provider
@@ -4768,7 +4834,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// epoch additionally fences overlapping rebuilds, so a slower earlier
 			// pass cannot publish over a newer one.
 			const gjcPassEpoch = gjcRuntimeStore.beginPass();
-			toolContextStore.setToolNames(toolNames);
 			const promptTools = (() => {
 				const previousPromptMetadataModel = promptMetadataModel;
 				promptMetadataModel = candidateModel;
@@ -4888,6 +4953,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const requestedToolNameSet = new Set(normalizedRequested);
 		const effectiveDiscoveryMode = resolveEffectiveDiscoveryMode(settings, explicitMcpConfigPath);
 		const mcpDiscoveryEnabled = effectiveDiscoveryMode !== "off";
+		const discoveryDefaultServerNames = new Set(settings.get("mcp.discoveryDefaultServers") ?? []);
+		const deferConventionalMcpAutoload = mcpDiscoveryEnabled && settings.get("mcp.discoveryDeferAutoload");
 		const defaultInactiveToolNames = new Set(
 			registeredTools.filter(tool => tool.definition.defaultInactive).map(tool => tool.definition.name),
 		);
@@ -4906,7 +4973,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		let hasExplicitDiscoveredBuiltinToolSelection = false;
 		let explicitlyRequestedDiscoveredBuiltinToolNames: string[] = [];
 		if (mcpDiscoveryEnabled) {
-			const defaultServerNames = new Set(settings.get("mcp.discoveryDefaultServers") ?? []);
 			for (const tool of toolRegistry.values()) {
 				if (!isMCPBridgeTool(tool)) continue;
 				discoverableMCPToolNames.add(tool.name);
@@ -4914,22 +4980,37 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					explicitlyRequestedMCPToolNames.push(tool.name);
 				}
 				const serverName = (tool as AgentTool & { mcpServerName?: string }).mcpServerName;
-				if (serverName && defaultServerNames.has(serverName)) {
+				if (serverName && discoveryDefaultServerNames.has(serverName)) {
 					discoveryDefaultServerToolNames.push(tool.name);
 				}
 			}
 		}
-		const mandatoryMCPToolNameSet = new Set(pluginMcpToolNames);
-		const selectableExplicitMCPToolNames = explicitlyRequestedMCPToolNames.filter(
-			name => !mandatoryMCPToolNameSet.has(name),
+		// Mandatory names follow the plugin tools that survived registration.
+		// A colliding user tool keeps the normalized name and must stay selectable.
+		pluginMcpToolNames.splice(
+			0,
+			pluginMcpToolNames.length,
+			...retainPluginMcpMandatoryNames(customTools, pluginMcpToolNames),
 		);
+		const mandatoryMCPToolNameSet = new Set(pluginMcpToolNames);
+		const deferredMcpConnectPending = deferredExactMcpConfig !== undefined || deferredConventionalMcp !== undefined;
+		const requestedDeferredMCPToolNames =
+			deferredMcpConnectPending && hasExplicitToolNames
+				? options
+						.toolNames!.map(name => name.toLowerCase())
+						.filter(name => isMCPToolName(name) && !toolRegistry.has(name))
+				: [];
+		const selectableExplicitMCPToolNames = [
+			...new Set([
+				...explicitlyRequestedMCPToolNames.filter(name => !mandatoryMCPToolNameSet.has(name)),
+				...requestedDeferredMCPToolNames.filter(name => !mandatoryMCPToolNameSet.has(name)),
+			]),
+		];
 		let initialToolNames = [...initialRequestedActiveToolNames];
 		if (mcpDiscoveryEnabled) {
 			// A pending deferred MCP connect (exact or conventional) registers its
 			// tools after construction, so persisted selections must be preserved
 			// verbatim instead of being trimmed to names the registry currently has.
-			const deferredMcpConnectPending =
-				deferredExactMcpConfig !== undefined || deferredConventionalMcp !== undefined;
 			const restoredSelectedMCPToolNames = deferredMcpConnectPending
 				? existingSession.selectedMCPToolNames.filter(name => !mandatoryMCPToolNameSet.has(name))
 				: existingSession.selectedMCPToolNames.filter(
@@ -4947,8 +5028,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					...discoveryDefaultServerToolNames,
 					...(explicitMcpConfigPath !== undefined ? exactMcpToolNames : []),
 					// Conventional autoload servers are selected by default so their
-					// tools are exposed in sessions that enable MCP discovery mode.
-					...conventionalMcpToolNames,
+					// tools are exposed in sessions that enable MCP discovery mode,
+					// unless `mcp.discoveryDeferAutoload` keeps them behind tool search.
+					...(deferConventionalMcpAutoload ? [] : conventionalMcpToolNames),
 				]),
 			];
 			hasExplicitMCPToolSelection =
@@ -5428,6 +5510,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			taskDepth,
 			workflowGatePublication: isCanonicalSubSession ? "local" : "endpoint",
 			toolRegistry,
+			onToolNamesChanged: toolNames => toolContextStore.setToolNames(toolNames),
 			builtinToolIdentities,
 			workflowGateToolSession: toolSession,
 			transformContext,
@@ -5461,6 +5544,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			initialSelectedDiscoveredBuiltinToolNames,
 			initialBaselineDiscoveredBuiltinToolNames,
 			defaultSelectedMCPToolNames,
+			defaultSelectedConventionalMCPToolNames: deferConventionalMcpAutoload ? [] : conventionalMcpToolNames,
 			mandatoryMCPToolNames: pluginMcpToolNames,
 			persistInitialMCPToolSelection: !hasExistingSession && hasExplicitMCPToolSelection,
 			persistInitialDiscoveredBuiltinToolSelection: !hasExistingSession && hasExplicitDiscoveredBuiltinToolSelection,
@@ -5497,6 +5581,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// carried by the host replay ring through the internal runtime seam above.
 		if (autoroutingInactive) session.configWarnings.push(AUTOROUTING_INACTIVE_WARNING);
 		hasSession = true;
+		if (taskFacade) {
+			const unregisterTaskMoveListener = sessionManager.registerAfterMoveListener(move =>
+				taskFacade.invalidateForSessionMove(move.newCwd),
+			);
+			session.registerToolSessionCleanup(unregisterTaskMoveListener);
+		}
 		const cleanupOwnedManager = cleanupOwnedMcpManager;
 		const sessionOwnedMcpManager = ownsMcpManager ? mcpManager : undefined;
 		if (cleanupOwnedManager && cleanupOwnedMcpManagerOwner !== sessionOwnedMcpManager) {
@@ -5745,14 +5835,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						const previousNames = ownedMcpManagerToolNames;
 						const nextToolNames = nextTools.map(tool => tool.name);
 						const previousSet = new Set(previousNames);
-						const nextPluginToolNames = nextTools
-							.filter(tool => tool.mcpServerName && pluginServerNames.has(tool.mcpServerName))
-							.map(tool => tool.name);
+						const nextPluginToolNames = retainPluginMcpMandatoryNames(
+							nextTools,
+							nextTools
+								.filter(tool => tool.mcpServerName && pluginServerNames.has(tool.mcpServerName))
+								.map(tool => tool.name),
+						);
 						const nextConventionalToolNames = nextTools
 							.filter(tool => tool.mcpServerName && conventionalServerNames.has(tool.mcpServerName))
 							.map(tool => tool.name);
 						const nextMandatoryMcpToolNames = [
-							...pluginMcpToolNames.filter(name => !previousSet.has(name)),
+							...retainPluginMcpMandatoryNames(nextTools, pluginMcpToolNames).filter(
+								name => !previousSet.has(name),
+							),
 							...nextPluginToolNames,
 						];
 						const nextConventionalMcpToolNames = [
@@ -5775,8 +5870,27 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						try {
 							await session.replaceNamedCustomTools(previousNames, nextTools, {
 								mandatoryMCPToolNames: nextMandatoryMcpToolNames,
+								defaultSelectedConventionalMCPToolNames: deferConventionalMcpAutoload
+									? []
+									: nextConventionalToolNames,
 								activateNewTools: false,
+								persistMCPSelection: false,
 							});
+							const defaultMcpToolNamesToActivate =
+								deferConventionalMcpAutoload && !session.hasCommittedMCPToolSelectionAuthority()
+									? nextTools
+											.filter(
+												tool =>
+													tool.mcpServerName !== undefined &&
+													discoveryDefaultServerNames.has(tool.mcpServerName),
+											)
+											.map(tool => tool.name)
+									: [];
+							if (defaultMcpToolNamesToActivate.length > 0 && !session.hasCommittedMCPToolSelectionAuthority()) {
+								await session.activateDiscoveredTools(defaultMcpToolNamesToActivate, {
+									persistMCPSelection: false,
+								});
+							}
 						} catch (error) {
 							ownedMcpManagerToolNames = [...new Set([...previousNames, ...nextToolNames])];
 							throw error;
@@ -5865,17 +5979,37 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						const previousNames = inheritedMcpManagerToolNames;
 						const nextNames = snapshot.map(tool => tool.name);
 						const classifiedTools = classifyInheritedMcpToolNames(manager, snapshot);
+						const mandatoryPluginToolNames = retainPluginMcpMandatoryNames(
+							snapshot,
+							classifiedTools.pluginMcpToolNames,
+						);
 						try {
 							await session.replaceNamedCustomTools(previousNames, snapshot, {
-								mandatoryMCPToolNames: classifiedTools.pluginMcpToolNames,
+								mandatoryMCPToolNames: mandatoryPluginToolNames,
 								activateNewTools: false,
+								persistMCPSelection: false,
 							});
+							const defaultMcpToolNamesToActivate =
+								deferConventionalMcpAutoload && !session.hasCommittedMCPToolSelectionAuthority()
+									? snapshot
+											.filter(
+												tool =>
+													tool.mcpServerName !== undefined &&
+													discoveryDefaultServerNames.has(tool.mcpServerName),
+											)
+											.map(tool => tool.name)
+									: [];
+							if (defaultMcpToolNamesToActivate.length > 0 && !session.hasCommittedMCPToolSelectionAuthority()) {
+								await session.activateDiscoveredTools(defaultMcpToolNamesToActivate, {
+									persistMCPSelection: false,
+								});
+							}
 						} catch (error) {
 							inheritedMcpManagerToolNames = [...new Set([...previousNames, ...nextNames])];
 							throw error;
 						}
 						inheritedMcpManagerToolNames = nextNames;
-						pluginMcpToolNames.splice(0, pluginMcpToolNames.length, ...classifiedTools.pluginMcpToolNames);
+						pluginMcpToolNames.splice(0, pluginMcpToolNames.length, ...mandatoryPluginToolNames);
 						conventionalMcpToolNames.splice(
 							0,
 							conventionalMcpToolNames.length,
@@ -5964,11 +6098,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 								throw new ExactMcpToolNameCollisionError(collidingToolNames);
 							}
 							if (!cancelled && !session.isDisposed) {
-								await session.refreshMCPTools(resultTools);
-								if (
-									!session.isDisposed &&
-									(!mcpDiscoveryEnabled || !existingSession.hasPersistedMCPToolSelection)
-								) {
+								await session.refreshMCPTools(resultTools, { persistMCPSelection: false });
+								if (!session.isDisposed && (!mcpDiscoveryEnabled || !session.hasMCPToolSelectionAuthority())) {
 									await session.activateDiscoveredTools(toolNames);
 								}
 							}
@@ -5994,14 +6125,23 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 								// only re-activates a swapped tool that was already active; running it
 								// before this registration would therefore drop a persisted conventional
 								// MCP selection and persist the empty set.
-								await session.refreshMCPTools(resultTools);
+								await session.refreshMCPTools(resultTools, { persistMCPSelection: false });
 								wireOwnedMcpToolSync(resultTools);
 								wireOwnedMcpManagerLifecycle();
-								if (
-									!session.isDisposed &&
-									(!mcpDiscoveryEnabled || !existingSession.hasPersistedMCPToolSelection)
-								) {
-									await session.activateDiscoveredTools(resultTools.map(tool => tool.name));
+								const shouldActivateStartupMcpTools =
+									!mcpDiscoveryEnabled || !session.hasMCPToolSelectionAuthority();
+								if (!session.isDisposed && shouldActivateStartupMcpTools) {
+									await session.activateDiscoveredTools(
+										resultTools
+											.filter(
+												tool =>
+													!deferConventionalMcpAutoload ||
+													(tool.mcpServerName !== undefined &&
+														discoveryDefaultServerNames.has(tool.mcpServerName)),
+											)
+											.map(tool => tool.name),
+										deferConventionalMcpAutoload ? { persistMCPSelection: false } : undefined,
+									);
 								}
 							}
 							loadedToolCount = resultTools.length;