@oh-my-pi/pi-coding-agent 14.2.0 → 14.3.0

package/src/tools/ast-edit.ts

@@ -294,6 +294,23 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 							failOnParseError: false,
 						});
 						const dedupedApplyParseErrors = dedupeParseErrors(applyResult.parseErrors);
+						const { record: recordAppliedFile, list: appliedFileList } = createFileRecorder();
+						const appliedFileReplacementCounts = new Map<string, number>();
+						for (const fileChange of applyResult.fileChanges) {
+							const relativePath = formatPath(fileChange.path);
+							recordAppliedFile(relativePath);
+							appliedFileReplacementCounts.set(
+								relativePath,
+								(appliedFileReplacementCounts.get(relativePath) ?? 0) + fileChange.count,
+							);
+						}
+						for (const change of applyResult.changes) {
+							recordAppliedFile(formatPath(change.path));
+						}
+						const appliedFileReplacements = appliedFileList.map(filePath => ({
+							path: filePath,
+							count: appliedFileReplacementCounts.get(filePath) ?? 0,
+						}));
 						const appliedDetails: AstEditToolDetails = {
 							totalReplacements: applyResult.totalReplacements,
 							filesTouched: applyResult.filesTouched,
@@ -302,9 +319,27 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 							limitReached: applyResult.limitReached,
 							...(dedupedApplyParseErrors.length > 0 ? { parseErrors: dedupedApplyParseErrors } : {}),
 							scopePath,
-							files: fileList,
-							fileReplacements,
+							files: appliedFileList,
+							fileReplacements: appliedFileReplacements,
 						};
+						const stalePreview =
+							applyResult.totalReplacements !== result.totalReplacements ||
+							applyResult.filesTouched !== result.filesTouched ||
+							fileList.some(
+								filePath => appliedFileReplacementCounts.get(filePath) !== fileReplacementCounts.get(filePath),
+							) ||
+							appliedFileList.some(
+								filePath => fileReplacementCounts.get(filePath) !== appliedFileReplacementCounts.get(filePath),
+							);
+						if (stalePreview) {
+							const text =
+								applyResult.totalReplacements === 0
+									? `Preview is stale / no longer matches; no replacements were applied. Preview expected ${result.totalReplacements} replacement${previewReplacementPlural} in ${result.filesTouched} file${previewFilePlural}.`
+									: applyResult.totalReplacements < result.totalReplacements
+										? `Preview is stale / no longer matches; only ${applyResult.totalReplacements} of ${result.totalReplacements} replacements were applied in ${applyResult.filesTouched} of ${result.filesTouched} files.`
+										: `Preview is stale / no longer matches; applied ${applyResult.totalReplacements} replacements but preview expected ${result.totalReplacements}.`;
+							return { ...toolResult(appliedDetails).text(text).done(), isError: true };
+						}
 						const appliedReplacementPlural = applyResult.totalReplacements !== 1 ? "s" : "";
 						const appliedFilePlural = applyResult.filesTouched !== 1 ? "s" : "";
 						const text = `Applied ${applyResult.totalReplacements} replacement${appliedReplacementPlural} in ${applyResult.filesTouched} file${appliedFilePlural}.`;

package/src/tools/bash.ts

@@ -23,13 +23,24 @@ import { resolveToCwd } from "./path-utils";
 import { formatToolWorkingDirectory, replaceTabs } from "./render-utils";
 import { ToolAbortError, ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
-import { clampTimeout } from "./tool-timeouts";
+import { clampTimeout, TOOL_TIMEOUTS } from "./tool-timeouts";
 
 export const BASH_DEFAULT_PREVIEW_LINES = 10;
 
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
 
+async function saveBashOriginalArtifact(session: ToolSession, originalText: string): Promise<string | undefined> {
+	try {
+		const alloc = await session.allocateOutputArtifact?.("bash-original");
+		if (!alloc?.path || !alloc.id) return undefined;
+		await Bun.write(alloc.path, originalText);
+		return alloc.id;
+	} catch {
+		return undefined;
+	}
+}
+
 const bashSchemaBase = Type.Object({
 	command: Type.String({ description: "Command to execute" }),
 	env: Type.Optional(
@@ -74,6 +85,7 @@ export interface BashToolInput {
 export interface BashToolDetails {
 	meta?: OutputMeta;
 	timeoutSeconds?: number;
+	requestedTimeoutSeconds?: number;
 	async?: {
 		state: "running" | "completed" | "failed";
 		jobId: string;
@@ -219,6 +231,13 @@ function getBashEnvForDisplay(args: BashRenderArgs): Record<string, string> | un
 	if (partialEnv && args.env) return { ...partialEnv, ...args.env };
 	return args.env ?? partialEnv;
 }
+
+function formatTimeoutClampNotice(requestedTimeoutSec: number, effectiveTimeoutSec: number): string | undefined {
+	return requestedTimeoutSec !== effectiveTimeoutSec
+		? `Timeout clamped to ${effectiveTimeoutSec}s (requested ${requestedTimeoutSec}s; allowed range ${TOOL_TIMEOUTS.bash.min}-${TOOL_TIMEOUTS.bash.max}s).`
+		: undefined;
+}
+
 /**
  * Bash tool implementation.
  *
@@ -289,9 +308,16 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		timeoutSec: number,
 		headLines?: number,
 		tailLines?: number,
+		options: { requestedTimeoutSec?: number; notices?: string[] } = {},
 	): AgentToolResult<BashToolDetails> {
-		const outputText = this.#formatResultOutput(result, headLines, tailLines);
+		const outputLines = [this.#formatResultOutput(result, headLines, tailLines)];
+		const notices = options.notices?.filter(Boolean) ?? [];
+		if (notices.length > 0) outputLines.push("", ...notices);
+		const outputText = outputLines.join("\n");
 		const details: BashToolDetails = { timeoutSeconds: timeoutSec };
+		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
+			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
+		}
 		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
 		this.#buildResultText(result, timeoutSec, outputText);
 		return resultBuilder.done();
@@ -302,16 +328,23 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		label: string,
 		previewText: string,
 		timeoutSec: number,
+		options: { requestedTimeoutSec?: number; notices?: string[] } = {},
 	): AgentToolResult<BashToolDetails> {
 		const details: BashToolDetails = {
 			timeoutSeconds: timeoutSec,
 			async: { state: "running", jobId, type: "bash" },
 		};
+		if (options.requestedTimeoutSec !== undefined && options.requestedTimeoutSec !== timeoutSec) {
+			details.requestedTimeoutSeconds = options.requestedTimeoutSec;
+		}
 		const lines: string[] = [];
 		const trimmedPreview = previewText.trimEnd();
 		if (trimmedPreview.length > 0) {
 			lines.push(trimmedPreview, "");
 		}
+		if (options.notices?.length) {
+			lines.push(...options.notices, "");
+		}
 		lines.push(`Background job ${jobId} started: ${label}`);
 		lines.push("Result will be delivered automatically when complete.");
 		lines.push(`Use \`poll\`, \`read jobs://${jobId}\`, or \`cancel_job\` if needed.`);
@@ -330,6 +363,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		commandCwd: string;
 		timeoutMs: number;
 		timeoutSec: number;
+		requestedTimeoutSec?: number;
+		timeoutClampNotice?: string;
 		headLines?: number;
 		tailLines?: number;
 		resolvedEnv?: Record<string, string>;
@@ -366,12 +401,17 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 							latestText = tailBuffer.text();
 							void reportProgress(latestText, { async: { state: "running", jobId, type: "bash" } });
 						},
+						onMinimizedSave: originalText => saveBashOriginalArtifact(this.session, originalText),
 					});
 					const finalResult = this.#buildCompletedResult(
 						result,
 						options.timeoutSec,
 						options.headLines,
 						options.tailLines,
+						{
+							requestedTimeoutSec: options.requestedTimeoutSec,
+							notices: [options.timeoutClampNotice].filter((notice): notice is string => Boolean(notice)),
+						},
 					);
 					const finalText = this.#extractTextResult(finalResult);
 					latestText = finalText;
@@ -531,8 +571,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		}
 
 		// Clamp to reasonable range: 1s - 3600s (1 hour)
-		const timeoutSec = clampTimeout("bash", rawTimeout);
+		const requestedTimeoutSec = rawTimeout;
+		const timeoutSec = clampTimeout("bash", requestedTimeoutSec);
 		const timeoutMs = timeoutSec * 1000;
+		const timeoutClampNotice = formatTimeoutClampNotice(requestedTimeoutSec, timeoutSec);
 
 		if (asyncRequested) {
 			if (!this.session.asyncJobManager) {
@@ -543,13 +585,18 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				commandCwd,
 				timeoutMs,
 				timeoutSec,
+				requestedTimeoutSec,
+				timeoutClampNotice,
 				headLines,
 				tailLines,
 				resolvedEnv,
 				onUpdate,
 				startBackgrounded: true,
 			});
-			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec);
+			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
+				requestedTimeoutSec,
+				notices: [timeoutClampNotice].filter((notice): notice is string => Boolean(notice)),
+			});
 		}
 
 		if (this.#autoBackgroundEnabled && !pty && this.session.asyncJobManager) {
@@ -560,6 +607,8 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				commandCwd,
 				timeoutMs,
 				timeoutSec,
+				requestedTimeoutSec,
+				timeoutClampNotice,
 				headLines,
 				tailLines,
 				resolvedEnv,
@@ -567,7 +616,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				startBackgrounded,
 			});
 			if (startBackgrounded) {
-				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec);
+				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
+					requestedTimeoutSec,
+					notices: [timeoutClampNotice].filter((notice): notice is string => Boolean(notice)),
+				});
 			}
 			const waitResult = await this.#waitForManagedBashJob(job, autoBackgroundWaitMs, signal);
 			if (waitResult.kind === "completed") {
@@ -584,7 +636,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 				throw new ToolAbortError(job.getLatestText() || "Command aborted");
 			}
 			job.setBackgrounded(true);
-			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec);
+			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec, {
+				requestedTimeoutSec,
+				notices: [timeoutClampNotice].filter((notice): notice is string => Boolean(notice)),
+			});
 		}
 
 		// Track output for streaming updates (tail only)
@@ -613,6 +668,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					artifactPath,
 					artifactId,
 					onChunk: streamTailUpdates(tailBuffer, onUpdate),
+					onMinimizedSave: originalText => saveBashOriginalArtifact(this.session, originalText),
 				});
 		if (result.cancelled) {
 			if (signal?.aborted) {
@@ -623,7 +679,10 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		if (isInteractiveResult(result) && result.timedOut) {
 			throw new ToolError(normalizeResultOutput(result) || `Command timed out after ${timeoutSec} seconds`);
 		}
-		return this.#buildCompletedResult(result, timeoutSec, headLines, tailLines);
+		return this.#buildCompletedResult(result, timeoutSec, headLines, tailLines, {
+			requestedTimeoutSec,
+			notices: [timeoutClampNotice].filter((notice): notice is string => Boolean(notice)),
+		});
 	}
 }
 
@@ -700,12 +759,16 @@ export const bashToolRenderer = {
 
 				// Build truncation warning
 				const timeoutSeconds = details?.timeoutSeconds ?? renderContext?.timeout;
-				const timeoutLine =
+				const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
+				const timeoutLabel =
 					typeof timeoutSeconds === "number"
-						? uiTheme.fg(
-								"dim",
-								`${uiTheme.format.bracketLeft}Timeout: ${timeoutSeconds}s${uiTheme.format.bracketRight}`,
-							)
+						? requestedTimeoutSeconds !== undefined && requestedTimeoutSeconds !== timeoutSeconds
+							? `Timeout: ${timeoutSeconds}s (requested ${requestedTimeoutSeconds}s clamped)`
+							: `Timeout: ${timeoutSeconds}s`
+						: undefined;
+				const timeoutLine =
+					timeoutLabel !== undefined
+						? uiTheme.fg("dim", `${uiTheme.format.bracketLeft}${timeoutLabel}${uiTheme.format.bracketRight}`)
 						: undefined;
 				let warningLine: string | undefined;
 				if (details?.meta?.truncation && !showingFullOutput) {

package/src/tools/find.ts

@@ -129,6 +129,19 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 			const includeHidden = hidden ?? true;
 			const timeoutSignal = AbortSignal.timeout(GLOB_TIMEOUT_MS);
 			const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+			const formatMatchPath = (matchPath: string, fileType?: natives.FileType): string => {
+				const hadTrailingSlash = matchPath.endsWith("/") || matchPath.endsWith("\\");
+				const absolutePath = path.isAbsolute(matchPath) ? matchPath : path.resolve(searchPath, matchPath);
+				let relativePath = path.relative(this.session.cwd, absolutePath).replace(/\\/g, "/");
+				if (relativePath.length === 0) {
+					relativePath = ".";
+				}
+				if ((fileType === natives.FileType.Dir || hadTrailingSlash) && !relativePath.endsWith("/")) {
+					relativePath += "/";
+				}
+				return relativePath;
+			};
+
 			const buildResult = (files: string[]): AgentToolResult<FindToolDetails> => {
 				if (files.length === 0) {
 					const details: FindToolDetails = { scopePath, fileCount: 0, files: [], truncated: false };
@@ -176,12 +189,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 					ignore: ["**/node_modules/**", "**/.git/**"],
 					limit: effectiveLimit,
 				});
-				const relativized = results.map(p => {
-					if (p.startsWith(searchPath)) {
-						return p.slice(searchPath.length + 1);
-					}
-					return path.relative(searchPath, p);
-				});
+				const relativized = results.map(p => formatMatchPath(p));
 
 				return buildResult(relativized);
 			}
@@ -225,12 +233,8 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 			};
 			const onMatch = onUpdate
 				? (err: Error | null, match: natives.GlobMatch | null) => {
-						if (err || signal?.aborted || !match) return;
-						let relativePath = match.path;
-						if (!relativePath) return;
-						if (match.fileType === natives.FileType.Dir && !relativePath.endsWith("/")) {
-							relativePath += "/";
-						}
+						if (err || signal?.aborted || !match?.path) return;
+						const relativePath = formatMatchPath(match.path, match.fileType);
 						onUpdateMatches.push(relativePath);
 						emitUpdate();
 					}
@@ -254,10 +258,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				);
 
 			try {
-				let result = await doGlob(true);
-				if (result.matches.length === 0 && !timeoutSignal.aborted) {
-					result = await doGlob(false);
-				}
+				const result = await doGlob(true);
 				// Sort by mtime descending (most recent first) in JS instead of native.
 				// This allows native glob to early-terminate at maxResults.
 				result.matches.sort((a, b) => (b.mtime ?? 0) - (a.mtime ?? 0));
@@ -276,19 +277,11 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 			const relativized: string[] = [];
 			for (const match of matches) {
 				throwIfAborted(signal);
-				const line = match.path;
-				if (!line) {
+				if (!match.path) {
 					continue;
 				}
 
-				const hadTrailingSlash = line.endsWith("/") || line.endsWith("\\");
-				let relativePath = line;
-				const isDirectory = match.fileType === natives.FileType.Dir;
-				if ((isDirectory || hadTrailingSlash) && !relativePath.endsWith("/")) {
-					relativePath += "/";
-				}
-
-				relativized.push(relativePath);
+				relativized.push(formatMatchPath(match.path, match.fileType));
 			}
 
 			return buildResult(relativized);

package/src/tools/gh.ts

@@ -611,14 +611,6 @@ function toLocalBranchRef(value: string): string {
 	return `refs/heads/${value}`;
 }
 
-function stripHeadsRef(value: string | undefined): string | undefined {
-	if (!value) {
-		return undefined;
-	}
-
-	return value.startsWith("refs/heads/") ? value.slice("refs/heads/".length) : value;
-}
-
 async function requireGitRepoRoot(cwd: string, signal?: AbortSignal): Promise<string> {
 	const repoRoot = await git.repo.root(cwd, signal);
 	if (!repoRoot) {
@@ -763,10 +755,13 @@ async function resolvePrBranchPushTarget(
 	maintainerCanModify?: boolean;
 	isCrossRepository: boolean;
 }> {
+	const headRef = await git.config.getBranch(repoRoot, localBranch, "ompPrHeadRef", signal);
+	if (!headRef) {
+		throw new ToolError(`branch ${localBranch} has no PR push metadata; check it out via gh_pr_checkout first`);
+	}
+
 	const pushRemote = await git.config.getBranch(repoRoot, localBranch, "pushRemote", signal);
 	const remote = await git.config.getBranch(repoRoot, localBranch, "remote", signal);
-	const mergeRef = await git.config.getBranch(repoRoot, localBranch, "merge", signal);
-	const headRef = await git.config.getBranch(repoRoot, localBranch, "ompPrHeadRef", signal);
 	const prUrl = await git.config.getBranch(repoRoot, localBranch, "ompPrUrl", signal);
 	const maintainerCanModifyValue = await git.config.getBranch(
 		repoRoot,
@@ -781,14 +776,9 @@ async function resolvePrBranchPushTarget(
 		throw new ToolError(`branch ${localBranch} has no configured push remote`);
 	}
 
-	const remoteBranch = headRef ?? stripHeadsRef(mergeRef);
-	if (!remoteBranch) {
-		throw new ToolError(`branch ${localBranch} has no tracked PR head ref`);
-	}
-
 	return {
 		remoteName,
-		remoteBranch,
+		remoteBranch: headRef,
 		remoteUrl: await git.remote.url(repoRoot, remoteName, signal),
 		prUrl,
 		maintainerCanModify:

package/src/tools/grep.ts

@@ -124,6 +124,7 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 			};
 			let searchPath: string;
 			let scopePath: string;
+			let exactFilePaths: string[] | undefined;
 			let globFilter = glob ? normalizePathLikeInput(glob) || undefined : undefined;
 			const internalRouter = this.session.internalRouter;
 			if (searchDir?.trim()) {
@@ -142,7 +143,8 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 					const multiSearchPath = await resolveMultiSearchPath(rawPath, this.session.cwd, globFilter);
 					if (multiSearchPath) {
 						searchPath = multiSearchPath.basePath;
-						globFilter = multiSearchPath.glob;
+						globFilter = multiSearchPath.exactFilePaths ? undefined : multiSearchPath.glob;
+						exactFilePaths = multiSearchPath.exactFilePaths;
 						scopePath = multiSearchPath.scopePath;
 					} else {
 						const parsedPath = parseSearchPath(rawPath);
@@ -174,26 +176,61 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 			// Run grep
 			let result: GrepResult;
 			try {
-				result = await grep(
-					{
-						pattern: normalizedPattern,
-						path: searchPath,
-						glob: globFilter,
-						type: type?.trim() || undefined,
-						ignoreCase,
-						multiline: effectiveMultiline,
-						hidden: true,
-						gitignore: useGitignore,
-						cache: false,
-						maxCount: internalLimit,
-						offset: normalizedOffset > 0 ? normalizedOffset : undefined,
-						contextBefore: normalizedContextBefore,
-						contextAfter: normalizedContextAfter,
-						maxColumns: DEFAULT_MAX_COLUMN,
-						mode: effectiveOutputMode,
-					},
-					undefined,
-				);
+				if (exactFilePaths) {
+					const matches: GrepMatch[] = [];
+					let limitReached = false;
+					for (const exactFilePath of exactFilePaths) {
+						const fileResult = await grep(
+							{
+								pattern: normalizedPattern,
+								path: exactFilePath,
+								type: type?.trim() || undefined,
+								ignoreCase,
+								multiline: effectiveMultiline,
+								hidden: true,
+								gitignore: useGitignore,
+								cache: false,
+								contextBefore: normalizedContextBefore,
+								contextAfter: normalizedContextAfter,
+								maxColumns: DEFAULT_MAX_COLUMN,
+								mode: effectiveOutputMode,
+							},
+							undefined,
+						);
+						limitReached = limitReached || Boolean(fileResult.limitReached);
+						const relativeFilePath = path.relative(searchPath, exactFilePath).replace(/\\/g, "/");
+						matches.push(...fileResult.matches.map(match => ({ ...match, path: relativeFilePath })));
+					}
+					const offsetMatches = matches.slice(normalizedOffset);
+					result = {
+						matches: offsetMatches,
+						totalMatches: offsetMatches.length,
+						filesWithMatches: new Set(offsetMatches.map(match => match.path)).size,
+						filesSearched: exactFilePaths.length,
+						limitReached,
+					};
+				} else {
+					result = await grep(
+						{
+							pattern: normalizedPattern,
+							path: searchPath,
+							glob: globFilter,
+							type: type?.trim() || undefined,
+							ignoreCase,
+							multiline: effectiveMultiline,
+							hidden: true,
+							gitignore: useGitignore,
+							cache: false,
+							maxCount: internalLimit,
+							offset: normalizedOffset > 0 ? normalizedOffset : undefined,
+							contextBefore: normalizedContextBefore,
+							contextAfter: normalizedContextAfter,
+							maxColumns: DEFAULT_MAX_COLUMN,
+							mode: effectiveOutputMode,
+						},
+						undefined,
+					);
+				}
 			} catch (err) {
 				if (err instanceof Error && err.message.startsWith("regex parse error")) {
 					throw new ToolError(err.message);
@@ -258,6 +295,7 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 			}
 			const outputLines: string[] = [];
 			let linesTruncated = false;
+			const hasContextLines = normalizedContextBefore > 0 || normalizedContextAfter > 0;
 			const matchesByFile = new Map<string, GrepMatch[]>();
 			for (const match of selectedMatches) {
 				const relativePath = formatPath(match.path);
@@ -289,10 +327,11 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 					}
 					chunkMatchesByFile.get(match.displayPath)!.push(match);
 				}
-				const renderChunkedMatchesForFile = (relativePath: string) => {
+				const renderChunkedMatchesForFile = (relativePath: string): string[] => {
+					const renderedLines: string[] = [];
 					const fileMatches = chunkMatchesByFile.get(relativePath) ?? [];
 					if (fileMatches.length === 0) {
-						return;
+						return renderedLines;
 					}
 					const lineWidth = fileMatches[0]?.fileLineCount.toString().length ?? 1;
 					const matchesByChunk = new Map<string, ChunkedGrepMatch[]>();
@@ -310,13 +349,14 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 							const anchor = chunkChecksum
 								? `${dashes}@${chunkPath}#${chunkChecksum}`
 								: `${dashes}@${chunkPath}`;
-							outputLines.push(anchor);
+							renderedLines.push(anchor);
 						}
 						for (const match of chunkMatches) {
-							outputLines.push(`    ${match.lineNumber.toString().padStart(lineWidth, " ")} |${match.line}`);
+							renderedLines.push(`    ${match.lineNumber.toString().padStart(lineWidth, " ")} |${match.line}`);
 							fileMatchCounts.set(relativePath, (fileMatchCounts.get(relativePath) ?? 0) + 1);
 						}
 					}
+					return renderedLines;
 				};
 				if (isDirectory) {
 					const filesByDirectory = new Map<string, string[]>();
@@ -330,26 +370,32 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 					for (const [directory, directoryFiles] of filesByDirectory) {
 						if (directory === ".") {
 							for (const relativePath of directoryFiles) {
+								const renderedLines = renderChunkedMatchesForFile(relativePath);
+								if (renderedLines.length === 0) continue;
 								if (outputLines.length > 0) {
 									outputLines.push("");
 								}
 								outputLines.push(`# ${path.basename(relativePath)}`);
-								renderChunkedMatchesForFile(relativePath);
+								outputLines.push(...renderedLines);
 							}
 							continue;
 						}
+						const renderedFiles = directoryFiles
+							.map(relativePath => ({ relativePath, lines: renderChunkedMatchesForFile(relativePath) }))
+							.filter(file => file.lines.length > 0);
+						if (renderedFiles.length === 0) continue;
 						if (outputLines.length > 0) {
 							outputLines.push("");
 						}
 						outputLines.push(`# ${directory}`);
-						for (const relativePath of directoryFiles) {
+						for (const { relativePath, lines } of renderedFiles) {
 							outputLines.push(`## └─ ${path.basename(relativePath)}`);
-							renderChunkedMatchesForFile(relativePath);
+							outputLines.push(...lines);
 						}
 					}
 				} else {
 					for (const relativePath of fileList) {
-						renderChunkedMatchesForFile(relativePath);
+						outputLines.push(...renderChunkedMatchesForFile(relativePath));
 					}
 				}
 				const rawOutput = outputLines.join("\n");
@@ -380,7 +426,8 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 				}
 				return resultBuilder.done();
 			}
-			const renderMatchesForFile = (relativePath: string) => {
+			const renderMatchesForFile = (relativePath: string): string[] => {
+				const renderedLines: string[] = [];
 				const fileMatches = matchesByFile.get(relativePath) ?? [];
 				for (const match of fileMatches) {
 					const lineNumbers: number[] = [match.lineNumber];
@@ -399,20 +446,21 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 						formatMatchLine(lineNumber, line, isMatch, { useHashLines, lineWidth });
 					if (match.contextBefore) {
 						for (const ctx of match.contextBefore) {
-							outputLines.push(formatLine(ctx.lineNumber, ctx.line, false));
+							renderedLines.push(formatLine(ctx.lineNumber, ctx.line, false));
 						}
 					}
-					outputLines.push(formatLine(match.lineNumber, match.line, true));
+					renderedLines.push(formatLine(match.lineNumber, match.line, true));
 					if (match.truncated) {
 						linesTruncated = true;
 					}
 					if (match.contextAfter) {
 						for (const ctx of match.contextAfter) {
-							outputLines.push(formatLine(ctx.lineNumber, ctx.line, false));
+							renderedLines.push(formatLine(ctx.lineNumber, ctx.line, false));
 						}
 					}
 					fileMatchCounts.set(relativePath, (fileMatchCounts.get(relativePath) ?? 0) + 1);
 				}
+				return renderedLines;
 			};
 			if (isDirectory) {
 				const filesByDirectory = new Map<string, string[]>();
@@ -426,28 +474,37 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 				for (const [directory, directoryFiles] of filesByDirectory) {
 					if (directory === ".") {
 						for (const relativePath of directoryFiles) {
+							const renderedLines = renderMatchesForFile(relativePath);
+							if (renderedLines.length === 0) continue;
 							if (outputLines.length > 0) {
 								outputLines.push("");
 							}
 							outputLines.push(`# ${path.basename(relativePath)}`);
-							renderMatchesForFile(relativePath);
+							outputLines.push(...renderedLines);
 						}
 						continue;
 					}
+					const renderedFiles = directoryFiles
+						.map(relativePath => ({ relativePath, lines: renderMatchesForFile(relativePath) }))
+						.filter(file => file.lines.length > 0);
+					if (renderedFiles.length === 0) continue;
 					if (outputLines.length > 0) {
 						outputLines.push("");
 					}
 					outputLines.push(`# ${directory}`);
-					for (const relativePath of directoryFiles) {
+					for (const { relativePath, lines } of renderedFiles) {
 						outputLines.push(`## └─ ${path.basename(relativePath)}`);
-						renderMatchesForFile(relativePath);
+						outputLines.push(...lines);
 					}
 				}
 			} else {
 				for (const relativePath of fileList) {
-					renderMatchesForFile(relativePath);
+					outputLines.push(...renderMatchesForFile(relativePath));
 				}
 			}
+			if (hasContextLines && outputLines.length > 0) {
+				outputLines.unshift("[grep] match lines use ':'; context lines use '-'.");
+			}
 			const rawOutput = outputLines.join("\n");
 			const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 			const output = truncation.content;