gsd-pi 2.80.0-dev.fbe7c8c6f → 2.81.0-dev.3cddbbba2

package/packages/pi-coding-agent/src/core/sdk.ts

@@ -1,3 +1,4 @@
+// GSD2 - Coding agent session factory and runtime wiring
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
@@ -38,8 +39,53 @@ export function canRestoreSessionModel(
 ): boolean {
 	return modelRegistry.isProviderRequestReady(model.provider);
 }
-import { Agent, type AgentMessage, type ThinkingLevel } from "@gsd/pi-agent-core";
-import type { Message, Model } from "@gsd/pi-ai";
+
+const PROVIDER_TOOL_LIMITS: Record<string, number> = {
+	groq: 128,
+};
+
+function resolveProviderToolLimit(
+	providerCaps: ReturnType<typeof getProviderCapabilities>,
+	provider: string | undefined,
+): number {
+	if (provider && PROVIDER_TOOL_LIMITS[provider]) {
+		return PROVIDER_TOOL_LIMITS[provider];
+	}
+	return providerCaps.maxTools > 0 ? providerCaps.maxTools : 0;
+}
+
+export function filterToolsForProviderRequest(
+	tools: AgentTool[],
+	model: Pick<Model<any>, "api" | "provider">,
+): { compatible: AgentTool[]; filtered: AgentTool[] } {
+	const providerCaps = getProviderCapabilities(model.api);
+	if (!providerCaps.toolCalling) {
+		return { compatible: [], filtered: tools };
+	}
+
+	const compatible: AgentTool[] = [];
+	const filtered: AgentTool[] = [];
+	for (const tool of tools) {
+		const compat = getToolCompatibility(tool.name);
+		if (
+			(compat?.producesImages && !providerCaps.imageToolResults) ||
+			compat?.schemaFeatures?.some((feature) => providerCaps.unsupportedSchemaFeatures.includes(feature))
+		) {
+			filtered.push(tool);
+		} else {
+			compatible.push(tool);
+		}
+	}
+
+	const toolLimit = resolveProviderToolLimit(providerCaps, model.provider);
+	if (toolLimit > 0 && compatible.length > toolLimit) {
+		filtered.push(...compatible.splice(toolLimit));
+	}
+
+	return { compatible, filtered };
+}
+import { Agent, maybeLogProviderPayloadAudit, type AgentMessage, type AgentTool, type ThinkingLevel } from "@gsd/pi-agent-core";
+import { getProviderCapabilities, type Message, type Model } from "@gsd/pi-ai";
 import { getAgentDir, getDocsPath } from "../config.js";
 import { AgentSession } from "./agent-session.js";
 import { AuthStorage } from "./auth-storage.js";
@@ -82,6 +128,22 @@ import {
 	type ToolName,
 	writeTool,
 } from "./tools/index.js";
+import { getToolCompatibility } from "./tools/tool-compatibility-registry.js";
+
+export function getAdjustToolSetRequestCustomMessages(
+	messages: readonly AgentMessage[] | undefined,
+): Array<{ index: number; customType: string }> {
+	if (!messages) return [];
+	const requestMessages: Array<{ index: number; customType: string }> = [];
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index] as { role?: unknown; customType?: unknown };
+		if (message?.role === "assistant") break;
+		if (message?.role === "custom" && typeof message.customType === "string") {
+			requestMessages.push({ index, customType: message.customType });
+		}
+	}
+	return requestMessages.reverse();
+}
 
 export interface CreateAgentSessionOptions {
 	/** Working directory for project-local discovery. Default: process.cwd() */
@@ -378,6 +440,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	};
 
 	const extensionRunnerRef: { current?: ExtensionRunner } = {};
+	const workspaceRootRef: { current: string } = { current: cwd };
 
 	agent = new Agent({
 		initialState: {
@@ -390,9 +453,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		onPayload: async (payload, currentModel) => {
 			const runner = extensionRunnerRef.current;
 			if (!runner?.hasHandlers("before_provider_request")) {
+				maybeLogProviderPayloadAudit(payload, "before_provider_request:unchanged");
 				return payload;
 			}
-			return runner.emitBeforeProviderRequest(payload, currentModel);
+			const nextPayload = await runner.emitBeforeProviderRequest(payload, currentModel);
+			maybeLogProviderPayloadAudit(nextPayload, "before_provider_request:after");
+			return nextPayload;
 		},
 		sessionId: sessionManager.getSessionId(),
 		transformContext: async (messages) => {
@@ -400,6 +466,24 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (!runner) return messages;
 			return runner.emitContext(messages);
 		},
+		filterTools: async (tools, _signal, messages) => {
+			const currentModel = agent.state.activeInferenceModel ?? agent.state.model ?? model;
+			if (!currentModel) return tools;
+			const providerFiltered = filterToolsForProviderRequest(tools, currentModel);
+			const runner = extensionRunnerRef.current;
+			if (!runner?.hasHandlers("adjust_tool_set")) return providerFiltered.compatible;
+			const result = await runner.emitAdjustToolSet({
+				selectedModelApi: currentModel.api,
+				selectedModelProvider: currentModel.provider,
+				selectedModelId: currentModel.id,
+				activeToolNames: providerFiltered.compatible.map((tool) => tool.name),
+				filteredTools: providerFiltered.filtered.map((tool) => tool.name),
+				requestCustomMessages: getAdjustToolSetRequestCustomMessages(messages),
+			});
+			if (!result?.toolNames) return providerFiltered.compatible;
+			const allowedNames = new Set(result.toolNames);
+			return providerFiltered.compatible.filter((tool) => allowedNames.has(tool.name));
+		},
 		steeringMode: settingsManager.getSteeringMode(),
 		followUpMode: settingsManager.getFollowUpMode(),
 		transport: settingsManager.getTransport(),
@@ -409,8 +493,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		getProviderOptions: async (currentModel) => {
 			if (currentModel.provider !== "claude-code") return undefined;
 			const runner = extensionRunnerRef.current;
-			if (!runner?.hasUI()) return undefined;
+			if (!runner?.hasUI()) {
+				return { cwd: workspaceRootRef.current };
+			}
 			return {
+				cwd: workspaceRootRef.current,
 				extensionUIContext: runner.getUIContext(),
 			};
 		},
@@ -554,6 +641,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		modelRegistry,
 		initialActiveToolNames,
 		extensionRunnerRef,
+		workspaceRootRef,
 		isClaudeCodeReady: options.isClaudeCodeReady,
 	});
 	const extensionsResult = resourceLoader.getExtensions();

package/packages/pi-coding-agent/src/core/settings-manager.ts

@@ -15,6 +15,13 @@ export interface CompactionSettings {
 	enabled?: boolean; // default: true
 	reserveTokens?: number; // default: 16384
 	keepRecentTokens?: number; // default: 20000
+	/**
+	 * Optional percent-of-context-window trigger (0 < value < 1). When set,
+	 * compaction fires at `contextWindow * thresholdPercent` and overrides
+	 * `reserveTokens`. Typically set as a runtime override by host integrations
+	 * (see `setCompactionThresholdOverride`) and not persisted by users directly.
+	 */
+	thresholdPercent?: number;
 }
 
 export interface BranchSummarySettings {
@@ -812,11 +819,42 @@ export class SettingsManager {
 		return this.settings.compaction?.keepRecentTokens ?? COMPACTION_KEEP_RECENT_TOKENS;
 	}
 
-	getCompactionSettings(): { enabled: boolean; reserveTokens: number; keepRecentTokens: number } {
+	getCompactionThresholdPercent(): number | undefined {
+		return this.settings.compaction?.thresholdPercent;
+	}
+
+	/**
+	 * Set or clear an in-memory compaction threshold-percent override.
+	 *
+	 * Applied to `this.settings` only; never persisted to disk. Pass `undefined`
+	 * to clear a previously set override (necessary for idempotent re-sync from
+	 * host integrations whose preference may have been removed).
+	 *
+	 * Direct mutation is used instead of `applyOverrides()` because deep-merge
+	 * semantics skip `undefined` values, which would prevent clearing.
+	 */
+	setCompactionThresholdOverride(percent: number | undefined): void {
+		if (!this.settings.compaction) {
+			this.settings.compaction = {};
+		}
+		if (percent === undefined) {
+			delete this.settings.compaction.thresholdPercent;
+		} else {
+			this.settings.compaction.thresholdPercent = percent;
+		}
+	}
+
+	getCompactionSettings(): {
+		enabled: boolean;
+		reserveTokens: number;
+		keepRecentTokens: number;
+		thresholdPercent?: number;
+	} {
 		return {
 			enabled: this.getCompactionEnabled(),
 			reserveTokens: this.getCompactionReserveTokens(),
 			keepRecentTokens: this.getCompactionKeepRecentTokens(),
+			thresholdPercent: this.getCompactionThresholdPercent(),
 		};
 	}
 

package/packages/pi-coding-agent/src/core/skill-tool.test.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Tests skill invocation and prompt-only skill visibility behavior.
+
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -86,4 +89,29 @@ describe("Skill tool", () => {
 		assert.match(message, /^Skill "nonexistent" not found\. Available skills: /);
 		assert.match(message, /swift-testing/);
 	});
+
+	it("filters skill catalog without unloading skills or disabling Skill tool", async () => {
+		writeSkill(testDir, "alpha", "Use alpha.");
+		writeSkill(testDir, "beta", "Use beta.");
+		const session = await createSession();
+
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.match(session.systemPrompt, /<name>beta<\/name>/);
+
+		session.setVisibleSkillsByName(["alpha"]);
+		assert.deepEqual(session.getVisibleSkillNames(), ["alpha"]);
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.doesNotMatch(session.systemPrompt, /<name>beta<\/name>/);
+
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should remain active");
+		const result = await tool.execute("call-3", { skill: "beta" });
+		const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+		assert.match(text, /<skill name="beta"/);
+
+		session.setVisibleSkillsByName(undefined);
+		assert.equal(session.getVisibleSkillNames(), undefined);
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.match(session.systemPrompt, /<name>beta<\/name>/);
+	});
 });

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -59,13 +59,12 @@ export interface BuildSystemPromptOptions {
 	 * Append a `Current date and time: <toLocaleString>` line to the system
 	 * prompt. Default: `false`.
 	 *
-	 * Anthropic prompt caching matches on byte-for-byte prefix equality.
-	 * Embedding a per-call timestamp in the system prompt invalidates the
-	 * cache on every request, forcing a full re-write that costs *more*
-	 * than an uncached call (cache-write premium). Most agentic flows do
-	 * not need wall-clock awareness in the system prompt — opt in only
-	 * when the consumer genuinely needs it (e.g. a clock-sensitive agent),
-	 * and inject it via a non-cached channel (user message) when possible.
+	 * Provider prompt caches generally depend on stable prompt prefixes.
+	 * Embedding a per-call timestamp in the system prompt invalidates that
+	 * stability on every request, often forcing full prompt reprocessing.
+	 * Most agentic flows do not need wall-clock awareness in the system
+	 * prompt — opt in only when the consumer genuinely needs it, and inject
+	 * it via a non-cached channel (user message) when possible.
 	 */
 	includeDateTime?: boolean;
 }
@@ -86,9 +85,8 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 	} = options;
 	const resolvedCwd = toPosixPath(cwd ?? process.cwd());
 
-	// Per-call timestamps invalidate Anthropic prompt caching (the cache
-	// matches on byte-for-byte prefix equality). Compute lazily and only
-	// when explicitly opted in via `includeDateTime`.
+	// Per-call timestamps invalidate provider prompt cache stability. Compute
+	// lazily and only when explicitly opted in via `includeDateTime`.
 	const dateTimeLine = includeDateTime
 		? `\nCurrent date and time: ${new Date().toLocaleString("en-US", {
 			weekday: "long",

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,