botholomew 0.22.2 → 0.24.0

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;
@@ -30,6 +51,8 @@ export interface BotholomewConfig {
   schedule_min_interval_seconds: number;
   schedule_claim_stale_seconds: number;
   tui_idle_timeout_seconds: number;
+  /** Default window (in hours) of recent threads the `dream` reflection reviews when `--since` is omitted. */
+  dream_lookback_hours: number;
   log_level: string;
   membot_scope: Scope;
   mcpx_scope: Scope;
@@ -49,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,
@@ -65,6 +95,7 @@ export const DEFAULT_CONFIG: BotholomewConfig = {
   schedule_min_interval_seconds: 60,
   schedule_claim_stale_seconds: 300,
   tui_idle_timeout_seconds: 180,
+  dream_lookback_hours: 24,
   log_level: "",
   membot_scope: "global",
   mcpx_scope: "global",

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/skills/commands.ts

@@ -1,3 +1,4 @@
+import { DREAM_PROMPT_BODY } from "../chat/dream-prompt.ts";
 import type { SkillDefinition } from "./parser.ts";
 import { renderSkill, tokenizeForSkill, validateSkillArgs } from "./parser.ts";
 
@@ -10,6 +11,11 @@ export interface SlashCommand {
 export const BUILTIN_SLASH_COMMANDS: SlashCommand[] = [
   { name: "help", description: "Show command reference and shortcuts" },
   { name: "skills", description: "List available skills" },
+  {
+    name: "dream",
+    description:
+      "Reflect on recent threads: consolidate learnings and update beliefs/goals",
+  },
   { name: "clear", description: "End current thread and start a new one" },
   { name: "exit", description: "End the chat session" },
 ];
@@ -120,6 +126,14 @@ export function handleSlashCommand(
     return true;
   }
 
+  if (name === "dream") {
+    // Built-in (not a user-editable skill) so reflection behaves consistently.
+    // Queue the reflection prompt as a normal user message — the chat agent
+    // already has every tool it needs (thread search, membot, prompt_edit).
+    ctx.queueUserMessage(DREAM_PROMPT_BODY, { display: input });
+    return true;
+  }
+
   if (name === "skills") {
     if (ctx.skills.size === 0) {
       ctx.addSystemMessage("No skills loaded. Add .md files to skills/");

package/src/tasks/store.ts

@@ -302,7 +302,7 @@ export async function resetStaleTasks(
   const reset: string[] = [];
   for (const id of ids) {
     const t = await getTask(projectDir, id);
-    if (!t || t.status !== "in_progress") continue;
+    if (t?.status !== "in_progress") continue;
     const claimedAt = t.claimed_at ? Date.parse(t.claimed_at) : Date.now();
     if (claimedAt >= cutoff) continue;
     const fm: TaskFrontmatter = {
@@ -365,7 +365,7 @@ export async function claimSpecificTask(
   workerId: string,
 ): Promise<Task | null> {
   const t = await getTask(projectDir, id);
-  if (!t || t.status !== "pending") return null;
+  if (t?.status !== "pending") return null;
   return tryClaim(projectDir, id, workerId);
 }
 
@@ -383,7 +383,7 @@ async function tryClaim(
   }
   try {
     const t = await getTask(projectDir, id);
-    if (!t || t.status !== "pending") {
+    if (t?.status !== "pending") {
       await releaseLock(lockPath);
       return null;
     }
@@ -427,7 +427,7 @@ async function isUnblocked(projectDir: string, t: Task): Promise<boolean> {
   if (t.blocked_by.length === 0) return true;
   for (const blockerId of t.blocked_by) {
     const blocker = await getTask(projectDir, blockerId);
-    if (!blocker || blocker.status !== "complete") return false;
+    if (blocker?.status !== "complete") return false;
   }
   return true;
 }

package/src/threads/store.ts

@@ -456,6 +456,108 @@ export async function listThreads(
   return out.slice(offset, offset + limit);
 }
 
+export interface ThreadSearchHit {
+  thread_id: string;
+  thread_title: string;
+  thread_type: ThreadType;
+  /** 1-based sequence of the matching interaction. Plug into `view_thread({ id, offset: sequence-1 })`. */
+  sequence: number;
+  role: InteractionRole;
+  kind: InteractionKind;
+  content_snippet: string;
+  created_at: Date;
+}
+
+export interface ThreadSearchOptions {
+  /** Compiled regex matched against content, tool_name, and tool_input. */
+  regex: RegExp;
+  role?: InteractionRole;
+  kind?: InteractionKind;
+  type?: ThreadType;
+  /** Only consider threads started on or after this date. */
+  since?: Date;
+  /** Only consider threads started on or before this date. */
+  until?: Date;
+  /** Maximum number of hits to return across all threads. */
+  maxResults?: number;
+}
+
+/**
+ * Scan past conversations for a regex match. Shared by the `search_threads`
+ * agent tool and the `botholomew thread search` CLI so both stay in lockstep.
+ * Returns hits with `(thread_id, sequence)` pairs and the count of threads
+ * actually opened.
+ */
+export async function searchThreads(
+  projectDir: string,
+  opts: ThreadSearchOptions,
+): Promise<{ hits: ThreadSearchHit[]; threadsScanned: number }> {
+  const sinceMs = opts.since ? opts.since.getTime() : Number.NEGATIVE_INFINITY;
+  const untilMs = opts.until ? opts.until.getTime() : Number.POSITIVE_INFINITY;
+  const maxResults = opts.maxResults ?? 20;
+
+  const threads = await listThreads(projectDir, { type: opts.type });
+  const hits: ThreadSearchHit[] = [];
+  let scanned = 0;
+
+  for (const t of threads) {
+    const startedMs = t.started_at.getTime();
+    if (startedMs < sinceMs || startedMs > untilMs) continue;
+    const data = await getThread(projectDir, t.id);
+    if (!data) continue;
+    scanned++;
+    for (const ix of data.interactions) {
+      if (opts.role && ix.role !== opts.role) continue;
+      if (opts.kind && ix.kind !== opts.kind) continue;
+      if (!matchInteraction(ix, opts.regex)) continue;
+      hits.push({
+        thread_id: t.id,
+        thread_title: t.title || "(untitled)",
+        thread_type: t.type,
+        sequence: ix.sequence,
+        role: ix.role,
+        kind: ix.kind,
+        content_snippet: snippetForMatch(ix.content, opts.regex),
+        created_at: ix.created_at,
+      });
+      if (hits.length >= maxResults) break;
+    }
+    if (hits.length >= maxResults) break;
+  }
+
+  return { hits, threadsScanned: scanned };
+}
+
+const SNIPPET_MAX = 240;
+
+function matchInteraction(ix: Interaction, regex: RegExp): boolean {
+  // We treat the user-visible content as the primary haystack, but a
+  // tool_use interaction's content is just "Calling <name>" — fall through
+  // to the tool name + JSON args so a search for an exact tool argument
+  // still finds the call.
+  if (regex.test(ix.content)) return true;
+  if (ix.tool_name && regex.test(ix.tool_name)) return true;
+  if (ix.tool_input && regex.test(ix.tool_input)) return true;
+  return false;
+}
+
+/**
+ * Pick a short window around the first regex match so callers get enough
+ * context to know whether the hit is relevant without paging the whole
+ * interaction. Falls back to the head when the match index isn't available.
+ */
+function snippetForMatch(content: string, regex: RegExp): string {
+  const m = regex.exec(content);
+  if (!m) return content.slice(0, SNIPPET_MAX);
+  const idx = m.index;
+  const start = Math.max(0, idx - 60);
+  const end = Math.min(content.length, idx + SNIPPET_MAX - 60);
+  let snippet = content.slice(start, end);
+  if (start > 0) snippet = `…${snippet}`;
+  if (end < content.length) snippet = `${snippet}…`;
+  return snippet;
+}
+
 // ---------------------------------------------------------------------------
 // internals
 // ---------------------------------------------------------------------------

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/skill/write.ts

@@ -30,7 +30,7 @@ const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Skill name (slash-command identifier). Will be normalized to lowercase + [a-z0-9-]. Reserved: help, skills, clear, exit.",
+      "Skill name (slash-command identifier). Will be normalized to lowercase + [a-z0-9-]. Reserved: help, skills, dream, clear, exit.",
     ),
   description: z
     .string()
@@ -67,7 +67,7 @@ const outputSchema = z.object({
 export const skillWriteTool = {
   name: "skill_write",
   description:
-    "[[ bash equivalent command: tee ]] Create or overwrite a skill file (user-defined slash command) at skills/<name>.md. Fails with path_conflict when the file exists unless on_conflict='overwrite'. Reserved names (help, skills, clear, exit) are rejected. The generated file is parsed to validate before being written.",
+    "[[ bash equivalent command: tee ]] Create or overwrite a skill file (user-defined slash command) at skills/<name>.md. Fails with path_conflict when the file exists unless on_conflict='overwrite'. Reserved names (help, skills, dream, clear, exit) are rejected. The generated file is parsed to validate before being written.",
   group: "skill",
   inputSchema,
   outputSchema,
@@ -78,7 +78,7 @@ export const skillWriteTool = {
         nameCheck.reason === "reserved" ? "reserved_name" : "invalid_name";
       const message =
         nameCheck.reason === "reserved"
-          ? `'${input.name}' is reserved by a built-in slash command (help, skills, clear, exit).`
+          ? `'${input.name}' is reserved by a built-in slash command (help, skills, dream, clear, exit).`
           : nameCheck.reason === "too_long"
             ? `Skill name too long (max 64 chars after normalization).`
             : `'${input.name}' is not a valid skill name. After normalization (lowercase, [a-z0-9-], trimmed hyphens) it is empty.`;

package/src/tools/thread/search.ts

@@ -1,11 +1,8 @@
 import { z } from "zod";
 import {
-  getThread,
-  type Interaction,
   type InteractionKind,
   type InteractionRole,
-  listThreads,
-  type Thread,
+  searchThreads,
 } from "../../threads/store.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -19,8 +16,6 @@ const KINDS = [
   "status_change",
 ] as const;
 
-const SNIPPET_MAX = 240;
-
 const inputSchema = z.object({
   pattern: z
     .string()
@@ -112,17 +107,16 @@ export const searchThreadsTool = {
       };
     }
 
-    const sinceMs = input.since
-      ? Date.parse(input.since)
-      : Number.NEGATIVE_INFINITY;
-    const untilMs = input.until
-      ? Date.parse(input.until)
-      : Number.POSITIVE_INFINITY;
-
-    let threads: Thread[];
+    let scanResult: Awaited<ReturnType<typeof searchThreads>>;
     try {
-      threads = await listThreads(ctx.projectDir, {
+      scanResult = await searchThreads(ctx.projectDir, {
+        regex,
+        role: input.role,
+        kind: input.kind,
         type: input.thread_type,
+        since: input.since ? new Date(input.since) : undefined,
+        until: input.until ? new Date(input.until) : undefined,
+        maxResults: input.max_results,
       });
     } catch (err) {
       return {
@@ -134,75 +128,29 @@ export const searchThreadsTool = {
       };
     }
 
-    type Hit = z.infer<typeof HitSchema>;
-    const matches: Hit[] = [];
-    let scanned = 0;
-
-    for (const t of threads) {
-      const startedMs = t.started_at.getTime();
-      if (startedMs < sinceMs || startedMs > untilMs) continue;
-      const data = await getThread(ctx.projectDir, t.id);
-      if (!data) continue;
-      scanned++;
-      for (const ix of data.interactions) {
-        if (input.role && ix.role !== input.role) continue;
-        if (input.kind && ix.kind !== input.kind) continue;
-        if (!matchInteraction(ix, regex)) continue;
-        matches.push({
-          thread_id: t.id,
-          thread_title: t.title || "(untitled)",
-          thread_type: t.type,
-          sequence: ix.sequence,
-          role: ix.role,
-          kind: ix.kind,
-          content_snippet: snippetForMatch(ix.content, regex),
-          created_at: ix.created_at.toISOString(),
-        });
-        if (matches.length >= input.max_results) break;
-      }
-      if (matches.length >= input.max_results) break;
-    }
+    const matches = scanResult.hits.map((h) => ({
+      thread_id: h.thread_id,
+      thread_title: h.thread_title,
+      thread_type: h.thread_type,
+      sequence: h.sequence,
+      role: h.role,
+      kind: h.kind,
+      content_snippet: h.content_snippet,
+      created_at: h.created_at.toISOString(),
+    }));
 
     return {
       matches,
-      threads_scanned: scanned,
+      threads_scanned: scanResult.threadsScanned,
       is_error: false,
       next_action_hint:
         matches.length === 0
-          ? `No hits in ${scanned} thread(s). Try a broader pattern or remove role/kind filters.`
+          ? `No hits in ${scanResult.threadsScanned} thread(s). Try a broader pattern or remove role/kind filters.`
           : `Pass any (thread_id, sequence) into view_thread({ id: thread_id, offset: sequence - 1, limit: 5 }) to read surrounding context.`,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;
 
-function matchInteraction(ix: Interaction, regex: RegExp): boolean {
-  // We treat the user-visible content as the primary haystack, but a
-  // tool_use interaction's content is just "Calling <name>" — fall through
-  // to the tool name + JSON args so a search for an exact tool argument
-  // still finds the call.
-  if (regex.test(ix.content)) return true;
-  if (ix.tool_name && regex.test(ix.tool_name)) return true;
-  if (ix.tool_input && regex.test(ix.tool_input)) return true;
-  return false;
-}
-
-/**
- * Pick a short window around the first regex match so the agent gets enough
- * context to know whether the hit is relevant without paging the whole
- * interaction. Falls back to the head when the match index isn't available.
- */
-function snippetForMatch(content: string, regex: RegExp): string {
-  const m = regex.exec(content);
-  if (!m) return content.slice(0, SNIPPET_MAX);
-  const idx = m.index;
-  const start = Math.max(0, idx - 60);
-  const end = Math.min(content.length, idx + SNIPPET_MAX - 60);
-  let snippet = content.slice(start, end);
-  if (start > 0) snippet = `…${snippet}`;
-  if (end < content.length) snippet = `${snippet}…`;
-  return snippet;
-}
-
 // Keep the role/kind unions exported for tests that want to type-pin filters.
 export type SearchThreadsRole = InteractionRole;
 export type SearchThreadsKind = InteractionKind;

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 };