@golba98/codexa 1.0.3 → 1.0.4

package/src/commands/handler.ts

@@ -36,7 +36,7 @@ import {
   type WorkspaceDisplayMode,
 } from "../config/settings.js";
 
-import type { WorkspaceCommandContext } from "../core/launchContext.js";
+import type { WorkspaceCommandContext } from "../core/workspace/launchContext.js";
 import {
   findModelCapability,
   formatModelCapabilitiesList,
@@ -120,7 +120,7 @@ export interface CommandContext {
   modelCapabilities?: CodexModelCapabilities | null;
   routeStatusMessage?: string;
   activeRouteProviderLabel?: string;
-  projectInstructions?: import("../core/projectInstructions.js").ProjectInstructionsLoadResult | null;
+  projectInstructions?: import("../core/workspace/projectInstructions.js").ProjectInstructionsLoadResult | null;
 }
 
 // Mirrors AVAILABLE_APPROVAL_POLICIES[].id from runtimeConfig.ts

package/src/config/buildInfo.ts

@@ -1,3 +1,3 @@
 // Generated by scripts/gen-build-info.mjs — do not edit manually.
-export const BUILD_COMMIT = "f4940aa066eae20c0b8decb1fb70f02aca0f2dc0" as const;
-export const APP_VERSION = "1.0.3" as const;
+export const BUILD_COMMIT = "b066a15b77696d2a0945ea7c6c3d07630584296b" as const;
+export const APP_VERSION = "1.0.4" as const;

package/src/config/layeredConfig.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { normalizeWorkspaceRoot } from "../core/workspaceRoot.js";
+import { normalizeWorkspaceRoot } from "../core/workspace/workspaceRoot.js";
 import {
   formatApprovalPolicyLabel,
   formatNetworkAccessLabel,

package/src/config/runtimeConfig.ts

@@ -106,7 +106,7 @@ export interface ResolvedRuntimeConfig {
 export interface RuntimeStatusContext {
   workspaceRoot: string;
   tokensUsed?: number | null;
-  projectInstructions?: import("../core/projectInstructions.js").ProjectInstructionsLoadResult | null;
+  projectInstructions?: import("../core/workspace/projectInstructions.js").ProjectInstructionsLoadResult | null;
 }
 
 export interface RuntimeSummary {

package/src/config/settings.ts

@@ -101,7 +101,7 @@ export const TERMINAL_MOUSE_MODES = ["wheel", "selection"] as const;
 
 export type TerminalMouseMode = (typeof TERMINAL_MOUSE_MODES)[number];
 
-export const DEFAULT_TERMINAL_MOUSE_MODE: TerminalMouseMode = "selection";
+export const DEFAULT_TERMINAL_MOUSE_MODE: TerminalMouseMode = "wheel";
 
 export interface SettingOption<TValue extends string> {
   value: TValue;

package/src/config/trustStore.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { dirname } from "path";
 import { getCodexaTrustStoreFile } from "./settings.js";
-import { normalizeWorkspaceRoot } from "../core/workspaceRoot.js";
+import { normalizeWorkspaceRoot } from "../core/workspace/workspaceRoot.js";
 
 interface TrustStoreData {
   trustedProjectRoots: string[];

package/src/core/README.md

@@ -0,0 +1,52 @@
+# `src/core`
+
+Non-UI runtime logic for Codexa: launching backends, talking to provider CLIs,
+terminal I/O, workspace resolution, and supporting utilities. UI lives in `src/ui`,
+app state in `src/session`, config in `src/config`. The top level of `src/core` is
+folders-only — every file lives in a domain folder so the directory stays scannable.
+
+## Folder map
+
+| Folder | Responsibility |
+| --- | --- |
+| `providers/` | **Low-level Codex subprocess I/O.** Spawns the `codex` binary and parses its output (`codexSubprocess`, `codexJsonStream`, `codexTranscript`), plus the backend registry/types and the `openaiNative` stub. |
+| `providerRuntime/` | **Multi-provider runtimes + discovery.** One runtime per provider (`anthropic`, `gemini`, `local`, `antigravity`) behind a shared interface, plus routing (`registry`), model/metadata helpers (`models`, `capabilityProfile`, `contextMetadata`, `reasoning`) and Claude Code discovery. |
+| `providerLauncher/` | **Workspace provider config + CLI launching.** Which provider is active per workspace (`workspaceConfig`), provider UI state (`registry`), and spawning provider CLIs (`launcher`). |
+| `codex/` | Codex CLI launch/prompt assembly: `codexExecArgs`, `codexLaunch`, `codexPrompt`. |
+| `models/` | Codex CLI capability discovery (`codexCapabilities`, `codexModelCapabilities`) and the legacy model-spec service (`modelSpecs`). |
+| `executables/` | Resolve external CLI binaries with PATH/env handling (`executableResolver` + per-CLI resolvers). |
+| `auth/` | Codex auth status probing. |
+| `process/` | Generic process spawning (`CommandRunner`) and executable-path validation. |
+| `terminal/` | Terminal I/O: ANSI sanitize, raw mode / cursor, title sequences, capability detection, and the `/clear` + resize repaint boundary (`clearFrameBoundary`, `inkRenderReset`). |
+| `workspace/` | Workspace resolution and state: `workspaceRoot`, `workspaceGuard`, `workspaceActivity`, `projectInstructions`, `planStorage`, `launchContext`. |
+| `version/` | Build channel / version branding (`channel`) and update checking (`updateCheck`). |
+| `shared/` | Small cross-cutting utilities: `clipboard`, `cleanupFastFail`, `githubDiagnostics`, `attachments`, `hollowResponseFormat`. |
+| `perf/` | Performance + render instrumentation (`profiler`, `renderDebug`). |
+| `debug/` | Dev-only tracing helpers (`inputDebug`). |
+
+## The three provider layers
+
+`providers/`, `providerRuntime/`, and `providerLauncher/` have similar names but are
+distinct layers — they are **not** duplicates:
+
+```
+providerLauncher/   which provider is active for this workspace + how to spawn its CLI
+        │
+providerRuntime/    per-provider runtimes (anthropic/gemini/local/antigravity),
+        │           routing, model discovery, capability/context metadata
+        │
+providers/          low-level Codex subprocess I/O + output parsing
+```
+
+The default Codex backend flows through `providers/`; the other providers are
+implemented as `providerRuntime/` runtimes.
+
+## Debug instrumentation
+
+These are intentional, env-gated diagnostics (not dead code) — keep them named clearly:
+
+- `debug/inputDebug.ts` — stdin state tracing (`CODEXA_DEBUG_INPUT=1`).
+- `perf/renderDebug.ts` — Ink render/flicker tracing (`CODEXA_RENDER_DEBUG=1`). Kept in
+  `perf/` rather than `debug/` because it is imported widely across the UI.
+- `providerRuntime/claudeCodeDiscoveryDebug.ts` — entry point for the
+  `bun run debug:claude-models` script; lives next to the discovery code it exercises.

package/src/core/agent/loop.ts

@@ -0,0 +1,282 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import type { BackendRunHandlers } from "../providers/types.js";
+import type { ProviderChatRequest } from "../providerRuntime/types.js";
+import { executeAgentTool, type AgentToolResult } from "./tools.js";
+import { parseAgentToolCall, serializeToolResult, type NormalizedAgentToolCall } from "./protocol.js";
+
+export interface AgentChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+}
+
+export interface AgentChatResponse {
+  text: string;
+  toolCalls?: readonly NormalizedAgentToolCall[];
+}
+
+export interface RunAgentLoopOptions {
+  request: ProviderChatRequest;
+  handlers: BackendRunHandlers;
+  sendMessages: (messages: readonly AgentChatMessage[], turnIndex: number) => Promise<AgentChatResponse>;
+  includeSystemPrompt: boolean;
+  signal?: AbortSignal;
+  maxToolCalls?: number;
+}
+
+const DEFAULT_MAX_TOOL_CALLS = 10;
+
+function workspaceSummary(workspaceRoot: string): string {
+  const lines = [`Workspace root: ${workspaceRoot}`];
+  try {
+    const entries = readdirSync(workspaceRoot, { withFileTypes: true })
+      .filter((entry) => ![".git", "node_modules", "dist", "build", "coverage"].includes(entry.name))
+      .map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`)
+      .sort()
+      .slice(0, 20);
+    if (entries.length > 0) lines.push(`Top-level entries: ${entries.join(", ")}`);
+  } catch {
+    // Tool-based inspection remains available when a shallow summary is unavailable.
+  }
+
+  try {
+    const packageJsonPath = path.join(workspaceRoot, "package.json");
+    if (existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as Record<string, unknown>;
+      const name = typeof packageJson.name === "string" ? packageJson.name : null;
+      const description = typeof packageJson.description === "string" ? packageJson.description : null;
+      if (name) lines.push(`Package: ${name}${description ? ` - ${description}` : ""}`);
+    }
+  } catch {
+    // A malformed package.json should not prevent a local chat request.
+  }
+
+  return lines.join("\n");
+}
+
+function localAgentSystemPrompt(request: ProviderChatRequest): string {
+  const hasCargoToml = existsSync(path.join(request.workspaceRoot, "Cargo.toml"));
+  return [
+    `You are an autonomous coding assistant running inside this workspace: ${request.workspaceRoot}`,
+    "You must inspect files with tools before claiming you cannot see them.",
+    "For broad questions about the repository, use the workspace summary below, then inspect with get_workspace_info or list_files before answering when more detail is needed.",
+    "Use tools to create, edit, build, and test when the user asks for workspace changes.",
+    "Do not ask vague clarification questions when the user's intent has an obvious safe implementation.",
+    hasCargoToml
+      ? "Rust workspace note: Cargo.toml exists. Prefer src/main.rs for simple binaries, use cargo check for validation, use cargo run for running, and do not use rustc main.rs unless main.rs is truly at the workspace root."
+      : null,
+    "Use exactly one tool call at a time in this format:",
+    '<tool_call>{"name":"read_file","arguments":{"path":"src/index.tsx"}}</tool_call>',
+    "Available tools: list_files, read_file, write_file, apply_patch, run_shell, get_workspace_info.",
+    "Summarize changed files and commands run in your final answer.",
+    `Workspace summary:\n${workspaceSummary(request.workspaceRoot)}`,
+    request.projectInstructions?.content
+      ? ["Project instructions:", request.projectInstructions.content].join("\n")
+      : null,
+  ].filter(Boolean).join("\n\n");
+}
+
+function buildInitialMessages(request: ProviderChatRequest, includeSystemPrompt: boolean): AgentChatMessage[] {
+  const systemPrompt = localAgentSystemPrompt(request);
+  if (includeSystemPrompt) {
+    return [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: request.prompt },
+    ];
+  }
+
+  return [
+    { role: "user", content: `${systemPrompt}\n\nUser request:\n${request.prompt}` },
+  ];
+}
+
+function toolActivityCommand(result: Pick<AgentToolResult, "tool" | "path" | "paths" | "command">): string {
+  if (result.command) return `${result.tool}: ${result.command}`;
+  if (result.path) return `${result.tool}: ${result.path}`;
+  if (result.paths && result.paths.length > 0) return `${result.tool}: ${result.paths.join(", ")}`;
+  return result.tool;
+}
+
+interface ExecutedCommand {
+  command: string;
+  success: boolean;
+  exitCode?: number | null;
+  durationMs?: number;
+}
+
+interface AgentLoopSummary {
+  changedFiles: Set<string>;
+  commands: ExecutedCommand[];
+  toolResults: AgentToolResult[];
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function toolCallSignature(call: Pick<NormalizedAgentToolCall, "name" | "arguments">): string {
+  return `${call.name}:${stableJson(call.arguments)}`;
+}
+
+function recordToolResult(summary: AgentLoopSummary, result: AgentToolResult): void {
+  for (const file of result.paths ?? []) {
+    if (file) summary.changedFiles.add(file);
+  }
+  if (result.path && (result.tool === "write_file" || result.tool === "apply_patch")) {
+    summary.changedFiles.add(result.path);
+  }
+  if (result.command) {
+    summary.commands.push({
+      command: result.command,
+      success: result.success,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+    });
+  }
+  summary.toolResults.push(result);
+}
+
+function commandStatus(command: ExecutedCommand): string {
+  const status = command.success ? "succeeded" : "failed";
+  const exitCode = command.exitCode === undefined ? "" : `, exit ${command.exitCode ?? "n/a"}`;
+  return `- ${command.command}: ${status}${exitCode}`;
+}
+
+function nextCommand(request: ProviderChatRequest, summary: AgentLoopSummary): string {
+  if (existsSync(path.join(request.workspaceRoot, "Cargo.toml"))) return "cargo run";
+  const lastValidation = [...summary.commands].reverse().find((item) =>
+    /\b(?:cargo check|cargo run|bun test|npm test|bun run typecheck|tsc)\b/.test(item.command)
+  );
+  if (lastValidation) return lastValidation.command;
+  return "bun test";
+}
+
+function synthesizeFinalMessage(request: ProviderChatRequest, summary: AgentLoopSummary, reason: string): string {
+  const files = [...summary.changedFiles].sort();
+  const commandLines = summary.commands.map(commandStatus);
+  return [
+    reason,
+    "",
+    "Files changed:",
+    files.length > 0 ? files.map((file) => `- ${file}`).join("\n") : "- None detected",
+    "",
+    "Commands run:",
+    commandLines.length > 0 ? commandLines.join("\n") : "- None",
+    "",
+    `Next command: ${nextCommand(request, summary)}`,
+  ].join("\n").trim();
+}
+
+async function requestFinalAnswer(options: RunAgentLoopOptions, messages: AgentChatMessage[], toolCallCount: number, reason: string): Promise<string | null> {
+  messages.push({
+    role: "user",
+    content: [
+      reason,
+      "Stop calling tools now. Write the final answer using the tool results already provided.",
+      "Include files changed, commands run, whether they succeeded, and the next command the user can run.",
+    ].join("\n"),
+  });
+  const response = await options.sendMessages(messages, toolCallCount);
+  const parsed = parseAgentToolCall(response.text);
+  return parsed.kind === "final" && parsed.text.trim() ? parsed.text.trim() : null;
+}
+
+export async function runAgentLoop(options: RunAgentLoopOptions): Promise<string> {
+  const maxToolCalls = options.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS;
+  const messages = buildInitialMessages(options.request, options.includeSystemPrompt);
+  let toolCallCount = 0;
+  let previousToolSignature: string | null = null;
+  const summary: AgentLoopSummary = {
+    changedFiles: new Set(),
+    commands: [],
+    toolResults: [],
+  };
+
+  while (true) {
+    if (options.signal?.aborted) {
+      throw new Error("Local agent run was canceled.");
+    }
+
+    const response = await options.sendMessages(messages, toolCallCount);
+    const structuredToolCall = response.toolCalls?.[0] ?? null;
+    const parsed = structuredToolCall
+      ? { kind: "tool_call" as const, ...structuredToolCall, raw: JSON.stringify(structuredToolCall) }
+      : parseAgentToolCall(response.text);
+
+    if (parsed.kind === "final") {
+      return parsed.text.trim();
+    }
+
+    if (toolCallCount >= maxToolCalls) {
+      const reason = `Local agent reached ${maxToolCalls} tool calls without a final answer.`;
+      const final = await requestFinalAnswer(options, messages, toolCallCount, reason);
+      return final ?? synthesizeFinalMessage(options.request, summary, reason);
+    }
+
+    if (parsed.kind === "malformed_tool_call") {
+      messages.push({ role: "assistant", content: response.text });
+      toolCallCount += 1;
+      messages.push({
+        role: "user",
+        content: serializeToolResult({
+          success: false,
+          error: `Malformed tool call: ${parsed.error}`,
+          raw: parsed.raw,
+        }),
+      });
+      continue;
+    }
+
+    const signature = toolCallSignature(parsed);
+    if (signature === previousToolSignature) {
+      const reason = `Local agent repeated the same ${parsed.name} tool call with identical arguments.`;
+      const final = await requestFinalAnswer(options, messages, toolCallCount, reason);
+      return final ?? synthesizeFinalMessage(options.request, summary, reason);
+    }
+
+    messages.push({ role: "assistant", content: response.text || parsed.raw });
+    previousToolSignature = signature;
+    toolCallCount += 1;
+    const activityId = `local-agent-${toolCallCount}-${parsed.name}`;
+    const startedAt = Date.now();
+    const runningCommand = toolActivityCommand({
+      tool: parsed.name,
+      path: typeof parsed.arguments.path === "string" ? parsed.arguments.path : undefined,
+      command: typeof parsed.arguments.command === "string" ? parsed.arguments.command : undefined,
+    });
+    options.handlers.onToolActivity?.({
+      id: activityId,
+      command: runningCommand,
+      status: "running",
+      startedAt,
+    });
+
+    const result = await executeAgentTool(parsed.name, parsed.arguments, {
+      workspaceRoot: options.request.workspaceRoot,
+      runtime: options.request.runtime,
+      signal: options.signal,
+    });
+    const completedCommand = toolActivityCommand(result);
+    options.handlers.onToolActivity?.({
+      id: activityId,
+      command: completedCommand,
+      status: result.success ? "completed" : "failed",
+      startedAt,
+      completedAt: Date.now(),
+      summary: result.summary ?? result.error ?? null,
+    });
+    recordToolResult(summary, result);
+
+    messages.push({
+      role: "user",
+      content: serializeToolResult(result),
+    });
+  }
+
+  throw new Error(`Local agent stopped after ${maxToolCalls} tool calls without a final answer.`);
+}

package/src/core/agent/protocol.ts

@@ -0,0 +1,211 @@
+export type AgentToolName =
+  | "list_files"
+  | "read_file"
+  | "write_file"
+  | "apply_patch"
+  | "run_shell"
+  | "get_workspace_info";
+
+export interface ParsedAgentToolCall {
+  kind: "tool_call";
+  name: AgentToolName;
+  arguments: Record<string, unknown>;
+  raw: string;
+}
+
+export interface NormalizedAgentToolCall {
+  name: AgentToolName;
+  arguments: Record<string, unknown>;
+}
+
+export interface MalformedAgentToolCall {
+  kind: "malformed_tool_call";
+  raw: string;
+  error: string;
+}
+
+export type AgentToolParseResult =
+  | { kind: "final"; text: string }
+  | ParsedAgentToolCall
+  | MalformedAgentToolCall;
+
+const TOOL_CALL_PATTERN = /<tool_call>([\s\S]*?)<\/tool_call>/i;
+const TOOL_CALL_OPEN_PATTERN = /<tool_call\b[^>]*>/i;
+
+const TOOL_NAMES = new Set<AgentToolName>([
+  "list_files",
+  "read_file",
+  "write_file",
+  "apply_patch",
+  "run_shell",
+  "get_workspace_info",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseJsonMaybeWithExtraBrace(raw: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch (firstError) {
+    const trimmed = raw.trim();
+    if (trimmed.endsWith("}")) {
+      try {
+        return JSON.parse(trimmed.slice(0, -1)) as unknown;
+      } catch {
+        // Return the original parse error below.
+      }
+    }
+    throw firstError;
+  }
+}
+
+function parseArguments(value: unknown): Record<string, unknown> | null {
+  if (value === undefined || value === null) return {};
+  if (isRecord(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value) as unknown;
+      return isRecord(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export function normalizeAgentToolCall(value: unknown): NormalizedAgentToolCall | null {
+  if (!isRecord(value)) return null;
+
+  const functionCall = isRecord(value.function) ? value.function : null;
+  const rawName = functionCall?.name ?? value.name ?? value.tool;
+  if (typeof rawName !== "string" || !TOOL_NAMES.has(rawName as AgentToolName)) {
+    return null;
+  }
+
+  const args = parseArguments(functionCall?.arguments ?? value.arguments ?? value.args);
+  if (!args) return null;
+
+  return {
+    name: rawName as AgentToolName,
+    arguments: args,
+  };
+}
+
+export function parseOpenAiToolCalls(value: unknown): NormalizedAgentToolCall[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => normalizeAgentToolCall(item))
+    .filter((item): item is NormalizedAgentToolCall => Boolean(item));
+}
+
+function extractJsonObjectAfterToolCall(text: string): string | null {
+  const open = TOOL_CALL_OPEN_PATTERN.exec(text);
+  if (!open) return null;
+
+  const startSearch = open.index + open[0].length;
+  const firstBrace = text.indexOf("{", startSearch);
+  if (firstBrace < 0) return text.slice(startSearch).trim();
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = firstBrace; index < text.length; index += 1) {
+    const char = text[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaped = inString;
+      continue;
+    }
+    if (char === "\"") {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (char === "{") depth += 1;
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return text.slice(firstBrace, index + 1).trim();
+      }
+    }
+  }
+
+  return text.slice(firstBrace).replace(/<\/tool_call>.*/is, "").trim();
+}
+
+function parseToolCallPayload(raw: string): AgentToolParseResult {
+  try {
+    const parsed = parseJsonMaybeWithExtraBrace(raw);
+    const fromToolCalls = isRecord(parsed) ? parseOpenAiToolCalls(parsed.tool_calls) : [];
+    const normalized = fromToolCalls[0] ?? normalizeAgentToolCall(parsed);
+    if (!normalized) {
+      return { kind: "malformed_tool_call", raw, error: "Tool call JSON did not contain a supported tool call." };
+    }
+
+    return {
+      kind: "tool_call",
+      ...normalized,
+      raw,
+    };
+  } catch (error) {
+    return {
+      kind: "malformed_tool_call",
+      raw,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function parseAgentToolCall(text: string): AgentToolParseResult {
+  const closedMatch = TOOL_CALL_PATTERN.exec(text);
+  const raw = closedMatch?.[1]?.trim() ?? extractJsonObjectAfterToolCall(text);
+  if (!raw) {
+    return TOOL_CALL_OPEN_PATTERN.test(text)
+      ? { kind: "malformed_tool_call", raw: "", error: "Tool call block did not contain JSON." }
+      : { kind: "final", text };
+  }
+
+  return parseToolCallPayload(raw);
+}
+
+function scalar(value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+
+function blockField(name: string, value: unknown): string[] {
+  return [`${name}:`, scalar(value)];
+}
+
+export function serializeToolResult(result: unknown): string {
+  const record = isRecord(result) ? result : {};
+  const tool = typeof record.tool === "string" ? record.tool : "unknown";
+  const lines: string[] = [`<tool_result name="${tool}">`];
+
+  lines.push(`success: ${scalar(record.success)}`);
+  if (record.command !== undefined) lines.push(`command: ${scalar(record.command)}`);
+  if (record.path !== undefined) lines.push(`path: ${scalar(record.path)}`);
+  if (record.paths !== undefined) lines.push(`paths: ${Array.isArray(record.paths) ? record.paths.join(", ") : scalar(record.paths)}`);
+  if (record.exitCode !== undefined) lines.push(`exit_code: ${scalar(record.exitCode)}`);
+  if (record.durationMs !== undefined) lines.push(`duration_ms: ${scalar(record.durationMs)}`);
+  if (record.summary !== undefined) lines.push(...blockField("summary", record.summary));
+  if (record.error !== undefined) lines.push(...blockField("error", record.error));
+
+  if (tool === "run_shell") {
+    lines.push(...blockField("stdout", record.stdout ?? record.output ?? ""));
+    lines.push(...blockField("stderr", record.stderr ?? ""));
+  } else if (record.output !== undefined) {
+    lines.push(...blockField("output", record.output));
+  }
+
+  if (record.raw !== undefined) lines.push(...blockField("raw", record.raw));
+  lines.push("</tool_result>");
+  return lines.join("\n");
+}