From a009b1e995d38a2149d84067bbf461f8be0e3456 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 18 Jun 2026 23:01:16 +0800
Subject: [PATCH] docs(tools): FIXME to rethink the ToolPresentation type
 shapes

The ToolCallPresentation / ToolResultPresentation / ToolTerminal shapes grew
incrementally and the responsibility split is now muddy (overlapping call/result
terminal fields, the bridge stitching content + terminal + rawInput per call).
Flag it as a release-blocking FIXME to redesign around a tool's render INTENT
(a tagged union over card kinds) and pin it in an RFC before more tools/UIs
depend on the current bag-of-optionals.
---
 packages/tools/src/index.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/tools/src/index.ts b/packages/tools/src/index.ts
index fad513fa52..5730b778c7 100644
--- a/packages/tools/src/index.ts
+++ b/packages/tools/src/index.ts
@@ -58,6 +58,18 @@ declare module 'cordis' {
  */
 export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'
 
+// FIXME(tool-presentation): the ToolCallPresentation / ToolResultPresentation /
+// ToolTerminal shapes need a rethink. They grew incrementally (title/kind/
+// rawInput, then a `content` block, then a `terminal` sub-shape carrying cwd/
+// output/exit) and the split of responsibility is now muddy: the call vs result
+// terminal fields overlap, the bridge has to reconcile a `content` block AND a
+// `terminal` block AND `rawInput` per call, and the "pending vs completed"
+// boundary doesn't cleanly map to how editors actually render (terminal card,
+// diff, generic card). Before more tools/UIs depend on this, redesign the type
+// so a tool declares its render INTENT once (e.g. a tagged union over card
+// kinds) rather than a bag of optional fields the bridge stitches together.
+// Pin the design in an RFC and migrate dsh-tool-bash + the ACP bridge together.
+
 /**
  * How a tool wants ONE of its calls shown in a UI (an editor's tool-call card,
  * a CLI log line) BEFORE the result is known — the *pending* state. Provider-