pi-cursor-sdk 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.18 - 2026-05-23
+
+### Added
+
+- Add `scripts/isolated-cursor-smoke.sh` and `npm run smoke:isolated` for packed `/tmp` install smoke with seeded `auth.json`, plan-strip shim, and JSONL replay-error scans.
+- Add `scripts/fixtures/plan-strip-shim/` to simulate plan-mode execute stripping active tools to `read`, `bash`, `edit`, and `write`.
+- Extend `scripts/validate-smoke-jsonl.mjs` with `--replay-errors` and `--replay-errors-only` to fail on persisted `Tool grep/cursor/find/ls not found` entries.
+- Add [Cursor testing lessons](docs/cursor-testing-lessons.md) documenting auth.json seeding, isolated harness layout, JSONL replay scans, and the plan-mode replay regression chain.
+- Add regression coverage in `test/cursor-native-replay-stress.test.ts`, `test/cursor-native-replay-trace.test.ts`, `test/cursor-native-replay-routing.test.ts`, and expanded live-run / extension lifecycle tests.
+
+### Changed
+
+- Centralize native replay routing in `src/cursor-native-replay-routing.ts` (`resolveNativeReplayDisposition`, shared context-tool partitioning) for turn coordinator and live-run drain.
+- Unify 240-character display truncation in `src/cursor-display-text.ts` and share `getActiveContextToolNames()` via `src/cursor-context-tools.ts`.
+- Unify inactive native replay trace formatting through `src/cursor-native-replay-trace.ts` (`title: summary`) for both live-run drain and turn-coordinator paths.
+- On non-Cursor model switch, strip all registered native replay wrappers except core pi tools (`read`, `bash`, `edit`, `write`), not only `cursor`.
+- Document `auth.json` as the primary live-smoke auth source in the live smoke checklist, README maintainer gate, and UX spec.
+
+### Fixed
+
+- Fix `Tool grep not found` and related native replay failures after plan-mode execute resets active tools by re-syncing registered Cursor replay wrappers on `before_agent_start` and `turn_start`.
+- Skip native replay `toolUse` when a replay tool is inactive in `context.tools`; emit scrubbed thinking trace instead of a broken pi tool call.
+- Partition live-run drain replay emission so inactive queued native tools fall back to trace output instead of invalid `toolUse` turns.
+
 ## 0.1.17 - 2026-05-23
 
 ### Added

package/README.md

@@ -232,7 +232,7 @@ PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 pi --model cursor/composer-2.5
 
 ### Maintainer live smoke release gate
 
-For Cursor provider/runtime changes, follow the manual [Cursor live smoke checklist](docs/cursor-live-smoke-checklist.md) before release. Assume every runtime surface is in scope. The checklist uses real `pi -e . --cursor-no-fast --model cursor/composer-2.5` runs with temporary session dirs and requires the visible TUI/output, scrubbed diagnostics, and persisted JSONL to agree. Do not mark a release ready with optional, deferred, mostly-passing, or unobserved smoke checks outstanding.
+For Cursor provider/runtime changes, follow the manual [Cursor live smoke checklist](docs/cursor-live-smoke-checklist.md) before release. See [Cursor testing lessons](docs/cursor-testing-lessons.md) for auth.json seeding, isolated `/tmp` harness layout, JSONL replay-error scans, and other regression traps. Assume every runtime surface is in scope. The checklist uses real `pi -e . --cursor-no-fast --model cursor/composer-2.5` runs with temporary session dirs and requires the visible TUI/output, scrubbed diagnostics, and persisted JSONL to agree. Do not mark a release ready with optional, deferred, mostly-passing, or unobserved smoke checks outstanding.
 
 ## Fallback models
 

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

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Use this manual checklist before releasing Cursor provider/runtime changes. Unit tests and mocks are necessary, but they are not enough for this extension. Always assume every runtime surface is in scope. A release is not ready until every live check below has been observed with `cursor/composer-2.5` through the local working tree.
+Use this manual checklist before releasing Cursor provider/runtime changes. Unit tests and mocks are necessary, but they are not enough for this extension. See [Cursor testing lessons](./cursor-testing-lessons.md) for auth/isolated-harness pitfalls and the plan-mode replay regression that motivated recent hardening. Always assume every runtime surface is in scope. A release is not ready until every live check below has been observed with `cursor/composer-2.5` through the local working tree.
 
 ## Release rule
 
@@ -22,19 +22,36 @@ mkdir -p "$SMOKE_DIR"
 pi -e . --list-models cursor
 ```
 
+Live pi runs resolve provider auth from **`~/.pi/agent/auth.json`**, not only shell env. Isolated smoke copies that file into a clean temporary `HOME`. Ensure `auth.json` includes a `cursor` provider entry, or export `CURSOR_API_KEY` as a fallback.
+
 The repo also ships partial automation for the prerequisite/basic/default-settings/non-interactive math/TUI output polling/steering/diagnostic/JSONL subset:
 
 ```bash
 npm run smoke:live
 ```
 
+For native replay regression checks (packed install, plan-strip resync, JSONL replay-error scan), use the isolated helper:
+
+```bash
+npm run smoke:isolated
+# unit tests + pack only (no live Cursor):
+SKIP_LIVE=1 npm run smoke:isolated
+```
+
+Scan persisted sessions for native replay tool failures:
+
+```bash
+node scripts/validate-smoke-jsonl.mjs --replay-errors "$SMOKE_DIR"
+node scripts/validate-smoke-jsonl.mjs --replay-errors-only "$SMOKE_DIR/session-subdir"
+```
+
 The script is a helper only; it polls the section 3 TUI for answer/footer evidence and then cleans up the tmux session, but it does not replace manual visual review of the full TUI checklist. Release readiness still requires the manual checks below for detailed TUI behavior, bridge, standalone native replay, abort/cancel, packaging, cleanup, and any touched runtime surface not covered by the helper.
 
 Pass criteria:
 
 - `cursor/composer-2.5` appears in the model list.
 - No Cursor key or auth token is printed.
-- If `CURSOR_API_KEY` is unavailable and `/login` is not configured, stop and report the live smoke as blocked.
+- If neither `~/.pi/agent/auth.json` cursor auth nor `CURSOR_API_KEY` is available, stop and report the live smoke as blocked.
 
 ## 1. Basic provider reality check
 

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

@@ -32,7 +32,7 @@ Current implementation notes:
 - 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.input`/`usage.output` are approximate pi session activity components: initial Cursor prompt input is counted once, consumed split-run tool results are counted as deduped input on the following assistant turn, and assistant output includes visible text/thinking/tool-call content. `usage.totalTokens` is the replayable Cursor prompt/context estimate derived from the same `buildCursorPrompt()` path used for `Agent.send`; it may differ from `input + output` and is the context-safe value for display/compaction. `src/cursor-usage-accounting.ts` owns this usage policy, and `src/cursor-live-run-accounting.ts` owns prompt-once and consumed-tool-result accounting so provider usage and bridge result resolution share the same matched tool-result boundary.
 - Audit observation, 2026-05-19, superseded by the 2026-05-21 replay pass: 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 started calls are now discarded at run completion instead of becoming synthetic replay errors. 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 should follow [Cursor Live Smoke Checklist](./cursor-live-smoke-checklist.md) with real `pi -e . --cursor-no-fast --model cursor/composer-2.5` invocations, manual observation, temporary session dirs, diagnostics scans, and persisted JSONL inspection. Assume every runtime surface is in scope. A release is not ready when any live check is optional, deferred, mostly passing, or unobserved.
+- Cursor provider/runtime releases should follow [Cursor Live Smoke Checklist](./cursor-live-smoke-checklist.md) with real `pi -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. A release is not ready when any live check is optional, deferred, mostly passing, or unobserved.
 - For models without a catalog `context` parameter, context windows are not hardcoded. The extension ships a bundled SDK-derived default/non-Max cache generated from `createAgentPlatform().checkpointStore.loadLatest(agentId).tokenDetails.maxTokens`. Successful runs can update a local override cache, but model discovery does not probe models at startup.
 - Max Mode context windows are distinct from default/non-Max context windows. `@cursor/sdk` 1.0.13 documentation says the SDK may enable Max Mode automatically when a selected model requires it, but the public local-agent `ModelSelection` path still does not expose a manual Max Mode selector. Do not advertise Max Mode context windows unless the SDK catalog exposes an exact parameter/variant or the SDK public API adds a Max Mode selector that the extension actually sends.
 - `@cursor/sdk` 1.0.13 adds latest-style `ModelListItem.aliases`. The extension registers only unambiguous aliases as pi model IDs (with the same context suffixes when applicable) and sends the alias back in `ModelSelection.id`, while sharing Cursor-only state such as fast defaults with the underlying catalog `id`. Aliases shared by multiple base models, such as generic family aliases, are skipped because the pi row metadata would otherwise imply one base model while Cursor may resolve the alias to another.

package/docs/cursor-testing-lessons.md

@@ -0,0 +1,199 @@
+# Cursor Testing Lessons
+
+## Purpose
+
+This document records maintainer testing lessons for `pi-cursor-sdk`. It complements unit tests and the [Cursor live smoke checklist](./cursor-live-smoke-checklist.md). Use it when adding regression coverage, debugging false-green releases, or building isolated smoke harnesses.
+
+## Core lesson: integration-shaped bugs beat unit mocks
+
+The native replay `Tool grep not found` failure was integration-shaped, not unit-shaped:
+
+1. **Plan mode** calls `setActiveTools(["read", "bash", "edit", "write"])` when execution starts.
+2. **pi-cursor-sdk** only re-synced native replay wrappers on `session_start` / `model_select`, not every turn.
+3. **The provider** still emitted native replay `toolUse` for `grep` / `cursor`.
+4. **pi's agent loop** looked up tools in `context.tools` and failed with `Tool grep not found`.
+
+Passing hundreds of unit tests did not prove that chain was safe. Regression coverage now includes:
+
+- `test/index.test.ts` — `before_agent_start` and `turn_start` resync after plan-style strip
+- `test/cursor-native-replay-stress.test.ts` — plan strip → resync → grep replay; inactive-tool trace fallbacks
+- `test/cursor-provider-replay-live-run.test.ts` — inactive replay tools emit trace instead of broken `toolUse`
+- `test/cursor-native-replay-trace.test.ts` — shared inactive replay trace formatting
+- `test/cursor-native-replay-routing.test.ts` — `resolveNativeReplayDisposition` and `partitionNativeToolsByActiveContext`
+
+When changing provider/runtime behavior, ask whether the bug spans **pi extension lifecycle**, **active tool state**, **provider streaming**, and **persisted JSONL**. If yes, add an integration-style unit test or live smoke coverage for that chain.
+
+## Dual-check invariant: `context.tools` vs pi active tools
+
+Native replay routing intentionally uses two layers:
+
+1. **Extension resync** (`before_agent_start`, `turn_start`) updates pi's active tool set via `syncRegisteredNativeCursorToolsForModel`. This fixes the common case where plan-mode execute strips `grep`/`find`/`cursor` before the next turn.
+2. **Provider routing** uses the **`context.tools` snapshot** captured when `streamCursor()` starts (`getActiveContextToolNames` in `src/cursor-context-tools.ts`). It does not read live `pi.getActiveTools()` mid-stream.
+
+`src/cursor-native-replay-routing.ts` centralizes provider-side routing against the same `context.tools` snapshot:
+
+- **Turn coordinator** calls `resolveNativeReplayDisposition()` per completed SDK tool → `queue_replay` (queue native `toolUse`), `inactive_trace` (`formatInactiveCursorReplayTrace()`), or `transcript_trace`.
+- **Live-run drain** calls `partitionNativeToolsByActiveContext()` on already-queued native tool batches → active tools become `toolUse`; inactive tools get trace only and the batch returns `"handled"` without `toolUse`.
+
+Disposition outcomes:
+
+- `queue_replay` — tool is in `context.tools` and a live run exists
+- `inactive_trace` — native replay tool missing from `context.tools`
+- `transcript_trace` — native replay off or non-native tool
+
+If resync runs but `context.tools` is still stale (e.g. only `read` listed), the provider must **not** emit `toolUse` for inactive tools. `test/cursor-native-replay-stress.test.ts` covers that stale-snapshot path.
+
+## Auth: use `auth.json`, not only env
+
+pi resolves Cursor auth in this order:
+
+1. pi `--api-key`
+2. stored `cursor` key in `~/.pi/agent/auth.json` from `/login`
+3. `CURSOR_API_KEY`
+
+For live smoke and isolated harnesses:
+
+- **Do not assume** `CURSOR_API_KEY` or `~/.secrets` alone is enough.
+- **Do assume** pi reads auth from the active `HOME`, usually `~/.pi/agent/auth.json`.
+- Isolated runs with `env -i HOME=/tmp/...` must **copy** `auth.json` into that temporary home before calling `pi`.
+
+Example seed step used by `scripts/isolated-cursor-smoke.sh`:
+
+```bash
+mkdir -p "$HOME/.pi/agent"
+cp "$REAL_HOME/.pi/agent/auth.json" "$HOME/.pi/agent/auth.json"
+chmod 600 "$HOME/.pi/agent/auth.json"
+```
+
+Fallback when `auth.json` lacks a `cursor` provider entry:
+
+```bash
+export CURSOR_API_KEY="your-key"
+```
+
+Never commit, log, or paste `auth.json` contents, API keys, or session JSONL with secrets.
+
+## Isolated directories: why and how
+
+Use isolated `/tmp` trees when validating:
+
+- packed tarball install (`npm pack` → extract → `pi install -l`)
+- clean `HOME` with no inherited shell profile state
+- plan-mode-style tool stripping via a shim extension
+- JSONL replay-error scans independent of stdout
+
+Recommended layout:
+
+```text
+/tmp/pi-cursor-sdk-isolated-<timestamp>/
+  home/                 # seeded ~/.pi/agent/auth.json
+  pack/                 # npm pack output (*.tgz)
+  extract/package/      # unpacked extension
+  project/              # empty pi project for install -l
+  sessions/
+    basic/
+    native-replay/
+    plan-strip/
+```
+
+Commands:
+
+```bash
+# full isolated smoke (unit preflight + pack + live pi)
+npm run smoke:isolated
+
+# pack/unit only, no live Cursor calls
+SKIP_LIVE=1 npm run smoke:isolated
+
+# custom artifact root
+ISOLATED=/tmp/pi-cursor-sdk-isolated-manual npm run smoke:isolated
+```
+
+Every live check should use its own `--session-dir` under the isolated tree. Do not reuse session dirs across scenarios.
+
+## Harness traps we hit repeatedly
+
+| Trap | What went wrong | Fix |
+| --- | --- | --- |
+| Clean `HOME` without auth | `pi` could not authenticate Cursor in isolated runs | Copy `~/.pi/agent/auth.json` into isolated `HOME` |
+| `npm pack \| tail -1` | Captured npm notice text, not tarball path | Use `ls -t "$PACK_DIR"/*.tgz \| head -1` |
+| Packed extension, no install | Provider never loaded in isolated project | Run `npm install --omit=dev` inside extracted package |
+| Inherited shell env | mise/profile hooks hung or polluted runs | Use `env -i ... MISE_DISABLE=1` for isolated pi calls |
+| No per-check timeout | One stuck prompt blocked entire harness | Wrap each live check with timeout/watchdog |
+| stdout-only assertions | Missed replay failures persisted only in JSONL | Scan JSONL for `Tool grep/cursor/find/ls not found` |
+| Plan strip only on first turn | Under-tested multi-turn resync | Shim strips on every `turn_start`; stress multi-turn separately |
+| Assuming env auth equals pi auth | False "blocked" or false "pass" in CI-like shells | Check `auth.json` provider keys explicitly when needed |
+
+## JSONL is the source of truth for replay regressions
+
+Stdout can look fine while persisted tool results contain errors. Prefer structural JSONL scans over grepping terminal output.
+
+Replay failure scan:
+
+```bash
+node scripts/validate-smoke-jsonl.mjs --replay-errors-only "$SESSION_DIR"
+```
+
+Combined usage + replay scan after broader smoke:
+
+```bash
+node scripts/validate-smoke-jsonl.mjs --replay-errors "$SMOKE_DIR"
+```
+
+The replay scan fails on records containing:
+
+- `Tool grep not found`
+- `Tool cursor not found`
+- `Tool find not found`
+- `Tool ls not found`
+
+## Plan-mode regression scenario
+
+Simulate plan-mode execute stripping with the repo fixture:
+
+- `scripts/fixtures/plan-strip-shim/index.ts`
+
+It sets active tools to `read`, `bash`, `edit`, `write` on each `turn_start`. Run pi with:
+
+```bash
+pi -e scripts/fixtures/plan-strip-shim --cursor-no-fast --model cursor/composer-2.5 \
+  --session-dir "$SMOKE_DIR/plan-strip" \
+  -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.'
+```
+
+Pass criteria:
+
+- No replay `Tool * not found` entries in JSONL
+- Native replay tools (`grep`, `find`, `read`, etc.) succeed after `turn_start` resync
+- On non-Cursor model switch, native replay wrappers are removed except core pi tools
+
+## Local validation ladder
+
+Run in order before claiming release-ready for provider/runtime changes:
+
+```bash
+npm test
+npm run typecheck
+npm pack --dry-run
+SKIP_LIVE=1 npm run smoke:isolated
+npm run smoke:isolated            # requires auth.json or CURSOR_API_KEY
+npm run smoke:live                # partial tmux checklist subset
+```
+
+Then follow the full manual [Cursor live smoke checklist](./cursor-live-smoke-checklist.md) for surfaces the scripts do not cover (bridge MCP, abort/cancel, full TUI observation, packaging review, cleanup).
+
+## What belongs in CI vs manual smoke
+
+- **CI / default `npm test`:** mocked provider tests, extension lifecycle tests, JSONL validator tests, script syntax/help checks. No live Cursor calls.
+- **Manual / pre-release:** `npm run smoke:isolated`, `npm run smoke:live`, and the full checklist. Requires real Cursor auth and observes TUI/runtime behavior mocks cannot reproduce.
+
+If live smoke auth is unavailable, report the release as **blocked**, not skipped-ready.
+
+## Related docs and scripts
+
+- [Cursor live smoke checklist](./cursor-live-smoke-checklist.md)
+- [Cursor native tool replay](./cursor-native-tool-replay.md)
+- `scripts/isolated-cursor-smoke.sh`
+- `scripts/tmux-live-smoke.sh`
+- `scripts/validate-smoke-jsonl.mjs`
+- `test/helpers/cursor-provider-harness.ts` — controllable native replay pi mock (`createNativeToolDisplayPiForTest`)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.17",
+	"version": "0.1.18",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -26,10 +26,12 @@
 		"scripts/refresh-cursor-model-snapshots.mjs",
 		"scripts/steering-rpc-smoke.mjs",
 		"scripts/tmux-live-smoke.sh",
+		"scripts/isolated-cursor-smoke.sh",
 		"scripts/validate-smoke-jsonl.mjs",
 		"README.md",
 		"docs/cursor-model-ux-spec.md",
 		"docs/cursor-live-smoke-checklist.md",
+		"docs/cursor-testing-lessons.md",
 		"docs/cursor-native-tool-replay.md",
 		"docs/cursor-native-tool-visual-audit.md",
 		"LICENSE",
@@ -45,6 +47,7 @@
 		"test:watch": "vitest",
 		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs",
 		"smoke:live": "scripts/tmux-live-smoke.sh",
+		"smoke:isolated": "scripts/isolated-cursor-smoke.sh",
 		"smoke:steering": "node scripts/steering-rpc-smoke.mjs",
 		"smoke:jsonl": "node scripts/validate-smoke-jsonl.mjs"
 	},

package/scripts/isolated-cursor-smoke.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# Isolated /tmp install + fail-fast live smoke for pi-cursor-sdk native replay.
+#
+# Validates packed extension load, plan-strip resync, and absence of "Tool * not found".
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+REAL_HOME="${REAL_HOME:-$HOME}"
+PI_AGENT_DIR="${PI_AGENT_DIR:-$REAL_HOME/.pi/agent}"
+AUTH_JSON="${AUTH_JSON:-$PI_AGENT_DIR/auth.json}"
+REPO="${REPO:-$ROOT}"
+ISOLATED="${ISOLATED:-/tmp/pi-cursor-sdk-isolated-$(date +%Y%m%dT%H%M%S)}"
+PI_LIVE_TIMEOUT="${PI_LIVE_TIMEOUT:-45}"
+SKIP_LIVE="${SKIP_LIVE:-0}"
+SKIP_UNIT="${SKIP_UNIT:-0}"
+PI_BIN="${PI_BIN:-pi}"
+PI_PATH="${PI_PATH:-/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin}"
+
+PACK_DIR="$ISOLATED/pack"
+EXTRACT_DIR="$ISOLATED/extract"
+PROJECT_DIR="$ISOLATED/project"
+SESSION_ROOT="$ISOLATED/sessions"
+SHIM_DIR="$ROOT/scripts/fixtures/plan-strip-shim"
+HOME_DIR="$ISOLATED/home"
+
+print_help() {
+	cat <<EOF
+Isolated /tmp install smoke for pi-cursor-sdk (native replay + plan-strip resync).
+
+Usage:
+  ./scripts/isolated-cursor-smoke.sh
+  SKIP_LIVE=1 ./scripts/isolated-cursor-smoke.sh
+  PI_LIVE_TIMEOUT=90 ./scripts/isolated-cursor-smoke.sh
+
+Environment:
+  REPO                          Repo under test (default: script parent directory).
+  ISOLATED                      Artifact root (default: /tmp/pi-cursor-sdk-isolated-<timestamp>).
+  REAL_HOME                     Source for auth.json (default: \$HOME).
+  AUTH_JSON                     Path to pi auth.json to seed isolated HOME (default: ~/.pi/agent/auth.json).
+  PI_LIVE_TIMEOUT               Per live pi check timeout in seconds (default: 45).
+  PI_BIN                        pi executable (default: pi on PATH).
+  PI_PATH                       PATH for isolated pi runs.
+  SKIP_LIVE=1                   Run unit tests + pack only; skip live Cursor calls.
+  SKIP_UNIT=1                   Skip repo unit tests (live checks only).
+  CURSOR_API_KEY                Optional fallback when auth.json lacks cursor provider.
+
+Prerequisites:
+  node, npm, pi, rg, python3 on PATH
+  ~/.pi/agent/auth.json with cursor provider OR CURSOR_API_KEY
+
+Exit codes:
+  0  all requested checks passed
+  1  prerequisite, unit, pack, live smoke, or JSONL replay validation failure
+EOF
+}
+
+log() {
+	printf '[isolated-smoke] %s\n' "$*"
+}
+
+fail() {
+	printf '[isolated-smoke] FAIL: %s\n' "$*" >&2
+	exit 1
+}
+
+seed_pi_agent_home() {
+	local home="$1"
+	mkdir -p "$home/.pi/agent"
+	if [[ -f "$AUTH_JSON" ]]; then
+		cp "$AUTH_JSON" "$home/.pi/agent/auth.json"
+		chmod 600 "$home/.pi/agent/auth.json"
+		log "seeded $home/.pi/agent/auth.json"
+	else
+		log "WARN: no auth.json at $AUTH_JSON"
+	fi
+	if [[ -f "$PI_AGENT_DIR/models.json" ]]; then
+		cp "$PI_AGENT_DIR/models.json" "$home/.pi/agent/models.json"
+	fi
+}
+
+has_auth_provider() {
+	local provider="$1"
+	python3 - "$provider" "$HOME_DIR/.pi/agent/auth.json" <<'PY'
+import json, sys
+provider, path = sys.argv[1], sys.argv[2]
+try:
+    data = json.load(open(path))
+except FileNotFoundError:
+    sys.exit(1)
+sys.exit(0 if provider in data and data[provider] else 1)
+PY
+}
+
+run_with_timeout() {
+	local label="$1"
+	local seconds="$2"
+	shift 2
+	log "$label (timeout ${seconds}s)"
+	if command -v timeout >/dev/null 2>&1; then
+		timeout --foreground "${seconds}s" "$@" || {
+			local rc=$?
+			[[ $rc -eq 124 ]] && fail "$label timed out after ${seconds}s"
+			fail "$label exited $rc"
+		}
+		return
+	fi
+	if command -v gtimeout >/dev/null 2>&1; then
+		gtimeout "${seconds}s" "$@" || {
+			local rc=$?
+			[[ $rc -eq 124 ]] && fail "$label timed out after ${seconds}s"
+			fail "$label exited $rc"
+		}
+		return
+	fi
+	"$@" &
+	local pid=$!
+	local waited=0
+	while kill -0 "$pid" 2>/dev/null; do
+		if (( waited >= seconds )); then
+			kill -TERM "$pid" 2>/dev/null || true
+			sleep 1
+			kill -KILL "$pid" 2>/dev/null || true
+			fail "$label timed out after ${seconds}s"
+		fi
+		sleep 1
+		waited=$((waited + 1))
+	done
+	wait "$pid" || fail "$label exited $?"
+}
+
+validate_replay_jsonl() {
+	local dir="$1"
+	node "$ROOT/scripts/validate-smoke-jsonl.mjs" --replay-errors-only "$dir"
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+	print_help
+	exit 0
+fi
+
+if [[ -f "${SECRETS_FILE:-$REAL_HOME/.secrets}" ]]; then
+	set +u
+	# shellcheck disable=SC1090
+	source "${SECRETS_FILE:-$REAL_HOME/.secrets}"
+	set -u
+fi
+
+command -v node >/dev/null || fail "missing node"
+command -v npm >/dev/null || fail "missing npm"
+command -v rg >/dev/null || fail "missing rg"
+command -v python3 >/dev/null || fail "missing python3"
+
+mkdir -p "$PACK_DIR" "$EXTRACT_DIR" "$PROJECT_DIR" "$SESSION_ROOT" "$HOME_DIR"
+seed_pi_agent_home "$HOME_DIR"
+
+log "isolated root: $ISOLATED"
+log "HOME=$HOME_DIR"
+
+if [[ "$SKIP_UNIT" != "1" ]]; then
+	log "preflight: repo unit tests"
+	run_with_timeout "npm test" 120 bash -lc "cd '$REPO' && npm test"
+fi
+
+if [[ "$SKIP_LIVE" == "1" ]]; then
+	log "SKIP_LIVE=1 — skipping live pi checks"
+	exit 0
+fi
+
+if ! has_auth_provider cursor && [[ -z "${CURSOR_API_KEY:-}" ]]; then
+	fail "no cursor auth in $HOME_DIR/.pi/agent/auth.json and CURSOR_API_KEY unset"
+fi
+
+command -v "$PI_BIN" >/dev/null || fail "PI_BIN not found: $PI_BIN"
+
+log "npm pack from $REPO"
+(cd "$REPO" && npm pack --pack-destination "$PACK_DIR" >/dev/null 2>&1)
+PACK_TGZ="$(ls -t "$PACK_DIR"/*.tgz | head -1)"
+[[ -f "$PACK_TGZ" ]] || fail "missing pack tarball"
+tar -xzf "$PACK_TGZ" -C "$EXTRACT_DIR"
+[[ -d "$EXTRACT_DIR/package" ]] || fail "extract missing package/ dir"
+
+log "npm install packed extension deps"
+run_with_timeout "npm install --omit=dev" 120 bash -lc "cd '$EXTRACT_DIR/package' && npm install --omit=dev >/dev/null 2>&1"
+
+log "pi install -l (clean HOME)"
+cp "$REPO/README.md" "$PROJECT_DIR/README.md"
+run_with_timeout "pi install" 30 env -i HOME="$HOME_DIR" PATH="$PI_PATH" MISE_DISABLE=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' install -l '$EXTRACT_DIR/package' >/dev/null"
+
+run_with_timeout "pi list" 15 env -i HOME="$HOME_DIR" PATH="$PI_PATH" MISE_DISABLE=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' list" | rg -q "extract/package" || fail "packed extension not installed"
+
+PI_ENV=(HOME="$HOME_DIR" PATH="$PI_PATH" MISE_DISABLE=1 PI_CURSOR_SETTING_SOURCES=none)
+if [[ -n "${CURSOR_API_KEY:-}" ]]; then
+	PI_ENV+=(CURSOR_API_KEY="$CURSOR_API_KEY")
+fi
+
+log "check: list-models"
+LIST_OUT="$ISOLATED/list-models.txt"
+run_with_timeout "list-models" 30 env -i "${PI_ENV[@]}" \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' --cursor-no-fast --list-models cursor > '$LIST_OUT' 2>&1"
+rg -q "composer-2\\.5|composer-2-5" "$LIST_OUT" || fail "composer-2.5 not listed (see $LIST_OUT)"
+
+log "check: basic provider prompt"
+BASIC_DIR="$SESSION_ROOT/basic"
+mkdir -p "$BASIC_DIR"
+run_with_timeout "basic prompt" "$PI_LIVE_TIMEOUT" env -i "${PI_ENV[@]}" \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' --cursor-no-fast --model cursor/composer-2.5 --session-dir '$BASIC_DIR' --no-tools -p 'Reply exactly: PI_CURSOR_ISOLATED_OK' > '$ISOLATED/basic.stdout.txt' 2> '$ISOLATED/basic.stderr.txt'"
+rg -q "PI_CURSOR_ISOLATED_OK" "$ISOLATED/basic.stdout.txt" || fail "basic prompt missing PI_CURSOR_ISOLATED_OK"
+validate_replay_jsonl "$BASIC_DIR"
+
+log "check: native replay"
+REPLAY_DIR="$SESSION_ROOT/native-replay"
+mkdir -p "$REPLAY_DIR"
+run_with_timeout "native replay" "$PI_LIVE_TIMEOUT" env -i "${PI_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' --cursor-no-fast --model cursor/composer-2.5 --session-dir '$REPLAY_DIR' -p 'Read ./README.md briefly, then answer README_SEEN=yes if it mentions pi-cursor-sdk.' > '$ISOLATED/replay.stdout.txt' 2> '$ISOLATED/replay.stderr.txt'"
+validate_replay_jsonl "$REPLAY_DIR"
+
+log "check: plan-strip shim (plan-mode execute reset)"
+PLAN_DIR="$SESSION_ROOT/plan-strip"
+mkdir -p "$PLAN_DIR"
+run_with_timeout "plan-strip replay" "$PI_LIVE_TIMEOUT" env -i "${PI_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' -e '$SHIM_DIR' --cursor-no-fast --model cursor/composer-2.5 --session-dir '$PLAN_DIR' -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.' > '$ISOLATED/plan.stdout.txt' 2> '$ISOLATED/plan.stderr.txt'"
+validate_replay_jsonl "$PLAN_DIR"
+
+log "PASS isolated install smoke: $ISOLATED"

package/scripts/validate-smoke-jsonl.mjs

@@ -5,6 +5,13 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 
+const REPLAY_TOOL_NOT_FOUND = [
+	"Tool grep not found",
+	"Tool cursor not found",
+	"Tool find not found",
+	"Tool ls not found",
+];
+
 function printHelp() {
 	console.log(`Validate assistant presence and usage metadata in pi smoke session JSONL files.
 
@@ -18,21 +25,26 @@ Arguments:
 
 Options:
   -h, --help                    Show this help.
+  --replay-errors               Also fail when JSONL contains native replay "Tool * not found" errors.
+  --replay-errors-only          Scan only for native replay "Tool * not found" errors (skip usage checks).
 
 Exit codes:
-  0  every scanned JSONL file has at least one assistant message and valid assistant usage metadata
-  1  invalid arguments, unreadable directory, invalid JSONL, empty/no-assistant files, or usage validation failures
+  0  every enforced invariant passed for the selected mode(s)
+  1  invalid arguments, unreadable directory, invalid JSONL, empty/no-assistant files, usage validation failures, or replay tool errors
   2  no JSONL files found under the smoke directory
 
-Enforced invariants:
+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
 
+Replay error scan (--replay-errors / --replay-errors-only):
+  - no JSONL record contains "Tool grep/cursor/find/ls not found"
+
 Notes:
-  - Prints one JSON summary line per scanned session file.
+  - Prints one JSON summary line per scanned session file (usage mode) or one replay summary line (replay-only mode).
   - Does not print session message contents or secrets.`);
 }
 
@@ -88,6 +100,19 @@ function parseJsonlFile(file) {
 	return { lineCount: lines.length, records, parseErrorCount };
 }
 
+function scanReplayErrors(file, records) {
+	const hits = [];
+	for (const [index, record] of records.entries()) {
+		const blob = JSON.stringify(record);
+		for (const needle of REPLAY_TOOL_NOT_FOUND) {
+			if (blob.includes(needle)) {
+				hits.push({ line: index + 1, needle });
+			}
+		}
+	}
+	return hits;
+}
+
 function main() {
 	const args = process.argv.slice(2);
 	if (args.includes("-h") || args.includes("--help")) {
@@ -95,11 +120,15 @@ function main() {
 		return;
 	}
 
-	if (args.length > 1) {
+	const replayErrorsOnly = args.includes("--replay-errors-only");
+	const replayErrors = replayErrorsOnly || args.includes("--replay-errors");
+	const positional = args.filter((arg) => !arg.startsWith("-"));
+
+	if (positional.length > 1) {
 		fail("too many arguments; pass only the smoke directory");
 	}
 
-	const smokeDir = args[0] ?? process.env.SMOKE_DIR;
+	const smokeDir = positional[0] ?? process.env.SMOKE_DIR;
 	if (!smokeDir) {
 		fail("missing smoke directory; pass a path or set SMOKE_DIR");
 	}
@@ -117,6 +146,24 @@ function main() {
 	}
 
 	let failures = 0;
+	if (replayErrorsOnly) {
+		let replayHitCount = 0;
+		for (const file of files) {
+			const { records } = parseJsonlFile(file);
+			const hits = scanReplayErrors(file, records);
+			replayHitCount += hits.length;
+			if (hits.length > 0) failures += 1;
+			console.log(
+				JSON.stringify({
+					file: relative(smokeDir, file),
+					replayErrorCount: hits.length,
+					replayErrors: hits.slice(0, 5),
+				}),
+			);
+		}
+		process.exit(failures === 0 ? 0 : 1);
+	}
+
 	for (const file of files) {
 		let summary;
 		try {
@@ -125,7 +172,14 @@ function main() {
 			const assistants = messages.filter((message) => message?.role === "assistant");
 			const usage = assistants.map((message) => message.usage).filter(Boolean);
 			const badUsage = assistants.map((message) => message.usage).filter(isBadUsage);
-			const fileFailure = lineCount === 0 || parseErrorCount > 0 || assistants.length === 0 || usage.length !== assistants.length || badUsage.length > 0;
+			const replayHits = replayErrors ? scanReplayErrors(file, records) : [];
+			const fileFailure =
+				lineCount === 0 ||
+				parseErrorCount > 0 ||
+				assistants.length === 0 ||
+				usage.length !== assistants.length ||
+				badUsage.length > 0 ||
+				replayHits.length > 0;
 			if (fileFailure) failures += 1;
 			summary = {
 				file: relative(smokeDir, file),
@@ -135,6 +189,7 @@ function main() {
 				assistantCount: assistants.length,
 				usageCount: usage.length,
 				badUsageCount: badUsage.length,
+				replayErrorCount: replayHits.length,
 			};
 		} catch (error) {
 			failures += 1;

package/src/cursor-context-tools.ts

@@ -0,0 +1,6 @@
+import type { Context } from "@earendil-works/pi-ai";
+
+/** Tool names from the provider context snapshot at stream start (not live pi.getActiveTools()). */
+export function getActiveContextToolNames(context: Context): ReadonlySet<string> | undefined {
+	return context.tools ? new Set(context.tools.map((tool) => tool.name)) : undefined;
+}

package/src/cursor-display-text.ts

@@ -0,0 +1,10 @@
+/** Canonical single-line sanitization and truncation for Cursor replay/trace display. */
+export function sanitizeCursorDisplayLine(value: string): string {
+	return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export function truncateCursorDisplayLine(value: string, maxLength = 240): string {
+	const sanitized = sanitizeCursorDisplayLine(value);
+	if (sanitized.length <= maxLength) return sanitized;
+	return `${sanitized.slice(0, maxLength - 1)}…`;
+}

package/src/cursor-native-replay-routing.ts

@@ -0,0 +1,48 @@
+import { canRenderCursorToolNatively } from "./cursor-native-tool-display.js";
+import { getActiveContextToolNames } from "./cursor-context-tools.js";
+import type { Context } from "@earendil-works/pi-ai";
+
+export type NativeReplayDisposition = "queue_replay" | "inactive_trace" | "transcript_trace";
+
+export interface NativeReplayRoutingInput {
+	toolName: string;
+	useNativeToolReplay: boolean;
+	activeToolNames?: ReadonlySet<string>;
+	hasLiveRun: boolean;
+}
+
+export function isNativeToolActiveInContext(toolName: string, activeToolNames?: ReadonlySet<string>): boolean {
+	return activeToolNames === undefined || activeToolNames.has(toolName);
+}
+
+/**
+ * Canonical native replay routing for coordinator and live-run drain.
+ * Extension resync (pi active tools) is separate; this uses context.tools snapshot only.
+ */
+export function resolveNativeReplayDisposition(input: NativeReplayRoutingInput): NativeReplayDisposition {
+	if (!input.useNativeToolReplay || !canRenderCursorToolNatively(input.toolName)) {
+		return "transcript_trace";
+	}
+	if (isNativeToolActiveInContext(input.toolName, input.activeToolNames) && input.hasLiveRun) {
+		return "queue_replay";
+	}
+	if (!isNativeToolActiveInContext(input.toolName, input.activeToolNames)) {
+		return "inactive_trace";
+	}
+	return "transcript_trace";
+}
+
+export function partitionNativeToolsByActiveContext<T extends { toolName: string }>(
+	context: Context,
+	tools: readonly T[],
+): { active: T[]; inactive: T[] } {
+	const activeToolNames = getActiveContextToolNames(context);
+	if (!activeToolNames) return { active: [...tools], inactive: [] };
+	const active: T[] = [];
+	const inactive: T[] = [];
+	for (const tool of tools) {
+		if (activeToolNames.has(tool.toolName)) active.push(tool);
+		else inactive.push(tool);
+	}
+	return { active, inactive };
+}

package/src/cursor-native-replay-trace.ts

@@ -0,0 +1,29 @@
+import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import { asRecord } from "./cursor-record-utils.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+
+function getCursorReplayResultText(display: CursorPiToolDisplay): string | undefined {
+	for (const content of display.result.content) {
+		if (content.type !== "text") continue;
+		const text = truncateCursorDisplayLine(content.text);
+		if (text) return text;
+	}
+	return undefined;
+}
+
+/** Unified inactive native-replay fallback: `title: summary` in thinking trace. */
+export function formatInactiveCursorReplayTrace(display: CursorPiToolDisplay): string {
+	const details = asRecord(display.result.details);
+	const args = asRecord(display.args);
+	const title = typeof details?.title === "string" && details.title.trim()
+		? details.title.trim()
+		: typeof args?.activityTitle === "string" && args.activityTitle.trim()
+			? args.activityTitle.trim()
+			: `Cursor ${display.toolName}`;
+	const summary = typeof details?.summary === "string" && details.summary.trim()
+		? details.summary.trim()
+		: typeof args?.activitySummary === "string" && args.activitySummary.trim()
+			? args.activitySummary.trim()
+			: getCursorReplayResultText(display) ?? "completed";
+	return `${truncateCursorDisplayLine(title)}: ${truncateCursorDisplayLine(summary)}\n`;
+}

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

@@ -1,7 +1,6 @@
-import type { ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent, TurnStartEvent } from "@earendil-works/pi-coding-agent";
 import {
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
-	CURSOR_REPLAY_TOOL_NAMES,
 	isNativeCursorToolName,
 	NATIVE_CURSOR_TOOL_NAMES,
 	registerNativeCursorTool,
@@ -16,10 +15,14 @@ import {
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-names.js";
 
+const CORE_PI_TOOL_NAMES = new Set(["read", "bash", "edit", "write"]);
+
 type CursorNativeToolRegistryApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "registerTool" | "setActiveTools">;
 
 export interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi {
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
 	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
 }
 
@@ -46,7 +49,8 @@ export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "
 			changed = true;
 		}
 	} else {
-		for (const toolName of CURSOR_REPLAY_TOOL_NAMES) {
+		for (const toolName of registeredNativeToolNames) {
+			if (CORE_PI_TOOL_NAMES.has(toolName)) continue;
 			if (!activeToolNames.delete(toolName)) continue;
 			changed = true;
 		}
@@ -85,6 +89,12 @@ export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExten
 	pi.on("session_start", (_event, ctx) => {
 		registerAvailableNativeCursorTools(pi, ctx);
 	});
+	pi.on("before_agent_start", (_event, ctx) => {
+		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+	});
+	pi.on("turn_start", (_event, ctx) => {
+		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+	});
 	pi.on("model_select", (event) => {
 		syncRegisteredNativeCursorToolsForModel(pi, event.model);
 	});

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

@@ -23,6 +23,8 @@ import { resetSessionCursorAgent } from "./cursor-session-agent.js";
 import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";
 import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import { hasUsableText } from "./cursor-record-utils.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-routing.js";
 
 export const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
 const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
@@ -200,6 +202,13 @@ function emitCursorNativeToolUseTurn(
 	cursorLiveRuns.requestIdleDispose(run);
 }
 
+function emitInactiveCursorReplayTrace(turn: CursorLiveTurnState, tools: CursorNativeToolDisplayItem[]): void {
+	if (tools.length === 0) return;
+	for (const tool of tools) {
+		turn.emitter.appendThinkingBlock(formatInactiveCursorReplayTrace(tool));
+	}
+}
+
 function emitCursorBridgeToolUseTurn(
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,
@@ -229,24 +238,30 @@ function emitCursorBridgeToolUseTurn(
 }
 
 async function emitCursorLiveRunPendingToolUseTurn(
+	turn: CursorLiveTurnState,
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,
 	model: Model<Api>,
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	signal?: AbortSignal,
-	beforeEmit?: () => void,
-): Promise<"tool_use" | undefined> {
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal },
+): Promise<"tool_use" | "handled" | undefined> {
 	const eventType = cursorLiveRuns.peekEvent(run)?.type;
 	if (eventType !== "tool" && eventType !== "bridge-tool") return undefined;
 	await settleCursorLiveToolBatch(run);
-	if (signal?.aborted) throw new CursorLiveRunAbortError();
-	beforeEmit?.();
+	if (options.signal?.aborted) throw new CursorLiveRunAbortError();
 	if (eventType === "tool") {
-		const tools = cursorLiveRuns.collectNativeToolBatch(run);
-		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, tools);
+		const { active, inactive } = partitionNativeToolsByActiveContext(context, cursorLiveRuns.collectNativeToolBatch(run));
+		if (options.mode === "emit") emitInactiveCursorReplayTrace(turn, inactive);
+		if (active.length === 0) {
+			// Inactive-only batch: trace was emitted above; do not emit toolUse.
+			return "handled";
+		}
+		if (options.mode === "emit") turn.emitter.closeAll();
+		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active);
 	} else {
+		if (options.mode === "emit") turn.emitter.closeAll();
 		const requests = cursorLiveRuns.collectBridgeToolBatch(run);
 		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests);
 	}
@@ -275,16 +290,17 @@ export async function drainCursorLiveRunTurn(
 
 		while (cursorLiveRuns.peekEvent(run)) {
 			const toolUse = await emitCursorLiveRunPendingToolUseTurn(
+				turn,
 				stream,
 				partial,
 				model,
 				context,
 				run,
 				toolResultInputTokens,
-				options.signal,
-				options.mode === "emit" ? () => turn.emitter.closeAll() : undefined,
+				options,
 			);
-			if (toolUse) return toolUse;
+			if (toolUse === "tool_use") return toolUse;
+			if (toolUse === "handled") continue;
 			const event = cursorLiveRuns.shiftEvent(run);
 			if (!event || event.type === "tool" || event.type === "bridge-tool") continue;
 			if (options.mode === "emit") emitCursorLiveQueuedEvent(turn, event, run);
@@ -376,4 +392,14 @@ export function resetCursorNativeReplayIdleDisposeMs(): void {
 	cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
 }
 
+export async function releaseAllPendingCursorLiveRunsForTests(): Promise<void> {
+	while (cursorLiveRuns.count() > 0) {
+		const run = cursorLiveRuns.getActiveForScope();
+		if (!run) break;
+		const before = cursorLiveRuns.count();
+		await cursorLiveRuns.release(run);
+		if (cursorLiveRuns.count() >= before) break;
+	}
+}
+
 export { hasTrailingUserMessagesAfterToolResults };

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

@@ -2,24 +2,17 @@ import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-wo
 import type { InteractionUpdate } from "@cursor/sdk";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
-import { canRenderCursorToolNatively } from "./cursor-native-tool-display.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { resolveNativeReplayDisposition } from "./cursor-native-replay-routing.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import { asRecord, getField, hasUsableText } from "./cursor-record-utils.js";
 import { scrubPiToolDisplay, scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { buildCursorPiToolDisplay, formatCursorToolTranscript, getCursorCreatePlanText, mergeCursorToolCalls } from "./cursor-tool-transcript.js";
 import { getString, getToolArgs, getToolName } from "./cursor-transcript-utils.js";
 
-function sanitizeSingleLine(value: string): string {
-	return value.replace(/\s+/g, " ").trim();
-}
-
-function truncateSingleLine(value: string, maxLength = 240): string {
-	const sanitized = sanitizeSingleLine(value);
-	return sanitized.length > maxLength ? `${sanitized.slice(0, maxLength - 1)}…` : sanitized;
-}
-
 function formatCursorToolName(toolCall: unknown): string {
-	return truncateSingleLine(getToolName(toolCall), 80) || "unknown";
+	return truncateCursorDisplayLine(getToolName(toolCall), 80) || "unknown";
 }
 
 interface CursorShellOutputDelta {
@@ -45,7 +38,7 @@ function extractCursorTaskProgressLabel(toolCall: unknown, apiKey?: string): str
 	if (!isCursorTaskToolCall(toolCall)) return undefined;
 	const description = getString(getToolArgs(toolCall), "description");
 	if (!description?.trim()) return undefined;
-	return truncateSingleLine(scrubSensitiveText(description, apiKey));
+	return truncateCursorDisplayLine(scrubSensitiveText(description, apiKey));
 }
 
 function getCursorShellOutputDelta(update: InteractionUpdate): CursorShellOutputDelta | undefined {
@@ -107,6 +100,7 @@ export interface CursorSdkTurnCoordinatorOptions {
 	resolvedApiKey?: string;
 	liveRun?: CursorLiveRun;
 	useNativeToolReplay: boolean;
+	activeToolNames?: ReadonlySet<string>;
 	nativeReplayId: string;
 	textDeltas: string[];
 }
@@ -118,6 +112,7 @@ export class CursorSdkTurnCoordinator {
 	readonly resolvedApiKey?: string;
 	readonly liveRun?: CursorLiveRun;
 	readonly useNativeToolReplay: boolean;
+	readonly activeToolNames?: ReadonlySet<string>;
 	readonly nativeReplayId: string;
 	readonly textDeltas: string[];
 
@@ -142,6 +137,7 @@ export class CursorSdkTurnCoordinator {
 		this.resolvedApiKey = options.resolvedApiKey;
 		this.liveRun = options.liveRun;
 		this.useNativeToolReplay = options.useNativeToolReplay;
+		this.activeToolNames = options.activeToolNames;
 		this.nativeReplayId = options.nativeReplayId;
 		this.textDeltas = options.textDeltas;
 		this.contentEmitter = new CursorPartialContentEmitter(options.stream, options.partial, undefined, false);
@@ -232,7 +228,7 @@ export class CursorSdkTurnCoordinator {
 			return;
 		}
 		if (update.type === "summary") {
-			const summary = `Cursor summary: ${truncateSingleLine(update.summary)}\n`;
+			const summary = `Cursor summary: ${truncateCursorDisplayLine(update.summary)}\n`;
 			if (this.liveRun) {
 				cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: summary });
 			} else {
@@ -346,10 +342,14 @@ export class CursorSdkTurnCoordinator {
 			this.completedFallbackToolFingerprints.add(fingerprint);
 		}
 
-		const nativeRenderable = canRenderCursorToolNatively(display.toolName);
-		const route = this.useNativeToolReplay && nativeRenderable && this.liveRun ? "native_replay" : "trace";
+		const disposition = resolveNativeReplayDisposition({
+			toolName: display.toolName,
+			useNativeToolReplay: this.useNativeToolReplay,
+			activeToolNames: this.activeToolNames,
+			hasLiveRun: this.liveRun !== undefined,
+		});
 
-		if (route === "native_replay" && this.liveRun) {
+		if (disposition === "queue_replay" && this.liveRun) {
 			this.nativeToolReplayStarted = true;
 			const id = `${this.nativeReplayId}-tool-${++this.nativeToolDisplayCounter}`;
 			const scrubbedDisplay = scrubPiToolDisplay(display, this.resolvedApiKey);
@@ -360,7 +360,11 @@ export class CursorSdkTurnCoordinator {
 			return;
 		}
 
-		this.emitCursorToolTrace(transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`);
+		const traceText =
+			disposition === "inactive_trace"
+				? formatInactiveCursorReplayTrace(display)
+				: transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`;
+		this.emitCursorToolTrace(traceText);
 	}
 
 	private emitCursorToolTrace(text: string): void {

package/src/cursor-provider.ts

@@ -28,6 +28,7 @@ import {
 	getCursorPromptOptions,
 } from "./cursor-usage-accounting.js";
 import { getCursorSessionCwd } from "./cursor-session-cwd.js";
+import { getActiveContextToolNames } from "./cursor-context-tools.js";
 import { CursorLiveRunAbortError, type CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import {
 	abandonSessionCursorAgent,
@@ -38,6 +39,7 @@ import {
 	DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
 	getPendingCursorLiveRun,
 	hasTrailingUserMessagesAfterToolResults,
+	releaseAllPendingCursorLiveRunsForTests,
 	resetCursorNativeReplayIdleDisposeMs,
 	selectCursorFinalText,
 	setCursorNativeReplayIdleDisposeMs,
@@ -209,6 +211,7 @@ export function streamCursor(
 			const sessionBridgeRun = sessionAgentLease.bridgeRun;
 			const promptInputTokens = estimateCursorPromptInputTokens(prompt, promptOptions);
 			const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+			const activeToolNames = getActiveContextToolNames(context);
 			const nativeReplayId = createCursorNativeReplayId();
 			const textDeltas: string[] = [];
 			const useLiveRun = useNativeToolReplay || bridgeRun !== undefined;
@@ -237,6 +240,7 @@ export function streamCursor(
 				resolvedApiKey,
 				liveRun,
 				useNativeToolReplay,
+				activeToolNames,
 				nativeReplayId,
 				textDeltas,
 			});
@@ -365,5 +369,6 @@ export const __testUtils = {
 	hasTrailingUserMessagesAfterToolResults,
 	setCursorNativeReplayIdleDisposeMs,
 	resetCursorNativeReplayIdleDisposeMs,
+	releaseAllPendingCursorLiveRunsForTests,
 	resetSessionCursorAgents: () => disposeAllSessionCursorAgents(),
 };

package/src/cursor-question-tool.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent, TurnStartEvent } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge.js";
@@ -36,6 +36,8 @@ interface CursorQuestionDetails {
 
 interface CursorQuestionToolExtensionApi extends Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> {
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
 	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
 }
 
@@ -246,6 +248,12 @@ export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi):
 	pi.on("session_start", (_event, ctx) => {
 		syncCursorQuestionToolForModel(pi, ctx.model);
 	});
+	pi.on("before_agent_start", (_event, ctx) => {
+		syncCursorQuestionToolForModel(pi, ctx.model);
+	});
+	pi.on("turn_start", (_event, ctx) => {
+		syncCursorQuestionToolForModel(pi, ctx.model);
+	});
 	pi.on("model_select", (event) => {
 		syncCursorQuestionToolForModel(pi, event.model);
 	});