@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/sdk/session.ts

@@ -1,3 +1,5 @@
+import * as nodeFs from "node:fs";
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
 	Agent,
@@ -33,6 +35,7 @@ import {
 	postmortem,
 	prompt,
 	Snowflake,
+	setProjectDir,
 } from "@gajae-code/utils";
 import {
 	createAppendOnlyContextManager,
@@ -46,9 +49,10 @@ import {
 	isBackgroundJobSupportEnabled,
 	jobElapsedMs,
 } from "../async";
-import { loadCapability } from "../capability";
+import { loadCapability, reset as resetCapabilities } from "../capability";
 import { type Rule, ruleCapability, setActiveRules } from "../capability/rule";
 import type { SourceMeta } from "../capability/types";
+import { AUTOROUTING_INACTIVE_WARNING } from "../config/autorouting-contract";
 import { resolveModelProfileName } from "../config/model-profile-contract";
 import { resolveProfileBindings } from "../config/model-profiles";
 import { kNoAuth, ModelRegistry } from "../config/model-registry";
@@ -64,12 +68,15 @@ import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate
 import { Settings, type SkillsSettings } from "../config/settings";
 import { resolveEagerTaskDelegation } from "../config/task-delegation";
 import { CursorExecHandlers } from "../cursor";
+import { EditTool } from "../edit";
 import type { BashRestrictionProfile } from "../tools/bash-allowed-prefixes";
+import { SearchTool } from "../tools/search";
 import "../discovery";
 import { resolveConfigValue } from "../config/resolve-config-value";
 import { getEmbeddedDefaultGjcSkills } from "../defaults/gjc-defaults";
 import { BUNDLED_GROK_BUILD_EXTENSION_ID, getBundledGrokBuildExtensionFactory } from "../defaults/gjc-grok-cli";
 import { initializeWithSettings } from "../discovery";
+import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../discovery/helpers";
 import { TtsrManager } from "../export/ttsr";
 import type { CustomCommandsLoadResult, LoadedCustomCommand } from "../extensibility/custom-commands";
 import type { CustomTool, CustomToolContext, CustomToolSessionEvent } from "../extensibility/custom-tools/types";
@@ -109,6 +116,7 @@ import type { HindsightSessionState } from "../hindsight/state";
 import { normalizePluginHook } from "../hooks/normalize";
 import { initializeLocalRoot, LocalProtocolHandler, type LocalProtocolOptions } from "../internal-urls";
 import type { LspStartupServerInfo } from "../lsp";
+import { shutdownAll as shutdownAllLspClients } from "../lsp/client";
 import btwUserPrompt from "../prompts/system/btw-user.md" with { type: "text" };
 import asyncResultTemplate from "../prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
@@ -129,9 +137,9 @@ import {
 import { createReconciliationStore, type ReconciliationStore } from "../sdk/bus/reconciliation-store";
 import { NotificationSessionController } from "../sdk/bus/session-control";
 import { shouldHostSdk } from "../sdk/host";
+import { markAutoroutingInactive } from "../sdk/host/internal-autorouting-state";
 import { createSdkSessionRuntimeExtension, registerSdkOnlyNotificationCommand } from "../sdk/host/session-runtime";
 import { createSdkWebSocketTransport } from "../sdk/host/websocket-transport";
-
 import type { SecretObfuscator } from "../secrets";
 import { AgentSession, type ForkContextSeed } from "../session/agent-session";
 import { AuthBrokerClient, AuthStorage, RemoteAuthCredentialStore } from "../session/auth-storage";
@@ -161,6 +169,8 @@ import { AgentOutputManager } from "../task/output-manager";
 import { parseThinkingLevel, resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import { isMCPBridgeTool, selectRestorableDiscoveredBuiltinToolNames } from "../tool-discovery/tool-index";
 import {
+	type AutomationToolName,
+	type AutomationTools,
 	BUILTIN_TOOL_DESCRIPTORS,
 	BUILTIN_TOOLS,
 	computeEssentialBuiltinNames,
@@ -183,6 +193,8 @@ import {
 	type SdkStartupCapability,
 } from "./startup-capability";
 
+export type { AutomationToolName, AutomationTools } from "../tools";
+
 type AsyncResultEntry = {
 	jobId: string;
 	generation: string;
@@ -211,6 +223,14 @@ type McpNotificationEntry = {
 	uri: string;
 };
 
+/** Capture the cursor edit grant before the model-facing edit entry is removed. */
+export function captureCursorEditTool<T>(
+	toolRegistry: ReadonlyMap<string, unknown>,
+	createReplaceTool: () => T,
+): T | undefined {
+	return toolRegistry.has("edit") ? createReplaceTool() : undefined;
+}
+
 function buildAsyncResultBatchMessage(entries: AsyncResultEntry[]): CustomMessage<AsyncResultDetails> | null {
 	if (entries.length === 0) return null;
 	// Partition denied owned-completion entries out ENTIRELY before batch
@@ -440,6 +460,13 @@ export interface CreateAgentSessionOptions {
 
 	/** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
 	customTools?: (CustomTool | ToolDefinition)[];
+	/**
+	 * Host-owned implementations for the built-in `browser` and `computer`
+	 * surfaces. These are materialized as built-ins, retain built-in provenance
+	 * and activation behavior, and receive cancellation through AgentTool's
+	 * AbortSignal. A matching custom or extension tool is rejected.
+	 */
+	automationTools?: AutomationTools;
 	/** Explicit parent/phase used to load active GJC sub-skill tools for this session. */
 	gjcSubskillToolContext?: { parent: string; phase: string; sessionId?: string; cwd?: string };
 	/** Inline extensions (merged with discovery). */
@@ -1246,7 +1273,31 @@ function findDeferredExactMcpToolNameCollisions(
 	return [...collisions];
 }
 
+const AUTOMATION_TOOL_NAMES = new Set<AutomationToolName>(["browser", "computer"]);
+
+function validateAutomationTools(options: CreateAgentSessionOptions): AutomationTools {
+	const automationTools = options.automationTools ?? {};
+	const entries = Object.entries(automationTools);
+	for (const [name, tool] of entries) {
+		if (!AUTOMATION_TOOL_NAMES.has(name as AutomationToolName)) {
+			throw new Error(`Unsupported SDK automation tool name: ${name}`);
+		}
+		if (!tool || tool.name !== name) {
+			throw new Error(`SDK automation tool ${name} must expose the built-in name ${JSON.stringify(name)}`);
+		}
+	}
+	const externalNames = new Set(entries.map(([name]) => name));
+	const collisions = [
+		...new Set((options.customTools ?? []).map(tool => tool.name).filter(name => externalNames.has(name))),
+	];
+	if (collisions.length > 0) {
+		throw new Error(`SDK automation tools cannot collide with custom tools: ${collisions.join(", ")}`);
+	}
+	return automationTools;
+}
+
 export async function createAgentSession(options: CreateAgentSessionOptions = {}): Promise<CreateAgentSessionResult> {
+	const automationTools = validateAutomationTools(options);
 	const lifecycleStartupCapability = (
 		options as CreateAgentSessionOptions & { [lifecycleStartupCapabilityOption]?: SdkStartupCapability }
 	)[lifecycleStartupCapabilityOption];
@@ -1302,7 +1353,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 	let agent: Agent;
 	let session!: AgentSession;
+	let sessionManager!: SessionManager;
 	let hasSession = false;
+	let processCwdClaimed = false;
 	let hasRegistered = false;
 	let asyncJobManager: AsyncJobManager | undefined;
 	let asyncJobManagerAdmitted = false;
@@ -1363,7 +1416,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			authStorage.setSessionCredentialSelector(scopeId, provider, selector);
 		};
 		const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
-		const runtimeServices = createOptionalRuntimeServices(settings, options.runtimeServices, { cwd });
+		const autoroutingInactive =
+			settings.get("task.autorouting.enabled") === true && !settings.getEffectiveAutorouting().active;
+		// Cwd-derived runtime state must follow a rescope (`move_session`, `/move`),
+		// so services resolve the LIVE session cwd per activation instead of
+		// capturing the launch root. Before the manager exists the launch cwd is the
+		// only truth available, and it is also the manager's initial cwd.
+		let liveSessionManager: SessionManager | undefined;
+		const getLiveCwd = (): string => liveSessionManager?.getCwd() ?? cwd;
+		const runtimeServices = createOptionalRuntimeServices(settings, options.runtimeServices, { cwd: getLiveCwd });
 		modelRegistry.applyConfiguredModelBindings(settings);
 		logger.time("initializeWithSettings", initializeWithSettings, settings);
 		if (!options.modelRegistry) {
@@ -1420,11 +1481,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 		applyConfiguredSearchTimeout(settings);
 
-		const sessionManager =
+		sessionManager =
 			options.sessionManager ??
 			(await logger.time("sessionManager", async () => {
 				return SessionManager.create(cwd, SessionManager.managedDestination(cwd, agentDir));
 			}));
+		liveSessionManager = sessionManager;
 		const logicalSessionId = sessionManager.getSessionId();
 		// Fork-context seeds carry conversation content only, never provider identity:
 		// a shared continuity id would make concurrent subagents present the same
@@ -1866,7 +1928,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			contextFilesResultPromise,
 			raceWithDeadline("buildWorkspaceTree", workspaceTreePromise),
 		]);
-		const contextFiles = contextFilesResult.contextFiles;
+		// Mutable: a rescope re-discovers cwd-derived project instructions so the
+		// model is never shown the launcher root's AGENTS.md alongside the new cwd.
+		let contextFiles = contextFilesResult.contextFiles;
+		let liveWorkspaceTree: WorkspaceTree | undefined = resolvedWorkspaceTree;
 		const discoveredContextFileWarnings = contextFilesResult.warnings;
 
 		const backgroundJobsEnabled = isBackgroundJobSupportEnabled(settings);
@@ -1974,6 +2039,168 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (model) return formatModelString(model);
 			return undefined;
 		};
+		let mcpManager: MCPManager | undefined = options.mcpManager;
+		let ownsMcpManager = false;
+		const cwdCapturingToolNames: string[] = [];
+		const notificationDebounceTimers = new Map<string, Timer>();
+		const wireMcpManagerCallbacks = (manager: MCPManager): void => {
+			manager.setOnPromptsChanged(serverName => {
+				const promptCommands = buildMCPPromptCommands(manager);
+				session.setMCPPromptCommands(promptCommands);
+				logger.debug("MCP prompt commands refreshed", { path: `mcp:${serverName}` });
+			});
+			manager.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);
+						if (!settings.get("mcp.notifications")) return;
+						session.yieldQueue.enqueue<McpNotificationEntry>("mcp-notification", { serverName, uri });
+					}, debounceMs),
+				);
+			});
+		};
+		const rebindCwdCapturingAuthority = async (to: string): Promise<void> => {
+			if (!session) return;
+			if (options.mcpManager && !ownsMcpManager) {
+				throw new Error(
+					"Cannot rescope a session with caller-owned MCP authority; recreate the session at the target cwd.",
+				);
+			}
+			await session.refreshGjcSubskillTools();
+			const previousCwdCapturing = [...cwdCapturingToolNames];
+			const nextCwdCapturing: string[] = [];
+			const nextCustomTools: CustomTool[] = [];
+			try {
+				const declarations = await getGjcPluginToolDeclarations(to);
+				const pluginToolResult = await loadAlwaysOnPluginTools({
+					cwd: to,
+					reservedToolNames: session.getAllToolNames().filter(name => !previousCwdCapturing.includes(name)),
+					declarations,
+				});
+				nextCustomTools.push(...pluginToolResult.tools);
+				nextCwdCapturing.push(...pluginToolResult.tools.map(tool => tool.name));
+			} catch (error) {
+				logger.warn("Failed to reload always-on plugin tools after session rescope", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+			if (!options.mcpManager && explicitMcpConfigPath === undefined) {
+				const previousManager = mcpManager;
+				if (previousManager) await previousManager.disconnectAll().catch(() => {});
+				pluginMcpToolNames.length = 0;
+				conventionalMcpToolNames.length = 0;
+				let nextManager: MCPManager | undefined;
+				try {
+					const loaded = await loadAllMCPConfigs(to, {
+						agentDir,
+						enableProjectConfig: settings.has("mcp.enableProjectConfig")
+							? settings.get("mcp.enableProjectConfig")
+							: true,
+						autoloadOnly: true,
+						nativeOnly: true,
+					});
+					const { configs: pluginConfigs } = await buildPluginMcpConfigs({ cwd: to });
+					const pluginNames = new Set(Object.keys(pluginConfigs));
+					const mergedConfigs = { ...loaded.configs, ...pluginConfigs };
+					const mergedSources = {
+						...loaded.sources,
+						...Object.fromEntries(
+							Object.keys(pluginConfigs).map(name => [
+								name,
+								{ provider: "gjc-plugins", providerName: "GJC plugin bundle", level: "project" as const },
+							]),
+						),
+					};
+					if (Object.keys(mergedConfigs).length > 0) {
+						nextManager = new MCPManager(to, null, { sharedPoolIdleMs: settings.get("mcp.sharedPoolIdleMs") });
+						nextManager.setAuthStorage(authStorage);
+						wireMcpManagerCallbacks(nextManager);
+						const result = await nextManager.connectServers(mergedConfigs, mergedSources as never);
+						nextCustomTools.push(...(result.tools as CustomTool[]));
+						nextCwdCapturing.push(...result.tools.map(tool => tool.name));
+						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);
+						}
+					}
+				} catch (error) {
+					logger.warn("Failed to recreate MCP authority after session rescope", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+				mcpManager = nextManager;
+				ownsMcpManager = Boolean(nextManager);
+				await session.replaceOwnedMcpManager(nextManager);
+				await session.refreshMCPTools((nextManager?.getTools() ?? []) as CustomTool[]);
+			}
+			cwdCapturingToolNames.length = 0;
+			cwdCapturingToolNames.push(...nextCwdCapturing);
+			await session.replaceNamedCustomTools(
+				previousCwdCapturing.filter(name => !nextCustomTools.some(tool => tool.name === name)),
+				nextCustomTools,
+			);
+		};
+
+		/**
+		 * Re-discover the cwd-derived read-only state the model is shown after a
+		 * committed rescope: project instructions, skills, and the workspace tree.
+		 * Without this the volatile message pairs the NEW cwd with the launch
+		 * root's AGENTS.md and tree, and subagents inherit the same mismatch.
+		 */
+		const applyRescopedReadState = async (to: string): Promise<void> => {
+			try {
+				const rediscovered = await loadContextFilesResultInternal({ cwd: to });
+				contextFiles = rediscovered.contextFiles;
+			} catch (error) {
+				logger.warn("Failed to re-discover context files after session rescope", {
+					error: safeErrorForLog(error),
+				});
+			}
+			if (options.skills === undefined && settings.get("skills.enabled")) {
+				try {
+					const reloaded = await loadSkills({
+						...settings.getGroup("skills"),
+						cwd: to,
+						disabledExtensions: settings.get("disabledExtensions"),
+					});
+					skills = withEmbeddedDefaultGjcSkills(reloaded.skills);
+					if (!options.parentTaskPrefix) setActiveSkills(skills);
+					await session?.replaceSkills(skills);
+				} catch (error) {
+					logger.warn("Failed to reload skills after session rescope", { error: safeErrorForLog(error) });
+				}
+			}
+			// The launch-bound tree is retired immediately: a stale root-scoped tree is
+			// worse than none, and the next turn re-scans at the new cwd.
+			liveWorkspaceTree = undefined;
+			workspaceTreePromise = Promise.resolve({
+				rootPath: to,
+				rendered: "",
+				truncated: false,
+				totalLines: 0,
+				agentsMdFiles: [],
+			});
+			workspaceTreePromise.catch(() => {});
+			try {
+				session?.retireWorkspaceTreeForRescope();
+				await session?.refreshBaseSystemPrompt();
+			} catch (error) {
+				logger.warn("Committed session rescope could not refresh the post-move prompt", {
+					error: safeErrorForLog(error),
+					cwd: to,
+				});
+			}
+		};
+
 		const toolSession: ToolSession = {
 			get cwd() {
 				return sessionManager.getCwd();
@@ -1988,14 +2215,248 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return !requestedToolNames || requestedToolNames.includes("edit");
 			},
 			skipPythonPreflight: options.skipPythonPreflight,
-			contextFiles,
-			workspaceTree: resolvedWorkspaceTree,
-			skills,
+			// Getters, not snapshots: subagents launched after a rescope inherit the
+			// CURRENT cwd's context files, skills, and tree rather than the launch
+			// root's, which would otherwise pair the new cwd with retired instructions.
+			get contextFiles() {
+				return contextFiles;
+			},
+			get workspaceTree() {
+				return liveWorkspaceTree;
+			},
+			get skills() {
+				return skills;
+			},
 			eventBus,
 			outputSchema: options.outputSchema,
 			requireYieldTool: options.requireYieldTool,
 			taskDepth: options.taskDepth ?? 0,
 			currentAgentType: options.currentAgentType,
+			// Agent-invokable session rescope (#4629). Provided only where
+			// relocation is safe: canonical top-level sessions (the same
+			// isCanonicalSubSession predicate that gates SDK hosting — taskDepth 0,
+			// no parentTaskPrefix, no currentAgentType) without a restricted bash
+			// surface. Runs the same sequence as the text/ACP `/move` handler so
+			// tool path resolution, the bash default cwd, and plugin caches follow
+			// the move. Unlike the user-driven `/move`, the model-invoked accessor
+			// is bound to at most one successful move per session, rejects
+			// re-entrant calls, refuses to move while a workflow skill is active
+			// (its cwd-local state and guards stay pinned to the launch root), and
+			// only narrows: the canonical target must be a strict descendant of
+			// the canonical current cwd, so an injected or speculative call cannot
+			// widen the session's tool/write scope to a parent, a sibling project,
+			// or an arbitrary absolute path.
+			...(!isCanonicalSubSession &&
+			!options.bashRestrictionProfile &&
+			(options.bashAllowedPrefixes ?? []).length === 0 &&
+			!options.mcpManager &&
+			explicitMcpConfigPath === undefined &&
+			options.workspaceTree === undefined
+				? {
+						rescopeSessionCwd: (() => {
+							let moveConsumed = false;
+							return async (target: string): Promise<{ from: string; to: string }> => {
+								if (moveConsumed) {
+									throw new Error(
+										"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.",
+									);
+								}
+								return sessionManager.runExclusiveCwdTransition(async () => {
+									if (moveConsumed) {
+										throw new Error(
+											"This session has already been rescoped; only one agent-invoked move is allowed per session.",
+										);
+									}
+									if (session?.getEffectiveActiveWorkflowSkillState()) {
+										throw new Error(
+											"A workflow skill became active while waiting for the cwd transition; finish or exit it before rescoping.",
+										);
+									}
+									const from = sessionManager.getCwd();
+									const resolvedPath = path.resolve(from, target);
+									let canonicalFrom: string;
+									let canonicalTarget: string;
+									try {
+										canonicalFrom = await fs.realpath(from);
+										canonicalTarget = await fs.realpath(resolvedPath);
+									} catch {
+										throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
+									}
+									if (!(await fs.stat(canonicalTarget)).isDirectory()) {
+										throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
+									}
+									const relative = path.relative(canonicalFrom, canonicalTarget);
+									if (relative === "") {
+										throw new Error(
+											`Target ${canonicalTarget} is the current session directory; nothing to move.`,
+										);
+									}
+									if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+										throw new Error(
+											`Refusing to rescope outside the current session directory: ${canonicalTarget} is not within ${canonicalFrom}. move_session only narrows the session scope; ask the user to restart or /move for a broader relocation.`,
+										);
+									}
+									let targetHandle: nodeFs.promises.FileHandle | undefined;
+									let expectedIdentity: { dev: bigint; ino: bigint };
+									try {
+										targetHandle = await SessionManager.openNoFollowDirectory(canonicalTarget);
+										const opened = await targetHandle.stat({ bigint: true });
+										if (!opened.isDirectory()) {
+											throw new Error(`Directory does not exist or is not a directory: ${resolvedPath}`);
+										}
+										expectedIdentity = { dev: opened.dev, ino: opened.ino };
+										await fs.access(canonicalTarget, nodeFs.constants.R_OK | nodeFs.constants.X_OK);
+									} catch (error) {
+										await targetHandle?.close().catch(() => {});
+										if (error instanceof Error && error.message.startsWith("Directory does not exist")) {
+											throw error;
+										}
+										throw new Error(
+											`Directory identity or access unavailable: ${canonicalTarget}${
+												error instanceof Error ? ` (${error.message})` : ""
+											}`,
+										);
+									}
+									// Process-cwd authority is an explicit claim, never inferred from
+									// `process.cwd() === from`: sibling sessions launched at the same
+									// root both satisfy that, so acting on it would chdir the process
+									// and clear process-global caches underneath the sibling.
+									const ownsProcessCwd = SessionManager.isProcessCwdOwner(sessionManager);
+									const restoreLaunchRoot = async (failure: unknown): Promise<never> => {
+										const restoreErrors: Error[] = [];
+										if (ownsProcessCwd) {
+											try {
+												setProjectDir(canonicalFrom);
+												if (path.resolve(process.cwd()) !== path.resolve(canonicalFrom)) {
+													throw new Error("Process cwd did not restore to the launch root.");
+												}
+											} catch (error) {
+												restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
+											}
+											try {
+												resetCapabilities();
+												const restoreRegistry = await resolveActiveProjectRegistryPath(canonicalFrom).catch(
+													() => undefined,
+												);
+												clearPluginRootsAndCaches(restoreRegistry ? [restoreRegistry] : undefined);
+											} catch (error) {
+												restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
+											}
+										}
+										try {
+											await rebindCwdCapturingAuthority(canonicalFrom);
+										} catch (error) {
+											restoreErrors.push(error instanceof Error ? error : new Error(String(error)));
+										}
+										if (restoreErrors.length > 0) {
+											throw new AggregateError(
+												restoreErrors,
+												"Failed to restore launch-root rescope authority.",
+												{
+													cause: failure,
+												},
+											);
+										}
+										throw failure;
+									};
+									try {
+										// Every fallible step that the moved session depends on runs
+										// BEFORE the session-file commit, so a failure here leaves the
+										// session exactly where it was and the tool call is a clean
+										// rejection rather than a half-moved session.
+										if (ownsProcessCwd) {
+											setProjectDir(canonicalTarget);
+											try {
+												// `setProjectDir` chdirs a NAME. Confirm the process actually
+												// landed on the pinned directory, so a path replaced after
+												// the name checks cannot escape the validated descendant.
+												await SessionManager.assertProcessCwdIdentity(expectedIdentity);
+											} catch (error) {
+												setProjectDir(canonicalFrom);
+												throw error;
+											}
+										}
+										let rescopeFailure: unknown;
+										try {
+											if (ownsProcessCwd) {
+												resetCapabilities();
+												const projectRegistry = await resolveActiveProjectRegistryPath(canonicalTarget);
+												clearPluginRootsAndCaches(projectRegistry ? [projectRegistry] : undefined);
+											}
+											// Plugin/MCP/Python authority must be rebound successfully
+											// before committing; swallowing a failure here is what leaves
+											// a moved session holding launch-root tool authority.
+											await rebindCwdCapturingAuthority(canonicalTarget);
+										} catch (error) {
+											rescopeFailure = error;
+										}
+										if (rescopeFailure !== undefined) {
+											await restoreLaunchRoot(rescopeFailure);
+										}
+										try {
+											await sessionManager.flush();
+											// Commit last: `moveTo` re-validates the pinned identity through
+											// the still-open handle at the state-changing boundary.
+											await sessionManager.moveTo(canonicalTarget, {
+												expectedIdentity,
+												targetHandle,
+											});
+										} catch (error) {
+											const committedCwd = sessionManager.getCwd();
+											const stayedAtLaunchRoot = path.resolve(committedCwd) === path.resolve(from);
+											if (stayedAtLaunchRoot) await restoreLaunchRoot(error);
+											// SessionManager can publish the durable move before a later metadata
+											// write fails. Treat that state as committed rather than reporting a
+											// rejection after the session has moved.
+											moveConsumed = true;
+											logger.warn("Session rescope committed before finalization failed", {
+												error: safeErrorForLog(error),
+												cwd: committedCwd,
+											});
+										}
+										moveConsumed = true;
+										if (ownsProcessCwd) {
+											try {
+												await shutdownAllLspClients();
+											} catch (error) {
+												logger.warn("Failed to reset launch-root LSP clients after session rescope", {
+													error: safeErrorForLog(error),
+												});
+											}
+										}
+										// Cwd-derived read-only state the prompt and subagents consume.
+										// Best-effort by design: the move is committed, and a failed
+										// re-discovery must not present a committed move as a failure.
+										await applyRescopedReadState(sessionManager.getCwd());
+										try {
+											await session?.refreshSshTool({ activateIfAvailable: true });
+										} catch (error) {
+											// Non-fatal: the session has moved; the SSH tool refreshes
+											// on its next activation attempt.
+											logger.warn("Committed session rescope could not refresh the SSH tool", {
+												error: safeErrorForLog(error),
+												cwd: sessionManager.getCwd(),
+											});
+										}
+										return { from, to: sessionManager.getCwd() };
+									} finally {
+										await targetHandle.close().catch(() => {});
+									}
+								});
+							};
+						})(),
+					}
+				: {}),
 			getSessionFile: () => sessionManager.getSessionFile() ?? null,
 			getEvalKernelOwnerId: () => evalKernelOwnerId,
 			assertEvalExecutionAllowed: () => session?.assertEvalExecutionAllowed(),
@@ -2123,6 +2584,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (!options.parentTaskPrefix) {
 			setActiveSkills(skills);
 			setActiveRules([...rulebookRules, ...alwaysApplyRules]);
+			// Claim process-cwd authority for the FIRST top-level session launched at
+			// the process cwd. A later sibling launched at the same root does not get
+			// the claim, so its rescope leaves process-global state (chdir,
+			// capabilities, plugin caches, browser tab cwd) untouched.
+			if (!isCanonicalSubSession && path.resolve(process.cwd()) === path.resolve(sessionManager.getCwd())) {
+				processCwdClaimed = SessionManager.claimProcessCwdOwnership(sessionManager);
+			}
 			if (asyncJobManager) {
 				// Register under the session endpoint so concurrent sessions'
 				// owned work settles in the correct manager (review thread P1).
@@ -2164,7 +2632,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		);
 
 		// Create built-in tools (already wrapped with meta notice formatting)
-		const builtinTools = await logger.time("createAllTools", createTools, toolSession, options.toolNames);
+		const builtinTools = await logger.time(
+			"createAllTools",
+			createTools,
+			toolSession,
+			options.toolNames,
+			automationTools,
+		);
 
 		// A top-level session loads MCP tools from three bounded surfaces: a
 		// caller-supplied exact config (`--mcp-config`), conventional native
@@ -2172,8 +2646,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// written by `gjc mcp add`; disabled by `--no-mcp`), and plugin-bundle
 		// MCP servers (created below after `customTools` is populated). Existing
 		// caller-supplied managers remain available for legacy in-process callers.
-		let mcpManager: MCPManager | undefined = options.mcpManager;
-		let ownsMcpManager = false;
 		const customTools: CustomTool[] = [];
 		const exactMcpToolNames: string[] = [];
 		const pluginMcpToolNames: string[] = [];
@@ -2263,7 +2735,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				reservedToolNames: [...getReservedSubskillToolNames(), ...customTools.map(tool => tool.name)],
 				declarations: gjcToolDeclarations,
 			});
-			if (pluginToolResult.tools.length > 0) customTools.push(...pluginToolResult.tools);
+			if (pluginToolResult.tools.length > 0) {
+				customTools.push(...pluginToolResult.tools);
+				cwdCapturingToolNames.push(...pluginToolResult.tools.map(tool => tool.name));
+			}
 			for (const q of pluginToolResult.quarantine) {
 				gjcFindings.add({ identity: q.identity, surfaceId: q.surfaceId, code: q.code, message: q.message });
 				logger.warn("Quarantined GJC plugin surface", { plugin: q.plugin, surface: q.surfaceId, code: q.code });
@@ -2293,6 +2768,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				const resultTools = result.tools as CustomTool[];
 				exactMcpToolNames.push(...resultTools.map(tool => tool.name));
 				customTools.push(...resultTools);
+				cwdCapturingToolNames.push(...resultTools.map(tool => tool.name));
 				if (result.errors.size > 0 || result.tools.length === 0) {
 					logger.warn("MCP tools could not be loaded.");
 				}
@@ -2314,6 +2790,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (options.enableMcpAutoload !== false) {
 				try {
 					const loaded = await loadAllMCPConfigs(cwd, {
+						// User scope is this session's agent directory, the same file
+						// `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
@@ -2383,6 +2863,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 							mcpManager = owned;
 							ownsMcpManager = true;
 							customTools.push(...(result.tools as CustomTool[]));
+							cwdCapturingToolNames.push(...result.tools.map(tool => tool.name));
 							const connectedPluginNames = new Set(
 								result.connectedServers.filter(name => pluginNames.has(name)),
 							);
@@ -2546,6 +3027,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (notificationsExtensionEligible || sdkHostEligible) {
 			inlineExtensions.push(async api => {
 				try {
+					if (autoroutingInactive) markAutoroutingInactive(api);
 					if (lifecycleStartupCapability) attachLifecycleStartupCapability(api, lifecycleStartupCapability);
 					if (lifecycleStartupCapability && process.env.GJC_SDK_TEST_FACTORY_FAILURE === cwd)
 						throw new Error(process.env.GJC_SDK_TEST_FACTORY_SECRET ?? "Lifecycle factory test failure.");
@@ -2553,6 +3035,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						const createNotificationsExtension = await notificationAdapterService.get("session-extension");
 						createNotificationsExtension(api, {
 							settings,
+
 							controller: notificationSessionController,
 							spawnedByGjc,
 							sdkHostModeSupported: options.sdkHostModeSupported,
@@ -2741,14 +3224,23 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const matchPreferences = {
 				usageOrder: settings.getStorage()?.getModelUsageOrder(),
 			};
-			const { model: resolved } = parseModelPattern(options.modelPattern, availableModels, matchPreferences, {
-				modelRegistry,
-				sessionId: logicalSessionId,
-				credentialSessionId,
-			});
+			const { model: resolved, thinkingLevel: resolvedThinkingLevel } = parseModelPattern(
+				options.modelPattern,
+				availableModels,
+				matchPreferences,
+				{
+					modelRegistry,
+					sessionId: logicalSessionId,
+					credentialSessionId,
+				},
+			);
 			if (resolved) {
 				model = resolved;
 				modelFallbackMessage = undefined;
+				if (resolvedThinkingLevel !== undefined) {
+					thinkingLevel = resolvedThinkingLevel;
+					thinkingLevelFromSchemaDefault = false;
+				}
 				if (thinkingLevelFromSchemaDefault && resolved.thinking?.defaultLevel !== undefined) {
 					thinkingLevel = resolved.thinking.defaultLevel;
 					thinkingLevelFromSchemaDefault = false;
@@ -2845,9 +3337,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			model: agent.state.model,
 			isIdle: () => !session.isStreaming,
 			hasQueuedMessages: () => session.queuedMessageCount > 0,
-			abort: () => {
-				session.abort();
-			},
+			abort: () => session.abort(),
 			settings,
 		});
 		const toolContextStore = new ToolContextStore(getSessionContext);
@@ -2884,6 +3374,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				.filter(isCustomTool)
 				.map(tool => CustomToolAdapter.wrap(tool, customToolContext));
 		}
+		const automationToolNames = new Set(Object.keys(automationTools));
+		const automationToolCollisions = [
+			...new Set(wrappedExtensionTools.map(tool => tool.name).filter(name => automationToolNames.has(name))),
+		];
+		if (automationToolCollisions.length > 0) {
+			throw new Error(
+				`SDK automation tools cannot collide with extension or MCP tools: ${automationToolCollisions.join(", ")}`,
+			);
+		}
 
 		// All built-in tools are active (conditional tools like git/ask return null from factory if disabled)
 		const toolRegistry = new Map<string, Tool>();
@@ -2931,6 +3430,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				toolRegistry.set(tool.name, wrapped);
 			}
 		}
+		const rawCursorReplaceEditTool = captureCursorEditTool(toolRegistry, () => new EditTool(toolSession, "replace"));
+		const cursorReplaceEditTool: AgentTool | undefined = rawCursorReplaceEditTool
+			? extensionRunner
+				? (new ExtensionToolWrapper(rawCursorReplaceEditTool, extensionRunner) as AgentTool)
+				: (rawCursorReplaceEditTool as AgentTool)
+			: undefined;
 		if (model?.provider === "cursor") {
 			toolRegistry.delete("edit");
 			builtinCandidateTools = builtinCandidateTools.filter(tool => tool.name !== "edit");
@@ -2978,6 +3483,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		const cursorExecHandlers = new CursorExecHandlers({
 			cwd,
 			tools: toolRegistry,
+			getEditReplaceTool: () => cursorReplaceEditTool,
+			createSearchTool: options => {
+				if (!toolRegistry.has("search")) return undefined;
+				const search = new SearchTool(toolSession, options);
+				return extensionRunner
+					? (new ExtensionToolWrapper(search as unknown as AgentTool, extensionRunner) as AgentTool)
+					: (search as unknown as AgentTool);
+			},
 			getToolContext: () => toolContextStore.getContext(),
 			emitEvent: event => cursorEventEmitter?.(event),
 			createEventEmitter: () => agent.createExternalEventEmitterForCurrentRun(),
@@ -3053,7 +3566,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const appendPrompt: string | undefined = memoryInstructions ?? undefined;
 			let pluginSystemAppendices = "";
 			try {
-				pluginSystemAppendices = await renderAlwaysOnSystemAppendices({ cwd });
+				pluginSystemAppendices = await renderAlwaysOnSystemAppendices({ cwd: getLiveCwd() });
 			} catch (error) {
 				gjcProducersComplete = false;
 				logger.warn("Failed to render GJC plugin system appendices", { error: safeErrorForLog(error) });
@@ -3067,7 +3580,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// `unavailable` rather than a stale generation.
 			if (gjcProducersComplete) gjcRuntimeStore.publish(gjcFindings.snapshot(), gjcPassEpoch);
 			const defaultPrompt = await buildSystemPromptInternal({
-				cwd,
+				// Live cwd: the prompt is rebuilt after a rescope, and describing the
+				// retired launcher root there is what makes the model pick wrong paths.
+				cwd: getLiveCwd(),
 				skills,
 				contextFiles,
 				tools: promptTools,
@@ -3600,7 +4115,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			convertToLlm: convertToLlmFinal,
 			rebuildSystemPrompt,
 			getMcpServerInstructions:
-				explicitMcpConfigPath === undefined && mcpManager ? () => mcpManager.getServerInstructions() : undefined,
+				explicitMcpConfigPath === undefined ? () => mcpManager?.getServerInstructions() : undefined,
 			workspaceTree: options.workspaceTree ?? (workspaceTreeMode === "eager" ? resolvedWorkspaceTree : undefined),
 			workspaceTreeService: options.workspaceTree ? undefined : runtimeServices.workspaceTree,
 			networkPrewarmService: runtimeServices.networkPrewarm,
@@ -3640,6 +4155,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		});
 		session.setActiveModelProfile(startupActiveModelProfile);
 		session.configWarnings.push(...contextFileWarnings);
+		// Determined once, here, where settings are already available. Keep the
+		// durable warning for interactive and print consumers; ACP delivery is
+		// carried by the host replay ring through the internal runtime seam above.
+		if (autoroutingInactive) session.configWarnings.push(AUTOROUTING_INACTIVE_WARNING);
 		hasSession = true;
 		const sessionAsyncJobManager = asyncJobManager;
 		if (sessionAsyncJobManager) {
@@ -3792,35 +4311,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					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;
-						session.yieldQueue.enqueue<McpNotificationEntry>("mcp-notification", { serverName, uri });
-					}, debounceMs),
-				);
-			});
+			wireMcpManagerCallbacks(mcpManager);
 		}
 
 		// Constructor-time workflow-gate tool restoration is deferred by one
@@ -3934,6 +4430,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				cleanupDiagnostic: safeCleanupDiagnosticForLog(cleanupDiagnostic),
 			});
 		} finally {
+			if (processCwdClaimed) {
+				SessionManager.releaseProcessCwdOwnership(sessionManager);
+				processCwdClaimed = false;
+			}
 			releaseLocalProtocolOverride();
 			try {
 				closeOwnedAuthStorage();