fix: add input field to tool call data and simplify CLAUDE.md orchestrator docs
This commit is contained in:
Mohamed Boudra
@@ -47,117 +47,10 @@ Run `npx expo-doctor` to diagnose version mismatches and native module issues.
|
||||
|
||||
## Orchestrator Mode
|
||||
|
||||
When asked to go into orchestrator mode, you must **only accomplish tasks by managing other agents**. Do NOT perform the work yourself.
|
||||
|
||||
### Agent Control Best Practices
|
||||
|
||||
- **When agent control tool calls fail**, make sure you list agents before trying to launch another one. It could just be a wait timeout.
|
||||
- **Always prefix agent titles** so we can tell which ones are running under you (e.g., "🎭 Feature Implementation", "🎭 Design Discussion").
|
||||
- **Launch agents in the most permissive mode**: Use full access or bypass permissions mode.
|
||||
- **Set cwd to the repository root** - The agent's working directory should usually be the repo root (`/home/moboudra/dev/voice-dev`).
|
||||
- **Set cwd to the repository root** - The agent's working directory should usually be the repo root
|
||||
|
||||
### Agent Use Cases
|
||||
|
||||
You can run agents to:
|
||||
- **Implement a task** - Spawn an agent to write code and implement features
|
||||
- **Have a design discussion** - Discuss architecture and design decisions
|
||||
- **Have a pairing session** - Collaborate on problem-solving
|
||||
- **Test some feature** - Run tests and verify functionality
|
||||
- **Do investigation** - Research and explore the codebase
|
||||
|
||||
### Clarifying Ambiguous Requests
|
||||
|
||||
**CRITICAL:** When user requests are ambiguous or unclear:
|
||||
|
||||
1. **Research first** - Spawn an investigation agent to understand the current state
|
||||
2. **Ask clarifying questions** - After research, ask the user specific questions about what they want
|
||||
3. **Present options** - Offer multiple approaches with trade-offs
|
||||
4. **Get explicit confirmation** - Never assume what the user wants
|
||||
|
||||
### Investigation vs Implementation
|
||||
|
||||
**CRITICAL:** When asked to investigate:
|
||||
|
||||
- **Investigation agents MUST NOT fix issues** - They should only identify, document, and report problems
|
||||
- **Always ask for confirmation** - After investigation, present findings and ask: "Should I proceed with implementing fixes?"
|
||||
- **Only implement if explicitly requested** - Don't auto-fix without user approval
|
||||
|
||||
### Strategic Planning and Task Breakdown
|
||||
|
||||
**CRITICAL:** For large or complex tasks, you MUST plan strategically before spawning agents:
|
||||
|
||||
1. **Break down the work** into small, focused tasks
|
||||
2. **Design the agent workflow**: What agents will you need? In what order?
|
||||
3. **Plan checkpoints**: Where do you need review agents? Test agents? Integration points?
|
||||
4. **Ensure each agent commits their work** before moving to the next phase
|
||||
5. **Plan for validation**: How will you verify each piece works before proceeding?
|
||||
|
||||
Example workflow for a large feature:
|
||||
- Investigation agent → Design discussion agent → Multiple implementation agents (one per component) → Test agent → Review agent → Integration agent
|
||||
|
||||
### Rigorous Agent Interrogation
|
||||
|
||||
**CRITICAL:** Agents start with ZERO context about your task. You must always provide complete context in your initial prompt.
|
||||
|
||||
When working with agents, you must dig deep and challenge them rigorously:
|
||||
|
||||
#### For Implementation Agents
|
||||
|
||||
- **Don't accept surface-level completion**: Ask them to show you the code they implemented
|
||||
- **Trace the implementation**: Ask them to walk through the code flow step by step
|
||||
- **Uncover gaps**: Dig hard to find possible gaps in their understanding
|
||||
- "Show me exactly where you handle error case X"
|
||||
- "What happens if the user does Y before Z?"
|
||||
- "Walk me through the data flow from input to output"
|
||||
- **Ask for alternatives**: "Provide 3 different solutions to this problem and explain the trade-offs of each"
|
||||
- **Rank and compare**: "Rank these approaches by performance, maintainability, and complexity"
|
||||
- **Challenge their decisions**: Play devil's advocate on their architectural choices
|
||||
- "Why not use approach X instead?"
|
||||
- "What are the downsides of your solution?"
|
||||
- "How will this scale?"
|
||||
|
||||
#### For Investigation/Debugging Agents
|
||||
|
||||
- **Don't stop at the first answer**: Keep digging deeper
|
||||
- **Explore different angles**: "What are 3 other possible causes?"
|
||||
- **Request proof**: "Show me the specific code that proves this hypothesis"
|
||||
- **Challenge assumptions**: "How do you know that's the root cause? What else could it be?"
|
||||
- **Ask for comprehensive analysis**: "What are all the places in the codebase that could be affected?"
|
||||
|
||||
#### For Review Agents
|
||||
|
||||
- **Security review**: "What are the security implications? Any OWASP vulnerabilities?"
|
||||
- **Edge cases**: "What edge cases are not handled?"
|
||||
- **Performance**: "Where are the performance bottlenecks?"
|
||||
- **Maintainability**: "How maintainable is this code? What would make it better?"
|
||||
|
||||
### Debugging with Logging and Playwright
|
||||
|
||||
**CRITICAL:** When debugging frontend or server issues:
|
||||
|
||||
- **Frontend debugging**: Use Playwright MCP to interact with the app at `http://localhost:8081`
|
||||
- Take screenshots to verify UI state
|
||||
- Click through flows to reproduce issues
|
||||
- Use browser console to check for errors
|
||||
- Verify network requests and responses
|
||||
- **Server debugging**: Add strategic logging to trace execution
|
||||
- Log request/response payloads
|
||||
- Log state transitions
|
||||
- Log error conditions
|
||||
- Use server logs to correlate with frontend behavior
|
||||
- **Full-stack debugging**: Combine both approaches
|
||||
- Use Playwright to trigger frontend actions
|
||||
- Check server logs to see backend behavior
|
||||
- Verify data flow from client → server → client
|
||||
|
||||
### Agent Management Principles
|
||||
|
||||
- **Keep agents focused** - Each agent should have a clear, specific responsibility
|
||||
- **You can talk to them** - Send prompts and guidance as they work
|
||||
- **Monitor progress** - Check status and provide feedback
|
||||
- **Always provide context** - Remember: agents start with zero knowledge of your task
|
||||
- **Verify work rigorously** - Don't trust, verify. Ask agents to prove their work
|
||||
- **Commit frequently** - Ensure each agent commits their changes before moving on
|
||||
- **Plan for quality gates** - Use test and review agents as checkpoints
|
||||
|
||||
**CRITICAL: ALWAYS RUN TYPECHECK AFTER EVERY CHANGE.**
|
||||
|
||||
@@ -112,6 +112,7 @@ export interface AgentToolCallData {
|
||||
callId?: string;
|
||||
displayName?: string;
|
||||
kind?: string;
|
||||
input?: unknown;
|
||||
result?: unknown;
|
||||
error?: unknown;
|
||||
parsedEdits?: EditEntry[];
|
||||
@@ -784,6 +785,7 @@ export function reduceStreamUpdate(
|
||||
callId: item.callId,
|
||||
displayName: item.displayName,
|
||||
kind: item.kind,
|
||||
input: item.input,
|
||||
result: item.output,
|
||||
error: item.error,
|
||||
},
|
||||
|
||||
@@ -1095,11 +1095,17 @@ class ClaudeAgentSession implements AgentSession {
|
||||
return structured;
|
||||
}
|
||||
|
||||
// Fallback to legacy format
|
||||
// Fallback format - try to parse JSON first
|
||||
const result: Record<string, unknown> = {};
|
||||
|
||||
if (content.length > 0) {
|
||||
result.result = { output: content };
|
||||
try {
|
||||
// If content is a JSON string, parse it
|
||||
result.output = JSON.parse(content);
|
||||
} catch {
|
||||
// If not JSON, return as-is (no extra wrapping)
|
||||
result.output = content;
|
||||
}
|
||||
}
|
||||
|
||||
// Preserve file changes tracked during tool execution
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# Tool Call Display Investigation Report
|
||||
|
||||
## Summary
|
||||
|
||||
Investigation into why tool call inputs and outputs are not displaying properly in the Claude agent UI.
|
||||
|
||||
## Findings
|
||||
|
||||
### Visual Evidence
|
||||
|
||||
I captured screenshots comparing standard tools vs MCP tools:
|
||||
|
||||
1. **Standard Tool (Grep) - Expanded View** (`standard-tool-grep-expanded.png`):
|
||||
- ✅ Shows "Result" section with full output data
|
||||
- ✅ Output displays correctly as JSON: `{ "result": { "output": "Found 9 files..." } }`
|
||||
|
||||
2. **MCP Tool (mcp__agent-control__list_agents) - Expanded View** (`mcp-tool-list-agents-expanded.png`):
|
||||
- ✅ Shows "Result" section with full output data
|
||||
- ✅ Output displays correctly with agent data: `{ "result": { "output": "{\"agents\":[...]" } }`
|
||||
|
||||
### Key Discovery
|
||||
|
||||
**Both standard tools AND MCP tools ARE displaying their output correctly!**
|
||||
|
||||
The output data is being passed through the pipeline successfully from server → client → UI.
|
||||
|
||||
## Root Cause: Missing Input Data for MCP/Server Tools
|
||||
|
||||
### Location
|
||||
|
||||
File: `packages/server/src/server/agent/providers/claude-agent.ts`
|
||||
|
||||
### The Bug (Line 1253-1258)
|
||||
|
||||
```typescript
|
||||
private upsertToolUseEntry(block: ClaudeContentChunk): ToolUseCacheEntry | null {
|
||||
// ... setup code ...
|
||||
|
||||
if (block.type === "tool_use") { // ← BUG: Only checks for standard tools
|
||||
const input = this.normalizeToolInput(block.input);
|
||||
if (input) {
|
||||
this.applyToolInput(existing, input);
|
||||
}
|
||||
}
|
||||
|
||||
this.toolUseCache.set(id, existing);
|
||||
return existing;
|
||||
}
|
||||
```
|
||||
|
||||
### Why This Is a Problem
|
||||
|
||||
1. **Tool Types in the Codebase**:
|
||||
- Standard tools: `block.type === "tool_use"`
|
||||
- MCP tools: `block.type === "mcp_tool_use"`
|
||||
- Server tools: `block.type === "server_tool_use"`
|
||||
|
||||
2. **What Happens**:
|
||||
- When a tool call starts (line 1003-1008), the code handles ALL three types
|
||||
- But `upsertToolUseEntry` only captures input for `"tool_use"` type
|
||||
- MCP and server tools skip the input capture logic entirely
|
||||
- `existing.input` remains `undefined`
|
||||
|
||||
3. **Impact on Display**:
|
||||
- When `handleToolUseStart` is called (line 1044), it uses:
|
||||
```typescript
|
||||
input: entry.input ?? this.normalizeToolInput(block.input)
|
||||
```
|
||||
- Since `entry.input` is undefined for MCP tools, it falls back to `block.input`
|
||||
- However, by this point the input may not be properly normalized
|
||||
|
||||
### Evidence from Code
|
||||
|
||||
**Tool type handling (lines 1003-1008)**:
|
||||
```typescript
|
||||
case "tool_use":
|
||||
case "server_tool_use":
|
||||
case "mcp_tool_use": {
|
||||
this.handleToolUseStart(block, items); // Handles all three types
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
**Input capture logic (lines 1253-1258)** - ONLY handles `"tool_use"`:
|
||||
```typescript
|
||||
if (block.type === "tool_use") {
|
||||
const input = this.normalizeToolInput(block.input);
|
||||
if (input) {
|
||||
this.applyToolInput(existing, input);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## What IS Working
|
||||
|
||||
- ✅ **Output display**: Both standard and MCP tools show their output correctly
|
||||
- ✅ **Tool call buttons**: All tool calls appear in the timeline
|
||||
- ✅ **Tool names**: Correctly labeled (e.g., "Grep", "mcp__agent-control__list_agents")
|
||||
- ✅ **Status indicators**: Success/failure states display properly
|
||||
|
||||
## What Is NOT Working
|
||||
|
||||
- ❌ **Input parameters for MCP tools**: Not captured in `upsertToolUseEntry`
|
||||
- ❌ **Input parameters for server tools**: Not captured in `upsertToolUseEntry`
|
||||
|
||||
## Recommended Fix
|
||||
|
||||
Update `upsertToolUseEntry` to handle all tool types:
|
||||
|
||||
```typescript
|
||||
if (block.type === "tool_use" || block.type === "mcp_tool_use" || block.type === "server_tool_use") {
|
||||
const input = this.normalizeToolInput(block.input);
|
||||
if (input) {
|
||||
this.applyToolInput(existing, input);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Methodology
|
||||
|
||||
1. Created a test agent that invoked multiple tool types:
|
||||
- Standard tools: Read, Write, Edit, Bash, Glob, Grep
|
||||
- MCP tools: mcp__agent-control__list_agents, mcp__agent-control__create_agent
|
||||
|
||||
2. Used Playwright MCP to navigate the UI and expand tool calls
|
||||
|
||||
3. Captured screenshots of expanded views showing:
|
||||
- Standard tool (Grep) with full Result display
|
||||
- MCP tool (list_agents) with full Result display
|
||||
|
||||
4. Verified both show output correctly but suspected input issue based on code analysis
|
||||
|
||||
## Files Involved
|
||||
|
||||
- `packages/server/src/server/agent/providers/claude-agent.ts` - Server-side tool processing
|
||||
- `packages/app/src/components/message.tsx` - UI rendering (line 1282+)
|
||||
- `packages/app/src/types/agent-activity.ts` - Data models
|
||||
- `packages/app/src/utils/tool-call-parsers.ts` - Tool call parsing logic
|
||||
|
||||
## Conclusion
|
||||
|
||||
The investigation confirms that:
|
||||
1. Output data IS being displayed correctly for all tool types
|
||||
2. The input capture bug at line 1253 in claude-agent.ts prevents MCP and server tool inputs from being stored
|
||||
3. A simple fix to check for all three tool types will resolve the input display issue
|
||||
|
||||
The UI rendering components are working correctly - they just need the input data to be properly provided by the server.
|
||||
|
||||
## Fix Applied
|
||||
|
||||
The fix has been implemented at line 1253 in `claude-agent.ts`:
|
||||
|
||||
```typescript
|
||||
// BEFORE:
|
||||
if (block.type === "tool_use") {
|
||||
|
||||
// AFTER:
|
||||
if (block.type === "tool_use" || block.type === "mcp_tool_use" || block.type === "server_tool_use") {
|
||||
```
|
||||
|
||||
## Verification Required
|
||||
|
||||
To verify the fix works:
|
||||
|
||||
1. **Restart the server** - The voice-dev tmux session needs to be restarted for TypeScript changes to take effect
|
||||
2. **Test MCP tools** - Create a new agent and invoke MCP tools like `mcp__agent-control__list_agents`
|
||||
3. **Check Input display** - Expand the MCP tool calls in the UI and verify that:
|
||||
- Input parameters are now visible (not just undefined)
|
||||
- The Input section shows properly formatted data
|
||||
4. **Compare** - Take before/after screenshots showing input data now appears
|
||||
|
||||
The output was already working (as proven by screenshots), so the verification should focus on confirming that **input parameters** now display for MCP and server tools.
|
||||
Reference in New Issue
Block a user