ROADMAP-27 — P3 (future) — Multi-agent orchestration and HITL approvals (design note first) #119

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M17-T06 (future) · Priority: P3 · Effort: very large — design note only for now

Problem / goal

Two roadmap-scale capabilities are declared in the README but have no design:

1. Multi-agent orchestration — hierarchical supervisor-worker delegation without external frameworks (ADR-001 constraints apply).
2. Human-in-the-loop interrupts — pausing execution for approval before sensitive tools (destructive actions, payments).

Both depend on the async run lifecycle (ROADMAP-10) — pausing/resuming and supervising long-lived runs are impossible on in-request execution.

Expected outcome

A design note (or notes) in docs/ covering: orchestration model (supervisor/worker roles, state sharing, step/context budgeting per sub-run), HITL suspension points (tool-level gateway, approval token semantics, TTL on pending approvals, resumability), security implications (which tools are gated, audit trail of approvals), and the persistence schema changes. Issues for each design element get filed from that note — implementation starts after ROADMAP-10, ROADMAP-14 and ROADMAP-24 land.

Suggested branch / commit

docs/roadmap-multi-agent-hitl-design · docs: design note for multi-agent orchestration and HITL approvals