@oh-my-pi/pi-tui 18.4.3 → 18.4.4

package/dist/types/tools/find.d.ts

@@ -1,7 +1,7 @@
 import type { Theme } from "../theme/theme.js";
 import type { Component } from "../tui.js";
 import type { OutputMeta } from "./output-meta.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 /** A verified line range with its yes-probability and a one-line preview. */
 export interface FindRange {
     start: number;
@@ -75,6 +75,20 @@ export declare const findToolRenderer: {
         details?: FindToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: FindRenderArgs): Component;
+    describeCall(args: FindRenderArgs): NativeToolView;
+    /**
+     * Inline (§7.3 find): `Find “query”  2 hits · 8 files`, then per hit its
+     * score bar, path and coverage over the strongest snippets. The search
+     * accounting (τ, tokens, cost, time) is the footnote's tooltip.
+     */
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: FindToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, args?: FindRenderArgs): NativeToolView;
     mergeCallAndResult: true;
     animatedPendingPreview: true;
     animatedPartialResult: true;

package/dist/types/tools/github.d.ts

@@ -1,3 +1,4 @@
+import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 import { type Component } from "../index.js";
 import type { RenderResultOptions } from "./renderer.js";
 import type { Theme } from "../theme/theme.js";
@@ -20,6 +21,8 @@ export declare const githubToolRenderer: {
         details?: GhToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: GithubToolRenderArgs): Component;
+    describeCall(args: GithubToolRenderArgs): NativeToolView;
+    describeResult(result: ToolRenderResult<GhToolDetails>, options: RenderResultOptions, args?: GithubToolRenderArgs): NativeToolView | undefined;
     mergeCallAndResult: true;
 };
 import type { OutputMeta } from "./output-meta.js";

package/dist/types/tools/glob.d.ts

@@ -1,5 +1,5 @@
 import type { Component } from "../tui.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
 import type { TruncationResult } from "./streaming-output.js";
@@ -39,6 +39,19 @@ export declare const globToolRenderer: {
         details?: GlobToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: GlobRenderArgs): Component;
+    describeCall(args: GlobRenderArgs): NativeToolView;
+    /**
+     * Inline (§7.3 glob): `Glob “pattern”  5 files`, then the files as rows
+     * (≤ 6) or a wrap of chips; one quiet footnote for limits and skipped paths.
+     */
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: GlobToolDetails;
+        isError?: boolean;
+    }, _options: RenderResultOptions, args?: GlobRenderArgs): NativeToolView;
     mergeCallAndResult: true;
 };
 export {};

package/dist/types/tools/goal.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions, ToolRenderResult } from "./renderer.js";
 /** Lifecycle state of a tracked goal. */
 export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";
 /** Serializable goal progress and resource budget. */
@@ -37,6 +37,8 @@ export declare const goalToolRenderer: {
         details?: GoalToolDetails;
         isError?: boolean;
     }, _options: RenderResultOptions, uiTheme: Theme, args?: GoalRenderArgs): Component;
+    describeCall(args: GoalRenderArgs): NativeToolView;
+    describeResult(result: ToolRenderResult<GoalToolDetails>, _options: RenderResultOptions, args?: GoalRenderArgs): NativeToolView | undefined;
     mergeCallAndResult: true;
 };
 export {};

package/dist/types/tools/grep.d.ts

@@ -1,5 +1,5 @@
 import type { Component } from "../tui.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
 import type { TruncationResult } from "./streaming-output.js";
@@ -59,6 +59,19 @@ export declare const grepToolRenderer: {
         details?: GrepToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: GrepRenderArgs): Component;
+    describeCall(args: GrepRenderArgs): NativeToolView;
+    /**
+     * Inline (§7.3 grep): `Grep “pattern”  5 matches · 2 files  in src`, then
+     * the matches grouped by file; collapsed shows the first two files.
+     */
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: GrepToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, args?: GrepRenderArgs): NativeToolView;
     mergeCallAndResult: true;
 };
 export {};

package/dist/types/tools/grouped-file-output.d.ts

@@ -1,3 +1,4 @@
+import type { NativeNode } from "../native/node.js";
 /**
  * One file's contribution to a grouped file output. The header itself is generated
  * by `formatGroupedFiles` (one `#` per nesting level); use `headerSuffix` to tack
@@ -35,6 +36,19 @@ export interface GroupedFilesOutput {
  * root-level file so the renderers can split the output into collapsible groups.
  */
 export declare function formatGroupedFiles(files: string[], renderFile: (filePath: string) => GroupedFileSection): GroupedFilesOutput;
+/** One file's rendered search matches, plus its hashline tag when editable. */
+export interface FileMatchSection {
+    model: string[];
+    display: string[];
+    tag?: string;
+}
+/**
+ * Render per-file search matches (grep / ast-grep). Grouped mode nests files
+ * via {@link formatGroupedFiles}, appending `#tag` to headers; flat mode
+ * blank-separates files and prefixes each with a hashline header when tagged.
+ * Files with no model lines are omitted.
+ */
+export declare function formatFileMatches(files: string[], grouped: boolean, renderFile: (filePath: string) => FileMatchSection): GroupedFilesOutput;
 /** Per-line classification of grouped output, used by renderers for hyperlinks. */
 export interface GroupedLineContext {
     /** Directory header, file header, or any non-header body/content line. */
@@ -69,3 +83,47 @@ export declare function classifyGroupedLines(lines: readonly string[], headerBas
  * indices lets callers slice parallel arrays (raw lines, styled lines, contexts).
  */
 export declare function groupLineIndicesByBlank(rawLines: readonly string[]): number[][];
+/** One event of {@link walkGroupedOutput}: a directory header, a file header, or a non-blank body line. */
+export type GroupedOutputEvent = {
+    readonly kind: "dir";
+} | {
+    readonly kind: "file";
+    readonly path: string;
+    readonly suffix?: string;
+} | {
+    readonly kind: "line";
+    readonly text: string;
+};
+/**
+ * Walk grouped output (`# dir/`, `## file.ts (suffix)`, body lines), resolving
+ * each file header to its full display path (the folded directory chain
+ * joined with the name) and dropping blank separator lines.
+ */
+export declare function walkGroupedOutput(lines: readonly string[]): Generator<GroupedOutputEvent>;
+/** One source line for {@link numberedCode}: its number (`null` for an elision marker), text and match mark. */
+export interface NumberedLine {
+    n: number | null;
+    text: string;
+    mark?: boolean;
+}
+/**
+ * Numbered `code` for possibly non-contiguous source lines: one block per run
+ * of consecutive line numbers (`start` = the run's first line, match lines
+ * `mark`ed), with a `…` row wherever the numbers jump or an elision marker
+ * (`n: null`) sits. No path header: the row or head above names the file.
+ */
+export declare function numberedCode(lines: readonly NumberedLine[], opts?: {
+    lang?: string;
+}): NativeNode[];
+/**
+ * Describe grouped search output (grep / ast-grep / ast-edit display content)
+ * by file (§7.3 grep): per file a 22px path row (dim dir, strong name, the
+ * header's suffix or the match count as a chip), then its lines as
+ * {@link numberedCode} with match lines marked and `…` between non-adjacent
+ * runs. Unnumbered body lines stay plain `code`. `maxFiles` keeps only the
+ * first files (the caller says how many were left out).
+ */
+export declare function describeGroupedOutput(lines: readonly string[], options?: {
+    lang?: (path: string) => string | undefined;
+    maxFiles?: number;
+}): NativeNode[];

package/dist/types/tools/json-tree.d.ts

@@ -1,4 +1,5 @@
 import type { Theme } from "../theme/theme.js";
+import type { NativeNode } from "../native/node.js";
 /** Max depth for JSON tree rendering */
 export declare const JSON_TREE_MAX_DEPTH_COLLAPSED = 2;
 /** Maximum expanded JSON tree depth. */
@@ -57,3 +58,22 @@ export declare function renderJsonTreeLines(value: unknown, theme: Theme, option
     lines: string[];
     truncated: boolean;
 };
+/** Data caps for {@link describeJsonTree}. */
+export interface JsonTreeDescribeOptions {
+    /** Deepest level expanded into child nodes; deeper containers get a `…` child. */
+    maxDepth?: number;
+    /** Tree nodes emitted before the remaining siblings collapse into `… N more`. */
+    maxNodes?: number;
+    /** Characters kept per string scalar (data cap, not a width). */
+    maxScalarLen?: number;
+    /** Levels open initially; deeper containers start closed. */
+    openDepth?: number;
+    /** Root object keys omitted. Defaults to internal tool argument metadata. */
+    hiddenRootKeys?: readonly string[];
+}
+/**
+ * TSP `tree` of a JSON value: containers become expandable nodes labelled with
+ * their key and size, scalars become `key: value` leaves styled by type.
+ * Bounded by depth, node count and scalar length; no width math.
+ */
+export declare function describeJsonTree(value: unknown, options?: JsonTreeDescribeOptions): NativeNode;

package/dist/types/tools/lsp.d.ts

@@ -1,13 +1,4 @@
-/**
- * LSP Tool TUI Rendering
- *
- * Renders LSP tool calls and results in the TUI with:
- * - Syntax-highlighted hover information
- * - Color-coded diagnostics by severity
- * - Grouped references and symbols
- * - Collapsible/expandable views
- */
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions, ToolRenderResult } from "./renderer.js";
 import type { Component } from "../tui.js";
 import { Text } from "../components/text.js";
 import { type Theme } from "../theme/theme.js";
@@ -67,6 +58,8 @@ export declare function renderResult(result: {
 export declare const lspToolRenderer: {
     renderCall: typeof renderCall;
     renderResult: typeof renderResult;
+    describeCall(args: LspParams): NativeToolView;
+    describeResult(result: ToolRenderResult<LspToolDetails>, _options: RenderResultOptions, args?: LspParams): NativeToolView | undefined;
     mergeCallAndResult: true;
     inline: true;
 };

package/dist/types/tools/mcp.d.ts

@@ -5,7 +5,7 @@
  * showing args and output in JSON tree format similar to task tool.
  */
 import { type Component } from "../index.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
 /**
  * Render MCP tool call.
@@ -22,6 +22,21 @@ export declare function renderMCPResult(result: {
     details?: MCPToolDetails;
     isError?: boolean;
 }, options: RenderResultOptions, theme: Theme, args?: Record<string, unknown>): Component;
+/** Native MCP call view: the head only, inline while pending. */
+export declare function describeMCPCall(args: Record<string, unknown>, label: string): NativeToolView;
+/**
+ * Native MCP result view: JSON output as a JSON tree, Markdown when the
+ * preference is on, otherwise the raw text as tool output. The head's args
+ * summary stands in for the ANSI card's Args tree.
+ */
+export declare function describeMCPResult(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    details?: MCPToolDetails;
+    isError?: boolean;
+}, _options: RenderResultOptions, args?: Record<string, unknown>): NativeToolView | undefined;
 import type { OutputMeta } from "./output-meta.js";
 /** Set whether plain MCP text results render as Markdown. */
 export declare function setMcpRenderMarkdownResults(enabled: boolean): void;

package/dist/types/tools/memory.d.ts

@@ -1,3 +1,4 @@
+import type { NativeToolView } from "./renderer.js";
 /**
  * Inline TUI renderers for the long-term memory tools (`retain`, `recall`,
  * `reflect`).
@@ -33,6 +34,15 @@ export declare const retainToolRenderer: {
         };
         isError?: boolean;
     }, options: RenderResultOptions, theme: Theme, args?: RetainRenderArgs): Component;
+    describeCall(args: RetainRenderArgs): NativeToolView | undefined;
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: MemoryRetainDetails;
+        isError?: boolean;
+    }, _options: RenderResultOptions, args?: RetainRenderArgs): NativeToolView | undefined;
 };
 /** Render recalled memories with an expandable body. */
 export declare const recallToolRenderer: {
@@ -46,6 +56,14 @@ export declare const recallToolRenderer: {
         }>;
         isError?: boolean;
     }, options: RenderResultOptions, theme: Theme, args?: QueryRenderArgs): Component;
+    describeCall(args: QueryRenderArgs): NativeToolView;
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        isError?: boolean;
+    }, _options: RenderResultOptions, args?: QueryRenderArgs): NativeToolView | undefined;
 };
 /** Render synthesized memory reflections. */
 export declare const reflectToolRenderer: {
@@ -59,6 +77,14 @@ export declare const reflectToolRenderer: {
         }>;
         isError?: boolean;
     }, options: RenderResultOptions, theme: Theme, args?: QueryRenderArgs): Component;
+    describeCall(args: QueryRenderArgs): NativeToolView;
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        isError?: boolean;
+    }, _options: RenderResultOptions, args?: QueryRenderArgs): NativeToolView | undefined;
 };
 /** Number of memories accepted by retain. */
 export interface MemoryRetainDetails {

package/dist/types/tools/native-view.d.ts

@@ -0,0 +1,90 @@
+import type { TspSpan, TspText, TspTone } from "@oh-my-pi/pi-wire";
+import type { NativeChild, NativeNode } from "../native/node.js";
+import { type ParsedDiagnostic } from "../render/render-utils.js";
+import type { FileDiagnosticsResult } from "./lsp.js";
+import { type OutputMeta } from "./output-meta.js";
+import type { NativeToolHead, NativeToolView, ToolRenderResult } from "./renderer.js";
+/** A path for native heads: relative to the working directory when inside it, else `~`-shortened. */
+export declare function displayPath(filePath: string): string;
+/** `file://` link for a head's path target, when the path is absolute. */
+export declare function fileHref(filePath: string | undefined): string | undefined;
+/** Diff stats as one head `meta` string, `+8 −1` (U+2212 minus), or undefined when nothing changed. */
+export declare function diffStatsMeta(added: number, removed: number): string | undefined;
+/**
+ * One file of a multi-file edit: a borderless `section` headed by the path
+ * (→ rename) and its `+a −d`, over the file's body (its diff, diagnostics).
+ */
+export declare function fileDiffSection(file: {
+    path: string;
+    rename?: string;
+    added?: number;
+    removed?: number;
+}, body: readonly NativeChild[], p: {
+    role: string;
+    tone?: TspTone;
+}): NativeNode;
+/**
+ * One 22px file row (role `omp.tool.file`) for read groups, grep files, glob
+ * lists and find hits: a leading glyph (the file icon unless `lead` replaces
+ * it), the path with a dim directory and a strong name (cut in the middle),
+ * a quiet `range` suffix (`:13-36`), then an optional count `chip` and a
+ * muted `detail`.
+ */
+export declare function fileRow(filePath: string, p?: {
+    range?: string;
+    chip?: {
+        text: string;
+        title?: string;
+    };
+    detail?: TspText;
+    href?: string;
+    lead?: NativeNode;
+    icon?: string;
+    tone?: TspTone;
+    title?: string;
+    key?: string;
+}): NativeNode;
+/**
+ * Inline error view (§7.3 read error): error tone, the message's first line
+ * after `—` in the head's meta, so a collapsed inline call never hides it,
+ * and the full message as the body only when the head had to cut it short.
+ */
+export declare function inlineErrorView(head: NativeToolHead, message: string): NativeToolView;
+/** Text blocks of a tool result joined by newlines, or `""`. */
+export declare function resultText(result: ToolRenderResult<unknown>): string;
+/**
+ * Card head: the bold `toolTitle` title, then detail spans; string details
+ * become muted plain text, empty details are skipped.
+ */
+export declare function toolHead(title: string, ...details: readonly (TspSpan | string | undefined)[]): TspSpan[];
+/** Error body: wrapped error text, or a JSON `code` block when the message is structured. */
+export declare function errorText(message: string): NativeNode;
+/** Error card view: error tone, the tool head and the error body (`<title> failed` when empty). */
+export declare function errorView(title: string, message: string, ...meta: readonly (string | undefined)[]): NativeToolView;
+/** Wrapped placeholder or secondary line (`(no output)`, `No matches`, …); `lines` clamps it. */
+export declare function noteText(message: string, token?: string, lines?: number): NativeNode;
+/** Muted `a · b · c` metadata line, or undefined when there are no parts. */
+export declare function statsText(parts: readonly string[]): NativeNode | undefined;
+/** Warning line for truncation / artifact capture failures, or undefined. */
+export declare function truncationNotice(meta: OutputMeta | undefined): NativeNode | undefined;
+/**
+ * The one final quiet line of a tool body (§7.2): `a · b` facts, then any
+ * truncation / artifact-capture notice from `meta`; undefined when empty.
+ */
+export declare function footnoteText(parts: readonly string[], meta?: OutputMeta): NativeNode | undefined;
+/** A diagnostic's severity glyph: `x-circle` error, `warn` warning, `info`, `lightbulb` hint, in the severity tone. */
+export declare function diagnosticGlyph(severity: ParsedDiagnostic["severity"]): NativeNode;
+/**
+ * LSP diagnostics section for write/edit results: rows of severity icon ·
+ * `line:col` · message, most severe first, capped at five with `+N more`.
+ * Rows name the file too when the messages span several files (or `withPath`).
+ * Undefined when there is nothing to show.
+ */
+export declare function diagnosticsSection(diagnostics: FileDiagnosticsResult | undefined, opts?: {
+    withPath?: boolean;
+}): NativeNode | undefined;
+/** Head chip counting LSP diagnostics across files (`2 diagnostics`), or undefined when there are none. */
+export declare function diagnosticsBadge(files: readonly (FileDiagnosticsResult | undefined)[]): {
+    text: string;
+    tone: TspTone;
+} | undefined;

package/dist/types/tools/proc-render.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 import type { AgentActivitySnapshot, CoordinationDetails, JobSnapshot } from "./wait.js";
 import type { DaemonSnapshot } from "./daemon.js";
 import { type CardToolResult as ToolResult } from "./result-card.js";
@@ -25,3 +25,9 @@ export declare function renderAgentWrite(to: string, body: string, result: ToolR
 /** Render live and completed process writes with the URL-selected operation. */
 export declare function renderProcWrite(id: string, action: ProcWriteAction, content: string | undefined, result: ToolResult | undefined, details: ProcWriteDetails | undefined, options: RenderResultOptions, theme: Theme): Component;
 export declare function renderProcRead(id: string, result: ToolResult | undefined, details: ProcReadDetails | undefined, options: RenderResultOptions, theme: Theme): Component;
+/** TSP view of an `agent://` write (IRC message). */
+export declare function describeAgentWrite(to: string, body: string, result: ToolResult | undefined, details: CoordinationDetails | undefined): NativeToolView;
+/** TSP view of a `proc://` write (stdin, mode change, kill). */
+export declare function describeProcWrite(id: string, action: ProcWriteAction, content: string | undefined, result: ToolResult | undefined, details: ProcWriteDetails | undefined): NativeToolView;
+/** TSP view of a `proc://` read: job/service detail, logs, or the process table. */
+export declare function describeProcRead(id: string, result: ToolResult | undefined, details: ProcReadDetails | undefined): NativeToolView;

package/dist/types/tools/read.d.ts

@@ -1,6 +1,7 @@
 import type { SummaryResult } from "@oh-my-pi/pi-natives";
 import type { Component } from "../tui.js";
-import type { RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions, ToolActivityContext, ToolActivitySummary } from "./renderer.js";
+import type { NativeNode } from "../native/node.js";
 import type { Theme } from "../theme/theme.js";
 import type { OutputMeta } from "./output-meta.js";
 import type { TruncationResult } from "./streaming-output.js";
@@ -107,6 +108,13 @@ export declare function pendingFileLinkPath(inputPath: string): string;
  * image reads only record the path in `meta.source`). URL/internal sources are
  * not fs paths, so only `type: "path"` qualifies. */
 export declare function readSourceFsPath(details: ReadToolDetails | undefined): string | undefined;
+/**
+ * Read content as numbered `code` (no path header: the head names the file).
+ * Numbers come from `lineNumbers` (`displayContent`'s per-line numbers,
+ * `null` for an elided block; runs split with `…` between) when they cover
+ * every line, else count up from `start`.
+ */
+export declare function readContentCode(content: string, start: number, numbers: readonly (number | null)[] | undefined, lang: string | undefined): NativeNode[];
 /** Render file, image, and URL reads in the transcript. */
 export declare const readToolRenderer: {
     activitySummary(args: unknown, _context: ToolActivityContext): ToolActivitySummary;
@@ -119,6 +127,20 @@ export declare const readToolRenderer: {
         details?: ReadToolDetails;
         isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: ReadRenderArgs): Component;
+    describeCall(args: ReadRenderArgs): NativeToolView;
+    /**
+     * Inline (§7.3 read): the head names the file and range; the content
+     * (numbered from the range start, no path header) is the disclosed body.
+     * An error shows its message in the head, never behind the disclosure.
+     */
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: ReadToolDetails;
+        isError?: boolean;
+    }, _options: RenderResultOptions, args?: ReadRenderArgs): NativeToolView;
     mergeCallAndResult: true;
 };
 /** Inclusive line range describing one elided span in a structural summary. */

package/dist/types/tools/renderer.d.ts

@@ -3,6 +3,8 @@
  * transcript components. Built-in renderers live beside this file; the
  * coding-agent tools implement the matching `*Details` payloads.
  */
+import type { TspPreview, TspText, TspTone, TspToolProps } from "@oh-my-pi/pi-wire";
+import type { NativeChild } from "../native/node.js";
 import type { Component } from "../tui.js";
 import type { Theme } from "../theme/theme.js";
 /** Display state handed to `renderCall`/`renderResult`. */
@@ -58,6 +60,54 @@ export interface ToolActivityContext {
     /** Tool-specific render context (same shape `renderCall` receives), when available. */
     readonly renderContext?: Record<string, unknown>;
 }
+/**
+ * The data head of a tool call (NATIVE_REDESIGN §7.2): what the terminal
+ * draws in the `tool` kind's head. Each fact appears once — a target named
+ * here is never repeated in the body.
+ */
+export interface NativeToolHead {
+    /** The verb ("Bash", "Edit"); defaults to the tool's label. */
+    readonly title?: TspText;
+    /** The primary argument, shown once: command, path, pattern, query. */
+    readonly target?: TspText;
+    readonly targetKind?: TspToolProps["targetKind"];
+    /** Language for `command` targets. */
+    readonly lang?: string;
+    /** `file://` link for path targets. */
+    readonly href?: string;
+    /** Short facts after the target (`+8 −1`, `5 matches · 2 files`). */
+    readonly meta?: readonly TspText[];
+    readonly badges?: TspToolProps["badges"];
+    /** A one-word state note ("timed out", "partial"). */
+    readonly note?: TspText;
+    /** A non-zero exit code (error chip). */
+    readonly exit?: number | null;
+}
+/**
+ * A tool's semantic presentation for Tern Surface Protocol terminals.
+ * `ToolExecutionComponent` wraps it in a `tool` node (terminals that list
+ * the kind) or, as the fallback, a `card` (role `omp.tool.<name>`, status,
+ * elapsed timer, collapse): the renderer supplies only the head data and the
+ * body nodes, never frames, padding or width math.
+ */
+export interface NativeToolView {
+    /** The data head; the fallback card's head spans derive from it when {@link head} is absent. */
+    readonly tool?: NativeToolHead;
+    /** Header spans for the fallback card (and the `tool` title when {@link tool} is absent). */
+    readonly head?: TspText;
+    /** Body: sections, never frames. */
+    readonly body?: readonly NativeChild[];
+    /** Tone override; the frame otherwise derives it from the call status. */
+    readonly tone?: TspTone;
+    /** Body clamp while collapsed; `{tail}` keeps the end (terminal output). Defaults to the transcript's preview size. */
+    readonly preview?: TspPreview | {
+        readonly tail: number;
+    } | "none";
+    /** Render frameless (`frame:"inline"`): a head line plus a disclosed body. */
+    readonly inline?: boolean;
+    /** Head actions offered on hover (`copy`, `retry`). */
+    readonly tools?: TspToolProps["tools"];
+}
 /**
  * A tool's transcript presentation: call preview, result view, and repaint/animation hints.
  * Method signatures are intentionally bivariant so a renderer typed over its own
@@ -67,6 +117,13 @@ export interface ToolActivityContext {
 export interface ToolRenderer<TArgs = unknown, TDetails = unknown> {
     renderCall(args: TArgs, options: RenderResultOptions, theme: Theme): Component | undefined;
     renderResult(result: ToolRenderResult<TDetails>, options: RenderResultContextOptions, theme: Theme, args?: TArgs): Component | undefined;
+    /**
+     * Semantic call preview for TSP terminals. When a renderer implements the
+     * describe hooks, the native backend never calls `renderCall`/`renderResult`.
+     */
+    describeCall?(args: TArgs, options: RenderResultOptions): NativeToolView | undefined;
+    /** Semantic result view for TSP terminals; merged with the call view when {@link mergeCallAndResult}. */
+    describeResult?(result: ToolRenderResult<TDetails>, options: RenderResultContextOptions, args?: TArgs): NativeToolView | undefined;
     mergeCallAndResult?: boolean;
     /** Describes current activity without coupling a renderer to terminal layout. */
     activitySummary?(args: TArgs, context: ToolActivityContext): ToolActivitySummary;

package/dist/types/tools/report-tool-issue.d.ts

@@ -1,7 +1,10 @@
 import type { Component } from "../index.js";
 import type { Theme } from "../theme/theme.js";
+import type { NativeToolView } from "./renderer.js";
 /** Call preview for an `xd://report_issue` write. */
 export declare function renderReportIssueDeviceCall(content: unknown, uiTheme: Theme): Component;
+/** Native call preview for an `xd://report_issue` write. */
+export declare function describeReportIssueDeviceCall(content: unknown): NativeToolView;
 /** Device name for automatic tool issue reports. */
 export declare const REPORT_ISSUE_DEVICE_NAME = "report_issue";
 /** Internal device URL for automatic tool issue reports. */

package/dist/types/tools/resolve.d.ts

@@ -1,5 +1,5 @@
 import type { Component } from "../index.js";
-import type { RenderResultOptions } from "./renderer.js";
+import type { NativeToolView, RenderResultOptions } from "./renderer.js";
 import type { Theme } from "../theme/theme.js";
 import { Ellipsis } from "../render/index.js";
 /** Device name for applying a staged action. */
@@ -27,6 +27,10 @@ export interface ResolveInvocation {
 }
 /** Streaming-safe call preview for a resolution-device write: `Resolve/Reject/Propose: <text>`. */
 export declare function renderResolutionDeviceCall(device: ResolutionDeviceName, content: unknown, uiTheme: Theme): Component;
+/** Native form of {@link renderResolutionDeviceCall}: `Resolve/Reject/Propose` head with the first content line. */
+export declare function describeResolutionDeviceCall(device: ResolutionDeviceName, content: unknown): NativeToolView;
+/** Native form of {@link renderDeviceCallPreview}: title head plus the first content line of a pending device write. */
+export declare function describeDeviceCallPreview(title: string, content: unknown): NativeToolView;
 /** Render the first content line of a pending device write. */
 export declare function renderDeviceCallPreview(title: string, content: unknown, uiTheme: Theme, ellipsis?: Ellipsis): Component;
 /** Render staged-action acceptance or rejection. */
@@ -40,6 +44,15 @@ export declare const resolveRenderer: {
         details?: ResolveDetails;
         isError?: boolean;
     }, _options: RenderResultOptions, uiTheme: Theme): Component;
+    describeCall(args: Partial<ResolveInvocation>): NativeToolView;
+    describeResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: ResolveDetails;
+        isError?: boolean;
+    }): NativeToolView | undefined;
     inline: true;
     mergeCallAndResult: true;
 };

package/dist/types/tools/task.d.ts

@@ -4,6 +4,7 @@ import type { ConfiguredThinkingLevel } from "../render/render-utils.js";
 import { type Component } from "../tui.js";
 import type { RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
+import type { NativeToolView, ToolRenderResult } from "./renderer.js";
 /** Render context threaded in from `ToolExecutionComponent.#buildRenderContext`. */
 interface TaskRenderContext {
     hasResult?: boolean;
@@ -61,6 +62,8 @@ export declare function renderNestedTaskResults(detailsList: TaskToolDetails[],
 export declare const taskToolRenderer: {
     renderCall: typeof renderCall;
     renderResult: typeof renderResult;
+    describeCall(args: TaskParams, options: RenderResultOptions): NativeToolView | undefined;
+    describeResult(result: ToolRenderResult<TaskToolDetails>, options: TaskRenderOptions, args?: TaskParams): NativeToolView | undefined;
     mergeCallAndResult: true;
 };
 /** Source of an agent definition */

package/dist/types/tools/think.d.ts

@@ -1,3 +1,4 @@
+import type { NativeToolView } from "./renderer.js";
 import { type Component } from "../index.js";
 import type { RenderResultOptions } from "./renderer.js";
 import { type Theme } from "../theme/theme.js";
@@ -10,4 +11,6 @@ export declare const thinkToolRenderer: {
     inline: true;
     renderCall(args: ThinkRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
     renderResult(): undefined;
+    describeCall(args: ThinkRenderArgs, options: RenderResultOptions): NativeToolView;
+    describeResult(): undefined;
 };