Agent Orchestration

ArcSwarm SDK

Fan-out parallel subagent coordination with ArcCharter identity inheritance and HAG (Human Approval Gate) at commit boundaries. Enables any agent to spawn a swarm of specialized subagents, collect their results, and merge with full audit trail. Lives in brain/arcrouter/swarm/. Currently building (brain repo PR #6).

@arcgrid/swarmbrain repoArcCharterHAGBuilding

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.

Status: Building

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

Fan-out

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.

Fan-in

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.

Charter

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.

HAG

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.