background subagents v2: session-scoped detach (durable outbox + child supervisor)
@JAORMX is already working on this.
Since Sep 7, 2026.
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
Context
The bg-subagents arc (2d0bb4f..0bdcc21) shipped run-scoped background subagents: a background child is cancelled+drained when its parent run ends. That bound is structural, not a preference — child events ride the run's event channel (closed at run end) and delivery is run-stream-coupled, so a child completing with no live run has no client, no outbox, no notification channel. See docs/design/BACKGROUND-SUBAGENTS.md (D8 + the v2 section).
This is the agents half follow-up to #23; the commands half (background Bash) remains there.
Shape (from the design doc)
context.WithoutCanceldetachment of the child goroutine from the run ctx tree.- A Service-owned child supervisor (lifecycle beyond any single run).
- A durable per-session completion outbox so events/results survive with no live stream, drained on the next Converse/SSE attach.
- Re-attach semantics + server-shutdown draining.
- Everything shipped in v1 carries forward unchanged: the child-run registry, the session-id handle convention, SubagentStatus (poll + wait_ms), and the turn-boundary notice seam — only cancel-scope and event routing change.
Acceptance sketch
A background child started in run A delivers its completion notice at the start of run B on the same session; mecatui shows the detached child across runs; server shutdown drains or persists cleanly; the leak gates stay green.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.