[ENHANCEMENT] Custom Tools: Streaming Output Support & NPM Package Dependencies for Agent Orchestration Workflows

[ilxqx]

Summary

I'd like to propose two enhancements to the experimental Custom Tools feature (introduced in v3.37) that would unlock powerful agent orchestration capabilities:

1. Streaming output support - Allow tools to emit progress/logs in real-time to the Roo Code UI
2. NPM package dependencies - Enable tools to use external npm packages

These enhancements would enable building sophisticated multi-agent workflows by orchestrating tools like Claude Agent SDK (@anthropic-ai/claude-agent-sdk) and OpenAI Codex CLI directly within Roo Code.

---

Problem Statement

1. Long-running tools provide no feedback

Currently, Custom Tools can only return results after complete execution. For complex workflows that may take several minutes (e.g., orchestrating multiple AI coding agents), users face:

• Anxiety from silent waiting - No indication of progress or what's happening
• Uncertainty about success/failure - Can't tell if the tool is stuck or working
• Poor debugging experience - Can't see intermediate steps when something goes wrong

2. No support for npm dependencies

Custom Tools currently cannot easily use npm packages. This severely limits the creative potential:

• Cannot use @anthropic-ai/claude-agent-sdk (Claude Agent SDK)
• Cannot use @openai/codex (Codex CLI SDK)
• Cannot leverage the rich npm ecosystem for HTTP clients, parsers, utilities, etc.

---

Use Case: Multi-Agent Coding Orchestration with Claude Agent SDK

I want to build a Custom Tool that orchestrates Claude Agent SDK to solve complex coding tasks. The SDK returns an AsyncGenerator<SDKMessage> that streams messages in real-time, but without Roo Code Custom Tools supporting streaming output, all these real-time events are lost - users see nothing until the entire task completes.

Current Limitation (No Streaming)

// .roo/tools/claude-agent-task.ts
import { query } from '@anthropic-ai/claude-agent-sdk'

export const name = "claude_agent_task"
export const description = "Execute a complex coding task using Claude Agent SDK"

export const parameters = {
  type: "object",
  properties: {
    task: { type: "string", description: "The coding task to accomplish" },
    cwd: { type: "string", description: "Working directory for the task" }
  },
  required: ["task"]
}

export async function execute(args: { task: string; cwd?: string }) {
  const result = query({
    prompt: args.task,
    options: {
      cwd: args.cwd || process.cwd(),
      permissionMode: 'acceptEdits',
      includePartialMessages: true,  // SDK supports streaming!
    }
  })

  const messages: string[] = []
  let finalResult: any = null

  // SDK streams messages via AsyncGenerator - BUT we can't forward them to UI!
  for await (const message of result) {
    if (message.type === 'assistant') {
      // We receive real-time assistant messages...
      // ...but can't show them to the user until execute() returns
      messages.push(`[Assistant] ${JSON.stringify(message.message)}`)
    } 
    else if (message.type === 'stream_event') {
      // Partial streaming events available...
      // ...but user sees nothing during the 5-10 minute execution
      messages.push(`[Stream] ${message.event.type}`)
    }
    else if (message.type === 'result') {
      finalResult = message
    }
  }

  // User finally sees output only after everything completes
  return {
    success: finalResult?.subtype === 'success',
    result: finalResult?.result,
    cost: finalResult?.total_cost_usd,
    usage: finalResult?.usage,
    // All the streaming messages are dumped at once - terrible UX
    transcript: messages
  }
}

Problem: The Claude Agent SDK beautifully streams SDKAssistantMessage, SDKPartialAssistantMessage, tool use events, etc. in real-time. But since Roo Code Custom Tools don't support streaming output, users stare at a blank screen for 5-10+ minutes while the agent works.

---

Ideal Implementation (With Streaming Support)

// .roo/tools/claude-agent-task.ts
import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk'

export const name = "claude_agent_task"
export const description = "Execute a complex coding task using Claude Agent SDK with real-time progress"

export const parameters = {
  type: "object",
  properties: {
    task: { type: "string", description: "The coding task to accomplish" },
    cwd: { type: "string", description: "Working directory" }
  },
  required: ["task"]
}

// PROPOSED: AsyncGenerator pattern for streaming
export async function* execute(args: { task: string; cwd?: string }) {
  yield { type: "progress", message: "🚀 Starting Claude Agent..." }

  const result = query({
    prompt: args.task,
    options: {
      cwd: args.cwd || process.cwd(),
      permissionMode: 'acceptEdits',
      includePartialMessages: true,
    }
  })

  let finalResult: any = null

  for await (const message of result) {
    // Stream each SDK message to Roo Code UI in real-time!
    if (message.type === 'system' && message.subtype === 'init') {
      yield { 
        type: "progress", 
        message: `📋 Session started: ${message.session_id}\n🔧 Tools: ${message.tools.join(', ')}` 
      }
    }
    else if (message.type === 'assistant') {
      // Show assistant's thinking/response as it happens
      const content = message.message.content
      for (const block of content) {
        if (block.type === 'text') {
          yield { type: "stream", content: block.text }
        } else if (block.type === 'tool_use') {
          yield { 
            type: "progress", 
            message: `🔨 Using tool: ${block.name}` 
          }
        }
      }
    }
    else if (message.type === 'stream_event') {
      // Forward partial streaming for real-time text display
      if (message.event.type === 'content_block_delta') {
        const delta = message.event.delta
        if (delta.type === 'text_delta') {
          yield { type: "stream", content: delta.text }
        }
      }
    }
    else if (message.type === 'result') {
      finalResult = message
    }
  }

  yield { 
    type: "progress", 
    message: `✅ Completed! Cost: $${finalResult?.total_cost_usd?.toFixed(4)}` 
  }

  // Final result for AI to consume
  return {
    success: finalResult?.subtype === 'success',
    result: finalResult?.result,
    cost: finalResult?.total_cost_usd,
    usage: finalResult?.usage
  }
}

Multi-Agent Orchestration Example

// .roo/tools/multi-agent-review.ts
import { query } from '@anthropic-ai/claude-agent-sdk'

export const name = "multi_agent_code_review"
export const description = "Use one Claude agent to implement, another to review"

export const parameters = {
  type: "object",
  properties: {
    feature: { type: "string", description: "Feature to implement" }
  },
  required: ["feature"]
}

export async function* execute(args: { feature: string }) {
  // Phase 1: Implementation Agent
  yield { type: "progress", message: "🔨 Phase 1: Implementation Agent starting..." }
  
  const implAgent = query({
    prompt: `Implement this feature: ${args.feature}`,
    options: {
      permissionMode: 'acceptEdits',
      includePartialMessages: true,
      model: 'claude-sonnet-4-20250514'
    }
  })

  let implResult: any
  for await (const msg of implAgent) {
    if (msg.type === 'stream_event' && msg.event.type === 'content_block_delta') {
      const delta = msg.event.delta as any
      if (delta.text) {
        yield { type: "stream", content: delta.text }
      }
    }
    if (msg.type === 'result') implResult = msg
  }

  yield { type: "progress", message: `\n\n📝 Implementation complete. Cost: $${implResult?.total_cost_usd?.toFixed(4)}` }

  // Phase 2: Review Agent  
  yield { type: "progress", message: "\n🔍 Phase 2: Review Agent starting..." }
  
  const reviewAgent = query({
    prompt: `Review the code changes just made for: ${args.feature}. Look for bugs, security issues, and suggest improvements.`,
    options: {
      permissionMode: 'plan', // Review only, no edits
      includePartialMessages: true,
      model: 'claude-sonnet-4-20250514'
    }
  })

  let reviewResult: any
  for await (const msg of reviewAgent) {
    if (msg.type === 'stream_event' && msg.event.type === 'content_block_delta') {
      const delta = msg.event.delta as any
      if (delta.text) {
        yield { type: "stream", content: delta.text }
      }
    }
    if (msg.type === 'result') reviewResult = msg
  }

  yield { type: "progress", message: `\n\n✅ Review complete. Total cost: $${((implResult?.total_cost_usd || 0) + (reviewResult?.total_cost_usd || 0)).toFixed(4)}` }

  return {
    success: true,
    implementation: implResult?.result,
    review: reviewResult?.result,
    totalCost: (implResult?.total_cost_usd || 0) + (reviewResult?.total_cost_usd || 0)
  }
}

---

Proposed API for Streaming

Option A: AsyncGenerator Pattern (Recommended)

// Tools can be async generators
export async function* execute(args) {
  yield { type: "stream", content: "Real-time text..." }    // Append to output
  yield { type: "progress", message: "Status update" }      // Show as status line
  yield { type: "log", level: "debug", message: "..." }     // Collapsible debug info
  
  return finalResult  // Final result for AI consumption
}

Option B: Context Callback

export async function execute(args, context) {
  context.stream("Real-time text...")
  context.progress("50% complete")
  context.log("Debug info")
  
  return finalResult
}

---

NPM Dependencies Proposal

Recommended: Tool-local package.json

.roo/
└── tools/
    ├── package.json              # Tool dependencies
    ├── node_modules/             # Installed packages (gitignored)
    ├── claude-agent-task.ts
    └── multi-agent-review.ts

// .roo/tools/package.json
{
  "name": "roo-custom-tools",
  "private": true,
  "type": "module",
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.76",
    "zod": "^4.2.1"
  }
}

Roo Code could:

1. Detect .roo/tools/package.json on startup
2. Auto-run npm install if node_modules is missing/stale
3. Bundle dependencies when compiling tools with esbuild

---

Benefits

Feature	Benefit
Streaming output	Real-time feedback from long-running agent tasks
NPM dependencies	Use official SDKs (Claude, OpenAI, etc.) in tools
Combined	Build powerful AI agent orchestration directly in Roo Code

Specific Use Cases Enabled

1. Claude Agent SDK Integration - Stream agent work in real-time
2. Multi-Agent Workflows - Orchestrate multiple AI agents (implement → review → test)
3. Codex CLI Integration - Use OpenAI's coding agent
4. Complex CI/CD - Stream build/test/deploy progress
5. Data Processing Pipelines - Show progress for batch operations

---

Why This Matters

The Claude Agent SDK is designed for streaming - it returns AsyncGenerator<SDKMessage> with rich event types:

• SDKAssistantMessage - Complete assistant responses
• SDKPartialAssistantMessage - Real-time streaming chunks
• SDKSystemMessage - Session initialization
• SDKResultMessage - Final results with cost/usage

Without Custom Tools streaming support, we lose all this real-time capability. Users must wait 5-10+ minutes seeing nothing, then receive a massive dump of output. This is a significant UX degradation.

---

Related

• PR Custom tool calling #10083 - Custom Tools implementation
• PR feat: implement streaming for native tool calls #9542 - Native tool call streaming (for built-in tools)
• Claude Agent SDK Documentation

[cte]

@ilxqx - Thanks for the feedback. I agree with both suggestions and we'll add support for both soon, so stay tuned. We intended to properly support npm package dependencies for the initial version, so it's a bug that it's not working out of the box.

[cte]

Partly addressed by: #10336

[ilxqx]

Thanks for the quick update and the PR! It's great to hear that both features are on the roadmap. I'll keep an eye on PR #10336 and look forward to trying it out once fully merged.