@ctliz/agent-intercom-pi 0.13.0 → 0.14.0

package/README.md

@@ -17,9 +17,11 @@
 | AGY | [`agent-intercom-agy`](https://github.com/ctliz/agent-intercom-agy) |
 | Fleet lifecycle | [`agent-intercom-orchestrator`](https://github.com/ctliz/agent-intercom-orchestrator) |
 
-## Pi 0.99 and codemode
+## Pi 1.0 compatibility and codemode
 
-Version 0.13.0 requires Pi 0.99.1 or newer in the 0.99 release line. It keeps the existing protocol v4 broker, durable queues, acknowledgements, and cross-harness routing unchanged.
+Version 0.14.0 is tested with Pi 1.0.0. The preceding 0.13.0 release was tested with Pi 0.99.1. The development test baseline now uses Pi 1.0.0; host-provided Pi modules remain peer dependencies, not runtime dependencies. The existing protocol v4 broker, durable queues, acknowledgements, and cross-harness routing are unchanged.
+
+Pi 1.0 defaults to fullscreen; set `tuiMode` to `"regular"` or launch with `--tui-mode regular` to retain terminal scrollback. Codemode's shorter declarations preserve Intercom's structured `{ ok, text, data }` results and team guidelines. To check tool existence in a script, use `"intercom_send" in tools`, not `typeof tools.intercom_send`, because unknown members now throw. Restart existing Pi processes to use a newly installed Pi version; `/reload` only reloads resources inside the running version.
 
 All Intercom tools remain directly callable and are also available through Pi's built-in codemode when active. Scripts receive `{ ok, text, data }` rather than a display string. `data` contains the tool's structured details: delivery flags and message ID, session lists, team roster, pending asks, or connection status. Returned failures set `isError: true` and retain structured data; a deferred ask is successful with `data.pending === true`. Always check `ok` before continuing with dependent actions. Blocked calls, invalid arguments, and thrown exceptions can still reject, so use `try/catch` or `Promise.allSettled()` when appropriate.
 
@@ -32,20 +34,59 @@ const result = await tools.intercom_send({ to: target.id, message: "Tests passed
 return { ok: result.ok, accepted: result.data.accepted, delivered: result.data.delivered };
 ```
 
-Concurrent sends and independent asks are supported; do not create two unresolved asks to the same recipient. Team joins execute sequentially because they change the caller's routing scope. Receiving a delivery acknowledgement means the message is durably queued, not that the recipient finished its task. Busy sessions wait until `ctx.isIdle()`; `agent_settled` updates final idle status after automatic retries and compaction.
+Concurrent sends and independent asks are supported; do not create two unresolved asks to the same recipient. Team joins execute sequentially; named task-team updates are also locked across independently launched Pi processes. Named joins append membership without changing the caller's broker routing scope. Receiving a delivery acknowledgement means the message is durably queued, not that the recipient finished its task. Busy sessions wait until `ctx.isIdle()`; `agent_settled` updates final idle status after automatic retries and compaction.
 
 ### Send from a shell or release script
 
 The package includes an `intercom-send` executable. Install the alias globally for a shell command, or run it without relying on Pi's private installation path:
 
 ```bash
-npm exec --yes --package=@ctliz/pi-intercom@0.13.0 -- intercom-send worker 'Tests passed.'
+npm exec --yes --package=@ctliz/pi-intercom@0.14.0 -- intercom-send worker 'Tests passed.'
 ```
 
 It prints one JSON result with `accepted`, `delivered`, `messageId`, and optional failure `code`/`reason`. Exit status is zero only for acknowledged delivery. It inherits the routing scope, but never inherits `PI_INTERCOM_SESSION_ID` or `AGENT_INTERCOM_SESSION_ID`: every invocation registers an independent sender, leaves running Pi sessions intact, and disconnects after sending. It is send-only; use the session tools for reply-tracked asks.
 
 When a second runtime claims the same stable session ID, Intercom reports `SESSION_ID_IN_USE`, pauses automatic reconnect, and preserves the original owner. Switch to a different session, or release the duplicate owner and `/reload`. `intercom_status` exposes the conflict as structured data rather than silently treating it as a temporary outage. Updating this adapter does not require restarting a compatible v4 broker.
 
+## Pi-local task teams
+
+Open Pi normally in separate terminals; no startup team, session name for the
+coordinator, or terminal multiplexer is required. When you ask an agent to work
+with `front` and `writer`, its tool guidelines tell it to ask once whether to form
+a team. After approval (or an explicit request to form a team), it discovers the
+sessions and creates the task group itself:
+
+```typescript
+intercom_join({ name: "launch", create: true, members: ["front", "writer"], work: "Build the product page" })
+intercom_send({ team: "launch", to: "front", message: "Implement the UI." })
+intercom_send({ team: "launch", to: "writer", message: "Write the copy." })
+intercom_team({})                     // all your task teams
+intercom_team({ team: "launch" })     // one team's manager and members
+```
+
+Joining another named team appends membership, never replaces it. The manager can
+append approved peers with `members`; any session can join itself. Missing or
+ambiguous targets fail before membership is written. Team updates are persistent
+and serialized across Pi processes. A different task can use a different team
+with the same participants.
+
+Every task message carries a public team name, displayed as `[Team: launch]`.
+When two sessions share multiple teams, sends/asks require `team`. Replies inherit
+the exact original message's team: use its receiver-local `contextId` reply hint,
+or an `askId` from `intercom_pending`. Mixed-team batches retain every message's
+label; ambiguous replies fail rather than guessing.
+
+This feature changes only Pi's named teams and prompt guidelines. It does not
+change the shared v4 broker or other adapters, does not add a security boundary,
+and does not isolate model history per team. Without a shared team, omitting
+`team` sends an ungrouped direct message even when either session belongs to
+unrelated teams, allowing initial contact before forming a team. Explicit team
+messages still require both sessions to be members; multiple shared teams still
+require selecting `team`. Consent is an agent instruction, not a broker-enforced approval record.
+Managed-team and workspace integration paths are unchanged. All participating Pi
+sessions need the 0.14.0 Pi adapter and `/reload`. This is not a cross-adapter
+protocol rollout.
+
 ## Grok Build and AGY support
 
 Grok Build and AGY are supported as first-class protocol peers through two dedicated npm packages:
@@ -122,7 +163,7 @@ Each pi session that has `pi-intercom` loaded and enabled connects to a tiny loc
 ## Install
 
 ```bash
-pi install git:github.com/ctliz/agent-intercom-pi@v0.12.2
+pi install npm:@ctliz/pi-intercom@0.14.0
 ```
 
 If you are coming from `connect.1`, read [Upgrading from `connect.1`](#upgrading-from-connect1-to-connect2) first — the package namespace changed and the two versions must not be installed side by side.
@@ -321,7 +362,7 @@ If you never set `/name`, Intercom still exposes a runtime-only fallback alias s
 
 ### How `intercom_team` chooses a team
 
-`intercom_team({})` has no arguments. It resolves the current group in this order and stops at the first match:
+With Pi-local task teams, `intercom_team({})` first shows all named teams containing this session; `intercom_team({ team: "billing" })` selects one. If there are no named task teams, the existing managed-team resolution below applies. Boss mode keeps its existing resolution and does not accept named task teams.
 
 1. **Orchestrator** — `~/.pi/agent/intercom/orchestrator/workers.json` has an owned record for this session (`AGENT_INTERCOM_WORKER_ID`) or this session is the current manager of live owned coworkers.
 2. **TmuxDeck manifest** — `AGENT_INTERCOM_TEAM_MANIFEST` points at a valid team file. The Lead is `leadId`; workers are the other members. An invalid or empty manifest fails closed and does not fall through to the live roster.
@@ -350,7 +391,7 @@ Manifest, live-roster, and standalone teams cannot inspect another session's inb
 
 ### Create or join a team without tmux
 
-Named teams live in the local Intercom directory. Creating one generates a private scope, makes this session the manager, and is enough for `intercom_team` to return a live roster. Tmux and TmuxDeck are not required.
+Named teams live in the local Intercom directory. Creating one makes this session the task-team manager and stores explicit member session IDs. Joining appends membership without switching broker scope or replacing previous memberships. Legacy records retain their manager; peers must join again to record their membership. Tmux and TmuxDeck are not required.
 
 ```text
 /intercom-create billing       # create a named team and join as manager
@@ -630,11 +671,11 @@ The supervisor can reply with plain JSON or a fenced `json` block. If the reply
 
 | Tool | Parameters | Description |
 |------|------------|-------------|
-| `intercom_send` | required `to`, required `message`, optional `attachments` | Fire-and-forget delivery |
-| `intercom_ask` | required `to`, required `message`, optional `attachments` | Ask and wait briefly for a reply |
-| `intercom_reply` | required `message`, optional `askId`, `to`, `which` | Reply to the active or pending inbound message; `askId` selects an exact unresolved ask, while `to`/`which` remain compatible selectors |
-| `intercom_team` | none | Show the current manager and live coworkers owned by that manager |
-| `intercom_join` | optional `name`, optional `create` | List, join, or create a named team without tmux |
+| `intercom_send` | required `to`, `message`; optional `team`, `attachments` | Fire-and-forget delivery in a task team |
+| `intercom_ask` | required `to`, `message`; optional `team`, `attachments` | Ask and wait briefly for a reply |
+| `intercom_reply` | required `message`; optional `contextId`, `askId`, `team`, `to`, `which` | Select an exact inbound context and inherit its team |
+| `intercom_team` | optional `team` | Show your named task teams, or fall back to managed-team discovery |
+| `intercom_join` | optional `name`, `create`, `members`, `work` | Append membership; a manager can add connected peers, and `work` describes a newly created task |
 | `intercom_list` | none | List connected sessions in your scope |
 | `intercom_pending` | optional `askId`, `session` | List unresolved inbound asks with stable IDs; `askId` retrieves the full untruncated body, and managers may use `session` for an owned coworker |
 | `intercom_status` | none | Show connection and queue status |
@@ -659,7 +700,7 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 ### Tool behavior
 
-**`intercom_team`** reads orchestrator ownership dynamically and returns the current manager plus live same-manager coworkers. After adoption it follows the new manager without restarting the worker; `AGENT_INTERCOM_MANAGER_TARGET` is only a startup fallback.
+**`intercom_team`** first shows your named Pi task teams. Without named memberships it reads orchestrator ownership dynamically and returns the current manager plus live same-manager coworkers. After adoption it follows the new manager without restarting the worker; `AGENT_INTERCOM_MANAGER_TARGET` is only a startup fallback.
 
 **`intercom_join`** lists named teams and TmuxDeck workspaces, joins one by name, or creates a named team with `create: true`. Creating a team does not require tmux. Listing never prints the raw scope.
 
@@ -669,7 +710,7 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 **`intercom_ask`** waits up to 30 seconds for a prompt reply, then returns a successful pending result while keeping the request open for a late reply. Different recipients may wait concurrently; the same recipient may have only one unresolved ask. `PI_INTERCOM_ASK_WAIT_MS` changes the blocking window.
 
-**`intercom_reply`** resolves the active or pending inbound context internally. Pass the stable `askId` returned by `intercom_pending` to select one exact ask. Optional `to` and `which: "oldest" | "latest"` remain available for compatibility. None of these values exposes the protocol thread ID.
+**`intercom_reply`** resolves the active or pending inbound context internally and inherits its original team. Use the `contextId` in a team message's reply hint for an exact ordinary message, or pass the stable `askId` returned by `intercom_pending` to select one exact ask. A `team` selector must match the original message, never override it. Optional `to` and `which: "oldest" | "latest"` remain available for compatibility. None of these values exposes the protocol thread ID.
 
 The broker refuses a second unresolved `intercom_ask` from one session to the same recipient. Wait for the first answer or use `intercom_send` for a non-blocking follow-up.
 

package/broker/client.ts

@@ -38,6 +38,7 @@ import type {
 
 export interface SendOptions {
   text: string;
+  team?: string;
   attachments?: Attachment[];
   control?: IntercomCommonControlEnvelope;
   replyTo?: string;
@@ -125,6 +126,8 @@ function isMessage(value: unknown): value is Message {
     return false;
   }
 
+  if (content.team !== undefined && (typeof content.team !== "string" || !/^[A-Za-z][A-Za-z0-9_-]{0,31}$/.test(content.team))) return false;
+
   const attachmentsValid = content.attachments === undefined
     || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
   const controlValid = content.control === undefined || isIntercomCommonControlEnvelope(content.control);
@@ -811,6 +814,7 @@ export class IntercomClient extends EventEmitter {
       expectsReply: options.expectsReply,
       content: {
         text: options.text,
+        ...(options.team === undefined ? {} : { team: options.team }),
         attachments: options.attachments,
         control: options.control,
       },

package/index.ts

@@ -16,7 +16,8 @@ import { formatMessageTiming } from "./ui/timestamps.ts";
 import { formatSessionDisplayName, sanitizeDisplayText, sessionOriginLabel, shortestUniqueIdPrefixes } from "./ui/session-identity.ts";
 import { getAskTimeoutMs, getAskWaitMs, loadConfig, type IntercomConfig } from "./config.ts";
 import type { SessionInfo, SessionRegistration, Message, Attachment } from "./types.ts";
-import { pendingAskId, ReplyTracker, type IntercomContext } from "./reply-tracker.ts";
+import { pendingAskId, replyContextId, ReplyTracker, type IntercomContext } from "./reply-tracker.ts";
+import { appendNamedTeamMembership, formatNamedTeamRoster, namedTeamRoster, requireNamedTeamMembers, resolveNamedMessageTeam, sessionNamedTeams } from "./named-team-membership.ts";
 import { InboundMessageConflictError, PersistentInboundInbox, readPendingAsksSnapshot, type StoredInboundMessage } from "./inbound-inbox.ts";
 import { PersistentOutboundOutbox } from "./outbound-outbox.ts";
 import { formatIntercomTeam, resolveBossIntercomTeam, resolveIntercomTeam, resolveManagedInboxSession } from "./team.ts";
@@ -34,7 +35,6 @@ import {
 } from "./workspace-join.ts";
 import {
   buildJoinableCircles,
-  createNamedTeam,
   findNamedTeamByScope,
   formatCreateSuccess,
   formatJoinableCircleList,
@@ -732,13 +732,14 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   const replyWaiters = new Map<string, {
     from: string;
     replyTo: string;
+    team?: string;
     resolve: (message: Message) => void;
     reject: (error: Error) => void;
   }>();
   function hasReplyWaiterForTarget(from: string): boolean {
     return Array.from(replyWaiters.values()).some((waiter) => waiter.from.toLowerCase() === from.toLowerCase());
   }
-  function waitForReply(from: string, replyTo: string, signal?: AbortSignal, onCancel?: () => void): Promise<Message> {
+  function waitForReply(from: string, replyTo: string, signal?: AbortSignal, onCancel?: () => void, team?: string): Promise<Message> {
     if (hasReplyWaiterForTarget(from)) {
       return Promise.reject(new Error(`Already waiting for a reply from "${from}"`));
     }
@@ -763,6 +764,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       replyWaiters.set(replyTo, {
         from,
         replyTo,
+        team,
         resolve: (message) => {
           cleanup();
           resolve(message);
@@ -921,6 +923,9 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     }
     return rejectManagedJoin(classifyMembership(), isZhLocale());
   }
+  function taskTeamsAvailable(): boolean {
+    return !rejectCircleChange();
+  }
   async function applyCircleScope(ctx: ExtensionContext, scopeId: string, managerSessionId?: string): Promise<void> {
     if (managerSessionId) {
       process.env.AGENT_INTERCOM_MANAGER_TARGET = managerSessionId;
@@ -933,16 +938,22 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     await switchRuntimeScope(scopeId);
     syncPresenceIdentity(currentSessionId ?? ctx.sessionManager.getSessionId());
   }
-  async function createAndJoinNamedTeam(ctx: ExtensionContext, name: string): Promise<string> {
+  async function appendTaskTeam(ctx: ExtensionContext, name: string, create = false, members: string[] = [], work?: string) {
     const blocked = rejectCircleChange();
     if (blocked) throw new Error(blocked);
     const teamName = parseTeamName(name);
-    if (!getLiveContext(ctx)) {
-      startSessionRuntime(ctx);
+    if (!getLiveContext(ctx)) startSessionRuntime(ctx);
+    const activeClient = await ensureConnected("tool");
+    const memberIds: string[] = [];
+    for (const target of members) {
+      const id = await resolveSessionTarget(activeClient, target);
+      if (!id) throw new Error(`Team member "${target}" is not connected`);
+      memberIds.push(id);
     }
-    const managerSessionId = currentSessionId ?? ctx.sessionManager.getSessionId();
-    const team = createNamedTeam({ name: teamName, managerSessionId });
-    await applyCircleScope(ctx, team.scopeId, team.managerSessionId);
+    return appendNamedTeamMembership({ name: teamName, selfId: activeClient.sessionId!, create, members: memberIds, work });
+  }
+  async function createAndJoinNamedTeam(ctx: ExtensionContext, name: string): Promise<string> {
+    const team = await appendTaskTeam(ctx, name, true);
     return formatCreateSuccess({ team: team.name, name: currentDisplayName(), zh: isZhLocale() });
   }
   async function listOrJoinCircle(ctx: ExtensionContext, args: string): Promise<string> {
@@ -973,10 +984,12 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
         ? (zh ? "没有这个编号的团队。" : "No team uses that number.")
         : (zh ? "无法加入该团队。" : "Could not join that team."));
     }
+    if (selected.kind === "named") {
+      await appendTaskTeam(ctx, selected.name);
+      return formatNamedJoinSuccess({ team: selected.name, name: currentDisplayName(), zh });
+    }
     await applyCircleScope(ctx, selected.scopeId, selected.managerSessionId);
-    return selected.kind === "named"
-      ? formatNamedJoinSuccess({ team: selected.name, name: currentDisplayName(), zh })
-      : formatJoinSuccess({ workspace: selected.name, name: currentDisplayName(), zh });
+    return formatJoinSuccess({ workspace: selected.name, name: currentDisplayName(), zh });
   }
 
   function restoreIntercomSessionId(): void {
@@ -1021,11 +1034,13 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     const attachmentText = stored.message.content.attachments?.length
       ? formatAttachments(stored.message.content.attachments)
       : "";
-    const replyCommand = config.replyHint && stored.message.expectsReply
-      ? batchSize === 1
-        ? `intercom_reply({ message: "..." })`
-        : `intercom_reply({ to: "${stored.from.id}", message: "..." })`
-      : undefined;
+    const replyCommand = config.replyHint && stored.message.content.team
+      ? `intercom_reply({ contextId: "${replyContextId(stored.from.id, stored.message.id)}", message: "..." })`
+      : config.replyHint && stored.message.expectsReply
+        ? batchSize === 1
+          ? `intercom_reply({ message: "..." })`
+          : `intercom_reply({ to: "${stored.from.id}", message: "..." })`
+        : undefined;
     return {
       key: stored.key,
       from: stored.from,
@@ -1039,7 +1054,8 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     const senderDisplay = formatSessionDisplayName(entry.from);
     const prefix = position ? `[${position.index}/${position.total}] ` : "";
     const replyInstruction = entry.replyCommand ? `\n\nTo reply, use: ${entry.replyCommand}` : "";
-    return `**${prefix}📨 From ${senderDisplay}** (${entry.from.cwd})${replyInstruction}\n\n${entry.bodyText}`;
+    const teamLabel = entry.message.content.team ? `[Team: ${sanitizeDisplayText(entry.message.content.team)}] ` : "";
+    return `**${prefix}${teamLabel}📨 From ${senderDisplay}** (${entry.from.cwd})${replyInstruction}\n\n${entry.bodyText}`;
   }
   function sendIncomingBatch(entries: InboundMessageEntry[], generation = runtimeGeneration, forceTrigger = false): void {
     if (entries.length === 0) return;
@@ -1210,6 +1226,18 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
       });
       return;
     }
+    try {
+      if (message.content.team !== undefined) {
+        if (!taskTeamsAvailable()) throw new Error("Named task-team messages are unavailable in managed-team mode");
+        requireNamedTeamMembers(message.content.team, receivingClient.sessionId!, from.id);
+      }
+      const waiter = message.replyTo ? replyWaiters.get(message.replyTo) : undefined;
+      if (waiter && waiter.team !== message.content.team) throw new Error("Reply team does not match the original ask");
+    } catch (error) {
+      receivingClient.rejectMessage(deliveryId, getErrorMessage(error));
+      pi.appendEntry("intercom_inbox_team_denied", { from: from.id, messageId: message.id, error: getErrorMessage(error), timestamp: Date.now() });
+      return;
+    }
     let enqueued;
     try {
       enqueued = inboxAtReceive.enqueue(from, message);
@@ -2226,6 +2254,8 @@ Usage:
       message: Type.Optional(Type.String({
         description: "Message to send (for 'send', 'ask', or 'reply' action)",
       })),
+      team: Type.Optional(Type.String({ description: "Task team for sending or selecting a reply; replies cannot change the original team" })),
+      contextId: Type.Optional(Type.String({ description: "Exact inbound message selector from its reply hint" })),
       attachments: Type.Optional(Type.Array(Type.Object({
         type: StringEnum(["file", "snippet", "context"] as const),
         name: Type.String(),
@@ -2275,7 +2305,7 @@ Usage:
         }
       }
 
-      const { action, to, message, attachments, replyTo, askId, session, which } = params;
+      const { action, to, message, attachments, replyTo, askId, session, which, team, contextId } = params;
 
       switch (action) {
         case "list": {
@@ -2337,6 +2367,10 @@ Usage:
                 details: { error: true },
               };
             }
+            const messageTeam = taskTeamsAvailable()
+              ? resolveNamedMessageTeam(connectedClient.sessionId!, sendTo, team)
+              : undefined;
+            if (!taskTeamsAvailable() && team !== undefined) throw new Error("Named task teams are unavailable in managed-team mode");
             if (!replyTo && config.confirmSend && ctx.hasUI) {
               const attachmentText = attachments?.length ? formatAttachments(attachments) : "";
               const confirmed = await ctx.ui.confirm(
@@ -2352,6 +2386,7 @@ Usage:
             }
             const result = await connectedClient.send(sendTo, {
               text: message,
+              team: messageTeam,
               attachments,
               replyTo,
             });
@@ -2364,7 +2399,7 @@ Usage:
             }
             pi.appendEntry("intercom_sent", {
               to,
-              message: { text: message, attachments, replyTo },
+              message: { text: message, attachments, replyTo, team: messageTeam },
               messageId: result.id,
               timestamp: Date.now(),
             });
@@ -2373,8 +2408,8 @@ Usage:
               inboundInbox?.dismissPendingAsk(replyTo, sendTo);
             }
             return {
-              content: [{ type: "text", text: `Message sent to ${to}` }],
-              details: deliveryResultDetails(result),
+              content: [{ type: "text", text: `Message sent to ${to}${messageTeam ? ` [Team: ${messageTeam}]` : ""}` }],
+              details: deliveryResultDetails(result, messageTeam ? { team: messageTeam } : {}),
             };
           } catch (error) {
             return {
@@ -2406,6 +2441,7 @@ Usage:
           }
           let replyPromise: Promise<Message> | null = null;
           let questionId: string | null = null;
+          let messageTeam: string | undefined;
 
           try {
             const sendTo = await resolveAuthorizedTarget(connectedClient, to);
@@ -2427,12 +2463,17 @@ Usage:
                 details: { error: true },
               };
             }
+            messageTeam = taskTeamsAvailable()
+              ? resolveNamedMessageTeam(connectedClient.sessionId!, sendTo, team)
+              : undefined;
+            if (!taskTeamsAvailable() && team !== undefined) throw new Error("Named task teams are unavailable in managed-team mode");
             questionId = randomUUID();
-            replyPromise = waitForReply(sendTo, questionId, _signal, () => { void connectedClient.cancelAsk(questionId!); });
+            replyPromise = waitForReply(sendTo, questionId, _signal, () => { void connectedClient.cancelAsk(questionId!); }, messageTeam);
             replyPromise.catch(() => undefined);
             const sendResult = await connectedClient.send(sendTo, {
               messageId: questionId,
               text: message,
+              team: messageTeam,
               attachments,
               replyTo,
               expectsReply: true,
@@ -2455,7 +2496,7 @@ Usage:
             }
             pi.appendEntry("intercom_sent", {
               to,
-              message: { text: message, attachments, replyTo },
+              message: { text: message, attachments, replyTo, team: messageTeam },
               messageId: sendResult.id,
               timestamp: Date.now(),
             });
@@ -2466,17 +2507,18 @@ Usage:
               : "";
             pi.appendEntry("intercom_received", {
               from: to,
-              message: { text: replyText, attachments: replyMessage.content.attachments },
+              message: { text: replyText, team: replyMessage.content.team, attachments: replyMessage.content.attachments },
               messageId: replyMessage.id,
               timestamp: replyMessage.timestamp,
             });
             return {
-              content: [{ type: "text", text: `**Reply from ${to}:**\n${replyText}${replyAttachments}` }],
-              details: {},
+              content: [{ type: "text", text: `**${messageTeam ? `[Team: ${messageTeam}] ` : ""}Reply from ${to}:**\n${replyText}${replyAttachments}` }],
+              details: messageTeam ? { team: messageTeam } : {},
             };
           } catch (error) {
             if (error instanceof AskWaitElapsedError) {
-              return deferredAskResult(to, error, await connectedClient.deferAsk(error.replyTo));
+              const deferred = deferredAskResult(to, error, await connectedClient.deferAsk(error.replyTo));
+              return { ...deferred, details: { ...deferred.details, ...(messageTeam ? { team: messageTeam } : {}) } };
             }
             if (questionId) rejectReplyWaiter(questionId, toError(error));
             if (replyPromise) {
@@ -2508,7 +2550,9 @@ Usage:
               if ("code" in requested) throw new BossTeamScopeError(requested.code, requested.error);
               exactReplyTarget = requested.targetId;
             }
-            const target = replyTracker.resolveReplyTarget({ to: exactReplyTarget, replyTo, askId, which });
+            const target = replyTracker.resolveReplyTarget({ to: exactReplyTarget, replyTo, askId, which, team, contextId });
+            const replyTeam = target.message.content.team;
+            if (replyTeam !== undefined) requireNamedTeamMembers(replyTeam, connectedClient.sessionId!, target.from.id);
             if (bossTeamScope.present) {
               const resolution = resolveBossLiveTarget(bossTeamScope, target.from.id, await connectedClient.listSessions(), connectedClient.sessionId);
               if ("code" in resolution) throw new BossTeamScopeError(resolution.code, resolution.error);
@@ -2522,6 +2566,7 @@ Usage:
             const threadedReplyTo = target.message.expectsReply ? target.message.id : undefined;
             const result = await connectedClient.send(target.from.id, {
               text: message,
+              team: replyTeam,
               ...(threadedReplyTo ? { replyTo: threadedReplyTo } : {}),
             });
             if (!result.delivered) {
@@ -2539,17 +2584,17 @@ Usage:
               replyTracker.markReplied(threadedReplyTo, target.from.id);
               inboundInbox?.dismissPendingAsk(threadedReplyTo, target.from.id);
             } else {
-              replyTracker.dismissOrdinarySender(target.from.id);
+              replyTracker.dismissOrdinarySender(target.from.id, target.message.id);
             }
             pi.appendEntry("intercom_sent", {
               to: bossTeamScope.present ? target.from.id : target.from.name || target.from.id,
-              message: { text: message, ...(threadedReplyTo ? { replyTo: threadedReplyTo } : {}) },
+              message: { text: message, team: replyTeam, ...(threadedReplyTo ? { replyTo: threadedReplyTo } : {}) },
               messageId: result.id,
               timestamp: Date.now(),
             });
             return {
-              content: [{ type: "text", text: `Reply sent to ${bossTeamScope.present ? target.from.id : target.from.name || target.from.id}` }],
-              details: deliveryResultDetails(result, threadedReplyTo ? { replyTo: threadedReplyTo } : {}),
+              content: [{ type: "text", text: `Reply sent to ${bossTeamScope.present ? target.from.id : target.from.name || target.from.id}${replyTeam ? ` [Team: ${replyTeam}]` : ""}` }],
+              details: deliveryResultDetails(result, { ...(threadedReplyTo ? { replyTo: threadedReplyTo } : {}), ...(replyTeam ? { team: replyTeam } : {}) }),
             };
           } catch (error) {
             return {
@@ -2621,7 +2666,7 @@ Usage:
               : "";
             const sender = bossTeamScope.present ? ask.from.id : ask.from.name || ask.from.id;
             return {
-              content: [{ type: "text", text: `**Pending ask ${ask.id}**\nInbox: ${inboxSessionId}\nFrom: ${sender}\n\n${ask.message.content.text}${attachmentText}` }],
+              content: [{ type: "text", text: `**Pending ask ${ask.id}**\nInbox: ${inboxSessionId}\nFrom: ${sender}${ask.message.content.team ? `\nTeam: ${ask.message.content.team}` : ""}\n\n${ask.message.content.text}${attachmentText}` }],
               details: {
                 inboxSessionId,
                 ask: {
@@ -2631,6 +2676,7 @@ Usage:
                   ...(ask.deferredAt ? { deferredAt: ask.deferredAt } : {}),
                   preview: ask.preview,
                   body: ask.message.content.text,
+                  ...(ask.message.content.team ? { team: ask.message.content.team } : {}),
                   attachments: ask.message.content.attachments ?? [],
                 },
               },
@@ -2640,7 +2686,7 @@ Usage:
           const lines = asks.map((ask) => {
             const state = ask.deferredAt ? " · async" : "";
             const sender = bossTeamScope.present ? ask.from.id : ask.from.name || ask.from.id;
-            return `- ${ask.id} · ${sender}${ask.selector} · ${ask.elapsedSeconds}s ago${state} · ${ask.preview}`;
+            return `- ${ask.id} · ${sender}${ask.message.content.team ? ` · Team: ${ask.message.content.team}` : ""}${ask.selector} · ${ask.elapsedSeconds}s ago${state} · ${ask.preview}`;
           });
           return {
             content: [{ type: "text", text: `**Pending asks:**\n${lines.join("\n")}` }],
@@ -2652,6 +2698,7 @@ Usage:
                 receivedAt: ask.receivedAt,
                 ...(ask.deferredAt ? { deferredAt: ask.deferredAt } : {}),
                 preview: ask.preview,
+                ...(ask.message.content.team ? { team: ask.message.content.team } : {}),
               })),
             },
           };
@@ -2747,6 +2794,7 @@ Usage:
     promptGuidelines: ["Use intercom_send for progress updates, notifications, and other messages that do not require a conversational reply."],
     parameters: Type.Object({
       to: Type.String({ description: "Required recipient session name or stable session ID" }),
+      team: Type.Optional(Type.String({ description: "Task team name. Required when both sessions share multiple teams." })),
       message: Type.String({ description: "Required message to send" }),
       attachments: attachmentParameters,
     }),
@@ -2763,6 +2811,7 @@ Usage:
     promptGuidelines: ["Use intercom_ask only when work genuinely depends on another session's answer. Use intercom_send for progress checks, status requests, assignments, notifications, and follow-ups. Different recipients may be asked concurrently, but keep only one unresolved ask per recipient."],
     parameters: Type.Object({
       to: Type.String({ description: "Required recipient session name or stable session ID" }),
+      team: Type.Optional(Type.String({ description: "Task team name. Required when both sessions share multiple teams." })),
       message: Type.String({ description: "Required question to ask" }),
       attachments: attachmentParameters,
     }),
@@ -2776,12 +2825,14 @@ Usage:
     label: "Intercom Reply",
     description: "Reply to an inbound intercom message or ask. Exact protocol threading is resolved internally.",
     promptSnippet: "Reply to the active or pending inbound intercom message.",
-    promptGuidelines: ["Use intercom_reply to answer an inbound intercom message. Prefer the stable `askId` returned by intercom_pending when selecting an exact ask; `to` plus `which` remains available for compatibility."],
+    promptGuidelines: ["Use intercom_reply to answer an inbound message, inheriting its original team. Prefer its `contextId` reply hint or the `askId` from intercom_pending. Never route replies using a mutable current team or mix work from different teams."],
     parameters: Type.Object({
       message: Type.String({ description: "Required reply text" }),
       to: Type.Optional(Type.String({ description: "Optional sender/session selector when multiple senders or asks are pending; never a message or thread ID" })),
       which: Type.Optional(StringEnum(["oldest", "latest"] as const, { description: "Select the oldest or latest ask when the chosen sender has multiple unresolved asks" })),
       askId: Type.Optional(Type.String({ description: "Stable ask selector returned by intercom_pending" })),
+      contextId: Type.Optional(Type.String({ description: "Exact inbound message selector from its reply hint, including ordinary messages" })),
+      team: Type.Optional(Type.String({ description: "Select an original-message team; cannot override it" })),
     }),
     execute: executeSplitAction("reply"),
     renderCall: renderSplitCall("reply"),
@@ -2791,11 +2842,11 @@ Usage:
   registerIntercomTool({
     name: "intercom_team",
     label: "Intercom Team",
-    description: "Show your current manager and the live coworkers owned by that manager. No arguments are required.",
-    promptSnippet: "Find your manager and managed coworkers without searching the global peer list.",
-    promptGuidelines: ["Use intercom_team whenever you need your manager's target or the other coworkers in your managed group."],
-    parameters: Type.Object({}),
-    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+    description: "Show all named task teams you belong to, or inspect one by name. Falls back to managed-team discovery when no named task team exists.",
+    promptSnippet: "Find your task teams, managers, and teammates.",
+    promptGuidelines: ["Use intercom_team to inspect your teams. A session can belong to multiple teams, with a different manager in each; specify `team` when the task is ambiguous."],
+    parameters: Type.Object({ team: Type.Optional(Type.String({ description: "Named task team to inspect; omit to show all your teams" })) }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const connectedClient = await ensureConnected("tool");
         syncPresenceIdentity(ctx.sessionManager.getSessionId());
@@ -2804,6 +2855,15 @@ Usage:
           if (selfError) throw new BossTeamScopeError("BOSS_TEAM_METADATA_INVALID", selfError);
         }
         const sessions = await connectedClient.listSessions();
+        if (taskTeamsAvailable()) {
+          const mine = sessionNamedTeams(connectedClient.sessionId!);
+          const selected = params.team === undefined ? mine : mine.filter((entry) => entry.name === params.team);
+          if (params.team !== undefined && selected.length === 0) throw new Error("You are not a member of that task team");
+          if (selected.length > 0) {
+            const teams = selected.map((entry) => namedTeamRoster(entry, connectedClient.sessionId!, sessions));
+            return { content: [{ type: "text", text: teams.map(formatNamedTeamRoster).join("\n\n") }], details: { self: { id: connectedClient.sessionId }, teams } };
+          }
+        } else if (params.team !== undefined) throw new Error("Named task teams are unavailable in Boss mode");
         const team = bossTeamScope.restricted
           ? resolveBossIntercomTeam({ selfId: connectedClient.sessionId, sessions, scope: bossTeamScope })
           : await resolveIntercomTeam({ selfId: connectedClient.sessionId, sessions });
@@ -2827,26 +2887,34 @@ Usage:
     name: "intercom_join",
     executionMode: "sequential",
     label: "Intercom Join",
-    description: "List, join, or create a named intercom team without tmux. Omit name to list joinable teams. Set create=true to create a team and join as manager.",
-    promptSnippet: "Join or create a named intercom team so intercom_team works without tmux.",
+    description: "List, join, or create a task team. Joining appends membership without leaving other named teams. The manager can add connected sessions using members; the creator need not have a session name.",
+    promptSnippet: "After user approval, form a task team with the named sessions they want to collaborate with.",
     promptGuidelines: [
-      "Use intercom_join with no name to list named teams and TmuxDeck workspaces.",
-      "Use intercom_join({ name: \"billing\" }) to join an existing named team or workspace.",
-      "Use intercom_join({ name: \"billing\", create: true }) to create a named team and join as manager.",
+      "For independent Pi sessions: when the user asks you to collaborate with named Pi sessions or delegate work, and this task has no approved team, ask once whether to form a team with you and those sessions (for example: 要把我、front、writer 组成一个 team 来负责这个任务吗？). Wait for approval before creating a team or adding peers.",
+      "An explicit user request to create/join a team is approval. Do not ask again for an approved team or in an inbound team-message turn. If the user declines, do not keep prompting or silently create a team. Without a shared team, send an ungrouped direct message by omitting `team`; belonging to an unrelated team must not prevent initial contact. Explicit team messages still require both sessions to be members.",
+      "After approval, discover the intended sessions, then use intercom_join({ name: \"launch\", create: true, members: [\"front\", \"writer\"], work: \"Current task\" }). The tool adds everyone together; do not ask the user to join each terminal manually.",
+      "Reuse the approved team for the same task and append new approved members. Joining another team preserves previous memberships. The same participants doing a different task may need a different team.",
+      "Pass `team` when sending task messages, especially if peers share multiple teams. Replies inherit their original message's team automatically.",
     ],
     parameters: Type.Object({
       name: Type.Optional(Type.String({ description: "Team name to join. Omit to list joinable teams." })),
       create: Type.Optional(Type.Boolean({ description: "Create this named team and join as manager. Requires name." })),
+      members: Type.Optional(Type.Array(Type.String({ description: "Connected session name or stable ID to add; manager-only, and requires name" }))),
+      work: Type.Optional(Type.String({ description: "Task description when creating a team; requires create=true" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const zh = isZhLocale();
-        if (params.create) {
+        if (params.create || params.members !== undefined || params.work !== undefined) {
           if (typeof params.name !== "string" || !params.name.trim()) {
-            throw new Error(zh ? "创建团队需要名称。" : "Creating a team requires a name.");
+            throw new Error(zh ? "组队需要名称。" : "Forming a team requires a name.");
           }
-          const text = await createAndJoinNamedTeam(ctx, params.name);
-          return { content: [{ type: "text", text }] };
+          const team = await appendTaskTeam(ctx, params.name, params.create === true, params.members ?? [], params.work);
+          const roster = namedTeamRoster(team, currentSessionId!, await client!.listSessions());
+          const text = params.create
+            ? formatCreateSuccess({ team: team.name, name: currentDisplayName(), zh })
+            : formatNamedJoinSuccess({ team: team.name, name: currentDisplayName(), zh });
+          return { content: [{ type: "text", text: `${text}\n\n${formatNamedTeamRoster(roster)}` }], details: { team: roster } };
         }
         const text = await listOrJoinCircle(ctx, typeof params.name === "string" ? params.name : "");
         return { content: [{ type: "text", text }] };
@@ -3078,6 +3146,11 @@ Usage:
       const zh = isZhLocale();
       try {
         const membership = classifyMembership();
+        const taskTeams = currentSessionId ? sessionNamedTeams(currentSessionId) : [];
+        if (taskTeams.length > 0 && taskTeamsAvailable()) {
+          notifyIfLive(ctx, `${zh ? "任务团队" : "Task teams"}: ${taskTeams.map((entry) => entry.name).join(", ")}\n${zh ? "你的显示名" : "Display name"}: ${currentDisplayName()}`, "info");
+          return;
+        }
         const namedTeam = runtimeScopeId ? findNamedTeamByScope(runtimeScopeId) : undefined;
         const workspace = namedTeam?.name
           ? undefined

package/named-team-membership.ts

@@ -0,0 +1,124 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { ensureIntercomRuntimeDir, getAgentDirPath, getIntercomDirPath } from "./broker/paths.ts";
+import { writeDurableJson } from "./durable-json.ts";
+import { generateNamedTeamScope, listNamedTeams, NAMED_TEAMS_FILE, NAMED_TEAMS_VERSION, parseTeamName, type NamedTeam } from "./named-teams.ts";
+import type { SessionInfo } from "./types.ts";
+
+export function namedTeamMemberIds(team: NamedTeam): string[] {
+  return team.memberSessionIds ?? [team.managerSessionId];
+}
+
+export function sessionNamedTeams(sessionId: string, agentDir?: string): NamedTeam[] {
+  return listNamedTeams(agentDir).filter((team) => namedTeamMemberIds(team).includes(sessionId));
+}
+
+/** Serialize the complete read-modify-write across independently launched Pi processes. */
+export async function appendNamedTeamMembership(input: {
+  name: string;
+  selfId: string;
+  members?: string[];
+  create?: boolean;
+  work?: string;
+  agentDir?: string;
+}): Promise<NamedTeam> {
+  const name = parseTeamName(input.name);
+  const memberIds = [...new Set([input.selfId, ...(input.members ?? [])])];
+  if (memberIds.some((id) => !id || id.trim() !== id || /[\u0000-\u001f\u007f]/.test(id))) {
+    throw new Error("Invalid team member session ID");
+  }
+  if (input.work !== undefined && (!input.work.trim() || input.work.length > 2000)) {
+    throw new Error("Work must be a non-empty task description (max 2000 characters)");
+  }
+  const dir = getIntercomDirPath(input.agentDir ?? getAgentDirPath());
+  ensureIntercomRuntimeDir(dir);
+  const lock = join(dir, "named-teams.lock");
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    try {
+      mkdirSync(lock, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) throw new Error("Team registry is busy; retry. If a writer crashed, remove the stale named-teams.lock directory after verifying no writer is active.");
+      await delay(25);
+    }
+  }
+  try {
+    const teams = listNamedTeams(input.agentDir);
+    let team = teams.find((entry) => entry.name === name);
+    if (input.create) {
+      if (team) throw new Error(`A named team called ${name} already exists; join it instead.`);
+      team = { name, scopeId: generateNamedTeamScope(teams.map((entry) => entry.scopeId)), managerSessionId: input.selfId, createdAt: Date.now() };
+      teams.push(team);
+    }
+    if (!team) throw new Error(`Team "${name}" does not exist; create it explicitly.`);
+    if (memberIds.some((id) => id !== input.selfId) && team.managerSessionId !== input.selfId) {
+      throw new Error(`Only the manager of team "${name}" may add other sessions`);
+    }
+    if (input.work !== undefined && !input.create) {
+      throw new Error("Work is set when creating a team; use a new team for a different task");
+    }
+    const updated: NamedTeam = {
+      ...team,
+      memberSessionIds: [...new Set([...namedTeamMemberIds(team), ...memberIds])],
+      ...(input.work === undefined ? {} : { work: input.work.trim() }),
+    };
+    writeDurableJson(join(dir, NAMED_TEAMS_FILE), {
+      version: NAMED_TEAMS_VERSION,
+      teams: teams.map((entry) => entry.name === name ? updated : entry),
+    });
+    return updated;
+  } finally {
+    rmSync(lock, { recursive: true });
+  }
+}
+
+export function requireNamedTeamMembers(name: string, selfId: string, peerId: string, agentDir?: string): NamedTeam {
+  const team = listNamedTeams(agentDir).find((entry) => entry.name === name);
+  if (!team) throw new Error(`Unknown team "${name}"`);
+  const members = namedTeamMemberIds(team);
+  if (!members.includes(selfId) || !members.includes(peerId)) {
+    throw new Error(`Both sessions must belong to team "${name}" before messaging`);
+  }
+  return team;
+}
+
+export function resolveNamedMessageTeam(selfId: string, peerId: string, requested?: string, agentDir?: string): string | undefined {
+  if (requested !== undefined) return requireNamedTeamMembers(requested, selfId, peerId, agentDir).name;
+  const mine = sessionNamedTeams(selfId, agentDir);
+  const shared = mine.filter((team) => namedTeamMemberIds(team).includes(peerId));
+  if (shared.length === 1) return shared[0]!.name;
+  if (shared.length > 1) throw new Error("Multiple shared teams; specify `team` for this task");
+  // No shared team means an ungrouped contact, even when either session belongs
+  // to unrelated teams. Do not silently create a team or add the recipient.
+  return undefined;
+}
+
+export function namedTeamRoster(team: NamedTeam, selfId: string, sessions: SessionInfo[]) {
+  return {
+    name: team.name,
+    ...(team.work ? { work: team.work } : {}),
+    self: { id: selfId, isManager: selfId === team.managerSessionId },
+    manager: { target: team.managerSessionId, connected: sessions.some((entry) => entry.id === team.managerSessionId) },
+    members: namedTeamMemberIds(team).map((id) => ({
+      id,
+      target: id,
+      name: sessions.find((entry) => entry.id === id)?.name,
+      role: id === team.managerSessionId ? "manager" : "member",
+      connected: sessions.some((entry) => entry.id === id),
+    })),
+  };
+}
+
+export function formatNamedTeamRoster(team: ReturnType<typeof namedTeamRoster>): string {
+  return [
+    `Team: ${team.name}`,
+    ...(team.work ? [`Work: ${team.work}`] : []),
+    `You: ${team.self.id}${team.self.isManager ? " [manager]" : ""}`,
+    `Manager: ${team.manager.target}${team.manager.connected ? "" : " [offline]"}`,
+    "Members:",
+    ...team.members.map((member) => `- ${member.name || member.id} (${member.id}) [${member.role}]${member.connected ? "" : " [offline]"}`),
+  ].join("\n");
+}

package/named-teams.ts

@@ -14,6 +14,9 @@ export interface NamedTeam {
   scopeId: string;
   managerSessionId: string;
   createdAt: number;
+  /** Pi task-team membership; absent in legacy single-scope teams. */
+  memberSessionIds?: string[];
+  work?: string;
 }
 
 export type JoinableCircleKind = "named" | "tmuxdeck";
@@ -57,11 +60,20 @@ function parseStoredTeam(value: unknown): NamedTeam | undefined {
   if (typeof value.createdAt !== "number" || !Number.isSafeInteger(value.createdAt) || value.createdAt <= 0) {
     return undefined;
   }
+  if (value.memberSessionIds !== undefined && (
+    !Array.isArray(value.memberSessionIds)
+    || !value.memberSessionIds.every((id) => typeof id === "string" && id.trim() === id && id.length > 0 && !/[\u0000-\u001f\u007f]/.test(id))
+    || new Set(value.memberSessionIds).size !== value.memberSessionIds.length
+    || !value.memberSessionIds.includes(value.managerSessionId)
+  )) return undefined;
+  if (value.work !== undefined && (typeof value.work !== "string" || !value.work.trim() || value.work.length > 2000)) return undefined;
   return {
     name: value.name,
     scopeId: value.scopeId,
     managerSessionId: value.managerSessionId,
     createdAt: value.createdAt,
+    ...(value.memberSessionIds === undefined ? {} : { memberSessionIds: value.memberSessionIds as string[] }),
+    ...(value.work === undefined ? {} : { work: value.work as string }),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Pi coding-agent intercom for local messaging with Codex, Claude Code, OpenCode, Grok Build, and AGY agents.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -58,14 +58,20 @@
   },
   "dependencies": {
     "@ctliz/agent-intercom-core": "0.2.0",
-    "@earendil-works/pi-ai": "^0.99.1",
-    "@earendil-works/pi-coding-agent": "^0.99.1",
-    "@earendil-works/pi-tui": "^0.99.1",
-    "tsx": "^4.20.0",
+    "tsx": "^4.20.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@types/node": "^22.15.0",
+    "typebox": "*",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/reply-tracker.ts

@@ -21,6 +21,10 @@ export function pendingAskId(fromSessionId: string, messageId: string): string {
   return `ask-${digest}`;
 }
 
+export function replyContextId(fromSessionId: string, messageId: string): string {
+  return pendingAskId(fromSessionId, messageId).replace(/^ask-/, "ctx-");
+}
+
 function matchesPendingSender(context: IntercomContext, to: string): boolean {
   if (context.from.id === to) {
     return true;
@@ -91,8 +95,23 @@ export class ReplyTracker {
     this.currentTurnContexts = [];
   }
 
-  resolveReplyTarget(options: { to?: string; replyTo?: string; askId?: string; which?: ReplyWhich }, now = Date.now()): IntercomContext {
+  resolveReplyTarget(options: { to?: string; replyTo?: string; askId?: string; which?: ReplyWhich; team?: string; contextId?: string }, now = Date.now()): IntercomContext {
     this.pruneExpired(now);
+    const checkTeam = (context: IntercomContext): IntercomContext => {
+      if (options.team !== undefined && context.message.content.team !== options.team) {
+        throw new Error("Reply team must match the original message; it cannot be changed");
+      }
+      return context;
+    };
+    if (options.contextId) {
+      const match = [...this.currentTurnContexts, ...this.pendingAsks.values()].find((context) =>
+        replyContextId(context.from.id, context.message.id) === options.contextId
+      );
+      if (!match) throw new Error(`No active message with context ID "${options.contextId}"`);
+      if (options.to && !matchesPendingSender(match, options.to)) throw new Error("Reply context is not from the selected sender");
+      if (options.askId && pendingAskId(match.from.id, match.message.id) !== options.askId) throw new Error("Reply selectors refer to different messages");
+      return checkTeam(match);
+    }
 
     if (options.askId) {
       const match = Array.from(this.pendingAsks.values()).find((context) =>
@@ -104,7 +123,7 @@ export class ReplyTracker {
       if (options.to && !matchesPendingSender(match, options.to)) {
         throw new Error(`Pending ask "${options.askId}" is not from "${options.to}"`);
       }
-      return match;
+      return checkTeam(match);
     }
 
     if (options.replyTo) {
@@ -119,13 +138,18 @@ export class ReplyTracker {
       if (matches.length > 1) {
         throw new Error(`Multiple pending asks use message ID "${options.replyTo}" — specify \`to\``);
       }
-      return matches[0]!;
+      return checkTeam(matches[0]!);
     }
 
-    if (this.currentTurnContexts.length > 0) {
+    const inTeam = (context: IntercomContext) => options.team === undefined || context.message.content.team === options.team;
+    const currentTurnContexts = this.currentTurnContexts.filter(inTeam);
+    if (currentTurnContexts.length > 0) {
       const turnMatches = options.to
-        ? this.currentTurnContexts.filter((context) => matchesPendingSender(context, options.to!))
-        : this.currentTurnContexts;
+        ? currentTurnContexts.filter((context) => matchesPendingSender(context, options.to!))
+        : currentTurnContexts;
+      if (new Set(turnMatches.map((context) => context.message.content.team)).size > 1) {
+        throw new Error("Messages from multiple teams are active — specify `contextId`, `askId`, or `team`");
+      }
       const replyableMatches = turnMatches.filter((context) => context.message.expectsReply);
       if (replyableMatches.length === 1) {
         return replyableMatches[0]!;
@@ -146,14 +170,13 @@ export class ReplyTracker {
       }
     }
 
-    const pending = Array.from(this.pendingAsks.values());
-    if (pending.length === 1) {
-      return pending[0]!;
-    }
-
+    const pending = Array.from(this.pendingAsks.values()).filter(inTeam);
     const matches = options.to
       ? pending.filter((context) => matchesPendingSender(context, options.to!))
       : pending;
+    if (new Set(matches.map((context) => context.message.content.team)).size > 1) {
+      throw new Error("Pending asks belong to multiple teams — specify `askId` or `team`");
+    }
     if (matches.length === 1) return matches[0]!;
     if (matches.length > 1) {
       if (!options.to && distinctSenders(matches) > 1) {
@@ -174,9 +197,9 @@ export class ReplyTracker {
     this.dismissPendingAsk(replyTo, fromSessionId);
   }
 
-  dismissOrdinarySender(fromSessionId: string): void {
+  dismissOrdinarySender(fromSessionId: string, messageId?: string): void {
     this.currentTurnContexts = this.currentTurnContexts.filter((context) =>
-      context.message.expectsReply || context.from.id !== fromSessionId
+      context.message.expectsReply || context.from.id !== fromSessionId || (messageId !== undefined && context.message.id !== messageId)
     );
   }
 

package/skills/pi-intercom/SKILL.md

@@ -2,8 +2,8 @@
 name: pi-intercom
 description: |
   Streamline session-to-session coordination with pi-intercom. Send messages,
-  delegate tasks, and coordinate work across multiple pi sessions on the same
-  machine. Use for planner-worker workflows, cross-session context sharing,
+  delegate tasks, and form task teams after user approval across multiple Pi
+  sessions on the same machine. Use for planner-worker workflows, cross-session context sharing,
   and real-time collaboration between sessions.
 ---
 
@@ -24,6 +24,60 @@ This skill covers how to handle those orchestrator-side escalations.
 - **Clarification loops**: Worker asks questions, planner answers, work continues
 - **Multi-session workflows**: Coordinate between specialized sessions (frontend/backend, research/implementation)
 
+## Task Teams: Ask Once, Then Organize (Pi 0.14+)
+
+Independently opened Pi sessions do not form a team merely by sharing a directory.
+When the user asks you to collaborate with named sessions (for example `front`
+and `writer`) or delegate work, and this task has no approved team, ask once:
+
+> 要把我、front、writer 组成一个 team 来负责这个任务吗？
+
+Wait for approval before creating a team or adding peers. An explicit instruction
+to create/join a team is already approval. Do not ask again for the same approved
+team, and do not prompt the user when replying to an inbound team message. If the
+user declines, do not repeatedly ask or silently create a team. Without a shared
+team, omit `team` to send an ungrouped direct message, even if either session
+belongs to unrelated teams. This allows initial contact before forming a team.
+Explicit team messages still require both sessions to be members; multiple
+shared teams still require selecting the intended task team.
+
+After approval, discover the named sessions and form the team in one operation:
+
+```typescript
+intercom_list({})
+intercom_join({
+  name: "launch",
+  create: true,
+  members: ["front", "writer"],
+  work: "Build the product page; front owns UI, writer owns copy",
+})
+intercom_send({ team: "launch", to: "front", message: "Implement the product page UI." })
+intercom_send({ team: "launch", to: "writer", message: "Write the product page copy." })
+```
+
+The creator is the manager of this task team and does not need a `/name`.
+Members are resolved to stable session IDs; no user needs to join each terminal
+manually. Only the manager can add other sessions with `members`; a session can
+join itself with `intercom_join({ name: "launch" })`. Joining appends membership
+without leaving other named teams or changing their managers. The approved
+manager can append a new approved peer with
+`intercom_join({ name: "launch", members: ["reviewer"] })`.
+
+Reuse the team for this task, not for every message. A different task may need a
+different team even with identical participants. `intercom_team({})` shows all
+your named teams; `intercom_team({ team: "launch" })` inspects one.
+
+Messages carry their team separately from their text. Read each `[Team: ...]`
+label independently, including mixed-team batches. Use the exact `contextId`
+reply hint to answer ordinary messages, or `askId` from `intercom_pending` for
+asks. `intercom_reply` inherits the original message's team; never choose a reply
+team using a mutable current-team setting. When peers share multiple teams,
+explicitly pass `team` to sends and asks. Ambiguous replies fail rather than guess.
+
+This is Pi-local task grouping, not a broker security boundary or separate model
+history for each team. Other adapters and managed-team integrations are unchanged;
+all participating Pi sessions must load adapter 0.14.0 or newer.
+
 ## Codemode (Pi 0.99.1+)
 
 Active Intercom tools can be called from codemode as `await tools.intercom_send({...})`, `await tools.intercom_team({})`, and so on. Every result is `{ ok, text, data }`: check `ok`, then read structured delivery flags, session lists, team roster, or pending asks from `data`. Returned errors retain this object; invalid arguments, blocked calls, and thrown exceptions can still reject. Use `try/catch` or `Promise.allSettled()` for independent operations.
@@ -91,12 +145,11 @@ Do not add artificial sleeps to form a batch. Each original message keeps its se
 
 ### Pattern 3: Find Your Manager or Team
 
-If no team exists yet, create one and have the other session join. This does not require tmux:
+For independent Pi sessions, ask for approval first, then create a task team and add the connected peer:
 
 ```typescript
-intercom_join({ name: "billing", create: true })  // manager
-intercom_join({ name: "billing" })                 // other session
-intercom_team({})
+intercom_join({ name: "billing", create: true, members: ["worker"], work: "Implement billing" })
+intercom_team({ team: "billing" })
 ```
 
 `/intercom-create billing` and `/intercom-join billing` do the same from the command line. `intercom_join({})` lists named teams and TmuxDeck workspaces without printing raw scopes.
@@ -135,7 +188,7 @@ intercom_pending({ askId: "ask-..." }) // Retrieve the full untruncated body whe
 intercom_reply({ askId: "ask-...", message: "Use exponential backoff starting at 100ms." })
 ```
 
-`intercom_reply` preserves exact threading internally. `intercom_pending` returns stable receiver-local ask IDs and short previews; models never see or construct the protocol message ID. Managers can pass `session` with an owned coworker target from `intercom_team` to inspect that coworker's pending inbox.
+`intercom_reply` preserves exact threading and the original team internally. Team-message reply hints provide an exact receiver-local `contextId`, including for ordinary messages. `intercom_pending` returns stable receiver-local ask IDs, team labels, and short previews; models never see or construct the protocol message ID. Managers can pass `session` with an owned coworker target from `intercom_team` to inspect that coworker's pending inbox.
 
 ### Pattern 5: Broadcast to Multiple Workers
 

package/types.ts

@@ -36,6 +36,8 @@ export interface Message {
   expectsReply?: boolean;
   content: {
     text: string;
+    /** Public, immutable task-team name; not a broker registration scope. */
+    team?: string;
     attachments?: Attachment[];
     control?: IntercomCommonControlEnvelope;
   };

package/ui/inline-message.ts

@@ -47,7 +47,8 @@ export class InlineMessageComponent implements Component {
     }
     const bodyWidth = Math.max(1, width - 2);
 
-    const header = ` 📨 From: ${senderName} (${senderCwd}) `;
+    const teamLabel = this.message.content.team ? `[Team: ${sanitizeDisplayText(this.message.content.team)}] ` : "";
+    const header = ` ${teamLabel}📨 From: ${senderName} (${senderCwd}) `;
     const headerText = truncateToWidth(this.collapsed ? `${header} Ctrl+O expands ` : header, bodyWidth, "");
     const headerPadding = Math.max(0, bodyWidth - visibleWidth(headerText));
     lines.push(this.theme.fg("accent", `╭${headerText}${borderChar.repeat(headerPadding)}╮`));