Overview
ArcSwarm is the parallel subagent coordination layer for the Grid. It answers the question: how does one agent spawn many agents, wait for all of them, and merge their results — safely, with audit, and without losing identity context?
The package lives at brain/arcrouter/swarm/ in the Brain repo and is designed to be called from any agent running via ArcTrigger or ArcRouter.
ArcSwarm is under active development (brain repo PR #6). The core fan-out primitive and charter inheritance are defined. HAG and result merging are in progress.
Core concepts
Parallel dispatch
The coordinator agent defines a set of tasks and dispatches them as concurrent subagent calls. Each subagent runs independently and returns a typed result.
Result merging
ArcSwarm waits for all subagents to complete, then calls the merge function with the full result set. The coordinator gets a single merged output.
Identity boundary
Every subagent inherits a scoped copy of the coordinator's ArcCharter. It can only act within the scope defined by the parent — no permission escalation.
Commit gate
Before any swarm result is committed to state (graph write, file write, API call), it passes through the Human Approval Gate. Humans stay in the loop at every decision boundary.
Charter inheritance
When the coordinator dispatches a subagent, ArcSwarm creates a child ArcCharter scoped to the task:
const charter = parentCharter.scope({
agent_id: "swarm-worker-1",
allowed_tools: parentCharter.tools, // inherits parent tools
allowed_scopes: [task.scope], // restricted to this task
can_write: task.allowWrite ?? false, // write-gated by default
parent_id: parentCharter.id // full audit trail
});Subagents receive only the permissions they need for their specific task. A subagent analyzing code cannot make API calls unless the parent charter explicitly allows it.
HAG (Human Approval Gate)
HAG fires before any state-mutating commit. The coordinator receives a diff of all pending changes from the swarm, approves or rejects each, and only approved changes are applied.
- Read-only swarms (analysis, research) bypass HAG and return directly
- Write swarms (code gen, graph writes, deploys) always require HAG
- HAG decisions are logged to the audit trail alongside the charter IDs of each subagent that contributed
Usage
import { Swarm } from "@arcgrid/swarm";
const swarm = new Swarm({ charter });
const results = await swarm.fanOut([
{ task: "analyze auth module", scope: "read", agent: "code-analyst" },
{ task: "analyze API routes", scope: "read", agent: "code-analyst" },
{ task: "analyze DB schema", scope: "read", agent: "code-analyst" },
]);
// results is an array of typed outputs from each subagent
// merge into a unified finding
const merged = swarm.merge(results);Build status
- Core fan-out/fan-in primitive — defined
- ArcCharter child scoping — defined
- HAG integration — in progress (PR #6)
- Result merging strategy — in progress
- Audit trail writes to neo4j — planned
- Surface integration (swarm status pane) — planned
Package: @arcgrid/swarm. Source: brain/arcrouter/swarm/ in agent-space-co/brain.