From 8f876d015461b9f90e935551acc2b088f8736600 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 4 Jul 2026 18:28:16 +0200
Subject: [PATCH] docs(terminal-rendering): expand fmtToolUse with complete
 pattern table
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the sparse 3-line prose description of fmtToolUse with a full
reference table covering every tool case added over the past several
PRs. Adds a new subsection listing the short-name convention (* suffix),
all Claude built-ins (Read/Write/Edit/Glob/Grep/Bash/TodoWrite), the
full hyperhive MCP surface (recv/send/ask/answer/remind/set_status/
get_loose_ends/get_agent_meta/cancel_loose_end/ack_until/kill/restart/
start/update/get_logs/get_host_journal/request_apply_commit/
request_init_config/request_update_meta_inputs), all scheduling tools
(list_schedules/cancel_schedule/fire_schedule_now/edit_schedule/
request_schedule_prompt — added in the previous PR), bash MCP tools
(run/status/kill), and matrix MCP tools (send_message/send_dm/
send_reply/send_reaction/read_room/mark_read/join_room/open_dm/
invite_user/download_file).
---
 docs/terminal-rendering.md | 65 ++++++++++++++++++++++++++++++++++----
 1 file changed, 59 insertions(+), 6 deletions(-)

diff --git a/docs/terminal-rendering.md b/docs/terminal-rendering.md
index 32da78cb..a7eb5f23 100644
--- a/docs/terminal-rendering.md
+++ b/docs/terminal-rendering.md
@@ -121,12 +121,65 @@ suffix, so the terminal degrades cleanly against older event shapes.
      `renderRichToolUse` (Write/Edit/send/ask/answer get
      custom renderings); on miss fall through to a flat
      `.tool-use` row with `fmtToolUse → fmtArgsGeneric`.
-     `fmtToolUse` surfaces the salient arg per built-in tool:
-     `recv` shows `wait <N>s` / `max <N>` when set; `Bash`
-     flags `[bg]`; `remind` shows `+Xm "preview"`; matrix
-     tools show `→ <room>/<user>: "body"` or `<room> [limit]`;
-     scheduling tools show `#id · fields`; `fmtArgsGeneric`
-     handles anything else.
+     `fmtToolUse` surfaces the salient arg per built-in tool
+     (see table below); `fmtArgsGeneric` handles everything
+     else.
+### `fmtToolUse` patterns
+
+The `short` name strips the `mcp__hyperhive__` / `mcp__bash__` /
+`mcp__matrix__` prefix and appends `*` (e.g. `recv*`, `run*`,
+`send_message*`). Unprefixed tools (Read, Write, etc.) keep their
+name as-is.
+
+| Tool | Rendered as |
+|------|-------------|
+| **Claude built-ins** | |
+| `Read` | `Read <path>` |
+| `Write` | rich diff row `Write <path> · +N` |
+| `Edit` | rich diff row `Edit <path> · -N +N` |
+| `Glob` | `Glob <pattern>` |
+| `Grep` | `Grep <pattern>` |
+| `Bash` | `Bash [bg] $ <cmd>` (also rich renderer for full body) |
+| `TodoWrite` | `TodoWrite (N items)` |
+| **Core hyperhive** | |
+| `send*` | rich renderer: `send* → to · NL` (default-open body) |
+| `recv*` | `recv*()` · `recv* wait Ns` · `recv* max N` |
+| `ask*` | rich renderer: `ask* → to` (inline answer form for operator) |
+| `answer*` | rich renderer: `answer* #id` |
+| `remind*` | `remind* +Xm "preview"` or `remind* at HH:MMZ "preview"` |
+| `set_status*` | `set_status* "text"` |
+| `get_loose_ends*` | `get_loose_ends*()` or `get_loose_ends* [agent]` |
+| `get_agent_meta*` | `get_agent_meta*()` or `get_agent_meta* name` |
+| `cancel_loose_end*` | `cancel_loose_end* kind #id` |
+| `ack_until*` | `ack_until* ≤N` |
+| **Lifecycle** | |
+| `kill*/restart*/start*/update*` | `kill* name` (etc.) |
+| `get_logs*` | `get_logs* name` or `get_logs* name NL` |
+| `get_host_journal*` | `get_host_journal*()` or with `[container] · [/grep/] · NL` |
+| **Approvals / config** | |
+| `request_apply_commit*` | `request_apply_commit* agent @ sha12` |
+| `request_init_config*` | `request_init_config* name` |
+| `request_update_meta_inputs*` | `request_update_meta_inputs* [inp1, …]` or `all` |
+| **Scheduling** | |
+| `list_schedules*` | `list_schedules*()` |
+| `cancel_schedule*` | `cancel_schedule* #id all` or `#id [t1, t2]` |
+| `fire_schedule_now*` | `fire_schedule_now* #id` |
+| `edit_schedule*` | `edit_schedule* #id · body · interval · next · +N tgt · -N tgt` (only changed fields shown) |
+| `request_schedule_prompt*` | `request_schedule_prompt* → t1, t2 at HH:MMZ` (+ `+Ns` if recurring) |
+| **Bash MCP** | |
+| `run*` | `run* [bg] $ cmd` (also rich renderer for full cmd body) |
+| `status*` (bash) | `status* id:xyz` or `status* id:xyz · wait Ns` |
+| `kill*` (bash) | `kill* id` or `kill* id [force]` |
+| **Matrix MCP** | |
+| `send_message*/send_dm*/send_reply*` | `send_message* → room: "body"` / `send_dm* → @user: "body"` |
+| `send_reaction*` | `send_reaction* room emoji` |
+| `read_room*` | `read_room* room` or `read_room* room [N]` |
+| `mark_read*` | `mark_read* room` |
+| `join_room*/open_dm*` | `join_room* room` / `open_dm* @user` |
+| `invite_user*` | `invite_user* @user → room` |
+| `download_file*` | `download_file* room` |
+| **Everything else** | `fmtArgsGeneric` — see [Extra-MCP tools](#extra-mcp-tools) |
+
 4. `type == "user"` → walk `message.content[]` for
    `tool_result`; `renderToolResult` correlates via
    `tool_use_id → toolNameById` to default-open `recv`