pi-cursor-sdk 0.5.3 → 0.5.4

package/src/cursor-pi-tool-bridge.ts

@@ -1,18 +1,12 @@
 import { spawnSync } from "node:child_process";
 import {
-	CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV,
 	CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX,
 	type CursorPiToolBridgeDiagnosticEvent,
 	serializeCursorPiToolBridgeDiagnostic,
 } from "./cursor-pi-tool-bridge-diagnostics.js";
-import {
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_ENV,
-} from "./cursor-pi-tool-bridge-env.js";
 import { bridgeToolExecutionAbortTracker } from "./cursor-pi-tool-bridge-abort.js";
-import { isCursorPiBridgeToolCallId, MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-constants.js";
-import { LOOPBACK_HOST, CursorPiToolBridgeRegistry } from "./cursor-pi-tool-bridge-server.js";
+import { isCursorPiBridgeToolCallId } from "./cursor-pi-tool-bridge-constants.js";
+import { CursorPiToolBridgeRegistry } from "./cursor-pi-tool-bridge-server.js";
 import type {
 	CursorPiToolBridge,
 	CursorPiToolBridgeExtensionApi,
@@ -34,9 +28,6 @@ export type {
 export type { CursorPiToolBridgeDiagnosticEvent } from "./cursor-pi-tool-bridge-diagnostics.js";
 export { resolveCursorPiToolBridgeDebugEnabled } from "./cursor-pi-tool-bridge-diagnostics.js";
 export {
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_ENV,
 	resolveCursorPiToolBridgeBuiltinsEnabled,
 	resolveCursorPiToolBridgeCallTimeoutMs,
 	resolveCursorPiToolBridgeEnabled,
@@ -145,13 +136,7 @@ export function getRegisteredCursorPiToolBridge(pi?: object): CursorPiToolBridge
 }
 
 export const __testUtils = {
-	CURSOR_PI_TOOL_BRIDGE_ENV,
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV,
 	CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX,
-	LOOPBACK_HOST,
-	MCP_SERVER_NAME,
 	createRegistry(
 		pi: CursorPiToolBridgeSnapshotApi,
 		env: Record<string, string | undefined> = process.env,
@@ -168,7 +153,6 @@ export const __testUtils = {
 		return bridgeToolExecutionAbortTracker.getActiveCount();
 	},
 	buildWindowsBridgeBashAbortCommandForTests: buildWindowsBridgeBashAbortCommand,
-	installWindowsBridgeBashAbortMarkerForTests: installWindowsBridgeBashAbortMarker,
 	emitBridgeToolExecutionProcessAbortSignalForTests(signal: NodeJS.Signals) {
 		bridgeToolExecutionAbortTracker.emitProcessAbortSignalForTests(signal);
 	},

package/src/cursor-provider-errors.ts

@@ -258,14 +258,6 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 	return undefined;
 }
 
-export function isCursorSdkAbortConnectError(error: unknown): boolean {
-	return classifyCursorConnectError(error)?.kind === "abort";
-}
-
-export function isUnauthenticatedConnectError(error: unknown): boolean {
-	return classifyCursorConnectError(error)?.kind === "unauthenticated";
-}
-
 function isLikelyNetworkTimeout(message: string): boolean {
 	return (
 		/\b(ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|EAI_AGAIN|NGHTTP2_ENHANCE_YOUR_CALM|ERR_HTTP2_STREAM_ERROR|ERR_HTTP2_SESSION_ERROR)\b/i.test(

package/src/cursor-provider-live-run-drain.ts

@@ -29,7 +29,7 @@ import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js
 import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-routing.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
-export const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
+const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
 function parseCursorNativeReplayIdleDisposeMs(raw: string | undefined): number {
 	if (!raw || /[^0-9]/.test(raw)) return DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
 	const value = Number(raw);
@@ -69,7 +69,7 @@ function getCursorNativeReplayIdFromToolCallId(toolCallId: string): string | und
 	return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
 }
 
-export function getPendingCursorLiveRun(context: Context, scopeKey: string): CursorLiveRun | undefined {
+function getPendingCursorLiveRun(context: Context, scopeKey: string): CursorLiveRun | undefined {
 	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId, scopeKey);
 }
 
@@ -449,6 +449,7 @@ export async function drainExistingCursorLiveRunBeforeSend(
 	turnDebugRecorder: CursorSdkEventDebugRecorder | undefined,
 	scopeKey: string,
 	occupancyFloor?: number,
+	nativeToolsEnabled = true,
 ): Promise<LiveRunPreSendOutcome> {
 	turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
 	while (true) {
@@ -461,6 +462,11 @@ export async function drainExistingCursorLiveRunBeforeSend(
 		try {
 			const outcome = await cursorLiveRuns.withRunLease(run, signal, async () => {
 				if (run.disposed) return "continue_send" as const;
+				// Check under the drain lease, before consuming/delivering Pi results:
+				// resolving a bridge waiter can resume the SDK's old tool surface.
+				if ((run.nativeToolsEnabled !== false) !== nativeToolsEnabled) {
+					throw new Error("Cursor native tool policy changed while a local run is pending; restore the prior policy to finish it or run /cursor-abort before retrying. Already-executed work is not undone.");
+				}
 				const consumed = cursorLiveRuns.consumeToolResults(run, context, getCursorNativeReplayIdFromToolCallId);
 				await run.bridgeRun?.resolveToolResults(consumed.toolResults);
 				const shouldChainUserInput = run.chainUserInputAfterCompletion || hasTrailingUserMessagesAfterToolResults(context);

package/src/cursor-provider-overflow.ts

@@ -1,5 +1,4 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { CURSOR_PROVIDER } from "./cursor-model.js";
 
 /**
@@ -15,7 +14,7 @@ import { CURSOR_PROVIDER } from "./cursor-model.js";
  *
  * See pi `docs/custom-provider.md` -> "Context Overflow Errors".
  */
-export const CURSOR_OVERFLOW_MARKER = "context_length_exceeded";
+const CURSOR_OVERFLOW_MARKER = "context_length_exceeded";
 
 /**
  * Context-overflow phrases. These overlap pi's own `OVERFLOW_PATTERNS` so the
@@ -43,9 +42,9 @@ const CURSOR_THROTTLE_PATTERN = /too many requests|rate.?limit|throttl|retry.?af
  * Map a finalized Cursor assistant `errorMessage` to pi's overflow form.
  * Returns `undefined` when the message is not a Cursor context-overflow failure.
  *
- * Pure and idempotent so it is safe to call repeatedly and unit-test in isolation.
+ * Idempotent so repeated message delivery does not add another prefix.
  */
-export function normalizeCursorOverflowErrorMessage(errorMessage: string | undefined): string | undefined {
+function normalizeCursorOverflowErrorMessage(errorMessage: string | undefined): string | undefined {
 	const message = errorMessage?.trim();
 	if (!message) return undefined;
 	// Idempotent: never double-prefix an already-normalized message.
@@ -57,24 +56,6 @@ export function normalizeCursorOverflowErrorMessage(errorMessage: string | undef
 	return undefined;
 }
 
-/**
- * Rewrite a finalized assistant message into pi's overflow form when it is a
- * Cursor context-overflow failure. Returns the replacement message (for the
- * `message_end` result) or `undefined` to leave it unchanged.
- *
- * `isCursorProvider` carries the provider scoping decision out of the handler so
- * the full logic is unit-testable without a pi event harness.
- */
-export function rewriteCursorOverflowAssistantMessage(
-	message: AssistantMessage,
-	isCursorProvider: boolean,
-): AssistantMessage | undefined {
-	if (!isCursorProvider || message.stopReason !== "error") return undefined;
-	const rewritten = normalizeCursorOverflowErrorMessage(message.errorMessage);
-	if (!rewritten) return undefined;
-	return { ...message, errorMessage: rewritten };
-}
-
 export type CursorOverflowExtensionApi = Pick<ExtensionAPI, "on">;
 
 /**
@@ -89,8 +70,9 @@ export function registerCursorOverflowNormalization(pi: CursorOverflowExtensionA
 		const message = event.message;
 		if (message.role !== "assistant") return undefined;
 		const isCursorProvider = message.provider === CURSOR_PROVIDER || ctx.model?.provider === CURSOR_PROVIDER;
-		const rewritten = rewriteCursorOverflowAssistantMessage(message, isCursorProvider);
+		if (!isCursorProvider || message.stopReason !== "error") return undefined;
+		const rewritten = normalizeCursorOverflowErrorMessage(message.errorMessage);
 		if (!rewritten) return undefined;
-		return { message: rewritten };
+		return { message: { ...message, errorMessage: rewritten } };
 	});
 }

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.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.ts

@@ -140,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;
@@ -153,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" };
@@ -254,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");
 }
 
@@ -273,7 +277,7 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry, options?: {
 		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 {
@@ -520,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 } : {}),
 		});
@@ -584,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);
@@ -725,11 +730,6 @@ export const __testUtils = {
 	resetSessionCursorAgent,
 	refreshSessionCursorAgentConfig,
 	disposeAllSessionCursorAgents,
-	setDeadTransportAgentDisposeTimeoutMs(ms: number): number {
-		const previous = deadTransportAgentDisposeTimeoutMs;
-		deadTransportAgentDisposeTimeoutMs = ms;
-		return previous;
-	},
 	SessionCursorAgentCreationSupersededError,
 	SessionCursorAgentScopeClosedError,
 };

package/src/cursor-session-scope.ts

@@ -12,7 +12,7 @@ interface CursorSessionScopeExtensionApi {
 
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
 const EPHEMERAL_SESSION_SCOPE_PREFIX = "__ephemeral__:";
-export const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
+const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
 
 type CursorSessionScopeChangeHandler = (previousScopeKey: string) => Promise<void> | void;
 
@@ -103,18 +103,10 @@ export function getCursorSessionScopeGeneration(scopeKey: string = getCursorSess
 	return scopeGenerations.get(scopeKey) ?? 0;
 }
 
-export function getCursorSessionCwd(): string {
-	return state.sessionCwd;
-}
-
 export function getCursorSessionProjectTrusted(pi?: object): boolean {
 	return pi ? scopes.get(pi)?.projectTrusted === true : state.projectTrusted;
 }
 
-export function getCursorSessionName(): string | undefined {
-	return state.sessionName;
-}
-
 function normalizeCursorSessionName(name: string | undefined): string | undefined {
 	if (name === undefined) return undefined;
 	return truncateCursorDisplayLine(name, MAX_CURSOR_SESSION_NAME_LENGTH) || undefined;

package/src/cursor-session-store.ts

@@ -55,7 +55,7 @@ const activeWorkspaceRoots = new Map<string, { root: Promise<string>; users: num
 // ponytail: leases protect only extension-owned stores in this process. Other SDK
 // users/processes must stop before upgrade; a cross-process lock belongs in the SDK.
 
-export function hashCursorSessionStoreScope(scopeKey: string): string {
+function hashCursorSessionStoreScope(scopeKey: string): string {
 	return createHash("sha256")
 		.update("pi-cursor-sdk-session-store\0")
 		.update(scopeKey)

package/src/cursor-state.ts

@@ -44,11 +44,7 @@ import {
 	updateCursorSdkConfig,
 } from "./cursor-config.js";
 import {
-	consumeCursorLocalForceOverride,
-	CURSOR_RUNTIME_ENTRY_TYPE,
 	formatCursorStatus,
-	getCursorCliConfig,
-	getCursorSessionConfig,
 	registerCursorCloudRuntimeControls,
 	resetCursorRuntimeStateForTests,
 	resolveCursorStatusRuntime,
@@ -57,19 +53,11 @@ import {
 	type CursorRuntimeStateExtensionApi,
 } from "./cursor-runtime-state.js";
 
-export {
-	consumeCursorLocalForceOverride,
-	getCursorCliConfig,
-	getCursorSessionConfig,
-} from "./cursor-runtime-state.js";
-
 export const CURSOR_FOOTER_ENV = "PI_CURSOR_FOOTER";
 
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const MODE_ENTRY_TYPE = "cursor-mode-state";
 
-export type CursorAgentMode = AgentModeOption;
-
 const DEFAULT_CURSOR_AGENT_MODE: AgentModeOption = "agent";
 
 interface CursorFastEntryData {
@@ -91,11 +79,11 @@ const authoritativeGlobalFastPreferenceIds = new Set<string>();
 let globalFastPreferences = new Map<string, boolean>();
 const invalidCursorModeNotifiedSessionScopeKeys = new Set<string>();
 
-export function isCursorAgentMode(value: unknown): value is AgentModeOption {
+function isCursorAgentMode(value: unknown): value is AgentModeOption {
 	return value === "agent" || value === "plan";
 }
 
-export function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined {
+function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined {
 	if (typeof raw !== "string") return undefined;
 	const mode = raw.trim();
 	return isCursorAgentMode(mode) ? mode : undefined;
@@ -115,17 +103,13 @@ function isCursorModeEntryData(value: unknown): value is CursorModeEntryData {
 	return isCursorAgentMode(asRecord(value)?.mode);
 }
 
-function getConfigPath(): string {
-	return getCursorSdkUserConfigPath();
-}
-
 function loadGlobalFastPreferences(): Map<string, boolean> {
 	return cursorFastDefaultsFromConfig(loadCursorSdkUserConfig());
 }
 
 function saveGlobalFastPreference(modelId: string, fast: boolean): void {
 	updateCursorSdkConfig(
-		getConfigPath(),
+		getCursorSdkUserConfigPath(),
 		(current) => {
 			const fastDefaults = { ...asRecord(current.fastDefaults), [modelId]: fast };
 			return {
@@ -141,7 +125,7 @@ function saveGlobalFastPreference(modelId: string, fast: boolean): void {
 
 function saveGlobalCursorHttp1Enabled(enabled: boolean): void {
 	updateCursorSdkConfig(
-		getConfigPath(),
+		getCursorSdkUserConfigPath(),
 		(current) => mergeCursorSdkConfigForUpdate(current, {
 			local: { useHttp1ForAgent: enabled },
 		}),
@@ -227,15 +211,15 @@ function formatInvalidCursorMode(raw: string): string {
 	return `Invalid --cursor-mode "${raw}". Use "agent" or "plan".`;
 }
 
-export type CursorAgentModeResolution =
+type CursorAgentModeResolution =
 	| { kind: "valid"; mode: AgentModeOption }
 	| { kind: "invalid"; raw: string; message: string };
 
-export function getStoredCursorAgentMode(scopeKey?: string): AgentModeOption {
+function getStoredCursorAgentMode(scopeKey?: string): AgentModeOption {
 	return getCursorSessionSettings(scopeKey).mode ?? DEFAULT_CURSOR_AGENT_MODE;
 }
 
-export function resolveCursorAgentMode(scopeKey?: string): CursorAgentModeResolution {
+function resolveCursorAgentMode(scopeKey?: string): CursorAgentModeResolution {
 	const cliCursorModeState = getCursorSessionSettings(scopeKey).cli.mode;
 	switch (cliCursorModeState.kind) {
 		case "valid":
@@ -383,10 +367,10 @@ function formatEffectiveCursorSettingSourcesLabel(raw: string | undefined = proc
 	return `${rawLabel} (effective: ${effectiveLabel})`;
 }
 
-export function formatCursorToolsDebugReport(
+function formatCursorToolsDebugReport(
 	pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">,
-	env: Record<string, string | undefined> = process.env,
 ): string {
+	const env = process.env;
 	const bridgeEnabled = resolveCursorPiToolBridgeEnabled(env);
 	const manifestEnabled = resolveCursorToolManifestEnabled(env);
 	const lines = [
@@ -689,16 +673,5 @@ function resetCursorModeStateForTests(): void {
 }
 
 export const __testUtils = {
-	FAST_ENTRY_TYPE,
-	MODE_ENTRY_TYPE,
-	CURSOR_HTTP1_ENTRY_TYPE,
-	RUNTIME_ENTRY_TYPE: CURSOR_RUNTIME_ENTRY_TYPE,
-	DEFAULT_CURSOR_AGENT_MODE,
-	getConfigPath,
-	loadGlobalFastPreferences,
-	get sessionFastPreferences() { return getCursorSessionSettings().fast; },
-	getSessionCursorAgentMode: () => getCursorSessionSettings().mode,
-	getCliCursorAgentMode: () => { const mode = getCursorSessionSettings().cli.mode; return mode.kind === "valid" ? mode.mode : undefined; },
-	getCliCursorModeState: () => getCursorSessionSettings().cli.mode,
 	resetCursorModeStateForTests,
 };

package/src/cursor-tool-lifecycle.ts

@@ -86,10 +86,6 @@ function buildCursorToolLifecycleLabelFromVisibility(
 	}
 }
 
-export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
-	return buildCursorToolLifecycleLabelFromVisibility(classifyCursorToolVisibility(toolCall), apiKey);
-}
-
 export function formatCursorToolLifecycleProgressText(toolCall: unknown, apiKey?: string): string | undefined {
 	const visibility = classifyCursorToolVisibility(toolCall);
 	const label = buildCursorToolLifecycleLabelFromVisibility(visibility, apiKey);

package/src/cursor-tool-manifest.ts

@@ -18,6 +18,7 @@ export function resolveCursorToolManifestEnabled(
 
 export function buildCursorToolManifestText(options: {
 	bridgeSnapshot?: CursorPiToolBridgeSnapshot;
+	nativeToolsEnabled?: boolean;
 	/** When false, bridge is off via PI_CURSOR_PI_TOOL_BRIDGE=0 (not merely empty). */
 	piBridgeEnabled?: boolean;
 	includePiBridgeGuidance?: boolean;
@@ -26,7 +27,9 @@ export function buildCursorToolManifestText(options: {
 	const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
 	const lines = [
 		"Callable tool surfaces this run:",
-		`- Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`,
+		options.nativeToolsEnabled === false
+			? "- Cursor native tools (including task/subagents): disabled (PI_CURSOR_NATIVE_TOOLS=0). MCP remains available; configured MCP depends on Cursor settings."
+			: `- Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`,
 		"- Pi tool toggles affect pi tools/bridge exposure only; they do not disable Cursor host/configured MCP tools.",
 	];
 	const bridgeTools = includePiBridgeGuidance ? options.bridgeSnapshot?.tools ?? [] : [];