fix: require AgentSwarm to run alone (#643)

Author: kermanx

.changeset/agent-swarm-exclusive-call.md

@@ -0,0 +1,6 @@
+---
+"@moonshot-ai/agent-core": patch
+"@moonshot-ai/kimi-code": patch
+---
+
+Require AgentSwarm tool calls to run alone in a model response.

docs/en/reference/tools.md

@@ -91,7 +91,7 @@ Collaboration tools handle inter-Agent coordination, user interaction, and Skill
 
 **`Agent`** delegates a subtask to a sub-Agent. Required parameters: `prompt` (complete task description) and `description` (a 3–5 word short summary). Optional parameters: `subagent_type` (defaults to `coder`), `resume` (ID of an existing Agent to resume; mutually exclusive with `subagent_type`), and `run_in_background` (defaults to false). Agent tasks have a fixed 30-minute timeout. In foreground mode the parent Agent waits for the sub-Agent to complete before continuing; in background mode a task ID is returned immediately and the result is automatically delivered back to the main Agent via a synthetic User message when done. When several foreground `Agent` calls run in the same step, the TUI groups them and shows each subagent's running, waiting, completed, or failed status with elapsed time. See [Agent & Sub-Agents](../customization/agents.md) for details.
 
-**`AgentSwarm`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the swarm, or omit it to use `coder`. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. In the TUI, foreground swarms show a live `Agent swarm` progress panel above the input box. In `manual` permission mode, `AgentSwarm` calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, `AgentSwarm` itself is auto-approved. Permission rules match `AgentSwarm` by tool name only — argument patterns such as `AgentSwarm(swarm)` are not supported.
+**`AgentSwarm`** launches subagents from a shared `prompt_template` and an `items` array, resumes existing subagents through `resume_agent_ids`, or combines both in one call. The template must contain the `{{item}}` placeholder; each item replaces that placeholder and launches one new subagent. Pass `subagent_type` to choose the profile used by every spawned subagent in the swarm, or omit it to use `coder`. Without `resume_agent_ids`, the tool requires at least 2 items; with `resume_agent_ids`, it can resume one or more existing subagents. The tool supports up to 128 total subagents, waits for all subagents to finish, and returns an aggregated report. In the TUI, foreground swarms show a live `Agent swarm` progress panel above the input box. If a model response calls `AgentSwarm`, that call must be the only tool call in the response; to run multiple swarms, call one `AgentSwarm`, wait for its result, then call the next, or combine the work into one swarm when a single template can cover it. In `manual` permission mode, `AgentSwarm` calls outside active swarm mode request approval unless a permission rule allows them; while swarm mode is active, `AgentSwarm` itself is auto-approved. Permission rules match `AgentSwarm` by tool name only — argument patterns such as `AgentSwarm(swarm)` are not supported.
 
 **`AskUserQuestion`** asks the user a structured multiple-choice question — useful for disambiguation or option selection. The `questions` parameter accepts 1–4 questions; each question requires `question` (ending with `?`), `options` (2–4 choices, each with a `label` and `description`), and optional `header` (max 12 characters) and `multi_select` (defaults to false). An "Other" option is appended automatically. Setting `background` to true starts a background question task and returns a task ID immediately. When the host does not support interactive questioning, a failure message is returned and the Agent should ask the user directly in a text reply instead.
 

docs/zh/reference/tools.md

@@ -91,7 +91,7 @@ Plan 模式是一种受约束的工作状态：进入后 `Write` 与 `Edit` 只
 
 **`Agent`** 将子任务委托给子 Agent 执行。必填参数：`prompt`（完整任务描述）和 `description`（3–5 个词的简短说明）。可选参数：`subagent_type`（默认 `coder`）、`resume`（恢复已有 Agent 的 ID，与 `subagent_type` 互斥）和 `run_in_background`（默认 false）。Agent 任务使用固定 30 分钟超时。前台模式下父 Agent 等待子 Agent 完成再继续；后台模式立即返回任务 ID，完成时通过合成 User 消息自动回到主 Agent。多个前台 `Agent` 调用在同一步运行时，TUI 会合并展示，并为每个子 Agent 显示运行、等待、完成或失败状态以及已耗时长。子 Agent 体系细节见 [Agent 与子 Agent](../customization/agents.md)。
 
-**`AgentSwarm`** 可以从共享的 `prompt_template` 和 `items` 数组启动子 Agent，也可以通过 `resume_agent_ids` 恢复已有子 Agent，或在一次调用中同时使用两者。模板必须包含 `{{item}}` 占位符；每个 item 会替换该占位符，并启动一个新的子 Agent。传入 `subagent_type` 可以指定整个 swarm 中所有新启动的子 Agent 使用的 profile；省略时默认使用 `coder`。不传 `resume_agent_ids` 时，本工具要求至少 2 个 item；传入 `resume_agent_ids` 时，可以恢复 1 个或多个已有子 Agent。本工具最多支持 128 个子 Agent，会等待全部子 Agent 完成，并返回聚合报告。在 TUI 中，前台 swarm 会在输入框上方显示实时 `Agent swarm` 进度面板。在 `manual` 权限模式下，未处于 swarm mode 时调用 `AgentSwarm` 会触发审批，除非已有权限规则允许；swarm mode 已开启时，`AgentSwarm` 本身会自动放行。权限规则只能按工具名 `AgentSwarm` 匹配，不支持 `AgentSwarm(swarm)` 这类参数模式。
+**`AgentSwarm`** 可以从共享的 `prompt_template` 和 `items` 数组启动子 Agent，也可以通过 `resume_agent_ids` 恢复已有子 Agent，或在一次调用中同时使用两者。模板必须包含 `{{item}}` 占位符；每个 item 会替换该占位符，并启动一个新的子 Agent。传入 `subagent_type` 可以指定整个 swarm 中所有新启动的子 Agent 使用的 profile；省略时默认使用 `coder`。不传 `resume_agent_ids` 时，本工具要求至少 2 个 item；传入 `resume_agent_ids` 时，可以恢复 1 个或多个已有子 Agent。本工具最多支持 128 个子 Agent，会等待全部子 Agent 完成，并返回聚合报告。在 TUI 中，前台 swarm 会在输入框上方显示实时 `Agent swarm` 进度面板。若一次模型响应调用 `AgentSwarm`，该调用必须是该响应中的唯一工具调用；如需运行多个 swarm，应先调用一个 `AgentSwarm` 并等待结果，再调用下一个，若单个模板可以覆盖这些工作，也可以合并为一个 swarm。在 `manual` 权限模式下，未处于 swarm mode 时调用 `AgentSwarm` 会触发审批，除非已有权限规则允许；swarm mode 已开启时，`AgentSwarm` 本身会自动放行。权限规则只能按工具名 `AgentSwarm` 匹配，不支持 `AgentSwarm(swarm)` 这类参数模式。
 
 **`AskUserQuestion`** 以结构化多选题的形式向用户提问，适用于需要消歧或选择方案的场景。`questions` 参数接受 1–4 道题，每道题需提供 `question`（以 `?` 结尾）、`options`（2–4 个选项，每项含 `label` 和 `description`）以及可选的 `header`（最多 12 字符）和 `multi_select`（默认 false）。系统自动附加"其他"选项。`background` 为 true 时启动后台问题任务并立即返回任务 ID。宿主未实现交互式提问能力时返回失败提示，Agent 应改为在文本回复中直接提问。
 

packages/agent-core/src/agent/permission/policies/agent-swarm-exclusive-deny.ts

@@ -0,0 +1,45 @@
+import type { PermissionPolicy, PermissionPolicyContext, PermissionPolicyResult } from '../types';
+
+export class AgentSwarmExclusiveDenyPermissionPolicy implements PermissionPolicy {
+  readonly name = 'agent-swarm-exclusive-deny';
+
+  evaluate(context: PermissionPolicyContext): PermissionPolicyResult | undefined {
+    const toolCalls = context.toolCalls;
+    const agentSwarmCount = toolCalls.filter(
+      (toolCall) => toolCall.name === 'AgentSwarm',
+    ).length;
+
+    if (agentSwarmCount === 0) return;
+    if (agentSwarmCount === 1 && toolCalls.length === 1) return;
+
+    return {
+      kind: 'deny',
+      message:
+        agentSwarmCount > 1
+          ? multipleAgentSwarmDeniedMessage(toolCalls.length > agentSwarmCount)
+          : mixedAgentSwarmDeniedMessage(),
+      reason: {
+        agent_swarm_tool_calls: agentSwarmCount,
+        tool_calls: toolCalls.length,
+      },
+    };
+  }
+}
+
+function multipleAgentSwarmDeniedMessage(hasOtherToolCalls: boolean): string {
+  const suffix = hasOtherToolCalls
+    ? ' AgentSwarm also must not be combined with other tools in the same response.'
+    : '';
+  return (
+    'AgentSwarm must be called one swarm at a time. Multiple AgentSwarm calls are not forbidden, ' +
+    'but issue them sequentially: call one AgentSwarm, wait for its result, then call the next; ' +
+    `or merge the work into a single AgentSwarm when one swarm can cover it.${suffix}`
+  );
+}
+
+function mixedAgentSwarmDeniedMessage(): string {
+  return (
+    'AgentSwarm must be the only tool call in a model response. Retry with a single AgentSwarm ' +
+    'call by itself, then call any other tools after it returns.'
+  );
+}

packages/agent-core/src/agent/permission/policies/index.ts

@@ -1,5 +1,6 @@
 import type { Agent } from '../..';
 import type { PermissionPolicy } from '../types';
+import { AgentSwarmExclusiveDenyPermissionPolicy } from './agent-swarm-exclusive-deny';
 import { AutoModeApprovePermissionPolicy } from './auto-mode-approve';
 import { AutoModeAskUserQuestionDenyPermissionPolicy } from './auto-mode-ask-user-question-deny';
 import { DefaultToolApprovePermissionPolicy } from './default-tool-approve';
@@ -27,6 +28,8 @@ export function createPermissionDecisionPolicies(agent: Agent): PermissionPolicy
   return [
     // PreToolUse hook returned a block → deny.
     new PreToolCallHookPermissionPolicy(agent),
+    // AgentSwarm is batch-exclusive and must run alone, regardless of permission mode.
+    new AgentSwarmExclusiveDenyPermissionPolicy(),
     // auto mode + AskUserQuestion → deny.
     new AutoModeAskUserQuestionDenyPermissionPolicy(agent),
     // plan mode: Write/Edit outside the plan file, or TaskStop → deny.

packages/agent-core/src/loop/tool-call.ts

@@ -72,6 +72,10 @@ export interface ToolCallStepContext {
   readonly stepUuid: string;
 }
 
+interface ToolCallBatchContext extends ToolCallStepContext {
+  readonly toolCalls: readonly ToolCall[];
+}
+
 type PreflightedToolCall = RunnableToolCall | RejectedToolCall;
 
 interface RunnableToolCall {
@@ -120,6 +124,7 @@ export async function runToolCallBatch(
   response: LLMChatResponse,
 ): Promise<ToolCallBatchResult> {
   if (response.toolCalls.length === 0) return { stopTurn: false };
+  const batchStep: ToolCallBatchContext = { ...step, toolCalls: response.toolCalls };
   const calls = response.toolCalls.map((toolCall) => preflightToolCall(step.tools, toolCall));
   const scheduler = new ToolScheduler<PendingToolResult>();
   const pendingResults: Array<Promise<PendingToolResult>> = [];
@@ -128,13 +133,13 @@ export async function runToolCallBatch(
   try {
     for (let index = 0; index < calls.length; index += 1) {
       const call = calls[index]!;
-      const prepared = await prepareToolCall(step, call);
+      const prepared = await prepareToolCall(batchStep, call);
       pendingResults.push(scheduler.add(prepared.task));
 
       if (prepared.stopBatchAfterThis === true) {
         stopTurn = true;
         for (const skippedCall of calls.slice(index + 1)) {
-          const skippedTask = await prepareSkippedToolCall(step, skippedCall);
+          const skippedTask = await prepareSkippedToolCall(batchStep, skippedCall);
           pendingResults.push(scheduler.add(skippedTask));
         }
         break;
@@ -145,7 +150,7 @@ export async function runToolCallBatch(
     // provider order. Await all tasks so each recorded `tool.call` gets a
     // paired `tool.result`; the caller checks abort before writing `step.end`.
     for (const pendingResult of pendingResults) {
-      const result = await finalizePendingToolResult(step, await pendingResult);
+      const result = await finalizePendingToolResult(batchStep, await pendingResult);
       if (result.stopTurn === true) stopTurn = true;
       await step.dispatchEvent({
         type: 'tool.result',
@@ -235,7 +240,7 @@ function validateExecutableToolArgs(tool: ExecutableTool, args: unknown): string
 }
 
 async function prepareToolCall(
-  step: ToolCallStepContext,
+  step: ToolCallBatchContext,
   call: PreflightedToolCall,
 ): Promise<PreparedToolCallTask> {
   const settleError = async (
@@ -336,7 +341,7 @@ async function prepareToolCall(
 }
 
 async function prepareSkippedToolCall(
-  step: ToolCallStepContext,
+  step: ToolCallBatchContext,
   call: PreflightedToolCall,
 ): Promise<ToolCallTask<PendingToolResult>> {
   const output = 'Tool skipped because a previous tool call stopped the turn.';
@@ -356,7 +361,7 @@ function makeResolvedToolCallTask(result: PendingToolResult): ToolCallTask<Pendi
  * Hook decisions can block a call or replace args before execution starts.
  */
 async function runPrepareToolExecutionHook(
-  step: ToolCallStepContext,
+  step: ToolCallBatchContext,
   call: RunnableToolCall,
 ): Promise<PrepareToolExecutionDecision> {
   const { hooks, signal, turnId, currentStep, llm } = step;
@@ -370,6 +375,7 @@ async function runPrepareToolExecutionHook(
   try {
     hookResult = await hooks.prepareToolExecution({
       toolCall,
+      toolCalls: step.toolCalls,
       tool: call.tool,
       args,
       turnId,
@@ -411,7 +417,7 @@ async function runPrepareToolExecutionHook(
 }
 
 async function runAuthorizeToolExecutionHook(
-  step: ToolCallStepContext,
+  step: ToolCallBatchContext,
   call: RunnableToolCall,
   args: unknown,
   execution: RunnableToolExecution,
@@ -422,6 +428,7 @@ async function runAuthorizeToolExecutionHook(
   try {
     return await hooks.authorizeToolExecution({
       toolCall: call.toolCall,
+      toolCalls: step.toolCalls,
       tool: call.tool,
       args,
       execution,
@@ -493,7 +500,7 @@ async function runRunnableToolCall(
 }
 
 async function finalizePendingToolResult(
-  step: ToolCallStepContext,
+  step: ToolCallBatchContext,
   pendingResult: PendingToolResult,
 ): Promise<PendingToolResult> {
   const { hooks, signal, turnId, currentStep, llm } = step;
@@ -504,6 +511,7 @@ async function finalizePendingToolResult(
   try {
     const finalizedResult = await hooks.finalizeToolResult({
       toolCall: pendingResult.toolCall,
+      toolCalls: step.toolCalls,
       args: pendingResult.args,
       result: pendingResult.result,
       turnId,

packages/agent-core/src/loop/types.ts

@@ -147,6 +147,7 @@ export interface LoopStepHookContext {
 
 export interface ToolExecutionHookContext extends LoopStepHookContext {
   readonly toolCall: ToolCall;
+  readonly toolCalls: readonly ToolCall[];
   readonly tool?: ExecutableTool | undefined;
   readonly args: unknown;
 }

packages/agent-core/src/tools/builtin/collaboration/agent-swarm.md

@@ -5,3 +5,5 @@ Use AgentSwarm when many subagents should run the same kind of task over differe
 Use `resume_agent_ids` to continue subagents that already exist from earlier work, such as ones that failed or timed out: map each agent id to the prompt for that resumed subagent (usually `continue` if no extra information is needed). You may combine `resume_agent_ids` with `items` in the same call to resume existing subagents and launch new ones. Do not duplicate resumed work in `items`.
 
 Use enough subagents to keep the work focused and parallel. AgentSwarm supports up to 128 subagents, and launches are queued automatically, so it is safe to split large tasks into many clear, independent items.
+
+If `AgentSwarm` is called, that call must be the only tool call in the response.