[FEATURE] native session-to-session (agent-to-agent) communication

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Body:

Summary

Add a first-class primitive for communication between concurrent Claude Code sessions on the same machine (and ideally across machines). Today there is no
built-in way for two live sessions to exchange messages, so users hand-roll fragile workarounds.

Background / current workaround

We run multiple Claude Code sessions in parallel with distinct roles — e.g. a designer session and a tool-builder session — that need to hand work back and
forth (bug handoffs, "this is ready," "I need X to proceed"). With no native mechanism, we built a local file-based "post office":

• Each session has an identity (role@workspace).
• Messages are markdown files in a shared dir, addressed and consume-once.
• Durable "threads" hold multi-step workstream context; messages carry a thread: pointer.
• Each session self-polls its mailbox on idle ticks via a recurring cron (/3 *).

It works, but it's a workaround with real limitations (below).

Problems with the workaround

• Poll-based, not push. A message only surfaces when the recipient session is both alive and idle. Latency is bounded by the poll interval; a busy or closed

session never sees it.

• No delivery guarantee / no presence. A sender can't tell which sessions are live, or whether a message was received.
• Lifecycle fragility. Polls are session-only crons — they die silently when a session closes, so scheduled watchers/pollers vanish without notice.
• cwd/project coupling. Identity inference and tooling depend on the launch directory; coordinating sessions started in different projects is awkward.
• Noise & cost. Idle-tick polling spends turns just to check an empty mailbox.

Requested capability

A native inter-session messaging primitive:

• Addressing by session identity (role/workspace), plus role-broadcast and global-broadcast.
• Push/notify delivery — surface an inbound message on the recipient's next turn, no polling.
• Presence — a session can query which other sessions are currently live.
• Optional durable threads for multi-step workstreams (message = trigger, thread = logbook).
• Location-independent — works regardless of each session's cwd/project; ideally across machines.
• Delivery/read status visible to the sender.

Why it matters

Multi-agent / multi-session workflows are increasingly common — a design agent routing tool bugs to a dev agent, parallel research agents coordinating,
orchestrator/worker patterns. The file-mailbox workaround doesn't scale, doesn't reliably deliver, and forces users to reinvent messaging infrastructure. A
native primitive would make robust multi-session collaboration a supported first-class pattern.

Example flow

Two sessions, run by one user in separate terminals:

• Session A — designer@projX (doing circuit/design work)
• Session B — dev@tools (maintaining the internal tool stack)

1. Designer hits a tool bug and hands it off (Session A):

▎ User: "The extract tool crashes on multi-rank netlists — hand this to the dev session."
▎
▎ Claude A creates a durable thread thread-extract-multirank-crash with repro steps, then sends dev@tools a short message pointing to it. (Today: writes two
▎ files + relies on B's poll. Desired: pushed to B, with delivery confirmation back to A.)

1. Dev session is notified and picks it up (Session B):

▎ On B's next turn, the inbound message surfaces automatically (no polling): "HANDOFF — thread-extract-multirank-crash: repro + expected/observed inside."
▎ Claude B reads the thread, reproduces, fixes, adds a test.

1. Dev reports back (Session B → A):

▎ Claude B replies: "DONE — thread-extract-multirank-crash: fixed in commit abc123, added regression test." This surfaces on A's next turn.

1. Designer resumes (Session A):

▎ Claude A sees the DONE, re-runs the failing case to confirm, and continues the design work — the thread carries the full history for either session to resume
▎ later.

What the native primitive removes from this flow: no shared mailbox dir, no consume-once file bookkeeping, no per-session polling cron (and no silent loss when
a session closes), no cwd-dependent identity guessing. Just addressed, pushed, acknowledged messages between live sessions, with optional threads for the
durable workstream.

Proposed Solution

A native inter-session messaging primitive:

• Addressing by session identity (role/workspace), plus role-broadcast and global-broadcast.
• Push/notify delivery — surface an inbound message on the recipient's next turn, no polling.
• Presence — a session can query which other sessions are currently live.
• Optional durable threads for multi-step workstreams (message = trigger, thread = logbook).
• Location-independent — works regardless of each session's cwd/project; ideally across machines.
• Delivery/read status visible to the sender.

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

Example flow

Two sessions, run by one user in separate terminals:

• Session A — designer@projX (doing circuit/design work)
• Session B — dev@tools (maintaining the internal tool stack)

1. Designer hits a tool bug and hands it off (Session A):

▎ User: "The extract tool crashes on multi-rank netlists — hand this to the dev session."
▎
▎ Claude A creates a durable thread thread-extract-multirank-crash with repro steps, then sends dev@tools a short message pointing to it. (Today: writes two
▎ files + relies on B's poll. Desired: pushed to B, with delivery confirmation back to A.)

1. Dev session is notified and picks it up (Session B):

▎ On B's next turn, the inbound message surfaces automatically (no polling): "HANDOFF — thread-extract-multirank-crash: repro + expected/observed inside."
▎ Claude B reads the thread, reproduces, fixes, adds a test.

1. Dev reports back (Session B → A):

▎ Claude B replies: "DONE — thread-extract-multirank-crash: fixed in commit abc123, added regression test." This surfaces on A's next turn.

1. Designer resumes (Session A):

▎ Claude A sees the DONE, re-runs the failing case to confirm, and continues the design work — the thread carries the full history for either session to resume
▎ later.