The short answer, up top. As of Claude Code v2.1.224 (August 7, 2026), a running Claude Code session can message another running session — on the same machine or any of your machines — using a SendMessage tool, and discover reachable peers with ListAgents. It's on macOS and Linux. Two settings gate delivery (crossSessionInbound, dialogExpiry), and the safety rule is simple: a message to a session running with bypassed permissions is held for your approval; a message to a normally-permissioned session auto-delivers.
That's the feature. The more useful question is when to use it — because it overlaps, but does not replace, the subagent you already reach for.
Peers, not children#
The mental model that keeps you from misusing this: cross-session messaging is between peers, subagents are children.
- A subagent is a worker you create. You hand it a task, it runs in its own context, and it returns a result into yours. Then it's gone. That's the Agent/Task pattern — a disposable worker whose whole existence is answering your one question.
- A peer session is an independent session that's already running its own work, with its own context and its own permissions. Cross-session
SendMessagelets you talk to it while both stay alive.
So the decision is about lifetime and ownership. If you want a throwaway that returns an answer, spawn a subagent — and note this same release removed the old 200-subagent-per-session cap, so a long-running session no longer refuses to spawn new ones. If you have two ongoing sessions that need to coordinate — hand off, notify, or ask each other something live — that's what cross-session messaging is for.
How discovery and delivery work#
ListAgents is the directory. A session calls it to see which other sessions are reachable — including ones on your other machines — and then addresses a message to one of them with SendMessage. Because it spans machines, the natural shape is a session on the box running a long build or test suite pinging the session (maybe on your laptop) that will act on the result, without either one having to hold the other's context in its own window.
Delivery is gated by two new settings:
| Setting | What it controls |
|---|---|
crossSessionInbound | Whether this session accepts incoming messages from other sessions at all. |
dialogExpiry | How long a held approval prompt stays open before it lapses. |
And the rule underneath them, worth reading twice: **a cross-session message sent to a session running with bypassed permissions is held for your approval; messages to other (normally-permissioned) sessions auto-deliver.** The reasoning is defensible — a bypassed-permission session would otherwise act on an incoming instruction with no human checkpoint, which is exactly the case you want a gate on. There's already an open discussion about a "trusted peers" mode to relax the per-message prompt for sessions you've explicitly trusted; if you use the desktop app, its session-management tool has its own confirmation prompt to account for separately.
A quick coordination pattern#
The clearest win is a watcher → actor handoff across contexts that shouldn't be merged:
- Session A runs on your CI/build host, watching a long job you don't want clogging your main window.
- Session B — your working session — calls
ListAgents, finds A, and asks it to report when the build settles. - When the job finishes, A uses
SendMessageto ping B with the outcome. B acts on it in its own clean context.
You could do this with shared files or a subagent, and for a durable, auditable handoff a file on disk is still the right tool. Cross-session messaging earns its place when the handoff is live and two-way and you'd rather not fold one session's long-running context into the other's.
The rest of v2.1.224, briefly#
Cross-session messaging shipped alongside self-hosted environments — the two headline features of the release — plus three quieter ones worth a line each:
- 200-subagent cap removed. Long-running sessions no longer refuse new agents; concurrency and depth limits still apply.
archiveplugin source. Install plugins from a zip over HTTPS without git or npm, with optional SHA-256 pinning — a supply-chain nicety for locked-down environments.- JWT-aware credential masking. Sandbox masking gained
decode: "jwt"withmaskClaims, plus AWS SigV4 re-signing, for structured secrets that a naive string mask would leak.
If your team is standardizing on how it runs multiple agents at once, cross-session messaging is a new primitive to fold into that decision — read it next to our parallel coding-agent runner guide, which covers the terminal-vs-desktop-vs-web trade-off it now sits on top of.
