intercom

# Intercom Skill Use this skill when you need to coordinate work across multiple atomic sessions running on the same machine. Intercom enables direct 1:1 messaging between sessions for delegation, context sharing, and collaborative workflows. When you are supervising with the `subagent` skill, delegated child agents can escalate to you via `contact_supervisor` if the subagent runtime supplied child bridge metadata. This skill covers how to handle those orchestrator-side escalations, and how children and workflow stages talk to each other as peers. ## When to Use - **Task delegation**: Split work between a planner session and worker sessions - **Context handoffs**: Send findings from a research session to an execution session - **Clarification loops**: Worker asks questions, planner answers, work continues - **Multi-session workflows**: Coordinate between specialized sessions (frontend/backend, research/implementation) - **Peer coordination**: Sibling subagents or workflow stages debate findings, hand off evidence, divide ownership, and learn from each other without routing through the supervisor ## Core Patterns ### Pattern 1: Planner-Worker Delegation The most common pattern. One session holds the big picture, others do hands-on work. **Setup** (in each session): ``` /name planner # Terminal 1 /name worker # Terminal 2 ``` **Planner delegates a task** (fire-and-forget): ```typescript intercom({ action: "send", to: "worker", message: "Task-3: Add retry logic to API client. Key files: src/api/client.ts. Ask if anything's unclear." }) ``` **Worker asks for clarification** (blocks until answer): ```typescript intercom({ action: "ask", to: "planner", message: "Should I use exponential backoff or fixed intervals?" }) // → Returns the planner's reply as the result ``` **Worker reports completion**: ```typescript intercom({ action: "ask", to: "planner", message: "Task-3 complete. Added exponential backoff (100ms → 1600ms, max 5 retries). Ready for task-4?" }) ``` ### Pattern 2: Quick Status Check Before sending, verify who's connected. Full session UUIDs or their unique 8-hex prefixes can be used as targets. Each list row leads with a copyable full session ID or canonical workflow path. Names are secondary; redundant generated aliases are omitted from the list but remain valid targets. ```typescript intercom({ action: "list" }) // → - `6332faab-1111-4222-8333-123456789abc` [idle] /workspace (model) name: planner intercom({ action: "ask", to: "6332faab-1111-4222-8333-123456789abc", message: "Which option should I use?" }) ``` Live sessions accept an exact full Intercom session ID, a unique 8-hex prefix of a visible UUID-backed session, or an exact case-insensitive name. Ambiguous prefixes require a listed full UUID. For workflow stages, first join `workflow:<rootRunId>` and use `intercom({ action: "list" })`: materialized stages appear as `PENDING` or `RUNNING` with canonical `workflow:<rootRunId>/<segment>[/<segment>...]` targets and actual groups, followed by possible future targets with queued counts. The invocation context can control owned isolated subgroups by exact target, while sibling subgroups and other runs remain isolated. Use queued `send` for `PENDING` or future targets; `ask` is supported only for `RUNNING`, where an exact correlated reply returns to the invocation asker. ### Deliver to workflow stages that have not started Send material updates through Intercom to every affected workflow stage, including stages that have not started. Before steering, join the invocation group `workflow:<rootRunId>` (discover it with the Intercom `groups` action), then use `intercom list` there to see live, pending, and possible future targets. ```typescript intercom({ action: "send", to: "workflow:<rootRunId>/reviewer", message: "Scope changed: preserve raw amendment text in the verification oracle." }) // → queued, distinct from live-session delivered, with the FIFO position ``` Each path segment may be a stage name, a run id, or a glob: `*` matches one segment and may be embedded (`reviewer-*`), while `**` matches any depth. When shared scope or acceptance criteria change, broadcast one authoritative update to `workflow:<rootRunId>/**` (or a narrower pattern) rather than enumerating stages. The broadcast reaches every live stage immediately and remains sticky for every future matching stage, including nested children, until the root run terminates. Other name or pattern sends have the same every-future-match behavior. A syntactically valid target outside the persisted possible-stage set is accepted speculatively: the queued acknowledgment carries `prediction: "unknown"` (or `"predicted"` when the decision model expects the path) and shows no warning. A line appears only when the target looks like a typo of a known stage. At terminal settlement, an entry that never delivered produces the correlated undeliverable notification; an entry delivered at least once does not. A stage receives queued messages through the ordinary inbound path before its first model turn under **Messages received before you started**, with real sender identity and a `Sent:` timestamp. Only same-workflow-group sessions may queue messages. Each target holds at most 50 queued messages; the next send is refused rather than evicting one. Resume/replay, broker restart, and stage-attempt restart preserve exactly-once delivery per message and materialized stage. Use `ask` only for a live target: pending, future, and pattern asks return `pending_stage_ask_unsupported`. ### Runtime named groups Plain chat sessions can add and remove group memberships without restarting: ```typescript // Add a membership. Existing memberships remain active. intercom({ action: "join", group: "api-review" }) // Discover every available group and see membership markers. intercom({ action: "groups" }) // Remove one membership, or reset to home by omitting group. intercom({ action: "leave", group: "api-review" }) intercom({ action: "leave" }) ``` `list` still lists sessions: without a filter it returns every peer sharing at least one membership. `default` remains shared, while `true` and `auto` remain reserved. Later subagents inherit the most recently joined membership. Ordinary `send`/`ask` requires a shared membership; only authorized `contact_supervisor` traffic crosses group boundaries. ### Pattern 3: Reply Naturally When responding to an inbound ask, prefer `reply` instead of reconstructing raw IDs: ```typescript // In the turn triggered by the ask: intercom({ action: "reply", message: "Use exponential backoff starting at 100ms." }) // If replying later and there might be more than one pending ask: intercom({ action: "pending" }) intercom({ action: "reply", to: "planner", message: "Use exponential backoff starting at 100ms." }) ``` Explicit `to` selects that sender's pending ask even if another message triggered the current turn. Use `pending` and an exact pending message ID or unique 8-hex UUID prefix in `replyTo` when the sender has several asks. Prefixes resolve to the canonical full ID before fallback; collisions fail. Stale, unknown, empty, or sender-mismatched explicit selectors fail without replying to another thread. Omit both selectors only when you intend to reply to the active message, or otherwise the single pending ask. ### Pattern 4: Broadcast to Multiple Workers Send to multiple sessions in parallel: ```typescript const workers = ["worker-1", "worker-2", "worker-3"]; const task = "Check for null pointer exceptions in your assigned files"; // Fire-and-forget to all workers workers.forEach(w => intercom({ action: "send", to: w, message: task }) ); ``` ### Pattern 5: Send with Attachments Share code snippets, files, or context: ```typescript intercom({ action: "send", to: "worker", message: "Here's the fix for the auth issue:", attachments: [{ type: "snippet", name: "auth.ts", language: "typescript", content: `function validateUser(user: User | null) { if (!user) throw new Error("User required"); return user.email?.includes("@"); }` }] }) ``` ### Pattern 6: Handle Subagent Escalations (Orchestrator Side) When the `subagent` runtime spawns a delegated child and supplies child bridge metadata, that child can reach you through `contact_supervisor`. You receive a formatted message that includes 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 using `reply`:** ```typescript // The reply hint in the incoming message will show the exact call: intercom({ action: "reply", message: "Use the stable v2 API." }) ``` This works because `reply` resolves the correct sender and message ID automatically. **Three types of escalations to expect:** | Type | What it means | How to respond | |------|---------------|----------------| | `need_decision` | Subagent is blocked and waiting for your answer. Has a 10-minute timeout. | Reply promptly with a clear decision. If you need more context, ask follow-up questions via `reply`. | | `interview_request` | Subagent needs multiple structured answers in one blocking exchange. Has a 10-minute timeout. | Reply with plain JSON or a fenced `json` block using the provided `{ "responses": [...] }` shape. | | `progress_update` | Subagent is sharing meaningful progress or a plan-changing discovery. Not blocking. | Read and acknowledge. No reply required unless you want to redirect. | **When a subagent asks:** ```typescript // In the turn triggered by the incoming ask: intercom({ action: "reply", message: "Use exponential backoff, max 3 retries." }) ``` **When a subagent sends an interview request:** Read the rendered questions in the incoming message and reply with the exact ids in JSON. `info` questions are context-only and do not need response entries: ```typescript intercom({ action: "reply", message: "```json\n{\n \"responses\": [\n { \"id\": \"api\", \"value\": \"Stable API\" },\n { \"id\": \"constraints\", \"value\": \"Keep the public error shape unchanged.\" }\n ]\n}\n```" }) ``` **If you receive multiple pending asks:** ```typescript intercom({ action: "pending" }) // → Shows every unresolved ask with sender, exact message ID, age, and preview intercom({ action: "reply", to: "subagent-worker-78f659a3-1", message: "Use the v2 API." }) // If that sender has multiple asks, select the exact listed thread: intercom({ action: "reply", replyTo: "message-id", message: "Use the v2 API." }) ``` **Important:** Only sessions where the `subagent` runtime supplied child bridge metadata get the `contact_supervisor` tool. Normal sessions use the regular `intercom` tool. If you see the formatted supervisor decision/progress update message, treat it as a `contact_supervisor` escalation. ### Pattern 7: Constructive Quorum Use constructive quorum when several fresh-context reviewers judge the same artifact and a tally could hide a defect one reviewer found or preserve another reviewer's misreading. 1. Each reviewer inspects independently and records a preliminary verdict before reading sibling findings or verdicts. 2. Run exactly one bounded evidence-exchange round: share concrete findings and evidence, challenge blocking claims, surface missed defects, and correct objective/acceptance-criteria misreadings. Do not continue into a second round. 3. Change a verdict only through evidence, never deference. Each reviewer emits its own final structured verdict and records whether the round changed it and which evidence caused the change. 4. Let the deterministic reducer count final votes; this pattern does not change quorum counts or the `stop_review_loop` contract. In Atomic workflows, each invocation has its own Intercom group, and parallel stages and delegated subagents inherit it when Intercom is available. Sibling reviewers can therefore coordinate without custom group wiring. See the [constructive quorum workflow pattern](../../../coding-agent/docs/workflows/reliable-design.md#common-workflow-patterns). ### Pattern 8: Peer Coordination Between Subagents and Workflow Stages Peer-to-peer (swarm) is the default topology inside a delegation. There are no limits on communication between agents; it is encouraged whenever you need to. The supervisor is not a message relay: relaying adds latency, loses detail, and fills the supervisor's context, so siblings exchange evidence directly and self-organize. Children launched in one parallel set (or one explicit `group`) share an Intercom group, and workflow stages share their invocation group `workflow:<rootRunId>`; delegated subagents inside a stage inherit it. Any of them can list live siblings and message them directly. `contact_supervisor` is reserved for the supervisor; peer traffic uses ordinary `intercom`. ```typescript // Any child or stage: discover who is live in your group intercom({ action: "list" }) // Broadcast: share a finding with every live sibling in the workflow intercom({ action: "send", to: "workflow:<rootRunId>/**", message: "Root cause confirmed: cache key omits tenant id (src/cache.ts:52). Adjust your angle." }) // Connect: pass what you found to the sibling who needs it intercom({ action: "send", to: "codebase-analyzer-2", message: "Null handling lives in src/auth/session.ts:40-118 and src/auth/refresh.ts:12-60. Start there." }) // Coordinate: claim shared work so two writers do not collide intercom({ action: "send", to: "worker-1", message: "I am running the integration suite now (~4 min). Do not start it; I will send the result." }) // Learn: reuse a sibling's verified reproduction intercom({ action: "ask", to: "debugger-1", message: "What exact command and env reproduced the timeout? I want to reuse it, not rediscover it." }) // Debate: challenge a finding with evidence, then decide for yourself intercom({ action: "ask", to: "reviewer-2", message: "You called the retry loop unbounded. client.ts:88 caps attempts at 5 — which path bypasses it?" }) ``` How a swarm works: - Coordinate proactively. Discover peers with `list` as soon as you start and again whenever new siblings may have joined, without waiting for the launcher to name them. - Broadcast findings, claim files or expensive steps, hand work along a chain, ask and answer each other, and debate disagreements for as long as it is useful. - Decide on evidence, not deference. A peer's approval, rejection, or claim is input to inspect, not a verdict to copy, and each agent still returns its own result. - `contact_supervisor` is for supervisor decisions; explicit user approval gates and authorization for destructive or external actions still apply. - Inside a workflow, `send` to a known pending sibling queues until it starts, and `ask` to a completed sibling that retains a valid conversation reopens it for a post-mortem turn. Named stage subgroups isolate their members from sibling subgroups. - Choose `delivery` per `send`/`ask` by urgency. The default `"steer"` arrives after the recipient's current tool calls finish and never cancels its work. Use `"interrupt"` when it must stop now (an urgent correction or a stop order), and `"followUp"` when the message can wait until it finishes (low priority, "after you're done"). - Peer asks and one blocking supervisor request may wait concurrently in the same child; mutual asks work when both sides process inbound work. - Scale with the task. For very complex work or requested heavy parallelism, hundreds or thousands of agents self-organize into teams (named groups, per-stage subagent sets, child workflows) and coordinate peer-to-peer like an organization. Groups have no member limit; team members reach their lead with `contact_supervisor`, and leads talk to each other in their shared group. ## Key Differences | Action | Behavior | Use When | |--------|----------|----------| | `join` | Adds or creates a named membership in place | Sessions need another shared routing group | | `leave` | Removes one named membership, or resets to home when omitted | Stop sharing one group or restore startup membership | | `groups` | Lists every available group with counts and membership markers | Discover a group instead of guessing its name | | `send` | Fire-and-forget to a live session, or durable sticky delivery to `workflow:<rootRunId>/<segment>[/<segment>...]`; globs and `**` broadcasts cover live and future matches | You don't need a response | | `ask` | Blocks until a live recipient replies (10 min timeout); refused for an unstarted stage | You need an answer to continue | | `reply` | Responds to the active or pending inbound ask; `to` accepts an exact name/full session ID or unique 8-hex session UUID prefix | You were asked something and need to answer naturally | | `pending` | Lists unresolved inbound asks | You need to see who is waiting before replying | | `list` | Returns all sessions sharing any membership, with full IDs and live status | Discover targets or choose an idle peer | | `status` | Returns connection state and every current membership | Troubleshooting | Inside workflows, `ask` may target a sibling stage that has already completed. If that stage retains a valid conversation, Atomic automatically schedules a post-mortem turn there and preserves the exact child-to-child reply thread; do not send a separate workflow follow-up. Missing, deleted, non-resumable, or failed-to-reopen completed targets return an actionable error. A parent or unrelated session cannot satisfy the pending ask. ## Optional: Visible Peer Sessions via cmux, tmux, or psmux (Windows rewrite of tmux that has fully parity with tmux) If no suitable intercom-connected peer session already exists and the task benefits from a long-lived visible conversation, you may spawn a new `atomic` session. Prefer `cmux new-split right` over new surfaces or workspaces so both sessions are visible side by side. If `cmux` is unavailable, `tmux` is an optional fallback when it is installed and relevant. Use it with a private socket so the session is isolated and observable. Use spawned peer sessions only for: - same-codebase worker/planner splits - reference-codebase scouting - long-lived visible conversations where the user benefits from watching both sides Do not use this for unrelated repos, trivial questions, or work you can finish cleanly in the current session. ### Preferred: cmux Worker or Scout Session Same codebase: ```bash cmux new-split right sleep 0.5 cmux send --surface right 'cd /path/to/current/repo && atomic\n' ``` Reference codebase: ```bash cmux new-split right sleep 0.5 cmux send --surface right 'cd /path/to/reference/repo && atomic\n' ``` ### Optional Fallback: tmux Worker or Scout Session Same codebase: ```bash