consult-mcp 0.6.1 → 1.0.0

package/README.md

@@ -4,7 +4,14 @@
 
 consult is an MCP server that lets Claude Code, Codex and Grok ask each other, and Google's Antigravity CLI, for advice through the CLIs already signed in on your machine. No API keys: each advisor runs on the subscription its CLI already uses.
 
-Claude Code on Opus can ask Codex on GPT-6 Astra to review a plan, Codex can ask Grok why a test is flaky, or any of them can put one question to all the others at once. With [task dispatch](#task-dispatch) on, an agent can also hand a coding task to a Codex or Grok worker and follow its progress.
+Claude Code on Opus can ask Codex on GPT-6 Astra to review a plan, Codex can ask Grok why a test is flaky, or any of them can put one question to all the others at once. Before calling work done, an agent can have the other vendors [review its diff](#review-your-changes) in one call, and so can you, from the terminal:
+
+```bash
+npx -y consult-mcp@latest review            # every installed advisor reviews your uncommitted changes
+npx -y consult-mcp@latest review --base main
+```
+
+With [live sessions](#live-sessions) on, agents can also ask the sessions you already have running and message them, and with [task dispatch](#task-dispatch) on, hand a coding task to a Codex or Grok worker and follow its progress.
 
 [consult.n3el.dev](https://consult.n3el.dev) · [npm](https://www.npmjs.com/package/consult-mcp)
 
@@ -26,7 +33,11 @@ To remove it:
 npx -y consult-mcp@latest uninstall
 ```
 
-Requirements: Node 22 or later, macOS or Linux, and at least one of the `claude`, `codex` or `grok` CLIs, signed in.
+Requirements: Node 22 or later on macOS, Linux or Windows, and at least one of the `claude`, `codex` or `grok` CLIs, signed in.
+
+On Windows, everything except [live sessions](#live-sessions) and [session messages](#session-messages) works: those find sessions with `ps` and `lsof` and deliver messages through POSIX shell hooks, so they stay off there. consult never runs an advisor through `cmd.exe`, which would reinterpret characters like `&` and `%` in a question: for a CLI installed as an npm `.cmd` shim it runs the script or binary the shim points at directly.
+
+Check the setup with `npx -y consult-mcp@latest doctor`. It reports each agent CLI and its version, whether consult is registered with it, your settings, the message hooks and whether agy's config is read-only, with a fix for each problem. `doctor --ask` also sends each advisor a one-word question, which shows that its CLI is signed in and can answer.
 
 <details>
 <summary>What install changes</summary>
@@ -37,7 +48,7 @@ Requirements: Node 22 or later, macOS or Linux, and at least one of the `claude`
 
 Each entry sets `PATH` to the directories holding the launcher (`npx` or `node`) and the agent CLIs, because some hosts start MCP servers with a minimal environment.
 
-With [session messages](#session-messages) on, install also adds one hook to each CLI's own hook file: `~/.claude/settings.json`, `~/.codex/hooks.json` and `~/.grok/hooks/consult.json`. Other hooks in those files are left as they are, and `uninstall` or turning messages off removes consult's.
+With [session messages](#session-messages) on, install also adds consult's hooks to each CLI's own hook file: `~/.claude/settings.json`, `~/.codex/hooks.json` and `~/.grok/hooks/consult.json`. Other hooks in those files are left as they are, and `uninstall` or turning messages off removes consult's. The server started through `npx consult-mcp@latest` also rewrites consult's own Claude Code entries when they differ from the current release's, so hook fixes reach you without reinstalling.
 
 To pin to a specific build instead of following `@latest`, install globally with `npm i -g consult-mcp` and run `consult install`, or run `node dist/cli.js install` from a checkout. Hosts then launch that exact script.
 </details>
@@ -54,6 +65,8 @@ To pin to a specific build instead of following `@latest`, install globally with
 
 **`ask_agents`** `{agents, question, effort?, cwd?}` asks several advisors the same question in parallel and returns `{results: [...]}`, one entry per advisor. Each entry is either an answer with its own `session_id` or an `error`. One advisor failing doesn't fail the others.
 
+**`review_changes`** `{agents, base?, focus?, effort?, cwd?}` gets a code review of the git changes in `cwd` from each advisor in parallel. See [Review your changes](#review-your-changes).
+
 **`list_agents`** shows the installed CLIs, their versions and the model IDs each account can use.
 
 **`list_sessions`** and **`ask_session`** `{session_id, question, effort?}` appear when [live sessions](#live-sessions) are on.
@@ -75,6 +88,25 @@ The server's MCP instructions, which hosts add to the agent's context, tell it t
 
 The instructions also tell it to prefer an advisor from a different vendor, to write self-contained questions (the advisor can read the repo but not the conversation), and to check advice against the code before acting on it.
 
+## Review your changes
+
+consult collects the diff itself and sends it to each advisor with review instructions: find real bugs, regressions, security problems and broken contracts with the rest of the code, give severity, `file:line`, the failing scenario and a fix, skip style nits, and say so plainly when nothing is worth fixing. Advisors read the surrounding code to check their findings before reporting them, and stay read-only like any other advisor.
+
+- Without `base`, it reviews everything not yet committed: staged and unstaged changes against `HEAD`, plus the names of new untracked files, which advisors read directly.
+- With `base` (e.g. `main`), it reviews the branch since it left `base`, including uncommitted work (`git diff --merge-base main`).
+- `focus` adds what to look at especially, e.g. `"error handling in the retry path"`.
+
+It always reviews the whole repository, even from a subdirectory, and advisors run at the repository root. The question reaches each CLI as one command-line argument, so the diff is cut to fit: up to about 110 KB on Linux, 190 KB on macOS and 25 KB on Windows, whose command lines are shortest. The advisors are told to read the changed files for the rest. External diff, textconv, fsmonitor and clean/process filter commands are off, so collecting the diff runs nothing but git.
+
+From the shell, `consult review` uses every advisor CLI on your `PATH` unless you pass `--agents codex,grok`:
+
+```bash
+consult review --base main --focus "the new caching layer"
+consult review --agents codex --effort high > review.md
+```
+
+Progress goes to stderr and the reviews to stdout, one section per advisor, each with the command for a follow-up question in the same conversation. The command exits 1 only if every advisor failed.
+
 ## Live sessions
 
 Off by default. When on, agents can ask the agent sessions you already have running, not only fresh advisors. For example, the Codex session working on your API can ask the Claude Code session that wrote the client what it changed.
@@ -109,15 +141,15 @@ Off by default, and only available with live sessions on. `ask_session` asks a c
 
 - **`send_message`** `{session_id, message}` leaves a message of up to 4,000 characters for a session from `list_sessions`. The receiving agent reads it in its own conversation, marked with the sending agent, session id, directory and branch, and with a note that it comes from a peer agent and is not an instruction from you. It can reply with its own `send_message`.
 
-Delivery uses each CLI's hooks, which `consult install` adds when messages are on:
+Delivery uses each CLI's hooks, which `consult install` adds when messages are on, and for Codex its own `codex queue` command:
 
-| CLI | When a waiting message is read |
-| --- | --- |
-| claude | with your next prompt, after its next tool call, or when it finishes its turn |
-| codex | with your next prompt, after its next tool call, or when it finishes its turn. Codex only runs a hook you have trusted |
-| grok | after its next tool call, or when it finishes its turn |
+| CLI | While it is working | While it is idle |
+| --- | --- | --- |
+| claude | read after its next tool call or when it finishes its turn | woken within a few seconds: a background hook (`asyncRewake`) started at the end of each turn waits for a message |
+| codex | read as its next prompt, after the current turn | woken at once: the message is queued with `codex queue` and starts a turn. If that command fails, the message waits for Codex's hooks, which only run once you have trusted them |
+| grok | read after its next tool call or when it finishes its turn | not woken: Grok has no way to start a turn from outside, so it reads the message after you prompt it |
 
-A message never wakes an idle session: it waits until that session works again, so an idle one reads it only after you prompt it. Nothing tells the sender that a message was read. A session without the hook still gets its messages with the reply to its next `list_sessions`, `ask_session` or `send_message` call. Unread messages are dropped after 24 hours; a session holds at most 20, and one session can send another at most 10 an hour.
+Waking a session starts a turn there without you, which uses that session's tokens and lets its agent act on the message. Nothing tells the sender that a message was read. A session without the hook still gets its messages with the reply to its next `list_sessions`, `ask_session` or `send_message` call. Unread messages are dropped after 24 hours; a session holds at most 20, and one session can send another at most 10 an hour.
 
 Turn it on when you install, or later:
 
@@ -185,6 +217,8 @@ The same calls are available from the shell, which is handy for debugging:
 consult ask codex --model gpt-6-astra "Is the retry logic in src/sync.ts safe under concurrent calls?"
 consult ask codex --resume <session_id> "What would you change first?"
 consult ask grok - < question.md      # long questions from a file or pipe
+consult review --base main            # every installed advisor reviews the branch
+consult doctor --ask                  # check the setup and that each advisor answers
 consult agents
 consult settings                      # live sessions, messages, task dispatch, and which agents use consult
 ```

package/dist/cli.js

@@ -4,16 +4,20 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { agy } from "./adapters/agy.js";
+import { homedir } from "node:os";
 import { claude } from "./adapters/claude.js";
 import { codex, codexWorker } from "./adapters/codex.js";
 import { grok, grokWorker } from "./adapters/grok.js";
 import { listAgents } from "./agents.js";
 import { createConsult } from "./consult.js";
 import { progressLog } from "./narrate.js";
-import { hookReply } from "./hook.js";
-import { applyHooks, hookCommand } from "./hooks-install.js";
-import { findOnPath, install, isRegistered, serverCommand, uninstall } from "./install.js";
+import { hookReply, rewakeText } from "./hook.js";
+import { diagnose, formatChecks } from "./doctor.js";
+import { applyHooks, hasConsultHook } from "./hooks-install.js";
+import { findOnPath, install, isRegistered, PACKAGE_NAME, serverCommand, uninstall } from "./install.js";
 import { DEFAULT_SETTINGS, loadSettings, messagesOn, saveSettings, sessionsMode, settingsPath, withMessagesEnabled, withSessionsMode, } from "./settings.js";
+import { collectChanges, reviewQuestion } from "./review.js";
+import { sessionsSupported, SESSIONS_UNSUPPORTED } from "./platform.js";
 import { run } from "./run.js";
 import { createServer } from "./server.js";
 import { claim, inboxDir } from "./sessions/inbox.js";
@@ -34,6 +38,11 @@ const USAGE = `consult ${VERSION} - let coding agents ask each other for advice
                                          ask an advisor; it can read --cwd but never change anything
       --model <id>  --effort low|medium|high  --resume <session_id>  --cwd <dir>
       a question of "-" is read from stdin; progress goes to stderr, the answer alone to stdout
+  consult review [--agents a,b] [--base <branch>] [--focus <text>] [--effort low|medium|high] [--cwd <dir>]
+                                         review the uncommitted changes (or the branch since --base) with
+                                         every installed advisor in parallel; findings go to stdout
+  consult doctor [--ask]                 check node, the agent CLIs, registrations, settings and hooks;
+                                         --ask also sends each advisor a one-word question to prove it is signed in
   consult agents                         list installed CLIs and models
   consult install [--sessions off|repo|machine] [--messages on|off]
                                          register the MCP server with claude, codex and grok
@@ -82,6 +91,7 @@ async function serve() {
         askFork: (target, question, effort, signal) => askSession(target, question, effort, withShutdown(signal)),
         warn: (message) => process.stderr.write(`consult: ${message}\n`),
     });
+    refreshClaudeHooks();
     const tasks = tasksEnabled()
         ? createTaskManager({
             run,
@@ -97,6 +107,7 @@ async function serve() {
         },
         listAgents: () => listAgents(run),
         defaultCwd: process.cwd(),
+        collectChanges: (cwd, base, signal) => collectChanges(run, cwd, base, withShutdown(signal)),
         ...(sessions ? { sessions } : {}),
         ...(tasks ? { tasks } : {}),
     });
@@ -145,7 +156,7 @@ async function askCommand(argv) {
             model: values.model,
             effort: values.effort,
             sessionId: values.resume,
-        }, undefined, progress.update);
+        }, interruptSignal(), progress.update);
     }
     finally {
         progress.stop();
@@ -153,12 +164,107 @@ async function askCommand(argv) {
     process.stdout.write(`${result.answer}\n`);
     process.stderr.write(`\n[${result.agent}${result.model ? ` ${result.model}` : ""} · session ${result.sessionId} · ${(result.durationMs / 1000).toFixed(1)}s]\n`);
 }
+/** Every advisor CLI on PATH, for commands that default to "all of them". */
+const installedAgents = () => AGENTS.filter((agent) => findOnPath(agent, process.env.PATH ?? ""));
+function parseAgents(list) {
+    if (list === undefined) {
+        const found = installedAgents();
+        if (found.length === 0)
+            throw new Error(`no advisor CLI found on PATH (${AGENTS.join(", ")})`);
+        return found;
+    }
+    const agents = [...new Set(list.split(",").map((a) => a.trim()).filter(Boolean))];
+    const unknown = agents.filter((a) => !AGENTS.includes(a));
+    if (agents.length === 0 || unknown.length > 0)
+        throw new Error(`--agents must be a comma-separated list of ${AGENTS.join(", ")}`);
+    return agents;
+}
+/** `value` quoted so a pasted command takes it literally: single quotes for POSIX shells, double on Windows. */
+const shellLiteral = (value) => process.platform === "win32" ? `"${value.replaceAll('"', '""')}"` : `'${value.replaceAll("'", "'\\''")}'`;
+/** Aborts on Ctrl-C or SIGTERM, so advisors in their own process groups stop with the command. */
+function interruptSignal() {
+    const controller = new AbortController();
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.once(sig, () => {
+            controller.abort();
+            process.exitCode = 130;
+        });
+    }
+    return controller.signal;
+}
+async function reviewCommand(argv) {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: { agents: { type: "string" }, base: { type: "string" }, focus: { type: "string" }, effort: { type: "string" }, cwd: { type: "string" } },
+    });
+    if (values.effort && !EFFORTS.includes(values.effort))
+        throw new Error(`effort must be one of ${EFFORTS.join(", ")}`);
+    const agents = parseAgents(values.agents);
+    const { ask } = consult();
+    const signal = interruptSignal();
+    const changes = await collectChanges(run, values.cwd ?? process.cwd(), values.base, signal);
+    const question = reviewQuestion(changes, values.focus);
+    const pending = new Set(agents);
+    const progress = progressLog((line) => process.stderr.write(line), () => `waiting on ${[...pending].join(", ")}`, HEARTBEAT_MS);
+    progress.update(`reviewing ${changes.base ? `changes since ${changes.base}` : "uncommitted changes"} with ${agents.join(", ")} (read-only)`);
+    let entries;
+    try {
+        entries = await Promise.all(agents.map(async (agent) => {
+            try {
+                const request = { agent, question, cwd: changes.root, effort: values.effort };
+                const result = await ask(request, signal, (text) => progress.update(`${agent}: ${text}`));
+                progress.update(`${agent} finished in ${(result.durationMs / 1000).toFixed(0)}s`);
+                return { agent, result };
+            }
+            catch (err) {
+                progress.update(`${agent} failed`);
+                return { agent, error: errorMessage(err) };
+            }
+            finally {
+                pending.delete(agent);
+            }
+        }));
+    }
+    finally {
+        progress.stop();
+    }
+    const sections = entries.map((e) => "result" in e && e.result
+        ? `## ${e.agent}${e.result.model ? ` (${e.result.model})` : ""}\n\n${e.result.answer}\n\n[session ${e.result.sessionId}: consult ask ${e.agent} --resume ${e.result.sessionId} --cwd ${shellLiteral(changes.root)} "..."]`
+        : `## ${e.agent}\n\nFailed: ${"error" in e ? e.error : "unknown error"}`);
+    process.stdout.write(`${sections.join("\n\n")}\n`);
+    if (entries.every((e) => "error" in e))
+        process.exitCode = 1;
+}
+async function doctorCommand(argv) {
+    const { values } = parseArgs({ args: [...argv], options: { ask: { type: "boolean" } } });
+    const { ask } = consult();
+    const checks = await diagnose({
+        nodeVersion: process.version,
+        agents: await listAgents(run),
+        isRegistered: (agent) => isRegistered(run, agent),
+        loadSettings: () => loadSettings(settingsPath()),
+        hasMessageHook: (agent) => hasConsultHook(agent),
+        sessionsSupported: sessionsSupported(),
+        agyContainment: async () => {
+            await agy.prepare?.(run, process.cwd());
+        },
+        ...(values.ask ? { ping: (agent) => ask({ agent, question: "Reply with the single word OK.", cwd: homedir(), effort: "low" }) } : {}),
+    });
+    process.stdout.write(`consult ${VERSION}\n\n${formatChecks(checks)}\n`);
+    if (checks.some((c) => c.status === "fail"))
+        process.exitCode = 1;
+}
 const installedHosts = () => HOSTS.filter((agent) => findOnPath(agent, process.env.PATH ?? ""));
 const scriptPath = () => realpathSync(fileURLToPath(import.meta.url));
 const searchPath = () => process.env.PATH ?? "";
 const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
 /** Applies --sessions, or asks in a terminal. With neither, the setting stays as it is. */
 async function configureSessions(flag) {
+    if (!sessionsSupported()) {
+        if (flag && flag !== "off")
+            process.stderr.write(`consult: ${SESSIONS_UNSUPPORTED}\n`);
+        return;
+    }
     const path = settingsPath();
     let current = DEFAULT_SETTINGS;
     try {
@@ -177,6 +283,8 @@ async function configureSessions(flag) {
 }
 /** Applies --messages, or asks in a terminal while live sessions are on. With neither, the setting stays as it is. */
 async function configureMessages(flag) {
+    if (!sessionsSupported())
+        return false;
     const path = settingsPath();
     let current;
     try {
@@ -199,20 +307,52 @@ async function configureMessages(flag) {
     return messagesOn(next);
 }
 /** Puts the message hook in `agents` and removes it from every other installed CLI. Reports only what changed. */
-function setMessageHooks(agents) {
-    const command = agents.length > 0 ? hookCommand(serverCommand(scriptPath(), searchPath())) : undefined;
+function setMessageHooks(wanted) {
+    // The hooks are POSIX shell; on Windows there is only ever something to remove.
+    const agents = sessionsSupported() ? wanted : [];
+    const cmd = agents.length > 0 ? serverCommand(scriptPath(), searchPath()) : undefined;
     const hosts = installedHosts();
     return [
-        ...applyHooks(hosts.filter((agent) => agents.includes(agent)), command),
+        ...applyHooks(hosts.filter((agent) => agents.includes(agent)), cmd),
         ...applyHooks(hosts.filter((agent) => !agents.includes(agent)), undefined),
     ].filter((r) => r.changed || !r.ok);
 }
+/**
+ * Hook commands are written into the hosts' settings at install time, so a fix to one would only reach users who
+ * reinstall. Each server start rewrites consult's own Claude Code entries where they already are; Codex's are
+ * left alone because changing them makes Codex ask the user to trust them again.
+ */
+function refreshClaudeHooks() {
+    try {
+        if (!sessionsSupported() || !messagesOn(loadSettings(settingsPath())) || !hasConsultHook("claude"))
+            return;
+        const cmd = serverCommand(scriptPath(), searchPath());
+        // Only a server started through `npx consult-mcp@latest`, as install sets up; a checkout or a pinned global
+        // install must not repoint the user's hooks at itself.
+        if (cmd.args.includes(`${PACKAGE_NAME}@latest`))
+            applyHooks(["claude"], cmd);
+    }
+    catch {
+        // Reinstalling fixes it; the server works either way.
+    }
+}
 /** Never fails and never prints anything but a hook reply: the host runs this on every tool call. */
-async function hookCommandMain() {
+async function hookCommandMain(argv) {
     try {
         if (!messagesOn(loadSettings(settingsPath())))
             return;
-        const reply = hookReply(JSON.parse(await readStdin()), (sessionId) => claim(inboxDir(), sessionId));
+        const payload = JSON.parse(await readStdin());
+        const take = (sessionId) => claim(inboxDir(), sessionId);
+        if (argv.includes("--rewake")) {
+            // Claude Code wakes an idle session when its background hook exits 2, and shows it what stderr holds.
+            const text = rewakeText(payload, take);
+            if (!text)
+                return;
+            process.stderr.write(`${text}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const reply = hookReply(payload, take);
         if (reply)
             process.stdout.write(`${reply}\n`);
     }
@@ -235,6 +375,10 @@ async function main(argv) {
             return serve();
         case "ask":
             return askCommand(rest);
+        case "doctor":
+            return doctorCommand(rest);
+        case "review":
+            return reviewCommand(rest);
         case "agents":
             process.stdout.write(`${JSON.stringify(await listAgents(run), null, 2)}\n`);
             return;
@@ -255,7 +399,7 @@ async function main(argv) {
             return;
         }
         case "hook":
-            return hookCommandMain();
+            return hookCommandMain(rest);
         case "settings": {
             if (!isInteractive()) {
                 throw new Error("consult settings needs an interactive terminal; in scripts use `consult install --sessions=off|repo|machine`");
@@ -270,6 +414,7 @@ async function main(argv) {
                 register: (agents) => install(run, cmd, agents),
                 unregister: (agents) => uninstall(run, agents),
                 setMessageHooks,
+                sessionsSupported: sessionsSupported(),
             });
             return;
         }

package/dist/consult.js

@@ -1,8 +1,25 @@
 import { statSync } from "node:fs";
 import { describeLine } from "./narrate.js";
+import { commandLineSize, maxCommandLine, resolveForSpawn } from "./platform.js";
 import { frameForkPrompt, framePrompt } from "./prompt.js";
 import { AdvisorError, } from "./types.js";
 const STDERR_TAIL = 2000;
+/** The question reaches each CLI as one argument, so it must fit the platform's command-line limit. */
+function assertFitsCommandLine(agent, invocation) {
+    // Measured as it will be spawned: on Windows a .cmd shim becomes node plus the script path.
+    let spawned = invocation;
+    try {
+        spawned = resolveForSpawn(invocation.command, invocation.args);
+    }
+    catch {
+        // run() reports the missing CLI.
+    }
+    const size = commandLineSize(spawned.command, spawned.args);
+    const max = maxCommandLine();
+    if (size > max) {
+        throw new AdvisorError(`the question for ${agent} is too long (${Math.round(size / 1000)} KB, limit ${Math.round(max / 1000)} KB on this platform): point the advisor at files instead of pasting them`);
+    }
+}
 export function assertDirectory(cwd) {
     let isDir = false;
     try {
@@ -45,6 +62,7 @@ export function createConsult({ run, adapters, timeoutMs }) {
         // Computed per call, never cached: containment must reflect the config as it is right now.
         const extraArgs = adapter.prepare ? await adapter.prepare(run, request.cwd, signal) : [];
         const invocation = invoke(extraArgs);
+        assertFitsCommandLine(adapter.name, invocation);
         const { describe } = adapter;
         const lines = [];
         const onStdoutLine = onUpdate && describe

package/dist/doctor.js

@@ -0,0 +1,87 @@
+import { messagesOn } from "./settings.js";
+import { HOSTS } from "./types.js";
+const MIN_NODE_MAJOR = 22;
+const INSTALL_FIX = "run `npx -y consult-mcp@latest install`";
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+const isHost = (agent) => HOSTS.includes(agent);
+function nodeCheck(version) {
+    const major = Number(/^v?(\d+)/.exec(version)?.[1]);
+    return major >= MIN_NODE_MAJOR
+        ? { status: "ok", label: `node ${version}` }
+        : { status: "fail", label: `node ${version}`, fix: `install Node ${MIN_NODE_MAJOR} or later` };
+}
+function settingsChecks(deps, hosts) {
+    let settings;
+    try {
+        settings = deps.loadSettings();
+    }
+    catch (err) {
+        return [{ status: "fail", label: "settings file invalid", detail: errorMessage(err), fix: "fix or delete the file, then run `consult settings`" }];
+    }
+    const features = [
+        `live sessions ${settings.sessions.enabled ? settings.sessions.scope : "off"}`,
+        `messages ${messagesOn(settings) ? "on" : "off"}`,
+        `task dispatch ${settings.tasks.enabled ? "on" : "off"}`,
+    ];
+    const summary = { status: "ok", label: "settings", detail: features.join(", ") };
+    if (deps.sessionsSupported === false) {
+        return settings.sessions.enabled
+            ? [summary, { status: "warn", label: "live sessions and messages are off on this platform", fix: "they need macOS or Linux" }]
+            : [summary];
+    }
+    if (!messagesOn(settings))
+        return [summary];
+    const hooks = hosts.map((agent) => deps.hasMessageHook(agent)
+        ? { status: "ok", label: `${agent} message hook installed` }
+        : { status: "fail", label: `${agent} message hook missing`, fix: INSTALL_FIX });
+    return [summary, ...hooks];
+}
+async function pingCheck(ping, agent) {
+    try {
+        const result = await ping(agent);
+        const detail = [...(result.model ? [result.model] : []), `${(result.durationMs / 1000).toFixed(1)}s`].join(", ");
+        return { status: "ok", label: `${agent} answered`, detail };
+    }
+    catch (err) {
+        return { status: "fail", label: `${agent} did not answer`, detail: errorMessage(err), fix: `check that \`${agent}\` works and is signed in when you run it yourself` };
+    }
+}
+/** Checks the setup consult depends on: node, the agent CLIs, registrations, settings, hooks and agy's containment. */
+export async function diagnose(deps) {
+    const installed = deps.agents.filter((a) => a.installed).map((a) => a.agent);
+    const agentChecks = deps.agents.map((a) => a.installed ? { status: "ok", label: `${a.agent} ${a.version ?? ""}`.trim() } : { status: "warn", label: `${a.agent} not installed` });
+    if (installed.length === 0) {
+        return [nodeCheck(deps.nodeVersion), ...agentChecks, { status: "fail", label: "no agent CLI installed", fix: "install and sign in to claude, codex, grok or agy" }];
+    }
+    const hosts = installed.filter(isHost);
+    // `consult settings` can leave a host out on purpose, so only a setup with no host at all is a failure.
+    const registered = (await Promise.all(hosts.map(async (agent) => ((await deps.isRegistered(agent)) ? [agent] : [])))).flat();
+    const registrations = hosts.map((agent) => registered.includes(agent)
+        ? { status: "ok", label: `${agent} registered` }
+        : { status: registered.length === 0 ? "fail" : "warn", label: `${agent} not registered`, fix: INSTALL_FIX });
+    let agyOk = true;
+    const agy = [];
+    if (installed.includes("agy")) {
+        try {
+            await deps.agyContainment();
+            agy.push({ status: "ok", label: "agy is read-only" });
+        }
+        catch (err) {
+            agyOk = false;
+            agy.push({ status: "warn", label: "agy is not read-only", detail: errorMessage(err), fix: "consult refuses to run agy until this is fixed; the other advisors are unaffected" });
+        }
+    }
+    const { ping } = deps;
+    const pings = ping ? await Promise.all(installed.filter((a) => a !== "agy" || agyOk).map((a) => pingCheck(ping, a))) : [];
+    return [nodeCheck(deps.nodeVersion), ...agentChecks, ...registrations, ...settingsChecks(deps, registered), ...agy, ...pings];
+}
+const MARKS = { ok: "✓", warn: "!", fail: "✗" };
+export function formatChecks(checks) {
+    const lines = checks.flatMap((c) => [
+        `${MARKS[c.status]} ${c.label}${c.detail ? `: ${c.detail}` : ""}`,
+        ...(c.fix && c.status !== "ok" ? [`  → ${c.fix}`] : []),
+    ]);
+    const problems = checks.filter((c) => c.status === "fail").length;
+    const summary = problems === 0 ? "No problems found." : `${problems} problem${problems === 1 ? "" : "s"} found.`;
+    return `${lines.join("\n")}\n\n${summary}`;
+}

package/dist/hook.js

@@ -5,6 +5,17 @@ function eventOf(payload) {
     const raw = text(payload.hook_event_name) ?? text(payload.hookEventName);
     return raw ? EVENTS[raw.toLowerCase().replaceAll("_", "")] : undefined;
 }
+/** For the idle watcher: this session's waiting messages as plain text, whatever event started the watcher. */
+export function rewakeText(payload, claim) {
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const event = payload;
+    const sessionId = text(event.session_id) ?? text(event.sessionId);
+    if (!sessionId || event.agent_id || event.agentId)
+        return undefined;
+    const messages = claim(sessionId);
+    return messages.length > 0 ? frameMessages(messages) : undefined;
+}
 /**
  * What `consult hook` prints for one host hook event: this session's waiting messages in the host's reply
  * format, or nothing. Claude Code and Codex send snake_case fields; Grok sends camelCase ones as well.

package/dist/hooks-install.js

@@ -4,6 +4,9 @@ import { dirname, join } from "node:path";
 /** Marks consult's handlers in hook files that other tools also write to. */
 const MARKER = "CONSULT_HOOK=1";
 const TIMEOUT_SEC = 10;
+/** How long Claude Code lets the idle watcher wait for a message before it stops it. */
+const WATCH_TIMEOUT_SEC = 24 * 60 * 60;
+const WATCH_POLL_SEC = 3;
 /** Grok discards what a UserPromptSubmit hook prints, so it gets no hook there. */
 const EVENTS = {
     claude: ["UserPromptSubmit", "PostToolUse", "Stop"],
@@ -24,6 +27,28 @@ export function hookCommand(cmd) {
         "done; exit 0",
     ].join(" ");
 }
+/**
+ * For Claude Code's `asyncRewake`: started in the background when a turn ends, it waits for a message and then
+ * exits 2 with the message on stderr, which wakes the idle session. One watcher runs per session, and it stops
+ * when the session's process is gone. Headless sessions get none. Grok also reads Claude Code's hook file but runs every handler in the
+ * foreground, so the command leaves at once when the event comes from Grok.
+ */
+export function watchCommand(cmd) {
+    const launcher = [cmd.command, ...cmd.args.slice(0, -1), "hook", "--rewake"].map(shellQuote).join(" ");
+    return [
+        // Headless runs (claude -p, the Agent SDK) wait for background hooks before they exit, so the watcher would
+        // keep them alive. They can't be woken anyway.
+        `i=$(cat); case "$CLAUDE_CODE_ENTRYPOINT" in sdk-*) exit 0;; esac; case "$i" in *'"hookEventName"'*) exit 0;; esac;`,
+        `s=$(printf '%s' "$i" | sed -n 's/.*"session_id" *: *"\\([A-Za-z0-9-]*\\)".*/\\1/p'); [ -n "$s" ] || exit 0;`,
+        'b="${XDG_STATE_HOME:-$HOME/.local/state}/consult"; w="$b/watch-$s.pid";',
+        'p=$(cat "$w" 2>/dev/null); [ -n "$p" ] && kill -0 "$p" 2>/dev/null && exit 0;',
+        'mkdir -p "$b"; echo $$ > "$w";',
+        "while kill -0 $PPID 2>/dev/null; do",
+        `if [ -d "$b/inbox/$s" ]; then printf '%s' "$i" | ${MARKER} PATH=${shellQuote(cmd.path)}:"$PATH" ${launcher}; [ $? -eq 2 ] && { rm -f "$w"; exit 2; }; fi;`,
+        `sleep ${WATCH_POLL_SEC};`,
+        'done; rm -f "$w"; exit 0',
+    ].join(" ");
+}
 export function hookFilePath(agent, env = process.env) {
     switch (agent) {
         case "claude":
@@ -48,10 +73,10 @@ function withoutOurs(groups) {
     });
 }
 /**
- * A hook file's content with consult's handlers set to `command` on `events`, or removed when there is no
- * command. Everything else in the file is kept.
+ * A hook file's content with consult's handlers set to `command` on `events` plus the `extra` ones, or removed
+ * when there is no command. Everything else in the file is kept.
  */
-export function withConsultHooks(config, command, events) {
+export function withConsultHooks(config, command, events, extra = []) {
     const base = isObject(config) ? config : {};
     const existing = isObject(base.hooks) ? base.hooks : {};
     const cleaned = Object.entries(existing).flatMap(([event, groups]) => {
@@ -60,15 +85,19 @@ export function withConsultHooks(config, command, events) {
     });
     const hooks = Object.fromEntries(cleaned);
     if (command) {
-        const group = { hooks: [{ type: "command", command, timeout: TIMEOUT_SEC }] };
-        for (const event of events)
-            hooks[event] = [...(Array.isArray(hooks[event]) ? hooks[event] : []), group];
+        const entries = [
+            ...events.map((event) => ({ event, handler: { type: "command", command, timeout: TIMEOUT_SEC } })),
+            ...extra,
+        ];
+        for (const { event, handler } of entries) {
+            hooks[event] = [...(Array.isArray(hooks[event]) ? hooks[event] : []), { hooks: [handler] }];
+        }
     }
     const { hooks: _dropped, ...rest } = base;
     return Object.keys(hooks).length > 0 ? { ...rest, hooks } : rest;
 }
 /** Writes or removes consult's hooks in one file. Returns whether the file changed. */
-export function applyHookFile(path, command, events) {
+export function applyHookFile(path, command, events, extra = []) {
     const exists = existsSync(path);
     if (!exists && !command)
         return false;
@@ -84,7 +113,7 @@ export function applyHookFile(path, command, events) {
         if (!isObject(config))
             throw new Error(`${path} does not hold a JSON object`);
     }
-    const next = withConsultHooks(config, command, events);
+    const next = withConsultHooks(config, command, events, extra);
     if (exists && Object.keys(next).length === 0 && Object.keys(config).length > 0) {
         // Only consult's hooks were in it.
         rmSync(path);
@@ -101,12 +130,26 @@ export function applyHookFile(path, command, events) {
     renameSync(tmp, target);
     return true;
 }
+/** Whether this CLI's hook file holds consult's message hook. */
+export function hasConsultHook(agent, env = process.env) {
+    try {
+        return readFileSync(hookFilePath(agent, env), "utf8").includes(MARKER);
+    }
+    catch {
+        return false;
+    }
+}
 /** Installs consult's message hook for each CLI, or removes it when there is no command. One failing does not stop the others. */
-export function applyHooks(agents, command, env = process.env) {
+export function applyHooks(agents, cmd, env = process.env) {
+    const command = cmd ? hookCommand(cmd) : undefined;
     return agents.map((agent) => {
         const path = hookFilePath(agent, env);
         try {
-            const changed = applyHookFile(path, command, EVENTS[agent]);
+            // Only Claude Code can be woken by a hook; Codex is woken through `codex queue` and Grok not at all.
+            const watcher = cmd && agent === "claude"
+                ? [{ event: "Stop", handler: { type: "command", command: watchCommand(cmd), asyncRewake: true, timeout: WATCH_TIMEOUT_SEC } }]
+                : [];
+            const changed = applyHookFile(path, command, EVENTS[agent], watcher);
             const what = command ? (changed ? "message hook written to" : "message hook already in") : changed ? "message hook removed from" : "no message hook in";
             const trust = command && agent === "codex" ? "; codex may need you to trust the hook before it runs" : "";
             return { agent, ok: true, changed, message: `${agent}: ${what} ${path}${trust}` };