toolfunnel 0.6.0 → 0.7.0

package/mcp/servers/mock-upstream/server.js

@@ -33,7 +33,7 @@
 
 const PROTOCOL_VERSION = '2024-11-05';
 // `title` is a fidelity fixture: the 2025-06-18 spec added serverInfo.title, and the wrap must
-// deliver it VERBATIM (a whitelist in wrappedIdentity used to eat it - wrap-lab, 2026-07-17).
+// deliver it VERBATIM (a whitelist in wrappedIdentity used to eat it - found wire-testing the wrap, 2026-07-17).
 const SERVER_INFO = { name: 'mock-upstream', version: '1.0.0', title: 'Mock Upstream Fixture' };
 
 const TOOLS = [
@@ -88,12 +88,12 @@ const TOOLS = [
   },
   {
     name: 'elicit',
-    description: 'Elicitation fixture (Bridge B): sends a server-initiated elicitation/create mid-call, holds the call open, completes from the answer.',
+    description: 'Elicitation fixture: sends a server-initiated elicitation/create mid-call, holds the call open, completes from the answer.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
   },
 ];
 
-// Outstanding SERVER->CLIENT requests this mock has issued (Bridge B fixture): id -> callback fed
+// Outstanding SERVER->CLIENT requests this mock has issued (elicitation-bridge fixture): id -> callback fed
 // with the client's response ({ result } or { error }).
 const outstandingServerRequests = new Map();
 let nextServerRequestId = 9001;
@@ -115,6 +115,15 @@ function handleMessage(msg) {
   const method = msg.method;
   const params = msg.params || {};
 
+  // Era-negotiation fixture: when TF_MOCK_METHOD_LOG is set, RECORD every incoming method in
+  // arrival order. A reconnect test reads the log to prove WHICH negotiation a fresh connection
+  // ran (server/discover probe vs straight initialize) - the wire is the only honest witness.
+  if (typeof method === 'string' && process.env.TF_MOCK_METHOD_LOG) {
+    try {
+      require('node:fs').appendFileSync(process.env.TF_MOCK_METHOD_LOG, method + '\n');
+    } catch (_e) { /* fixture logging must never crash the mock */ }
+  }
+
   // Notifications carry no id and must never be answered. Cancel-fidelity fixture: when
   // TF_MOCK_CANCEL_LOG is set, RECORD each received notifications/cancelled requestId - a
   // gateway test can then prove which id (translated or raw) actually reached this server.
@@ -128,7 +137,7 @@ function handleMessage(msg) {
   }
 
   // A message with an id and NO method is a client RESPONSE - route it to the outstanding
-  // server-initiated request it answers (Bridge B fixture). Unknown ids are dropped.
+  // server-initiated request it answers (elicitation-bridge fixture). Unknown ids are dropped.
   if (method === undefined) {
     const cb = outstandingServerRequests.get(id);
     if (cb) {
@@ -140,6 +149,17 @@ function handleMessage(msg) {
 
   switch (method) {
     case 'initialize':
+      // Era-memo self-heal fixture: while the file named by TF_MOCK_INIT_REFUSE_FILE EXISTS,
+      // REFUSE the legacy handshake - the shape of an upstream upgraded to modern-only across a
+      // restart. File-gated (not env-gated) so a test can flip the behaviour BETWEEN respawns of
+      // this same fixture without touching the upstream's configured env.
+      if (process.env.TF_MOCK_INIT_REFUSE_FILE &&
+          require('node:fs').existsSync(process.env.TF_MOCK_INIT_REFUSE_FILE)) {
+        return writeMessage({
+          jsonrpc: '2.0', id,
+          error: { code: -32000, message: 'initialize refused (TF_MOCK_INIT_REFUSE_FILE fixture)' },
+        });
+      }
       // Identity-mirroring fixture: RECORD the clientInfo each connect presents when
       // TF_MOCK_CLIENTINFO_LOG is set. A wire test reads the log across a reconnect - first
       // entry = the gateway's boot identity, last entry = the mirrored downstream client.
@@ -163,6 +183,16 @@ function handleMessage(msg) {
       });
 
     case 'tools/list':
+      // Era-memo invariant fixture: while the file named by TF_MOCK_LIST_FAIL_FILE EXISTS,
+      // tools/list errors AFTER a successful handshake - the shape of an upstream that half-boots.
+      // File-gated so a test can flip the behaviour between respawns of this same fixture.
+      if (process.env.TF_MOCK_LIST_FAIL_FILE &&
+          require('node:fs').existsSync(process.env.TF_MOCK_LIST_FAIL_FILE)) {
+        return writeMessage({
+          jsonrpc: '2.0', id,
+          error: { code: -32000, message: 'tools/list unavailable (TF_MOCK_LIST_FAIL_FILE fixture)' },
+        });
+      }
       return writeMessage({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
 
     case 'server/discover':
@@ -203,7 +233,7 @@ function handleMessage(msg) {
       const uri = params.uri;
       if (uri === 'mock://upstream/slow') {
         // In-flight fixture: reply after 2s so a gateway test has a WIDE window to fire a
-        // cancel at a genuinely outstanding forwarded request (400ms made W1 a flake candidate
+        // cancel at a genuinely outstanding forwarded request (400ms made the wire cancel test a flake candidate
         // on a loaded runner).
         setTimeout(() => writeMessage({
           jsonrpc: '2.0', id,
@@ -267,7 +297,7 @@ function handleMessage(msg) {
           return;
         }
         if (name === 'elicit') {
-          // Bridge B fixture: ask the CLIENT a question mid-call, hold the tools/call open, and
+          // elicitation-bridge fixture: ask the CLIENT a question mid-call, hold the tools/call open, and
           // complete it from the answer - exactly what a real eliciting legacy server does.
           const reqId = nextServerRequestId++;
           outstandingServerRequests.set(reqId, (resp) => {

package/package.json

@@ -1,65 +1,67 @@
-{
-  "name": "toolfunnel",
-  "version": "0.6.0",
-  "description": "A zero-dependency MCP gateway: host your own tools, forward and curate tools from other MCP servers, expose them leanly to cut agent token cost, and gate every call through your own policy hooks before it runs.",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "mcp-gateway",
-    "mcp-proxy",
-    "mcp-server",
-    "ai",
-    "agents",
-    "llm",
-    "tools",
-    "claude",
-    "anthropic",
-    "aggregator",
-    "token-efficiency"
-  ],
-  "license": "MIT",
-  "type": "commonjs",
-  "main": "src/mcp/server.js",
-  "bin": {
-    "toolfunnel": "bin/toolfunnel.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "start": "node bin/toolfunnel.js",
-    "build": "echo toolfunnel has no build step - zero-dependency, runs from source",
-    "http": "node bin/toolfunnel.js --http",
-    "install-oauth": "node bin/toolfunnel.js install-oauth",
-    "test": "node test/run-all.js",
-    "release": "node scripts/release.js",
-    "test:integration": "node test/integration-real-mcp.test.js && node test/integration-http-client.test.js"
-  },
-  "dependencies": {},
-  "author": "rendeverance",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Rendeverance/toolfunnel.git"
-  },
-  "homepage": "https://github.com/Rendeverance/toolfunnel#readme",
-  "bugs": {
-    "url": "https://github.com/Rendeverance/toolfunnel/issues"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "tools/tools.register.json",
-    "tools/scripts/",
-    "mcp/expose.example.json",
-    "mcp/servers/",
-    "hooks/hooks.manifest.json",
-    "hooks/scripts/",
-    "docs/",
-    "README.md",
-    "LICENSE"
-  ],
-  "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "jose": "^5.10.0"
-  }
-}
+{
+  "name": "toolfunnel",
+  "version": "0.7.0",
+  "description": "A zero-dependency MCP gateway: host your own tools, forward and curate tools from other MCP servers, expose them leanly to cut agent token cost, and gate every call through your own policy hooks before it runs.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-gateway",
+    "mcp-proxy",
+    "mcp-server",
+    "ai",
+    "agents",
+    "llm",
+    "tools",
+    "claude",
+    "anthropic",
+    "aggregator",
+    "token-efficiency"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "src/mcp/server.js",
+  "bin": {
+    "toolfunnel": "bin/toolfunnel.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/toolfunnel.js",
+    "build": "echo toolfunnel has no build step - zero-dependency, runs from source",
+    "http": "node bin/toolfunnel.js --http",
+    "install-oauth": "node bin/toolfunnel.js install-oauth",
+    "test": "node test/run-all.js",
+    "prepublishOnly": "node test/run-all.js",
+    "release": "node scripts/release.js",
+    "test:integration": "node test/integration-real-mcp.test.js && node test/integration-http-client.test.js"
+  },
+  "dependencies": {},
+  "author": "rendeverance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rendeverance/toolfunnel.git"
+  },
+  "homepage": "https://github.com/Rendeverance/toolfunnel#readme",
+  "bugs": {
+    "url": "https://github.com/Rendeverance/toolfunnel/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "tools/tools.register.json",
+    "tools/scripts/",
+    "mcp/expose.example.json",
+    "mcp/servers/",
+    "hooks/hooks.manifest.json",
+    "hooks/scripts/",
+    "docs/",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "jose": "^5.10.0"
+  }
+}

package/src/auth/config.js

@@ -99,7 +99,7 @@ function getConfig() {
   }
 }
 
-/** A fresh, mutation-safe copy of the defaults (arrays cloned so a caller can't poison the frozen one). */
+/** A fresh, mutation-safe copy of the defaults (arrays cloned so a caller can't corrupt the frozen one). */
 function cloneDefaults() {
   return {
     enabled: DEFAULTS.enabled,
@@ -118,7 +118,7 @@ function cloneDefaults() {
  * rather than silently mis-validating. Only meaningful when `enabled` is true.
  *
  * Enforcement requires: an issuer, an audience (the RFC 8707 confused-deputy defence - a gateway
- * that does not bind tokens to its own resource URI is exploitable), at least one pinned algorithm,
+ * that does not bind tokens to its own resource URI is unsafe), at least one pinned algorithm,
  * and a key source (explicit jwksUri OR an issuer to derive one from via OIDC discovery).
  *
  * @param {object} [cfg]  defaults to getConfig()

package/src/auth/resource-server.js

@@ -11,9 +11,9 @@
  *
  * Why a library and not hand-rolled node:crypto: validating a JWT securely is not the signature
  * math (node:crypto has that) - it is the protocol discipline around it. The dangerous, CVE-prone
- * decisions are (1) PINNING the accepted algorithm so an attacker can't downgrade RS256->HS256 and
+ * decisions are (1) PINNING the accepted algorithm so an untrusted token can't downgrade RS256->HS256 and
  * forge a token by signing with the public key as an HMAC secret, (2) rejecting `alg:none`, (3)
- * ignoring attacker-controlled header params (jku/jwk/x5u), (4) validating iss/aud/exp/nbf, and (5)
+ * ignoring caller-controlled header params (jku/jwk/x5u), (4) validating iss/aud/exp/nbf, and (5)
  * JWKS caching + key rotation. `jose` encodes all of these into its API; we MUST drive that API
  * correctly - above all, ALWAYS pass the `algorithms` allowlist and the `audience` (the RFC 8707
  * confused-deputy defence). `jose` v5's `require` build uses Node's native crypto (Node ≥18, no
@@ -245,6 +245,13 @@ function createValidator(cfg, opts) {
       // refuses to start in this state, but a request must still never slip through.
       return unauthorized(500, 'server_error', 'authentication misconfigured', 'no audience configured');
     }
+    if (!cfg.issuer) {
+      // Symmetric with the audience guard: a blank issuer would make jwtVerify's `issuer` undefined,
+      // silently DISABLING issuer binding so a token from any authorization server would validate.
+      // configError refuses this at start-up, but the UI can persist an enabled+blank-issuer config
+      // that takes effect on the next request with no restart - so fail closed here too.
+      return unauthorized(500, 'server_error', 'authentication misconfigured', 'no issuer configured');
+    }
 
     const token = extractBearer(authorizationHeader);
     if (!token) {
@@ -266,7 +273,9 @@ function createValidator(cfg, opts) {
       // issuer + audience are ENFORCED by jose; clockTolerance bounds exp/nbf skew. We never read the
       // token header to choose the algorithm - the allowlist is fixed from config.
       result = await jose.jwtVerify(token, resolver, {
-        issuer: cfg.issuer || undefined,
+        // The guard above guarantees a non-empty issuer here; pass it straight through. The old
+        // `cfg.issuer || undefined` was the silent-skip footgun - undefined tells jose NOT to check.
+        issuer: cfg.issuer,
         audience: cfg.audience,
         algorithms: cfg.algorithms,
         clockTolerance: cfg.clockToleranceSec,

package/src/core/child-reaper.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * child-reaper.js - last-resort cleanup for spawned hook/tool children.
+ *
+ * The hook runner and both local executors spawn their children `detached` on POSIX so the
+ * process GROUP can be killed as a tree. setsid() has a consequence: the children leave the
+ * gateway's session, so a terminal Ctrl-C no longer reaches them, and a gateway that dies
+ * without executing its per-child kill path leaves them reparented to init running to their
+ * natural end - with their supervising timeout timers dead alongside the gateway.
+ *
+ * This module is the counterpart: every spawn site registers its child here and unregisters on
+ * settle; process exit / SIGINT / SIGTERM sweeps whatever is still tracked. Synchronous kills
+ * only - an 'exit' handler cannot await. Windows gets child.kill() (the shell only; taskkill is
+ * async and cannot run here) - best effort, matching the platform's weaker group semantics.
+ * A SIGKILLed gateway sweeps nothing; that limit is inherent to SIGKILL.
+ */
+
+const live = new Set();
+let installed = false;
+
+function sweep() {
+  for (const child of live) {
+    try {
+      if (child.pid != null && process.platform !== 'win32') {
+        try { process.kill(-child.pid, 'SIGKILL'); } catch (_eg) { child.kill('SIGKILL'); }
+      } else {
+        child.kill();
+      }
+    } catch (_e) { /* already gone */ }
+  }
+  live.clear();
+}
+
+function install() {
+  if (installed) return;
+  installed = true;
+  process.on('exit', sweep);
+  // On a signal, sweep and re-raise the default behaviour by exiting: only do so if nobody
+  // else handles the signal (respect an embedding host's own handlers).
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => {
+      sweep();
+      if (process.listenerCount(sig) === 1) process.exit(sig === 'SIGINT' ? 130 : 143);
+    });
+  }
+}
+
+/** Register a spawned child for the last-resort sweep. Call untrack() when it settles. */
+function track(child) {
+  if (!child || typeof child.kill !== 'function') return;
+  install();
+  live.add(child);
+}
+
+/** Remove a settled child from the sweep set. Safe to call twice. */
+function untrack(child) {
+  live.delete(child);
+}
+
+module.exports = { track, untrack };

package/src/core/events.js

@@ -3,8 +3,8 @@
 /**
  * events.js - lifecycle event names + per-event stdin payload builder.
  *
- * This is the contract surface from HOOK_ENGINE.md §1 (the six events) and §2
- * (the exact stdin JSON shape). Field names are FROZEN by §2's table - they must
+ * This is the hook contract surface: the six lifecycle events and
+ * (the exact stdin JSON shape). Field names are FROZEN - they are the hook wire contract and must
  * match Claude Code's documented hook input byte-for-byte so the real hook
  * scripts run unchanged. Do not rename or add fields.
  *
@@ -12,7 +12,7 @@
  */
 
 /**
- * The six lifecycle events v3 supports (HOOK_ENGINE.md §1).
+ * The six lifecycle events v3 supports.
  * Values equal the `hook_event_name` written into the stdin payload.
  * Frozen so callers can rely on identity comparison and can't mutate the set.
  */
@@ -31,7 +31,7 @@ const EVENT_NAMES = Object.freeze(Object.values(EVENTS));
 /**
  * Build the stdin JSON object the runner pipes to a hook command.
  *
- * Every event carries the four common fields (HOOK_ENGINE.md §2):
+ * Every event carries the same four common fields:
  *   session_id, transcript_path, cwd, hook_event_name
  * supplied by `ctx`. Each event then adds its own fields from `extra`:
  *
@@ -45,7 +45,7 @@ const EVENT_NAMES = Object.freeze(Object.values(EVENTS));
  * @param {string} event  one of EVENTS (the hook_event_name).
  * @param {object} ctx    common fields: { session_id, transcript_path, cwd }.
  * @param {object} [extra] event-specific fields (see table above).
- * @returns {object} the stdin payload, with frozen field names per §2.
+ * @returns {object} the stdin payload, with the contract's frozen field names.
  * @throws {Error} if `event` is not one of the six known events.
  */
 function buildPayload(event, ctx, extra) {
@@ -56,7 +56,7 @@ function buildPayload(event, ctx, extra) {
   const c = ctx || {};
   const e = extra || {};
 
-  // Common fields - present on EVERY event, in the order §2 lists them.
+  // Common fields - present on EVERY event, in their contract order.
   // hook_event_name is always the canonical event string (not whatever ctx held).
   const payload = {
     session_id: c.session_id,
@@ -65,7 +65,7 @@ function buildPayload(event, ctx, extra) {
     hook_event_name: event,
   };
 
-  // Event-specific additions. Each branch sets EXACTLY the fields §2 names -
+  // Event-specific additions. Each branch sets EXACTLY the fields the contract names -
   // no more, no fewer - so the payload matches Claude Code's shape precisely.
   switch (event) {
     case EVENTS.SessionStart:

package/src/core/hook-engine.js

@@ -3,7 +3,7 @@
 /**
  * hook-engine.js - fire a lifecycle event through its matching, enabled hooks.
  *
- * Contract: HOOK_ENGINE.md §6.
+ * Contract: fire() never rejects - see the class doc below.
  *
  *   class HookEngine {
  *     constructor(loader)                       // loader provides enabled hook specs
@@ -12,7 +12,7 @@
  *       blocked:   boolean,       // any hook blocked
  *       reason:    string|null,   // first block reason (in manifest order)
  *       stopLoop:  boolean,       // any hook said continue:false
- *       results:   HookResult[]   // per §4, in stable (manifest) order
+ *       results:   HookResult[]   // runner-result shapes, in stable (manifest) order
  *     }
  *   }
  *
@@ -21,6 +21,11 @@
  *     Tool-less events (SessionStart, UserPromptSubmit, Stop, PreCompact) ignore the matcher -
  *     matcher.js handles that, but we also derive toolName only from the built payload so the
  *     matcher gets exactly what the contract says it should see.
+ *   - A matcher that does not COMPILE is an unreadable gate: on a tool-bearing event the hook
+ *     contributes a synthetic BLOCKING result (its command never runs) - an unreadable gate is
+ *     never permission, mirroring the runner's unreadable-decision rule. Authoring surfaces
+ *     refuse such a matcher up front (hook-loader.addEntry), so this only fires for a
+ *     hand-edited manifest. (0.7.0; matcher-compile.test.js is the acceptance.)
  *   - Build the stdin payload once via events.buildPayload(event, ctx, extra).
  *   - Run selected hooks CONCURRENTLY (they are independent) with a global concurrency cap
  *     (default 8) so a big event cannot fork-bomb, but return results in MANIFEST ORDER.
@@ -28,7 +33,7 @@
  *   - blocked/reason = the FIRST blocker in order.
  *   - stopLoop = true if ANY hook returned continue:false.
  *
- * The runner never throws (§4), and this engine defends against a misbehaving runner too:
+ * The runner never throws (its hard guarantee), and this engine defends against a misbehaving runner too:
  * any rejection is converted into a synthetic error result so fire() never rejects.
  *
  * CommonJS only. Zero host imports (must run headless under `node --test`).
@@ -55,6 +60,16 @@ function getMatchesFn() {
   return () => true;
 }
 
+/**
+ * Resolve matcherError from matcher.js (named export). Falls back to "no problem" so an older
+ * matcher module degrades to the previous behaviour rather than crashing the engine.
+ * @returns {(m: string|undefined) => (string|null)}
+ */
+function getMatcherErrorFn() {
+  if (matcher && typeof matcher.matcherError === 'function') return matcher.matcherError;
+  return () => null;
+}
+
 /**
  * Resolve buildPayload from events.js (named export per contract).
  * @returns {(event: string, ctx: object, extra: object) => object}
@@ -85,7 +100,7 @@ function getRunHookFn() {
 }
 
 /**
- * Build a synthetic "failed" result matching the §4 shape, used when the runner rejects
+ * Build a synthetic "failed" result matching the runner's result shape, used when the runner rejects
  * unexpectedly (it is contractually not supposed to, but we never let the loop throw).
  * @param {object} spec
  * @param {string} event
@@ -166,6 +181,7 @@ class HookEngine {
 
     // Resolve contract functions once.
     this._matches = getMatchesFn();
+    this._matcherError = getMatcherErrorFn();
     this._buildPayload = getBuildPayloadFn();
     this._runHook = getRunHookFn();
   }
@@ -183,7 +199,7 @@ class HookEngine {
     const context = ctx || {};
     const extraFields = extra || {};
 
-    // Build the stdin payload once (frozen field names per §2).
+    // Build the stdin payload once (the contract's frozen field names).
     let payload;
     try {
       payload = this._buildPayload(event, context, extraFields);
@@ -204,43 +220,81 @@ class HookEngine {
     // For tool-less events this is undefined and matcher.js treats it as always-fire.
     const toolName = payload && payload.tool_name;
 
-    // Select enabled hooks for this event whose matcher matches, in MANIFEST ORDER.
-    const candidates = this.loader.enabledHooksFor(event) || [];
-    const selected = candidates.filter((spec) => {
-      try {
-        return this._matches(spec && spec.matcher, toolName);
-      } catch (_) {
-        // A broken matcher string should not crash the engine; skip that hook.
-        return false;
-      }
-    });
-
     // Resolve the child cwd/env once for the runner.
     const runCwd = (payload && payload.cwd) || this.cwd;
     const runOpts = { cwd: runCwd };
     if (this.env) runOpts.env = this.env;
 
-    // Build task factories (one per selected hook) - never reject.
-    const factories = selected.map((spec) => async () => {
-      const started = Date.now();
-      try {
-        const res = await this._runHook(spec, payload, runOpts);
-        // Defensive: ensure the result carries id/event even if the runner omitted them.
-        if (res && typeof res === 'object') {
-          if (res.id === undefined) res.id = spec.id;
-          if (res.event === undefined) res.event = event;
-          return res;
+    // Select enabled hooks for this event and build task factories, in MANIFEST ORDER.
+    //
+    // A matcher that does not COMPILE cannot be evaluated, and an unreadable gate is never
+    // permission - the same rule the runner applies to an unreadable decision (gate-semantics /
+    // matcher-compile tests). On a TOOL-BEARING event such a hook contributes a synthetic
+    // BLOCKING result in its manifest position (its command is never run); authoring surfaces
+    // refuse the pattern up front (hook-loader.addEntry), so this branch only fires for a
+    // hand-edited manifest. Tool-less events ignore the matcher entirely (existing contract).
+    const candidates = this.loader.enabledHooksFor(event) || [];
+    const factories = [];
+    for (const spec of candidates) {
+      if (toolName !== undefined && toolName !== null) {
+        let compileProblem = null;
+        try {
+          compileProblem = this._matcherError(spec && spec.matcher);
+        } catch (_) {
+          compileProblem = null; // discriminator itself failing must not take the engine down
+        }
+        if (compileProblem) {
+          const unreadable = {
+            id: spec && spec.id,
+            event,
+            exitCode: -1,
+            timedOut: false,
+            stdout: '',
+            stderr: '',
+            blocked: true,
+            stopLoop: false,
+            reason:
+              `hook-engine: hook "${(spec && spec.id) || '(unnamed)'}" has a matcher that does ` +
+              `not compile (${compileProblem}); its gate could not be read, so the call is ` +
+              'denied (fail closed). Fix or disable the hook.',
+            inject: null,
+            durationMs: 0,
+          };
+          factories.push(async () => unreadable);
+          continue;
         }
-        return syntheticFailure(spec, event, new Error('runner returned no result'), Date.now() - started);
-      } catch (err) {
-        return syntheticFailure(spec, event, err, Date.now() - started);
       }
-    });
+
+      let fires = false;
+      try {
+        fires = this._matches(spec && spec.matcher, toolName);
+      } catch (_) {
+        // A matcher evaluation crash should not crash the engine; skip that hook.
+        fires = false;
+      }
+      if (!fires) continue;
+
+      factories.push(async () => {
+        const started = Date.now();
+        try {
+          const res = await this._runHook(spec, payload, runOpts);
+          // Defensive: ensure the result carries id/event even if the runner omitted them.
+          if (res && typeof res === 'object') {
+            if (res.id === undefined) res.id = spec.id;
+            if (res.event === undefined) res.event = event;
+            return res;
+          }
+          return syntheticFailure(spec, event, new Error('runner returned no result'), Date.now() - started);
+        } catch (err) {
+          return syntheticFailure(spec, event, err, Date.now() - started);
+        }
+      });
+    }
 
     // Run concurrently with the cap; results come back in manifest order.
     const results = await runWithConcurrency(factories, this.concurrency);
 
-    // Aggregate per §6.
+    // Aggregate the per-hook results into the engine outcome.
     const injectFragments = [];
     let blocked = false;
     let reason = null;