@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/docs/intercom.md

@@ -0,0 +1,581 @@
+# Intercom
+
+Direct 1:1 messaging between pi sessions on the same machine. Send context, findings, or requests from one session to another — whether you're driving the conversation or letting agents coordinate.
+
+```text
+Your agents: Option+Shift+M (Alt+Shift+M) or /agents. Other peers: /intercom [all]. Quiet current state: /intercom topics.
+```
+
+## Why
+
+Sometimes you're running multiple pi sessions — one researching, one executing, one reviewing. Pi-intercom lets you:
+
+- **User-driven orchestration** — Send context or findings from your research session to your execution session
+- **Agent collaboration** — An agent can reach out to another session when it needs help or wants to share results
+- **Session awareness** — See what other pi sessions are running and their current status
+
+Unlike pi-messenger (a shared chat room for multi-agent swarms), pi-intercom is for targeted 1:1 communication where you pick the recipient.
+
+Intercom is bundled with `pi-subagents`: delegated child agents get a child-only `contact_supervisor` tool when the subagent extension supplies bridge metadata. Use blocking `need_decision` or `interview_request` only when the ephemeral child cannot safely continue and must remain alive for the reply. Use `progress_update` only for a discovery or change the supervisor needs while working. It steers at the next tool boundary; skip starts, redundant narration, and routine completion, and retain material findings in the final result. Fresh normal sessions see `load_intercom`, a small entry that enables the full `intercom` tool without sending or checking anything.
+
+The broker, presence, receipts and keyboard UI stay active while the model schema is hidden. Call `load_intercom({})` for explicit peer checks, messaging or topics. Actionable peer inbound and recovered reply obligations enable `intercom` before model delivery; mere presence, passive breadcrumbs, routine synthetic child notices, and human-origin messages answered in chat do not. Managed-child `contact_supervisor` remains eager. If an explicit tool policy permits only `intercom` without its loader, it stays eager; excluded tools never reactivate. Selection follows native session/branch declarations and stays stable between turns.
+
+## In One Minute
+
+Each Pi session with the bundled intercom extension loaded connects to a tiny local broker over a local IPC transport. The broker keeps track of connected sessions and routes direct messages to the one you target by name or session ID. The extension gives you both a tool (`intercom`) and a small peer overlay (`/intercom`); Option+Shift+M (Alt+Shift+M) toggles owned agent conversations when `pi-subagents` is loaded. Messages that do not request a reply default to steer: they wake idle recipients and reach active recipients after the current tool call. Important steers release portable subagent waits without stopping the owner or child. Background calls return immediate receipts, with completion delivered later as a separate wake-up message. Foreground waits return saved results or durable questions and release for important Intercom attention without stopping existing work. Explicit queue waits behind active work, and passive delivery is a discouraged opt-in for human-visible breadcrumbs only. Quiet topic state uses native custom entries outside model context, not passive messages.
+
+## Install
+
+Intercom requires Pi **1.0.0** and Node **24.21.0** or later. No Pi fork is required.
+
+```bash
+pi install npm:@fitchmultz/pi-subagents
+```
+
+**The unscoped npm package `pi-subagents` is not this project.** Use `@fitchmultz/pi-subagents`.
+
+Git fallback (existing tags and branches remain installable):
+
+```bash
+pi install git:github.com/fitchmultz/pi-subagents
+```
+
+That one package includes both extension entries and both skills. For a local checkout, follow the [runtime-only install and rebuild recipe](../README.md#installation): run `npm install --omit=dev` before registering or loading it, including after development validation. Before rebuilding or updating an in-use Pi checkout or extension, checkpoint work and fully quit every Pi session using that installation. Update from a separate terminal, then restart Pi and resume the same saved parent session to retain ownership and pending coordination. `/reload` refreshes supported settings, skills, and prompts but is not a reliable code-update boundary.
+
+To restart the shared broker too, close every Pi session using the same agent directory and wait at least five seconds before reopening Pi.
+
+## Development
+
+Follow the [local validation instructions](../README.md#local-validation). Keep retained/cleared custom-queue, rejected-input and pre-admission preparation regressions intact and report results for the exact selected host; earlier published Pi 0.87.1 failures are historical evidence, not current 1.0 certification.
+
+`ci` runs typechecking, package and install smokes, and the full subagent/intercom test suite. The native intercom regression uses real SDK sessions, a controlled provider, and private runtime directories without credentials or model-service calls. To run just that regression:
+
+```bash
+PI_INTERCOM_TEST_SDK=/path/to/pi/packages/coding-agent node --test test/integration/pi-intercom-native-replay.test.ts
+```
+
+The real-Pi smoke installs the single checkout into an isolated temporary Pi home, verifies `pi list`, and loads both bundled extension entries. Use direct `node` with the intended CLI first on `PATH`:
+
+```bash
+export PATH="$PWD/node_modules/.bin:$PATH"
+node scripts/real-pi-smoke.mjs
+PI_REAL_SMOKE_MODEL=openai/gpt-6-astra node scripts/real-pi-smoke.mjs --llm
+```
+
+The `--llm` mode copies local `auth.json` and `models.json` into the isolated Pi agent dir. Set `PI_REAL_SMOKE_AUTH_AGENT_DIR` if your auth files are not in `~/.pi/agent`.
+
+Pi-intercom automatically gives ordinary agents a bounded presence hint when another connected session is working in the same Git repository, including separate worktrees. The hint is a constant count-free string; agents load `load_intercom({})` if needed, then use `intercom({ action: "list" })` before changing shared state or coordinating known overlapping work. Routine standalone read-only tasks do not need a peer check. No message is sent automatically. This guidance applies on official Pi and the fork; broker presence, delivery, approvals, and child recovery are unchanged. Both the tool and `/intercom` overlay default to that repository/worktree scope. Use `intercom({ action: "list", scope: "all" })` or `/intercom all` only when intentionally discovering sessions in other projects. Managed `pi-subagents` children keep their dedicated supervisor channel instead of receiving the peer hint. Project matching is an advisory presence signal, not an authorization boundary. Add project instructions only when you want a stricter mandatory coordination policy.
+
+A session becomes intercom-connected when all of these are true:
+- the bundled intercom extension is enabled through `pi config`
+- the session has been restarted after the extension was installed or updated
+- the local broker is running or can be auto-started
+
+The session list only shows intercom-connected sessions, not every open Pi process on the machine. Reconnecting the same Pi session reuses a stable broker identity, so transient broker or extension restarts do not create a second logical sender.
+
+If a session is unnamed, pi-intercom now exposes a runtime-only fallback alias like `subagent-chat-1a2b3c4d` so other sessions can still target it. That alias is not persisted as the Pi session title, so `pi --resume` can keep showing the transcript snippet instead of a generic `session-...` name.
+
+## Quick Start
+
+### From the Keyboard
+
+With `pi-subagents`, **Option+Shift+M** (**Alt+Shift+M**) opens your task-labelled agent conversations first; press it again to close. The shortcut is configurable below. In native fullscreen mode, clicking the **Agents** entrance again also closes the open view. See [the agent-view controls](../README.md#try-this-first) for direct human messaging, context replies, saved drafts, unread history, pinning, selected-child stop and explicit continuation. The plain `/intercom` command remains the current-project peer list. Type `/intercom all` to include sessions in other projects:
+
+1. **Select a session** — Use arrow keys to pick a target session
+2. **Compose message** — Write your message in the compose overlay. Pasted multiline handoffs are preserved.
+3. **Choose mode** — Press Tab to toggle between Send and Request Reply mode. Request Reply marks the message as needing a reply and adds the recipient reply hint; the overlay itself does not wait for or collect that reply.
+4. **Send** — Press Enter to send, Escape to cancel
+
+### Quiet topics and resource owners
+
+Subscribe explicitly to an exact topic; there are no automatic subscriptions or wildcard broadcasts. Topics span connected local sessions, so use a project/resource-specific name unless cross-project coordination is intended. Publications are self-contained latest state, not deltas. Each sender has one current record per topic; older queued versions cannot replace a newer record. Same-session subscriptions, publications and received records use native session entries. Late subscribers read current published state without replaying earlier interruptions.
+
+```typescript
+intercom({ action: "subscribe", topic: "browser/shared-profile/tab-4", awaitRelease: true })
+intercom({ action: "publish", topic: "browser/shared-profile/tab-4", resource: "tab-4", ownership: "held", message: "Reviewing the sign-in flow; keep this tab open." })
+intercom({ action: "topics", topic: "browser/shared-profile/tab-4" })
+intercom({ action: "publish", topic: "browser/shared-profile/tab-4", event: "release", resource: "tab-4", ownership: "released", message: "Sign-in check complete; this tab is available." })
+intercom({ action: "unsubscribe", topic: "browser/shared-profile/tab-4" })
+```
+
+Routine `event: "update"` publications replace quiet inspectable state; they do not become passive conversation messages or wake a model. Inspect current records and declared resource ownership in **`/intercom topics`** or `intercom({ action: "topics" })`; topic state does not appear in the footer. Ownership is advisory, not an exclusive lock; disconnect means **unavailable/disconnected**, never an implied release.
+
+`event: "blocker"` and `event: "decision"` steer subscribed sessions. An explicit `event: "release"` interrupts only subscriptions with `awaitRelease: true`; other subscribers get the quiet record. Direct messages, answers and stop acknowledgements bypass topic subscriptions. Keep routine status and browser handoff prose here rather than repeatedly sending it into conversations. The native raw entries remain available as history, but old topic records are not replayed as new work.
+
+Topics require an updated broker. If an older broker is still serving open sessions, topic actions report that they are unavailable; ordinary messaging and active work stay untouched. Let those sessions close normally. Once the old broker exits, reconnect with the updated package and retry. No broker or active session is stopped or restarted to enable topics.
+
+### From the Agent
+
+The agent can list sessions and send messages using the `intercom` tool. Tool calls and results render as compact transcript rows so send/ask/reply flows are easy to scan. Successful `list` results show only the session count by default in the TUI; press Ctrl+O (or the configured tool-expansion key) to show the full list. For common patterns like planner-worker delegation, the bundled `pi-intercom` skill provides copy-paste ready examples:
+
+```typescript
+// Enable the peer tool if it is not already available
+load_intercom({})
+// List connected sessions in this repository and its worktrees
+intercom({ action: "list" })
+// → **Current session:**
+// → • executor (20d43841) — ~/projects/api (claude-sonnet-4) [self, idle, state:idle, accepts_asks:true, pending_asks:0, last_intercom_activity:none]
+// →   ↳ self target unavailable; choose a peer from Other sessions; use pending/reply for inbound asks
+// → **Other sessions:**
+// → • research (6332faab) — ~/projects/api (claude-sonnet-4) [same cwd, thinking, state:busy, accepts_asks:false, pending_asks:1, last_intercom_activity:2m ago]
+// →   ↳ send defaults to steer; ask only if sender must stay alive for a required reply (default sends without waiting when peer is busy); queue only for intentional delay; passive discouraged
+
+// Intentionally discover sessions in other projects
+intercom({ action: "list", scope: "all" })
+
+// Send live guidance without blocking this long-lived session; send defaults to steer
+intercom({ action: "send", to: "research", message: "Check if UserService.validate() handles null. Send the finding back." })
+// → Message sent to research. This session can end its turn or continue independent work.
+
+// Check connection status and the same live recipient guidance
+intercom({ action: "status" })
+// → Connected: Yes, Session ID: abc123, Active sessions: 3
+// → Current session and other-session rows follow.
+
+// Send with attachments (code snippets, files, or context)
+intercom({
+  action: "send",
+  to: "worker",
+  message: "Here's the fix:",
+  attachments: [{
+    type: "snippet",
+    name: "auth.ts",
+    language: "typescript",
+    content: "function validate(user: User) { ... }"
+  }]
+})
+```
+
+### Receiving Messages
+
+With native [compact view](../README.md#compact-view) enabled, ordinary incoming messages use one content row plus Pi's blank line. In native fullscreen mode, click a collapsed row to reveal its full message and attachments; click it again to collapse. Ctrl+O (or the configured tool-expansion key) still expands all messages. Questions, reply guidance, and needs-attention notices stay prominent. The mode defaults off and does not change delivery or model-visible content.
+
+When a message arrives, it appears inline in your chat with the sender's info. The cwd label is the sender's **Native session cwd**, not proof of a command's physical directory. Messages sent with `ask` include a reply hint:
+
+```
+**From research** (Native session cwd: ~/projects/api)
+
+To reply, use the intercom tool: intercom({ action: "reply", message: "..." })
+
+Found the issue — UserService.validate() doesn't check for null input.
+See auth.ts:142-156.
+```
+
+The reply hint (enabled by default) points to `intercom({ action: "reply", ... })`, so recipients do not need raw sender or `replyTo` IDs. `send` and `reply` default to steer: they wake an idle recipient or reach a busy recipient at the next tool boundary.
+
+If Esc clears a steered or follow-up message before native handoff, it is re-delivered after the actual agent run settles. Messages already in Pi's session history are not reinserted, even after compaction or reload; messages still in Pi's native queues remain there for its next continuation or prompt. Pi 1.0's turn-boundary pending messages expose the next queued batch, not the whole custom queue; its coarse `hasPendingMessages()` reports only UI text queues. An empty boundary proves all queues cleared, while a nonempty boundary retains admitted messages until their actual history receipts arrive. Selectively removing individual custom items while other queue items remain is not observable through these public APIs: such items remain pending rather than risk a duplicate. Full queue clearing, retained-queue abort, reload and fresh-process recovery are supported. A rejected overlapping prompt does not start receiver retries while the original run is active.
+
+Official Pi 1.0 runs user preparation hooks before marking a prompt busy. During that pre-admission window, an incoming custom message can legitimately start a separate model request; custom-triggered runs do not run `before_agent_start`. Both inputs and their receipts are preserved, but one combined request is not guaranteed. Intercom does not reserve rejected input or emulate a core admission hook. Reload also does not cancel active work: abort explicitly when cancellation is intended.
+
+An omitted `ask` still honors recipient availability; use explicit steer only when the sender must remain alive for a busy recipient's reply. The recipient should incorporate relevant context and continue its active task unless the message explicitly replaces it. Use `delivery:"queue"` only when delay is intentional; `queueMode:"replace"` keeps only the latest undelivered thread update.
+
+Old queued subagent progress is discarded from pending delivery when its exact generated thread and sender match a proven finished child. Its original checkpoint stays in saved history, but it does not trigger another turn or late notification. Actual final results remain available as completed work. The association survives reload; detached siblings, live successors, unmatched peers, questions, answers, and unrelated explicit queues are unchanged.
+
+Pending delivery is checkpointed in the saved Pi session before native handoff. Reloading, or resuming that same saved session in a fresh process, restores undelivered messages, including lost native queues, and the latest unsuperseded milestones once; a fork or new session does not adopt them. Resuming again does not replay consumed messages, and passive-only recovery does not start a model turn. Accepted pending messages have no fixed-count backlog cap or age-based expiry. Ordinary peer asks still use the configured reply timeout. Attachment content is included in the agent-visible body and stored in Pi session history. Only passive `send` renders without waking the recipient model.
+
+## Workflow: Planner-Worker Coordination
+
+The most natural use of pi-intercom is splitting a task between two sessions — one holds the big picture, the other does the hands-on work. When the worker hits an ambiguity, it steers the planner without losing context or blocking its long-lived session.
+
+### Setup
+
+Open two terminals and start pi in each. Name them so they can find each other:
+
+```
+# Terminal 1                    # Terminal 2
+/name planner                   /name worker
+```
+
+Verify they see each other from either session:
+
+```typescript
+intercom({ action: "list" })
+// → • worker — ~/projects/api (claude-sonnet-4) [idle]
+```
+
+### The Conversation
+
+Long-lived Pi sessions normally coordinate without blocking each other. The sender uses `send`, which steers by default, and ends its turn or continues independent work. The recipient sees the message at its next tool boundary, incorporates relevant context, continues the active task, and sends any answer back with steer. A steer supplements the task unless it explicitly says to replace it.
+
+**Planner delegates work:**
+```typescript
+intercom({
+  action: "send",
+  to: "worker",
+  delivery: "steer",
+  message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts, src/api/types.ts."
+})
+```
+
+**Worker steers a live discovery without holding its process open:**
+```typescript
+intercom({
+  action: "send",
+  to: "planner",
+  delivery: "steer",
+  message: "Blocked: should retry apply only to idempotent endpoints? Send the decision back with steer."
+})
+// Worker ends its turn instead of polling or waiting.
+```
+
+**Planner answers while preserving the worker's active task:**
+```typescript
+intercom({
+  action: "send",
+  to: "worker",
+  delivery: "steer",
+  message: "Apply retries only to GET/PUT/DELETE. Max 3, exponential backoff from 100ms. Continue the current task."
+})
+```
+
+**Worker reports completion:**
+```typescript
+intercom({
+  action: "send",
+  to: "planner",
+  delivery: "steer",
+  message: "Task-3 done. Added RetryPolicy, applied it to GET/PUT/DELETE, surfaced NetworkError, and passed 4 tests."
+})
+```
+
+### Communication Patterns
+
+| Pattern | Action | Why |
+|---------|--------|-----|
+| **Task Delegation** | `send` + steer | Wakes an idle worker or reaches a busy worker at the next tool boundary without blocking the planner. |
+| **Guidance / Answer** | `send` + steer | Makes relevant context available during active work. |
+| **Clarification / Blocker** | `send` + steer | Long-lived peers can end their turn and wake when the answer arrives. |
+| **Intentional Deferral** | `send` + queue | The recipient should not incorporate the note until after active work. |
+| **Ephemeral Blocking Wait** | `ask` + steer | Keeps a short-lived process alive only when it cannot safely continue without the reply. |
+
+### Blocking Ask Exception
+
+Use `ask` only when the sender process must remain alive and cannot safely continue without the answer, such as an ephemeral dispatched subagent. Pass `delivery:"steer"` so the question reaches a busy recipient at its next tool boundary. The recipient answers with `intercom({ action: "reply", message: "..." })`; `pending` recovers unresolved asks when needed.
+
+### `send` vs `ask`
+
+`send` is the default for agent-to-agent coordination and uses steer when `delivery` is omitted. It wakes idle recipients or reaches busy recipients at the next tool boundary, then returns after broker acceptance. Use explicit queue only when delay is intentional, and passive only for human-visible breadcrumbs. If you want approval before non-reply sends, set `confirmSend: true`.
+
+`ask` sends and waits up to `askTimeoutMs` (default 2 minutes). Reserve `ask` plus steer for a sender process that must remain alive and cannot safely continue without the answer. Long-lived peers should use `send` plus steer and end their turn instead. A default ask to a peer publishing `accepts_asks:false` returns promptly with `reason:"peer_busy"`; an explicit steer ask keeps waiting.
+
+`reply` answers an inbound ask using its exact sender and message automatically. Otherwise, answer ordinary coordination with `send` plus steer. If multiple asks are pending, use `pending` and disambiguate with `to`.
+
+Inbound steers are supplemental coordination inside the active task. Incorporate relevant context and continue; replace the task only when the message explicitly instructs replacement.
+
+## Workflow: Subagent-to-Supervisor Escalation
+
+When this package spawns a Pi-backed delegated child, it supplies bridge metadata that gives the child a subagent-only `contact_supervisor` tool in addition to the regular `intercom` tool. Normal sessions never see `contact_supervisor`; non-Pi child backends such as Claude Code do not load this tool.
+
+### When the Tool Appears
+
+`contact_supervisor` only registers when `pi-subagents` sets all of these environment variables:
+
+- `PI_SUBAGENT_ORCHESTRATOR_TARGET` — the supervisor session name or ID
+- `PI_SUBAGENT_RUN_ID` — the run identifier
+- `PI_SUBAGENT_CHILD_AGENT` — the agent type
+- `PI_SUBAGENT_CHILD_INDEX` — the child index within the run
+
+If any are missing, the session falls back to the regular `intercom` tool. A subagent status line may mention an intercom target before the child is actually registered with pi-intercom; treat `intercom({ action: "list" })` as the source of truth. If the advertised target is absent from `list`, use normal subagent controls (`status`, `resume`, `nudge`, result artifacts) instead of sending to that target; the child may be Claude Code-backed or already exited and have no child-side `contact_supervisor`.
+
+When both bundled extension entries are enabled, parent sessions can use `agent_runs({ action: "nudge", id: "<run-id>", message: "..." })` to send a non-blocking steered nudge to a live child. If the run has already finished, nudge returns its terminal outcome and evidence without restarting it. `agent_runs({ action: "list" })` includes this parent's active and completed durable runs across working directories, plus recoverable legacy foreground and background records. `agent_runs` inspection may also show the direct blocking `intercom({ action: "ask", to: "...", delivery: "steer", message: "..." })` path; use that exception only when the parent process must remain alive and cannot safely continue without the reply. `pi-intercom` remains the source of truth for connected sessions and only delivers to registered local peers.
+
+### Three Reasons
+
+| Reason | Behavior | Use When |
+|--------|----------|----------|
+| `need_decision` | Persists the question, steers the supervisor, and waits without the ordinary ask timeout | The ephemeral child cannot safely continue without one decision, approval, or product/API/scope clarification |
+| `interview_request` | Persists structured questions and waits without the ordinary ask timeout | The ephemeral child cannot safely continue until it receives multiple structured answers |
+| `progress_update` | Non-blocking steer at the next tool boundary | A discovery or change the supervisor needs while working |
+
+Do not use `contact_supervisor` for routine completion handoffs. Return the final subagent result normally through `pi-subagents`.
+
+Intercom provides live coordination and portable background completion notices. Every new subagent run has one detached owner, regardless of whether the parent waits or receives a background receipt. Waiting tools receive their saved result directly; the watcher suppresses an extra Intercom completion notice. See [host capabilities and result delivery](../README.md#host-capabilities-and-result-delivery).
+
+Durable output lives in `pi-subagents` result details and artifact/output paths (`savedOutputPath`, `artifactPaths`, or explicit workspace `output` files). Completion notices include existing saved result and metadata paths, including acceptance details when configured. Use those files as the source of truth for long reports. Broker acceptance, notification delivery, parent review, and runtime acceptance are separate facts.
+
+### Recovering a supervisor question
+
+`need_decision` and `interview_request` save the question before notification. Supervisor or broker disconnection does not end the wait. Resume the same saved supervisor session and use:
+
+```typescript
+agent_runs({ action: "questions" })
+agent_runs({ action: "answer", id: "<run-id>", questionId: "<question-id>", message: "Use the stable API." })
+agent_runs({ action: "stop", id: "<run-id>" })
+```
+
+The full `subagent` tool also accepts `questions` and `answer`; its stop action is `interrupt`. Questions expose `awaiting_input`, `answer_pending`, `answered`, or `cancelled` independently of run completion. Ownership follows the saved supervisor session, not its cwd or display name. The live intercom reply path saves the same answer. Saving an answer or cancelling through run controls also clears the matching live intercom pending ask; a nudge does not resolve a question.
+
+Question lists page 20 summaries by default, unresolved first. Use `limit: 1–100`, then pass `details.questionList.nextOffset` as `offset`; `id`, `index` and `questionId` narrow the lookup. Summaries retain identity, state, delivery and revival evidence without copying the saved launch or attempt baseline. Previews stop at 2,048 characters. Read `questionPath` for the complete question/interview/contract and `answerPath` for the exact saved answer; never retry an answer using a truncated preview. Browsing does not modify these durable files.
+
+Needs-attention notices for a matching unresolved question say **Waiting for supervisor input** and include the question ID and answer call. `answer_pending` still means delivery is unconfirmed, not that the child resumed. A live waiter consumes the durable answer. If it exited, answering revives its saved Pi session with the original acceptance contract and a new run ID. Identical repeated answers do not launch duplicate work; conflicting answers leave the original intact. `stop` cancels the question and aborts any live waiter. An interrupted pre-launch revival can be recovered with the exact `continue` call shown in the answer receipt; ambiguous launch evidence is not silently retried.
+
+Questions, saved launch contracts, and canonical version-2 run status/results live under `${PI_CODING_AGENT_DIR:-~/.pi/agent}/sessions/subagent-runs`, separate from disposable temporary files. Pending records are not age-cleaned. Active legacy owners keep their original runtime and files until they finish; recovery preserves available evidence for the same saved owner without replaying work or deleting history. Ordinary peer asks still use `askTimeoutMs` and are not durable supervisor questions.
+
+### Example: Blocked Subagent Asks for Guidance
+
+```typescript
+contact_supervisor({
+  reason: "need_decision",
+  message: "The auth service returns 403 instead of 401 for expired tokens. Should I treat 403 as a re-auth trigger or a hard failure?"
+})
+// → Reply from supervisor: Treat 403 as re-auth trigger. Update the token refresh logic.
+```
+
+### Example: Structured Supervisor Interview
+
+```typescript
+contact_supervisor({
+  reason: "interview_request",
+  message: "Please answer these before I continue the migration.",
+  interview: {
+    title: "API migration choices",
+    questions: [
+      { id: "api", type: "single", question: "Which API should I target?", options: ["Stable API", "Experimental API"] },
+      { id: "constraints", type: "text", question: "What constraints should I preserve?" }
+    ]
+  }
+})
+// → Reply from supervisor: { "responses": [{ "id": "api", "value": "Stable API" }, ...] }
+```
+
+### Example: Progress Update
+
+```typescript
+contact_supervisor({
+  reason: "progress_update",
+  message: "Discovered the bug is in the retry wrapper, not the API client. Fixing the wrapper will also close issue #42."
+})
+// → Progress update accepted for supervisor planner. Queued for the next tool boundary; broker acceptance does not confirm the supervisor has read or acted on it.
+```
+
+### What the Supervisor Sees
+
+The supervisor receives a formatted message with run metadata:
+
+```
+**From subagent-worker-78f659a3-1**
+
+Subagent needs a supervisor decision.
+Run: 78f659a3
+Agent: worker
+Child index: 0
+
+Which API should I use?
+```
+
+Reply hints work the same as regular `intercom` ask/reply flows. The supervisor can reply with `intercom({ action: "reply", message: "..." })` and the subagent receives the answer as the tool result. If the parent agent is busy and later needs to recover the request, `intercom({ action: "pending" })` summarizes supervisor asks with run id, agent, child target, and question text.
+
+For `interview_request`, the supervisor message includes the structured questions plus a fenced JSON answer example using this stable shape:
+
+```json
+{
+  "responses": [
+    { "id": "api", "value": "Stable API" },
+    { "id": "constraints", "value": "Keep the public error shape unchanged." }
+  ]
+}
+```
+
+The supervisor can reply with plain JSON or a fenced `json` block. If the reply matches the `{ "responses": [...] }` shape and references valid question ids/options, the child tool result includes it in `details.structuredReply` while still showing the raw reply text.
+
+## Tool Reference
+
+### load_intercom
+
+`load_intercom({})` enables the full peer schema without sending messages or checking sessions. Then use `intercom` for all existing actions. Ordinary peer asks restored after reload retain their configured expiry. Saved replies, peer disconnects, recipient-error feedback, and durable supervisor answers retire the reply obligation without replaying consumed messages.
+
+### intercom
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `action` | string | `"list"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
+| `scope` | string | Optional for list/status: `"project"` (default) shows this Git repository and its worktrees; `"all"` includes sessions in other projects. |
+| `to` | string | Target session name or ID (for send/ask, or to disambiguate reply) |
+| `message` | string | Message text (for send/ask/reply) |
+| `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
+| `replyTo` | string | Optional message ID for threading or replying to an `ask` |
+| `delivery` | string | Optional: omitted `send` defaults to `"steer"`, which injects after the current tool call; `"queue"` intentionally waits behind active work, and `"passive"` does not wake the recipient model (`send` only). |
+| `queueMode` | string | Optional with queued delivery: `"stack"` keeps all messages, `"replace"` keeps only the latest undelivered message for the same `threadId` after a short coalescing window. |
+| `threadId` | string | Required for `queueMode:"replace"`; stable topic key for replacement. |
+| `passive` | boolean | Legacy `send`-only alias for `delivery:"passive"`. Discouraged for agent-to-agent messages. |
+
+### contact_supervisor
+
+Only registered in sessions where `pi-subagents` supplied the required child bridge metadata. Contacts the supervisor session that delegated the current task.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `reason` | string | `"need_decision"` (blocking), `"interview_request"` (blocking structured questions), or `"progress_update"` (non-blocking) |
+| `message` | string | The decision request, optional interview note, or progress update |
+| `interview` | object | Required for `interview_request`: `{ title?, description?, questions: [...] }` |
+
+**`need_decision`** — Use only when the ephemeral child cannot safely continue without one decision, approval, or product/API/scope clarification. It sends a formatted steered ask to the supervisor and keeps the child alive until the reply arrives, without the ordinary intercom ask timeout. The reply comes back as the tool result. Includes run metadata in the message so the supervisor knows which subagent is asking.
+
+**`interview_request`** — Use only when the ephemeral child cannot safely continue until it receives multiple structured answers. It sends a formatted, steered agent-readable interview to the supervisor and keeps the child alive until the reply arrives. Questions use a local pi-interview-like shape: `{ id, type, question, options?, context? }` where `type` is `single`, `multi`, `text`, `image`, or `info`. `info` questions are context-only and do not need responses. The supervisor reply should be JSON with `{ "responses": [{ "id": "...", "value": ... }] }`. Parsed JSON replies are returned in `details.structuredReply`.
+
+**`progress_update`** — Steers a material discovery at the next native tool boundary without waiting for a reply. The receipt confirms broker acceptance, not model consumption or action. Send only what the supervisor needs while working; skip starts, redundant status, and routine completion. Keep material findings in the final result.
+
+### intercom actions
+
+**`list`** — Returns the current session plus other intercom-connected sessions in the current Git repository and its worktrees by default. Pass `scope:"all"` to intentionally include sessions in other projects. Hidden sessions remain connected and directly targetable by an exact known target. Rows include name, safe target, working directory, model, live status, and peer health tags: `state` (`idle`, `busy`, or `unknown`), `accepts_asks`, `pending_asks`, `last_intercom_activity`, and `last_seen`. Peer rows include live delivery guidance for `ask`, `send`, `queue`, `steer`, and the discouraged passive path; the self row says self-target delivery is unavailable and points to peer targets / `pending` / `reply`. Status is derived automatically from Pi lifecycle events: `idle`, `thinking`, or `tool:<name>`. If multiple sessions have the same name, use the displayed target exactly as shown, for example `to: "ca7bfec2"`. The target may be longer than eight characters when needed to avoid collisions.
+
+**`send`** — Sends a non-blocking, default-steered message to the specified session and returns broker acceptance, not a later response. It wakes idle recipients or reaches busy recipients at the next tool boundary. Use `delivery:"queue"` only when delay is intentional, and `delivery:"passive"`/`passive:true` only for human-visible breadcrumbs. `queueMode:"replace"` with a `threadId` replaces older undelivered intercom-staged messages for that thread after a short coalescing window; once a message is handed to Pi's native queue it cannot be keyed-replaced. Set `confirmSend: true` in config if you want a confirmation dialog for non-reply sends. Replies that include `replyTo` skip confirmation.
+
+**`ask`** — Sends a message and waits for the recipient to reply (`askTimeoutMs`, default 2 minutes). Reserve it for a sender process that must remain alive and cannot safely continue without the answer; use `delivery:"steer"` so a busy recipient sees it at the next tool boundary. If the target publishes `accepts_asks:false`, a default blocking ask returns promptly with `reason:"peer_busy"`, while an explicit steer ask still waits. Only one pending waiting ask is allowed per session. Passive delivery is rejected.
+
+**`reply`** — Replies to the current intercom-triggered message if there is one. Otherwise it falls back to the single unresolved inbound ask. If multiple asks are pending, pass `to` or inspect them with `pending` first. Under the hood this is still a normal `send` with the exact `replyTo` value.
+
+**`pending`** — Lists unresolved inbound asks with sender, elapsed time, a labeled `replyTo` ID, and a copy-ready `intercom({ action: "reply", ... })` call. For `pi-subagents` supervisor asks, the preview expands the run id, agent, child intercom target, and question so the parent can reply without guessing. Useful when replying after the original triggered turn.
+
+**`status`** — Shows connection status, session ID, and the same project-scoped recipient capability rows as `list`. Also shows inbound messages still queued for delivery or handed to Pi but not yet consumed. Pass `scope:"all"` to include other projects.
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| Option+Shift+M (Alt+Shift+M), configurable | Toggle owned agent conversations; open peer messaging when the agent view is unavailable |
+| ↑/↓ | Navigate session list |
+| Tab | Toggle Send / Request Reply mode in the compose overlay |
+| Enter | Select session / Send or ask |
+| Escape | Cancel / Close overlay |
+
+## Config
+
+Create `${PI_CODING_AGENT_DIR:-~/.pi/agent}/intercom/config.json`:
+
+```json
+{
+  "shortcut": "alt+shift+m",
+  "confirmSend": false,
+  "replyHint": true,
+  "askTimeoutMs": 120000,
+  "sendTimeoutMs": 8000,
+  "listTimeoutMs": 5000,
+  "status": "researching"
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `shortcut` | `"alt+shift+m"` | Native Pi key identifier for the Agents/Intercom shortcut, for example `"ctrl+shift+k"`. The Agents entrance hint uses the same setting. |
+| `brokerCommand` | current Node executable | Command used to start the local broker process when you override the default |
+| `brokerArgs` | `[]` | Arguments passed to `brokerCommand` before the broker script path. The built-in default runs the bundled TypeScript broker directly with Node. |
+| `confirmSend` | false | Show a confirmation dialog before non-reply sends from an interactive session with UI |
+| `replyHint` | true | Include reply instructions in incoming asks |
+| `askTimeoutMs` | `120000` | Reply wait timeout for ordinary peer `ask`; durable supervisor questions do not expire |
+| `sendTimeoutMs` | `8000` | Broker delivery-ack timeout for sends/asks |
+| `listTimeoutMs` | `5000` | Session-list response timeout |
+| `status` | — | Optional custom status suffix shown after the automatic lifecycle status, for example `thinking · researching` |
+
+The default shortcut requires a terminal that reports combined modifiers through Kitty keyboard protocol or xterm modifyOtherKeys. Pi negotiates these automatically on supported terminals. `/agents` is also available. Restart Pi after changing the shortcut.
+
+Use `pi config` to enable or disable the bundled intercom extension. The former `config.json` `enabled` key is no longer read; in particular, an existing `"enabled": false` does not disable intercom after this migration.
+
+For example, if you have Bun installed and want it to start the broker directly, use:
+
+```json
+{
+  "brokerCommand": "bun",
+  "brokerArgs": []
+}
+```
+
+Pi-intercom publishes live session status automatically. Sessions register as `idle`, switch to `thinking` while the agent is running, show `tool:<name>` during tool execution, and return to `idle` on agent completion. If `status` is set in config, it is appended as context instead of replacing the lifecycle status.
+
+## How It Works
+
+```mermaid
+graph TB
+    subgraph A["Pi Session A"]
+        A1[Intercom Client]
+        A2[intercom tool]
+        A3[UI overlays]
+    end
+
+    subgraph Broker["Intercom Broker"]
+        B1[Session Registry]
+        B2[Message Router]
+    end
+
+    subgraph B["Pi Session B"]
+        B3[Intercom Client]
+        B4[intercom tool]
+        B5[UI overlays]
+    end
+
+    A1 <-->|Unix Socket| B1
+    B1 --- B2
+    B2 <-->|Unix Socket| B3
+```
+
+The broker is a standalone TypeScript process that manages session registration and message routing. It auto-spawns when the first intercom session needs it and exits after 5 seconds when the last connected session disconnects. Clients now reconnect automatically if the broker disappears and later comes back.
+
+Messages use length-prefixed JSON over a local Unix socket transport (4-byte length + JSON payload) to handle fragmentation properly. The protocol includes request correlation for session listing, explicit delivery failures, and validation for malformed or out-of-order messages. Session registration carries user-facing identity plus live health fields; process ID, start time, and the redundant activity timestamp are no longer part of the protocol.
+
+Startup restoration and inbound batches join during shutdown while their old native owner remains valid. Work that outlives a replaced owner (reconnects, overlays, and relays) no-ops rather than using stale APIs. Completion handoffs retain accepted acknowledgements before listeners stop; failed shutdown deliveries remain eligible on reopen without requesting a new turn after ingress closes. Undelivered receiver messages remain in native session metadata, bound to the exact saved session UUID. Native message entries are the delivery receipt, including messages that have left the active context after compaction. Each body is checkpointed once; later handoff metadata stores only the message ID and state.
+
+Runtime files:
+- Unix domain socket — private short temp path `pi-intercom-<hash>/broker.sock` on macOS/Linux, keyed by user ID and `PI_CODING_AGENT_DIR` or `~/.pi/agent`
+- `${PI_CODING_AGENT_DIR:-~/.pi/agent}/intercom/broker.pid` — Broker process ID on the first line (backward-readable). On Linux, new brokers add native boot ID, PID namespace, reader time namespace and process start ticks on a second `linux-v1` line.
+- `${PI_CODING_AGENT_DIR:-~/.pi/agent}/intercom/config.json` — User configuration
+
+## Design Decisions
+
+**Local IPC instead of TCP.** Same-machine only by design. `pi-intercom` uses Unix sockets on macOS/Linux, which keeps setup simple and avoids port management.
+
+**Auto-spawn with file lock.** The broker starts on first connection and exits after 5 seconds idle. There is no daemon to manage. A spawn lock file, keyed by PID and timestamp, prevents duplicate brokers when multiple sessions start at once.
+
+**PID reuse after restore.** A live numeric PID alone does not identify a broker: a cold restore can reuse that number for an unrelated process or thread. Linux startup ignores a saved PID only when readable native metadata disproves its identity. Different boot/PID namespace or comparable start ticks identify a stale record; start ticks are compared only in the same reader time namespace. Legacy numeric-only records remain ambiguous and blocking, except a proven non-leader thread (`Tgid != Pid`) cannot be the process ID a broker wrote. Unreadable/unsupported metadata, foreign procfs PID views and signal-0 permission errors retain the conservative refusal. macOS needs no procfs and retains numeric-PID behavior. No process is killed and no PID file is deleted to recover; normal broker startup writes its new record. A connected broker and its accepted queues are unchanged. The fields follow Linux [`proc_pid_status(5)`](https://man7.org/linux/man-pages/man5/proc_pid_status.5.html), [`proc_pid_stat(5)`](https://man7.org/linux/man-pages/man5/proc_pid_stat.5.html) and [`namespaces(7)`](https://man7.org/linux/man-pages/man7/namespaces.7.html); they are identity evidence, not process-control authority.
+
+**`ask` stays client-side.** The broker still routes plain messages; it does not have a special request/response mode for `ask`. The sender marks the message as expecting a reply, the recipient wakes or queues according to the delivery mode, and the sender waits for the matching reply before returning it as the tool result. Reply hints make that flow practical by showing the recipient the exact `reply` call to use. Separately, `list` / `sessions` now carry a `requestId` so a delayed session-list reply cannot be mistaken for a newer one.
+
+## pi-intercom vs pi-messenger
+
+| Aspect | pi-intercom | pi-messenger |
+|--------|-------------|--------------|
+| **Model** | Direct 1:1 messaging | Shared chat room |
+| **Primary use** | User orchestrating sessions | Autonomous agent coordination |
+| **Discovery** | Broker-based (real-time) | File-based registry |
+| **Messages** | Private, session-to-session | Broadcast to all agents |
+| **Persistence** | In Pi session history | Shared coordination files |
+
+Use pi-messenger for multi-agent swarms working on a shared task. Use pi-intercom when you want to manually coordinate your own sessions or have one agent reach out to another specific session.
+
+## File Structure
+
+```
+pi-subagents/
+├── package.json          # One manifest for both extensions
+├── src/pi-intercom/
+│   ├── index.ts          # Intercom extension entry point
+│   ├── types.ts          # SessionInfo, Message, protocol types
+│   ├── config.ts         # Config loading
+│   ├── broker/
+│   │   ├── broker.ts         # Broker process
+│   │   ├── client.ts         # IntercomClient class
+│   │   ├── framing.ts        # Length-prefixed JSON protocol
+│   │   ├── paths.ts          # Platform-specific Unix socket paths
+│   │   └── spawn.ts          # Auto-spawn logic with lock file
+│   └── ui/
+│       ├── session-list.ts   # Session selection overlay
+│       ├── compose.ts        # Message composition overlay
+│       └── inline-message.ts # Received message display
+└── skills/pi-intercom/
+    └── SKILL.md              # Bundled skill for common patterns
+```
+
+## Lifecycle and saved work
+
+Pi 1.0 uses ordinary shutdown/reload boundaries, not the old fork's idle-checkpoint or broker-admission-hold API. A settled parent does not prove its detached children are finished. Preserve their saved sessions, run records and questions, and keep a legacy runtime available until its active owners finish. Do not disconnect a recipient or stop a broker to manufacture completion: accepted replace-mode messages can still exist only in broker memory.
+
+Assistant-error replies wait for broker acknowledgement during `message_end`, bounded by `sendTimeoutMs`. Async inbound/reconnect/relay callbacks remain tied to their owning session generation; late callbacks cannot append into a replacement session. Durable inbox stages and actual parent message publication drive recovery.
+
+## Limitations
+
+Historical official Pi 0.87.1 checks exposed queue visibility and prompt-preparation races. Current tests preserve exact-once receipts and input rejection/recovery on the selected host, including the genuine Pi 1.0 pre-admission window described above; they do not promise one combined provider turn. Historical results are not a current 1.0 pass. Use an explicit `async: false` wait when dependent work needs a finalized result. Native pending-call, idle-checkpoint and immediate-usage APIs are no longer supported. See [result delivery](../README.md#host-capabilities-and-result-delivery) and [local qualification](../README.md#local-validation).
+
+- **Same machine only** — The core broker uses local Unix sockets, no network support. The optional [secure remote bridge](intercom-bridge.md) authenticates remote messaging through a separate loopback mTLS proxy; it does not expose the broker socket.
+- **No dedicated intercom log** — Messages are kept in Pi session history, but there is no separate intercom transcript or inbox
+- **No attachments UI** — `file`, `snippet`, and `context` attachments are supported in the protocol, but not in the compose overlay
+- **Only connected sessions appear** — The list shows Pi sessions that have loaded `pi-intercom` and successfully registered with the broker, not every open Pi process on the machine
+- **Broker lifecycle** — The broker auto-spawns on first use and exits when idle; sessions reconnect automatically if the broker restarts