@emmaneugene/pi-cursor-sdk 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.3 - 2026-09-11
+
+### Fixed
+
+- Keep live Cursor runs open while bridged pi tools await results. Long `cursor_ask_question` waits and other bridge calls now use the bridge CallTool deadline instead of being cancelled by the five-minute inactive-run cleanup.
+
+## 0.4.2 - 2026-09-07
+
+### Fixed
+
+- Register an isolated Cursor provider, SDK agent scope, and pi tool bridge for nested in-process child sessions. A non-Cursor parent can now dispatch a pi subagent with a Cursor model, and a Cursor parent can dispatch a Cursor-model pi subagent without waiting on or disposing its own busy Cursor SDK agent.
+
 ## 0.4.1 - 2026-09-07
 
 ### Fixed

package/README.md

@@ -367,6 +367,8 @@ Local Cursor runs use two separate tool surfaces:
 
 Bridge capabilities are snapshotted from `pi.getActiveTools()` and `pi.getAllTools()` for each Cursor run, including per-tool prompt guidelines when pi exposes them. Cursor sees active bridgeable pi tools as collision-safe MCP names such as `pi__sem_reindex` only when they are exposed in that current run. When exposed, Cursor is instructed to prefer `pi__mcp` for MCP work and `pi__subagent` for delegation; Cursor-configured MCP and Cursor-native subagents are fallbacks when the matching pi tool is not exposed or is unavailable. Pi session output, tool cards, confirmations, hooks, renderers, history, and abort behavior use the real pi tool name, such as `sem_reindex`. The bridge queues Cursor's MCP call, emits a normal pi `toolCall`, waits for the matching pi `toolResult`, and resolves that result back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled. The bridge does not call pi tool `execute()` handlers directly.
 
+Pi subagents can select Cursor models under both Cursor and non-Cursor parents. Each nested Cursor child registers a child-local provider and bridge and uses an isolated SDK agent scope, so it does not replace or wait on the parent's active Cursor agent.
+
 Overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are hidden by default because Cursor local agents already have native equivalents. Extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. The bridge also exposes `cursor_ask_question` as `pi__cursor_ask_question` when enabled, allowing Cursor to ask the user through pi UI instead of silently choosing a default. When pi has visible Agent Skills loaded, the extension rewrites pi's skill catalog for Cursor and exposes `cursor_activate_skill` as `pi__cursor_activate_skill`; Cursor should call that bridge tool with a listed skill name to load the full `SKILL.md` and bundled resource list before applying the skill. If the bridge is disabled, the catalog remains available and instructs Cursor to fall back to reading the listed `SKILL.md` path directly.
 
 Cursor-native tool replay is separate from the bridge. Replay cards are display-only recorded Cursor SDK activity. They never re-run Cursor-side commands, reapply Cursor edits, call MCP servers, or mutate pi state. See [Cursor native tool replay](docs/cursor-native-tool-replay.md).

package/dist/cursor-live-run-coordinator.js

@@ -11,6 +11,11 @@ function isPendingBridgeToolRequest(run, request) {
     const bridgeRun = [run.bridgeRun, run.sessionBridgeRun].find((candidate) => candidate?.id === request.runId);
     return bridgeRun?.hasPendingPiToolCallId(request.piToolCallId) === true;
 }
+function hasPendingBridgeCalls(run) {
+    if (run.bridgeRun?.hasPendingCalls())
+        return true;
+    return run.sessionBridgeRun !== run.bridgeRun && run.sessionBridgeRun?.hasPendingCalls() === true;
+}
 async function cancelCursorLiveSdkRun(run) {
     if (!run.sdkRun)
         return;
@@ -350,6 +355,12 @@ export function createCursorLiveRunCoordinator(deps) {
                 return;
             state.idleDisposeRequested = false;
             state.idleDisposeTimer = setTimeout(() => {
+                if (hasPendingBridgeCalls(run)) {
+                    // Bridge calls have their own deadline. Reuse the idle interval to avoid a hot
+                    // polling loop if the SDK does not emit a terminal event after that deadline.
+                    coordinator.requestIdleDispose(run);
+                    return;
+                }
                 void coordinator.release(run).catch(() => {
                     // Idle dispose must not leave release failures as unhandled rejections.
                 });

package/dist/cursor-pi-tool-bridge-run.js

@@ -126,6 +126,9 @@ export class CursorPiToolBridgeRunImpl {
     async resolveToolResultsFromContext(context) {
         await this.resolveToolResults(context.messages.map(asToolResultMessage).filter((message) => message !== undefined));
     }
+    hasPendingCalls() {
+        return this.pendingCount() > 0;
+    }
     hasPendingPiToolCallId(piToolCallId) {
         return this.pendingByPiToolCallId.has(piToolCallId);
     }

package/dist/cursor-pi-tool-bridge.js

@@ -48,18 +48,9 @@ Get-CimInstance Win32_Process -Filter "Name = 'bash.exe' OR Name = 'sh.exe'" |
         windowsHide: true,
     });
 }
-export function registerCursorPiToolBridge(pi) {
-    // Replacing a bridge during a live MCP run cancels its pending pi tool
-    // calls. Keep the active registry as a final safety belt.
-    if (registeredCursorPiToolBridge?.hasLiveRuns()) {
-        return registeredCursorPiToolBridge;
-    }
-    bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
-    void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
-    const bridge = new CursorPiToolBridgeRegistry(pi);
-    registeredCursorPiToolBridge = bridge;
+function attachCursorPiToolBridgeHandlers(pi, bridge, options) {
     pi.on("tool_call", (event, ctx) => {
-        if (registeredCursorPiToolBridge !== bridge)
+        if (!options.isActive())
             return undefined;
         if (!bridge.hasPendingPiToolCallId(event.toolCallId)) {
             return isCursorPiBridgeToolCallId(event.toolCallId)
@@ -86,9 +77,34 @@ export function registerCursorPiToolBridge(pi) {
     });
     pi.on("session_shutdown", async (event) => {
         const reason = `Cursor pi tool bridge session shutdown: ${event.reason}`;
-        bridgeToolExecutionAbortTracker.abortAll(reason);
+        if (options.abortAllOnShutdown)
+            bridgeToolExecutionAbortTracker.abortAll(reason);
         await bridge.disposeAll(reason);
     });
+}
+export function registerCursorPiToolBridge(pi) {
+    // Replacing a bridge during a live MCP run cancels its pending pi tool
+    // calls. Keep the active registry as a final safety belt.
+    if (registeredCursorPiToolBridge?.hasLiveRuns()) {
+        return registeredCursorPiToolBridge;
+    }
+    bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
+    void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
+    const bridge = new CursorPiToolBridgeRegistry(pi);
+    registeredCursorPiToolBridge = bridge;
+    attachCursorPiToolBridgeHandlers(pi, bridge, {
+        abortAllOnShutdown: true,
+        isActive: () => registeredCursorPiToolBridge === bridge,
+    });
+    return bridge;
+}
+/** Register a bridge owned only by one nested in-process child session. */
+export function registerNestedCursorPiToolBridge(pi) {
+    const bridge = new CursorPiToolBridgeRegistry(pi);
+    attachCursorPiToolBridgeHandlers(pi, bridge, {
+        abortAllOnShutdown: false,
+        isActive: () => true,
+    });
     return bridge;
 }
 export function getRegisteredCursorPiToolBridge() {

package/dist/cursor-provider-lazy.js

@@ -21,11 +21,11 @@ function makeProviderRuntimeErrorMessage(model, error, apiKey) {
         errorMessage: `Cursor provider runtime failed: ${sanitizeCursorProviderError(error, apiKey)}`,
     };
 }
-export function streamCursorLazy(model, context, options) {
+export function streamCursorLazy(model, context, options, runtimeContext) {
     const outer = createAssistantMessageEventStream();
     queueMicrotask(async () => {
         try {
-            for await (const event of streamCursor(model, context, options)) {
+            for await (const event of streamCursor(model, context, options, runtimeContext)) {
                 outer.push(event);
             }
         }

package/dist/cursor-provider-live-run-drain.js

@@ -32,8 +32,8 @@ function getCursorNativeReplayIdFromToolCallId(toolCallId) {
 export function getPendingCursorLiveRun(context) {
     return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId);
 }
-export function getActiveCursorLiveRunForCurrentScope() {
-    return cursorLiveRuns.getActiveForScope();
+export function getActiveCursorLiveRunForScope(scopeKey) {
+    return cursorLiveRuns.getActiveForScope(scopeKey);
 }
 function splitTextIntoReplayDeltas(text) {
     const deltas = [];
@@ -334,10 +334,10 @@ export async function drainCursorLiveRunTurn(stream, partial, model, context, ru
         });
     }
 }
-export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder) {
+export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder, scopeKey) {
     turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
     while (true) {
-        const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
+        const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForScope(scopeKey);
         if (!run || run.disposed) {
             turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
             return "continue_send";

package/dist/cursor-provider-run-finalizer.js

@@ -89,6 +89,7 @@ export class CursorRunFinalizer {
         if (liveCompletion) {
             void liveCompletion.waitCompletion
                 .finally(async () => {
+                await prepared?.lifecycle.dispose().catch(() => { });
                 await this.finalizeSdkEventDebugBestEffort();
                 this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
             })

package/dist/cursor-provider-runtime-context.js

@@ -0,0 +1 @@
+export {};

package/dist/cursor-provider-turn-prepare.js

@@ -20,20 +20,23 @@ import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
-export function resolveCursorProviderTurnConfig(cwd) {
-    return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+export function resolveCursorProviderTurnConfig(cwd, projectTrusted = getCursorSessionProjectTrusted()) {
+    return resolveEffectiveCursorConfig({ cwd, projectTrusted });
 }
-function buildLocalCursorProviderTurnLifecycle(lease, scopeKey) {
+function buildLocalCursorProviderTurnLifecycle(lease, scopeKey, disposeAgentAfterTurn) {
     return {
         trackRunCompletion: (completion) => lease.trackRunCompletion(completion),
         commitSend: (context, bootstrapped) => lease.commitSend(context, bootstrapped),
         abandon: () => abandonSessionCursorAgent(scopeKey),
-        dispose: async () => { },
+        dispose: async () => {
+            if (disposeAgentAfterTurn)
+                await resetSessionCursorAgent(scopeKey);
+        },
     };
 }
 async function prepareCursorLocalProviderTurn(prepareParams) {
     const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
-    const { model, context, options } = params;
+    const { model, context, options, runtimeContext } = params;
     let restoreCursorSdkOutputFilter;
     let sessionAgentScopeKey;
     let liveRun;
@@ -54,6 +57,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         const queuedBridgeRequestsBeforeLiveRun = [];
         let liveRunForBridgeQueue;
         const bridgeExcludeToolNames = buildCursorBridgeExcludeToolNames(resolvedConfig);
+        const localResumeEnabled = runtimeContext?.localResume ?? resolvedConfig.local.resume.value;
         const sessionAgentAcquireParams = {
             apiKey: resolvedApiKey,
             agentMode,
@@ -61,8 +65,12 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             modelSelection: selection,
             settingSources,
             localSafety,
-            localResume: resolvedConfig.local.resume.value,
+            localResume: localResumeEnabled,
             useHttp1ForAgent,
+            runtimeScope: runtimeContext
+                ? { scopeKey: runtimeContext.scopeKey, sessionFile: runtimeContext.sessionFile }
+                : undefined,
+            bridge: runtimeContext?.bridge,
             bridgeExcludeToolNames,
             debugRecorder: sdkEventDebug,
             onBridgeToolRequest: (request) => {
@@ -124,7 +132,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
         };
         const sessionBridgeRun = bridgeRun;
         const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
-        const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+        const useNativeToolReplay = runtimeContext?.nativeToolReplay ?? isCursorNativeToolDisplayRuntimeEnabled();
         const activeToolNames = getActiveContextToolNames(context);
         sdkEventDebug?.recordProviderMeta({
             model: {
@@ -142,7 +150,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             toolManifestEnabled: resolveCursorToolManifestEnabled(),
             agentMode,
             localForce: resolvedConfig.local.force.value,
-            localResume: resolvedConfig.local.resume.value,
+            localResume: localResumeEnabled,
             resumedAgent: sessionAgentLease.resumed,
             activeToolNames: activeToolNames ? [...activeToolNames] : [],
             sessionAgentScopeKey,
@@ -204,7 +212,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             sessionAgentLease,
             localForce: resolvedConfig.local.force,
             restoreCursorSdkOutputFilter,
-            lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey),
+            lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey, runtimeContext?.disposeAgentAfterTurn === true),
             runtime: liveRun
                 ? { kind: "live", liveRun, turnCoordinator }
                 : { kind: "direct", turnCoordinator },

package/dist/cursor-provider-turn-runner.js

@@ -42,7 +42,8 @@ export class CursorProviderTurnRunner {
         });
         try {
             this.throwIfAborted();
-            const cwd = getCursorSessionCwd();
+            const runtimeContext = this.params.runtimeContext;
+            const cwd = runtimeContext?.cwd ?? getCursorSessionCwd();
             this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
                 cwd,
                 modelId: model.id,
@@ -50,10 +51,10 @@ export class CursorProviderTurnRunner {
             });
             sdkEventDebugRef.current = this.sdkEventDebug;
             this.sdkEventDebug?.recordContextSnapshot(context);
-            const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
-            const localScopeKey = getCursorSessionScopeKey();
+            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, runtimeContext?.projectTrusted);
+            const localScopeKey = runtimeContext?.scopeKey ?? getCursorSessionScopeKey();
             sdkProcessErrorGuard.containLocalTransportClosedPipe(() => invalidateSessionAgent(localScopeKey, { deadTransport: true }));
-            if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+            if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, localScopeKey)) ===
                 "stream_ended") {
                 return;
             }

package/dist/cursor-provider.js

@@ -27,7 +27,7 @@ function makeInitialMessage(model) {
         timestamp: Date.now(),
     };
 }
-export function streamCursor(model, context, options) {
+export function streamCursor(model, context, options, runtimeContext) {
     const stream = createAssistantMessageEventStream();
     const sdkEventDebugRef = {};
     attachCursorSdkEventDebugPiStreamTap(stream, sdkEventDebugRef);
@@ -39,11 +39,12 @@ export function streamCursor(model, context, options) {
             stream,
             partial,
             options,
+            runtimeContext,
             sdkEventDebugRef,
         });
         try {
             stream.push({ type: "start", partial });
-            await runExclusiveCursorSessionTurn(getCursorSessionScopeKey(), () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
+            await runExclusiveCursorSessionTurn(runtimeContext?.scopeKey ?? getCursorSessionScopeKey(), () => runner.run(installCursorSdkProcessErrorGuard()), options?.signal);
         }
         catch (error) {
             await runner.handleOuterCatch(error);

package/dist/cursor-session-agent.js

@@ -283,16 +283,18 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
     let bridgeRun;
     let sessionStore;
     try {
-        const registeredBridge = getRegisteredCursorPiToolBridge();
+        const registeredBridge = params.bridge ?? getRegisteredCursorPiToolBridge();
         if (registeredBridge) {
-            bridgeRun = await registeredBridge.createRun({
+            const createdBridgeRun = await registeredBridge.createRun({
                 onToolRequest: params.onBridgeToolRequest,
                 debugRecorder: params.debugRecorder,
                 excludeToolNames: params.bridgeExcludeToolNames,
             });
-            if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
-                await bridgeRun.dispose();
-                bridgeRun = undefined;
+            if (!createdBridgeRun.enabled || !createdBridgeRun.mcpServers) {
+                await createdBridgeRun.dispose();
+            }
+            else {
+                bridgeRun = createdBridgeRun;
             }
         }
         const resolvedPoolKey = buildSessionAgentPoolKey(scopeKey, params);
@@ -382,8 +384,8 @@ export function invalidateSessionAgent(scopeKey = getCursorSessionScopeKey(), op
         deadTransportScopeKeys.add(scopeKey);
 }
 export async function acquireSessionCursorAgent(params) {
-    const scopeKey = getCursorSessionScopeKey();
-    const persistentStore = getCursorSessionFile() !== undefined;
+    const scopeKey = params.runtimeScope?.scopeKey ?? getCursorSessionScopeKey();
+    const persistentStore = params.runtimeScope ? params.runtimeScope.sessionFile !== undefined : getCursorSessionFile() !== undefined;
     let forceCreate = params.forceCreate === true;
     while (true) {
         assertScopeAcceptsAcquire(scopeKey);

package/dist/index.js

@@ -1,7 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { discoverModels } from "./model-discovery.js";
 import { registerCursorRuntimeControls } from "./cursor-state.js";
 import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-registration.js";
-import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import { registerCursorPiToolBridge, registerNestedCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
 import { registerCursorSkillTool } from "./cursor-skill-tool.js";
 import { registerCursorSessionScope } from "./cursor-session-scope.js";
@@ -15,24 +16,61 @@ import { registerCursorAgentsContextDedup } from "./cursor-agents-context-regist
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
+import { disposeSessionCursorAgent } from "./cursor-session-agent.js";
+import { getCursorSessionCwd, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
 import { claimCursorExtensionFactory, registerCursorExtensionFactoryRelease, releaseCursorExtensionFactory, } from "./cursor-extension-factory-guard.js";
-function createCursorProviderConfig(models) {
+let activeCursorProviderModels;
+function createCursorProviderConfig(models, streamSimple = streamCursorLazy) {
     return {
         name: "Cursor",
         baseUrl: "https://cursor.com",
         apiKey: CURSOR_API_KEY_CONFIG_VALUE,
         api: "cursor-sdk",
         models,
-        streamSimple: streamCursorLazy,
+        streamSimple,
     };
 }
-function registerCursorProvider(pi, models) {
-    pi.registerProvider("cursor", createCursorProviderConfig(models));
+function registerCursorProvider(pi, models, streamSimple) {
+    pi.registerProvider("cursor", createCursorProviderConfig(models, streamSimple));
+}
+function registerNestedCursorProvider(pi, models) {
+    const bridge = registerNestedCursorPiToolBridge(pi);
+    const nestedRuntimeId = randomUUID();
+    let runtimeContext = {
+        scopeKey: `__nested_cursor__:${nestedRuntimeId}`,
+        cwd: getCursorSessionCwd(),
+        sessionFile: undefined,
+        projectTrusted: getCursorSessionProjectTrusted(),
+        bridge,
+        localResume: false,
+        nativeToolReplay: false,
+        disposeAgentAfterTurn: true,
+    };
+    pi.on("session_start", (_event, ctx) => {
+        const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? undefined;
+        const sessionId = ctx.sessionManager?.getSessionId?.() ?? nestedRuntimeId;
+        runtimeContext = {
+            ...runtimeContext,
+            scopeKey: sessionFile ?? `__nested_cursor__:${sessionId}`,
+            cwd: ctx.cwd,
+            sessionFile,
+            projectTrusted: ctx.isProjectTrusted?.() === true || runtimeContext.projectTrusted,
+        };
+    });
+    pi.on("session_shutdown", async () => {
+        await disposeSessionCursorAgent(runtimeContext.scopeKey);
+    });
+    registerCursorProvider(pi, models, (model, context, options) => streamCursorLazy(model, context, options, runtimeContext));
 }
 export default async function (pi) {
     const factoryClaim = claimCursorExtensionFactory();
-    if (factoryClaim.kind === "nested")
+    if (factoryClaim.kind === "nested") {
+        if (!activeCursorProviderModels) {
+            throw new Error("Nested Cursor provider loaded before the owner model catalog was ready");
+        }
+        registerNestedCursorProvider(pi, activeCursorProviderModels);
         return;
+    }
     try {
         // Discover first. A discovery failure must not leave process-global
         // registrars from a discarded extension load.
@@ -42,6 +80,7 @@ export default async function (pi) {
                 fallbackIssue = issue;
             },
         });
+        activeCursorProviderModels = models;
         // Session cwd must register before other session_start listeners that depend on it.
         registerCursorSessionScope(pi);
         registerCursorSessionAgentLineage(pi);

package/docs/cursor-model-ux-spec.md

@@ -29,7 +29,7 @@ Current implementation notes:
 - The bridge queues MCP calls, emits provider `toolcall_*` events, waits for matching pi `toolResult` messages by `toolCallId`, resolves the result back into the same live Cursor SDK run without creating a new `Agent`, and never calls tool `execute()` handlers directly. The same-run resume invariant holds unless the run was disposed, aborted, or cancelled.
 - Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.30 still has a 60-second MCP request default with no public per-server timeout option. The extension extends the verified Cursor SDK MCP `callTool` timeout path to 3600 seconds by default and shortens the verified first-send MCP initialize/listTools timeout paths to 10 seconds by default so unavailable configured MCP servers do not block the first reply for a full minute; unknown MCP protocol timeout stacks keep the SDK default. Users can override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`. Bridged `CallTool` waits also have a local fail-closed deadline that defaults to and cannot exceed the effective MCP tool timeout; `PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS` can lower it, expiry or MCP cancellation aborts active pi execution when available, and expired bridge events are dropped before pi tool emission.
 - Cursor SDK local safety controls are off by default. `--cursor-auto-review` / `PI_CURSOR_AUTO_REVIEW` and `--cursor-sandbox` / `PI_CURSOR_SANDBOX` pass only explicit enabled values into `Agent.create({ local })`; user or trusted project config can set `local.autoReview` and `local.sandboxOptions.enabled`; project config is active only when Pi's project-trust flow reached the extension and approved the project or the run used explicit `--approve`, and project saves require the same immutable trust provenance rather than creating Pi trust resources automatically. Pi 0.84.0 loads `pi install -l` project-local extensions after the trust event, so those installs require `--approve` on every run that reads or writes `.pi/cursor-sdk.json`. Fast-default and HTTP transport saves preserve unrecognized config fields, reject malformed or non-object JSON without rewriting it, and use one lock-protected read-modify-write path; fast saves mutate only the selected model key. Because Pi can mutate its in-memory session branch before a journal append throws, a completed global save is authoritative and the command reports the partial journal failure instead of attempting an ambiguous rollback; the new global value stays authoritative over stale branch entries until a later successful save or session restart.
-- Local HTTP/1.1/SSE compatibility is strictly opt-in through `PI_CURSOR_HTTP_1_1`, `/cursor-http on|off|toggle`, or user `cursor-sdk.json` `local.useHttp1ForAgent`. Precedence is session, environment, user, then the built-in unset default; project config is excluded. Unset makes no `Cursor.configure()` call. Explicit values configure the installed SDK before local `Agent.create()`, extension-owned explicit state is cleared with the SDK's documented `null` reset when returning to unset and during session shutdown before module reload, and default/HTTP2/HTTP1 choices split pooled local agents. Pi's supported CLI/TUI/print/RPC lifecycle has one active session runtime per process; concurrent independent `AgentSession` embedding in one process is outside this transport toggle's contract because the installed SDK setting and executor cache are module-global. The extension factory is also process-global: the first load owns the bridge, session scope, and pooled SDK agent. A nested child `createAgentSession` load is ignored until that owner session shuts down, so a live parent `pi__subagent` MCP run is not disposed as an extension reload. The footer adds `http1` only when HTTP/1.1 transport is enabled.
+- Local HTTP/1.1/SSE compatibility is strictly opt-in through `PI_CURSOR_HTTP_1_1`, `/cursor-http on|off|toggle`, or user `cursor-sdk.json` `local.useHttp1ForAgent`. Precedence is session, environment, user, then the built-in unset default; project config is excluded. Unset makes no `Cursor.configure()` call. Explicit values configure the installed SDK before local `Agent.create()`, extension-owned explicit state is cleared with the SDK's documented `null` reset when returning to unset and during session shutdown before module reload, and default/HTTP2/HTTP1 choices split pooled local agents. Pi's supported CLI/TUI/print/RPC lifecycle has one active session runtime per process; concurrent independent `AgentSession` embedding in one process is outside this transport toggle's contract because the installed SDK setting and executor cache are module-global. The extension factory has process-owner and nested-child paths. The first load owns process-global controls, session scope, native replay state, and the owner SDK agent pool. A nested child `createAgentSession` load registers only a child-local Cursor provider, bridge, and SDK agent scope. This split keeps the parent bridge live and lets a Cursor child run without waiting on the busy parent SDK agent. The footer adds `http1` only when HTTP/1.1 transport is enabled.
 - Bridge diagnostics are opt-in only: `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` writes typed, allowlisted, scrubbed single-line JSONL records to `process.stderr` with prefix `[pi-cursor-sdk:bridge]`. Diagnostics are scrubbed operational logs, not anonymous telemetry. They intentionally include tool names, safe correlation IDs, run lifecycle, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. Correlation IDs are generated independently from the tokenized endpoint path, and Cursor MCP call IDs are hashed before serialization. Diagnostics must not include endpoint paths/URLs/path components/tokens, API keys, bearer tokens, cookies, session credentials, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, or local private session paths in tracked docs, and they must not call pi UI status, notification, or footer APIs. If tool names themselves are unacceptable for a release target, bridge debug diagnostics are not safe for shared logs under the current contract.
 - This repo does not provide a generic desktop-automation, browser-driver, or CDP recipe. Provider docs should describe pi-cursor-sdk's Cursor provider/bridge contract only.
 - Cursor internal tool activity is recorded from SDK events and scrubbed. Maintainer reference for `@cursor/sdk@1.0.30` `ToolType` values, runtime alias normalization, and intentional mapping/fallback rules: [Cursor native tool replay — SDK ToolType replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix) (official SDK docs: https://cursor.com/docs/sdk/typescript). In TUI sessions and structured JSON/RPC modes, supported completed `read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`, diagnostics, delete, todo/plan, task, image generation, MCP, semantic search, and screen recording activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so users and JSON/RPC consumers can see native-looking cards/events without rerunning Cursor's reads/shell commands/file edits. Cursor `glob` activity is replayed through native `find` cards. Cursor write activity is replayed through native-looking `write` cards, and Cursor StrReplace/edit activity uses native-looking `edit` only when recorded arguments truthfully satisfy pi's `edit` schema; path-only Cursor edit and notebook edit replay falls back to neutral Cursor activity before pi validation. Diagnostics, delete, todos/plans, task/subagent, image, and MCP activity use neutral Cursor activity cards with pi's default success/error shell. Cursor SDK `task` activity is labeled **Cursor subagent** by default because it represents Cursor-spawned child-agent work; the card summary includes description plus subagent kind/model/short ID when Cursor reports them, and `PI_CURSOR_TASK_PRESENTATION=task` restores the older **Cursor task** wording for comparison. This is visibility over Cursor SDK task events, not a native pi subagent session: pi shows start/final output plus any `conversationSteps` tool-call summaries Cursor returns, but cannot show a live nested read/shell/MCP trail when the SDK only returns final subagent text. Neutral Cursor activity calls include `activityTitle` and, when available, `activitySummary` so partial/collapsed cards preserve identity such as `Cursor plan`, `Cursor todos`, `Cursor subagent`, `Cursor MCP`, or `Cursor edit`. For long-running or externally meaningful Cursor tools (`task`, `shell`, `mcp`, `generateImage`, `recordScreen`, `semSearch`, web search/fetch, plan/todo), the provider may surface one low-noise deferred in-progress thinking line such as `Cursor MCP: external_search` from bounded, scrubbed SDK args; fast local tools (`read`, `grep`, `glob`, and similar) skip lifecycle lines when completion follows immediately, and pi bridge MCP calls are excluded because pi already shows real pi tool execution ([lifecycle visibility](./cursor-native-tool-replay.md#low-noise-tool-lifecycle-visibility)). Replay-only tools display recorded Cursor results, normalize workspace-local paths/diff headers for display, use pi diff colors for edit previews and path-inferred syntax highlighting for write previews, and fail closed if called without a recorded result. Native replay wrappers are registered only for tool names not already owned by another extension; conflicting tools use the bounded scrubbed transcript fallback. Cursor workflow tools such as mode/task/todo/plan activity are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards can be followed by Cursor's final plan text, selected from `run.wait().result` when Cursor provides one and trimmed against already-emitted text. Started Cursor SDK tool calls that never receive a completion event are surfaced with bounded user-visible labels/traces (neutral activity cards when native replay routing allows, otherwise the same inactive or transcript trace fallbacks used for completed replay) instead of being silently discarded when the run failed, was aborted, or produced no assistant text; after a successful text-producing run, missing-completion starts remain maintainer-debug-only for all tools: installed `@cursor/sdk` 1.0.30 emits `tool-call-started` with no completion delta, step, or conversation entry when a permission policy or hook denies a call, and offers no way to distinguish such denials from lost completions, so suppression is the deliberate choice over false error cards. Explicit failures remain visible when Cursor reports them through completed tool calls or step results. Pi bridge MCP starts remain excluded from duplicate incomplete Cursor cards because pi already shows real pi tool execution. `PI_CURSOR_NATIVE_TOOL_DISPLAY=0` disables native replay, and `PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is a registration-only opt-out that keeps the transcript fallback without shadowing pi tool names. When bridge or native replay cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK activity arrives: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later tool batches as further `toolUse` turns, then Cursor's final assistant answer. For shell replay, completed `stdout` / `stderr` are primary; unambiguous `shell-output-delta` data is also shown as bounded live progress while one shell call is active and used as display-only fallback for empty successful shell completions, while overlapping shell calls drop ambiguous deltas instead of guessing. Print mode keeps bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when no live-run turn split is active.

package/docs/cursor-testing-lessons.md

@@ -32,16 +32,25 @@ When changing provider/runtime behavior, ask whether the bug spans **pi extensio
 
 Pi subagents build a child `AgentSession` in the same process (`createAgentSession` + `bindExtensions`). That re-invokes the `pi-cursor-sdk` factory against a new ExtensionAPI while the parent Cursor run still owns the process-global bridge, session scope, and pooled SDK agent.
 
-The observed failure: the child dies at `0 tool uses` with no transcript file, the parent turn aborts with `This operation was aborted`, and bridge diagnostics show `request_rejected` / `cancelled` with `Cursor pi tool bridge extension reloaded`.
+The first observed failure: the child died at `0 tool uses` with no transcript file. The parent turn aborted with `This operation was aborted`. Bridge diagnostics showed `request_rejected` / `cancelled` with `Cursor pi tool bridge extension reloaded`.
+
+The process-owner guard fixed that abort, but an unconditional nested-factory return introduced a second failure. A child that selected `cursor/grok-4.6` had model metadata from the parent but no `cursor` provider in its own model runtime. Pi reported `unrecognized provider error` before the first child turn.
+
+Nested factories must split registration by ownership:
+
+- The owner registers process-global controls, session state, native replay, and the owner bridge.
+- Each nested child registers the Cursor provider on its own ExtensionAPI.
+- Each nested child uses its own scope key and SDK agent pool entry. A Cursor child must not wait for the busy parent agent that is waiting for the subagent result.
+- Each nested child uses its own bridge registry over the child's active pi tools. Child shutdown must not call the process-wide bridge abort path.
+- Nested children disable local resume and native replay wrappers. They dispose their isolated SDK agent after the provider run completes.
 
 Regression coverage:
 
-- `src/cursor-extension-factory-guard.ts` — the first factory owns the process; nested loads no-op until the owner session shuts down and Pi can create its replacement runtime
 - `test/cursor-extension-factory-guard.test.ts` — owner tokens reject stale release and release for every Pi shutdown reason
-- `test/index-factory-guard.test.ts` — nested factory does not re-register, does not steal session scope, and does not dispose a live parent MCP run
-- `test/cursor-pi-tool-bridge.test.ts` — `registerCursorPiToolBridge` keeps the existing registry when a run is live
-
-If the host resolves a Cursor model for a child, that child uses the process-global Cursor agent pool. This guard stops the parent teardown; it does not give the child an independent Cursor session agent. Cursor-child model selection remains a separate live-test requirement.
+- `test/index-factory-guard.test.ts` — nested factories register only the child-local provider and bridge hooks without stealing owner scope
+- `test/cursor-session-agent.test.ts` — a nested scope acquires its own SDK agent while the parent scope is busy
+- `test/cursor-pi-tool-bridge.test.ts` — nested bridge shutdown does not reject a pending owner bridge call
+- `test/cursor-provider-run-finalizer.test.ts` — live provider completion runs the nested lifecycle disposal path
 
 ## Dual-check invariant: `context.tools` vs pi active tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emmaneugene/pi-cursor-sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "pi provider extension backed by @cursor/sdk local agents",
   "publishConfig": {
     "access": "public"

package/src/cursor-live-run-coordinator.ts

@@ -111,6 +111,11 @@ function isPendingBridgeToolRequest(run: CursorLiveRun, request: CursorPiBridgeT
 	return bridgeRun?.hasPendingPiToolCallId(request.piToolCallId) === true;
 }
 
+function hasPendingBridgeCalls(run: CursorLiveRun): boolean {
+	if (run.bridgeRun?.hasPendingCalls()) return true;
+	return run.sessionBridgeRun !== run.bridgeRun && run.sessionBridgeRun?.hasPendingCalls() === true;
+}
+
 export interface CursorLiveRunRecord {
 	id: string;
 	disposed: boolean;
@@ -494,6 +499,12 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			if (state.leased || state.leaseQueue.length > 0) return;
 			state.idleDisposeRequested = false;
 			state.idleDisposeTimer = setTimeout(() => {
+				if (hasPendingBridgeCalls(run)) {
+					// Bridge calls have their own deadline. Reuse the idle interval to avoid a hot
+					// polling loop if the SDK does not emit a terminal event after that deadline.
+					coordinator.requestIdleDispose(run);
+					return;
+				}
 				void coordinator.release(run).catch(() => {
 					// Idle dispose must not leave release failures as unhandled rejections.
 				});

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

@@ -183,6 +183,10 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		await this.resolveToolResults(context.messages.map(asToolResultMessage).filter((message): message is ToolResultMessage => message !== undefined));
 	}
 
+	hasPendingCalls(): boolean {
+		return this.pendingCount() > 0;
+	}
+
 	hasPendingPiToolCallId(piToolCallId: string): boolean {
 		return this.pendingByPiToolCallId.has(piToolCallId);
 	}

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

@@ -65,6 +65,7 @@ export interface CursorPiToolBridgeRun {
 	takeQueuedToolRequests(): CursorPiBridgeToolRequest[];
 	resolveToolResults(toolResults: readonly ToolResultMessage[]): Promise<void>;
 	resolveToolResultsFromContext(context: Context): Promise<void>;
+	hasPendingCalls(): boolean;
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
 	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;

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

@@ -88,18 +88,13 @@ Get-CimInstance Win32_Process -Filter "Name = 'bash.exe' OR Name = 'sh.exe'" |
 	});
 }
 
-export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi): CursorPiToolBridge {
-	// Replacing a bridge during a live MCP run cancels its pending pi tool
-	// calls. Keep the active registry as a final safety belt.
-	if (registeredCursorPiToolBridge?.hasLiveRuns()) {
-		return registeredCursorPiToolBridge;
-	}
-	bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
-	void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
-	const bridge = new CursorPiToolBridgeRegistry(pi);
-	registeredCursorPiToolBridge = bridge;
+function attachCursorPiToolBridgeHandlers(
+	pi: CursorPiToolBridgeExtensionApi,
+	bridge: CursorPiToolBridgeRegistry,
+	options: { abortAllOnShutdown: boolean; isActive: () => boolean },
+): void {
 	pi.on("tool_call", (event, ctx) => {
-		if (registeredCursorPiToolBridge !== bridge) return undefined;
+		if (!options.isActive()) return undefined;
 		if (!bridge.hasPendingPiToolCallId(event.toolCallId)) {
 			return isCursorPiBridgeToolCallId(event.toolCallId)
 				? { block: true, reason: "Cursor pi bridge tool call is no longer pending" }
@@ -124,9 +119,35 @@ export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi):
 	});
 	pi.on("session_shutdown", async (event) => {
 		const reason = `Cursor pi tool bridge session shutdown: ${event.reason}`;
-		bridgeToolExecutionAbortTracker.abortAll(reason);
+		if (options.abortAllOnShutdown) bridgeToolExecutionAbortTracker.abortAll(reason);
 		await bridge.disposeAll(reason);
 	});
+}
+
+export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi): CursorPiToolBridge {
+	// Replacing a bridge during a live MCP run cancels its pending pi tool
+	// calls. Keep the active registry as a final safety belt.
+	if (registeredCursorPiToolBridge?.hasLiveRuns()) {
+		return registeredCursorPiToolBridge;
+	}
+	bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
+	void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
+	const bridge = new CursorPiToolBridgeRegistry(pi);
+	registeredCursorPiToolBridge = bridge;
+	attachCursorPiToolBridgeHandlers(pi, bridge, {
+		abortAllOnShutdown: true,
+		isActive: () => registeredCursorPiToolBridge === bridge,
+	});
+	return bridge;
+}
+
+/** Register a bridge owned only by one nested in-process child session. */
+export function registerNestedCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi): CursorPiToolBridge {
+	const bridge = new CursorPiToolBridgeRegistry(pi);
+	attachCursorPiToolBridgeHandlers(pi, bridge, {
+		abortAllOnShutdown: false,
+		isActive: () => true,
+	});
 	return bridge;
 }
 

package/src/cursor-provider-lazy.ts

@@ -9,6 +9,7 @@ import {
 } from "@earendil-works/pi-ai";
 import { streamCursor } from "./cursor-provider.js";
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
 
 function makeProviderRuntimeErrorMessage(model: Model<Api>, error: unknown, apiKey?: string): AssistantMessage {
 	return {
@@ -35,11 +36,12 @@ export function streamCursorLazy(
 	model: Model<Api>,
 	context: Context,
 	options?: SimpleStreamOptions,
+	runtimeContext?: CursorProviderRuntimeContext,
 ): AssistantMessageEventStream {
 	const outer = createAssistantMessageEventStream();
 	queueMicrotask(async () => {
 		try {
-			for await (const event of streamCursor(model, context, options)) {
+			for await (const event of streamCursor(model, context, options, runtimeContext)) {
 				outer.push(event);
 			}
 		} catch (error) {

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

@@ -67,8 +67,8 @@ export function getPendingCursorLiveRun(context: Context): CursorLiveRun | undef
 	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId);
 }
 
-export function getActiveCursorLiveRunForCurrentScope(): CursorLiveRun | undefined {
-	return cursorLiveRuns.getActiveForScope();
+export function getActiveCursorLiveRunForScope(scopeKey?: string): CursorLiveRun | undefined {
+	return cursorLiveRuns.getActiveForScope(scopeKey);
 }
 
 function splitTextIntoReplayDeltas(text: string): string[] {
@@ -427,10 +427,11 @@ export async function drainExistingCursorLiveRunBeforeSend(
 	context: Context,
 	signal?: AbortSignal,
 	turnDebugRecorder?: CursorSdkEventDebugRecorder,
+	scopeKey?: string,
 ): Promise<LiveRunPreSendOutcome> {
 	turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
 	while (true) {
-		const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
+		const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForScope(scopeKey);
 		if (!run || run.disposed) {
 			turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
 			return "continue_send";

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

@@ -147,6 +147,7 @@ export class CursorRunFinalizer {
 		if (liveCompletion) {
 			void liveCompletion.waitCompletion
 				.finally(async () => {
+					await prepared?.lifecycle.dispose().catch(() => {});
 					await this.finalizeSdkEventDebugBestEffort();
 					this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
 				})

package/src/cursor-provider-runtime-context.ts

@@ -0,0 +1,13 @@
+import type { CursorPiToolBridge } from "./cursor-pi-tool-bridge-types.js";
+
+/** Runtime state captured by one nested in-process Cursor provider registration. */
+export interface CursorProviderRuntimeContext {
+	readonly scopeKey: string;
+	readonly cwd: string;
+	readonly sessionFile: string | undefined;
+	readonly projectTrusted: boolean;
+	readonly bridge: CursorPiToolBridge;
+	readonly localResume: false;
+	readonly nativeToolReplay: false;
+	readonly disposeAgentAfterTurn: true;
+}

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

@@ -20,7 +20,6 @@ import {
 	abandonSessionCursorAgent,
 	createCursorNativeReplayId,
 	cursorLiveRuns,
-	getActiveCursorLiveRunForCurrentScope,
 	getPendingCursorLiveRun,
 } from "./cursor-provider-live-run-drain.js";
 import {
@@ -66,19 +65,22 @@ interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnPara
 	fastEnabled: boolean | undefined;
 }
 
-export function resolveCursorProviderTurnConfig(cwd: string) {
-	return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+export function resolveCursorProviderTurnConfig(cwd: string, projectTrusted = getCursorSessionProjectTrusted()) {
+	return resolveEffectiveCursorConfig({ cwd, projectTrusted });
 }
 
 function buildLocalCursorProviderTurnLifecycle(
 	lease: SessionCursorAgentLease,
 	scopeKey: string,
+	disposeAgentAfterTurn: boolean,
 ): CursorProviderTurnLifecycle {
 	return {
 		trackRunCompletion: (completion) => lease.trackRunCompletion(completion),
 		commitSend: (context, bootstrapped) => lease.commitSend(context, bootstrapped),
 		abandon: () => abandonSessionCursorAgent(scopeKey),
-		dispose: async () => {},
+		dispose: async () => {
+			if (disposeAgentAfterTurn) await resetSessionCursorAgent(scopeKey);
+		},
 	};
 }
 
@@ -86,7 +88,7 @@ async function prepareCursorLocalProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<CursorProviderTurnPrepareResult> {
 	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
-	const { model, context, options } = params;
+	const { model, context, options, runtimeContext } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
 	let sessionAgentScopeKey: string | undefined;
@@ -113,6 +115,7 @@ async function prepareCursorLocalProviderTurn(
 		const queuedBridgeRequestsBeforeLiveRun: CursorPiBridgeToolRequest[] = [];
 		let liveRunForBridgeQueue: CursorLiveRun | undefined;
 		const bridgeExcludeToolNames = buildCursorBridgeExcludeToolNames(resolvedConfig);
+		const localResumeEnabled = runtimeContext?.localResume ?? resolvedConfig.local.resume.value;
 
 		const sessionAgentAcquireParams = {
 			apiKey: resolvedApiKey,
@@ -121,8 +124,12 @@ async function prepareCursorLocalProviderTurn(
 			modelSelection: selection,
 			settingSources,
 			localSafety,
-			localResume: resolvedConfig.local.resume.value,
+			localResume: localResumeEnabled,
 			useHttp1ForAgent,
+			runtimeScope: runtimeContext
+				? { scopeKey: runtimeContext.scopeKey, sessionFile: runtimeContext.sessionFile }
+				: undefined,
+			bridge: runtimeContext?.bridge,
 			bridgeExcludeToolNames,
 			debugRecorder: sdkEventDebug,
 			onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
@@ -185,7 +192,7 @@ async function prepareCursorLocalProviderTurn(
 		};
 		const sessionBridgeRun = bridgeRun;
 		const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
-		const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+		const useNativeToolReplay = runtimeContext?.nativeToolReplay ?? isCursorNativeToolDisplayRuntimeEnabled();
 		const activeToolNames = getActiveContextToolNames(context);
 		sdkEventDebug?.recordProviderMeta({
 			model: {
@@ -203,7 +210,7 @@ async function prepareCursorLocalProviderTurn(
 			toolManifestEnabled: resolveCursorToolManifestEnabled(),
 			agentMode,
 			localForce: resolvedConfig.local.force.value,
-			localResume: resolvedConfig.local.resume.value,
+			localResume: localResumeEnabled,
 			resumedAgent: sessionAgentLease.resumed,
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
@@ -266,7 +273,11 @@ async function prepareCursorLocalProviderTurn(
 			sessionAgentLease,
 			localForce: resolvedConfig.local.force,
 			restoreCursorSdkOutputFilter,
-			lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey),
+			lifecycle: buildLocalCursorProviderTurnLifecycle(
+			sessionAgentLease,
+			sessionAgentScopeKey,
+			runtimeContext?.disposeAgentAfterTurn === true,
+		),
 			runtime: liveRun
 				? { kind: "live", liveRun, turnCoordinator }
 				: { kind: "direct", turnCoordinator },

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

@@ -62,7 +62,8 @@ export class CursorProviderTurnRunner {
 
 		try {
 			this.throwIfAborted();
-			const cwd = getCursorSessionCwd();
+			const runtimeContext = this.params.runtimeContext;
+			const cwd = runtimeContext?.cwd ?? getCursorSessionCwd();
 			this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
 				cwd,
 				modelId: model.id,
@@ -70,13 +71,21 @@ export class CursorProviderTurnRunner {
 			});
 			sdkEventDebugRef.current = this.sdkEventDebug;
 			this.sdkEventDebug?.recordContextSnapshot(context);
-			const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
-			const localScopeKey = getCursorSessionScopeKey();
+			const resolvedConfig = resolveCursorProviderTurnConfig(cwd, runtimeContext?.projectTrusted);
+			const localScopeKey = runtimeContext?.scopeKey ?? getCursorSessionScopeKey();
 			sdkProcessErrorGuard.containLocalTransportClosedPipe(() =>
 				invalidateSessionAgent(localScopeKey, { deadTransport: true }),
 			);
 			if (
-				(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+				(await drainExistingCursorLiveRunBeforeSend(
+					stream,
+					partial,
+					model,
+					context,
+					options?.signal,
+					this.sdkEventDebug,
+					localScopeKey,
+				)) ===
 				"stream_ended"
 			) {
 				return;

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

@@ -15,6 +15,7 @@ import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinato
 import type { CursorPrompt } from "./context.js";
 import type { CursorResolvedSetting } from "./cursor-config.js";
 import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
 
 export interface CursorProviderTurnRunnerParams {
 	model: Model<Api>;
@@ -22,6 +23,7 @@ export interface CursorProviderTurnRunnerParams {
 	stream: AssistantMessageEventStream;
 	partial: AssistantMessage;
 	options?: SimpleStreamOptions;
+	runtimeContext?: CursorProviderRuntimeContext;
 	sdkEventDebugRef: { current?: CursorSdkEventDebugSink };
 }
 

package/src/cursor-provider.ts

@@ -23,6 +23,7 @@ import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { CursorProviderTurnRunner } from "./cursor-provider-turn-runner.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { runExclusiveCursorSessionTurn, __testUtils as cursorSessionTurnQueueTestUtils } from "./cursor-session-turn-queue.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -48,6 +49,7 @@ export function streamCursor(
 	model: Model<Api>,
 	context: Context,
 	options?: SimpleStreamOptions,
+	runtimeContext?: CursorProviderRuntimeContext,
 ): AssistantMessageEventStream {
 	const stream = createAssistantMessageEventStream();
 	const sdkEventDebugRef: { current?: CursorSdkEventDebugSink } = {};
@@ -62,13 +64,14 @@ export function streamCursor(
 			stream,
 			partial,
 			options,
+			runtimeContext,
 			sdkEventDebugRef,
 		});
 
 		try {
 			stream.push({ type: "start", partial });
 			await runExclusiveCursorSessionTurn(
-				getCursorSessionScopeKey(),
+				runtimeContext?.scopeKey ?? getCursorSessionScopeKey(),
 				() => runner.run(installCursorSdkProcessErrorGuard()),
 				options?.signal,
 			);

package/src/cursor-session-agent.ts

@@ -4,6 +4,7 @@ import type { Context } from "@earendil-works/pi-ai";
 import {
 	getRegisteredCursorPiToolBridge,
 	type CursorPiBridgeToolRequest,
+	type CursorPiToolBridge,
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
@@ -136,6 +137,8 @@ interface SessionCursorAgentCreateParams {
 	bridgeExcludeToolNames?: ReadonlySet<string>;
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
+	runtimeScope?: { scopeKey: string; sessionFile: string | undefined };
+	bridge?: CursorPiToolBridge;
 	localResume?: boolean;
 	forceCreate?: boolean;
 	createAgent?: CursorSdkModule["Agent"]["create"];
@@ -453,16 +456,17 @@ async function createSessionAgentEntry(
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	let sessionStore: OpenCursorSessionStore | undefined;
 	try {
-		const registeredBridge = getRegisteredCursorPiToolBridge();
+		const registeredBridge = params.bridge ?? getRegisteredCursorPiToolBridge();
 		if (registeredBridge) {
-			bridgeRun = await registeredBridge.createRun({
+			const createdBridgeRun = await registeredBridge.createRun({
 				onToolRequest: params.onBridgeToolRequest,
 				debugRecorder: params.debugRecorder,
 				excludeToolNames: params.bridgeExcludeToolNames,
 			});
-			if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
-				await bridgeRun.dispose();
-				bridgeRun = undefined;
+			if (!createdBridgeRun.enabled || !createdBridgeRun.mcpServers) {
+				await createdBridgeRun.dispose();
+			} else {
+				bridgeRun = createdBridgeRun;
 			}
 		}
 
@@ -559,8 +563,8 @@ export function invalidateSessionAgent(
 }
 
 export async function acquireSessionCursorAgent(params: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
-	const scopeKey = getCursorSessionScopeKey();
-	const persistentStore = getCursorSessionFile() !== undefined;
+	const scopeKey = params.runtimeScope?.scopeKey ?? getCursorSessionScopeKey();
+	const persistentStore = params.runtimeScope ? params.runtimeScope.sessionFile !== undefined : getCursorSessionFile() !== undefined;
 	let forceCreate = params.forceCreate === true;
 
 	while (true) {

package/src/index.ts

@@ -1,8 +1,9 @@
+import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import { discoverModels, type CursorModelFallbackIssue } from "./model-discovery.js";
 import { registerCursorRuntimeControls } from "./cursor-state.js";
 import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-registration.js";
-import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import { registerCursorPiToolBridge, registerNestedCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
 import { registerCursorSkillTool } from "./cursor-skill-tool.js";
 import { registerCursorSessionScope } from "./cursor-session-scope.js";
@@ -16,6 +17,9 @@ import { registerCursorAgentsContextDedup } from "./cursor-agents-context-regist
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
+import { disposeSessionCursorAgent } from "./cursor-session-agent.js";
+import { getCursorSessionCwd, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
 import {
 	claimCursorExtensionFactory,
 	registerCursorExtensionFactoryRelease,
@@ -39,24 +43,70 @@ type CursorExtensionApi =
 	& Parameters<typeof registerCursorSdkSessionProcessErrorGuard>[0]
 	& Parameters<typeof registerCursorExtensionFactoryRelease>[0];
 
-function createCursorProviderConfig(models: ProviderModelConfig[]): ProviderConfig {
+let activeCursorProviderModels: ProviderModelConfig[] | undefined;
+
+function createCursorProviderConfig(
+	models: ProviderModelConfig[],
+	streamSimple: NonNullable<ProviderConfig["streamSimple"]> = streamCursorLazy,
+): ProviderConfig {
 	return {
 		name: "Cursor",
 		baseUrl: "https://cursor.com",
 		apiKey: CURSOR_API_KEY_CONFIG_VALUE,
 		api: "cursor-sdk",
 		models,
-		streamSimple: streamCursorLazy,
+		streamSimple,
 	};
 }
 
-function registerCursorProvider(pi: Pick<ExtensionAPI, "registerProvider">, models: ProviderModelConfig[]): void {
-	pi.registerProvider("cursor", createCursorProviderConfig(models));
+function registerCursorProvider(
+	pi: Pick<ExtensionAPI, "registerProvider">,
+	models: ProviderModelConfig[],
+	streamSimple?: NonNullable<ProviderConfig["streamSimple"]>,
+): void {
+	pi.registerProvider("cursor", createCursorProviderConfig(models, streamSimple));
+}
+
+function registerNestedCursorProvider(pi: CursorExtensionApi, models: ProviderModelConfig[]): void {
+	const bridge = registerNestedCursorPiToolBridge(pi);
+	const nestedRuntimeId = randomUUID();
+	let runtimeContext: CursorProviderRuntimeContext = {
+		scopeKey: `__nested_cursor__:${nestedRuntimeId}`,
+		cwd: getCursorSessionCwd(),
+		sessionFile: undefined,
+		projectTrusted: getCursorSessionProjectTrusted(),
+		bridge,
+		localResume: false,
+		nativeToolReplay: false,
+		disposeAgentAfterTurn: true,
+	};
+	pi.on("session_start", (_event, ctx) => {
+		const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? undefined;
+		const sessionId = ctx.sessionManager?.getSessionId?.() ?? nestedRuntimeId;
+		runtimeContext = {
+			...runtimeContext,
+			scopeKey: sessionFile ?? `__nested_cursor__:${sessionId}`,
+			cwd: ctx.cwd,
+			sessionFile,
+			projectTrusted: ctx.isProjectTrusted?.() === true || runtimeContext.projectTrusted,
+		};
+	});
+	pi.on("session_shutdown", async () => {
+		await disposeSessionCursorAgent(runtimeContext.scopeKey);
+	});
+	registerCursorProvider(pi, models, (model, context, options) =>
+		streamCursorLazy(model, context, options, runtimeContext));
 }
 
 export default async function (pi: CursorExtensionApi) {
 	const factoryClaim = claimCursorExtensionFactory();
-	if (factoryClaim.kind === "nested") return;
+	if (factoryClaim.kind === "nested") {
+		if (!activeCursorProviderModels) {
+			throw new Error("Nested Cursor provider loaded before the owner model catalog was ready");
+		}
+		registerNestedCursorProvider(pi, activeCursorProviderModels);
+		return;
+	}
 
 	try {
 		// Discover first. A discovery failure must not leave process-global
@@ -67,6 +117,7 @@ export default async function (pi: CursorExtensionApi) {
 				fallbackIssue = issue;
 			},
 		});
+		activeCursorProviderModels = models;
 
 		// Session cwd must register before other session_start listeners that depend on it.
 		registerCursorSessionScope(pi);