pi-cursor-sdk 0.1.40 → 0.1.42

package/scripts/visual-tui-smoke.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { accessSync, chmodSync, constants, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { accessSync, constants, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { commonBooleanFlag, commonRepeatStringFlag, parseArgv } from "./lib/cursor-cli-args.mjs";
 import { buildCursorSmokeEnvPlan, CURSOR_SDK_EVENT_DEBUG_ENV_NAMES, sealedNodePath } from "./lib/cursor-smoke-env.mjs";
+import { writeVisualManifest } from "./lib/cursor-visual-manifest.mjs";
+import { runVisualSmokeSelfTest } from "./visual-tui-smoke-self-test.mjs";
 import { buildTerminalHtml, writeTerminalScreenshot } from "./lib/cursor-visual-render.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -71,6 +72,7 @@ Artifacts written:
   <label>.html                  Self-contained browser/xterm render.
   <label>.png                   Browser-rendered screenshot, unless --no-screenshot.
   <label>.jsonl.path            Latest persisted pi session JSONL path.
+  <label>.manifest.json         Agent-readable artifact index for this run.
 
 Prerequisites:
   - pi, node, tmux, and npm-installed dev dependencies on PATH / in node_modules.
@@ -448,205 +450,60 @@ function runVisualSmoke(options) {
 		const htmlPath = `${base}.html`;
 		const pngPath = `${base}.png`;
 		const jsonlPathFile = `${base}.jsonl.path`;
+		const manifestPath = `${base}.manifest.json`;
 
 		writeUtf8(ansiPath, ansi);
 		writeUtf8(textPath, plain);
 		writeUtf8(htmlPath, buildTerminalHtml({ ansi, plain, options }));
 
+		const partialArtifacts = { ansiPath, textPath, htmlPath, pngPath, jsonlPathFile, manifestPath };
 		const jsonlPath = findLatestJsonl(options.sessionDir, { sinceMs: runStartedAtMs, previousMtimes: jsonlMtimesBeforeRun });
-		if (!jsonlPath) throw new Error(`no current-run persisted .jsonl found under ${options.sessionDir}`);
+		if (!jsonlPath) {
+			const message = `no current-run persisted .jsonl found under ${options.sessionDir}`;
+			writeVisualManifest(manifestPath, options, partialArtifacts, { message, writtenAt: new Date().toISOString() });
+			throw new Error(message);
+		}
 		writeUtf8(jsonlPathFile, `${jsonlPath}\n`);
 
-		return { ansiPath, textPath, htmlPath, pngPath, jsonlPathFile, jsonlPath };
+		return { ...partialArtifacts, jsonlPath };
 	} finally {
 		if (bufferLoaded) run(commands.tmux, ["delete-buffer", "-b", bufferName]);
 		if (sessionStarted) run(commands.tmux, ["kill-session", "-t", sessionName]);
 	}
 }
 
-function assertSelfTest(condition, message) {
-	if (!condition) throw new Error(`self-test failed: ${message}`);
-}
-
-function envMap(assignments) {
-	return new Map(assignments.map(([name, value]) => [name, value]));
-}
-
-function parseEnvCapture(path) {
-	return new Map(
-		readFileSync(path, "utf8")
-			.split("\n")
-			.filter(Boolean)
-			.map((line) => {
-				const index = line.indexOf("=");
-				return index === -1 ? [line, ""] : [line.slice(0, index), line.slice(index + 1)];
-			}),
-	);
-}
-
-function runSelfTest() {
-	const tempDir = mkdtempSync(join(tmpdir(), "pi-cursor-sdk-visual-self-test-"));
-	try {
-		const binDir = join(tempDir, "bin");
-		mkdirSync(binDir, { recursive: true });
-		const fakePi = join(binDir, "pi");
-		const fakeNode = join(binDir, "node");
-		const fakeNodeMarker = join(tempDir, "fake-node-used");
-		const envCapture = join(tempDir, "fake-pi.env");
-		writeFileSync(
-			fakePi,
-			`#!/usr/bin/env node\nconst { writeFileSync } = require("node:fs");\nwriteFileSync(${JSON.stringify(envCapture)}, Object.entries(process.env).map(([key, value]) => key + "=" + (value ?? "")).join("\\n") + "\\n", "utf8");\n`,
-			"utf8",
-		);
-		writeFileSync(fakeNode, `#!/bin/sh\necho fake-node-used > ${shellQuote(fakeNodeMarker)}\nexit 99\n`, "utf8");
-		chmodSync(fakePi, 0o755);
-		chmodSync(fakeNode, 0o755);
-
-		const promptFile = join(tempDir, "prompt.txt");
-		writeFileSync(promptFile, "file prompt", "utf8");
-		assertSelfTest(parseArgs(["--label", "prompt-order", "--prompt-file", promptFile, "--prompt", "inline prompt"]).prompt === "inline prompt", "--prompt should override an earlier --prompt-file");
-		assertSelfTest(parseArgs(["--label", "prompt-dash", "--prompt", "--starts-with-dash"]).prompt === "--starts-with-dash", "--prompt should accept dash-prefixed free-form text");
-		assertSelfTest(parseArgs(["--label", "prompt-order", "--prompt", "inline prompt", "--prompt-file", promptFile]).prompt === "file prompt", "--prompt-file should override an earlier --prompt");
-
-		const jsonlDir = join(tempDir, "jsonl-filter");
-		mkdirSync(jsonlDir, { recursive: true });
-		const staleJsonl = join(jsonlDir, "stale.jsonl");
-		const freshJsonl = join(jsonlDir, "fresh.jsonl");
-		writeFileSync(staleJsonl, "{}\n", "utf8");
-		utimesSync(staleJsonl, new Date(1_000), new Date(1_000));
-		const previousJsonlMtimes = snapshotJsonlMtimes(jsonlDir);
-		writeFileSync(freshJsonl, "{}\n", "utf8");
-		utimesSync(freshJsonl, new Date(3_000), new Date(3_000));
-		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 2_000, previousMtimes: previousJsonlMtimes }) === freshJsonl, "JSONL discovery should ignore unchanged stale files before run start");
-		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 4_000, previousMtimes: snapshotJsonlMtimes(jsonlDir) }) === undefined, "JSONL discovery should not return stale evidence when current run has no changed JSONL");
-
-		assertSelfTest(!sealedNodePath(process.execPath, "").includes(delimiter), "empty inherited PATH must not leave an empty PATH segment");
-		const hostilePath = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
-		const sealedHostilePath = sealedNodePath(process.execPath, hostilePath);
-		assertSelfTest(resolveCommand("pi", hostilePath) === fakePi, "direct PATH resolver did not prefer fake PATH head");
-		assertSelfTest(requireNode() === process.execPath, "node resolver must use process.execPath");
-		assertSelfTest(requireCommand("pi", { envPath: hostilePath, env: { ...process.env, PATH: sealedHostilePath } }) === fakePi, "pi prereq should use sealed PATH when executing the shim");
-		assertSelfTest(!existsSync(fakeNodeMarker), "pi prereq should not use hostile fake node");
-
-		const baseOptions = {
-			ext: ROOT,
-			cwd: ROOT,
-			mode: DEFAULT_MODE,
-			model: DEFAULT_MODEL,
-			outDir: tempDir,
-			safeLabel: "self-test",
-			sessionDir: join(tempDir, "session"),
-			sessionId: "self-test",
-			settingSources: DEFAULT_SETTING_SOURCES,
-			bridge: false,
-			exposeBuiltinTools: false,
-			eventDebug: false,
-		};
-		const plan = buildLaunchPlan(baseOptions, { pi: fakePi, node: process.execPath, sealedPath: sealedHostilePath }, "/bin/sh");
-		const defaults = envMap(plan.envAssignments);
-		assertSelfTest(defaults.get("PI_CURSOR_NATIVE_TOOL_DISPLAY") === "1", "native display must be forced on");
-		assertSelfTest(defaults.get("PI_CURSOR_REGISTER_NATIVE_TOOLS") === "1", "native tool registration must be forced on");
-		assertSelfTest(defaults.get("PI_CURSOR_SETTING_SOURCES") === "none", "setting sources must default to none");
-		assertSelfTest(defaults.get("PI_CURSOR_PI_TOOL_BRIDGE") === "0", "bridge must default off");
-		assertSelfTest(defaults.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "0", "built-in exposure must default off");
-		for (const name of DEBUG_ENV_NAMES) {
-			assertSelfTest(plan.clearEnvNames.includes(name), `${name} must be cleared by default`);
-		}
-		assertSelfTest(plan.script.includes(shellQuote(fakePi)), "launch script must use resolved pi path");
-		assertSelfTest(!plan.script.includes(" exec pi "), "launch script must not use bare pi");
-		const hostileEnv = {
-			...process.env,
-			...Object.fromEntries(DEBUG_ENV_NAMES.map((name) => [name, join(tempDir, name)])),
-			PATH: hostilePath,
-			PI_CURSOR_REGISTER_NATIVE_TOOLS: "0",
-			PI_CURSOR_SETTING_SOURCES: "all",
-			PI_CURSOR_PI_TOOL_BRIDGE: "1",
-			PI_CURSOR_EXPOSE_BUILTIN_TOOLS: "1",
-		};
-		const probe = run("/bin/sh", ["-c", plan.script], { env: hostileEnv });
-		assertSelfTest(probe.status === 0, `fake-pi env capture exited ${probe.status}: ${probe.stderr?.toString() ?? ""}`);
-		const capturedEnv = parseEnvCapture(envCapture);
-		assertSelfTest(!existsSync(fakeNodeMarker), "launch PATH should force the resolved node before hostile fake node");
-		assertSelfTest((capturedEnv.get("PATH") ?? "").split(delimiter)[0] === dirname(process.execPath), "captured PATH should start with resolved node directory");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_NATIVE_TOOL_DISPLAY") === "1", "captured env should force native display on");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_REGISTER_NATIVE_TOOLS") === "1", "captured env should force native registration on");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_SETTING_SOURCES") === "none", "captured env should force settings off");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_PI_TOOL_BRIDGE") === "0", "captured env should force bridge off");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "0", "captured env should force built-in exposure off");
-		for (const name of DEBUG_ENV_NAMES) {
-			assertSelfTest(!capturedEnv.has(name), `${name} should be absent from captured env by default`);
-		}
-
-		const optInPlan = buildLaunchPlan(
-			{ ...baseOptions, settingSources: "all", bridge: true, exposeBuiltinTools: true, eventDebug: true },
-			{ pi: fakePi, node: process.execPath, sealedPath: sealedHostilePath },
-			"/bin/sh",
-		);
-		const optIns = envMap(optInPlan.envAssignments);
-		assertSelfTest(optIns.get("PI_CURSOR_SETTING_SOURCES") === "all", "setting source opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_PI_TOOL_BRIDGE") === "1", "bridge opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "1", "built-in exposure opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_SDK_EVENT_DEBUG") === "1", "event debug opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_SDK_EVENT_DEBUG_DIR") === join(tempDir, "self-test.cursor-sdk-events"), "event debug dir must be deterministic under out-dir");
-		for (const name of DEBUG_ENV_NAMES) {
-			assertSelfTest(optInPlan.clearEnvNames.includes(name), `${name} must be cleared even when event debug is explicit`);
-		}
-		const eventDebugProbe = run("/bin/sh", ["-c", optInPlan.script], { env: hostileEnv });
-		assertSelfTest(eventDebugProbe.status === 0, `fake-pi event-debug env capture exited ${eventDebugProbe.status}: ${eventDebugProbe.stderr?.toString() ?? ""}`);
-		const capturedEventDebugEnv = parseEnvCapture(envCapture);
-		assertSelfTest(capturedEventDebugEnv.get("PI_CURSOR_SDK_EVENT_DEBUG") === "1", "event debug should be explicitly enabled");
-		assertSelfTest(capturedEventDebugEnv.get("PI_CURSOR_SDK_EVENT_DEBUG_DIR") === join(tempDir, "self-test.cursor-sdk-events"), "event debug dir should be deterministic under out-dir");
-		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_RUN_DIR"), "stale event debug run dir should be cleared");
-		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_SESSION_DIR"), "stale event debug session dir should be cleared");
-		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_STDERR"), "stale event debug stderr flag should be cleared");
-
-		const fakeTmux = join(binDir, "tmux");
-		const deleteBufferMarker = join(tempDir, "delete-buffer-called");
-		writeFileSync(
-			fakeTmux,
-			`#!/bin/sh\ncase "$1" in\n  -V) echo 'tmux fake'; exit 0 ;;\n  new-session) exit 0 ;;\n  load-buffer) cat >/dev/null; exit 0 ;;\n  paste-buffer) exit 77 ;;\n  delete-buffer) echo deleted > ${shellQuote(deleteBufferMarker)}; exit 0 ;;\n  kill-session) exit 0 ;;\n  *) echo "unexpected tmux command: $*" >&2; exit 64 ;;\nesac\n`,
-			"utf8",
-		);
-		chmodSync(fakeTmux, 0o755);
-		const originalPath = process.env.PATH;
-		try {
-			process.env.PATH = hostilePath;
-			let pasteFailed = false;
-			try {
-				runVisualSmoke({
-					...baseOptions,
-					prompt: "buffer cleanup prompt",
-					startupMs: 1,
-					waitMs: 1,
-					width: 80,
-					height: 24,
-					historyLines: 100,
-				});
-			} catch (error) {
-				pasteFailed = /paste-buffer failed/.test(error instanceof Error ? error.message : String(error));
-			}
-			assertSelfTest(pasteFailed, "fake tmux paste failure should exercise prompt-buffer cleanup path");
-			assertSelfTest(existsSync(deleteBufferMarker), "prompt tmux buffer should be deleted when paste/send fails");
-		} finally {
-			if (originalPath === undefined) delete process.env.PATH;
-			else process.env.PATH = originalPath;
-		}
-		console.log("[visual-smoke] self-test PASS");
-	} finally {
-		rmSync(tempDir, { recursive: true, force: true });
-	}
-}
 
 const options = parseArgs(process.argv.slice(2));
+let artifacts;
 try {
 	if (options.selfTest) {
-		runSelfTest();
+		runVisualSmokeSelfTest({
+			ROOT,
+			DEFAULT_MODE,
+			DEFAULT_MODEL,
+			DEFAULT_SETTING_SOURCES,
+			DEBUG_ENV_NAMES,
+			shellQuote,
+			parseArgs,
+			snapshotJsonlMtimes,
+			findLatestJsonl,
+			sealedNodePath,
+			resolveCommand,
+			requireNode,
+			requireCommand,
+			buildLaunchPlan,
+			run,
+			runVisualSmoke,
+		});
 		process.exit(0);
 	}
-	const artifacts = runVisualSmoke(options);
+	artifacts = runVisualSmoke(options);
+	writeVisualManifest(artifacts.manifestPath, options, artifacts);
 	checkLeftovers(options.leftoverPatterns);
 	if (options.screenshot) {
 		await writeTerminalScreenshot(artifacts.htmlPath, artifacts.pngPath, options.width, options.height);
+		artifacts.pngWritten = true;
+		writeVisualManifest(artifacts.manifestPath, options, artifacts);
 	}
 	console.log("[visual-smoke] artifacts:");
 	console.log(`  ansi:       ${artifacts.ansiPath}`);
@@ -655,6 +512,15 @@ try {
 	if (options.screenshot) console.log(`  png:        ${artifacts.pngPath}`);
 	console.log(`  jsonl.path: ${artifacts.jsonlPathFile}`);
 	console.log(`  jsonl:      ${artifacts.jsonlPath}`);
+	console.log(`  manifest:  ${artifacts.manifestPath}`);
 } catch (error) {
-	fail(error instanceof Error ? error.message : String(error));
+	const message = error instanceof Error ? error.message : String(error);
+	if (artifacts?.manifestPath) {
+		try {
+			writeVisualManifest(artifacts.manifestPath, options, artifacts, { message, writtenAt: new Date().toISOString() });
+		} catch {
+			// Preserve the original failure.
+		}
+	}
+	fail(message);
 }

package/src/context.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
-import type { SDKImage } from "@cursor/sdk";
+import type { AgentModeOption, SDKImage } from "@cursor/sdk";
 import { getCursorReplayPromptLabel } from "./cursor-tool-presentation-registry.js";
 
 export interface CursorPrompt {
@@ -13,6 +13,7 @@ export interface CursorPromptOptions {
 	maxInputTokens?: number;
 	charsPerToken?: number;
 	imageTokenEstimate?: number;
+	agentMode?: AgentModeOption;
 	/** Compact callable-surface summary; included on bootstrap prompts when set. */
 	toolManifest?: string;
 }
@@ -21,35 +22,49 @@ export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
 export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
-export function getCursorToolTailGuardText(): string {
+export function getCursorPlanModeToolGuidanceText(agentMode: AgentModeOption | undefined): 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");
+}
+
+export function getCursorToolTailGuardText(
+	options: Pick<CursorPromptOptions, "agentMode"> & { includePlanModeGuidance?: 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.",
-	].join("\n");
+	].filter((line): line is string => line !== undefined).join("\n");
 }
 
-function getCursorToolBoundaryText(options: { hasToolManifest?: boolean } = {}): string {
+function getCursorToolBoundaryText(options: Pick<CursorPromptOptions, "agentMode"> & { hasToolManifest?: boolean } = {}): string {
 	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.",
-	];
+	].filter((line): line is string => line !== undefined);
 	if (options.hasToolManifest) {
 		lines.push("See callable tool surfaces block below.");
 	}
 	return lines.join("\n");
 }
 
-function getCursorBootstrapTailSections(): string[] {
+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"),
-		getCursorToolTailGuardText(),
+		getCursorToolTailGuardText({ ...options, includePlanModeGuidance: false }),
 	];
 }
 
@@ -366,7 +381,7 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 	const parts = applyPromptBudget(
 		sectionsBeforeMessages,
 		latestUserMessageSections,
-		[getCursorToolTailGuardText()],
+		[getCursorToolTailGuardText(options)],
 		latestUserMessageIndex,
 		budgetOptions,
 	);
@@ -374,7 +389,7 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 }
 
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ hasToolManifest: Boolean(options.toolManifest) })];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ agentMode: options.agentMode, hasToolManifest: Boolean(options.toolManifest) })];
 	if (options.toolManifest) {
 		sectionsBeforeMessages.push(options.toolManifest);
 	}
@@ -390,7 +405,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 			return text ? { index, text } : undefined;
 		})
 		.filter((section): section is { index: number; text: string } => section !== undefined);
-	const sectionsAfterMessages = getCursorBootstrapTailSections();
+	const sectionsAfterMessages = getCursorBootstrapTailSections(options);
 	const images = extractLatestImages(messages);
 	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
 	const budgetOptions =

package/src/cursor-active-tools.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type CursorActiveToolApi = Pick<ExtensionAPI, "getActiveTools">;
+
+export function arePiToolsDisabled(pi: CursorActiveToolApi): boolean {
+	return pi.getActiveTools().length === 0;
+}

package/src/cursor-compact-tool-summary.ts

@@ -0,0 +1,81 @@
+import { isAbsolute, relative, win32 } from "node:path";
+import { asRecord, getRecord, getString } from "./cursor-record-utils.js";
+import { formatDisplayPath } from "./cursor-transcript-utils.js";
+
+export interface CursorCompactToolSummaryOptions {
+	cwd?: string;
+}
+
+function isWindowsAbsolutePath(path: string): boolean {
+	return /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+
+export function formatCursorCompactToolPath(path: string | undefined, options: CursorCompactToolSummaryOptions): string | undefined {
+	const trimmed = path?.trim();
+	if (!trimmed) return undefined;
+	const normalized = trimmed.replace(/\\/g, "/");
+	if (normalized === "~" || normalized.startsWith("~/") || /^~[^/]+(?:\/|$)/.test(normalized)) return undefined;
+	if (normalized.split("/").includes("..")) return undefined;
+	if (/^[A-Za-z]:(?!\/)/.test(normalized)) return undefined;
+	if (isWindowsAbsolutePath(trimmed)) {
+		const cwd = options.cwd;
+		if (!cwd || !isWindowsAbsolutePath(cwd)) return undefined;
+		const relativePath = win32.relative(cwd, trimmed);
+		if (!relativePath || relativePath.startsWith("..") || isWindowsAbsolutePath(relativePath)) return undefined;
+		return relativePath.replace(/\\/g, "/");
+	}
+	if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(normalized)) return undefined;
+	if (isAbsolute(trimmed)) {
+		const cwd = options.cwd;
+		if (!cwd) return undefined;
+		const relativePath = relative(cwd, trimmed);
+		if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath)) return undefined;
+		return relativePath.replace(/\\/g, "/");
+	}
+	return formatDisplayPath(normalized, options.cwd);
+}
+
+function getNestedRecord(record: Record<string, unknown> | undefined, ...keys: string[]): Record<string, unknown> | undefined {
+	let current = record;
+	for (const key of keys) {
+		current = getRecord(current, key);
+		if (!current) return undefined;
+	}
+	return current;
+}
+
+function summarizeShellTool(args: Record<string, unknown> | undefined, resultValue: Record<string, unknown> | undefined): string {
+	const command = getString(args, "command");
+	const stdout = getString(resultValue, "stdout");
+	const stderr = getString(resultValue, "stderr");
+	return [command ? `$ ${command}` : "shell", stdout, stderr].filter((part): part is string => Boolean(part)).join("\n");
+}
+
+export function summarizeCursorCompactToolCall(
+	toolName: string | undefined,
+	args: Record<string, unknown> | undefined,
+	result: Record<string, unknown> | undefined,
+	options: CursorCompactToolSummaryOptions,
+): string | undefined {
+	if (!toolName) return undefined;
+	const compactName = toolName.replace(/\s+/g, " ").trim() || "unknown";
+	if (compactName === "shell") return summarizeShellTool(args, getNestedRecord(result, "value"));
+
+	const path = formatCursorCompactToolPath(getString(args, "path"), options);
+	if (path) return `${compactName} ${path}`;
+	const query = getString(args, "query") ?? getString(args, "pattern");
+	if (query) return `${compactName} ${query}`;
+	return compactName;
+}
+
+export function summarizeCursorCompactConversationToolCall(step: unknown, options: CursorCompactToolSummaryOptions): string | undefined {
+	const record = asRecord(step);
+	if (getString(record, "type") !== "toolCall") return undefined;
+	const message = getRecord(record, "message");
+	return summarizeCursorCompactToolCall(
+		getString(message, "type"),
+		getRecord(message, "args"),
+		getRecord(message, "result"),
+		options,
+	);
+}

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

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { arePiToolsDisabled } from "./cursor-active-tools.js";
 import {
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
 	isNativeCursorToolName,
@@ -13,6 +14,7 @@ import {
 	NATIVE_CURSOR_TOOL_DISPLAY_ENV,
 	readBooleanEnv,
 	registeredNativeToolNames,
+	setCursorNativeToolDisplayRuntimeRequested,
 	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
@@ -70,37 +72,41 @@ function hasAttemptedNativeCursorToolRegistration(): boolean {
 	return registeredNativeToolNames.size > 0 || skippedNativeToolNames.size > 0;
 }
 
+function removeRegisteredNonCoreNativeCursorTools(pi: CursorNativeToolActivationApi): void {
+	if (registeredNativeToolNames.size === 0) return;
+	const activeToolNames = new Set(pi.getActiveTools());
+	let changed = false;
+	for (const toolName of registeredNativeToolNames) {
+		if (isCursorCorePiReplayToolName(toolName)) continue;
+		if (!activeToolNames.delete(toolName)) continue;
+		changed = true;
+	}
+	if (changed) pi.setActiveTools([...activeToolNames]);
+}
+
 export function syncRegisteredNativeCursorToolsForModel(
 	pi: CursorNativeToolActivationApi,
 	model: ExtensionContext["model"],
 ): void {
 	if (registeredNativeToolNames.size === 0) return;
+	if (!isCursorModel(model)) {
+		removeRegisteredNonCoreNativeCursorTools(pi);
+		return;
+	}
+	if (arePiToolsDisabled(pi)) return;
 	const activeToolNames = new Set(pi.getActiveTools());
 	let changed = false;
-	if (isCursorModel(model)) {
-		for (const toolName of registeredNativeToolNames) {
-			if (isCursorReplayToolName(toolName) && !CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES.some((activeReplayToolName) => activeReplayToolName === toolName)) continue;
-			if (activeToolNames.has(toolName)) continue;
-			activeToolNames.add(toolName);
-			changed = true;
-		}
-	} else {
-		for (const toolName of registeredNativeToolNames) {
-			if (isCursorCorePiReplayToolName(toolName)) continue;
-			if (!activeToolNames.delete(toolName)) continue;
-			changed = true;
-		}
+	for (const toolName of registeredNativeToolNames) {
+		if (isCursorReplayToolName(toolName) && !CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES.some((activeReplayToolName) => activeReplayToolName === toolName)) continue;
+		if (activeToolNames.has(toolName)) continue;
+		activeToolNames.add(toolName);
+		changed = true;
 	}
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
 async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
-	if (!isCursorNativeToolRegistrationRequested()) {
-		registeredNativeToolNames.clear();
-		skippedNativeToolNames.clear();
-		return;
-	}
-	if (ctx.mode !== "tui" || !isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
+	if (!isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
 
 	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
 	const skippedToolNames = [
@@ -111,9 +117,13 @@ async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolReg
 }
 
 async function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
-	if (isCursorModel(ctx.model) && !hasAttemptedNativeCursorToolRegistration()) {
-		await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
+	const requested = isCursorNativeToolRegistrationRequested(ctx.mode);
+	setCursorNativeToolDisplayRuntimeRequested(requested);
+	if (!requested) {
+		removeRegisteredNonCoreNativeCursorTools(pi);
+		return;
 	}
+	await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 

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

@@ -1,6 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { basename } from "node:path";
-import { getLanguageFromPath, highlightCode, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { getLanguageFromPath, highlightCode, keyHint, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Image, Text, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
@@ -9,6 +9,7 @@ import { LOCAL_READ_PREVIEW_NOTICE, isLocalReadPreviewContent } from "./cursor-t
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 	getCursorReplayCallSummary,
+	shouldShowCursorReplayCollapsedExpandHint,
 	type CursorReplayToolName,
 } from "./cursor-tool-presentation-registry.js";
 import {
@@ -423,6 +424,14 @@ function hasCursorReplayDisplayTitle(details: CursorReplayToolDetails | undefine
 	return isCursorReplayActivityDetails(details) || isCursorReplayGenerateImageDetails(details);
 }
 
+function formatCursorReplayExpandHint(): string {
+	try {
+		return keyHint("app.tools.expand", "to expand");
+	} catch {
+		return "Ctrl+O to expand";
+	}
+}
+
 function renderExpandableCursorReplayResult(
 	title: string,
 	details: CursorReplayExpandableResultDetails,
@@ -434,8 +443,10 @@ function renderExpandableCursorReplayResult(
 ): Component {
 	const text = firstContentText(result);
 	const summary = details.summary ?? text.split("\n").find((line) => line.trim()) ?? "completed";
-	let rendered = `${theme.fg("toolTitle", theme.bold(title))} ${theme.fg(isError ? "error" : "success", summary)}`;
 	const expandedText = details.expandedText ?? (text.includes("\n") ? text : undefined);
+	const showExpandHint = expandedText && !options.expanded && shouldShowCursorReplayCollapsedExpandHint(details.sourceToolName);
+	const expandHint = showExpandHint ? theme.fg("dim", ` (${formatCursorReplayExpandHint()})`) : "";
+	let rendered = `${theme.fg("toolTitle", theme.bold(title))} ${theme.fg(isError ? "error" : "success", summary)}${expandHint}`;
 	if (expandedText && (options.expanded || !details.collapseDetailsByDefault)) {
 		const preview = formatCursorReplayActivityPreview(
 			details,

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

@@ -13,18 +13,25 @@ export const registeredNativeToolNames = new Set<string>();
 export const skippedNativeToolNames = new Set<string>();
 export const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
 
+let nativeToolDisplayRuntimeRequested = false;
+
 export function readBooleanEnv(name: string, env: Record<string, string | undefined> = process.env): boolean | undefined {
 	return parseOptionalEnvBoolean(env[name]);
 }
 
-export function isCursorNativeToolDisplayRequested(): boolean {
+export function isCursorNativeToolDisplayRequested(mode?: string): boolean {
 	const override = readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV);
 	if (override !== undefined) return override;
+	if (mode) return mode === "tui" || mode === "json" || mode === "rpc";
 	return process.stdout.isTTY === true;
 }
 
-export function isCursorNativeToolRegistrationRequested(): boolean {
-	return readBooleanEnv(NATIVE_CURSOR_TOOL_REGISTRATION_ENV) !== false && isCursorNativeToolDisplayRequested();
+export function isCursorNativeToolRegistrationRequested(mode?: string): boolean {
+	return mode !== "print" && readBooleanEnv(NATIVE_CURSOR_TOOL_REGISTRATION_ENV) !== false && isCursorNativeToolDisplayRequested(mode);
+}
+
+export function setCursorNativeToolDisplayRuntimeRequested(requested: boolean): void {
+	nativeToolDisplayRuntimeRequested = requested;
 }
 
 export function isCursorNativeToolDisplayEnabled(): boolean {
@@ -32,7 +39,7 @@ export function isCursorNativeToolDisplayEnabled(): boolean {
 }
 
 export function isCursorNativeToolDisplayRuntimeEnabled(): boolean {
-	return isCursorNativeToolDisplayRequested() && registeredNativeToolNames.size > 0;
+	return nativeToolDisplayRuntimeRequested && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) !== false && registeredNativeToolNames.size > 0;
 }
 
 export function canRenderCursorToolNatively(toolName: string): boolean {
@@ -70,9 +77,11 @@ export function isCursorFileMutationToolName(toolName: string): toolName is "edi
 export const __testUtils = {
 	nativeToolResultCount: () => nativeToolResults.size,
 	registerNativeToolNameForTests(toolName: string): void {
+		nativeToolDisplayRuntimeRequested = true;
 		registeredNativeToolNames.add(toolName);
 	},
 	reset(): void {
+		nativeToolDisplayRuntimeRequested = false;
 		registeredNativeToolNames.clear();
 		skippedNativeToolNames.clear();
 		nativeToolResults.clear();