@indigoai-us/hq-cli 5.117.2 → 5.118.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.118.0] — 2026-09-16
+
+### Added
+
+- External agents can now be woken the moment an HQ message arrives. `hq agent kit wake set-url --stdin` points the kit at a webhook, such as a Grok Bot routine webhook trigger. `hq agent kit wake set-command -- <cmd>` runs a local command for frameworks with a CLI. The kit sends a short notice with no message text when mail is pending, and again every 10 minutes until it is handled. The webhook URL is stored privately and never logged.
+- `hq agent inbox` lists an external agent's pending HQ messages and `hq agent inbox done <id>` marks them handled, so a woken bot never answers the same message twice. The MCP server gains a matching `hq_inbox_done` tool.
+
+### Fixed
+
+- The `hq_inbox_read` MCP tool no longer fails with 403 AGENT_ROUTE_NOT_SUPPORTED. It reads the agent's own inbox instead of the person-only DM inbox, and by default returns only messages not yet handled.
+- The HQ direct-message skill shipped to external agents no longer tells them to use person-only read commands.
+
+## [5.117.3] — 2026-09-16
+
+### Fixed
+
+- `hq doctor --fix` no longer breaks Claude Code sessions. Since HQ moved to a single master hook, the doctor saw every hook script as unregistered. It then added one hook entry per script with no tool filter, so guards such as the Glob path check and core protection ran on every tool call and blocked Bash, Skill and Read with "Glob needs a path" or "Edit to locked path is not allowed". An HQ update could then move those entries into `.claude/settings.local.json`. The doctor no longer auto-registers orphan scripts. It now detects the stray entries in both settings files and `hq doctor --fix` removes them, keeping your permissions and any hooks you added yourself. Scripts listed in `.claude/hooks/hook-registry.json` also no longer show as orphans.
+
+### Fixed
+
+- `hq doctor` now keeps its hook-health compatibility verdict in step with
+  `check-hq-hooks.sh` when either required command hook is missing.
+
 ## [5.117.2] — 2026-09-16
 
 ### Fixed
@@ -26,6 +49,12 @@
   Workforce now. The free plan is called Starter rather than "free plan", to
   match the pricing page.
 
+### Fixed
+
+- `hq doctor` now reports failed hook wiring when `.claude/settings.json` has
+  no usable command hook for `SessionStart` or `PreToolUse`. The file can still
+  be present and valid JSON, but it no longer reads as healthy when nothing runs.
+
 ## [5.117.1] — 2026-09-16
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -4218,6 +4218,83 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "wake";
+            readonly description: "Wake this bot's own framework when HQ messages arrive (webhook URL or local command)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] [command]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [{
+                readonly name: "set-url";
+                readonly description: "POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] [url]";
+                readonly arguments: readonly [{
+                    readonly name: "url";
+                    readonly required: false;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--stdin";
+                    readonly description: "Read the URL from stdin";
+                }, {
+                    readonly flags: "--retry-minutes <n>";
+                    readonly description: "Re-wake while items stay pending (default 10, minimum 1)";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "set-command";
+                readonly description: "Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <argv...>";
+                readonly arguments: readonly [{
+                    readonly name: "argv";
+                    readonly required: true;
+                    readonly variadic: true;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--timeout-minutes <n>";
+                    readonly description: "Kill a run after this long (default 10)";
+                }, {
+                    readonly flags: "--retry-minutes <n>";
+                    readonly description: "Re-wake while items stay pending (default 10, minimum 1)";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "show";
+                readonly description: "Show the configured wake (the URL is masked)";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "clear";
+                readonly description: "Remove the wake configuration";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "test";
+                readonly description: "Fire the wake once now with the current pending count";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [];
+                readonly subcommands: readonly [];
+            }];
         }, {
             readonly name: "run";
             readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process";
@@ -4253,6 +4330,34 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly arguments: readonly [];
         readonly options: readonly [];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "inbox";
+        readonly description: "List this agent's pending HQ messages (mirrored by the kit), or mark them handled";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--all";
+            readonly description: "Include items already marked handled";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON";
+        }];
+        readonly subcommands: readonly [{
+            readonly name: "done";
+            readonly description: "Mark inbox items handled and ack them on the server";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <ids...>";
+            readonly arguments: readonly [{
+                readonly name: "ids";
+                readonly required: true;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
     }];
 }, {
     readonly name: "outposts";

package/dist/command-catalog.generated.js

@@ -5457,6 +5457,102 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "wake",
+                        "description": "Wake this bot's own framework when HQ messages arrive (webhook URL or local command)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] [command]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": [
+                            {
+                                "name": "set-url",
+                                "description": "POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] [url]",
+                                "arguments": [
+                                    {
+                                        "name": "url",
+                                        "required": false,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--stdin",
+                                        "description": "Read the URL from stdin"
+                                    },
+                                    {
+                                        "flags": "--retry-minutes <n>",
+                                        "description": "Re-wake while items stay pending (default 10, minimum 1)"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "set-command",
+                                "description": "Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <argv...>",
+                                "arguments": [
+                                    {
+                                        "name": "argv",
+                                        "required": true,
+                                        "variadic": true
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--timeout-minutes <n>",
+                                        "description": "Kill a run after this long (default 10)"
+                                    },
+                                    {
+                                        "flags": "--retry-minutes <n>",
+                                        "description": "Re-wake while items stay pending (default 10, minimum 1)"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "show",
+                                "description": "Show the configured wake (the URL is masked)",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "clear",
+                                "description": "Remove the wake configuration",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "test",
+                                "description": "Fire the wake once now with the current pending count",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [],
+                                "subcommands": []
+                            }
+                        ]
+                    },
                     {
                         "name": "run",
                         "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process",
@@ -5499,6 +5595,42 @@ export const COMMAND_CATALOG = [
                 "arguments": [],
                 "options": [],
                 "subcommands": []
+            },
+            {
+                "name": "inbox",
+                "description": "List this agent's pending HQ messages (mirrored by the kit), or mark them handled",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--all",
+                        "description": "Include items already marked handled"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": [
+                    {
+                        "name": "done",
+                        "description": "Mark inbox items handled and ack them on the server",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <ids...>",
+                        "arguments": [
+                            {
+                                "name": "ids",
+                                "required": true,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
             }
         ]
     },

package/dist/commands/agent-inbox.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
+ *
+ *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
+ *   hq agent inbox done <id...>       mark handled locally and ack on the server
+ */
+import { Command } from "commander";
+export declare function registerAgentInboxCommand(agent: Command): void;
+//# sourceMappingURL=agent-inbox.d.ts.map

package/dist/commands/agent-inbox.js

@@ -0,0 +1,81 @@
+/**
+ * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
+ *
+ *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
+ *   hq agent inbox done <id...>       mark handled locally and ack on the server
+ */
+import chalk from "chalk";
+import * as os from "node:os";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { requireExternalCreds } from "./agent-kit.js";
+const ID_RE = /^[A-Za-z0-9._:-]{1,200}$/;
+export function registerAgentInboxCommand(agent) {
+    const inbox = agent
+        .command("inbox")
+        .description("List this agent's pending HQ messages (mirrored by the kit), or mark them handled")
+        .option("--all", "Include items already marked handled")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const done = readDoneIds(paths);
+        const rows = readMirroredInbox(paths)
+            .filter((e) => opts.all || !done.has(e.id))
+            .map((e) => summarizeInboxEntry(e, done.has(e.id)));
+        if (opts.json) {
+            console.log(JSON.stringify({ count: rows.length, messages: rows }, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(opts.all ? "Inbox is empty." : "No pending messages.");
+            return;
+        }
+        for (const r of rows) {
+            const state = r.done ? chalk.dim(" (done)") : "";
+            console.log(`${chalk.bold(r.id)}${state}  ${r.channel ?? "?"}  from ${r.from}${r.fromUid ? ` <${r.fromUid}>` : ""}  ${r.at ?? ""}`);
+            if (r.text)
+                console.log(`  ${r.text.replace(/\n/g, "\n  ")}`);
+        }
+        if (!opts.all)
+            console.log(chalk.dim(`\nReply with hq dm <uid> "…", then: hq agent inbox done <id>`));
+    });
+    inbox
+        .command("done <ids...>")
+        .description("Mark inbox items handled and ack them on the server")
+        .action(async (ids) => {
+        const bad = ids.filter((id) => !ID_RE.test(id));
+        if (bad.length) {
+            console.error(chalk.red(`Invalid id(s): ${bad.join(", ")}`));
+            process.exit(1);
+        }
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const creds = requireExternalCreds(paths);
+        const added = markInboxDone(paths, ids);
+        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
+        let acked = 0;
+        try {
+            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+            for (const id of ids) {
+                const res = await vaultApiFetch({
+                    token,
+                    baseUrl: creds.apiBaseUrl,
+                    path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`,
+                    method: "POST",
+                });
+                if (res.ok)
+                    acked += 1;
+                else
+                    console.error(chalk.yellow(`server ack ${id} → ${res.status}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.yellow(`server ack skipped: ${err instanceof Error ? err.message : String(err)}`));
+        }
+        console.log(`Marked ${added.length} handled (${ids.length - added.length} already done); server acked ${acked}.`);
+    });
+}
+//# sourceMappingURL=agent-inbox.js.map

package/dist/commands/agent-kit.js

@@ -34,6 +34,8 @@ import { fallbackStatus, rebootCrontabLine, shouldUseFallback, startFallback, st
 import { serviceLogPath } from "../lib/agent-kit/paths.js";
 import { spawn } from "node:child_process";
 import { startMeshListener } from "../lib/agent-kit/run/mesh-listener.js";
+import { pendingInbox } from "../lib/agent-kit/inbox-state.js";
+import { buildWakeNotice, clearWakeConfig, currentWakeState, DEFAULT_WAKE_RETRY_MS, describeWake, fireWake, readWakeConfig, validateWakeUrl, writeWakeConfig, } from "../lib/agent-kit/wake.js";
 import { runSyncLoop } from "../lib/agent-kit/run/sync.js";
 import { resolveHqBinary, resolveNodeBinary, } from "../lib/mesh/live/daemon/install.js";
 import { installServices, servicesStatus, uninstallServices, } from "../lib/service-manager/index.js";
@@ -245,6 +247,14 @@ export function formatFallbackStatus(paths, kill) {
         : chalk.yellow(st.pid === null ? "pidfile unreadable" : `not running (stale pid ${st.pid})`);
     return [`  mode: fallback supervisor (hq agent kit run all) ${state}${chalk.dim(`  ${st.pidFile}`)}`];
 }
+function retryMsFrom(raw) {
+    if (raw === undefined)
+        return DEFAULT_WAKE_RETRY_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        throw new Error("--retry-minutes must be at least 1");
+    return n * 60_000;
+}
 function fail(err) {
     console.error(chalk.red(err instanceof Error ? err.message : String(err)));
     process.exit(1);
@@ -341,6 +351,101 @@ export function registerAgentKitCommand(agent) {
             fail(err);
         }
     });
+    const wake = kit
+        .command("wake")
+        .description("Wake this bot's own framework when HQ messages arrive (webhook URL or local command)");
+    wake
+        .command("set-url [url]")
+        .description("POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history")
+        .option("--stdin", "Read the URL from stdin")
+        .option("--retry-minutes <n>", "Re-wake while items stay pending (default 10, minimum 1)")
+        .action(async (url, opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            requireExternalCreds(paths);
+            let raw = url;
+            if (opts.stdin) {
+                const chunks = [];
+                for await (const c of process.stdin)
+                    chunks.push(c);
+                raw = Buffer.concat(chunks).toString("utf8").trim();
+            }
+            if (!raw)
+                throw new Error("Provide the URL as an argument or with --stdin");
+            const config = { kind: "url", url: validateWakeUrl(raw), retryMs: retryMsFrom(opts.retryMinutes) };
+            writeWakeConfig(paths, config);
+            console.log(chalk.green(`Wake set: ${describeWake(config)}`));
+            console.log("Test it: hq agent kit wake test");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    wake
+        .command("set-command <argv...>")
+        .description("Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command")
+        .option("--timeout-minutes <n>", "Kill a run after this long (default 10)")
+        .option("--retry-minutes <n>", "Re-wake while items stay pending (default 10, minimum 1)")
+        .action((argv, opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            requireExternalCreds(paths);
+            const minutes = opts.timeoutMinutes ? Number(opts.timeoutMinutes) : 10;
+            if (!Number.isFinite(minutes) || minutes <= 0)
+                throw new Error("--timeout-minutes must be a positive number");
+            const config = { kind: "command", command: argv, timeoutMs: minutes * 60_000, retryMs: retryMsFrom(opts.retryMinutes) };
+            writeWakeConfig(paths, config);
+            console.log(chalk.green(`Wake set: ${describeWake(config)}`));
+            console.log("Test it: hq agent kit wake test");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    wake
+        .command("show")
+        .description("Show the configured wake (the URL is masked)")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const config = readWakeConfig(paths);
+        const state = currentWakeState(paths);
+        if (opts.json) {
+            console.log(JSON.stringify({ configured: !!config, wake: describeWake(config), lastWakeAt: state.lastWakeAt ?? null }, null, 2));
+            return;
+        }
+        console.log(`  wake:      ${describeWake(config)}`);
+        console.log(`  last wake: ${state.lastWakeAt ?? "never"}`);
+    });
+    wake
+        .command("clear")
+        .description("Remove the wake configuration")
+        .action(() => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        console.log(clearWakeConfig(paths) ? "Wake cleared." : "No wake was configured.");
+    });
+    wake
+        .command("test")
+        .description("Fire the wake once now with the current pending count")
+        .action(async () => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const creds = requireExternalCreds(paths);
+            ensureKitDirs(paths);
+            const config = readWakeConfig(paths);
+            if (!config)
+                throw new Error("No wake configured. Run hq agent kit wake set-url --stdin (or set-command).");
+            const log = createKitLogger(paths, "wake", { echo: false });
+            const ids = pendingInbox(paths).map((e) => e.id);
+            const result = await fireWake(config, buildWakeNotice(creds.entityUid, "test", ids, new Date()), { paths, agentUid: creds.entityUid, log });
+            console.log(result.ok ? chalk.green(result.detail) : chalk.red(result.detail));
+            if (!result.ok)
+                process.exit(1);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     kit
         .command("run <service>")
         .description(`Run one kit service in the foreground (${KIT_SERVICES.join("|")}), or \`all\` to supervise every service in one process`)

package/dist/commands/agent-mcp.d.ts

@@ -11,12 +11,13 @@
 import { Command } from "commander";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { type HqRunResult, type McpToolClients } from "../lib/agent-kit/mcp/tools.js";
+import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
 export declare const AGENT_MCP_SERVER_NAME = "hq-agent";
 export declare const AGENT_MCP_INSTRUCTIONS: string;
 export declare const HQ_SUBPROCESS_TIMEOUT_MS = 120000;
 export declare function defaultRunHq(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<HqRunResult>;
-export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string): McpToolClients;
+export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string, paths?: Pick<AgentKitPaths, "inboxDir">): McpToolClients;
 export declare function createAgentMcpServer(clients: McpToolClients): McpServer;
 export declare function registerAgentMcpCommand(agent: Command): void;
 //# sourceMappingURL=agent-mcp.d.ts.map

package/dist/commands/agent-mcp.js

@@ -21,7 +21,7 @@ export const AGENT_MCP_SERVER_NAME = "hq-agent";
 export const AGENT_MCP_INSTRUCTIONS = "You are acting inside HQ as an enrolled external agent. Tools run as that machine identity: " +
     "hq_whoami (identity), hq_search / hq_files_list / hq_files_read (company vault), " +
     "hq_secrets_list / hq_secrets_exec (secrets by NAME only — values are never returned), " +
-    "hq_dm_send / hq_inbox_read (direct messages), hq_work_mesh_status (what the team is doing). " +
+    "hq_inbox_read / hq_dm_send / hq_inbox_done (read pending HQ messages, reply, then mark each handled), hq_work_mesh_status (what the team is doing). " +
     "Never ask a user for a token or secret value; if a secret is missing, name it and ask an admin to add it.";
 export const HQ_SUBPROCESS_TIMEOUT_MS = 120_000;
 export function defaultRunHq(nodeBinary, hqBinary, env) {
@@ -45,7 +45,7 @@ export function defaultRunHq(nodeBinary, hqBinary, env) {
         });
     });
 }
-export function defaultMcpClients(creds, credsPath) {
+export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.homedir(), process.env)) {
     const env = {
         ...process.env,
         HQ_MACHINE_CREDS_FILE: credsPath,
@@ -55,6 +55,7 @@ export function defaultMcpClients(creds, credsPath) {
     };
     return {
         creds,
+        paths,
         runHq: defaultRunHq(process.execPath, process.argv[1], env),
         getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
         apiJson: async (token, path, init) => {
@@ -96,7 +97,7 @@ export function registerAgentMcpCommand(agent) {
         process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
         process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
         process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
-        const server = createAgentMcpServer(defaultMcpClients(creds, paths.machineCredsPath));
+        const server = createAgentMcpServer(defaultMcpClients(creds, paths.machineCredsPath, paths));
         process.stderr.write(`hq agent mcp: serving as ${creds.entityUid} (${creds.companySlug})\n`);
         await server.serve(process.stdin, process.stdout);
     });

package/dist/commands/agent.d.ts

@@ -6,6 +6,7 @@
  *   hq agent kit install|status|uninstall|run <service>
  *   hq agent probe                end-to-end membership check
  *   hq agent mcp                  stdio MCP server for the bot framework
+ *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
 import { Command } from "commander";
 export declare function registerAgentCommand(program: Command): void;

package/dist/commands/agent.js

@@ -6,8 +6,10 @@
  *   hq agent kit install|status|uninstall|run <service>
  *   hq agent probe                end-to-end membership check
  *   hq agent mcp                  stdio MCP server for the bot framework
+ *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
 import { registerAgentEnrollCommand } from "./agent-enroll.js";
+import { registerAgentInboxCommand } from "./agent-inbox.js";
 import { registerAgentKitCommand } from "./agent-kit.js";
 import { registerAgentMcpCommand } from "./agent-mcp.js";
 import { registerAgentProbeCommand } from "./agent-probe.js";
@@ -19,5 +21,6 @@ export function registerAgentCommand(program) {
     registerAgentKitCommand(agent);
     registerAgentProbeCommand(agent);
     registerAgentMcpCommand(agent);
+    registerAgentInboxCommand(agent);
 }
 //# sourceMappingURL=agent.js.map

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Local handled-state for the external agent's mirrored inbox.
+ *
+ * The inbox poller appends every new item to ~/.hq-agent/inbox/inbox.jsonl.
+ * A bot marks an item handled with `hq agent inbox done <id>` (or the
+ * `hq_inbox_done` MCP tool); ids land in done-ids.json. "Pending" is every
+ * mirrored item whose id is not done, oldest first. This works the same
+ * whether or not the kit acks on the server (`inboxAck`), so a woken bot can
+ * always drain exactly what it has not handled yet and never reply twice.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export declare const DONE_IDS_NAME = "done-ids.json";
+export declare const MAX_DONE_IDS = 5000;
+export interface MirroredInboxEntry {
+    id: string;
+    mirroredAt?: string;
+    [key: string]: unknown;
+}
+export declare function readDoneIds(paths: Pick<AgentKitPaths, "inboxDir">): Set<string>;
+export declare function markInboxDone(paths: Pick<AgentKitPaths, "inboxDir">, ids: string[]): string[];
+/** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
+export declare function readMirroredInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
+export declare function pendingInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
+/** Compact view for bots: who, when, which channel, and the text. */
+export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean): {
+    id: string;
+    channel: string | undefined;
+    from: string;
+    fromUid: string | undefined;
+    at: string | undefined;
+    text: string | undefined;
+    done: boolean;
+};
+//# sourceMappingURL=inbox-state.d.ts.map