@cohortapp/agent-sdk 2.3.0

package/lib/action-executor.js

@@ -0,0 +1,689 @@
+/**
+ * Maestro — Action Executor
+ *
+ * Executes tool calls from the Claude API. Write tools run agent-local
+ * scripts; lookup/RAG tools run targeted `claude --print` queries that
+ * leverage MCP servers (Gmail, Calendar, Slack, filesystem, etc.)
+ * via the agent's Max subscription.
+ *
+ * Usage:
+ *   import { executeAction } from "@cohortapp/agent-sdk/lib/action-executor.js";
+ *   const result = await executeAction("search_email", { query: "..." }, callerInfo, sessionId);
+ *
+ * @module action-executor
+ */
+
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  getToolNamesForAccessLevel,
+  normalizeAccessLevel,
+} from "./tool-definitions.js";
+import { isOrgTool, executeOrgTool } from "./org/tool-surface.mjs";
+import { resolveClaudeBin, augmentedPath } from "./claude-bin.mjs";
+
+const AGENT_ROOT = process.env.AGENT_ROOT || process.cwd();
+
+// The historical model for a lookup `claude --print` spawn. When the model
+// router is absent / inert / killed, lookups fall back to this exactly as
+// before (behaviour-preserving default).
+export const LOOKUP_DEFAULT_MODEL = "haiku";
+
+// ---------------------------------------------------------------------------
+// Spawn tuning constants (audit L25)
+// ---------------------------------------------------------------------------
+// These were previously inline magic numbers at each spawn site, which made
+// them invisible and impossible to tune per deployment. They are hoisted here
+// as named, env-overridable constants. A non-numeric / absent env var falls
+// back to the original default, so existing behaviour is preserved verbatim.
+
+/** Wall-clock budget for a lookup `claude --print` spawn (ms). */
+export const LOOKUP_TIMEOUT_MS =
+  Number(process.env.MAESTRO_LOOKUP_TIMEOUT_MS) || 25000;
+/** Max stdout buffer for a lookup `claude --print` spawn (bytes). */
+export const LOOKUP_MAX_BUFFER =
+  Number(process.env.MAESTRO_LOOKUP_MAX_BUFFER) || 1024 * 1024;
+/** Wall-clock budget for an agent-local write-script spawn (ms). */
+export const SCRIPT_TIMEOUT_MS =
+  Number(process.env.MAESTRO_SCRIPT_TIMEOUT_MS) || 15000;
+
+// ---------------------------------------------------------------------------
+// Access Control
+// ---------------------------------------------------------------------------
+
+// Privilege ranking (higher = more privileged). Anything not listed — which,
+// after normalisation, can only be "default" — ranks as least privilege.
+const ACCESS_LEVEL_RANK = { default: 0, voice: 1, leadership: 2, ceo: 3 };
+
+/**
+ * Resolve the EFFECTIVE access level for an action — defence-in-depth (audit M4).
+ *
+ * executeAction historically trusted whatever `accessLevel` the caller put on
+ * `callerInfo`. A compromised or buggy caller could therefore self-assert "ceo"
+ * and obtain CEO-only write tools. This helper derives the access level from
+ * authenticated provenance when it is available and CLAMPS a self-asserted level
+ * so it can never EXCEED the provenance-derived one.
+ *
+ * Contract (additive — existing callers keep working unchanged):
+ *   - If `callerInfo.verifiedAccessLevel` is present (provenance-derived), it is
+ *     the upper bound. The self-asserted `callerInfo.accessLevel` is honoured
+ *     only when it would NOT grant more privilege; otherwise it is clamped down
+ *     to the verified level. (A self-asserted level may narrow, never escalate.)
+ *   - Otherwise fall back to the self-asserted `callerInfo.accessLevel` (legacy
+ *     path).
+ *   - If nothing usable is provided, default to least privilege ("default").
+ *   - Unknown / badly-cased levels are normalised (never empty, never throw).
+ *
+ * Clamping is by privilege RANK, not string equality.
+ *
+ * @param {object|null|undefined} callerInfo - { slug, name, accessLevel, verifiedAccessLevel }
+ * @returns {string} A guaranteed-known access-level key (never empty).
+ */
+export function resolveEffectiveAccessLevel(callerInfo) {
+  const info = callerInfo && typeof callerInfo === "object" ? callerInfo : {};
+  const rankOf = (level) => ACCESS_LEVEL_RANK[normalizeAccessLevel(level)] ?? 0;
+
+  const verifiedRaw = info.verifiedAccessLevel;
+
+  // No authenticated provenance: trust the self-asserted level (legacy path),
+  // normalised to least privilege if unknown / absent.
+  if (verifiedRaw === undefined || verifiedRaw === null) {
+    return normalizeAccessLevel(info.accessLevel);
+  }
+
+  const verified = normalizeAccessLevel(verifiedRaw);
+
+  // Provenance present but no self-asserted level: the verified level is the
+  // baseline (nothing to clamp).
+  if (info.accessLevel === undefined || info.accessLevel === null) {
+    return verified;
+  }
+
+  const asserted = normalizeAccessLevel(info.accessLevel);
+
+  // Clamp: a self-asserted level may only narrow, never escalate, privilege.
+  if (rankOf(asserted) > rankOf(verified)) {
+    console.warn(
+      `[action-executor] Self-asserted access level ${JSON.stringify(
+        info.accessLevel,
+      )} exceeds verified level ${JSON.stringify(
+        verifiedRaw,
+      )}; clamping to verified.`,
+    );
+    return verified;
+  }
+
+  return asserted;
+}
+
+function isAuthorized(toolName, accessLevel) {
+  return getToolNamesForAccessLevel(accessLevel).includes(toolName);
+}
+
+// ---------------------------------------------------------------------------
+// Self-auditing (audit observability F1/F3)
+// ---------------------------------------------------------------------------
+
+// The PostToolUse shell hook (scripts/hooks/post-action-log.sh) only sees the
+// Bash/MCP tools Claude Code itself invokes — it never sees executeAction's
+// own dispatch (slack_send, draft_email, voice calls, …) or its authorization
+// denials. So executeAction writes its OWN audit row per invocation, including
+// DENIED attempts, into the same date-stamped stream. This is best-effort and
+// MUST never throw into the action path (a logging failure cannot break a
+// send), mirroring the fail-open discipline of every other log writer.
+
+/** Best-effort target for the audit row: first present, never throws. */
+function auditTarget(input) {
+  if (!input || typeof input !== "object") return null;
+  const cmd =
+    typeof input.command === "string" ? input.command.slice(0, 200) : undefined;
+  const t =
+    input.file_path ??
+    cmd ??
+    input.url ??
+    input.to ??
+    input.channel ??
+    input.recipient ??
+    null;
+  return t == null ? null : String(t);
+}
+
+/**
+ * Append one JSONL audit row for an executeAction invocation. Fail-open: any
+ * I/O or serialisation error is swallowed so logging can never break the
+ * action it is recording.
+ *
+ * EXPORTED (spec §1.5b) so the MCP tools/call dispatcher (lib/mcp/server.mjs)
+ * writes the SAME row shape into the SAME logs/audit/<date>-actions.jsonl
+ * stream for its plane — one row shape, both planes, no double-logging (the
+ * native path's rows are written here by executeAction; the MCP dispatcher
+ * writes its own with session_id "mcp:<pid>").
+ *
+ * @param {string} agentRoot
+ * @param {{tool:string,status:string,denied:boolean,input:object,sessionId:string}} row
+ */
+export function appendActionAudit(agentRoot, { tool, status, denied, input, sessionId }) {
+  try {
+    const auditDir = path.join(agentRoot, "logs", "audit");
+    fs.mkdirSync(auditDir, { recursive: true });
+    const date = new Date().toISOString().slice(0, 10);
+    const file = path.join(auditDir, `${date}-actions.jsonl`);
+    const entry = {
+      timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+      tool: typeof tool === "string" ? tool : String(tool ?? "unknown"),
+      status,
+      denied: Boolean(denied),
+      target: auditTarget(input),
+      session_id: sessionId == null ? null : String(sessionId),
+    };
+    fs.appendFileSync(file, JSON.stringify(entry) + "\n");
+  } catch {
+    /* best effort — never throw into the action path */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a tool call.
+ * @param {string} toolName
+ * @param {object} input
+ * @param {object} callerInfo - { slug, name, accessLevel, verifiedAccessLevel? }
+ * @param {string} sessionId
+ * @param {object} [options] - { agentRoot, scripts }
+ * @returns {Promise<{success: boolean, result: string}>}
+ */
+export async function executeAction(toolName, input, callerInfo, sessionId, options = {}) {
+  const agentRoot = options.agentRoot || AGENT_ROOT;
+
+  // Authorise against the EFFECTIVE access level (defence-in-depth, audit M4):
+  // derived from authenticated provenance when available, with any
+  // self-asserted level clamped so it cannot escalate privilege. Falls back to
+  // least privilege when nothing usable is provided.
+  const effectiveAccessLevel = resolveEffectiveAccessLevel(callerInfo);
+  if (!isAuthorized(toolName, effectiveAccessLevel)) {
+    appendActionAudit(agentRoot, {
+      tool: toolName,
+      status: "denied",
+      denied: true,
+      input,
+      sessionId,
+    });
+    return { success: false, result: "You do not have permission to perform this action." };
+  }
+
+  // Carry the agent identity (when the caller supplied one) into the lookup
+  // ledger rows so cost attribution joins to the right agent. Everything else
+  // about the lookup path stays on its fail-open defaults (lazy router import).
+  const lookupOpts = { agent: options.agent ?? callerInfo?.slug ?? null };
+
+  let outcome;
+  try {
+    // Org (Cohort) tools — the curated surface from lib/org/tool-surface.mjs.
+    // ONE executor shared with the cohort-mcp plane: config resolution
+    // (env-first, config-file fallback — the executor always runs inside an
+    // agent repo so config/org.yaml is the normal source), the outbound
+    // send-gate for messaging_send/email_send (and org_rpc passthroughs of
+    // those methods), and the org client's fail-open frame semantics. The
+    // access clamp above already covered authorization (name-set based), and
+    // the appendActionAudit call below records the row for the NATIVE plane.
+    if (isOrgTool(toolName)) {
+      const frame = await executeOrgTool(toolName, input, {
+        agentRoot,
+        fetchImpl: options.fetchImpl,
+        screenImpl: options.screenImpl,
+      });
+      outcome = frame.ok
+        ? {
+            success: true,
+            result:
+              typeof frame.result === "string"
+                ? frame.result
+                : JSON.stringify(frame.result ?? null, null, 2),
+            meta: frame.result,
+          }
+        : {
+            success: false,
+            result: `${(frame.error && frame.error.code) || "ERROR"}: ${(frame.error && frame.error.message) || "org call failed"}`,
+          };
+    }
+    // Lookup tools — RAG via Claude Code CLI. Only the public registry is
+    // dispatchable from here; INTERNAL_LOOKUP_PROMPTS entries are reached
+    // exclusively via their dedicated write-tool executors below.
+    else if (LOOKUP_PROMPTS[toolName]) {
+      outcome = await executeLookup(toolName, input, agentRoot, lookupOpts);
+    } else {
+      // Write tools — delegate to agent-local scripts
+      switch (toolName) {
+        case "slack_send":
+          outcome = await executeScript(agentRoot, "slack-send.sh", [input.recipient, input.message]);
+          break;
+        case "draft_email":
+          outcome = await executeDraft(agentRoot, input);
+          break;
+        case "whatsapp_send":
+          outcome = await executeScript(agentRoot, "send-whatsapp.sh", [input.recipient, input.message]);
+          break;
+        case "sms_send":
+          outcome = await executeScript(agentRoot, "send-sms.sh", [input.recipient, input.message]);
+          break;
+        case "send_voice_message":
+          outcome = await executeSendVoiceMessage(agentRoot, input);
+          break;
+        case "place_voice_call":
+          outcome = await executePlaceVoiceCall(agentRoot, input);
+          break;
+        case "rag_search":
+          outcome = await executeRagSearch(agentRoot, input);
+          break;
+        case "queue_update":
+          outcome = await executeQueueUpdate(agentRoot, input, lookupOpts);
+          break;
+        case "create_action_item":
+          outcome = await executeCreateItem(agentRoot, input, lookupOpts);
+          break;
+        case "schedule_meeting":
+          outcome = await executeLookup("schedule_meeting", input, agentRoot, lookupOpts);
+          break;
+        case "create_reminder":
+          outcome = await executeLookup("create_reminder", input, agentRoot, lookupOpts);
+          break;
+        case "generate_memo":
+          outcome = await executeGenerateMemo(agentRoot, input);
+          break;
+        case "generate_report":
+          outcome = await executeLookup("generate_report", input, agentRoot, lookupOpts);
+          break;
+        default:
+          outcome = { success: false, result: `Unknown tool: ${toolName}` };
+      }
+    }
+  } catch (err) {
+    outcome = { success: false, result: `Action failed: ${err.message}` };
+  }
+
+  appendActionAudit(agentRoot, {
+    tool: toolName,
+    status: outcome.success ? "completed" : "failed",
+    denied: false,
+    input,
+    sessionId,
+  });
+  return outcome;
+}
+
+// ---------------------------------------------------------------------------
+// Lookup / RAG via Claude Code CLI
+// ---------------------------------------------------------------------------
+
+// Public lookup tools — directly addressable by name from executeAction.
+const LOOKUP_PROMPTS = {
+  search_email: (i) =>
+    `Search Gmail for: "${i.query}". Return top ${i.max_results || 5} results with sender, subject, date, 1-sentence summary. Be concise — spoken aloud.`,
+  search_calendar: (i) =>
+    `Look up calendar: "${i.query}" for ${i.time_range || "this week"}. List events with title, time, attendees. Be concise.`,
+  search_files: (i) =>
+    `Search operational files for: "${i.query}"${i.scope && i.scope !== "all" ? ` in ${i.scope}/` : ""}. Summarise in 2-4 sentences.`,
+  search_meetings: (i) =>
+    `Search Granola meeting notes for: "${i.query}"${i.date_range ? ` from ${i.date_range}` : ""}. Summarise key discussions and decisions in 2-4 sentences.`,
+  search_slack: (i) =>
+    `Search Slack for: "${i.query}"${i.channel ? ` in ${i.channel}` : ""}. Summarise who said what, when. 2-4 sentences.`,
+  search_web: (i) =>
+    `Web search: "${i.query}". Summarise top ${i.max_results || 5} results concisely.`,
+  search_documents: (i) =>
+    `Search shared documents for: "${i.query}"${i.doc_type && i.doc_type !== "all" ? ` (${i.doc_type} only)` : ""}. List titles and brief summaries.`,
+  search_decisions: (i) =>
+    `Search the decision archive for: "${i.query}". Include rationale, who decided, and outcome. 2-4 sentences.`,
+  lookup_person: (i) =>
+    `Look up information about ${i.name}: ${i.info_type || "all available info"} — role, contact, recent activity. Be concise.`,
+  search_regulatory: (i) =>
+    `Search regulatory/compliance info for: "${i.query}"${i.jurisdiction ? ` in ${i.jurisdiction}` : ""}. Status, deadlines, requirements. Be concise.`,
+  search_strategy: (i) =>
+    `Search strategic context for: "${i.query}". Priorities, OKRs, initiative status. 2-4 sentences.`,
+  search_precedents: (i) =>
+    `Search operational precedents for: "${i.query}". How was this handled before? Templates? 2-4 sentences.`,
+  search_financial: (i) =>
+    `Search financial data for: "${i.query}". Runway, burn, capital readiness. Be concise.`,
+  search_pipeline: (i) =>
+    `Search pipeline for: "${i.query}"${i.stage && i.stage !== "all" ? ` (stage: ${i.stage})` : ""}. Deal status, partner conversations. Be concise.`,
+  search_engineering: (i) =>
+    `Search engineering health for: "${i.query}"${i.repo ? ` in ${i.repo}` : ""}. PRs, delivery confidence, blockers. Be concise.`,
+  search_hiring: (i) =>
+    `Search hiring pipeline for: "${i.query}"${i.status && i.status !== "all" ? ` (status: ${i.status})` : ""}. Roles, candidates, offers. Be concise.`,
+  search_risk: (i) =>
+    `Search risk register for: "${i.query}"${i.severity && i.severity !== "all" ? ` (severity: ${i.severity})` : ""}. Risks, mitigations, owners. Be concise.`,
+  schedule_meeting: (i) =>
+    `Schedule a meeting: "${i.title}" with ${i.attendees} on ${i.date}${i.time ? ` at ${i.time}` : ""}${i.duration ? ` for ${i.duration}` : ""}. Check availability and create the event. Confirm what was scheduled.`,
+  create_reminder: (i) =>
+    `Create a reminder: "${i.message}" for ${i.for_whom || "the principal"} at ${i.when}. Confirm when it will fire.`,
+  generate_report: (i) =>
+    `Generate a ${i.report_type} report${i.custom_query ? `: ${i.custom_query}` : ""}${i.time_range ? ` for ${i.time_range}` : ""}. Aggregate data from dashboards and queues. Format as a concise executive summary.`,
+};
+
+// Internal lookup prompts (audit L24). These were previously appended to
+// LOOKUP_PROMPTS via post-declaration mutation, which hid them from the
+// declared object literal and meant `const` only froze the binding, not the
+// shape. They live in their own clearly-named map; they are NOT directly
+// dispatchable from executeAction (the public LOOKUP_PROMPTS check above
+// excludes them) and are reached only by their dedicated write-tool
+// executors (executeQueueUpdate, executeCreateItem) which call executeLookup
+// with the internal name explicitly.
+const INTERNAL_LOOKUP_PROMPTS = {
+  queue_update_internal: (i) =>
+    `In the state/queues/ directory, find the item matching "${i.search_term}" and update its status to "${i.new_status}"${i.new_priority ? ` and priority to "${i.new_priority}"` : ""}${i.note ? `. Add note: "${i.note}"` : ""}. Confirm what was updated.`,
+  create_item_internal: (i) =>
+    `Create a new item in state/queues/${i.queue || "action-stack"}.yaml with title "${i.title}", priority "${i.priority || "high"}"${i.due_date ? `, due ${i.due_date}` : ""}${i.owner ? `, owner: ${i.owner}` : ""}${i.context ? `, context: "${i.context}"` : ""}. Use the existing YAML format. Confirm what was created.`,
+};
+
+/**
+ * Resolve the MODEL FLAG for a lookup spawn through the model router (#29
+ * residual): most lookup/RAG tools are Haiku-class, so routing the SELECTION
+ * lets the cheapest capable model serve them, and stamps a `decision_id` we can
+ * join to the cost ledger. This is a model-selection + cost-accounting upgrade
+ * ONLY — the spawn itself (a `claude --print` with MCP access) is unchanged.
+ *
+ * FAIL-OPEN by construction: the kill switch, the absence of a v2 config, or ANY
+ * router error all return the historical `haiku` default with no decision_id —
+ * the lookup never breaks because routing did.
+ *
+ * Injectable for tests (no real router import on the test path) via `opts`:
+ *   - opts.resolve(req, ropts) → RouteDecision (defaults to lazy resolveChain)
+ *   - opts.loadConfig(root)    → routing config or null (defaults to lazy loader)
+ *   - opts.env                 → env for the kill-switch probe (defaults process.env)
+ *
+ * @returns {Promise<{modelFlag:string, decision:object|null, decisionId:string|null,
+ *                     provider:string|null, model:string|null, ref:string|null,
+ *                     catalog:object|null}>}
+ */
+export async function resolveLookupModel(toolName, agentRoot, opts = {}) {
+  const fallback = {
+    modelFlag: LOOKUP_DEFAULT_MODEL,
+    decision: null,
+    decisionId: null,
+    provider: null,
+    model: null,
+    ref: null,
+    catalog: null,
+  };
+  try {
+    const env = opts.env || process.env || {};
+    // Kill switch: stock Anthropic, no router selection (mirrors resolveChain).
+    const force = env.MAESTRO_ROUTER_FORCE_ANTHROPIC;
+    if (force === "1" || force === "true") return fallback;
+
+    // Load the routing config — null when absent (preserve "current behaviour").
+    let config = opts.config;
+    if (config === undefined) {
+      const loadConfig =
+        opts.loadConfig ||
+        (async () => {
+          const m = await import("./model-router.mjs");
+          return m.loadRoutingConfig(agentRoot);
+        });
+      config = await loadConfig(agentRoot);
+    }
+    // Only the v2 router produces a model-selecting RouteDecision; anything else
+    // (no config, v1) keeps the historical default.
+    if (!config || config.schema_version !== 2) return fallback;
+
+    const resolveFn =
+      opts.resolve ||
+      (async (req, ropts) => {
+        const m = await import("./model-router/resolve.mjs");
+        return m.resolveChain(req, ropts);
+      });
+    const decision = await resolveFn(
+      {
+        task_class: "session.lookup",
+        // Lookups are tool-LESS RAG queries over MCP; they read sensitive
+        // mailboxes/calendars, so deny-default to sensitive.
+        data_class: "sensitive",
+        harness_hint: "session",
+        needs_tool_use: true,
+        source: "lookup",
+        lane: "realtime",
+      },
+      { config, agentRoot, env },
+    );
+    if (!decision || !decision.chosen) return fallback;
+
+    const sa = decision.spawnArgs || {};
+    const chosen = decision.chosen || {};
+    return {
+      modelFlag: sa.modelFlag || chosen.model || LOOKUP_DEFAULT_MODEL,
+      decision,
+      decisionId: decision.decision_id || null,
+      provider: chosen.provider || null,
+      model: chosen.model || null,
+      ref: (chosen.catalogRow && chosen.catalogRow.ref) || null,
+      catalog: (chosen.catalogRow && { byRef: { [chosen.catalogRow.ref]: chosen.catalogRow } }) || null,
+    };
+  } catch {
+    // Absolute fail-open: any router fault → the historical default model.
+    return fallback;
+  }
+}
+
+/**
+ * Write ONE ledger row for a lookup spawn (cost accounting). Best-effort and
+ * NEVER throws into the lookup path — a ledger we cannot persist degrades
+ * silently rather than failing the search. Injectable via `opts.writeLedger`.
+ */
+async function writeLookupLedger(toolName, agentRoot, routed, exitReason, opts = {}) {
+  // No router decision → nothing the v2 ledger can price; skip (preserves the
+  // no-config behaviour: a plain `--model haiku` spawn wrote no ledger row).
+  if (!routed || !routed.decisionId || !routed.ref) return;
+  try {
+    const writer =
+      opts.writeLedger ||
+      (async (catalog, entry, deps) => {
+        const m = await import("./model-router/ledger.mjs");
+        return m.writeLedgerRow(catalog, entry, deps);
+      });
+    // Use the REAL catalog (its byRef is a Map that lookupModel/estimateCost
+    // query) so the row is actually priced — a synthesized plain object would
+    // silently price every lookup at $0. Falls back to the routed snapshot.
+    let catalog = routed.catalog;
+    try {
+      const cm = await import("./model-router/catalog.mjs");
+      catalog = cm.loadCatalogCached(agentRoot) || routed.catalog;
+    } catch { /* keep the routed snapshot fallback */ }
+    await writer(
+      catalog,
+      {
+        agent: opts.agent ?? null,
+        decision_id: routed.decisionId,
+        task_class: "session.lookup",
+        source: "lookup",
+        lane: "realtime",
+        harness: "session",
+        ref: routed.ref,
+        provider: routed.provider,
+        model: routed.model,
+        inputTokens: opts.inputTokens || 0,
+        outputTokens: opts.outputTokens || 0,
+        exitReason,
+      },
+      opts.ledgerDeps || { agentRoot },
+    );
+  } catch {
+    /* a ledger we can't write must not fail the lookup */
+  }
+}
+
+export async function executeLookup(toolName, input, agentRoot, opts = {}) {
+  const promptBuilder = LOOKUP_PROMPTS[toolName] || INTERNAL_LOOKUP_PROMPTS[toolName];
+  if (!promptBuilder) return { success: false, result: `No prompt for: ${toolName}` };
+
+  const prompt = promptBuilder(input);
+
+  // Route the MODEL SELECTION (only) through the router; the spawn itself is
+  // unchanged. Fail-open: routing errors yield the historical `haiku` default.
+  const routed = await resolveLookupModel(toolName, agentRoot, opts);
+
+  try {
+    const { stdout } = await new Promise((resolve, reject) => {
+      execFile(resolveClaudeBin(), ["--print", "--model", routed.modelFlag, "-p", prompt], {
+        timeout: LOOKUP_TIMEOUT_MS,
+        maxBuffer: LOOKUP_MAX_BUFFER,
+        env: { ...process.env, TERM: "dumb", PATH: augmentedPath() },
+        cwd: agentRoot,
+      }, (err, stdout, stderr) => {
+        if (err) reject(err);
+        else resolve({ stdout, stderr });
+      });
+    });
+
+    // Estimate usage from the text in hand (~4 chars/token) so the ledger row is
+    // actually priced, not $0 — a lookup is a one-shot, no usage envelope to parse.
+    const estTok = (s) => Math.ceil(String(s || "").length / 4);
+    await writeLookupLedger(toolName, agentRoot, routed, "ok", {
+      ...opts, inputTokens: opts.inputTokens || estTok(prompt), outputTokens: opts.outputTokens || estTok(stdout),
+    });
+    return { success: true, result: (stdout || "").trim() || "No results found." };
+  } catch (err) {
+    await writeLookupLedger(toolName, agentRoot, routed, err.killed ? "timeout" : "error", { ...opts, inputTokens: opts.inputTokens || Math.ceil(String(prompt || "").length / 4) });
+    if (err.killed) return { success: false, result: "Search timed out. Try a more specific query." };
+    return { success: false, result: `Search failed: ${err.message}` };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write tool executors (generic implementations — agents can override)
+// ---------------------------------------------------------------------------
+
+async function executeScript(agentRoot, scriptName, args) {
+  const scriptPath = path.join(agentRoot, "scripts", scriptName);
+  if (!fs.existsSync(scriptPath)) {
+    return { success: false, result: `Script not found: ${scriptName}` };
+  }
+
+  return new Promise((resolve) => {
+    execFile("bash", [scriptPath, ...args.filter(Boolean)], {
+      timeout: SCRIPT_TIMEOUT_MS,
+      cwd: agentRoot,
+      env: { ...process.env },
+    }, (err, stdout, stderr) => {
+      if (err) resolve({ success: false, result: stderr || err.message });
+      else resolve({ success: true, result: stdout.trim() || "Done." });
+    });
+  });
+}
+
+async function executeDraft(agentRoot, input) {
+  const draftsDir = path.join(agentRoot, "outputs/drafts");
+  fs.mkdirSync(draftsDir, { recursive: true });
+
+  const date = new Date().toISOString().split("T")[0];
+  const slug = input.to.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase();
+  const filePath = path.join(draftsDir, `${date}-draft-${slug}.md`);
+
+  const content = `---\nto: ${input.to}\nsubject: ${input.subject}\nvoice: ${input.voice || "agent"}\nurgency: ${input.urgency || "routine"}\ndate: ${new Date().toISOString()}\n---\n\n${input.body}\n`;
+  fs.writeFileSync(filePath, content);
+
+  if (input.urgency === "immediate") {
+    return executeScript(agentRoot, "send-email.sh", [input.to, input.subject, input.body]);
+  }
+
+  return { success: true, result: `Draft saved: ${filePath}` };
+}
+
+async function executeQueueUpdate(agentRoot, input, opts = {}) {
+  // Delegate to claude CLI for intelligent queue searching and updating.
+  // queue_update_internal lives in INTERNAL_LOOKUP_PROMPTS (audit L24).
+  return executeLookup("queue_update_internal", input, agentRoot, opts);
+}
+
+async function executeCreateItem(agentRoot, input, opts = {}) {
+  // create_item_internal lives in INTERNAL_LOOKUP_PROMPTS (audit L24).
+  return executeLookup("create_item_internal", input, agentRoot, opts);
+}
+
+async function executeGenerateMemo(agentRoot, input) {
+  const draftsDir = path.join(agentRoot, "outputs/drafts");
+  fs.mkdirSync(draftsDir, { recursive: true });
+
+  const slug = input.title.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase().slice(0, 40);
+  const filePath = path.join(draftsDir, `${new Date().toISOString().split("T")[0]}-${slug}.md`);
+  fs.writeFileSync(filePath, `# ${input.title}\n\n${input.content}\n`);
+
+  return { success: true, result: `Memo saved to ${filePath}` };
+}
+
+// ---------------------------------------------------------------------------
+// Voice — outbound TTS messages + live conversational PSTN
+// ---------------------------------------------------------------------------
+
+async function executeSendVoiceMessage(agentRoot, input) {
+  try {
+    const { sendVoiceMessage } = await import("./voice/outbound.mjs");
+    const result = await sendVoiceMessage({
+      to: input.to,
+      text: input.text,
+      transport: input.transport,
+      voice: input.voice,
+      agentRoot,
+    });
+    return {
+      success: true,
+      result:
+        `Voice message delivered via ${result.transport} (${result.audio_bytes} bytes, ` +
+        `~$${result.cost_usd}). message_id=${result.message_id}`,
+      meta: result,
+    };
+  } catch (err) {
+    return { success: false, result: `send_voice_message failed: ${err.message}` };
+  }
+}
+
+async function executeRagSearch(agentRoot, input) {
+  try {
+    const { search } = await import("./rag/search.mjs");
+    const hits = await search({
+      query: input.query,
+      topN: Math.min(input.top_n || 5, 20),
+      kind: input.kind,
+      agentRoot,
+    });
+    if (hits.length === 0) {
+      return { success: true, result: `No matches for "${input.query}" in the indexed corpus. Try fewer / different terms, or run scripts/rag/build-index.mjs to refresh the index.` };
+    }
+    const formatted = hits.map((h, i) =>
+      `${i + 1}. ${h.source_path} (${h.kind}, rel=${h.relevance.toFixed(2)})` +
+      `\n   title: ${h.title}` +
+      (h.heading ? `\n   section: ${h.heading}` : "") +
+      `\n   snippet: ${h.snippet.replace(/\s+/g, " ").slice(0, 240)}`
+    ).join("\n");
+    return {
+      success: true,
+      result: `Found ${hits.length} match(es) for "${input.query}":\n${formatted}`,
+      meta: { hits },
+    };
+  } catch (err) {
+    return { success: false, result: `rag_search failed: ${err.message}` };
+  }
+}
+
+async function executePlaceVoiceCall(agentRoot, input) {
+  try {
+    const { placeOutboundCall } = await import("./voice/outbound.mjs");
+    const result = await placeOutboundCall({
+      to: input.to,
+      brief: input.brief,
+      voice: input.voice,
+      agentRoot,
+    });
+    return {
+      success: true,
+      result:
+        `Outbound call initiated. call_id=${result.call_id}, twilio_sid=${result.twilio_call_sid}, ` +
+        `status=${result.status}. Transcript will appear in state/inbox/voice/ when the call ends.`,
+      meta: result,
+    };
+  } catch (err) {
+    return { success: false, result: `place_voice_call failed: ${err.message}` };
+  }
+}