Give tool calls a user-visible rationale and carry it into permission asks

Problem

When mecatui asks the user to authorize a tool call, it shows what the agent wants to execute but not why it wants to execute it.

This is especially difficult for long or unfamiliar shell commands. Even when the command is presented readably, the user must reconstruct its purpose from earlier conversation and tool activity before making an authorization decision.

The same missing context makes ordinary tool-call cards harder to follow: users can see the mechanism, but not how the action advances the current task.

Desired behavior

Allow the agent to provide a concise, user-visible rationale for a tool call, and preserve that rationale with the call throughout its lifecycle.

For a permission ask, mecatui should distinguish:

• What: the tool, arguments, command, or diff being authorized.
• Why: the agent's explanation of what the action is intended to accomplish and how it relates to the current task.

This should be an action summary, not raw or hidden chain-of-thought.

Requirements

• Associate an optional, bounded rationale with a tool call.
• Transport it through the session event/API surfaces needed by embedded and remote mecatui sessions.
• Show it alongside the pending permission prompt before the user decides.
• Preserve it with the tool call in scrollback and replay.
• Clearly indicate when no rationale was supplied; do not infer or fabricate one from the command.
• Treat the rationale as model-authored, untrusted explanatory text. It must not weaken policy evaluation or change the actual capability being authorized.
• Sanitize and length-bound it like other model-produced UI content.

Acceptance criteria

• A permission prompt for a long Bash command shows both the exact command and a concise explanation of its purpose.
• The user can inspect the verbatim arguments independently of the rationale.
• The rationale remains associated with the resulting tool card after allow or deny.
• Missing rationales have an honest fallback.
• Embedded and remote mecatui sessions behave consistently.
• Tests cover transport, rendering, replay, bounds, sanitization, and missing-rationale behavior.

Related

• #1361 — compact tool-call output
• #833 — live LLM stream progress
• #552 — richer permission-argument presentation
• #488 — wrapping and scrolling long permission arguments
• #1362 — permission-prompt placement/navigation

Start by tracing the existing permission prompt, tool-call event/API, and scrollback or replay paths; the issue does not name specific files or tests. Map how embedded and remote sessions carry and render tool-call data, then use the acceptance criteria to verify rationale bounds, sanitization, missing-rationale behavior, and independent display of exact arguments.