toolfunnel 0.3.0

package/src/mcp/expose-store.js

@@ -0,0 +1,430 @@
+'use strict';
+
+/**
+ * expose-store.js — the persisted MCP config store (the architecture notes and
+ * the extension guide define the authoritative shape).
+ *
+ * This is a PURE, config-only module: no process spawning, no network, no MCP
+ * client. It is the on-disk source of truth that the (Phase 2) aggregator reads
+ * to know WHICH upstream MCPs to connect to and WHICH of their tools to surface
+ * downstream as curated-direct tools. Editing this store is how a human/model
+ * authors the MCP surface; the aggregator just consumes the result.
+ *
+ * Persisted file shape (src/mcp/expose.json):
+ *   {
+ *     "version": 1,
+ *     "upstreams": [
+ *       { id, transport:"stdio", command, args:[], env:{}, enabled:bool, description }
+ *     ],
+ *     "expose": [
+ *       { upstream, tool, as, category, enabled:bool }
+ *     ]
+ *   }
+ *
+ * Two blocks (per the extension guide):
+ *   - upstreams[]  — one entry per upstream MCP. `id` is the stable key referenced
+ *                    by expose[].upstream. `transport:"stdio"` spawns command+args.
+ *   - expose[]     — which upstream tools become curated-direct. `(upstream,tool)`
+ *                    is the natural key; `as` is the downstream name the CLI sees
+ *                    (defaults to `<upstream>_<tool>` so two upstreams can't collide).
+ *
+ * Read/write discipline (mirrors src/tools/registry.js — the safety contract):
+ *   - READS never throw and always return CLONES (callers cannot mutate internal
+ *     state, and a missing file is simply an empty store).
+ *   - WRITES validate and throw a clear error on a bad write; nothing is persisted
+ *     when validation fails.
+ *   - Persistence is ATOMIC: a temp file in the SAME directory, fsync, then rename
+ *     over the target (copied exactly from registry.js::atomicWriteJson). A crash
+ *     leaves either the old file or the new file, never a half-written config.
+ *   - loadExposeStore on a MISSING file returns an empty store bound to the path;
+ *     the file is NOT created until the first write (keeps the server starting
+ *     clean with no live upstreams).
+ *
+ * CommonJS only. Node built-ins only. No new npm dependency.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VALID_TRANSPORTS = new Set(['stdio']);
+
+/** Deep-ish clone for plain JSON values (structuredClone may be absent on old node). */
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * Atomic write: serialise to a temp file in the SAME directory as the target (so
+ * the rename is atomic on the same filesystem/drive), fsync, then rename over the
+ * target. Copied verbatim from src/tools/registry.js so the two stores share one
+ * proven persistence pattern.
+ */
+function atomicWriteJson(targetPath, obj) {
+  const dir = path.dirname(targetPath);
+  const base = path.basename(targetPath);
+  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
+  const data = JSON.stringify(obj, null, 2) + '\n';
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, data, 0, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, targetPath);
+}
+
+/** True for a non-empty string. */
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+/**
+ * Normalise a raw upstream object into the canonical shape, filling sane defaults
+ * for the optional fields. Does NOT validate — used both on load (lenient) and as
+ * the base for write-validation. Always returns a fresh object.
+ */
+function normaliseUpstream(raw) {
+  const u = raw && typeof raw === 'object' ? raw : {};
+  return {
+    id: typeof u.id === 'string' ? u.id : '',
+    transport: typeof u.transport === 'string' ? u.transport : 'stdio',
+    command: typeof u.command === 'string' ? u.command : '',
+    args: Array.isArray(u.args) ? u.args.slice() : [],
+    env: u.env && typeof u.env === 'object' && !Array.isArray(u.env) ? { ...u.env } : {},
+    enabled: typeof u.enabled === 'boolean' ? u.enabled : true,
+    description: typeof u.description === 'string' ? u.description : '',
+  };
+}
+
+/**
+ * Normalise a raw expose object into the canonical shape. `as` is left as-is (may
+ * be empty); exposedName() / addExpose() apply the `<upstream>_<tool>` default so
+ * the stored entry can carry an explicit override or fall back lazily.
+ */
+function normaliseExpose(raw) {
+  const e = raw && typeof raw === 'object' ? raw : {};
+  return {
+    upstream: typeof e.upstream === 'string' ? e.upstream : '',
+    tool: typeof e.tool === 'string' ? e.tool : '',
+    as: typeof e.as === 'string' ? e.as : '',
+    category: typeof e.category === 'string' ? e.category : '',
+    enabled: typeof e.enabled === 'boolean' ? e.enabled : true,
+  };
+}
+
+/**
+ * Validate an upstream entry for a WRITE. Throws a clear error on a bad shape.
+ *  - id must be a non-empty string and unique among the OTHER upstreams.
+ *  - transport must be 'stdio' (the only baseline transport).
+ *  - a stdio upstream requires a non-empty command.
+ * @param {object} entry        normalised upstream
+ * @param {Map}    byId         existing upstreams keyed by id (for uniqueness)
+ * @param {string} [ignoreId]   an id to skip in the uniqueness check (updates)
+ */
+function validateUpstream(entry, byId, ignoreId) {
+  if (!isNonEmptyString(entry.id)) {
+    throw new Error('ExposeStore: upstream.id must be a non-empty string');
+  }
+  if (byId.has(entry.id) && entry.id !== ignoreId) {
+    throw new Error(`ExposeStore: upstream id "${entry.id}" already exists`);
+  }
+  if (!VALID_TRANSPORTS.has(entry.transport)) {
+    throw new Error(
+      `ExposeStore: upstream.transport must be one of ${[...VALID_TRANSPORTS].join('|')} (id=${entry.id})`
+    );
+  }
+  if (entry.transport === 'stdio' && !isNonEmptyString(entry.command)) {
+    throw new Error(`ExposeStore: stdio upstream needs a non-empty "command" (id=${entry.id})`);
+  }
+  return entry;
+}
+
+class ExposeStore {
+  /**
+   * @param {object} opts
+   * @param {string} opts.filePath  path to expose.json (source of truth on disk)
+   * @param {object} [opts.data]    parsed config { version, upstreams, expose }
+   */
+  constructor({ filePath, data } = {}) {
+    if (!isNonEmptyString(filePath)) throw new Error('ExposeStore: filePath is required');
+    this._filePath = filePath;
+
+    const d = data && typeof data === 'object' ? data : {};
+    this._version = typeof d.version === 'number' ? d.version : 1;
+
+    // Index upstreams by id; reject duplicate ids at load (a duplicate id makes
+    // getUpstream / cascade-remove ambiguous). Keep insertion order via the Map.
+    this._upstreams = new Map();
+    const rawUpstreams = Array.isArray(d.upstreams) ? d.upstreams : [];
+    for (const raw of rawUpstreams) {
+      const u = normaliseUpstream(raw);
+      if (!isNonEmptyString(u.id)) {
+        throw new Error(`ExposeStore: an upstream is missing its id in ${filePath}`);
+      }
+      if (this._upstreams.has(u.id)) {
+        throw new Error(`ExposeStore: duplicate upstream id "${u.id}" in ${filePath}`);
+      }
+      this._upstreams.set(u.id, u);
+    }
+
+    // expose[] is kept as an ordered array; the natural key is (upstream,tool).
+    // Reject duplicate (upstream,tool) pairs at load.
+    this._expose = [];
+    const seenExpose = new Set();
+    const rawExpose = Array.isArray(d.expose) ? d.expose : [];
+    for (const raw of rawExpose) {
+      const e = normaliseExpose(raw);
+      const key = `${e.upstream} ${e.tool}`;
+      if (seenExpose.has(key)) {
+        throw new Error(
+          `ExposeStore: duplicate expose entry (upstream="${e.upstream}", tool="${e.tool}") in ${filePath}`
+        );
+      }
+      seenExpose.add(key);
+      this._expose.push(e);
+    }
+  }
+
+  // ── upstreams: read API (clones, never throw) ─────────────────────────────
+
+  /** @returns {Array<{id,transport,command,args,env,enabled,description}>} cloned, in order. */
+  listUpstreams() {
+    return [...this._upstreams.values()].map(clone);
+  }
+
+  /** @returns {object|undefined} cloned upstream entry, or undefined if unknown. */
+  getUpstream(id) {
+    const u = this._upstreams.get(id);
+    return u ? clone(u) : undefined;
+  }
+
+  // ── upstreams: write API (validate + atomic persist) ──────────────────────
+
+  /**
+   * Add an upstream. Validates: unique non-empty id; transport === 'stdio';
+   * stdio requires a non-empty command. Persists atomically. Returns the clone.
+   */
+  addUpstream(entry) {
+    const u = normaliseUpstream(entry);
+    validateUpstream(u, this._upstreams);
+    this._upstreams.set(u.id, u);
+    this._persist();
+    return clone(u);
+  }
+
+  /**
+   * Shallow-merge `patch` over an existing upstream. `id` is immutable (the key);
+   * any `id` in the patch is ignored. Re-validates the merged result and persists.
+   */
+  updateUpstream(id, patch) {
+    const existing = this._upstreams.get(id);
+    if (!existing) throw new Error(`ExposeStore.updateUpstream: unknown upstream id "${id}"`);
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+      throw new Error('ExposeStore.updateUpstream: patch must be an object');
+    }
+    const merged = normaliseUpstream({ ...existing, ...patch, id });
+    validateUpstream(merged, this._upstreams, id);
+    this._upstreams.set(id, merged);
+    this._persist();
+    return clone(merged);
+  }
+
+  /**
+   * Remove an upstream AND cascade-remove any expose[] entries whose `upstream`
+   * matches this id (a dangling expose entry would reference a missing upstream).
+   * Persists atomically. Throws on an unknown id.
+   * @returns {true}
+   */
+  removeUpstream(id) {
+    if (!this._upstreams.has(id)) {
+      throw new Error(`ExposeStore.removeUpstream: unknown upstream id "${id}"`);
+    }
+    this._upstreams.delete(id);
+    this._expose = this._expose.filter((e) => e.upstream !== id);
+    this._persist();
+    return true;
+  }
+
+  /** Toggle an upstream's `enabled` flag; persists. Throws on unknown id. */
+  setUpstreamEnabled(id, enabled) {
+    return this.updateUpstream(id, { enabled: !!enabled });
+  }
+
+  // ── expose: read API (clones, never throw) ────────────────────────────────
+
+  /**
+   * List exposed entries. Optional filters:
+   *   - `upstream`    restrict to one upstream id.
+   *   - `enabledOnly` only entries with enabled === true.
+   * @returns {Array<{upstream,tool,as,category,enabled}>} cloned, in order.
+   */
+  listExposed({ upstream, enabledOnly } = {}) {
+    const out = [];
+    for (const e of this._expose) {
+      if (upstream && e.upstream !== upstream) continue;
+      if (enabledOnly && e.enabled !== true) continue;
+      out.push(clone(e));
+    }
+    return out;
+  }
+
+  /** @returns {object|undefined} cloned expose entry for (upstream,tool), or undefined. */
+  getExposed(upstream, tool) {
+    const e = this._findExpose(upstream, tool);
+    return e ? clone(e) : undefined;
+  }
+
+  /**
+   * The downstream name the CLI sees for an expose entry: explicit `as` if set,
+   * else the namespaced default `<upstream>_<tool>`.
+   * @param {{upstream,tool,as?}} e
+   * @returns {string}
+   */
+  exposedName(e) {
+    const obj = e && typeof e === 'object' ? e : {};
+    if (isNonEmptyString(obj.as)) return obj.as;
+    return `${obj.upstream}_${obj.tool}`;
+  }
+
+  // ── expose: write API (validate + atomic persist) ─────────────────────────
+
+  /**
+   * Add an expose entry. Validates: the `upstream` must EXIST; `tool` must be a
+   * non-empty string; `(upstream,tool)` must be unique. `as` defaults to the
+   * namespaced `<upstream>_<tool>`. Persists atomically. Returns the clone.
+   */
+  addExpose(entry) {
+    const e = normaliseExpose(entry);
+    if (!isNonEmptyString(e.upstream)) {
+      throw new Error('ExposeStore.addExpose: expose.upstream must be a non-empty string');
+    }
+    if (!this._upstreams.has(e.upstream)) {
+      throw new Error(`ExposeStore.addExpose: unknown upstream "${e.upstream}" (add the upstream first)`);
+    }
+    if (!isNonEmptyString(e.tool)) {
+      throw new Error(`ExposeStore.addExpose: expose.tool must be a non-empty string (upstream=${e.upstream})`);
+    }
+    if (this._findExpose(e.upstream, e.tool)) {
+      throw new Error(
+        `ExposeStore.addExpose: expose entry (upstream="${e.upstream}", tool="${e.tool}") already exists`
+      );
+    }
+    // Persist an explicit `as` (default the namespaced name so the stored entry
+    // is self-describing and the aggregator never has to recompute it).
+    e.as = isNonEmptyString(e.as) ? e.as : `${e.upstream}_${e.tool}`;
+    this._expose.push(e);
+    this._persist();
+    return clone(e);
+  }
+
+  /**
+   * Shallow-merge `patch` over an existing expose entry. The natural key
+   * `(upstream,tool)` is immutable — any `upstream`/`tool` in the patch is ignored.
+   * Persists atomically. Throws on an unknown (upstream,tool).
+   */
+  updateExpose(upstream, tool, patch) {
+    const idx = this._indexOfExpose(upstream, tool);
+    if (idx === -1) {
+      throw new Error(`ExposeStore.updateExpose: unknown expose entry (upstream="${upstream}", tool="${tool}")`);
+    }
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+      throw new Error('ExposeStore.updateExpose: patch must be an object');
+    }
+    const merged = normaliseExpose({ ...this._expose[idx], ...patch, upstream, tool });
+    this._expose[idx] = merged;
+    this._persist();
+    return clone(merged);
+  }
+
+  /** Remove an expose entry. Persists. Throws on an unknown (upstream,tool). @returns {true} */
+  removeExpose(upstream, tool) {
+    const idx = this._indexOfExpose(upstream, tool);
+    if (idx === -1) {
+      throw new Error(`ExposeStore.removeExpose: unknown expose entry (upstream="${upstream}", tool="${tool}")`);
+    }
+    this._expose.splice(idx, 1);
+    this._persist();
+    return true;
+  }
+
+  /** Toggle an expose entry's `enabled` flag; persists. Throws on unknown (upstream,tool). */
+  setExposeEnabled(upstream, tool, enabled) {
+    return this.updateExpose(upstream, tool, { enabled: !!enabled });
+  }
+
+  // ── serialisation ─────────────────────────────────────────────────────────
+
+  /** @returns {{version, upstreams, expose}} a clone of the full config (safe to mutate). */
+  toJSON() {
+    return {
+      version: this._version,
+      upstreams: [...this._upstreams.values()].map(clone),
+      expose: this._expose.map(clone),
+    };
+  }
+
+  // ── internals ───────────────────────────────────────────────────────────
+
+  /** @returns {object|undefined} the LIVE expose entry (not a clone) for (upstream,tool). */
+  _findExpose(upstream, tool) {
+    return this._expose.find((e) => e.upstream === upstream && e.tool === tool);
+  }
+
+  /** @returns {number} index of the expose entry for (upstream,tool), or -1. */
+  _indexOfExpose(upstream, tool) {
+    return this._expose.findIndex((e) => e.upstream === upstream && e.tool === tool);
+  }
+
+  /** Serialise current state back to the config file atomically. */
+  _persist() {
+    atomicWriteJson(this._filePath, this.toJSON());
+  }
+}
+
+/**
+ * loadExposeStore(filePath) -> ExposeStore
+ *
+ * Reads + parses the config JSON at `filePath` and returns an ExposeStore bound to
+ * it.
+ *  - MISSING file → return an empty store bound to filePath. The file is NOT
+ *    created until the first write (keeps the server starting clean).
+ *  - MALFORMED JSON (or a duplicate id / duplicate expose key) → throw a clear
+ *    error so misconfiguration is caught at load, not at run time.
+ *
+ * @param {string} filePath
+ * @returns {ExposeStore}
+ */
+function loadExposeStore(filePath) {
+  if (!isNonEmptyString(filePath)) {
+    throw new Error('loadExposeStore: filePath (non-empty string) is required');
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      // Missing file is not an error — bind an empty store; defer file creation.
+      return new ExposeStore({ filePath, data: { version: 1, upstreams: [], expose: [] } });
+    }
+    throw new Error(`loadExposeStore: cannot read config at "${filePath}": ${err.message}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`loadExposeStore: config at "${filePath}" is not valid JSON: ${err.message}`);
+  }
+  return new ExposeStore({ filePath, data });
+}
+
+module.exports = {
+  ExposeStore,
+  loadExposeStore,
+  // exported for unit tests / the aggregator
+  atomicWriteJson,
+  normaliseUpstream,
+  normaliseExpose,
+  validateUpstream,
+  VALID_TRANSPORTS,
+};

package/src/mcp/gated-run.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * gated-run.js — the SAFETY CRUX of the gateway.
+ *
+ * Contract: the architecture contract §2 (the `toolfunnel_run_tool` path) and §9 (the tested invariant).
+ * Hook contract: HOOK_ENGINE.md §1 (PreToolUse can block, PostToolUse cannot un-run) and §6
+ * (HookEngine.fire returns { injected, blocked, reason, stopLoop, results }; the engine has
+ * ALREADY normalised exit-2 / hookSpecificOutput.permissionDecision:"deny" into { blocked, reason }).
+ *
+ * This is the single place where "run a tool" becomes "fire PreToolUse → maybe execute →
+ * fire PostToolUse". Every powerful run-path (toolfunnel_run_tool, registry.run) funnels through here so
+ * the gate is impossible to bypass. The LOAD-BEARING INVARIANT, proven by test:
+ *
+ *     A PreToolUse deny MUST prevent execute() from ever being called.
+ *
+ * Design rules:
+ *   - PURE: `engine` and `execute` are INJECTED. No transport, no SDK, no host, no fs.
+ *     Unit-testable under `node --test` with a fake engine + a spy execute().
+ *   - NEVER throws out of gatedRun. A thrown execute() is captured as { ok:false, error }.
+ *     A misbehaving engine.fire() (rejection or junk return) is treated conservatively.
+ *   - PostToolUse is advisory (HOOK_ENGINE.md §1: a PostToolUse block cannot un-run the tool),
+ *     so we fire it for feedback but never let it flip ok→false or throw the path.
+ *
+ * Return shape (always one of these, never an exception):
+ *   blocked by PreToolUse : { ok:false, blocked:true,  reason, output:null }
+ *   execute threw         : { ok:false, blocked:false, error, output:null }
+ *   success               : { ok:true,  blocked:false, output }
+ *
+ * CommonJS only. Node built-ins only. No new dependencies.
+ */
+
+// Activity log. Self-gating (no-op unless explicitly enabled) and contracted never to
+// throw, so wiring it here cannot alter gate behaviour or break the run path.
+const logger = require('../core/logger');
+
+const EVENTS = {
+  PRE: 'PreToolUse',
+  POST: 'PostToolUse',
+};
+
+/**
+ * Fire one lifecycle event through the injected engine, defensively.
+ *
+ * The HookEngine contract (HOOK_ENGINE.md §6) says fire() never rejects, but gatedRun is the
+ * safety crux: we must not assume a perfectly-behaved engine. If fire() rejects or returns a
+ * non-object, we fail CLOSED on the gate (PreToolUse) — an engine we cannot trust to answer
+ * "allowed?" must not be read as "allowed". PostToolUse is advisory, so a failure there is benign.
+ *
+ * @param {object} engine an object exposing async fire(event, ctx, extra)
+ * @param {string} event one of EVENTS
+ * @param {object} ctx common hook context (session_id, transcript_path, cwd, …)
+ * @param {object} extra event-specific fields (per HOOK_ENGINE.md §2 table)
+ * @returns {Promise<{ injected:string, blocked:boolean, reason:(string|null),
+ *                     stopLoop:boolean, results:object[] }>}
+ */
+async function fireSafely(engine, event, ctx, extra) {
+  try {
+    const res = await engine.fire(event, ctx, extra);
+    // The engine already normalises blocking to { blocked, reason }. Defensively coerce a
+    // junk/undefined return into a well-shaped result so callers can read fields safely.
+    if (res && typeof res === 'object') {
+      return {
+        injected: typeof res.injected === 'string' ? res.injected : '',
+        blocked: res.blocked === true,
+        reason: res.reason != null ? res.reason : null,
+        stopLoop: res.stopLoop === true,
+        results: Array.isArray(res.results) ? res.results : [],
+      };
+    }
+    // Non-object return from fire(): per-event. PreToolUse fails CLOSED — a gate that
+    // returns junk cannot be read as "allowed". PostToolUse is advisory → benign.
+    if (event === EVENTS.PRE) {
+      return {
+        injected: '',
+        blocked: true,
+        reason: 'hook engine returned a non-object for ' + event + ' — failing closed',
+        stopLoop: false,
+        results: [],
+      };
+    }
+    return { injected: '', blocked: false, reason: null, stopLoop: false, results: [] };
+  } catch (err) {
+    // fire() should never reject; if it does, fail closed on the GATE and benign on POST.
+    const reason =
+      'hook engine error during ' + event + ': ' + ((err && err.message) || String(err));
+    if (event === EVENTS.PRE) {
+      // Fail CLOSED: an engine that cannot answer the gate denies the run.
+      return { injected: '', blocked: true, reason, stopLoop: false, results: [] };
+    }
+    // PostToolUse is advisory and cannot un-run the tool — a failure here is benign.
+    return { injected: '', blocked: false, reason: null, stopLoop: false, results: [] };
+  }
+}
+
+/**
+ * gatedRun — route a single tool invocation through the host's hook engine.
+ *
+ * Sequence (the architecture contract §2):
+ *   1. fire PreToolUse with { tool_name, tool_input: args }.
+ *   2. if blocked → return { ok:false, blocked:true, reason, output:null } and DO NOT call execute.
+ *   3. else await execute(); on throw, capture as error (output stays null).
+ *   4. fire PostToolUse with { tool_name, tool_input: args, tool_response: output }.
+ *      (PostToolUse is advisory — fired for feedback even on the error path so PostToolUse hooks
+ *       observe what happened; it never flips ok or throws.)
+ *   5. return { ok:true, blocked:false, output } | { ok:false, blocked:false, error, output:null }.
+ *
+ * @param {object}   params
+ * @param {object}   params.engine   the host's HookEngine — async fire(event, ctx, extra). INJECTED.
+ * @param {object}   [params.ctx]    common hook context (session_id, transcript_path, cwd, …).
+ * @param {string}   params.toolName the tool name (becomes tool_name in the payload).
+ * @param {*}        [params.args]   the tool input (becomes tool_input in the payload).
+ * @param {Function} params.execute  thunk that performs the actual call (from
+ *                                   registry.resolveExecution). `() => any | Promise<any>`. INJECTED.
+ * @returns {Promise<{ ok:boolean, blocked:boolean, reason?:(string|null),
+ *                     output:(*|null), error?:Error }>}
+ */
+async function gatedRun(params) {
+  const p = params || {};
+  const { engine, ctx, toolName, args, execute } = p;
+
+  // ---- Validate injected dependencies, failing CLOSED (never execute on a bad wiring). ----
+  if (!engine || typeof engine.fire !== 'function') {
+    return {
+      ok: false,
+      blocked: true,
+      reason: 'gatedRun: engine with async fire() is required',
+      output: null,
+    };
+  }
+  if (typeof execute !== 'function') {
+    return {
+      ok: false,
+      blocked: true,
+      reason: 'gatedRun: execute thunk (function) is required',
+      output: null,
+    };
+  }
+
+  const context = ctx || {};
+
+  // ---- 1. PreToolUse gate. -------------------------------------------------------------
+  // tool_input carries the args verbatim (per HOOK_ENGINE.md §2 PreToolUse row).
+  const pre = await fireSafely(engine, EVENTS.PRE, context, {
+    tool_name: toolName,
+    tool_input: args,
+  });
+
+  // ---- Activity log: record the gate decision (allow|deny). Self-gates on enabled;
+  //      never throws. Placed before the blocked-return so BOTH outcomes are logged. ---
+  logger.log({
+    type: 'gate',
+    tool: toolName,
+    decision: pre.blocked ? 'deny' : 'allow',
+    reason: pre.reason,
+  });
+
+  // ---- 2. Blocked → STOP. The load-bearing invariant: execute() is NOT called. ---------
+  if (pre.blocked) {
+    return {
+      ok: false,
+      blocked: true,
+      reason: pre.reason,
+      output: null,
+    };
+  }
+
+  // ---- 3. Allowed → execute the real call. Capture a throw as `error`. -----------------
+  let output = null;
+  let error = null;
+  try {
+    output = await execute();
+  } catch (err) {
+    // Normalise any thrown value into an Error so the caller always gets an Error instance.
+    error = err instanceof Error ? err : new Error(String(err));
+  }
+
+  // ---- 4. PostToolUse (advisory). Fired even on the error path so hooks see the outcome. -
+  // tool_response is the output (null when execute threw). PostToolUse cannot un-run the tool
+  // (HOOK_ENGINE.md §1), so its result never flips ok and never throws this path.
+  await fireSafely(engine, EVENTS.POST, context, {
+    tool_name: toolName,
+    tool_input: args,
+    tool_response: output,
+  });
+
+  // ---- 5. Final result. ----------------------------------------------------------------
+  if (error) {
+    return { ok: false, blocked: false, error, output: null };
+  }
+  return { ok: true, blocked: false, output };
+}
+
+module.exports = { gatedRun, EVENTS };