[FEATURE] Mod API: expose the engine's own header text on ToolUse and ToolGroup props

Status Open
Reported on v2.1.300
Maintainer reply None cached
Activity 0 comments · opened Oct 15, 2026

Problem Statement

A ui.render hook on ToolUse receives tool, input and the call's state, but not the header the engine draws: the user-facing name (Update for Edit, glean_default - search (MCP)) and the argument summary each tool formats its own way ((query: "catppuccin", num_results: 1), a Read's line range). next(e) resolves to an opaque reference, so a mod can wrap the row but not restyle its header.

A mod that draws its own header (e.g. a Powerline capsule colored by kind and state) must rebuild every tool's wording from input. It gets unknown tools wrong and drifts when a built-in renderer changes. ToolGroup has the same gap: its line (Read 3 files, ran 2 shell commands, Wrote 1 memory) is not in the props, only calls.

Proposed Solution

Expose the engine's text as read-only props, as PromptHint does with hint:

ToolUse: {
  // ...existing props
  /** The name the row draws for the tool (`Update`, `Bash`, `github - issue_read (MCP)`). Read-only. */
  label: string;
  /** The argument text the tool's renderer draws after it, without the parentheses; empty when none. Read-only. */
  summary: string;
};
ToolGroup: {
  // ...existing props
  /** The line the engine draws for the group (`Read 3 files, ran 2 shell commands`). Read-only. */
  text: string;
};

Alternative Solutions

Rebuilding each header from input, as today: per-tool guesswork, lost wording (Update, (MCP)), nothing for plugin tools with their own renderer.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

  1. A mod draws each tool row as an icon + label capsule colored by kind (shell, read, edit, MCP) and state (running, errored, interrupted), followed by the summary.
  2. With label and summary, it shows exactly what the engine shows, restyled: an MCP row keeps (MCP) and its arguments as the engine formats them.
  3. A folded group keeps the engine's wording next to its per-kind counts.

Additional Context

#89476 asks to document the mapping between display labels and tool names; these props would give mods that mapping directly. Version 2.1.300, terminal surface.

View original on GitHub ↗