@agenticmail/claudecode 0.2.7 → 0.2.9

package/dist/{chunk-JUEHPFKY.js → chunk-2RVJ2Q3W.js}

@@ -1,6 +1,6 @@
 import {
   removeUserPromptSubmitHook
-} from "./chunk-DKTAW2N5.js";
+} from "./chunk-LO5EQSQA.js";
 import {
   removeMcpServer,
   stopDispatcher

package/dist/chunk-B5JDOV32.js

@@ -0,0 +1,73 @@
+// src/dispatcher-tuning.ts
+import { readFileSync, existsSync, writeFileSync, mkdirSync, renameSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+function defaultDispatcherConfigPath() {
+  return join(homedir(), ".agenticmail", "dispatcher.json");
+}
+function positiveInt(s) {
+  if (s === void 0 || s === null || s === "") return void 0;
+  const n = typeof s === "number" ? s : parseInt(String(s), 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+function readTuningFile(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return {};
+    if (parsed.version !== 1) return {};
+    return {
+      maxConcurrentWorkers: positiveInt(parsed.maxConcurrentWorkers),
+      maxWakesPerThread: positiveInt(parsed.maxWakesPerThread),
+      wakeWindowMs: positiveInt(parsed.wakeWindowMs),
+      wakeCoalesceMs: positiveInt(parsed.wakeCoalesceMs),
+      accountSyncIntervalMs: positiveInt(parsed.accountSyncIntervalMs)
+    };
+  } catch {
+    return {};
+  }
+}
+function resolveDispatcherTuning(opts = {}) {
+  const env = opts.env ?? process.env;
+  const configPath = opts.configPath ?? defaultDispatcherConfigPath();
+  const fileLayer = readTuningFile(configPath);
+  const envLayer = {
+    maxConcurrentWorkers: positiveInt(env.AGENTICMAIL_DISPATCHER_MAX),
+    maxWakesPerThread: positiveInt(env.AGENTICMAIL_DISPATCHER_MAX_WAKES_PER_THREAD),
+    wakeWindowMs: positiveInt(env.AGENTICMAIL_DISPATCHER_WAKE_WINDOW_MS),
+    wakeCoalesceMs: positiveInt(env.AGENTICMAIL_DISPATCHER_COALESCE_MS),
+    accountSyncIntervalMs: positiveInt(env.AGENTICMAIL_DISPATCHER_SYNC)
+  };
+  const explicit = opts.explicit ?? {};
+  return {
+    maxConcurrentWorkers: explicit.maxConcurrentWorkers ?? envLayer.maxConcurrentWorkers ?? fileLayer.maxConcurrentWorkers,
+    maxWakesPerThread: explicit.maxWakesPerThread ?? envLayer.maxWakesPerThread ?? fileLayer.maxWakesPerThread,
+    wakeWindowMs: explicit.wakeWindowMs ?? envLayer.wakeWindowMs ?? fileLayer.wakeWindowMs,
+    wakeCoalesceMs: explicit.wakeCoalesceMs ?? envLayer.wakeCoalesceMs ?? fileLayer.wakeCoalesceMs,
+    accountSyncIntervalMs: explicit.accountSyncIntervalMs ?? envLayer.accountSyncIntervalMs ?? fileLayer.accountSyncIntervalMs
+  };
+}
+function writeDispatcherTuning(patch, configPath = defaultDispatcherConfigPath()) {
+  const current = readTuningFile(configPath);
+  const merged = {
+    version: 1,
+    updatedAtMs: Date.now(),
+    maxConcurrentWorkers: positiveInt(patch.maxConcurrentWorkers) ?? current.maxConcurrentWorkers,
+    maxWakesPerThread: positiveInt(patch.maxWakesPerThread) ?? current.maxWakesPerThread,
+    wakeWindowMs: positiveInt(patch.wakeWindowMs) ?? current.wakeWindowMs,
+    wakeCoalesceMs: positiveInt(patch.wakeCoalesceMs) ?? current.wakeCoalesceMs,
+    accountSyncIntervalMs: positiveInt(patch.accountSyncIntervalMs) ?? current.accountSyncIntervalMs
+  };
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${configPath}.tmp`;
+  writeFileSync(tmp, JSON.stringify(merged, null, 2));
+  renameSync(tmp, configPath);
+  return merged;
+}
+
+export {
+  defaultDispatcherConfigPath,
+  resolveDispatcherTuning,
+  writeDispatcherTuning
+};

package/dist/{chunk-DKTAW2N5.js → chunk-LO5EQSQA.js}

@@ -5,8 +5,8 @@ function isAgenticMailHookCommand(command) {
   if (typeof command !== "string") return false;
   return command.includes("agenticmail-mail-hook") || command.includes("mail-hook.js");
 }
-var HOOK_EVENTS_TO_REGISTER = ["UserPromptSubmit", "Stop"];
-var HOOK_EVENTS_TO_REMOVE = ["UserPromptSubmit", "Stop", "PreToolUse"];
+var HOOK_EVENTS_TO_REGISTER = ["UserPromptSubmit", "Stop", "SessionStart"];
+var HOOK_EVENTS_TO_REMOVE = ["UserPromptSubmit", "Stop", "PreToolUse", "SessionStart"];
 function readSettings(path) {
   if (!existsSync(path)) return {};
   const raw = readFileSync(path, "utf-8");

package/dist/{chunk-JOK76WRC.js → chunk-LVYWYEFG.js}

@@ -1205,7 +1205,10 @@ var Dispatcher = class {
   async fireWakeImmediately(account, event, threadId) {
     const verdict = this.chargeWake(account.id, threadId);
     if (!verdict.ok) {
-      this.log("warn", `[dispatcher] wake-budget exhausted for "${account.name}" on thread "${threadId}" \u2014 dropped uid=${event.uid}`);
+      this.log(
+        "warn",
+        `[dispatcher] wake-budget exhausted for "${account.name}" on thread "${threadId}" \u2014 dropped uid=${event.uid} (cap=${this.maxWakesPerThread} per ${Math.round(this.wakeWindowMs / 6e4)}min; raise with AGENTICMAIL_DISPATCHER_MAX_WAKES_PER_THREAD env var, or via ~/.agenticmail/dispatcher.json)`
+      );
       this.postSkipped(account, event, "budget-exhausted", `wake budget exhausted for thread "${threadId}" (count=${verdict.count}, cap=${this.maxWakesPerThread})`);
       return;
     }

package/dist/{chunk-4EHV3I6W.js → chunk-OUYPF4ER.js}

@@ -1,6 +1,6 @@
 import {
   upsertUserPromptSubmitHook
-} from "./chunk-DKTAW2N5.js";
+} from "./chunk-LO5EQSQA.js";
 import {
   startDispatcher,
   upsertMcpServer

package/dist/{chunk-ZFLOFC6P.js → chunk-UARFA4NI.js}

@@ -1,12 +1,12 @@
+import {
+  status
+} from "./chunk-Q5BA2J2C.js";
 import {
   uninstall
-} from "./chunk-JUEHPFKY.js";
+} from "./chunk-2RVJ2Q3W.js";
 import {
   install
-} from "./chunk-4EHV3I6W.js";
-import {
-  status
-} from "./chunk-Q5BA2J2C.js";
+} from "./chunk-OUYPF4ER.js";
 import {
   AgenticMailApiError
 } from "./chunk-4VQP57SO.js";

package/dist/cli.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
 import {
-  uninstall
-} from "./chunk-JUEHPFKY.js";
-import {
-  install
-} from "./chunk-4EHV3I6W.js";
-import "./chunk-DKTAW2N5.js";
+  defaultDispatcherConfigPath,
+  resolveDispatcherTuning,
+  writeDispatcherTuning
+} from "./chunk-B5JDOV32.js";
 import {
   status
 } from "./chunk-Q5BA2J2C.js";
+import {
+  uninstall
+} from "./chunk-2RVJ2Q3W.js";
+import {
+  install
+} from "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
 import {
   AgenticMailApiError
@@ -42,17 +47,31 @@ function usage() {
   print(`    install            Register AgenticMail with Claude Code (default)`);
   print(`    uninstall          Remove the registration`);
   print(`    status             Show what's currently installed`);
+  print(`    tune               View / change dispatcher tuning knobs (rate limits, concurrency)`);
   print("");
   print(`  ${BOLD("Flags:")}`);
-  print(`    --json             (status) Emit machine-readable JSON instead of prose`);
+  print(`    --json             (status / tune) Emit machine-readable JSON instead of prose`);
   print(`    --purge-bridge     (uninstall) Also delete the AgenticMail bridge agent`);
+  print("");
+  print(`  ${BOLD("Tune flags:")}`);
+  print(`    --max-concurrent N         Cap total simultaneous workers across all agents (default 50)`);
+  print(`    --max-wakes-per-thread N   Wakes a single (agent, thread) pair gets per window (default 10)`);
+  print(`    --wake-window-ms N         Rolling window for the above counter, ms (default 86400000 = 24h)`);
+  print(`    --wake-coalesce-ms N       Burst-debounce \u2014 collapse rapid replies into one wake (default 30000 = 30s, set 0 to disable)`);
+  print(`    --sync-ms N                How often the dispatcher polls /accounts for new agents (default 30000)`);
+  print(`    --reset                    Delete ~/.agenticmail/dispatcher.json, return to defaults`);
   print(`    -h, --help         Show this help and exit`);
   print("");
-  print(`  ${BOLD("Environment overrides:")}`);
-  print(`    AGENTICMAIL_API_URL          Override AgenticMail master API URL`);
-  print(`    AGENTICMAIL_MASTER_KEY       Override master key (otherwise read from ~/.agenticmail/config.json)`);
-  print(`    CLAUDE_CODE_CONFIG_PATH      Override Claude Code config path (default ~/.claude.json)`);
-  print(`    CLAUDE_CODE_AGENTS_DIR       Override Claude Code agents dir (default ~/.claude/agents)`);
+  print(`  ${BOLD("Environment overrides (same effect as the flags above, for PM2 setups):")}`);
+  print(`    AGENTICMAIL_API_URL                          Override AgenticMail master API URL`);
+  print(`    AGENTICMAIL_MASTER_KEY                       Override master key`);
+  print(`    CLAUDE_CODE_CONFIG_PATH                      Override Claude Code config path`);
+  print(`    CLAUDE_CODE_AGENTS_DIR                       Override Claude Code agents dir`);
+  print(`    AGENTICMAIL_DISPATCHER_MAX                   Same as --max-concurrent`);
+  print(`    AGENTICMAIL_DISPATCHER_MAX_WAKES_PER_THREAD  Same as --max-wakes-per-thread`);
+  print(`    AGENTICMAIL_DISPATCHER_WAKE_WINDOW_MS        Same as --wake-window-ms`);
+  print(`    AGENTICMAIL_DISPATCHER_COALESCE_MS           Same as --wake-coalesce-ms`);
+  print(`    AGENTICMAIL_DISPATCHER_SYNC                  Same as --sync-ms`);
   print("");
 }
 function envOptions() {
@@ -148,6 +167,92 @@ async function runStatus(asJson) {
     return 2;
   }
 }
+function argNum(args, flag) {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === flag && i + 1 < args.length) {
+      const n = parseInt(args[i + 1], 10);
+      return Number.isFinite(n) && n > 0 ? n : void 0;
+    }
+    if (a.startsWith(`${flag}=`)) {
+      const n = parseInt(a.slice(flag.length + 1), 10);
+      return Number.isFinite(n) && n > 0 ? n : void 0;
+    }
+  }
+  return void 0;
+}
+async function runTune(args) {
+  const { existsSync, unlinkSync } = await import("fs");
+  const path = defaultDispatcherConfigPath();
+  const asJson = args.includes("--json");
+  if (args.includes("--reset")) {
+    try {
+      if (existsSync(path)) unlinkSync(path);
+    } catch {
+    }
+    if (asJson) {
+      print(JSON.stringify({ reset: true, path }, null, 2));
+    } else {
+      print("");
+      print(`  ${PINK("\u{1F380} Dispatcher tuning")}`);
+      print("");
+      ok(`Reset: deleted ${path}`);
+      print(`  ${DIM("The dispatcher will use built-in defaults until you re-tune.")}`);
+      print("");
+    }
+    return 0;
+  }
+  const patch = {
+    maxConcurrentWorkers: argNum(args, "--max-concurrent"),
+    maxWakesPerThread: argNum(args, "--max-wakes-per-thread"),
+    wakeWindowMs: argNum(args, "--wake-window-ms"),
+    wakeCoalesceMs: argNum(args, "--wake-coalesce-ms"),
+    accountSyncIntervalMs: argNum(args, "--sync-ms")
+  };
+  const anyFlag = Object.values(patch).some((v) => v !== void 0);
+  if (anyFlag) {
+    const merged = writeDispatcherTuning(patch);
+    if (asJson) {
+      print(JSON.stringify(merged, null, 2));
+      return 0;
+    }
+    print("");
+    print(`  ${PINK("\u{1F380} Dispatcher tuning saved")}`);
+    print("");
+    ok(`Wrote ${path}`);
+    dim(`  maxConcurrentWorkers:   ${merged.maxConcurrentWorkers ?? "(default)"}`);
+    dim(`  maxWakesPerThread:      ${merged.maxWakesPerThread ?? "(default)"}`);
+    dim(`  wakeWindowMs:           ${merged.wakeWindowMs ?? "(default)"}`);
+    dim(`  wakeCoalesceMs:         ${merged.wakeCoalesceMs ?? "(default)"}`);
+    dim(`  accountSyncIntervalMs:  ${merged.accountSyncIntervalMs ?? "(default)"}`);
+    print("");
+    print(`  ${BOLD("Next:")} restart the dispatcher daemon to apply.`);
+    print(`  ${DIM("pm2 restart agenticmail-claudecode-dispatcher")}`);
+    print("");
+    return 0;
+  }
+  const resolved = resolveDispatcherTuning();
+  if (asJson) {
+    print(JSON.stringify({ resolved, path }, null, 2));
+    return 0;
+  }
+  print("");
+  print(`  ${PINK("\u{1F380} Dispatcher tuning (current)")}`);
+  print("");
+  print(`  Config file: ${path}`);
+  print("");
+  print(`  ${BOLD("Effective values (env > file > built-in default):")}`);
+  dim(`  maxConcurrentWorkers:   ${resolved.maxConcurrentWorkers ?? "50 (default)"}`);
+  dim(`  maxWakesPerThread:      ${resolved.maxWakesPerThread ?? "10 (default)"}`);
+  dim(`  wakeWindowMs:           ${resolved.wakeWindowMs ?? "86400000 (default \u2014 24h)"}`);
+  dim(`  wakeCoalesceMs:         ${resolved.wakeCoalesceMs ?? "30000 (default \u2014 30s)"}`);
+  dim(`  accountSyncIntervalMs:  ${resolved.accountSyncIntervalMs ?? "30000 (default)"}`);
+  print("");
+  print(`  ${BOLD("Change with flags, e.g.:")}`);
+  dim(`  agenticmail-claudecode tune --max-wakes-per-thread 100 --max-concurrent 200`);
+  print("");
+  return 0;
+}
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes("-h") || args.includes("--help") || args[0] === "help") {
@@ -163,6 +268,8 @@ async function main() {
       return runUninstall(args.includes("--purge-bridge"));
     case "status":
       return runStatus(args.includes("--json"));
+    case "tune":
+      return runTune(args);
     default:
       fail(`Unknown command: ${command}`);
       usage();

package/dist/dispatcher-bin.js

@@ -1,17 +1,27 @@
 #!/usr/bin/env node
+import {
+  resolveDispatcherTuning
+} from "./chunk-B5JDOV32.js";
 import {
   Dispatcher
-} from "./chunk-JOK76WRC.js";
+} from "./chunk-LVYWYEFG.js";
 import "./chunk-4VQP57SO.js";
 
 // src/dispatcher-bin.ts
 async function main() {
+  const tuning = resolveDispatcherTuning();
+  console.error(
+    `[dispatcher-bin] tuning: maxConcurrentWorkers=${tuning.maxConcurrentWorkers ?? "(default)"} maxWakesPerThread=${tuning.maxWakesPerThread ?? "(default)"} wakeWindowMs=${tuning.wakeWindowMs ?? "(default)"} wakeCoalesceMs=${tuning.wakeCoalesceMs ?? "(default)"} accountSyncIntervalMs=${tuning.accountSyncIntervalMs ?? "(default)"}`
+  );
   const dispatcher = new Dispatcher({
     apiUrl: process.env.AGENTICMAIL_API_URL,
     masterKey: process.env.AGENTICMAIL_MASTER_KEY,
     agentsDir: process.env.CLAUDE_CODE_AGENTS_DIR,
-    maxConcurrentWorkers: positiveInt(process.env.AGENTICMAIL_DISPATCHER_MAX),
-    accountSyncIntervalMs: positiveInt(process.env.AGENTICMAIL_DISPATCHER_SYNC)
+    maxConcurrentWorkers: tuning.maxConcurrentWorkers,
+    maxWakesPerThread: tuning.maxWakesPerThread,
+    wakeWindowMs: tuning.wakeWindowMs,
+    wakeCoalesceMs: tuning.wakeCoalesceMs,
+    accountSyncIntervalMs: tuning.accountSyncIntervalMs
   });
   const shutdown = async (sig) => {
     console.error(`[dispatcher-bin] received ${sig} \u2014 shutting down`);
@@ -32,11 +42,6 @@ async function main() {
   });
   await dispatcher.start();
 }
-function positiveInt(s) {
-  if (!s) return void 0;
-  const n = parseInt(s, 10);
-  return Number.isFinite(n) && n > 0 ? n : void 0;
-}
 main().catch((err) => {
   console.error(`[dispatcher-bin] fatal: ${err.message}`);
   process.exit(1);

package/dist/dispatcher-tuning.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Tuning knobs for the dispatcher daemon.
+ *
+ * # Why this exists
+ *
+ * The dispatcher has several rate-limit / concurrency knobs that need
+ * to be tunable WITHOUT a code change:
+ *
+ *   - `maxConcurrentWorkers` — global worker cap (default 50)
+ *   - `maxWakesPerThread`    — wakes per (agent, thread) per window (default 10)
+ *   - `wakeWindowMs`         — the window itself (default 24h)
+ *   - `wakeCoalesceMs`       — burst-debounce window (default 30s)
+ *   - `accountSyncIntervalMs` — how often to poll /accounts (default 30s)
+ *
+ * The DEFAULTS are conservative — protect a fresh install from runaway
+ * cost. Power users running active coordination on a single thread
+ * routinely hit the 10/24h wake cap and need it raised. Today (before
+ * this module) the only way to do that was edit dispatcher.ts and rebuild,
+ * which is absurd.
+ *
+ * # Three input sources, in precedence order
+ *
+ *   1. Explicit constructor args (programmatic callers, tests)
+ *   2. Env vars (PM2 ecosystem.config.cjs lives here)
+ *   3. `~/.agenticmail/dispatcher.json` (persistent operator preference,
+ *      written by the CLI's `agenticmail dispatcher tune` command)
+ *   4. Hard-coded defaults
+ *
+ * Earlier sources win.
+ *
+ * # File format
+ *
+ *   { "version": 1,
+ *     "maxConcurrentWorkers": 200,
+ *     "maxWakesPerThread": 50,
+ *     "wakeWindowMs": 86400000,
+ *     "wakeCoalesceMs": 30000,
+ *     "accountSyncIntervalMs": 30000 }
+ *
+ * Missing keys fall through to the next precedence level. All values
+ * are integers; non-positive / non-finite values fall through (so a
+ * broken edit produces a slightly-stale config, not a broken
+ * dispatcher).
+ */
+interface DispatcherTuning {
+    maxConcurrentWorkers?: number;
+    maxWakesPerThread?: number;
+    wakeWindowMs?: number;
+    wakeCoalesceMs?: number;
+    accountSyncIntervalMs?: number;
+}
+declare function defaultDispatcherConfigPath(): string;
+/**
+ * Resolve final tuning values by merging the three precedence layers:
+ * explicit args > env vars > file > defaults (left to the consumer).
+ *
+ * Returns ONLY the keys that were explicitly set — the caller passes
+ * the result through to the Dispatcher constructor, whose defaults
+ * fill in anything still undefined.
+ */
+declare function resolveDispatcherTuning(opts?: {
+    explicit?: DispatcherTuning;
+    env?: NodeJS.ProcessEnv;
+    configPath?: string;
+}): DispatcherTuning;
+/**
+ * Persist the operator's preferences to ~/.agenticmail/dispatcher.json
+ * atomically (.tmp + rename) so a power outage mid-write never produces
+ * a half-written config. Only writes the keys that are explicitly set
+ * in the patch — preserves keys the user already configured.
+ *
+ * Returns the resulting on-disk shape so the caller can echo it back.
+ */
+declare function writeDispatcherTuning(patch: DispatcherTuning, configPath?: string): DispatcherTuning & {
+    version: number;
+    updatedAtMs: number;
+};
+
+export { type DispatcherTuning, defaultDispatcherConfigPath, resolveDispatcherTuning, writeDispatcherTuning };

package/dist/dispatcher-tuning.js

@@ -0,0 +1,10 @@
+import {
+  defaultDispatcherConfigPath,
+  resolveDispatcherTuning,
+  writeDispatcherTuning
+} from "./chunk-B5JDOV32.js";
+export {
+  defaultDispatcherConfigPath,
+  resolveDispatcherTuning,
+  writeDispatcherTuning
+};

package/dist/dispatcher.js

@@ -1,6 +1,6 @@
 import {
   Dispatcher
-} from "./chunk-JOK76WRC.js";
+} from "./chunk-LVYWYEFG.js";
 import "./chunk-4VQP57SO.js";
 export {
   Dispatcher

package/dist/http-routes.js

@@ -1,10 +1,10 @@
 import {
   createIntegrationRoutes
-} from "./chunk-ZFLOFC6P.js";
-import "./chunk-JUEHPFKY.js";
-import "./chunk-4EHV3I6W.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-UARFA4NI.js";
 import "./chunk-Q5BA2J2C.js";
+import "./chunk-2RVJ2Q3W.js";
+import "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
 import "./chunk-4VQP57SO.js";
 export {

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { A as AgenticMailAccount } from './config-CXW3gXFC.js';
 export { C as ClaudeCodeIntegrationConfig, I as InstallResult, a as InstallStatus, R as ResolveConfigOptions, U as UninstallResult, r as resolveConfig } from './config-CXW3gXFC.js';
 export { createIntegrationRoutes } from './http-routes.js';
 export { Dispatcher, DispatcherOptions, QueryFn } from './dispatcher.js';
+export { DispatcherTuning, defaultDispatcherConfigPath, resolveDispatcherTuning, writeDispatcherTuning } from './dispatcher-tuning.js';
 import 'express';
 
 /**

package/dist/index.js

@@ -1,20 +1,25 @@
+import {
+  defaultDispatcherConfigPath,
+  resolveDispatcherTuning,
+  writeDispatcherTuning
+} from "./chunk-B5JDOV32.js";
 import {
   Dispatcher,
   loadPersonaForAgent
-} from "./chunk-JOK76WRC.js";
+} from "./chunk-LVYWYEFG.js";
 import {
   createIntegrationRoutes
-} from "./chunk-ZFLOFC6P.js";
+} from "./chunk-UARFA4NI.js";
+import {
+  status
+} from "./chunk-Q5BA2J2C.js";
 import {
   uninstall
-} from "./chunk-JUEHPFKY.js";
+} from "./chunk-2RVJ2Q3W.js";
 import {
   install
-} from "./chunk-4EHV3I6W.js";
-import "./chunk-DKTAW2N5.js";
-import {
-  status
-} from "./chunk-Q5BA2J2C.js";
+} from "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
 import {
   AgenticMailApiError,
@@ -34,6 +39,7 @@ export {
   MANAGED_BY_MARKER,
   checkApiHealth,
   createIntegrationRoutes,
+  defaultDispatcherConfigPath,
   deleteAccount,
   ensureAccount,
   getAccountByName,
@@ -43,6 +49,8 @@ export {
   renderPersonaBody,
   renderSubagentMarkdown,
   resolveConfig,
+  resolveDispatcherTuning,
   status,
-  uninstall
+  uninstall,
+  writeDispatcherTuning
 };

package/dist/install.js

@@ -1,8 +1,8 @@
 import {
   install,
   selectExposableAgents
-} from "./chunk-4EHV3I6W.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
 import "./chunk-4VQP57SO.js";
 export {

package/dist/mail-hook.js

@@ -7,6 +7,8 @@ import { join, dirname } from "path";
 var AGENTICMAIL_DIR = join(homedir(), ".agenticmail");
 var CONFIG_PATH = join(AGENTICMAIL_DIR, "config.json");
 var CURSOR_PATH = join(AGENTICMAIL_DIR, "claudecode-hook-cursor.json");
+var SESSIONS_PATH = join(AGENTICMAIL_DIR, "claudecode-hook-sessions.json");
+var SESSIONS_CAP = 100;
 var HOOK_VERSION = "1";
 var HTTP_TIMEOUT_MS = 800;
 var GLOBAL_TIMEOUT_MS = 1500;
@@ -47,17 +49,95 @@ async function readStdinJson() {
     setTimeout(() => finish(() => null), 200).unref();
   });
 }
+function capabilitiesBlurb() {
+  return [
+    "\u{1F380} AgenticMail is available via MCP (mcp__agenticmail__*).",
+    "",
+    "When to reach for it:",
+    "  \xB7 Building anything that benefits from MULTIPLE specialized roles working in parallel \u2014 designer + developer + reviewer, researcher + writer + fact-checker, planner + executor + critic.",
+    "  \xB7 Coordinating long-running async work that survives across Claude Code restarts (email threads are durable; in-memory state is not).",
+    "  \xB7 Anywhere you would otherwise spawn the Task tool repeatedly for sub-tasks \u2014 prefer AgenticMail when those sub-tasks need to talk to EACH OTHER, not just back to you.",
+    "",
+    "High-leverage tools:",
+    "  \xB7 mcp__agenticmail__create_account({ name, role })       \u2014 spawn a fresh persistent agent identity with its own inbox + API key.",
+    '  \xB7 mcp__agenticmail__send_email({ to, cc, subject, text, wake }) \u2014 kick off the work. CC the whole team; use `wake: ["alice"]` to give exactly one agent the next turn while others stay informed.',
+    "  \xB7 mcp__agenticmail__call_agent({ agent, message }) / mcp__agenticmail__wait_for_email \u2014 blocking RPC when you need a specific answer back before continuing your own turn.",
+    "",
+    "Coordination pattern: one email thread = the shared workspace. Reply-all keeps the audit trail. Use `wake` to control whose turn it is.",
+    "",
+    "Other tools cover: inbox/folder management, drafts, templates, tasks, contacts, signatures, SMS, voice. Full list under mcp__agenticmail__* \u2014 discover on demand, don't front-load them all."
+  ].join("\n");
+}
+function loadSeenSessions() {
+  if (!existsSync(SESSIONS_PATH)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(SESSIONS_PATH, "utf-8"));
+    const arr = Array.isArray(parsed?.seen) ? parsed.seen : [];
+    return arr.filter((s) => typeof s === "string");
+  } catch {
+    return [];
+  }
+}
+function rememberSession(sessionId, seen) {
+  const next = seen.filter((s) => s !== sessionId);
+  next.push(sessionId);
+  while (next.length > SESSIONS_CAP) next.shift();
+  try {
+    if (!existsSync(dirname(SESSIONS_PATH))) mkdirSync(dirname(SESSIONS_PATH), { recursive: true });
+    writeFileSync(SESSIONS_PATH, JSON.stringify({ seen: next, hookVersion: HOOK_VERSION }, null, 2));
+  } catch {
+  }
+}
 async function main() {
   const input = await readStdinJson();
   const eventName = input?.hook_event_name ?? "UserPromptSubmit";
-  if (!existsSync(CONFIG_PATH)) return;
+  const sessionId = typeof input?.session_id === "string" ? input.session_id : "";
+  if (eventName === "SessionStart") {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: capabilitiesBlurb()
+      }
+    }));
+    return;
+  }
+  let blurbContext = "";
+  if (eventName === "UserPromptSubmit" && sessionId) {
+    const seen = loadSeenSessions();
+    if (!seen.includes(sessionId)) {
+      blurbContext = capabilitiesBlurb();
+      rememberSession(sessionId, seen);
+    }
+  }
+  const emitAndExit = (mailContext) => {
+    const combined = [blurbContext, mailContext].filter(Boolean).join("\n\n");
+    if (!combined) return;
+    if (eventName === "Stop") {
+      process.stdout.write(JSON.stringify({ decision: "block", reason: combined }));
+    } else {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: eventName,
+          additionalContext: combined
+        }
+      }));
+    }
+  };
+  if (!existsSync(CONFIG_PATH)) {
+    emitAndExit("");
+    return;
+  }
   let cfg;
   try {
     cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
   } catch {
+    emitAndExit("");
+    return;
+  }
+  if (!cfg.masterKey) {
+    emitAndExit("");
     return;
   }
-  if (!cfg.masterKey) return;
   const apiHost = cfg.api?.host ?? "127.0.0.1";
   const apiPort = cfg.api?.port ?? 3829;
   const apiUrl = `http://${apiHost}:${apiPort}`;
@@ -67,15 +147,22 @@ async function main() {
       headers: { Authorization: `Bearer ${cfg.masterKey}` },
       signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
     });
-    if (!r.ok) return;
+    if (!r.ok) {
+      emitAndExit("");
+      return;
+    }
     const data = await r.json();
     bridge = (data.agents ?? []).find(
       (a) => a.name === "claudecode" || a.name === "claude" || a.role === "bridge"
     );
   } catch {
+    emitAndExit("");
+    return;
+  }
+  if (!bridge?.apiKey) {
+    emitAndExit("");
     return;
   }
-  if (!bridge?.apiKey) return;
   let cursorMs = 0;
   let lastCheckedMs = 0;
   if (existsSync(CURSOR_PATH)) {
@@ -96,10 +183,14 @@ async function main() {
       headers: { Authorization: `Bearer ${bridge.apiKey}` },
       signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
     });
-    if (!r.ok) return;
+    if (!r.ok) {
+      emitAndExit("");
+      return;
+    }
     const data = await r.json();
     messages = data.messages ?? [];
   } catch {
+    emitAndExit("");
     return;
   }
   const newOnes = messages.filter((m) => {
@@ -118,6 +209,7 @@ async function main() {
       } catch {
       }
     }
+    emitAndExit("");
     return;
   }
   newOnes.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
@@ -149,19 +241,7 @@ async function main() {
     );
   } catch {
   }
-  if (eventName === "Stop") {
-    process.stdout.write(JSON.stringify({
-      decision: "block",
-      reason: lines.join("\n")
-    }));
-  } else {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: eventName,
-        additionalContext: lines.join("\n")
-      }
-    }));
-  }
+  emitAndExit(lines.join("\n"));
 }
 var globalTimeout = new Promise((resolve) => {
   setTimeout(() => resolve(), GLOBAL_TIMEOUT_MS).unref();

package/dist/uninstall.js

@@ -1,7 +1,7 @@
 import {
   uninstall
-} from "./chunk-JUEHPFKY.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-2RVJ2Q3W.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
 import "./chunk-4VQP57SO.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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",
@@ -41,7 +41,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts src/install.ts src/uninstall.ts src/status.ts src/http-routes.ts src/dispatcher.ts src/dispatcher-bin.ts src/mail-hook.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/cli.ts src/install.ts src/uninstall.ts src/status.ts src/http-routes.ts src/dispatcher.ts src/dispatcher-bin.ts src/dispatcher-tuning.ts src/mail-hook.ts --format esm --dts --clean",
     "test": "vitest run --passWithNoTests",
     "preuninstall": "node scripts/uninstall.mjs",
     "prepublishOnly": "npm run build"