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)

---

## 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:** Tool results in the most recent assistant message are expanded by default
- **AC-5:** When a new assistant message arrives, previous tool results collapse
- **AC-6:** Edit and Write tool diffs remain expanded regardless of message age
- **AC-7:** Tool calls without results display as non-expandable with muted styling

### Diff Rendering

- **AC-8:** Edit/Write results display structuredPatch data as syntax-highlighted diff
- **AC-9:** Diff additions render with VS Code dark theme green background (rgba(46, 160, 67, 0.15))
- **AC-10:** Diff deletions render with VS Code dark theme red background (rgba(248, 81, 73, 0.15))
- **AC-11:** Full file path displays above each diff block
- **AC-12:** Diff context lines use structuredPatch as-is (no recomputation)

### Other Tool Types

- **AC-13:** Bash results display stdout in monospace, stderr separately if present
- **AC-14:** Read results display file content with syntax highlighting based on file extension
- **AC-15:** Grep/Glob results display file list with match counts
- **AC-16:** WebFetch results display URL and response summary

### Truncation

- **AC-17:** Long outputs truncate at thresholds matching Claude Code behavior
- **AC-18:** Truncated outputs show "Show full output (N lines)" link
- **AC-19:** Clicking "Show full output" opens a dedicated lightweight modal
- **AC-20:** Modal displays full content with syntax highlighting, scrollable

### Error States

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

### API Contract

- **AC-24:** /api/conversation response includes tool results nested in tool_calls
- **AC-25:** Each tool_call has: name, id, input, result (when available)
- **AC-26:** Result structure varies by tool type (documented in IMP-SERVER)

---

## 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.

### 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-24, AC-25, AC-26

**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

**Tool call schema after change:**
```python
{
    "name": "Edit",
    "id": "toolu_abc123",
    "input": {"file_path": "...", "old_string": "...", "new_string": "..."},
    "result": {
        "content": "The file has been updated successfully.",
        "is_error": False,
        "structuredPatch": [...],
        "filePath": "...",
        # ... other fields from toolUseResult
    }
}
```

**Result Structure by Tool Type:**

| Tool | Result Fields |
|------|---------------|
| Edit | `structuredPatch`, `filePath`, `oldString`, `newString` |
| Write | `filePath`, content confirmation |
| Read | `file`, `type`, content in `content` field |
| Bash | `stdout`, `stderr`, `interrupted` |
| Glob | `filenames`, `numFiles`, `truncated` |
| Grep | `content`, `filenames`, `numFiles`, `numLines` |

---

### IMP-TOOLCALL: Expandable Tool Call Component

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

**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 expanded state per message. When new assistant message arrives:
- Compare latest assistant message ID to stored ID
- If different, reset expanded set to empty
- Edit/Write tools bypass this logic (always expanded via CSS/logic)

---

### IMP-DIFF: Diff Rendering Component

**Fulfills:** AC-8, AC-9, AC-10, AC-11, AC-12

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

**Add diff language to highlight.js:**
```javascript
import langDiff from 'https://esm.sh/highlight.js@11.11.1/lib/languages/diff';
hljs.registerLanguage('diff', langDiff);
```

**Diff Renderer:**

1. Convert `structuredPatch` array to unified diff text:
   - Each hunk: `@@ -oldStart,oldLines +newStart,newLines @@`
   - Followed by hunk.lines array
2. Syntax highlight with hljs diff language
3. Sanitize with DOMPurify before rendering
4. 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-13, AC-21, AC-22

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

Renders:
- `stdout` in monospace pre block
- `stderr` in separate block with error styling (if present)
- "Command interrupted" notice (if interrupted flag)

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

---

### IMP-TRUNCATE: Output Truncation

**Fulfills:** AC-17, AC-18

**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-19, AC-20

**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-21, AC-22, AC-23

**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

**Goal:** API returns tool results nested in tool_calls

**Deliverables:**
1. Two-pass parsing in `_parse_claude_conversation`
2. Tool results attached with `id` field
3. Unit tests for result attachment
4. Handle missing results gracefully (return tool_call without result)

**Exit Criteria:** AC-24, AC-25, AC-26 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-7 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-8 through AC-12 pass

---

### Slice 5: Other Tool Types

**Goal:** Bash, Read, Glob, Grep render appropriately

**Deliverables:**
1. `renderBashResult` with stdout/stderr separation
2. `renderFileContent` for Read
3. `renderFileList` for Glob/Grep
4. Generic fallback for unknown tools

**Exit Criteria:** AC-13 through AC-16 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-17 through AC-20 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-21 through AC-23 pass, feature complete

---

## Open Questions

1. **Exact Claude Code truncation thresholds** — need to verify against Claude Code source or experiment
2. **Performance with 100+ tool calls** — monitor after ship, optimize if needed
3. **Codex support timeline** — when should we prioritize v2?

---

## Appendix: Research Findings

### Claude Code JSONL Format

Tool calls and results are stored as separate entries:

```json
// 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:
```json
{"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.