@opengsd/gsd-core 1.10.0 → 1.12.0

package/hooks/dist/gsd-agent-isolation-guard.js

@@ -43,8 +43,9 @@
 // authoritative — `none`/`orchestrator-worktree` ALLOW immediately
 // (sequential/orchestrator-managed dispatch is legitimate, not a bug); an
 // absent/stale sentinel falls back to a conservative registry+config check
-// (GSD_RUNTIME env > .planning/config.json `runtime` — no confident signal
-// degrades to inert rather than guessing 'claude', see resolveRegistryIsolation)
+// (GSD_RUNTIME env > .planning/config.json `runtime` > the per-install
+// `.gsd-runtime` marker, #3566 — no confident signal degrades to inert rather
+// than guessing 'claude', see resolveRegistryIsolation)
 // gated additionally by `workflow.use_worktrees` — read directly, in-process,
 // no subprocess spawn.
 //
@@ -63,6 +64,32 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
+const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+
+// Required at module top, alongside the other ./lib requires — NOT behind
+// ensureRuntimeBuild() below. Terminating on a parse/timeout failure must
+// never depend on the gitignored build artifacts this hook self-heals for
+// its own registry lookups (#3911).
+//
+// This guard's outer catch (main(), below) has always exited 0 (fail open):
+// that outer catch only covers payload PARSING failing before applicability
+// could even be determined (malformed stdin JSON, etc.) — the guard's real
+// fail-closed logic (a GSD project whose dispatch-isolation configuration
+// cannot be verified) is handled separately, inside evaluateDispatch/
+// resolveIsolationState, and already returns a 'block' decision through the
+// normal exit-2 path rather than through this catch. So an unparseable
+// payload has nothing to enforce; allowing it preserves today's behavior
+// exactly.
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
+// #3582: gsd-core/bin/lib/*.cjs (runtime-name-policy.cjs, capability-registry.cjs
+// below) are tsc build artifacts (ADR-457), gitignored and absent on a raw
+// plugin-marketplace / git-clone install that never ran `npm run build:lib`.
+// Self-heal before the first such require (resolveRegistryIsolation, below) —
+// see ensureRuntimeBuild's own header for the full rationale. This module
+// itself (gsd-core/bin/ensure-runtime-build.cjs) depends on nothing under
+// ./lib, so requiring it here is always safe.
+const { ensureRuntimeBuild, RuntimeBuildError } = require('../gsd-core/bin/ensure-runtime-build.cjs');
 
 // No other executor-shaped subagent_type exists in agents/ today
 // (verified: only agents/gsd-executor.md). A Set, not a bare string compare,
@@ -85,6 +112,42 @@ function parseHarnessFlag(flag) {
   return { param: m[1], value: m[2] };
 }
 
+// ─── #3897 rung 2: per-install runtime marker, single canonical owner ────────
+// bin/install.js writes `<install>/gsd-core/.gsd-runtime` for EVERY runtime
+// install (#2297), co-located with VERSION. Unlike `~/.gsd/defaults.json` —
+// which is host-wide and names whichever runtime's install ran LAST, the exact
+// leakage #2840's config.cjs change exists to prevent — the marker describes
+// THIS install, which is the property runtime identity needs on a machine
+// with 2+ runtimes. Previously this hook held its own private reader/cache
+// (one of four #3897 found); it now delegates to the single canonical owner,
+// `src/runtime-slash.cts` (compiled to gsd-core/bin/lib/runtime-slash.cjs),
+// reached through `ensureRuntimeBuild()` like every other compiled-lib require
+// in this file (`scripts/lint-hooks-runtime-build-seam.cjs`).
+function readInstallRuntimeMarker() {
+  try {
+    ensureRuntimeBuild();
+    const runtimeSlash = require('../gsd-core/bin/lib/runtime-slash.cjs');
+    return runtimeSlash.readInstallRuntimeMarker();
+  } catch {
+    // Unbuilt runtime library, or any other failure reaching the canonical
+    // owner — "no signal from this rung" (N4), never a resolution failure.
+    return null;
+  }
+}
+
+// Test seam for the marker rung — forwards to the canonical owner's seam so
+// this hook and runtime-slash.cjs always share one cache (#3897 rung 2).
+function _setInstallRuntimeMarkerForTests(value) {
+  try {
+    ensureRuntimeBuild();
+    const runtimeSlash = require('../gsd-core/bin/lib/runtime-slash.cjs');
+    runtimeSlash._setInstallRuntimeMarkerForTests(value);
+  } catch {
+    // Test-only seam; an unbuilt library here means the test itself will fail
+    // downstream, which is a louder and more actionable signal than throwing here.
+  }
+}
+
 /**
  * Resolve this project's declared `runtime` identity WITHOUT defaulting to
  * 'claude' when no explicit signal exists (#3045 MAJOR 2).
@@ -100,9 +163,10 @@ function parseHarnessFlag(flag) {
  *
  * Returns `{ runtimeId, confident }`. `confident` is true only when an
  * explicit signal exists (GSD_RUNTIME env override, a `runtime` key literally
- * present in config.json, or a `runtime` persisted to `~/.gsd/defaults.json`
- * by the installer — see below); false means "cannot determine" and callers
- * must NOT silently substitute 'claude' — see resolveRegistryIsolation.
+ * present in config.json, the per-install `.gsd-runtime` marker, or a
+ * `runtime` persisted to `~/.gsd/defaults.json` by the installer — see
+ * below); false means "cannot determine" and callers must NOT silently
+ * substitute 'claude' — see resolveRegistryIsolation.
  *
  * #3045 BLOCKER 2 fix: precedence is GSD_RUNTIME env > config.json `runtime`
  * key > `~/.gsd/defaults.json` `runtime`. The first two are unchanged; the
@@ -117,6 +181,17 @@ function parseHarnessFlag(flag) {
  * (`nativeModelAliases` short-circuits it) and therefore correctly still rely
  * on config.json/env. Reading the installer's own persisted signal makes
  * "confident" the common case instead.
+ *
+ * #3566: the per-install `.gsd-runtime` marker now sits BETWEEN config.json
+ * and defaults.json. defaults.json is host-wide and names whichever runtime
+ * installed LAST — on a 2-runtime machine that confidently resolves the WRONG
+ * runtime (a Codex install's `runtime:"codex"` leaking into Claude projects),
+ * and when the wrong runtime declares no harnessIsolationFlag the guard goes
+ * silently inert. The marker describes THIS install (written for every
+ * runtime since #2297), which is the source #2840's config.cjs change names
+ * as correct. defaults.json stays as the final rung so single-runtime default
+ * installs and pre-#2297 installs (no marker on disk) keep the #3045
+ * BLOCKER 2 behavior.
  */
 function resolveRuntimeIdentity(cwd, configPath, resolveRuntimeNameFromCandidates) {
   const envRuntime = resolveRuntimeNameFromCandidates(process.env.GSD_RUNTIME);
@@ -132,6 +207,13 @@ function resolveRuntimeIdentity(cwd, configPath, resolveRuntimeNameFromCandidate
     if (configRuntime) return { runtimeId: configRuntime, confident: true };
   }
 
+  // #3566: the per-install marker, above the host-wide defaults — see the
+  // block comment on readInstallRuntimeMarker. An empty/whitespace-only file
+  // or an unknown value degrades exactly like the other rungs (no signal /
+  // future-runtime tolerance via resolveRuntimeNameFromCandidates).
+  const markerRuntime = resolveRuntimeNameFromCandidates(readInstallRuntimeMarker());
+  if (markerRuntime) return { runtimeId: markerRuntime, confident: true };
+
   // #3045 BLOCKER 2: fall back to the installer-persisted default. Read
   // defensively — an absent/corrupt/non-object defaults.json is "no signal",
   // never a resolution failure (this function only ever throws for the
@@ -183,6 +265,15 @@ function resolveHarnessFlag(runtimeId, runtimes) {
  * run, e.g. a manual Agent() call before any sentinel has been written).
  */
 function resolveRegistryIsolation(cwd, configPath) {
+  // #3582: self-heal the compiled runtime library BEFORE either require
+  // below — this is the only reaching path to both (resolveRegistryIsolation
+  // is the sole caller of each), so one call here covers both. Throws
+  // RuntimeBuildError on an unbuildable tree; the caller (resolveIsolationState)
+  // already wraps this whole function in try/catch and folds any error into
+  // its fail-closed `error` result — evaluateDispatch below distinguishes a
+  // RuntimeBuildError there so it surfaces this seam's actionable message
+  // instead of being misreported as an unreadable config.json (#3050 lesson).
+  ensureRuntimeBuild();
   const { resolveRuntimeNameFromCandidates } = require('../gsd-core/bin/lib/runtime-name-policy.cjs');
   const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');
 
@@ -208,18 +299,40 @@ function resolveRegistryIsolation(cwd, configPath) {
 
   if (isolation === 'harness-worktree') {
     let useWorktrees = true;
+    // #3972: the opt-out read shares the ONE owner every other
+    // isolation-deciding surface uses — planning-workspace's
+    // worktreesOptedOut ladder (scoped own-key wins; root inherited under
+    // the GSD_WORKSTREAM gate; strict === false). A flat single-file read
+    // here made a workstream-LOCAL opt-out invisible, so the sentinel-absent
+    // fallback denied a sequential dispatch the config explicitly allowed.
+    // Reached through ensureRuntimeBuild() like every other compiled-lib
+    // require in this file (scripts/lint-hooks-runtime-build-seam.cjs); if
+    // the library is unreachable the flat-root read below remains as the
+    // degraded fallback — today's behavior, never worse.
+    let ladderAnswered = false;
     try {
-      const raw = fs.readFileSync(configPath, 'utf-8');
-      const parsedCfg = JSON.parse(raw);
-      if (parsedCfg && typeof parsedCfg === 'object' && parsedCfg.workflow &&
-          typeof parsedCfg.workflow === 'object' && parsedCfg.workflow.use_worktrees === false) {
-        useWorktrees = false;
-      }
+      ensureRuntimeBuild();
+      const { worktreesOptedOut } = require('../gsd-core/bin/lib/planning-workspace.cjs');
+      useWorktrees = !worktreesOptedOut(cwd);
+      ladderAnswered = true;
     } catch {
-      // Unreadable config already propagated to the outer caller's catch
-      // before this point in practice (resolveRuntimeIdentity reads it
-      // first); tolerate defensively and keep the conservative (enforce)
-      // default rather than silently disabling the guard.
+      // Unbuilt runtime library or a ladder failure — fall through to the
+      // legacy flat-root read (conservative: keep enforcing).
+    }
+    if (!ladderAnswered) {
+      try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsedCfg = JSON.parse(raw);
+        if (parsedCfg && typeof parsedCfg === 'object' && parsedCfg.workflow &&
+            typeof parsedCfg.workflow === 'object' && parsedCfg.workflow.use_worktrees === false) {
+          useWorktrees = false;
+        }
+      } catch {
+        // Unreadable config already propagated to the outer caller's catch
+        // before this point in practice (resolveRuntimeIdentity reads it
+        // first); tolerate defensively and keep the conservative (enforce)
+        // default rather than silently disabling the guard.
+      }
     }
     if (!useWorktrees) isolation = 'none';
   }
@@ -360,13 +473,27 @@ function evaluateDispatch(data, { clock = Date } = {}) {
   if (!state.gsdProject) return { action: 'allow' };
 
   if (state.error) {
-    const reason =
-      `Agent isolation guard: could not read or resolve this project's dispatch-isolation ` +
-      `configuration ('.planning/config.json' under '${cwd}'). Refusing to dispatch ` +
-      `subagent_type="${subagentType}" without being able to verify whether isolation is ` +
-      `required — a guard that cannot verify must not answer "safe" (#3050). Retry once the ` +
-      `project configuration is readable.`;
-    return { action: 'block', reason };
+    // #3582: a missing/unbuildable compiled runtime library (RuntimeBuildError,
+    // thrown by ensureRuntimeBuild in resolveRegistryIsolation) is a DIFFERENT,
+    // actionable failure from an unreadable/unparsable config.json — surface
+    // its own message instead of misreporting it as the generic
+    // "could not read or resolve ... configuration" text (the exact #3050
+    // misreport this issue exists to fix). Both cases still fail closed
+    // (block); only the message differs.
+    const isBuildFailure = state.error instanceof RuntimeBuildError;
+    const reason = isBuildFailure
+      ? `Agent isolation guard: cannot resolve this project's dispatch-isolation ` +
+        `configuration because the GSD runtime library failed to self-build. ` +
+        `${state.error.message} Refusing to dispatch subagent_type="${subagentType}" until ` +
+        `the runtime library is built — a guard that cannot verify must not answer "safe" ` +
+        `(#3050).`
+      : `Agent isolation guard: could not read or resolve this project's dispatch-isolation ` +
+        `configuration ('.planning/config.json' under '${cwd}'). Refusing to dispatch ` +
+        `subagent_type="${subagentType}" without being able to verify whether isolation is ` +
+        `required — a guard that cannot verify must not answer "safe" (#3050). Retry once the ` +
+        `project configuration is readable.`;
+    const reasonCode = isBuildFailure ? REASON_CODE.RUNTIME_BUILD_FAILED : REASON_CODE.CONFIG_UNREADABLE;
+    return { action: 'block', reason, reasonCode };
   }
 
   if (state.isolation !== 'harness-worktree') return { action: 'allow' };
@@ -382,13 +509,13 @@ function evaluateDispatch(data, { clock = Date } = {}) {
     `${parsed.param}="${parsed.value}". Add ${parsed.param}="${parsed.value}" to the Agent() ` +
     `call so the executor runs in an isolated worktree instead of the primary checkout ` +
     `(gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md).`;
-  return { action: 'block', reason };
+  return { action: 'block', reason, reasonCode: REASON_CODE.HARNESS_FLAG_MISSING };
 }
 
 /* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
 function main() {
   let input = '';
-  const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+  const stdinTimeout = setTimeout(() => allow(undefined), 3000);
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
   process.stdin.on('end', () => {
@@ -397,19 +524,19 @@ function main() {
       const data = JSON.parse(input);
       const decision = evaluateDispatch(data);
       if (decision.action === 'block') {
-        const out = { decision: 'block', reason: decision.reason };
-        process.stdout.write(JSON.stringify(out));
+        const out = { decision: 'block', reason: decision.reason, reason_code: decision.reasonCode };
         // Kimi feeds stderr (not stdout) back to the model on exit 2.
-        process.stderr.write(decision.reason);
-        process.exit(2);
+        deny(out, decision.reason);
       }
-      process.exit(0);
+      allow(undefined);
     } catch {
       // Silent fail — never block valid tool calls due to hook errors
       // (malformed payload, etc.). This is distinct from resolveIsolationState's
       // internal error handling, which DOES deny — this outer catch only
       // covers payload parsing before applicability could even be determined.
-      process.exit(0);
+      // ON_CRASH is declared ALLOW at module top: this preserves today's
+      // exit(0) fail-open behavior exactly (#3911).
+      crash(ON_CRASH, undefined);
     }
   });
 }
@@ -425,4 +552,5 @@ module.exports = {
   resolveHarnessFlag,
   resolveRegistryIsolation,
   parseHarnessFlag,
+  _setInstallRuntimeMarkerForTests,
 };

package/hooks/dist/gsd-check-update-worker.js

@@ -11,18 +11,61 @@
 
 const fs = require('fs');
 const path = require('path');
-const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
-// Latest-version lookup is delegated to the single deterministic adapter
-// (#498). checkLatestVersion() owns the npm-view call, the timeout/semver
-// policy, and the package name — sourced from the baked Package Identity seam.
-// The previous `require('../package.json').name` (#378) never yielded a name in
-// the installed tree — at the time it resolved to the synthetic
-// {"type":"commonjs"} marker GSD wrote at the config root, which has no `.name`,
-// so the background check never reported updates. Since #2544 GSD writes no
-// marker there at all, so that require would now fail to resolve outright.
-// Either way the name must come from the baked seam, never a walk-up.
-const { checkLatestVersion } = require('../gsd-core/bin/check-latest-version.cjs');
-const { PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs');
+
+// #3582: gsd-core/bin/lib/semver-compare.cjs and package-identity.cjs (and,
+// transitively, check-latest-version.cjs's own gsd-core/bin/lib/cli-exit.cjs
+// + shell-command-projection.cjs) are tsc build artifacts (ADR-457),
+// gitignored and absent on a raw plugin-marketplace / git-clone install that
+// never ran `npm run build:lib`. This worker is a DETACHED SessionStart
+// background process (spawned with stdio: 'ignore') — a build failure here
+// must DEGRADE to the no-signal fallbacks below (mirroring the
+// managed-hooks-registry.cjs degrade just below) so the worker still runs to
+// completion and writes a result cache record, rather than dying silently
+// with no visible signal and no cache-file write at all.
+//
+// This try/require/ensureRuntimeBuild/require/catch shape repeats (with
+// different destructured names) in hooks/gsd-check-update.js and
+// hooks/gsd-update-banner.js. It is deliberately NOT extracted into a shared
+// hooks/lib/ helper: scripts/lint-hooks-runtime-build-seam.cjs enforces this
+// exact seam textually, PER FILE — it greps each hooks/ file for its OWN
+// literal `require('.../ensure-runtime-build.cjs')` + `ensureRuntimeBuild(`
+// call co-occurring with its OWN literal `require('.../gsd-core/bin/lib/*.cjs')`.
+// A generic helper taking the compiled module's path as a variable would move
+// the literal compiled-lib require OUT of this file and into the helper,
+// called with a non-literal argument — the scan's regex (see that script's
+// "Known limitations") cannot see a require() called with a variable, so this
+// file would then read as "requires nothing" and the lint would stop
+// protecting it. A ceremony-only helper (just the ensureRuntimeBuild call,
+// each caller keeping its own literal compiled-lib require) fails the SAME
+// way from the other side: it would remove this file's own literal
+// `require('.../ensure-runtime-build.cjs')` + `ensureRuntimeBuild(` call,
+// which the lint also requires to be textually present in THIS file. Either
+// shape needs the lint script itself widened to special-case the helper,
+// which is a bigger, riskier change than the ~6 duplicated lines it would
+// save; kept inline instead.
+let isSemverNewer = () => false;
+let checkLatestVersion = () => ({ ok: false });
+let PACKAGE_NAME = null;
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs'));
+  // Latest-version lookup is delegated to the single deterministic adapter
+  // (#498). checkLatestVersion() owns the npm-view call, the timeout/semver
+  // policy, and the package name — sourced from the baked Package Identity seam.
+  // The previous `require('../package.json').name` (#378) never yielded a name in
+  // the installed tree — at the time it resolved to the synthetic
+  // {"type":"commonjs"} marker GSD wrote at the config root, which has no `.name`,
+  // so the background check never reported updates. Since #2544 GSD writes no
+  // marker there at all, so that require would now fail to resolve outright.
+  // Either way the name must come from the baked seam, never a walk-up.
+  ({ checkLatestVersion } = require('../gsd-core/bin/check-latest-version.cjs'));
+  ({ PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs'));
+} catch (e) {
+  // Runtime library missing/broken and could not self-build — degrade to the
+  // no-signal fallbacks declared above; the worker still writes a result
+  // cache record (package_name: null, update_available: false).
+}
 // Authoritative list of managed hooks — shared with tests to retire source-grep
 // assertions (pending-migration-to-typed-ir [#455]).
 // NOTE: managed-hooks-registry.cjs must be in HOOKS_TO_COPY (scripts/build-hooks.js)
@@ -63,7 +106,7 @@ try {
 // (e.g., gsd-intel-*.js) must be ignored to avoid permanent stale warnings (#1750)
 // MANAGED_HOOKS is imported from ./managed-hooks-registry.cjs above.
 
-let staleHooks = [];
+const staleHooks = [];
 if (configDir) {
   // #3023: the bundle's directory name is runtime-descriptor-driven (pi stages
   // it as `gsd-hooks/`), so deriving it as `<configDir>/hooks` silently scanned

package/hooks/dist/gsd-check-update.js

@@ -8,7 +8,25 @@ const path = require('path');
 const os = require('os');
 const { spawn } = require('child_process');
 
-const { updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
+// #3582: gsd-core/bin/lib/package-identity.cjs is a tsc build artifact
+// (ADR-457), gitignored and absent on a raw plugin-marketplace / git-clone
+// install that never ran `npm run build:lib`. This SessionStart hook must
+// DEGRADE (fall back to a generic cache filename) rather than crash session
+// start. gsd-check-update-worker.js — the process this hook spawns — degrades
+// identically and independently, so the shared fallback literal keeps the
+// cache path consistent between writer and reader even in the (rare)
+// doubly-degraded case. This try/require/ensureRuntimeBuild/require/catch
+// shape is deliberately duplicated (not extracted to hooks/lib/) — see
+// gsd-check-update-worker.js's identical #3582 comment for why.
+let updateCacheFileName = 'gsd-update-check.json';
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs'));
+} catch (e) {
+  // Runtime library missing/broken and could not self-build — degrade to the
+  // fallback filename above rather than crash the SessionStart hook.
+}
 
 const homeDir = os.homedir();
 const cwd = process.cwd();

package/hooks/dist/gsd-config-reload.js

@@ -20,11 +20,17 @@
 
 const fs = require('fs');
 const path = require('path');
+const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+
+// This hook only injects an advisory config-reload summary; a crash mid-parse
+// must not block the session or the FileChanged event that triggered it — the
+// agent simply keeps using the config context it already had (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 let input = '';
 // Timeout guard: if stdin does not close within 8s exit silently rather than
 // hanging until Claude Code kills the process and reports "hook error".
-const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+const stdinTimeout = setTimeout(() => allow(undefined), 8000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => (input += chunk));
 process.stdin.on('end', () => {
@@ -42,24 +48,23 @@ process.stdin.on('end', () => {
     // inject spurious additionalContext.
     const basename = path.basename(filePath);
     if (basename !== 'config.json') {
-      process.exit(0);
+      allow(undefined);
     }
     const expectedPath = path.resolve(cwd, '.planning', 'config.json');
     if (path.resolve(filePath) !== expectedPath) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // On unlink (deletion) emit a brief notice and exit
     if (event === 'unlink') {
-      process.stdout.write(JSON.stringify({
+      allow({
         hookSpecificOutput: {
           hookEventName: 'FileChanged',
           additionalContext:
             'GSD config (.planning/config.json) was deleted. ' +
             'Falling back to built-in defaults for this session.',
         },
-      }));
-      process.exit(0);
+      });
     }
 
     // Read the updated config file
@@ -68,17 +73,16 @@ process.stdin.on('end', () => {
       const raw = fs.readFileSync(filePath, 'utf8');
       config = JSON.parse(raw);
     } catch (e) {
-      if (e && e.code === 'ENOENT') process.exit(0);
+      if (e && e.code === 'ENOENT') allow(undefined);
       // Malformed JSON — inform the agent without crashing
-      process.stdout.write(JSON.stringify({
+      allow({
         hookSpecificOutput: {
           hookEventName: 'FileChanged',
           additionalContext:
             'GSD config (.planning/config.json) was modified but could not be parsed. ' +
             'Check the file for JSON syntax errors.',
         },
-      }));
-      process.exit(0);
+      });
     }
 
     // Build a concise summary of key config fields the agent cares about
@@ -127,7 +131,9 @@ process.stdin.on('end', () => {
       },
     }));
   } catch (e) {
-    // Silent fail — never block the session on a config reload error
-    process.exit(0);
+    // Silent fail — never block the session on a config reload error.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });

package/hooks/dist/gsd-context-monitor.js

@@ -22,6 +22,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
+const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+
+// This hook only injects an advisory context-usage warning; it never blocks
+// the tool call it rides in on. A crash here (e.g. a malformed bridge file)
+// must not turn a PostToolUse advisory into a blocked tool call — losing a
+// context warning is far cheaper than stalling the agent's work (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
 const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
@@ -33,7 +40,7 @@ let input = '';
 // Windows/Git Bash, or slow Claude Code piping during large outputs),
 // exit silently instead of hanging until Claude Code kills the process
 // and reports "hook error". See #775, #1162.
-const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+const stdinTimeout = setTimeout(() => allow(undefined), 10000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
@@ -43,14 +50,14 @@ process.stdin.on('end', () => {
     const sessionId = data.session_id;
 
     if (!sessionId) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Reject session IDs that contain path traversal sequences or path separators.
     // session_id is used to construct file paths in /tmp — an unsanitized value
     // could escape the temp directory and read or write arbitrary files.
     if (/[/\\]|\.\./.test(sessionId)) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Check if context warnings are disabled via config.
@@ -61,7 +68,7 @@ process.stdin.on('end', () => {
       const configPath = path.join(cwd, '.planning', 'config.json');
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       if (config.hooks?.context_warnings === false) {
-        process.exit(0);
+        allow(undefined);
       }
     } catch (e) {
       // Missing or unparseable config → proceed with defaults (context warnings enabled)
@@ -77,7 +84,7 @@ process.stdin.on('end', () => {
     try {
       metricsRaw = fs.readFileSync(metricsPath, 'utf8');
     } catch (e) {
-      if (e && e.code === 'ENOENT') process.exit(0);
+      if (e && e.code === 'ENOENT') allow(undefined);
       throw e;
     }
     const metrics = JSON.parse(metricsRaw);
@@ -85,7 +92,7 @@ process.stdin.on('end', () => {
 
     // Ignore stale metrics
     if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
-      process.exit(0);
+      allow(undefined);
     }
 
     const remaining = metrics.remaining_percentage;
@@ -93,7 +100,7 @@ process.stdin.on('end', () => {
 
     // No warning needed
     if (remaining > WARNING_THRESHOLD) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Debounce: check if we warned recently
@@ -121,7 +128,7 @@ process.stdin.on('end', () => {
     if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
       // Update counter and exit without warning
       fs.writeFileSync(warnPath, JSON.stringify(warnData));
-      process.exit(0);
+      allow(undefined);
     }
 
     // Reset debounce counter
@@ -208,7 +215,9 @@ process.stdin.on('end', () => {
       process.stdout.write(JSON.stringify(output));
     }
   } catch (e) {
-    // Silent fail -- never block tool execution
-    process.exit(0);
+    // Silent fail -- never block tool execution.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });

package/hooks/dist/gsd-cursor-post-tool.js

@@ -22,6 +22,8 @@
 
 'use strict';
 
+const { allow } = require('./lib/hook-exit.js');
+
 const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
 const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
 const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
@@ -29,7 +31,7 @@ const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
 let raw = '';
 const stdinTimeout = setTimeout(() => {
   // Timeout guard: exit silently rather than hanging.
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');

package/hooks/dist/gsd-cursor-pre-tool.js

@@ -22,8 +22,7 @@
 
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
+const { allow } = require('./lib/hook-exit.js');
 
 const WRITE_TOOL_RE = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/i;
 const PATH_KEY_RE = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
@@ -31,7 +30,7 @@ const PLANNING_PATH_RE = /(^|[\\/])\.planning([\\/]|$)/;
 
 let raw = '';
 const stdinTimeout = setTimeout(() => {
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');

package/hooks/dist/gsd-cursor-session-start.js

@@ -23,6 +23,7 @@
 'use strict';
 
 const fs = require('fs');
+const { allow } = require('./lib/hook-exit.js');
 
 const MSG_PRESENT =
   'GSD: .planning/STATE.md is present — review the current phase and any blockers before acting.';
@@ -37,7 +38,7 @@ const { resolveStatePath } = require('./lib/cursor-workspace.js');
 let raw = '';
 const stdinTimeout = setTimeout(() => {
   // Timeout guard: exit silently rather than hanging.
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');

package/hooks/dist/gsd-cursor-stop.js

@@ -21,6 +21,7 @@
 'use strict';
 
 const fs = require('fs');
+const { allow } = require('./lib/hook-exit.js');
 
 // Workspace resolution is shared across the Cursor hooks (#2587) — see
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
@@ -29,7 +30,7 @@ const { resolveStatePath } = require('./lib/cursor-workspace.js');
 
 let raw = '';
 const stdinTimeout = setTimeout(() => {
-  process.exit(0);
+  allow(undefined);
 }, 10000);
 
 process.stdin.setEncoding('utf8');