RFC: Group Coordination

[ribeirojose]

Why

Interruptions. Any session can message any other.

• A message waits until the recipient is at rest, then is typed into its prompt, which starts a turn (internal/execution/polldelivery.go).
• Delivery already holds while I have text typed in that prompt (polldelivery.go:62-66). Nothing limits who can send.
• So a session I parked on unrelated work picks up another agent's request and runs with it. The same goes for the rest: any agent can read, wait on or kill any session, and spawn into any group.

Experiments. I'd like to put a few agents in a group, give them a task, and have them coordinate only with each other while I watch. That's the same problem from the other side.

Visibility. What agents do to each other is hard to see and isn't kept.

• The TUI shows a count of queued messages (✉N, internal/ui/theme_styles.go:245), not who sent what, what a message started, or which agent spawned which. ParentID only nests terminals under a session.
• Delivered messages are pruned after 24 hours (internal/sessioncmd/owner.go:70).
• Deleting a session removes its messages (internal/store/sessions.go:600).
• Task updates overwrite the row in place (internal/store/tasks.go:79-133).

Note: This assumes #735 lands as is. File references are permalinks to that branch at cebd90c.

Principles

• Unopinionated. Agent Manager shouldn't prescribe a lead/worker shape, an orchestrator or a workflow. It offers one primitive, reach, plus a record of what crossed it. People arrange their sessions however they like on top.
• Nothing changes unless you set it. The default stays open.
• Only agents are limited. The human in the TUI is never restricted, and neither is a script run with no session.
• Only the human sets policy. Agents can't change the reach or mode of any group or session, including their own.
• Behavioral gates (not a safe sandbox). An agent runs with the user's shell privileges. It can unset AGENT_MANAGER_SESSION_ID (internal/hooks/hooks.go:29) and call the CLI as a script, open state.db, or run tmux send-keys. Reach keeps well-behaved agents from stepping on each other; it doesn't contain a hostile agent. The docs and UI should say so.

Where things are today

• Coordination mode ("on request" or "proactive") is one global setting (internal/store/settings.go:52). It reaches an agent in one of two ways:

  • MCP tools: the MCP server reads it at start (internal/mcpserver/mcpserver.go:821-828).
  • Tools without MCP: a launch-prompt note (internal/launch/launch.go:38-41).

  It is guidance in text mostly w/o enforcement though.

• Groups already carry settings that resolve from the nearest ancestor: worktree and base (internal/sessioncmd/spawn.go:174-222). Spawn without a group lands in the caller's group (spawn.go:26-28).

• Tasks have no group (internal/store/tasks.go).

• Inbox limits are global: a queue of 20, 5 per minute, and 8 per pair per 10 minutes (internal/store/inbox.go:41-48).

• No-session callers. Commands that accept a caller with no session serve scripts outside Agent Manager (optionalCaller, internal/sessioncmd/runtime.go:119).

Reach

Commands that touch another session fall into two kinds:

• See: sessions/list_sessions, groups/list_groups, read, wait, message_status, and listing terminals.
• Act: send, spawn into a group, kill, revive, archive, rename, and task changes.

Interruptions come from acting. Seeing is mostly harmless and often useful, for example an agent reading a sibling's screen before starting the same work.

A group or a single session can set reach:

reach	Across the boundary, in either direction
open (default)	No boundary
quiet	Can see, can't act
closed	Can't see, can't act

Proposed rule. A session's scope is the innermost group or session around it whose reach isn't open, or the whole profile when there is none.

• Two sessions in the same scope can see and act on each other.
• Across scopes, acting is refused, and seeing is refused if any closed boundary separates them.
• Boundaries nest: a closed subgroup inside a quiet group is its own scope.

What follows from the rule:

• One session. Marking a single session quiet is "do not disturb": other agents can still see it, but none can message, kill or spawn into it. It doesn't have to move in the tree.
• Spawn. A member's spawns land in its own scope, which is already the default group (spawn.go:26-28). Spawning into a group outside the scope is refused. The same goes for creating groups.
• Tasks. Tasks gain a scope, set from the creator. A list shows the caller's scope. Existing tasks belong to the profile-wide scope.
• Reservations stay global, because they protect a shared checkout. Holders outside the caller's scope are listed without their names.
• Moves. Every call evaluates against the session's current group, so moving a session takes effect on its next command.
• Agents can't move sessions. Moving is TUI-only (m, internal/keybind/keybind.go:302); there's no CLI or MCP move. So an agent can't leave a boundary on its own. Any future move command for agents should check reach at both ends.
• Changing reach. create_group from an agent inherits its parent's reach. Setting reach is a human action, in the TUI or from a shell with no session.

What agents see.

• Lists only show what the caller can see, so agents don't aim at what they can't reach.
• A refusal names the reason and the way out. For example: "builder is outside your group's boundary, set by the user; ask the user if you need to reach it." Otherwise agents retry or route around.
• The MCP instructions and the launch note mention the boundary when the caller is inside one.

Coordination mode per group

A group can set the mode. It resolves like worktree and base, falling back to the global setting. The MCP server and the launch note read it from the caller's group. A change applies to sessions launched afterward and to any session whose MCP server restarts, as global changes do today.

Activity log

This is a record of what crossed between sessions. It's useful every day, not just in experiments:

• Messages: sender, recipient, text, and each state change (queued, held, delivered, refused, answered).
• Spawns: which session spawned which. Today nothing records it, so the dispatch tree can't be seen.
• Tasks: created by, claimed by, and each state change.
• Lifecycle actions one session took on another: kill, revive, archive.
• Refusals by reach.

The log is append-only, so pruning the inbox or deleting a session doesn't erase history. agent-manager log --group <g> exports JSONL. The export lists each member's tool, conversation id and working directory, since most of an agent's reasoning lives in its own transcript.

Views come after the data, and none prescribe a structure:

• a session's messages in and out, in its preview;
• the dispatch tree under a session;
• a group's timeline.

Stages

Each stage merges on its own.

1. Reach for groups and sessions, with human-only policy changes. This fixes the interruptions.
2. Coordination mode per group.
3. Activity log and its export.
4. TUI views on the log.

Interaction with other work

• SSH connections (feat: manage sessions on other machines over SSH connections #737). A message from another host arrives with no session (send --from). Treating it as the human would let it bypass every boundary. External senders should reach only open scopes.
• Multiplayer (several controllers sharing one host, a planned follow-up to feat: manage sessions on other machines over SSH connections #737). Reach is stored in the host's profile, so every controller on that host sees and enforces the same boundaries.
• Later: groups across hosts. A group that spawns its members onto SSH hosts fits refactor: restructure the UI by feature and run effects off the update path #735's boundaries, where a remote device's MCP stays device-local and control flows from the controller to the host (docs/architecture/boundaries.md:35). Members on different hosts reaching each other doesn't: each host's manager only knows its own sessions, and replies would have to flow back from host to controller. That's a stretch for this project and stays out of scope here, but nothing above should block it.

Not in scope

• Sandboxing or any security claim.
• Roles, lead agents, orchestration or workflows.
• Moving or forking sessions between hosts. That needs a separate RFC and depends on that multiplayer work.

Open questions

1. Dispatch down. Should a session be able to act on a closed subgroup inside its own scope? That suits lead/worker setups, but it's the first opinion about structure.
2. Direction. Should quiet block only incoming actions, so members can still message out, or both directions as proposed?
3. Is per-session reach needed, or is a group of one enough?
4. Reservations: list outside holders by name or not?
5. Inbox limits per scope, for experiments with many agents?
6. Mode changes: restart members' MCP servers so they apply now, or wait for the next launch?
7. Log storage and retention: a table in state.db or JSONL under the profile directory, and how large it may grow?

[YoanWai]

@ribeirojose this is absolutely needed. coordination today is a note in text that nothing enforces, and what agents do to each other leaves no trace, so both halves of this land on real pain. i want to read it properly before getting into the open questions, but it goes on our list for sure. thanks again for all the work and care you put into this!

[YoanWai]

@ribeirojose thanks for this, read it properly now. Reach is welcome as a PR, on its own and kept small. On the questions:

1. No exception. A closed subgroup is closed to its parent too. If you want to message your workers, leave their group open.
2. Incoming only. A quiet member can still message out.
3. Groups only. Not ideal, but much simpler. To quiet one session, put it in its own group.
4. Keep the names. The conflict text tells agents to message the holder, so the name has to be there.
5. No. Limits stay global. If they get in the way we change the global setting, separately.
6. I think restart them, behind a confirm dialog that says which sessions it will restart. Just a suggestion, if that gets messy, next launch is fine.
7. Skip the log for now.

Two things since you wrote it: #813 landed, so send --from with no session should reach open scopes only, as you proposed. And @subbeh is taking #924, a move over MCP, so a move needs the reach check at both ends.