[ENHANCEMENT] Add subagent tool to offload focused tasks

[kels-ng]

Problem (one or two sentences)

Add a subagent tool so the model can run a focused sub-task in the background. The subagent’s result or summary is returned as the tool result and the main task continues in the same chat, without creating a new user-visible task.

Context (who is affected and when)

• Keeps context in one place – Research, exploration, or multi-step sub-tasks can be done without switching to a new task or losing the current conversation. Reduce context pollution in main chat.
• Clearer control – subagent_type lets users and the model choose read-only exploration vs. sub-tasks that may edit files or run commands.
• Better flow – The main task gets a single, structured result from the subagent instead of long inline outputs, so the model can reason and continue more reliably.
• Fits existing mental model – Subagents are for offloading work inside a task; creating a new user-visible task stays the job of the existing new_task tool.

Desired behavior (conceptual, not technical)

• The model calls the subagent tool with:

  • description – Short label shown in the chat (e.g. “List exports in src”, “Check README”).
  • prompt – Full instructions for the subagent. Its result/summary is returned as the tool result.
  • subagent_type – "explore" (read-only: search, list, read only) or "general" (full tools: read, edit, run commands).

• The sub-task runs in the background; the user stays in the current task.

• Progress is shown in the chat (e.g. “Running subagent: …”, current step).

• When the subagent finishes (or is cancelled), its result is passed back to the model as the tool result so the main task can use it in the next step.

Constraints / preferences (optional)

• Feature is experiment-gated (e.g. under Settings → Experimental). Default: off, so current behavior is unchanged until users opt in.
• When enabled, the model can call the subagent tool when it needs to offload a focused sub-task or do read-only exploration without leaving the current task.

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

Roo Code Task Links (optional)

No response

Acceptance criteria (optional)

No response

Proposed approach (optional)

No response

Trade-offs / risks (optional)

No response

[roomote]

I've analyzed this issue and the existing codebase architecture. Here's my proposed implementation plan for the subagent tool:

Proposed Implementation Plan

Overview

The subagent tool lets the model spin up a focused sub-task that runs within the current task context, returning its result/summary as the tool result. Unlike new_task (which delegates to a new user-visible task), the subagent runs "inline" and feeds its output back to the calling model.

Key Files to Modify/Create

1. Register the tool name and types

• packages/types/src/tool.ts -- Add "sub_agent" to the toolNames array so it becomes a valid ToolName.
• packages/types/src/experiment.ts -- Add "subAgent" to experimentIds and update experimentsSchema.
• src/shared/experiments.ts -- Add SUB_AGENT to EXPERIMENT_IDS and experimentConfigsMap (default: disabled).

2. Define the native tool schema (for LLM prompt)

• src/core/prompts/tools/native-tools/sub_agent.ts (new file) -- OpenAI function-calling definition with parameters: description (string), prompt (string), subagent_type ("explore" | "general").
• src/core/prompts/tools/native-tools/index.ts -- Import and add subAgent to getNativeTools().

3. Add tool type definitions

• src/shared/tools.ts -- Add sub_agent to NativeToolArgs, add SubAgentToolUse interface, add to TOOL_DISPLAY_NAMES, add to ALWAYS_AVAILABLE_TOOLS or an appropriate tool group, and add param names (description, subagent_type) to toolParamNames.

4. Implement the tool execution class

• src/core/tools/SubAgentTool.ts (new file) -- Extends BaseTool<"sub_agent">. Key behavior:
  • Validates prompt (required), description (required), and subagent_type (default: "explore").
  • Asks user approval (showing description and subagent_type).
  • Creates a lightweight, non-user-visible Task instance with restricted tool access:
    • "explore" mode: only read tools (read_file, search_files, list_files, codebase_search).
    • "general" mode: full tool access (read + edit + command).
  • Runs the subagent Task to completion (or cancellation/error).
  • Collects the subagent's final output (e.g., via attempt_completion result).
  • Returns the subagent's result as pushToolResult(...) to the parent model.

5. Wire up tool parsing and execution dispatch

• src/core/assistant-message/NativeToolCallParser.ts -- Add "sub_agent" case for streaming partial args.
• src/core/assistant-message/presentAssistantMessage.ts -- Import subAgentTool and add a case "sub_agent": block that calls subAgentTool.handle(...).

6. Experiment-gate the tool

• src/core/prompts/tools/filter-tools-for-mode.ts -- Add a check like the existing generate_image/run_slash_command pattern: if !experiments?.subAgent, exclude "sub_agent" from the allowed tool set.
• src/core/tools/validateToolUse.ts -- Ensure experiment gating works for validation.

7. UI: Show subagent progress in chat

• Add a new ClineAsk/ClineSay message type (e.g., "sub_agent") so the webview can render progress. The tool's handlePartial will emit streaming updates (description, current step) and the final result will appear in the chat as a collapsible section.
• webview-ui/src/components/chat/ -- Add rendering for subagent progress/result messages.

8. Settings UI: Experimental toggle

• webview-ui/src/components/settings/ExperimentalSettings.tsx -- Add a toggle for "Sub-Agent" under the existing Experimental Features section.

9. Auto-approval

• src/core/auto-approval/index.ts -- Add "sub_agent" alongside "newTask"/"finishTask" in the subtask approval check so alwaysAllowSubtasks covers subagents too.

Design Decisions & Trade-offs

• Non-blocking vs blocking: The subagent tool call is "blocking" from the parent model's perspective (the model waits for the tool result, just like any other tool). The user sees progress in the chat while it runs.
• Subagent Task reuse: The subagent will reuse the existing Task class but configured with restricted tools and no user-visible tab/history entry. This maximizes code reuse.
• Token budget: The subagent gets its own conversation context, so it won't bloat the parent's context window. Only the final summary is returned.
• Cancellation: If the user cancels the subagent, a cancellation message is returned as the tool result so the parent can handle it gracefully.
• Nesting: Initially, subagents should not be allowed to call sub_agent themselves (prevents runaway recursion). This can be relaxed later with a depth limit.

Test Plan

• Unit tests for SubAgentTool (parameter validation, explore vs general tool restrictions, error handling).
• Unit tests for experiment gating (tool excluded when experiment disabled).
• Integration test: subagent runs read-only tools and returns result.
• Integration test: subagent cancellation returns appropriate message.

This is a substantial feature. I'd suggest tackling it incrementally, starting with the experiment gate + tool definition + basic explore-only subagent, then expanding to general mode and UI polish.

Please mention @roomote in a comment saying that you approve this plan, and I'll proceed with the implementation.