gsd-pi 2.80.0-dev.3065f7bfa → 2.80.0-dev.488219eb6

package/packages/pi-coding-agent/dist/resources/extensions/memory/storage-safety-guard.test.js

@@ -1,10 +1,28 @@
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { lstatSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-test("MemoryStorage persists sql.js snapshots through the atomic DB snapshot writer", () => {
-    const src = readFileSync(join(process.cwd(), "packages", "pi-coding-agent", "src", "resources", "extensions", "memory", "storage.ts"), "utf-8");
-    assert.match(src, /atomicWriteDbSnapshotSync\(/, "storage must use atomic DB snapshot writes");
-    assert.doesNotMatch(src, /writeFileSync\(this\.dbPath/, "direct live DB overwrite is forbidden");
+import { MemoryStorage } from "./storage.js";
+test("MemoryStorage replaces a symlinked DB path instead of overwriting the symlink target", async (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "memory-storage-atomic-"));
+    t.after(() => rmSync(dir, { recursive: true, force: true }));
+    const canaryPath = join(dir, "canary.txt");
+    const dbPath = join(dir, "memory.db");
+    const canaryStorage = await MemoryStorage.create(canaryPath);
+    canaryStorage.close();
+    const originalCanary = readFileSync(canaryPath);
+    symlinkSync(canaryPath, dbPath);
+    const storage = await MemoryStorage.create(dbPath);
+    storage.upsertThreads([{
+            threadId: "thread-1",
+            filePath: join(dir, "thread.jsonl"),
+            fileSize: 1,
+            fileMtime: 1,
+            cwd: dir,
+        }]);
+    storage.close();
+    assert.deepEqual(readFileSync(canaryPath), originalCanary);
+    assert.equal(lstatSync(dbPath).isSymbolicLink(), false, "atomic snapshot write should replace the symlink");
 });
 //# sourceMappingURL=storage-safety-guard.test.js.map

package/packages/pi-coding-agent/dist/resources/extensions/memory/storage-safety-guard.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage-safety-guard.test.js","sourceRoot":"","sources":["../../../../src/resources/extensions/memory/storage-safety-guard.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,IAAI,CAAC,+EAA+E,EAAE,GAAG,EAAE;IAC1F,MAAM,GAAG,GAAG,YAAY,CACvB,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,CAAC,EAC5G,OAAO,CACP,CAAC;IAEF,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,6BAA6B,EAAE,4CAA4C,CAAC,CAAC;IAC/F,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,6BAA6B,EAAE,uCAAuC,CAAC,CAAC;AAClG,CAAC,CAAC,CAAC","sourcesContent":["import assert from \"node:assert/strict\";\nimport { readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport test from \"node:test\";\n\ntest(\"MemoryStorage persists sql.js snapshots through the atomic DB snapshot writer\", () => {\n\tconst src = readFileSync(\n\t\tjoin(process.cwd(), \"packages\", \"pi-coding-agent\", \"src\", \"resources\", \"extensions\", \"memory\", \"storage.ts\"),\n\t\t\"utf-8\",\n\t);\n\n\tassert.match(src, /atomicWriteDbSnapshotSync\\(/, \"storage must use atomic DB snapshot writes\");\n\tassert.doesNotMatch(src, /writeFileSync\\(this\\.dbPath/, \"direct live DB overwrite is forbidden\");\n});\n"]}
+{"version":3,"file":"storage-safety-guard.test.js","sourceRoot":"","sources":["../../../../src/resources/extensions/memory/storage-safety-guard.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,IAAI,CAAC,sFAAsF,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IACxG,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAClE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE7D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7D,aAAa,CAAC,KAAK,EAAE,CAAC;IACtB,MAAM,cAAc,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAChD,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,CAAC,aAAa,CAAC,CAAC;YACtB,QAAQ,EAAE,UAAU;YACpB,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC;YACnC,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC;YACZ,GAAG,EAAE,GAAG;SACR,CAAC,CAAC,CAAC;IACJ,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,KAAK,EAAE,kDAAkD,CAAC,CAAC;AAC7G,CAAC,CAAC,CAAC","sourcesContent":["import assert from \"node:assert/strict\";\nimport { lstatSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport test from \"node:test\";\nimport { MemoryStorage } from \"./storage.js\";\n\ntest(\"MemoryStorage replaces a symlinked DB path instead of overwriting the symlink target\", async (t) => {\n\tconst dir = mkdtempSync(join(tmpdir(), \"memory-storage-atomic-\"));\n\tt.after(() => rmSync(dir, { recursive: true, force: true }));\n\n\tconst canaryPath = join(dir, \"canary.txt\");\n\tconst dbPath = join(dir, \"memory.db\");\n\tconst canaryStorage = await MemoryStorage.create(canaryPath);\n\tcanaryStorage.close();\n\tconst originalCanary = readFileSync(canaryPath);\n\tsymlinkSync(canaryPath, dbPath);\n\n\tconst storage = await MemoryStorage.create(dbPath);\n\tstorage.upsertThreads([{\n\t\tthreadId: \"thread-1\",\n\t\tfilePath: join(dir, \"thread.jsonl\"),\n\t\tfileSize: 1,\n\t\tfileMtime: 1,\n\t\tcwd: dir,\n\t}]);\n\tstorage.close();\n\n\tassert.deepEqual(readFileSync(canaryPath), originalCanary);\n\tassert.equal(lstatSync(dbPath).isSymbolicLink(), false, \"atomic snapshot write should replace the symlink\");\n});\n"]}

package/packages/pi-coding-agent/src/core/chat-controller-ordering.test.ts

@@ -1049,7 +1049,9 @@ test("chat-controller rolls up only contiguous low-signal tool runs on message_e
 	assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent");
 	assert.equal(host.chatContainer.children[2]?.constructor?.name, "ToolPhaseSummaryComponent");
 	assert.match(host.chatContainer.children[0].render(120).join("\n"), /Setup \/ shell 2 actions/);
-	assert.match(host.chatContainer.children[2].render(120).join("\n"), /Context reads 2 actions/);
+	const readSummary = host.chatContainer.children[2].render(120).join("\n");
+	assert.match(readSummary, /Context reads · 2 files/);
+	assert.match(readSummary, /\/tmp\/a · \/tmp\/b/);
 	assert.equal(host.chatContainer._prevRender, null, "summary reposition must invalidate the chat container render cache");
 });
 

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -69,6 +69,7 @@ import type {
 	LsToolInput,
 	ReadToolDetails,
 	ReadToolInput,
+	WriteToolDetails,
 	WriteToolInput,
 } from "../tools/index.js";
 
@@ -1031,7 +1032,7 @@ export interface EditToolResultEvent extends ToolResultEventBase {
 
 export interface WriteToolResultEvent extends ToolResultEventBase {
 	toolName: "write";
-	details: undefined;
+	details: WriteToolDetails | undefined;
 }
 
 export interface GrepToolResultEvent extends ToolResultEventBase {

package/packages/pi-coding-agent/src/core/tools/bash-spawn-windows.test.ts

@@ -19,76 +19,32 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
+import { createBashTool } from "./bash.js";
 
-// Verify the spawn option pattern used across the codebase.
-// This is a static/structural test — it reads the source files and asserts
-// they use the platform-guarded detached flag.
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-function findRepoRoot(): string {
-	const requiredFiles = [
-		"packages/pi-coding-agent/src/core/tools/bash.ts",
-		"packages/pi-coding-agent/src/core/bash-executor.ts",
-		"packages/pi-coding-agent/src/utils/shell.ts",
-	];
-	const candidates = [
-		resolve(__dirname, "../../../../../"),
-		resolve(__dirname, "../../../../../../"),
-	];
-	for (const candidate of candidates) {
-		if (requiredFiles.every((file) => existsSync(join(candidate, file)))) {
-			return candidate;
-		}
-	}
-	throw new Error(`Unable to resolve repository root from ${__dirname}`);
-}
-
-const REPO_ROOT = findRepoRoot();
-
-const SPAWN_FILES = [
-	join(REPO_ROOT, "packages/pi-coding-agent/src/core/tools/bash.ts"),
-	join(REPO_ROOT, "packages/pi-coding-agent/src/core/bash-executor.ts"),
-	join(REPO_ROOT, "packages/pi-coding-agent/src/utils/shell.ts"),
-];
-
-test("spawn calls use platform-guarded detached flag (no unconditional detached: true)", () => {
-	for (const file of SPAWN_FILES) {
-		const content = readFileSync(file, "utf-8");
-		const lines = content.split("\n");
-
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i]!;
-			// Skip comments
-			if (line.trim().startsWith("//") || line.trim().startsWith("*")) continue;
-			// Check for unconditional `detached: true`
-			if (/detached:\s*true\b/.test(line)) {
-				assert.fail(
-					`${file}:${i + 1} has unconditional 'detached: true' — ` +
-					`must use 'detached: process.platform !== "win32"' ` +
-					`to prevent EINVAL on Windows (ConPTY / VSCode terminal)`,
-				);
-			}
-		}
-	}
-});
+test("bash tool delegates command execution through operations without forcing process detachment", async () => {
+	const calls: Array<{ command: string; cwd: string; env?: NodeJS.ProcessEnv }> = [];
+	const tool = createBashTool(process.cwd(), {
+		operations: {
+			async exec(command, cwd, options) {
+				calls.push({ command, cwd, env: options.env });
+				options.onData(Buffer.from("ok\n"));
+				return { exitCode: 0 };
+			},
+		},
+	});
 
-test("killProcessTree does not use detached: true for taskkill on Windows", () => {
-	const shellFile = join(REPO_ROOT, "packages/pi-coding-agent/src/utils/shell.ts");
-	const content = readFileSync(shellFile, "utf-8");
+	const result = await tool.execute("tool-call", { command: "echo ok" });
+	const firstContent = result.content[0];
 
-	// Find the taskkill spawn call and ensure it doesn't have detached: true
-	const taskkillRegion = content.match(/spawn\("taskkill"[\s\S]*?\}\)/);
-	if (taskkillRegion) {
-		assert.ok(
-			!/detached:\s*true/.test(taskkillRegion[0]),
-			"taskkill spawn should not use detached: true — " +
-			"it can cause EINVAL on Windows and is unnecessary for a utility process",
-		);
+	assert.ok(firstContent);
+	if (firstContent.type !== "text") {
+		assert.fail(`Expected text content, got ${firstContent.type}`);
 	}
+	assert.equal(firstContent.text, "ok\n");
+	assert.deepEqual(calls.map((call) => ({ command: call.command, cwd: call.cwd })), [
+		{ command: "echo ok", cwd: process.cwd() },
+	]);
+	assert.ok(calls[0]?.env, "default bash context should provide an execution environment");
 });
 
 // Smoke test: spawn with platform-guarded detached flag actually works

package/packages/pi-coding-agent/src/core/tools/bash.ts

@@ -116,6 +116,7 @@ const bashSchema = Type.Object({
 export type BashToolInput = Static<typeof bashSchema>;
 
 export interface BashToolDetails {
+	cwd?: string;
 	truncation?: TruncationResult;
 	fullOutputPath?: string;
 	artifactId?: string;
@@ -384,6 +385,7 @@ export function createBashTool(cwd: string, options?: BashToolOptions): AgentToo
 						onUpdate({
 							content: [{ type: "text", text: truncation.content || "" }],
 							details: {
+								cwd: spawnContext.cwd,
 								truncation: truncation.truncated ? truncation : undefined,
 								fullOutputPath: spillFilePath,
 							},
@@ -412,10 +414,11 @@ export function createBashTool(cwd: string, options?: BashToolOptions): AgentToo
 						let outputText = truncation.content || "(no output)";
 
 						// Build details with truncation info
-						let details: BashToolDetails | undefined;
+						let details: BashToolDetails | undefined = { cwd: spawnContext.cwd };
 
 						if (truncation.truncated) {
 							details = {
+								...details,
 								truncation,
 								fullOutputPath: spillFilePath,
 								...(spillArtifactId ? { artifactId: spillArtifactId } : {}),

package/packages/pi-coding-agent/src/core/tools/edit.ts

@@ -13,6 +13,7 @@ import {
 } from "./edit-diff.js";
 import { notifyFileChanged } from "../lsp/client.js";
 import { resolveToCwd } from "./path-utils.js";
+import { createToolTarget, type ToolTargetMetadata } from "./tool-target.js";
 
 const editSchema = Type.Object({
 	path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
@@ -27,6 +28,7 @@ export interface EditToolDetails {
 	diff: string;
 	/** Line number of the first change in the new file (for editor navigation) */
 	firstChangedLine?: number;
+	target?: ToolTargetMetadata;
 }
 
 /**
@@ -208,7 +210,17 @@ export function createEditTool(cwd: string, options?: EditToolOptions): AgentToo
 									text: `Successfully replaced text in ${path}.`,
 								},
 							],
-							details: { diff: diffResult.diff, firstChangedLine: diffResult.firstChangedLine },
+							details: {
+								diff: diffResult.diff,
+								firstChangedLine: diffResult.firstChangedLine,
+								target: createToolTarget({
+									kind: "file",
+									action: "edit",
+									inputPath: path,
+									resolvedPath: absolutePath,
+									line: diffResult.firstChangedLine,
+								}),
+							},
 						});
 					} catch (error: any) {
 						// Clean up abort handler

package/packages/pi-coding-agent/src/core/tools/find.ts

@@ -5,6 +5,7 @@ import { existsSync } from "fs";
 import path from "path";
 import { FIND_DEFAULT_LIMIT } from "../constants.js";
 import { resolveToCwd } from "./path-utils.js";
+import { createToolTarget, type ToolTargetMetadata } from "./tool-target.js";
 import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
 
 const findSchema = Type.Object({
@@ -20,6 +21,7 @@ export type FindToolInput = Static<typeof findSchema>;
 const DEFAULT_LIMIT = FIND_DEFAULT_LIMIT;
 
 export interface FindToolDetails {
+	target?: ToolTargetMetadata;
 	truncation?: TruncationResult;
 	resultLimitReached?: number;
 }
@@ -73,6 +75,13 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 				(async () => {
 					try {
 						const searchPath = resolveToCwd(searchDir || ".", cwd);
+						const target = createToolTarget({
+							kind: "search",
+							action: "find",
+							inputPath: searchDir || ".",
+							resolvedPath: searchPath,
+							pattern,
+						});
 						const effectiveLimit = limit ?? DEFAULT_LIMIT;
 						const ops = customOps ?? defaultFindOperations;
 
@@ -93,7 +102,7 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 							if (results.length === 0) {
 								resolve({
 									content: [{ type: "text", text: "No files found matching pattern" }],
-									details: undefined,
+									details: { target },
 								});
 								return;
 							}
@@ -111,7 +120,7 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 							const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 
 							let resultOutput = truncation.content;
-							const details: FindToolDetails = {};
+							const details: FindToolDetails = { target };
 							const notices: string[] = [];
 
 							if (resultLimitReached) {
@@ -130,7 +139,7 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 
 							resolve({
 								content: [{ type: "text", text: resultOutput }],
-								details: Object.keys(details).length > 0 ? details : undefined,
+								details,
 							});
 							return;
 						}
@@ -150,7 +159,7 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 						if (globResult.matches.length === 0) {
 							resolve({
 								content: [{ type: "text", text: "No files found matching pattern" }],
-								details: undefined,
+								details: { target },
 							});
 							return;
 						}
@@ -163,7 +172,7 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 						const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 
 						let resultOutput = truncation.content;
-						const details: FindToolDetails = {};
+						const details: FindToolDetails = { target };
 						const notices: string[] = [];
 
 						if (resultLimitReached) {
@@ -184,7 +193,7 @@ export function createFindTool(cwd: string, options?: FindToolOptions): AgentToo
 
 						resolve({
 							content: [{ type: "text", text: resultOutput }],
-							details: Object.keys(details).length > 0 ? details : undefined,
+							details,
 						});
 					} catch (e: any) {
 						signal?.removeEventListener("abort", onAbort);

package/packages/pi-coding-agent/src/core/tools/grep.ts

@@ -6,6 +6,7 @@ import { readFileSync, statSync } from "fs";
 import path from "path";
 import { ensureTool } from "../../utils/tools-manager.js";
 import { resolveToCwd } from "./path-utils.js";
+import { createToolTarget, type ToolTargetMetadata } from "./tool-target.js";
 import {
 	DEFAULT_MAX_BYTES,
 	formatSize,
@@ -34,6 +35,7 @@ export type GrepToolInput = Static<typeof grepSchema>;
 const DEFAULT_LIMIT = 100;
 
 export interface GrepToolDetails {
+	target?: ToolTargetMetadata;
 	truncation?: TruncationResult;
 	matchLimitReached?: number;
 	linesTruncated?: boolean;
@@ -112,6 +114,14 @@ export function createGrepTool(cwd: string, options?: GrepToolOptions): AgentToo
 						}
 
 						const searchPath = resolveToCwd(searchDir || ".", cwd);
+						const target = createToolTarget({
+							kind: "search",
+							action: "grep",
+							inputPath: searchDir || ".",
+							resolvedPath: searchPath,
+							pattern,
+							glob,
+						});
 						const ops = customOps ?? defaultGrepOperations;
 
 						let isDirectory: boolean;
@@ -282,7 +292,7 @@ export function createGrepTool(cwd: string, options?: GrepToolOptions): AgentToo
 
 							if (matchCount === 0) {
 								settle(() =>
-									resolve({ content: [{ type: "text", text: "No matches found" }], details: undefined }),
+									resolve({ content: [{ type: "text", text: "No matches found" }], details: { target } }),
 								);
 								return;
 							}
@@ -298,7 +308,7 @@ export function createGrepTool(cwd: string, options?: GrepToolOptions): AgentToo
 							const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 
 							let output = truncation.content;
-							const details: GrepToolDetails = {};
+							const details: GrepToolDetails = { target };
 
 							// Build notices
 							const notices: string[] = [];
@@ -329,7 +339,7 @@ export function createGrepTool(cwd: string, options?: GrepToolOptions): AgentToo
 							settle(() =>
 								resolve({
 									content: [{ type: "text", text: output }],
-									details: Object.keys(details).length > 0 ? details : undefined,
+									details,
 								}),
 							);
 						});

package/packages/pi-coding-agent/src/core/tools/hashline-read.ts

@@ -17,6 +17,7 @@ import { formatDimensionNote, resizeImage } from "../../utils/image-resize.js";
 import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
 import { formatHashLines } from "./hashline.js";
 import { resolveReadPath } from "./path-utils.js";
+import { createReadFileTarget, type ToolTargetMetadata } from "./tool-target.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
 
 const readSchema = Type.Object({
@@ -28,6 +29,7 @@ const readSchema = Type.Object({
 export type HashlineReadToolInput = Static<typeof readSchema>;
 
 export interface HashlineReadToolDetails {
+	target?: ToolTargetMetadata;
 	truncation?: TruncationResult;
 }
 
@@ -66,6 +68,7 @@ export function createHashlineReadTool(cwd: string, options?: HashlineReadToolOp
 			signal?: AbortSignal,
 		) => {
 			const absolutePath = resolveReadPath(path, cwd);
+			const target = createReadFileTarget(path, absolutePath, offset, limit);
 
 			return new Promise<{ content: (TextContent | ImageContent)[]; details: HashlineReadToolDetails | undefined }>(
 				(resolve, reject) => {
@@ -186,7 +189,7 @@ export function createHashlineReadTool(cwd: string, options?: HashlineReadToolOp
 							if (aborted) return;
 
 							if (signal) signal.removeEventListener("abort", onAbort);
-							resolve({ content, details });
+							resolve({ content, details: { ...details, target } });
 						} catch (error: any) {
 							if (signal) signal.removeEventListener("abort", onAbort);
 							if (!aborted) {

package/packages/pi-coding-agent/src/core/tools/index.ts

@@ -70,10 +70,18 @@ export {
 export {
 	createWriteTool,
 	type WriteOperations,
+	type WriteToolDetails,
 	type WriteToolInput,
 	type WriteToolOptions,
 	writeTool,
 } from "./write.js";
+export {
+	createToolTarget,
+	type ToolTargetAction,
+	type ToolTargetKind,
+	type ToolTargetMetadata,
+	type ToolTargetRange,
+} from "./tool-target.js";
 export {
 	createHashlineEditTool,
 	type HashlineEditInput,

package/packages/pi-coding-agent/src/core/tools/ls.ts

@@ -3,6 +3,7 @@ import { type Static, Type } from "@sinclair/typebox";
 import { existsSync, readdirSync, statSync } from "fs";
 import nodePath from "path";
 import { resolveToCwd } from "./path-utils.js";
+import { createToolTarget, type ToolTargetMetadata } from "./tool-target.js";
 import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
 
 const lsSchema = Type.Object({
@@ -15,6 +16,7 @@ export type LsToolInput = Static<typeof lsSchema>;
 const DEFAULT_LIMIT = 500;
 
 export interface LsToolDetails {
+	target?: ToolTargetMetadata;
 	truncation?: TruncationResult;
 	entryLimitReached?: number;
 }
@@ -68,6 +70,12 @@ export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<ty
 				(async () => {
 					try {
 						const dirPath = resolveToCwd(path || ".", cwd);
+						const target = createToolTarget({
+							kind: "directory",
+							action: "list",
+							inputPath: path || ".",
+							resolvedPath: dirPath,
+						});
 						const effectiveLimit = limit ?? DEFAULT_LIMIT;
 
 						// Check if path exists
@@ -124,7 +132,7 @@ export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<ty
 						signal?.removeEventListener("abort", onAbort);
 
 						if (results.length === 0) {
-							resolve({ content: [{ type: "text", text: "(empty directory)" }], details: undefined });
+							resolve({ content: [{ type: "text", text: "(empty directory)" }], details: { target } });
 							return;
 						}
 
@@ -133,7 +141,7 @@ export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<ty
 						const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 
 						let output = truncation.content;
-						const details: LsToolDetails = {};
+						const details: LsToolDetails = { target };
 
 						// Build notices
 						const notices: string[] = [];
@@ -154,7 +162,7 @@ export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<ty
 
 						resolve({
 							content: [{ type: "text", text: output }],
-							details: Object.keys(details).length > 0 ? details : undefined,
+							details,
 						});
 					} catch (e: any) {
 						signal?.removeEventListener("abort", onAbort);

package/packages/pi-coding-agent/src/core/tools/read.ts

@@ -6,6 +6,7 @@ import { access as fsAccess, readFile as fsReadFile } from "fs/promises";
 import { formatDimensionNote, resizeImage } from "../../utils/image-resize.js";
 import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.js";
 import { resolveReadPath } from "./path-utils.js";
+import { createReadFileTarget, type ToolTargetMetadata } from "./tool-target.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "./truncate.js";
 
 const readSchema = Type.Object({
@@ -17,6 +18,7 @@ const readSchema = Type.Object({
 export type ReadToolInput = Static<typeof readSchema>;
 
 export interface ReadToolDetails {
+	target?: ToolTargetMetadata;
 	truncation?: TruncationResult;
 }
 
@@ -61,6 +63,7 @@ export function createReadTool(cwd: string, options?: ReadToolOptions): AgentToo
 			signal?: AbortSignal,
 		) => {
 			const absolutePath = resolveReadPath(path, cwd);
+			const target = createReadFileTarget(path, absolutePath, offset, limit);
 
 			return new Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }>(
 				(resolve, reject) => {
@@ -210,7 +213,7 @@ export function createReadTool(cwd: string, options?: ReadToolOptions): AgentToo
 								signal.removeEventListener("abort", onAbort);
 							}
 
-							resolve({ content, details });
+							resolve({ content, details: { ...details, target } });
 						} catch (error: any) {
 							// Clean up abort handler
 							if (signal) {

package/packages/pi-coding-agent/src/core/tools/spawn-shell-windows.test.ts

@@ -15,78 +15,17 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname, relative } from "node:path";
-import { fileURLToPath } from "node:url";
+import { execCommand } from "../exec.js";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const coreDir = join(__dirname, "..");
-
-/**
- * Files that call `spawn()` with a user-facing binary (not `node`, `sh`, `bash`,
- * or `cmd`) and therefore need the Windows shell guard.
- *
- * If a file spawns only hardcoded system binaries (like `node` in rpc-client.ts),
- * it does not need the guard and should NOT appear here.
- */
-const SPAWN_FILES_NEEDING_SHELL_GUARD = [
-	// Extension's GSD client — spawns the `gsd` binary which is a .cmd on Windows
-	join(coreDir, "..", "..", "..", "vscode-extension", "src", "gsd-client.ts"),
-	// exec.ts — used by extensions to run arbitrary commands
-	join(coreDir, "exec.ts"),
-	// LSP index — spawns project-type commands (tsc, cargo, etc.)
-	join(coreDir, "lsp", "index.ts"),
-	// LSP client — spawns LSP server binaries (npx, etc.)
-	join(coreDir, "lsp", "client.ts"),
-	// LSP mux — spawns lspmux binary
-	join(coreDir, "lsp", "lspmux.ts"),
-	// Package manager — spawns npm/yarn/pnpm
-	join(coreDir, "package-manager.ts"),
-];
-
-test("all spawn sites that invoke user-facing binaries include shell: process.platform === 'win32'", () => {
-	const failures: string[] = [];
-
-	for (const file of SPAWN_FILES_NEEDING_SHELL_GUARD) {
-		let content: string;
-		try {
-			content = readFileSync(file, "utf-8");
-		} catch {
-			// File may not exist in this checkout — skip
-			continue;
-		}
-
-		const lines = content.split("\n");
-
-		// Find all spawn(..., { ... }) call sites and check each one
-		// for the presence of `shell: process.platform === "win32"` within
-		// 5 lines after the spawn call.
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i]!;
-			// Skip comments
-			if (line.trim().startsWith("//") || line.trim().startsWith("*")) continue;
-
-			// Detect a spawn() call
-			if (/\bspawn\(/.test(line)) {
-				// Look ahead up to 8 lines for the shell guard
-				const lookahead = lines.slice(i, i + 8).join("\n");
-				const hasShellGuard =
-					/shell:\s*process\.platform\s*===\s*["']win32["']/.test(lookahead);
-
-				if (!hasShellGuard) {
-					const relPath = relative(join(coreDir, "..", ".."), file);
-					failures.push(`${relPath}:${i + 1}`);
-				}
-			}
-		}
-	}
-
-	assert.deepEqual(
-		failures,
-		[],
-		`The following spawn sites are missing 'shell: process.platform === "win32"':\n` +
-		failures.map(f => `  - ${f}`).join("\n") +
-		`\nOn Windows, .cmd wrapper scripts (npm, npx, tsc, gsd) require shell ` +
-		`resolution. Without this guard, spawn fails with ENOENT or EINVAL.`,
+test("execCommand runs a user-facing binary and captures stdout", async () => {
+	const result = await execCommand(
+		process.execPath,
+		["-e", "process.stdout.write('ok')"],
+		process.cwd(),
 	);
+
+	assert.equal(result.stdout, "ok");
+	assert.equal(result.stderr, "");
+	assert.equal(result.code, 0);
+	assert.equal(result.killed, false);
 });