pi-cursor-sdk 0.1.51 → 0.1.53

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+## 0.1.53 - 2026-06-29
+
+### Changed
+
+- Use real per-turn Cursor SDK usage when available, including cache read/write fields, while keeping local prompt/output estimates as the no-SDK-usage fallback. SDK-attributed context occupancy is pinned to latest-turn input plus output so cumulative run input and cache reads do not overstate compaction pressure; fallback context occupancy uses the replayable context estimate so split tool turns do not show a tiny footer percentage next to large input counts.
+- Shorten Cursor bootstrap and incremental prompt boundary text while preserving host-tool, configured MCP, pi bridge, exact-output, shell cwd, plan-mode, and latest-image guidance. The callable-surface manifest remains enabled by default but uses compact wording for Cursor host/configured MCP tools and pi tools/bridge exposure.
+
+### Fixed
+
+- Resolve standalone Windows platform-smoke suite setup by resolving the local `pi` CLI after target dependencies are installed instead of falling back to a missing global `pi.cmd`.
+
+### Validation
+
+- Usage accounting regression tests prove the old 6.7M cumulative fixture now reports per-turn input `25,432`, cache read `24,000`, and context `26,044` instead of a sub-1k char/4 estimate or cumulative input.
+- Prompt-builder measurement reduced pi's local bootstrap estimate from 537 to 367 tokens for explicit no-bridge eval prompts and from 546 to 367 tokens for interactive bridge prompts; this is not a claim about real Cursor token savings because SDK/Cursor-side settings, rules, and tool schemas dominate actual usage.
+- `pi-model-eval` default-seed HumanEval+ smoke for `cursor/gpt-5.5@272k (medium)` passed 5/5 with average pi-estimated input reduced from 721.2 to 648.2 on the same first five tasks; real Cursor usage is now reported from SDK usage when available.
+- Focused live smokes verified exact-output, Cursor-native file read, pi bridge `pi__read`, and corrected footer context percentages after split tool turns.
+- `npm run verify`, `npm pack --dry-run`, and `npm run smoke:platform:all` pass locally; release-review subagent returned no findings.
+
+## 0.1.52 - 2026-06-28
+
+### Fixed
+
+- Serialize Cursor provider turns per pi session scope so parallel same-session Cursor model evaluations cannot supersede each other's SDK session agent or drain the wrong live run. Queued aborts now return an aborted stream without creating a Cursor SDK agent or leaking the turn queue.
+
+### Validation
+
+- `npm run check:platform-smoke`, `npm run typecheck`, `npm test` (796 tests), and `npm publish --dry-run` pass locally.
+- `npm run smoke:platform:all` passes on macOS, Ubuntu, and Windows native with Cursor auth. Artifact index: `.artifacts/platform-smoke/latest.json`.
+- Subagent review/fix loop and thermo-nuclear release review completed with final `NO FINDINGS`.
+
 ## 0.1.51 - 2026-06-25
 
 ### Changed

package/README.md

@@ -317,7 +317,7 @@ PI_CURSOR_TOOL_MANIFEST=0 pi --model cursor/composer-2-5
 PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 pi --model cursor/composer-2-5
 ```
 
-On bootstrap sends, a compact **callable tool surfaces** block is injected into the Cursor prompt by default so models see host-tool categories, exposed `pi__*` bridge names for the current run, and a reminder that configured Cursor MCP servers are discovered at runtime (not via pi's tool catalog). It also states that pi's `--no-tools` disables pi tools/bridge exposure only; Cursor SDK host tools and configured Cursor MCP remain controlled by Cursor. Disable with `PI_CURSOR_TOOL_MANIFEST=0`.
+On bootstrap sends, a compact **callable tool surfaces** block is injected into the Cursor prompt by default. It reminds the model that Cursor host/configured MCP tools are controlled by Cursor, while pi tool toggles only affect pi tools/bridge exposure; when bridge tools are exposed, it lists the current `pi__*` names. Disable with `PI_CURSOR_TOOL_MANIFEST=0`.
 
 `PI_CURSOR_PI_TOOL_BRIDGE=0` is the supported rollback flag and disables the bridge entirely. The bridge also treats `false`, `off`, `none`, `no`, and `disabled` as off; `1`, `true`, `on`, `yes`, and `enabled` as on. `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1` opts in to exposing overlapping pi tool names that Cursor already has native equivalents for. The installed Cursor SDK uses a 60-second MCP protocol default with no public per-server timeout option. pi-cursor-sdk overrides that seam in two directions by default: MCP `callTool` requests are extended to 3600 seconds for long-running local MCP tools (including the pi bridge and configured Cursor MCP servers), and known MCP initialize/listTools requests on first send are shortened to 10 seconds so unavailable configured MCP servers fail fast instead of blocking for a full minute. Unknown Cursor SDK MCP protocol timeout stacks keep the SDK default instead of being shortened. Override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and first-send initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`. `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` is off by default and emits typed, allowlisted, scrubbed single-line JSONL records to `process.stderr`. These records are operational diagnostics, not anonymous telemetry: they intentionally include tool names, safe correlation IDs, bridge run state, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. They must not include endpoint URLs, endpoint path components, endpoint tokens, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, API keys, bearer tokens, cookies, session credentials, or secrets. Do not enable or share bridge debug logs where tool names themselves are sensitive.
 
@@ -354,7 +354,7 @@ Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-k
 - **AGENTS.md / CLAUDE.md are not duplicated on Cursor models when Cursor loads the same rules.** Pi discovers global and project context files (`AGENTS.md`, `CLAUDE.md`, and case variants) unless you start with `-nc`. On `cursor/*` models the extension removes only `<project_instructions>` blocks that overlap Cursor `settingSources` via the `before_agent_start` hook: `user` for `~/.pi/agent/AGENTS.md`, `project` for repo/parent `AGENTS.md` and `CLAUDE.md` (verified Cursor behavior: local agents load project `AGENTS.md` and `CLAUDE.md` alongside Cursor rules). `~/.pi/agent/CLAUDE.md` is not stripped (Cursor user rules use `~/.claude/CLAUDE.md`, not pi's agent dir). With `PI_CURSOR_SETTING_SOURCES=none` or `plugins`-only, pi context is left intact. Set `PI_CURSOR_PRESERVE_PI_AGENTS_MD=1` to keep duplicate injection.
 - **Max Mode is not a manual pi variant.** Cursor's SDK may enable Max Mode automatically for models that require it. This extension only advertises exact context-window variants that the SDK catalog exposes and otherwise uses conservative SDK-derived default/non-Max context windows.
 - **Output token limits are conservative.** Cursor SDK model metadata does not currently expose output token limits directly.
-- **Token usage is approximate in pi.** Cursor SDK usage events include cumulative internal agent/tool/cache work, so raw Cursor SDK counters are not copied into pi usage. The extension reports an additive replayable-context estimate instead: `output` estimates visible assistant output, `input` estimates the replayable Cursor context before that output, cache fields are zero, and `totalTokens = input + output + cacheRead + cacheWrite`. This keeps pi context display and compaction sizing consistent while avoiding Cursor's cumulative internal counters.
+- **Token usage uses Cursor SDK data when safely attributable.** For turns with in-time SDK usage, pi records the latest per-turn `inputTokens`, `outputTokens`, `cacheReadTokens`, and `cacheWriteTokens`; SDK-backed `totalTokens` stays `inputTokens + outputTokens` so cache reads do not inflate context occupancy. If the SDK reports no usage in time, the extension falls back to local `input/output` activity estimates while setting `totalTokens` to the current replayable context estimate so the footer/compaction percentage does not collapse after split tool turns. Later usage for that live run is ignored rather than risk applying stale usage to the wrong pi turn. Cursor SDK cost is not exposed, so pi cost remains zero/absent.
 
 ## Troubleshooting
 

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

@@ -90,7 +90,7 @@ Pass criteria:
 - Exit code is `0`.
 - stdout contains `PI_CURSOR_SMOKE_OK`.
 - stderr is empty or contains only expected non-secret diagnostics for the specific test.
-- The persisted JSONL has exactly one assistant message with non-negative usage fields and `cacheRead/cacheWrite` equal to `0`.
+- The persisted JSONL has exactly one assistant message with non-negative usage fields and non-negative `cacheRead/cacheWrite`.
 
 ## 2. Default setting-source startup noise check
 
@@ -239,7 +239,7 @@ Pass criteria:
 - Diagnostics include `run_created`, `tools_exposed`, two `request_queued`, two `request_resolved`, and `run_disposed`.
 - The missing-file request has `isError: true`.
 - Persisted JSONL contains real pi tool calls named `read`, matching `toolResult` messages, and final assistant output.
-- Later assistant usage counts consumed tool-result input; no assistant usage has negative values or nonzero cache fields.
+- Later assistant usage counts consumed tool-result input; no assistant usage has negative values.
 
 ## 7. Native replay cards without the pi bridge
 
@@ -346,7 +346,7 @@ Script-enforced pass criteria:
 - Every scanned JSONL file contains at least one assistant message.
 - Every assistant message has usage metadata.
 - Assistant usage `input`, `output`, and `totalTokens` are non-negative numbers.
-- Assistant usage `cacheRead` and `cacheWrite` are exactly `0`.
+- Assistant usage `cacheRead` and `cacheWrite` are non-negative when present.
 
 Additional manual usage checks for provider/accounting changes:
 

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

@@ -31,7 +31,7 @@ Current implementation notes:
 - 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 all 16 `@cursor/sdk@1.0.22` `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/aborted, produced no assistant text, or involved external/side-effectful tools; incomplete fast local discovery starts (`read`, `grep`, `glob`, `ls`) remain maintainer-debug-only after successful text-producing runs so stale SDK start events do not create red post-answer 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.
 - Cursor native replay uses one neutral replay tool name, `cursor`, plus native-compatible card names when renderer-compatible (`read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`). Neutral replay identity lives in `activityTitle`, `activitySummary`, and typed replay details, not in extra registered tool names. Bridge MCP names such as `pi__sem_reindex` are MCP-only; pi session output uses real pi tool names.
-- Cursor SDK usage events report cumulative internal agent/tool/cache work, not the replayable pi prompt context. The extension does not copy raw Cursor SDK usage into pi usage or compaction. For Cursor assistant messages, `usage.output` estimates visible assistant output, `usage.input` estimates the replayable Cursor context before that output, cache fields are zero, and `usage.totalTokens = input + output + cacheRead + cacheWrite`. The input/total estimate is derived from the same `buildCursorPrompt()` path used for `Agent.send` so context display and compaction keep using replayable Cursor context sizing while pi session summaries remain additive. `src/cursor-usage-accounting.ts` owns this usage policy.
+- Cursor SDK usage events are used when the SDK reports them before the corresponding pi turn is emitted. For each SDK-attributed assistant turn, `usage.input`, `usage.output`, `usage.cacheRead`, and `usage.cacheWrite` come from the latest per-turn SDK usage; `usage.totalTokens = latestTurn.inputTokens + latestTurn.outputTokens` so cache reads do not inflate context occupancy. Cumulative `RunResult.usage` is never used for per-message occupancy. If the SDK reports no usage in time, the provider falls back to local `input/output` activity estimates while setting `usage.totalTokens` to the current replayable context estimate so footer/compaction context does not collapse after split tool turns; after a split live-run turn times out waiting for SDK usage, later SDK usage for that live run is ignored rather than risk applying stale usage to the wrong pi turn. Cursor SDK cost is unavailable, so cost remains absent/zero. `src/cursor-usage-accounting.ts` owns this policy.
 - Audit observation, 2026-05-19, superseded by the 2026-05-21 replay pass and #68 incomplete visibility, then narrowed by the 2026-05-26 fast-local suppression: a missing-file read with Composer 2.5 emitted `tool-call-started` for Cursor `read`, then streamed final text `Error: File not found`, but did not emit `tool-call-completed` or an `onStep` `toolCall` error result. Leftover external/side-effectful started calls are surfaced at run completion through the same native replay routing as completed tools (activity cards when allowed, otherwise inactive/transcript traces), while fast local discovery starts are debug-only after a successful text-producing run. Cursor-reported completed/step errors remain visible.
 - Maintainer visual verification for replay-card changes should follow [Cursor Native Tool Visual Audit Workflow](./cursor-native-tool-visual-audit.md): offscreen PTY-driven pi run, xterm.js/Playwright screenshot rendering, and JSONL inspection before accepting commits or PRs.
 - Cursor provider/runtime releases must pass the [Platform Smoke Gate](./platform-smoke.md): `npm run smoke:platform:doctor && npm run smoke:platform:all`. Use [Cursor Live Smoke Checklist](./cursor-live-smoke-checklist.md) only for focused inner-loop/debug runs with real `pi --approve -e . --cursor-no-fast --model cursor/composer-2-5` invocations, manual observation, temporary session dirs, diagnostics scans, and persisted JSONL inspection. See [Cursor testing lessons](./cursor-testing-lessons.md) for auth.json seeding, isolated smoke harnesses, and replay JSONL scans. Assume every runtime surface is in scope.

package/docs/cursor-native-tool-replay.md

@@ -182,7 +182,7 @@ Lifecycle rules:
 
 As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results, then continuing with live post-tool Cursor thinking/text, later Cursor tool batches, or Cursor's final answer as the next assistant turn. For plan-mode runs, neutral Cursor plan/todo cards can therefore appear before the final Cursor plan text.
 
-Bridged pi tool calls follow the same visible pi `toolUse` turn shape, but they are real pi tool executions rather than replayed Cursor results. Usage accounting keeps Cursor SDK internal counters out of pi usage and reports an additive replayable-context estimate: `output` estimates visible assistant activity, `input` estimates the replayable Cursor context before that output, cache fields are zero, and `usage.totalTokens = input + output + cacheRead + cacheWrite`.
+Bridged pi tool calls follow the same visible pi `toolUse` turn shape, but they are real pi tool executions rather than replayed Cursor results. Usage accounting uses per-turn Cursor SDK usage when available before the corresponding pi turn is emitted, including cache read/write fields; SDK-backed `usage.totalTokens` remains latest-turn input plus output so cache reads do not inflate context occupancy. If the SDK reports no usage in time, the provider falls back to local `input/output` activity estimates with `usage.totalTokens` set to the current replayable context estimate, then ignores later usage for that live run rather than risk applying stale usage to the wrong pi turn.
 
 For shell replay, completed `stdout` / `stderr` remain the primary source. While exactly one shell call is active, the provider also emits a bounded scrubbed preview of the first few `shell-output-delta` stdout/stderr chunks so long-running commands show visible progress before completion. If a successful completed shell result is empty, the replay card uses unambiguous buffered delta data as display-only fallback data. Overlapping shell calls make delta attribution ambiguous, so those fallback/progress deltas are dropped rather than guessed. `(no output)` is kept only when no completed output or safe delta fallback is available.
 

package/docs/cursor-tool-surfaces.md

@@ -17,7 +17,7 @@ Pi CLI tool toggles apply at the pi tool-registry boundary. `--no-tools`, `--too
 ## Discoverability
 
 - **MCP `listTools`** (and pi's MCP catalog when present) lists **MCP servers only** — for example `pi_tools` with `pi__cursor_ask_question`. It does **not** enumerate Cursor SDK host tools such as `Read` or `Shell`.
-- **Bootstrap prompts** include a short **Cursor SDK tool boundary** block plus a compact **callable tool surfaces** manifest by default (disable manifest with `PI_CURSOR_TOOL_MANIFEST=0`). The manifest lists host-tool categories, bridge `pi__*` names for the current run, and a reminder that configured Cursor MCP servers appear at runtime via `listTools`. MCP `listTools` entries for bridged pi tools point back to the bootstrap prompt instead of repeating the full contract.
+- **Bootstrap prompts** include a short **Cursor SDK tool boundary** block plus a compact **callable tool surfaces** manifest by default (disable manifest with `PI_CURSOR_TOOL_MANIFEST=0`). The manifest reminds the model that Cursor host/configured MCP tools are controlled by Cursor, while pi tool toggles only affect pi tools/bridge exposure; when bridge tools are exposed, it lists the current `pi__*` names. MCP `listTools` entries for bridged pi tools point back to the bootstrap prompt instead of repeating the full contract.
 - **Incremental prompts** omit the full boundary block but keep a short tail guard (including an explicit shell `cd` hint); the session agent retains prior bootstrap context.
 - **In-session debug:** `/cursor-tools` prints bridge enablement, manifest enablement, effective `PI_CURSOR_SETTING_SOURCES`, and the current callable-surface snapshot.
 

package/docs/platform-smoke.md

@@ -481,8 +481,7 @@ Required JSONL evidence:
 - successful native `find` result proving `src/cursor-provider.ts` was enumerated;
 - failed shell result with `isError=true` and `native shell failure` output;
 - final assistant message's last non-empty `text` part contains `NATIVE_MATRIX_OK`;
-- assistant usage fields are non-negative;
-- `cacheRead=0` and `cacheWrite=0`.
+- assistant usage fields are non-negative.
 
 ### `cursor-bridge-visual-matrix`
 
@@ -556,8 +555,7 @@ Required JSONL evidence:
 - real pi tool call named `read`, failure;
 - real pi tool call named `bash`, success;
 - final assistant message's last non-empty `text` part contains `BRIDGE_MATRIX_OK`;
-- assistant usage fields are non-negative;
-- `cacheRead=0` and `cacheWrite=0`.
+- assistant usage fields are non-negative.
 
 ### `cursor-abort-cleanup`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cursor-sdk",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "pi provider extension backed by @cursor/sdk local agents",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",

package/scripts/platform-smoke/live-suite-runner.mjs

@@ -581,7 +581,6 @@ async function main() {
 	try {
 		console.log(`[platform-live] suite=${args.suite} target=${args.target} model=${args.model}`);
 		copyFixtureWorkspace(workspaceDir);
-		const piCli = resolvePiCli();
 		const piEnv = { ...process.env, PI_CODING_AGENT_DIR: agentDir, PI_OFFLINE: "1" };
 		let installPath = `./node_modules/${packageName}`;
 		if (args.prepDir) {
@@ -603,6 +602,7 @@ async function main() {
 			const npmInstallPacked = runLogged(logDir, "workspace-npm-install-packed", commandName("npm"), ["install", "--no-save", tarballPath], { cwd: workspaceDir, timeout: 180_000 });
 			requireOk(npmInstallPacked, "workspace npm install packed tarball");
 		}
+		const piCli = resolvePiCli();
 		const install = runLogged(logDir, "pi-install", piCli, ["install", "--approve", "-l", installPath], { cwd: workspaceDir, env: piEnv, timeout: 120_000 });
 		requireOk(install, "pi install --approve packed package directory");
 		const list = runLogged(logDir, "pi-list", piCli, ["list", "--approve"], { cwd: workspaceDir, env: piEnv, timeout: 60_000 });

package/scripts/platform-smoke/targets.mjs

@@ -638,7 +638,6 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 		{ id: "provider-debug-artifacts", fn: () => providerDebugFiles.some((file) => file.endsWith("session.json")) && providerDebugFiles.length > 1 },
 		...(suiteName !== "cursor-abort-cleanup" ? [
 			{ id: "jsonl-usage-non-negative", fn: () => usageChecks.seen && usageChecks.nonNegative },
-			{ id: "jsonl-cache-zero", fn: () => usageChecks.seen && usageChecks.cacheZero },
 		] : []),
 		{ id: "final-marker", fn: () => scenario?.finalMarker ? status?.finalMarkerObserved === true : status?.ok === true },
 		...(suiteName === "cursor-abort-cleanup" ? [{ id: "abort-no-successful-answer", fn: () => !hasAbortSuccessClaim(jsonlRaw) }] : []),
@@ -798,7 +797,6 @@ function collectBridgeDiagnostics(terminalText) {
 function collectUsageChecks(jsonlRaw) {
 	let seen = false;
 	let nonNegative = true;
-	let cacheZero = true;
 	for (const line of jsonlRaw.split(/\r?\n/)) {
 		if (!line.trim()) continue;
 		let event;
@@ -809,10 +807,10 @@ function collectUsageChecks(jsonlRaw) {
 		for (const value of Object.values(usage)) {
 			if (typeof value === "number" && value < 0) nonNegative = false;
 		}
-		if (typeof usage.cacheRead === "number" && usage.cacheRead !== 0) cacheZero = false;
-		if (typeof usage.cacheWrite === "number" && usage.cacheWrite !== 0) cacheZero = false;
+		if (typeof usage.cacheRead === "number" && usage.cacheRead < 0) nonNegative = false;
+		if (typeof usage.cacheWrite === "number" && usage.cacheWrite < 0) nonNegative = false;
 	}
-	return { seen, nonNegative, cacheZero };
+	return { seen, nonNegative };
 }
 
 export function hasAbortSuccessClaim(jsonlRaw) {

package/scripts/validate-smoke-jsonl.mjs

@@ -37,8 +37,7 @@ Enforced invariants (default mode):
   - each scanned JSONL file contains parseable JSONL records
   - each scanned JSONL file contains at least one persisted assistant message
   - every persisted assistant message has usage metadata
-  - assistant usage input/output/totalTokens are non-negative numbers
-  - assistant usage cacheRead/cacheWrite are exactly 0
+  - assistant usage input/output/totalTokens/cacheRead/cacheWrite are non-negative numbers
 
 Replay error scan (--replay-errors / --replay-errors-only):
   - no persisted error toolResult or error assistant message contains "Tool grep/cursor/find/ls not found"
@@ -79,8 +78,8 @@ function isBadUsage(usage) {
 		!isNonNegativeNumber(usage.input) ||
 		!isNonNegativeNumber(usage.output) ||
 		!isNonNegativeNumber(usage.totalTokens) ||
-		usage.cacheRead !== 0 ||
-		usage.cacheWrite !== 0
+		!isNonNegativeNumber(usage.cacheRead) ||
+		!isNonNegativeNumber(usage.cacheWrite)
 	);
 }
 

package/src/context.ts

@@ -16,54 +16,66 @@ export interface CursorPromptOptions {
 	agentMode?: AgentModeOption;
 	/** Compact callable-surface summary; included on bootstrap prompts when set. */
 	toolManifest?: string;
+	includePiBridgeGuidance?: boolean;
+	includePiAskQuestionGuidance?: boolean;
 }
 
 export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
 export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
-export function getCursorPlanModeToolGuidanceText(agentMode: AgentModeOption | undefined): string | undefined {
+export function getCursorPlanModeToolGuidanceText(
+	agentMode: AgentModeOption | undefined,
+	options: { includePiBridgeGuidance?: boolean } = {},
+): string | undefined {
 	if (agentMode !== "plan") return undefined;
 	return [
 		"Cursor SDK mode is plan for this run. In pi-cursor-sdk, plan mode may still use available Cursor SDK/MCP tools for inspection when needed.",
 		"Safe/read-only shell commands that inspect or print information are allowed when Cursor chooses to call Shell; do not say Shell is blocked by plan mode and then call it anyway.",
-		"Exposed pi__* bridge tools are also callable in plan mode when the user asks for them or they are needed to answer.",
-	].join("\n");
+		options.includePiBridgeGuidance === false
+			? undefined
+			: "Exposed pi__* bridge tools are also callable in plan mode when the user asks for them or they are needed to answer.",
+	].filter((line): line is string => line !== undefined).join("\n");
 }
 
 export function getCursorToolTailGuardText(
-	options: Pick<CursorPromptOptions, "agentMode"> & { includePlanModeGuidance?: boolean } = {},
+	options: Pick<CursorPromptOptions, "agentMode"> & { includePlanModeGuidance?: boolean; includePiBridgeGuidance?: boolean } = {},
 ): string {
 	return [
-		"Shell: use an explicit `cd` to the repo path when running project commands; session cwd may not match paths in tool args.",
-		options.includePlanModeGuidance === false ? undefined : getCursorPlanModeToolGuidanceText(options.agentMode),
-		"Exact-output requests: if the latest user asks to reply exactly, output exactly that text and do not add preambles, diagnostics, or repo checks unless explicitly requested.",
-		"Tool boundary reminder: If a tool is needed, call an available Cursor SDK/MCP tool. Never print a tool card (for example Tool call/Shell/command) as assistant text.",
+		"Shell: use explicit `cd` to repo path for project commands; session cwd may differ from tool args.",
+		options.includePlanModeGuidance === false
+			? undefined
+			: getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance: options.includePiBridgeGuidance }),
+		"Exact-output requests: output exactly the requested text; no preamble or checks unless asked.",
+		"Tools: call available Cursor SDK/MCP tools; never print tool cards as assistant text.",
 	].filter((line): line is string => line !== undefined).join("\n");
 }
 
-function getCursorToolBoundaryText(options: Pick<CursorPromptOptions, "agentMode"> & { hasToolManifest?: boolean } = {}): string {
+function getCursorToolBoundaryText(
+	options: Pick<CursorPromptOptions, "agentMode" | "includePiAskQuestionGuidance"> & { hasToolManifest?: boolean; includePiBridgeGuidance?: boolean } = {},
+): string {
+	const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
+	const includePiAskQuestionGuidance = includePiBridgeGuidance && options.includePiAskQuestionGuidance !== false;
 	const lines = [
 		"Cursor SDK tool boundary:",
-		"Call only tools exposed by Cursor SDK in this run. Pi tool names, replay labels, and transcript names are context only—not callable.",
-		"Bridged pi tools: call pi__* MCP names when exposed, not the pi card name in history. Replay activity is display-only.",
-		"Do not claim pi-side or WebSearch/WebFetch tools unless Cursor executes an equivalent tool.",
-		"Use pi__cursor_ask_question for material choices if exposed.",
-		getCursorPlanModeToolGuidanceText(options.agentMode),
-		"Images: only the latest user message's images are sent as bytes; ask to reattach or describe prior images.",
+		"Call only Cursor SDK/MCP tools exposed in this run; pi history names, replay labels, and transcript names are not callable.",
+		includePiBridgeGuidance
+			? "For exposed pi bridge tools, call pi__* MCP names, not pi card/history names."
+			: undefined,
+		"Do not claim pi-side or WebSearch/WebFetch tools unless Cursor ran an equivalent tool.",
+		includePiAskQuestionGuidance ? "Use pi__cursor_ask_question for material choices if exposed." : undefined,
+		getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance }),
+		"Images: only latest user images are sent; ask to reattach prior images.",
 	].filter((line): line is string => line !== undefined);
 	if (options.hasToolManifest) {
-		lines.push("See callable tool surfaces block below.");
+		lines.push("See callable surfaces below.");
 	}
 	return lines.join("\n");
 }
 
 function getCursorBootstrapTailSections(options: Pick<CursorPromptOptions, "agentMode"> = {}): string[] {
 	return [
-		[
-			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
-			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
-		].join("\n"),
+		"Answer the latest user request above using the instructions and Cursor SDK capabilities available in this run.",
 		getCursorToolTailGuardText({ ...options, includePlanModeGuidance: false }),
 	];
 }
@@ -389,7 +401,12 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 }
 
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ agentMode: options.agentMode, hasToolManifest: Boolean(options.toolManifest) })];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({
+		agentMode: options.agentMode,
+		hasToolManifest: Boolean(options.toolManifest),
+		includePiBridgeGuidance: options.includePiBridgeGuidance,
+		includePiAskQuestionGuidance: options.includePiAskQuestionGuidance,
+	})];
 	if (options.toolManifest) {
 		sectionsBeforeMessages.push(options.toolManifest);
 	}

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

@@ -1,10 +1,13 @@
 import type { Context, Message, ToolResultMessage } from "@earendil-works/pi-ai/compat";
 import { CURSOR_APPROX_CHARS_PER_TOKEN, estimateCursorPromptMessageTokens } from "./context.js";
+import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
 
 export interface CursorLiveRunAccountingState {
 	promptInputTokens: number;
 	promptInputTokensReported: boolean;
 	consumedToolResultIds: ReadonlySet<string>;
+	sdkTurnEnded: boolean;
+	sdkTurnUsage?: CursorSdkTurnUsage;
 }
 
 export interface CursorLiveToolResultConsumption {
@@ -19,9 +22,25 @@ export function createCursorLiveRunAccountingState(promptInputTokens: number): C
 		promptInputTokens,
 		promptInputTokensReported: false,
 		consumedToolResultIds: new Set(),
+		sdkTurnEnded: false,
 	};
 }
 
+export function recordCursorLiveSdkTurnEnded(
+	state: CursorLiveRunAccountingState,
+	sdkTurnUsage?: CursorSdkTurnUsage,
+): CursorLiveRunAccountingState {
+	return { ...state, sdkTurnEnded: true, sdkTurnUsage };
+}
+
+export function takeCursorLiveSdkTurnUsage(state: CursorLiveRunAccountingState): {
+	state: CursorLiveRunAccountingState;
+	sdkTurnUsage?: CursorSdkTurnUsage;
+} {
+	const { sdkTurnUsage, ...nextState } = state;
+	return { state: { ...nextState, sdkTurnEnded: false }, sdkTurnUsage };
+}
+
 function asToolResultMessage(message: Message): ToolResultMessage | undefined {
 	return message.role === "toolResult" ? message : undefined;
 }

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

@@ -3,10 +3,13 @@ import type { SDKAgent } from "@cursor/sdk";
 import {
 	consumeCursorLiveToolResults,
 	createCursorLiveRunAccountingState,
+	recordCursorLiveSdkTurnEnded,
+	takeCursorLiveSdkTurnUsage,
 	takeCursorLiveTurnInputTokens,
 	type CursorLiveRunAccountingState,
 	type CursorLiveToolResultConsumption,
 } from "./cursor-live-run-accounting.js";
+import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
 import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display-state.js";
 import type { CursorPiBridgeToolRequest, CursorPiToolBridgeRun } from "./cursor-pi-tool-bridge.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
@@ -38,6 +41,7 @@ export interface CursorLiveRun {
 	sessionBridgeRun?: CursorPiToolBridgeRun;
 	sessionAgentScopeKey: string;
 	sdkRun?: CursorLiveSdkRun;
+	ignoreFutureSdkTurnUsage?: boolean;
 	accounting: CursorLiveRunAccountingState;
 	pendingEvents: CursorLiveQueuedEvent[];
 	textDeltas: string[];
@@ -77,6 +81,9 @@ export interface CursorLiveRunCoordinator {
 	markFinished(run: CursorLiveRun, finalText: string): void;
 	markCancelled(run: CursorLiveRun, abortMessage?: string): void;
 	markError(run: CursorLiveRun, errorMessage: string): void;
+	recordSdkTurnEnded(run: CursorLiveRun, usage?: CursorSdkTurnUsage): void;
+	ignoreFutureSdkTurnUsage(run: CursorLiveRun): void;
+	hasSdkTurnEnded(run: CursorLiveRun): boolean;
 	queueEvent(run: CursorLiveRun, event: CursorLiveQueuedEvent): void;
 	peekEvent(run: CursorLiveRun): CursorLiveQueuedEvent | undefined;
 	shiftEvent(run: CursorLiveRun): CursorLiveQueuedEvent | undefined;
@@ -84,6 +91,7 @@ export interface CursorLiveRunCoordinator {
 	collectBridgeToolBatch(run: CursorLiveRun): CursorPiBridgeToolRequest[];
 	consumeToolResults(run: CursorLiveRun, context: Context, getReplayId: CursorReplayIdResolver): CursorLiveToolResultConsumption;
 	takeTurnInputTokens(run: CursorLiveRun, toolResultInputTokens: number): number;
+	takeSdkTurnUsage(run: CursorLiveRun): CursorSdkTurnUsage | undefined;
 	getPendingFromContext(context: Context, getReplayId: CursorReplayIdResolver): CursorLiveRun | undefined;
 	getActiveForScope(scopeKey?: string): CursorLiveRun | undefined;
 	isReady(run: CursorLiveRun): boolean;
@@ -328,6 +336,25 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			coordinator.requestIdleDispose(run);
 		},
 
+		recordSdkTurnEnded(run, usage): void {
+			if (run.disposed) return;
+			if (run.ignoreFutureSdkTurnUsage) {
+				run.accounting = { ...run.accounting, sdkTurnEnded: false, sdkTurnUsage: undefined };
+				notifyProgress(run);
+				return;
+			}
+			run.accounting = recordCursorLiveSdkTurnEnded(run.accounting, usage);
+			notifyProgress(run);
+		},
+
+		ignoreFutureSdkTurnUsage(run): void {
+			if (!run.disposed) run.ignoreFutureSdkTurnUsage = true;
+		},
+
+		hasSdkTurnEnded(run): boolean {
+			return run.accounting.sdkTurnEnded;
+		},
+
 		queueEvent(run, event): void {
 			if (run.disposed) return;
 			run.pendingEvents.push(event);
@@ -375,6 +402,12 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			return taken.sessionInputTokens;
 		},
 
+		takeSdkTurnUsage(run): CursorSdkTurnUsage | undefined {
+			const taken = takeCursorLiveSdkTurnUsage(run.accounting);
+			run.accounting = taken.state;
+			return taken.sdkTurnUsage;
+		},
+
 		getPendingFromContext(context, getReplayId): CursorLiveRun | undefined {
 			let index = context.messages.length - 1;
 			while (index >= 0 && context.messages[index]?.role === "user") {

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

@@ -20,7 +20,7 @@ import {
 } from "./cursor-native-tool-display-state.js";
 import { type CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
-import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";
+import { applyCursorUsage } from "./cursor-usage-accounting.js";
 import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import { trimCurrentTurnAlreadyEmittedCursorText } from "./cursor-run-final-text.js";
 import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause } from "./cursor-provider-errors.js";
@@ -105,6 +105,17 @@ export async function settleCursorLiveToolBatch(run: CursorLiveRun): Promise<voi
 	await scheduler.wait(75);
 }
 
+async function waitForCursorLiveSdkTurnEnded(run: CursorLiveRun, signal?: AbortSignal): Promise<boolean> {
+	const deadline = Date.now() + 125;
+	while (!cursorLiveRuns.hasSdkTurnEnded(run) && !run.done && !run.disposed && !run.cancelled && !run.errorMessage) {
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) return false;
+		await scheduler.wait(Math.min(25, remainingMs));
+		if (signal?.aborted) throw new CursorLiveRunAbortError();
+	}
+	return cursorLiveRuns.hasSdkTurnEnded(run);
+}
+
 export function flushPendingCursorLiveRunTraceEventsToStream(
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,
@@ -184,7 +195,9 @@ function emitCursorNativeToolUseTurn(
 			});
 		}
 	}
-	applyCursorApproximateUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens));
+	applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
+		turn: cursorLiveRuns.takeSdkTurnUsage(run),
+	});
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
 	cursorLiveRuns.requestIdleDispose(run);
@@ -229,7 +242,9 @@ function emitCursorBridgeToolUseTurn(
 		const block = partial.content[contentIndex];
 		if (block.type === "toolCall") stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
 	}
-	applyCursorApproximateUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens));
+	applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
+		turn: cursorLiveRuns.takeSdkTurnUsage(run),
+	});
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
 	cursorLiveRuns.requestIdleDispose(run);
@@ -249,6 +264,7 @@ async function emitCursorLiveRunPendingToolUseTurn(
 	const eventType = cursorLiveRuns.peekEvent(run)?.type;
 	if (eventType !== "tool" && eventType !== "bridge-tool") return undefined;
 	await settleCursorLiveToolBatch(run);
+	const sdkTurnEnded = await waitForCursorLiveSdkTurnEnded(run, options.signal);
 	if (options.signal?.aborted) throw new CursorLiveRunAbortError();
 	if (eventType === "tool") {
 		const { active, inactive } = partitionNativeToolsByActiveContext(context, cursorLiveRuns.collectNativeToolBatch(run));
@@ -257,9 +273,11 @@ async function emitCursorLiveRunPendingToolUseTurn(
 			// Inactive-only batch: trace was emitted above; do not emit toolUse.
 			return "handled";
 		}
+		if (!sdkTurnEnded) cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
 		if (options.mode === "emit") turn.emitter.closeAll();
 		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, debugRecorder);
 	} else {
+		if (!sdkTurnEnded) cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
 		if (options.mode === "emit") turn.emitter.closeAll();
 		const requests = cursorLiveRuns.collectBridgeToolBatch(run);
 		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests);
@@ -358,7 +376,9 @@ export async function drainCursorLiveRunTurn(
 				if (finalText) {
 					await emitTextDeltas(stream, partial, splitTextIntoReplayDeltas(finalText));
 				}
-				applyCursorApproximateUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens));
+				applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
+					turn: cursorLiveRuns.takeSdkTurnUsage(run),
+				});
 				partial.stopReason = "stop";
 				stream.push({ type: "done", reason: "stop", message: partial });
 				await cursorLiveRuns.release(run);

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

@@ -24,7 +24,7 @@ import type {
 	CursorProviderTurnSend,
 	CursorProviderTurnSendResult,
 } from "./cursor-provider-turn-types.js";
-import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";
+import { applyCursorUsage } from "./cursor-usage-accounting.js";
 import { hasUsableText } from "./cursor-record-utils.js";
 export type CursorTurnTerminalEvent =
 	| {
@@ -174,7 +174,9 @@ export class CursorRunFinalizer {
 				prepared.runtime.turnCoordinator.flushText(
 					outcome.kind === "finished" && hasUsableText(outcome.finalText) ? [outcome.finalText] : [],
 				);
-				applyCursorApproximateUsage(partial, model, context, prepared.meta.promptInputTokens);
+				applyCursorUsage(partial, model, context, prepared.meta.promptInputTokens, {
+					turn: prepared.runtime.turnCoordinator.lastSdkTurnUsage,
+				});
 				stream.push({ type: "done", reason: "stop", message: partial });
 				break;
 		}

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

@@ -32,6 +32,7 @@ import {
 	CursorToolCompletionLedger,
 	getToolFingerprint,
 } from "./cursor-provider-turn-tool-ledger.js";
+import { readCursorSdkTurnUsageFromUpdate, type CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
 
 export interface CursorSdkTurnCoordinatorOptions {
 	stream: AssistantMessageEventStream;
@@ -63,6 +64,7 @@ export class CursorSdkTurnCoordinator {
 	private readonly displayRouter: CursorTurnDisplayRouter;
 	private readonly lifecycleEmitter: CursorToolLifecycleEmitter;
 	private readonly contentEmitter;
+	private sdkTurnUsage?: CursorSdkTurnUsage;
 
 	constructor(options: CursorSdkTurnCoordinatorOptions) {
 		this.stream = options.stream;
@@ -104,6 +106,10 @@ export class CursorSdkTurnCoordinator {
 		return this.displayRouter.nativeToolReplayStarted;
 	}
 
+	get lastSdkTurnUsage(): CursorSdkTurnUsage | undefined {
+		return this.sdkTurnUsage;
+	}
+
 	discardIncompleteStartedToolCalls(
 		outcome: IncompleteCursorToolRunOutcome = buildIncompleteCursorToolRunOutcome(),
 	): void {
@@ -141,6 +147,11 @@ export class CursorSdkTurnCoordinator {
 	}
 
 	handleDelta(update: InteractionUpdate): void {
+		const sdkTurnUsage = readCursorSdkTurnUsageFromUpdate(update);
+		if (sdkTurnUsage) this.sdkTurnUsage = sdkTurnUsage;
+		if (this.liveRun && (update.type === "turn-ended" || sdkTurnUsage)) {
+			cursorLiveRuns.recordSdkTurnEnded(this.liveRun, sdkTurnUsage);
+		}
 		if (update.type === "text-delta") {
 			this.textDeltas.push(update.text);
 			if (this.liveRun) {

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

@@ -88,8 +88,15 @@ export async function prepareCursorProviderTurn(
 		sessionAgentScopeKey = sessionAgentLease.scopeKey;
 		throwIfAborted();
 
+		let bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
+		let includePiBridgeGuidance = bridgeToolNames.size > 0;
 		const buildPromptOptions = (plan: ReturnType<typeof planCursorSessionSend>) => {
-			const promptOptions = { ...getCursorPromptOptions(model), agentMode };
+			const promptOptions = {
+				...getCursorPromptOptions(model),
+				agentMode,
+				includePiBridgeGuidance,
+				includePiAskQuestionGuidance: bridgeToolNames.has("pi__cursor_ask_question"),
+			};
 			if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
 				return promptOptions;
 			}
@@ -98,6 +105,7 @@ export async function prepareCursorProviderTurn(
 				toolManifest: buildCursorToolManifestText({
 					bridgeSnapshot: sessionAgentLease.bridgeRun?.snapshot,
 					piBridgeEnabled: resolveCursorPiToolBridgeEnabled(),
+					includePiBridgeGuidance,
 				}),
 			};
 		};
@@ -108,6 +116,8 @@ export async function prepareCursorProviderTurn(
 			await resetSessionCursorAgent(sessionAgentScopeKey);
 			sessionAgentLease = await acquireSessionCursorAgent(sessionAgentAcquireParams);
 			sessionAgentScopeKey = sessionAgentLease.scopeKey;
+			bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
+			includePiBridgeGuidance = bridgeToolNames.size > 0;
 			sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
 			promptOptions = buildPromptOptions(sendPlan);
 			prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);

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

@@ -46,7 +46,6 @@ export class CursorProviderTurnRunner {
 		});
 
 		try {
-			stream.push({ type: "start", partial });
 			this.throwIfAborted();
 			const cwd = getCursorSessionCwd();
 			this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
@@ -62,6 +61,7 @@ export class CursorProviderTurnRunner {
 			) {
 				return;
 			}
+			this.throwIfAborted();
 
 			this.resolvedApiKey = requireCursorApiKey(options);
 			prepared = await prepareCursorProviderTurn({

package/src/cursor-provider.ts

@@ -22,6 +22,8 @@ import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-gu
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 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";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -54,7 +56,6 @@ export function streamCursor(
 
 	(async () => {
 		const partial = makeInitialMessage(model);
-		const sdkProcessErrorGuard = installCursorSdkProcessErrorGuard();
 
 		const runner = new CursorProviderTurnRunner({
 			model,
@@ -66,7 +67,12 @@ export function streamCursor(
 		});
 
 		try {
-			await runner.run(sdkProcessErrorGuard);
+			stream.push({ type: "start", partial });
+			await runExclusiveCursorSessionTurn(
+				getCursorSessionScopeKey(),
+				() => runner.run(installCursorSdkProcessErrorGuard()),
+				options?.signal,
+			);
 		} catch (error) {
 			await runner.handleOuterCatch(error);
 		}
@@ -93,4 +99,5 @@ export const __testUtils = {
 	resetCursorNativeReplayIdleDisposeMs,
 	releaseAllPendingCursorLiveRunsForTests,
 	resetSessionCursorAgents: () => disposeAllSessionCursorAgents(),
+	resetSessionTurnQueue: cursorSessionTurnQueueTestUtils.reset,
 };

package/src/cursor-session-turn-queue.ts

@@ -0,0 +1,52 @@
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+
+const turnQueuesByScope = new Map<string, Promise<void>>();
+
+async function waitForPreviousTurn(previous: Promise<void>, signal?: AbortSignal): Promise<void> {
+	if (!signal) {
+		await previous.catch(() => undefined);
+		return;
+	}
+	if (signal.aborted) throw new CursorLiveRunAbortError();
+	await new Promise<void>((resolve, reject) => {
+		const onAbort = (): void => {
+			reject(new CursorLiveRunAbortError());
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		previous.catch(() => undefined).then(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		});
+	});
+}
+
+export async function runExclusiveCursorSessionTurn<T>(scopeKey: string, body: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+	const previous = turnQueuesByScope.get(scopeKey);
+	let releaseCurrent!: () => void;
+	const current = new Promise<void>((resolve) => {
+		releaseCurrent = resolve;
+	});
+	const tail = (previous ?? Promise.resolve()).catch(() => undefined).then(() => current);
+	turnQueuesByScope.set(scopeKey, tail);
+	void tail.finally(() => {
+		if (turnQueuesByScope.get(scopeKey) === tail) {
+			turnQueuesByScope.delete(scopeKey);
+		}
+	});
+
+	try {
+		if (previous) await waitForPreviousTurn(previous, signal);
+		return await body();
+	} finally {
+		releaseCurrent();
+	}
+}
+
+export const __testUtils = {
+	reset(): void {
+		turnQueuesByScope.clear();
+	},
+	count(): number {
+		return turnQueuesByScope.size;
+	},
+};

package/src/cursor-tool-manifest.ts

@@ -8,7 +8,7 @@ export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY =
-	"read, shell, grep, glob, ls, edit, write, delete, readLints, updateTodos, createPlan, task, generateImage, mcp, semSearch, recordScreen, and web search/fetch when exposed";
+	"read/shell/search/edit/write and other host tools when Cursor exposes them";
 
 export function resolveCursorToolManifestEnabled(
 	env: Record<string, string | undefined> = process.env,
@@ -20,23 +20,26 @@ export function buildCursorToolManifestText(options: {
 	bridgeSnapshot?: CursorPiToolBridgeSnapshot;
 	/** When false, bridge is off via PI_CURSOR_PI_TOOL_BRIDGE=0 (not merely empty). */
 	piBridgeEnabled?: boolean;
+	includePiBridgeGuidance?: boolean;
 } = {}): string {
 	const piBridgeEnabled = options.piBridgeEnabled ?? true;
+	const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
 	const lines = [
 		"Callable tool surfaces this run:",
-		`- Cursor SDK host tools (callable; not listed in MCP listTools): ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}.`,
-		"- Configured Cursor MCP servers: discovered at runtime via MCP listTools (depends on Cursor settings and PI_CURSOR_SETTING_SOURCES).",
-		"- Pi CLI tool toggles such as --no-tools affect pi tools and bridge exposure only; they do not disable Cursor SDK host tools or configured Cursor MCP.",
+		`- Cursor host/MCP: ${CURSOR_HOST_TOOL_MANIFEST_SUMMARY}; configured MCP depends on Cursor settings.`,
+		"- Pi tool toggles affect pi tools/bridge exposure only; they do not disable Cursor host/configured MCP tools.",
 	];
-	const bridgeTools = options.bridgeSnapshot?.tools ?? [];
-	if (!piBridgeEnabled) {
-		lines.push("- Pi bridge: disabled (PI_CURSOR_PI_TOOL_BRIDGE=0).");
-	} else if (bridgeTools.length === 0) {
-		lines.push("- Pi bridge: no pi__* tools exposed this run.");
-	} else {
-		const names = [...bridgeTools.map((tool) => tool.mcpToolName)].sort().join(", ");
-		lines.push(`- Pi bridge (call pi__* MCP names; pi shows real pi tool names): ${names}.`);
+	const bridgeTools = includePiBridgeGuidance ? options.bridgeSnapshot?.tools ?? [] : [];
+	if (includePiBridgeGuidance) {
+		if (!piBridgeEnabled) {
+			lines.push("- Pi bridge: disabled (PI_CURSOR_PI_TOOL_BRIDGE=0).");
+		} else if (bridgeTools.length === 0) {
+			lines.push("- Pi bridge: no pi__* tools exposed this run.");
+		} else {
+			const names = [...bridgeTools.map((tool) => tool.mcpToolName)].sort().join(", ");
+			lines.push(`- Pi bridge: call exposed pi__* MCP names (${names}); pi shows real pi names.`);
+		}
 	}
-	lines.push("- Not callable: cursor-replay-* IDs, pi history tool names, and transcript labels.");
+	lines.push("- Not callable: cursor-replay-* IDs, pi history names, transcript labels.");
 	return lines.join("\n");
 }

package/src/cursor-usage-accounting.ts

@@ -6,6 +6,7 @@ import {
 	estimateCursorTextTokens,
 	type CursorPromptOptions,
 } from "./context.js";
+import { asRecord, getNumber } from "./cursor-record-utils.js";
 
 export interface CursorUsagePromptOptions extends CursorPromptOptions {
 	maxInputTokens: number;
@@ -13,6 +14,13 @@ export interface CursorUsagePromptOptions extends CursorPromptOptions {
 	imageTokenEstimate: number;
 }
 
+export interface CursorSdkTurnUsage {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+}
+
 function getPromptInputTokenBudget(model: Model<Api>): number {
 	const outputReserveTokens = Math.min(model.maxTokens, Math.max(1, Math.floor(model.contextWindow * 0.2)));
 	return Math.max(1, model.contextWindow - outputReserveTokens);
@@ -26,6 +34,26 @@ export function getCursorPromptOptions(model: Model<Api>): CursorUsagePromptOpti
 	};
 }
 
+function getNonNegativeTokenCount(record: Record<string, unknown> | undefined, key: string): number | undefined {
+	const value = getNumber(record, key);
+	return value === undefined ? undefined : Math.max(0, Math.floor(value));
+}
+
+export function readCursorSdkTurnUsage(value: unknown): CursorSdkTurnUsage | undefined {
+	const record = asRecord(value);
+	const inputTokens = getNonNegativeTokenCount(record, "inputTokens");
+	const outputTokens = getNonNegativeTokenCount(record, "outputTokens");
+	const cacheReadTokens = getNonNegativeTokenCount(record, "cacheReadTokens");
+	const cacheWriteTokens = getNonNegativeTokenCount(record, "cacheWriteTokens");
+	if (inputTokens === undefined || outputTokens === undefined || cacheReadTokens === undefined || cacheWriteTokens === undefined) return undefined;
+	return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+}
+
+export function readCursorSdkTurnUsageFromUpdate(update: unknown): CursorSdkTurnUsage | undefined {
+	const record = asRecord(update);
+	return record?.type === "turn-ended" ? readCursorSdkTurnUsage(record.usage) : undefined;
+}
+
 function stringifyUsageValue(value: unknown): string {
 	try {
 		return JSON.stringify(value) ?? "";
@@ -56,11 +84,36 @@ export function estimateCursorContextTotalTokens(partial: AssistantMessage, mode
 	return estimateCursorContextTokens(withAssistantMessage(context, partial), getCursorPromptOptions(model));
 }
 
-export function applyCursorApproximateUsage(partial: AssistantMessage, _model: Model<Api>, _context: Context, sessionInputTokens: number): void {
+export function applyCursorSdkUsage(partial: AssistantMessage, turnUsage: CursorSdkTurnUsage): void {
+	partial.usage.input = turnUsage.inputTokens;
+	partial.usage.output = turnUsage.outputTokens;
+	partial.usage.cacheRead = turnUsage.cacheReadTokens;
+	partial.usage.cacheWrite = turnUsage.cacheWriteTokens;
+	partial.usage.totalTokens = turnUsage.inputTokens + turnUsage.outputTokens;
+}
+
+export function applyCursorApproximateUsage(partial: AssistantMessage, model: Model<Api>, context: Context, sessionInputTokens: number): void {
 	const outputTokens = estimateCursorAssistantSessionOutputTokens(partial);
 	partial.usage.input = Math.max(0, sessionInputTokens);
 	partial.usage.output = outputTokens;
 	partial.usage.cacheRead = 0;
 	partial.usage.cacheWrite = 0;
-	partial.usage.totalTokens = partial.usage.input + partial.usage.output + partial.usage.cacheRead + partial.usage.cacheWrite;
+	partial.usage.totalTokens = Math.max(
+		partial.usage.input + partial.usage.output,
+		estimateCursorContextTotalTokens(partial, model, context),
+	);
+}
+
+export function applyCursorUsage(
+	partial: AssistantMessage,
+	model: Model<Api>,
+	context: Context,
+	sessionInputTokens: number,
+	sdkUsage?: { turn?: CursorSdkTurnUsage },
+): void {
+	if (sdkUsage?.turn) {
+		applyCursorSdkUsage(partial, sdkUsage.turn);
+		return;
+	}
+	applyCursorApproximateUsage(partial, model, context, sessionInputTokens);
 }