botholomew 0.23.0 → 0.24.0

package/src/commands/approval.ts

@@ -0,0 +1,130 @@
+import ansis from "ansis";
+import type { Command } from "commander";
+import { decideAndRequeue } from "../approvals/decide.ts";
+import {
+  APPROVAL_STATUSES,
+  type Approval,
+  type ApprovalStatus,
+} from "../approvals/schema.ts";
+import { getApproval, listApprovals } from "../approvals/store.ts";
+import { logger } from "../utils/logger.ts";
+
+function statusColor(status: ApprovalStatus): string {
+  switch (status) {
+    case "approved":
+      return ansis.green(status);
+    case "denied":
+      return ansis.red(status);
+    case "pending":
+      return ansis.yellow(status);
+  }
+}
+
+function printApproval(a: Approval) {
+  console.log(
+    `${ansis.bold(a.id.slice(0, 8))}  ${statusColor(a.status).padEnd(18)}  ${ansis.cyan(`${a.server}/${a.tool}`)}`,
+  );
+  console.log(`  args: ${a.args}`);
+  if (a.task_id) console.log(`  task: ${a.task_id}`);
+  if (a.reason) console.log(`  reason: ${a.reason}`);
+  console.log(`  created: ${a.created_at}`);
+  if (a.decided_at) {
+    console.log(`  decided: ${a.decided_at} by ${a.decided_by ?? "?"}`);
+  }
+}
+
+export function registerApprovalCommand(program: Command) {
+  const approval = program
+    .command("approval")
+    .description("Review and decide pending mcpx tool-call approvals");
+
+  approval
+    .command("list")
+    .description("List approval requests (newest first)")
+    .option(
+      "-s, --status <status>",
+      `filter by status (${APPROVAL_STATUSES.join("|")})`,
+    )
+    .option("-l, --limit <n>", "max number of approvals", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N approvals", Number.parseInt)
+    .action(
+      async (opts: {
+        status?: ApprovalStatus;
+        limit?: number;
+        offset?: number;
+      }) => {
+        if (opts.status && !APPROVAL_STATUSES.includes(opts.status)) {
+          logger.error(
+            `Unknown status: ${opts.status}. Use one of: ${APPROVAL_STATUSES.join(", ")}`,
+          );
+          process.exit(1);
+        }
+        const dir = program.opts().dir;
+        const approvals = await listApprovals(dir, {
+          status: opts.status,
+          limit: opts.limit,
+          offset: opts.offset,
+        });
+        if (approvals.length === 0) {
+          logger.dim("No approvals found.");
+          return;
+        }
+        for (const a of approvals) {
+          printApproval(a);
+          console.log("");
+        }
+        console.log(ansis.dim(`${approvals.length} approval(s)`));
+      },
+    );
+
+  approval
+    .command("view <id>")
+    .description("Show a single approval request")
+    .action(async (id: string) => {
+      const dir = program.opts().dir;
+      const a = await getApproval(dir, id);
+      if (!a) {
+        logger.error(`No approval found with id ${id}.`);
+        process.exit(1);
+      }
+      printApproval(a);
+    });
+
+  approval
+    .command("approve <id>")
+    .description("Approve a pending request and re-queue its task")
+    .action(async (id: string) => {
+      const dir = program.opts().dir;
+      const a = await getApproval(dir, id);
+      if (!a) {
+        logger.error(`No approval found with id ${id}.`);
+        process.exit(1);
+      }
+      if (a.status !== "pending") {
+        logger.warn(`Approval ${id} is already ${a.status}.`);
+        return;
+      }
+      await decideAndRequeue(dir, id, "approved", "cli");
+      logger.success(`Approved ${a.server}/${a.tool} (${id}).`);
+      if (a.task_id) logger.dim(`Re-queued task ${a.task_id} (now pending).`);
+    });
+
+  approval
+    .command("deny <id>")
+    .description("Deny a pending request and re-queue its task to recover")
+    .action(async (id: string) => {
+      const dir = program.opts().dir;
+      const a = await getApproval(dir, id);
+      if (!a) {
+        logger.error(`No approval found with id ${id}.`);
+        process.exit(1);
+      }
+      if (a.status !== "pending") {
+        logger.warn(`Approval ${id} is already ${a.status}.`);
+        return;
+      }
+      await decideAndRequeue(dir, id, "denied", "cli");
+      logger.success(`Denied ${a.server}/${a.tool} (${id}).`);
+      if (a.task_id) logger.dim(`Re-queued task ${a.task_id} (now pending).`);
+    });
+}

package/src/commands/chat.ts

@@ -8,8 +8,9 @@ export function registerChatCommand(program: Command) {
       "Open the interactive chat TUI\n\n" +
         "  Tab navigation (Ctrl+<letter> from any tab):\n" +
         "    Ctrl+a  Chat        Ctrl+t  Tasks       Ctrl+w  Workers\n" +
-        "    Ctrl+o  Tools       Ctrl+e  Threads     Ctrl+g  Help\n" +
-        "    Ctrl+n  Context     Ctrl+s  Schedules   Esc     Return to Chat\n\n" +
+        "    Ctrl+o  Tools       Ctrl+e  Threads     Ctrl+p  Approvals\n" +
+        "    Ctrl+n  Context     Ctrl+s  Schedules   Ctrl+g  Help\n" +
+        "                                            Esc     Return to Chat\n\n" +
         "  Refresh: Ctrl+R refreshes Context · Tasks · Threads · Schedules · Workers\n\n" +
         "  Chat input:\n" +
         "    Enter          Send message\n" +
@@ -27,37 +28,49 @@ export function registerChatCommand(program: Command) {
     )
     .option("--thread-id <id>", "Resume an existing chat thread")
     .option("-p, --prompt <text>", "Start chat with an initial prompt")
-    .action(async (opts: { threadId?: string; prompt?: string }) => {
-      const { render } = await import("ink");
-      const React = await import("react");
-      const { App } = await import("../tui/App.tsx");
-      const dir = program.opts().dir;
-      const config = await loadConfig(dir);
-      const idleTimeoutMs = config.tui_idle_timeout_seconds * 1000;
+    .option(
+      "--unsafe",
+      "bypass the mcpx approval gate (allow every tool without approval)",
+      false,
+    )
+    .action(
+      async (opts: {
+        threadId?: string;
+        prompt?: string;
+        unsafe?: boolean;
+      }) => {
+        const { render } = await import("ink");
+        const React = await import("react");
+        const { App } = await import("../tui/App.tsx");
+        const dir = program.opts().dir;
+        const config = await loadConfig(dir);
+        const idleTimeoutMs = config.tui_idle_timeout_seconds * 1000;
 
-      // VHS/ttyd doesn't fully negotiate the Kitty Keyboard protocol, so
-      // Ink's "enabled" mode drops non-text keystrokes (Tab, Escape) under
-      // capture. Use "disabled" mode in capture to keep text input working;
-      // captures that need Tab/Escape should use the `-p` prompt flag or
-      // a /slash command typed as text instead.
-      const isCapture = process.env.BOTHOLOMEW_FAKE_LLM === "1";
-      const instance = render(
-        React.createElement(App, {
-          projectDir: dir,
-          threadId: opts.threadId,
-          initialPrompt: opts.prompt,
-          idleTimeoutMs,
-        }),
-        {
-          exitOnCtrlC: false,
-          kittyKeyboard: isCapture
-            ? { mode: "disabled" }
-            : {
-                mode: "enabled",
-                flags: ["disambiguateEscapeCodes"],
-              },
-        },
-      );
-      await instance.waitUntilExit();
-    });
+        // VHS/ttyd doesn't fully negotiate the Kitty Keyboard protocol, so
+        // Ink's "enabled" mode drops non-text keystrokes (Tab, Escape) under
+        // capture. Use "disabled" mode in capture to keep text input working;
+        // captures that need Tab/Escape should use the `-p` prompt flag or
+        // a /slash command typed as text instead.
+        const isCapture = process.env.BOTHOLOMEW_FAKE_LLM === "1";
+        const instance = render(
+          React.createElement(App, {
+            projectDir: dir,
+            threadId: opts.threadId,
+            initialPrompt: opts.prompt,
+            idleTimeoutMs,
+            unsafe: opts.unsafe,
+          }),
+          {
+            exitOnCtrlC: false,
+            kittyKeyboard: isCapture
+              ? { mode: "disabled" }
+              : {
+                  mode: "enabled",
+                  flags: ["disambiguateEscapeCodes"],
+                },
+          },
+        );
+        await instance.waitUntilExit();
+      },
+    );
 }

package/src/commands/nuke.ts

@@ -2,8 +2,14 @@ import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import ansis from "ansis";
 import type { Command } from "commander";
+import { deleteAllApprovals } from "../approvals/store.ts";
 import { loadConfig } from "../config/loader.ts";
-import { SCHEDULES_DIR, TASKS_DIR, THREADS_DIR } from "../constants.ts";
+import {
+  APPROVALS_DIR,
+  SCHEDULES_DIR,
+  TASKS_DIR,
+  THREADS_DIR,
+} from "../constants.ts";
 import { openMembot, resolveMembotDir } from "../mem/client.ts";
 import { deleteAllSchedules } from "../schedules/store.ts";
 import { deleteAllTasks } from "../tasks/store.ts";
@@ -86,6 +92,10 @@ async function runNuke(projectDir: string, scope: NukeScope): Promise<void> {
       `Deleted ${threads} threads (${interactions} interactions) from ${THREADS_DIR}/`,
     );
   }
+  if (scope === "all") {
+    const n = await deleteAllApprovals(projectDir);
+    logger.success(`Deleted ${n} approval file(s) from ${APPROVALS_DIR}/`);
+  }
 }
 
 function registerScope(
@@ -151,6 +161,6 @@ export function registerNukeCommand(program: Command) {
     program,
     nuke,
     "all",
-    "Erase all agent-writable data: membot store, tasks/, schedules/, threads/",
+    "Erase all agent-writable data: membot store, tasks/, schedules/, threads/, approvals/",
   );
 }

package/src/commands/worker.ts

@@ -64,11 +64,17 @@ export function registerWorkerCommand(program: Command) {
       "run exactly this task (implies one-shot; incompatible with --persist)",
     )
     .option("--no-eval-schedules", "skip schedule evaluation this run")
+    .option(
+      "--unsafe",
+      "bypass the mcpx approval gate (allow every tool without approval)",
+      false,
+    )
     .action(
       async (opts: {
         persist?: boolean;
         taskId?: string;
         evalSchedules?: boolean;
+        unsafe?: boolean;
       }) => {
         if (opts.persist && opts.taskId) {
           logger.error("--persist and --task-id are mutually exclusive.");
@@ -81,6 +87,7 @@ export function registerWorkerCommand(program: Command) {
           mode: opts.persist ? "persist" : "once",
           taskId: opts.taskId,
           evalSchedules: opts.evalSchedules,
+          unsafe: opts.unsafe,
         });
       },
     );
@@ -90,18 +97,30 @@ export function registerWorkerCommand(program: Command) {
     .description("Spawn a worker as a detached background process")
     .option("--persist", "keep running, looping over the tick cycle", false)
     .option("--task-id <id>", "run exactly this task (implies one-shot)")
-    .action(async (opts: { persist?: boolean; taskId?: string }) => {
-      if (opts.persist && opts.taskId) {
-        logger.error("--persist and --task-id are mutually exclusive.");
-        process.exit(1);
-      }
-      const dir = program.opts().dir;
-      const { spawnWorker } = await import("../worker/spawn.ts");
-      await spawnWorker(dir, {
-        mode: opts.persist ? "persist" : "once",
-        taskId: opts.taskId,
-      });
-    });
+    .option(
+      "--unsafe",
+      "bypass the mcpx approval gate (allow every tool without approval)",
+      false,
+    )
+    .action(
+      async (opts: {
+        persist?: boolean;
+        taskId?: string;
+        unsafe?: boolean;
+      }) => {
+        if (opts.persist && opts.taskId) {
+          logger.error("--persist and --task-id are mutually exclusive.");
+          process.exit(1);
+        }
+        const dir = program.opts().dir;
+        const { spawnWorker } = await import("../worker/spawn.ts");
+        await spawnWorker(dir, {
+          mode: opts.persist ? "persist" : "once",
+          taskId: opts.taskId,
+          unsafe: opts.unsafe,
+        });
+      },
+    );
 
   worker
     .command("list")

package/src/config/loader.ts

@@ -3,6 +3,7 @@ import { getConfigPath } from "../constants.ts";
 import { setLogLevel } from "../utils/logger.ts";
 import {
   type BotholomewConfig,
+  DEFAULT_APPROVALS,
   DEFAULT_CHUNKER_LLM,
   DEFAULT_CONFIG,
   DEFAULT_LLM,
@@ -60,6 +61,9 @@ export async function loadConfig(
     ...userConfig,
     llm: mergeLlmBlock(DEFAULT_LLM, userConfig.llm),
     chunker_llm: mergeLlmBlock(DEFAULT_CHUNKER_LLM, userConfig.chunker_llm),
+    // Deep-merge so a config predating the approval gate (or only overriding
+    // one key) still gets the safe defaults — and back-compat keeps the gate ON.
+    approvals: { ...DEFAULT_APPROVALS, ...(userConfig.approvals ?? {}) },
   };
 
   const config = applyEnvOverrides(merged);
@@ -101,3 +105,26 @@ export async function saveConfig(
   const configPath = getConfigPath(projectDir);
   await Bun.write(configPath, `${JSON.stringify(config, null, 2)}\n`);
 }
+
+/**
+ * Append an mcpx tool pattern to `approvals.allowed_tools` on disk, preserving
+ * every other key in the file (a surgical merge, not a full rewrite of merged
+ * defaults). Used by the chat TUI's "always allow" decision. No-op if the
+ * pattern is already present.
+ */
+export async function addAllowedTool(
+  projectDir: string,
+  pattern: string,
+): Promise<void> {
+  const configPath = getConfigPath(projectDir);
+  const file = Bun.file(configPath);
+  const raw: Record<string, unknown> = (await file.exists())
+    ? JSON.parse(await file.text())
+    : {};
+  if (!raw.approvals || typeof raw.approvals !== "object") raw.approvals = {};
+  const approvals = raw.approvals as Record<string, unknown>;
+  if (!Array.isArray(approvals.allowed_tools)) approvals.allowed_tools = [];
+  const allowed = approvals.allowed_tools as string[];
+  if (!allowed.includes(pattern)) allowed.push(pattern);
+  await Bun.write(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+}

package/src/config/schemas.ts

@@ -14,9 +14,30 @@ export interface LlmBlock {
   supports_tools: boolean;
 }
 
+/**
+ * Human-in-the-loop approval gate for outbound mcpx tool calls. The gate is
+ * ON by default (`enabled: true`) and gates **every** mcpx tool — users opt
+ * specific tools out via `allowed_tools`. A run launched with `--unsafe`
+ * bypasses the gate entirely (see `buildApprovalPolicy` in `src/mcpx/client.ts`).
+ */
+export interface ApprovalConfig {
+  /** Master switch. When false the gate is off (equivalent to running `--unsafe`). Default true. */
+  enabled: boolean;
+  /**
+   * Opt-in allowlist of tools that run WITHOUT approval. Patterns match against
+   * "server/tool": exact ("gmail/send_email"), wildcards on either side
+   * ("gmail/" + star, or star + "/search"), or a "/regex/" tested against the
+   * tool name. Empty (default) ⇒ gate everything.
+   */
+  allowed_tools: string[];
+  /** Convenience: also skip the gate for tools the server annotates `readOnlyHint: true`. Default false. */
+  auto_allow_read_only: boolean;
+}
+
 export interface BotholomewConfig {
   llm: LlmBlock;
   chunker_llm: LlmBlock;
+  approvals: ApprovalConfig;
   embedding_model: string;
   embedding_dimension: number;
   tick_interval_seconds: number;
@@ -51,9 +72,16 @@ export const DEFAULT_CHUNKER_LLM: LlmBlock = {
   model: "claude-haiku-4-5-20251001",
 };
 
+export const DEFAULT_APPROVALS: ApprovalConfig = {
+  enabled: true,
+  allowed_tools: [],
+  auto_allow_read_only: false,
+};
+
 export const DEFAULT_CONFIG: BotholomewConfig = {
   llm: DEFAULT_LLM,
   chunker_llm: DEFAULT_CHUNKER_LLM,
+  approvals: DEFAULT_APPROVALS,
   embedding_model: "Xenova/bge-small-en-v1.5",
   embedding_dimension: 384,
   tick_interval_seconds: 300,

package/src/constants.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
  *     tasks/.locks/<id>.lock            O_EXCL claim files
  *     schedules/<id>.md
  *     schedules/.locks/<id>.lock
+ *     approvals/<id>.md                 pending/decided mcpx approval requests
  *     threads/<YYYY-MM-DD>/<id>.csv     conversation history
  *     workers/<id>.json                 pidfile + heartbeat
  *     logs/                             worker logs
@@ -42,6 +43,7 @@ export const SKILLS_DIR = "skills";
 export const MCPX_DIR = "mcpx";
 export const TASKS_DIR = "tasks";
 export const SCHEDULES_DIR = "schedules";
+export const APPROVALS_DIR = "approvals";
 export const LOCKS_SUBDIR = ".locks";
 export const LOGS_DIR = "logs";
 export const WORKERS_DIR = "workers";
@@ -106,6 +108,10 @@ export function getSchedulesDir(projectDir: string): string {
   return join(projectDir, SCHEDULES_DIR);
 }
 
+export function getApprovalsDir(projectDir: string): string {
+  return join(projectDir, APPROVALS_DIR);
+}
+
 export function getSchedulesLockDir(projectDir: string): string {
   return join(projectDir, SCHEDULES_DIR, LOCKS_SUBDIR);
 }

package/src/init/index.ts

@@ -5,6 +5,7 @@ import type { LlmProvider } from "../config/schemas.ts";
 import {
   CONFIG_DIR,
   CONFIG_FILENAME,
+  getApprovalsDir,
   getConfigPath,
   getMcpxDir,
   getPromptsDir,
@@ -74,6 +75,7 @@ export async function initProject(
   await mkdir(getTasksLockDir(projectDir), { recursive: true });
   await mkdir(getSchedulesDir(projectDir), { recursive: true });
   await mkdir(getSchedulesLockDir(projectDir), { recursive: true });
+  await mkdir(getApprovalsDir(projectDir), { recursive: true });
   await mkdir(getWorkersDir(projectDir), { recursive: true });
   await mkdir(getThreadsDir(projectDir), { recursive: true });
   await mkdir(join(projectDir, LOGS_DIR), { recursive: true });
@@ -150,6 +152,9 @@ export async function initProject(
   logger.dim(`  ${TASKS_DIR}/          one markdown file per task`);
   logger.dim(`    ${LOCKS_SUBDIR}/        worker claim lockfiles`);
   logger.dim(`  ${SCHEDULES_DIR}/      one markdown file per schedule`);
+  logger.dim(
+    `  approvals/       one markdown file per gated tool-call request`,
+  );
   logger.dim(`  threads/         one CSV per conversation, by UTC date`);
   logger.dim(`  workers/         one JSON pidfile per worker (heartbeats)`);
   logger.dim(`  skills/, mcpx/, logs/`);

package/src/mcpx/client.ts

@@ -1,7 +1,14 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { type CallToolResult, McpxClient } from "@evantahler/mcpx";
+import {
+  type ApprovalPolicy,
+  type CallToolResult,
+  isWriteable,
+  McpxClient,
+  type Tool,
+  type ToolApprovalCallback,
+} from "@evantahler/mcpx";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { getMcpxDir, MCPX_SERVERS_FILENAME } from "../constants.ts";
 
@@ -19,13 +26,24 @@ export function resolveMcpxDir(
     : join(homedir(), ".mcpx");
 }
 
+export interface McpxApprovalOptions {
+  /** mcpx approval policy. Omit/undefined ⇒ no gate (back-compat). */
+  approvalPolicy?: ApprovalPolicy;
+  /** Callback invoked when a gated tool is about to run. */
+  onApprovalRequired?: ToolApprovalCallback;
+}
+
 /**
  * Create an McpxClient from `<mcpxDir>/servers.json`. Returns null if the
  * file is missing or has no servers configured. The caller is responsible
  * for resolving `mcpxDir` via `resolveMcpxDir`.
+ *
+ * Pass `approval` to wire the human-in-the-loop approval gate (see
+ * `buildApprovalPolicy`). When omitted the client gates nothing.
  */
 export async function createMcpxClient(
   mcpxDir: string,
+  approval: McpxApprovalOptions = {},
 ): Promise<McpxClient | null> {
   const serversPath = join(mcpxDir, MCPX_SERVERS_FILENAME);
   if (!existsSync(serversPath)) return null;
@@ -52,9 +70,73 @@ export async function createMcpxClient(
     auth,
     searchIndex,
     configDir: mcpxDir,
+    approvalPolicy: approval.approvalPolicy,
+    onApprovalRequired: approval.onApprovalRequired,
   });
 }
 
+/**
+ * Translate the Botholomew `approvals` config into an mcpx `ApprovalPolicy`.
+ *
+ * The gate is ON by default and gates **every** mcpx tool; the predicate
+ * returns `true` (require approval) for any tool NOT covered by the allowlist
+ * (and, when `auto_allow_read_only`, not annotated read-only). Returns
+ * `undefined` — meaning "gate nothing", mcpx's zero-overhead path — when the
+ * run is `--unsafe` or `approvals.enabled` is false.
+ */
+export function buildApprovalPolicy(
+  config: Pick<BotholomewConfig, "approvals">,
+  opts: { unsafe?: boolean } = {},
+): ApprovalPolicy | undefined {
+  const approvals = config.approvals;
+  if (opts.unsafe || !approvals.enabled) return undefined;
+  return (tool: Tool, server: string): boolean => {
+    if (approvals.auto_allow_read_only && !isWriteable(tool)) return false;
+    return !matchesAllowlist(approvals.allowed_tools, server, tool.name);
+  };
+}
+
+/**
+ * True when "server/toolName" matches any allowlist pattern. Patterns:
+ *   - exact "server/tool"
+ *   - wildcard, where "*" on either side of the slash matches anything
+ *   - a "/regex/" (with optional flags) tested against the tool name
+ * A bare token with no slash matches the tool name (server side wildcarded).
+ */
+export function matchesAllowlist(
+  patterns: string[],
+  server: string,
+  toolName: string,
+): boolean {
+  for (const raw of patterns) {
+    const pattern = raw.trim();
+    if (!pattern) continue;
+    if (pattern.startsWith("/") && pattern.lastIndexOf("/") > 0) {
+      const close = pattern.lastIndexOf("/");
+      const body = pattern.slice(1, close);
+      const flags = pattern.slice(close + 1);
+      try {
+        if (new RegExp(body, flags).test(toolName)) return true;
+      } catch {
+        // invalid regex — ignore this pattern
+      }
+      continue;
+    }
+    const [serverPat, toolPat] = pattern.includes("/")
+      ? pattern.split("/", 2)
+      : ["*", pattern];
+    if (wildcardEq(serverPat, server) && wildcardEq(toolPat, toolName)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function wildcardEq(pattern: string | undefined, value: string): boolean {
+  if (pattern === undefined || pattern === "*" || pattern === "") return true;
+  return pattern === value;
+}
+
 /**
  * Serialize a CallToolResult's content array into a plain text string.
  */

package/src/tools/mcp/exec.ts

@@ -1,4 +1,9 @@
+import {
+  ToolApprovalDeniedError,
+  ToolApprovalRequiredError,
+} from "@evantahler/mcpx";
 import { z } from "zod";
+import { ApprovalPendingError } from "../../approvals/errors.ts";
 import { formatCallToolResult } from "../../mcpx/client.ts";
 import { fakeMcpExec, isCaptureMode } from "../../worker/fake-mcp.ts";
 import { getTool, type ToolDefinition } from "../tool.ts";
@@ -131,6 +136,33 @@ export const mcpExecTool = {
           : undefined,
       };
     } catch (err) {
+      // Human-in-the-loop approval gate outcomes (see src/mcpx/client.ts).
+      if (err instanceof ApprovalPendingError) {
+        // Worker context: signal the loop to park this task as `waiting`.
+        ctx.onApprovalPending?.(err.approvalId);
+        return {
+          result: `This action is queued for human approval (id ${err.approvalId}).`,
+          is_error: true,
+          error_kind: "permanent" as const,
+          hint: `Awaiting approval. Call wait_task with a reason referencing approval ${err.approvalId}; the task will be re-queued automatically once a human approves or denies it.`,
+        };
+      }
+      if (err instanceof ToolApprovalDeniedError) {
+        return {
+          result: `This action was denied by a human reviewer (${input.server}/${input.tool}).`,
+          is_error: true,
+          error_kind: "permanent" as const,
+          hint: "Do not retry the same call — the human said no. Try a different approach, or call fail_task explaining that the required action was denied.",
+        };
+      }
+      if (err instanceof ToolApprovalRequiredError) {
+        return {
+          result: `This action requires approval, but no approver is wired up.`,
+          is_error: true,
+          error_kind: "permanent" as const,
+          hint: "The approval gate is active but no approver is available. Call fail_task; a human must re-run with --unsafe or allowlist this tool in config.",
+        };
+      }
       const { error_kind, hint } = classifyError(err);
       return {
         result: `MCP tool error: ${err}`,

package/src/tools/tool.ts

@@ -36,6 +36,13 @@ export interface ToolContext {
    * back to `logger.info` so worker logs are unchanged.
    */
   notify?: (message: string) => void;
+  /**
+   * Worker-mode only. Called by `mcp_exec` when a gated mcpx call has no
+   * decision yet and a pending `approvals/<id>.md` was written. The worker
+   * loop records the id and parks the task as `waiting` after the turn.
+   * Chat leaves this `undefined` (chat resolves approvals inline).
+   */
+  onApprovalPending?: (approvalId: string) => void;
 }
 
 type ToolOutputBase = { is_error: z.ZodBoolean };