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

package/src/lsp/utils.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs/promises";
 import path from "node:path";
 import { isEnoent } from "@oh-my-pi/pi-utils";
 import { type Theme, theme } from "../modes/theme/theme";
+import { formatGroupedFiles } from "../tools/grouped-file-output";
 import { resolveToCwd } from "../tools/path-utils";
 import type {
 	CodeAction,
@@ -154,7 +155,7 @@ const DIAG_PATH_RE = /^(.+?):(\d+:\d+\s+.*)$/;
 /**
  * Reformat pre-formatted diagnostic messages into grep-style directory/file groups.
  * Input:  ["path:line:col [sev] msg", ...]
- * Output: "# dir\n## └─ file.ts\n  line:col [sev] msg"
+ * Output: "# dir/\n## file.ts\n  line:col [sev] msg"
  *
  * Messages that don't match the expected format are appended ungrouped at the end.
  */
@@ -183,41 +184,10 @@ export function formatGroupedDiagnosticMessages(messages: string[]): string {
 		return ungrouped.join("\n");
 	}
 
-	const filesByDirectory = new Map<string, string[]>();
-	for (const filePath of fileOrder) {
-		const directory = path.dirname(filePath).replace(/\\/g, "/");
-		if (!filesByDirectory.has(directory)) {
-			filesByDirectory.set(directory, []);
-		}
-		filesByDirectory.get(directory)?.push(filePath);
-	}
-
-	const lines: string[] = [];
-	for (const [directory, directoryFiles] of filesByDirectory) {
-		if (directory === ".") {
-			for (const filePath of directoryFiles) {
-				if (lines.length > 0) {
-					lines.push("");
-				}
-				lines.push(`# ${path.basename(filePath)}`);
-				for (const diagnostic of diagnosticsByFile.get(filePath) ?? []) {
-					lines.push(`  ${diagnostic}`);
-				}
-			}
-			continue;
-		}
-
-		if (lines.length > 0) {
-			lines.push("");
-		}
-		lines.push(`# ${directory}`);
-		for (const filePath of directoryFiles) {
-			lines.push(`## └─ ${path.basename(filePath)}`);
-			for (const diagnostic of diagnosticsByFile.get(filePath) ?? []) {
-				lines.push(`  ${diagnostic}`);
-			}
-		}
-	}
+	const grouped = formatGroupedFiles(fileOrder, filePath => ({
+		modelLines: (diagnosticsByFile.get(filePath) ?? []).map(diagnostic => `  ${diagnostic}`),
+	}));
+	const lines: string[] = grouped.model;
 
 	if (ungrouped.length > 0) {
 		lines.push("");

package/src/modes/components/status-line.ts

@@ -388,10 +388,12 @@ export class StatusLineComponent implements Component {
 
 		// Collect visible segment contents
 		const leftParts: string[] = [];
+		const leftSegIds: StatusLineSegmentId[] = [];
 		for (const segId of effectiveSettings.leftSegments) {
 			const rendered = renderSegment(segId, ctx);
 			if (rendered.visible && rendered.content) {
 				leftParts.push(rendered.content);
+				leftSegIds.push(segId);
 			}
 		}
 
@@ -434,8 +436,42 @@ export class StatusLineComponent implements Component {
 				right.pop();
 				rightWidth = groupWidth(right, rightCapWidth, rightSepWidth);
 			}
+			// Shrink path before dropping left segments — path is the only elastic segment
+			const pathIdx = leftSegIds.indexOf("path");
+			if (pathIdx >= 0 && totalWidth() > topFillWidth) {
+				const overflow = totalWidth() - topFillWidth;
+				const currentPathVW = visibleWidth(left[pathIdx]);
+				const minPathVW = 8; // icon + ellipsis + a few chars
+				const shrinkable = currentPathVW - minPathVW;
+				if (shrinkable > 0) {
+					const shrinkBy = Math.min(shrinkable, overflow);
+					const currentMaxLen = ctx.options.path?.maxLength ?? 40;
+					let newMaxLen = Math.max(4, Math.min(currentMaxLen, currentPathVW) - shrinkBy);
+					const pathCtx = (maxLen: number): SegmentContext => ({
+						...ctx,
+						options: { ...ctx.options, path: { ...ctx.options.path, maxLength: maxLen } },
+					});
+					let reRendered = renderSegment("path", pathCtx(newMaxLen));
+					if (reRendered.visible && reRendered.content) {
+						// maxLength governs path text, not icon prefix; iterate to compensate
+						for (let i = 0; i < 8; i++) {
+							const saved = currentPathVW - visibleWidth(reRendered.content);
+							if (saved >= shrinkBy) break;
+							const nextMaxLen = Math.max(4, newMaxLen - (shrinkBy - saved));
+							if (nextMaxLen >= newMaxLen) break; // no progress or hit floor
+							newMaxLen = nextMaxLen;
+							const adjusted = renderSegment("path", pathCtx(newMaxLen));
+							if (!adjusted.visible || !adjusted.content) break;
+							reRendered = adjusted;
+						}
+						left[pathIdx] = reRendered.content;
+						leftWidth = groupWidth(left, leftCapWidth, leftSepWidth);
+					}
+				}
+			}
 			while (totalWidth() > topFillWidth && left.length > 0) {
 				left.pop();
+				leftSegIds.pop();
 				leftWidth = groupWidth(left, leftCapWidth, leftSepWidth);
 			}
 		}

package/src/modes/controllers/event-controller.ts

@@ -52,6 +52,7 @@ export class EventController {
 			ttsr_triggered: e => this.#handleTtsrTriggered(e),
 			todo_reminder: e => this.#handleTodoReminder(e),
 			todo_auto_clear: e => this.#handleTodoAutoClear(e),
+			irc_message: e => this.#handleIrcMessage(e),
 		} satisfies AgentSessionEventHandlers;
 	}
 
@@ -203,6 +204,17 @@ export class EventController {
 		}
 	}
 
+	async #handleIrcMessage(event: Extract<AgentSessionEvent, { type: "irc_message" }>): Promise<void> {
+		const signature = `${event.message.role}:${event.message.customType}:${event.message.timestamp}`;
+		if (this.#renderedCustomMessages.has(signature)) {
+			return;
+		}
+		this.#renderedCustomMessages.add(signature);
+		this.#resetReadGroup();
+		this.ctx.addMessageToChat(event.message);
+		this.ctx.ui.requestRender();
+	}
+
 	async #handleMessageUpdate(event: Extract<AgentSessionEvent, { type: "message_update" }>): Promise<void> {
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			this.ctx.streamingMessage = event.message;
@@ -269,8 +281,21 @@ export class EventController {
 			for (const content of this.ctx.streamingMessage.content) {
 				if (content.type !== "toolCall") continue;
 				const args = content.arguments;
-				if (!args || typeof args !== "object" || !(INTENT_FIELD in args)) continue;
-				this.#updateWorkingMessageFromIntent(args[INTENT_FIELD] as string | undefined);
+				if (!args || typeof args !== "object") continue;
+				if (INTENT_FIELD in args) {
+					this.#updateWorkingMessageFromIntent(args[INTENT_FIELD] as string | undefined);
+					continue;
+				}
+				const tool = this.ctx.session.getToolByName(content.name);
+				if (typeof tool?.intent !== "function") continue;
+				try {
+					const derived = tool.intent(args as never)?.trim();
+					if (derived) {
+						this.#updateWorkingMessageFromIntent(derived);
+					}
+				} catch {
+					// intent function must never break the UI
+				}
 			}
 
 			this.ctx.ui.requestRender();

package/src/prompts/system/system-prompt.md

@@ -168,7 +168,7 @@ Tools:
 
 {{#if intentTracing}}
 <intent-field>
-Every tool has a `{{intentField}}` parameter. Fill it with a concise intent in present participle form, 2-6 words, no period.
+Most tools have a `{{intentField}}` parameter. Fill it with a concise intent in present participle form, 2-6 words, no period.
 </intent-field>
 {{/if}}
 

package/src/prompts/tools/atom.md

@@ -1,98 +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: "s/foo/bar/"` — sed-style substitution applied to the anchor line. **Prefer this over `splice` for token-level changes**
-Flags: `g` (all occurrences), `i` (case-insensitive), `F` (literal).
-Delimiter is whatever character follows `s`.
-You **MUST** keep the pattern 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 pattern that uniquely identifies the change.
-`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:"s/\\|\\|/??/"}]}`
-
-# Substitute every occurrence with `sed` (literal/fixed-string)
-Use the `F` flag to disable regex; the delimiter can be any non-alphanumeric char.
-`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:"s|data|input|gF"}]}`
-
-# 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:"s/x/x \\&\\& ready/"},{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 `sed` pattern that uniquely identifies the change on that line; do not pad it with surrounding text just to feel safe. 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;
@@ -2970,6 +2971,30 @@ export class AgentSession {
 			attribution: "user",
 			timestamp: Date.now(),
 		});
+		// When fully idle AND the session is in a resumable assistant-ended state,
+		// schedule an immediate continue so the queued follow-up is delivered
+		// without waiting for the next user turn. We gate on isStreaming (model
+		// actively producing), isRetrying (auto-retry backoff is sleeping between
+		// attempts, #retryPromise set), and the last message being assistant —
+		// agent.continue() only dequeues follow-ups from an assistant-ended state;
+		// resuming from user/toolResult state runs an extra model call on the
+		// stale prompt before draining the queue.
+		if (this.#canAutoContinueForFollowUp()) {
+			this.#scheduleAgentContinue({
+				shouldContinue: () => this.#canAutoContinueForFollowUp() && this.agent.hasQueuedMessages(),
+			});
+		}
+	}
+
+	/**
+	 * Gate for idle-path follow-up auto-continue. See `#queueFollowUp` for rationale.
+	 */
+	#canAutoContinueForFollowUp(): boolean {
+		if (this.isStreaming) return false;
+		if (this.isRetrying) return false;
+		const messages = this.agent.state.messages;
+		const last = messages[messages.length - 1];
+		return last?.role === "assistant";
 	}
 
 	queueDeferredMessage(message: CustomMessage): void {
@@ -5973,6 +5998,7 @@ export class AgentSession {
 			attribution: "agent",
 			timestamp: incomingTimestamp,
 		};
+		void this.#emitSessionEvent({ type: "irc_message", message: incomingRecord });
 
 		if (!awaitReply) {
 			this.#queueBackgroundExchangeInjection([incomingRecord]);
@@ -5997,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/checkpoint.ts

@@ -52,6 +52,7 @@ export class CheckpointTool implements AgentTool<typeof checkpointSchema, Checkp
 	readonly description: string;
 	readonly parameters = checkpointSchema;
 	readonly strict = true;
+	readonly intent = (args: Partial<CheckpointParams>) => args.goal;
 
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(checkpointDescription);
@@ -94,6 +95,7 @@ export class RewindTool implements AgentTool<typeof rewindSchema, RewindToolDeta
 	readonly description: string;
 	readonly parameters = rewindSchema;
 	readonly strict = true;
+	readonly intent = (): string => "Rewinding to checkpoint";
 
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(rewindDescription);

package/src/tools/exit-plan-mode.ts

@@ -46,6 +46,7 @@ export class ExitPlanModeTool implements AgentTool<typeof exitPlanModeSchema, Ex
 	readonly parameters = exitPlanModeSchema;
 	readonly strict = true;
 	readonly concurrency = "exclusive";
+	readonly intent = (): string => "Exiting plan mode";
 
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(exitPlanModeDescription);