/intercom

name: intercom
description: |
  Streamline session-to-session coordination with the intercom extension. Send
  messages, delegate tasks, and coordinate work across multiple atomic sessions on
  the same machine. Use for planner-worker workflows, cross-session context
  sharing, and real-time collaboration between sessions.

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):

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):

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**:

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.

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.

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 includes `notInKnownSet`. 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:

// Add a membership. Existing memberships remain active.
intercom({ action: "join", group: "api-review" })

// Discover every