consult-mcp 0.2.1 → 0.3.1

package/README.md

@@ -52,6 +52,8 @@ To pin to a specific build instead of following `@latest`, install globally with
 
 **`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.
+
 While an advisor is working, the server sends MCP progress notifications (`codex is thinking (40s)`), so hosts that show progress don't look stuck.
 
 ## When agents consult
@@ -65,6 +67,34 @@ 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.
 
+## 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.
+
+- **`list_sessions`** lists other live sessions: agent, session id, directory, git branch, title, and when each started and was last active. Nothing else from their conversations.
+- **`ask_session`** `{session_id, question, effort?}` asks a read-only **copy** of that session. consult forks it (`claude --resume <id> --fork-session`, `codex exec fork <id>`, `grok --resume <id> --fork-session`) with the same containment as any advisor. The copy knows everything the session has seen, while the session itself is not interrupted and never sees the question. Pass the reply's `session_id` and `cwd` to `ask_agent` for follow-ups.
+
+Turn it on when you install, or later:
+
+```bash
+npx -y consult-mcp@latest install --sessions=repo   # or off, machine; without the flag, install asks when run in a terminal
+npx -y consult-mcp@latest settings                  # interactive: live sessions, and which agents use consult
+```
+
+| Setting | Who can see and ask whom |
+| --- | --- |
+| `off` (default) | Nobody. The tools don't appear. |
+| `repo` | Sessions in the same git repository, including its worktrees (outside git: the same directory) |
+| `machine` | Every consult session you run on this machine |
+
+Settings are stored in `$XDG_CONFIG_HOME/consult/settings.json` (default `~/.config/consult/`). Running sessions register in `$XDG_STATE_HOME/consult/sessions/` (default `~/.local/state/consult/`), and only you can read those files. Turning sessions on takes effect in new agent sessions; turning them off, or changing the scope, applies immediately.
+
+| CLI | How consult finds the session |
+| --- | --- |
+| claude | the record Claude Code keeps for each running process (`~/.claude/sessions/<pid>.json`), so it follows `/resume` and `/clear`; `CLAUDE_CODE_SESSION_ID` as a fallback. Listed once the conversation is saved, after its first message |
+| codex | the `rollout-*.jsonl` file the codex process holds open, from the session's first turn on |
+| grok | the `~/.grok/sessions/<cwd>/<session id>/events.jsonl` file the interactive grok process holds open, from the session's first turn on; not identified if several sessions are open |
+
 ## How advisors are contained
 
 Every advisor runs headless and read-only, and has no MCP servers. So an advisor can't call consult again, which prevents loops.
@@ -75,6 +105,8 @@ Every advisor runs headless and read-only, and has no MCP servers. So an advisor
 | codex | `exec`, `sandbox_mode="read-only"`, `approval_policy="never"`, plugins off, and every enabled MCP server disabled by name (Codex runs MCP tools outside its sandbox) |
 | grok | `--tools read_file,grep,list_dir --disallowed-tools Agent,search_tool,use_tool` (the MCP helper tools can reach servers that write files) |
 
+`ask_session` copies use the same flags, plus `--resume <id> --fork-session` (claude, grok) or `exec fork <id>` (codex), so the live session's own transcript is only read.
+
 consult doesn't use Grok's kernel sandbox (`--sandbox read-only`), because it refuses to start on machines where `/var/run/docker.sock` is a symlink, as it often is on Macs with Docker installed.
 
 The first message of each session also tells the advisor that another agent is consulting it. It should answer directly, skip approval and brainstorming workflows, and not modify anything.
@@ -89,6 +121,7 @@ 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 agents
+consult settings                      # live sessions, and which agents use consult
 ```
 
 Use `npx -y consult-mcp@latest <command>` if it isn't installed globally. `CONSULT_TIMEOUT_SEC` (default 900) caps each advisor call.

package/dist/adapters/claude.js

@@ -2,25 +2,30 @@ import { randomUUID } from "node:crypto";
 import { AdvisorError } from "../types.js";
 // --restricted drops every tool that runs commands or code and confines file tools to the cwd;
 // --strict-mcp-config with no --mcp-config loads no MCP servers, so the advisor cannot call consult back.
+const CONTAINMENT = ["--restricted", "--tools", "Read,Grep,Glob", "--strict-mcp-config"];
+function invocation(request, prompt, session) {
+    return {
+        command: "claude",
+        args: [
+            "-p",
+            "--output-format", "json",
+            ...CONTAINMENT,
+            ...session,
+            ...(request.model ? ["--model", request.model] : []),
+            ...(request.effort ? ["--effort", request.effort] : []),
+            prompt,
+        ],
+    };
+}
 export const claude = {
     name: "claude",
     command: "claude",
     build(request, prompt) {
-        const session = request.sessionId ? ["--resume", request.sessionId] : ["--session-id", randomUUID()];
-        return {
-            command: "claude",
-            args: [
-                "-p",
-                "--output-format", "json",
-                "--restricted",
-                "--tools", "Read,Grep,Glob",
-                "--strict-mcp-config",
-                ...session,
-                ...(request.model ? ["--model", request.model] : []),
-                ...(request.effort ? ["--effort", request.effort] : []),
-                prompt,
-            ],
-        };
+        return invocation(request, prompt, request.sessionId ? ["--resume", request.sessionId] : ["--session-id", randomUUID()]);
+    },
+    // --fork-session copies the source into a new session id, so the live session's transcript is never written.
+    fork(sourceSessionId, request, prompt) {
+        return invocation(request, prompt, ["--resume", sourceSessionId, "--fork-session"]);
     },
     parse(stdout) {
         let out;

package/dist/adapters/codex.js

@@ -12,6 +12,15 @@ async function listEnabledMcpServers(run, cwd, signal) {
     const servers = JSON.parse(res.stdout);
     return servers.filter((s) => s.enabled).map((s) => s.name);
 }
+function configArgs(request, extraArgs) {
+    return [
+        "-c", 'sandbox_mode="read-only"',
+        "-c", 'approval_policy="never"',
+        ...(request.model ? ["-c", `model=${JSON.stringify(request.model)}`] : []),
+        ...(request.effort ? ["-c", `model_reasoning_effort="${request.effort}"`] : []),
+        ...extraArgs,
+    ];
+}
 export const codex = {
     name: "codex",
     command: "codex",
@@ -20,16 +29,16 @@ export const codex = {
         return [...PLUGINS_OFF, ...names.flatMap((n) => ["-c", `mcp_servers.${n}.enabled=false`])];
     },
     build(request, prompt, extraArgs) {
-        const config = [
-            "-c", 'sandbox_mode="read-only"',
-            "-c", 'approval_policy="never"',
-            ...(request.model ? ["-c", `model=${JSON.stringify(request.model)}`] : []),
-            ...(request.effort ? ["-c", `model_reasoning_effort="${request.effort}"`] : []),
-            ...extraArgs,
-        ];
         const head = request.sessionId ? ["exec", "resume", "--json"] : ["exec", "--json"];
         const tail = request.sessionId ? [request.sessionId, prompt] : [prompt];
-        return { command: "codex", args: [...head, "--skip-git-repo-check", ...config, ...tail] };
+        return { command: "codex", args: [...head, "--skip-git-repo-check", ...configArgs(request, extraArgs), ...tail] };
+    },
+    // exec fork starts a new thread from the source's history; the source rollout is only read.
+    fork(sourceSessionId, request, prompt, extraArgs) {
+        return {
+            command: "codex",
+            args: ["exec", "fork", "--json", "--skip-git-repo-check", ...configArgs(request, extraArgs), sourceSessionId, prompt],
+        };
     },
     parse(stdout) {
         const events = parseJsonLines(stdout);

package/dist/adapters/grok.js

@@ -4,23 +4,28 @@ import { parseJsonLines } from "../jsonl.js";
 // --tools keeps only read-only built-ins, but grok still adds its MCP meta-tools (search_tool/use_tool),
 // which can reach write-capable MCP servers, so those are removed too. Grok's kernel sandbox is not used:
 // it refuses to start on machines where /var/run/docker.sock is a symlink.
+function invocation(request, prompt, session) {
+    return {
+        command: "grok",
+        args: [
+            "--single", prompt,
+            "--output-format", "streaming-messages-json",
+            "--tools", "read_file,grep,list_dir",
+            "--disallowed-tools", "Agent,search_tool,use_tool",
+            ...session,
+            ...(request.model ? ["--model", request.model] : []),
+            ...(request.effort ? ["--reasoning-effort", request.effort] : []),
+        ],
+    };
+}
 export const grok = {
     name: "grok",
     command: "grok",
     build(request, prompt) {
-        const session = request.sessionId ? ["--resume", request.sessionId] : ["--session-id", randomUUID()];
-        return {
-            command: "grok",
-            args: [
-                "--single", prompt,
-                "--output-format", "streaming-messages-json",
-                "--tools", "read_file,grep,list_dir",
-                "--disallowed-tools", "Agent,search_tool,use_tool",
-                ...session,
-                ...(request.model ? ["--model", request.model] : []),
-                ...(request.effort ? ["--reasoning-effort", request.effort] : []),
-            ],
-        };
+        return invocation(request, prompt, request.sessionId ? ["--resume", request.sessionId] : ["--session-id", randomUUID()]);
+    },
+    fork(sourceSessionId, request, prompt) {
+        return invocation(request, prompt, ["--resume", sourceSessionId, "--fork-session"]);
     },
     parse(stdout) {
         const events = parseJsonLines(stdout);

package/dist/cli.js

@@ -8,10 +8,15 @@ import { codex } from "./adapters/codex.js";
 import { grok } from "./adapters/grok.js";
 import { listAgents } from "./agents.js";
 import { createConsult } from "./consult.js";
-import { findOnPath, install, serverCommand, uninstall } from "./install.js";
+import { findOnPath, install, isRegistered, serverCommand, uninstall } from "./install.js";
+import { DEFAULT_SETTINGS, loadSettings, saveSettings, sessionsMode, settingsPath, withSessionsMode } from "./settings.js";
 import { run } from "./run.js";
 import { createServer } from "./server.js";
-import { AGENTS, EFFORTS } from "./types.js";
+import { listLive, registryDir } from "./sessions/registry.js";
+import { assertNotLiveSession } from "./sessions/service.js";
+import { sessionTools } from "./sessions/wire.js";
+import { chooseInstallMode, isInteractive, parseSessionsFlag, promptSessionsMode, runSettings } from "./tui.js";
+import { AGENTS, EFFORTS, SESSION_ID_PATTERN } from "./types.js";
 import { VERSION } from "./version.js";
 const DEFAULT_TIMEOUT_SEC = 900;
 const USAGE = `consult ${VERSION} - let coding agents ask each other for advice
@@ -20,8 +25,10 @@ const USAGE = `consult ${VERSION} - let coding agents ask each other for advice
   consult ask <agent> [options] <question...>
       --model <id>  --effort low|medium|high  --resume <session_id>  --cwd <dir>
   consult agents                         list installed CLIs and models
-  consult install                        register the MCP server with claude, codex and grok
+  consult install [--sessions off|repo|machine]
+                                         register the MCP server with claude, codex and grok
   consult uninstall                      remove it from all three
+  consult settings                       live sessions, and which agents use consult (interactive)
 
 agents: ${AGENTS.join(", ")}    timeout: CONSULT_TIMEOUT_SEC (default ${DEFAULT_TIMEOUT_SEC})`;
 function timeoutMs() {
@@ -31,16 +38,35 @@ function timeoutMs() {
         throw new Error(`CONSULT_TIMEOUT_SEC must be a positive number, got ${raw}`);
     return sec * 1000;
 }
+/** Resuming a live session in place would write its transcript; those are reachable only through ask_session. */
+const refuseLive = (sessionId) => {
+    if (sessionId)
+        assertNotLiveSession(sessionId, listLive(registryDir()));
+};
 const consult = () => createConsult({ run, adapters: { claude, codex, grok }, timeoutMs: timeoutMs() });
 // Advisors run in their own process groups, so they would outlive the server. Stop them when the host
 // disconnects or signals us.
 async function serve() {
     const shutdown = new AbortController();
-    const { ask } = consult();
+    const withShutdown = (signal) => (signal ? AbortSignal.any([signal, shutdown.signal]) : shutdown.signal);
+    const { ask, askSession } = consult();
+    const sessions = await sessionTools({
+        run,
+        env: process.env,
+        cwd: process.cwd(),
+        pid: process.pid,
+        signal: shutdown.signal,
+        askFork: (target, question, effort, signal) => askSession(target, question, effort, withShutdown(signal)),
+        warn: (message) => process.stderr.write(`consult: ${message}\n`),
+    });
     const server = createServer({
-        ask: (request, signal) => ask(request, signal ? AbortSignal.any([signal, shutdown.signal]) : shutdown.signal),
+        ask: (request, signal) => {
+            refuseLive(request.sessionId);
+            return ask(request, withShutdown(signal));
+        },
         listAgents: () => listAgents(run),
         defaultCwd: process.cwd(),
+        ...(sessions ? { sessions } : {}),
     });
     const transport = new StdioServerTransport();
     transport.onclose = () => shutdown.abort();
@@ -65,6 +91,10 @@ async function askCommand(argv) {
         throw new Error(`agent must be one of ${AGENTS.join(", ")}`);
     if (values.effort && !EFFORTS.includes(values.effort))
         throw new Error(`effort must be one of ${EFFORTS.join(", ")}`);
+    if (values.resume !== undefined && !SESSION_ID_PATTERN.test(values.resume)) {
+        throw new Error("--resume must be a session id: letters, digits and hyphens, not starting with a hyphen");
+    }
+    refuseLive(values.resume);
     const result = await consult().ask({
         agent: agent,
         question: words.join(" "),
@@ -77,6 +107,27 @@ async function askCommand(argv) {
     process.stderr.write(`\n[${result.agent}${result.model ? ` ${result.model}` : ""} · session ${result.sessionId} · ${(result.durationMs / 1000).toFixed(1)}s]\n`);
 }
 const installedAgents = () => AGENTS.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) {
+    const path = settingsPath();
+    let current = DEFAULT_SETTINGS;
+    try {
+        current = loadSettings(path);
+    }
+    catch (err) {
+        if (!flag) {
+            process.stderr.write(`consult: ${errorMessage(err)}\n`);
+            return;
+        }
+    }
+    const mode = await chooseInstallMode({ flag, current: sessionsMode(current), interactive: isInteractive(), prompt: promptSessionsMode });
+    if (mode !== undefined)
+        saveSettings(path, withSessionsMode(current, mode));
+    process.stdout.write(`Live sessions: ${mode ?? sessionsMode(current)} (change with \`consult settings\`)\n`);
+}
 /** Prints one line per CLI and returns whether every step succeeded. */
 function report(results) {
     process.stdout.write(`${results.map((r) => r.message).join("\n")}\n`);
@@ -96,11 +147,31 @@ async function main(argv) {
             process.stdout.write(`${JSON.stringify(await listAgents(run), null, 2)}\n`);
             return;
         case "install": {
-            const script = realpathSync(fileURLToPath(import.meta.url));
-            const searchPath = process.env.PATH ?? "";
-            if (report(await install(run, serverCommand(script, searchPath), installedAgents()))) {
+            const { values } = parseArgs({ args: [...rest], options: { sessions: { type: "string" } } });
+            const flag = parseSessionsFlag(values.sessions);
+            if (report(await install(run, serverCommand(scriptPath(), searchPath()), installedAgents()))) {
+                await configureSessions(flag);
                 process.stdout.write("Restart running agent sessions to pick up the new tools.\n");
             }
+            else if (flag) {
+                process.stderr.write("consult: live sessions setting left unchanged because registration failed\n");
+            }
+            return;
+        }
+        case "settings": {
+            if (!isInteractive()) {
+                throw new Error("consult settings needs an interactive terminal; in scripts use `consult install --sessions=off|repo|machine`");
+            }
+            const cmd = serverCommand(scriptPath(), searchPath());
+            const path = settingsPath();
+            await runSettings({
+                load: () => loadSettings(path),
+                save: (settings) => saveSettings(path, settings),
+                installed: installedAgents(),
+                isRegistered: (agent) => isRegistered(run, agent),
+                register: (agents) => install(run, cmd, agents),
+                unregister: (agents) => uninstall(run, agents),
+            });
             return;
         }
         case "uninstall":

package/dist/codex-config.js

@@ -56,6 +56,10 @@ function withoutConsult(config) {
     return Object.keys(otherServers).length > 0 ? { ...rest, mcp_servers: otherServers } : rest;
 }
 const hasConsult = (config) => CODEX_SERVER in (config.mcp_servers ?? {});
+/** Whether the codex config has a consult entry. A missing file means not registered. */
+export function isCodexRegistered(path) {
+    return existsSync(path) && hasConsult(parseConfig(readFileSync(path, "utf8"), path));
+}
 function writeAtomically(path, text) {
     mkdirSync(dirname(path), { recursive: true });
     if (existsSync(path))

package/dist/consult.js

@@ -1,6 +1,6 @@
 import { statSync } from "node:fs";
-import { framePrompt } from "./prompt.js";
-import { AdvisorError } from "./types.js";
+import { frameForkPrompt, framePrompt } from "./prompt.js";
+import { AdvisorError, } from "./types.js";
 const STDERR_TAIL = 2000;
 function validate(request) {
     if (!request.question.trim())
@@ -26,13 +26,12 @@ function stoppedMessage(agent, reason, timeoutMs) {
     }
 }
 export function createConsult({ run, adapters, timeoutMs }) {
-    async function ask(request, signal) {
+    async function execute(adapter, request, invoke, signal) {
         validate(request);
-        const adapter = adapters[request.agent];
         const started = Date.now();
         // 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 = adapter.build(request, framePrompt(request.question, Boolean(request.sessionId)), extraArgs);
+        const invocation = invoke(extraArgs);
         const res = await run(invocation.command, invocation.args, { cwd: request.cwd, timeoutMs, signal });
         if (res.stopped)
             throw new AdvisorError(stoppedMessage(adapter.name, res.stopped, timeoutMs));
@@ -42,5 +41,16 @@ export function createConsult({ run, adapters, timeoutMs }) {
         }
         return { agent: adapter.name, ...adapter.parse(res.stdout), durationMs: Date.now() - started };
     }
-    return { ask };
+    async function ask(request, signal) {
+        const adapter = adapters[request.agent];
+        const prompt = framePrompt(request.question, Boolean(request.sessionId));
+        return execute(adapter, request, (extra) => adapter.build(request, prompt, extra), signal);
+    }
+    /** Asks a read-only fork of a live session. It runs in that session's directory, where its CLI can find it. */
+    async function askSession(target, question, effort, signal) {
+        const adapter = adapters[target.agent];
+        const request = { agent: target.agent, question, cwd: target.cwd, ...(effort ? { effort } : {}) };
+        return execute(adapter, request, (extra) => adapter.fork(target.sessionId, request, frameForkPrompt(question), extra), signal);
+    }
+    return { ask, askSession };
 }

package/dist/install.js

@@ -1,7 +1,7 @@
 import { accessSync, constants } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
-import { codexConfigPath, editConfig } from "./codex-config.js";
+import { codexConfigPath, editConfig, isCodexRegistered } from "./codex-config.js";
 import { AGENTS } from "./types.js";
 const SYSTEM_PATH = ["/usr/bin", "/bin", "/usr/sbin", "/sbin"];
 export const SERVER_NAME = "consult";
@@ -10,7 +10,7 @@ export const PACKAGE_NAME = "consult-mcp";
 export const CODEX_TOOL_TIMEOUT_SEC = 960;
 /** Codex's default 10s startup timeout is too short for npx fetching a new release. */
 export const CODEX_STARTUP_TIMEOUT_SEC = 60;
-export { codexConfigPath, removeTomlTable } from "./codex-config.js";
+export { codexConfigPath, isCodexRegistered, removeTomlTable } from "./codex-config.js";
 // Package-runner caches that get cleaned up, so a host must never be pointed at a script inside one.
 const NPX_CACHE = /[\\/]_npx[\\/]/;
 const OTHER_RUNNER_CACHE = /[\\/](bunx-[^\\/]*|dlx-[^\\/]*|\.pnpm-store|\.yarn[\\/]berry)[\\/]/;
@@ -84,6 +84,20 @@ async function unregisterFromCli(run, agent) {
     const res = await run(agent, ["mcp", "remove", SERVER_NAME, "-s", "user"], CLI_OPTS);
     return res.code === 0 ? `${agent}: removed` : `${agent}: not registered (${res.stderr.trim()})`;
 }
+const GROK_ENTRY = new RegExp(`^\\s*${SERVER_NAME}:`, "m");
+/** Whether consult is currently registered with this CLI. */
+export async function isRegistered(run, agent, codexPath = codexConfigPath()) {
+    switch (agent) {
+        case "claude":
+            return (await run("claude", ["mcp", "get", SERVER_NAME], CLI_OPTS)).code === 0;
+        case "grok": {
+            const res = await run("grok", ["mcp", "list"], CLI_OPTS);
+            return res.code === 0 && GROK_ENTRY.test(res.stdout);
+        }
+        case "codex":
+            return isCodexRegistered(codexPath);
+    }
+}
 /** Runs one step per installed CLI. One CLI failing does not stop the others. */
 async function forEachInstalled(installed, steps) {
     const results = [];

package/dist/prompt.js

@@ -11,3 +11,10 @@ export function framePrompt(question, isFollowUp) {
         ? `Follow-up from the consulting agent:\n\n${question}`
         : `${BRIEFING}\n\nQuestion from the consulting agent:\n\n${question}`;
 }
+const FORK_BRIEFING = `You are a read-only copy of this session, made so that another AI coding agent on this machine can ask you a question. The user is not here, and the original session carries on without you.
+Answer from what you know of this session and the files you can read. Do not continue or redo your earlier task, do not try to modify files or run commands that change state, and do not follow brainstorming, planning or approval workflows.
+Be concrete and concise, and cite files and lines when relevant.`;
+/** Builds the question sent to a fork of a live session. Like framePrompt, it starts with a letter. */
+export function frameForkPrompt(question) {
+    return `${FORK_BRIEFING}\n\nQuestion from the other agent:\n\n${question}`;
+}

package/dist/server.js

@@ -1,7 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { withProgress } from "./progress.js";
-import { AGENTS, EFFORTS } from "./types.js";
+import { registerSessionTools, SESSIONS_INSTRUCTIONS } from "./session-tools.js";
+import { AGENTS, EFFORTS, SESSION_ID_PATTERN } from "./types.js";
 import { VERSION } from "./version.js";
 const DEFAULT_PROGRESS_INTERVAL_MS = 10_000;
 // Hosts put this in the agent's context, so it is where the agent learns when consulting is worth a call.
@@ -55,8 +56,9 @@ function formatPanel(entries) {
     const sections = entries.map((e) => "result" in e ? `## ${e.agent}\n\n${e.result.answer}\n\n${footer(e.result)}` : `## ${e.agent}\n\nFailed: ${e.error}`);
     return `${sections.join("\n\n")}\n\n---\nPass an advisor's session_id to ask_agent for a follow-up.`;
 }
-export function createServer({ ask, listAgents, defaultCwd, progressIntervalMs = DEFAULT_PROGRESS_INTERVAL_MS, }) {
-    const server = new McpServer({ name: "consult", version: VERSION }, { instructions: INSTRUCTIONS });
+export function createServer({ ask, listAgents, defaultCwd, progressIntervalMs = DEFAULT_PROGRESS_INTERVAL_MS, sessions, }) {
+    const instructions = sessions ? `${INSTRUCTIONS}\n${SESSIONS_INSTRUCTIONS}` : INSTRUCTIONS;
+    const server = new McpServer({ name: "consult", version: VERSION }, { instructions });
     server.registerTool("ask_agent", {
         title: "Ask another agent",
         description: ASK_DESCRIPTION,
@@ -65,7 +67,7 @@ export function createServer({ ask, listAgents, defaultCwd, progressIntervalMs =
             question: questionSchema,
             model: z.string().optional().describe("Model for that CLI, e.g. gpt-6-astra, opus, grok-4.7. Omit for the CLI's default; list_agents shows options"),
             effort: effortSchema,
-            session_id: z.string().optional().describe("session_id from an earlier reply, to ask a follow-up"),
+            session_id: z.string().regex(SESSION_ID_PATTERN).optional().describe("session_id from an earlier reply, to ask a follow-up"),
             cwd: cwdSchema,
         },
         annotations: ADVISOR_HINTS,
@@ -129,5 +131,7 @@ export function createServer({ ask, listAgents, defaultCwd, progressIntervalMs =
         const agents = await listAgents();
         return { content: [{ type: "text", text: JSON.stringify(agents, null, 2) }], structuredContent: { agents } };
     });
+    if (sessions)
+        registerSessionTools(server, sessions, progressIntervalMs);
     return server;
 }

package/dist/session-tools.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { withProgress } from "./progress.js";
+import { EFFORTS, SESSION_ID_PATTERN } from "./types.js";
+export const SESSIONS_INSTRUCTIONS = `Live sessions are on. list_sessions shows other agent sessions running on this machine; ask_session asks a read-only copy of one of them, which knows that session's whole conversation.
+Ask one when another agent has context you need: it wrote the code you are changing, or it works on the other side of an interface you share. The original session is not interrupted and never sees your question.`;
+const LIST_DESCRIPTION = `List other AI coding agent sessions (Claude Code, Codex, Grok) running live on this machine that you can ask with ask_session: agent, session_id, directory, git branch, title, and when each started and was last active. Only sessions allowed by the user's live-sessions scope are shown.`;
+const ASK_DESCRIPTION = `Ask a question of a live session from list_sessions. consult forks that session into a read-only copy, so the answer draws on everything the session has seen and done; the original keeps working and never sees your question.
+The copy runs headless and read-only: it cannot edit files or change anything. It replays the session's conversation, so it can take longer than ask_agent. The reply includes the copy's session_id and cwd: pass both, with the same agent, to ask_agent for a follow-up.`;
+// Forks only read files; replies differ between calls and come from the session's model provider.
+const FORK_HINTS = { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+function footer(result) {
+    return [
+        `agent: ${result.agent}`,
+        ...(result.model ? [`model: ${result.model}`] : []),
+        `forked from: ${result.source}`,
+        `session_id: ${result.sessionId}`,
+        `cwd: ${result.cwd}`,
+        `${(result.durationMs / 1000).toFixed(1)}s`,
+    ].join(" · ");
+}
+export function registerSessionTools(server, deps, progressIntervalMs) {
+    server.registerTool("list_sessions", {
+        title: "List live sessions",
+        description: LIST_DESCRIPTION,
+        inputSchema: {},
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async () => {
+        try {
+            const sessions = deps.list();
+            const body = sessions.length > 0 ? JSON.stringify(sessions, null, 2) : "No other live sessions in scope.";
+            return { content: [{ type: "text", text: body }], structuredContent: { sessions } };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: "text", text: errorMessage(err) }] };
+        }
+    });
+    server.registerTool("ask_session", {
+        title: "Ask a live session",
+        description: ASK_DESCRIPTION,
+        inputSchema: {
+            session_id: z.string().regex(SESSION_ID_PATTERN).describe("session_id from list_sessions"),
+            question: z
+                .string()
+                .min(1)
+                .describe("The question. The copy knows its own session's conversation but not yours, so include what it needs to know about your side"),
+            effort: z.enum(EFFORTS).optional().describe("Reasoning effort. Omit for the CLI's default"),
+        },
+        annotations: FORK_HINTS,
+    }, async (args, extra) => {
+        try {
+            const work = deps.ask(args.session_id, args.question, args.effort, extra.signal);
+            const result = await withProgress(extra, progressIntervalMs, (s) => `asking a copy of ${args.session_id} (${s}s)`, work);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${result.answer}\n\n---\n${footer(result)}\nFor a follow-up, call ask_agent with this agent, session_id and cwd.`,
+                    },
+                ],
+                structuredContent: {
+                    agent: result.agent,
+                    answer: result.answer,
+                    session_id: result.sessionId,
+                    source_session_id: result.source,
+                    cwd: result.cwd,
+                    ...(result.model ? { model: result.model } : {}),
+                    duration_ms: result.durationMs,
+                },
+            };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: "text", text: errorMessage(err) }] };
+        }
+    });
+}

package/dist/sessions/describe.js

@@ -0,0 +1,72 @@
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { codexConfigPath } from "../codex-config.js";
+const TAIL_BYTES = 2 * 1024 * 1024;
+const MAX_TITLE = 120;
+export function codexIndexPath(env = process.env) {
+    return join(dirname(codexConfigPath(env)), "session_index.jsonl");
+}
+/** The last `bytes` of a file, without the partial line it may start in. */
+export function readTail(path, bytes = TAIL_BYTES) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        const size = fstatSync(fd).size;
+        const start = Math.max(0, size - bytes);
+        const buffer = Buffer.alloc(size - start);
+        readSync(fd, buffer, 0, buffer.length, start);
+        const text = buffer.toString("utf8");
+        return start === 0 ? text : text.slice(text.indexOf("\n") + 1);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** The string `pick` returns for the last JSON line that contains `needle` (checked before parsing, to stay cheap). */
+function lastMatch(text, needle, pick) {
+    const lines = text?.split("\n") ?? [];
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (!line.includes(needle))
+            continue;
+        try {
+            const value = pick(JSON.parse(line));
+            if (typeof value === "string" && value)
+                return value;
+        }
+        catch {
+            // Not JSON, or cut by the tail.
+        }
+    }
+    return undefined;
+}
+function mtime(path) {
+    try {
+        return statSync(path).mtime.toISOString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function title(entry, codexIndex) {
+    switch (entry.agent) {
+        case "claude":
+            return entry.transcriptPath
+                ? lastMatch(readTail(entry.transcriptPath), '"ai-title"', (row) => (row.type === "ai-title" ? row.aiTitle : undefined))
+                : undefined;
+        case "codex":
+            return lastMatch(readTail(codexIndex), entry.sessionId, (row) => (row.id === entry.sessionId ? row.thread_name : undefined));
+        case "grok":
+            return undefined;
+    }
+}
+/** The session's title and last activity, from the host's own files. Nothing else from the conversation is read. */
+export function describeSession(entry, codexIndex) {
+    const name = title(entry, codexIndex)?.slice(0, MAX_TITLE);
+    const lastActive = entry.transcriptPath ? mtime(entry.transcriptPath) : undefined;
+    return { ...(name ? { title: name } : {}), ...(lastActive ? { lastActive } : {}) };
+}

package/dist/sessions/identity.js

@@ -0,0 +1,125 @@
+import { existsSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { AGENTS, SESSION_ID_PATTERN } from "../types.js";
+const MAX_DEPTH = 6;
+const PROC_OPTS = { cwd: "/", timeoutMs: 5_000 };
+const PS_LINE = /^\s*(\d+)\s+(\S.*?)\s*$/;
+const SAFE_ID = SESSION_ID_PATTERN;
+const ROLLOUT = /\/sessions\/(?:.*\/)?rollout-[^/]*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
+const GROK_EVENTS = /\/\.grok\/sessions\/[^/]+\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/events\.jsonl$/;
+const isAgent = (name) => AGENTS.includes(name);
+/**
+ * The nearest agent CLI among this server's ancestors. An agent started from another agent's terminal inherits
+ * that agent's environment, so the process tree decides; CLAUDE_CODE_SESSION_ID is only a fallback for claude
+ * builds that run under a different process name.
+ */
+export async function detectHost(deps) {
+    const nearest = (await deps.ancestors()).find((p) => isAgent(p.name));
+    if (nearest)
+        return { agent: nearest.name, pid: nearest.pid };
+    return deps.env.CLAUDE_CODE_SESSION_ID ? { agent: "claude" } : undefined;
+}
+export async function currentSession(host, deps) {
+    switch (host.agent) {
+        case "claude": {
+            // CLAUDE_CODE_SESSION_ID is fixed when this server starts, so it goes stale after /resume or /clear.
+            // Claude Code's per-process record follows the conversation, so it wins when there is one.
+            const sessionId = (host.pid === undefined ? undefined : deps.claudeSessionOf(host.pid)) ?? deps.env.CLAUDE_CODE_SESSION_ID;
+            if (!sessionId || !SAFE_ID.test(sessionId))
+                return undefined;
+            // A fork resumes the saved conversation, so the session can only be asked once its transcript exists.
+            const transcriptPath = deps.claudeTranscript(sessionId);
+            return transcriptPath ? { sessionId, transcriptPath } : undefined;
+        }
+        case "codex": {
+            if (host.pid === undefined)
+                return undefined;
+            // Subagent threads open rollouts too. The main thread opened its rollout first, and the name starts
+            // with that timestamp, so it sorts first.
+            const rollouts = (await deps.openFiles(host.pid))
+                .filter((f) => ROLLOUT.test(f))
+                .sort((a, b) => basename(a).localeCompare(basename(b)));
+            const transcriptPath = rollouts[0];
+            const sessionId = transcriptPath ? ROLLOUT.exec(transcriptPath)?.[1] : undefined;
+            return transcriptPath && sessionId ? { sessionId, transcriptPath } : undefined;
+        }
+        case "grok": {
+            if (host.pid === undefined)
+                return undefined;
+            // An interactive grok holds ~/.grok/sessions/<encoded cwd>/<session id>/events.jsonl open.
+            // Several distinct ids (subagent, /new) are ambiguous, so refuse rather than risk advertising the wrong one.
+            const matches = (await deps.openFiles(host.pid)).flatMap((f) => {
+                const id = GROK_EVENTS.exec(f)?.[1];
+                return id ? [{ sessionId: id, transcriptPath: f }] : [];
+            });
+            const ids = new Set(matches.map((m) => m.sessionId));
+            return ids.size === 1 ? matches[0] : undefined;
+        }
+    }
+}
+function procFds(pid) {
+    try {
+        return readdirSync(`/proc/${pid}/fd`).flatMap((fd) => {
+            try {
+                return [readlinkSync(`/proc/${pid}/fd/${fd}`)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function systemIdentityDeps(run, env = process.env, platform = process.platform, startPid = process.ppid) {
+    const claudeDir = env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+    return {
+        env,
+        async ancestors() {
+            const chain = [];
+            for (let pid = startPid; pid > 1 && chain.length < MAX_DEPTH;) {
+                const res = await run("ps", ["-o", "ppid=,comm=", "-p", String(pid)], PROC_OPTS).catch(() => undefined);
+                const match = res?.code === 0 ? PS_LINE.exec(res.stdout) : null;
+                if (!match)
+                    break;
+                chain.push({ pid, name: basename(match[2].split(/\s+/)[0]) });
+                pid = Number(match[1]);
+            }
+            return chain;
+        },
+        async openFiles(pid) {
+            if (platform === "linux")
+                return procFds(pid);
+            const res = await run("lsof", ["-p", String(pid), "-Fn"], PROC_OPTS).catch(() => undefined);
+            return (res?.stdout ?? "")
+                .split("\n")
+                .filter((line) => line.startsWith("n"))
+                .map((line) => line.slice(1));
+        },
+        claudeSessionOf(pid) {
+            try {
+                const record = JSON.parse(readFileSync(join(claudeDir, "sessions", `${pid}.json`), "utf8"));
+                return record.pid === pid && typeof record.sessionId === "string" && SAFE_ID.test(record.sessionId)
+                    ? record.sessionId
+                    : undefined;
+            }
+            catch {
+                // No record (older Claude Code, or not a claude process) or one being rewritten: use the env var.
+                return undefined;
+            }
+        },
+        claudeTranscript(sessionId) {
+            const projects = join(claudeDir, "projects");
+            let dirs;
+            try {
+                dirs = readdirSync(projects);
+            }
+            catch {
+                return undefined;
+            }
+            return dirs.map((dir) => join(projects, dir, `${sessionId}.jsonl`)).find((path) => existsSync(path));
+        },
+    };
+}

package/dist/sessions/live.js

@@ -0,0 +1,54 @@
+import { currentSession, detectHost } from "./identity.js";
+import { removeEntry, writeEntry } from "./registry.js";
+import { gitBranch, repoKey } from "./scope.js";
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Registers the host session this server runs in, so other sessions can find it, and keeps the entry current:
+ * codex opens its rollout only after the first turn, `/new` starts a new thread, and the branch can change.
+ * The entry is removed when `signal` aborts. Readers prune the entries of servers that crash.
+ */
+export async function startLiveSession(opts) {
+    const key = await repoKey(opts.run, opts.cwd);
+    const startedAt = (opts.now ?? (() => new Date()))().toISOString();
+    const host = await detectHost(opts.identity);
+    let written;
+    async function refresh() {
+        if (!host || opts.signal.aborted)
+            return;
+        const [identity, branch] = await Promise.all([
+            currentSession(host, opts.identity).catch(() => undefined),
+            gitBranch(opts.run, opts.cwd),
+        ]);
+        if (!identity || opts.signal.aborted)
+            return;
+        const entry = {
+            version: 1,
+            pid: opts.pid,
+            agent: host.agent,
+            sessionId: identity.sessionId,
+            cwd: opts.cwd,
+            repoKey: key,
+            startedAt,
+            ...(branch ? { branch } : {}),
+            ...(identity.transcriptPath ? { transcriptPath: identity.transcriptPath } : {}),
+        };
+        if (written && JSON.stringify(written) === JSON.stringify(entry))
+            return;
+        writeEntry(opts.dir, entry);
+        written = entry;
+    }
+    const safeRefresh = () => refresh().catch((err) => opts.warn(`could not register this session: ${errorMessage(err)}`));
+    await safeRefresh();
+    const timer = setInterval(() => void safeRefresh(), opts.refreshMs);
+    timer.unref();
+    opts.signal.addEventListener("abort", () => {
+        clearInterval(timer);
+        try {
+            removeEntry(opts.dir, opts.pid);
+        }
+        catch (err) {
+            opts.warn(`could not remove this session's registry entry: ${errorMessage(err)}`);
+        }
+    }, { once: true });
+    return { self: () => ({ repoKey: key, ...(written ? { sessionId: written.sessionId } : {}) }) };
+}

package/dist/sessions/registry.js

@@ -0,0 +1,81 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { AGENTS, SESSION_ID_PATTERN } from "../types.js";
+const entrySchema = z.object({
+    version: z.literal(1),
+    /** The consult server's pid; it names the file and tells readers whether the entry is stale. */
+    pid: z.number().int().positive(),
+    agent: z.enum(AGENTS),
+    sessionId: z.string().regex(SESSION_ID_PATTERN),
+    cwd: z.string().min(1),
+    repoKey: z.string().min(1),
+    branch: z.string().optional(),
+    startedAt: z.string(),
+    transcriptPath: z.string().optional(),
+});
+const ENTRY_FILE = /^(\d+)\.json$/;
+/** `$XDG_STATE_HOME/consult/sessions`, else `~/.local/state/consult/sessions`. */
+export function registryDir(env = process.env) {
+    return join(env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "consult", "sessions");
+}
+const fileFor = (dir, pid) => join(dir, `${pid}.json`);
+export function writeEntry(dir, entry) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = join(dir, `.${entry.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(entrySchema.parse(entry)), { mode: 0o600 });
+    renameSync(tmp, fileFor(dir, entry.pid));
+}
+export function removeEntry(dir, pid) {
+    rmSync(fileFor(dir, pid), { force: true });
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: the process exists but belongs to someone else.
+        return err.code === "EPERM";
+    }
+}
+function readEntry(path) {
+    try {
+        const parsed = entrySchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Entries of running consult servers, newest first and one per session. Files left by servers that died are
+ * deleted; unreadable files of live servers are skipped, since they may be mid-write.
+ */
+export function listLive(dir, isAlive = pidAlive) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const bySession = new Map();
+    for (const name of names) {
+        const pid = Number(ENTRY_FILE.exec(name)?.[1]);
+        if (!pid)
+            continue;
+        if (!isAlive(pid)) {
+            removeEntry(dir, pid);
+            continue;
+        }
+        const entry = readEntry(join(dir, name));
+        if (!entry || entry.pid !== pid)
+            continue;
+        const seen = bySession.get(entry.sessionId);
+        if (!seen || seen.startedAt < entry.startedAt)
+            bySession.set(entry.sessionId, entry);
+    }
+    return [...bySession.values()].sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}

package/dist/sessions/scope.js

@@ -0,0 +1,27 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+const GIT_TIMEOUT_MS = 5_000;
+const real = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+};
+async function git(run, cwd, args) {
+    const res = await run("git", args, { cwd, timeoutMs: GIT_TIMEOUT_MS }).catch(() => undefined);
+    return res?.code === 0 ? res.stdout.trim() : "";
+}
+/** Identifies a repository by its git common dir, which all its worktrees share. Outside git: the directory. */
+export async function repoKey(run, cwd) {
+    const commonDir = await git(run, cwd, ["rev-parse", "--git-common-dir"]);
+    return real(commonDir ? resolve(cwd, commonDir) : resolve(cwd));
+}
+export async function gitBranch(run, cwd) {
+    const branch = await git(run, cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    return branch && branch !== "HEAD" ? branch : undefined;
+}
+export function inScope(self, other, scope) {
+    return scope === "machine" || self.repoKey === other.repoKey;
+}

package/dist/sessions/service.js

@@ -0,0 +1,43 @@
+import { AdvisorError } from "../types.js";
+import { inScope } from "./scope.js";
+/** A live session is the user's own: resuming it in place would write its transcript. */
+export function assertNotLiveSession(sessionId, live) {
+    if (live.some((e) => e.sessionId === sessionId)) {
+        throw new AdvisorError(`session ${sessionId} is a live session; use ask_session to ask a read-only copy of it`);
+    }
+}
+const MAX_BRANCH = 120;
+function toView(entry, details) {
+    return {
+        session_id: entry.sessionId,
+        agent: entry.agent,
+        cwd: entry.cwd,
+        ...(entry.branch ? { branch: entry.branch.slice(0, MAX_BRANCH) } : {}),
+        ...(details.title ? { title: details.title } : {}),
+        started_at: entry.startedAt,
+        ...(details.lastActive ? { last_active: details.lastActive } : {}),
+    };
+}
+export function createSessions(deps) {
+    function visible(self) {
+        const { sessions } = deps.settings();
+        if (!sessions.enabled)
+            throw new AdvisorError("live sessions are turned off; run `consult settings` to turn them on");
+        return deps.listLive().filter((e) => e.sessionId !== self.sessionId && inScope(self, e, sessions.scope));
+    }
+    function list() {
+        return visible(deps.self()).map((entry) => toView(entry, deps.describe(entry)));
+    }
+    async function ask(sessionId, question, effort, signal) {
+        const self = deps.self();
+        const target = visible(self).find((e) => e.sessionId === sessionId);
+        if (!target) {
+            throw new AdvisorError(sessionId === self.sessionId
+                ? "that is your own session; ask a different one"
+                : `no live session ${sessionId} in scope; call list_sessions to see the current ones`);
+        }
+        const result = await deps.askFork({ agent: target.agent, sessionId: target.sessionId, cwd: target.cwd }, question, effort, signal);
+        return { ...result, cwd: target.cwd, source: target.sessionId };
+    }
+    return { list, ask };
+}

package/dist/sessions/wire.js

@@ -0,0 +1,50 @@
+import { loadSettings, settingsPath } from "../settings.js";
+import { codexIndexPath, describeSession } from "./describe.js";
+import { systemIdentityDeps } from "./identity.js";
+import { startLiveSession } from "./live.js";
+import { listLive, registryDir } from "./registry.js";
+import { createSessions } from "./service.js";
+const REFRESH_MS = 15_000;
+/**
+ * For `consult serve`: registers this session and returns the session tools when live sessions are on.
+ * Without valid settings it returns nothing, so the rest of consult works as before.
+ */
+export async function sessionTools(opts) {
+    const path = settingsPath(opts.env);
+    let settings;
+    try {
+        settings = loadSettings(path);
+    }
+    catch (err) {
+        opts.warn(`${err instanceof Error ? err.message : String(err)}; live sessions are off for this session`);
+        return undefined;
+    }
+    if (!settings.sessions.enabled)
+        return undefined;
+    try {
+        const dir = registryDir(opts.env);
+        const codexIndex = codexIndexPath(opts.env);
+        const live = await startLiveSession({
+            run: opts.run,
+            dir,
+            cwd: opts.cwd,
+            pid: opts.pid,
+            identity: opts.identity ?? systemIdentityDeps(opts.run, opts.env),
+            refreshMs: opts.refreshMs ?? REFRESH_MS,
+            signal: opts.signal,
+            warn: opts.warn,
+        });
+        const { list, ask } = createSessions({
+            self: live.self,
+            settings: () => loadSettings(path),
+            listLive: () => listLive(dir),
+            describe: (entry) => describeSession(entry, codexIndex),
+            askFork: opts.askFork,
+        });
+        return { list, ask };
+    }
+    catch (err) {
+        opts.warn(`could not start live sessions: ${err instanceof Error ? err.message : String(err)}; live sessions are off for this session`);
+        return undefined;
+    }
+}

package/dist/settings.js

@@ -0,0 +1,58 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+export const SESSIONS_MODES = ["off", "repo", "machine"];
+const schema = z.object({
+    version: z.literal(1),
+    sessions: z.object({ enabled: z.boolean(), scope: z.enum(["repo", "machine"]) }),
+});
+/** Live sessions stay off until the user turns them on. */
+export const DEFAULT_SETTINGS = { version: 1, sessions: { enabled: false, scope: "repo" } };
+export class SettingsError extends Error {
+    name = "SettingsError";
+}
+/** `$XDG_CONFIG_HOME/consult/settings.json`, else `~/.config/consult/settings.json`. */
+export function settingsPath(env = process.env) {
+    return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "consult", "settings.json");
+}
+/** Returns the defaults when the file does not exist; throws SettingsError when it exists but is not valid. */
+export function loadSettings(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return DEFAULT_SETTINGS;
+        throw new SettingsError(`could not read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new SettingsError(`${path} is not valid JSON; run \`consult settings\` to reset it`);
+    }
+    const parsed = schema.safeParse(json);
+    if (!parsed.success) {
+        const reason = parsed.error.issues[0]?.message ?? "unknown problem";
+        throw new SettingsError(`${path} has invalid settings (${reason}); run \`consult settings\` to reset it`);
+    }
+    return parsed.data;
+}
+export function saveSettings(path, settings) {
+    const valid = schema.parse(settings);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(valid, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+export const sessionsMode = (settings) => settings.sessions.enabled ? settings.sessions.scope : "off";
+/** Turning sessions off keeps the scope, so turning them back on restores it. */
+export function withSessionsMode(settings, mode) {
+    return {
+        ...settings,
+        sessions: mode === "off" ? { ...settings.sessions, enabled: false } : { enabled: true, scope: mode },
+    };
+}

package/dist/tui.js

@@ -0,0 +1,79 @@
+import { cancel, confirm, intro, isCancel, log, multiselect, outro, select } from "@clack/prompts";
+import { DEFAULT_SETTINGS, SESSIONS_MODES, sessionsMode, withSessionsMode, } from "./settings.js";
+const MODE_OPTIONS = [
+    { value: "off", label: "Off", hint: "default: agents can't see each other's sessions" },
+    { value: "repo", label: "Same repo", hint: "sessions in the same git repository and its worktrees" },
+    { value: "machine", label: "Whole machine", hint: "every consult session you run" },
+];
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+export function parseSessionsFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (!SESSIONS_MODES.includes(value)) {
+        throw new Error(`--sessions must be one of ${SESSIONS_MODES.join(", ")}`);
+    }
+    return value;
+}
+export const isInteractive = (stdin = process.stdin, stdout = process.stdout) => Boolean(stdin.isTTY && stdout.isTTY);
+/** The flag wins; otherwise ask, but only in a terminal. Undefined means leave the setting as it is. */
+export async function chooseInstallMode(opts) {
+    if (opts.flag)
+        return opts.flag;
+    return opts.interactive ? opts.prompt(opts.current) : undefined;
+}
+export function planSettings(current, registered, chosen) {
+    return {
+        settings: withSessionsMode(current, chosen.mode),
+        register: chosen.hosts.filter((agent) => !registered.includes(agent)),
+        unregister: registered.filter((agent) => !chosen.hosts.includes(agent)),
+    };
+}
+/** Asks for the live-sessions mode. Undefined when the user cancels. */
+export async function promptSessionsMode(current) {
+    const mode = await select({
+        message: "Live sessions: let agents see and ask each other's running sessions?",
+        options: [...MODE_OPTIONS],
+        initialValue: current,
+    });
+    return isCancel(mode) ? undefined : mode;
+}
+async function loadOrReset(io) {
+    try {
+        return io.load();
+    }
+    catch (err) {
+        log.warn(errorMessage(err));
+        const reset = await confirm({ message: "Reset settings to the defaults?", initialValue: true });
+        return !isCancel(reset) && reset ? DEFAULT_SETTINGS : undefined;
+    }
+}
+export async function runSettings(io) {
+    intro("consult settings");
+    const current = await loadOrReset(io);
+    if (!current)
+        return cancel("Left settings unchanged.");
+    const registered = (await Promise.all(io.installed.map(async (agent) => ((await io.isRegistered(agent)) ? [agent] : [])))).flat();
+    const mode = await promptSessionsMode(sessionsMode(current));
+    if (mode === undefined)
+        return cancel("No changes made.");
+    const hosts = io.installed.length === 0
+        ? []
+        : await multiselect({
+            message: "Use consult in",
+            options: io.installed.map((agent) => ({ value: agent, label: agent })),
+            initialValues: [...registered],
+            required: false,
+        });
+    if (isCancel(hosts))
+        return cancel("No changes made.");
+    const plan = planSettings(current, registered, { mode, hosts });
+    io.save(plan.settings);
+    const changed = [...plan.register, ...plan.unregister];
+    const results = [
+        ...(plan.register.length > 0 ? await io.register(plan.register) : []),
+        ...(plan.unregister.length > 0 ? await io.unregister(plan.unregister) : []),
+    ].filter((r) => changed.includes(r.agent));
+    for (const r of results)
+        (r.ok ? log.success : log.error)(r.message);
+    outro(`Live sessions: ${mode}. Restart running agent sessions to apply.`);
+}

package/dist/types.js

@@ -1,4 +1,6 @@
 export const AGENTS = ["claude", "codex", "grok"];
+/** Session ids reach CLI argv after `--resume`; a leading `-` could be parsed as a flag. */
+export const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
 export const EFFORTS = ["low", "medium", "high"];
 export class AdvisorError extends Error {
     name = "AdvisorError";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "consult-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "MCP server that lets Claude Code, Codex and Grok ask each other for a second opinion through the CLIs already signed in on your machine",
   "keywords": [
     "mcp",
@@ -46,6 +46,7 @@
     "linux"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.8.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "smol-toml": "^1.9.0",
     "zod": "^4.6.5"