pi-cursor-sdk 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -2,7 +2,54 @@
 
 **Release preparation is not a publication receipt:** confirm the exact version, source and artifact integrity in npm/GitHub publication records before relying on availability. No issue is closed by preparation alone.
 
-## Unreleased
+## 0.5.6 - 2026-11-01
+
+<!-- npm-release:unreleased:start -->
+<!-- npm-release:unreleased:end -->
+
+- Merge pull request #395 from fitchmultz/task/npm-zod-release-gate ([49e7f8d](https://github.com/fitchmultz/pi-cursor-sdk/commit/49e7f8dbcfb6bf76b3f550f49ffd7d3f547cc9ab))
+
+### Changed
+
+- Gate automatic patch releases on exact-scope commit, PR, prospective-release, and retained-candidate reviews. Bind catalog and installer qualification to the candidate and retain npm and GitHub publication evidence (#393, #394, #395).
+- Approve Bun and pnpm's required setup scripts with npm 12's targeted `--allow-scripts=bun,pnpm` before the five-mode Node/Bun installer qualification (#397).
+
+### Fixed
+
+- Credit a complete source-file read for a byte-identical package copy after the reviewer opens the package path. The review receipt records SHA-256 provenance. Different package content still requires a complete read.
+
+Cursor runtime behavior and runtime dependency versions are unchanged.
+
+### What's Changed
+* Qualify exact review scopes before release (1/3) by @fitchmultz in https://github.com/fitchmultz/pi-cursor-sdk/pull/393
+* Bind prospective release reviews to the open PR (2/3) by @fitchmultz in https://github.com/fitchmultz/pi-cursor-sdk/pull/394
+* Gate automatic Cursor releases on exact-candidate review (3/3) by @fitchmultz in https://github.com/fitchmultz/pi-cursor-sdk/pull/395
+
+
+**Full Changelog**: https://github.com/fitchmultz/pi-cursor-sdk/compare/v0.5.5...v0.5.6
+
+## 0.5.5
+
+### Fixed
+
+- Stop a failed LOCAL Cursor run's shell commands and other native tool processes. SDK 1.0.40 leaves them running after a run fails, for example when it gives up resuming a reset connection, and `Run.cancel()` stops them only while the run is still running. The provider now cancels the run while the SDK records the failure, which the SDK does before it marks the run failed, and still reports the SDK's failure message as a Pi error. A separate SDK error code, when present, is not shown after this cancellation. Explicit Pi aborts and Cloud runs are unchanged (#384).
+
+- Upgrade the exact unbundled Cursor SDK and its optional platform packages from 1.0.37 to 1.0.40 for LOCAL Claude-format hook compatibility: the SDK now enables translation of nested `hookSpecificOutput` denial/rewrite output into the fields its tool adapters consume. It also improves Windows command-hook UTF-8 input and native exit-code propagation. This is not a Pi pre-execution hook, universal policy guarantee, or resolution of the original rtk report (#173).
+
+- Supply SDK 1.0.40's required Zod peer as a direct exact `zod@4.6.6` runtime dependency, with the bundled MCP bridge's newer nested `4.6.7` copies retained by npm's lockfile. This keeps the peer outside the tarball's bundle and reachable by the unbundled SDK under Pi's `--legacy-peer-deps` installation, without peer auto-installation, overrides or SDK patches (#380). A deduplicated root `4.6.7` copy instead gets bundled and breaks that installation.
+
+- Both the SDK's v4/v4-mini parsers and the bridge's v4 parsers now include the bounded-collection fix for [GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5): array, set and map size bounds are checked before parsing elements. Zod 4.6.7 differs from 4.6.6 only in version metadata. The legacy `zod/v3` implementation is unchanged, and unconstrained collections still validate every element; this is not a universal resource cap or a claim of a demonstrated SDK exploit.
+
+- Stop `smoke:steering --self-test` from rebuilding `dist/` before its offline probe. The rebuild briefly removed `dist/` while the concurrent package test packed the checkout, producing an intermittent missing `dist/index.js` failure. Live steering runs still rebuild first (fitchmultz/.github#98).
+
+### Changed
+
+- Refresh the fallback catalog from the authenticated SDK 1.0.40 catalog-only observation on 2026-10-31: 49 models, adding DeepSeek V4.1 Flash 1017 (`deepseek-v41-flash-1017`) and recording `cyber=false` on Claude Opus 5.5 variants. All 48 prior model IDs and the 33 bundled checkpoint-derived entries remain; no Agent/model turn or Cloud run was performed.
+
+### Verification and limits
+
+- **User-visible rollout:** admitted user/project Claude hooks returning only nested denial/rewrite output can now affect tool execution where SDK 1.0.37 ignored that output; this is an intended behavior change, not just a test-harness repair.
+- Add installed-package contracts for actual Claude settings loading, UTF-8 hook input, nested denial/rewrite, conflicting/mismatched output guards and native exit-2 denial. These use test-only lexical observation, not a production SDK patch, public Agent/backend run or startup canary. Preserve the dated SDK 1.0.37 catalog and older captures at their actual identities; the other original backlog causes remain unqualified and both commit/PR attribution controls remain unavailable.
 
 ## 0.5.4
 

package/README.md

@@ -8,7 +8,7 @@ Use Cursor models in [Pi](https://pi.dev)'s terminal UI. `pi-cursor-sdk` runs Cu
 
 ## Quick start
 
-Requirements: Node.js 24+, Pi 0.87.1+, and an API key for Cursor SDK. The package installs `@cursor/sdk` for you.
+Requirements: Node.js, Pi, and an API key for Cursor SDK. Check the [supported Node.js and Pi versions](docs/reference.md#requirements). The package installs `@cursor/sdk` for you.
 
 Use a user key from Cursor Dashboard → API Keys or a service-account key from Team settings. Team Admin keys do not work. Cursor Desktop and Agent CLI login do not supply the SDK key.
 
@@ -56,7 +56,7 @@ The footer shows status such as `cursor:local · fast:off`, with `plan` or `http
 
 Cursor controls file tools, shell commands, edits, and configured MCP servers. The local MCP bridge exposes active Pi extension tools as `pi__*` names. The bridge is on by default. Pi hides matching built-ins from the bridge by default.
 
-**Availability:** `PI_CURSOR_NATIVE_TOOLS` and `/cursor-abort` require **0.5.4 or later**, beginning with the implementation from [#372](https://github.com/fitchmultz/pi-cursor-sdk/pull/372). Source checkouts preparing 0.5.4 remain candidates until exact publication records exist; the version change alone is not a publication record. Verify the exact npm version and GitHub release before relying on its availability. Published **0.5.3 ignores this flag and does not provide the command**; do not rely on them for native-tool restriction or pending-run recovery there. Development version labels alone do not establish which controls are installed.
+**Availability:** Some older releases **ignore `PI_CURSOR_NATIVE_TOOLS` and do not provide `/cursor-abort`**. Check your installed version against the [version boundary](docs/cursor-tool-surfaces.md#the-three-surfaces) before relying on either control; a development version label alone does not prove availability.
 
 **Pi's `--no-tools`, `--tools`, and `--exclude-tools` do not disable Cursor tools or Cursor MCP servers.** For local ordinary turns on a supporting revision, opt in to `PI_CURSOR_NATIVE_TOOLS=0` to allow only MCP through the public SDK tool surface (including disabling native task/subagents). It leaves configured Cursor MCP available unless you also disable ambient setting sources. Cloud rejects this opt-out for both ordinary and selected-Cloud summary requests; only existing isolated LOCAL summary agents remain unaffected with `tools: []`.
 
@@ -67,7 +67,7 @@ A policy mismatch preserves the pending local run: restore its prior policy to f
 Local runs leave Cursor auto-review and sandboxing off by default. Read the [safety controls and hook limits](docs/reference.md#cursor-local-agent-config-and-safety-controls) before you depend on those controls or Cursor hooks.
 
 ```bash
-# Requires 0.5.4+ containing #372; verify publication/installation (0.5.3 ignores the flag).
+# Verify the installed version supports the native-tool opt-out and /cursor-abort.
 # MCP-only local agent; explicitly expose Pi builtins through the Pi execution path.
 PI_CURSOR_NATIVE_TOOLS=0 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 PI_CURSOR_SETTING_SOURCES=none pi --model cursor/grok-4.6
 
@@ -117,7 +117,7 @@ Run `/cursor-cloud list` to see agents recorded for your session branch. Read th
 | Models appear, but a run fails | Run `/login` with an API key for Cursor SDK. Run `/cursor-refresh-models`. |
 | First reply is slow | Check configured Cursor MCP servers. Read [settings and connection limits](docs/reference.md#first-cursor-message-is-slow-10-seconds). |
 | Streams fail behind a VPN or proxy | Run `/cursor-http on`. This changes the local SDK transport only. |
-| Fallback catalog remains with a saved key | Read the [startup refresh limit](docs/reference.md#model-catalog-cache) for official Pi 1.0.4 and 1.1.0. |
+| Fallback catalog remains with a saved key | Read the [startup refresh limit](docs/reference.md#model-catalog-cache) for affected Pi versions. |
 
 See [Troubleshooting](docs/reference.md#troubleshooting) for other problems. [Report a bug](https://github.com/fitchmultz/pi-cursor-sdk/issues) with Pi/extension versions, model, flags, exact prompt, and a redacted session.
 

package/dist/cursor-fallback-models.generated.js

@@ -1,4 +1,4 @@
-// Generated with @cursor/sdk@1.0.37 from 48 Cursor models.
+// Generated with @cursor/sdk@1.0.40 from 49 Cursor models.
 // Refresh with: npm run refresh:cursor-snapshots -- --write
 // Do not add secrets; this file stores public model metadata only.
 export const FALLBACK_MODEL_ITEMS = [
@@ -4794,6 +4794,10 @@ export const FALLBACK_MODEL_ITEMS = [
         variants: [
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4811,6 +4815,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4828,6 +4836,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4845,6 +4857,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4862,6 +4878,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4879,6 +4899,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4896,6 +4920,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4913,6 +4941,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4930,6 +4962,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4947,6 +4983,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "300k"
@@ -4964,6 +5004,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -4981,6 +5025,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -4998,6 +5046,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5016,6 +5068,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5033,6 +5089,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5050,6 +5110,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5067,6 +5131,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5084,6 +5152,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5101,6 +5173,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -5118,6 +5194,10 @@ export const FALLBACK_MODEL_ITEMS = [
             },
             {
                 params: [
+                    {
+                        id: "cyber",
+                        value: "false"
+                    },
                     {
                         id: "context",
                         value: "1m"
@@ -6262,6 +6342,86 @@ export const FALLBACK_MODEL_ITEMS = [
             }
         ]
     },
+    {
+        id: "deepseek-v41-flash-1017",
+        displayName: "DeepSeek V4.1 Flash 1017",
+        parameters: [
+            {
+                id: "reasoning_effort",
+                displayName: "Reasoning",
+                values: [
+                    {
+                        value: "none",
+                        displayName: "None"
+                    },
+                    {
+                        value: "low",
+                        displayName: "Low"
+                    },
+                    {
+                        value: "medium",
+                        displayName: "Medium"
+                    },
+                    {
+                        value: "high",
+                        displayName: "High"
+                    },
+                    {
+                        value: "max",
+                        displayName: "Max"
+                    }
+                ]
+            }
+        ],
+        variants: [
+            {
+                params: [
+                    {
+                        id: "reasoning_effort",
+                        value: "none"
+                    }
+                ],
+                displayName: "DeepSeek V4.1 Flash 1017 None"
+            },
+            {
+                params: [
+                    {
+                        id: "reasoning_effort",
+                        value: "low"
+                    }
+                ],
+                displayName: "DeepSeek V4.1 Flash 1017 Low"
+            },
+            {
+                params: [
+                    {
+                        id: "reasoning_effort",
+                        value: "medium"
+                    }
+                ],
+                displayName: "DeepSeek V4.1 Flash 1017 Medium"
+            },
+            {
+                params: [
+                    {
+                        id: "reasoning_effort",
+                        value: "high"
+                    }
+                ],
+                displayName: "DeepSeek V4.1 Flash 1017 High"
+            },
+            {
+                params: [
+                    {
+                        id: "reasoning_effort",
+                        value: "max"
+                    }
+                ],
+                displayName: "DeepSeek V4.1 Flash 1017 Max",
+                isDefault: true
+            }
+        ]
+    },
     {
         id: "default",
         displayName: "Auto",

package/dist/cursor-local-run-terminal-error.js

@@ -0,0 +1,57 @@
+const watchedRunsByStore = new WeakMap();
+const terminalErrors = new WeakMap();
+const TERMINAL_RUN_STATUSES = new Set(["finished", "error", "cancelled", "expired"]);
+// A failed local SDK run leaves its native tool processes running, and Run.cancel() stops them only
+// while run.status is "running". The SDK awaits the terminal run-row write before it changes
+// run.status, so cancelling from that write is ordered before the change, not racing it.
+function onRunRowWrite(watched, row) {
+    const run = watched.get(row.runId);
+    if (!run || !TERMINAL_RUN_STATUSES.has(row.status))
+        return;
+    watched.delete(row.runId);
+    if (row.status !== "error" || run.status !== "running")
+        return;
+    terminalErrors.set(run, { message: row.error?.trim() || "Cursor SDK run failed." });
+    run.cancel().catch(() => { });
+}
+/** Wraps a local store so watched runs are cancelled while still running when the SDK records a terminal error. */
+export function observeCursorLocalRunTerminalErrors(store) {
+    const watched = new Map();
+    const { runs } = store;
+    const observed = {
+        agents: store.agents,
+        checkpoints: store.checkpoints,
+        runEvents: store.runEvents,
+        runs: {
+            get: (input) => runs.get(input),
+            create: (input) => runs.create(input),
+            delete: (input) => runs.delete(input),
+            list: (input) => runs.list(input),
+            update: async (input) => {
+                try {
+                    return await runs.update(input);
+                }
+                finally {
+                    onRunRowWrite(watched, input.run);
+                }
+            },
+        },
+    };
+    watchedRunsByStore.set(observed, watched);
+    return observed;
+}
+/**
+ * Call as soon as send() resolves. A run can only fail with native tools running after network
+ * input, which cannot be processed before this continuation.
+ */
+export function watchCursorLocalRunTerminalError(store, run) {
+    if (run.status === "running")
+        watchedRunsByStore.get(store)?.set(run.id, run);
+}
+/** Restores the SDK failure that terminal-error cancellation turned into a "cancelled" wait result. */
+export function resolveCursorLocalRunTerminalError(run, waitResult, callerAborted) {
+    const terminalError = terminalErrors.get(run);
+    if (!terminalError || callerAborted || waitResult.status !== "cancelled")
+        return waitResult;
+    return { ...waitResult, status: "error", error: terminalError };
+}

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

@@ -4,6 +4,7 @@ import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-w
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { isCursorRunFinishedSuccessfully, resolveCursorRunOutcome, } from "./cursor-provider-run-outcome.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { resolveCursorLocalRunTerminalError } from "./cursor-local-run-terminal-error.js";
 export async function cacheSdkContextWindow(agentId, modelId, cwd, store) {
     try {
         const { createAgentPlatform } = await loadCursorSdk();
@@ -91,6 +92,7 @@ export async function awaitFinalizeCursorRunOutcome(params) {
     let waitResult;
     try {
         waitResult = params.waitResult ?? (await params.run.wait());
+        waitResult = resolveCursorLocalRunTerminalError(params.run, waitResult, params.signal?.aborted === true);
     }
     catch (error) {
         await recordCursorProviderTerminalUsage(params.prepared, params.signal?.aborted ? "abort" : "error");

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

@@ -3,6 +3,7 @@ import { createCursorCloudLifecyclePersistenceError } from "./cursor-cloud-lifec
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { consumeCursorLocalForceOverride } from "./cursor-runtime-state.js";
 import { recordCursorSessionAgentLineage } from "./cursor-session-agent-lineage.js";
+import { watchCursorLocalRunTerminalError } from "./cursor-local-run-terminal-error.js";
 const CLOUD_LEDGER_CANCEL_TIMEOUT_MS = 5000;
 async function requestBoundedCloudRunCancellation(run) {
     let timer;
@@ -105,6 +106,8 @@ export async function sendCursorProviderTurn(sendParams) {
             recordCursorSessionAgentLineage(agent.agentId, params.scope.scopeKey);
         }
         const run = await runPromise;
+        if (prepared.runtimeTarget === "local")
+            watchCursorLocalRunTerminalError(prepared.store, run);
         sdkRun = run;
         runtime.sdkRun = run;
         try {

package/dist/cursor-session-store.js

@@ -5,6 +5,7 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep, toNamespacedPath } from "node:path";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { guardCursorCustomStorePath, normalizeCursorCustomStoreRoot, prepareCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
+import { observeCursorLocalRunTerminalErrors } from "./cursor-local-run-terminal-error.js";
 let sdkOperationsForTests;
 const activeWorkspaceRoots = new Map();
 // ponytail: leases protect only extension-owned stores in this process. Other SDK
@@ -244,7 +245,7 @@ async function openOwnedCursorSessionStore(cwd, identity, options) {
     const openedStore = store;
     return {
         identity: openedIdentity,
-        store: openedStore,
+        store: observeCursorLocalRunTerminalErrors(openedStore),
         dispose: async () => {
             try {
                 await openedStore.dispose();

package/docs/cursor-live-smoke-checklist.md

@@ -71,7 +71,7 @@ Pass criteria:
 
 - `node --version` reports Node 24+.
 - `pi --version` reports official Pi 0.87.1 or the selected official-latest/current-`fitchmultz/pi` compatibility target.
-- `npm ls` shows exact `@cursor/sdk@1.0.37`; development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 1.1.0 with matching lockfile-resolved Pi cohort, nested host TypeBox 1.3.27 and root validation TypeBox 1.3.36; and the bundled bridge runtime closure `@modelcontextprotocol/server@2.3.1`, `@modelcontextprotocol/hono@2.0.2`, `hono@4.13.13`, and `@hono/node-server@2.1.3`. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run.
+- `npm ls` shows exact `@cursor/sdk@1.0.40`; development `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` 1.1.0 with matching lockfile-resolved Pi cohort, nested host TypeBox 1.3.27 and root validation TypeBox 1.3.36; and the bundled bridge runtime closure `@modelcontextprotocol/server@2.3.1`, `@modelcontextprotocol/hono@2.0.2`, `hono@4.13.13`, and `@hono/node-server@2.1.3`. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run.
 - `cursor/grok-4.6` appears in the model list.
 - No Cursor key or auth token is printed.
 - If neither `~/.pi/agent/auth.json` cursor auth nor `CURSOR_API_KEY` is available, stop and report the live smoke as blocked.
@@ -136,7 +136,7 @@ Pass criteria:
 
 ## 4. Focused visual card/color rendering check
 
-This is a visual debug menu for changed card/color behavior requiring new live evidence. Select only the relevant category below, or reuse a batched existing platform suite; do not execute the entire list by default. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Node 24+, official Pi 0.87.1 or another current compatibility target, exact `@cursor/sdk@1.0.37`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
+This is a visual debug menu for changed card/color behavior requiring new live evidence. Select only the relevant category below, or reuse a batched existing platform suite; do not execute the entire list by default. It requires offscreen TUI visual inspection, not only JSONL or code review. Use Node 24+, official Pi 0.87.1 or another current compatibility target, exact `@cursor/sdk@1.0.40`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
 
 ```bash
 VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1016-visual.XXXXXX)"

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

@@ -24,7 +24,7 @@ Current implementation notes:
 - Shared SDK initialization resolves the native platform package relative to `@cursor/sdk` before import and sets `CURSOR_TREE_SITTER_VENDOR_DIR` only when unset and both vendored parser entrypoints exist. Explicit overrides remain SDK-owned. This repairs sibling-install native lookup. Static SDK and bridge imports additionally repair the compiled-Bun extension graph; the packed extension was qualified in official compiled Pi 1.0.3 on macOS arm64 with isolated empty credentials and a fake key. Embedded Windows missing-export behavior remains unqualified.
 - The selected vendor path is process-wide and inherited by shell commands and child Pi processes. A child using another install/worktree preserves the inherited value as an explicit override, even when stale. Unset it in the child's environment to rediscover that install's parser, or provide its absolute vendor path; see [native parser troubleshooting](reference.md#native-shell-parsing-or-module-loading-fails).
 - Provider and discovery errors retain bounded, scrubbed name/code/message/cause fields without serializing arbitrary error objects. Module-loading and ambiguous session-authentication failures do not imply a rejected API key. Explicit key rejection retains actionable setup guidance; no automatic reload or authentication recovery is performed.
-- Exact `@cursor/sdk@1.0.37` is an unbundled package dependency; users do not need a global SDK install. This package requires Node 24+ and official Pi 0.87.1+, while optional published Pi and TypeBox peer dependencies use `"*"` ranges per Pi guidance. Direct development Pi dependencies and their lockfile-resolved Pi cohort are 1.1.0 reproducible snapshots, not qualification targets or user runtime upgrades; nested host TypeBox remains 1.3.27; the extension's root TypeBox validation baseline is 1.3.36.
+- Exact `@cursor/sdk@1.0.40` is an unbundled package dependency; users do not need a global SDK install. This package requires Node 24+ and official Pi 0.87.1+, while optional published Pi and TypeBox peer dependencies use `"*"` ranges per Pi guidance. Direct development Pi dependencies and their lockfile-resolved Pi cohort are 1.1.0 reproducible snapshots, not qualification targets or user runtime upgrades; nested host TypeBox remains 1.3.27; the extension's root TypeBox validation baseline is 1.3.36.
 - Native usage contains coherent current-context components only. The origin-owned ledger records every raw turn, original wait/handle snapshots, terminal success/error/abort/abandon, and bounded public whole-agent `getUsage()` observations separately. Cumulative bills never enter native usage. Request floors use actual native source chronology and projection equivalence, not text or clocks; see [Context and accounting boundaries](#context-and-accounting-boundaries).
 - Cursor owns one public native Provider with native API-key login and a small resolver for stored/provider-env, runtime, composed config, and ambient credentials. Startup and auth mutations are cache-only, retaining known cached/fallback identities. `PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT=1` hides only unauthenticated picker/list availability, not CLI selection or login. Discovery receives explicit effective native auth and never guesses a default auth store. `/cursor-refresh-models` uses native registry refresh/publication. Provider turns keep Pi's resolved `options.apiKey`; non-secret Cursor-only settings remain separate.
 - Cursor Cloud repository overrides accept only HTTPS repository URLs without userinfo, query parameters, or fragments. Invalid values fail during preflight before `Agent.create()`, messages never echo the supplied URL, and shared provider/maintainer scrubbing removes URL/SCP-style userinfo defensively.
@@ -161,7 +161,9 @@ Both modes call `Cursor.models.list({ apiKey })` and use the same sanitizer and
 
 The authenticated SDK 1.0.37 catalog-only refresh on 2026-10-07 returned 46 models, adding Claude Haiku 5.5 (`claude-haiku-5-5`) while preserving all 45 model records from the SDK 1.0.36 capture on 2026-10-06. That refresh's generated header recorded SDK 1.0.37 and the 46-model count. Haiku 5.5 exposes 20 variants across `thinking=false|true`, `context=300k|1m`, and `reasoning_effort=low|medium|high|xhigh|max`; its default is `thinking=true`, `context=1m`, `reasoning_effort=high`. The 33 bundled checkpoint-derived entries were unchanged; this refresh started no Agent/model turn or Cloud run and does not qualify effective checkpoint limits.
 
-The current snapshot is the authenticated SDK 1.0.37 catalog-only refresh on 2026-10-22: 48 models, adding Gemini 4 Argon (`gemini-4-argon`, low/medium/high reasoning with medium default) and Muse Wonder (`muse-wonder-1.0`, 300k/1m contexts and minimal through max reasoning, default 1m/xhigh) while preserving the prior 46 records. Existing generic context/thinking selection handles both; neither adds fast controls or aliases. Preserve SDK variant labels verbatim. The 33 checkpoint-derived entries remain unchanged; this refresh started no Agent/model turn or Cloud run and establishes no new checkpoint limit.
+The authenticated SDK 1.0.37 catalog-only refresh on 2026-10-22 returned 48 models, adding Gemini 4 Argon (`gemini-4-argon`, low/medium/high reasoning with medium default) and Muse Wonder (`muse-wonder-1.0`, 300k/1m contexts and minimal through max reasoning, default 1m/xhigh) while preserving the prior 46 records. Existing generic context/thinking selection handles both; neither adds fast controls or aliases.
+
+The current snapshot is the authenticated SDK 1.0.40 catalog-only refresh on 2026-10-31: 49 models, adding DeepSeek V4.1 Flash 1017 (`deepseek-v41-flash-1017`, reasoning effort none/low/medium/high/max with max default) while retaining the prior 48 model IDs. All 20 Claude Opus 5.5 variants now include `cyber=false`. Preserve SDK variant labels verbatim. The 33 checkpoint-derived entries remain unchanged; this refresh started no Agent/model turn or Cloud run and establishes no new checkpoint limit.
 
 Dated evidence for Cursor's assistant-visible, model-specific system text and reconstructed tool guidance lives in [Cursor System Prompts and Tool Guidance — 2026-08-02](https://github.com/fitchmultz/pi-cursor-sdk/blob/main/docs/evidence/cursor-system-prompts-2026-08-02/README.md). Keep that evidence separate from pi-cursor-sdk's own bootstrap prompt: Cursor persists its base system message in the local SDK checkpoint, while this extension sends Pi context and bridge instructions as user content.
 

package/docs/cursor-native-tool-visual-audit.md

@@ -6,7 +6,7 @@ This workflow is the canonical repo path for verifying Cursor SDK tool replay th
 
 Use it when changed replay-card behavior needs new visual proof not covered by offline rendering contracts or valid retained evidence. Text logs and JSONL are not enough for visual-parity claims: keep PNGs for the exact prompt, and before/after PNGs for a rendering comparison. Reuse a valid retained baseline instead of paying to recreate it.
 
-Current validation baseline: Node 24+, exact `@cursor/sdk@1.0.37`, official Pi 0.87.1/latest and current `fitchmultz/pi` main. Development Pi packages `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` are exact locked 1.1.0 snapshots, with host TypeBox 1.3.27. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run. Optional published Pi and TypeBox peer dependencies use `"*"` ranges per Pi guidance.
+Current validation baseline: Node 24+, exact `@cursor/sdk@1.0.40`, official Pi 0.87.1/latest and current `fitchmultz/pi` main. Development Pi packages `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` are exact locked 1.1.0 snapshots, with host TypeBox 1.3.27. These locked development snapshots are not qualification targets; resolve latest stable official Pi and current `fitchmultz/pi` main once per workflow run. Optional published Pi and TypeBox peer dependencies use `"*"` ranges per Pi guidance.
 
 ## Cursor SDK 1.0.17 / pi 0.79.0 cutover visual record
 

package/docs/cursor-testing-lessons.md

@@ -84,6 +84,12 @@ SDK 1.0.37 does materially change its vendored transport/retry source: HTTP/2 pi
 
 The 60-second MCP protocol default and lack of a public timeout option remain. SDK 1.0.37's internal `setToolCallRequestOptions`, `setToolCallOutputSchemaPassthrough` and `setListingDeadline` each occur only as definitions in the inspected ESM JavaScript, with no invocation found. They are not supported public setters or proof of readiness; preserve the extension's verified timeout compatibility path rather than adding private patches. The new public `computerUse` output variant uses the existing bounded generic replay fallback, not dedicated action/screenshot rendering or a new local execution option; see the [canonical replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix).
 
+### SDK 1.0.40 hook maintenance boundary
+
+The 1.0.40 pin has a concrete compatibility/security reason beyond its version number. Both 1.0.37 and 1.0.40 load enabled Claude user/project hook settings, but only 1.0.40 enables nested `hookSpecificOutput` compatibility in the LOCAL hook runtime factory. A successful command hook returning only nested `permissionDecision: "deny"` or `updatedInput` otherwise leaves the top-level fields consumed by the adapters absent. SDK 1.0.40 also adds Windows native exit-code propagation and UTF-8 payload handling; exit 2 denotes denial, while other nonzero exits normally require `failClosed` to block.
+
+`test/cursor-sdk-hook-compatibility-contract.test.ts` reuses the installed-module harness to discover that factory structurally, observe its lexical binding in a test-only evaluation, load fresh project Claude settings, and execute a harmless Node hook child. It checks nested denial/rewrite, output precedence/event guards, UTF-8 stdin and native exit-2 handling. Original fixtures are retained when `PI_CURSOR_TEST_EVIDENCE_DIR` is set. Linux results do not qualify Windows PowerShell; the unchanged native Windows CI runs this contract too. The rewritten command is not executed, and neither a public Agent/model request nor Pi/rtk policy enforcement is tested. These checks do not close #173 or qualify #206/#233/#247/#257/#282/#339; SDK 1.0.40 still exposes neither commit nor PR attribution control (#302). Preserve all earlier package/canary/catalog observations at their actual versions and dates.
+
 ## Maintainer-only offline proof retention
 
 Native SQLite fixtures should open the public `SqliteLocalAgentStore` from `@cursor/sdk/sqlite` with an explicit `stateRoot` under their temporary directory, pass it as `localStore` to `createAgentPlatform`, and await `dispose()` in `finally` before removing that directory. `scopedWorkspaceRef` filters agents; it does not relocate storage. Assert the owned `index.db` exists to guard isolation. A fresh missing-agent `checkpointStore.loadLatest()` returning `null` checks the lookup boundary, not per-agent checkpoint database I/O; see `test/cursor-sdk-lazy-import.test.ts`.
@@ -355,7 +361,7 @@ The script writes timestamped artifacts under `--out` (default `/tmp/pi-cursor-s
 
 Stdout prints artifact paths and summary counts only. Raw payloads stay on disk and may contain local paths, project text, tool args/results, or secrets — do not commit or share them.
 
-Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current validation targets Node 24+, exact `@cursor/sdk@1.0.37`, official Pi 0.87.1/latest, and current `fitchmultz/pi` main.
+Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current validation targets Node 24+, exact `@cursor/sdk@1.0.40`, official Pi 0.87.1/latest, and current `fitchmultz/pi` main.
 
 ## Pi provider SDK event capture
 

package/docs/cursor-tool-surfaces.md

@@ -4,7 +4,7 @@ pi-cursor-sdk runs Cursor models through the local `@cursor/sdk` agent runtime b
 
 ## The three surfaces
 
-**Version boundary:** the MCP-only opt-out (`PI_CURSOR_NATIVE_TOOLS`) and `/cursor-abort` require **0.5.4 or later**, including [#372](https://github.com/fitchmultz/pi-cursor-sdk/pull/372). Source checkouts preparing 0.5.4 remain candidates until exact npm/GitHub publication records exist; verify the installed artifact separately. Published **0.5.3 ignores the flag and has no such command**. Do not treat these examples as enforcement on an older installed package, or infer feature availability from a development version label alone.
+**Version boundary:** the MCP-only opt-out (`PI_CURSOR_NATIVE_TOOLS`) and `/cursor-abort` require **0.5.4 or later**, including [#372](https://github.com/fitchmultz/pi-cursor-sdk/pull/372). Published **0.5.3 ignores the flag and has no such command**. Verify the installed version before relying on these controls; a development version label alone does not prove availability.
 
 | Surface | Who owns it | Callable by Cursor? | What pi shows |
 | --- | --- | --- | --- |
@@ -18,14 +18,14 @@ Pi CLI tool toggles apply at the pi tool-registry boundary. `--no-tools`, `--too
 
 ## Opt-in MCP-only local turns
 
-This section requires the 0.5.4+ implementation and publication/installation check described above; it is not available in published npm 0.5.3.
+This section requires the supporting installed version described above; the controls are not available in published npm 0.5.3.
 
 `PI_CURSOR_NATIVE_TOOLS=0` restricts **ordinary LOCAL** agents through the public SDK `AgentOptions.tools: ["mcp"]`. All other main-agent tools are omitted, including native `task`/subagents (whose own curated toolsets do not inherit a main-loop restriction). Unset, blank, unrecognized, or enabled values preserve the SDK's default toolset. The canonical boolean parser accepts `0`, `false`, `off`, `none`, `no`, and `disabled` as off, and `1`, `true`, `on`, `yes`, and `enabled` as on, case-insensitively with surrounding whitespace ignored.
 
 To send file/shell work through Pi's normal execution and `tool_call` hook boundary instead of native Cursor tools:
 
 ```bash
-# Requires 0.5.4+ containing #372; verify publication/installation (0.5.3 ignores the flag).
+# Verify the installed version supports these controls (0.5.3 ignores the flag).
 PI_CURSOR_NATIVE_TOOLS=0 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 PI_CURSOR_SETTING_SOURCES=none pi --model cursor/grok-4.6
 ```