4 +title: Deliver pivi tool presentation
5 +spec: NL-SPEC-GMWDCMJZ
12 +#
Deliver pivi tool presentation 16 +Make a tool call as legible in Neovim as it is in Pi's own interface, using native surfaces rather than a ported component tree.
18 +[NL-PLAN-LAJ8PGRK](../NL-PLAN-LAJ8PGRK-deliver-pivi-transcript-presentation-and-navigat/index.md) made every tool call an addressable, collapsible entry.
19 +That entry currently shows what a tool acted on and nothing about how it ended, and it discards everything a tool reports about its own work.
21 +Blocker: the behavior below is not yet in [NL-SPEC-GMWDCMJZ](../../specs/NL-SPEC-GMWDCMJZ-pivi-native-neovim-integration/index.md).
22 +A tool presentation section and its acceptance criteria were drafted and await one-shot approval.
23 +This plan is not executable until that amendment lands.
27 +Read from the installed Pi 0.85.1 implementation, not from prose.
28 +Tool results reach a client unchanged, so everything a tool reports is already on the wire and merely unused.
30 +| Tool | What it reports about its own work | When |
32 +| edit | a display diff, a unified patch, and the first changed line | always |
33 +| bash | progressive output, truncation, and a full output path | while running, throttled |
34 +| read | truncation | only when truncated |
35 +| grep, find, ls | truncation and the limit that was reached | only at a limit |
36 +| write | nothing | — |
38 +Neovim side: no diff parser ships, but diff syntax and the diff highlight groups do, and the theme already defines them.
44 + session["bugabinga.pivi.session"] --> tool["bugabinga.pivi.tool"]
45 + tool --> entry["bugabinga.pivi.entry"]
46 + tool --> render["bugabinga.pivi.render"]
47 + render --> fold["bugabinga.pivi.fold"]
48 + tool --> diff["bugabinga.pivi.diff"]
49 + diff --> command["bugabinga.pivi.command"]
50 + tool --> navigate["bugabinga.pivi.navigate"]
53 +| Module | Responsibility |
55 +| `bugabinga.pivi.tool` | Interprets what a tool reports: outcome, change, progress, language, truncation |
56 +| `bugabinga.pivi.render` | Presents that interpretation as decoration inside the entry |
57 +| `bugabinga.pivi.diff` | Editor comparison of a completed change |
58 +| `bugabinga.pivi.fold` | Collapsed line that still states subject and outcome |
59 +| `bugabinga.pivi.navigate` | Reaching the first changed line rather than the file start |
60 +| `bugabinga.pivi.entry` | Carries the interpretation as entry metadata |
61 +| `bugabinga.pivi.session` | Feeds tool reports in, including while a tool still runs |
67 + s1["1 Outcome after the name"] --> s2["2 Change as a diff"]
68 + s1 --> s6["6 Truncation is reachable"]
69 + s2 --> s3["3 First changed line"]
70 + s2 --> s4["4 Editor comparison"]
71 + s1 --> s5["5 Output while running"]
72 + s5 --> s7["7 Output in its language"]
75 +| # | Observable behavior | Modules touched | Verified by |
76 +| --- | --- | --- | --- |
77 +| 1 | A finished tool entry states how it ended beside what it acted on, and a collapsed entry keeps both | `bugabinga.pivi.tool`, `bugabinga.pivi.render`, `bugabinga.pivi.fold`, `bugabinga.pivi.session` | Outcome spec across edit, shell, search, and failure, plus a collapsed-line spec |
78 +| 2 | A completed edit shows its change with added and removed lines distinguished | `bugabinga.pivi.tool`, `bugabinga.pivi.render` | Diff presentation spec asserting distinct added and removed lines and unchanged buffer text |
79 +| 3 | Navigating from an edit lands on its first changed line | `bugabinga.pivi.navigate`, `bugabinga.pivi.tool` | Navigation spec over a recorded edit |
80 +| 4 | A change can be opened as a full editor comparison and left again | `bugabinga.pivi.diff`, `bugabinga.pivi.command` | Comparison spec asserting the working window survives and the transcript is unchanged |
81 +| 5 | Output of a running tool appears as it arrives rather than only at completion | `bugabinga.pivi.session`, `bugabinga.pivi.tool`, `bugabinga.pivi.entry` | Progressive-output spec asserting growth before completion and stable bounds |
82 +| 6 | A truncated result says so, and its full output is reachable | `bugabinga.pivi.tool`, `bugabinga.pivi.render`, `bugabinga.pivi.navigate` | Truncation spec asserting the notice and a reachable full output |
83 +| 7 | Output is presented in the language it came from when that language is known | `bugabinga.pivi.tool`, `bugabinga.pivi.render` | Language spec asserting a second language is parsed inside the transcript |
85 +Slice 1 is the walking skeleton: it establishes the interpretation every later slice reads.
89 +- Interpretation is derived only from what a tool reports; a tool that reports nothing degrades to today's behavior rather than to a guess.
90 +- Diff presentation is decoration over reported change text, so the transcript still yields message text when copied.
91 +- An editor comparison reconstructs the prior content from the reported change rather than re-reading a file that has already moved on.
92 +- Progressive output replaces the tail of its own entry; entry bounds stay extmark-backed and must survive repeated rewrites.
93 +- Presentation stays redraw-driven, so a tool that emits output continuously cannot force parsing per update.
97 +| Risk | Slice | Mitigation |
99 +| Tools differ in what they report | 1 | Interpretation is per tool with a plain fallback, asserted for a tool that reports nothing |
100 +| Diff decoration drifts from the text it marks | 2 | Anchor decoration to entry-relative rows and assert after later entries are appended |
101 +| A reconstructed comparison disagrees with the file on disk | 4 | Present it as a comparison of the recorded change, and state when the file has moved on |
102 +| Frequent progress updates cost too much | 5 | Rewrite only the entry tail, keep parsing redraw-driven, and hold the streaming budget spec |
103 +| A collapsed line grows unreadable | 1 | Bound subject and outcome, and assert a maximum collapsed width |