@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  MAX_SPAWN_AGENTS_PER_CALL,
+  spawnAgentsParams,
+} from '../params/tool/spawn-agents'
+
+describe('the spawn_agents batch limit', () => {
+  const batch = (n: number) => ({
+    agents: Array.from({ length: n }, () => ({
+      agent_type: 'file-picker',
+      prompt: 'find files',
+    })),
+  })
+
+  test(`${MAX_SPAWN_AGENTS_PER_CALL} agents pass the schema`, () => {
+    expect(
+      spawnAgentsParams.inputSchema.safeParse(batch(MAX_SPAWN_AGENTS_PER_CALL))
+        .success,
+    ).toBe(true)
+  })
+
+  test(`${MAX_SPAWN_AGENTS_PER_CALL + 1} agents are refused by the schema`, () => {
+    const result = spawnAgentsParams.inputSchema.safeParse(
+      batch(MAX_SPAWN_AGENTS_PER_CALL + 1),
+    )
+    expect(result.success).toBe(false)
+  })
+
+  test('the 21-agent swarm that ran on 2026-10-10 no longer validates', () => {
+    expect(spawnAgentsParams.inputSchema.safeParse(batch(21)).success).toBe(
+      false,
+    )
+  })
+})
@@ -17,6 +17,10 @@ export const spawnAgentsOutputSchema = z
   .and(jsonObjectSchema)
   .array()
 
+/** Most agents one spawn_agents call may spawn; the runtime handler refuses a
+ *  bigger batch with the same number, so bypassing this schema changes nothing. */
+export const MAX_SPAWN_AGENTS_PER_CALL = 6
+
 const toolName = 'spawn_agents'
 const endsAgentStep = true
 const inputSchema = z
@@ -101,11 +105,19 @@ const inputSchema = z
             .optional()
             .describe('Parameters object for the agent'),
         })
-        .array(),
+        .array()
+        // One swarm at a time, and never a big one: a free-mode root once
+        // fanned out to 21 subagents in a single call (2026-10-10). The
+        // runtime handler enforces the same ceiling, so a caller that
+        // bypasses the schema still cannot.
+        .max(
+          MAX_SPAWN_AGENTS_PER_CALL,
+          `Spawn at most ${MAX_SPAWN_AGENTS_PER_CALL} agents in one call. For more, spawn again after these return.`,
+        ),
     ),
   })
   .describe(
-    `Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead.`,
+    `Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead. At most 6 agents per call.`,
   )
 const description = `
 Use this tool to spawn agents to help you complete the user request. Each agent has specific requirements for prompt and params based on their tools schema.
 
@@ -280,6 +280,34 @@ describe('Spawn Agents Permissions', () => {
       },
     })
 
+    it('should refuse a batch over MAX_SPAWN_AGENTS_PER_CALL without starting any agent', async () => {
+      const parentAgent = createMockAgent('parent', ['thinker'])
+      const childAgent = createMockAgent('thinker')
+      const sessionState = getInitialSessionState(mockFileContext)
+      // The 21-agent swarm of 2026-10-10, replayed.
+      const toolCall: CodebuffToolCall<'spawn_agents'> = {
+        toolName: 'spawn_agents' as const,
+        toolCallId: 'test-tool-call-id',
+        input: {
+          agents: Array.from({ length: 21 }, () => ({
+            agent_type: 'thinker',
+            prompt: 'swarm',
+          })),
+        },
+      }
+
+      const { output } = await handleSpawnAgents({
+        ...handleSpawnAgentsBaseParams,
+        agentState: sessionState.mainAgentState,
+        agentTemplate: parentAgent,
+        localAgentTemplates: { thinker: childAgent },
+        toolCall,
+      })
+
+      expect(JSON.stringify(output)).toContain('at most 6')
+      expect(mockLoopAgentSteps).not.toHaveBeenCalled()
+    })
+
     it('should allow spawning when agent is in spawnableAgents list', async () => {
       const parentAgent = createMockAgent('parent', ['thinker', 'reviewer'])
       const childAgent = createMockAgent('thinker')
 
@@ -1,3 +1,4 @@
+import { MAX_SPAWN_AGENTS_PER_CALL } from '@codebuff/common/tools/params/tool/spawn-agents'
 import { jsonToolResult } from '@codebuff/common/util/messages'
 
 import { outputForParent } from '../../../util/agent-output'
@@ -85,6 +86,20 @@ export const handleSpawnAgents = (async (
   const { agents } = toolCall.input
   const { logger } = params
 
+  // Enforce the schema's MAX_SPAWN_AGENTS_PER_CALL even when validation was
+  // bypassed (custom tool-call parsing, a cached schema from an older client).
+  // The batch answers in place: no subagent starts and no token is spent.
+  if (agents.length > MAX_SPAWN_AGENTS_PER_CALL) {
+    return {
+      output: jsonToolResult([
+        {
+          agentType: agents[0]?.agent_type ?? 'unknown',
+          errorMessage: `Refusing to spawn ${agents.length} agents at once: at most ${MAX_SPAWN_AGENTS_PER_CALL} per spawn_agents call. Split the fan-out into smaller batches.`,
+        },
+      ]),
+    }
+  }
+
   await previousToolCallFinished
 
   const results = await Promise.allSettled(