@opengsd/gsd-core 1.10.0 → 1.12.0

package/hooks/gsd-validate-commit.sh

@@ -7,10 +7,43 @@
 #
 # OPT-IN: This hook is a no-op unless config.json has hooks.community: true.
 # Enable with: "hooks": { "community": true } in .planning/config.json
+set -euo pipefail
+
+# Temp files created below for subprocess stderr capture (config read, command
+# extraction, classifier). A single EXIT trap replaces three hand-rolled
+# mktemp/rm-f pairs so an early or unexpected exit path can never leak one —
+# and a future fourth check does not need its own copy (#3911 review).
+# Idempotent and failure-proof by construction: unset vars expand to "" (a
+# no-op rm -f target), and `|| true` guarantees the trap itself never changes
+# the script's exit status.
+ENABLED_ERR=""
+CMD_ERR=""
+CLASSIFY_ERR=""
+cleanup_temp_files() {
+  rm -f "${ENABLED_ERR:-}" "${CMD_ERR:-}" "${CLASSIFY_ERR:-}" 2>/dev/null || true
+}
+trap cleanup_temp_files EXIT
 
 # Check opt-in config — exit silently if not enabled
 if [ -f .planning/config.json ]; then
-  ENABLED=$(node -e "try{const c=require('./.planning/config.json');process.stdout.write(c.hooks?.community===true?'1':'0')}catch{process.stdout.write('0')}" 2>/dev/null)
+  ENABLED_ERR=$(mktemp)
+  ENABLED=$(node -e "
+    try{
+      const c=require('./.planning/config.json');
+      process.stdout.write(c.hooks?.community===true?'1':'0');
+    }catch(e){
+      process.stderr.write('CONFIG_READ_FAILED: '+(e&&e.message?e.message:String(e)));
+      process.exit(3);
+    }
+  " 2>"$ENABLED_ERR") || CONFIG_STATUS=$?
+  CONFIG_STATUS=${CONFIG_STATUS:-0}
+  if [ "$CONFIG_STATUS" != "0" ]; then
+    # Could not determine the opt-in flag at all (node missing, JSON parse
+    # error other than absence, etc.) — distinct from ".planning/config.json
+    # exists and legitimately disables the hook". Say so and pass, per #3838.
+    echo "gsd-validate-commit.sh: could not read .planning/config.json (opt-in check) — validator disabled for this call. $(cat "$ENABLED_ERR")" >&2
+    exit 0
+  fi
   if [ "$ENABLED" != "1" ]; then exit 0; fi
 else
   exit 0
@@ -19,17 +52,58 @@ fi
 INPUT=$(cat)
 
 # Extract command from JSON using Node (handles escaping correctly, no jq needed)
-CMD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.command||'')}catch{}})" 2>/dev/null)
+CMD_ERR=$(mktemp)
+CMD=$(echo "$INPUT" | node -e "
+  let d='';
+  process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    try{
+      process.stdout.write(JSON.parse(d).tool_input?.command||'');
+    }catch(e){
+      process.stderr.write('COMMAND_EXTRACTION_FAILED: '+(e&&e.message?e.message:String(e)));
+      process.exit(3);
+    }
+  });
+" 2>"$CMD_ERR") || CMD_STATUS=$?
+CMD_STATUS=${CMD_STATUS:-0}
+if [ "$CMD_STATUS" != "0" ]; then
+  # Could not extract tool_input.command at all (node missing, malformed
+  # JSON, etc.) — distinct from "there is genuinely no command field". Say
+  # so and pass, per #3838.
+  echo "gsd-validate-commit.sh: could not extract tool_input.command from the hook payload — validator disabled for this call. $(cat "$CMD_ERR")" >&2
+  exit 0
+fi
 
 # Only check git commit commands.
 # Delegates to hooks/lib/git-cmd.js isGitSubcommand() — the canonical token-walk
 # classifier that handles env-prefix, -C path, and full-path git invocations.
 # A naive `^git\s+commit` regex misses all three; this guard fixes that (#3129).
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-if GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
-  const {isGitSubcommand}=require(process.env.GIT_CMD_LIB);
-  process.exit(isGitSubcommand(process.argv[1],'commit')?0:1);
-" "$CMD" 2>/dev/null; then
+CLASSIFY_ERR=$(mktemp)
+GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
+  try {
+    const {isGitSubcommand}=require(process.env.GIT_CMD_LIB);
+    process.exit(isGitSubcommand(process.argv[1],'commit')?0:1);
+  } catch(e) {
+    process.stderr.write('CLASSIFIER_THREW: '+(e&&e.message?e.message:String(e)));
+    process.exit(3);
+  }
+" "$CMD" 2>"$CLASSIFY_ERR" || CLASSIFY_STATUS=$?
+CLASSIFY_STATUS=${CLASSIFY_STATUS:-0}
+if [ "$CLASSIFY_STATUS" != "0" ] && [ "$CLASSIFY_STATUS" != "1" ]; then
+  # 0 = is a git commit (validate below); 1 = genuinely not a git commit
+  # (real negative, pass silently) — the ONLY intentional non-zero exit the
+  # script above ever produces on success. Any other status — 127 node
+  # missing, or 3 from the try/catch above when the git-cmd.js require chain
+  # throws (e.g. its built dependency, gsd-core/bin/lib/token-scanner.cjs, is
+  # a gitignored build artifact and absent on a fresh checkout — run
+  # `npm run build:lib`) — means the classifier could not run at all. Say so
+  # on stderr and pass (#3838): PreToolUse stderr does not disturb the JSON
+  # protocol.
+  echo "gsd-validate-commit.sh: could not classify the command via hooks/lib/git-cmd.js (exit $CLASSIFY_STATUS) — validator disabled for this call. If this persists, run \`npm run build:lib\`. $(cat "$CLASSIFY_ERR")" >&2
+  exit 0
+fi
+if [ "$CLASSIFY_STATUS" = "0" ]; then
   # Extract message from -m flag
   MSG=""
   if [[ "$CMD" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then

package/hooks/gsd-windsurf-pre-command.js

@@ -47,6 +47,16 @@
 
 'use strict';
 
+const { allow, deny } = require('./lib/hook-exit.js');
+
+// #3911 (ADR-3889 Phase 7): the exit(2) call site (block(), below) is
+// migrated to hook-exit.js's deny(undefined, reason) now that
+// hooks/lib/cli-exit.js's terminateNow emits fd 1 and fd 2 (stderrPayload)
+// in INDEPENDENT try/catch blocks — `payload=undefined` cleanly skips the
+// fd 1 write (preserving "nothing written to stdout") instead of throwing
+// into a shared catch that used to also swallow the fd 2 write, which is
+// what silently dropped the deny reason before this fix.
+
 // No realistic destructive command comes anywhere close to this length.
 const MAX_COMMAND_LENGTH = 4096;
 
@@ -244,16 +254,11 @@ function destructiveReason(cmd) {
 }
 
 function block(reason) {
-  process.stderr.write(`GSD windsurf pre_run_command guard: ${reason}\n`);
-  process.exit(2);
-}
-
-function allow() {
-  process.exit(0);
+  deny(undefined, `GSD windsurf pre_run_command guard: ${reason}\n`);
 }
 
 let input = '';
-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', () => {
@@ -262,14 +267,14 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input || '{}');
     const toolInfo = (data && typeof data.tool_info === 'object' && data.tool_info) || {};
     const commandLine = typeof toolInfo.command_line === 'string' ? toolInfo.command_line : '';
-    if (!commandLine) { allow(); return; }
-    if (commandLine.length > MAX_COMMAND_LENGTH) { allow(); return; }
+    if (!commandLine) { allow(undefined); return; }
+    if (commandLine.length > MAX_COMMAND_LENGTH) { allow(undefined); return; }
 
     const reason = destructiveReason(commandLine);
     if (reason) { block(reason); return; }
-    allow();
+    allow(undefined);
   } catch {
     // Silent fail-open — never block a valid tool call due to a hook bug.
-    allow();
+    allow(undefined);
   }
 });

package/hooks/gsd-windsurf-pre-write.js

@@ -30,6 +30,13 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { allow, deny } = require('./lib/hook-exit.js');
+const { reportIfUndetermined } = require('./lib/git-probe.js');
+
+// #3911 (ADR-3889 Phase 7): the exit(2) call site (block(), below) is
+// migrated to hook-exit.js's deny(undefined, reason) — see
+// gsd-windsurf-pre-command.js's identical note for the fixed defect
+// (terminateNow's fd 1/fd 2 writes now run in independent try/catch blocks).
 
 const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, windowsHide: true };
 
@@ -54,16 +61,11 @@ function nearestExistingDir(start) {
 }
 
 function block(reason) {
-  process.stderr.write(`GSD windsurf pre_write_code guard: ${reason}\n`);
-  process.exit(2);
-}
-
-function allow() {
-  process.exit(0);
+  deny(undefined, `GSD windsurf pre_write_code guard: ${reason}\n`);
 }
 
 let input = '';
-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', () => {
@@ -72,14 +74,19 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input || '{}');
     const toolInfo = (data && typeof data.tool_info === 'object' && data.tool_info) || {};
     const rawFilePath = typeof toolInfo.file_path === 'string' ? toolInfo.file_path : '';
-    if (!rawFilePath) { allow(); return; }
+    if (!rawFilePath) { allow(undefined); return; }
 
     const cwd = process.cwd();
 
     // Determine the active project's git root. No git root at all -> nothing
     // to enforce a boundary against -> fail open.
     const cwdTopResult = git(['rev-parse', '--show-toplevel'], cwd);
-    if (cwdTopResult.status !== 0 || !cwdTopResult.stdout) { allow(); return; }
+    // #3911: a timeout/spawn-failure result is indistinguishable from a clean
+    // "no git root here" answer by status/stdout alone — reportIfUndetermined
+    // is a no-op on a genuine negative and only fires when the probe itself
+    // could not run. The allow() below is UNCHANGED either way.
+    reportIfUndetermined('gsd-windsurf-pre-write', 'git rev-parse --show-toplevel (cwd)', cwdTopResult);
+    if (cwdTopResult.status !== 0 || !cwdTopResult.stdout) { allow(undefined); return; }
     const cwdTopRaw = cwdTopResult.stdout.trim();
 
     const filePath = path.isAbsolute(rawFilePath) ? path.resolve(rawFilePath) : path.resolve(cwd, rawFilePath);
@@ -95,14 +102,16 @@ process.stdin.on('end', () => {
         }
       })(),
     );
-    if (!checkDir) { allow(); return; } // synthetic path with no existing ancestor — fail open
+    if (!checkDir) { allow(undefined); return; } // synthetic path with no existing ancestor — fail open
 
     const fileTopResult = git(['rev-parse', '--show-toplevel'], checkDir);
+    reportIfUndetermined('gsd-windsurf-pre-write', 'git rev-parse --show-toplevel (file location)', fileTopResult);
     if (fileTopResult.status !== 0 || !fileTopResult.stdout) {
       // Not inside any git worktree. Distinguish "inside a .git/ internals
       // directory" (dangerous — BLOCK) from "outside all git repos entirely"
       // (not the escape vector this guard targets — fail open).
       const insideGitDir = git(['rev-parse', '--is-inside-git-dir'], checkDir);
+      reportIfUndetermined('gsd-windsurf-pre-write', 'git rev-parse --is-inside-git-dir', insideGitDir);
       if (insideGitDir.status === 0 && insideGitDir.stdout && insideGitDir.stdout.trim() === 'true') {
         block(
           `'${filePath}' is inside a git internal (.git) directory, not the active project at ` +
@@ -111,12 +120,12 @@ process.stdin.on('end', () => {
         );
         return;
       }
-      allow();
+      allow(undefined);
       return;
     }
 
     const fileTopRaw = fileTopResult.stdout.trim();
-    if (fileTopRaw === cwdTopRaw) { allow(); return; }
+    if (fileTopRaw === cwdTopRaw) { allow(undefined); return; }
 
     // BLOCK: file resolves to a different git root than the active project.
     block(
@@ -127,6 +136,6 @@ process.stdin.on('end', () => {
     );
   } catch {
     // Silent fail-open — never block a valid tool call due to a hook bug.
-    allow();
+    allow(undefined);
   }
 });

package/hooks/gsd-workflow-guard.js

@@ -4,9 +4,15 @@
 // Detects when Claude attempts file edits outside a GSD workflow context
 // (no active /gsd- skill or Task subagent) and injects an advisory warning.
 //
-// This is a SOFT guard — it advises, not blocks. The edit still proceeds.
-// The warning nudges Claude to use /gsd:quick or /gsd:fast instead of
-// making direct edits that bypass state tracking.
+// This is a SOFT guard for edits — it advises, not blocks. The edit still
+// proceeds. The warning nudges Claude to use /gsd:quick or /gsd:fast instead
+// of making direct edits that bypass state tracking.
+//
+// ONE hard block lives here: `git add -f` on an agent/worktree-agent branch
+// (WORKTREE_AGENT_FORCE_ADD_FORBIDDEN) — and that block leg fails CLOSED on
+// internal error (#3504): when the guard is enabled and the blocking context
+// holds, a thrown error exits 2 (block), not 0. The advisory legs keep the
+// fail-open posture — a broken advisory must never wedge every tool call.
 //
 // Enable via config: hooks.workflow_guard: true (default: false)
 // Only triggers on Write/Edit tool calls to non-.planning/ files.
@@ -14,40 +20,58 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
-const { tokenize } = require('./lib/git-cmd.js');
+const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+const { reportIfUndetermined } = require('./lib/git-probe.js');
+
+// This guard is almost entirely advisory (fail open — a broken advisory must
+// never wedge every tool call), with ONE hard block (#3504 force-add-on-
+// agent-branch) that fails CLOSED on internal error instead. That split is
+// re-derived dynamically inside the outer catch (failClosedBlockContext), not
+// a fixed per-hook policy, so ON_CRASH names only the FINAL, unconditional
+// fallback reached when the fail-closed context does not apply — i.e. the
+// historical exit(0). Declared ONCE here so that fallback states its policy
+// explicitly rather than inheriting a default (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 function forceGitAddCwds(command, defaultCwd) {
   const tokens = tokenize(command || '');
   const separators = new Set(['&&', '||', ';', '|']);
   const cwdList = [];
-  for (let i = 0; i < tokens.length; i++) {
-    if (path.basename(tokens[i]) !== 'git') continue;
+  // #3504: per-segment walk driven by git-cmd.js's canonical skipToSubcommand.
+  // The previous inline walk knew six global flags and silently missed the
+  // rest — `git -c core.hooksPath=/tmp/x add -f x`, `git --no-optional-locks
+  // add -f x`, `--literal-pathspecs`, `--namespace=…` and friends all fell
+  // through to a silent exit 0, a no-crash bypass the fail-closed catch is
+  // structurally blind to (it only fires on throws). Sharing the classifier
+  // makes the block's flag knowledge exactly the classifier's.
+  const segments = [];
+  let start = 0;
+  for (let i = 0; i <= tokens.length; i++) {
+    if (i === tokens.length || separators.has(tokens[i])) {
+      if (i > start) segments.push(tokens.slice(start, i));
+      start = i + 1;
+    }
+  }
+  for (const seg of segments) {
+    const subIdx = skipToSubcommand(seg);
+    if (subIdx === -1 || subIdx >= seg.length || seg[subIdx] !== 'add') continue;
 
-    let j = i + 1;
+    // Resolve a `-C <dir>` (separate-arg form) preceding the subcommand so
+    // the branch is probed at the repository the add targets.
     let gitCwd = defaultCwd;
-    while (j < tokens.length) {
-      const token = tokens[j];
-      const flagName = token.includes('=') ? token.slice(0, token.indexOf('=')) : token;
-      if (token === '-C' && tokens[j + 1]) {
-        gitCwd = path.resolve(gitCwd, tokens[j + 1]);
-        j += 2;
-        continue;
-      }
-      if (['-C', '--git-dir', '--work-tree'].includes(flagName) && !token.includes('=')) {
-        j += 2;
-        continue;
-      }
-      if (['--git-dir', '--work-tree', '--no-pager', '-p', '-P'].includes(flagName)) {
-        j++;
+    for (let k = 0; k < subIdx; ) {
+      if (seg[k] === '-C' && k + 1 < subIdx) {
+        gitCwd = path.resolve(gitCwd, seg[k + 1]);
+        k += 2;
         continue;
       }
-      break;
+      k++;
     }
 
-    if (tokens[j] !== 'add') continue;
-    for (let k = j + 1; k < tokens.length && !separators.has(tokens[k]); k++) {
-      if (tokens[k] === '--') break;
-      if (tokens[k] === '--force' || tokens[k] === '-f' || /^-[A-Za-z]*f[A-Za-z]*$/.test(tokens[k])) {
+    for (let k = subIdx + 1; k < seg.length; k++) {
+      if (seg[k] === '--') break;
+      if (seg[k] === '--force' || seg[k] === '-f' || /^-[A-Za-z]*f[A-Za-z]*$/.test(seg[k])) {
         cwdList.push(gitCwd);
         break;
       }
@@ -62,11 +86,93 @@ function currentBranch(cwd) {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
     windowsHide: true,
+    // #3504: bounded — this ran unbounded before, an indefinite hang under a
+    // wedged git would hang every PreToolUse call. Host wiring allows a 5s
+    // budget for the whole hook, so the probe gets 2s of it; a timeout
+    // returns '' (branch unknown), which both the block decision and the
+    // fail-closed re-check treat as "cannot establish agent branch".
+    timeout: 2000,
+    killSignal: 'SIGTERM',
   });
+  // #3911: a timeout/spawn-failure here previously degraded to '' exactly
+  // like a clean "not on a branch" answer — indistinguishable from the
+  // caller's point of view. reportIfUndetermined is a no-op on a genuine
+  // negative and only emits a diagnostic when the probe itself could not
+  // run; the '' fallback (and therefore this hook's exit code) is unchanged.
+  reportIfUndetermined('gsd-workflow-guard', 'git branch --show-current', result);
   if (result.status !== 0) return '';
   return result.stdout.trim();
 }
 
+// Agent-branch predicate, shared by the happy-path detector and the fail-closed
+// re-check so the block's scope cannot drift between the two paths (#3504).
+function isAgentBranch(branch) {
+  return /^(worktree-)?agent-/.test(branch);
+}
+
+// Typed cwd read, shared by both paths for the same reason: a non-string cwd
+// degrades to process.cwd() instead of throwing inside path.join().
+function payloadCwd(data) {
+  return typeof data?.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
+}
+
+// The force-add block payload, emitted by the happy-path detector and the
+// fail-closed catch — one source so the two exits cannot drift. `origin`
+// distinguishes them structurally ('force-add-detected' vs 'fail-closed') so a
+// consumer — or the model reading Kimi's stderr feedback — is never told a
+// force-add was detected when the call was in fact blocked unanalyzed.
+function emitForceAddBlock(origin) {
+  const failClosed = origin === 'fail-closed';
+  const reason = failClosed
+    ? 'workflow guard internal error on an agent branch - failing closed. The command was NOT analyzed and was NOT confirmed to be a force-add. Retry the call or inspect the guard.'
+    : 'agent/worktree-agent branches must not run git add -f or git add --force. Respect the SDK skipped_gitignored/skipped_commit_docs_false contract and leave gitignored files untracked.';
+  const output = {
+    decision: 'block',
+    code: 'WORKTREE_AGENT_FORCE_ADD_FORBIDDEN',
+    origin: failClosed ? 'fail-closed' : 'force-add-detected',
+    reason,
+  };
+  // Kimi CLI's exit-2 protocol feeds stderr back to the model (#2304) — deny's
+  // stderrPayload keeps fd 2 to the plain reason string, matching the
+  // pre-migration two-write byte-for-byte.
+  deny(output, output.reason);
+}
+
+// #3504 fail-closed context re-derivation. Runs INSIDE the outer catch, after
+// an internal error, and answers exactly one question: does the blocking
+// context of the force-add guard hold for this payload? Each stage is guarded —
+// a re-derivation that itself throws must degrade to "cannot establish" (false),
+// never take down the catch. Deliberately does NOT re-detect the force-add: the
+// error may live in the detector itself, and on an agent branch with the guard
+// enabled, a Bash call under an internal error is conservative-correct to block.
+// Anything it cannot establish (unparseable payload, non-Bash tool, guard
+// disabled, branch not determinably agent-*) fails open, preserving the
+// advisory legs' fail-open posture.
+function failClosedBlockContext(rawInput) {
+  let data;
+  try {
+    data = normalizeKimiPayload(JSON.parse(rawInput));
+  } catch {
+    return false;
+  }
+  if (data === null || typeof data !== 'object' || data.tool_name !== 'Bash') return false;
+  const cwd = payloadCwd(data);
+  let enabled;
+  try {
+    enabled = workflowGuardEnabled(cwd);
+  } catch {
+    return false;
+  }
+  if (!enabled) return false;
+  let branch;
+  try {
+    branch = currentBranch(cwd);
+  } catch {
+    return false;
+  }
+  return isAgentBranch(branch);
+}
+
 function workflowGuardEnabled(cwd) {
   const configPath = path.join(cwd, '.planning', 'config.json');
   if (!fs.existsSync(configPath)) return false;
@@ -173,49 +279,50 @@ function normalizeKimiPayload(data) {
 }
 
 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', () => {
   clearTimeout(stdinTimeout);
   try {
     const data = normalizeKimiPayload(JSON.parse(input));
+    // #3504 test-only fault seam: throws right after parse so the fail-closed
+    // posture of the outer catch is exercisable — no JSON-expressible input
+    // throws in this handler today (#2547/#2595 hardened every read). Gated on
+    // GSD_TEST_MODE as well so a leaked GSD_TEST_WORKFLOW_GUARD_FAULT in a real
+    // shell cannot wedge a production session. The fault's failure direction
+    // is CLOSED: the catch below may block, never bypass a block.
+    if (process.env.GSD_TEST_MODE === '1' && process.env.GSD_TEST_WORKFLOW_GUARD_FAULT === '1') {
+      throw new Error('GSD_TEST_WORKFLOW_GUARD_FAULT: injected fault');
+    }
     const toolName = data.tool_name;
     const cwd = data.cwd || process.cwd();
     const isWorkflowGuardEnabled = workflowGuardEnabled(cwd);
 
     if (toolName === 'Bash') {
       if (!isWorkflowGuardEnabled) {
-        process.exit(0);
+        allow(undefined);
       }
       const command = data.tool_input?.command || '';
       for (const gitCwd of forceGitAddCwds(command, cwd)) {
         const branch = currentBranch(gitCwd);
         if (/^(worktree-)?agent-/.test(branch)) {
-          const output = {
-            decision: 'block',
-            code: 'WORKTREE_AGENT_FORCE_ADD_FORBIDDEN',
-            reason: 'agent/worktree-agent branches must not run git add -f or git add --force. Respect the SDK skipped_gitignored/skipped_commit_docs_false contract and leave gitignored files untracked.',
-          };
-          process.stdout.write(JSON.stringify(output));
-          // Kimi CLI's exit-2 protocol feeds stderr back to the model (#2304)
-          process.stderr.write(output.reason);
-          process.exit(2);
+          emitForceAddBlock();
         }
       }
-      process.exit(0);
+      allow(undefined);
     }
 
     // Only guard Write, Edit, and MultiEdit tool calls
     if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Check if we're inside a GSD workflow (Task subagent or /gsd- skill)
     // Subagents have a session_id that differs from the parent
     // and typically have a description field set by the orchestrator
     if (data.tool_input?.is_subagent || data.session_type === 'task') {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Check the file being edited
@@ -230,7 +337,7 @@ process.stdin.on('end', () => {
 
     // Allow edits to .planning/ files (GSD state management)
     if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Allow edits to common config/docs files that don't need GSD tracking
@@ -243,11 +350,11 @@ process.stdin.on('end', () => {
       /settings\.json$/,
     ];
     if (allowedPatterns.some(p => p.test(filePath))) {
-      process.exit(0);
+      allow(undefined);
     }
 
     if (!isWorkflowGuardEnabled) {
-      process.exit(0); // Guard disabled (default) or no GSD project
+      allow(undefined); // Guard disabled (default) or no GSD project
     }
 
     // If we get here: GSD project, guard enabled, file edit outside .planning/,
@@ -264,8 +371,17 @@ process.stdin.on('end', () => {
     };
 
     process.stdout.write(JSON.stringify(output));
-  } catch (e) {
-    // Silent fail — never block tool execution
-    process.exit(0);
+  } catch {
+    // #3504: split posture on internal error. The ONE hard block in this hook
+    // (force-add on agent branches) fails CLOSED — if the blocking context can
+    // be re-derived from the payload (Bash tool + guard enabled + determinably
+    // an agent branch), deny rather than silently allowing. Everything else
+    // keeps the historical fail-open posture: a broken advisory guard must
+    // never wedge the session's tool calls. ON_CRASH is declared ALLOW at
+    // module top for exactly that unconditional fallback (#3911).
+    if (failClosedBlockContext(input)) {
+      emitForceAddBlock('fail-closed');
+    }
+    crash(ON_CRASH, undefined);
   }
 });