Coordination & Communication
How agents, the coordination layer, and you stay in sync — blockers, requests, and what the fleet view actually tells you.
xSwarm agents work autonomously across projects, which raises an obvious question: how do you find out what they’re doing, and how do they reach you when they need a decision only you can make? Two structured record types answer that, plus a status feed that tells you what it can and plainly says what it can’t.
Blockers — questions raised to you
When an agent needs a human decision and would otherwise just stop and wait, it files a blocker instead. A blocker is not a bare question — the API rejects one that doesn’t carry:
- At least two options, each a real alternative.
- A recommendation — what the agent would do if forced to choose, and why.
The design intent: you should be able to answer in one word. “Hold a day or cut over now?” with a stated recommendation gets a “yes” in five minutes. A bare “what should I do?” hands the thinking back to you and sits unanswered for hours or days. An agent may also withdraw its own blocker if the question becomes moot before you see it — always with a stated reason, so the record still reads as a complete story rather than vanishing.
Requests — things you asked for, tracked so they can’t go missing
The other direction: things you explicitly asked for, recorded so a request made in conversation can’t be silently lost when a session ends or compacts. Two rules govern them:
- A request states up front what would prove it done (
evidence_required), before work starts. - It closes only on evidence, never on a claim. “I fixed it” is rejected. A test run, a live response, a screenshot at the stated size — something that couldn’t be talked past — is required to close it.
Other work can legitimately outrank a request. That’s normal, but it’s never silent: an
agent that sets a request aside for something more urgent has to say why, and the
request stays open (displaced), not deleted.
The activity feed and session status
Every tool call, prompt, and stop from every session is recorded automatically via hooks — this is mechanical coverage, not something an agent has to remember to do. The fleet view shows a status per session, and it’s worth knowing exactly what each one claims and doesn’t:
- working — a hook fired recently. Tool calls are happening; this says nothing about whether the approach is right.
- idle — the last turn ended. Not the same as “task done” — it can mean genuinely finished, or mid-task waiting to be noticed.
- needs_human — a notification fired. Could be a routine permission prompt or a real blocker; the filed blocker’s own question is what tells you which.
- ended — the session closed. Doesn’t distinguish a clean finish from a crash.
- unknown — the session has gone quiet long enough (currently 15 minutes) that its last reported status can no longer be trusted, so it’s shown as unknown rather than as whatever it last claimed.
Hooks give mechanical coverage; they can’t produce the sentence “code-complete, needs a go/no-go on the cutover.” Agents can additionally post plain-language milestones as real progress happens, layered over the mechanical status, not replacing it.
When an agent may stop and ask
Not every uncertainty warrants a blocker. An agent is expected to proceed and course- correct on anything it can reasonably decide itself, and to stop and ask only for: a permission it cannot grant itself, spending money, an irreversible outward-facing action (a deploy, a publish), approving something on someone else’s behalf, or a genuine product decision with no defensible default. Everything else gets a decision made, reported, and revisited if wrong — rather than a stalled session waiting on an answer that might not come for days.