/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.

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)

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. The full session ID printed by `list` is directly usable by `send`, `ask`, and targeted `reply`:

intercom({ action: "list" })
// → • planner (6332faab-1111-4222-8333-123456789abc) — /workspace (model) [idle]
intercom({ action: "ask", to: "6332faab-1111-4222-8333-123456789abc", message: "Which option should I use?" })

Intercom accepts only an exact full session ID or an exact case-insensitive session name. Use the full ID printed by `list` or the session's exact name.

Runtime named groups

Plain chat sessions can create or join a group without restarting:

// Join or create the named group. Both sessions should run this call.
intercom({ action: "join", group: "api-review" })
intercom({ action: "list" }) // now shows only peers in api-review

// Leave the named group and return to the resolved startup home group.
intercom({ action: "leave" })

Joining changes broker presence without changing the session ID. `default` is the shared group. The names `true` and `auto` are reserved for subagent auto-groups and are rejected. Subagents launched after a join inherit the joined group. Ordinary `send`/`ask` calls remain group-isolated; only an authorized `contact_supervisor` call can cross groups.

Pattern 3: Reply Naturally

When responding to an inbound ask, prefer `reply` instead of reconstructing raw IDs:

// 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." })

`reply` still preserves exact threading under the hood by sending the response with the original `replyTo` value.

Pattern 4: Broadcast to Multiple Workers

Send to multiple sessions in parallel:

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:

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

// 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 `{ "respo