pi-cursor-sdk 0.1.19 → 0.1.21

package/shared/cursor-sensitive-text.d.mts

@@ -0,0 +1 @@
+export declare function scrubSensitiveText(text: string, apiKey?: string): string;

package/{scripts/lib/cursor-probe-utils.mjs → shared/cursor-sensitive-text.mjs}

@@ -1,21 +1,9 @@
-export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+/** Canonical secret/bridge scrubbing (parity-tested by provider runtime and maintainer scripts). */
 
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-export function resolveCursorSettingSources(raw) {
-	const trimmed = raw?.trim();
-	if (!trimmed) return ["all"];
-	const normalized = trimmed.toLowerCase();
-	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
-	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
-	return trimmed
-		.split(",")
-		.map((entry) => entry.trim())
-		.filter(Boolean);
-}
-
 const BRIDGE_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
 const BRIDGE_ENDPOINT_TOKEN_PATTERN = "[^/\\s\"'<>]+";
 const BRIDGE_LOOPBACK_HOST_PATTERN = "127\\.0\\.0\\.1(?::\\d+)?";

package/shared/cursor-setting-sources.d.mts

@@ -0,0 +1,5 @@
+export declare const CURSOR_SETTING_SOURCES_ENV: "PI_CURSOR_SETTING_SOURCES";
+
+export declare function resolveCursorSettingSources(raw?: string): string[] | undefined;
+
+export declare function serializeCursorSettingSources(settingSources: string[] | undefined): string;

package/shared/cursor-setting-sources.mjs

@@ -0,0 +1,22 @@
+/** Canonical Cursor settingSources parsing (parity-tested by provider runtime and maintainer scripts). */
+export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+
+export function resolveCursorSettingSources(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return ["all"];
+	const normalized = trimmed.toLowerCase();
+	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
+	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
+	const sources = trimmed
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+	if (sources.length === 0) return undefined;
+	return sources;
+}
+
+/** Serialize parsed settingSources for PI_CURSOR_SETTING_SOURCES (undefined => explicit none). */
+export function serializeCursorSettingSources(settingSources) {
+	if (settingSources === undefined || settingSources.length === 0) return "none";
+	return settingSources.join(",");
+}

package/src/context.ts

@@ -2,7 +2,6 @@ import { createHash } from "node:crypto";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { SDKImage } from "@cursor/sdk";
-import { getCursorPiBridgeContractText } from "./cursor-bridge-contract.js";
 import { getCursorReplayPromptLabel } from "./cursor-tool-names.js";
 
 export interface CursorPrompt {
@@ -14,6 +13,8 @@ export interface CursorPromptOptions {
 	maxInputTokens?: number;
 	charsPerToken?: number;
 	imageTokenEstimate?: number;
+	/** Compact callable-surface summary; included on bootstrap prompts when set. */
+	toolManifest?: string;
 }
 
 export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
@@ -21,20 +22,25 @@ export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
 export function getCursorToolTailGuardText(): string {
-	return "Tool boundary reminder: If a tool is needed, call an available Cursor SDK/MCP tool. Never print a tool card (for example Tool call/Shell/command) as assistant text.";
+	return [
+		"Shell: use an explicit `cd` to the repo path when running project commands; session cwd may not match paths in tool args.",
+		"Tool boundary reminder: If a tool is needed, call an available Cursor SDK/MCP tool. Never print a tool card (for example Tool call/Shell/command) as assistant text.",
+	].join("\n");
 }
 
-function getCursorToolBoundaryText(): string {
-	return [
+function getCursorToolBoundaryText(options: { hasToolManifest?: boolean } = {}): string {
+	const lines = [
 		"Cursor SDK tool boundary:",
-		"You can call only tools actually exposed by Cursor SDK in this run. Pi tool names, replay tool names, and transcript tool names are context only, not callable capabilities.",
-		getCursorPiBridgeContractText(),
-		"If asked to list or exercise available tools, list and exercise Cursor SDK tools only; do not claim access to pi-side tools from the system prompt unless Cursor exposes an equivalent tool that runs.",
+		"Call only tools exposed by Cursor SDK in this run. Pi tool names, replay labels, and transcript names are context only—not callable.",
+		"Bridged pi tools: call pi__* MCP names when exposed, not the pi card name in history. Replay activity is display-only.",
+		"Do not claim pi-side or WebSearch/WebFetch tools unless Cursor executes an equivalent tool.",
 		"Use pi__cursor_ask_question for material choices if exposed.",
-		"Web: use Cursor web/search/browser/MCP or say web search is not configured; do not claim WebSearch/WebFetch unless Cursor executes them.",
-		"Replay: pi may display recorded Cursor tool activity as pi-style cards, but replay is display-only and not a capability to invoke.",
-		"Images: only latest user images are sent; ask to reattach or describe prior images.",
-	].join("\n");
+		"Images: only the latest user message's images are sent as bytes; ask to reattach or describe prior images.",
+	];
+	if (options.hasToolManifest) {
+		lines.push("See callable tool surfaces block below.");
+	}
+	return lines.join("\n");
 }
 
 function getCursorBootstrapTailSections(): string[] {
@@ -370,7 +376,10 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 }
 
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText()];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ hasToolManifest: Boolean(options.toolManifest) })];
+	if (options.toolManifest) {
+		sectionsBeforeMessages.push(options.toolManifest);
+	}
 
 	if (context.systemPrompt) {
 		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);

package/src/cursor-bridge-contract.ts

@@ -20,8 +20,6 @@ export function buildCursorPiBridgeMcpToolDescription(options: {
 }): string {
 	return [
 		options.piToolDescription,
-		"",
-		getCursorPiBridgeContractText(),
-		`This run exposes real pi tool ${options.piToolName} as Cursor MCP tool ${options.mcpToolName}.`,
+		`Call MCP name ${options.mcpToolName} (pi tool: ${options.piToolName}). Full tool-surface rules are in the session bootstrap prompt.`,
 	].join("\n");
 }

package/src/cursor-incomplete-tool-visibility.ts

@@ -1,34 +1,63 @@
-import {
-	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
-	getCursorReplayDisplayLabel,
-	type CursorReplayLegacyToolName,
-} from "./cursor-tool-names.js";
+import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME } from "./cursor-tool-names.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import {
 	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
 	type DiscardedIncompleteStartedToolCallReason,
 } from "./cursor-sdk-event-debug.js";
-import { getToolArgs, getToolName, normalizeToolName, truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
-import { resolveTranscriptToolName } from "./cursor-web-tool-activity.js";
+import {
+	assembleCursorReplayActivityDetails,
+	parseCursorReplayToolDetails,
+	resolveIncompleteReplayActivitySourceToolName,
+} from "./cursor-replay-tool-details.js";
+import { truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
+import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
 
 export type IncompleteCursorToolDiscardReason = DiscardedIncompleteStartedToolCallReason;
 
-const INCOMPLETE_TITLE_KEYS: Partial<Record<string, CursorReplayLegacyToolName>> = {
-	task: "cursor_task",
-	mcp: "cursor_mcp",
-	generateimage: "cursor_generate_image",
-	recordscreen: "cursor_record_screen",
-	semsearch: "cursor_sem_search",
-	websearch: "cursor_web_search",
-	webfetch: "cursor_web_fetch",
-	createplan: "cursor_create_plan",
-	updatetodos: "cursor_update_todos",
-	readlints: "cursor_read_lints",
-	delete: "cursor_delete",
-	edit: "cursor_edit",
-	write: "cursor_write",
-};
+export interface IncompleteCursorToolRunOutcome {
+	reason: IncompleteCursorToolDiscardReason;
+	assistantTextProduced: boolean;
+}
+
+export interface IncompleteCursorToolRunOutcomeInput {
+	reason?: IncompleteCursorToolDiscardReason;
+	status?: string;
+	signalAborted?: boolean;
+	assistantTextProduced?: boolean;
+}
+
+export type IncompleteCursorToolVisibilityDecision = "emit" | "suppress" | "debugOnly";
+
+export function buildIncompleteCursorToolRunOutcome(
+	outcome: IncompleteCursorToolRunOutcomeInput = {},
+): IncompleteCursorToolRunOutcome {
+	return {
+		reason:
+			outcome.reason ??
+			(outcome.status === "cancelled" || outcome.signalAborted
+				? "abort"
+				: outcome.status === "error"
+					? "sdk-failure"
+					: DISCARDED_INCOMPLETE_TOOL_CALL_REASON),
+		assistantTextProduced: outcome.assistantTextProduced ?? false,
+	};
+}
+
+export function resolveIncompleteCursorToolVisibility(
+	toolCall: unknown,
+	outcome: IncompleteCursorToolRunOutcome,
+): IncompleteCursorToolVisibilityDecision {
+	const visibility = classifyCursorToolVisibility(toolCall);
+	if (
+		outcome.reason === DISCARDED_INCOMPLETE_TOOL_CALL_REASON &&
+		outcome.assistantTextProduced &&
+		visibility.fastLocalDiscovery
+	) {
+		return "debugOnly";
+	}
+	return "emit";
+}
 
 function buildGenericIncompleteActivityTitle(displayName: string): string {
 	if (!displayName || displayName === "unknown") return "Cursor tool";
@@ -49,25 +78,8 @@ export function formatIncompleteCursorToolReasonText(reason: IncompleteCursorToo
 }
 
 export function getIncompleteCursorToolActivityTitle(toolCall: unknown): string {
-	const args = getToolArgs(toolCall);
-	const name = resolveTranscriptToolName(getToolName(toolCall), args);
-	const normalized = normalizeToolName(name).toLowerCase();
-	const labelKey = INCOMPLETE_TITLE_KEYS[normalized];
-	if (labelKey) return getCursorReplayDisplayLabel(labelKey);
-	switch (normalized) {
-		case "read":
-			return "Cursor read";
-		case "shell":
-			return "Cursor shell";
-		case "grep":
-			return "Cursor grep";
-		case "glob":
-			return "Cursor find";
-		case "ls":
-			return "Cursor ls";
-		default:
-			return buildGenericIncompleteActivityTitle(name);
-	}
+	const visibility = classifyCursorToolVisibility(toolCall);
+	return visibility.incompleteTitle ?? buildGenericIncompleteActivityTitle(visibility.displayName);
 }
 
 export function buildIncompleteCursorToolDisplay(
@@ -75,33 +87,44 @@ export function buildIncompleteCursorToolDisplay(
 	reason: IncompleteCursorToolDiscardReason,
 	options: { apiKey?: string } = {},
 ): CursorPiToolDisplay {
-	const args = getToolArgs(toolCall);
-	const transcriptName = resolveTranscriptToolName(getToolName(toolCall), args);
+	const visibility = classifyCursorToolVisibility(toolCall);
 	const activityTitle = getIncompleteCursorToolActivityTitle(toolCall);
 	const headline = `${activityTitle} did not complete`;
 	const reasonText = scrubSensitiveText(formatIncompleteCursorToolReasonText(reason), options.apiKey);
 	const contentText = `${headline}\n${reasonText}`;
+	const details = assembleCursorReplayActivityDetails(
+		resolveIncompleteReplayActivitySourceToolName(visibility.normalizedName),
+		headline,
+		{ summary: reasonText, expandedText: contentText },
+		contentText,
+		true,
+		reasonText,
+	);
 	return {
 		toolName: CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 		args: {
-			cursorToolName: normalizeToolName(transcriptName),
+			cursorToolName: visibility.normalizedName,
 			activityTitle,
 			activitySummary: reasonText,
 			incomplete: true,
 		},
 		result: {
 			content: [{ type: "text", text: contentText }],
-			details: {
-				cursorToolName: normalizeToolName(transcriptName),
-				title: headline,
-				summary: reasonText,
-			},
+			details,
 		},
 		isError: true,
 	};
 }
 
 export function formatIncompleteCursorToolTrace(display: CursorPiToolDisplay): string {
+	const parsed = parseCursorReplayToolDetails(display.result.details);
+	if (parsed?.variant === "activity") {
+		const summary =
+			parsed.summary?.trim() ||
+			(typeof display.args.activitySummary === "string" && display.args.activitySummary.trim()) ||
+			formatIncompleteCursorToolReasonText(DISCARDED_INCOMPLETE_TOOL_CALL_REASON);
+		return `${truncateCursorDisplayLine(parsed.title)}: ${truncateCursorDisplayLine(summary)}\n`;
+	}
 	const details = display.result.details;
 	const detailRecord = details && typeof details === "object" ? (details as Record<string, unknown>) : undefined;
 	const argsRecord = display.args;

package/src/cursor-mcp-timeout-override.ts

@@ -1,17 +1,23 @@
 const CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS = 3_600_000;
+const DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS = 10_000;
+const MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS = 1_000;
 const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;
 const CURSOR_MCP_TOOL_TIMEOUT_MS_ENV = "PI_CURSOR_MCP_TOOL_TIMEOUT_MS";
 const CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS";
+const CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_MS";
+const CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS";
 
 interface CursorMcpToolTimeoutOverrideOptions {
 	timeoutMs?: number;
+	connectTimeoutMs?: number;
 	env?: Record<string, string | undefined>;
 }
 
 interface CursorMcpToolTimeoutOverrideState {
 	installed: boolean;
 	timeoutMs: number;
+	connectTimeoutMs: number;
 	sdkDefaultTimeoutMs: number;
 }
 
@@ -20,7 +26,8 @@ type SetTimeoutHandler = Parameters<GlobalSetTimeout>[0];
 type SetTimeoutDelay = Parameters<GlobalSetTimeout>[1];
 
 let originalSetTimeout: GlobalSetTimeout | undefined;
-let installedTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+let installedToolTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+let installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 
 function parsePositiveNumber(value: string | undefined): number | undefined {
 	const trimmed = value?.trim();
@@ -46,15 +53,47 @@ export function resolveCursorMcpToolTimeoutMs(
 	return DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
 }
 
-export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
+function normalizeConnectTimeoutMs(timeoutMs: number): number {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
+	return Math.min(
+		Math.max(Math.trunc(timeoutMs), MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS),
+		CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
+	);
+}
+
+export function resolveCursorMcpConnectTimeoutMs(
+	env: Record<string, string | undefined> = process.env,
+): number {
+	const explicitMs = parsePositiveNumber(env[CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV]);
+	if (explicitMs !== undefined) return normalizeConnectTimeoutMs(explicitMs);
+
+	const explicitSeconds = parsePositiveNumber(env[CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV]);
+	if (explicitSeconds !== undefined) return normalizeConnectTimeoutMs(explicitSeconds * 1000);
+
+	return DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
+}
+
+function isCursorSdkMcpProtocolTimeoutStack(stack: string | undefined): boolean {
 	if (!stack) return false;
 	return (
 		/(?:node_modules[/\\]@cursor[/\\]sdk|node_modules\/\@cursor\/sdk|@cursor\/sdk\/dist)/.test(stack) &&
-		/\b_setupTimeout\b|\bProtocol\._setupTimeout\b/.test(stack) &&
+		/\b_setupTimeout\b|\bProtocol\._setupTimeout\b/.test(stack)
+	);
+}
+
+export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
+	if (!stack) return false;
+	return (
+		isCursorSdkMcpProtocolTimeoutStack(stack) &&
 		/\bcallTool\b|\bClient\.callTool\b|\bMcpSdkClient\.callTool\b/.test(stack)
 	);
 }
 
+export function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
+	if (!stack || !isCursorSdkMcpProtocolTimeoutStack(stack)) return false;
+	return /\bClient\.(?:connect|listTools)\b|\bMcpSdkClient\.getTools\b/.test(stack);
+}
+
 function isCursorSdkDefaultMcpTimeout(delay: SetTimeoutDelay): boolean {
 	return typeof delay === "number" && delay === CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS;
 }
@@ -67,10 +106,15 @@ function patchedSetTimeout(
 	const delegate = originalSetTimeout;
 	if (!delegate) throw new Error("Cursor MCP timeout override installed without original setTimeout");
 
-	const nextDelay =
-		isCursorSdkDefaultMcpTimeout(delay) && isCursorSdkMcpToolTimeoutStack(new Error().stack)
-			? installedTimeoutMs
-			: delay;
+	let nextDelay = delay;
+	if (isCursorSdkDefaultMcpTimeout(delay)) {
+		const stack = new Error().stack;
+		if (isCursorSdkMcpToolTimeoutStack(stack)) {
+			nextDelay = installedToolTimeoutMs;
+		} else if (isCursorSdkMcpConnectTimeoutStack(stack)) {
+			nextDelay = installedConnectTimeoutMs;
+		}
+	}
 
 	return Reflect.apply(delegate, globalThis, [handler, nextDelay, ...args]) as ReturnType<GlobalSetTimeout>;
 }
@@ -78,9 +122,12 @@ function patchedSetTimeout(
 export function installCursorMcpToolTimeoutOverride(
 	options: CursorMcpToolTimeoutOverrideOptions = {},
 ): CursorMcpToolTimeoutOverrideState {
-	installedTimeoutMs = normalizeOverrideTimeoutMs(
+	installedToolTimeoutMs = normalizeOverrideTimeoutMs(
 		options.timeoutMs ?? resolveCursorMcpToolTimeoutMs(options.env),
 	);
+	installedConnectTimeoutMs = normalizeConnectTimeoutMs(
+		options.connectTimeoutMs ?? resolveCursorMcpConnectTimeoutMs(options.env),
+	);
 
 	if (!originalSetTimeout) {
 		originalSetTimeout = globalThis.setTimeout;
@@ -89,23 +136,31 @@ export function installCursorMcpToolTimeoutOverride(
 
 	return {
 		installed: true,
-		timeoutMs: installedTimeoutMs,
+		timeoutMs: installedToolTimeoutMs,
+		connectTimeoutMs: installedConnectTimeoutMs,
 		sdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
 	};
 }
 
-export function restoreCursorMcpToolTimeoutOverrideForTests(): void {
+export function restoreCursorMcpToolTimeoutOverride(): void {
 	if (originalSetTimeout) {
 		globalThis.setTimeout = originalSetTimeout;
 		originalSetTimeout = undefined;
 	}
-	installedTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+	installedToolTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+	installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 }
 
+export const restoreCursorMcpToolTimeoutOverrideForTests = restoreCursorMcpToolTimeoutOverride;
+
 export const cursorMcpToolTimeoutOverrideDefaults = {
 	cursorSdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
 	defaultOverrideTimeoutMs: DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS,
+	defaultConnectTimeoutMs: DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS,
+	minConnectTimeoutMs: MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS,
 	maxNodeTimerDelayMs: MAX_NODE_TIMER_DELAY_MS,
 	timeoutMsEnv: CURSOR_MCP_TOOL_TIMEOUT_MS_ENV,
 	timeoutSecondsEnv: CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV,
+	connectTimeoutMsEnv: CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV,
+	connectTimeoutSecondsEnv: CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV,
 } as const;

package/src/cursor-native-tool-display-registration.ts

@@ -13,12 +13,19 @@ import {
 	NATIVE_CURSOR_TOOL_DISPLAY_ENV,
 	readBooleanEnv,
 	registeredNativeToolNames,
+	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-names.js";
 
-const CORE_PI_TOOL_NAMES = new Set(["read", "bash", "edit", "write"]);
+export const CURSOR_CORE_PI_REPLAY_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
+const CORE_PI_TOOL_NAMES = new Set<string>(CURSOR_CORE_PI_REPLAY_TOOL_NAMES);
 
-type CursorNativeToolRegistryApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "registerTool" | "setActiveTools">;
+function isCursorCorePiReplayToolName(toolName: string): toolName is (typeof CURSOR_CORE_PI_REPLAY_TOOL_NAMES)[number] {
+	return CORE_PI_TOOL_NAMES.has(toolName);
+}
+
+type CursorNativeToolActivationApi = Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">;
+type CursorNativeToolRegistryApi = CursorNativeToolActivationApi & Pick<ExtensionAPI, "getAllTools" | "registerTool">;
 
 export interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi {
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
@@ -34,7 +41,40 @@ function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: Nati
 
 type NativeRegistrationContext = { hasUI: boolean; ui: Pick<ExtensionContext["ui"], "notify">; model?: ExtensionContext["model"] };
 
-export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
+function registerNativeCursorToolsFromSet(
+	pi: CursorNativeToolRegistryApi,
+	toolNames: readonly NativeCursorToolName[],
+): NativeCursorToolName[] {
+	const newlySkippedToolNames: NativeCursorToolName[] = [];
+	for (const toolName of toolNames) {
+		if (registeredNativeToolNames.has(toolName) || skippedNativeToolNames.has(toolName)) continue;
+		if (hasNonBuiltinTool(pi, toolName)) {
+			skippedNativeToolNames.add(toolName);
+			newlySkippedToolNames.push(toolName);
+			continue;
+		}
+		registerNativeCursorTool(pi, toolName);
+		registeredNativeToolNames.add(toolName);
+	}
+	return newlySkippedToolNames;
+}
+
+function notifySkippedNativeCursorToolsIfNeeded(ctx: NativeRegistrationContext, skippedToolNames: readonly NativeCursorToolName[]): void {
+	if (skippedToolNames.length === 0 || readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) !== true || !ctx.hasUI) return;
+	ctx.ui.notify(
+		`Cursor native tool replay skipped for ${skippedToolNames.join(", ")} because another extension already provides ${skippedToolNames.length === 1 ? "that tool" : "those tools"}. Cursor will use scrubbed activity transcripts for skipped tools.`,
+		"warning",
+	);
+}
+
+function hasAttemptedNativeCursorToolRegistration(): boolean {
+	return registeredNativeToolNames.size > 0 || skippedNativeToolNames.size > 0;
+}
+
+export function syncRegisteredNativeCursorToolsForModel(
+	pi: CursorNativeToolActivationApi,
+	model: ExtensionContext["model"],
+): void {
 	if (registeredNativeToolNames.size === 0) return;
 	const activeToolNames = new Set(pi.getActiveTools());
 	let changed = false;
@@ -47,7 +87,7 @@ export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "
 		}
 	} else {
 		for (const toolName of registeredNativeToolNames) {
-			if (CORE_PI_TOOL_NAMES.has(toolName)) continue;
+			if (isCursorCorePiReplayToolName(toolName)) continue;
 			if (!activeToolNames.delete(toolName)) continue;
 			changed = true;
 		}
@@ -55,45 +95,41 @@ export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-function registerAvailableNativeCursorTools(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	if (!isCursorNativeToolRegistrationRequested()) {
 		registeredNativeToolNames.clear();
+		skippedNativeToolNames.clear();
 		return;
 	}
+	if (!isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
 
-	const skippedToolNames: string[] = [];
-	for (const toolName of NATIVE_CURSOR_TOOL_NAMES) {
-		if (registeredNativeToolNames.has(toolName)) continue;
-		if (hasNonBuiltinTool(pi, toolName)) {
-			skippedToolNames.push(toolName);
-			continue;
-		}
-		registerNativeCursorTool(pi, toolName);
-		registeredNativeToolNames.add(toolName);
-	}
-
-	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
+	const skippedToolNames = [
+		...registerNativeCursorToolsFromSet(pi, nonCoreToolNames),
+		...registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES),
+	];
+	notifySkippedNativeCursorToolsIfNeeded(ctx, skippedToolNames);
+}
 
-	if (skippedToolNames.length > 0 && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) === true && ctx.hasUI) {
-		ctx.ui.notify(
-			`Cursor native tool replay skipped for ${skippedToolNames.join(", ")} because another extension already provides ${skippedToolNames.length === 1 ? "that tool" : "those tools"}. Cursor will use scrubbed activity transcripts for skipped tools.`,
-			"warning",
-		);
+function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+	if (isCursorModel(ctx.model) && !hasAttemptedNativeCursorToolRegistration()) {
+		ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	}
+	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 
 export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
 	pi.on("session_start", (_event, ctx) => {
-		registerAvailableNativeCursorTools(pi, ctx);
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 	pi.on("before_agent_start", (_event, ctx) => {
-		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 	pi.on("turn_start", (_event, ctx) => {
-		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
-	pi.on("model_select", (event) => {
-		syncRegisteredNativeCursorToolsForModel(pi, event.model);
+	pi.on("model_select", (event, ctx) => {
+		ensureThenSyncNativeCursorToolsForModel(pi, { ...ctx, model: event.model });
 	});
 }