@ctliz/agent-intercom-codex 0.12.2 → 0.13.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-intercom",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Codex MCP plugin and bridge daemon for local Pi/Codex intercom messaging.",
   "author": {
     "name": "ctliz",

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.13.0 - 2026-10-02
+
+- Add additive task teams shared with Pi, Claude, and OpenCode; managers can add connected peers and task descriptions in one call without changing registration scopes.
+- Expose exact pending ask/context selectors; ordinary-message replies and blocking-ask replies inherit the original task team, never a mutable current team.
+- Preserve teams in app-server worker replies and tools; add one-time approval guidance and allow initial contact across unrelated memberships.
+
 ## 0.12.2 - 2026-09-30
 
 - Synchronize native `thread/name/updated` notifications into Intercom presence without changing stable session IDs; retain the updated name on broker reconnect.

package/README.md

@@ -186,15 +186,26 @@ intercom tools.
 ## Tools
 
 - `intercom_whoami`: show this session's intercom ID, name, cwd, and model.
-- `intercom_team`: show the current manager and live coworkers owned by that manager.
-- `intercom_join`: list, join, or create a named team without tmux (`create: true` joins as manager).
+- `intercom_team({ team? })`: show all named task memberships, inspect one team, or fall back to managed-team discovery.
+- `intercom_join({ name?, create?, members?, work? })`: add task-team membership without leaving earlier teams; managers add connected peers in one call.
 - `intercom_status`: show connection status and pending message counts.
 - `intercom_list`: list local Pi, Codex, Claude Code, and OpenCode sessions in your scope (protocol v4 is same-scope; cross-scope contact requires an exact full session ID).
 - `intercom_set_summary`: publish a short discoverable status.
 - `intercom_send`: send a non-blocking message.
 - `intercom_ask`: send a question and wait for the target's reply.
 - `intercom_pending`: read queued inbound messages and unresolved asks.
-- `intercom_reply`: reply to a pending inbound ask; use `to` plus `which: "oldest" | "latest"` if one sender has multiple unresolved asks.
+- `intercom_reply`: reply to an inbound ask or ordinary message via `askId` or `contextId` from `intercom_pending`; replies inherit the original team. Within one task, `to` plus `which: "oldest" | "latest"` also selects an ask.
+
+### Task teams
+
+When the user delegates to named peers, the agent asks once whether to form a team for this task and waits for approval. Explicit create/join requests are already approval; approved tasks and inbound team messages do not prompt again. Discover the peers, then add everyone in one call:
+
+```typescript
+intercom_join({ name: "launch", create: true, members: ["front", "writer"], work: "Launch page" })
+intercom_send({ to: "front", team: "launch", message: "Implement the header." })
+```
+
+Membership and roles are per task and additive; joining preserves earlier teams and registration scope. Reuse an approved team for the same task and append approved peers as manager. For initial contact without a shared team, omit `team`; unrelated memberships do not block messaging or silently create teams. Multiple shared teams require `team` on sends/asks. Replies retain the original message's team via exact selectors, not a mutable current team. App-server workers also retain the team on automatic replies.
 
 Pending output never exposes protocol message IDs. Keep at most one unresolved `intercom_ask` to the same recipient; the broker rejects a second ask and recommends `intercom_send` for a non-blocking follow-up. Use `intercom_send`—not `intercom_ask`—for assignments and progress/status checkpoints.
 

package/broker/broker.ts

@@ -240,6 +240,7 @@ 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;
   return content.attachments === undefined
     || (
       Array.isArray(content.attachments)

package/broker/client.ts

@@ -41,6 +41,7 @@ import type {
 
 export interface SendOptions {
   text: string;
+  team?: string;
   attachments?: Attachment[];
   replyTo?: string;
   expectsReply?: boolean;
@@ -134,6 +135,7 @@ 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;
   return content.attachments === undefined
     || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
 }
@@ -905,6 +907,7 @@ export class IntercomClient extends EventEmitter {
       expectsReply: options.expectsReply,
       content: {
         text: options.text,
+        ...(options.team === undefined ? {} : { team: options.team }),
         attachments: options.attachments,
       },
     };

package/codex/bridge-daemon.ts

@@ -23,6 +23,9 @@ import type { Message, SessionInfo } from "../types.ts";
 import { resolveContactTarget, type IntercomContact } from "./contact.ts";
 import { formatAttachments, formatSessionDisplay, formatSessionList, resolveSessionTarget, type ToolResult } from "./runtime.ts";
 import { formatIntercomTeam, resolveIntercomTeam } from "./team.ts";
+import { appendNamedTeamMembership, sessionNamedTeams, namedTeamRoster, formatNamedTeamRoster, resolveNamedMessageTeam } from "./named-team-membership.ts";
+import { formatJoinableNamedTeamList, listNamedTeams } from "./named-teams.ts";
+import { TASK_TEAM_GUIDANCE } from "./team-guidance.ts";
 
 interface TurnWaiter {
   from: SessionInfo;
@@ -31,6 +34,7 @@ interface TurnWaiter {
 
 interface ToolReplyWaiter {
   from: string;
+  team?: string;
   resolve: (message: Message) => void;
   reject: (error: Error) => void;
   timeout: NodeJS.Timeout;
@@ -58,6 +62,7 @@ export interface VirtualCodexAgentOptions {
 const APPROVED_INTERCOM_TOOLS = new Set([
   "intercom_whoami",
   "intercom_team",
+  "intercom_join",
   "intercom_status",
   "intercom_list",
   "intercom_set_summary",
@@ -88,6 +93,7 @@ function formatMessage(from: SessionInfo, message: Message, agent: BridgeAgentCo
   return [
     `Intercom message for ${agent.name}.`,
     `From: ${formatSessionDisplay(from)} (${from.id})`,
+    ...(message.content.team ? [`[Team: ${message.content.team}]`] : []),
     `Message id: ${message.id}`,
     "",
     message.content.text,
@@ -191,7 +197,7 @@ function getCompletedAgentText(params: unknown): string | null {
   return raw.type === "agentMessage" && typeof raw.text === "string" ? raw.text : null;
 }
 
-function intercomSendFromArgs(rawArgs: unknown): { to: string; message: string } | null {
+function intercomSendFromArgs(rawArgs: unknown): { to: string; message: string; team?: string } | null {
   let args: Record<string, unknown>;
   try {
     args = parseToolArguments(rawArgs);
@@ -199,11 +205,11 @@ function intercomSendFromArgs(rawArgs: unknown): { to: string; message: string }
     return null;
   }
   return typeof args.to === "string" && typeof args.message === "string"
-    ? { to: args.to, message: args.message }
+    ? { to: args.to, message: args.message, ...(typeof args.team === "string" ? { team: args.team } : {}) }
     : null;
 }
 
-export function getCompletedIntercomSend(params: unknown): { to: string; message: string } | null {
+export function getCompletedIntercomSend(params: unknown): { to: string; message: string; team?: string } | null {
   if (!params || typeof params !== "object") return null;
   const item = (params as Record<string, unknown>).item;
   if (!isRecord(item)) return null;
@@ -212,7 +218,7 @@ export function getCompletedIntercomSend(params: unknown): { to: string; message
   return intercomSendFromArgs(item.arguments ?? item.args ?? item.input);
 }
 
-export function getApprovedIntercomSend(params: unknown): { to: string; message: string } | null {
+export function getApprovedIntercomSend(params: unknown): { to: string; message: string; team?: string } | null {
   if (getApprovedIntercomToolFromApproval(params) !== "intercom_send") return null;
   if (!isRecord(params)) return null;
   const meta = isRecord(params._meta) ? params._meta : {};
@@ -234,7 +240,7 @@ function asOptionalPositiveInteger(value: unknown, name: string): number | undef
 }
 
 function normalizeToolName(name: string): string {
-  const mcpMatch = name.match(/(?:^|__|\.)intercom_(whoami|status|list|set_summary|send|ask|pending|reply)$/);
+  const mcpMatch = name.match(/(?:^|__|\.)intercom_(whoami|team|join|status|list|set_summary|send|ask|pending|reply)$/);
   if (mcpMatch) return `intercom_${mcpMatch[1]}`;
   return name;
 }
@@ -511,7 +517,7 @@ export class VirtualCodexAgent {
       approvalPolicy: bridgeAgentApprovalPolicy(this.agent),
       sandbox,
       serviceName: "codex-intercom",
-      developerInstructions: this.agent.instructions ?? null,
+      developerInstructions: [this.agent.instructions, TASK_TEAM_GUIDANCE].filter(Boolean).join("\n\n"),
       threadSource: "cli",
     });
     this.threadId = getThreadId(result);
@@ -525,7 +531,7 @@ export class VirtualCodexAgent {
   private routeMessage(from: SessionInfo, message: Message): Promise<void> {
     const toolWaiter = this.toolReplyWaiters.get(message.replyTo ?? "");
     if (toolWaiter) {
-      if (from.id === toolWaiter.from) {
+      if (from.id === toolWaiter.from && message.content.team === toolWaiter.team) {
         this.toolReplyWaiters.delete(message.replyTo ?? "");
         clearTimeout(toolWaiter.timeout);
         toolWaiter.cleanup?.();
@@ -578,18 +584,22 @@ export class VirtualCodexAgent {
     this.waiters.delete(turnId);
     const reply = this.finalMessages.get(turnId)?.trim() || "Codex turn completed without a final message.";
     for (const waiter of waiters) {
-      await this.client.send(waiter.from.id, { text: reply, replyTo: waiter.message.id }).catch((error) => {
+      await this.client.send(waiter.from.id, { text: reply, replyTo: waiter.message.id, team: waiter.message.content.team }).catch((error) => {
         process.stderr.write(`reply failed for ${this.agent.id}: ${error instanceof Error ? error.message : String(error)}\n`);
       });
     }
   }
 
-  async replyToWaitersFromIntercomSend(turnId: string, send: { to: string; message: string }): Promise<void> {
+  async replyToWaitersFromIntercomSend(turnId: string, send: { to: string; message: string; team?: string }): Promise<void> {
     const waiters = this.waiters.get(turnId);
     if (!waiters?.length) return;
     const lowerTo = send.to.toLowerCase();
     const remaining: TurnWaiter[] = [];
     for (const waiter of waiters) {
+      if (send.team !== undefined && send.team !== waiter.message.content.team) {
+        remaining.push(waiter);
+        continue;
+      }
       const matchesSender = send.to === waiter.from.id
         || waiter.from.id.startsWith(send.to)
         || waiter.from.name?.toLowerCase() === lowerTo;
@@ -597,7 +607,7 @@ export class VirtualCodexAgent {
         remaining.push(waiter);
         continue;
       }
-      await this.client.send(waiter.from.id, { text: send.message, replyTo: waiter.message.id }).catch((error) => {
+      await this.client.send(waiter.from.id, { text: send.message, replyTo: waiter.message.id, team: waiter.message.content.team }).catch((error) => {
         remaining.push(waiter);
         process.stderr.write(`reply failed for ${this.agent.id}: ${error instanceof Error ? error.message : String(error)}\n`);
       });
@@ -664,8 +674,32 @@ export class VirtualCodexAgent {
           `session_id: ${this.agent.id}\nname: ${this.agent.name}\ncwd: ${this.agent.cwd}`,
           { session_id: this.agent.id, name: this.agent.name, cwd: this.agent.cwd, model: this.agent.model ?? "codex-app-server" },
         );
+      case "intercom_join": {
+        if (args.name === undefined) {
+          if (args.create || args.members !== undefined || args.work !== undefined) throw new Error("Creating or extending a team requires a name");
+          return textToolResult(formatJoinableNamedTeamList(listNamedTeams()));
+        }
+        if (args.members !== undefined && !Array.isArray(args.members)) throw new Error("members must be an array");
+        const sessions = await this.client.listSessions();
+        const members = Array.from((args.members ?? []) as unknown[], (member) => {
+          const id = resolveSessionTarget(sessions, asString(member, "member"));
+          if (!id) throw new Error("Team member is not connected");
+          return id;
+        });
+        const team = await appendNamedTeamMembership({ name: asString(args.name, "name"), selfId: this.agent.id, members, create: args.create === true, ...(args.work === undefined ? {} : { work: asString(args.work, "work") }) });
+        const roster = namedTeamRoster(team, this.agent.id, sessions);
+        return textToolResult(formatNamedTeamRoster(roster), { ok: true, team: team.name, roster });
+      }
       case "intercom_team": {
         const sessions = await this.client.listSessions();
+        const mine = sessionNamedTeams(this.agent.id);
+        const requested = args.team === undefined ? undefined : asString(args.team, "team");
+        const selected = requested ? mine.filter((entry) => entry.name === requested) : mine;
+        if (requested && !selected.length) throw new Error("You do not belong to that team");
+        if (selected.length) {
+          const teams = selected.map((entry) => namedTeamRoster(entry, this.agent.id, sessions));
+          return textToolResult(teams.map(formatNamedTeamRoster).join("\n\n"), { teams });
+        }
         const team = await resolveIntercomTeam({ selfId: this.agent.id, sessions });
         return textToolResult(formatIntercomTeam(team), team as unknown as Record<string, unknown>);
       }
@@ -692,7 +726,8 @@ export class VirtualCodexAgent {
         const to = asString(args.to, "to");
         const message = asString(args.message, "message");
         const sendTo = await this.resolveTarget(to);
-        const result = await this.client.send(sendTo, { text: message });
+        const team = resolveNamedMessageTeam(this.agent.id, sendTo, args.team === undefined ? undefined : asString(args.team, "team"));
+        const result = await this.client.send(sendTo, { text: message, team });
         if (!result.delivered) {
           return textToolResult(`Message to "${to}" was not delivered: ${result.reason ?? "Session may not exist or has disconnected."}`, { ok: false, message_id: result.id, reason: result.reason }, true);
         }
@@ -705,10 +740,11 @@ export class VirtualCodexAgent {
         const message = asString(args.message, "message");
         const timeoutMs = asOptionalPositiveInteger(args.timeout_ms, "timeout_ms") ?? DEFAULT_ASK_TIMEOUT_MS;
         const sendTo = await this.resolveTarget(to);
+        const team = resolveNamedMessageTeam(this.agent.id, sendTo, args.team === undefined ? undefined : asString(args.team, "team"));
         const questionId = randomUUID();
-        const replyPromise = this.waitForToolReply(sendTo, questionId, timeoutMs, signal);
+        const replyPromise = this.waitForToolReply(sendTo, questionId, timeoutMs, signal, team);
         void replyPromise.catch(() => undefined);
-        const result = await this.client.send(sendTo, { messageId: questionId, text: message, expectsReply: true });
+        const result = await this.client.send(sendTo, { messageId: questionId, text: message, expectsReply: true, team });
         if (!result.delivered) {
           this.rejectToolReply(questionId, new Error(result.reason ?? "Session may not exist or has disconnected."));
           return textToolResult(`Message to "${to}" was not delivered: ${result.reason ?? "Session may not exist or has disconnected."}`, { ok: false, message_id: result.id, reason: result.reason }, true);
@@ -748,7 +784,7 @@ export class VirtualCodexAgent {
     return resolveSessionTarget(sessions, to) ?? to;
   }
 
-  private waitForToolReply(from: string, replyTo: string, timeoutMs = DEFAULT_ASK_TIMEOUT_MS, signal?: AbortSignal): Promise<Message> {
+  private waitForToolReply(from: string, replyTo: string, timeoutMs = DEFAULT_ASK_TIMEOUT_MS, signal?: AbortSignal, team?: string): Promise<Message> {
     return new Promise((resolve, reject) => {
       if (signal?.aborted) {
         reject(new Error("intercom_ask cancelled"));
@@ -772,7 +808,7 @@ export class VirtualCodexAgent {
         reject(new Error(`No reply from "${from}" within ${Math.round(timeoutMs / 1000)} seconds`));
       }, timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
-      this.toolReplyWaiters.set(replyTo, { from, resolve, reject, timeout, cleanup });
+      this.toolReplyWaiters.set(replyTo, { from, team, resolve, reject, timeout, cleanup });
     });
   }
 

package/codex/mcp-protocol.ts

@@ -1,5 +1,6 @@
 import type { CodexIntercomRuntime, ToolResult } from "./runtime.ts";
 import { validateAskTimeoutMs } from "../config.ts";
+import { TASK_TEAM_GUIDANCE } from "./team-guidance.ts";
 import type { Attachment } from "../types.ts";
 
 interface JsonRpcRequest {
@@ -34,6 +35,16 @@ function asString(value: unknown, name: string): string {
   return value;
 }
 
+function optionalString(value: unknown, name: string): string | undefined {
+  return value === undefined ? undefined : asString(value, name);
+}
+
+function memberArray(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new Error("members must be an array of session names or IDs");
+  return Array.from(value, (member) => asString(member, "member"));
+}
+
 function asBoolean(value: unknown, defaultValue: boolean): boolean {
   return typeof value === "boolean" ? value : defaultValue;
 }
@@ -85,26 +96,30 @@ export function buildToolDefinitions(runtime: CodexIntercomRuntime): ToolDefinit
     },
     {
       name: "intercom_team",
-      description: "Show your current manager and the live coworkers owned by that manager. No arguments are required.",
-      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      description: "Show all your named task teams, or inspect one by name. Falls back to managed-team discovery.",
+      inputSchema: { type: "object", properties: { team: { type: "string" } }, additionalProperties: false },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-      handler: async () => runtime.team(),
+      handler: async (args) => runtime.team(optionalString(args.team, "team")),
     },
     {
       name: "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.",
+      description: "After user approval, create or join a task team. Membership is additive; members lets the manager add connected peers in one call. Omit name to list teams.",
       inputSchema: {
         type: "object",
         properties: {
           name: { type: "string", description: "Team name to join. Omit to list joinable teams." },
           create: { type: "boolean", description: "Create this named team and join as manager. Requires name." },
+          members: { type: "array", items: { type: "string" }, description: "Connected session names or IDs to add; manager only." },
+          work: { type: "string", maxLength: 2000, description: "Task description when creating a team." },
         },
         additionalProperties: false,
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
       handler: async (args) => runtime.join(
-        typeof args.name === "string" ? args.name : undefined,
+        optionalString(args.name, "name"),
         args.create === true,
+        memberArray(args.members),
+        optionalString(args.work, "work"),
       ),
     },
     {
@@ -152,12 +167,13 @@ export function buildToolDefinitions(runtime: CodexIntercomRuntime): ToolDefinit
           to: { type: "string" },
           message: { type: "string" },
           attachments: attachmentsSchema,
+          team: { type: "string", description: "Task team; required when multiple teams are shared. Omit for ungrouped contact." },
         },
         required: ["to", "message"],
         additionalProperties: false,
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-      handler: async (args) => runtime.send(asString(args.to, "to"), asString(args.message, "message"), asAttachmentArray(args.attachments)),
+      handler: async (args) => runtime.send(asString(args.to, "to"), asString(args.message, "message"), asAttachmentArray(args.attachments), undefined, optionalString(args.team, "team")),
     },
     {
       name: "intercom_ask",
@@ -168,6 +184,7 @@ export function buildToolDefinitions(runtime: CodexIntercomRuntime): ToolDefinit
           to: { type: "string" },
           message: { type: "string" },
           attachments: attachmentsSchema,
+          team: { type: "string", description: "Task team; required when multiple teams are shared." },
           timeout_ms: { type: "integer", minimum: 1, maximum: 120000, description: "Maximum time to wait for a reply before returning an error. Use intercom_send plus intercom_pending for longer work." },
         },
         required: ["to", "message"],
@@ -180,6 +197,7 @@ export function buildToolDefinitions(runtime: CodexIntercomRuntime): ToolDefinit
         asAttachmentArray(args.attachments),
         asOptionalPositiveInteger(args.timeout_ms, "timeout_ms"),
         signal,
+        optionalString(args.team, "team"),
       ),
     },
     {
@@ -195,19 +213,22 @@ export function buildToolDefinitions(runtime: CodexIntercomRuntime): ToolDefinit
     },
     {
       name: "intercom_reply",
-      description: "Reply to a pending inbound ask. Use to plus which=oldest/latest when one sender has multiple unresolved asks.",
+      description: "Reply to an inbound ask or ordinary message using askId or contextId from intercom_pending. Inherits the original team; team cannot override it.",
       inputSchema: {
         type: "object",
         properties: {
           message: { type: "string" },
           to: { type: "string", description: "Optional sender/session selector; never a message or thread ID." },
+          askId: { type: "string", description: "Stable receiver-local pending ask selector." },
+          contextId: { type: "string", description: "Exact inbound context selector, including ordinary messages." },
+          team: { type: "string", description: "Must match the original message; omit to inherit." },
           which: { type: "string", enum: ["oldest", "latest"], description: "Select the oldest or latest ask from the chosen sender." },
         },
         required: ["message"],
         additionalProperties: false,
       },
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
-      handler: async (args) => runtime.reply(asString(args.message, "message"), typeof args.to === "string" ? args.to : undefined, args.which === "oldest" || args.which === "latest" ? args.which : undefined),
+      handler: async (args) => runtime.reply(asString(args.message, "message"), typeof args.to === "string" ? args.to : undefined, args.which === "oldest" || args.which === "latest" ? args.which : undefined, optionalString(args.askId, "askId"), optionalString(args.contextId, "contextId"), optionalString(args.team, "team")),
     },
   ];
 }
@@ -243,7 +264,8 @@ export async function handleMcpRequest(request: JsonRpcRequest, runtime: CodexIn
       return ok(request.id, {
         protocolVersion: "2025-06-18",
         capabilities: { tools: {} },
-        serverInfo: { name: "codex-intercom", version: "0.12.2" },
+        instructions: TASK_TEAM_GUIDANCE,
+        serverInfo: { name: "codex-intercom", version: "0.13.0" },
       });
     case "ping":
       return ok(request.id, {});

package/codex/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 agent 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/codex/named-teams.ts

@@ -13,6 +13,8 @@ export interface NamedTeam {
   scopeId: string;
   managerSessionId: string;
   createdAt: number;
+  memberSessionIds?: string[];
+  work?: string;
 }
 
 interface NamedTeamsFile {
@@ -55,11 +57,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/codex/reply-context.ts

@@ -0,0 +1,49 @@
+import type { PendingInboundMessage, ReplyWhich } from "./runtime.ts";
+import { selectPendingAsk } from "./runtime.ts";
+
+export function contextId(entry: PendingInboundMessage): string {
+  return `ctx-${entry.message.id}`;
+}
+
+export function askId(entry: PendingInboundMessage): string {
+  return `ask-${entry.message.id}`;
+}
+
+export function replyHint(entry: PendingInboundMessage): string {
+  const team = entry.message.content.team;
+  return `${team ? ` [Team: ${team}]` : ""} [contextId: ${contextId(entry)}]${entry.message.expectsReply ? ` [askId: ${askId(entry)}]` : ""}`;
+}
+
+/** Select from the receiver's own retained inbox, never from a mutable current team. */
+export function selectReplyContext(entries: PendingInboundMessage[], asks: PendingInboundMessage[], input: {
+  to?: string;
+  which?: ReplyWhich;
+  askId?: string;
+  contextId?: string;
+  team?: string;
+}): PendingInboundMessage {
+  if (input.askId && input.contextId) throw new Error("Specify askId or contextId, not both");
+  let target: PendingInboundMessage;
+  if (input.askId || input.contextId) {
+    const selected = input.askId
+      ? asks.find((entry) => askId(entry) === input.askId)
+      : entries.find((entry) => contextId(entry) === input.contextId);
+    if (!selected || (selected.message.expectsReply && !asks.includes(selected))) throw new Error("Unknown or resolved reply selector; call intercom_pending");
+    if (input.to && selected.from.id !== input.to && selected.from.name?.toLowerCase() !== input.to.toLowerCase()) {
+      throw new Error("Reply sender does not match the selected context");
+    }
+    if (input.which) throw new Error("Do not combine an exact reply selector with which");
+    target = selected;
+  } else {
+    const to = input.to;
+    const candidates = to ? asks.filter((entry) => entry.from.id === to || entry.from.name?.toLowerCase() === to.toLowerCase() || entry.from.id.startsWith(to)) : asks;
+    if (!input.which && new Set(candidates.map((entry) => entry.message.content.team)).size > 1) {
+      throw new Error("Multiple team contexts; specify askId or contextId");
+    }
+    target = selectPendingAsk(asks, input.to, input.which);
+  }
+  if (input.team !== undefined && input.team !== target.message.content.team) {
+    throw new Error("Reply team must match the original message; omit team to inherit it");
+  }
+  return target;
+}