pi-cursor-sdk 0.5.0 → 0.5.3

package/src/cursor-provider-binding.ts

@@ -1,5 +1,8 @@
-import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
-import { CURSOR_API_KEY_CONFIG_VALUE } from "./cursor-api-key.js";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Model, Provider } from "@earendil-works/pi-ai";
+import { cursorApiKeyAuth, normalizeCursorApiKey, resolveCursorCredentialApiKey } from "./cursor-api-key.js";
+import { discoverModels, type CursorModelFallbackIssue } from "./model-discovery.js";
+import { clearModelListCache } from "./model-list-cache.js";
 import { captureCursorCloudLifecycleRecorder } from "./cursor-cloud-lifecycle.js";
 import { captureCursorUsageRecorder, type CursorUsageRecorder } from "./cursor-usage-ledger.js";
 import { getCursorNativeToolDisplayState } from "./cursor-native-tool-display-state.js";
@@ -7,24 +10,30 @@ import { getRegisteredCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { createCursorLazyStream } from "./cursor-provider-lazy.js";
 import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 import { captureCursorRequestProjection, resolveCursorRequestProvenance, type CursorRequestProjectionSnapshot, type CursorRequestProvenance } from "./cursor-request-provenance.js";
+import type { CursorSdkOutputNoticeHandler } from "./cursor-sdk-output-filter.js";
 
-export const CURSOR_PROVIDER_OWNERSHIP_ERROR = "Cursor provider ownership is unavailable: this request does not belong to the active Cursor registration. Bind this session's extensions and refresh Cursor models/reload it; use independent ModelRuntime instances for sibling sessions.";
+export const CURSOR_PROVIDER_OWNERSHIP_ERROR = "Cursor provider ownership is unavailable: this request does not belong to the active Cursor registration. Reload this session's extensions to restore its Cursor registration; use independent ModelRuntime instances for sibling sessions.";
 interface ProviderBinding { active: boolean; closed: boolean }
 interface RequestReceipt {
 	binding: ProviderBinding;
 	scope: ReturnType<typeof getCursorSessionScopeSnapshot>;
 	projection: CursorRequestProjectionSnapshot;
 	usageRecorder: CursorUsageRecorder;
+	reportSdkNotice: CursorSdkOutputNoticeHandler;
 }
 const requestOwners = new WeakMap<object, RequestReceipt>();
 
 /** One closure per ExtensionAPI, including direct compaction/tree/bug-report streams. */
-export function registerCursorProviderBinding(pi: Pick<ExtensionAPI, "on" | "registerProvider" | "appendEntry">) {
+export function registerCursorProviderBinding(
+	pi: Pick<ExtensionAPI, "on" | "registerProvider" | "appendEntry">,
+) {
 	const binding: ProviderBinding = { active: false, closed: false };
+	let registry: ExtensionContext["modelRegistry"] | undefined;
 	const operations = new WeakMap<AbortSignal, CursorRequestProvenance["purpose"]>();
 	pi.on("session_before_compact", (event) => { operations.set(event.signal, "compaction"); });
 	pi.on("session_before_tree", (event) => { operations.set(event.signal, "tree"); });
 	pi.on("before_provider_headers", (event, ctx) => {
+		const notices = new Set<string>();
 		// Pi's SDK supplies this session-owned callback for ordinary and auxiliary
 		// streams. ModelRuntime forwards the same real headers object to the provider.
 		requestOwners.set(event.headers, {
@@ -32,6 +41,14 @@ export function registerCursorProviderBinding(pi: Pick<ExtensionAPI, "on" | "reg
 			scope: getCursorSessionScopeSnapshot(pi),
 			projection: captureCursorRequestProjection(ctx.sessionManager),
 			usageRecorder: captureCursorUsageRecorder(pi, ctx),
+			reportSdkNotice: (kind, message) => {
+				if (!binding.active || binding.closed) return false;
+				if (notices.has(kind)) return;
+				pi.appendEntry("pi-cursor-sdk:capability-notice", { kind, message });
+				if (ctx.hasUI) ctx.ui.notify(message, "warning");
+				else console.warn(message);
+				notices.add(kind);
+			},
 		});
 	});
 	const stream = createCursorLazyStream((model, context, options) => {
@@ -48,15 +65,57 @@ export function registerCursorProviderBinding(pi: Pick<ExtensionAPI, "on" | "reg
 			bridge: getRegisteredCursorPiToolBridge(pi),
 			nativeDisplay: getCursorNativeToolDisplayState(pi),
 			recordCloudLifecycle: captureCursorCloudLifecycleRecorder(pi),
+			reportSdkNotice: owner.reportSdkNotice,
 		};
 	});
-	pi.on("session_start", () => { if (!binding.closed) binding.active = true; });
-	pi.on("session_shutdown", () => { binding.active = false; binding.closed = true; });
-	return (models: ProviderModelConfig[]) => {
+	pi.on("session_start", async (_event, ctx) => {
 		if (binding.closed) return;
-		pi.registerProvider("cursor", {
-			name: "Cursor", baseUrl: "https://cursor.com", apiKey: CURSOR_API_KEY_CONFIG_VALUE,
-			api: "cursor-sdk", models, streamSimple: stream,
-		});
+		binding.active = true;
+		registry = ctx.modelRegistry;
+		// The genuine extension context supplies composed config auth; startup
+		// selection already has the known baseline, without reading a default store.
+		await registry.refresh({ providers: ["cursor"], allowNetwork: false });
+	});
+	pi.on("session_shutdown", () => { binding.active = false; binding.closed = true; registry = undefined; });
+	return (models: Awaited<ReturnType<typeof discoverModels>>, onCatalog: (issue?: CursorModelFallbackIssue) => void) => {
+		if (binding.closed) return;
+		const toNative = (definitions: typeof models): Model<"cursor-sdk">[] =>
+			definitions.map(({ compat: _compat, ...definition }) => ({
+				...definition, provider: "cursor", api: "cursor-sdk", baseUrl: "https://cursor.com",
+			}));
+		let current = toNative(models);
+		const provider: Provider<"cursor-sdk"> = {
+			id: "cursor", name: "Cursor", baseUrl: "https://cursor.com",
+			auth: { apiKey: cursorApiKeyAuth() },
+			getModels: () => current,
+			stream: stream,
+			streamSimple: stream,
+			async refreshModels(context) {
+				if (binding.closed) return;
+				const resolved = await registry?.getProviderAuth("cursor");
+				context.signal.throwIfAborted();
+				const credential = context.credential;
+				const apiKey = registry
+					? normalizeCursorApiKey(resolved?.auth.apiKey)
+					: credential && credential.type !== "api_key" ? undefined
+						: await resolveCursorCredentialApiKey(credential, async () => process.env.CURSOR_API_KEY);
+				let issue: CursorModelFallbackIssue | undefined;
+				await discoverModels({
+					apiKey, allowNetwork: context.allowNetwork, forceRefresh: context.force, signal: context.signal,
+					onFallback: (next) => { issue = next; },
+					publish: (definitions, update) => context.publish({
+						update: () => {
+							if (binding.closed) return;
+							update();
+							current = toNative(definitions);
+							// Do not infer logout before native composed auth is reachable.
+							if (registry && !apiKey) clearModelListCache();
+							onCatalog(issue);
+						},
+					}),
+				});
+			},
+		};
+		pi.registerProvider(provider);
 	};
 }

package/src/cursor-provider-errors.ts

@@ -143,7 +143,10 @@ function collectConnectErrorStacks(error: unknown, record: Record<string, unknow
 
 function isConnectError(error: unknown, record: Record<string, unknown> | undefined): boolean {
 	const name = error instanceof Error ? error.name : getErrorStringField(record, "name");
-	return name === "ConnectError";
+	if (name === "ConnectError") return true;
+	// @cursor/sdk convertConnectError re-wraps backend ConnectErrors (name -> NetworkError,
+	// code -> "unavailable") and leaves the original ConnectError on `.cause` without outer details.
+	return getErrorStringField(asRecord(record?.cause), "name") === "ConnectError";
 }
 
 function isUnauthenticatedConnectCode(code: unknown): boolean {
@@ -160,13 +163,12 @@ function isCursorSdkStallAbortNetworkError(code: unknown, evidence: string, stac
 		/(?:operation was aborted|canceled)/i.test(evidence) &&
 		/(?:AbortError|operation was aborted)/i.test(`${evidence}\n${stackEvidence}`) &&
 		stackEvidence.includes("@cursor/sdk") &&
-		stackEvidence.includes("@connectrpc/connect-node") &&
 		/\b(?:onStall|reportStall|StallDetected)\b/i.test(stackEvidence)
 	);
 }
 
 /**
- * @cursor/sdk@1.0.32 throws internal RetriableError (name/kind "RetriableError") with message
+ * @cursor/sdk@1.0.37 throws internal RetriableError (name/kind "RetriableError") with message
  * "Connection stalled" or "Connection stalled repeatedly" after fetchWithRetry exhausts stalls.
  * The ConnectError is only the cause; the top-level error is not a ConnectError.
  */
@@ -181,30 +183,26 @@ export function isCursorSdkConnectionStalledError(error: unknown): boolean {
 	return /(?:^|[\\/])node_modules[\\/]@cursor[\\/]sdk[\\/]dist[\\/]/.test(stack) || stack.includes("@cursor/sdk");
 }
 
-function isCursorExtensionConnectStack(stack: string): boolean {
-	// pi runs Cursor SDK in Node, where the SDK dynamically imports connect-node.
-	// connect-web is the SDK's Bun/Deno path and is intentionally not classified for supported pi runs.
-	return stack.includes("@connectrpc/connect-node") && /(?:^|[\\/])pi-cursor-sdk(?:[\\/]|$)/.test(stack);
-}
-
 function getCursorConnectSource(error: unknown, record: Record<string, unknown> | undefined): CursorConnectErrorSource {
-	const stack = getErrorStack(error, record);
+	const stack = collectConnectErrorStacks(error, record);
+	// Node/Bun use the SDK's vendored transport; Deno uses connect-web.
 	if (stack.includes("@cursor/sdk")) return "cursor-sdk-stack";
-	if (isCursorExtensionConnectStack(stack)) return "cursor-extension-connect-stack";
-	const details = Array.isArray(record?.details) ? record.details : [];
-	const hasCursorBackendDetails = details.some((detail) => {
-		const type = getErrorStringField(asRecord(detail), "type");
-		return typeof type === "string" && type.startsWith("aiserver.");
-	});
-	if (hasCursorBackendDetails) return "cursor-backend-details";
-	return stack.includes("@connectrpc/connect-node") ? "connect-node-stack" : "generic-connect";
+	let current = record;
+	for (let depth = 0; depth < 3 && current; depth += 1) {
+		const details = Array.isArray(current.details) ? current.details : [];
+		const hasCursorBackendDetails = details.some((detail) => {
+			const type = getErrorStringField(asRecord(detail), "type");
+			return typeof type === "string" && type.startsWith("aiserver.");
+		});
+		if (hasCursorBackendDetails) return "cursor-backend-details";
+		current = asRecord(current.cause);
+	}
+	return "generic-connect";
 }
 
 export type CursorConnectErrorSource =
 	| "cursor-sdk-stack"
-	| "cursor-extension-connect-stack"
 	| "cursor-backend-details"
-	| "connect-node-stack"
 	| "generic-connect";
 
 export type CursorConnectErrorClassification =
@@ -225,20 +223,26 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 	const evidence = collectConnectErrorEvidence(error, record);
 	const stackEvidence = collectConnectErrorStacks(error, record);
 
+	if (isCursorSdkStallAbortNetworkError(code, evidence, stackEvidence)) {
+		return { kind: "network", source: getCursorConnectSource(error, record) };
+	}
+
+	const directAbort = (code === 1 || code === "canceled") &&
+		(causeName === "AbortError" || /AbortError/.test(stack));
+	// The vendored SDK transport can wrap a canceled ConnectError as Unknown.
+	// Require the observed canceled -> AbortError cause chain, not generic text.
+	const wrappedAbort = (code === 2 || code === "unknown") &&
+		causeName === "ConnectError" &&
+		(cause?.code === 1 || cause?.code === "canceled") &&
+		asRecord(cause?.cause)?.name === "AbortError";
 	if (
-		(code === 1 || code === "canceled") &&
+		(directAbort || wrappedAbort) &&
 		Boolean(rawMessage && /(?:operation was aborted|canceled)/i.test(rawMessage)) &&
-		(causeName === "AbortError" || /AbortError/.test(stack)) &&
-		stack.includes("@cursor/sdk") &&
-		stack.includes("@connectrpc/connect-node")
+		stack.includes("@cursor/sdk")
 	) {
 		return { kind: "abort", source: "cursor-sdk-stack" };
 	}
 
-	if (isCursorSdkStallAbortNetworkError(code, evidence, stackEvidence)) {
-		return { kind: "network", source: getCursorConnectSource(error, record) };
-	}
-
 	if (isUnauthenticatedConnectCode(code) || isLikelyAuthError(evidence)) {
 		return { kind: "unauthenticated", source: getCursorConnectSource(error, record) };
 	}

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

@@ -30,13 +30,18 @@ import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-rout
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export 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);
+	return value >= 1 && value <= 2147483647 ? value : DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+}
 const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
 
 interface CursorLiveTurnState {
 	emitter: CursorPartialContentEmitter;
 	emittedText: string;
 }
-let cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+let cursorNativeReplayIdleDisposeMsOverride: number | undefined;
 
 type CursorLiveRunDrainMode = "emit" | "chain_user_input";
 type CursorLiveRunDrainOutcome = "tool_use" | "stop" | "error" | "aborted" | "chain_user_input";
@@ -50,7 +55,7 @@ export async function abandonSessionCursorAgent(scopeKey: string | undefined): P
 }
 
 export const cursorLiveRuns = createCursorLiveRunCoordinator({
-	getIdleDisposeMs: () => cursorNativeReplayIdleDisposeMs,
+	getIdleDisposeMs: () => cursorNativeReplayIdleDisposeMsOverride ?? parseCursorNativeReplayIdleDisposeMs(process.env.PI_CURSOR_LIVE_RUN_IDLE_DISPOSE_MS),
 	deleteNativeToolDisplay: deleteCursorNativeToolDisplay,
 	abandonSessionAgent: (scopeKey) => abandonSessionCursorAgent(scopeKey),
 });
@@ -497,11 +502,11 @@ export async function drainExistingCursorLiveRunBeforeSend(
 }
 
 export function setCursorNativeReplayIdleDisposeMs(value: number): void {
-	cursorNativeReplayIdleDisposeMs = value;
+	cursorNativeReplayIdleDisposeMsOverride = value;
 }
 
 export function resetCursorNativeReplayIdleDisposeMs(): void {
-	cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+	cursorNativeReplayIdleDisposeMsOverride = undefined;
 }
 
 export async function releaseAllPendingCursorLiveRunsForTests(): Promise<void> {

package/src/cursor-provider-run-finalizer.ts

@@ -145,12 +145,12 @@ export class CursorRunFinalizer {
 		sendResult: CursorProviderTurnSendResult | undefined,
 		liveCompletion: CursorLiveRunCompletion | undefined,
 	): Promise<void> {
-		this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
 		const abortRegistration = sendResult?.abortRegistration;
 		this.params.runnerParams.sdkEventDebugRef.current = undefined;
 		if (liveCompletion) {
 			void liveCompletion.waitCompletion
 				.finally(async () => {
+					this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
 					if (abortRegistration) {
 						this.safeCleanup(() => abortRegistration.signal.removeEventListener("abort", abortRegistration.listener));
 					}
@@ -160,6 +160,7 @@ export class CursorRunFinalizer {
 				.catch(() => {});
 			return;
 		}
+		this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
 		if (abortRegistration) {
 			this.safeCleanup(() => abortRegistration.signal.removeEventListener("abort", abortRegistration.listener));
 		}

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

@@ -1,6 +1,6 @@
 import type { Context, SimpleStreamOptions } from "@earendil-works/pi-ai";
 import { getCursorConversationMessages, resolveCursorPiContext } from "./cursor-pi-context.js";
-import type { AgentModeOption, ModelSelection, SDKAgent } from "@cursor/sdk";
+import type { AgentModeOption, AgentOptions, ModelSelection, SDKAgent } from "@cursor/sdk";
 import { configureCursorSdkHttp1 } from "./cursor-http1.js";
 import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
 import { ensureCursorRipgrepPath } from "./cursor-ripgrep-path.js";
@@ -13,7 +13,7 @@ import {
 	type CursorSessionSendPlan,
 } from "./cursor-session-agent.js";
 import type { CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
-import { buildCursorPrompt, estimateCursorPromptTokens } from "./context.js";
+import { buildCursorPrompt, estimateCursorPromptTokens, getCursorPendingInput } from "./context.js";
 import { getCursorPromptOptions } from "./cursor-usage-accounting.js";
 import { getActiveContextToolNames } from "./cursor-context-tools.js";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
@@ -29,6 +29,7 @@ import {
 } from "./cursor-state.js";
 import { resolveEffectiveCursorConfig } from "./cursor-runtime-state.js";
 import type { CursorResolvedSdkConfig } from "./cursor-config.js";
+import { buildCursorCustomSubagentDefinitions } from "./cursor-custom-subagent-definitions.js";
 import { buildCursorModelSelection } from "./model-discovery.js";
 import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
 import {
@@ -74,14 +75,20 @@ interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnPara
 	agentMode: AgentModeOption;
 	selection: ModelSelection;
 	fastEnabled: boolean | undefined;
+	agents: AgentOptions["agents"];
+	customSubagentNames: string[] | undefined;
 }
 
-function buildCursorCloudPromptContext(context: Context, handoff: "fresh" | "bootstrap" | "never"): Context {
+function buildCursorCloudPromptContext(context: Context, handoff: "fresh" | "bootstrap" | "never", nativeSourceRoles?: readonly string[]): Context {
 	if (handoff === "bootstrap") return context;
 	// Fresh cloud runs omit history, not the current Pi instructions. Replay before
 	// selecting the user message, otherwise transcript-only inputs lose the prompt.
 	const current = resolveCursorPiContext(context);
 	const messages = getCursorConversationMessages(context);
+	if (nativeSourceRoles) {
+		const { start } = getCursorPendingInput(messages, nativeSourceRoles);
+		return { ...current, messages: messages.slice(start) };
+	}
 	for (let index = messages.length - 1; index >= 0; index -= 1) {
 		const message = messages[index];
 		if (message.role === "user") return { ...current, messages: [message] };
@@ -121,7 +128,7 @@ function buildLocalCursorProviderTurnLifecycle(
 async function prepareCursorCloudProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<CloudCursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -146,16 +153,16 @@ async function prepareCursorCloudProviderTurn(
 
 		const { Agent } = await loadCursorSdk();
 		restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+		const promptContext = buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value, params.request.nativeSourceRoles);
+		const nativeSourceRoles = params.request.nativeSourceRoles;
 		const promptOptions = {
 			...getCursorPromptOptions(model),
+			nativeSourceRoles: nativeSourceRoles?.slice(nativeSourceRoles.length - getCursorConversationMessages(promptContext).length),
 			agentMode,
 			includePiBridgeGuidance: false,
 			includePiAskQuestionGuidance: false,
 		};
-		const prompt = buildCursorPrompt(
-			buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value),
-			promptOptions,
-		);
+		const prompt = buildCursorPrompt(promptContext, promptOptions);
 		const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
 		const agent = await suppressCursorSdkOutput(() =>
 			Agent.create(buildCursorCloudAgentOptions({
@@ -164,6 +171,7 @@ async function prepareCursorCloudProviderTurn(
 				agentMode,
 				resolvedConfig,
 				name: params.scope.sessionName,
+				agents,
 			})),
 		);
 		cloudAgentForCleanup = agent;
@@ -201,6 +209,7 @@ async function prepareCursorCloudProviderTurn(
 			promptOptions,
 			agentMode,
 			localForce: false,
+			...(customSubagentNames ? { customSubagentNames } : {}),
 		});
 
 		completed = true;
@@ -243,7 +252,7 @@ async function prepareCursorCloudProviderTurn(
 async function prepareCursorLocalProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<LocalCursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -279,7 +288,9 @@ async function prepareCursorLocalProviderTurn(
 			modelSelection: selection,
 			settingSources,
 			localSafety,
+			agents,
 			localResume: resolvedConfig.local.resume.value,
+			storeRoot: resolvedConfig.local.storeRoot.value,
 			useHttp1ForAgent,
 			debugRecorder: sdkEventDebug,
 			onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
@@ -301,9 +312,10 @@ async function prepareCursorLocalProviderTurn(
 		const buildPromptOptions = (plan: ReturnType<typeof planCursorSessionSend>) => {
 			const promptOptions = {
 				...getCursorPromptOptions(model),
+				nativeSourceRoles: params.request.nativeSourceRoles,
 				agentMode,
 				includePiBridgeGuidance,
-				includePiAskQuestionGuidance: bridgeToolNames.has("pi__cursor_ask_question"),
+				includePiAskQuestionGuidance: false,
 			};
 			if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
 				return promptOptions;
@@ -317,7 +329,7 @@ async function prepareCursorLocalProviderTurn(
 				}),
 			};
 		};
-		let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+		let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context, params.request.nativeSourceRoles);
 		if (sessionAgentLease.created && sessionAgentLease.resumed && sendPlan.mode === "incremental") {
 			sendPlan = { mode: "bootstrap", resetAgent: false, reason: "process_resume" };
 		}
@@ -329,7 +341,7 @@ async function prepareCursorLocalProviderTurn(
 			sessionAgentScopeKey = sessionAgentLease.scopeKey;
 			bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
 			includePiBridgeGuidance = bridgeToolNames.size > 0;
-			sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+			sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context, params.request.nativeSourceRoles);
 			promptOptions = buildPromptOptions(sendPlan);
 			prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
 		}
@@ -365,6 +377,7 @@ async function prepareCursorLocalProviderTurn(
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
 			bridgeRunId: bridgeRun?.id,
+			...(customSubagentNames ? { customSubagentNames } : {}),
 		});
 		const nativeReplayId = createCursorNativeReplayId();
 		const textDeltas: string[] = [];
@@ -461,7 +474,9 @@ export async function prepareCursorProviderTurn(
 		return prepareCursorSummaryProviderTurn(prepareParams, selection);
 	}
 	const agentMode = getCursorProviderAgentModeOrThrow(params.scope.scopeKey);
-	const context: PrepareCursorProviderTurnContext = { ...prepareParams, agentMode, selection, fastEnabled };
+	const agents = buildCursorCustomSubagentDefinitions(resolvedConfig.subagents.value);
+	const customSubagentNames = agents ? Object.keys(agents) : undefined;
+	const context: PrepareCursorProviderTurnContext = { ...prepareParams, agentMode, selection, fastEnabled, agents, customSubagentNames };
 
 	return resolvedConfig.runtime.value === "cloud"
 		? prepareCursorCloudProviderTurn(context)

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, hasResumeHandle: false,
+			cwd, scopeKey: params.scope.persistentScopeKey ?? params.scope.scopeKey, persistent: false,
 		})).sessionStore;
 		throwIfAborted();
 		agent = await suppressCursorSdkOutput(() => sdk.Agent.create({

package/src/cursor-provider-turn-tool-ledger.ts

@@ -1,3 +1,4 @@
+import { normalizeCursorToolName } from "./cursor-tool-presentation-registry.js";
 import { getToolArgs, getToolName } from "./cursor-transcript-utils.js";
 
 export type CursorToolDisplaySource = "started" | "fallback" | "transcript";
@@ -53,12 +54,12 @@ export class CursorToolCompletionLedger {
 			return stepId;
 		}
 		const fingerprint = getStartedToolCallFingerprint(toolCall);
-		for (const [callId, startedToolCall] of this.startedToolCalls) {
-			if (getStartedToolCallFingerprint(startedToolCall) !== fingerprint) continue;
-			this.clearStartedToolCall(callId);
-			return callId;
-		}
-		return undefined;
+		const matches = [...this.startedToolCalls].filter(([, started]) => getStartedToolCallFingerprint(started) === fingerprint);
+		// Identical concurrent shells cannot be joined safely without a matching ID.
+		if (normalizeCursorToolName(getToolName(toolCall)) === "shell" && matches.length !== 1) return undefined;
+		const callId = matches[0]?.[0];
+		if (callId !== undefined) this.clearStartedToolCall(callId);
+		return callId;
 	}
 
 	recordCompletedIdentity(identity: string): void {
@@ -121,5 +122,9 @@ export function getToolFingerprint(value: unknown): string {
 }
 
 export function getStartedToolCallFingerprint(toolCall: unknown): string {
-	return getToolFingerprint({ toolName: getToolName(toolCall), args: getToolArgs(toolCall) });
+	const name = getToolName(toolCall);
+	// Accept legacy shell aliases; this does not establish that the SDK emits alias-changing pairs.
+	// Keep exact argument matching; assistant text alone is not completion proof.
+	const toolName = normalizeCursorToolName(name) === "shell" ? "shell" : name;
+	return getToolFingerprint({ toolName, args: getToolArgs(toolCall) });
 }

package/src/cursor-provider.ts

@@ -29,6 +29,7 @@ import type { CursorCloudLifecycleRecorder } from "./cursor-cloud-lifecycle.js";
 import type { CursorRequestProvenance } from "./cursor-request-provenance.js";
 import type { CursorUsageRecorder } from "./cursor-usage-ledger.js";
 import { runExclusiveCursorSessionTurn, __testUtils as cursorSessionTurnQueueTestUtils } from "./cursor-session-turn-queue.js";
+import { withCursorSdkOutputNoticeHandler, type CursorSdkOutputNoticeHandler } from "./cursor-sdk-output-filter.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -57,6 +58,7 @@ export interface CursorProviderOwnership {
 	recordCloudLifecycle: CursorCloudLifecycleRecorder;
 	request: CursorRequestProvenance;
 	usageRecorder: CursorUsageRecorder;
+	reportSdkNotice?: CursorSdkOutputNoticeHandler;
 }
 
 export function streamCursor(
@@ -92,7 +94,7 @@ export function streamCursor(
 			stream.push({ type: "start", partial });
 			await runExclusiveCursorSessionTurn(
 				scope.scopeKey,
-				() => runner.run(installCursorSdkProcessErrorGuard()),
+				() => withCursorSdkOutputNoticeHandler(ownership.reportSdkNotice, () => runner.run(installCursorSdkProcessErrorGuard())),
 				options?.signal,
 			);
 		} catch (error) {

package/src/cursor-question-tool.ts

@@ -11,7 +11,7 @@ export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
 export const CURSOR_ASK_QUESTION_ENV = "PI_CURSOR_ASK_QUESTION";
 
 export function resolveCursorAskQuestionEnabled(env: Record<string, string | undefined> = process.env): boolean {
-	return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], true);
+	return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], false);
 }
 
 /** Package-namespaced event while `cursor_ask_question` awaits pi UI input. */
@@ -216,13 +216,13 @@ export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi):
 		name: CURSOR_ASK_QUESTION_TOOL_NAME,
 		label: "Cursor question",
 		description:
-			"Ask the user a clarifying question from Cursor. Use when user preferences materially affect the next step; provide options when possible.",
-		promptSnippet: "Ask the user a clarifying question through pi UI when material choices affect Cursor's next step",
+			"Ask the user a clarifying question through pi UI. Do not use this unless the user asked to be prompted; otherwise proceed with a stated assumption.",
+		promptSnippet: "Do not prompt the user through cursor_ask_question unless they asked to be asked",
 		executionMode: "sequential",
 		parameters: CursorAskQuestionParamsSchema,
 		promptGuidelines: [
-			"Use cursor_ask_question only when running a Cursor model and user input would materially change the plan, scope, platform, or implementation path.",
-			"Prefer cursor_ask_question with 2-4 concrete options instead of guessing when Cursor plan mode needs user choices.",
+			"Do not call cursor_ask_question unless the user explicitly asked to be prompted or to choose among options.",
+			"If this tool is available, prefer a reasonable default and state the assumption instead of blocking on a questionnaire.",
 		],
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const questions = normalizeQuestions(params as CursorAskQuestionParams);

package/src/cursor-request-provenance.ts

@@ -5,6 +5,8 @@ import type { Api, Context, Model } from "@earendil-works/pi-ai";
 export interface CursorRequestProvenance {
 	readonly purpose: "normal" | "compaction" | "tree";
 	readonly occupancyFloor?: number;
+	/** Canonical native source roles in converted conversation order, only for an equivalent request. */
+	readonly nativeSourceRoles?: readonly string[];
 }
 
 interface Measurement {
@@ -14,10 +16,11 @@ interface Measurement {
 	readonly tokens: number;
 }
 
-/** Receipt data contains hashes and scalars only, never conversation text. */
+/** Receipt data contains hashes and source-role/accounting scalars only, never conversation text. */
 export interface CursorRequestProjectionSnapshot {
 	readonly digest: string;
 	readonly measurements: readonly Measurement[];
+	readonly nativeSourceRoles: readonly string[];
 }
 
 function projectionDigest(messages: readonly unknown[]): string {
@@ -49,7 +52,13 @@ export function captureCursorRequestProjection(manager: ExtensionContext["sessio
 			measurements.push(Object.freeze({ api: message.api, provider: message.provider, model: message.model, tokens }));
 		}
 	}
-	return Object.freeze({ digest: projectionDigest(convertToLlm(projection.messages)), measurements: Object.freeze(measurements) });
+	const nativeSourceRoles = projection.messages.flatMap((message) =>
+		message.role === "system" ? [] : convertToLlm([message]).map(() => message.role));
+	return Object.freeze({
+		digest: projectionDigest(convertToLlm(projection.messages)),
+		measurements: Object.freeze(measurements),
+		nativeSourceRoles: Object.freeze(nativeSourceRoles),
+	});
 }
 
 export function resolveCursorRequestProvenance(
@@ -58,7 +67,13 @@ export function resolveCursorRequestProvenance(
 	context: Context,
 	purpose: CursorRequestProvenance["purpose"],
 ): CursorRequestProvenance {
+	// ponytail: canonical native origin only. Unmatched transforms stay conservative;
+	// upgrade if Pi exposes final request-bound source provenance.
 	if (purpose !== "normal" || snapshot.digest !== projectionDigest(context.messages)) return Object.freeze({ purpose });
 	const measurement = snapshot.measurements.findLast((item) => item.api === model.api && item.provider === model.provider && item.model === model.id && item.tokens <= model.contextWindow);
-	return Object.freeze({ purpose, ...(measurement ? { occupancyFloor: measurement.tokens } : {}) });
+	return Object.freeze({
+		purpose,
+		nativeSourceRoles: snapshot.nativeSourceRoles,
+		...(measurement ? { occupancyFloor: measurement.tokens } : {}),
+	});
 }

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

@@ -1,7 +1,9 @@
 export {
 	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	withCursorSdkOutputNoticeHandler,
 	installCursorSdkOutputFilter,
 	isCursorSdkOutputSuppressed,
 	isCursorSdkStartupNoise,
 	suppressCursorSdkOutput,
 } from "../shared/cursor-sdk-output-filter.mjs";
+export type { CursorSdkCapabilityNotice, CursorSdkOutputNoticeHandler } from "../shared/cursor-sdk-output-filter.mjs";

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

@@ -40,7 +40,7 @@ function hasActiveAbortSuppression(): boolean {
 }
 
 function isCursorProvenance(source: string): boolean {
-	return source === "cursor-sdk-stack" || source === "cursor-extension-connect-stack" || source === "cursor-backend-details";
+	return source === "cursor-sdk-stack" || source === "cursor-backend-details";
 }
 
 function isCursorSdkWriteIterableClosedError(error: unknown): boolean {
@@ -83,7 +83,6 @@ function shouldSuppressProcessError(event: string | symbol, args: readonly unkno
 	if (!classification) return false;
 	if (classification.kind === "abort") return hasActiveAbortSuppression();
 	if (activeProviderTurns.size === 0) return false;
-	if (classification.kind === "network") return isCursorProvenance(classification.source) || classification.source === "connect-node-stack";
 	return isCursorProvenance(classification.source);
 }