@oh-my-pi/pi-coding-agent 14.4.0 → 14.4.3

package/src/session/agent-session.ts

@@ -27,6 +27,7 @@ import {
 } from "@oh-my-pi/pi-agent-core";
 import type {
 	AssistantMessage,
+	Context,
 	Effort,
 	ImageContent,
 	Message,
@@ -48,6 +49,7 @@ import {
 	isUsageLimitError,
 	modelsAreEqual,
 	parseRateLimitReason,
+	streamSimple,
 } from "@oh-my-pi/pi-ai";
 import { killTree, MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
 import {
@@ -121,6 +123,7 @@ import type { PlanModeState } from "../plan-mode/state";
 import autoHandoffThresholdFocusPrompt from "../prompts/system/auto-handoff-threshold-focus.md" with { type: "text" };
 import eagerTodoPrompt from "../prompts/system/eager-todo.md" with { type: "text" };
 import handoffDocumentPrompt from "../prompts/system/handoff-document.md" with { type: "text" };
+import ircIncomingTemplate from "../prompts/system/irc-incoming.md" with { type: "text" };
 import planModeActivePrompt from "../prompts/system/plan-mode-active.md" with { type: "text" };
 import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
 import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool-decision-reminder.md" with {
@@ -469,6 +472,11 @@ export class AgentSession {
 	#pendingPythonMessages: PythonExecutionMessage[] = [];
 	#activePythonExecutions = new Set<Promise<unknown>>();
 	#pythonExecutionDisposing = false;
+
+	// Background-channel IRC exchanges queued while the recipient was streaming.
+	// Drained into history (via emitExternalEvent) once the recipient becomes idle.
+	#pendingBackgroundExchanges: CustomMessage[][] = [];
+	#scheduledBackgroundExchangeFlush = false;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
 	#turnIndex = 0;
@@ -2653,6 +2661,7 @@ export class AgentSession {
 			// Flush any pending bash messages before the new prompt
 			this.#flushPendingBashMessages();
 			this.#flushPendingPythonMessages();
+			this.#flushPendingBackgroundExchanges();
 
 			// Reset todo reminder count on new user prompt
 			this.#todoReminderCount = 0;
@@ -3237,11 +3246,11 @@ export class AgentSession {
 		return phases.map(phase => ({
 			id: phase.id,
 			name: phase.name,
-			tasks: phase.tasks.map(task => ({
-				id: task.id,
-				content: task.content,
-				status: task.status,
-			})),
+			tasks: phase.tasks.map(task => {
+				const out: TodoItem = { id: task.id, content: task.content, status: task.status };
+				if (task.notes && task.notes.length > 0) out.notes = [...task.notes];
+				return out;
+			}),
 		}));
 	}
 
@@ -5924,6 +5933,209 @@ export class AgentSession {
 		this.#pendingPythonMessages = [];
 	}
 
+	// =========================================================================
+	// Background-Channel IRC Exchanges
+	// =========================================================================
+
+	/**
+	 * Generate an ephemeral reply to a background message (e.g. an IRC ping from
+	 * another agent) using this session's current model + system prompt + history.
+	 *
+	 * The reply is computed via a side-channel `streamSimple` call (analogous to
+	 * `/btw`) so it never blocks on the recipient's in-flight tool calls.  After
+	 * the reply is generated, both the incoming question and the auto-reply are
+	 * queued for injection into the recipient's persisted history so the model
+	 * sees the exchange on its next turn.  Injection happens immediately when the
+	 * session is idle, otherwise it is deferred until streaming ends.
+	 */
+	async respondAsBackground(args: {
+		from: string;
+		message: string;
+		awaitReply?: boolean;
+		signal?: AbortSignal;
+	}): Promise<{ replyText: string | null }> {
+		const awaitReply = args.awaitReply !== false;
+		const incomingTimestamp = Date.now();
+		const incomingRecord: CustomMessage = {
+			role: "custom",
+			customType: "irc:incoming",
+			content: `[IRC \`${args.from}\` \u2192 you]\n\n${args.message}`,
+			display: true,
+			details: { from: args.from, message: args.message },
+			attribution: "agent",
+			timestamp: incomingTimestamp,
+		};
+
+		if (!awaitReply) {
+			this.#queueBackgroundExchangeInjection([incomingRecord]);
+			return { replyText: null };
+		}
+
+		const incomingPrompt = prompt.render(ircIncomingTemplate, {
+			from: args.from,
+			message: args.message,
+		});
+		const { replyText } = await this.runEphemeralTurn({
+			promptText: incomingPrompt,
+			signal: args.signal,
+		});
+
+		const replyRecord: CustomMessage = {
+			role: "custom",
+			customType: "irc:autoreply",
+			content: `[IRC you \u2192 \`${args.from}\` (auto)]\n\n${replyText}`,
+			display: true,
+			details: { to: args.from, reply: replyText },
+			attribution: "agent",
+			timestamp: Date.now(),
+		};
+		this.#queueBackgroundExchangeInjection([incomingRecord, replyRecord]);
+
+		return { replyText };
+	}
+
+	/**
+	 * Run a single ephemeral side-channel turn against this session's current
+	 * model + system prompt + history.  No tools are used; the side request
+	 * does not block on, or interfere with, any in-flight main turn.  The
+	 * session's history and persisted state are NOT modified by this call.
+	 *
+	 * Used by `respondAsBackground` (IRC) and `BtwController` (`/btw`) to share
+	 * the snapshot + stream pipeline.  The snapshot includes any in-flight
+	 * streaming assistant text so the model sees the half-finished response
+	 * rather than missing context.
+	 */
+	async runEphemeralTurn(args: {
+		promptText: string;
+		onTextDelta?: (delta: string) => void;
+		signal?: AbortSignal;
+	}): Promise<{ replyText: string; assistantMessage: AssistantMessage }> {
+		const model = this.model;
+		if (!model) {
+			throw new Error("No active model on session");
+		}
+		const apiKey = await this.#modelRegistry.getApiKey(model, this.sessionId);
+		if (!apiKey) {
+			throw new Error(`No API key for ${model.provider}/${model.id}`);
+		}
+
+		const snapshot = this.#buildEphemeralSnapshot(args.promptText);
+		const llmMessages = await this.convertMessagesToLlm(snapshot, args.signal);
+		const context: Context = {
+			systemPrompt: this.systemPrompt,
+			messages: llmMessages,
+		};
+		const options = this.prepareSimpleStreamOptions({
+			apiKey,
+			sessionId: this.sessionId,
+			reasoning: toReasoningEffort(this.thinkingLevel),
+			serviceTier: this.serviceTier,
+			signal: args.signal,
+			toolChoice: "none",
+		});
+
+		let replyText = "";
+		let assistantMessage: AssistantMessage | undefined;
+		const stream = streamSimple(model, context, options);
+		for await (const event of stream) {
+			if (event.type === "text_delta") {
+				replyText += event.delta;
+				if (args.onTextDelta) args.onTextDelta(event.delta);
+				continue;
+			}
+			if (event.type === "done") {
+				assistantMessage = event.message;
+				break;
+			}
+			if (event.type === "error") {
+				throw new Error(event.error.errorMessage || "Ephemeral turn failed");
+			}
+		}
+
+		if (!assistantMessage) {
+			throw new Error("Ephemeral turn ended without a final message");
+		}
+		return { replyText: replyText.trim(), assistantMessage };
+	}
+
+	/**
+	 * Build a message snapshot for an ephemeral side-channel turn.  Includes
+	 * the in-flight streaming assistant message (if any) so the model sees
+	 * the partial response in context, then appends the prompt as a virtual
+	 * user message.
+	 */
+	#buildEphemeralSnapshot(promptText: string): AgentMessage[] {
+		const messages = [...this.messages];
+		const streaming = this.agent.state.streamMessage;
+		if (streaming && streaming.role === "assistant") {
+			const streamingText = streaming.content
+				.filter((c): c is TextContent => c.type === "text")
+				.map(c => c.text)
+				.join("");
+			if (streamingText) {
+				const normalized: AssistantMessage = {
+					...streaming,
+					content: [{ type: "text", text: streamingText }],
+				};
+				const lastMessage = messages.at(-1);
+				if (lastMessage?.role === "assistant") {
+					messages[messages.length - 1] = normalized;
+				} else {
+					messages.push(normalized);
+				}
+			}
+		}
+		messages.push({
+			role: "user",
+			content: [{ type: "text", text: promptText }],
+			attribution: "agent",
+			timestamp: Date.now(),
+		});
+		return messages;
+	}
+
+	#queueBackgroundExchangeInjection(messages: CustomMessage[]): void {
+		this.#pendingBackgroundExchanges.push(messages);
+		if (!this.isStreaming) {
+			this.#flushPendingBackgroundExchanges();
+			return;
+		}
+		this.#scheduleBackgroundExchangeFlush();
+	}
+
+	#scheduleBackgroundExchangeFlush(): void {
+		if (this.#scheduledBackgroundExchangeFlush) return;
+		this.#scheduledBackgroundExchangeFlush = true;
+		const attempt = (): void => {
+			if (this.#pendingBackgroundExchanges.length === 0) {
+				this.#scheduledBackgroundExchangeFlush = false;
+				return;
+			}
+			if (this.isStreaming) {
+				setTimeout(attempt, 50);
+				return;
+			}
+			this.#scheduledBackgroundExchangeFlush = false;
+			this.#flushPendingBackgroundExchanges();
+		};
+		setTimeout(attempt, 0);
+	}
+
+	#flushPendingBackgroundExchanges(): void {
+		if (this.#pendingBackgroundExchanges.length === 0) return;
+		const batches = this.#pendingBackgroundExchanges;
+		this.#pendingBackgroundExchanges = [];
+		for (const batch of batches) {
+			for (const msg of batch) {
+				// emitExternalEvent on message_end appends to agent state and dispatches
+				// to all session listeners, which in turn handle TUI rendering and
+				// sessionManager persistence via #handleAgentEvent.
+				this.agent.emitExternalEvent({ type: "message_start", message: msg });
+				this.agent.emitExternalEvent({ type: "message_end", message: msg });
+			}
+		}
+	}
+
 	// =========================================================================
 	// Session Management
 	// =========================================================================

package/src/session/session-manager.ts

@@ -259,6 +259,8 @@ export interface SessionInfo {
 	created: Date;
 	modified: Date;
 	messageCount: number;
+	/** File size in bytes on disk; used for compact list rendering. */
+	size: number;
 	firstMessage: string;
 	allMessagesText: string;
 }
@@ -1264,7 +1266,7 @@ function extractTextFromContent(content: Message["content"]): string {
 		.join(" ");
 }
 
-const SESSION_LIST_PREFIX_BYTES = 1024;
+const SESSION_LIST_PREFIX_BYTES = 4096;
 const SESSION_LIST_PARALLEL_THRESHOLD = 64;
 const SESSION_LIST_MAX_WORKERS = 16;
 const sessionListPrefixDecoder = new TextDecoder("utf-8", { fatal: false });
@@ -1466,6 +1468,7 @@ async function collectSessionFromFile(
 			created: new Date(header.timestamp ?? ""),
 			modified: stats.mtime,
 			messageCount,
+			size: stats.size,
 			firstMessage: firstMessage || "(no messages)",
 			allMessagesText: allMessages.length > 0 ? allMessages.join(" ") : firstMessage,
 		};

package/src/session/streaming-output.ts

@@ -759,7 +759,7 @@ export function formatHeadTruncationNotice(
 	const totalFileLines = options.totalFileLines ?? truncation.totalLines;
 	const endLineDisplay = startLineDisplay + (truncation.outputLines ?? truncation.totalLines) - 1;
 	const nextOffset = endLineDisplay + 1;
-	const notice = `[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use sel=L${nextOffset} to continue]`;
+	const notice = `[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use sel=${nextOffset} to continue]`;
 	return `\n\n${notice}`;
 }
 

package/src/slash-commands/builtin-registry.ts

@@ -259,6 +259,30 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<BuiltinSlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "todo",
+		description: "View or modify the agent's todo list",
+		subcommands: [
+			{ name: "edit", description: "Open todos in $EDITOR (Markdown round-trip)" },
+			{ name: "copy", description: "Copy todos as Markdown to clipboard" },
+			{ name: "export", description: "Write todos as Markdown to a file (default: TODO.md)", usage: "[<path>]" },
+			{ name: "import", description: "Replace todos from a Markdown file (default: TODO.md)", usage: "[<path>]" },
+			{
+				name: "append",
+				description: "Append a task; phase fuzzy-matched or auto-created",
+				usage: "[<phase>] <task...>",
+			},
+			{ name: "start", description: "Mark task in_progress (fuzzy-matched)", usage: "<task>" },
+			{ name: "done", description: "Mark task/phase/all completed (fuzzy-matched)", usage: "[<task|phase>]" },
+			{ name: "drop", description: "Mark task/phase/all abandoned (fuzzy-matched)", usage: "[<task|phase>]" },
+			{ name: "rm", description: "Remove task/phase/all (fuzzy-matched)", usage: "[<task|phase>]" },
+		],
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			await runtime.ctx.handleTodoCommand(command.args);
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "session",
 		description: "Session management commands",

package/src/task/executor.ts

@@ -20,6 +20,7 @@ import { callTool } from "../mcp/client";
 import type { MCPManager } from "../mcp/manager";
 import subagentSystemPromptTemplate from "../prompts/system/subagent-system-prompt.md" with { type: "text" };
 import submitReminderTemplate from "../prompts/system/subagent-yield-reminder.md" with { type: "text" };
+import { AgentRegistry } from "../registry/agent-registry";
 import { createAgentSession, discoverAuthStorage } from "../sdk";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { AuthStorage } from "../session/auth-storage";
@@ -73,6 +74,14 @@ function normalizeModelPatterns(value: string | string[] | undefined): string[]
 		.filter(Boolean);
 }
 
+function renderIrcPeerRoster(selfId: string): string {
+	const peers = AgentRegistry.global()
+		.list()
+		.filter(ref => ref.id !== selfId && (ref.status === "running" || ref.status === "idle"));
+	if (peers.length === 0) return "- (no other live agents)";
+	return peers.map(peer => `- \`${peer.id}\` — ${peer.displayName} (${peer.kind}, ${peer.status})`).join("\n");
+}
+
 function withAbortTimeout<T>(promise: Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<T> {
 	if (signal?.aborted) {
 		return Promise.reject(new ToolAbortError());
@@ -543,6 +552,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				: agent.spawns.join(",");
 
 	const lspEnabled = enableLsp ?? true;
+	const ircEnabled = subagentSettings.get("irc.enabled") === true;
 	const skipPythonPreflight = Array.isArray(toolNames) && !toolNames.includes("python");
 
 	const outputChunks: string[] = [];
@@ -962,12 +972,16 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 						worktree: worktree ?? "",
 						outputSchema: normalizedOutputSchema,
 						contextFile: options.contextFile,
+						ircPeers: ircEnabled ? renderIrcPeerRoster(id) : "",
+						ircSelfId: ircEnabled ? id : "",
 					}),
 				sessionManager,
 				hasUI: false,
 				spawns: spawnsEnv,
 				taskDepth: childDepth,
 				parentTaskPrefix: id,
+				agentId: id,
+				agentDisplayName: agent.name,
 				enableLsp: lspEnabled,
 				skipPythonPreflight,
 				enableMCP,

package/src/tools/bash.ts

@@ -346,7 +346,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 		}
 		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.`);
+		lines.push(`Use \`job\` (with \`poll\` or \`cancel\`) or \`read jobs://${jobId}\` if needed.`);
 		return {
 			content: [{ type: "text", text: lines.join("\n") }],
 			details,

package/src/tools/fetch.ts

@@ -137,7 +137,9 @@ export function isReadableUrlPath(value: string): boolean {
 	return /^https?:\/\//i.test(value) || /^www\./i.test(value);
 }
 
-const URL_LINE_RANGE_RE = /^L(\d+)(?:-L?(\d+))?$/i;
+const URL_LINE_RANGE_RE = /^L?(\d+)(?:([-+])L?(\d+))?$/i;
+// Embedded URL selectors (after a `:` in the path) keep the explicit `L` prefix to avoid colliding with ports such as `https://example.com:50`.
+const URL_EMBEDDED_LINE_RANGE_RE = /^L\d+(?:[-+]L?\d+)?$/i;
 
 export interface ParsedReadUrlTarget {
 	path: string;
@@ -159,11 +161,21 @@ export function parseReadUrlTarget(readPath: string, sel?: string): ParsedReadUr
 	if (lineMatch) {
 		const startLine = Number.parseInt(lineMatch[1]!, 10);
 		if (startLine < 1) {
-			throw new ToolError("L0 is invalid; lines are 1-indexed. Use sel=L1.");
+			throw new ToolError("sel=0 is invalid; lines are 1-indexed. Use sel=1.");
 		}
-		const endLine = lineMatch[2] ? Number.parseInt(lineMatch[2], 10) : undefined;
-		if (endLine !== undefined && endLine < startLine) {
-			throw new ToolError(`Invalid range L${startLine}-L${endLine}: end must be >= start.`);
+		const sep = lineMatch[2];
+		const rhs = lineMatch[3] ? Number.parseInt(lineMatch[3], 10) : undefined;
+		let endLine: number | undefined;
+		if (sep === "+") {
+			if (rhs === undefined || rhs < 1) {
+				throw new ToolError(`Invalid range ${startLine}+${rhs ?? 0}: count must be >= 1.`);
+			}
+			endLine = startLine + rhs - 1;
+		} else if (sep === "-") {
+			if (rhs === undefined || rhs < startLine) {
+				throw new ToolError(`Invalid range ${startLine}-${rhs ?? 0}: end must be >= start.`);
+			}
+			endLine = rhs;
 		}
 		return {
 			path: urlPath,
@@ -183,7 +195,7 @@ function tryExtractEmbeddedUrlSelector(readPath: string): { path: string; sel?:
 	}
 
 	const candidateSelector = readPath.slice(lastColonIndex + 1);
-	const isEmbeddedSelector = candidateSelector === "raw" || URL_LINE_RANGE_RE.test(candidateSelector);
+	const isEmbeddedSelector = candidateSelector === "raw" || URL_EMBEDDED_LINE_RANGE_RE.test(candidateSelector);
 	if (!isEmbeddedSelector) {
 		return null;
 	}

package/src/tools/fs-cache-invalidation.ts

@@ -1,12 +1,10 @@
 import { invalidateFsScanCache } from "@oh-my-pi/pi-natives";
-import { invalidateChunkCache } from "../edit/modes/chunk";
 
 /**
  * Invalidate shared filesystem scan caches after a content write/update.
  */
 export function invalidateFsScanAfterWrite(path: string): void {
 	invalidateFsScanCache(path);
-	invalidateChunkCache(path);
 }
 
 /**
@@ -14,7 +12,6 @@ export function invalidateFsScanAfterWrite(path: string): void {
  */
 export function invalidateFsScanAfterDelete(path: string): void {
 	invalidateFsScanCache(path);
-	invalidateChunkCache(path);
 }
 
 /**
@@ -25,9 +22,7 @@ export function invalidateFsScanAfterDelete(path: string): void {
  */
 export function invalidateFsScanAfterRename(oldPath: string, newPath: string): void {
 	invalidateFsScanCache(oldPath);
-	invalidateChunkCache(oldPath);
 	if (newPath !== oldPath) {
 		invalidateFsScanCache(newPath);
-		invalidateChunkCache(newPath);
 	}
 }

package/src/tools/grep.ts

@@ -6,13 +6,11 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { type ChunkedGrepMatch, describeChunkedGrepMatch } from "../edit/modes/chunk";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
-import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
+import type { Theme } from "../modes/theme/theme";
 import grepDescription from "../prompts/tools/grep.md" with { type: "text" };
 import { DEFAULT_MAX_COLUMN, type TruncationResult, truncateHead } from "../session/streaming-output";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
-import { resolveEditMode } from "../utils/edit-mode";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { createFileRecorder } from "./file-recorder";
@@ -64,7 +62,7 @@ export interface GrepToolDetails {
 	truncated?: boolean;
 	error?: string;
 	/** Pre-formatted text for the user-visible TUI render. Mirrors the model-facing
-	 * `result.text` lines but uses a `│` gutter and `*` to mark match lines (vs `-` for
+	 * `result.text` lines but uses a `│` gutter and `*` to mark match lines (vs space for
 	 * context). The TUI uses this directly so it never parses model-facing hashline anchors. */
 	displayContent?: string;
 }
@@ -83,7 +81,6 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 		this.description = prompt.render(grepDescription, {
 			IS_HASHLINE_MODE: displayMode.hashLines,
 			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
-			IS_CHUNK_MODE: displayMode.chunked,
 		});
 	}
 
@@ -98,7 +95,6 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 
 		return untilAborted(signal, async () => {
 			const normalizedPattern = pattern.trim();
-			const chunkMode = resolveEditMode(this.session) === "chunk";
 			if (!normalizedPattern) {
 				throw new ToolError("Pattern must not be empty");
 			}
@@ -297,124 +293,6 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 				}
 				matchesByFile.get(relativePath)!.push(match);
 			}
-			if (chunkMode) {
-				const annotatedMatches = await Promise.all(
-					selectedMatches.map(match => {
-						const relativePath = match.path.startsWith("/") ? match.path.slice(1) : match.path;
-						const absoluteFilePath = isDirectory ? path.join(searchPath, relativePath) : searchPath;
-						return describeChunkedGrepMatch({
-							filePath: absoluteFilePath,
-							lineNumber: match.lineNumber,
-							line: match.line,
-							cwd: this.session.cwd,
-							language: getLanguageFromPath(absoluteFilePath),
-						});
-					}),
-				);
-				const chunkMatchesByFile = new Map<string, ChunkedGrepMatch[]>();
-				for (const match of annotatedMatches) {
-					recordFile(match.displayPath);
-					if (!chunkMatchesByFile.has(match.displayPath)) {
-						chunkMatchesByFile.set(match.displayPath, []);
-					}
-					chunkMatchesByFile.get(match.displayPath)!.push(match);
-				}
-				const renderChunkedMatchesForFile = (relativePath: string): string[] => {
-					const renderedLines: string[] = [];
-					const fileMatches = chunkMatchesByFile.get(relativePath) ?? [];
-					if (fileMatches.length === 0) {
-						return renderedLines;
-					}
-					const matchesByChunk = new Map<string, ChunkedGrepMatch[]>();
-					for (const match of fileMatches) {
-						const chunkKey = match.chunkPath ?? "";
-						if (!matchesByChunk.has(chunkKey)) {
-							matchesByChunk.set(chunkKey, []);
-						}
-						matchesByChunk.get(chunkKey)!.push(match);
-					}
-					for (const [chunkPath, chunkMatches] of matchesByChunk) {
-						if (chunkPath) {
-							const chunkChecksum = chunkMatches[0]?.chunkChecksum;
-							const dashes = "-".repeat(chunkPath.split(".").length - 1);
-							const anchor = chunkChecksum
-								? `${dashes}@${chunkPath}#${chunkChecksum}`
-								: `${dashes}@${chunkPath}`;
-							renderedLines.push(anchor);
-						}
-						for (const match of chunkMatches) {
-							renderedLines.push(`    ${match.lineNumber}|${match.line}`);
-							fileMatchCounts.set(relativePath, (fileMatchCounts.get(relativePath) ?? 0) + 1);
-						}
-					}
-					return renderedLines;
-				};
-				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 renderedLines = renderChunkedMatchesForFile(relativePath);
-								if (renderedLines.length === 0) continue;
-								if (outputLines.length > 0) {
-									outputLines.push("");
-								}
-								outputLines.push(`# ${path.basename(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, lines } of renderedFiles) {
-							outputLines.push(`## └─ ${path.basename(relativePath)}`);
-							outputLines.push(...lines);
-						}
-					}
-				} else {
-					for (const relativePath of fileList) {
-						outputLines.push(...renderChunkedMatchesForFile(relativePath));
-					}
-				}
-				if (matchLimitReached || result.limitReached) {
-					outputLines.push("", limitMessage);
-				}
-				const rawOutput = outputLines.join("\n");
-				const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
-				const truncated = Boolean(matchLimitReached || result.limitReached || truncation.truncated);
-				const details: GrepToolDetails = {
-					scopePath,
-					matchCount: selectedMatches.length,
-					fileCount: fileList.length,
-					files: fileList,
-					fileMatches: fileList.map(path => ({
-						path,
-						count: fileMatchCounts.get(path) ?? 0,
-					})),
-					truncated,
-					matchLimitReached: matchLimitReached ? effectiveLimit : undefined,
-					resultLimitReached: result.limitReached ? internalLimit : undefined,
-				};
-				if (truncation.truncated) details.truncation = truncation;
-				const resultBuilder = toolResult(details).text(truncation.content);
-				if (truncation.truncated) {
-					resultBuilder.truncation(truncation, { direction: "head" });
-				}
-				return resultBuilder.done();
-			}
 			const displayLines: string[] = [];
 			const renderMatchesForFile = (relativePath: string): { model: string[]; display: string[] } => {
 				const modelOut: string[] = [];
@@ -502,7 +380,9 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 				}
 			}
 			if (hasContextLines && outputLines.length > 0) {
-				outputLines.unshift("[grep] match lines use ':'; context lines use '-'.");
+				outputLines.unshift(
+					"[grep] '*' marks match lines; leading space marks context. Anchor and content are separated by '|'.",
+				);
 			}
 			if (matchLimitReached || result.limitReached) {
 				outputLines.push("", limitMessage);