Session messaging
Sessions that hand work to each other with @ — how the picker is scoped, why mode parity blocks some sends, and what the inbound gate does.
A session can send work to another session. Type @ in the composer and pick one — the agent that just finished a migration can ask the agent that owns the tests to check it, without you carrying the message between two windows.
What the @ picker lists
Other Claude sessions on the same machine, including ones you started yourself in a terminal outside Foreman. They're read from the CLI's own registry, so anything running locally is reachable whether or not Foreman launched it.
Peer messaging runs over a unix socket, so it is same-machine by construction. A session on a remote node in your fleet cannot be reached this way and is deliberately not listed — offering it would produce a send that silently goes nowhere.
Mode parity, and why a message might not arrive
A peer message auto-delivers only when sender and receiver have matching permission postures: bypass to bypass, or prompting to prompting. A prompting session cannot hand work to a bypass session and have it run unattended.
This is Anthropic's mitigation, not ours, and it is guarding something real — without it, a session that had been denied permission for something could simply ask a more permissive session to do it instead. Foreman honours the rule rather than working around it.
The inbound gate
Each session has an explicit gate for incoming peer messages:
- accept — deliver messages straight through.
- hold — park the message and tell the sender.
- refuse — reject them.
Leaving it unset is a real choice, not a missing one: unset means the CLI's mode-parity rule applies, which is the safe default. Foreman never sets accept for you in bulk. A value here only ever comes from you choosing it for one session.
The hold caveat
hold promises less than it sounds like in Foreman's sessions. The CLI's approve/deny surface for a held message is its own interactive TUI — and Foreman runs sessions headlessly. A held message therefore parks in the receiving process's memory where nothing in Foreman can release it, and it expires on its own after a few minutes.
We kept the option because "park it and tell the sender" is still a coherent posture, but the UI says this plainly rather than showing you an approve button that cannot work. If you want messages to actually arrive, use accept.
How a peer message appears
A peer's words are kept structurally separate from your own input, and rendered as a message from that session rather than as something you typed. That separation is deliberate: it means a peer cannot dress its content up as instructions from you.
Practical uses
- Specialist hand-off. One session owns the migration, another owns the test suite. Each keeps its own context instead of one session accumulating both.
- A second opinion. Ask a session that has been nowhere near the change to review it. It has no investment in the approach it is checking.
- Long-running coordination. A session waiting on something slow can nudge another when it finishes, rather than you noticing twenty minutes later.
The thing it is not: a way to build an autonomous swarm. Every session still runs under its own permission posture, and mode parity means you cannot escalate one session's authority by routing through another.