feat: Add subagent tool for focused subtasks

[kels-ng]

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.

Benefits:

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

Related GitHub Issue

Closes: #11741

Roo Code Task Context (Optional)

Description

This PR adds the subagent tool so the model can run a focused sub-task in the background and receive its result back in the main task.

Implementation overview:

• Types & experiments: subagent is added to experimentIds, experimentsSchema, and toolNames; message types support subagentRunning / subagentCompleted and progressStatus.spin; ClineSayTool includes optional fields for subagent payloads.
• Shared layer: New src/shared/subagent.ts with constants and types; tools.ts extended with subagent_type and description params and TOOL_DISPLAY_NAMES.subagent; SUBAGENT experiment (off by default) in experiments.ts.
• Core flow: NativeToolCallParser handles subagent (description, prompt, subagent_type); presentAssistantMessage wires subagent progress and delegates to SubagentTool; SubagentTool validates args, emits running/completed tool messages, calls provider.runSubagentInBackground, and pushes the tool result (string or structured e.g. cancelled).
• Task & build-tools: Task gains subagentType, needUpdateHistory, reportSubagentProgress, runBackgroundSubagentLoop, and backgroundCompletionResolve; build-tools applies applySubagentToolRestrictions (explore = read-only + attempt_completion; all subagents exclude subagent + ask_followup_question, new_task, switch_mode, update_todo_list).
• ClineProvider: Cancel path only cancels the active subagent when one is running; runSubagentInBackground creates a child Task, runs runBackgroundSubagentLoop, and returns a Promise that resolves via backgroundCompletionResolve (or rejects on error).
• AttemptCompletion: When task.backgroundCompletionResolve is set, completion resolves that, clears callbacks, and aborts the task (subagent exit path).
• Webview: ChatRow renders subagentRunning (description, progress, optional spin) and subagentCompleted (result/error/resultCode/messageKey); CodeAccordion supports progressStatus.spin.
• i18n: All locales get subagents in chat.json and SUBAGENT experiment name/description in settings.json.

Design choices:

• Subagent is gated by an experiment (default off) so behavior is unchanged until opted in.
• Only Roo-existing tools are in SUBAGENT_EXCLUDE_TOOLS (no kilocode-specific tools).
• Subagent tool is included in ALWAYS_AVAILABLE_TOOLS for filtering but actually allowed only when the experiment is on (see filter-tools-for-mode).

Test Procedure

Unit tests (run from repo root):

1. Subagent tool & parsing: cd src && pnpm exec vitest run core/tools/__tests__/SubagentTool.spec.ts core/assistant-message/__tests__/NativeToolCallParser.spec.ts — SubagentTool parseLegacy/execute and NativeToolCallParser subagent cases.
2. Filter & task: cd src && pnpm exec vitest run core/prompts/tools/__tests__/filter-tools-for-mode.spec.ts core/task/__tests__/flushPendingToolResultsToHistory.spec.ts — subagent experiment filtering and reportSubagentProgress.
3. Shared experiments: Run src/shared tests (e.g. experiments.spec.ts) to confirm SUBAGENT in experiment config and test records.

Manual testing:

1. Enable the Subagent experiment in Settings → Experimental.
2. Start a task and ask the model to run a sub-task (e.g. “Use a subagent to list all exports in the src folder” or “Run a read-only subagent to search for usages of X”).
3. Confirm chat shows “Running subagent: …” with progress, then “Subagent completed” with result; cancel during run and confirm “cancelled by user” message and that the main task continues.
4. With experiment off, confirm the subagent tool is not available or not called.

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Documentation Impact: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Screenshots / Videos

Documentation Updates

• No documentation updates are required.
• Yes, documentation updates are required. (e.g. document the Subagent experiment and when to use explore vs general.)

Additional Notes

• Subagent is off by default; no behavior change until the user enables the experiment.

Get in Touch

Discord: kels9009
Telegram: kelsnewman

Interactively review PR in Roo Code Cloud

[RuntimeRacer]

Does this also support sending off multiple Subagents in parallel and waiting for the result?

I might play around with this today to check how reliably this works with my GSD-Roo port I created yesterday:
gsd-build/get-shit-done#830

It works well with Subtasks already, so I guess this will already be a nice abstraction layer for agents which don't need supervision.
But if I could offload multiple research agents in parallel during a research phase this would allow me to bury Claude Code I guess. :-)

[kels-ng]

Does this also support sending off multiple Subagents in parallel and waiting for the result?

I might play around with this today to check how reliably this works with my GSD-Roo port I created yesterday: gsd-build/get-shit-done#830

It works well with Subtasks already, so I guess this will already be a nice abstraction layer for agents which don't need supervision. But if I could offload multiple research agents in parallel during a research phase this would allow me to bury Claude Code I guess. :-)

Hello,

Good point. I checked and add parallel subagent execution:

Also, rebase on top of HEAD.

[kels-ng]

@cte @daniel-lxs Any thoughts about the PR?