consult-mcp 0.3.1 → 0.4.1

package/README.md

@@ -4,7 +4,7 @@
 
 consult is an MCP server that lets Claude Code, Codex and Grok ask each other 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.
+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.
 
 [consult.n3el.dev](https://consult.n3el.dev) · [npm](https://www.npmjs.com/package/consult-mcp)
 
@@ -54,6 +54,8 @@ To pin to a specific build instead of following `@latest`, install globally with
 
 **`list_sessions`** and **`ask_session`** `{session_id, question, effort?}` appear when [live sessions](#live-sessions) are on.
 
+**`dispatch_task`**, **`task_status`** and **`cancel_task`** appear when [task dispatch](#task-dispatch) is 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
@@ -78,7 +80,7 @@ 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
+npx -y consult-mcp@latest settings                  # interactive: live sessions, task dispatch, and which agents use consult
 ```
 
 | Setting | Who can see and ask whom |
@@ -95,6 +97,18 @@ Settings are stored in `$XDG_CONFIG_HOME/consult/settings.json` (default `~/.con
 | 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 |
 
+## Task dispatch
+
+Off by default. When on, an agent can hand a well-defined coding task to a Codex or Grok worker, keep working, and check in on it. For example, Claude Code can have Codex write the tests for a module while it builds the next one.
+
+- **`dispatch_task`** `{agent, task, model?, effort?, cwd?}` starts the worker in the background and returns a `task_id` at once. `agent` is `codex` or `grok`. The worker runs headless in `cwd` (default: the host's directory) and can edit files and run commands there. It can't see the host's conversation or ask questions, so the task must be self-contained.
+- **`task_status`** `{task_id?, wait_sec?, since?}` returns the task's state (`running`, `succeeded`, `failed`, `cancelled`), its latest updates (commands run, files edited, messages), and the worker's final report once it finishes. `wait_sec` (up to 600) waits for the task to finish, sending each update as an MCP progress notification as it happens. `since` returns only updates after the `last_seq` of an earlier call (the server keeps the last 200; `earlier_updates_dropped` says when you missed some). Without `task_id` it lists all tasks.
+- **`cancel_task`** `{task_id}` stops the worker. Files it already changed stay changed.
+
+Tasks live in the consult server's memory: they end with the agent session that started them, and the server stops any still running when it exits. `CONSULT_TASK_TIMEOUT_SEC` (default 3600) caps each task. The report includes the worker's `session_id`; pass it to `ask_agent` with the same agent to ask a read-only follow-up about the work.
+
+Turn it on with `npx -y consult-mcp@latest settings`; it applies to agent sessions started afterwards. Workers change files, so review their diff before building on it, and don't point two workers at the same files.
+
 ## 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.
@@ -111,6 +125,15 @@ consult doesn't use Grok's kernel sandbox (`--sandbox read-only`), because it re
 
 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.
 
+[Task dispatch](#task-dispatch) workers are the one exception to read-only, and only when you turn it on. They stay headless and have no MCP servers, so they can't call consult either:
+
+| CLI | Worker flags |
+| --- | --- |
+| codex | `exec`, `sandbox_mode="workspace-write"` with `network_access=false` and `writable_roots=[]` (writes confined to the cwd and temp dirs, no network), `approval_policy="never"`, plugins off, and every enabled MCP server disabled by name |
+| grok | `--tools read_file,grep,list_dir,search_replace,write_file,run_terminal_cmd --always-approve --disallowed-tools Agent,search_tool,use_tool`. Without Grok's kernel sandbox (see above), its shell commands run unconfined as your user, with network access. Its shell could even start another agent CLI, so for grok "no MCP servers" stops loops through consult but is not a hard boundary |
+
+Their first message tells them another agent dispatched them, to finish the task without asking questions, to stay within the task and the directory, and not to commit or push unless the task says so.
+
 Advisors send what they read to their own provider. [SECURITY.md](SECURITY.md) covers read scope and the threat model.
 
 ## CLI
@@ -120,11 +143,14 @@ The same calls are available from the shell, which is handy for debugging:
 ```bash
 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 agents
-consult settings                      # live sessions, and which agents use consult
+consult settings                      # live sessions, task dispatch, 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.
+Use `npx -y consult-mcp@latest <command>` if it isn't installed globally. Advisors are read-only here too: the same containment flags apply, so there is no need to tell them not to edit files. While one works, `consult ask` prints timestamped progress to stderr (commands run and messages for codex and grok, a heartbeat after 30 quiet seconds for any agent) and only the answer to stdout.
+
+`CONSULT_TIMEOUT_SEC` (default 900) caps each advisor call; raise it for long grok runs on large questions. `CONSULT_TASK_TIMEOUT_SEC` (default 3600) caps each dispatched task.
 
 ## Development
 

package/dist/adapters/codex.js

@@ -1,9 +1,18 @@
 import { AdvisorError } from "../types.js";
 import { parseJsonLines } from "../jsonl.js";
+import { unwrapShell } from "../narrate.js";
 const PLUGINS_OFF = ["-c", "features.plugins=false"];
-// Codex runs MCP tools outside its shell sandbox, so the advisor gets none: plugins are switched off
+const READ_ONLY = ["-c", 'sandbox_mode="read-only"'];
+// Workers may edit files under the cwd (and temp dirs) and run commands there, without network access. Extra
+// writable roots from the user's config are dropped.
+const WORKSPACE_WRITE = [
+    "-c", 'sandbox_mode="workspace-write"',
+    "-c", "sandbox_workspace_write.network_access=false",
+    "-c", "sandbox_workspace_write.writable_roots=[]",
+];
+// Codex runs MCP tools outside its shell sandbox, so advisors and workers get none: plugins are switched off
 // (they bring their own MCP servers) and every server still enabled is disabled by name.
-// That includes consult itself, which is what stops advisors from consulting each other in a loop.
+// That includes consult itself, which is what stops agents from consulting each other in a loop.
 async function listEnabledMcpServers(run, cwd, signal) {
     const res = await run("codex", ["mcp", "list", "--json", ...PLUGINS_OFF], { cwd, timeoutMs: 30_000, signal });
     if (res.code !== 0) {
@@ -12,49 +21,80 @@ 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) {
+const prepare = async (run, cwd, signal) => {
+    const names = await listEnabledMcpServers(run, cwd, signal);
+    return [...PLUGINS_OFF, ...names.flatMap((n) => ["-c", `mcp_servers.${n}.enabled=false`])];
+};
+function configArgs(sandbox, request, extraArgs) {
     return [
-        "-c", 'sandbox_mode="read-only"',
+        ...sandbox,
         "-c", 'approval_policy="never"',
         ...(request.model ? ["-c", `model=${JSON.stringify(request.model)}`] : []),
         ...(request.effort ? ["-c", `model_reasoning_effort="${request.effort}"`] : []),
         ...extraArgs,
     ];
 }
+function parse(stdout) {
+    const events = parseJsonLines(stdout);
+    const failure = events.find((e) => e.type === "turn.failed" || e.type === "error");
+    if (failure) {
+        const message = failure.error?.message ?? failure.message;
+        throw new AdvisorError(`codex reported an error: ${String(message ?? "unknown error")}`);
+    }
+    const threadId = events.find((e) => e.type === "thread.started")?.thread_id;
+    const answer = events
+        .filter((e) => e.type === "item.completed")
+        .map((e) => e.item)
+        .filter((item) => item.type === "agent_message" && item.text)
+        .at(-1)?.text;
+    if (!answer || typeof threadId !== "string")
+        throw new AdvisorError("codex returned no answer");
+    return { answer, sessionId: threadId };
+}
+function describe(event) {
+    const item = event.item;
+    if (!item)
+        return undefined;
+    if (event.type === "item.started" && item.type === "command_execution" && item.command)
+        return `$ ${unwrapShell(item.command)}`;
+    if (event.type !== "item.completed")
+        return undefined;
+    switch (item.type) {
+        case "command_execution":
+            return item.exit_code && item.command ? `exit ${item.exit_code}: ${unwrapShell(item.command)}` : undefined;
+        case "file_change":
+            return item.changes?.map((c) => `${c.kind ?? "edit"} ${c.path ?? "?"}`).join(", ");
+        case "agent_message":
+            return item.text;
+        default:
+            return undefined;
+    }
+}
 export const codex = {
     name: "codex",
     command: "codex",
-    async prepare(run, cwd, signal) {
-        const names = await listEnabledMcpServers(run, cwd, signal);
-        return [...PLUGINS_OFF, ...names.flatMap((n) => ["-c", `mcp_servers.${n}.enabled=false`])];
-    },
+    prepare,
     build(request, prompt, 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", ...configArgs(request, extraArgs), ...tail] };
+        return { command: "codex", args: [...head, "--skip-git-repo-check", ...configArgs(READ_ONLY, 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],
+            args: ["exec", "fork", "--json", "--skip-git-repo-check", ...configArgs(READ_ONLY, request, extraArgs), sourceSessionId, prompt],
         };
     },
-    parse(stdout) {
-        const events = parseJsonLines(stdout);
-        const failure = events.find((e) => e.type === "turn.failed" || e.type === "error");
-        if (failure) {
-            const message = failure.error?.message ?? failure.message;
-            throw new AdvisorError(`codex reported an error: ${String(message ?? "unknown error")}`);
-        }
-        const threadId = events.find((e) => e.type === "thread.started")?.thread_id;
-        const answer = events
-            .filter((e) => e.type === "item.completed")
-            .map((e) => e.item)
-            .filter((item) => item.type === "agent_message" && item.text)
-            .at(-1)?.text;
-        if (!answer || typeof threadId !== "string")
-            throw new AdvisorError("codex returned no answer");
-        return { answer, sessionId: threadId };
+    parse,
+    describe,
+};
+export const codexWorker = {
+    name: "codex",
+    prepare,
+    build(request, prompt, extraArgs) {
+        return { command: "codex", args: ["exec", "--json", "--skip-git-repo-check", ...configArgs(WORKSPACE_WRITE, request, extraArgs), prompt] };
     },
+    describe,
+    parse,
 };

package/dist/adapters/grok.js

@@ -1,43 +1,78 @@
 import { randomUUID } from "node:crypto";
 import { AdvisorError } from "../types.js";
 import { parseJsonLines } from "../jsonl.js";
+import { unwrapShell } from "../narrate.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) {
+const ADVISOR_TOOLS = ["--tools", "read_file,grep,list_dir"];
+const NO_MCP = ["--disallowed-tools", "Agent,search_tool,use_tool"];
+// Workers also edit files and run shell commands, approved up front because nobody is there to approve.
+// Without the kernel sandbox (see above), those commands are not confined to the cwd.
+const WORKER_TOOLS = ["--tools", "read_file,grep,list_dir,search_replace,write_file,run_terminal_cmd", "--always-approve"];
+function invocation(tools, 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",
+            ...tools,
+            ...NO_MCP,
             ...session,
             ...(request.model ? ["--model", request.model] : []),
             ...(request.effort ? ["--reasoning-effort", request.effort] : []),
         ],
     };
 }
+function parse(stdout) {
+    const events = parseJsonLines(stdout);
+    const result = events.findLast((e) => e.type === "result");
+    if (!result)
+        throw new AdvisorError(`grok returned no result: ${stdout.slice(0, 500)}`);
+    if (result.is_error)
+        throw new AdvisorError(`grok reported an error: ${String(result.result ?? "unknown error")}`);
+    const model = events.find((e) => e.type === "system")?.model;
+    if (typeof result.result !== "string" || !result.result || typeof result.session_id !== "string") {
+        throw new AdvisorError("grok returned no answer");
+    }
+    return { answer: result.result, sessionId: result.session_id, ...(typeof model === "string" ? { model } : {}) };
+}
+function describeTool(name, input = {}) {
+    if (name === "run_terminal_cmd" && typeof input.command === "string")
+        return `$ ${unwrapShell(input.command)}`;
+    const target = Object.values(input).find((v) => typeof v === "string");
+    return target ? `${name} ${target}` : name;
+}
+function describe(event) {
+    if (event.type !== "assistant")
+        return undefined;
+    const content = event.message?.content ?? [];
+    const parts = content.flatMap((block) => {
+        if (block.type === "text" && block.text?.trim())
+            return [block.text];
+        if (block.type === "tool_use" && block.name)
+            return [describeTool(block.name, block.input)];
+        return [];
+    });
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
 export const grok = {
     name: "grok",
     command: "grok",
     build(request, prompt) {
-        return invocation(request, prompt, request.sessionId ? ["--resume", request.sessionId] : ["--session-id", randomUUID()]);
+        return invocation(ADVISOR_TOOLS, request, prompt, request.sessionId ? ["--resume", request.sessionId] : ["--session-id", randomUUID()]);
     },
     fork(sourceSessionId, request, prompt) {
-        return invocation(request, prompt, ["--resume", sourceSessionId, "--fork-session"]);
+        return invocation(ADVISOR_TOOLS, request, prompt, ["--resume", sourceSessionId, "--fork-session"]);
     },
-    parse(stdout) {
-        const events = parseJsonLines(stdout);
-        const result = events.findLast((e) => e.type === "result");
-        if (!result)
-            throw new AdvisorError(`grok returned no result: ${stdout.slice(0, 500)}`);
-        if (result.is_error)
-            throw new AdvisorError(`grok reported an error: ${String(result.result ?? "unknown error")}`);
-        const model = events.find((e) => e.type === "system")?.model;
-        if (typeof result.result !== "string" || !result.result || typeof result.session_id !== "string") {
-            throw new AdvisorError("grok returned no answer");
-        }
-        return { answer: result.result, sessionId: result.session_id, ...(typeof model === "string" ? { model } : {}) };
+    parse,
+    describe,
+};
+export const grokWorker = {
+    name: "grok",
+    build(request, prompt) {
+        return invocation(WORKER_TOOLS, request, prompt, ["--session-id", randomUUID()]);
     },
+    describe,
+    parse,
 };

package/dist/cli.js

@@ -4,10 +4,11 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { claude } from "./adapters/claude.js";
-import { codex } from "./adapters/codex.js";
-import { grok } from "./adapters/grok.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 { findOnPath, install, isRegistered, serverCommand, uninstall } from "./install.js";
 import { DEFAULT_SETTINGS, loadSettings, saveSettings, sessionsMode, settingsPath, withSessionsMode } from "./settings.js";
 import { run } from "./run.js";
@@ -15,36 +16,53 @@ import { createServer } from "./server.js";
 import { listLive, registryDir } from "./sessions/registry.js";
 import { assertNotLiveSession } from "./sessions/service.js";
 import { sessionTools } from "./sessions/wire.js";
+import { createTaskManager } from "./tasks.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 DEFAULT_TASK_TIMEOUT_SEC = 3600;
+const HEARTBEAT_MS = 30_000;
 const USAGE = `consult ${VERSION} - let coding agents ask each other for advice
 
   consult serve                          run the MCP server (stdio)
   consult ask <agent> [options] <question...>
+                                         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 agents                         list installed CLIs and models
   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)
+  consult settings                       live sessions, task dispatch, and which agents use consult (interactive)
 
-agents: ${AGENTS.join(", ")}    timeout: CONSULT_TIMEOUT_SEC (default ${DEFAULT_TIMEOUT_SEC})`;
-function timeoutMs() {
-    const raw = process.env.CONSULT_TIMEOUT_SEC;
-    const sec = raw ? Number(raw) : DEFAULT_TIMEOUT_SEC;
+agents: ${AGENTS.join(", ")}
+timeouts: CONSULT_TIMEOUT_SEC per advisor call (default ${DEFAULT_TIMEOUT_SEC}; raise it for long grok runs),
+          CONSULT_TASK_TIMEOUT_SEC per task (default ${DEFAULT_TASK_TIMEOUT_SEC})`;
+function secondsFromEnv(name, defaultSec) {
+    const raw = process.env[name];
+    const sec = raw ? Number(raw) : defaultSec;
     if (!Number.isFinite(sec) || sec <= 0)
-        throw new Error(`CONSULT_TIMEOUT_SEC must be a positive number, got ${raw}`);
+        throw new Error(`${name} must be a positive number, got ${raw}`);
     return sec * 1000;
 }
+const timeoutMs = () => secondsFromEnv("CONSULT_TIMEOUT_SEC", DEFAULT_TIMEOUT_SEC);
+/** Invalid settings mean off; sessionTools already warns about them. */
+function tasksEnabled() {
+    try {
+        return loadSettings(settingsPath()).tasks.enabled;
+    }
+    catch {
+        return false;
+    }
+}
 /** 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
+// Advisors and workers 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();
@@ -59,6 +77,14 @@ async function serve() {
         askFork: (target, question, effort, signal) => askSession(target, question, effort, withShutdown(signal)),
         warn: (message) => process.stderr.write(`consult: ${message}\n`),
     });
+    const tasks = tasksEnabled()
+        ? createTaskManager({
+            run,
+            workers: { codex: codexWorker, grok: grokWorker },
+            timeoutMs: secondsFromEnv("CONSULT_TASK_TIMEOUT_SEC", DEFAULT_TASK_TIMEOUT_SEC),
+            signal: shutdown.signal,
+        })
+        : undefined;
     const server = createServer({
         ask: (request, signal) => {
             refuseLive(request.sessionId);
@@ -67,6 +93,7 @@ async function serve() {
         listAgents: () => listAgents(run),
         defaultCwd: process.cwd(),
         ...(sessions ? { sessions } : {}),
+        ...(tasks ? { tasks } : {}),
     });
     const transport = new StdioServerTransport();
     transport.onclose = () => shutdown.abort();
@@ -80,6 +107,12 @@ async function serve() {
     }
     await server.connect(transport);
 }
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
 async function askCommand(argv) {
     const { values, positionals } = parseArgs({
         args: [...argv],
@@ -95,14 +128,23 @@ async function askCommand(argv) {
         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(" "),
-        cwd: values.cwd ?? process.cwd(),
-        model: values.model,
-        effort: values.effort,
-        sessionId: values.resume,
-    });
+    const question = words.length === 1 && words[0] === "-" ? await readStdin() : words.join(" ");
+    const progress = progressLog((line) => process.stderr.write(line), `${agent} is still working`, HEARTBEAT_MS);
+    progress.update(`asking ${agent} (read-only)`);
+    let result;
+    try {
+        result = await consult().ask({
+            agent: agent,
+            question,
+            cwd: values.cwd ?? process.cwd(),
+            model: values.model,
+            effort: values.effort,
+            sessionId: values.resume,
+        }, undefined, progress.update);
+    }
+    finally {
+        progress.stop();
+    }
     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`);
 }

package/dist/consult.js

@@ -1,19 +1,23 @@
 import { statSync } from "node:fs";
+import { describeLine } from "./narrate.js";
 import { frameForkPrompt, framePrompt } from "./prompt.js";
 import { AdvisorError, } from "./types.js";
 const STDERR_TAIL = 2000;
-function validate(request) {
-    if (!request.question.trim())
-        throw new AdvisorError("question must not be empty");
+export function assertDirectory(cwd) {
     let isDir = false;
     try {
-        isDir = statSync(request.cwd).isDirectory();
+        isDir = statSync(cwd).isDirectory();
     }
     catch {
         // Reported below.
     }
     if (!isDir)
-        throw new AdvisorError(`cwd is not a directory: ${request.cwd}`);
+        throw new AdvisorError(`cwd is not a directory: ${cwd}`);
+}
+function validate(request) {
+    if (!request.question.trim())
+        throw new AdvisorError("question must not be empty");
+    assertDirectory(request.cwd);
 }
 function stoppedMessage(agent, reason, timeoutMs) {
     switch (reason) {
@@ -25,26 +29,42 @@ function stoppedMessage(agent, reason, timeoutMs) {
             return `${agent} produced too much output and was stopped`;
     }
 }
+/** Throws when the CLI was stopped or exited non-zero. */
+export function assertExitedCleanly(agent, res, timeoutMs) {
+    if (res.stopped)
+        throw new AdvisorError(stoppedMessage(agent, res.stopped, timeoutMs));
+    if (res.code !== 0) {
+        const detail = (res.stderr.trim() || res.stdout.trim()).slice(-STDERR_TAIL);
+        throw new AdvisorError(`${agent} exited with code ${res.code}: ${detail}`);
+    }
+}
 export function createConsult({ run, adapters, timeoutMs }) {
-    async function execute(adapter, request, invoke, signal) {
+    async function execute(adapter, request, invoke, signal, onUpdate) {
         validate(request);
         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 = 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));
-        if (res.code !== 0) {
-            const detail = (res.stderr.trim() || res.stdout.trim()).slice(-STDERR_TAIL);
-            throw new AdvisorError(`${adapter.name} exited with code ${res.code}: ${detail}`);
-        }
-        return { agent: adapter.name, ...adapter.parse(res.stdout), durationMs: Date.now() - started };
+        const { describe } = adapter;
+        const lines = [];
+        const onStdoutLine = onUpdate && describe
+            ? (line) => {
+                lines.push(line);
+                const text = describeLine(describe, line);
+                if (text)
+                    onUpdate(text);
+            }
+            : undefined;
+        const res = await run(invocation.command, invocation.args, { cwd: request.cwd, timeoutMs, signal, onStdoutLine });
+        const stdout = onStdoutLine ? lines.join("\n") : res.stdout;
+        assertExitedCleanly(adapter.name, { ...res, stdout }, timeoutMs);
+        return { agent: adapter.name, ...adapter.parse(stdout), durationMs: Date.now() - started };
     }
-    async function ask(request, signal) {
+    /** `onUpdate` receives one-line progress updates for CLIs that stream their work (codex, grok). */
+    async function ask(request, signal, onUpdate) {
         const adapter = adapters[request.agent];
         const prompt = framePrompt(request.question, Boolean(request.sessionId));
-        return execute(adapter, request, (extra) => adapter.build(request, prompt, extra), signal);
+        return execute(adapter, request, (extra) => adapter.build(request, prompt, extra), signal, onUpdate);
     }
     /** 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) {

package/dist/narrate.js

@@ -0,0 +1,42 @@
+import { parseJsonLines } from "./jsonl.js";
+const MAX_UPDATE_CHARS = 200;
+/** Collapses whitespace and shortens text to a single progress line. */
+export function oneLine(text, max = MAX_UPDATE_CHARS) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Turns one line of a CLI's JSONL output into a progress line, if it is worth reporting.
+ * Never throws: a malformed event must not break the run it came from.
+ */
+export function describeLine(describe, line) {
+    try {
+        const [event] = parseJsonLines(line);
+        const text = event ? describe(event)?.trim() : undefined;
+        return text ? oneLine(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `/bin/zsh -lc 'npm test'` → `npm test`: CLIs wrap every command in a login shell. */
+export function unwrapShell(command) {
+    return /^\S*sh -lc '(.*)'$/s.exec(command)?.[1] ?? command;
+}
+/**
+ * A timestamped progress log for the shell: each update as one line, plus a heartbeat whenever nothing has been
+ * written for `heartbeatMs`, so a long quiet run still shows it is alive. Call stop() when the run ends.
+ */
+export function progressLog(write, heartbeat, heartbeatMs) {
+    const started = Date.now();
+    let last = started;
+    const update = (text) => {
+        last = Date.now();
+        write(`[${Math.round((last - started) / 1000)}s] ${text}\n`);
+    };
+    const timer = setInterval(() => {
+        if (Date.now() - last >= heartbeatMs)
+            update(heartbeat);
+    }, Math.max(1, Math.round(heartbeatMs / 3)));
+    return { update, stop: () => clearInterval(timer) };
+}

package/dist/progress.js

@@ -1,22 +1,30 @@
 /**
- * Sends a progress notification every `intervalMs` while `work` runs, if the client asked for progress.
- * Long advisor calls otherwise look hung, and some hosts reset their tool timeout on progress.
+ * Returns a function that sends one progress notification, or undefined if the client did not ask for progress.
+ * Progress values only go up, as the spec requires, however many sources share the function.
  */
-export async function withProgress(extra, intervalMs, describe, work) {
+export function progressSender(extra) {
     const progressToken = extra._meta?.progressToken;
     if (progressToken === undefined)
-        return work;
-    const started = Date.now();
-    let tick = 0;
-    const timer = setInterval(() => {
-        tick++;
-        const message = describe(Math.round((Date.now() - started) / 1000));
+        return undefined;
+    let progress = 0;
+    return (message) => {
+        progress++;
         extra
-            .sendNotification({ method: "notifications/progress", params: { progressToken, progress: tick, message } })
+            .sendNotification({ method: "notifications/progress", params: { progressToken, progress, message } })
             .catch(() => {
             // The client went away; the call itself will be cancelled.
         });
-    }, intervalMs);
+    };
+}
+/**
+ * Sends a progress notification every `intervalMs` while `work` runs, if the client asked for progress.
+ * Long advisor calls otherwise look hung, and some hosts reset their tool timeout on progress.
+ */
+export async function withProgress(extra, intervalMs, describe, work, send = progressSender(extra)) {
+    if (!send)
+        return work;
+    const started = Date.now();
+    const timer = setInterval(() => send(describe(Math.round((Date.now() - started) / 1000))), intervalMs);
     try {
         return await work;
     }

package/dist/prompt.js

@@ -18,3 +18,11 @@ Be concrete and concise, and cite files and lines when relevant.`;
 export function frameForkPrompt(question) {
     return `${FORK_BRIEFING}\n\nQuestion from the other agent:\n\n${question}`;
 }
+const TASK_BRIEFING = `Another AI coding agent working in this repository has dispatched you to complete a task on its behalf. Work in your current directory.
+Nobody can answer questions or approve plans: do not follow brainstorming, planning or approval workflows. Make reasonable assumptions, note them, and finish the task.
+Keep changes to what the task asks for. Do not commit, push, or touch anything outside this directory unless the task says to. Verify your work (build, tests) where you can.
+End with a short report: what you changed (files), how you verified it, and anything left undone.`;
+/** Builds the text sent to a worker. Like framePrompt, it starts with a letter. */
+export function frameTaskPrompt(task) {
+    return `${TASK_BRIEFING}\n\nTask:\n\n${task}`;
+}

package/dist/run.js

@@ -1,15 +1,61 @@
 import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 const KILL_GRACE_MS = 3000;
 const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+// A signal handler that calls process.exit() skips the SIGKILL grace timers, so groups still running then are
+// killed synchronously on the way out.
+const liveGroups = new Set();
+let exitHookInstalled = false;
+function trackGroup(pid) {
+    if (!exitHookInstalled) {
+        exitHookInstalled = true;
+        process.once("exit", () => {
+            for (const group of liveGroups) {
+                try {
+                    process.kill(-group, "SIGKILL");
+                }
+                catch {
+                    // Group already exited.
+                }
+            }
+        });
+    }
+    liveGroups.add(pid);
+}
+/** Calls `onLine` for each complete line, without rescanning text already split. */
+function lineSplitter(onLine) {
+    const decoder = new StringDecoder("utf8");
+    let partial = "";
+    return {
+        write(chunk) {
+            const text = decoder.write(chunk);
+            let start = 0;
+            for (let nl = text.indexOf("\n"); nl !== -1; nl = text.indexOf("\n", start)) {
+                onLine(partial + text.slice(start, nl));
+                partial = "";
+                start = nl + 1;
+            }
+            partial += text.slice(start);
+        },
+        end() {
+            const rest = partial + decoder.end();
+            partial = "";
+            if (rest)
+                onLine(rest);
+        },
+    };
+}
 /**
  * Runs a command with stdin closed, in its own process group so that a timeout, an abort or runaway
  * output kills everything it started.
  */
-export function run(command, args, { cwd, timeoutMs, signal, maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES }) {
+export function run(command, args, { cwd, timeoutMs, signal, maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES, onStdoutLine }) {
     if (signal?.aborted)
         return Promise.resolve({ stdout: "", stderr: "", code: null, stopped: "aborted" });
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"], detached: true });
+        if (child.pid)
+            trackGroup(child.pid);
         const stdout = [];
         const stderr = [];
         let outputBytes = 0;
@@ -33,6 +79,8 @@ export function run(command, args, { cwd, timeoutMs, signal, maxOutputBytes = DE
         };
         const onAbort = () => stop("aborted");
         const cleanup = () => {
+            if (child.pid)
+                liveGroups.delete(child.pid);
             clearTimeout(timer);
             clearTimeout(graceTimer);
             signal?.removeEventListener("abort", onAbort);
@@ -45,10 +93,15 @@ export function run(command, args, { cwd, timeoutMs, signal, maxOutputBytes = DE
             outputBytes += chunk.length;
             if (outputBytes > maxOutputBytes)
                 return stop("output_limit");
-            into.push(chunk);
+            into(chunk);
         };
-        child.stdout.on("data", collect(stdout));
-        child.stderr.on("data", collect(stderr));
+        const lines = onStdoutLine ? lineSplitter(onStdoutLine) : undefined;
+        child.stdout.on("data", collect((chunk) => (lines ? lines.write(chunk) : stdout.push(chunk))));
+        child.stderr.on("data", collect((chunk) => stderr.push(chunk)));
+        child.stdout.on("end", () => {
+            if (!stopped)
+                lines?.end();
+        });
         child.on("error", (err) => {
             cleanup();
             reject(err.code === "ENOENT" ? new Error(`${command} CLI not found on PATH`) : err);

package/dist/server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { withProgress } from "./progress.js";
 import { registerSessionTools, SESSIONS_INSTRUCTIONS } from "./session-tools.js";
+import { registerTaskTools, TASKS_INSTRUCTIONS } from "./task-tools.js";
 import { AGENTS, EFFORTS, SESSION_ID_PATTERN } from "./types.js";
 import { VERSION } from "./version.js";
 const DEFAULT_PROGRESS_INTERVAL_MS = 10_000;
@@ -56,8 +57,8 @@ 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, sessions, }) {
-    const instructions = sessions ? `${INSTRUCTIONS}\n${SESSIONS_INSTRUCTIONS}` : INSTRUCTIONS;
+export function createServer({ ask, listAgents, defaultCwd, progressIntervalMs = DEFAULT_PROGRESS_INTERVAL_MS, sessions, tasks, }) {
+    const instructions = [INSTRUCTIONS, ...(sessions ? [SESSIONS_INSTRUCTIONS] : []), ...(tasks ? [TASKS_INSTRUCTIONS] : [])].join("\n");
     const server = new McpServer({ name: "consult", version: VERSION }, { instructions });
     server.registerTool("ask_agent", {
         title: "Ask another agent",
@@ -133,5 +134,7 @@ export function createServer({ ask, listAgents, defaultCwd, progressIntervalMs =
     });
     if (sessions)
         registerSessionTools(server, sessions, progressIntervalMs);
+    if (tasks)
+        registerTaskTools(server, tasks, defaultCwd, progressIntervalMs);
     return server;
 }

package/dist/settings.js

@@ -6,9 +6,11 @@ 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"]) }),
+    // Added after the first release, so files written before it have no tasks entry.
+    tasks: z.object({ enabled: z.boolean() }).default({ enabled: false }),
 });
-/** Live sessions stay off until the user turns them on. */
-export const DEFAULT_SETTINGS = { version: 1, sessions: { enabled: false, scope: "repo" } };
+/** Live sessions and task dispatch stay off until the user turns them on. */
+export const DEFAULT_SETTINGS = { version: 1, sessions: { enabled: false, scope: "repo" }, tasks: { enabled: false } };
 export class SettingsError extends Error {
     name = "SettingsError";
 }
@@ -56,3 +58,4 @@ export function withSessionsMode(settings, mode) {
         sessions: mode === "off" ? { ...settings.sessions, enabled: false } : { enabled: true, scope: mode },
     };
 }
+export const withTasksEnabled = (settings, enabled) => ({ ...settings, tasks: { enabled } });

package/dist/task-tools.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { oneLine } from "./narrate.js";
+import { progressSender, withProgress } from "./progress.js";
+import { EFFORTS, WORKERS } from "./types.js";
+export const TASKS_INSTRUCTIONS = `Task dispatch is on. dispatch_task hands a coding task to a Codex or Grok worker that edits files in the working directory in the background; task_status reports its progress and final report, and cancel_task stops it.
+Dispatch work that is well defined and separable from yours, such as tests for a module or a mechanical refactor, and keep working meanwhile. Do not edit the files a running worker is changing.
+The worker cannot see your conversation or ask you questions: state the goal, the files involved, the constraints and how to verify. Review its changes (git diff) before building on them.`;
+const DISPATCH_DESCRIPTION = `Start a Codex or Grok agent on a coding task in the background, using the CLIs signed in on this machine. Returns a task_id at once.
+The worker runs headless in the working directory and can edit files and run commands there (codex in its workspace-write sandbox without network; grok without a sandbox). It has no MCP servers and cannot ask you anything, so make the task self-contained: goal, relevant files, constraints, how to verify.
+Follow it with task_status: pass wait_sec to block until it finishes, with live progress updates meanwhile.`;
+const STATUS_DESCRIPTION = `Show a dispatched task's state, its latest progress updates (commands run, files edited, messages) and, once finished, the worker's final report. Without task_id, lists all tasks.
+Pass wait_sec to wait for the task to finish (returns early when it does), and since (the last update seq you saw) to get only newer updates.`;
+const CANCEL_DESCRIPTION = "Stop a running task and its worker process. Files it already changed stay changed.";
+const MAX_WAIT_SEC = 600;
+const DEFAULT_UPDATES = 20;
+const taskIdSchema = z.string().min(1).describe("task_id returned by dispatch_task");
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+const seconds = (ms) => `${Math.round(ms / 1000)}s`;
+const elapsed = (view) => (view.finishedAt ?? Date.now()) - view.startedAt;
+const lastSeq = (view) => view.updates.at(-1)?.seq ?? 0;
+function selectUpdates(view, since) {
+    return since === undefined ? view.updates.slice(-DEFAULT_UPDATES) : view.updates.filter((u) => u.seq > since);
+}
+/** Whether updates after `since` were already dropped from the task's history. */
+const missedUpdates = (view, since) => since !== undefined && (view.updates[0]?.seq ?? 0) > since + 1;
+const formatUpdate = (u) => `[${seconds(u.atMs)}] ${u.text}`;
+const headline = (view) => `${view.id} · ${view.agent} · ${view.state} · ${seconds(elapsed(view))}`;
+function structured(view, updates, since) {
+    return {
+        task_id: view.id,
+        agent: view.agent,
+        state: view.state,
+        cwd: view.cwd,
+        elapsed_ms: elapsed(view),
+        updates: updates.map((u) => ({ seq: u.seq, at_ms: u.atMs, text: u.text })),
+        last_seq: lastSeq(view),
+        ...(missedUpdates(view, since) ? { earlier_updates_dropped: true } : {}),
+        ...(view.result
+            ? { result: { report: view.result.answer, session_id: view.result.sessionId, ...(view.result.model ? { model: view.result.model } : {}) } }
+            : {}),
+        ...(view.error ? { error: view.error } : {}),
+    };
+}
+function formatTask(view, updates, since) {
+    const lines = [headline(view), `cwd: ${view.cwd}`, `task: ${oneLine(view.task, 120)}`];
+    if (updates.length > 0) {
+        const note = missedUpdates(view, since) ? " (some earlier ones were dropped)" : "";
+        lines.push("", `Updates${note}:`, ...updates.map(formatUpdate));
+    }
+    if (view.state === "running") {
+        lines.push("", `Still running. Call task_status again with since=${lastSeq(view)} for newer updates, or wait_sec to wait.`);
+    }
+    else if (view.result) {
+        const model = view.result.model ? ` · model: ${view.result.model}` : "";
+        lines.push("", "Report:", view.result.answer, "", "---", `session_id: ${view.result.sessionId}${model}`);
+        lines.push("Review the changes before relying on them. For a read-only follow-up, pass this agent and session_id to ask_agent.");
+    }
+    else if (view.error) {
+        lines.push("", `Failed: ${view.error}`);
+    }
+    return lines.join("\n");
+}
+function formatList(views) {
+    if (views.length === 0)
+        return "No tasks yet.";
+    return views.map((v) => `${headline(v)} · ${oneLine(v.task, 80)}`).join("\n");
+}
+export function registerTaskTools(server, tasks, defaultCwd, progressIntervalMs) {
+    server.registerTool("dispatch_task", {
+        title: "Dispatch a task",
+        description: DISPATCH_DESCRIPTION,
+        inputSchema: {
+            agent: z.enum(WORKERS).describe("Which CLI does the work"),
+            task: z.string().min(1).describe("The task, self-contained: goal, relevant files, constraints, how to verify"),
+            model: z.string().optional().describe("Model for that CLI. Omit for the CLI's default; list_agents shows options"),
+            effort: z.enum(EFFORTS).optional().describe("Reasoning effort. Omit for the CLI's default"),
+            cwd: z.string().optional().describe("Directory the worker works in. Defaults to the directory this server was started in"),
+        },
+        // Workers write files and run commands; each dispatch starts new work.
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const view = tasks.start({ agent: args.agent, task: args.task, cwd: args.cwd ?? defaultCwd, model: args.model, effort: args.effort });
+            const text = `Dispatched ${view.id} to ${view.agent} in ${view.cwd}.\nCall task_status with task_id "${view.id}" for progress; pass wait_sec (up to ${MAX_WAIT_SEC}) to wait for the report.`;
+            return { content: [{ type: "text", text }], structuredContent: structured(view, []) };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: "text", text: errorMessage(err) }] };
+        }
+    });
+    server.registerTool("task_status", {
+        title: "Task status",
+        description: STATUS_DESCRIPTION,
+        inputSchema: {
+            task_id: taskIdSchema.optional(),
+            wait_sec: z.number().int().min(0).max(MAX_WAIT_SEC).optional().describe("Wait up to this many seconds for the task to finish. Default 0"),
+            since: z.number().int().min(0).optional().describe("Only return updates after this seq (last_seq from an earlier call)"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (args, extra) => {
+        try {
+            if (args.task_id === undefined) {
+                const views = tasks.list();
+                return { content: [{ type: "text", text: formatList(views) }], structuredContent: { tasks: views.map((v) => structured(v, [])) } };
+            }
+            const initial = tasks.get(args.task_id);
+            const send = progressSender(extra);
+            // Relay each new update as it arrives, alongside withProgress's heartbeat.
+            let relayed = args.since ?? lastSeq(initial);
+            const unsubscribe = send
+                ? tasks.subscribe(initial.id, (view) => {
+                    for (const u of view.updates.filter((u) => u.seq > relayed))
+                        send(formatUpdate(u));
+                    relayed = Math.max(relayed, lastSeq(view));
+                })
+                : () => { };
+            const heartbeat = () => `${initial.id} (${initial.agent}) working, ${seconds(elapsed(initial))}`;
+            let view;
+            try {
+                const work = tasks.wait(initial.id, (args.wait_sec ?? 0) * 1000, extra.signal);
+                view = await withProgress(extra, progressIntervalMs, heartbeat, work, send);
+            }
+            finally {
+                unsubscribe();
+            }
+            const updates = selectUpdates(view, args.since);
+            return {
+                content: [{ type: "text", text: formatTask(view, updates, args.since) }],
+                structuredContent: structured(view, updates, args.since),
+            };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: "text", text: errorMessage(err) }] };
+        }
+    });
+    server.registerTool("cancel_task", {
+        title: "Cancel a task",
+        description: CANCEL_DESCRIPTION,
+        inputSchema: { task_id: taskIdSchema },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        try {
+            const view = await tasks.cancel(args.task_id);
+            const updates = selectUpdates(view, undefined);
+            return { content: [{ type: "text", text: formatTask(view, updates) }], structuredContent: structured(view, updates) };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: "text", text: errorMessage(err) }] };
+        }
+    });
+}

package/dist/tasks.js

@@ -0,0 +1,139 @@
+import { assertDirectory, assertExitedCleanly } from "./consult.js";
+import { describeLine } from "./narrate.js";
+import { frameTaskPrompt } from "./prompt.js";
+import { AdvisorError } from "./types.js";
+const MAX_UPDATES = 200;
+const MAX_FINISHED = 50;
+// Workers can stream far more than an advisor answers with (codex events carry each command's full output), so
+// they get a larger cap, and only lines short enough to hold a final message are kept for parse.
+const MAX_TASK_OUTPUT_BYTES = 1024 * 1024 * 1024;
+const MAX_KEPT_LINE_CHARS = 256 * 1024;
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Runs worker tasks in the background. Tasks live in memory only, so they end with the server process,
+ * which stops their process groups on the way out.
+ */
+export function createTaskManager({ run, workers, timeoutMs, signal, now = Date.now }) {
+    const entries = new Map();
+    let count = 0;
+    function entry(id) {
+        const found = entries.get(id);
+        if (!found) {
+            throw new AdvisorError(`unknown task_id ${id}: tasks last as long as this consult server, which keeps the last ${MAX_FINISHED} finished ones`);
+        }
+        return found;
+    }
+    function change(id, update) {
+        const current = entries.get(id);
+        if (!current)
+            return;
+        const view = update(current.view);
+        entries.set(id, { ...current, view });
+        for (const listener of current.listeners) {
+            try {
+                listener(view);
+            }
+            catch {
+                // A failing listener must not change the task's outcome.
+            }
+        }
+    }
+    function narrate(id, worker, line) {
+        const text = describeLine((event) => worker.describe(event), line);
+        if (!text)
+            return;
+        change(id, (view) => {
+            const seq = (view.updates.at(-1)?.seq ?? 0) + 1;
+            return { ...view, updates: [...view.updates, { seq, atMs: now() - view.startedAt, text }].slice(-MAX_UPDATES) };
+        });
+    }
+    function finish(id, outcome) {
+        change(id, (view) => ({ ...view, ...outcome, finishedAt: now() }));
+    }
+    async function execute(id, request, abort) {
+        const worker = workers[request.agent];
+        try {
+            // Computed per task, never cached: containment must reflect the config as it is right now.
+            const extraArgs = worker.prepare ? await worker.prepare(run, request.cwd, abort) : [];
+            const { command, args } = worker.build(request, frameTaskPrompt(request.task), extraArgs);
+            const kept = [];
+            const res = await run(command, args, {
+                cwd: request.cwd,
+                timeoutMs,
+                signal: abort,
+                maxOutputBytes: MAX_TASK_OUTPUT_BYTES,
+                onStdoutLine: (line) => {
+                    if (line.length <= MAX_KEPT_LINE_CHARS)
+                        kept.push(line);
+                    narrate(id, worker, line);
+                },
+            });
+            const stdout = kept.join("\n");
+            assertExitedCleanly(worker.name, { ...res, stdout }, timeoutMs);
+            finish(id, { state: "succeeded", result: worker.parse(stdout) });
+        }
+        catch (err) {
+            finish(id, abort.aborted ? { state: "cancelled" } : { state: "failed", error: errorMessage(err) });
+        }
+    }
+    function prune() {
+        const finished = [...entries.values()].filter((e) => e.view.state !== "running");
+        for (const e of finished.slice(0, -MAX_FINISHED))
+            entries.delete(e.view.id);
+    }
+    /** Starts a task and returns at once; the worker keeps running in the background. */
+    function start(request) {
+        if (!request.task.trim())
+            throw new AdvisorError("task must not be empty");
+        assertDirectory(request.cwd);
+        if (signal?.aborted)
+            throw new AdvisorError("consult is shutting down");
+        const id = `task-${++count}`;
+        const controller = new AbortController();
+        const view = { id, agent: request.agent, task: request.task, cwd: request.cwd, state: "running", startedAt: now(), updates: [] };
+        entries.set(id, { view, controller, listeners: new Set() });
+        prune();
+        void execute(id, request, signal ? AbortSignal.any([controller.signal, signal]) : controller.signal);
+        return view;
+    }
+    const get = (id) => entry(id).view;
+    /** Newest first. */
+    const list = () => [...entries.values()].map((e) => e.view).reverse();
+    /** Calls `listener` with the new view on every update and when the task finishes. */
+    function subscribe(id, listener) {
+        const { listeners } = entry(id);
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    }
+    /** Resolves when the task finishes, `ms` passes (if given) or `abort` fires, whichever is first. */
+    function wait(id, ms, abort) {
+        const current = get(id);
+        if (current.state !== "running" || ms === 0 || abort?.aborted)
+            return Promise.resolve(current);
+        return new Promise((resolve) => {
+            let latest = current;
+            const done = () => {
+                clearTimeout(timer);
+                unsubscribe();
+                abort?.removeEventListener("abort", done);
+                resolve(latest);
+            };
+            const timer = ms === undefined ? undefined : setTimeout(done, ms);
+            const unsubscribe = subscribe(id, (view) => {
+                latest = view;
+                if (view.state !== "running")
+                    done();
+            });
+            abort?.addEventListener("abort", done, { once: true });
+        });
+    }
+    /** Stops a running task and resolves once its process has exited. */
+    function cancel(id) {
+        const { view, controller } = entry(id);
+        if (view.state !== "running")
+            return Promise.resolve(view);
+        controller.abort();
+        return wait(id);
+    }
+    return { start, get, list, subscribe, wait, cancel };
+}

package/dist/tui.js

@@ -1,5 +1,5 @@
 import { cancel, confirm, intro, isCancel, log, multiselect, outro, select } from "@clack/prompts";
-import { DEFAULT_SETTINGS, SESSIONS_MODES, sessionsMode, withSessionsMode, } from "./settings.js";
+import { DEFAULT_SETTINGS, SESSIONS_MODES, sessionsMode, withSessionsMode, withTasksEnabled, } 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" },
@@ -23,7 +23,7 @@ export async function chooseInstallMode(opts) {
 }
 export function planSettings(current, registered, chosen) {
     return {
-        settings: withSessionsMode(current, chosen.mode),
+        settings: withTasksEnabled(withSessionsMode(current, chosen.mode), chosen.tasks),
         register: chosen.hosts.filter((agent) => !registered.includes(agent)),
         unregister: registered.filter((agent) => !chosen.hosts.includes(agent)),
     };
@@ -56,6 +56,12 @@ export async function runSettings(io) {
     const mode = await promptSessionsMode(sessionsMode(current));
     if (mode === undefined)
         return cancel("No changes made.");
+    const tasks = await confirm({
+        message: "Task dispatch: let agents hand tasks to Codex and Grok workers that edit files and run commands?",
+        initialValue: current.tasks.enabled,
+    });
+    if (isCancel(tasks))
+        return cancel("No changes made.");
     const hosts = io.installed.length === 0
         ? []
         : await multiselect({
@@ -66,7 +72,7 @@ export async function runSettings(io) {
         });
     if (isCancel(hosts))
         return cancel("No changes made.");
-    const plan = planSettings(current, registered, { mode, hosts });
+    const plan = planSettings(current, registered, { mode, tasks, hosts });
     io.save(plan.settings);
     const changed = [...plan.register, ...plan.unregister];
     const results = [
@@ -75,5 +81,5 @@ export async function runSettings(io) {
     ].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.`);
+    outro(`Live sessions: ${mode}. Task dispatch: ${tasks ? "on" : "off"}. Restart running agent sessions to apply.`);
 }

package/dist/types.js

@@ -2,6 +2,7 @@ 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 const WORKERS = ["codex", "grok"];
 export class AdvisorError extends Error {
     name = "AdvisorError";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "consult-mcp",
-  "version": "0.3.1",
+  "version": "0.4.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",