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 withagent_start parent: "cc:<your session id>"(noattach: false, which makes the child an independent root).parentis for a caller the daemon cannot identify (Claude Code on a static MCP URL, or the sharedclaude-desktopidentity); a call that already carries an identity attaches under it automatically. The parent is declared, not proven: same trust asreplyTo. - Driving a child from Claude Desktop: a child spawned with
parent: "cc:<id>"through theclaude-desktopidentity is owned by thatcc:row, which a Desktop call cannot present (it arrives asclaude-desktop). So the daemon recordsallowPromptFrom: ["claude-desktop"]on such a child by default, andagent_prompt,agent_interrupt,agent_kill,session_restartandsession_continue_freshwork from the Desktop chat. Pass your ownallowPromptFromto replace it, orallowPromptFrom: []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 oneallowPromptFrom: "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 isno_live_session_for_label, several isambiguous_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_interruptandagent_killacceptsessionId(orid) as"label:<label>"too, with the same resolution (one live session whoseoperatorLabelmatches;no_live_session_for_label,ambiguous_label). The owner gate andsession:prompt/session:controlgrants 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}, somessage_send to: "label:<x>"andagent_prompt/agent_interrupt/agent_killwithid: "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 aallowPromptFromgrant is not ownership). From the sharedclaude-desktopidentity you may label a child spawned withparent: "cc:<id>"that still carries the defaultclaude-desktopgrant. 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.operatorDelegatesandsession-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-desktopidentity has no session id, so passdeclaredSender: "cc:<your session id>"tomessage_send. The recipient sees[declared sender: cc:<id>, unverified]and can reply to that address. It is declared, not proven (same trust asreplyTo): urgency stays capped belowinterrupt, permissions still use the real caller, and a call that carries a session identity is refused. - Urgency:
| Urgency | Effect |
|---|---|
fyi | never wakes |
next-turn | queues behind the current turn |
steer | injects into the running turn |
interrupt | only 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 mode | Wakes? | Needs |
|---|---|---|
| default, acceptEdits, auto | yes | nothing |
| bypassPermissions | only 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 --fixAdds "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
- Look at the
wakeobject in the send result and the daemon log line[socket-wake] to= written= reason= pid= rowMode=. Nowakeobject means the socket wake is off. agentproto doctorshows thedaemon.wakecheck;daemon_healthlists one warning per held receiver.no-registrationorno-socket: the receiver is not a live Claude Code session (wrong id, or it exited).urgency: anfyinever wakes, by design.- Desktop sessions: the env-var attestation cannot work (Desktop does not set
CLAUDE_CODE_SESSION_IDfor 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
Find out why your daemon looks big
Your Activity Monitor (or top, or ps) shows the agentproto daemon using more memory than you expected.
Get woken by signals (sessions ending, PRs, CI) without polling
How a supervisor session (a daemon session, a Claude Code session, a Claude Desktop chat) declares once what it cares about and lets the daemon wake it, instead of polling session_list or gh pr…