@oh-my-pi/pi-coding-agent 14.5.2 → 14.5.3

package/src/prompts/tools/atom.md

@@ -1,103 +1,76 @@
-Applies precise file edits using full anchors from `read` output (for example `160sr`).
-
-Read the file first. Copy the full anchors exactly as shown by `read`.
-
-<operations>
-**Top level**: `{ path, edits: […] }` — `path` is shared by all entries. You may still override the file inside `loc` with forms like `other.ts:160sr`.
-
-Each entry has one shared locator plus one or more verbs:
-- `loc: "160sr"` — single anchored line
-- `loc: "$"` — whole file: `pre` prepends, `post` appends, `sed` substitutes across every line
-- `loc: "a.ts:160sr"` — cross-file override inside the locator
-
-Verbs:
-- `splice: […]`: lines are spliced in at the anchor.
-- `pre: […]`: prepend before the anchor (or at BOF if `loc=$`)
-- `post: […]`: append after the anchor (or at EOF if `loc=$`)
-- `sed: { pat, rep, g?, F? }` — structured find/replace on the anchor line. **Prefer this over `splice` for token-level changes**
-  - `pat`: pattern to find (regex by default)
-  - `rep`: replacement (regex back-refs like `$1`, `$&` available)
-  - `g`: global — replace every occurrence (default `false`; pass `true` to replace all)
-  - `F`: literal — treat `pat` as a literal substring (no regex). Use this whenever `pat` contains `||`, `.`, `(`, `?`, `\`, etc. you mean literally.
-You **MUST** keep `pat` as short as possible.
-
-Combination rules:
-- On a single-anchor `loc`, you may combine `pre`, `splice`, and `post` in the same entry.
-- `splice: []` on a single-anchor `loc` deletes that line.
-- `splice:[""]` is **not** delete — it replaces the line with a blank line.
-</operations>
+Applies precise file edits using anchors (line+hash).
+
+<ops>
+Each call **MUST** have shape `{path:"a.ts",edits:[…]}`. `path` is the default file; you **MAY** override it per edit with `loc:"b.ts:160sr"`.
+Each edit **MUST** have exactly one `loc` and **MUST** include one or more verbs.
+
+# Locators
+- `"A"` targets one anchored line. `"$"` targets the whole file: `pre` = BOF, `post` = EOF, `sed` = every line.
+- Bracketed locators are **`splice` only** and select a balanced region around anchor `A`.
+- `"(A)"` = block body. `"[A]"` = whole block/node.
+- `"[A"` / `"(A"` = tail after/including anchor, closer excluded.
+- `"A]"` / `"A)"` = head through/before anchor, opener excluded.
+- Anchor bracketed forms on a body line of the intended block, not the opener line.
+- Do not use bracketed locators on files that do not currently parse.
+
+# Verbs
+- `splice:[…]` replaces the anchored line, or the bracketed region. `[]` deletes; `[""]` makes a blank line.
+- `pre:[…]` inserts before the anchor, or BOF with `loc:"$"`.
+- `post:[…]` inserts after the anchor, or EOF with `loc:"$"`.
+</ops>
+
+<splice>
+Replaces the anchored line, or the bracketed region.
+- `[]` deletes. `[""]` leaves a blank line.
+- For bracketed `splice`, write body at column 0, it will be re-indented.
+- Do not use bracketed `splice` on broken files, or for single line edits.
+</splice>
+
+<sed>
+Use for tiny inline edits: names, operators, literals.
+- Keep `pat` as short as possible, it does not have to be unique.
+- `g:false` by default; set to replace all instead of first.
+</sed>
 
 <examples>
-All examples below reference the same file:
-
 ```ts title="a.ts"
-{{hline 1 "const tag = \"BAD\";"}}
+{{hline 1 "const FALLBACK = \"guest\";"}}
 {{hline 2 ""}}
-{{hline 3 "function beta(x) {"}}
-{{hline 4 "\tif (x) {"}}
-{{hline 5 "\t\treturn parse(data) || fallback;"}}
-{{hline 6 "\t}"}}
-{{hline 7 "\treturn null;"}}
-{{hline 8 "}"}}
+{{hline 3 "export function label(name) {"}}
+{{hline 4 "\tconst clean = name || FALLBACK;"}}
+{{hline 5 "\treturn clean.trim().toLowerCase();"}}
+{{hline 6 "}"}}
 ```
 
-# Replace a line with `splice`
-`{path:"a.ts",edits:[{loc:{{href 1 "const tag = \"BAD\";"}},splice:["const tag = \"OK\";"]}]}`
-
-# Combine `pre` + `splice` + `post` in one entry
-`{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},pre:["\tvalidate();"],splice:["\tif (!x) {"],post:["\t\tlog();"]}]}`
-
-# Delete a line with `splice: []`
-`{path:"a.ts",edits:[{loc:{{href 7 "\treturn null;"}},splice:[]}]}`
-
-# Preserve a blank line with `splice:[""]`
+# Single-line replacement:
+`{path:"a.ts",edits:[{loc:{{href 1 "const FALLBACK = \"guest\";"}},splice:["const FALLBACK = \"anonymous\";"]}]}`
+# Small token edit: prefer `sed`:
+`{path:"a.ts",edits:[{loc:{{href 5 "\treturn clean.trim().toLowerCase();"}},sed:{pat:"toLowerCase",rep:"toUpperCase"}}]}`
+# Insert before / after an anchor:
+`{path:"a.ts",edits:[{loc:{{href 5 "\treturn clean.trim().toLowerCase();"}},pre:["\tif (!clean) return FALLBACK;"],post:["\t// normalized label"]}]}`
+# Delete a line vs make it blank:
+`{path:"a.ts",edits:[{loc:{{href 2 ""}},splice:[]}]}`
 `{path:"a.ts",edits:[{loc:{{href 2 ""}},splice:[""]}]}`
-
-# Insert before / after a line
-`{path:"a.ts",edits:[{loc:{{href 3 "function beta(x) {"}},pre:["function gamma() {","\tvalidate();","}",""]}]}`
-
-# Substitute one token with `sed` (regex) — preferred for token-level edits
-Use the smallest `pat` that uniquely identifies the change.
-`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:{pat:"\\|\\|",rep:"??"}}]}`
-
-# Substitute literal text — set `F:true` so `pat` is not parsed as regex
-`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:{pat:"data",rep:"input",F:true}}]}`
-
-# Comment out a line by capturing the whole content with a regex
-Use `$&` (the entire match) inside `rep` to keep the original text and prepend `// `.
-`{path:"a.ts",edits:[{loc:{{href 7 "\treturn null;"}},sed:{pat:".+",rep:"// $&"}}]}`
-
-# Prepend / append at file edges
+# File edges:
 `{path:"a.ts",edits:[{loc:"$",pre:["// Copyright (c) 2026",""]}]}`
-`{path:"a.ts",edits:[{loc:"$",post:["","export const VERSION = \"1.0.0\";"]}]}`
-
-# Cross-file override inside `loc`
-`{path:"a.ts",edits:[{loc:"b.ts:{{href 1 "const tag = \"BAD\";"}}",splice:["const tag = \"OK\";"]}]}`
-
-# WRONG: retyping unchanged neighbors inside `splice` duplicates them
-`{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},splice:["\tif (x && ready) {","\t\treturn parse(data) ?? fallback;","\t\t//unreachable"]}]}`
-The 2nd array element matches existing line 5, which is **not** overwritten, it shifts, so return statement ends up duplicated.
-
-# RIGHT: split into separate edits
-- `{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},sed:{pat:"x",rep:"x && ready",g:false}},{loc:{{href 5 "\t\treturn parse(data) ?? fallback;"}},post:["\t\t//unreachable"]}]}`
-OR
-- `{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},splice:["\tif (x && ready) {"]},{loc:{{href 5 "\t\treturn parse(data) ?? fallback;"}},splice:["\t\treturn parse(data) ?? fallback;","\t\t//unreachable"]}]}`
+`{path:"a.ts",edits:[{loc:"$",post:["","export { FALLBACK };"]}]}`
+# Cross-file override:
+`{path:"a.ts",edits:[{loc:{{href 1 "const FALLBACK = \"guest\";" "config.ts:" ""}},splice:["const FALLBACK = \"anonymous\";"]}]}`
+# Body replacement: use bracketed `splice`, write body at column 0:
+`{path:"a.ts",edits:[{loc:{{href 4 "\tconst clean = name || FALLBACK;" "(" ")"}},splice:["if (name == null) return FALLBACK;","const clean = String(name).trim();","return clean || FALLBACK;"]}]}`
+# Whole function replacement: anchor on a body line:
+`{path:"a.ts",edits:[{loc:{{href 5 "\treturn clean.trim().toLowerCase();" "[" "]"}},splice:["export function label(name) {","\treturn String(name ?? FALLBACK).trim().toLowerCase();","}"]}]}`
+# WRONG: bare-anchor `splice` does not own neighboring lines:
+`{path:"a.ts",edits:[{loc:{{href 4 "\tconst clean = name || FALLBACK;"}},splice:["\tconst clean = String(name ?? FALLBACK).trim();","\treturn clean.toLowerCase();"]}]}`
+This replaces only line 4. Original line 5 still shifts down, so the function now has two returns.
+# RIGHT: use a body edit for that rewrite:
+`{path:"a.ts",edits:[{loc:{{href 4 "\tconst clean = name || FALLBACK;" "(" ")"}},splice:["const clean = String(name ?? FALLBACK).trim();","return clean.toLowerCase();"]}]}`
 </examples>
 
 <critical>
-- Make the minimum exact edit.
-- Copy the full anchors exactly as shown by `read/grep` (for example `160sr`, not just `sr`).
-- `loc` chooses the target. Verbs describe what to do there.
-- On a single-anchor `loc`, you may combine `pre`, `splice`, and `post`.
-- `loc:"$"` operates on the whole file: `pre` prepends, `post` appends, `sed` runs across every line.
-- `splice: []` deletes the anchored line. `splice:[""]` preserves a blank line.
-- Within a single request you may submit edits in any order — the runtime applies them bottom-up so they don't shift each other. After any request that mutates a file, anchors below the mutation are stale on disk; re-read before issuing more edits to that file.
-- `splice` operations target the current file content only. Do not try to reference old line text after the file has changed.
-- For **small** in-line edits (renaming a token, flipping an operator, tweaking a literal), prefer `sed` over `splice`. The `loc` anchor already pins the line — repeating the entire line in a `splice` array invites hallucinated content. Use the smallest `pat` that uniquely identifies the change on that line; do not pad it with surrounding text just to feel safe. When `pat` contains regex metacharacters you mean literally (e.g. `||`, `.`, `(`, `?`, `\`), set `F:true` to disable regex. `g` is `false` by default — pass `g:true` to replace every occurrence. For multi-line restructuring (wrapping logic, adding new branches, inserting blocks), use `splice`/`pre`/`post` — do **not** stretch `sed` into a rewrite tool.
-- When you do use `splice`, re-read the anchored line first and copy it verbatim, changing only the required token(s). Anchor identity does not verify line content, so a hallucinated replacement will silently corrupt the file.
-- Anchors are pin points, not region markers. One anchor pins exactly one line. If your change touches N distinct source lines, that is N edits with N anchors — not one big `splice` array intended to cover the whole region. `splice` cannot "replace lines 4 through 7"; it can only splice content in at one anchor.
-- You **MUST NOT** include lines in `splice`/`pre`/`post` that already exist immediately adjacent to the anchor in the current file. `splice` does not overwrite the lines below — they shift down — so any neighbor you re-type in your array becomes a duplicate. If your intended replacement contains content that is already on neighboring source lines, split into multiple edits at each real change site instead of one fat `splice`.
-- Before issuing a multi-line `splice`, mentally diff each array element against the current file lines at and just below the anchor. Any element that matches a line within ~5 lines of the anchor will become a duplicate after the splice. If you find a match, drop that element and use a separate edit (or `pre`/`post`) at the real change point.
-- Text content must be literal file content with matching indentation. If the file uses tabs, use real tabs.
-- You **MUST NOT** use this tool to reformat or clean up unrelated code.
+- You **MUST** copy full anchors exactly from a read op (e.g. `160sr`); you **MUST NOT** send only the 2-letter suffix.
+- You **MUST** make the minimum exact edit; you **MUST NOT** reformat unrelated code.
+- A bare anchor **MUST** target one line only; you **MUST** use bracketed `splice` for balanced block rewrites.
+- You **MUST NOT** include unchanged adjacent lines in `splice`/`pre`/`post`; they shift and duplicate.
+- For bracketed `splice`, replacement braces **MUST** be balanced for the selected region.
 </critical>

package/src/prompts/tools/read.md

@@ -23,7 +23,7 @@ The `read` tool is multi-purpose and more capable than it looks — inspects fil
 # Filesystem
 - Reading a directory path returns a list of dirents.
 {{#if IS_HASHLINE_MODE}}
-- Reading a file returns lines prefixed with anchors (line # .. hash .. | .. line content): `41th|def alpha():`
+- Reading a file returns lines prefixed with anchors (line+hash): `41th|def alpha():`
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Reading a file returns lines prefixed with line numbers: `41|def alpha():`

package/src/session/agent-session.ts

@@ -196,7 +196,8 @@ export type AgentSessionEvent =
 	| { type: "retry_fallback_succeeded"; model: string; role: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
-	| { type: "todo_auto_clear" };
+	| { type: "todo_auto_clear" }
+	| { type: "irc_message"; message: CustomMessage };
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
@@ -5997,6 +5998,7 @@ export class AgentSession {
 			attribution: "agent",
 			timestamp: incomingTimestamp,
 		};
+		void this.#emitSessionEvent({ type: "irc_message", message: incomingRecord });
 
 		if (!awaitReply) {
 			this.#queueBackgroundExchangeInjection([incomingRecord]);
@@ -6021,6 +6023,7 @@ export class AgentSession {
 			attribution: "agent",
 			timestamp: Date.now(),
 		};
+		void this.#emitSessionEvent({ type: "irc_message", message: replyRecord });
 		this.#queueBackgroundExchangeInjection([incomingRecord, replyRecord]);
 
 		return { replyText };

package/src/tools/ast-edit.ts

@@ -13,6 +13,7 @@ import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, t
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
+import { formatGroupedFiles } from "./grouped-file-output";
 import type { OutputMeta } from "./output-meta";
 import {
 	hasGlobPathChars,
@@ -204,7 +205,9 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 			const useHashLines = resolveFileDisplayMode(this.session).hashLines;
 			const outputLines: string[] = [];
 			const displayLines: string[] = [];
-			const renderChangesForFile = (relativePath: string) => {
+			const renderChangesForFile = (relativePath: string): { model: string[]; display: string[] } => {
+				const modelOut: string[] = [];
+				const displayOut: string[] = [];
 				const fileChanges = changesByFile.get(relativePath) ?? [];
 				const lineNumberWidth = fileChanges.reduce(
 					(width, change) => Math.max(width, String(change.startLine).length),
@@ -222,55 +225,31 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 						? `${change.startLine}${computeLineHash(change.startLine, afterFirstLine)}`
 						: `${change.startLine}:${change.startColumn}`;
 					const lineSeparator = useHashLines ? HASHLINE_CONTENT_SEPARATOR : " ";
-					outputLines.push(`-${beforeRef}${lineSeparator}${beforeLine}`);
-					outputLines.push(`+${afterRef}${lineSeparator}${afterLine}`);
-					displayLines.push(formatCodeFrameLine("-", change.startLine, beforeLine, lineNumberWidth));
-					displayLines.push(formatCodeFrameLine("+", change.startLine, afterLine, lineNumberWidth));
+					modelOut.push(`-${beforeRef}${lineSeparator}${beforeLine}`);
+					modelOut.push(`+${afterRef}${lineSeparator}${afterLine}`);
+					displayOut.push(formatCodeFrameLine("-", change.startLine, beforeLine, lineNumberWidth));
+					displayOut.push(formatCodeFrameLine("+", change.startLine, afterLine, lineNumberWidth));
 				}
+				return { model: modelOut, display: displayOut };
 			};
 
 			if (isDirectory) {
-				const filesByDirectory = new Map<string, string[]>();
-				for (const relativePath of fileList) {
-					const directory = path.dirname(relativePath).replace(/\\/g, "/");
-					if (!filesByDirectory.has(directory)) {
-						filesByDirectory.set(directory, []);
-					}
-					filesByDirectory.get(directory)!.push(relativePath);
-				}
-				for (const [directory, directoryFiles] of filesByDirectory) {
-					if (directory === ".") {
-						for (const relativePath of directoryFiles) {
-							if (outputLines.length > 0) {
-								outputLines.push("");
-								displayLines.push("");
-							}
-							const count = fileReplacementCounts.get(relativePath) ?? 0;
-							const header = `# ${path.basename(relativePath)} (${formatCount("replacement", count)})`;
-							outputLines.push(header);
-							displayLines.push(header);
-							renderChangesForFile(relativePath);
-						}
-						continue;
-					}
-					if (outputLines.length > 0) {
-						outputLines.push("");
-						displayLines.push("");
-					}
-					const dirHeader = `# ${directory}`;
-					outputLines.push(dirHeader);
-					displayLines.push(dirHeader);
-					for (const relativePath of directoryFiles) {
-						const count = fileReplacementCounts.get(relativePath) ?? 0;
-						const fileHeader = `## └─ ${path.basename(relativePath)} (${formatCount("replacement", count)})`;
-						outputLines.push(fileHeader);
-						displayLines.push(fileHeader);
-						renderChangesForFile(relativePath);
-					}
-				}
+				const grouped = formatGroupedFiles(fileList, relativePath => {
+					const rendered = renderChangesForFile(relativePath);
+					const count = fileReplacementCounts.get(relativePath) ?? 0;
+					return {
+						headerSuffix: ` (${formatCount("replacement", count)})`,
+						modelLines: rendered.model,
+						displayLines: rendered.display,
+					};
+				});
+				outputLines.push(...grouped.model);
+				displayLines.push(...grouped.display);
 			} else {
 				for (const relativePath of fileList) {
-					renderChangesForFile(relativePath);
+					const rendered = renderChangesForFile(relativePath);
+					outputLines.push(...rendered.model);
+					displayLines.push(...rendered.display);
 				}
 			}
 

package/src/tools/ast-grep.ts

@@ -12,6 +12,7 @@ import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, t
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
+import { formatGroupedFiles } from "./grouped-file-output";
 import { formatMatchLine } from "./match-line-format";
 import type { OutputMeta } from "./output-meta";
 import {
@@ -184,7 +185,9 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 			const useHashLines = resolveFileDisplayMode(this.session).hashLines;
 			const outputLines: string[] = [];
 			const displayLines: string[] = [];
-			const renderMatchesForFile = (relativePath: string) => {
+			const renderMatchesForFile = (relativePath: string): { model: string[]; display: string[] } => {
+				const modelOut: string[] = [];
+				const displayOut: string[] = [];
 				const fileMatches = matchesByFile.get(relativePath) ?? [];
 				const lineNumberWidth = fileMatches.reduce((width, match) => {
 					const lineCount = match.text.split("\n").length;
@@ -197,61 +200,34 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 						const lineNumber = match.startLine + index;
 						const isMatch = index === 0;
 						const line = matchLines[index] ?? "";
-						outputLines.push(formatMatchLine(lineNumber, line, isMatch, { useHashLines }));
-						displayLines.push(formatCodeFrameLine(isMatch ? "*" : " ", lineNumber, line, lineNumberWidth));
+						modelOut.push(formatMatchLine(lineNumber, line, isMatch, { useHashLines }));
+						displayOut.push(formatCodeFrameLine(isMatch ? "*" : " ", lineNumber, line, lineNumberWidth));
 					}
 					if (match.metaVariables && Object.keys(match.metaVariables).length > 0) {
 						const serializedMeta = Object.entries(match.metaVariables)
 							.sort(([left], [right]) => left.localeCompare(right))
 							.map(([key, value]) => `${key}=${value}`)
 							.join(", ");
-						outputLines.push(`  meta: ${serializedMeta}`);
-						displayLines.push(`  meta: ${serializedMeta}`);
+						modelOut.push(`  meta: ${serializedMeta}`);
+						displayOut.push(`  meta: ${serializedMeta}`);
 					}
 					fileMatchCounts.set(relativePath, (fileMatchCounts.get(relativePath) ?? 0) + 1);
 				}
+				return { model: modelOut, display: displayOut };
 			};
 
 			if (isDirectory) {
-				const filesByDirectory = new Map<string, string[]>();
-				for (const relativePath of fileList) {
-					const directory = path.dirname(relativePath).replace(/\\/g, "/");
-					if (!filesByDirectory.has(directory)) {
-						filesByDirectory.set(directory, []);
-					}
-					filesByDirectory.get(directory)!.push(relativePath);
-				}
-				for (const [directory, directoryFiles] of filesByDirectory) {
-					if (directory === ".") {
-						for (const relativePath of directoryFiles) {
-							if (outputLines.length > 0) {
-								outputLines.push("");
-								displayLines.push("");
-							}
-							const header = `# ${path.basename(relativePath)}`;
-							outputLines.push(header);
-							displayLines.push(header);
-							renderMatchesForFile(relativePath);
-						}
-						continue;
-					}
-					if (outputLines.length > 0) {
-						outputLines.push("");
-						displayLines.push("");
-					}
-					const dirHeader = `# ${directory}`;
-					outputLines.push(dirHeader);
-					displayLines.push(dirHeader);
-					for (const relativePath of directoryFiles) {
-						const fileHeader = `## └─ ${path.basename(relativePath)}`;
-						outputLines.push(fileHeader);
-						displayLines.push(fileHeader);
-						renderMatchesForFile(relativePath);
-					}
-				}
+				const grouped = formatGroupedFiles(fileList, relativePath => {
+					const rendered = renderMatchesForFile(relativePath);
+					return { modelLines: rendered.model, displayLines: rendered.display };
+				});
+				outputLines.push(...grouped.model);
+				displayLines.push(...grouped.display);
 			} else {
 				for (const relativePath of fileList) {
-					renderMatchesForFile(relativePath);
+					const rendered = renderMatchesForFile(relativePath);
+					outputLines.push(...rendered.model);
+					displayLines.push(...rendered.display);
 				}
 			}
 

package/src/tools/grep.ts

@@ -14,6 +14,7 @@ import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, t
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { createFileRecorder } from "./file-recorder";
+import { formatGroupedFiles } from "./grouped-file-output";
 import { formatMatchLine } from "./match-line-format";
 import { formatFullOutputReference, type OutputMeta } from "./output-meta";
 import {
@@ -283,7 +284,6 @@ 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);
@@ -332,46 +332,16 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 				return { model: modelOut, display: displayOut };
 			};
 			if (isDirectory) {
-				const filesByDirectory = new Map<string, string[]>();
-				for (const relativePath of fileList) {
-					const directory = path.dirname(relativePath).replace(/\\/g, "/");
-					if (!filesByDirectory.has(directory)) {
-						filesByDirectory.set(directory, []);
-					}
-					filesByDirectory.get(directory)!.push(relativePath);
-				}
-				for (const [directory, directoryFiles] of filesByDirectory) {
-					if (directory === ".") {
-						for (const relativePath of directoryFiles) {
-							const rendered = renderMatchesForFile(relativePath);
-							if (rendered.model.length === 0) continue;
-							if (outputLines.length > 0) {
-								outputLines.push("");
-								displayLines.push("");
-							}
-							const header = `# ${path.basename(relativePath)}`;
-							outputLines.push(header, ...rendered.model);
-							displayLines.push(header, ...rendered.display);
-						}
-						continue;
-					}
-					const renderedFiles = directoryFiles
-						.map(relativePath => ({ relativePath, rendered: renderMatchesForFile(relativePath) }))
-						.filter(file => file.rendered.model.length > 0);
-					if (renderedFiles.length === 0) continue;
-					if (outputLines.length > 0) {
-						outputLines.push("");
-						displayLines.push("");
-					}
-					const dirHeader = `# ${directory}`;
-					outputLines.push(dirHeader);
-					displayLines.push(dirHeader);
-					for (const { relativePath, rendered } of renderedFiles) {
-						const fileHeader = `## └─ ${path.basename(relativePath)}`;
-						outputLines.push(fileHeader, ...rendered.model);
-						displayLines.push(fileHeader, ...rendered.display);
-					}
-				}
+				const grouped = formatGroupedFiles(fileList, relativePath => {
+					const rendered = renderMatchesForFile(relativePath);
+					return {
+						modelLines: rendered.model,
+						displayLines: rendered.display,
+						skip: rendered.model.length === 0,
+					};
+				});
+				outputLines.push(...grouped.model);
+				displayLines.push(...grouped.display);
 			} else {
 				for (const relativePath of fileList) {
 					const rendered = renderMatchesForFile(relativePath);
@@ -379,11 +349,6 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 					displayLines.push(...rendered.display);
 				}
 			}
-			if (hasContextLines && outputLines.length > 0) {
-				outputLines.unshift(
-					"[grep] '*' marks match lines; leading space marks context. Anchor and content are separated by '|'.",
-				);
-			}
 			if (matchLimitReached || result.limitReached) {
 				outputLines.push("", limitMessage);
 			}

package/src/tools/grouped-file-output.ts

@@ -0,0 +1,96 @@
+import path from "node:path";
+
+/**
+ * One file's contribution to a grouped file output. The header itself is generated
+ * by `formatGroupedFiles` (single `#` for root files, `##` for files inside a dir);
+ * use `headerSuffix` to tack on extras like ` (1 replacement)`.
+ */
+export interface GroupedFileSection {
+	/** Optional suffix appended to the file header. */
+	headerSuffix?: string;
+	/** Body lines emitted into the textual model output. */
+	modelLines: string[];
+	/** Body lines emitted into the display output. Defaults to `modelLines`. */
+	displayLines?: string[];
+	/** When true, the file (and its header) is omitted entirely. */
+	skip?: boolean;
+}
+
+export interface GroupedFilesOutput {
+	model: string[];
+	display: string[];
+}
+
+/**
+ * Render a list of files as directory-grouped sections shared by grep, ast-grep,
+ * ast-edit, and the LSP diagnostic formatter.
+ *
+ * Layout:
+ *   # dir/
+ *   ## file.ts
+ *   …body…
+ *
+ *   # otherdir/
+ *   ## other.ts
+ *   …body…
+ *
+ * Files in the project root (directory `.`) become single-`#` headers without a
+ * `## file` line, matching the existing convention.
+ */
+export function formatGroupedFiles(
+	files: string[],
+	renderFile: (filePath: string) => GroupedFileSection,
+): GroupedFilesOutput {
+	const filesByDirectory = new Map<string, string[]>();
+	for (const filePath of files) {
+		const directory = path.dirname(filePath).replace(/\\/g, "/");
+		if (!filesByDirectory.has(directory)) {
+			filesByDirectory.set(directory, []);
+		}
+		filesByDirectory.get(directory)!.push(filePath);
+	}
+
+	const model: string[] = [];
+	const display: string[] = [];
+
+	const pushSeparatorIfNeeded = () => {
+		if (model.length > 0) {
+			model.push("");
+			display.push("");
+		}
+	};
+
+	for (const [directory, dirFiles] of filesByDirectory) {
+		if (directory === ".") {
+			for (const filePath of dirFiles) {
+				const section = renderFile(filePath);
+				if (section.skip) continue;
+				pushSeparatorIfNeeded();
+				const header = `# ${path.basename(filePath)}${section.headerSuffix ?? ""}`;
+				model.push(header, ...section.modelLines);
+				display.push(header, ...(section.displayLines ?? section.modelLines));
+			}
+			continue;
+		}
+
+		const sections: Array<{ filePath: string; section: GroupedFileSection }> = [];
+		for (const filePath of dirFiles) {
+			const section = renderFile(filePath);
+			if (section.skip) continue;
+			sections.push({ filePath, section });
+		}
+		if (sections.length === 0) continue;
+
+		pushSeparatorIfNeeded();
+		const dirHeader = `# ${directory}/`;
+		model.push(dirHeader);
+		display.push(dirHeader);
+		for (const { filePath, section } of sections) {
+			const fileHeader = `## ${path.basename(filePath)}${section.headerSuffix ?? ""}`;
+			model.push(fileHeader, ...section.modelLines);
+			display.push(fileHeader, ...(section.displayLines ?? section.modelLines));
+		}
+	}
+
+	return { model, display };
+}

package/src/tools/todo-write.ts

@@ -717,7 +717,6 @@ export const todoWriteToolRenderer = {
 		const lines: string[] = [header];
 		for (let p = 0; p < phases.length; p++) {
 			const phase = phases[p];
-			if (p > 0) lines.push("");
 			if (phases.length > 1) {
 				lines.push(uiTheme.fg("accent", chalk.bold(`  ${phase.name}`)));
 			}