toolfunnel 0.3.0

package/src/auth/resource-server.js

@@ -0,0 +1,319 @@
+'use strict';
+
+/**
+ * auth/resource-server.js — OPTIONAL OAuth 2.1 resource-server token validation.
+ *
+ * This is the ONLY module that touches `jose`, and it does so with a LAZY require so the core
+ * gateway keeps `dependencies: {}` (zero runtime deps). `jose` is installed on demand — the CLI
+ * `toolfunnel install-oauth` or the admin-UI button (see src/auth/install.js) — and pulled in here
+ * only when auth is enabled. If it is not installed, every entry point fails CLOSED with a clear,
+ * actionable message; it never silently allows a request through.
+ *
+ * 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
+ * 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)
+ * 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
+ * Web-Crypto-global dependency), which is why it is the pinned major for this CommonJS project.
+ *
+ * NOTHING here throws out of validate() — a verification failure is a structured unauthorized
+ * result, not an exception. CommonJS only; Node built-ins (node:url, global fetch) + lazy jose.
+ */
+
+/**
+ * The PINNED jose version installed on demand. A caret range so patch/minor security fixes flow,
+ * but the major (v5 — the CommonJS, Node-native-crypto build; v6 is ESM-only and would force a
+ * Node ≥22 require-of-ESM floor incompatible with this project's `engines: >=18`) is fixed.
+ */
+const JOSE_PIN = '^5.10.0';
+
+/** Lazy jose handle: undefined = not yet attempted, null = attempted + absent, object = loaded. */
+let _jose = undefined;
+
+/**
+ * loadJose — lazily require('jose'), cached. Returns the module or null if it is not installed.
+ * NEVER throws (a missing/incompatible jose returns null; the caller fails closed with a message).
+ * @returns {object|null}
+ */
+function loadJose() {
+  if (_jose !== undefined) return _jose;
+  try {
+    // eslint-disable-next-line global-require
+    _jose = require('jose');
+  } catch (_e) {
+    _jose = null;
+  }
+  return _jose;
+}
+
+/** Is jose importable in this runtime? (installed AND loadable as CommonJS). */
+function isJoseInstalled() {
+  return loadJose() != null;
+}
+
+/** Reset the lazy cache — used by tests and by the UI right after an on-demand install. */
+function _resetJoseCache() {
+  _jose = undefined;
+}
+
+/**
+ * Build the value of a WWW-Authenticate response header for the Bearer scheme. Per RFC 6750 +
+ * RFC 9728: a bare challenge (no credentials) omits the error code; an invalid/insufficient token
+ * carries error= and error_description=. `resource_metadata` points the client at the protected-
+ * resource-metadata document so it can discover the authorization server (RFC 9728).
+ *
+ * @param {{ resourceMetadataUrl?:string, error?:string, description?:string }} o
+ * @returns {string}
+ */
+function buildWwwAuthenticate(o) {
+  const parts = [];
+  if (o && o.resourceMetadataUrl) parts.push(`resource_metadata="${o.resourceMetadataUrl}"`);
+  if (o && o.error) parts.push(`error="${o.error}"`);
+  if (o && o.description) parts.push(`error_description="${String(o.description).replace(/"/g, "'")}"`);
+  return parts.length ? `Bearer ${parts.join(', ')}` : 'Bearer';
+}
+
+/**
+ * Extract the bearer token from an Authorization header. Returns the token string, or null if the
+ * header is absent/malformed/not the Bearer scheme. Exactly one whitespace-delimited token after a
+ * case-insensitive "Bearer" is accepted.
+ * @param {string|undefined} authorizationHeader
+ * @returns {string|null}
+ */
+function extractBearer(authorizationHeader) {
+  if (typeof authorizationHeader !== 'string') return null;
+  const m = /^Bearer[ \t]+([^\s]+)[ \t]*$/i.exec(authorizationHeader.trim());
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve the JWKS URI: prefer an explicit cfg.jwksUri, else discover it from the issuer via OIDC
+ * Discovery (RFC 8414 / OpenID Connect Discovery). Tries the OIDC well-known first, then the OAuth
+ * Authorization Server Metadata well-known. Bounded by a timeout. Returns the URL string or throws
+ * a plain Error (the caller turns a throw into a fail-closed unauthorized result).
+ *
+ * @param {object} cfg  the resolved auth config
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string>}
+ */
+async function resolveJwksUri(cfg, timeoutMs) {
+  if (cfg.jwksUri) return cfg.jwksUri;
+  if (!cfg.issuer) throw new Error('no jwksUri and no issuer to discover one from');
+
+  const base = cfg.issuer.replace(/\/+$/, '');
+  const candidates = [
+    `${base}/.well-known/openid-configuration`,
+    `${base}/.well-known/oauth-authorization-server`,
+  ];
+  let lastErr = null;
+  for (const url of candidates) {
+    try {
+      const doc = await fetchJson(url, timeoutMs);
+      if (doc && typeof doc.jwks_uri === 'string' && doc.jwks_uri.length > 0) return doc.jwks_uri;
+      lastErr = new Error(`discovery doc at ${url} has no jwks_uri`);
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw lastErr || new Error('OIDC discovery failed');
+}
+
+/** GET + parse JSON with a hard timeout. Throws on non-2xx, network error, or bad JSON. */
+async function fetchJson(url, timeoutMs) {
+  const ac = new AbortController();
+  const ms = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 10000;
+  const t = setTimeout(() => ac.abort(), ms);
+  try {
+    const res = await fetch(url, { signal: ac.signal, redirect: 'follow' });
+    if (!res || !res.ok) throw new Error(`GET ${url} -> HTTP ${res ? res.status : 'no-response'}`);
+    return await res.json();
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/**
+ * Collect the scopes carried by a verified token: the space-delimited `scope` claim (RFC 8693) or
+ * an array `scp` claim (some issuers). Returns a Set of scope strings.
+ * @param {object} claims
+ * @returns {Set<string>}
+ */
+function scopesOf(claims) {
+  const out = new Set();
+  if (claims && typeof claims.scope === 'string') {
+    for (const s of claims.scope.split(/\s+/)) if (s) out.add(s);
+  }
+  if (claims && Array.isArray(claims.scp)) {
+    for (const s of claims.scp) if (typeof s === 'string' && s) out.add(s);
+  }
+  return out;
+}
+
+/**
+ * createValidator — build a token validator from a resolved auth config.
+ *
+ * @param {object} cfg  the resolved config (see auth/config.js getConfig()).
+ * @param {object} [opts]
+ * @param {string}   [opts.resourceMetadataUrl]  the absolute URL of this gateway's protected-
+ *                                                resource-metadata document, embedded in 401
+ *                                                WWW-Authenticate challenges (RFC 9728).
+ * @param {number}   [opts.discoveryTimeoutMs]   OIDC discovery + JWKS fetch timeout (default 10s).
+ * @param {Function} [opts.log]                  optional (msg)=>void for server-side diagnostics
+ *                                                (the real reason is logged, NOT leaked to clients).
+ * @returns {{ validate:(authHeader:string|undefined)=>Promise<object>, unauthorized:Function,
+ *             jwksReady:()=>boolean }}
+ */
+function createValidator(cfg, opts) {
+  const o = opts || {};
+  const resourceMetadataUrl = typeof o.resourceMetadataUrl === 'string' ? o.resourceMetadataUrl : '';
+  const log = typeof o.log === 'function' ? o.log : () => {};
+  const discoveryTimeoutMs = Number.isFinite(o.discoveryTimeoutMs) ? o.discoveryTimeoutMs : 10000;
+
+  // The JWKS resolver is built ONCE, lazily, on first validate — memoised across calls. jose's
+  // createRemoteJWKSet owns the HTTP fetch, in-memory cache, cooldown, and refetch-on-unknown-kid
+  // (key rotation) — we do not hand-roll any of that. A build failure is recomputed next call so a
+  // transient discovery outage self-heals.
+  let jwks = null;
+  let jwksBuildPromise = null;
+
+  function unauthorized(status, error, description, logReason) {
+    if (logReason) log(`auth reject: ${logReason}`);
+    return {
+      ok: false,
+      status: status || 401,
+      error: error || 'invalid_token',
+      errorDescription: description || '',
+      wwwAuthenticate: buildWwwAuthenticate({ resourceMetadataUrl, error, description }),
+    };
+  }
+
+  async function ensureJwks() {
+    if (jwks) return jwks;
+    if (!jwksBuildPromise) {
+      jwksBuildPromise = (async () => {
+        const jose = loadJose();
+        if (!jose) throw new Error('jose is not installed');
+        const uri = await resolveJwksUri(cfg, discoveryTimeoutMs);
+        // cooldownDuration throttles refetches on unknown-kid; cacheMaxAge bounds key staleness.
+        return jose.createRemoteJWKSet(new URL(uri), { cooldownDuration: 30000, cacheMaxAge: 600000 });
+      })().catch((e) => {
+        jwksBuildPromise = null; // allow a retry on the next request (self-heal)
+        throw e;
+      });
+    }
+    jwks = await jwksBuildPromise;
+    return jwks;
+  }
+
+  async function validate(authorizationHeader) {
+    // Fail closed if the dependency or configuration is not coherent — never allow on misconfig.
+    const jose = loadJose();
+    if (!jose) {
+      return unauthorized(500, 'server_error', 'authentication unavailable', 'jose not installed');
+    }
+    if (!cfg.audience) {
+      // Without an audience we cannot bind the token to THIS resource (RFC 8707) — refuse rather
+      // than validate an unbound token (the confused-deputy hole). Belt-and-braces: the transport
+      // refuses to start in this state, but a request must still never slip through.
+      return unauthorized(500, 'server_error', 'authentication misconfigured', 'no audience configured');
+    }
+
+    const token = extractBearer(authorizationHeader);
+    if (!token) {
+      // No credentials → a BARE challenge (no error code), the canonical "authenticate, please".
+      return unauthorized(401, '', '', 'missing or malformed Authorization header');
+    }
+
+    let resolver;
+    try {
+      resolver = await ensureJwks();
+    } catch (e) {
+      // Cannot reach/parse the key source → cannot verify → reject (do not leak the URL/reason).
+      return unauthorized(401, 'invalid_token', 'unable to verify token', `jwks unavailable: ${(e && e.message) || e}`);
+    }
+
+    let result;
+    try {
+      // The security-critical call. algorithms PINS the allowlist (blocks alg-confusion + alg:none);
+      // 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,
+        audience: cfg.audience,
+        algorithms: cfg.algorithms,
+        clockTolerance: cfg.clockToleranceSec,
+        // Require `exp` to be PRESENT — jose only checks exp/nbf when present, so without this a
+        // token that omits exp would be accepted as never-expiring. RFC 9068 access tokens carry
+        // exp; a resource server should reject one that does not.
+        requiredClaims: ['exp'],
+      });
+    } catch (e) {
+      return unauthorized(401, 'invalid_token', 'token verification failed', `jwtVerify: ${(e && e.code) || (e && e.message) || e}`);
+    }
+
+    const claims = result && result.payload ? result.payload : {};
+
+    // Optional scope enforcement — every required scope must be present, else 403 insufficient_scope.
+    if (Array.isArray(cfg.requiredScopes) && cfg.requiredScopes.length > 0) {
+      const have = scopesOf(claims);
+      const missing = cfg.requiredScopes.filter((s) => !have.has(s));
+      if (missing.length > 0) {
+        return {
+          ok: false,
+          status: 403,
+          error: 'insufficient_scope',
+          errorDescription: `missing scope: ${missing.join(' ')}`,
+          wwwAuthenticate: buildWwwAuthenticate({
+            resourceMetadataUrl,
+            error: 'insufficient_scope',
+            description: `missing scope: ${missing.join(' ')}`,
+          }),
+        };
+      }
+    }
+
+    return {
+      ok: true,
+      sub: typeof claims.sub === 'string' ? claims.sub : undefined,
+      claims,
+      scopes: Array.from(scopesOf(claims)),
+    };
+  }
+
+  return { validate, unauthorized, jwksReady: () => jwks != null };
+}
+
+/**
+ * protectedResourceMetadata — the RFC 9728 Protected Resource Metadata document for this gateway.
+ * Served (unauthenticated) at /.well-known/oauth-protected-resource so a client can discover which
+ * authorization server issues tokens for this resource. NEVER throws.
+ * @param {object} cfg  the resolved auth config
+ * @returns {{ resource:string, authorization_servers:string[], bearer_methods_supported:string[],
+ *             scopes_supported?:string[] }}
+ */
+function protectedResourceMetadata(cfg) {
+  const doc = {
+    resource: (cfg && cfg.audience) || '',
+    authorization_servers: cfg && cfg.issuer ? [cfg.issuer] : [],
+    bearer_methods_supported: ['header'],
+  };
+  if (cfg && Array.isArray(cfg.requiredScopes) && cfg.requiredScopes.length > 0) {
+    doc.scopes_supported = cfg.requiredScopes.slice();
+  }
+  return doc;
+}
+
+module.exports = {
+  JOSE_PIN,
+  isJoseInstalled,
+  createValidator,
+  protectedResourceMetadata,
+  buildWwwAuthenticate,
+  extractBearer,
+  scopesOf,
+  resolveJwksUri,
+  _resetJoseCache,
+};

package/src/core/events.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * 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
+ * match Claude Code's documented hook input byte-for-byte so the real hook
+ * scripts run unchanged. Do not rename or add fields.
+ *
+ * CommonJS only. Zero host imports (core/ must run headless under node --test).
+ */
+
+/**
+ * The six lifecycle events v3 supports (HOOK_ENGINE.md §1).
+ * 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.
+ */
+const EVENTS = Object.freeze({
+  SessionStart: 'SessionStart',
+  UserPromptSubmit: 'UserPromptSubmit',
+  PreToolUse: 'PreToolUse',
+  PostToolUse: 'PostToolUse',
+  Stop: 'Stop',
+  PreCompact: 'PreCompact',
+});
+
+// Set of valid event names for fast membership checks / validation.
+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):
+ *   session_id, transcript_path, cwd, hook_event_name
+ * supplied by `ctx`. Each event then adds its own fields from `extra`:
+ *
+ *   SessionStart      → source            : "startup" | "resume" | "compact"
+ *   UserPromptSubmit  → prompt            : "<user text>"
+ *   PreToolUse        → tool_name, tool_input
+ *   PostToolUse       → tool_name, tool_input, tool_response
+ *   Stop              → stop_hook_active   : true | false
+ *   PreCompact        → trigger ("manual"|"auto"), custom_instructions
+ *
+ * @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.
+ * @throws {Error} if `event` is not one of the six known events.
+ */
+function buildPayload(event, ctx, extra) {
+  if (!EVENT_NAMES.includes(event)) {
+    throw new Error(`buildPayload: unknown event "${event}"`);
+  }
+
+  const c = ctx || {};
+  const e = extra || {};
+
+  // Common fields — present on EVERY event, in the order §2 lists them.
+  // hook_event_name is always the canonical event string (not whatever ctx held).
+  const payload = {
+    session_id: c.session_id,
+    transcript_path: c.transcript_path,
+    cwd: c.cwd,
+    hook_event_name: event,
+  };
+
+  // Event-specific additions. Each branch sets EXACTLY the fields §2 names —
+  // no more, no fewer — so the payload matches Claude Code's shape precisely.
+  switch (event) {
+    case EVENTS.SessionStart:
+      payload.source = e.source;
+      break;
+
+    case EVENTS.UserPromptSubmit:
+      payload.prompt = e.prompt;
+      break;
+
+    case EVENTS.PreToolUse:
+      payload.tool_name = e.tool_name;
+      payload.tool_input = e.tool_input;
+      break;
+
+    case EVENTS.PostToolUse:
+      payload.tool_name = e.tool_name;
+      payload.tool_input = e.tool_input;
+      payload.tool_response = e.tool_response;
+      break;
+
+    case EVENTS.Stop:
+      payload.stop_hook_active = e.stop_hook_active;
+      break;
+
+    case EVENTS.PreCompact:
+      payload.trigger = e.trigger;
+      payload.custom_instructions = e.custom_instructions;
+      break;
+
+    // No default: the membership check above already rejected unknown events.
+  }
+
+  return payload;
+}
+
+module.exports = { EVENTS, EVENT_NAMES, buildPayload };

package/src/core/hook-engine.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * hook-engine.js — fire a lifecycle event through its matching, enabled hooks.
+ *
+ * Contract: HOOK_ENGINE.md §6.
+ *
+ *   class HookEngine {
+ *     constructor(loader)                       // loader provides enabled hook specs
+ *     async fire(event, ctx, extra) → {
+ *       injected:  string,        // all non-null inject fragments joined by "\n"
+ *       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
+ *     }
+ *   }
+ *
+ * Behaviour:
+ *   - Select hooks where spec.event === event AND spec.enabled AND matches(spec.matcher, toolName).
+ *     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.
+ *   - 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.
+ *   - injected = every non-null inject joined by "\n", in order.
+ *   - 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:
+ * any rejection is converted into a synthetic error result so fire() never rejects.
+ *
+ * CommonJS only. Zero host imports (must run headless under `node --test`).
+ */
+
+const path = require('node:path');
+
+// Sibling core modules (authored to the same contract in this build pass).
+const matcher = require('./matcher');
+const events = require('./events');
+const hookRunner = require('./hook-runner');
+
+const DEFAULT_CONCURRENCY = 8;
+
+/**
+ * Resolve the matcher function from matcher.js regardless of whether it is the default or
+ * a named export, so we interlock with the contract's `matches(matcher, toolName)`.
+ * @returns {(m: string|undefined, toolName: string) => boolean}
+ */
+function getMatchesFn() {
+  if (typeof matcher === 'function') return matcher;
+  if (matcher && typeof matcher.matches === 'function') return matcher.matches;
+  // Defensive fallback: if matcher.js is unavailable, fire everything (never crash).
+  return () => true;
+}
+
+/**
+ * Resolve buildPayload from events.js (named export per contract).
+ * @returns {(event: string, ctx: object, extra: object) => object}
+ */
+function getBuildPayloadFn() {
+  if (events && typeof events.buildPayload === 'function') return events.buildPayload;
+  // Defensive fallback: assemble a minimal common payload.
+  return (event, ctx, extra) =>
+    Object.assign(
+      {
+        session_id: (ctx && ctx.session_id) || '',
+        transcript_path: (ctx && ctx.transcript_path) || '',
+        cwd: (ctx && ctx.cwd) || process.cwd(),
+        hook_event_name: event,
+      },
+      extra || {}
+    );
+}
+
+/**
+ * Resolve runHook from hook-runner.js (named export per contract).
+ * @returns {(spec: object, payload: object, opts: object) => Promise<object>}
+ */
+function getRunHookFn() {
+  if (hookRunner && typeof hookRunner.runHook === 'function') return hookRunner.runHook;
+  if (typeof hookRunner === 'function') return hookRunner;
+  throw new Error('hook-engine: hook-runner.runHook is unavailable');
+}
+
+/**
+ * Build a synthetic "failed" result matching the §4 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
+ * @param {Error} err
+ * @param {number} durationMs
+ * @returns {object}
+ */
+function syntheticFailure(spec, event, err, durationMs) {
+  return {
+    id: spec && spec.id,
+    event,
+    exitCode: -1,
+    timedOut: false,
+    stdout: '',
+    stderr: (err && err.message) || String(err),
+    blocked: false,
+    stopLoop: false,
+    reason: null,
+    inject: null,
+    durationMs: durationMs || 0,
+  };
+}
+
+/**
+ * Run an array of async task factories with a concurrency cap, preserving input order in
+ * the returned results array. Each task is a `() => Promise<T>`; the returned slot holds
+ * the resolved value (tasks here are written to never reject).
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} taskFactories
+ * @param {number} cap maximum simultaneous tasks
+ * @returns {Promise<T[]>} results in the same order as taskFactories
+ */
+async function runWithConcurrency(taskFactories, cap) {
+  const total = taskFactories.length;
+  const results = new Array(total);
+  if (total === 0) return results;
+
+  const limit = Math.max(1, Math.min(cap || DEFAULT_CONCURRENCY, total));
+  let nextIndex = 0;
+
+  // Each worker pulls the next index until the queue drains.
+  async function worker() {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const i = nextIndex++;
+      if (i >= total) return;
+      results[i] = await taskFactories[i]();
+    }
+  }
+
+  const workers = [];
+  for (let w = 0; w < limit; w++) workers.push(worker());
+  await Promise.all(workers);
+  return results;
+}
+
+class HookEngine {
+  /**
+   * @param {object} loader a HookLoader (or any object exposing enabledHooksFor(event)).
+   * @param {object} [options]
+   * @param {number} [options.concurrency=8] global concurrency cap per fire().
+   * @param {string} [options.cwd] working dir passed to the runner.
+   * @param {object} [options.env] base env merged into the runner's child env.
+   */
+  constructor(loader, options) {
+    if (!loader || typeof loader.enabledHooksFor !== 'function') {
+      throw new TypeError('HookEngine: loader must expose enabledHooksFor(event)');
+    }
+    this.loader = loader;
+    const opts = options || {};
+    this.concurrency =
+      Number.isInteger(opts.concurrency) && opts.concurrency > 0
+        ? opts.concurrency
+        : DEFAULT_CONCURRENCY;
+    this.cwd = opts.cwd || (loader.hooksDir ? path.dirname(loader.hooksDir) : process.cwd());
+    this.env = opts.env || null;
+
+    // Resolve contract functions once.
+    this._matches = getMatchesFn();
+    this._buildPayload = getBuildPayloadFn();
+    this._runHook = getRunHookFn();
+  }
+
+  /**
+   * Fire a lifecycle event through its matching, enabled hooks.
+   *
+   * @param {string} event one of EVENTS (e.g. "PreToolUse")
+   * @param {object} [ctx] common context: { session_id, transcript_path, cwd, ... }
+   * @param {object} [extra] event-specific fields (tool_name, tool_input, prompt, source, …)
+   * @returns {Promise<{injected:string, blocked:boolean, reason:(string|null),
+   *                     stopLoop:boolean, results:object[]}>}
+   */
+  async fire(event, ctx, extra) {
+    const context = ctx || {};
+    const extraFields = extra || {};
+
+    // Build the stdin payload once (frozen field names per §2).
+    let payload;
+    try {
+      payload = this._buildPayload(event, context, extraFields);
+    } catch (err) {
+      // If payload assembly fails, fall back to a minimal valid payload so hooks still run.
+      payload = Object.assign(
+        {
+          session_id: context.session_id || '',
+          transcript_path: context.transcript_path || '',
+          cwd: context.cwd || this.cwd,
+          hook_event_name: event,
+        },
+        extraFields
+      );
+    }
+
+    // The toolName for matcher scoping comes from the payload (tool-bearing events only).
+    // 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;
+        }
+        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.
+    const injectFragments = [];
+    let blocked = false;
+    let reason = null;
+    let stopLoop = false;
+
+    for (const r of results) {
+      if (!r) continue;
+      if (r.inject != null) injectFragments.push(r.inject);
+      if (r.blocked && !blocked) {
+        // First blocker in order owns the reason.
+        blocked = true;
+        reason = r.reason != null ? r.reason : null;
+      }
+      if (r.stopLoop) stopLoop = true;
+    }
+
+    return {
+      injected: injectFragments.join('\n'),
+      blocked,
+      reason,
+      stopLoop,
+      results,
+    };
+  }
+}
+
+module.exports = {
+  HookEngine,
+  DEFAULT_CONCURRENCY,
+  // Exported for unit tests / reuse:
+  runWithConcurrency,
+};