Design & Implementation Plan: Async Agent Coordination + Typed Guardrails (follow-up to #444)

[jflowers]

Context

This is a concrete, spiked implementation plan for the proposal in #444 (Asynchronous Agent Coordination & Typed Guardrails via OpenCode Background Listeners). It reflects a design pass against our current architecture (forge/Replicator swarm, /uf.unleash, the Divisor review council).

TL;DR

We already have a working multi-agent swarm. The right move is extend, don't rebuild — the delta needed to deliver #444 is narrow:

1. Real-time push (Replicator comms/forge_broadcast are SQLite polling today).
2. Mid-flight typed interruptions (the Divisor council escalates only at phase gates, not during execution).
3. Headless cross-repo/batch control (the scripted/ SDK driver's niche).

What already exists (reused as-is)

Capability	Where
Coordinator→worker orchestration	coordinator.md, worker.md, /forge
Background worker	background-worker.md
Parallel worktree execution (4 concurrent)	/uf.unleash via swarm_worktree_*
Messaging + file reservations	Replicator comms/
Broadcast (polled)	Replicator forge_broadcast
Typed review governance + ESCALATED verdict (phase-gated)	Divisor council (divisor-*)
Resumability via filesystem markers	/uf.unleash
Human gates (secrets/commit/push/PR)	/uf.finale

Architecture

Replicator talks to OpenCode over stdio JSON-RPC (request/response) — a plugin can't receive push there. So we add a second, opt-in transport: a local HTTP SSE sidecar. Push is one-way (broker → listener); the listener acts back through OpenCode's own SDK client.

Replicator (Go)
 ├─ stdio JSON-RPC  ───────────►  OpenCode MCP client   (existing: tools/call)
 └─ HTTP + SSE sidecar  ───────►  listener plugin        (NEW: held-open push)
       ▲ internal/events/ bus fans out message/reservation/forge events

The listener plugin (@opencode-ai/plugin) holds the SSE stream open, runs the typed-interruption router, and enacts decisions via the OpenCode client (session.command / prompt / abort).

Native substrate (feature-detected via experimental.capabilities.get())

• experimental.session.background({sessionID}) — detach blocking subagents to background.
• experimental.session.list(...) — cross-project session discovery.
• controlPlane.moveSession(...), experimental.workspace.warp(...) — session mobility.

Typed interruption contract

send_message requires structured JSON: { interruption: { type, severity, context, action_required } }. Bail on unknown type (safety property mirrored from the headless driver's answer table).

• IMPLEMENTATION_DEVIATION → inject "halt, discard tasks.md, re-propose" (self-heal).
• GOVERNANCE_BLOCKER → abort the /uf.unleash loop, escalate to a human architect.

This extends the Divisor council's escalation from phase-gated → real-time.

Design decisions (locked)

Decision	Choice
Vehicle	OpenCode plugin (not a standalone MCP server)
Plugin distribution	npm package (@unbound-force/coordination-plugin), referenced per-project
Push transport	SSE sidecar in Replicator (alongside stdio; polling stays for back-compat)
Isolation	Hybrid by goal — in-session subagents + session.background for the interactive swarm; separate server per issue for headless batch
Batch parallelism	Cross-issue only + one global cap (3); reuse /uf.unleash's internal swarm
Recursion	Depth-1 only (guarded via session metadata)
Registration	Per-project

Phased plan

• P1 — Native spike: confirm experimental.capabilities.get() + session.background; resolve the one real unknown — injection admission into a busy session (does client.session.prompt land mid-turn or at next idle?).
• P2 — Replicator push: internal/events/ bus + SSE sidecar + comms_subscribe; emit on message/reservation/forge events; polling untouched.
• P3 — Listener plugin + typed schema: SSE consumer, active-session map via the event hook, typed router, bail-on-unknown.
• P4 — Wire into pipeline: /uf.unleash workers emit typed signals; listener enacts self-heal vs. human escalation.
• P5 — Headless batch: scripted/ cross-issue loop (/opsx-propose → /uf.unleash → /uf.finale) under the global cap; scoped permission profiles replace allow-all; add --resume.

Feedback wanted

• P1 unknown: does OpenCode admit mid-turn injected prompts, or only at turn boundaries? This decides whether interruptions are truly mid-flight.
• Is Ideas the right home, or should this become a tracking issue once accepted?
• Any objection to the SSE sidecar vs. keeping everything on stdio?