pi-cursor-sdk 0.5.2 → 0.5.4

package/src/cursor-provider-turn-prepare.ts

@@ -59,6 +59,7 @@ import type {
 } from "./cursor-provider-turn-types.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { SessionCursorAgentLease } from "./cursor-session-agent.js";
+import { assertCursorNativeToolsRuntime } from "./cursor-native-tools.js";
 import { prepareCursorSummaryProviderTurn } from "./cursor-provider-turn-summary.js";
 
 export interface PrepareCursorProviderTurnParams {
@@ -69,6 +70,8 @@ export interface PrepareCursorProviderTurnParams {
 	throwIfAborted: () => void;
 	/** Snapshot resolved once by the runner before draining; reused unchanged through prepare. */
 	resolvedConfig: CursorResolvedSdkConfig;
+	/** Snapshotted before drain/acquisition, never re-read during creation/resume. */
+	nativeToolsEnabled: boolean;
 }
 
 interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnParams {
@@ -252,7 +255,7 @@ async function prepareCursorCloudProviderTurn(
 async function prepareCursorLocalProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<LocalCursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames, nativeToolsEnabled } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -289,6 +292,7 @@ async function prepareCursorLocalProviderTurn(
 			settingSources,
 			localSafety,
 			agents,
+			nativeToolsEnabled,
 			localResume: resolvedConfig.local.resume.value,
 			storeRoot: resolvedConfig.local.storeRoot.value,
 			useHttp1ForAgent,
@@ -314,6 +318,7 @@ async function prepareCursorLocalProviderTurn(
 				...getCursorPromptOptions(model),
 				nativeSourceRoles: params.request.nativeSourceRoles,
 				agentMode,
+				nativeToolsEnabled,
 				includePiBridgeGuidance,
 				includePiAskQuestionGuidance: false,
 			};
@@ -323,6 +328,7 @@ async function prepareCursorLocalProviderTurn(
 			return {
 				...promptOptions,
 				toolManifest: buildCursorToolManifestText({
+					nativeToolsEnabled,
 					bridgeSnapshot: sessionAgentLease.bridgeRun?.snapshot,
 					piBridgeEnabled: resolveCursorPiToolBridgeEnabled(),
 					includePiBridgeGuidance,
@@ -373,6 +379,7 @@ async function prepareCursorLocalProviderTurn(
 			agentMode,
 			localForce: resolvedConfig.local.force.value,
 			localResume: resolvedConfig.local.resume.value,
+			...(nativeToolsEnabled ? {} : { nativeToolsEnabled: false, tools: ["mcp"] }),
 			resumedAgent: sessionAgentLease.resumed,
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
@@ -386,6 +393,7 @@ async function prepareCursorLocalProviderTurn(
 			? cursorLiveRuns.start({
 					id: useNativeToolReplay ? nativeReplayId : bridgeRun?.id ?? nativeReplayId,
 					agent,
+					nativeToolsEnabled,
 					bridgeRun,
 					sessionBridgeRun,
 					sessionAgentScopeKey,
@@ -467,6 +475,7 @@ export async function prepareCursorProviderTurn(
 ): Promise<CursorProviderTurnPrepareResult> {
 	const { params, resolvedConfig } = prepareParams;
 	const { model, options } = params;
+	assertCursorNativeToolsRuntime(resolvedConfig.runtime.value, prepareParams.nativeToolsEnabled);
 
 	const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id, params.scope.scopeKey);
 	const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);

package/src/cursor-provider-turn-runner.ts

@@ -1,5 +1,6 @@
+import { assertCursorNativeToolsRuntime, resolveCursorNativeToolsEnabled } from "./cursor-native-tools.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
-import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns, drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type { CursorRuntime } from "./cursor-config.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
@@ -68,6 +69,13 @@ export class CursorProviderTurnRunner {
 			this.throwIfAborted();
 			const { scope } = this.params;
 			const cwd = scope.cwd;
+
+			// Resolved once here, before any drain await, so the drain decision and the
+			// prepare dispatch below always act on the same config snapshot.
+			const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
+			this.runtimeTarget = resolvedConfig.runtime.value;
+			const nativeToolsEnabled = resolveCursorNativeToolsEnabled();
+			assertCursorNativeToolsRuntime(this.runtimeTarget, nativeToolsEnabled);
 			this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
 				cwd,
 				modelId: model.id,
@@ -76,13 +84,9 @@ export class CursorProviderTurnRunner {
 			});
 			sdkEventDebugRef.current = this.sdkEventDebug;
 			this.sdkEventDebug?.recordContextSnapshot(context);
-			// Resolved once here, before any drain await, so the drain decision and the
-			// prepare dispatch below always act on the same config snapshot.
-			const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
-			this.runtimeTarget = resolvedConfig.runtime.value;
 			if (resolvedConfig.runtime.value === "local" && this.params.request.purpose === "normal") {
 				if (
-					(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor)) ===
+					(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor, nativeToolsEnabled)) ===
 					"stream_ended"
 				) {
 					return;
@@ -98,6 +102,7 @@ export class CursorProviderTurnRunner {
 				sdkEventDebug: this.sdkEventDebug,
 				throwIfAborted: () => this.throwIfAborted(),
 				resolvedConfig,
+				nativeToolsEnabled,
 			});
 
 			const usage = await this.params.usageRecorder.start({
@@ -173,6 +178,12 @@ export class CursorProviderTurnRunner {
 				displayOnlyTraceBlock: finalized.displayOnlyTraceBlock,
 			});
 		} catch (error) {
+			// This body owns the session turn lease; a queued request aborted before
+			// entry must not release another request's run in handleOuterCatch().
+			if (!prepared && (error instanceof CursorLiveRunAbortError || options?.signal?.aborted)) {
+				const pending = cursorLiveRuns.getActiveForScope(this.params.scope.scopeKey);
+				if (pending && !pending.disposed) await cursorLiveRuns.release(pending);
+			}
 			await runFinalizer.applyTerminalEvent({ kind: "error", prepared: started ?? prepared, error });
 		} finally {
 			await runFinalizer.cleanup(prepared, sendResult, liveCompletion);

package/src/cursor-provider-turn-summary.ts

@@ -40,7 +40,7 @@ export async function prepareCursorSummaryProviderTurn(
 		configureCursorSdkHttp1(sdk, resolvedConfig.local.useHttp1ForAgent);
 		restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
 		sessionStore = (await openCursorSessionStoreForScope({
-			cwd, scopeKey: params.scope.scopeKey, persistent: false,
+			cwd, scopeKey: params.scope.persistentScopeKey ?? params.scope.scopeKey, persistent: false,
 		})).sessionStore;
 		throwIfAborted();
 		agent = await suppressCursorSdkOutput(() => sdk.Agent.create({

package/src/cursor-provider.ts

@@ -9,8 +9,6 @@ import {
 } from "@earendil-works/pi-ai";
 import {
 	cursorLiveRuns,
-	DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
-	getPendingCursorLiveRun,
 	hasTrailingUserMessagesAfterToolResults,
 	releaseAllPendingCursorLiveRunsForTests,
 	resetCursorNativeReplayIdleDisposeMs,
@@ -114,10 +112,7 @@ export function streamCursor(
 }
 
 export const __testUtils = {
-	DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
 	pendingCursorNativeRunCount: cursorLiveRuns.count,
-	getPendingCursorLiveRun,
-	getActiveCursorLiveRunForScope: cursorLiveRuns.getActiveForScope,
 	hasTrailingUserMessagesAfterToolResults,
 	setCursorNativeReplayIdleDisposeMs,
 	resetCursorNativeReplayIdleDisposeMs,

package/src/cursor-runtime-state.ts

@@ -39,9 +39,9 @@ import { getResolvedSessionCursorHttp1Enabled } from "./cursor-http1.js";
 import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 import { cursorSettingsScopeForContext, getCursorSessionSettings } from "./cursor-session-settings.js";
 
-export const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
+const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
 
-export const CURSOR_CLOUD_ACK_DISCLOSURE = [
+const CURSOR_CLOUD_ACK_DISCLOSURE = [
 	"Cursor Cloud executes this work remotely.",
 	"Fresh context is used by default; prior Pi context is included only with explicit bootstrap opt-in.",
 	"Pi-local tools and the Pi bridge are unavailable, and Pi environment variables are not forwarded.",
@@ -145,7 +145,7 @@ export function resolveCursorStatusRuntime(ctx: CursorRuntimeContext): CursorRun
 	}
 }
 
-export function formatResolvedCursorRuntime(runtime: CursorResolvedSetting<CursorRuntime>): string {
+function formatResolvedCursorRuntime(runtime: CursorResolvedSetting<CursorRuntime>): string {
 	const cap = runtime.cappedBy;
 	return cap
 		? `${runtime.value} (source: ${runtime.source} safety cap over ${cap.cappedSource} ${cap.cappedValue})`

package/src/cursor-sdk-event-debug.ts

@@ -171,7 +171,7 @@ export type DiscardedIncompleteStartedToolCallReason =
 	| "sdk-failure"
 	| "run-drain";
 
-export function hashCursorSdkCallId(callId: string): string {
+function hashCursorSdkCallId(callId: string): string {
 	return createHash("sha256").update(callId).digest("hex").slice(0, 8);
 }
 
@@ -182,7 +182,7 @@ export interface DiscardedIncompleteStartedToolCallRecord {
 	reason: DiscardedIncompleteStartedToolCallReason;
 }
 
-export function serializeDiscardedIncompleteStartedToolCall(record: {
+function serializeDiscardedIncompleteStartedToolCall(record: {
 	toolName: string;
 	callId: string;
 	reason?: DiscardedIncompleteStartedToolCallReason;

package/src/cursor-sdk-output-filter.ts

@@ -1,5 +1,6 @@
 export {
-	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	__testUtils,
+	installCursorSdkProcessOutputFilter,
 	withCursorSdkOutputNoticeHandler,
 	installCursorSdkOutputFilter,
 	isCursorSdkOutputSuppressed,

package/src/cursor-sdk-process-error-guard.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { classifyCursorConnectError, isCursorSdkAbortConnectError, isCursorSdkConnectionStalledError } from "./cursor-provider-errors.js";
+import { classifyCursorConnectError, isCursorSdkConnectionStalledError } from "./cursor-provider-errors.js";
 
 interface CursorSdkProcessErrorGuardToken {
 	suppressAbortErrors: boolean;
@@ -147,8 +147,6 @@ export const __testUtils = {
 	},
 };
 
-export { isCursorSdkAbortConnectError };
-
 export function installCursorSdkProcessErrorGuard(): CursorSdkProcessErrorGuard {
 	const token: CursorSdkProcessErrorGuardToken = { suppressAbortErrors: false };
 	activeProviderTurns.add(token);

package/src/cursor-session-agent-cleanup.ts

@@ -5,6 +5,7 @@ import { fsyncExistingRegularFile } from "./cursor-durable-fs.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import {
 	CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE,
 	isCursorLocalAgentId,
@@ -323,7 +324,11 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 						openedStore = await openCursorSessionStore(ctx.cwd, identity, identities.workspaceRoot, identities.storeRoot);
 						openedStores.set(identity.stateRoot, openedStore);
 					}
-					await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
+					const release = claimCursorLocalAgent(identity, agentId);
+					if (!release) throw new Error("Cursor local agent is still owned by an active runtime");
+					try {
+						await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
+					} finally { release(); }
 					deletedAgentIds.push(agentId);
 				} catch (error) {
 					failedAgentIds.push({

package/src/cursor-session-agent-lifecycle.ts

@@ -7,7 +7,7 @@ import type {
 	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { clearCursorSdkHttp1 } from "./cursor-http1.js";
-import { cursorSessionScopeKeyForManager, hasLiveCursorSessions, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import { cursorRuntimeSessionScopeKeyForManager, hasLiveCursorSessions, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
 import {
 	disposeSessionCursorAgent,
 	invalidateSessionAgent,
@@ -25,7 +25,7 @@ export interface CursorSessionAgentLifecycleExtensionApi {
 
 export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
 	let scopeKey: string | undefined;
-	pi.on("session_start", (_event, ctx) => { scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager); });
+	pi.on("session_start", (_event, ctx) => { scopeKey = cursorRuntimeSessionScopeKeyForManager(ctx.sessionManager); });
 	onCursorSessionScopeKeyChange(pi, async (previousScopeKey) => {
 		await disposeSessionCursorAgent(previousScopeKey);
 	});

package/src/cursor-session-agent-lineage.ts

@@ -29,6 +29,7 @@ interface CursorSessionAgentLineageState {
 	sessionId?: string;
 	sessionFile?: string;
 	scopeKey?: string;
+	runtimeScopeKey?: string;
 	cwd?: string;
 	recordedAgentIds: Set<string>;
 }
@@ -82,7 +83,7 @@ function readRecordedAgentIds(entries: readonly SessionEntry[], sessionId: strin
 export function recordCursorSessionAgentLineage(agentId: string, turnScopeKey?: string): void {
 	const sessionState = turnScopeKey === undefined
 		? state
-		: statesByScope.get(turnScopeKey) ?? (state.scopeKey === turnScopeKey ? state : undefined);
+		: statesByScope.get(turnScopeKey) ?? ((state.runtimeScopeKey ?? state.scopeKey) === turnScopeKey ? state : undefined);
 	if (!sessionState) return;
 	const { appendEntry, sessionId, sessionFile, scopeKey, cwd } = sessionState;
 	if (!appendEntry || !sessionId || !scopeKey || !cwd) return;
@@ -115,22 +116,25 @@ export function registerCursorSessionAgentLineage(pi: CursorSessionAgentLineageE
 	pi.on("session_start", (_event, ctx) => {
 		state = sessionState;
 		const record = sessionState;
-		if (record.scopeKey && statesByScope.get(record.scopeKey) === record) statesByScope.delete(record.scopeKey);
+		if (record.runtimeScopeKey && statesByScope.get(record.runtimeScopeKey) === record) statesByScope.delete(record.runtimeScopeKey);
 		record.appendEntry = pi.appendEntry;
 		record.sessionId = ctx.sessionManager.getSessionId();
 		record.sessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
-		record.scopeKey = getCursorSessionScopeSnapshot(pi).scopeKey;
-		statesByScope.set(record.scopeKey, record);
+		const scope = getCursorSessionScopeSnapshot(pi);
+		record.runtimeScopeKey = scope.scopeKey;
+		record.scopeKey = scope.persistentScopeKey ?? scope.scopeKey;
+		statesByScope.set(scope.scopeKey, record);
 		record.cwd = ctx.cwd;
 		record.recordedAgentIds = readRecordedAgentIds(ctx.sessionManager.getEntries(), record.sessionId);
 	});
 	pi.on("session_shutdown", () => {
 		const state = sessionState;
-		if (state.scopeKey && statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
+		if (state.runtimeScopeKey && statesByScope.get(state.runtimeScopeKey) === state) statesByScope.delete(state.runtimeScopeKey);
 		state.appendEntry = undefined;
 		state.sessionId = undefined;
 		state.sessionFile = undefined;
 		state.scopeKey = undefined;
+		state.runtimeScopeKey = undefined;
 		state.cwd = undefined;
 		state.recordedAgentIds = new Set();
 	});
@@ -142,6 +146,7 @@ function resetStateForTests(): void {
 	state.sessionId = undefined;
 	state.sessionFile = undefined;
 	state.scopeKey = undefined;
+	state.runtimeScopeKey = undefined;
 	state.cwd = undefined;
 	state.recordedAgentIds = new Set();
 }

package/src/cursor-session-agent-resume.ts

@@ -60,6 +60,7 @@ interface PendingCursorSessionAgentResumeHandle {
 
 interface CursorSessionResumeState {
 	appendEntry?: ExtensionAPI["appendEntry"];
+	runtimeScopeKey?: string;
 	scopeKey: string;
 	sessionFile?: string;
 	sessionId?: string;
@@ -355,7 +356,7 @@ function restoreFromBranch(branch: readonly SessionEntry[], allEntries: readonly
 
 export function getMatchingCursorSessionAgentResumeHandle(poolKey: string, scopeKey?: string): CursorSessionAgentResumeEntryData | undefined {
 	const state = getResumeState(scopeKey);
-	if (scopeKey !== undefined && state.scopeKey !== scopeKey) return undefined;
+	if (scopeKey !== undefined && (state.runtimeScopeKey ?? state.scopeKey) !== scopeKey) return undefined;
 	const handle = state.activeHandle;
 	if (!handle || !isCursorLocalAgentId(handle.agentId)) return undefined;
 	if (handle.poolKey !== poolKey) return undefined;
@@ -373,7 +374,7 @@ export function getMatchingCursorSessionAgentResumeHandle(poolKey: string, scope
 
 export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle, scopeKey?: string): void {
 	const state = getResumeState(scopeKey);
-	if (scopeKey !== undefined && state.scopeKey !== scopeKey) return;
+	if (scopeKey !== undefined && (state.runtimeScopeKey ?? state.scopeKey) !== scopeKey) return;
 	if (!isCursorLocalAgentId(input.agentId)) return;
 	state.pendingHandle = {
 		runtime: input.runtime,
@@ -427,8 +428,9 @@ interface CursorSessionAgentResumeExtensionApi {
 }
 
 export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExtensionApi): void {
+	const scope = getCursorSessionScopeSnapshot(pi);
 	const sessionState: CursorSessionResumeState = {
-		appendEntry: pi.appendEntry, scopeKey: getCursorSessionScopeSnapshot(pi).scopeKey,
+		appendEntry: pi.appendEntry, scopeKey: scope.persistentScopeKey ?? scope.scopeKey,
 		cwd: process.cwd(), branchPathHash: EMPTY_BRANCH_HASH,
 		compactionGeneration: 0, unownedUserEntryIds: new Set(),
 	};
@@ -439,9 +441,12 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		restoreFromBranch(branch, entries.length > 0 ? entries : branch, state);
 	};
 	pi.on("session_start", (_event, ctx) => {
-		if (statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
-		state.scopeKey = getCursorSessionScopeSnapshot(pi).scopeKey;
-		statesByScope.set(state.scopeKey, state);
+		const key = state.runtimeScopeKey ?? state.scopeKey;
+		if (statesByScope.get(key) === state) statesByScope.delete(key);
+		const scope = getCursorSessionScopeSnapshot(pi);
+		state.runtimeScopeKey = scope.scopeKey;
+		state.scopeKey = scope.persistentScopeKey ?? scope.scopeKey;
+		statesByScope.set(scope.scopeKey, state);
 		lastBoundState = state;
 		state.sessionFile = ctx.sessionManager.getSessionFile?.() ?? undefined;
 		state.sessionId = ctx.sessionManager.getSessionId?.() ?? undefined;
@@ -482,7 +487,8 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		state.branchPathHash = hashBranchStep(state.branchPathHash, event.compactionEntry);
 	});
 	pi.on("session_shutdown", () => {
-		if (statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
+		const key = state.runtimeScopeKey ?? state.scopeKey;
+		if (statesByScope.get(key) === state) statesByScope.delete(key);
 		state.appendEntry = undefined;
 		state.pendingHandle = undefined;
 	});
@@ -496,6 +502,7 @@ function resetStateForTests(): void {
 	const state = lastBoundState;
 	state.appendEntry = undefined;
 	state.scopeKey = getCursorSessionScopeKey();
+	state.runtimeScopeKey = undefined;
 	state.sessionFile = undefined;
 	state.sessionId = undefined;
 	state.cwd = process.cwd();

package/src/cursor-session-agent.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { AgentModeOption, AgentOptions, LocalAgentOptions, LocalAgentStore, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
 import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
+import { claimCursorLocalAgent } from "./cursor-local-agent-ownership.js";
 import {
 	getRegisteredCursorPiToolBridge,
 	type CursorPiToolBridge,
@@ -9,7 +10,7 @@ import {
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
-import { getCursorSessionFile, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeGeneration, getCursorSessionScopeKey, type CursorTurnScope } from "./cursor-session-scope.js";
 import {
 	getMatchingCursorSessionAgentResumeHandle,
 	persistCursorSessionAgentResumeHandle,
@@ -68,6 +69,7 @@ interface SessionCursorAgentReadyEntry extends SessionCursorAgentPoolEntryBase {
 	resumeEnabled: boolean;
 	resumed: boolean;
 	resumeNotice?: string;
+	releaseAgentClaim: () => void;
 }
 
 interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
@@ -78,6 +80,7 @@ interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
 	resumeEnabled: boolean;
 	resumed: boolean;
 	resumeNotice?: string;
+	releaseAgentClaim: () => void;
 	completionSettled: Promise<void>;
 	pendingCompletion: Promise<void>;
 	releaseBusyWait: () => void;
@@ -137,6 +140,8 @@ interface SessionCursorAgentCreateParams {
 	settingSources?: SettingSource[];
 	localSafety?: CursorLocalSafetyOptions;
 	agents?: AgentOptions["agents"];
+	/** Captured by the turn owner before asynchronous acquisition. */
+	nativeToolsEnabled?: boolean;
 	useHttp1ForAgent?: boolean;
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
@@ -150,7 +155,7 @@ interface SessionCursorAgentCreateParams {
 const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
 const invalidatedScopeKeys = new Set<string>();
 const deadTransportScopeKeys = new Set<string>();
-let deadTransportAgentDisposeTimeoutMs = 3000;
+const DEAD_TRANSPORT_AGENT_DISPOSE_TIMEOUT_MS = 3000;
 const terminalDisposedScopeGenerations = new Map<string, number>();
 const scopeCreationGenerations = new Map<string, number>();
 const EMPTY_POOL_STATE: SessionCursorAgentPoolState = { status: "empty" };
@@ -238,7 +243,7 @@ function buildCustomSubagentPoolKeySuffix(agents: AgentOptions["agents"]): strin
 
 function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCreateParams): string {
 	return [
-		scopeKey,
+		params.scope?.persistentScopeKey ?? scopeKey,
 		params.cwd,
 		buildModelPoolKey(params.modelSelection),
 		buildSettingSourcesPoolKey(params.settingSources),
@@ -251,6 +256,8 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 		buildApiKeyPoolKeyFingerprint(params.apiKey),
 		buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
 		...buildCustomSubagentPoolKeySuffix(params.agents),
+		// Omit for the default so historical durable keys remain byte-for-byte stable.
+		...(params.nativeToolsEnabled === false ? ["tools:mcp-only"] : []),
 	].join("\0");
 }
 
@@ -262,20 +269,23 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: {
 	} catch {
 		// disposal failure should not block session replacement
 	}
+	let disposal: Promise<unknown> | undefined;
 	try {
-		const disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]()).catch(() => undefined);
+		disposal = Promise.resolve(entry.agent[Symbol.asyncDispose]());
 		// A dead local transport may never settle SDK disposal; bound the wait so the
 		// next acquire recreates instead of hanging on the dead agent.
 		await (options?.deadTransport
 			? Promise.race([
 					disposal,
-					new Promise<void>((resolve) => setTimeout(resolve, deadTransportAgentDisposeTimeoutMs).unref?.()),
+					new Promise<void>((resolve) => setTimeout(resolve, DEAD_TRANSPORT_AGENT_DISPOSE_TIMEOUT_MS).unref?.()),
 				])
 			: disposal);
 	} catch {
 		// disposal failure should not block session replacement
 	}
 	await entry.sessionStore.dispose().catch(() => undefined);
+	// Timeout/rejection is not proof of closure; only successful SDK disposal releases ownership.
+	void disposal?.then(entry.releaseAgentClaim, () => {});
 }
 
 async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?: boolean }): Promise<void> {
@@ -470,6 +480,7 @@ async function createSessionAgentEntry(
 ): Promise<SessionCursorAgentReadyEntry> {
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	let sessionStore: OpenCursorSessionStore | undefined;
+	let releaseAgentClaim: (() => void) | undefined;
 	try {
 		const registeredBridge = params.bridge;
 		if (registeredBridge) {
@@ -495,7 +506,7 @@ async function createSessionAgentEntry(
 		const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey, scopeKey) : undefined;
 		const storeSelection = await openCursorSessionStoreForScope({
 			cwd: params.cwd,
-			scopeKey,
+			scopeKey: params.scope?.persistentScopeKey ?? scopeKey,
 			persistent: persistentStore,
 			storeRoot: params.storeRoot,
 			resume: resumeHandle ? { identity: resumeHandle.storeIdentity, agentId: resumeHandle.agentId } : undefined,
@@ -513,6 +524,7 @@ async function createSessionAgentEntry(
 				localSafety: params.localSafety,
 				store: sessionStore!.store,
 			}),
+			...(params.nativeToolsEnabled === false ? { tools: ["mcp"] } : {}),
 			...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
 			...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
 		});
@@ -520,11 +532,16 @@ async function createSessionAgentEntry(
 		let effectiveSendState = sendState;
 		let resumed = false;
 		if (resumeHandle && resumeAttemptAllowed && resumeAgent) {
+			releaseAgentClaim = claimCursorLocalAgent(sessionStore.identity, resumeHandle.agentId);
+		}
+		if (resumeHandle && resumeAttemptAllowed && resumeAgent && releaseAgentClaim) {
 			try {
 				agent = await resumeAgent(resumeHandle.agentId, buildAgentOptions());
 				effectiveSendState = { ...resumeHandle.sendState };
 				resumed = true;
 			} catch {
+				releaseAgentClaim();
+				releaseAgentClaim = undefined;
 				if (persistentStore) resumeNotice = LOCAL_RESUME_FALLBACK_NOTICE;
 				if (storeSelection.persistent && !cursorSessionStoreIdentitiesEqual(sessionStore.identity, storeSelection.identities.sessionStore)) {
 					const { identities } = storeSelection;
@@ -537,6 +554,8 @@ async function createSessionAgentEntry(
 		agent ??= await createAgent(buildAgentOptions());
 		if (!agent) throw new Error("Cursor SDK agent creation returned no agent");
 		if (!sessionStore) throw new Error("Cursor SDK session store was not opened");
+		releaseAgentClaim ??= claimCursorLocalAgent(sessionStore.identity, agent.agentId);
+		if (!releaseAgentClaim) throw new Error("Cursor SDK agent is already owned by another runtime");
 
 		return {
 			status: "ready",
@@ -550,12 +569,14 @@ async function createSessionAgentEntry(
 			sendState: effectiveSendState,
 			resumeEnabled: params.localResume === true,
 			resumed,
+			releaseAgentClaim,
 			...(resumeNotice ? { resumeNotice } : {}),
 		};
 	} catch (error) {
 		bridgeRun?.cancel("Cursor session agent create failed");
 		await bridgeRun?.dispose().catch(() => undefined);
 		await sessionStore?.dispose().catch(() => undefined);
+		releaseAgentClaim?.();
 		throw error;
 	}
 }
@@ -568,7 +589,7 @@ export {
 } from "./cursor-session-send-policy.js";
 
 export function invalidateSessionAgent(
-	scopeKey: string = getCursorSessionScopeKey(),
+	scopeKey: string,
 	options?: { deadTransport?: boolean },
 ): void {
 	invalidatedScopeKeys.add(scopeKey);
@@ -576,9 +597,9 @@ export function invalidateSessionAgent(
 }
 
 export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
-	const params = { ...input, bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
-	const scopeKey = params.scope?.scopeKey ?? getCursorSessionScopeKey();
-	const persistentStore = (params.scope ? params.scope.sessionFile : getCursorSessionFile()) !== undefined;
+	const params = { ...input, scope: input.scope ?? getCursorSessionScopeSnapshot(), bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
+	const scopeKey = params.scope.scopeKey;
+	const persistentStore = params.scope.sessionFile !== undefined;
 	params.storeRoot = persistentStore && params.storeRoot !== undefined ? normalizeCursorCustomStoreRoot(params.storeRoot) : undefined;
 
 	while (true) {
@@ -709,11 +730,6 @@ export const __testUtils = {
 	resetSessionCursorAgent,
 	refreshSessionCursorAgentConfig,
 	disposeAllSessionCursorAgents,
-	setDeadTransportAgentDisposeTimeoutMs(ms: number): number {
-		const previous = deadTransportAgentDisposeTimeoutMs;
-		deadTransportAgentDisposeTimeoutMs = ms;
-		return previous;
-	},
 	SessionCursorAgentCreationSupersededError,
 	SessionCursorAgentScopeClosedError,
 };