mini-coder 0.5.11 → 0.5.13

package/src/ui/conversation.ts

@@ -8,12 +8,18 @@
  * @module
  */
 
+import { homedir } from "node:os";
 import {
-  SyntaxHighlight,
-  type SyntaxHighlightTheme,
-} from "@cel-tui/components";
+  basename,
+  extname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+} from "node:path";
+import { SyntaxHighlight } from "@cel-tui/components";
 import { HStack, measureContentHeight, Text, VStack } from "@cel-tui/core";
-import type { Color, Node } from "@cel-tui/types";
+import type { Node } from "@cel-tui/types";
 import type {
   AssistantMessage,
   TextContent,
@@ -22,8 +28,17 @@ import type {
 } from "@mariozechner/pi-ai";
 import type { AppState } from "../index.ts";
 import type { UiMessage } from "../session.ts";
-import type { Theme } from "../theme.ts";
-import { parseTodoSnapshot, type TodoItem } from "../tools.ts";
+import { readBoolean, readFiniteNumber, readString } from "../shared.ts";
+import { getSyntaxHighlightTheme, type Theme } from "../theme.ts";
+import {
+  parseGrepResult,
+  parseLegacyShellResult,
+  parseReadContinuationHint,
+  parseReadResult,
+  parseShellResultDetails,
+  parseTodoSnapshot,
+  type TodoItem,
+} from "../tools.ts";
 import { APP_NAME, DEV_VERSION_LABEL } from "../version.ts";
 
 /** Single blank-line gap used between conversation-level blocks. */
@@ -35,32 +50,9 @@ const UI_TOOL_PREVIEW_ROWS = 8;
 /** Default width used when preview measurements do not receive one explicitly. */
 const DEFAULT_TOOL_PREVIEW_WIDTH = 80;
 
-/** Horizontal columns consumed by assistant-markdown padding. */
-const MARKDOWN_BLOCK_CHROME_WIDTH = 2;
-
 /** Horizontal columns consumed by tool-block padding and the left border. */
 const TOOL_BLOCK_CHROME_WIDTH = 4;
 
-/** ANSI16 fallback hex values for syntax-highlighter theme overrides. */
-const ANSI_COLOR_HEX: Readonly<Record<Color, string>> = {
-  color00: "#000000",
-  color01: "#cd3131",
-  color02: "#0dbc79",
-  color03: "#e5e510",
-  color04: "#2472c8",
-  color05: "#bc3fbc",
-  color06: "#11a8cd",
-  color07: "#e5e5e5",
-  color08: "#666666",
-  color09: "#f14c4c",
-  color10: "#23d18b",
-  color11: "#f5f543",
-  color12: "#3b8eea",
-  color13: "#d670d6",
-  color14: "#29b8db",
-  color15: "#ffffff",
-};
-
 /** A pending tool result shown in the streaming tail. */
 export interface PendingToolResult {
   /** Tool call id from the assistant message. */
@@ -69,6 +61,8 @@ export interface PendingToolResult {
   toolName: string;
   /** Progressive or final tool-result content captured so far. */
   content: ToolResultMessage["content"];
+  /** Optional structured details preserved on the tool result. */
+  details?: ToolResultMessage["details"];
   /** Whether the tool result was an error. */
   isError: boolean;
 }
@@ -81,6 +75,8 @@ interface ConversationRenderOpts {
   verbose: boolean;
   /** Active UI theme. */
   theme: Theme;
+  /** Session working directory used for path display. */
+  cwd?: string;
   /** Available terminal width for width-aware tool previews. */
   previewWidth?: number;
 }
@@ -107,7 +103,7 @@ type ConversationMessage = AppState["messages"][number];
 
 type ConversationLogState = Pick<
   AppState,
-  "messages" | "showReasoning" | "verbose" | "theme"
+  "messages" | "showReasoning" | "verbose" | "theme" | "cwd"
 > & {
   versionLabel?: AppState["versionLabel"];
 };
@@ -123,15 +119,14 @@ interface ToolCallArgsCache {
   entries: Map<string, ToolCallRenderInfo>;
 }
 
-interface ConversationRenderCache {
-  messages: readonly ConversationMessage[] | null;
-  startIndex: number;
-  count: number;
+interface ConversationMessageRenderCacheEntry {
+  node: Node | null;
+  height: number;
   showReasoning: boolean;
   verbose: boolean;
   previewWidth: number;
+  cwd: string | null;
   theme: Theme | null;
-  nodes: Node[];
 }
 
 type ToolRenderDirection = "->" | "<-";
@@ -140,12 +135,13 @@ type ToolRenderLineKind =
   | "command"
   | "path"
   | "text"
+  | "context"
   | "diffAdded"
   | "diffRemoved"
   | "summary"
   | "error";
 
-type SyntaxThemeVariant = "markdown" | "shell";
+type SyntaxThemeVariant = "markdown" | "code" | "shell";
 
 interface HighlightedBodySpec {
   /** Full raw source content to syntax-highlight. */
@@ -161,12 +157,16 @@ interface ToolBlockSpec {
   toolName: string;
   /** Direction shown in the header pill. */
   direction: ToolRenderDirection;
+  /** Optional compact text appended after the header pill. */
+  headerSuffix?: string;
   /** Logical body lines for the tool block. */
   bodyLines: readonly ToolRenderLine[];
   /** Optional syntax-highlighted body rendered from the full unsplit source. */
   highlightedBody?: HighlightedBodySpec;
   /** Optional custom body node rendered as-is. */
   bodyNode?: Node;
+  /** Optional footer lines rendered after the body. */
+  footerLines?: readonly ToolRenderLine[];
   /** Whether `/verbose` preview rules apply to the body. */
   previewBody: boolean;
 }
@@ -179,9 +179,36 @@ export interface ToolRenderLine {
   text: string;
 }
 
+/** A rendered conversation item plus its measured height. */
+export interface ConversationLogItem {
+  /** Rendered conversation node. */
+  node: Node;
+  /** Intrinsic item height in rows, excluding conversation gaps. */
+  height: number;
+}
+
+/** Rendered items plus cached cumulative intrinsic heights. */
+export interface ConversationLayoutSnapshot {
+  /** Rendered items in on-screen order. */
+  items: readonly ConversationLogItem[];
+  /** Cumulative intrinsic heights, excluding inter-item gaps. */
+  prefixHeights: readonly number[];
+}
+
+interface ConversationLayoutCache {
+  messages: readonly ConversationMessage[] | null;
+  count: number;
+  showReasoning: boolean;
+  verbose: boolean;
+  previewWidth: number;
+  cwd: string | null;
+  theme: Theme | null;
+  items: ConversationLogItem[];
+  prefixHeights: number[];
+}
+
 const EMPTY_STREAMING_CONTENT: AssistantMessage["content"] = [];
 const EMPTY_PENDING_TOOL_RESULTS: readonly PendingToolResult[] = [];
-const EMPTY_RENDER_NODES: Node[] = [];
 const EMPTY_TOOL_RESULT_ARGS: Record<string, unknown> = Object.freeze({});
 
 const toolCallArgsCache: ToolCallArgsCache = {
@@ -190,15 +217,21 @@ const toolCallArgsCache: ToolCallArgsCache = {
   entries: new Map(),
 };
 
-const conversationRenderCache: ConversationRenderCache = {
+let conversationMessageRenderCache = new WeakMap<
+  ConversationMessage,
+  ConversationMessageRenderCacheEntry
+>();
+
+const conversationLayoutCache: ConversationLayoutCache = {
   messages: null,
-  startIndex: 0,
   count: 0,
   showReasoning: false,
   verbose: false,
   previewWidth: DEFAULT_TOOL_PREVIEW_WIDTH,
+  cwd: null,
   theme: null,
-  nodes: EMPTY_RENDER_NODES,
+  items: [],
+  prefixHeights: [0],
 };
 
 /** Reset cached committed conversation renders. */
@@ -206,14 +239,16 @@ export function resetConversationRenderCache(): void {
   toolCallArgsCache.messages = null;
   toolCallArgsCache.count = 0;
   toolCallArgsCache.entries = new Map();
-  conversationRenderCache.messages = null;
-  conversationRenderCache.startIndex = 0;
-  conversationRenderCache.count = 0;
-  conversationRenderCache.showReasoning = false;
-  conversationRenderCache.verbose = false;
-  conversationRenderCache.previewWidth = DEFAULT_TOOL_PREVIEW_WIDTH;
-  conversationRenderCache.theme = null;
-  conversationRenderCache.nodes = EMPTY_RENDER_NODES;
+  conversationMessageRenderCache = new WeakMap();
+  conversationLayoutCache.messages = null;
+  conversationLayoutCache.count = 0;
+  conversationLayoutCache.showReasoning = false;
+  conversationLayoutCache.verbose = false;
+  conversationLayoutCache.previewWidth = DEFAULT_TOOL_PREVIEW_WIDTH;
+  conversationLayoutCache.cwd = null;
+  conversationLayoutCache.theme = null;
+  conversationLayoutCache.items = [];
+  conversationLayoutCache.prefixHeights = [0];
 }
 
 /** Render a user message with a subtle background. */
@@ -232,29 +267,24 @@ function renderUserMessage(msg: UserMessage, theme: Theme): Node {
 }
 
 /** Render a syntax-highlighted raw markdown block. */
-function renderMarkdownTextBlock(
-  content: string,
-  theme: Theme,
-  previewWidth?: number,
-): Node | null {
+function renderMarkdownTextBlock(content: string, theme: Theme): Node | null {
   if (content === "") {
     return null;
   }
 
-  const children = getHighlightedBodyLines(
+  const highlighted = getHighlightedBodyNode(
     {
       text: content,
       language: "markdown",
       themeVariant: "markdown",
     },
     theme,
-    getMarkdownBodyWidth(previewWidth),
   );
-  if (children.length === 0) {
+  if (!highlighted) {
     return null;
   }
 
-  return HStack({ padding: { x: 1 } }, [VStack({ flex: 1 }, children)]);
+  return HStack({ padding: { x: 1 } }, [VStack({ flex: 1 }, [highlighted])]);
 }
 
 function getAssistantErrorMessage(
@@ -324,7 +354,7 @@ function renderAssistantContentBlock(
   opts: ConversationRenderOpts,
 ): Node | null {
   if (block.type === "text" && block.text) {
-    return renderMarkdownTextBlock(block.text, opts.theme, opts.previewWidth);
+    return renderMarkdownTextBlock(block.text, opts.theme);
   }
   if (block.type === "thinking" && block.thinking) {
     return renderThinkingBlock(block.thinking, opts);
@@ -377,21 +407,10 @@ function getPreviewWidth(previewWidth?: number): number {
   return Math.max(1, Math.floor(previewWidth!));
 }
 
-function getMarkdownBodyWidth(previewWidth?: number): number {
-  return Math.max(
-    1,
-    getPreviewWidth(previewWidth) - MARKDOWN_BLOCK_CHROME_WIDTH,
-  );
-}
-
 function getToolBodyWidth(previewWidth?: number): number {
   return Math.max(1, getPreviewWidth(previewWidth) - TOOL_BLOCK_CHROME_WIDTH);
 }
 
-function getHighlightWrapChunkSize(bodyWidth: number): number {
-  return Math.max(1, Math.min(HIGHLIGHT_WRAP_MAX_CHUNK_GRAPHEMES, bodyWidth));
-}
-
 /** Split multi-line tool text into logical render lines. */
 function splitToolTextLines(
   text: string,
@@ -409,254 +428,228 @@ function splitToolTextLines(
   return lines.map((line) => ({ kind, text: line }));
 }
 
+function normalizeDisplayLineEndings(text: string): string {
+  return text.replace(/\r\n/g, "\n");
+}
+
 /** Read a string argument from a tool-call argument map. */
 function getToolArgString(args: Record<string, unknown>, key: string): string {
-  const value = args[key];
-  return typeof value === "string" ? value : "";
+  return readString(args, key) ?? "";
 }
 
-function formatTodoWriteCallSummary(args: Record<string, unknown>): string {
-  const todoCount = Array.isArray(args.todos) ? args.todos.length : 0;
-  const todoLabel = todoCount === 1 ? "todo" : "todos";
-  return `Updating todos... ${todoCount} ${todoLabel} updated`;
-}
+const HOME_DIR = homedir();
 
-/** Strip shell execution labels and normalize the exit line for the UI. */
-function normalizeShellOutput(output: string): string {
-  return output
-    .replace(/^Exit code: (\d+)(?:\n|$)/, (_, code: string) => `exit ${code}\n`)
-    .replace(/(^|\n)\[stderr\]\n/g, "$1")
-    .replace(/\n$/, "");
+function resolveToolPath(path: string, cwd?: string): string {
+  if (path === "") {
+    return "";
+  }
+  if (!cwd || isAbsolute(path)) {
+    return path;
+  }
+  return join(cwd, path);
 }
 
-function getToolHeaderName(toolName: string): string {
-  return toolName.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+function abbreviateHomePath(path: string): string {
+  if (path === HOME_DIR) {
+    return "~";
+  }
+  if (path.startsWith(`${HOME_DIR}/`)) {
+    return `~/${path.slice(HOME_DIR.length + 1)}`;
+  }
+  return path;
 }
 
-function getToolHeaderColor(toolName: string, theme: Theme) {
-  switch (toolName) {
-    case "shell":
-    case "readImage":
-    case "todoWrite":
-    case "todoRead":
-      return theme.accentText;
-    case "edit":
-      return theme.secondaryAccentText;
-    default:
-      return theme.secondaryAccentText ?? theme.toolText;
+function normalizeDisplayPath(path: string): string {
+  if (path === "") {
+    return path;
   }
+  return normalize(path).replace(/\\/g, "/");
 }
 
-type SyntaxThemeRegistration = Exclude<SyntaxHighlightTheme, string>;
-type SyntaxThemeTokenColor = NonNullable<
-  SyntaxThemeRegistration["tokenColors"]
->[number];
-
-const graphemeSegmenter = new Intl.Segmenter(undefined, {
-  granularity: "grapheme",
-});
-const HIGHLIGHT_WRAP_MAX_CHUNK_GRAPHEMES = 32;
-const syntaxThemeCache: Record<
-  SyntaxThemeVariant,
-  WeakMap<Theme, SyntaxThemeRegistration>
-> = {
-  markdown: new WeakMap(),
-  shell: new WeakMap(),
-};
-
-function colorToHex(color: Color | undefined): string | undefined {
-  return color ? ANSI_COLOR_HEX[color] : undefined;
+function formatResolvedToolPath(path: string, cwd?: string): string {
+  const resolved = resolveToolPath(path, cwd);
+  if (resolved === "") {
+    return path;
+  }
+  return abbreviateHomePath(normalizeDisplayPath(resolved));
 }
 
-function pushSyntaxTokenColor(
-  tokenColors: SyntaxThemeTokenColor[],
-  scope: string | readonly string[],
-  foreground: Color | undefined,
-  fontStyle?: string,
-): void {
-  const foregroundHex = colorToHex(foreground);
-  if (!foregroundHex && !fontStyle) {
-    return;
+function formatRelativeToolPath(path: string, cwd?: string): string {
+  const resolved = resolveToolPath(path, cwd);
+  if (resolved === "" || !cwd || !isAbsolute(resolved)) {
+    return normalizeDisplayPath(path);
   }
 
-  tokenColors.push({
-    scope,
-    settings: {
-      ...(foregroundHex ? { foreground: foregroundHex } : {}),
-      ...(fontStyle ? { fontStyle } : {}),
-    },
-  });
+  const relativePath = relative(cwd, resolved);
+  if (relativePath === "") {
+    return ".";
+  }
+  if (relativePath.startsWith("..")) {
+    return formatResolvedToolPath(resolved);
+  }
+  return normalizeDisplayPath(relativePath);
+}
+
+function getReadLanguageCandidates(path: string): string[] {
+  const fileName = basename(path).toLowerCase();
+  const extension = extname(fileName).toLowerCase();
+
+  switch (extension) {
+    case ".ts":
+      return ["typescript"];
+    case ".tsx":
+      return ["tsx", "typescript"];
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return ["javascript"];
+    case ".jsx":
+      return ["jsx", "javascript"];
+    case ".json":
+      return ["json"];
+    case ".md":
+      return ["markdown"];
+    case ".yml":
+    case ".yaml":
+      return ["yaml"];
+    case ".toml":
+      return ["toml"];
+    case ".sh":
+    case ".bash":
+      return ["bash"];
+    case ".css":
+      return ["css"];
+    case ".html":
+    case ".htm":
+      return ["html"];
+    case ".xml":
+      return ["xml"];
+    case ".py":
+      return ["python"];
+    case ".rs":
+      return ["rust"];
+    case ".go":
+      return ["go"];
+    case ".java":
+      return ["java"];
+    case ".c":
+      return ["c"];
+    case ".h":
+      return ["c"];
+    case ".cpp":
+    case ".cc":
+    case ".cxx":
+    case ".hpp":
+      return ["cpp"];
+    default:
+      break;
+  }
+
+  if (fileName === "dockerfile") {
+    return ["dockerfile"];
+  }
+  if (fileName === "makefile") {
+    return ["makefile"];
+  }
+  if (fileName === "agents.md" || fileName === "readme.md") {
+    return ["markdown"];
+  }
+  return [];
 }
 
-function pushShellSyntaxTokenColors(
-  tokenColors: SyntaxThemeTokenColor[],
-  theme: Theme,
-): void {
-  pushSyntaxTokenColor(tokenColors, "comment", theme.mutedText);
-  pushSyntaxTokenColor(
-    tokenColors,
-    ["keyword", "storage"],
-    theme.secondaryAccentText,
-  );
-  pushSyntaxTokenColor(
-    tokenColors,
-    [
-      "entity.name.function",
-      "function",
-      "meta.function-call",
-      "support.function",
-      "title",
-    ],
-    theme.accentText,
-  );
-  pushSyntaxTokenColor(
-    tokenColors,
-    [
-      "built_in",
-      "class",
-      "entity.name.type",
-      "entity.other.inherited-class",
-      "support.class",
-      "support.type",
-      "type",
-    ],
-    theme.accentText,
-  );
-  pushSyntaxTokenColor(
-    tokenColors,
-    ["constant.language", "constant.numeric", "literal", "symbol"],
-    theme.secondaryAccentText ?? theme.accentText,
-  );
-  pushSyntaxTokenColor(
-    tokenColors,
-    ["markup.inline", "string"],
-    theme.diffAdded,
-  );
-  pushSyntaxTokenColor(tokenColors, "regexp", theme.diffRemoved);
-  pushSyntaxTokenColor(
-    tokenColors,
-    ["attr", "attribute", "entity.other.attribute-name", "property"],
-    theme.accentText,
-  );
-  pushSyntaxTokenColor(
-    tokenColors,
-    ["entity.name.tag", "name", "tag"],
-    theme.accentText,
-  );
+function formatTodoWriteCallSummary(args: Record<string, unknown>): string {
+  const todoCount = Array.isArray(args.todos) ? args.todos.length : 0;
+  const todoLabel = todoCount === 1 ? "todo" : "todos";
+  return `Updating todos... ${todoCount} ${todoLabel} updated`;
 }
 
-function pushMarkdownSyntaxTokenColors(
-  tokenColors: SyntaxThemeTokenColor[],
-  theme: Theme,
-): void {
-  pushSyntaxTokenColor(tokenColors, "quote", theme.mutedText, "italic");
-  pushSyntaxTokenColor(tokenColors, "section", theme.accentText, "bold");
-  pushSyntaxTokenColor(
-    tokenColors,
-    "bullet",
-    theme.secondaryAccentText,
-    "bold",
+function parseShellToolContent(
+  content: ToolResultMessage["content"],
+  details?: ToolResultMessage["details"],
+) {
+  return (
+    parseShellResultDetails(details) ??
+    parseLegacyShellResult(getToolContentText(content))
   );
-  pushSyntaxTokenColor(tokenColors, ["code", "string"], theme.diffAdded);
-  pushSyntaxTokenColor(tokenColors, "link", theme.accentText, "underline");
-  pushSyntaxTokenColor(tokenColors, "strong", undefined, "bold");
-  pushSyntaxTokenColor(tokenColors, "emphasis", undefined, "italic");
 }
 
-function getSyntaxTheme(
-  theme: Theme,
-  variant: SyntaxThemeVariant,
-): SyntaxThemeRegistration {
-  const cache = syntaxThemeCache[variant];
-  const cached = cache.get(theme);
-  if (cached) {
-    return cached;
-  }
-
-  const tokenColors: SyntaxThemeTokenColor[] = [];
-  if (variant === "shell") {
-    pushShellSyntaxTokenColors(tokenColors, theme);
-  } else {
-    pushMarkdownSyntaxTokenColors(tokenColors, theme);
+function buildShellResultLines(
+  content: ToolResultMessage["content"],
+  details?: ToolResultMessage["details"],
+): { bodyLines: ToolRenderLine[]; footerLines?: ToolRenderLine[] } {
+  const result = parseShellToolContent(content, details);
+  if (!result) {
+    return {
+      bodyLines: splitToolTextLines(
+        normalizeDisplayLineEndings(getToolContentText(content)),
+        "text",
+      ),
+    };
   }
 
-  const syntaxTheme: SyntaxThemeRegistration = {
-    tokenColors,
-  };
-  cache.set(theme, syntaxTheme);
-  return syntaxTheme;
-}
+  const bodyLines: ToolRenderLine[] = [];
+  const stdout = normalizeDisplayLineEndings(result.stdout);
+  const stderr = normalizeDisplayLineEndings(result.stderr);
 
-function splitHighlightedTextNode(
-  node: Extract<Node, { type: "text" }>,
-  chunkSize: number,
-): Node[] {
-  if (node.content === "") {
-    return [Text("", node.props)];
+  if (stdout !== "") {
+    bodyLines.push(...splitToolTextLines(stdout, "text"));
   }
-
-  const parts = node.content.match(/\s+|\S+/gu);
-  if (!parts) {
-    return [Text(node.content, node.props)];
-  }
-
-  const children: Node[] = [];
-  for (const part of parts) {
-    if (/^\s+$/u.test(part)) {
-      children.push(Text(part, node.props));
-      continue;
-    }
-
-    let chunk = "";
-    let chunkGraphemes = 0;
-    for (const { segment } of graphemeSegmenter.segment(part)) {
-      chunk += segment;
-      chunkGraphemes += 1;
-
-      if (chunkGraphemes === chunkSize) {
-        children.push(Text(chunk, node.props));
-        chunk = "";
-        chunkGraphemes = 0;
-      }
-    }
-
-    if (chunk !== "") {
-      children.push(Text(chunk, node.props));
+  if (stderr !== "") {
+    if (bodyLines.length > 0) {
+      bodyLines.push({ kind: "text", text: "" });
     }
+    bodyLines.push(...splitToolTextLines(stderr, "text"));
+  }
+  if (bodyLines.length === 0) {
+    bodyLines.push({ kind: "summary", text: "(no output)" });
   }
 
-  return children;
+  return {
+    bodyLines,
+    footerLines: [
+      {
+        kind: "text",
+        text: `exit ${result.exitCode}`,
+      },
+    ],
+  };
 }
 
-function normalizeHighlightedLine(line: Node, bodyWidth: number): Node {
-  if (line.type !== "hstack") {
-    return line;
-  }
+function getToolHeaderName(toolName: string): string {
+  return toolName.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+}
 
-  const chunkSize = getHighlightWrapChunkSize(bodyWidth);
-  const children = line.children.flatMap((child) => {
-    return child.type === "text"
-      ? splitHighlightedTextNode(child, chunkSize)
-      : [child];
-  });
-  return HStack(line.props, children);
+function getToolHeaderColor(toolName: string, theme: Theme) {
+  switch (toolName) {
+    case "shell":
+    case "read":
+    case "grep":
+    case "readImage":
+    case "todoWrite":
+    case "todoRead":
+      return theme.accentText;
+    case "edit":
+      return theme.secondaryAccentText;
+    default:
+      return theme.secondaryAccentText ?? theme.toolText;
+  }
 }
 
-function getHighlightedBodyLines(
+function getHighlightedBodyNode(
   spec: HighlightedBodySpec,
   theme: Theme,
-  bodyWidth: number,
-): Node[] {
+): Node | null {
   if (spec.text === "") {
-    return [];
+    return null;
   }
 
-  const highlighted = SyntaxHighlight(spec.text, spec.language, {
-    theme: getSyntaxTheme(theme, spec.themeVariant),
-  });
-  return highlighted.children.map((line) =>
-    normalizeHighlightedLine(line, bodyWidth),
-  );
+  try {
+    return SyntaxHighlight(spec.text, spec.language, {
+      theme: getSyntaxHighlightTheme(theme, spec.themeVariant),
+    });
+  } catch {
+    return null;
+  }
 }
 
 /** Render a single styled text node for a tool line. */
@@ -673,6 +666,11 @@ function renderToolLine(line: ToolRenderLine, theme: Theme): Node {
       return Text(line.text, { fgColor: theme.diffAdded, wrap: "word" });
     case "diffRemoved":
       return Text(line.text, { fgColor: theme.diffRemoved, wrap: "word" });
+    case "context":
+      return Text(line.text, {
+        fgColor: theme.mutedText,
+        wrap: "word",
+      });
     case "summary":
       return Text(line.text, {
         fgColor: theme.toolText,
@@ -682,7 +680,10 @@ function renderToolLine(line: ToolRenderLine, theme: Theme): Node {
     case "error":
       return Text(line.text, { fgColor: theme.error, wrap: "word" });
     case "text":
-      return Text(line.text, { wrap: "word" });
+      return Text(line.text, {
+        fgColor: theme.toolText,
+        wrap: "word",
+      });
   }
 }
 
@@ -736,36 +737,58 @@ function renderTodoChecklist(todos: readonly TodoItem[], theme: Theme): Node {
   );
 }
 
-function measureToolNodesHeight(lines: readonly Node[], width: number): number {
-  if (lines.length === 0) {
-    return 0;
+function measureToolNodeHeight(node: Node, width: number): number {
+  return measureContentHeight(VStack({}, [node]), { width });
+}
+
+function renderFullToolBody(spec: ToolBlockSpec, theme: Theme): Node | null {
+  if (spec.highlightedBody) {
+    const highlighted = getHighlightedBodyNode(spec.highlightedBody, theme);
+    if (highlighted) {
+      return highlighted;
+    }
   }
 
-  return measureContentHeight(VStack({}, [...lines]), { width });
-}
+  if (spec.bodyLines.length === 0) {
+    return null;
+  }
 
-function measureToolNodeHeight(line: Node, width: number): number {
-  return measureContentHeight(VStack({}, [line]), { width });
+  return VStack({}, renderToolLines(spec.bodyLines, theme));
 }
 
-function countVisibleTailNodes(
-  lines: readonly Node[],
-  width: number,
-  maxRows: number,
-): number {
-  let remainingRows = maxRows;
-  let visibleLineCount = 0;
+function renderToolBodyLines(
+  spec: ToolBlockSpec,
+  lines: readonly ToolRenderLine[],
+  theme: Theme,
+): Node | null {
+  if (lines.length === 0) {
+    return null;
+  }
 
-  for (let index = lines.length - 1; index >= 0; index--) {
-    const lineHeight = measureToolNodeHeight(lines[index]!, width);
-    if (lineHeight > remainingRows) {
-      return visibleLineCount > 0 ? visibleLineCount : 1;
+  if (spec.highlightedBody) {
+    const highlighted = getHighlightedBodyNode(
+      {
+        ...spec.highlightedBody,
+        text: lines.map((line) => line.text).join("\n"),
+      },
+      theme,
+    );
+    if (highlighted) {
+      return highlighted;
     }
-    remainingRows -= lineHeight;
-    visibleLineCount += 1;
   }
 
-  return visibleLineCount;
+  return VStack({}, renderToolLines(lines, theme));
+}
+
+function wrapToolPreviewBody(body: Node): Node {
+  return VStack(
+    {
+      height: UI_TOOL_PREVIEW_ROWS,
+      justifyContent: "end",
+    },
+    body.type === "vstack" ? [...body.children] : [body],
+  );
 }
 
 function renderToolHeaderPill(
@@ -781,49 +804,64 @@ function renderToolHeaderPill(
   ]);
 }
 
-function renderToolBodyFromNodes(
-  lines: readonly Node[],
-  previewBody: boolean,
-  opts: Pick<ConversationRenderOpts, "previewWidth" | "theme" | "verbose">,
-): { body: Node | null; summary?: ToolRenderLine } {
-  if (lines.length === 0) {
-    return { body: null };
+function renderToolHeaderRow(spec: ToolBlockSpec, theme: Theme): Node {
+  const children: Node[] = [
+    renderToolHeaderPill(spec.toolName, spec.direction, theme),
+  ];
+
+  if (spec.headerSuffix) {
+    children.push(
+      Text(` ${spec.headerSuffix}`, {
+        fgColor: theme.toolText,
+        wrap: "word",
+      }),
+    );
   }
 
-  if (opts.verbose || !previewBody) {
-    return { body: VStack({}, [...lines]) };
+  return HStack({}, children);
+}
+
+function renderCompactToolBody(
+  spec: ToolBlockSpec,
+  opts: Pick<ConversationRenderOpts, "previewWidth" | "theme">,
+): { body: Node | null; summary?: ToolRenderLine } {
+  if (spec.bodyLines.length === 0) {
+    return { body: null };
   }
 
   const bodyWidth = getToolBodyWidth(opts.previewWidth);
-  const totalHeight = measureToolNodesHeight(lines, bodyWidth);
-  if (totalHeight <= UI_TOOL_PREVIEW_ROWS) {
-    return { body: VStack({}, [...lines]) };
-  }
+  let previewStart = Math.max(0, spec.bodyLines.length - UI_TOOL_PREVIEW_ROWS);
 
-  const visibleLineCount = countVisibleTailNodes(
-    lines,
-    bodyWidth,
-    UI_TOOL_PREVIEW_ROWS,
-  );
-  const previewLines = lines.slice(-visibleLineCount);
-  const hiddenLineCount = Math.max(0, lines.length - visibleLineCount);
+  for (;;) {
+    const previewLines = spec.bodyLines.slice(previewStart);
+    const previewBody = renderToolBodyLines(spec, previewLines, opts.theme);
+    if (!previewBody) {
+      return { body: null };
+    }
 
-  return {
-    body: VStack(
-      {
-        height: UI_TOOL_PREVIEW_ROWS,
-        justifyContent: "end",
-      },
-      [...previewLines],
-    ),
-    summary:
-      hiddenLineCount > 0
-        ? {
-            kind: "summary",
-            text: `And ${hiddenLineCount} lines more`,
-          }
-        : undefined,
-  };
+    const previewHeight = measureToolNodeHeight(previewBody, bodyWidth);
+    if (
+      previewHeight <= UI_TOOL_PREVIEW_ROWS ||
+      previewStart >= spec.bodyLines.length - 1
+    ) {
+      const hiddenLineCount = previewStart;
+      return {
+        body:
+          hiddenLineCount > 0 || previewHeight > UI_TOOL_PREVIEW_ROWS
+            ? wrapToolPreviewBody(previewBody)
+            : previewBody,
+        summary:
+          hiddenLineCount > 0
+            ? {
+                kind: "summary",
+                text: `And ${hiddenLineCount} lines more`,
+              }
+            : undefined,
+      };
+    }
+
+    previewStart += 1;
+  }
 }
 
 function renderToolBody(
@@ -834,23 +872,13 @@ function renderToolBody(
     return { body: spec.bodyNode };
   }
 
-  if (spec.highlightedBody) {
-    return renderToolBodyFromNodes(
-      getHighlightedBodyLines(
-        spec.highlightedBody,
-        opts.theme,
-        getToolBodyWidth(opts.previewWidth),
-      ),
-      spec.previewBody,
-      opts,
-    );
+  if (opts.verbose || !spec.previewBody) {
+    return {
+      body: renderFullToolBody(spec, opts.theme),
+    };
   }
 
-  return renderToolBodyFromNodes(
-    renderToolLines(spec.bodyLines, opts.theme),
-    spec.previewBody,
-    opts,
-  );
+  return renderCompactToolBody(spec, opts);
 }
 
 /** Render a tool block with a left border and compact header pill. */
@@ -859,11 +887,7 @@ function renderToolBlock(
   opts: Pick<ConversationRenderOpts, "previewWidth" | "theme" | "verbose">,
 ): Node {
   const body = renderToolBody(spec, opts);
-  const children: Node[] = [
-    HStack({}, [
-      renderToolHeaderPill(spec.toolName, spec.direction, opts.theme),
-    ]),
-  ];
+  const children: Node[] = [renderToolHeaderRow(spec, opts.theme)];
 
   if (body.body) {
     children.push(body.body);
@@ -871,18 +895,41 @@ function renderToolBlock(
   if (body.summary) {
     children.push(renderToolLine(body.summary, opts.theme));
   }
+  if (spec.footerLines) {
+    children.push(...renderToolLines(spec.footerLines, opts.theme));
+  }
 
   return HStack({ padding: { x: 1 } }, [
     Text("│ ", { fgColor: opts.theme.toolBorder }),
-    VStack({ flex: 1, fgColor: opts.theme.toolText }, children),
+    VStack({ flex: 1 }, children),
   ]);
 }
 
-function getToolContentText(content: ToolResultMessage["content"]): string {
+function getToolTextBlocks(content: ToolResultMessage["content"]): string[] {
   return content
     .filter((entry): entry is TextContent => entry.type === "text")
-    .map((entry) => entry.text)
-    .join("\n");
+    .map((entry) => entry.text);
+}
+
+function getToolContentText(content: ToolResultMessage["content"]): string {
+  return getToolTextBlocks(content).join("\n");
+}
+
+function parseReadToolContent(
+  content: ToolResultMessage["content"],
+): ReturnType<typeof parseReadResult> {
+  const textBlocks = getToolTextBlocks(content);
+  if (textBlocks.length > 1) {
+    const continuation = parseReadContinuationHint(textBlocks.at(-1) ?? "");
+    if (continuation) {
+      return {
+        body: textBlocks.slice(0, -1).join("\n"),
+        continuation,
+      };
+    }
+  }
+
+  return parseReadResult(textBlocks.join("\n"));
 }
 
 function buildShellToolCallSpec(args: Record<string, unknown>): ToolBlockSpec {
@@ -903,6 +950,70 @@ function buildShellToolCallSpec(args: Record<string, unknown>): ToolBlockSpec {
   };
 }
 
+function buildReadToolCallSpec(args: Record<string, unknown>): ToolBlockSpec {
+  const lines: ToolRenderLine[] = [];
+  const filePath = getToolArgString(args, "path");
+  const offset = readFiniteNumber(args, "offset");
+  const limit = readFiniteNumber(args, "limit");
+
+  if (filePath) {
+    lines.push({ kind: "path", text: filePath });
+  }
+  if (offset !== null) {
+    lines.push({ kind: "text", text: `offset: ${offset}` });
+  }
+  if (limit !== null) {
+    lines.push({ kind: "text", text: `limit: ${limit}` });
+  }
+
+  return {
+    toolName: "read",
+    direction: "->",
+    bodyLines: lines,
+    previewBody: true,
+  };
+}
+
+function buildGrepToolCallSpec(args: Record<string, unknown>): ToolBlockSpec {
+  const lines: ToolRenderLine[] = [];
+  const pattern = getToolArgString(args, "pattern");
+  const path = getToolArgString(args, "path");
+  const glob = getToolArgString(args, "glob");
+  const context = readFiniteNumber(args, "context");
+  const limit = readFiniteNumber(args, "limit");
+  const ignoreCase = readBoolean(args, "ignoreCase");
+  const literal = readBoolean(args, "literal");
+
+  if (pattern) {
+    lines.push({ kind: "command", text: pattern });
+  }
+  if (path) {
+    lines.push({ kind: "text", text: `path: ${path}` });
+  }
+  if (glob) {
+    lines.push({ kind: "text", text: `glob: ${glob}` });
+  }
+  if (ignoreCase) {
+    lines.push({ kind: "text", text: "ignoreCase: true" });
+  }
+  if (literal) {
+    lines.push({ kind: "text", text: "literal: true" });
+  }
+  if (context !== null) {
+    lines.push({ kind: "text", text: `context: ${context}` });
+  }
+  if (limit !== null) {
+    lines.push({ kind: "text", text: `limit: ${limit}` });
+  }
+
+  return {
+    toolName: "grep",
+    direction: "->",
+    bodyLines: lines,
+    previewBody: true,
+  };
+}
+
 function buildEditToolCallSpec(args: Record<string, unknown>): ToolBlockSpec {
   const lines: ToolRenderLine[] = [];
   const filePath = getToolArgString(args, "path");
@@ -947,6 +1058,10 @@ function buildReadImageToolCallSpec(
   };
 }
 
+function isMcpToolName(toolName: string): boolean {
+  return toolName.includes("__");
+}
+
 function buildGenericToolCallSpec(
   toolName: string,
   args: Record<string, unknown>,
@@ -956,7 +1071,7 @@ function buildGenericToolCallSpec(
     toolName,
     direction: "->",
     bodyLines: text && text !== "{}" ? splitToolTextLines(text, "text") : [],
-    previewBody: false,
+    previewBody: isMcpToolName(toolName),
   };
 }
 
@@ -967,6 +1082,12 @@ function buildToolCallSpec(
   if (toolName === "shell") {
     return buildShellToolCallSpec(args);
   }
+  if (toolName === "read") {
+    return buildReadToolCallSpec(args);
+  }
+  if (toolName === "grep") {
+    return buildGrepToolCallSpec(args);
+  }
   if (toolName === "edit") {
     return buildEditToolCallSpec(args);
   }
@@ -991,14 +1112,119 @@ function renderToolCall(
 
 function buildShellToolResultSpec(
   content: ToolResultMessage["content"],
+  details?: ToolResultMessage["details"],
 ): ToolBlockSpec {
+  const shellResult = buildShellResultLines(content, details);
   return {
     toolName: "shell",
     direction: "<-",
-    bodyLines: splitToolTextLines(
-      normalizeShellOutput(getToolContentText(content)),
-      "text",
-    ),
+    bodyLines: shellResult.bodyLines,
+    ...(shellResult.footerLines
+      ? { footerLines: shellResult.footerLines }
+      : {}),
+    previewBody: true,
+  };
+}
+
+function buildReadToolResultSpec(
+  args: Record<string, unknown>,
+  content: ToolResultMessage["content"],
+  isError: boolean,
+  cwd?: string,
+): ToolBlockSpec {
+  const filePath = getToolArgString(args, "path");
+  const resolvedPath = formatResolvedToolPath(filePath, cwd);
+  const resultText = getToolContentText(content);
+
+  if (isError) {
+    return {
+      toolName: "read",
+      direction: "<-",
+      ...(resolvedPath ? { headerSuffix: resolvedPath } : {}),
+      bodyLines: splitToolTextLines(
+        normalizeDisplayLineEndings(resultText),
+        "error",
+      ),
+      previewBody: true,
+    };
+  }
+
+  const parsed = parseReadToolContent(content);
+  const bodyText = parsed.body;
+  const displayBodyText = normalizeDisplayLineEndings(bodyText);
+  const language = getReadLanguageCandidates(resolveToolPath(filePath, cwd))[0];
+  return {
+    toolName: "read",
+    direction: "<-",
+    ...(resolvedPath ? { headerSuffix: resolvedPath } : {}),
+    bodyLines:
+      displayBodyText === ""
+        ? [{ kind: "summary", text: "Empty file." }]
+        : splitToolTextLines(displayBodyText, "text"),
+    ...(bodyText !== "" && language
+      ? {
+          highlightedBody: {
+            text: bodyText,
+            language,
+            themeVariant: "code" as const,
+          },
+        }
+      : {}),
+    previewBody: true,
+  };
+}
+
+function buildGrepToolResultSpec(
+  content: ToolResultMessage["content"],
+  isError: boolean,
+  cwd?: string,
+): ToolBlockSpec {
+  const resultText = getToolContentText(content);
+  if (isError) {
+    return {
+      toolName: "grep",
+      direction: "<-",
+      bodyLines: splitToolTextLines(resultText, "error"),
+      previewBody: true,
+    };
+  }
+
+  const result = parseGrepResult(resultText);
+  if (!result) {
+    return {
+      toolName: "grep",
+      direction: "<-",
+      bodyLines: splitToolTextLines(resultText, "text"),
+      previewBody: true,
+    };
+  }
+
+  const lines: ToolRenderLine[] = [];
+  for (const file of result.files) {
+    lines.push({
+      kind: "path",
+      text: formatRelativeToolPath(file.path, cwd),
+    });
+    for (const line of file.lines) {
+      const text = line.text.replace(/\r?\n$/, "");
+      lines.push({
+        kind: line.kind === "context" ? "context" : "text",
+        text: `  ${line.lineNumber}: ${text}`,
+      });
+    }
+  }
+
+  if (lines.length === 0) {
+    lines.push({ kind: "summary", text: "No matches found." });
+  }
+
+  return {
+    toolName: "grep",
+    direction: "<-",
+    bodyLines: lines,
+    ...(result.hint
+      ? { footerLines: [{ kind: "summary", text: result.hint }] }
+      : {}),
     previewBody: true,
   };
 }
@@ -1083,7 +1309,7 @@ function buildGenericToolResultSpec(
     toolName,
     direction: "<-",
     bodyLines: splitToolTextLines(output, isError ? "error" : "text"),
-    previewBody: false,
+    previewBody: isMcpToolName(toolName),
   };
 }
 
@@ -1092,10 +1318,26 @@ function renderToolResultContent(
   args: Record<string, unknown>,
   content: ToolResultMessage["content"],
   isError: boolean,
-  opts: Pick<ConversationRenderOpts, "previewWidth" | "verbose" | "theme">,
+  opts: Pick<
+    ConversationRenderOpts,
+    "previewWidth" | "verbose" | "theme" | "cwd"
+  >,
+  details?: ToolResultMessage["details"],
 ): Node {
   if (toolName === "shell") {
-    return renderToolBlock(buildShellToolResultSpec(content), opts);
+    return renderToolBlock(buildShellToolResultSpec(content, details), opts);
+  }
+  if (toolName === "read") {
+    return renderToolBlock(
+      buildReadToolResultSpec(args, content, isError, opts.cwd),
+      opts,
+    );
+  }
+  if (toolName === "grep") {
+    return renderToolBlock(
+      buildGrepToolResultSpec(content, isError, opts.cwd),
+      opts,
+    );
   }
   if (toolName === "edit") {
     return renderToolBlock(
@@ -1130,6 +1372,7 @@ function renderToolResultContent(
  * @param resultText - Text content from the tool result message.
  * @param isError - Whether the tool execution failed.
  * @param opts - Shared conversation render options.
+ * @param details - Optional structured tool-result details.
  * @returns The rendered tool block node.
  */
 export function renderToolResult(
@@ -1138,12 +1381,20 @@ export function renderToolResult(
   resultText: string,
   isError: boolean,
   opts: ConversationRenderOpts,
+  details?: ToolResultMessage["details"],
 ): Node {
   const content: ToolResultMessage["content"] = resultText
     ? [{ type: "text", text: resultText }]
     : [];
 
-  return renderToolResultContent(toolName, args, content, isError, opts);
+  return renderToolResultContent(
+    toolName,
+    args,
+    content,
+    isError,
+    opts,
+    details,
+  );
 }
 
 function renderUiTodoMessage(
@@ -1170,11 +1421,7 @@ function renderUiMessage(
   }
 
   if (msg.format === "markdown") {
-    const markdown = renderMarkdownTextBlock(
-      msg.content,
-      opts.theme,
-      opts.previewWidth,
-    );
+    const markdown = renderMarkdownTextBlock(msg.content, opts.theme);
     if (markdown) {
       return markdown;
     }
@@ -1206,13 +1453,6 @@ function renderEmptyConversationBanner(
   ]);
 }
 
-function pushConversationNode(nodes: Node[], node: Node | null): void {
-  if (!node) {
-    return;
-  }
-  nodes.push(node);
-}
-
 function rememberToolCallArgs(
   message: AssistantMessage,
   toolCallArgs: Map<string, ToolCallRenderInfo>,
@@ -1234,8 +1474,16 @@ function renderToolResultMessage(
   content: ToolResultMessage["content"],
   isError: boolean,
   renderOpts: ConversationRenderOpts,
+  details?: ToolResultMessage["details"],
 ): Node {
-  return renderToolResultContent(toolName, args, content, isError, renderOpts);
+  return renderToolResultContent(
+    toolName,
+    args,
+    content,
+    isError,
+    renderOpts,
+    details,
+  );
 }
 
 function renderConversationMessage(
@@ -1262,6 +1510,7 @@ function renderConversationMessage(
     message.content,
     message.isError,
     renderOpts,
+    message.details,
   );
 }
 
@@ -1285,58 +1534,150 @@ function cacheToolCallArgs(messages: readonly ConversationMessage[]): void {
   toolCallArgsCache.count = messages.length;
 }
 
-function canReuseCommittedConversationCache(
-  state: ConversationLogState,
-  startIndex: number,
+function canReuseConversationMessageRender(
+  cached: ConversationMessageRenderCacheEntry | undefined,
+  renderOpts: ConversationRenderOpts,
   previewWidth: number,
-): boolean {
+): cached is ConversationMessageRenderCacheEntry {
   return (
-    conversationRenderCache.messages === state.messages &&
-    conversationRenderCache.startIndex === startIndex &&
-    conversationRenderCache.showReasoning === state.showReasoning &&
-    conversationRenderCache.verbose === state.verbose &&
-    conversationRenderCache.previewWidth === previewWidth &&
-    conversationRenderCache.theme === state.theme &&
-    conversationRenderCache.count <= state.messages.length
+    cached !== undefined &&
+    cached.showReasoning === renderOpts.showReasoning &&
+    cached.verbose === renderOpts.verbose &&
+    cached.previewWidth === previewWidth &&
+    cached.cwd === renderOpts.cwd &&
+    cached.theme === renderOpts.theme
   );
 }
 
-function cacheCommittedConversation(
+function canReuseCommittedConversationLayout(
   state: ConversationLogState,
   renderOpts: ConversationRenderOpts,
-  startIndex: number,
+  previewWidth: number,
+): boolean {
+  return (
+    conversationLayoutCache.messages === state.messages &&
+    conversationLayoutCache.count <= state.messages.length &&
+    conversationLayoutCache.showReasoning === renderOpts.showReasoning &&
+    conversationLayoutCache.verbose === renderOpts.verbose &&
+    conversationLayoutCache.previewWidth === previewWidth &&
+    conversationLayoutCache.cwd === renderOpts.cwd &&
+    conversationLayoutCache.theme === renderOpts.theme
+  );
+}
+
+function appendConversationLogItem(
+  items: ConversationLogItem[],
+  prefixHeights: number[],
+  item: ConversationLogItem | null,
 ): void {
+  if (!item) {
+    return;
+  }
+
+  items.push(item);
+  prefixHeights.push(prefixHeights[prefixHeights.length - 1]! + item.height);
+}
+
+function measureConversationItemHeight(
+  node: Node,
+  previewWidth: number,
+): number {
+  return measureContentHeight(node, {
+    width: getPreviewWidth(previewWidth),
+  });
+}
+
+function createConversationLogItem(
+  node: Node | null,
+  previewWidth: number,
+): ConversationLogItem | null {
+  if (!node) {
+    return null;
+  }
+
+  return {
+    node,
+    height: measureConversationItemHeight(node, previewWidth),
+  };
+}
+
+function getCommittedConversationLogItem(
+  message: ConversationMessage,
+  renderOpts: ConversationRenderOpts,
+): ConversationLogItem | null {
   const previewWidth = getPreviewWidth(renderOpts.previewWidth);
-  cacheToolCallArgs(state.messages);
+  const cached = conversationMessageRenderCache.get(message);
+  if (canReuseConversationMessageRender(cached, renderOpts, previewWidth)) {
+    if (!cached.node) {
+      return null;
+    }
+    return {
+      node: cached.node,
+      height: cached.height,
+    };
+  }
+
+  const node = renderConversationMessage(
+    message,
+    renderOpts,
+    toolCallArgsCache.entries,
+    renderOpts.theme,
+  );
+  const nextEntry: ConversationMessageRenderCacheEntry = {
+    node,
+    height: node ? measureConversationItemHeight(node, previewWidth) : 0,
+    showReasoning: renderOpts.showReasoning,
+    verbose: renderOpts.verbose,
+    previewWidth,
+    cwd: renderOpts.cwd ?? null,
+    theme: renderOpts.theme,
+  };
+  conversationMessageRenderCache.set(message, nextEntry);
+
+  if (!node) {
+    return null;
+  }
+
+  return {
+    node,
+    height: nextEntry.height,
+  };
+}
 
-  if (!canReuseCommittedConversationCache(state, startIndex, previewWidth)) {
-    conversationRenderCache.messages = state.messages;
-    conversationRenderCache.startIndex = startIndex;
-    conversationRenderCache.count = startIndex;
-    conversationRenderCache.showReasoning = state.showReasoning;
-    conversationRenderCache.verbose = state.verbose;
-    conversationRenderCache.previewWidth = previewWidth;
-    conversationRenderCache.theme = state.theme;
-    conversationRenderCache.nodes = [];
+function getCommittedConversationLayoutSnapshot(
+  state: ConversationLogState,
+  renderOpts: ConversationRenderOpts,
+): ConversationLayoutSnapshot {
+  const previewWidth = getPreviewWidth(renderOpts.previewWidth);
+  if (!canReuseCommittedConversationLayout(state, renderOpts, previewWidth)) {
+    conversationLayoutCache.messages = state.messages;
+    conversationLayoutCache.count = 0;
+    conversationLayoutCache.showReasoning = renderOpts.showReasoning;
+    conversationLayoutCache.verbose = renderOpts.verbose;
+    conversationLayoutCache.previewWidth = previewWidth;
+    conversationLayoutCache.cwd = renderOpts.cwd ?? null;
+    conversationLayoutCache.theme = renderOpts.theme;
+    conversationLayoutCache.items = [];
+    conversationLayoutCache.prefixHeights = [0];
   }
 
   for (
-    let index = conversationRenderCache.count;
+    let index = conversationLayoutCache.count;
     index < state.messages.length;
     index++
   ) {
-    pushConversationNode(
-      conversationRenderCache.nodes,
-      renderConversationMessage(
-        state.messages[index]!,
-        renderOpts,
-        toolCallArgsCache.entries,
-        state.theme,
-      ),
+    appendConversationLogItem(
+      conversationLayoutCache.items,
+      conversationLayoutCache.prefixHeights,
+      getCommittedConversationLogItem(state.messages[index]!, renderOpts),
     );
   }
 
-  conversationRenderCache.count = state.messages.length;
+  conversationLayoutCache.count = state.messages.length;
+  return {
+    items: conversationLayoutCache.items,
+    prefixHeights: conversationLayoutCache.prefixHeights,
+  };
 }
 
 function hasStreamingTail(streaming: StreamingConversationState): boolean {
@@ -1347,67 +1688,149 @@ function hasStreamingTail(streaming: StreamingConversationState): boolean {
   );
 }
 
+function appendStreamingConversationLogItems(
+  items: ConversationLogItem[],
+  prefixHeights: number[],
+  streaming: StreamingConversationState,
+  renderOpts: ConversationRenderOpts,
+  previewWidth: number,
+): void {
+  appendConversationLogItem(
+    items,
+    prefixHeights,
+    createConversationLogItem(
+      renderAssistantMessage(
+        {
+          content: streaming.content,
+        },
+        renderOpts,
+      ),
+      previewWidth,
+    ),
+  );
+
+  for (const pendingToolResult of streaming.pendingToolResults) {
+    const info = toolCallArgsCache.entries.get(pendingToolResult.toolCallId);
+    appendConversationLogItem(
+      items,
+      prefixHeights,
+      createConversationLogItem(
+        renderToolResultMessage(
+          info?.name ?? pendingToolResult.toolName,
+          info?.args ?? EMPTY_TOOL_RESULT_ARGS,
+          pendingToolResult.content,
+          pendingToolResult.isError,
+          renderOpts,
+          pendingToolResult.details,
+        ),
+        previewWidth,
+      ),
+    );
+  }
+}
+
+function buildEmptyConversationBannerSnapshot(
+  state: ConversationLogState,
+  previewWidth: number,
+): ConversationLayoutSnapshot {
+  const banner = renderEmptyConversationBanner(
+    state.theme,
+    state.versionLabel ?? DEV_VERSION_LABEL,
+  );
+  const item = {
+    node: banner,
+    height: measureConversationItemHeight(banner, previewWidth),
+  };
+  return {
+    items: [item],
+    prefixHeights: [0, item.height],
+  };
+}
+
 /**
- * Build the full conversation log as an array of nodes.
+ * Build rendered conversation items plus cached cumulative intrinsic heights.
  *
  * @param state - Conversation rendering state.
  * @param streaming - Current in-progress assistant tail, if any.
- * @param startIndex - Index of the first committed message to render.
  * @param previewWidth - Available terminal width for width-aware tool previews.
- * @returns The rendered conversation log nodes.
+ * @returns Rendered items plus cumulative heights in on-screen order.
  */
-export function buildConversationLogNodes(
+export function buildConversationLayoutSnapshot(
   state: ConversationLogState,
   streaming: StreamingConversationState,
-  startIndex = 0,
   previewWidth = DEFAULT_TOOL_PREVIEW_WIDTH,
-): Node[] {
+): ConversationLayoutSnapshot {
   const renderOpts: ConversationRenderOpts = {
     showReasoning: state.showReasoning,
     verbose: state.verbose,
     theme: state.theme,
+    cwd: state.cwd,
     previewWidth,
   };
 
-  if (state.messages.length === 0 && !hasStreamingTail(streaming)) {
-    return [
-      renderEmptyConversationBanner(
-        state.theme,
-        state.versionLabel ?? DEV_VERSION_LABEL,
-      ),
-    ];
-  }
-
-  cacheCommittedConversation(state, renderOpts, startIndex);
+  cacheToolCallArgs(state.messages);
 
-  if (!hasStreamingTail(streaming)) {
-    return conversationRenderCache.nodes;
+  const committedSnapshot = getCommittedConversationLayoutSnapshot(
+    state,
+    renderOpts,
+  );
+  const streamingTailVisible = hasStreamingTail(streaming);
+  if (!streamingTailVisible) {
+    if (committedSnapshot.items.length > 0 || state.messages.length > 0) {
+      return committedSnapshot;
+    }
+    return buildEmptyConversationBannerSnapshot(state, previewWidth);
   }
 
-  const nodes = [...conversationRenderCache.nodes];
-  pushConversationNode(
-    nodes,
-    renderAssistantMessage(
-      {
-        content: streaming.content,
-      },
-      renderOpts,
-    ),
+  const items = [...committedSnapshot.items];
+  const prefixHeights = [...committedSnapshot.prefixHeights];
+  appendStreamingConversationLogItems(
+    items,
+    prefixHeights,
+    streaming,
+    renderOpts,
+    previewWidth,
   );
+  return {
+    items,
+    prefixHeights,
+  };
+}
 
-  for (const pendingToolResult of streaming.pendingToolResults) {
-    const info = toolCallArgsCache.entries.get(pendingToolResult.toolCallId);
-    pushConversationNode(
-      nodes,
-      renderToolResultMessage(
-        info?.name ?? pendingToolResult.toolName,
-        info?.args ?? EMPTY_TOOL_RESULT_ARGS,
-        pendingToolResult.content,
-        pendingToolResult.isError,
-        renderOpts,
-      ),
-    );
-  }
+/**
+ * Build the rendered conversation items with cached per-message nodes/heights.
+ *
+ * @param state - Conversation rendering state.
+ * @param streaming - Current in-progress assistant tail, if any.
+ * @param previewWidth - Available terminal width for width-aware tool previews.
+ * @returns Rendered items in on-screen order.
+ */
+export function buildConversationLogItems(
+  state: ConversationLogState,
+  streaming: StreamingConversationState,
+  previewWidth = DEFAULT_TOOL_PREVIEW_WIDTH,
+): readonly ConversationLogItem[] {
+  return buildConversationLayoutSnapshot(state, streaming, previewWidth).items;
+}
 
-  return nodes;
+/**
+ * Build the full conversation log as an array of nodes.
+ *
+ * @param state - Conversation rendering state.
+ * @param streaming - Current in-progress assistant tail, if any.
+ * @param startIndex - Index of the first rendered item to include.
+ * @param previewWidth - Available terminal width for width-aware tool previews.
+ * @param endIndex - Exclusive rendered-item end index.
+ * @returns The rendered conversation log nodes.
+ */
+export function buildConversationLogNodes(
+  state: ConversationLogState,
+  streaming: StreamingConversationState,
+  startIndex = 0,
+  previewWidth = DEFAULT_TOOL_PREVIEW_WIDTH,
+  endIndex = Number.POSITIVE_INFINITY,
+): Node[] {
+  return buildConversationLogItems(state, streaming, previewWidth)
+    .slice(startIndex, endIndex)
+    .map((item) => item.node);
 }