toolfunnel 0.6.0 → 0.7.0

package/src/core/hook-loader.js

@@ -3,7 +3,7 @@
 /**
  * hook-loader.js - load and persist the hook manifest, resolve runnable specs.
  *
- * Contract: HOOK_ENGINE.md §7 (manifest shape) and §8 (loader API).
+ * Contract: the manifest shape and the loader API are both specified below.
  *
  * Responsibilities:
  *   - loadManifest(path): read hooks.manifest.json, expand ${HOOKS_DIR} (the absolute
@@ -14,7 +14,7 @@
  *   - writeScript(id, text): save to the COPY under src/hooks/scripts - and REFUSE any
  *     resolved path outside src/hooks/scripts (path-traversal guard, isolation rule).
  *
- * Hook Manager v2 additions (see the architecture notes §4) - all ADDITIVE; the API above
+ * Hook Manager v2 additions - all ADDITIVE; the API above
  * keeps its exact behaviour so the existing loader tests still pass:
  *   - AUTO-DETECT: autodetect() scans <hooksDir>/scripts for hook scripts and reconciles
  *     them with the manifest. The FOLDER is the source of truth for what EXISTS; the
@@ -38,6 +38,10 @@ const path = require('node:path');
 // six supported events. events.js has zero host imports, so this cannot cycle.
 const { EVENT_NAMES } = require('./events');
 
+// The matcher-compile discriminator - addEntry refuses a matcher that can never be
+// evaluated (matcher.js has zero host imports, so this cannot cycle either).
+const { matcherError } = require('./matcher');
+
 /**
  * Extensions we treat as hook scripts during auto-detect. Everything else in the
  * scripts dir (e.g. *.conf files, READMEs) is config/data, not a hook.
@@ -251,7 +255,7 @@ class HookLoader {
     };
   }
 
-  /** @returns {object} alias of {@link HookLoader#autodetect} (contract §4 naming). */
+  /** @returns {object} alias of {@link HookLoader#autodetect} (compatibility naming). */
   reconcile() { return this.autodetect(); }
   /** @returns {object} alias of {@link HookLoader#autodetect}. */
   reconcileScripts() { return this.autodetect(); }
@@ -313,12 +317,7 @@ class HookLoader {
     const liveSpec = this.getSpec(id);
     if (liveSpec) liveSpec.enabled = desired;
 
-    // (1) Persist the overlay - the authoritative, precedence-winning store.
-    const overlay = this.readState();
-    overlay[id] = desired;
-    this.writeState(overlay);
-
-    // (2) Mirror into the manifest when a matching row exists (keeps the manifest a
+    // (1) Mirror into the manifest when a matching row exists (keeps the manifest a
     //     faithful default and preserves the v1 setEnabled contract). Skipped for
     //     detected-only ids that have no manifest row.
     let raw;
@@ -330,17 +329,32 @@ class HookLoader {
       raw = collapseManifest(this.manifest, this.hooksDir);
     }
 
+    let manifestRow = false;
     if (raw && Array.isArray(raw.hooks)) {
       const rawSpec = raw.hooks.find((h) => h && h.id === id);
       if (rawSpec) {
+        manifestRow = true;
         rawSpec.enabled = desired;
         atomicWriteJson(this.manifestPath, raw);
       }
     }
 
-    // True if we toggled a known manifest hook; also true if we recorded the overlay
-    // for a detected (manifest-less) hook so the manager can persist its state.
-    return !!liveSpec || true;
+    // (2) Persist the overlay - the authoritative, precedence-winning store - ONLY for an id
+    //     that matched something. The first correction here fixed the constant-true return
+    //     (`!!liveSpec || true`) but left this write unconditional, so a typo'd id still left a
+    //     stray key in hooks.state.json forever. Strays are not inert: applyState() lays the
+    //     overlay over the manifest at every load, so a future hook adopting the id would boot
+    //     silently in the stale recorded state - a pre-disabled gate.
+    if (liveSpec || manifestRow) {
+      const overlay = this.readState();
+      overlay[id] = desired;
+      this.writeState(overlay);
+    }
+
+    // True if we toggled a known manifest hook; also true for a detected (manifest-less) hook
+    // so the manager can persist its state. An id matching NEITHER is a miss: report false,
+    // write nothing.
+    return !!liveSpec || manifestRow;
   }
 
   /**
@@ -357,7 +371,9 @@ class HookLoader {
    *   - id: non-empty string; must not already exist in the manifest (rejected if it does)
    *   - event: one of the lifecycle EVENTS (EVENT_NAMES)
    *   - command: non-empty string
-   *   - matcher/script/timeout/description: optional, stored verbatim
+   *   - matcher: optional string; must COMPILE under matcher.js's anchoring (rejected
+   *     otherwise - an uncompilable matcher can never be evaluated)
+   *   - script/timeout/description: optional, stored verbatim
    *   - enabled: defaults to (spec.enabled === true)
    * @returns {object} the stored spec (exactly as written to the manifest)
    * @throws TypeError/Error if validation fails or the id already exists
@@ -377,6 +393,23 @@ class HookLoader {
     if (typeof spec.command !== 'string' || spec.command.length === 0) {
       throw new Error('addEntry: spec.command must be a non-empty string');
     }
+    // A matcher that does not compile can never be evaluated - storing it would author a
+    // hook whose gate the engine must refuse on every tool-bearing call (hook-engine's
+    // unreadable-gate rule). Refuse HERE so the UI's POST /api/hooks/add and tf_hook_add
+    // both answer with the problem instead of 200/ok. (0.7.0; matcher-compile.test.js.)
+    if (spec.matcher !== undefined && spec.matcher !== null && typeof spec.matcher !== 'string') {
+      throw new Error('addEntry: spec.matcher must be a string when provided');
+    }
+    {
+      const compileProblem = matcherError(spec.matcher);
+      if (compileProblem) {
+        throw new Error(
+          `addEntry: spec.matcher ${JSON.stringify(spec.matcher)} does not compile as a ` +
+          `regular expression (${compileProblem}) - matchers are anchored regexes ` +
+          '(e.g. "Bash|Write"), not globs'
+        );
+      }
+    }
 
     // The stored spec: every supplied field VERBATIM, with enabled normalized to a
     // strict boolean. The command is left untouched so a portable ${HOOKS_DIR} token

package/src/core/hook-runner.js

@@ -3,30 +3,45 @@
 /**
  * hook-runner.js - run ONE command hook and return a structured result.
  *
- * Authoritative contract: docs/HOOK_ENGINE.md §3 (two output protocols) and §4
- * (the exact result shape). This module is backend-agnostic and has ZERO host-framework
- * imports so it runs headless under `node --test`.
+ * Contract: the two output protocols and the exact result shape are specified below and pinned by
+ * test/gate.test.js + test/hook-runner-bounds.test.js. This module is backend-agnostic and has
+ * ZERO host-framework imports so it runs headless under `node --test`.
  *
- * Hard guarantee (§4): runHook NEVER rejects. A spawn failure or a timeout always
+ * Hard guarantee: runHook NEVER rejects. A spawn failure or a timeout always
  * resolves with the full result object (exitCode:-1, timedOut set appropriately,
  * blocked:false).
  */
 
 const { spawn, execFile } = require('node:child_process');
+const reaper = require('./child-reaper');
 const path = require('node:path');
 
 // Default HOOKS_DIR: <root>/src/hooks. __dirname is <root>/src/core, so up one.
 const DEFAULT_HOOKS_DIR = path.resolve(__dirname, '..', 'hooks');
 
-// Events whose exit-0 stdout is treated as injected context (§3-A, §1 table).
+// Events whose exit-0 stdout is treated as injected context (the exit-code protocol's injection half).
 const INJECTABLE_EVENTS = new Set(['SessionStart', 'UserPromptSubmit']);
 
+// Returned by tryParseJsonProtocol when stdout was clearly meant to be a protocol object (it opens
+// with '{') but does not parse. This is DISTINCT from null: null means "no protocol was attempted,
+// use the exit-code protocol", whereas this means "a decision was attempted but could not be read".
+// The two must be handled differently - an unreadable decision fails closed, the same as output
+// past the cap, so a decision that loses a character is never mistaken for "allow".
+const CORRUPT_PROTOCOL = Symbol('corrupt-protocol');
+
+// Output ceilings. A hook's decision is a small JSON object and its diagnostics are a few lines;
+// anything approaching these is a runaway, and accumulating it unbounded would OOM the gateway
+// itself. Hitting either cap is treated as a WIRING FAILURE and fails closed (see the accumulator
+// and the close handler) - an unreadable decision must never pass for "allow".
+const MAX_STDOUT_BYTES = 1024 * 1024; // 1 MiB
+const MAX_STDERR_BYTES = 256 * 1024; //  256 KiB
+
 /**
- * Decide whether a parsed stdout object should be treated as the §3-B JSON
+ * Decide whether a parsed stdout object should be treated as the JSON
  * protocol. We only switch to the JSON interpretation when the object actually
  * carries one of the protocol's known keys - otherwise an arbitrary JSON blob a
- * hook happens to print should fall through to the exit-code protocol (§3:
- * "Exit-code protocol wins if stdout is not valid JSON").
+ * hook happens to print should fall through to the exit-code protocol ("the
+ * exit-code protocol wins if stdout is not valid JSON").
  *
  * @param {*} parsed
  * @returns {boolean}
@@ -44,23 +59,28 @@ function isKnownJsonProtocol(parsed) {
 }
 
 /**
- * Try to parse stdout as the JSON protocol. Returns the parsed object only if it
- * is valid JSON AND carries known protocol keys; otherwise null (use exit-code
- * protocol).
+ * Try to parse stdout as the JSON protocol. Returns the parsed object if it is
+ * valid JSON AND carries known protocol keys; CORRUPT_PROTOCOL if stdout opened
+ * with '{' (a protocol object was attempted) but did not parse; otherwise null
+ * (no protocol attempt - use the exit-code protocol).
  *
  * @param {string} stdout
- * @returns {object|null}
+ * @returns {object|symbol|null}
  */
 function tryParseJsonProtocol(stdout) {
   const trimmed = (stdout || '').trim();
   if (!trimmed) return null;
-  // Cheap pre-check: protocol output is always a JSON object.
+  // Cheap pre-check: protocol output is always a JSON object. Anything not opening with '{' made
+  // no protocol attempt and belongs to the exit-code protocol (arbitrary text a hook prints).
   if (trimmed[0] !== '{') return null;
   let parsed;
   try {
     parsed = JSON.parse(trimmed);
   } catch (_e) {
-    return null; // not valid JSON -> exit-code protocol wins
+    // Opened with '{' but is not valid JSON: an attempted decision that could not be read. Signal
+    // CORRUPT (fail closed) rather than null - falling through to exit-code here would let a
+    // truncated or malformed deny be read as "allow".
+    return CORRUPT_PROTOCOL;
   }
   return isKnownJsonProtocol(parsed) ? parsed : null;
 }
@@ -76,7 +96,7 @@ function tryParseJsonProtocol(stdout) {
  * @param {string} [opts.projectDir]      value for CLAUDE_PROJECT_DIR.
  * @param {string} [opts.hooksDir]        value for HOOKS_DIR (default <root>/src/hooks).
  * @param {AbortSignal} [opts.signal]      external cancellation; aborts the child.
- * @returns {Promise<object>}  the §4 result shape. Never rejects.
+ * @returns {Promise<object>}  the full result shape. Never rejects.
  */
 function runHook(hookSpec, payload, opts = {}) {
   return new Promise((resolve) => {
@@ -100,7 +120,7 @@ function runHook(hookSpec, payload, opts = {}) {
       durationMs: 0,
     });
 
-    // Guard: a malformed spec must not throw out of the runner (§4: never reject).
+    // Guard: a malformed spec must not throw out of the runner (the never-reject guarantee).
     if (!hookSpec || typeof hookSpec.command !== 'string' || hookSpec.command.length === 0) {
       const r = baseResult();
       r.stderr = 'hook-runner: invalid hookSpec (missing command)';
@@ -109,14 +129,14 @@ function runHook(hookSpec, payload, opts = {}) {
       return;
     }
 
-    // timeout is stored in SECONDS in the manifest -> convert to ms (§4).
+    // timeout is stored in SECONDS in the manifest -> convert to ms.
     // Fall back to a sane default if absent or non-positive.
     const timeoutSec =
       typeof hookSpec.timeout === 'number' && hookSpec.timeout > 0 ? hookSpec.timeout : 60;
     const timeoutMs = timeoutSec * 1000;
 
     // Child env: inherit process.env, layer opts.env, then set the two paths the
-    // hook scripts rely on to resolve themselves (§4).
+    // hook scripts rely on to resolve themselves.
     const hooksDir = opts.hooksDir || (opts.env && opts.env.HOOKS_DIR) || DEFAULT_HOOKS_DIR;
     const projectDir =
       opts.projectDir ||
@@ -131,9 +151,20 @@ function runHook(hookSpec, payload, opts = {}) {
     });
 
     // Own AbortController so we can enforce the timeout via kill, and chain any
-    // externally-supplied signal so the engine can cancel us too.
+    // externally-supplied signal so the engine can cancel us too. The abort path RESOLVES
+    // immediately, exactly like the timeout: it must not depend on 'close', which a surviving
+    // grandchild holding inherited pipes can withhold forever (the same reasoning that moved
+    // the timeout onto its timer).
+    const onExternalAbort = () => {
+      timedOut = true;
+      killChildTree();
+      const r = baseResult();
+      r.stdout = stdout;
+      r.stderr = stderr || 'hook-runner: aborted by caller signal';
+      r.timedOut = true; // exitCode -1, blocked false - the caller cancelled, same class as a timeout
+      finish(r);
+    };
     const controller = new AbortController();
-    const onExternalAbort = () => killChildTree();
     if (opts.signal) {
       if (opts.signal.aborted) controller.abort();
       else opts.signal.addEventListener('abort', onExternalAbort, { once: true });
@@ -147,7 +178,17 @@ function runHook(hookSpec, payload, opts = {}) {
         env: childEnv,
         signal: controller.signal,
         windowsHide: true,
+        // POSIX: give the shell its OWN PROCESS GROUP so killChildTree can tear down the
+        // grandchildren too (see the comment there - killing the shell alone orphans them and
+        // they hold the stdio pipes open forever). Windows has no process groups in this sense
+        // and uses taskkill /T instead; `detached` there only suppresses a console window, which
+        // windowsHide already covers, so it stays off to keep Windows behaviour byte-identical.
+        detached: process.platform !== 'win32',
       });
+      // Last-resort sweep: if the gateway dies without running killChildTree (crash, signal),
+      // the reaper's exit handler kills whatever is still tracked - detached children have left
+      // our session and would otherwise run to their natural end unsupervised.
+      reaper.track(child);
     } catch (err) {
       // Synchronous spawn failure (rare). Resolve, never throw.
       cleanupSignal();
@@ -162,16 +203,26 @@ function runHook(hookSpec, payload, opts = {}) {
     let stderr = '';
     let timedOut = false;
     let settled = false;
-
-    // Kill the WHOLE child tree. On Windows, killing the shell (cmd.exe) does NOT
-    // kill its node/bash grandchildren - they orphan and hold the stdio pipes open,
-    // which prevents the parent process (and node:test) from ever exiting. taskkill
-    // /T tears down the tree so the pipes close and nothing lingers. (Real hooks
-    // that hang would orphan the same way, so this matters beyond the test suite.)
+    let outputCapped = null; // 'stdout' | 'stderr' once a cap was hit (fail-closed trigger)
+
+    // Kill the WHOLE child tree. Killing the shell (cmd.exe / sh) does NOT kill its node/bash
+    // grandchildren - they orphan and hold the stdio pipes open, which prevents the parent
+    // process (and node:test) from ever exiting. Both platforms need a TREE kill, by their own
+    // mechanism: Windows has taskkill /T; POSIX has process groups, which is why the spawn above
+    // sets `detached` there - the shell is a group leader, so kill(-pid) reaches every descendant.
+    // (Before 0.7.0 the POSIX branch sent SIGKILL to the shell alone: the bug was diagnosed in
+    // this comment and fixed for Windows only.)
     function killChildTree() {
       try {
         if (child && child.pid != null && process.platform === 'win32') {
           execFile('taskkill', ['/pid', String(child.pid), '/T', '/F'], () => {});
+        } else if (child && child.pid != null) {
+          // Negative pid = the whole process group. ESRCH simply means it is already gone.
+          try {
+            process.kill(-child.pid, 'SIGKILL');
+          } catch (_eg) {
+            child.kill('SIGKILL'); // group gone or never formed - fall back to the direct child
+          }
         } else if (child) {
           child.kill('SIGKILL');
         }
@@ -189,10 +240,22 @@ function runHook(hookSpec, payload, opts = {}) {
       }
     }
 
-    // Hard timeout: kill the child tree; the 'close'/'error' handler resolves.
+    // Hard timeout: kill the child tree AND resolve immediately - never wait for 'close'.
+    //
+    // 'close' fires only when every stdio pipe is closed, and a GRANDCHILD that inherited those
+    // pipes keeps them open for its own lifetime even after the shell is dead. Waiting for 'close'
+    // therefore made the timeout unenforceable in exactly the case it exists for: measured
+    // 2026-07-30, a hook whose grandchild slept 60 s resolved at 60 s against a 2.5 s timeout, on
+    // Windows, WITH taskkill /T. The tree kill still matters (it stops us leaking processes), but
+    // the timeout contract must not depend on it succeeding on any platform.
     const timer = setTimeout(() => {
       timedOut = true;
       killChildTree();
+      const r = baseResult();
+      r.stdout = stdout;
+      r.stderr = stderr || `hook-runner: timed out after ${timeoutMs}ms`;
+      r.timedOut = true; // exitCode -1, blocked false (the timeout contract)
+      finish(r);
     }, timeoutMs);
     if (typeof timer.unref === 'function') timer.unref();
 
@@ -200,25 +263,79 @@ function runHook(hookSpec, payload, opts = {}) {
       if (opts.signal) opts.signal.removeEventListener('abort', onExternalAbort);
     }
 
+    /** A capped hook resolves NOW (same reasoning as the timeout: 'close' may never come) and
+     *  FAILS CLOSED - a decision we stopped reading is not a decision we may treat as allow. */
+    function finishCapped() {
+      const r = baseResult();
+      r.stdout = stdout;
+      r.stderr = stderr;
+      r.blocked = true;
+      r.reason = `hook-runner: ${event || 'hook'}${id ? ` "${id}"` : ''} exceeded the `
+        + `${outputCapped} output cap (`
+        + `${outputCapped === 'stdout' ? MAX_STDOUT_BYTES : MAX_STDERR_BYTES} bytes); `
+        + 'its decision could not be read, so the call is denied (fail closed).';
+      finish(r);
+    }
+
     function finish(result) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       cleanupSignal();
+      // Release our ends of the pipes AND unref the child handle. The pipes alone are not
+      // enough: the ChildProcess handle itself keeps the event loop referenced until the child
+      // exits, so a tree that survives killChildTree (measured: a 30 s grandchild) pinned the
+      // process to its natural death even after we had answered. unref() lets the loop drain;
+      // the 'close'/'error' handlers stay attached and no-op behind the settled guard.
+      for (const s of [child && child.stdout, child && child.stderr, child && child.stdin]) {
+        try { if (s && typeof s.destroy === 'function') s.destroy(); } catch (_e) { /* ignore */ }
+      }
+      try { if (child && typeof child.unref === 'function') child.unref(); } catch (_e) { /* ignore */ }
+      reaper.untrack(child);
       result.durationMs = Date.now() - started;
       resolve(result);
     }
 
+    // BOUNDED accumulation. An unbounded `stdout += chunk` turns a chatty or runaway hook into an
+    // out-of-memory kill of the GATEWAY - a far worse failure than any hook outcome, and in the
+    // one module whose job is running untrusted external processes. Past the cap we stop
+    // accumulating, kill the tree, and (below) FAIL CLOSED: a decision we could not read in full
+    // must never be interpreted as "allow" just because the exit code was 0.
+    // Caps are measured in REAL bytes (Buffer.byteLength), not String.length - the latter counts
+    // UTF-16 code units, which let non-ASCII output run ~3x past a nominal "byte" ceiling.
+    let hrOutBytes = 0;
+    let hrErrBytes = 0;
     if (child.stdout) {
       child.stdout.setEncoding('utf8');
       child.stdout.on('data', (chunk) => {
-        stdout += chunk;
+        if (hrOutBytes >= MAX_STDOUT_BYTES) return;
+        hrOutBytes += Buffer.byteLength(chunk, 'utf8');
+        // Trim the final chunk to the byte budget - streams deliver whole chunks, so appending
+        // before checking retained up to cap+chunkSize (seen: +64KB on win node 18/20, where
+        // chunk boundaries do not align with the cap). Chars trimmed by a byte overshoot can
+        // only under-retain (a char is >= 1 byte), which is the safe side of the ceiling.
+        const outOver = hrOutBytes - MAX_STDOUT_BYTES;
+        stdout += outOver > 0 ? chunk.slice(0, Math.max(0, chunk.length - outOver)) : chunk;
+        if (hrOutBytes >= MAX_STDOUT_BYTES) {
+          outputCapped = 'stdout';
+          killChildTree();
+          finishCapped();
+        }
       });
     }
     if (child.stderr) {
       child.stderr.setEncoding('utf8');
       child.stderr.on('data', (chunk) => {
-        stderr += chunk;
+        if (hrErrBytes >= MAX_STDERR_BYTES) return;
+        hrErrBytes += Buffer.byteLength(chunk, 'utf8');
+        const errOver = hrErrBytes - MAX_STDERR_BYTES;
+        stderr += errOver > 0 ? chunk.slice(0, Math.max(0, chunk.length - errOver)) : chunk;
+        if (hrErrBytes >= MAX_STDERR_BYTES) {
+          stderr += '\n[hook-runner: stderr truncated at cap]';
+          if (!outputCapped) outputCapped = 'stderr';
+          killChildTree();
+          finishCapped();
+        }
       });
     }
 
@@ -242,21 +359,43 @@ function runHook(hookSpec, payload, opts = {}) {
       const r = baseResult();
       r.stdout = stdout;
       r.stderr = stderr || (err && err.message ? err.message : String(err));
+      if (outputCapped) {
+        r.blocked = true;
+        r.reason = `hook-runner: ${event || 'hook'}${id ? ` "${id}"` : ''} exceeded the `
+          + `${outputCapped} output cap; its decision could not be read, so the call is denied (fail closed).`;
+        finish(r);
+        return;
+      }
       if (timedOut) {
         r.timedOut = true;
         r.stderr = stderr || `hook-runner: timed out after ${timeoutMs}ms`;
       }
-      // blocked stays false; exitCode stays -1 (§4).
+      // blocked stays false; exitCode stays -1 (the error contract).
       finish(r);
     });
 
     child.on('close', (code, sig) => {
+      // Output cap hit: the decision is UNREADABLE (we stopped reading mid-stream), so the only
+      // safe classification is a block flagged as a wiring failure. Checked BEFORE the timeout
+      // branch because the cap also kills the tree, which can set timedOut on the way down.
+      if (outputCapped) {
+        const r = baseResult();
+        r.stdout = stdout;
+        r.stderr = stderr;
+        r.blocked = true;
+        r.reason = `hook-runner: ${event || 'hook'}${id ? ` "${id}"` : ''} exceeded the `
+          + `${outputCapped} output cap (${outputCapped === 'stdout' ? MAX_STDOUT_BYTES : MAX_STDERR_BYTES} bytes); `
+          + 'its decision could not be read, so the call is denied (fail closed).';
+        finish(r);
+        return;
+      }
+
       // If we aborted for the timeout, classify as timeout regardless of code.
       if (timedOut) {
         const r = baseResult();
         r.stdout = stdout;
         r.stderr = stderr || `hook-runner: timed out after ${timeoutMs}ms`;
-        r.timedOut = true; // exitCode -1, blocked false (§4)
+        r.timedOut = true; // exitCode -1, blocked false (the timeout contract)
         finish(r);
         return;
       }
@@ -267,7 +406,7 @@ function runHook(hookSpec, payload, opts = {}) {
       // On a clean close, code is a number; if killed by signal, code is null.
       r.exitCode = typeof code === 'number' ? code : -1;
 
-      // --- Protocol interpretation (§3) ---
+      // --- Protocol interpretation ---
       // Exit 2 is ALWAYS stderr-blocking, and stdout/JSON is ignored on any
       // non-zero exit - this matches real Claude Code (the JSON protocol is
       // processed ONLY on a clean exit 0; on exit 2 the reason is stderr).
@@ -278,15 +417,96 @@ function runHook(hookSpec, payload, opts = {}) {
         return;
       }
 
-      // B) Advanced / JSON protocol (§3-B) - honored only on exit 0.
+      // B) Advanced / JSON protocol - honored only on exit 0.
       const json = r.exitCode === 0 ? tryParseJsonProtocol(stdout) : null;
 
+      // A protocol object that FAILED TO PARSE (stdout opened with '{' but is not valid JSON) is an
+      // unreadable decision. It fails closed - denied - the same as output past the cap: the runner
+      // saw an attempted answer it could not read, and an unreadable answer is never "allow". Only
+      // stdout that made no protocol attempt (no leading '{', or valid JSON that is not a decision)
+      // falls through to the exit-code protocol below.
+      if (json === CORRUPT_PROTOCOL) {
+        r.blocked = true;
+        r.reason = `hook-runner: ${event || 'hook'}${id ? ` "${id}"` : ''} emitted a protocol `
+          + 'message that could not be parsed; its decision could not be read, so the call is '
+          + 'denied (fail closed).';
+        finish(r);
+        return;
+      }
+
       if (json) {
         const hso =
           json.hookSpecificOutput && typeof json.hookSpecificOutput === 'object'
             ? json.hookSpecificOutput
             : null;
 
+        // The decision VOCABULARY is exact and case-sensitive: permissionDecision is
+        // allow|deny|ask, top-level decision is block. A decision SLOT carrying any other
+        // value - miscased "DENY", a synonym like "denied", the right word in the wrong
+        // slot, a non-string - is an ATTEMPTED decision the runner cannot read, and an
+        // unreadable decision is never "allow" (the same rule as CORRUPT_PROTOCOL and the
+        // output caps). A key marks an attempt ONLY when it carries a value: `null` is the
+        // readable spelling of "no value" - what typed-struct and dataclass serialisers
+        // emit for an unset optional field - so a null slot is no decision and falls
+        // through exactly as the absent key does. (0.7.0; gate-semantics.test.js pins
+        // both halves.)
+        const permAttempted =
+          hso !== null &&
+          Object.prototype.hasOwnProperty.call(hso, 'permissionDecision') &&
+          hso.permissionDecision !== null;
+        const decisionAttempted =
+          Object.prototype.hasOwnProperty.call(json, 'decision') && json.decision !== null;
+        const permUnknown =
+          permAttempted &&
+          hso.permissionDecision !== 'allow' &&
+          hso.permissionDecision !== 'deny' &&
+          hso.permissionDecision !== 'ask';
+        const decisionUnknown = decisionAttempted && json.decision !== 'block';
+        // Same rule for the OTHER protocol slots: `continue` is boolean and
+        // `hookSpecificOutput` is an object - a present NON-NULL key with any other type
+        // is an attempted instruction that cannot be read. The hso check tests the RAW
+        // value: `hso` coerces both null and a wrong type (a bare string, a number) to
+        // null, and only the wrong types are unreadable attempts.
+        const contUnknown =
+          Object.prototype.hasOwnProperty.call(json, 'continue') &&
+          json.continue !== null &&
+          typeof json.continue !== 'boolean';
+        const hsoUnknown =
+          Object.prototype.hasOwnProperty.call(json, 'hookSpecificOutput') &&
+          json.hookSpecificOutput !== null &&
+          (hso === null || Array.isArray(hso));
+        if (permUnknown || decisionUnknown || contUnknown || hsoUnknown) {
+          const slot = permUnknown
+            ? 'hookSpecificOutput.permissionDecision'
+            : decisionUnknown
+              ? 'decision'
+              : contUnknown
+                ? 'continue'
+                : 'hookSpecificOutput';
+          const got = JSON.stringify(
+            permUnknown
+              ? hso.permissionDecision
+              : decisionUnknown
+                ? json.decision
+                : contUnknown
+                  ? json.continue
+                  : json.hookSpecificOutput
+          );
+          const known = permUnknown
+            ? '"allow", "deny", "ask"'
+            : decisionUnknown
+              ? '"block"'
+              : contUnknown
+                ? 'true, false'
+                : 'an object';
+          r.blocked = true;
+          r.reason = `hook-runner: ${event || 'hook'}${id ? ` "${id}"` : ''} emitted ${slot}: `
+            + `${got}, which is not in the protocol vocabulary (${known}); its decision could `
+            + 'not be read, so the call is denied (fail closed).';
+          finish(r);
+          return;
+        }
+
         // PreToolUse blocks via hookSpecificOutput.permissionDecision
         // (allow|deny|ask), NOT top-level decision - this is the real Claude Code
         // mechanism. "deny" blocks (reason = permissionDecisionReason). "allow"
@@ -313,12 +533,12 @@ function runHook(hookSpec, payload, opts = {}) {
           if (r.reason == null) r.reason = '';
         } else if (decision === 'block') {
           r.blocked = true;
-          r.reason = jsonReason; // block reason from JSON.reason (§4)
+          r.reason = jsonReason; // block reason from JSON.reason
         }
         if (cont === false) {
-          r.stopLoop = true; // continue:false -> stop the whole loop (§3-B, §4)
+          r.stopLoop = true; // continue:false -> stop the whole loop
         }
-        // additionalContext is the injected text when present (§3-B, §4).
+        // additionalContext is the injected text when present.
         if (additional !== null) {
           r.inject = additional;
         }
@@ -326,7 +546,7 @@ function runHook(hookSpec, payload, opts = {}) {
         return;
       }
 
-      // A) Simple / exit-code protocol (§3-A), exit 0.
+      // A) Simple / exit-code protocol, exit 0.
       if (r.exitCode === 0) {
         // Success. For SessionStart / UserPromptSubmit, stdout IS the injection.
         // For other events stdout is advisory only (captured, not injected).
@@ -336,7 +556,7 @@ function runHook(hookSpec, payload, opts = {}) {
         }
       }
       // Any other non-zero (non-2) code -> non-blocking error: stderr captured,
-      // blocked stays false, reason stays null (§3-A).
+      // blocked stays false, reason stays null.
 
       finish(r);
     });