@agenticmail/claudecode 0.2.18 → 0.2.20

package/dist/{chunk-O7S3FYJT.js → chunk-7FQNH2YO.js}

@@ -273,6 +273,35 @@ function renderPersonaBody(input) {
     "",
     `**Closing a thread.** When the work is genuinely done and no more contributions are needed, send a wrap-up reply with one of these markers in the subject: \`[FINAL]\`, \`[DONE]\`, \`[CLOSED]\`, or \`[WRAP]\` PAIRED with \`wake: []\`. The marker tells the dispatcher to stop waking workers; the empty wake confirms you mean it. Use this when YOU are the one signing off the work, not as a routine ack. ANY OTHER use of \`wake: []\` is a bug.`,
     "",
+    `**Handing off to the host bridge (\`claudecode\` / \`codex\`) \u2014 read this carefully too.** The host bridge inboxes belong to the HUMAN OPERATOR's host session, not to an automated worker. The dispatcher DOES NOT spawn worker turns for them \u2014 they're surfaced to the operator via host-session hooks (Stop / UserPromptSubmit) when the operator's CLI is actively running. If no host session is open, mail to the bridge sits unread.`,
+    "",
+    `Practical implications:`,
+    `  \xB7 DO NOT use bridge handoffs as a default "punt the baton when you don't know what to do" move. The chain dies if the operator isn't watching.`,
+    `  \xB7 BEFORE handing off to the bridge, ask: is there a teammate (another sub-agent) who could decide this instead? If yes, route to them and CC the bridge as an FYI observer (do not name the bridge in \`wake\`).`,
+    `  \xB7 ONLY hand off to the bridge when you genuinely need the operator's judgment \u2014 billing-side rate limits, scope changes, architectural calls only the human can make, ambiguous spec questions where no sub-agent has authority. Treat it like paging a human at 2am: legitimate sometimes, rude often.`,
+    `  \xB7 WHEN you must escalate, mark the subject with \`[NEEDS OPERATOR]\` or \`[BLOCKED]\` so the operator's notification feed surfaces it. State the exact question + the options + your recommendation in the body. Don't make them re-read the thread.`,
+    `  \xB7 You can name the bridge in \`wake: ["claudecode"]\` / \`wake: ["codex"]\` to signal intent \u2014 the dispatcher still won't spawn a worker (bridges are filtered), but the web UI's notification sound + system event still fires so an attentive operator hears it.`,
+    "",
+    `Example \u2014 correct operator-escalation:`,
+    "",
+    "```",
+    `${tool("reply_email")}({ uid: 42, replyAll: true, _account: "${agent.name}",`,
+    `  subject: "[NEEDS OPERATOR] Slice 4 \u2014 Stripe vs Lemon Squeezy",`,
+    `  text: "Team: I've prototyped both. Stripe = better SDK, more compliance work. Lemon = faster ship, 5% take.\\nThis is a business call, not a code call. Operator \u2014 your pick?\\n\\nMy recommendation: Lemon for v0, swap later.",`,
+    `  wake: ["claudecode"] })  // signals intent; doesn't spawn a worker`,
+    "```",
+    "",
+    `Example \u2014 WRONG (this is how threads die):`,
+    "",
+    "```",
+    `// You finished your slice and don't know who's next. DO NOT do this:`,
+    `${tool("reply_email")}({ uid: 42, replyAll: true, _account: "${agent.name}",`,
+    `  text: "Shipped my slice. Claudecode \u2014 over to you for next steps.",`,
+    `  wake: ["claudecode"] })`,
+    `// Bridge sits unread until the operator notices.`,
+    `// Instead: bounce the baton to a teammate who can act, e.g. wake: ["vesper"].`,
+    "```",
+    "",
     `**When to use \`${tool("call_agent")}\` instead:** only when you need ONE structured answer from ONE teammate, inline in your current turn \u2014 e.g. "give me a JSON list of X". For multi-step / multi-agent work, the thread pattern above is the right primitive.`,
     "",
     `On-demand (via invoke) examples \u2014 anything NOT in the pre-loaded list:`,

package/dist/{chunk-WC5ZK4RG.js → chunk-ALWSCQFP.js}

@@ -4,7 +4,7 @@ import {
   listPendingTasksForAgent,
   renderPersonaBody,
   resolveConfig
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 
 // src/persona-loader.ts
 import { existsSync, readFileSync } from "fs";
@@ -160,7 +160,95 @@ var DispatcherState = class {
 import { mkdirSync as mkdirSync2, createWriteStream, rmSync } from "fs";
 import { join as join3 } from "path";
 import { homedir as homedir2 } from "os";
-import { ThreadCache, AgentMemoryStore, threadIdFor, normalizeSubject } from "@agenticmail/core";
+import { ThreadCache, AgentMemoryStore, threadIdFor, normalizeSubject, loadHostSession, forgetHostSession } from "@agenticmail/core";
+
+// src/bridge-wake.ts
+async function resumeBridgeSession(query, input, log) {
+  const startMs = Date.now();
+  const timeoutMs = input.timeoutMs ?? 5 * 60 * 1e3;
+  let result = { ok: false };
+  try {
+    log("info", `[bridge-wake] resuming Claude Code session ${input.sessionId.slice(0, 8)}\u2026 for ${input.bridge.name}`);
+    const opts = {
+      resume: input.sessionId,
+      cwd: input.cwd,
+      mcpServers: {
+        agenticmail: {
+          command: "agenticmail-mcp",
+          args: [],
+          env: input.mcpEnv
+        }
+      },
+      permissionMode: "bypassPermissions",
+      // Headless mode — no stdin tty.
+      includePartialMessages: false
+    };
+    let assistantText = "";
+    let timedOut = false;
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+    }, timeoutMs);
+    timeoutHandle.unref?.();
+    try {
+      const stream = query({ prompt: input.prompt, options: opts });
+      for await (const event of stream) {
+        if (timedOut) break;
+        const e = event;
+        if (e.type === "assistant" && Array.isArray(e.message?.content)) {
+          for (const block of e.message.content) {
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string") {
+              assistantText = b.text;
+            }
+          }
+        }
+      }
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+    if (timedOut) {
+      log("warn", `[bridge-wake] timeout after ${timeoutMs}ms \u2014 bridge wake gave up`);
+      return { ok: false, error: "timeout", durationMs: Date.now() - startMs };
+    }
+    result = { ok: true, text: assistantText, durationMs: Date.now() - startMs };
+    log("info", `[bridge-wake] resumed session ok (${result.durationMs}ms, ${assistantText.length} chars)`);
+    return result;
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    const m = msg.toLowerCase();
+    const expired = m.includes("session not found") || m.includes("invalid session") || m.includes("session expired") || m.includes("no such session") || m.includes("unknown session");
+    const sdkMissing = m.includes("cannot find module") || m.includes("could not be found") || m.includes("command not found");
+    const error = expired ? "session-expired" : sdkMissing ? "sdk-missing" : "other";
+    log("warn", `[bridge-wake] resume failed (${error}): ${msg.slice(0, 200)}`);
+    return { ok: false, error, errorMessage: msg, durationMs: Date.now() - startMs };
+  }
+}
+function composeBridgeWakePrompt(args) {
+  const subject = args.subject ?? "(no subject)";
+  const from = args.from ?? "unknown";
+  const preview = (args.preview ?? "").slice(0, 600);
+  return [
+    `\u{1F380} Bridge mail arrived \u2014 headless wake.`,
+    "",
+    `You are being resumed against your last session because new mail landed in your bridge inbox (${args.bridgeName}@localhost) and you weren't actively at the keyboard.`,
+    "",
+    `Trigger:`,
+    `  UID:     ${args.uid}`,
+    `  From:    ${from}`,
+    `  Subject: ${subject}`,
+    `  Preview: ${preview}`,
+    "",
+    `Read it with mcp__agenticmail__read_email({ uid: ${args.uid} }) and decide:`,
+    `  \xB7 Does it need a reply from YOU (the operator's session)? Reply via mcp__agenticmail__reply_email.`,
+    `  \xB7 Does it need a teammate to act? Forward / re-route by replying with wake: ["<teammate>"].`,
+    `  \xB7 Is it [NEEDS OPERATOR] / [BLOCKED]? Then it's actually for the human \u2014 mark it unread, and the operator will see it on their next keystroke.`,
+    `  \xB7 Is it FYI noise? mark_read and exit.`,
+    "",
+    `Keep this turn SHORT. You're being resumed to handle ONE piece of mail, not to continue the prior conversation.`
+  ].join("\n");
+}
+
+// src/dispatcher.ts
 function extractSubject(event) {
   if (typeof event.subject === "string") return event.subject;
   if (event.message && typeof event.message.subject === "string") return event.message.subject;
@@ -761,6 +849,14 @@ var Dispatcher = class _Dispatcher {
   /** Public for tests — directly hand an event to the routing path. */
   async handleEvent(account, event) {
     if (this.stopped) return;
+    if (event.type === "new" && typeof event.uid === "number" && account.name.toLowerCase() === this.cfg.bridgeAgentName.toLowerCase()) {
+      const ch = this.channels.get(account.id);
+      if (ch?.seenUids.has(event.uid)) return;
+      if (ch) rememberBounded(ch.seenUids, event.uid);
+      this.state.markSeen(account.id, event.uid);
+      void this.handleBridgeMail(account, event);
+      return;
+    }
     if (event.type === "new" && typeof event.uid === "number") {
       const ch = this.channels.get(account.id);
       if (ch?.seenUids.has(event.uid)) return;
@@ -860,7 +956,7 @@ var Dispatcher = class _Dispatcher {
   shouldWatch(account) {
     const bridgeName = this.cfg.bridgeAgentName.toLowerCase();
     const meta = account.metadata;
-    if (account.name.toLowerCase() === bridgeName) return false;
+    if (account.name.toLowerCase() === bridgeName) return true;
     if (account.role === "bridge") return false;
     if (meta && meta.bridge === true) return false;
     if (meta && typeof meta.host === "string" && meta.host.length > 0) {
@@ -1333,6 +1429,107 @@ var Dispatcher = class _Dispatcher {
     sections.push("this thread will load that memory into context for you.");
     return sections.join("\n");
   }
+  /**
+   * Handle mail that lands in the host's OWN bridge inbox.
+   *
+   * Unlike normal sub-agent wakes (which spawn a fresh worker turn),
+   * bridge wakes resume the operator's last interactive session via
+   * the Claude Agent SDK's `resume` option — keeping the operator's
+   * context intact and avoiding a duplicate "second Claude trying to
+   * be Claude Code". When no fresh session is available (operator
+   * hasn't run `claude` in >24h, or `~/.agenticmail/host-sessions.json`
+   * was wiped), the dispatcher emits an `urgent` system event so the
+   * web UI's notification surface + any future SMS escalation hook
+   * can pick it up. See packages/claudecode/src/bridge-wake.ts.
+   *
+   * Two short-circuits:
+   *   1. If lastSeenMs is within 30s, the operator is actively at the
+   *      keyboard right now — their own UserPromptSubmit / Stop hook
+   *      will surface the mail on their next keystroke. We skip the
+   *      resume entirely to avoid token waste.
+   *   2. If a previous bridge-wake for this same UID is already
+   *      in-flight (same key in `inFlightBridgeWakes`), skip — IMAP
+   *      IDLE replays + SSE reconnects can fire the same event
+   *      twice and we don't want to double-resume.
+   */
+  inFlightBridgeWakes = /* @__PURE__ */ new Set();
+  async handleBridgeMail(account, event) {
+    if (typeof event.uid !== "number") return;
+    if (this.inFlightBridgeWakes.has(event.uid)) return;
+    this.inFlightBridgeWakes.add(event.uid);
+    const startMs = Date.now();
+    const subject = extractSubject(event);
+    const from = extractFrom(event);
+    const preview = event.preview ?? event.message?.preview ?? "";
+    try {
+      const saved = loadHostSession("claudecode");
+      if (saved && Date.now() - saved.lastSeenMs < 3e4) {
+        this.log("info", `[bridge-wake] skip \u2014 operator is live (lastSeen=${Date.now() - saved.lastSeenMs}ms ago); their hook will surface uid=${event.uid}`);
+        this.postActivity("/dispatcher/bridge-skipped", {
+          uid: event.uid,
+          agentName: account.name,
+          reason: "operator-live"
+        });
+        return;
+      }
+      if (!saved) {
+        this.log("warn", `[bridge-wake] no fresh Claude Code session recorded \u2014 bridge mail uid=${event.uid} cannot resume. Escalating via system-event.`);
+        this.postActivity("/dispatcher/bridge-escalation", {
+          uid: event.uid,
+          agentName: account.name,
+          subject,
+          from,
+          preview,
+          reason: "no-fresh-session"
+        });
+        return;
+      }
+      const mcpEnv = await this.buildMcpEnv();
+      const prompt = composeBridgeWakePrompt({
+        bridgeName: account.name,
+        uid: event.uid,
+        subject,
+        from,
+        preview
+      });
+      const result = await resumeBridgeSession(this.query, {
+        bridge: account,
+        sessionId: saved.sessionId,
+        cwd: saved.workspace,
+        prompt,
+        mcpEnv
+      }, this.log);
+      if (result.ok) {
+        this.postActivity("/dispatcher/bridge-resumed", {
+          uid: event.uid,
+          agentName: account.name,
+          subject,
+          from,
+          durationMs: result.durationMs,
+          resultPreview: result.text?.slice(0, 240)
+        });
+      } else {
+        if (result.error === "session-expired") {
+          this.log("warn", `[bridge-wake] session expired; forgetting and escalating uid=${event.uid}`);
+          forgetHostSession("claudecode");
+        }
+        this.postActivity("/dispatcher/bridge-escalation", {
+          uid: event.uid,
+          agentName: account.name,
+          subject,
+          from,
+          preview,
+          reason: result.error ?? "resume-failed",
+          errorMessage: result.errorMessage
+        });
+      }
+    } catch (err) {
+      this.log("error", `[bridge-wake] uid=${event.uid} threw: ${err.message}`);
+    } finally {
+      this.inFlightBridgeWakes.delete(event.uid);
+      this.log("info", `[bridge-wake] finished uid=${event.uid} in ${Date.now() - startMs}ms`);
+    }
+  }
   /** Acquire a concurrency slot, run a worker, release the slot. */
   async spawnWorker(account, prompt, ctx) {
     const releaseAgentLock = await this.acquireAgentSerial(account.id);

package/dist/{chunk-OMUB5FRY.js → chunk-HCZTDR4T.js}

@@ -7,7 +7,7 @@ import {
   MANAGED_BY_MARKER,
   getAccountByName,
   resolveConfig
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 
 // src/status.ts
 import { existsSync, readFileSync, readdirSync } from "fs";

package/dist/{chunk-4NKBITBR.js → chunk-NCV65VKS.js}

@@ -14,7 +14,7 @@ import {
   resolveConfig,
   setAccountHost,
   setAccountRole
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 
 // src/install.ts
 import { existsSync, mkdirSync, readdirSync, writeFileSync, readFileSync, unlinkSync } from "fs";

package/dist/{chunk-EWHWSNAQ.js → chunk-QXFCUEN3.js}

@@ -1,15 +1,15 @@
 import {
   status
-} from "./chunk-OMUB5FRY.js";
+} from "./chunk-HCZTDR4T.js";
 import {
   uninstall
-} from "./chunk-7D3D7T34.js";
+} from "./chunk-ZVIW6BL2.js";
 import {
   install
-} from "./chunk-4NKBITBR.js";
+} from "./chunk-NCV65VKS.js";
 import {
   AgenticMailApiError
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 
 // src/http-routes.ts
 import { Router } from "express";

package/dist/{chunk-7D3D7T34.js → chunk-ZVIW6BL2.js}

@@ -10,7 +10,7 @@ import {
   deleteAccount,
   getAccountByName,
   resolveConfig
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 
 // src/uninstall.ts
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "fs";

package/dist/cli.js

@@ -6,13 +6,13 @@ import {
 } from "./chunk-B5JDOV32.js";
 import {
   status
-} from "./chunk-OMUB5FRY.js";
+} from "./chunk-HCZTDR4T.js";
 import {
   uninstall
-} from "./chunk-7D3D7T34.js";
+} from "./chunk-ZVIW6BL2.js";
 import {
   install
-} from "./chunk-4NKBITBR.js";
+} from "./chunk-NCV65VKS.js";
 import "./chunk-SWDS64K2.js";
 import "./chunk-7DGWW72Q.js";
 import {
@@ -20,7 +20,7 @@ import {
   listAccounts,
   resolveConfig,
   setAccountHost
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 
 // src/cli.ts
 var GREEN = (s) => `\x1B[32m${s}\x1B[0m`;

package/dist/dispatcher-bin.js

@@ -4,8 +4,8 @@ import {
 } from "./chunk-B5JDOV32.js";
 import {
   Dispatcher
-} from "./chunk-WC5ZK4RG.js";
-import "./chunk-O7S3FYJT.js";
+} from "./chunk-ALWSCQFP.js";
+import "./chunk-7FQNH2YO.js";
 
 // src/dispatcher-bin.ts
 async function main() {

package/dist/dispatcher.d.ts

@@ -370,6 +370,31 @@ declare class Dispatcher {
         subject?: string;
         uid?: number;
     }, prompt: string): string;
+    /**
+     * Handle mail that lands in the host's OWN bridge inbox.
+     *
+     * Unlike normal sub-agent wakes (which spawn a fresh worker turn),
+     * bridge wakes resume the operator's last interactive session via
+     * the Claude Agent SDK's `resume` option — keeping the operator's
+     * context intact and avoiding a duplicate "second Claude trying to
+     * be Claude Code". When no fresh session is available (operator
+     * hasn't run `claude` in >24h, or `~/.agenticmail/host-sessions.json`
+     * was wiped), the dispatcher emits an `urgent` system event so the
+     * web UI's notification surface + any future SMS escalation hook
+     * can pick it up. See packages/claudecode/src/bridge-wake.ts.
+     *
+     * Two short-circuits:
+     *   1. If lastSeenMs is within 30s, the operator is actively at the
+     *      keyboard right now — their own UserPromptSubmit / Stop hook
+     *      will surface the mail on their next keystroke. We skip the
+     *      resume entirely to avoid token waste.
+     *   2. If a previous bridge-wake for this same UID is already
+     *      in-flight (same key in `inFlightBridgeWakes`), skip — IMAP
+     *      IDLE replays + SSE reconnects can fire the same event
+     *      twice and we don't want to double-resume.
+     */
+    private inFlightBridgeWakes;
+    private handleBridgeMail;
     /** Acquire a concurrency slot, run a worker, release the slot. */
     private spawnWorker;
     /**

package/dist/dispatcher.js

@@ -1,7 +1,7 @@
 import {
   Dispatcher
-} from "./chunk-WC5ZK4RG.js";
-import "./chunk-O7S3FYJT.js";
+} from "./chunk-ALWSCQFP.js";
+import "./chunk-7FQNH2YO.js";
 export {
   Dispatcher
 };

package/dist/http-routes.js

@@ -1,12 +1,12 @@
 import {
   createIntegrationRoutes
-} from "./chunk-EWHWSNAQ.js";
-import "./chunk-OMUB5FRY.js";
-import "./chunk-7D3D7T34.js";
-import "./chunk-4NKBITBR.js";
+} from "./chunk-QXFCUEN3.js";
+import "./chunk-HCZTDR4T.js";
+import "./chunk-ZVIW6BL2.js";
+import "./chunk-NCV65VKS.js";
 import "./chunk-SWDS64K2.js";
 import "./chunk-7DGWW72Q.js";
-import "./chunk-O7S3FYJT.js";
+import "./chunk-7FQNH2YO.js";
 export {
   createIntegrationRoutes
 };

package/dist/index.js

@@ -6,19 +6,19 @@ import {
 import {
   Dispatcher,
   loadPersonaForAgent
-} from "./chunk-WC5ZK4RG.js";
+} from "./chunk-ALWSCQFP.js";
 import {
   createIntegrationRoutes
-} from "./chunk-EWHWSNAQ.js";
+} from "./chunk-QXFCUEN3.js";
 import {
   status
-} from "./chunk-OMUB5FRY.js";
+} from "./chunk-HCZTDR4T.js";
 import {
   uninstall
-} from "./chunk-7D3D7T34.js";
+} from "./chunk-ZVIW6BL2.js";
 import {
   install
-} from "./chunk-4NKBITBR.js";
+} from "./chunk-NCV65VKS.js";
 import "./chunk-SWDS64K2.js";
 import "./chunk-7DGWW72Q.js";
 import {
@@ -32,7 +32,7 @@ import {
   renderPersonaBody,
   renderSubagentMarkdown,
   resolveConfig
-} from "./chunk-O7S3FYJT.js";
+} from "./chunk-7FQNH2YO.js";
 export {
   AgenticMailApiError,
   Dispatcher,

package/dist/install.js

@@ -1,10 +1,10 @@
 import {
   install,
   selectExposableAgents
-} from "./chunk-4NKBITBR.js";
+} from "./chunk-NCV65VKS.js";
 import "./chunk-SWDS64K2.js";
 import "./chunk-7DGWW72Q.js";
-import "./chunk-O7S3FYJT.js";
+import "./chunk-7FQNH2YO.js";
 export {
   install,
   selectExposableAgents

package/dist/mail-hook.js

@@ -4,6 +4,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { homedir } from "os";
 import { join, dirname } from "path";
+import { saveHostSession } from "@agenticmail/core";
 var AGENTICMAIL_DIR = join(homedir(), ".agenticmail");
 var CONFIG_PATH = join(AGENTICMAIL_DIR, "config.json");
 var CURSOR_PATH = join(AGENTICMAIL_DIR, "claudecode-hook-cursor.json");
@@ -92,6 +93,12 @@ async function main() {
   const input = await readStdinJson();
   const eventName = input?.hook_event_name ?? "UserPromptSubmit";
   const sessionId = typeof input?.session_id === "string" ? input.session_id : "";
+  if (sessionId) {
+    try {
+      saveHostSession("claudecode", { sessionId, workspace: process.cwd() });
+    } catch {
+    }
+  }
   if (eventName === "SessionStart") {
     process.stdout.write(JSON.stringify({
       hookSpecificOutput: {

package/dist/status.js

@@ -1,8 +1,8 @@
 import {
   status
-} from "./chunk-OMUB5FRY.js";
+} from "./chunk-HCZTDR4T.js";
 import "./chunk-7DGWW72Q.js";
-import "./chunk-O7S3FYJT.js";
+import "./chunk-7FQNH2YO.js";
 export {
   status
 };

package/dist/uninstall.js

@@ -1,9 +1,9 @@
 import {
   uninstall
-} from "./chunk-7D3D7T34.js";
+} from "./chunk-ZVIW6BL2.js";
 import "./chunk-SWDS64K2.js";
 import "./chunk-7DGWW72Q.js";
-import "./chunk-O7S3FYJT.js";
+import "./chunk-7FQNH2YO.js";
 export {
   uninstall
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Claude Code integration for AgenticMail — surfaces every AgenticMail agent as a native Claude Code subagent so any Claude Code session can delegate to them with the Agent tool",
   "type": "module",
   "main": "dist/index.js",
@@ -47,7 +47,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agenticmail/core": "^0.9.5",
+    "@agenticmail/core": "^0.9.6",
     "@agenticmail/mcp": "^0.9.7",
     "@anthropic-ai/claude-agent-sdk": "^0.2.140"
   },