acpmux: agent sessions start, steer and stop their own sub-sessions (review record)

Merged
LA
18d ago
+3157-26

Review record for the acpmux sub-session tools. This lands directly on feat-cmux-next (lane rule: no PRs into feat-cmux-next); this PR only carries the review and is closed with the landed SHA.

What

  • Every local acpmux agent session (Claude Code, Codex, every harness) gets a cmux-subsessions MCP server by default: start_session, list_sessions, get_session, wait_for_sessions, send_message, stop_session, set_session_limits.
  • Width and depth limits come from the settings catalog: agents.subsessions.enabled (on), agents.subsessions.maxChildren (50, 1 to 1000), agents.subsessions.maxDepth (10, 1 to 100), in schemas/settings/source/subsessions.json. The daemon embeds the same file for its defaults. Settings > Agents > Sub-sessions shows the rows.
  • Spec: plans/cmux-next/subagents/PROTOCOL.md (HQ); source of truth cmux-tui/crates/acpmux/spec/acpmux-protocol.json.

Tests

Behavior tests at the daemon socket: cmux-tui/crates/acpmux/tests/subsessions.rs; live Claude Code and Codex: tests/subsessions_live.rs (gated on ACPMUX_SUBSESSIONS_LIVE_CLAUDE / _CODEX).

šŸ¤– Generated with Claude Code

Summary by cubic

Enables agent sessions to start, steer and stop their own sub-sessions. Every local session (all harnesses) now gets a cmux-subsessions MCP server by default, with width and depth limits enforced by the daemon from three new user-only settings. This review record lands directly on feat-cmux-next and is closed with the landed SHA.

Behavior

  • The tools (start_session, list_sessions, get_session, wait_for_sessions, send_message, stop_session, set_session_limits) map one-to-one to daemon requests proven by the session's caller token, never by a request field.
  • A sub-session is a normal session that carries a startedBy, shortName and depth link; SessionSummary exposes them plus open-child counts, and forks or accepted offers never inherit the link.
  • Limits cascade from the session's own override, then an ancestor's, then the settings (agents.subsessions.maxChildren 50, maxDepth 10), then the embedded catalog defaults; a refusal names the limit, its value and source, and how to get more.
  • stop_session with close:true closes the whole subtree and frees its slots; send reaches descendants or the caller's own parent.
  • The person can raise limits at runtime up to the catalog max; an ancestor can lower them within its own budget; a session can never raise its own.

Settings and tests

  • Three user-only rows under Settings > Agents > Sub-sessions, produced from schemas/settings/source/subsessions.json in all 21 locales; the daemon embeds the same file.
  • Behavior tests at the daemon socket (stand-in agents) plus live Claude Code and Codex tests, gated on ACPMUX_SUBSESSIONS_LIVE_CLAUDE / _CODEX.