@ctliz/agent-intercom-claude 0.12.0-connect.3 → 0.13.0-connect.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.13.0-connect.3 - 2026-08-23
+
+- Add complete OpenAI MCP annotations for all nine Intercom tools and verify their exact semantics in tests.
+- Reference every MCP tool by name so tool coverage is complete.
+- Explicitly disable shell execution for production and release-verification child processes.
+
+## 0.13.0-connect.2 - 2026-08-18
+
+- Document standard stdio MCP setup for Grok Build and AGY, including host-neutral identity variables, scope requirements, source-checkout configuration, manual `intercom_pending` polling, and the absence of wake-on-message support.
+
 ## 0.12.0-connect.3 - 2026-08-14
 
 - Fix package bundling by adding `monitors/**/*` (`monitors/monitors.json`) to `package.json` `files`, ensuring Claude Code plugin monitor configurations resolve properly at runtime when installed from the packaged npm artifact.

package/README.md

@@ -149,6 +149,44 @@ claude mcp add claude-intercom -- claude-intercom-mcp
 
 With `--transport mcp`, `cci` does this automatically for each normal headless worker. Native headless workers are still woken and replied through the worker daemon's broker connection, but omit the packaged MCP server from the Claude turn. `ccim` intentionally uses Claude's `--safe-mode`, which disables MCP servers along with plugins, hooks, and skills.
 
+### Other stdio MCP hosts
+
+The `claude-intercom-mcp` executable is a standard stdio MCP server, so Grok Build, AGY, and other compatible local hosts can use it without installing the Claude Code plugin. An npm/global installation provides that executable; for a source checkout, configure `node` with the absolute path to `dist/claude-server.mjs`. Node 20+ is required.
+
+Use `AGENT_INTERCOM_SESSION_ID` and `AGENT_INTERCOM_SESSION_NAME` for a host-neutral identity; `CLAUDE_INTERCOM_SESSION_ID` and `CLAUDE_INTERCOM_NAME` remain higher-priority compatibility aliases. Do not share a fixed session ID between concurrent host sessions.
+
+A plain MCP host is connected only while its MCP process is alive. Incoming Intercom messages are durable and appear through `intercom_pending`, but this server cannot itself inject a new prompt into Grok or AGY. Use `intercom_send` plus `intercom_pending` for manual-polling workflows; a host-specific relay is required for wake-on-message.
+
+For Grok Build, register the server and use a unique static ID for an individual long-lived probe or worker:
+
+```bash
+grok mcp add agent-intercom \
+  -e AGENT_INTERCOM_SESSION_ID=grok-probe-01 \
+  -e AGENT_INTERCOM_SESSION_NAME=grok-probe \
+  -e CLAUDE_INTERCOM_MODEL=grok-build \
+  -- claude-intercom-mcp
+```
+
+For AGY, add the equivalent entry to `~/.gemini/config/mcp_config.json` (replace the source-checkout paths when using an installed `claude-intercom-mcp` executable):
+
+```json
+{
+  "mcpServers": {
+    "agent-intercom": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/agent-intercom-claude/dist/claude-server.mjs"],
+      "env": {
+        "AGENT_INTERCOM_SESSION_ID": "agy-probe-01",
+        "AGENT_INTERCOM_SESSION_NAME": "agy-probe",
+        "CLAUDE_INTERCOM_MODEL": "agy"
+      }
+    }
+  }
+}
+```
+
+Both hosts must use the same `AGENT_INTERCOM_SCOPE_ID` as their intended peers, or leave it unset for the default local scope. Call `intercom_whoami` once after startup, then use `intercom_list`, `intercom_send`, and `intercom_pending` to verify delivery.
+
 Optional identity variables can be attached at registration time:
 
 ```bash
@@ -413,6 +451,8 @@ environment when no config file is given (`CLAUDE_INTERCOM_WORKER_ID`, `…_NAME
 | `CLAUDE_INTERCOM_NAME` | MCP server | Discoverable session name |
 | `CLAUDE_INTERCOM_SESSION_ID` | MCP server | Stable intercom id |
 | `CLAUDE_INTERCOM_MODEL` | MCP server | Model label shown to peers |
+| `AGENT_INTERCOM_SESSION_ID` / `_NAME` | MCP server | Host-neutral identity fallback; Claude-specific values take precedence |
+| `AGENT_INTERCOM_SCOPE_ID` | MCP server | Broker-enforced local routing scope |
 | `CLAUDE_INTERCOM_EFFORT` | `cci` / `ccim` | Effort level forwarded to every Claude turn |
 | `CLAUDE_INTERCOM_CWD` / `_INSTRUCTIONS` | `cci` / `ccim` | Defaults for `--cwd` / `--instructions` |
 | `CLAUDE_INTERCOM_CLAUDE_COMMAND` | workers | Claude Code executable (default `claude`) |

package/broker/spawn.ts

@@ -191,6 +191,7 @@ export function getBrokerSpawnOptions(
   cwd: string;
   env: NodeJS.ProcessEnv;
   windowsHide: true;
+  shell: false;
 } {
   return {
     detached: true,
@@ -198,6 +199,7 @@ export function getBrokerSpawnOptions(
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
     windowsHide: true,
+    shell: false,
   };
 }
 

package/claude/cci.ts

@@ -66,6 +66,7 @@ function gitString(cwd: string, args: string[]): string | null {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
+    shell: false,
   });
   if (result.status !== 0) return null;
   const trimmed = result.stdout.trim();
@@ -341,6 +342,7 @@ async function runCciTui(options: CciOptions, id: string, name: string, scopeId:
   const child = spawn(options.claudeCommand, args, {
     cwd: options.cwd,
     stdio: "inherit",
+    shell: false,
     env: {
       ...process.env,
       ...scopeEnv,

package/claude/cli-runner.ts

@@ -116,6 +116,7 @@ export function runClaudeTurn(options: ClaudeTurnOptions): Promise<ClaudeTurnRes
         cwd: launch.cwd,
         env: { ...process.env, ...options.env },
         stdio: ["pipe", "pipe", "pipe"],
+        shell: false,
       });
     } finally {
       // Directory descriptors remain open across the synchronous spawn setup,

package/claude/contact.ts

@@ -20,14 +20,14 @@ export function copyTextToClipboard(text: string): boolean {
           ["clip.exe", []],
         ];
   for (const [command, args] of candidates) {
-    if (spawnSync("which", [command], { stdio: "ignore" }).status !== 0) continue;
+    if (spawnSync("which", [command], { stdio: "ignore", shell: false }).status !== 0) continue;
     if (command === "wl-copy") {
-      const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+      const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"], shell: false });
       child.stdin.end(text);
       child.unref();
       return true;
     }
-    if (spawnSync(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"] }).status === 0) return true;
+    if (spawnSync(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"], shell: false }).status === 0) return true;
   }
   return false;
 }

package/claude/mcp-protocol.ts

@@ -17,6 +17,12 @@ interface ToolDefinition {
   name: string;
   description: string;
   inputSchema: Record<string, unknown>;
+  annotations: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+  };
   handler: ToolHandler;
 }
 
@@ -78,18 +84,21 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
       name: "intercom_whoami",
       description: "Return this Claude session's intercom identity for reliable targeting.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async () => runtime.whoami(),
     },
     {
       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 },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       handler: async () => runtime.team(),
     },
     {
       name: "intercom_status",
       description: "Show intercom connection status, active sessions, unread messages, and pending asks.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       handler: async () => runtime.status(),
     },
     {
@@ -103,6 +112,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         },
         additionalProperties: false,
       },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       handler: async (args) => runtime.list(
         args.scope === "directory" || args.scope === "repo" ? args.scope : "machine",
         asBoolean(args.include_self, false),
@@ -117,6 +127,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         required: ["summary"],
         additionalProperties: false,
       },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.setSummary(asString(args.summary, "summary")),
     },
     {
@@ -132,6 +143,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         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)),
     },
     {
@@ -148,6 +160,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         required: ["to", "message"],
         additionalProperties: false,
       },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
       handler: async (args, signal) => runtime.ask(
         asString(args.to, "to"),
         asString(args.message, "message"),
@@ -164,6 +177,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         properties: { mark_read: { type: "boolean", default: false } },
         additionalProperties: false,
       },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
       handler: async (args) => runtime.pending(asBoolean(args.mark_read, false)),
     },
     {
@@ -179,6 +193,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         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),
     },
   ];
@@ -222,7 +237,7 @@ export async function handleMcpRequest(request: JsonRpcRequest, runtime: ClaudeI
       return ok(request.id, {});
     case "tools/list":
       return ok(request.id, {
-        tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+        tools: tools.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations })),
       });
     case "tools/call": {
       const name = request.params?.name;

package/claude/native-protocol.ts

@@ -271,7 +271,7 @@ export async function bindNativeClaudeSocket(socketPath: string, onFrame: (frame
 
 function processStart(pid: number): Promise<string | undefined> {
   return new Promise((resolve) => {
-    execFile("ps", ["-o", "lstart=", "-p", String(pid)], (error, stdout) => resolve(error ? undefined : stdout.trim() || undefined));
+    execFile("ps", ["-o", "lstart=", "-p", String(pid)], { shell: false }, (error, stdout) => resolve(error ? undefined : stdout.trim() || undefined));
   });
 }
 

package/claude/runtime.ts

@@ -96,13 +96,28 @@ function shortHash(value: string): string {
   return createHash("sha256").update(value).digest("hex").slice(0, 8);
 }
 
+const GENERIC_SESSION_ID_REGEX = /^[A-Za-z0-9_-]{1,128}$/;
+
 export function buildClaudeRuntimeIdentity(env: NodeJS.ProcessEnv = process.env, cwd = env.PWD || processCwd(), pid = process.pid): ClaudeRuntimeIdentity {
-  const sessionId = env.CLAUDE_INTERCOM_SESSION_ID?.trim()
-    || env.CLAUDE_PEER_ID?.trim()
-    || `claude-${pid}-${shortHash(cwd)}`;
+  let sessionId = env.CLAUDE_INTERCOM_SESSION_ID?.trim()
+    || env.CLAUDE_PEER_ID?.trim();
+  if (!sessionId && env.AGENT_INTERCOM_SESSION_ID !== undefined) {
+    const raw = env.AGENT_INTERCOM_SESSION_ID.trim();
+    if (raw) {
+      if (!GENERIC_SESSION_ID_REGEX.test(raw)) {
+        throw new Error("Invalid AGENT_INTERCOM_SESSION_ID: must match ^[A-Za-z0-9_-]{1,128}$");
+      }
+      sessionId = raw;
+    }
+  }
+  if (!sessionId) {
+    sessionId = `claude-${pid}-${shortHash(cwd)}`;
+  }
+
   const cwdName = basename(cwd) || "workspace";
   const name = env.CLAUDE_INTERCOM_NAME?.trim()
     || env.CLAUDE_PEER_NAME?.trim()
+    || (env.AGENT_INTERCOM_SESSION_NAME !== undefined && env.AGENT_INTERCOM_SESSION_NAME.trim() ? env.AGENT_INTERCOM_SESSION_NAME.trim() : undefined)
     || `claude-${cwdName}-${pid}`;
   return {
     sessionId,
@@ -168,6 +183,7 @@ export function detectGitRoot(cwd: string): string | null {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
+    shell: false,
   });
   if (result.status !== 0) return null;
   return result.stdout.trim() || null;

package/claude/team.ts

@@ -1,12 +1,17 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { PARTICIPANT_STATES, TERMINAL_PARTICIPANT_STATES } from "@ctliz/agent-intercom-core/boss";
+import { readTeamManifestAsync, TeamManifestError } from "@ctliz/agent-intercom-core/team-manifest";
 import type { BossSessionMetadata } from "../types.ts";
 import { getAgentDirPath } from "../broker/paths.ts";
 
+export type TeamSource = "orchestrator" | "boss" | "manifest" | "live" | "standalone";
+
 export interface TeamSession {
   id: string;
   name?: string;
+  model?: string;
+  origin?: "local" | "remote";
   /** Already parsed and broker-authenticated by the client session decoder. */
   boss?: Pick<BossSessionMetadata, "binding" | "principal" | "liveWorker">;
 }
@@ -42,6 +47,7 @@ export interface IntercomTeam {
   self: { id: string; workerId?: string; isManager: boolean };
   manager?: { target: string; connected: boolean };
   coworkers: TeamMember[];
+  source: TeamSource;
 }
 
 const LEGACY_LIVE_STATES = new Set(["provisioning", "running", "idle", "needs_attention", "stopping"]);
@@ -212,11 +218,106 @@ function teamMember(worker: StoredWorker, session: TeamSession): TeamMember {
   };
 }
 
-function resolveLegacyTeam(
+async function resolveNonAuthoritativeTeam(
+  input: { selfId: string; sessions: TeamSession[] },
+  env: NodeJS.ProcessEnv,
+): Promise<IntercomTeam> {
+  if (env.AGENT_INTERCOM_TEAM_MANIFEST !== undefined) {
+    const rawPath = env.AGENT_INTERCOM_TEAM_MANIFEST.trim();
+    if (!rawPath) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+    const manifest = await readTeamManifestAsync(rawPath);
+    if (!manifest) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+    const selfMember = manifest.members.find((m) => m.sessionId === input.selfId);
+    if (!selfMember) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+
+    const isManager = input.selfId === manifest.leadId;
+    const managerTarget = manifest.leadId;
+    const managerConnected = connectedTo(input.sessions, managerTarget);
+
+    const coworkers: TeamMember[] = manifest.members
+      .filter((m) => m.sessionId !== input.selfId)
+      .filter((m) => isManager || m.sessionId !== managerTarget)
+      .map((m) => {
+        const live = input.sessions.find((s) => s.id === m.sessionId || s.name === m.sessionId);
+        return {
+          id: m.sessionId,
+          target: m.sessionId,
+          role: m.role,
+          connected: Boolean(live),
+        };
+      });
+
+    return {
+      teamId: manifest.runId,
+      self: { id: input.selfId, isManager },
+      manager: { target: managerTarget, connected: managerConnected },
+      coworkers,
+      source: "manifest",
+    };
+  }
+
+  if (stringValue(env.AGENT_INTERCOM_SCOPE_ID)) {
+    const managerTarget = stringValue(env.AGENT_INTERCOM_MANAGER_TARGET)
+      ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+    const role = stringValue(env.AGENT_INTERCOM_ROLE)?.toLowerCase();
+
+    const isManager = role === "manager"
+      || (managerTarget !== undefined && managerTarget === input.selfId)
+      || (managerTarget === undefined && role !== "worker");
+
+    const effectiveManagerTarget = isManager ? input.selfId : managerTarget;
+
+    const coworkers: TeamMember[] = input.sessions
+      .filter((session) => session.id !== input.selfId)
+      .filter((session) => session.model !== "human")
+      .filter((session) => session.id !== effectiveManagerTarget)
+      .map((session): TeamMember => ({
+        id: session.id,
+        target: session.id,
+        ...(session.model ? { harness: session.model } : {}),
+        connected: true,
+      }));
+
+    const manager = effectiveManagerTarget
+      ? {
+          target: effectiveManagerTarget,
+          connected: isManager ? true : connectedTo(input.sessions, effectiveManagerTarget),
+        }
+      : undefined;
+
+    return {
+      teamId: effectiveManagerTarget ?? input.selfId,
+      self: { id: input.selfId, isManager },
+      ...(manager ? { manager } : {}),
+      coworkers,
+      source: "live",
+    };
+  }
+
+  const managerTarget = stringValue(env.AGENT_INTERCOM_MANAGER_TARGET)
+    ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+  return {
+    teamId: managerTarget ?? input.selfId,
+    self: { id: input.selfId, isManager: !managerTarget },
+    manager: managerTarget
+      ? { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) }
+      : { target: input.selfId, connected: true },
+    coworkers: [],
+    source: "standalone",
+  };
+}
+
+async function resolveLegacyTeam(
   input: { selfId: string; sessions: TeamSession[] },
   workers: StoredWorker[],
   env: NodeJS.ProcessEnv,
-): IntercomTeam {
+): Promise<IntercomTeam> {
   const workerId = stringValue(env.AGENT_INTERCOM_WORKER_ID);
   const runId = stringValue(env.AGENT_INTERCOM_RUN_ID);
   const current = workerId
@@ -225,37 +326,86 @@ function resolveLegacyTeam(
       && (!runId || stringValue(worker.runId) === runId)
     )
     : undefined;
-  const managerTarget = stringValue(current?.managerSessionId)
-    ?? stringValue(env.AGENT_INTERCOM_MANAGER_TARGET)
-    ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
-  const teamId = managerTarget ?? input.selfId;
-  const coworkers = workers
-    .filter((worker) => worker.owned === true)
-    .filter((worker) => stringValue(worker.managerSessionId) === teamId)
-    .filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? ""))
-    .filter((worker) => stringValue(worker.id) !== workerId)
-    .map((worker): TeamMember | undefined => {
-      const id = stringValue(worker.id);
-      if (!id) return undefined;
-      const target = stringValue(worker.intercomTarget) ?? id;
+
+  if (current) {
+    const managerTarget = stringValue(current?.managerSessionId)
+      ?? stringValue(env.AGENT_INTERCOM_MANAGER_TARGET)
+      ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+    if (!managerTarget) {
       return {
-        id,
-        target,
-        ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
-        ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
-        ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
-        connected: connectedTo(input.sessions, target),
+        self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
+        coworkers: [],
+        source: "orchestrator",
       };
-    })
-    .filter((member): member is TeamMember => Boolean(member));
-  return {
-    teamId,
-    self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: !managerTarget },
-    manager: managerTarget
-      ? { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) }
-      : { target: input.selfId, connected: true },
-    coworkers,
-  };
+    }
+    const coworkers = workers
+      .filter((worker) => worker.owned === true)
+      .filter((worker) => {
+        const mgr = stringValue(worker.managerSessionId);
+        return mgr !== undefined && mgr === managerTarget;
+      })
+      .filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? ""))
+      .filter((worker) => stringValue(worker.id) !== workerId && stringValue(worker.id) !== input.selfId)
+      .map((worker): TeamMember | undefined => {
+        const id = stringValue(worker.id);
+        if (!id) return undefined;
+        const target = stringValue(worker.intercomTarget) ?? id;
+        return {
+          id,
+          target,
+          ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
+          ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
+          ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
+          connected: connectedTo(input.sessions, target),
+        };
+      })
+      .filter((member): member is TeamMember => Boolean(member));
+
+    return {
+      teamId: managerTarget,
+      self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
+      manager: { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) },
+      coworkers,
+      source: "orchestrator",
+    };
+  }
+
+  if (workerId === undefined) {
+    const ownedCoworkers = workers
+      .filter((worker) => worker.owned === true)
+      .filter((worker) => {
+        const mgr = stringValue(worker.managerSessionId);
+        return mgr !== undefined && mgr === input.selfId;
+      })
+      .filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? ""))
+      .filter((worker) => stringValue(worker.id) !== input.selfId)
+      .map((worker): TeamMember | undefined => {
+        const id = stringValue(worker.id);
+        if (!id) return undefined;
+        const target = stringValue(worker.intercomTarget) ?? id;
+        return {
+          id,
+          target,
+          ...(stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {}),
+          ...(stringValue(worker.role) ? { role: stringValue(worker.role) } : {}),
+          ...(stringValue(worker.state) ? { state: stringValue(worker.state) } : {}),
+          connected: connectedTo(input.sessions, target),
+        };
+      })
+      .filter((member): member is TeamMember => Boolean(member));
+
+    if (ownedCoworkers.length > 0) {
+      return {
+        teamId: input.selfId,
+        self: { id: input.selfId, isManager: true },
+        manager: { target: input.selfId, connected: true },
+        coworkers: ownedCoworkers,
+        source: "orchestrator",
+      };
+    }
+  }
+
+  return resolveNonAuthoritativeTeam(input, env);
 }
 
 export async function resolveIntercomTeam(input: {
@@ -276,6 +426,7 @@ export async function resolveIntercomTeam(input: {
       teamId: selfSession.boss.binding.bossRunId,
       self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
       coworkers: [],
+      source: "boss",
     };
   }
 
@@ -301,6 +452,7 @@ export async function resolveIntercomTeam(input: {
       teamId: selfSession.boss.binding.bossRunId,
       self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: false },
       coworkers: [],
+      source: "boss",
     };
   }
 
@@ -327,9 +479,36 @@ export async function resolveIntercomTeam(input: {
     self: { id: input.selfId, ...(workerId ? { workerId } : {}), isManager: selfIsManager },
     manager: { target: managerTarget, connected: true },
     coworkers,
+    source: "boss",
   };
 }
 
+/** Authorizes a read-only local inbox lookup using exact orchestrator ownership. */
+export function resolveManagedInboxSession(input: {
+  team: IntercomTeam;
+  sessions: TeamSession[];
+  requestedSession: string;
+}): TeamSession {
+  if (input.team.source !== "orchestrator" && input.team.source !== "boss") {
+    throw new Error("Pending-ask inbox access denied: cross-session inbox inspection is only permitted for Orchestrator/Boss-managed teams");
+  }
+  if (!input.team.self.isManager) {
+    throw new Error("Only a manager may inspect another session's pending-ask inbox");
+  }
+  const member = input.team.coworkers.find((entry) => entry.target === input.requestedSession);
+  if (!member) {
+    throw new Error(`Pending-ask inbox access denied for "${input.requestedSession}"; select an owned coworker target returned by intercom_team`);
+  }
+  const liveSession = input.sessions.find((session) => session.id === input.requestedSession);
+  if (!liveSession) {
+    throw new Error(`Pending-ask inbox access denied for "${input.requestedSession}"; the owned coworker target must equal an exact connected stable session ID`);
+  }
+  if (liveSession.origin === "remote") {
+    throw new Error(`Pending-ask inbox "${input.requestedSession}" is remote and cannot be read from this host`);
+  }
+  return liveSession;
+}
+
 export function formatIntercomTeam(team: IntercomTeam): string {
   const lines = [
     `Manager: ${team.manager ? `${team.manager.target} [${team.manager.connected ? "connected" : "not connected"}]` : "unknown"}`,

package/claude/transport.ts

@@ -49,6 +49,7 @@ export function probeClaudeVersion(command = "claude"): ClaudeVersionProbe {
   const result = spawnSync(command, ["--version"], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
   });
   if (result.error || result.status !== 0) {
     return {

package/dist/cci.mjs

@@ -274,7 +274,8 @@ function runClaudeTurn(options) {
       child = spawn(command, launch.args, {
         cwd: launch.cwd,
         env: { ...process.env, ...options.env },
-        stdio: ["pipe", "pipe", "pipe"]
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: false
       });
     } finally {
       launch.release();
@@ -566,7 +567,8 @@ function isNativeClaudeVersionCompatible(version) {
 function probeClaudeVersion(command = "claude") {
   const result = spawnSync(command, ["--version"], {
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false
   });
   if (result.error || result.status !== 0) {
     return {
@@ -2063,7 +2065,8 @@ function getBrokerSpawnOptions(extensionDir = EXTENSION_DIR, env = process.env)
     stdio: "ignore",
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
-    windowsHide: true
+    windowsHide: true,
+    shell: false
   };
 }
 function toError2(error) {
@@ -2399,6 +2402,7 @@ function defaultInboxPath(sessionId, intercomDir = getIntercomDirPath()) {
 
 // claude/team.ts
 import { PARTICIPANT_STATES, TERMINAL_PARTICIPANT_STATES } from "@ctliz/agent-intercom-core/boss";
+import { readTeamManifestAsync, TeamManifestError } from "@ctliz/agent-intercom-core/team-manifest";
 var BOSS_NONTERMINAL_STATES = new Set(
   PARTICIPANT_STATES.filter((state) => !TERMINAL_PARTICIPANT_STATES.includes(state))
 );
@@ -2443,14 +2447,14 @@ function copyTextToClipboard(text) {
     ["clip.exe", []]
   ];
   for (const [command, args] of candidates) {
-    if (spawnSync2("which", [command], { stdio: "ignore" }).status !== 0) continue;
+    if (spawnSync2("which", [command], { stdio: "ignore", shell: false }).status !== 0) continue;
     if (command === "wl-copy") {
-      const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+      const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"], shell: false });
       child.stdin.end(text);
       child.unref();
       return true;
     }
-    if (spawnSync2(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"] }).status === 0) return true;
+    if (spawnSync2(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"], shell: false }).status === 0) return true;
   }
   return false;
 }
@@ -3017,7 +3021,7 @@ async function bindNativeClaudeSocket(socketPath, onFrame) {
 }
 function processStart(pid) {
   return new Promise((resolve5) => {
-    execFile("ps", ["-o", "lstart=", "-p", String(pid)], (error, stdout) => resolve5(error ? void 0 : stdout.trim() || void 0));
+    execFile("ps", ["-o", "lstart=", "-p", String(pid)], { shell: false }, (error, stdout) => resolve5(error ? void 0 : stdout.trim() || void 0));
   });
 }
 async function registerNativeClaudePeer(options) {
@@ -3201,7 +3205,8 @@ function gitString(cwd, args) {
   const result = spawnSync3("git", args, {
     cwd,
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"]
+    stdio: ["ignore", "pipe", "ignore"],
+    shell: false
   });
   if (result.status !== 0) return null;
   const trimmed = result.stdout.trim();
@@ -3445,6 +3450,7 @@ async function runCciTui(options, id, name, scopeId) {
   const child = spawn4(options.claudeCommand, args, {
     cwd: options.cwd,
     stdio: "inherit",
+    shell: false,
     env: {
       ...process.env,
       ...scopeEnv,

package/dist/ccim.mjs

@@ -278,7 +278,8 @@ function runClaudeTurn(options) {
       child = spawn(command, launch.args, {
         cwd: launch.cwd,
         env: { ...process.env, ...options.env },
-        stdio: ["pipe", "pipe", "pipe"]
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: false
       });
     } finally {
       launch.release();
@@ -570,7 +571,8 @@ function isNativeClaudeVersionCompatible(version) {
 function probeClaudeVersion(command = "claude") {
   const result = spawnSync(command, ["--version"], {
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false
   });
   if (result.error || result.status !== 0) {
     return {
@@ -2067,7 +2069,8 @@ function getBrokerSpawnOptions(extensionDir = EXTENSION_DIR, env = process.env)
     stdio: "ignore",
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
-    windowsHide: true
+    windowsHide: true,
+    shell: false
   };
 }
 function toError2(error) {
@@ -2403,6 +2406,7 @@ function defaultInboxPath(sessionId, intercomDir = getIntercomDirPath()) {
 
 // claude/team.ts
 import { PARTICIPANT_STATES, TERMINAL_PARTICIPANT_STATES } from "@ctliz/agent-intercom-core/boss";
+import { readTeamManifestAsync, TeamManifestError } from "@ctliz/agent-intercom-core/team-manifest";
 var BOSS_NONTERMINAL_STATES = new Set(
   PARTICIPANT_STATES.filter((state) => !TERMINAL_PARTICIPANT_STATES.includes(state))
 );
@@ -2447,14 +2451,14 @@ function copyTextToClipboard(text) {
     ["clip.exe", []]
   ];
   for (const [command, args] of candidates) {
-    if (spawnSync2("which", [command], { stdio: "ignore" }).status !== 0) continue;
+    if (spawnSync2("which", [command], { stdio: "ignore", shell: false }).status !== 0) continue;
     if (command === "wl-copy") {
-      const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+      const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"], shell: false });
       child.stdin.end(text);
       child.unref();
       return true;
     }
-    if (spawnSync2(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"] }).status === 0) return true;
+    if (spawnSync2(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"], shell: false }).status === 0) return true;
   }
   return false;
 }
@@ -3021,7 +3025,7 @@ async function bindNativeClaudeSocket(socketPath, onFrame) {
 }
 function processStart(pid) {
   return new Promise((resolve5) => {
-    execFile("ps", ["-o", "lstart=", "-p", String(pid)], (error, stdout) => resolve5(error ? void 0 : stdout.trim() || void 0));
+    execFile("ps", ["-o", "lstart=", "-p", String(pid)], { shell: false }, (error, stdout) => resolve5(error ? void 0 : stdout.trim() || void 0));
   });
 }
 async function registerNativeClaudePeer(options) {
@@ -3205,7 +3209,8 @@ function gitString(cwd, args) {
   const result = spawnSync3("git", args, {
     cwd,
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"]
+    stdio: ["ignore", "pipe", "ignore"],
+    shell: false
   });
   if (result.status !== 0) return null;
   const trimmed = result.stdout.trim();
@@ -3449,6 +3454,7 @@ async function runCciTui(options, id, name, scopeId) {
   const child = spawn4(options.claudeCommand, args, {
     cwd: options.cwd,
     stdio: "inherit",
+    shell: false,
     env: {
       ...process.env,
       ...scopeEnv,

package/dist/claude-server.mjs

@@ -1501,7 +1501,8 @@ function getBrokerSpawnOptions(extensionDir = EXTENSION_DIR, env = process.env)
     stdio: "ignore",
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
-    windowsHide: true
+    windowsHide: true,
+    shell: false
   };
 }
 function toError2(error2) {
@@ -1870,6 +1871,7 @@ function appendInboxMessage(path, from, message) {
 import { readFile } from "node:fs/promises";
 import { join as join6 } from "node:path";
 import { PARTICIPANT_STATES, TERMINAL_PARTICIPANT_STATES } from "@ctliz/agent-intercom-core/boss";
+import { readTeamManifestAsync, TeamManifestError } from "@ctliz/agent-intercom-core/team-manifest";
 var LEGACY_LIVE_STATES = /* @__PURE__ */ new Set(["provisioning", "running", "idle", "needs_attention", "stopping"]);
 var BOSS_NONTERMINAL_STATES = new Set(
   PARTICIPANT_STATES.filter((state) => !TERMINAL_PARTICIPANT_STATES.includes(state))
@@ -1948,33 +1950,139 @@ function teamMember(worker, session) {
     connected: session.id === id
   };
 }
-function resolveLegacyTeam(input, workers, env) {
+async function resolveNonAuthoritativeTeam(input, env) {
+  if (env.AGENT_INTERCOM_TEAM_MANIFEST !== void 0) {
+    const rawPath = env.AGENT_INTERCOM_TEAM_MANIFEST.trim();
+    if (!rawPath) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+    const manifest = await readTeamManifestAsync(rawPath);
+    if (!manifest) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+    const selfMember = manifest.members.find((m) => m.sessionId === input.selfId);
+    if (!selfMember) {
+      throw new TeamManifestError("ERR_TEAM_MANIFEST_INVALID");
+    }
+    const isManager = input.selfId === manifest.leadId;
+    const managerTarget2 = manifest.leadId;
+    const managerConnected = connectedTo(input.sessions, managerTarget2);
+    const coworkers = manifest.members.filter((m) => m.sessionId !== input.selfId).filter((m) => isManager || m.sessionId !== managerTarget2).map((m) => {
+      const live = input.sessions.find((s) => s.id === m.sessionId || s.name === m.sessionId);
+      return {
+        id: m.sessionId,
+        target: m.sessionId,
+        role: m.role,
+        connected: Boolean(live)
+      };
+    });
+    return {
+      teamId: manifest.runId,
+      self: { id: input.selfId, isManager },
+      manager: { target: managerTarget2, connected: managerConnected },
+      coworkers,
+      source: "manifest"
+    };
+  }
+  if (stringValue(env.AGENT_INTERCOM_SCOPE_ID)) {
+    const managerTarget2 = stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+    const role = stringValue(env.AGENT_INTERCOM_ROLE)?.toLowerCase();
+    const isManager = role === "manager" || managerTarget2 !== void 0 && managerTarget2 === input.selfId || managerTarget2 === void 0 && role !== "worker";
+    const effectiveManagerTarget = isManager ? input.selfId : managerTarget2;
+    const coworkers = input.sessions.filter((session) => session.id !== input.selfId).filter((session) => session.model !== "human").filter((session) => session.id !== effectiveManagerTarget).map((session) => ({
+      id: session.id,
+      target: session.id,
+      ...session.model ? { harness: session.model } : {},
+      connected: true
+    }));
+    const manager = effectiveManagerTarget ? {
+      target: effectiveManagerTarget,
+      connected: isManager ? true : connectedTo(input.sessions, effectiveManagerTarget)
+    } : void 0;
+    return {
+      teamId: effectiveManagerTarget ?? input.selfId,
+      self: { id: input.selfId, isManager },
+      ...manager ? { manager } : {},
+      coworkers,
+      source: "live"
+    };
+  }
+  const managerTarget = stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+  return {
+    teamId: managerTarget ?? input.selfId,
+    self: { id: input.selfId, isManager: !managerTarget },
+    manager: managerTarget ? { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) } : { target: input.selfId, connected: true },
+    coworkers: [],
+    source: "standalone"
+  };
+}
+async function resolveLegacyTeam(input, workers, env) {
   const workerId = stringValue(env.AGENT_INTERCOM_WORKER_ID);
   const runId = stringValue(env.AGENT_INTERCOM_RUN_ID);
   const current = workerId ? workers.find(
     (worker) => stringValue(worker.id) === workerId && (!runId || stringValue(worker.runId) === runId)
   ) : void 0;
-  const managerTarget = stringValue(current?.managerSessionId) ?? stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
-  const teamId = managerTarget ?? input.selfId;
-  const coworkers = workers.filter((worker) => worker.owned === true).filter((worker) => stringValue(worker.managerSessionId) === teamId).filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? "")).filter((worker) => stringValue(worker.id) !== workerId).map((worker) => {
-    const id = stringValue(worker.id);
-    if (!id) return void 0;
-    const target = stringValue(worker.intercomTarget) ?? id;
+  if (current) {
+    const managerTarget = stringValue(current?.managerSessionId) ?? stringValue(env.AGENT_INTERCOM_MANAGER_TARGET) ?? stringValue(env.AGENT_INTERCOM_MANAGER_SESSION_ID);
+    if (!managerTarget) {
+      return {
+        self: { id: input.selfId, ...workerId ? { workerId } : {}, isManager: false },
+        coworkers: [],
+        source: "orchestrator"
+      };
+    }
+    const coworkers = workers.filter((worker) => worker.owned === true).filter((worker) => {
+      const mgr = stringValue(worker.managerSessionId);
+      return mgr !== void 0 && mgr === managerTarget;
+    }).filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? "")).filter((worker) => stringValue(worker.id) !== workerId && stringValue(worker.id) !== input.selfId).map((worker) => {
+      const id = stringValue(worker.id);
+      if (!id) return void 0;
+      const target = stringValue(worker.intercomTarget) ?? id;
+      return {
+        id,
+        target,
+        ...stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {},
+        ...stringValue(worker.role) ? { role: stringValue(worker.role) } : {},
+        ...stringValue(worker.state) ? { state: stringValue(worker.state) } : {},
+        connected: connectedTo(input.sessions, target)
+      };
+    }).filter((member) => Boolean(member));
     return {
-      id,
-      target,
-      ...stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {},
-      ...stringValue(worker.role) ? { role: stringValue(worker.role) } : {},
-      ...stringValue(worker.state) ? { state: stringValue(worker.state) } : {},
-      connected: connectedTo(input.sessions, target)
+      teamId: managerTarget,
+      self: { id: input.selfId, ...workerId ? { workerId } : {}, isManager: false },
+      manager: { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) },
+      coworkers,
+      source: "orchestrator"
     };
-  }).filter((member) => Boolean(member));
-  return {
-    teamId,
-    self: { id: input.selfId, ...workerId ? { workerId } : {}, isManager: !managerTarget },
-    manager: managerTarget ? { target: managerTarget, connected: connectedTo(input.sessions, managerTarget) } : { target: input.selfId, connected: true },
-    coworkers
-  };
+  }
+  if (workerId === void 0) {
+    const ownedCoworkers = workers.filter((worker) => worker.owned === true).filter((worker) => {
+      const mgr = stringValue(worker.managerSessionId);
+      return mgr !== void 0 && mgr === input.selfId;
+    }).filter((worker) => LEGACY_LIVE_STATES.has(stringValue(worker.state) ?? "")).filter((worker) => stringValue(worker.id) !== input.selfId).map((worker) => {
+      const id = stringValue(worker.id);
+      if (!id) return void 0;
+      const target = stringValue(worker.intercomTarget) ?? id;
+      return {
+        id,
+        target,
+        ...stringValue(worker.harness) ? { harness: stringValue(worker.harness) } : {},
+        ...stringValue(worker.role) ? { role: stringValue(worker.role) } : {},
+        ...stringValue(worker.state) ? { state: stringValue(worker.state) } : {},
+        connected: connectedTo(input.sessions, target)
+      };
+    }).filter((member) => Boolean(member));
+    if (ownedCoworkers.length > 0) {
+      return {
+        teamId: input.selfId,
+        self: { id: input.selfId, isManager: true },
+        manager: { target: input.selfId, connected: true },
+        coworkers: ownedCoworkers,
+        source: "orchestrator"
+      };
+    }
+  }
+  return resolveNonAuthoritativeTeam(input, env);
 }
 async function resolveIntercomTeam(input) {
   const env = input.env ?? process.env;
@@ -1987,7 +2095,8 @@ async function resolveIntercomTeam(input) {
     return {
       teamId: selfSession.boss.binding.bossRunId,
       self: { id: input.selfId, ...workerId ? { workerId } : {}, isManager: false },
-      coworkers: []
+      coworkers: [],
+      source: "boss"
     };
   }
   const currentRole = selfSession.boss.binding.role;
@@ -2000,7 +2109,8 @@ async function resolveIntercomTeam(input) {
     return {
       teamId: selfSession.boss.binding.bossRunId,
       self: { id: input.selfId, ...workerId ? { workerId } : {}, isManager: false },
-      coworkers: []
+      coworkers: [],
+      source: "boss"
     };
   }
   const coworkers = workers.filter((worker) => exactStringValue(worker.id) !== workerId).filter((worker) => exactStringValue(worker.managerSessionId) === managerTarget).map((worker) => {
@@ -2014,7 +2124,8 @@ async function resolveIntercomTeam(input) {
     teamId: selfSession.boss.binding.bossRunId,
     self: { id: input.selfId, ...workerId ? { workerId } : {}, isManager: selfIsManager },
     manager: { target: managerTarget, connected: true },
-    coworkers
+    coworkers,
+    source: "boss"
   };
 }
 function formatIntercomTeam(team) {
@@ -2082,10 +2193,23 @@ function publicPendingEntry(entry, selector) {
 function shortHash(value) {
   return createHash2("sha256").update(value).digest("hex").slice(0, 8);
 }
+var GENERIC_SESSION_ID_REGEX = /^[A-Za-z0-9_-]{1,128}$/;
 function buildClaudeRuntimeIdentity(env = process.env, cwd = env.PWD || processCwd(), pid = process.pid) {
-  const sessionId = env.CLAUDE_INTERCOM_SESSION_ID?.trim() || env.CLAUDE_PEER_ID?.trim() || `claude-${pid}-${shortHash(cwd)}`;
+  let sessionId = env.CLAUDE_INTERCOM_SESSION_ID?.trim() || env.CLAUDE_PEER_ID?.trim();
+  if (!sessionId && env.AGENT_INTERCOM_SESSION_ID !== void 0) {
+    const raw = env.AGENT_INTERCOM_SESSION_ID.trim();
+    if (raw) {
+      if (!GENERIC_SESSION_ID_REGEX.test(raw)) {
+        throw new Error("Invalid AGENT_INTERCOM_SESSION_ID: must match ^[A-Za-z0-9_-]{1,128}$");
+      }
+      sessionId = raw;
+    }
+  }
+  if (!sessionId) {
+    sessionId = `claude-${pid}-${shortHash(cwd)}`;
+  }
   const cwdName = basename(cwd) || "workspace";
-  const name = env.CLAUDE_INTERCOM_NAME?.trim() || env.CLAUDE_PEER_NAME?.trim() || `claude-${cwdName}-${pid}`;
+  const name = env.CLAUDE_INTERCOM_NAME?.trim() || env.CLAUDE_PEER_NAME?.trim() || (env.AGENT_INTERCOM_SESSION_NAME !== void 0 && env.AGENT_INTERCOM_SESSION_NAME.trim() ? env.AGENT_INTERCOM_SESSION_NAME.trim() : void 0) || `claude-${cwdName}-${pid}`;
   return {
     sessionId,
     name,
@@ -2151,7 +2275,8 @@ function detectGitRoot(cwd) {
   const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
     cwd,
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"]
+    stdio: ["ignore", "pipe", "ignore"],
+    shell: false
   });
   if (result.status !== 0) return null;
   return result.stdout.trim() || null;
@@ -2506,18 +2631,21 @@ function buildToolDefinitions(runtime2) {
       name: "intercom_whoami",
       description: "Return this Claude session's intercom identity for reliable targeting.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async () => runtime2.whoami()
     },
     {
       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 },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       handler: async () => runtime2.team()
     },
     {
       name: "intercom_status",
       description: "Show intercom connection status, active sessions, unread messages, and pending asks.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       handler: async () => runtime2.status()
     },
     {
@@ -2531,6 +2659,7 @@ function buildToolDefinitions(runtime2) {
         },
         additionalProperties: false
       },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       handler: async (args) => runtime2.list(
         args.scope === "directory" || args.scope === "repo" ? args.scope : "machine",
         asBoolean(args.include_self, false)
@@ -2545,6 +2674,7 @@ function buildToolDefinitions(runtime2) {
         required: ["summary"],
         additionalProperties: false
       },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime2.setSummary(asString(args.summary, "summary"))
     },
     {
@@ -2560,6 +2690,7 @@ function buildToolDefinitions(runtime2) {
         required: ["to", "message"],
         additionalProperties: false
       },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
       handler: async (args) => runtime2.send(asString(args.to, "to"), asString(args.message, "message"), asAttachmentArray(args.attachments))
     },
     {
@@ -2576,6 +2707,7 @@ function buildToolDefinitions(runtime2) {
         required: ["to", "message"],
         additionalProperties: false
       },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
       handler: async (args, signal) => runtime2.ask(
         asString(args.to, "to"),
         asString(args.message, "message"),
@@ -2592,6 +2724,7 @@ function buildToolDefinitions(runtime2) {
         properties: { mark_read: { type: "boolean", default: false } },
         additionalProperties: false
       },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
       handler: async (args) => runtime2.pending(asBoolean(args.mark_read, false))
     },
     {
@@ -2607,6 +2740,7 @@ function buildToolDefinitions(runtime2) {
         required: ["message"],
         additionalProperties: false
       },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
       handler: async (args) => runtime2.reply(asString(args.message, "message"), typeof args.to === "string" ? args.to : void 0, args.which === "oldest" || args.which === "latest" ? args.which : void 0)
     }
   ];
@@ -2644,7 +2778,7 @@ async function handleMcpRequest(request, runtime2) {
       return ok(request.id, {});
     case "tools/list":
       return ok(request.id, {
-        tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }))
+        tools: tools.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations }))
       });
     case "tools/call": {
       const name = request.params?.name;

package/dist/worker-daemon.mjs

@@ -265,7 +265,8 @@ function runClaudeTurn(options) {
       child = spawn(command, launch.args, {
         cwd: launch.cwd,
         env: { ...process.env, ...options.env },
-        stdio: ["pipe", "pipe", "pipe"]
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: false
       });
     } finally {
       launch.release();
@@ -557,7 +558,8 @@ function isNativeClaudeVersionCompatible(version) {
 function probeClaudeVersion(command = "claude") {
   const result = spawnSync(command, ["--version"], {
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false
   });
   if (result.error || result.status !== 0) {
     return {
@@ -2054,7 +2056,8 @@ function getBrokerSpawnOptions(extensionDir = EXTENSION_DIR, env = process.env)
     stdio: "ignore",
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
-    windowsHide: true
+    windowsHide: true,
+    shell: false
   };
 }
 function toError2(error) {
@@ -2381,6 +2384,7 @@ function loadConfig() {
 
 // claude/team.ts
 import { PARTICIPANT_STATES, TERMINAL_PARTICIPANT_STATES } from "@ctliz/agent-intercom-core/boss";
+import { readTeamManifestAsync, TeamManifestError } from "@ctliz/agent-intercom-core/team-manifest";
 var BOSS_NONTERMINAL_STATES = new Set(
   PARTICIPANT_STATES.filter((state) => !TERMINAL_PARTICIPANT_STATES.includes(state))
 );
@@ -2425,14 +2429,14 @@ function copyTextToClipboard(text) {
     ["clip.exe", []]
   ];
   for (const [command, args] of candidates) {
-    if (spawnSync2("which", [command], { stdio: "ignore" }).status !== 0) continue;
+    if (spawnSync2("which", [command], { stdio: "ignore", shell: false }).status !== 0) continue;
     if (command === "wl-copy") {
-      const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+      const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"], shell: false });
       child.stdin.end(text);
       child.unref();
       return true;
     }
-    if (spawnSync2(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"] }).status === 0) return true;
+    if (spawnSync2(command, args, { input: text, stdio: ["pipe", "ignore", "ignore"], shell: false }).status === 0) return true;
   }
   return false;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-claude",
-  "version": "0.12.0-connect.3",
+  "version": "0.13.0-connect.3",
   "description": "Claude Code MCP plugin and wakeable worker for direct local messaging with Pi, Codex, and Claude coding-agent sessions.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -67,10 +67,10 @@
     "codex"
   ],
   "peerDependencies": {
-    "@ctliz/agent-intercom-core": "0.1.0"
+    "@ctliz/agent-intercom-core": "0.2.0"
   },
   "devDependencies": {
-    "@ctliz/agent-intercom-core": "git+https://github.com/ctliz/agent-intercom-core.git#37e074970e2a9de32a16fc325607c3b476b0bd45",
+    "@ctliz/agent-intercom-core": "0.2.0",
     "@types/node": "^24.0.0",
     "esbuild": "^0.28.1",
     "tsx": "^4.20.0",

package/scripts/verify-core-provenance.mjs

@@ -5,25 +5,25 @@ import { spawnSync } from "node:child_process";
 
 export const APPROVED_CORE = Object.freeze({
   name: "@ctliz/agent-intercom-core",
-  version: "0.1.0",
-  commit: "37e074970e2a9de32a16fc325607c3b476b0bd45",
-  integrity: "sha512-b5MXnfKh/RCjKoVor0tsFO+NKAqPROWgkgbHt7jiHxhdVbSh7gWvOdnVUtpSdPwJLYKSQrYXT+TJl7QocdJEPA==",
+  version: "0.2.0",
+  integrity: "sha512-bpifL9cc8cwMm74fpvjgRBarXMwn6BY4cST4ry6HrGtfpRTXyiJOtwfNnhORF6xTKwQNOWakxS1sZALczInvkQ==",
+  resolved: "https://registry.npmjs.org/@ctliz/agent-intercom-core/-/agent-intercom-core-0.2.0.tgz",
 });
 
 const repositoryRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
-const devSpec = `git+https://github.com/ctliz/agent-intercom-core.git#${APPROVED_CORE.commit}`;
+const devSpec = APPROVED_CORE.version;
 
 function readJson(path) {
   return JSON.parse(readFileSync(path, "utf8"));
 }
 
-function requireEqual(actual, expected, field) {
+export function requireEqual(actual, expected, field) {
   if (actual !== expected) {
     throw new Error(`${field} must be ${JSON.stringify(expected)}; received ${JSON.stringify(actual)}`);
   }
 }
 
-function verifyLocalProvenance() {
+export function verifyLocalProvenance() {
   const manifest = readJson(join(repositoryRoot, "package.json"));
   const lock = readJson(join(repositoryRoot, "package-lock.json"));
   const lockRoot = lock.packages?.[""];
@@ -36,28 +36,30 @@ function verifyLocalProvenance() {
   requireEqual(lockRoot?.peerDependencies?.[APPROVED_CORE.name], APPROVED_CORE.version, "locked Core peer dependency");
   requireEqual(lockRoot?.devDependencies?.[APPROVED_CORE.name], devSpec, "locked Core development provenance");
   requireEqual(lockedCore?.version, APPROVED_CORE.version, "supplied Core version");
-  requireEqual(lockedCore?.resolved, devSpec, "supplied Core commit");
+  requireEqual(lockedCore?.resolved, APPROVED_CORE.resolved, "supplied Core resolved URL");
   requireEqual(lockedCore?.integrity, APPROVED_CORE.integrity, "supplied Core artifact integrity");
   requireEqual(lockedCore?.dev, true, "supplied Core dependency class");
 }
 
-function verifyPublishedProvenance() {
-  const result = spawnSync("npm", [
+export function parseAndVerifyPublishedProvenance(jsonString) {
+  const published = typeof jsonString === "string" ? JSON.parse(jsonString) : jsonString;
+  requireEqual(published.version, APPROVED_CORE.version, "published Core version");
+  requireEqual(published["dist.integrity"] ?? published.dist?.integrity, APPROVED_CORE.integrity, "published Core artifact integrity");
+}
+
+export function verifyPublishedProvenance(runner = spawnSync) {
+  const result = runner("npm", [
     "view",
     `${APPROVED_CORE.name}@${APPROVED_CORE.version}`,
     "version",
     "dist.integrity",
-    "gitHead",
     "--json",
-  ], { encoding: "utf8" });
+  ], { encoding: "utf8", shell: false });
   if (result.error) throw result.error;
   if (result.status !== 0) {
     throw new Error(`Unable to inspect published Core ${APPROVED_CORE.version}: ${(result.stderr || result.stdout).trim()}`);
   }
-  const published = JSON.parse(result.stdout);
-  requireEqual(published.version, APPROVED_CORE.version, "published Core version");
-  requireEqual(published["dist.integrity"] ?? published.dist?.integrity, APPROVED_CORE.integrity, "published Core artifact integrity");
-  requireEqual(published.gitHead, APPROVED_CORE.commit, "published Core commit");
+  parseAndVerifyPublishedProvenance(result.stdout);
 }
 
 verifyLocalProvenance();

package/scripts/verify-packed-runtime.mjs

@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
 
 const repositoryRoot = resolve(import.meta.dirname, "..");
 const corePackage = "@ctliz/agent-intercom-core";
-const coreDevSpec = "git+https://github.com/ctliz/agent-intercom-core.git#37e074970e2a9de32a16fc325607c3b476b0bd45";
+const coreDevSpec = "0.2.0";
 const coreConsumers = new Set([
   "broker.mjs",
   "cci.mjs",
@@ -51,6 +51,7 @@ function createPackageArchive(temp) {
     cwd: repositoryRoot,
     env: { ...process.env, npm_config_cache: join(temp, "npm-cache") },
     encoding: "utf8",
+    shell: false,
   });
   if (result.error) throw result.error;
   if (result.status !== 0) throw new Error(`npm pack failed: ${result.stderr || result.stdout}`);
@@ -72,10 +73,10 @@ try {
   const manifestEntry = entries.get("package/package.json");
   if (!manifestEntry) throw new Error("Packed adapter is missing package.json");
   const manifest = JSON.parse(manifestEntry.toString("utf8"));
-  if (manifest.peerDependencies?.[corePackage] !== "0.1.0") throw new Error("Packed adapter must require Core peer 0.1.0");
+  if (manifest.peerDependencies?.[corePackage] !== "0.2.0") throw new Error("Packed adapter must require Core peer 0.2.0");
   if (manifest.peerDependenciesMeta?.[corePackage]?.optional === true) throw new Error("Packed Core peer must not be optional");
   if (manifest.dependencies?.[corePackage] !== undefined) throw new Error("Packed adapter must not install a private Core dependency");
-  if (manifest.devDependencies?.[corePackage] !== coreDevSpec) throw new Error("Packed adapter lost the approved Core build commit");
+  if (manifest.devDependencies?.[corePackage] !== coreDevSpec) throw new Error("Packed adapter lost the approved Core dependency");
   if ([...entries.keys()].some((path) => path.includes("node_modules/@ctliz/agent-intercom-core/"))) {
     throw new Error("Packed adapter contains a private Core module tree");
   }
@@ -134,7 +135,7 @@ try {
     }
   }
 
-  console.log(`Verified complete plugin+MCP+monitors+dist chain and ${bundles.length} packed bundles using Core peer 0.1.0`);
+  console.log(`Verified complete plugin+MCP+monitors+dist chain and ${bundles.length} packed bundles using Core peer 0.2.0`);
 } finally {
   if (temp) rmSync(temp, { recursive: true, force: true });
 }