---
name: pi-intercom
description: "Discover eligible local Pi sessions, send guidance, ask/reply, or read a peer's last completed response without waking it. Use for same-machine Pi coordination, not generic chat or unrelated remote messaging."
---

# Pi Intercom

The `intercom` tool is eager. There is no loader, separate child supervisor tool,
workflow UI, or topic registry.

1. Use `intercom({action:"list"})` before choosing a peer. It prints the main
   sessions first, then the child sessions of your group as one count line. A
   child is a valid target by name or ID without its row; `children:true` prints
   the rows. Default discovery spans projects and agent directories under the
   same OS user; optional `scope:"project"` filters to this repository and its
   worktrees, and optional `to` keeps the sessions whose name or ID contains it,
   child rows included.
2. Pick the exact displayed target. Names are not unique; resolve ambiguity rather
   than guessing. The current session is not a peer target.
3. Choose the lightest operation. The lightest is no message: do not send
   acknowledgements, thanks or receipts. Send only what the peer must act on or
   must know to avoid a mistake. When a message you receive needs no action, do
   not reply and do not restate it.
   - `send`: non-blocking guidance/corrections/blockers; default delivery steers.
     A message to an idle peer costs it a full model request. If it needs no
     action and must still be on record, use `delivery:"passive"`.
   - `last`: original last completed assistant text, without waking the peer.
   - `ask`: bounded correlated wait only when the sender must stay alive waiting.
   - `reply`: answer the active/sole pending ask, or specify `replyTo` when ambiguous.
   - `pending`: unresolved inbound asks and their correlation.
   - `status`: connection, peer health and inbound queue state.
4. Handle the actual outcome. Broker acceptance is not recipient persistence,
   model consumption, a reply, completion, or process exit. Do not replay an
   uncertain side effect merely because its response was lost.

## Topology

A main and its children form one group. Every pair inside it can communicate.
Mains can also communicate with other mains. Children cannot discover, send to,
or read a foreign group's agents—even with an exact ID. Only mains delegate;
there is one level. Cwd and agentDir do not define groups. These are coordination
rules, not a sandbox against other code running as the same OS user.

## Other devices

A main can list the main sessions on the owner's other devices:
`intercom({action:"list", device:"all"})`, or one device name. The answer has one
block per device, with rows written `name@device`, and no session of this device.
A device can also be unreachable, have no Pi session, or lack the command; its
block says which.

The name and the ID of a row are targets: `send` and `ask` with
`to:"name@device"` reach that main. Its reply to an ask comes back as the tool
result. A message from another device shows its sender as `name@device`; use
that as `to` for a message back, and `reply` for an ask. A failure says whether
the message was not sent, or whether its delivery is unknown; check the
recipient before sending an unknown one again. A default ask of a busy main is
refused: use `send`, or `delivery:"steer"`. `last` reads only the sessions of
this device.

A child cannot use `device` or a `name@device` target; its main does that. If no
devices are configured, a `device` list names the file and the keys to set.

## Delivery and paging

Default `send` steers at the next tool boundary or wakes an idle peer. Explicit
`delivery:"queue"` intentionally defers. Explicit `delivery:"passive"` never wakes;
the peer reads the message at its next turn. Use it for receipts and FYI that need
no action. Guidance the peer must act on should not be passive.

`last` returns a stable entry ID and offsets. Follow its exact next-page call to
retrieve all text; offsets are UTF-16 code units, not bytes. A read never sends a
model prompt. It does not substitute a fabricated status summary for the answer.

Keep messages compact and self-contained: objective, scope, files, authority,
stop boundary, and expected reply. Never attach secrets or unrelated private
context. Use ordinary run completion for delegated handoff, not duplicate sends.

## Recovery

If a target disappears, list again. A timeout is not a reply. Multiple pending
asks require explicit correlation. Ordinary asks do not recreate the retired
persistent supervisor question/approval workflow.

Old agent-directory brokers may coexist during migration; updated sessions use
the same-user broker. Do not kill another broker or change runtime configuration
to force discovery. Only intercom-connected eligible sessions appear, not all
open Pi processes. See [local messaging](../../docs/intercom.md) for broker and
persistence contracts.