Guides

Message between agentproto sessions and Claude Code or Desktop sessions

Status: Experimental

How a daemon session, a Claude Code session and a Claude Desktop chat send messages to each other, and what it takes to wake an idle Claude Code session.

Who is who

  • Daemon sessions: sess_xxxx.
  • Claude Code sessions: cc:<session_id> (rows created by the hooks, agentproto hook inbox).
  • Claude Desktop MCP entries share one unverified identity, claude-desktop.

Send a message

  • Child to its supervisor: message_parent. A supervisor that must be woken is declared at spawn with agent_start parent: "cc:<your session id>" (no attach: false, which makes the child an independent root). parent is for a caller the daemon cannot identify (Claude Code on a static MCP URL, or the shared claude-desktop identity); a call that already carries an identity attaches under it automatically. The parent is declared, not proven: same trust as replyTo.
  • Driving a child from Claude Desktop: a child spawned with parent: "cc:<id>" through the claude-desktop identity is owned by that cc: row, which a Desktop call cannot present (it arrives as claude-desktop). So the daemon records allowPromptFrom: ["claude-desktop"] on such a child by default, and agent_prompt, agent_interrupt, agent_kill, session_restart and session_continue_fresh work from the Desktop chat. Pass your own allowPromptFrom to replace it, or allowPromptFrom: [] to keep the child owner-only. Verified identities and identity-less callers get no such grant.
  • Any session to any session: message_send to: "<sess_xxxx | cc:<id>>".
  • By label: message_send to: "label:<label>" reaches the one live session carrying that operator-assigned label (operatorLabel, the one allowPromptFrom: "label:..." matches), so a brain whose session id changes at every daemon restart stays addressable. A killed or retired session never matches: no live match is no_live_session_for_label, several is ambiguous_label. The usual permission rules apply to the session it resolves to; a label never widens who you can reach.
  • Driving by label: agent_prompt, agent_interrupt and agent_kill accept sessionId (or id) as "label:<label>" too, with the same resolution (one live session whose operatorLabel matches; no_live_session_for_label, ambiguous_label). The owner gate and session:prompt / session:control grants are checked on the resolved session, so a label is a way to name the target, never a way to gain the right to drive it.
  • Naming your children: a supervisor can give a stable name to the sessions it launches with agent_set_operator_label {sessionId, operatorLabel}, so message_send to: "label:<x>" and agent_prompt / agent_interrupt / agent_kill with id: "label:<x>" reach them without tracking session ids. You may label a session you OWN: one you spawned, or a descendant of it (the same ownership as the drive gate, but a allowPromptFrom grant is not ownership). From the shared claude-desktop identity you may label a child spawned with parent: "cc:<id>" that still carries the default claude-desktop grant. You may not label yourself, nor a session you do not own, and a label already carried by another non-archived session, live or dead, is refused (the error names the holder and its status; archive the dead session to free its name). The human operator may label any session. A label on a session that has a parent is an address only: allowPromptFrom: "label:...", defaults.tasks.operatorDelegates and session-label:// grant principals match root sessions only, so labelling a child never grants it anything.
  • From Claude Desktop, say who you are: the shared claude-desktop identity has no session id, so pass declaredSender: "cc:<your session id>" to message_send. The recipient sees [declared sender: cc:<id>, unverified] and can reply to that address. It is declared, not proven (same trust as replyTo): urgency stays capped below interrupt, permissions still use the real caller, and a call that carries a session identity is refused.
  • Urgency:
UrgencyEffect
fyinever wakes
next-turnqueues behind the current turn
steerinjects into the running turn
interruptonly if the operator allows it, otherwise steer

The result of message_send and message_parent carries wake: { written, reason, hint? } when the socket wake is enabled (see below). Read it: written: true with reason: "held-by-receiver-bypass" means the message is parked, not delivered.

What wakes an idle Claude Code session

The socket wake writes a frame on /tmp/cc-socks/<pid>.sock. It is off by default: turn it on with agentproto config set daemon.claudeSocketWake true (applied on daemon restart). It only writes for next-turn, steer and interrupt; an fyi is parked in the inbox.

Claude Code accepts the frame depending on the receiver's permission mode:

Receiver modeWakes?Needs
default, acceptEdits, autoyesnothing
bypassPermissionsonly with crossSessionInbound: "accept"the setting below

Without the setting a bypass receiver holds the frame (cause no-mode-asserted: the frame carries no permission class). The daemon also parks a copy in the receiver's inbox, so it shows at the next prompt. If Claude Code later releases its held copy, the receiver may see the message twice.

Fix for bypass receivers

agentproto doctor --fix

Adds "crossSessionInbound": "accept" to ~/.claude/settings.json (backup, atomic write, other keys kept, diff printed, no-op if already set). The daemon never writes that file. Restart the receiver session if it does not wake after the change (whether a running session picks it up is not proven).

When it does not work

  1. Look at the wake object in the send result and the daemon log line [socket-wake] to= written= reason= pid= rowMode=. No wake object means the socket wake is off.
  2. agentproto doctor shows the daemon.wake check; daemon_health lists one warning per held receiver.
  3. no-registration or no-socket: the receiver is not a live Claude Code session (wrong id, or it exited). urgency: an fyi never wakes, by design.
  4. Desktop sessions: the env-var attestation cannot work (Desktop does not set CLAUDE_CODE_SESSION_ID for MCP servers); use the declared parent.

Test recipe

Start a throwaway receiver in a terminal tab (agentproto must be on PATH):

claude --permission-mode bypassPermissions "Reply READY, then wait."

Then send message_send to: "cc:<its session id>" urgency: "next-turn" and watch it answer. The session id is in ~/.claude/sessions/<pid>.json (never print the .key files).

See also

  • signals-and-wake: get woken by session lifecycle and PR signals without polling, and how signal routing picks a provider