@swarmclawai/swarmclaw 1.5.61 → 1.5.63

package/README.md

@@ -399,6 +399,23 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.63 Highlights
+
+Chatroom fix from @borislavnnikolov: CLI-backed agents (codex-cli, copilot-cli, gemini-cli, and the rest of the `NON_LANGGRAPH_PROVIDER_IDS` set) now work correctly as chatroom members instead of falling through a LangGraph path they cannot run. With the execution path fixed, the worker-only membership blocks are lifted too, so any non-trashed agent can be added to a room.
+
+- **Direct provider runtime for CLI chatroom turns.** `src/app/api/chatrooms/[id]/chat/route.ts` now branches on `NON_LANGGRAPH_PROVIDER_IDS` and calls `provider.handler.streamChat()` directly for CLI-backed agents while keeping the LangGraph `streamAgentChat` path for everything else. Streaming, tool events, and persisted messages all flow through unchanged.
+- **Full member selection.** The create, update, members, session-tool, and UI layers (`src/app/api/chatrooms/route.ts`, `src/app/api/chatrooms/[id]/route.ts`, `src/app/api/chatrooms/[id]/members/route.ts`, `src/lib/server/session-tools/chatroom.ts`, `src/components/chatrooms/chatroom-sheet.tsx`) no longer reject or hide worker-only agents. Any non-trashed agent is eligible.
+- **Regression test.** `src/app/api/chatrooms/[id]/chat/route.test.ts` proves a `codex-cli`-backed chatroom turn bypasses `streamAgentChat`, streams a response through the provider handler, and persists one assistant reply.
+
+### v1.5.62 Highlights
+
+Hardens parallel sub-agent dispatch with a concurrency cap, a quorum join policy, and a cycle check — so a fan-out can't accidentally saturate providers, melt a mission budget, or wedge the runtime on a delegation loop.
+
+- **`spawn_subagent` swarm/batch actions now accept `maxConcurrency`, `joinPolicy`, `quorum`, and `cancelRemaining`.** Parallel mode fans out at most 4 branches at a time by default (hard-capped at 16). Task buckets share an `executionGroupKey` so the existing per-execution serial lock enforces the cap with zero new scheduler code. `joinPolicy: 'quorum'` resolves once `quorum` branches succeed and (by default) cancels the remaining in-flight branches. `joinPolicy: 'first'` resolves on the first success. `joinPolicy: 'all'` stays the default.
+- **Cycle detection in `spawnSubagent`.** Before creating a child session, the runtime walks the `parentSessionId` ancestry and rejects the spawn when the requested `agentId` already appears higher in the chain. Clear error message with an `allowCycle: true` escape hatch. Orthogonal to the existing depth cap.
+- **Per-agent and per-mission overrides.** `Agent.maxParallelDelegations` and `MissionBudget.maxParallelBranches` plumb into the swarm resolver. Precedence: explicit tool arg > agent cap > mission cap > system default (4). Both are validated by `AgentUpdateSchema` and the mission budget schemas, and normalized on load via `storage-normalization.ts`.
+- **Swarm snapshot exposes the effective cap.** `SwarmSnapshot.maxConcurrency` lands in the persisted snapshot payload so the UI and external tooling can surface the active concurrency level. Verified live via a 3-branch quorum run: `totalCompleted: 2`, `totalCancelled: 1`, `maxConcurrency: 2`, `joinPolicy: "quorum"`.
+
 ### v1.5.61 Highlights
 
 Adds an opt-in per-agent planning mode that rides on the existing `[MAIN_LOOP_PLAN]` token machinery.
@@ -423,30 +440,6 @@ Viral-loop release. Adds public share links for missions, skills, and sessions,
 - **Share-link-based skill install.** `POST /api/skills/import` already accepts an http(s) URL; pointing it at `https://<your-host>/api/s/<token>/raw` now installs a shared skill from another SwarmClaw instance without auth handshakes. Pairs naturally with existing `swarmclaw skills import` CLI.
 - **Share-link repository tests.** `share-link-repository.test.ts` covers mint / list / revoke / lookup-by-token round-trip plus expiry handling against a temporary data dir.
 
-### v1.5.58 Highlights
-
-This release broadens the built-in evaluation harness so SwarmClaw runs can be benchmarked against named suites, adds two targeted starter kits, exposes live per-session cost data, tightens auto-skill drafting, and ships a zero-setup demo mission template.
-
-- **Benchmark-style eval suites.** New `SWEBENCH_LITE_SCENARIOS` and `GAIA_L1_SCENARIOS` in `src/lib/server/eval/scenarios-swebench.ts` and `scenarios-gaia.ts` — curated parallels (not the upstream datasets) sized for a single-agent harness run. The shared `EvalScenario` type now carries an optional `suite: 'core' | 'swe-bench-lite' | 'gaia-l1' | 'tool-use' | 'code-action'` tag. `POST /api/eval/suite` accepts `{ suite: "swe-bench-lite" }` to scope a run. New `GET /api/eval/suites` lists every suite with scenario count, max score, and categories. CLI commands: `swarmclaw eval suites`, and `swarmclaw eval suite` still takes a JSON body now including `suite`. Useful for advertising verifiable numbers against a named benchmark instead of a bespoke scoring rubric.
-- **Two additional starter kits.** `inbox_triage` (single Triager agent over email + memory + documents) and `data_analyst` (single Analyst agent over shell + files + web + documents) join the existing seven kits in `src/lib/setup-defaults.ts`. Both are surfaced on the intent-driven setup path alongside Personal Assistant, Research Copilot, Builder Studio, and Delegate Team.
-- **Live per-session usage API.** New `GET /api/usage/live?sessionId=...` returns a lightweight snapshot — records, tokens in/out, estimated cost, firstAt/lastAt, wallclockMs, turns — so frontends can surface a live cost meter without pulling the full aggregated `/api/usage` payload. Without a `sessionId` the route returns the ten most recently active sessions. Registered in the CLI as `swarmclaw usage live`.
-- **Auto-skill drafting is stricter and rate-limited.** `shouldAutoDraftSkillSuggestion` in `chat-turn-finalization.ts` now requires at least 3 tool events in the completed turn (was 1), and a new per-agent daily cap limits automatic drafts to 3 per day per agent to prevent suggestion-inbox spam. Both thresholds are named constants (`AUTO_DRAFT_MIN_TOOL_EVENTS`, `AUTO_DRAFT_DAILY_LIMIT`). Agents with `autoDraftSkillSuggestions = false` are unaffected (auto-drafting remains opt-in per agent).
-- **Hello World demo mission template.** New `hello-world-demo` entry in `BUILT_IN_MISSION_TEMPLATES` — a bounded, zero-setup mission that reads three files in the working directory and writes a one-paragraph markdown summary to `hello-world-report.md`. Budgets (USD 0.25, 20k tokens, 30 turns, 15 min) are small enough to run on a local Ollama model without cost. Intended as the first thing a new user watches an agent complete end to end.
-
-### v1.5.57 Highlights
-
-This release closes the org-orchestration feature gap with Paperclip while keeping SwarmClaw's autonomous-assistant focus. Most additions are additive; nothing existing has changed shape.
-
-- **Workspace templates: full export/import bundle.** `src/lib/server/portability/{export,import}.ts` now round-trips agents, skills, schedules, **connectors** (with secret scrubbing), **chatrooms**, **MCP servers**, **projects**, **goals**, and an extension manifest reference. Manifest version bumped to `2`; v1 bundles still import. Connectors and MCP servers re-import with credentials stripped — the response payload now lists which records `needCredentials` so the UI can prompt. ID remapping handles cross-references (chatrooms → agents, schedules → agents, goals → projects/agents).
-- **Per-agent budget enforcement at enqueue.** New `src/lib/server/agents/agent-budget-hook.ts` mirrors the existing mission budget hook. When an agent has `budgetAction: 'block'` and any window (`hourlyBudget`/`dailyBudget`/`monthlyBudget`) is exhausted, autonomous enqueues now fail fast in `session-run-manager` instead of getting blocked deeper in the chat-turn pipeline. User-initiated chats still flow through (so users can talk to an agent that's hit its cap). Default `'warn'` behavior is unchanged.
-- **Goal hierarchy ancestry through Mission.** `Mission.goalId` is a new optional field. When a session has a `missionId` and the bound mission has a `goalId`, `main-agent-loop.ts` now walks `mission → goal → parentGoal → …` so the full Initiative/Project/Goal ancestry flows into the agent system prompt — previously only direct session-level goals were resolved.
-- **Billing codes / cost attribution.** `Mission`, `BoardTask`, `Session`, and `UsageRecord` accept an optional `billingCodes: string[]`. `resolveBillingCodesForSession` combines session + mission codes when usage is appended, and the new `GET /api/usage/by-code?codes=foo,bar&range=7d` endpoint rolls up cost per code (and per agent within each code). Lets users running multiple parallel projects answer "what did Project X cost?" across agents, missions, and ad-hoc chats.
-- **Customizable task workflow states.** New `WorkflowState` collection (`src/lib/server/tasks/workflow-state-repository.ts`) stores team-defined states like "Needs Review" or "Blocked on PM" that are orthogonal to `BoardTaskStatus` lifecycle. `BoardTask.workflowStateId` references one of seven defaults (Triage / Backlog / Todo / In Progress / Needs Review / Done / Cancelled) or any custom state. CRUD via `GET|POST|DELETE /api/task-workflow-states`. Atomic checkout via `task-checkout.ts` was already in place.
-- **Cross-agent delegation refusal policy.** `Chatroom.onRefusal` (`'reroute' | 'escalate' | 'human'`) and `Chatroom.escalationTargetAgentId` formalize what happens when a delegated agent declines work. `chatroom-refusal.ts` reroutes to another room member, escalates to a configured target, or surfaces a `human_loop` approval. Policy management at `POST /api/chatrooms/refusal-policy`; simulation at `PUT` for tests.
-- **Configuration version history.** Every `updateAgent` call now snapshots the prior agent state into `config-versions.json` (capped at 50 versions per entity). `GET /api/config-versions?entityKind=agent&entityId=...` lists history; `POST /api/config-versions/restore` rolls back. Foundation for extending to extensions, connectors, MCP servers, chatrooms, and projects.
-- **Multi-workspace scaffolding.** New `Workspace` registry with `GET|POST|PATCH|DELETE /api/workspaces` and `GET|POST /api/workspaces/active`. The default workspace seeds itself on first read; switching the active workspace persists to `workspace-registry.json`. **Note:** this is metadata only in v1.5.57 — actual data-dir forking per workspace is intentionally deferred (low-risk shipping).
-- **CLI manifest expanded.** New top-level groups: `workspaces`, `workflow-states`, `config-versions`, `cost-attribution`, `chatroom-policy`. Run `swarmclaw workspaces list`, `swarmclaw cost-attribution by-code --query codes=client-a,range=30d`, `swarmclaw config-versions list --query entityKind=agent,entityId=...`, etc. CLI route-coverage test passes.
-
 Older releases: https://swarmclaw.ai/docs/release-notes
 
 - GitHub releases: https://github.com/swarmclawai/swarmclaw/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.61",
+  "version": "1.5.63",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/chatrooms/[id]/chat/route.test.ts

@@ -297,3 +297,114 @@ test('chatroom route forwards tool activity and records one reply per participat
   assert.deepEqual(output.assistantCounts, { alpha: 1, beta: 1 })
   assert.deepEqual([...new Set(output.agentOrder)].sort(), ['alpha', 'beta'])
 })
+
+test('chatroom route uses direct provider runtime for CLI providers', () => {
+  const output = runWithTempDataDir<{
+    errors: string[]
+    streamedText: string
+    assistantTexts: string[]
+  }>(`
+    const storageMod = await import('./src/lib/server/storage')
+    const providersMod = await import('@/lib/providers')
+    const routeMod = await import('./src/app/api/chatrooms/[id]/chat/route')
+    const streamMod = await import('@/lib/server/chat-execution/stream-agent-chat')
+    const storage = storageMod.default || storageMod
+    const providers = providersMod.default || providersMod
+    const route = routeMod.default || routeMod
+    const stream = streamMod.default || streamMod
+
+    const originalHandler = providers.PROVIDERS['codex-cli'].handler
+
+    const now = Date.now()
+    storage.saveAgents({
+      alpha: {
+        id: 'alpha',
+        name: 'Alpha',
+        provider: 'codex-cli',
+        model: 'gpt-5.3-codex',
+        extensions: [],
+        createdAt: now,
+        updatedAt: now,
+      },
+    })
+    storage.saveChatrooms({
+      room_1: {
+        id: 'room_1',
+        name: 'CLI Room',
+        agentIds: ['alpha'],
+        messages: [],
+        createdAt: now,
+        updatedAt: now,
+        chatMode: 'sequential',
+        autoAddress: true,
+      },
+    })
+
+    async function readSse(response) {
+      const reader = response.body.getReader()
+      const decoder = new TextDecoder()
+      let buffer = ''
+      const events = []
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        buffer += decoder.decode(value, { stream: true })
+        let idx = buffer.indexOf('\\n\\n')
+        while (idx !== -1) {
+          const chunk = buffer.slice(0, idx)
+          buffer = buffer.slice(idx + 2)
+          const line = chunk
+            .split('\\n')
+            .map((entry) => entry.trim())
+            .find((entry) => entry.startsWith('data: '))
+          if (line) {
+            events.push(JSON.parse(line.slice(6)))
+          }
+          idx = buffer.indexOf('\\n\\n')
+        }
+      }
+      return events
+    }
+
+    stream.setStreamAgentChatForTest(async () => {
+      throw new Error('streamAgentChat should not be called for codex-cli chatroom turns')
+    })
+    providers.PROVIDERS['codex-cli'].handler = {
+      streamChat: async (opts) => {
+        const reply = 'Codex CLI answered from direct provider runtime.'
+        opts.write('data: ' + JSON.stringify({ t: 'd', text: reply }) + '\\n')
+        return reply
+      },
+    }
+
+    try {
+      const response = await route.POST(
+        new Request('http://local/api/chatrooms/room_1/chat', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ senderId: 'user', text: 'Say hello to the room.' }),
+        }),
+        { params: Promise.resolve({ id: 'room_1' }) },
+      )
+
+      const events = await readSse(response)
+      const chatroom = storage.loadChatrooms().room_1
+      const assistantTexts = chatroom.messages
+        .filter((entry) => entry.role === 'assistant')
+        .map((entry) => entry.text)
+
+      console.log(JSON.stringify({
+        errors: events.filter((entry) => entry.t === 'err').map((entry) => entry.text),
+        streamedText: events.filter((entry) => entry.t === 'd').map((entry) => entry.text).join(''),
+        assistantTexts,
+      }))
+    } finally {
+      providers.PROVIDERS['codex-cli'].handler = originalHandler
+      stream.setStreamAgentChatForTest(null)
+    }
+  `, { prefix: 'swarmclaw-chatroom-route-cli-provider-' })
+
+  assert.equal(output.errors.some((text) => /streamAgentChat should not be called/i.test(text)), false)
+  assert.equal(output.streamedText.includes('Codex CLI answered from direct provider runtime.'), true)
+  assert.equal(output.assistantTexts.some((text) => text.includes('Codex CLI answered from direct provider runtime.')), true)
+})

package/src/app/api/chatrooms/[id]/chat/route.ts

@@ -6,6 +6,7 @@ import { notFound } from '@/lib/server/collection-helpers'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { streamAgentChat } from '@/lib/server/chat-execution/stream-agent-chat'
 import { getProvider } from '@/lib/providers'
+import { NON_LANGGRAPH_PROVIDER_IDS } from '@/lib/provider-sets'
 import {
   resolveApiKey,
   parseMentions,
@@ -231,37 +232,55 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
 
             let fullText = ''
             let agentError = ''
-            const result = await streamAgentChat({
-              session: syntheticSession,
-              message: messageForAgent,
-              imagePath,
-              attachedFiles,
-              apiKey,
-              systemPrompt: fullSystemPrompt,
-              write: (raw: string) => {
-                const lines = raw.split('\n').filter(Boolean)
-                for (const line of lines) {
-                  if (!line.startsWith('data: ')) continue
-                  try {
-                    const parsed = JSON.parse(line.slice(6).trim())
-                    if (parsed.t === 'd' && parsed.text) {
-                      fullText += parsed.text
-                      writeEvent({ t: 'd', text: parsed.text, agentId: agent.id, agentName: agent.name })
-                    } else if (parsed.t === 'tool_call' || parsed.t === 'tool_result') {
-                      writeEvent({ ...parsed, agentId: agent.id, agentName: agent.name })
-                    } else if (parsed.t === 'err' && parsed.text) {
-                      agentError = parsed.text
-                      writeEvent({ t: 'err', text: parsed.text, agentId: agent.id, agentName: agent.name })
-                    }
-                  } catch {
-                    // skip malformed lines
+            const forwardProviderEvents = (raw: string) => {
+              const lines = raw.split('\n').filter(Boolean)
+              for (const line of lines) {
+                if (!line.startsWith('data: ')) continue
+                try {
+                  const parsed = JSON.parse(line.slice(6).trim())
+                  if (parsed.t === 'd' && parsed.text) {
+                    fullText += parsed.text
+                    writeEvent({ t: 'd', text: parsed.text, agentId: agent.id, agentName: agent.name })
+                  } else if (parsed.t === 'tool_call' || parsed.t === 'tool_result') {
+                    writeEvent({ ...parsed, agentId: agent.id, agentName: agent.name })
+                  } else if (parsed.t === 'err' && parsed.text) {
+                    agentError = parsed.text
+                    writeEvent({ t: 'err', text: parsed.text, agentId: agent.id, agentName: agent.name })
                   }
+                } catch {
+                  // skip malformed lines
                 }
-              },
-              history,
-            })
+              }
+            }
 
-            const rawResponseText = result.finalResponse || result.fullText || fullText
+            let rawResponseText = ''
+            if (NON_LANGGRAPH_PROVIDER_IDS.has(syntheticSession.provider)) {
+              const provider = getProvider(syntheticSession.provider)
+              if (!provider) throw new Error(`Unknown provider: ${syntheticSession.provider}`)
+              rawResponseText = await provider.handler.streamChat({
+                session: syntheticSession,
+                message: messageForAgent,
+                imagePath,
+                apiKey,
+                systemPrompt: fullSystemPrompt,
+                write: forwardProviderEvents,
+                active: new Map<string, unknown>(),
+                loadHistory: () => history,
+              })
+              if (!rawResponseText) rawResponseText = fullText
+            } else {
+              const result = await streamAgentChat({
+                session: syntheticSession,
+                message: messageForAgent,
+                imagePath,
+                attachedFiles,
+                apiKey,
+                systemPrompt: fullSystemPrompt,
+                write: forwardProviderEvents,
+                history,
+              })
+              rawResponseText = result.finalResponse || result.fullText || fullText
+            }
             const responseText = stripAgentReactionTokens(stripHiddenControlTokens(rawResponseText))
 
             // Don't persist empty or error-only messages — they pollute chat history

package/src/app/api/chatrooms/[id]/members/route.ts

@@ -4,7 +4,6 @@ import { notify } from '@/lib/server/ws-hub'
 import { notFound } from '@/lib/server/collection-helpers'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { genId } from '@/lib/id'
-import { isWorkerOnlyAgent, buildWorkerOnlyAgentMessage } from '@/lib/server/agents/agent-availability'
 
 export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
@@ -18,13 +17,6 @@ export async function POST(req: Request, { params }: { params: Promise<{ id: str
   if (!agentId) return NextResponse.json({ error: 'agentId is required' }, { status: 400 })
 
   const agents = loadAgents()
-  if (isWorkerOnlyAgent(agents[agentId])) {
-    return NextResponse.json(
-      { error: buildWorkerOnlyAgentMessage(agents[agentId], 'join chatrooms') },
-      { status: 400 },
-    )
-  }
-
   if (!chatroom.agentIds.includes(agentId)) {
     chatroom.agentIds.push(agentId)
 

package/src/app/api/chatrooms/[id]/route.ts

@@ -4,7 +4,6 @@ import { notify } from '@/lib/server/ws-hub'
 import { notFound } from '@/lib/server/collection-helpers'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { genId } from '@/lib/id'
-import { isWorkerOnlyAgent } from '@/lib/server/agents/agent-availability'
 import {
   ensureChatroomRoutingGuidance,
   synthesizeRoutingGuidanceFromRules,
@@ -78,16 +77,6 @@ export async function PUT(req: Request, { params }: { params: Promise<{ id: stri
         { status: 400 },
       )
     }
-    const cliAgentNames = agentIds
-      .filter((agentId) => isWorkerOnlyAgent(agents[agentId]))
-      .map((agentId) => agents[agentId]?.name || agentId)
-    if (cliAgentNames.length > 0) {
-      return NextResponse.json(
-        { error: `CLI-based agents cannot join chatrooms: ${cliAgentNames.join(', ')}. They can only be used for direct chats and delegation.` },
-        { status: 400 },
-      )
-    }
-
     const oldIds = new Set(chatroom.agentIds)
     const newIds = new Set(agentIds)
     const added = agentIds.filter((aid: string) => !oldIds.has(aid))

package/src/app/api/chatrooms/route.ts

@@ -6,7 +6,6 @@ import { ChatroomCreateSchema, formatZodError } from '@/lib/validation/schemas'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { z } from 'zod'
 import type { Chatroom, ChatroomMessage } from '@/types'
-import { isWorkerOnlyAgent } from '@/lib/server/agents/agent-availability'
 import {
   ensureChatroomRoutingGuidance,
   synthesizeRoutingGuidanceFromRules,
@@ -61,15 +60,6 @@ export async function POST(req: Request) {
       { status: 400 },
     )
   }
-  const cliAgentNames = requestedAgentIds
-    .filter((agentId) => isWorkerOnlyAgent(knownAgents[agentId]))
-    .map((agentId) => knownAgents[agentId]?.name || agentId)
-  if (cliAgentNames.length > 0) {
-    return NextResponse.json(
-      { error: `CLI-based agents cannot join chatrooms: ${cliAgentNames.join(', ')}. They can only be used for direct chats and delegation.` },
-      { status: 400 },
-    )
-  }
   const agentIds: string[] = requestedAgentIds
   const chatMode = body.chatMode === 'parallel' ? 'parallel' : 'sequential'
   const autoAddress = Boolean(body.autoAddress)

package/src/app/api/missions/[id]/route.ts

@@ -23,6 +23,7 @@ const MissionUpdateSchema = z.object({
     maxToolCalls: z.number().positive().int().nullable().optional(),
     maxWallclockSec: z.number().positive().int().nullable().optional(),
     maxTurns: z.number().positive().int().nullable().optional(),
+    maxParallelBranches: z.number().positive().int().nullable().optional(),
     warnAtFractions: z.array(z.number().positive().lt(1)).max(10).optional(),
   }).partial().optional(),
   reportSchedule: z.object({

package/src/app/api/missions/route.ts

@@ -14,6 +14,7 @@ const MissionBudgetSchema = z.object({
   maxToolCalls: z.number().positive().int().nullable().optional(),
   maxWallclockSec: z.number().positive().int().nullable().optional(),
   maxTurns: z.number().positive().int().nullable().optional(),
+  maxParallelBranches: z.number().positive().int().nullable().optional(),
   warnAtFractions: z.array(z.number().positive().lt(1)).max(10).optional(),
 }).strict()
 

package/src/components/chatrooms/chatroom-sheet.tsx

@@ -9,7 +9,6 @@ import { toast } from 'sonner'
 import { AgentAvatar } from '@/components/agents/agent-avatar'
 import type { Agent } from '@/types'
 import { CheckIcon } from '@/components/shared/check-icon'
-import { WORKER_ONLY_PROVIDER_IDS } from '@/lib/provider-sets'
 
 export function ChatroomSheet() {
   const open = useChatroomStore((s) => s.chatroomSheetOpen)
@@ -105,9 +104,7 @@ export function ChatroomSheet() {
     )
   }
 
-  const agentList = Object.values(agents).filter(
-    (a: Agent) => !a.trashedAt && !WORKER_ONLY_PROVIDER_IDS.has(a.provider)
-  ) as Agent[]
+  const agentList = Object.values(agents).filter((a: Agent) => !a.trashedAt) as Agent[]
 
   return (
     <BottomSheet open={open} onClose={() => setChatroomSheetOpen(false)}>

package/src/lib/server/agents/subagent-runtime.ts

@@ -73,6 +73,8 @@ export interface SpawnSubagentInput {
   timeoutSec?: number
   /** Optional shared execution lane key for serializing sibling runs. */
   executionGroupKey?: string
+  /** When true, skip the ancestor-agent cycle check (A → B → A). Default false. */
+  allowCycle?: boolean
 }
 
 export interface SubagentHandle {
@@ -183,6 +185,31 @@ export function getSessionDepth(
   return depth
 }
 
+/**
+ * Collect agentIds of every session in the parent chain including the given
+ * session. Used to detect delegation cycles (A → B → A) before spawning.
+ */
+export function collectAncestorAgentIds(
+  sessionId: string | undefined,
+  sessions: Record<string, unknown>,
+  limit = 32,
+): string[] {
+  if (!sessionId) return []
+  const ids: string[] = []
+  let current: string | undefined = sessionId
+  const visited = new Set<string>()
+  while (current && ids.length < limit && !visited.has(current)) {
+    visited.add(current)
+    const s = sessions[current] as Record<string, unknown> | undefined
+    const agentId = typeof s?.agentId === 'string' ? s.agentId.trim() : ''
+    if (agentId) ids.push(agentId)
+    const parentId = typeof s?.parentSessionId === 'string' ? s.parentSessionId : null
+    if (!parentId) break
+    current = parentId
+  }
+  return ids
+}
+
 // ---------------------------------------------------------------------------
 // Core: Spawn a Native Subagent
 // ---------------------------------------------------------------------------
@@ -215,6 +242,16 @@ async function spawnSubagentImpl(
     log.warn('subagent', 'Spawn rejected: max depth exceeded', { agentId: input.agentId, depth, maxDepth })
     throw new Error(`Max subagent depth (${maxDepth}) reached.`)
   }
+  if (input.allowCycle !== true && context.sessionId) {
+    const ancestorAgentIds = collectAncestorAgentIds(context.sessionId, sessions)
+    if (ancestorAgentIds.includes(input.agentId)) {
+      log.warn('subagent', 'Spawn rejected: delegation cycle', { agentId: input.agentId, chain: ancestorAgentIds })
+      throw new Error(
+        `Delegation cycle: agent "${input.agentId}" is already active higher in this chain. `
+        + 'Pick a different sibling agent, or pass allowCycle=true to override.',
+      )
+    }
+  }
   const parent = context.sessionId ? sessions[context.sessionId] : null
   const parentExtensions = getEnabledCapabilityIds(parent as { tools?: string[] | null, extensions?: string[] | null } | null)
   const spawningResult = await runCapabilitySubagentSpawning(

package/src/lib/server/agents/subagent-swarm.test.ts

@@ -2,8 +2,11 @@ import assert from 'node:assert/strict'
 import { afterEach, describe, it } from 'node:test'
 
 import {
+  _clampSwarmConcurrency,
   _clearSwarmRegistry,
   _resolveSwarmExecutionMode,
+  SWARM_DEFAULT_PARALLEL_CONCURRENCY,
+  SWARM_MAX_CONCURRENCY_HARD_LIMIT,
   getSwarm,
   getSwarmSnapshot,
   listSwarms,
@@ -13,6 +16,7 @@ import {
   type SwarmMember,
   type SwarmSnapshot,
 } from '@/lib/server/agents/subagent-swarm'
+import { collectAncestorAgentIds } from '@/lib/server/agents/subagent-runtime'
 
 /**
  * Unit tests for the swarm layer. Since spawnSubagent depends on storage,
@@ -22,6 +26,17 @@ import {
  */
 
 function fakeSwarmHandle(overrides?: Partial<SwarmHandle>): SwarmHandle {
+  const allSettled = Promise.resolve({
+    swarmId: 'swarm-test-1',
+    parentSessionId: 'parent-sess-1',
+    totalSpawned: 0,
+    totalCompleted: 0,
+    totalFailed: 0,
+    totalCancelled: 0,
+    totalSpawnErrors: 0,
+    durationMs: 0,
+    results: [],
+  })
   const base: SwarmHandle = {
     swarmId: 'swarm-test-1',
     parentSessionId: 'parent-sess-1',
@@ -29,18 +44,10 @@ function fakeSwarmHandle(overrides?: Partial<SwarmHandle>): SwarmHandle {
     status: 'running',
     createdAt: Date.now() - 5000,
     completedAt: null,
-    allSettled: Promise.resolve({
-      swarmId: 'swarm-test-1',
-      parentSessionId: 'parent-sess-1',
-      totalSpawned: 0,
-      totalCompleted: 0,
-      totalFailed: 0,
-      totalCancelled: 0,
-      totalSpawnErrors: 0,
-      durationMs: 0,
-      results: [],
-    }),
+    maxConcurrency: 4,
+    allSettled,
     firstSettled: Promise.resolve({ index: -1, result: null as any }),
+    quorumSettled: async () => allSettled,
     cancelAll: () => {},
     ...overrides,
   }
@@ -357,6 +364,92 @@ describe('subagent-swarm', () => {
   // Reliability fix: firstSettled with zero memberPromises (#15)
   // ---------------------------------------------------------------------------
 
+  // ---------------------------------------------------------------------------
+  // Concurrency cap (v1.5.62+)
+  // ---------------------------------------------------------------------------
+
+  describe('clampSwarmConcurrency', () => {
+    it('returns 1 when task count is 0 or 1', () => {
+      assert.equal(_clampSwarmConcurrency(8, 0), 1)
+      assert.equal(_clampSwarmConcurrency(8, 1), 1)
+    })
+
+    it('uses the default when no explicit cap is given', () => {
+      assert.equal(_clampSwarmConcurrency(undefined, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+    })
+
+    it('honors an explicit finite positive cap', () => {
+      assert.equal(_clampSwarmConcurrency(2, 10), 2)
+      assert.equal(_clampSwarmConcurrency(7, 10), 7)
+    })
+
+    it('enforces the hard limit', () => {
+      assert.equal(_clampSwarmConcurrency(100, 50), SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+    })
+
+    it('rounds and floors the cap to an integer >= 1', () => {
+      assert.equal(_clampSwarmConcurrency(3.9, 10), 3)
+      assert.equal(_clampSwarmConcurrency(0, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+      assert.equal(_clampSwarmConcurrency(-4, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+      assert.equal(_clampSwarmConcurrency(Number.NaN, 10), SWARM_DEFAULT_PARALLEL_CONCURRENCY)
+    })
+  })
+
+  // ---------------------------------------------------------------------------
+  // Cycle detection via ancestor agentIds (v1.5.62+)
+  // ---------------------------------------------------------------------------
+
+  describe('collectAncestorAgentIds', () => {
+    it('returns empty when the session is unknown', () => {
+      assert.deepEqual(collectAncestorAgentIds('missing', {}), [])
+      assert.deepEqual(collectAncestorAgentIds(undefined, {}), [])
+    })
+
+    it('walks parent chain and collects agentIds', () => {
+      const sessions: Record<string, unknown> = {
+        root: { id: 'root', agentId: 'agent-root', parentSessionId: null },
+        mid: { id: 'mid', agentId: 'agent-mid', parentSessionId: 'root' },
+        leaf: { id: 'leaf', agentId: 'agent-leaf', parentSessionId: 'mid' },
+      }
+      assert.deepEqual(
+        collectAncestorAgentIds('leaf', sessions),
+        ['agent-leaf', 'agent-mid', 'agent-root'],
+      )
+    })
+
+    it('terminates on a self-loop without infinite recursion', () => {
+      const sessions: Record<string, unknown> = {
+        a: { id: 'a', agentId: 'agent-a', parentSessionId: 'a' },
+      }
+      assert.deepEqual(collectAncestorAgentIds('a', sessions), ['agent-a'])
+    })
+
+    it('detects a cycle candidate (A → B → A is visible in the chain)', () => {
+      const sessions: Record<string, unknown> = {
+        root: { id: 'root', agentId: 'agent-a', parentSessionId: null },
+        child: { id: 'child', agentId: 'agent-b', parentSessionId: 'root' },
+      }
+      const chain = collectAncestorAgentIds('child', sessions)
+      // Attempting to spawn agent-a again would be caught by the cycle check:
+      assert.ok(chain.includes('agent-a'))
+    })
+  })
+
+  // ---------------------------------------------------------------------------
+  // quorumSettled (v1.5.62+)
+  // ---------------------------------------------------------------------------
+
+  describe('quorumSettled shape', () => {
+    it('fakeSwarmHandle exposes the new quorumSettled and maxConcurrency fields', async () => {
+      const swarm = fakeSwarmHandle({ maxConcurrency: 3 })
+      assert.equal(swarm.maxConcurrency, 3)
+      assert.equal(typeof swarm.quorumSettled, 'function')
+      const agg = await swarm.quorumSettled(1)
+      assert.ok(agg)
+      assert.equal(agg.totalSpawned, 0)
+    })
+  })
+
   describe('firstSettled — all spawn errors (zero promises)', () => {
     it('firstSettled resolves with a valid SubagentResult, not null', async () => {
       // Build a swarm where ALL members fail to spawn

package/src/lib/server/agents/subagent-swarm.ts

@@ -63,10 +63,19 @@ export interface SwarmHandle {
   createdAt: number
   /** When all members finished (null if still running) */
   completedAt: number | null
+  /** Effective concurrency cap used to dispatch this swarm. 0 = unbounded (non-serial). */
+  maxConcurrency: number
   /** Promise that resolves when ALL members complete */
   allSettled: Promise<SwarmAggregateResult>
   /** Promise that resolves when the FIRST member completes */
   firstSettled: Promise<{ index: number; result: SubagentResult }>
+  /**
+   * Resolve when `count` members succeed (status === 'completed').
+   * If the swarm cannot reach the quorum (enough members already failed),
+   * resolves with the current aggregate. When `cancelRemaining` is true,
+   * best-effort aborts in-flight members after the quorum is reached.
+   */
+  quorumSettled: (count: number, opts?: { cancelRemaining?: boolean }) => Promise<SwarmAggregateResult>
   /** Cancel all running members */
   cancelAll: () => void
 }
@@ -109,8 +118,29 @@ export interface BatchSpawnInput {
   onSwarmComplete?: (result: SwarmAggregateResult) => void
   /** Execution mode for sibling subagents. Auto defaults to serial for Ollama-backed targets. */
   executionMode?: 'auto' | 'parallel' | 'serial'
+  /**
+   * Maximum number of members allowed to run concurrently when `executionMode`
+   * resolves to `'parallel'`. A value of 0 or `undefined` preserves the legacy
+   * unbounded behavior. Ignored in serial mode (always 1).
+   */
+  maxConcurrency?: number
 }
 
+/** Hard cap on `maxConcurrency` regardless of caller-supplied value. */
+export const SWARM_MAX_CONCURRENCY_HARD_LIMIT = 16
+/** Default concurrency when a parallel swarm does not specify an explicit cap. */
+export const SWARM_DEFAULT_PARALLEL_CONCURRENCY = 4
+
+function clampConcurrency(requested: number | undefined, taskCount: number): number {
+  if (taskCount <= 1) return 1
+  const raw = typeof requested === 'number' && Number.isFinite(requested) && requested > 0
+    ? Math.floor(requested)
+    : SWARM_DEFAULT_PARALLEL_CONCURRENCY
+  return Math.min(SWARM_MAX_CONCURRENCY_HARD_LIMIT, Math.max(1, raw))
+}
+
+export const _clampSwarmConcurrency = clampConcurrency
+
 // ---------------------------------------------------------------------------
 // Batch types (absorbed from subagent-batch)
 // ---------------------------------------------------------------------------
@@ -165,6 +195,7 @@ function persistSwarmSnapshot(swarm: SwarmHandle): void {
       parentSessionId: swarm.parentSessionId,
       status: swarm.status,
       memberCount: swarm.members.length,
+      maxConcurrency: swarm.maxConcurrency,
       createdAt: swarm.createdAt,
       completedAt: swarm.completedAt,
       updatedAt: Date.now(),
@@ -198,9 +229,20 @@ export async function spawnSwarm(
   const createdAt = Date.now()
   const members: SwarmMember[] = []
   const executionMode = _resolveSwarmExecutionMode(input.tasks, input.executionMode)
-  const executionGroupKey = executionMode === 'serial'
-    ? `swarm:${context.sessionId || 'root'}:${swarmId}`
-    : undefined
+  const effectiveConcurrency = executionMode === 'serial'
+    ? 1
+    : clampConcurrency(input.maxConcurrency, input.tasks.length)
+  const parentKey = context.sessionId || 'root'
+
+  // Concurrency is implemented by bucketing tasks across N shared execution
+  // group keys — each bucket serializes through the existing session-run-manager
+  // per-execution lock, so bucket count === effective parallelism.
+  const bucketKeyFor = (index: number): string | undefined => {
+    if (executionMode === 'serial') return `swarm:${parentKey}:${swarmId}`
+    if (effectiveConcurrency >= input.tasks.length) return undefined
+    const bucket = index % effectiveConcurrency
+    return `swarm:${parentKey}:${swarmId}:b${bucket}`
+  }
 
   // Pre-load sessions once for all spawns (avoids N SQLite reads)
   const cachedSessions = context._sessions ?? loadSessions()
@@ -218,7 +260,7 @@ export async function spawnSwarm(
           cwd: task.cwd,
           shareBrowserProfile: task.shareBrowserProfile,
           waitForCompletion: false,
-          executionGroupKey,
+          executionGroupKey: bucketKeyFor(i),
         },
         cachedContext,
       )
@@ -249,8 +291,10 @@ export async function spawnSwarm(
     status: 'running',
     createdAt,
     completedAt: null,
+    maxConcurrency: effectiveConcurrency,
     allSettled: null as unknown as Promise<SwarmAggregateResult>,
     firstSettled: null as unknown as Promise<{ index: number; result: SubagentResult }>,
+    quorumSettled: null as unknown as SwarmHandle['quorumSettled'],
     cancelAll: () => {
       for (const member of members) {
         if (member.handle && !member.result && !member.spawnError) {
@@ -330,6 +374,46 @@ export async function spawnSwarm(
         }
       })
 
+  // quorumSettled — resolves when `count` members succeed. If too many fail to
+  // ever reach the quorum, falls back to allSettled.
+  swarm.quorumSettled = (count, opts) => {
+    const requested = Math.max(1, Math.floor(Number.isFinite(count) ? count : 1))
+    const target = Math.min(requested, swarm.members.length)
+    const cancelRemaining = opts?.cancelRemaining !== false
+    if (target <= 0 || memberPromises.length === 0) return swarm.allSettled
+    return new Promise<SwarmAggregateResult>((resolve) => {
+      let settled = false
+      let successes = 0
+      let finalized = 0
+      const finalize = () => {
+        if (settled) return
+        settled = true
+        if (cancelRemaining) {
+          for (const member of members) {
+            if (member.handle && !member.result && !member.spawnError) {
+              try {
+                member.handle.run.abort()
+                cancelLineageNode(member.handle.lineageId)
+              } catch { /* best-effort */ }
+            }
+          }
+        }
+        swarm.allSettled.then(resolve).catch(() => resolve(buildAggregateResult(swarm)))
+      }
+      for (const p of memberPromises) {
+        p.then(({ result }) => {
+          finalized++
+          if (result.status === 'completed') successes++
+          if (successes >= target) finalize()
+          else if (finalized >= memberPromises.length) finalize()
+        }).catch(() => {
+          finalized++
+          if (finalized >= memberPromises.length) finalize()
+        })
+      }
+    })
+  }
+
   // Register in swarm registry
   swarmRegistry.set(swarmId, swarm)
   notifySwarmChanged()
@@ -575,6 +659,7 @@ export interface SwarmSnapshot {
   memberCount: number
   completedCount: number
   failedCount: number
+  maxConcurrency?: number
   members: SwarmMemberSnapshot[]
 }
 
@@ -622,6 +707,7 @@ function buildSwarmSnapshot(swarm: SwarmHandle): SwarmSnapshot {
     failedCount: members.filter((m) =>
       m.status === 'failed' || m.status === 'timed_out' || m.status === 'spawn_error',
     ).length,
+    maxConcurrency: swarm.maxConcurrency,
     members,
   }
 }

package/src/lib/server/session-tools/chatroom.ts

@@ -12,7 +12,6 @@ import { log } from '../logger'
 import { debug } from '../debug'
 import { logExecution } from '../execution-log'
 import { logActivity } from '../storage'
-import { WORKER_ONLY_PROVIDER_IDS } from '@/lib/provider-sets'
 
 /**
  * Core Chatroom Execution Logic
@@ -78,12 +77,6 @@ async function executeChatroomAction(args: Record<string, unknown>, context: { a
       const agents = loadAgents()
       const requestedAgentIds = agentIds || []
       const validAgentIds = requestedAgentIds.filter((aid: string) => !!agents[aid])
-      const cliAgentNames = validAgentIds
-        .filter((aid: string) => WORKER_ONLY_PROVIDER_IDS.has(agents[aid]?.provider))
-        .map((aid: string) => agents[aid]?.name || aid)
-      if (cliAgentNames.length > 0) {
-        return `Error: CLI-based agents cannot join chatrooms: ${cliAgentNames.join(', ')}. They can only be used for direct chats and delegation.`
-      }
 
       const chatroom: Chatroom = {
         id,
@@ -208,10 +201,6 @@ async function executeChatroomAction(args: Record<string, unknown>, context: { a
 
     if (action === 'add_agent') {
       if (!agentId) return 'Error: agentId required.'
-      const agents = loadAgents()
-      if (WORKER_ONLY_PROVIDER_IDS.has(agents[agentId]?.provider)) {
-        return `Error: ${agents[agentId]?.name || agentId} is a CLI-based agent and cannot join chatrooms. CLI agents can only be used for direct chats and delegation.`
-      }
       if (!chatroom.agentIds.includes(agentId)) {
         chatroom.agentIds.push(agentId)
         chatroom.updatedAt = Date.now()

package/src/lib/server/session-tools/subagent.ts

@@ -34,7 +34,11 @@ import {
   listSwarms,
   aggregateResults,
   waitForAll,
+  SWARM_MAX_CONCURRENCY_HARD_LIMIT,
+  SWARM_DEFAULT_PARALLEL_CONCURRENCY,
 } from '@/lib/server/agents/subagent-swarm'
+import { getSession } from '@/lib/server/sessions/session-repository'
+import { getMission } from '@/lib/server/missions/mission-repository'
 
 const SUBAGENT_ACTIONS = [
   'start',
@@ -73,6 +77,10 @@ const subagentToolSchema = z.object({
   jobIds: z.union([z.array(z.string()), z.string()]).optional(),
   tasks: z.union([z.array(subagentTaskSchema), z.string()]).optional(),
   executionMode: z.enum(['auto', 'parallel', 'serial']).optional(),
+  maxConcurrency: z.union([z.number(), z.string()]).optional(),
+  joinPolicy: z.enum(['all', 'first', 'quorum']).optional(),
+  quorum: z.union([z.number(), z.string()]).optional(),
+  cancelRemaining: z.boolean().optional(),
   waitForCompletion: z.boolean().optional(),
   background: z.boolean().optional(),
   timeoutSec: z.union([z.number(), z.string()]).optional(),
@@ -150,10 +158,12 @@ export function coerceSubagentActionArgs(rawArgs: Record<string, unknown>): Reco
   const normalized = normalizeToolInputArgs(rawArgs)
   const coerced: Record<string, unknown> = { ...normalized }
 
-  for (const key of ['waitForCompletion', 'background', 'shareBrowserProfile'] as const) {
+  for (const key of ['waitForCompletion', 'background', 'shareBrowserProfile', 'cancelRemaining'] as const) {
     coerced[key] = parseBooleanLike(coerced[key])
   }
   coerced.timeoutSec = parseNumberLike(coerced.timeoutSec)
+  coerced.maxConcurrency = parseNumberLike(coerced.maxConcurrency)
+  coerced.quorum = parseNumberLike(coerced.quorum)
 
   const parsedTasks = parseJsonLike(coerced.tasks)
   if (Array.isArray(parsedTasks)) {
@@ -239,6 +249,76 @@ function requireString(args: Record<string, unknown>, key: string): string {
   return val
 }
 
+type JoinPolicy =
+  | { type: 'all' }
+  | { type: 'first' }
+  | { type: 'quorum'; count: number; cancelRemaining: boolean }
+
+function parseJoinPolicy(args: Record<string, unknown>, taskCount: number): JoinPolicy {
+  const raw = typeof args.joinPolicy === 'string' ? args.joinPolicy.trim().toLowerCase() : ''
+  if (raw === 'first') return { type: 'first' }
+  if (raw === 'quorum') {
+    const parsed = typeof args.quorum === 'number' ? args.quorum : Number(args.quorum)
+    const count = Number.isFinite(parsed) && parsed > 0
+      ? Math.min(Math.floor(parsed), taskCount)
+      : Math.max(1, Math.ceil(taskCount / 2))
+    const cancelRemaining = args.cancelRemaining !== false
+    return { type: 'quorum', count, cancelRemaining }
+  }
+  return { type: 'all' }
+}
+
+/**
+ * Resolve the effective maxConcurrency for a swarm dispatch using the
+ * precedence: explicit arg > agent.maxParallelDelegations > mission.budget.maxParallelBranches > system default.
+ */
+function resolveSwarmMaxConcurrency(
+  args: Record<string, unknown>,
+  ctx: ActionContext,
+): number {
+  const pickFinite = (value: unknown): number | null => {
+    const n = typeof value === 'number' ? value : Number(value)
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null
+  }
+  const explicit = pickFinite(args.maxConcurrency)
+  if (explicit !== null) return Math.min(explicit, SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+
+  if (ctx.agentId) {
+    const agent = loadAgents()[ctx.agentId]
+    const agentCap = pickFinite(agent?.maxParallelDelegations)
+    if (agentCap !== null) return Math.min(agentCap, SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+  }
+
+  if (ctx.sessionId) {
+    const session = getSession(ctx.sessionId) as { missionId?: string | null } | null
+    const missionId = typeof session?.missionId === 'string' && session.missionId.trim()
+      ? session.missionId.trim()
+      : null
+    if (missionId) {
+      const mission = getMission(missionId)
+      const missionCap = pickFinite(mission?.budget?.maxParallelBranches)
+      if (missionCap !== null) return Math.min(missionCap, SWARM_MAX_CONCURRENCY_HARD_LIMIT)
+    }
+  }
+
+  return SWARM_DEFAULT_PARALLEL_CONCURRENCY
+}
+
+async function awaitSwarmByPolicy(
+  swarm: Awaited<ReturnType<typeof spawnSwarm>>,
+  policy: JoinPolicy,
+): Promise<ReturnType<typeof spawnSwarm> extends Promise<infer T> ? T extends { allSettled: Promise<infer A> } ? A : never : never> {
+  if (policy.type === 'first') {
+    await swarm.firstSettled
+    swarm.cancelAll()
+    return swarm.allSettled
+  }
+  if (policy.type === 'quorum') {
+    return swarm.quorumSettled(policy.count, { cancelRemaining: policy.cancelRemaining })
+  }
+  return swarm.allSettled
+}
+
 // ---------------------------------------------------------------------------
 // Promise-based wait (no polling when handle exists)
 // ---------------------------------------------------------------------------
@@ -336,9 +416,11 @@ async function handleBatch(args: Record<string, unknown>, ctx: ActionContext): P
   const executionMode = args.executionMode === 'parallel' || args.executionMode === 'serial'
     ? args.executionMode
     : 'auto'
+  const maxConcurrency = resolveSwarmMaxConcurrency(args, ctx)
+  const policy = parseJoinPolicy(args, tasks.length)
 
   // Use spawnSwarm internally — batch is a simplified interface
-  const swarm = await spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
+  const swarm = await spawnSwarm({ tasks, executionMode, maxConcurrency }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
   const jobIds = swarm.members
     .filter((m) => !m.spawnError && m.handle)
     .map((m) => m.handle.jobId)
@@ -349,13 +431,16 @@ async function handleBatch(args: Record<string, unknown>, ctx: ActionContext): P
       status: 'running',
       jobIds,
       taskCount: tasks.length,
+      maxConcurrency: swarm.maxConcurrency,
     })
   }
-  const aggregate = await swarm.allSettled
+  const aggregate = await awaitSwarmByPolicy(swarm, policy)
   return JSON.stringify({
     action: 'batch',
     status: 'completed',
     jobIds,
+    maxConcurrency: swarm.maxConcurrency,
+    joinPolicy: policy.type,
     completed: aggregate.totalCompleted,
     failed: aggregate.totalFailed + aggregate.totalSpawnErrors,
     cancelled: aggregate.totalCancelled,
@@ -397,8 +482,10 @@ async function handleSwarm(args: Record<string, unknown>, ctx: ActionContext): P
   const executionMode = args.executionMode === 'parallel' || args.executionMode === 'serial'
     ? args.executionMode
     : 'auto'
+  const maxConcurrency = resolveSwarmMaxConcurrency(args, ctx)
+  const policy = parseJoinPolicy(args, tasks.length)
 
-  const swarm = await spawnSwarm({ tasks, executionMode }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
+  const swarm = await spawnSwarm({ tasks, executionMode, maxConcurrency }, { sessionId: ctx.sessionId, cwd: ctx.cwd })
   if (!waitForCompletion) {
     const snapshot = getSwarmSnapshot(swarm.swarmId)
     return JSON.stringify({
@@ -406,15 +493,18 @@ async function handleSwarm(args: Record<string, unknown>, ctx: ActionContext): P
       status: 'running',
       swarmId: swarm.swarmId,
       memberCount: swarm.members.length,
+      maxConcurrency: swarm.maxConcurrency,
       snapshot,
     })
   }
-  const aggregate = await swarm.allSettled
+  const aggregate = await awaitSwarmByPolicy(swarm, policy)
   const snapshot = getSwarmSnapshot(swarm.swarmId)
   return JSON.stringify({
     action: 'swarm',
     ...aggregate,
     status: swarm.status,
+    maxConcurrency: swarm.maxConcurrency,
+    joinPolicy: policy.type,
     snapshot,
   })
 }
@@ -633,6 +723,23 @@ const SubagentExtension: Extension = {
             enum: ['auto', 'parallel', 'serial'],
             description: 'How to schedule sibling subagents. "auto" defaults to serial for Ollama-backed targets and parallel otherwise.',
           },
+          maxConcurrency: {
+            type: 'number',
+            description: 'Max sibling branches that may run at the same time when parallel. Defaults to agent/mission policy or 4. Hard-capped at 16.',
+          },
+          joinPolicy: {
+            type: 'string',
+            enum: ['all', 'first', 'quorum'],
+            description: 'How to wait. "all" (default) waits for every branch. "first" resolves when one succeeds and cancels the rest. "quorum" resolves when `quorum` branches succeed.',
+          },
+          quorum: {
+            type: 'number',
+            description: 'Required when joinPolicy="quorum" — number of successful branches needed before resolving.',
+          },
+          cancelRemaining: {
+            type: 'boolean',
+            description: 'When joinPolicy="quorum", cancel in-flight branches after quorum is reached. Default true.',
+          },
           waitForCompletion: { type: 'boolean' },
           background: { type: 'boolean' },
           timeoutSec: { type: 'number' },

package/src/lib/server/storage-normalization.ts

@@ -399,6 +399,7 @@ function normalizeStoredAgentMissionRecord(value: unknown): unknown {
   budget.maxToolCalls = normalizeFiniteNumber(budget.maxToolCalls)
   budget.maxWallclockSec = normalizeFiniteNumber(budget.maxWallclockSec)
   budget.maxTurns = normalizeFiniteNumber(budget.maxTurns)
+  budget.maxParallelBranches = normalizeFiniteNumber(budget.maxParallelBranches)
   if (!Array.isArray(budget.warnAtFractions)) {
     budget.warnAtFractions = [0.5, 0.8, 0.95]
   } else {
@@ -620,6 +621,7 @@ function normalizeStoredRecordInner(
     if (!Array.isArray(agent.delegationTargetAgentIds)) {
       agent.delegationTargetAgentIds = legacyTargetIds
     }
+    agent.maxParallelDelegations = normalizeFiniteNumber(agent.maxParallelDelegations)
     delete agent.platformAssignScope
     delete agent.subAgentIds
     agent.sandboxConfig = normalizeAgentSandboxConfig(agent.sandboxConfig)

package/src/lib/validation/schemas.ts

@@ -88,6 +88,7 @@ export const AgentCreateSchema = z.object({
   delegationEnabled: z.boolean().optional().default(false),
   delegationTargetMode: z.enum(['all', 'selected']).optional().default('all'),
   delegationTargetAgentIds: z.array(z.string()).optional().default([]),
+  maxParallelDelegations: z.number().int().positive().nullable().optional().default(null),
   tools: z.array(z.string()).optional(),
   extensions: z.array(z.string()).optional().default([]),
   skills: z.array(z.string()).optional().default([]),

package/src/types/agent.ts

@@ -67,6 +67,12 @@ export interface Agent {
   delegationEnabled?: boolean
   delegationTargetMode?: DelegationTargetMode
   delegationTargetAgentIds?: string[]
+  /**
+   * Cap on sibling subagents this agent may dispatch concurrently via
+   * `spawn_subagent` swarm/batch actions. Resolves after the mission-level
+   * cap and before the system default (4). Hard-capped at 16.
+   */
+  maxParallelDelegations?: number | null
   tools?: string[]
   // When 'scoped', the chat turn restricts enabled extensions to the
   // intersection of the universal core list and agent.tools (plus a small

package/src/types/mission.ts

@@ -28,6 +28,12 @@ export interface MissionBudget {
   maxToolCalls?: number | null
   maxWallclockSec?: number | null
   maxTurns?: number | null
+  /**
+   * Cap on concurrent sub-agent branches when this mission's agents fan out
+   * via `spawn_subagent` swarm/batch actions. Overrides the system default
+   * (4) when set. Hard-capped at 16 regardless.
+   */
+  maxParallelBranches?: number | null
   warnAtFractions?: number[]
 }