amc/plans/PLAN-tool-result-display.md

Plan: Tool Result Display in AMC Dashboard

Status: Draft — awaiting review and mockup phase Author: Claude + Taylor Created: 2026-02-27

Summary

Add the ability to view tool call results (diffs, bash output, file contents) directly in the AMC dashboard conversation view. Currently, users see that a tool was called but cannot see what it did. This feature brings Claude Code's result visibility to the multi-agent dashboard.

Goals

1. See code changes as they happen — diffs from Edit/Write tools always visible
2. Debug agent behavior — inspect Bash output, Read content, search results
3. Match Claude Code UX — familiar expand/collapse behavior with latest results expanded

Non-Goals (v1)

• Codex agent support (different JSONL format — deferred to v2)
• Copy-to-clipboard functionality
• Virtual scrolling / performance optimization
• Editor integration (clicking paths to open files)
• Accessibility (keyboard navigation, focus management, ARIA labels — deferred to v2)
• Lazy-fetch API for tool results (consider for v2 if payload size becomes an issue)

---

User Workflows

Workflow 1: Watching an Active Session

1. User opens a session card showing an active Claude agent
2. Agent calls Edit tool to modify a file
3. User immediately sees the diff expanded below the tool call pill
4. Agent calls Bash to run tests
5. User sees bash output expanded, previous Edit diff stays expanded (it's a diff)
6. Agent sends a text message explaining results
7. Bash output collapses (new assistant message arrived), Edit diff stays expanded

Workflow 2: Reviewing a Completed Session

1. User opens a completed session to review what the agent did
2. All tool calls are collapsed by default (no "latest" assistant message)
3. Exception: Edit/Write diffs are still expanded
4. User clicks a Bash tool call to see what command ran and its output
5. User clicks "Show full output" when output is truncated
6. Lightweight modal opens with full scrollable content
7. User closes modal and continues reviewing

Workflow 3: Debugging a Failed Tool Call

1. Agent runs a Bash command that fails
2. Tool result block shows with red-tinted background
3. stderr content is visible, clearly marked as error
4. User can see what went wrong without leaving the dashboard

---

Acceptance Criteria

Display Behavior

• AC-1: Tool calls render as expandable elements showing tool name and summary
• AC-2: Clicking a collapsed tool call expands to show its result
• AC-3: Clicking an expanded tool call collapses it
• AC-4: In active sessions, tool results in the most recent assistant message are expanded by default
• AC-5: When a new assistant message arrives, previous non-diff tool results collapse unless the user has manually toggled them in that message
• AC-6: Edit and Write results remain expanded regardless of message age or session status (even if Write only has confirmation text)
• AC-7: In completed sessions, all non-diff tool results start collapsed
• AC-8: Tool calls without results display as non-expandable with muted styling; in active sessions, pending tool calls show a spinner to distinguish in-progress from permanently missing

Diff Rendering

• AC-9: Edit/Write results display structuredPatch data as syntax-highlighted diff; falls back to raw content text if structuredPatch is malformed or absent
• AC-10: Diff additions render with VS Code dark theme green background (rgba(46, 160, 67, 0.15))
• AC-11: Diff deletions render with VS Code dark theme red background (rgba(248, 81, 73, 0.15))
• AC-12: Full file path displays above each diff block
• AC-13: Diff context lines use structuredPatch as-is (no recomputation)

Other Tool Types

• AC-14: Bash results display stdout in monospace, stderr separately if present
• AC-15: Bash output with ANSI escape codes renders as colored HTML (via ansi_up)
• AC-16: Read results display file content with syntax highlighting based on file extension
• AC-17: Grep/Glob results display file list with match counts
• AC-18: Unknown tools (WebFetch, Task, etc.) use GenericResult fallback showing raw content

Truncation

• AC-19: Long outputs truncate at configurable line/character thresholds (defaults tuned to approximate Claude Code behavior)
• AC-20: Truncated outputs show "Show full output (N lines)" link
• AC-21: Clicking "Show full output" opens a dedicated lightweight modal
• AC-22: Modal displays full content with syntax highlighting, scrollable

Error States

• AC-23: Failed tool calls display with red-tinted background
• AC-24: Error content (stderr, error messages) is clearly distinguishable from success content
• AC-25: is_error flag from tool_result determines error state

API Contract

• AC-26: /api/conversation response includes tool results nested in tool_calls
• AC-27: Each tool_call has: name, id, input, result (when available)
• AC-28: All tool results conform to a normalized envelope: { kind, status, content, is_error } with tool-specific fields nested in content

---

Architecture

Why Two-Pass JSONL Parsing

The Claude Code JSONL stores tool_use and tool_result as separate entries linked by tool_use_id. To nest results inside tool_calls for the API response, the server must:

1. First pass: Build a map of tool_use_id → toolUseResult
2. Second pass: Parse messages, attaching results to matching tool_calls

This adds parsing overhead but keeps the API contract simple. Alternatives considered:

• Streaming/incremental: More complex, doesn't help since we need full conversation anyway
• Client-side joining: Shifts complexity to frontend, increases payload size

Why Render Everything, Not Virtual Scroll

Sessions typically have 20-80 tool calls. Modern browsers handle hundreds of DOM elements efficiently. Virtual scrolling adds significant complexity (measuring, windowing, scroll position management) for marginal benefit.

Decision: Ship simple, measure real-world performance, optimize if >100ms render times observed.

Why Dedicated Modal Over Inline Expansion

Full output can be thousands of lines. Inline expansion would:

• Push other content out of view
• Make scrolling confusing
• Lose context of surrounding conversation

A modal provides a focused reading experience without disrupting conversation layout.

Why a Normalized Result Contract

Raw toolUseResult shapes vary wildly by tool type — Edit has structuredPatch, Bash has stdout/stderr, Glob has filenames. Passing these raw to the frontend means every renderer must know the exact JSONL format, and adding Codex support (v2) would require duplicating all that branching.

Instead, the server normalizes each result into a stable envelope:

{
    "kind": "diff" | "bash" | "file_content" | "file_list" | "generic",
    "status": "success" | "error" | "pending",
    "is_error": bool,
    "content": { ... }  # tool-specific fields, documented per kind
}

The frontend switches on kind (5 cases) rather than tool name (unbounded). This also gives us a clean seam for the result_mode query parameter if payload size becomes an issue later.

Component Structure

MessageBubble
├── Content (text)
├── Thinking (existing)
└── ToolCallList (new)
    └── ToolCallItem (repeated)
        ├── Header (pill: chevron, name, summary, status)
        └── ResultContent (conditional)
            ├── DiffResult (for Edit/Write)
            ├── BashResult (for Bash)
            ├── FileListResult (for Glob/Grep)
            └── GenericResult (fallback)

FullOutputModal (new, top-level)
├── Header (tool name, file path)
├── Content (full output, scrollable)
└── CloseButton

---

Implementation Specifications

IMP-SERVER: Parse and Attach Tool Results

Fulfills: AC-26, AC-27, AC-28

Location: amc_server/mixins/conversation.py

Changes to _parse_claude_conversation:

Two-pass parsing:

1. First pass: Scan all entries, build map of tool_use_id → toolUseResult
2. Second pass: Parse messages as before, but when encountering tool_use, lookup and attach result

API query parameter: /api/conversation?result_mode=full (default). Future option: result_mode=preview to return truncated previews and reduce payload size without an API-breaking change.

Normalization step: After looking up the raw toolUseResult, the server normalizes it into the stable envelope before attaching:

{
    "name": "Edit",
    "id": "toolu_abc123",
    "input": {"file_path": "...", "old_string": "...", "new_string": "..."},
    "result": {
        "kind": "diff",
        "status": "success",
        "is_error": False,
        "content": {
            "structuredPatch": [...],
            "filePath": "...",
            "text": "The file has been updated successfully."
        }
    }
}

Normalized kind mapping:

kind	Source Tools	content Fields
diff	Edit, Write	structuredPatch, filePath, text
bash	Bash	stdout, stderr, interrupted
file_content	Read	file, type, text
file_list	Glob, Grep	filenames, numFiles, truncated, numLines
generic	All others	text (raw content string)

---

IMP-TOOLCALL: Expandable Tool Call Component

Fulfills: AC-1, AC-2, AC-3, AC-4, AC-5, AC-6, AC-7, AC-8

Location: dashboard/lib/markdown.js (refactor renderToolCalls)

New function: ToolCallItem

Renders a single tool call with:

• Chevron for expand/collapse (when result exists and not Edit/Write)
• Tool name (bold, colored)
• Summary (from existing getToolSummary)
• Status icon (checkmark or X)
• Result content (when expanded)

State Management:

Track two sets per message: autoExpanded (system-controlled) and userToggled (manual clicks).

When new assistant message arrives:

• Compare latest assistant message ID to stored ID
• If different, reset autoExpanded to empty for previous messages
• userToggled entries are never reset — user intent is preserved
• Edit/Write tools bypass this logic (always expanded via CSS/logic)

Expand/collapse logic: a tool call is expanded if it is in userToggled (explicit click) OR in autoExpanded (latest message) OR is Edit/Write kind.

---

IMP-DIFF: Diff Rendering Component

Fulfills: AC-9, AC-10, AC-11, AC-12, AC-13

Location: dashboard/lib/markdown.js (new function renderDiff)

Add diff language to highlight.js:

import langDiff from 'https://esm.sh/highlight.js@11.11.1/lib/languages/diff';
hljs.registerLanguage('diff', langDiff);

Diff Renderer:

1. If structuredPatch is present and valid, convert to unified diff text:
   • Each hunk: @@ -oldStart,oldLines +newStart,newLines @@
   • Followed by hunk.lines array
2. If structuredPatch is missing or malformed, fall back to raw content.text in a monospace block
3. Syntax highlight with hljs diff language
4. Sanitize with DOMPurify before rendering
5. Wrap in container with file path header

CSS styling:

• Container: dark border, rounded corners
• Header: muted background, monospace font, full file path
• Content: monospace, horizontal scroll
• Additions: background: rgba(46, 160, 67, 0.15)
• Deletions: background: rgba(248, 81, 73, 0.15)

---

IMP-BASH: Bash Output Component

Fulfills: AC-14, AC-15, AC-23, AC-24

Location: dashboard/lib/markdown.js (new function renderBashResult)

ANSI-to-HTML conversion:

import AnsiUp from 'https://esm.sh/ansi_up';
const ansi = new AnsiUp();
const html = ansi.ansi_to_html(bashOutput);

The ansi_up library (zero dependencies, ~8KB) converts ANSI escape codes to styled HTML spans, preserving colored test output, progress indicators, and error highlighting from CLI tools.

Renders:

• stdout in monospace pre block with ANSI colors preserved
• stderr in separate block with error styling (if present)
• "Command interrupted" notice (if interrupted flag)

Sanitization order (CRITICAL): First convert ANSI to HTML via ansi_up, THEN sanitize with DOMPurify. Sanitizing before conversion would strip escape codes; sanitizing after preserves the styled spans while preventing XSS.

Error state: is_error or presence of stderr triggers error styling (red tint, left border).

---

IMP-TRUNCATE: Output Truncation

Fulfills: AC-19, AC-20

Truncation Thresholds (match Claude Code):

Tool Type	Max Lines	Max Chars
Bash stdout	100	10000
Bash stderr	50	5000
Read content	500	50000
Grep matches	100	10000
Glob files	100	5000

Note: These thresholds need verification against Claude Code behavior. May require adjustment based on testing.

Truncation Helper:

Takes content string, returns { text, truncated, totalLines }. If truncated, result renderers show "Show full output (N lines)" link.

---

IMP-MODAL: Full Output Modal

Fulfills: AC-21, AC-22

Location: dashboard/components/FullOutputModal.js (new file)

Structure:

• Overlay (click to close)
• Modal container (click does NOT close)
• Header: title (tool name + file path), close button
• Content: scrollable pre/code block with syntax highlighting

Integration: Modal state managed at App level or ChatMessages level. "Show full output" link sets state with content + metadata.

---

IMP-ERROR: Error State Styling

Fulfills: AC-23, AC-24, AC-25

Styling:

• Tool call header: red-tinted background when result.is_error
• Status icon: red X instead of green checkmark
• Bash stderr: red text, italic, distinct from stdout
• Overall: left border accent in error color

---

Rollout Slices

Slice 1: Design Mockups (Pre-Implementation)

Goal: Validate visual design before building

Deliverables:

1. Create /mockups test route with static data
2. Implement 3-4 design variants (card-based, minimal, etc.)
3. Use real tool result data from session JSONL
4. User reviews and selects preferred design

Exit Criteria: Design direction locked

---

Slice 2: Server-Side Tool Result Parsing and Normalization

Goal: API returns normalized tool results nested in tool_calls

Deliverables:

1. Two-pass parsing in _parse_claude_conversation
2. Normalization layer: raw toolUseResult → { kind, status, is_error, content } envelope
3. Tool results attached with id field
4. Unit tests for result attachment and normalization per tool type
5. Handle missing results gracefully (return tool_call without result)
6. Support result_mode=full query parameter (only mode for now, but wired up for future preview)

Exit Criteria: AC-26, AC-27, AC-28 pass

---

Slice 3: Basic Expand/Collapse UI

Goal: Tool calls are expandable, show raw result content

Deliverables:

1. Refactor renderToolCalls to ToolCallList component
2. Implement expand/collapse with chevron
3. Track expanded state per message
4. Collapse on new assistant message
5. Keep Edit/Write always expanded

Exit Criteria: AC-1 through AC-8 pass

---

Slice 4: Diff Rendering

Goal: Edit/Write show beautiful diffs

Deliverables:

1. Add diff language to highlight.js
2. Implement renderDiff function
3. VS Code dark theme styling
4. Full file path header

Exit Criteria: AC-9 through AC-13 pass

---

Slice 5: Other Tool Types

Goal: Bash, Read, Glob, Grep render appropriately

Deliverables:

1. Import and configure ansi_up for ANSI-to-HTML conversion
2. renderBashResult with stdout/stderr separation and ANSI color preservation
3. renderFileContent for Read
4. renderFileList for Glob/Grep
5. GenericResult fallback for unknown tools (WebFetch, Task, etc.)

Exit Criteria: AC-14 through AC-18 pass

---

Slice 6: Truncation and Modal

Goal: Long outputs truncate with modal expansion

Deliverables:

1. Truncation helper with Claude Code thresholds
2. "Show full output" link
3. FullOutputModal component
4. Syntax highlighting in modal

Exit Criteria: AC-19 through AC-22 pass

---

Slice 7: Error States and Polish

Goal: Failed tools visually distinct, edge cases handled

Deliverables:

1. Error state styling (red tint)
2. Muted styling for missing results
3. Test with interrupted sessions
4. Cross-browser testing

Exit Criteria: AC-23 through AC-25 pass, feature complete

---

Open Questions

1. Exact Claude Code truncation thresholds — Resolved: using reasonable defaults with a note to tune via testing. AC-19 updated.
2. Performance with 100+ tool calls — monitor after ship, optimize if needed
3. Codex support timeline — when should we prioritize v2? The normalized kind contract makes this easier: add Codex normalizers without touching renderers.
4. Lazy-fetch for large payloads — Resolved: result_mode query parameter wired into API contract. Only full implemented in v1; preview deferred.

---

Appendix: Research Findings

Claude Code JSONL Format

Tool calls and results are stored as separate entries:

// Assistant sends tool_use
{"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "toolu_abc", "name": "Edit", "input": {...}}]}}

// Result in separate user entry
{"type": "user", "message": {"content": [{"type": "tool_result", "tool_use_id": "toolu_abc", "content": "Success"}]}, "toolUseResult": {...}}

The toolUseResult object contains rich structured data varying by tool type.

Missing Results Statistics

Across 55 sessions with 2,063 tool calls:

• 11 missing results (0.5%)
• Affected tools: Edit (4), Read (2), Bash (1), others

Interrupt Handling

User interrupts create a separate user message:

{"type": "user", "message": {"content": [{"type": "text", "text": "[Request interrupted by user for tool use]"}]}}

Tool results for completed tools are still present; the interrupt message indicates the turn ended early.