feat(core): add dynamic swarm worker tool (#3433)

* feat(core): add dynamic swarm worker tool

  Add a swarm tool for ad-hoc parallel worker execution with bounded concurrency, wait-all and first-success modes, per-worker failure
  isolation, and aggregated results.

  Register the tool in core, prevent nested worker recursion, and document the new workflow.

* fix(core): harden swarm worker execution

  Prevent swarm calls from bypassing the outer scheduler concurrency budget.

  Disallow interactive question prompts in swarm workers by default, and avoid incomplete Markdown table escaping by using an HTML entity for
  pipe characters. Add focused tests for the scheduler behavior, worker tool restrictions, and result formatting.

Author: reidliu41

docs/developers/tools/_meta.ts

@@ -5,6 +5,7 @@ export default {
   shell: 'Shell',
   'todo-write': 'Todo Write',
   task: 'Task',
+  swarm: 'Swarm',
   'exit-plan-mode': 'Exit Plan Mode',
   'web-fetch': 'Web Fetch',
   'web-search': 'Web Search',

docs/developers/tools/introduction.md

@@ -51,6 +51,7 @@ Qwen Code's built-in tools can be broadly categorized as follows:
 - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions.
 - **[Todo Write Tool](./todo-write.md) (`todo_write`):** For creating and managing structured task lists during coding sessions.
 - **[Task Tool](./task.md) (`task`):** For delegating complex tasks to specialized subagents.
+- **[Swarm Tool](./swarm.md) (`swarm`):** For running many independent lightweight workers in parallel and aggregating their results.
 - **[Exit Plan Mode Tool](./exit-plan-mode.md) (`exit_plan_mode`):** For exiting plan mode and proceeding with implementation.
 
 Additionally, these tools incorporate:

docs/developers/tools/swarm.md

@@ -0,0 +1,102 @@
+# Swarm Tool (`swarm`)
+
+Use `swarm` to run many independent, simple tasks through ephemeral worker
+agents and return a structured aggregate result to the parent agent.
+
+Swarm is intended for map-reduce style work:
+
+- analyzing many files independently
+- processing chunks of a large data file
+- running independent searches where the first successful result is enough
+- collecting per-item summaries, counts, or validation results
+
+For a few complex role-based tasks, use the [`task`](./task.md) tool instead.
+For model comparison on the same task, use Agent Arena.
+
+## Arguments
+
+- `description` (string, required): Short description of the overall swarm job.
+- `tasks` (array, required): Independent tasks. Each task becomes one worker.
+  - `id` (string, optional): Stable identifier returned in results.
+  - `description` (string, required): Short per-worker description.
+  - `prompt` (string, required): Complete instructions for the worker.
+- `mode` (`wait_all` or `first_success`, optional): Defaults to `wait_all`.
+- `max_concurrency` (number, optional): Maximum workers to run at once.
+- `max_turns` (number, optional): Maximum model/tool turns per worker.
+  Defaults to `8`.
+- `timeout_seconds` (number, optional): Per-worker wall-clock timeout.
+- `worker_system_prompt` (string, optional): Shared worker system prompt.
+- `allowed_tools` (string array, optional): Tool allowlist for workers.
+- `disallowed_tools` (string array, optional): Tools removed from workers.
+
+If `max_concurrency` is omitted, Qwen Code uses
+`QWEN_CODE_MAX_SWARM_CONCURRENCY`, then `QWEN_CODE_MAX_TOOL_CONCURRENCY`, then
+`10`.
+
+## Result
+
+The tool returns JSON to the parent agent with:
+
+- `summary.total`
+- `summary.completed`
+- `summary.failed`
+- `summary.cancelled`
+- `summary.notStarted`
+- `results[]` with one entry per task, including `taskId`, `status`, `output`
+  or `error`, duration, and execution stats when available
+
+Individual worker failures do not abort the whole swarm. The parent agent is
+responsible for reading the aggregate result and presenting the final answer.
+
+## Examples
+
+Analyze files in parallel:
+
+```text
+swarm(
+  description="Extract function names",
+  tasks=[
+    {
+      id="src/a.ts",
+      description="Analyze src/a.ts",
+      prompt="Read /repo/src/a.ts and return the exported function names."
+    },
+    {
+      id="src/b.ts",
+      description="Analyze src/b.ts",
+      prompt="Read /repo/src/b.ts and return the exported function names."
+    }
+  ],
+  max_concurrency=10
+)
+```
+
+Use first successful result:
+
+```text
+swarm(
+  description="Find API route definition",
+  mode="first_success",
+  tasks=[
+    {
+      description="Search routes directory",
+      prompt="Search /repo/src/routes for the user creation route."
+    },
+    {
+      description="Search controllers directory",
+      prompt="Search /repo/src/controllers for the user creation route."
+    }
+  ]
+)
+```
+
+## Notes
+
+Workers are lightweight and ephemeral: they are spawned, execute one task,
+return a result, and are cleaned up. Workers cannot spawn further subagents or
+cron jobs.
+
+Swarm workers run concurrently, so interactive permission prompts are avoided.
+Permission hooks can still approve actions, and permissive approval modes still
+apply where configured. Prefer read-only or disjoint file scopes for swarm
+tasks.

docs/users/features/arena.md

@@ -199,9 +199,9 @@ Agent Arena is experimental. Current limitations:
 
 ## Comparison with other multi-agent modes
 
-Agent Arena is one of several planned multi-agent modes in Qwen Code. **Agent Team** and **Agent Swarm** are not yet implemented — the table below describes their intended design for reference.
+Agent Arena is one of several multi-agent modes in Qwen Code. **Agent Team** is not yet implemented. **Agent Swarm** is available as a lightweight tool for batch-style parallel worker execution.
 
-|                   | **Agent Arena**                                        | **Agent Team** (planned)                           | **Agent Swarm** (planned)                                |
+|                   | **Agent Arena**                                        | **Agent Team** (planned)                           | **Agent Swarm**                                          |
 | :---------------- | :----------------------------------------------------- | :------------------------------------------------- | :------------------------------------------------------- |
 | **Goal**          | Competitive: Find the best solution to the _same_ task | Collaborative: Tackle _different_ aspects together | Batch parallel: Dynamically spawn workers for bulk tasks |
 | **Agents**        | Pre-configured models compete independently            | Teammates collaborate with assigned roles          | Workers spawned on-the-fly, destroyed on completion      |

packages/core/src/agents/runtime/agent-core.ts

@@ -72,6 +72,7 @@ import { type ContextState, templateString } from './agent-headless.js';
  */
 export const EXCLUDED_TOOLS_FOR_SUBAGENTS: ReadonlySet<string> = new Set([
   ToolNames.AGENT,
+  ToolNames.SWARM,
   ToolNames.CRON_CREATE,
   ToolNames.CRON_LIST,
   ToolNames.CRON_DELETE,

packages/core/src/config/config.ts

@@ -2463,6 +2463,10 @@ export class Config {
       const { AgentTool } = await import('../tools/agent/agent.js');
       return new AgentTool(this);
     });
+    await registerLazy(ToolNames.SWARM, async () => {
+      const { SwarmTool } = await import('../tools/swarm.js');
+      return new SwarmTool(this);
+    });
     await registerLazy(ToolNames.SKILL, async () => {
       const { SkillTool } = await import('../tools/skill.js');
       return new SkillTool(this);

packages/core/src/core/coreToolScheduler.test.ts

@@ -43,6 +43,7 @@ import type { HookExecutionResponse } from '../confirmation-bus/types.js';
 import { type NotificationType } from '../hooks/types.js';
 import type { MessageBus } from '../confirmation-bus/message-bus.js';
 import { IdeClient } from '../ide/ide-client.js';
+import { ToolNames } from '../tools/tool-names.js';
 
 vi.mock('fs/promises', () => ({
   writeFile: vi.fn(),
@@ -3167,6 +3168,61 @@ describe('Fire hook functions integration', () => {
       expect(startIndices.every((i) => i < firstEnd)).toBe(true);
     });
 
+    it('should execute multiple swarm tools sequentially', async () => {
+      const executionLog: string[] = [];
+
+      const swarmTool = new MockTool({
+        name: ToolNames.SWARM,
+        execute: async (params) => {
+          const id = (params as { id: string }).id;
+          executionLog.push(`swarm:start:${id}`);
+          await new Promise((r) => setTimeout(r, 50));
+          executionLog.push(`swarm:end:${id}`);
+          return {
+            llmContent: `Swarm ${id} done`,
+            returnDisplay: `Swarm ${id} done`,
+          };
+        },
+      });
+
+      const tools = new Map([[ToolNames.SWARM, swarmTool]]);
+      const onAllToolCallsComplete = vi.fn();
+      const onToolCallsUpdate = vi.fn();
+      const scheduler = createScheduler(
+        tools,
+        onAllToolCallsComplete,
+        onToolCallsUpdate,
+      );
+
+      await scheduler.schedule(
+        [
+          {
+            callId: '1',
+            name: ToolNames.SWARM,
+            args: { id: 'A' },
+            isClientInitiated: false,
+            prompt_id: 'p1',
+          },
+          {
+            callId: '2',
+            name: ToolNames.SWARM,
+            args: { id: 'B' },
+            isClientInitiated: false,
+            prompt_id: 'p1',
+          },
+        ],
+        new AbortController().signal,
+      );
+
+      expect(onAllToolCallsComplete).toHaveBeenCalled();
+      expect(executionLog).toEqual([
+        'swarm:start:A',
+        'swarm:end:A',
+        'swarm:start:B',
+        'swarm:end:B',
+      ]);
+    });
+
     it('should run concurrency-safe tools in parallel and unsafe tools sequentially', async () => {
       const executionLog: string[] = [];
 

packages/core/src/index.ts

@@ -108,6 +108,7 @@ export type {
 } from './tools/shell.js';
 export type { SkillTool, SkillParams } from './tools/skill.js';
 export type { AgentTool, AgentParams } from './tools/agent/agent.js';
+export type { SwarmTool, SwarmParams, SwarmTask } from './tools/swarm.js';
 export type {
   TodoWriteTool,
   TodoItem,