NomadArch/dev-docs/TOOL_CALL_IMPLEMENTATION.md

Tool Call Rendering Implementation

This document describes how tool calls are rendered in the CodeNomad, following the patterns established in the TUI.

Overview

Each tool type has specialized rendering logic that displays the most relevant information for that tool. This matches the TUI's approach of providing context-specific displays rather than generic input/output dumps.

Tool-Specific Rendering

1. read - File Reading

• Title: Read {filename}
• Body: Preview of file content (first 6 lines) from metadata.preview
• Use case: Shows what file content the assistant is reading

2. edit - File Editing

• Title: Edit {filename}
• Body: Diff/patch showing changes from metadata.diff
• Special: Shows diagnostics if available in metadata
• Use case: Shows what changes are being made to files

3. write - File Writing

• Title: Write {filename}
• Body: File content being written (first 10 lines)
• Special: Shows diagnostics if available in metadata
• Use case: Shows new file content being created

4. bash - Shell Commands

• Title: Shell {description} (or command if no description)
• Body: Console-style display with $ command and output

$ npm install vitest
added 50 packages...

• Output from: metadata.output
• Use case: Shows command execution and results

5. webfetch - Web Fetching

• Title: Fetch {url}
• Body: Fetched content (first 10 lines)
• Use case: Shows web content being retrieved

6. todowrite - Task Planning

• Title: Dynamic based on todo phase:
  • All pending: "Creating plan"
  • All completed: "Completing plan"
  • Mixed: "Updating plan"
• Body: Formatted todo list:
  • - [x] Completed task
  • - [ ] Pending task
  • - [ ] ~~Cancelled task~~
  • - [ ] In progress task (highlighted)
• Use case: Shows the AI's task planning

7. task - Delegated Tasks

• Title: Task[subagent_type] {description}
• Body: List of delegated tool calls with icons:

⚡ bash: npm install
📖 read package.json
✏️ edit src/app.ts

• Special: In TUI, includes navigation hints for session tree
• Use case: Shows what the delegated agent is doing

8. todoread - Plan Reading

• Special: Hidden in TUI, returns empty string
• Use case: Internal tool, not displayed to user

9. glob - File Pattern Matching

• Title: Glob {pattern}
• Use case: Shows file search patterns

10. grep - Content Search

• Title: Grep "{pattern}"
• Use case: Shows what content is being searched

11. list - Directory Listing

• Title: List
• Use case: Shows directory operations

12. patch - Patching Files

• Title: Patch
• Use case: Shows patch operations

13. invalid - Invalid Tool Calls

• Title: Name of the actual tool attempted
• Use case: Shows validation errors

14. Default - Unknown Tools

• Title: Capitalized tool name
• Body: Output truncated to 10 lines
• Use case: Fallback for any new or custom tools

Status States

Pending

• Icon: ⏸ (pause symbol)
• Title: Action text (e.g., "Writing command...", "Preparing edit...")
• Border: Accent color
• Animation: Shimmer effect on title
• Expandable: Shows "Waiting for permission..." message

Running

• Icon: ⏳ (hourglass)
• Title: Same as completed state
• Border: Warning color (yellow/orange)
• Animation: Pulse on status icon

Completed

• Icon: ✓ (checkmark)
• Title: Tool-specific title with arguments
• Border: Success color (green)
• Body: Tool-specific rendered content

Error

• Icon: ✗ (X mark)
• Title: Same format but in error color
• Border: Error color (red)
• Body: Error message in highlighted box

Title Rendering Logic

The title follows this pattern:

1. Pending state: Show action text

   "Writing command..."
   "Preparing edit..."
   "Delegating..."
   

2. Completed/Running/Error: Show specific info

   "Shell npm install"
   "Edit src/app.ts"
   "Read package.json"
   "Task[general] Search for files"
   

3. Special cases:

   • todowrite: Shows plan phase
   • todoread: Just "Plan"
   • bash: Uses description if available, otherwise shows command

Metadata Usage

Tool calls use metadata for rich content:

• read: metadata.preview - file preview content
• edit: metadata.diff - patch/diff text
• bash: metadata.output - command output
• todowrite: metadata.todos[] - todo items with status
• task: metadata.summary[] - delegated tool calls
• edit/write: metadata.diagnostics - LSP diagnostics

Design Principles

1. Context-specific: Each tool shows the most relevant information
2. Progressive disclosure: Collapsed by default, expand for details
3. Visual hierarchy: Icons, colors, and borders indicate status
4. Truncation: Long content is truncated (6-10 lines) to prevent overwhelming
5. Consistency: All tools follow same header/body/error structure

Component Structure

<div class="tool-call tool-call-status-{status}">
  <button class="tool-call-header" onClick={toggle}>
    <span class="tool-call-icon">▶/▼</span>
    <span class="tool-call-emoji">{icon}</span>
    <span class="tool-call-summary">{title}</span>
    <span class="tool-call-status">{statusIcon}</span>
  </button>

  {expanded && (
    <div class="tool-call-details">
      {/* Tool-specific body content */}
      {error && <div class="tool-call-error-content">{error}</div>}
    </div>
  )}
</div>

CSS Classes

• .tool-call - Base container
• .tool-call-status-{pending|running|completed|error} - Status-specific styling
• .tool-call-header - Clickable header with expand/collapse
• .tool-call-emoji - Tool type icon
• .tool-call-summary - Tool title/description
• .tool-call-details - Expanded content area
• .tool-call-content - Code/output content (monospace)
• .tool-call-todos - Todo list container
• .tool-call-task-summary - Delegated task list
• .tool-call-error-content - Error message display

Future Enhancements

1. Syntax highlighting: Use Shiki for code blocks in bash, read, write
2. Diff rendering: Better diff visualization for edit tool
3. Copy buttons: Quick copy for code/output
4. File links: Click filename to open in editor
5. Diagnostics display: Show LSP errors/warnings inline