@ctliz/agent-intercom-claude 0.16.0 → 0.16.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-intercom",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Claude Code MCP plugin and wakeable worker for local Pi/Codex/Claude intercom messaging.",
   "author": {
     "name": "ctliz",

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.1 - 2026-11-01
+
+- Align `intercom_ask` soft-wait timeouts with Pi: defer timed-out asks on the broker (`ok: true`, `pending: true`, `deferred: true`) instead of cancelling them, so late `intercom_reply` answers still succeed; retain `cancelAsk` for explicit aborts.
+- Align MCP tool `annotations` with Pi (`openWorldHint: false` for all local IPC tools and `destructiveHint: false` for `intercom_set_summary`, `intercom_pending`, and `intercom_reply`) so Claude Code auto-mode and companion Grok permission gates do not prompt unnecessarily.
+- Document plugin-first `claude` interactive usage on Claude Code 2.1.316 alongside Channels and headless worker modes.
+
 ## 0.16.0 - 2026-10-11
 
 - Add opt-in `cci --tui --channel` wakeups through Claude Code Channels, sharing the existing MCP identity and unread inbox. Messages queued before initialization trigger a notice without a first user prompt.

package/README.md

@@ -41,7 +41,7 @@ AGENT_INTERCOM_SCOPE_ID=<shared-team-or-workspace-scope>
 
 The plugin manifests intentionally do not contain static session IDs, because sharing one ID across concurrent panes would create identity collisions. `CLAUDE_INTERCOM_SESSION_ID` and `CLAUDE_INTERCOM_NAME` remain higher-priority compatibility aliases.
 
-Grok Build and AGY currently provide polling-only MCP integrations. Messages are durably retained, but there is no host-specific wake bridge to inject a new turn. Each active agent should call `intercom_pending` at startup and at natural work boundaries. They can join an existing team and exchange messages with every other adapter, but Agent Intercom Orchestrator does not currently spawn or lifecycle-manage Grok or AGY workers.
+Grok Build supports native `monitor` and leader `_x.ai/interject` wakeups through `@ctliz/agent-intercom-grok`; AGY currently provides a polling-only MCP integration. Both join teams and exchange messages with every other adapter, while Agent Intercom Orchestrator does not currently spawn or lifecycle-manage Grok or AGY workers.
 
 ## Maintenance & Upstream Provenance
 
@@ -92,13 +92,12 @@ have it act with real system access.
 
 ## Status
 
-Preview. This is the Claude-side adapter, built alongside `pi-intercom` and
-`codex-intercom`.
+Tested with Claude Code 2.1.316.
 
-A plain Claude Code MCP session does not receive unsolicited visible turns.
-Incoming messages are queued while the MCP server is running; call
-`intercom_pending` to read them. Wake-on-message workflows use `cci` /
-`claude-intercom-worker`.
+- **Plugin mode (`claude` directly — Pi-consistent interactive workflow)**: Installing the packaged Claude Code plugin gives ordinary `claude` sessions automatic eager broker registration (`SessionStart`/`SessionEnd` hooks), native `/rename` presence synchronization, automatic inbound wakeups (`monitors/monitors.json`), and `/claude-intercom:intercom*` slash commands without a wrapper CLI.
+- **Channel mode (`cci --tui --channel`)**: Uses Claude Code Channels (`notifications/claude/channel`) for cold-start wakeups before the first user prompt.
+- **Headless worker mode (`cci` / `claude-intercom-worker`)**: Runs resumable headless `claude -p --resume` turns for background worker daemons and `agent-intercom-orchestrator`.
+- **Bare MCP-only mode (`claude mcp add`)**: Without the plugin's hooks and monitor, incoming messages remain queued until read with `intercom_pending`.
 
 ## How Claude gets woken
 

package/claude/mcp-protocol.ts

@@ -102,7 +102,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
       name: "intercom_team",
       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 },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.team(optionalString(args.team, "team")),
     },
     {
@@ -118,7 +118,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         },
         additionalProperties: false,
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args) => runtime.join(
         optionalString(args.name, "name"),
         args.create === true,
@@ -130,7 +130,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
       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 },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async () => runtime.status(),
     },
     {
@@ -144,7 +144,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         },
         additionalProperties: false,
       },
-      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.list(
         args.scope === "directory" || args.scope === "repo" ? args.scope : "machine",
         asBoolean(args.include_self, false),
@@ -159,7 +159,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         required: ["summary"],
         additionalProperties: false,
       },
-      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.setSummary(asString(args.summary, "summary")),
     },
     {
@@ -176,7 +176,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         required: ["to", "message"],
         additionalProperties: false,
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args) => runtime.send(asString(args.to, "to"), asString(args.message, "message"), asAttachmentArray(args.attachments), undefined, optionalString(args.team, "team")),
     },
     {
@@ -189,12 +189,12 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
           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." },
+          timeout_ms: { type: "integer", minimum: 1, maximum: 120000, description: "Soft wait in milliseconds before continuing asynchronously (default 30000, max 120000); timed-out asks remain open for late replies." },
         },
         required: ["to", "message"],
         additionalProperties: false,
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args, signal) => runtime.ask(
         asString(args.to, "to"),
         asString(args.message, "message"),
@@ -212,7 +212,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 },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.pending(asBoolean(args.mark_read, false)),
     },
     {
@@ -231,7 +231,7 @@ export function buildToolDefinitions(runtime: ClaudeIntercomRuntime): ToolDefini
         required: ["message"],
         additionalProperties: false,
       },
-      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       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")),
     },
   ];

package/claude/runtime.ts

@@ -216,6 +216,19 @@ export interface ClaudeIntercomRuntimeOptions {
   reconnectDelays?: number[];
 }
 
+class AskWaitElapsedError extends Error {
+  readonly from: string;
+  readonly replyTo: string;
+  readonly waitMs: number;
+  constructor(from: string, replyTo: string, waitMs: number) {
+    super(`No reply from "${from}" within ${Math.round(waitMs / 1000)} seconds`);
+    this.name = "AskWaitElapsedError";
+    this.from = from;
+    this.replyTo = replyTo;
+    this.waitMs = waitMs;
+  }
+}
+
 export class ClaudeIntercomRuntime {
   private client: IntercomClient | null = null;
   private connectPromise: Promise<IntercomClient> | null = null;
@@ -474,9 +487,8 @@ export class ClaudeIntercomRuntime {
       };
       timeout = setTimeout(() => {
         this.replyWaiters.delete(replyTo);
-        void this.client?.deferAsk(replyTo);
         signal?.removeEventListener("abort", onAbort);
-        reject(new Error(`No reply from "${from}" within ${Math.round(timeoutMs / 1000)} seconds`));
+        reject(new AskWaitElapsedError(from, replyTo, timeoutMs));
       }, timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
       this.replyWaiters.set(replyTo, { from, replyTo, team, resolve, reject, timeout, cleanup });
@@ -597,6 +609,16 @@ export class ClaudeIntercomRuntime {
       const replyText = `${reply.content.text}${formatAttachments(reply.content.attachments)}`;
       return textResult(`Reply from ${to}:\n${replyText}`, { ok: true, message_id: result.id, reply });
     } catch (error) {
+      if (error instanceof AskWaitElapsedError) {
+        const deferred = await client.deferAsk(error.replyTo);
+        const seconds = Math.round(error.waitMs / 1000);
+        return textResult(
+          deferred
+            ? `No reply from "${to}" within ${seconds}s. The ask remains open asynchronously; continue only independent work and handle the late reply when it arrives.`
+            : `No reply from "${to}" within ${seconds}s; ask is no longer open.`,
+          { ok: true, pending: deferred, deferred, message_id: questionId, to, ...(team ? { team } : {}) },
+        );
+      }
       void client.cancelAsk(questionId);
       return textResult(error instanceof Error ? error.message : String(error), { ok: false }, true);
     }

package/dist/claude-server.mjs

@@ -2552,6 +2552,18 @@ function textResult(text, structuredContent, isError = false) {
     ...isError ? { isError: true } : {}
   };
 }
+var AskWaitElapsedError = class extends Error {
+  from;
+  replyTo;
+  waitMs;
+  constructor(from, replyTo, waitMs) {
+    super(`No reply from "${from}" within ${Math.round(waitMs / 1e3)} seconds`);
+    this.name = "AskWaitElapsedError";
+    this.from = from;
+    this.replyTo = replyTo;
+    this.waitMs = waitMs;
+  }
+};
 var ClaudeIntercomRuntime = class {
   client = null;
   connectPromise = null;
@@ -2789,9 +2801,8 @@ Other team memberships are unchanged.`, { ok: true, team: team.name, role: roste
       };
       timeout = setTimeout(() => {
         this.replyWaiters.delete(replyTo);
-        void this.client?.deferAsk(replyTo);
         signal?.removeEventListener("abort", onAbort);
-        reject(new Error(`No reply from "${from}" within ${Math.round(timeoutMs / 1e3)} seconds`));
+        reject(new AskWaitElapsedError(from, replyTo, timeoutMs));
       }, timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
       this.replyWaiters.set(replyTo, { from, replyTo, team, resolve: resolve3, reject, timeout, cleanup });
@@ -2913,6 +2924,14 @@ Pending asks: ${this.unresolvedAsks.size}`,
       return textResult(`Reply from ${to}:
 ${replyText}`, { ok: true, message_id: result.id, reply });
     } catch (error2) {
+      if (error2 instanceof AskWaitElapsedError) {
+        const deferred = await client.deferAsk(error2.replyTo);
+        const seconds = Math.round(error2.waitMs / 1e3);
+        return textResult(
+          deferred ? `No reply from "${to}" within ${seconds}s. The ask remains open asynchronously; continue only independent work and handle the late reply when it arrives.` : `No reply from "${to}" within ${seconds}s; ask is no longer open.`,
+          { ok: true, pending: deferred, deferred, message_id: questionId, to, ...team ? { team } : {} }
+        );
+      }
       void client.cancelAsk(questionId);
       return textResult(error2 instanceof Error ? error2.message : String(error2), { ok: false }, true);
     }
@@ -3035,7 +3054,7 @@ function buildToolDefinitions(runtime) {
       name: "intercom_team",
       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 },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.team(optionalString(args.team, "team"))
     },
     {
@@ -3051,7 +3070,7 @@ function buildToolDefinitions(runtime) {
         },
         additionalProperties: false
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args) => runtime.join(
         optionalString(args.name, "name"),
         args.create === true,
@@ -3063,7 +3082,7 @@ function buildToolDefinitions(runtime) {
       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 },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async () => runtime.status()
     },
     {
@@ -3077,7 +3096,7 @@ function buildToolDefinitions(runtime) {
         },
         additionalProperties: false
       },
-      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.list(
         args.scope === "directory" || args.scope === "repo" ? args.scope : "machine",
         asBoolean(args.include_self, false)
@@ -3092,7 +3111,7 @@ function buildToolDefinitions(runtime) {
         required: ["summary"],
         additionalProperties: false
       },
-      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.setSummary(asString(args.summary, "summary"))
     },
     {
@@ -3109,7 +3128,7 @@ function buildToolDefinitions(runtime) {
         required: ["to", "message"],
         additionalProperties: false
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args) => runtime.send(asString(args.to, "to"), asString(args.message, "message"), asAttachmentArray(args.attachments), void 0, optionalString(args.team, "team"))
     },
     {
@@ -3122,12 +3141,12 @@ function buildToolDefinitions(runtime) {
           message: { type: "string" },
           attachments: attachmentsSchema,
           team: { type: "string", description: "Task team; required when multiple teams are shared." },
-          timeout_ms: { type: "integer", minimum: 1, maximum: 12e4, description: "Maximum time to wait for a reply before returning an error. Use intercom_send plus intercom_pending for longer work." }
+          timeout_ms: { type: "integer", minimum: 1, maximum: 12e4, description: "Soft wait in milliseconds before continuing asynchronously (default 30000, max 120000); timed-out asks remain open for late replies." }
         },
         required: ["to", "message"],
         additionalProperties: false
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args, signal) => runtime.ask(
         asString(args.to, "to"),
         asString(args.message, "message"),
@@ -3145,7 +3164,7 @@ function buildToolDefinitions(runtime) {
         properties: { mark_read: { type: "boolean", default: false } },
         additionalProperties: false
       },
-      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       handler: async (args) => runtime.pending(asBoolean(args.mark_read, false))
     },
     {
@@ -3164,7 +3183,7 @@ function buildToolDefinitions(runtime) {
         required: ["message"],
         additionalProperties: false
       },
-      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       handler: async (args) => runtime.reply(asString(args.message, "message"), typeof args.to === "string" ? args.to : void 0, args.which === "oldest" || args.which === "latest" ? args.which : void 0, optionalString(args.askId, "askId"), optionalString(args.contextId, "contextId"), optionalString(args.team, "team"))
     }
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-claude",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Claude Code MCP plugin and wakeable worker for local messaging with Pi, Codex, OpenCode, Grok Build, and AGY agents.",
   "license": "AGPL-3.0-or-later",
   "type": "module",