@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -20,13 +20,14 @@
 
 'use strict';
 
-let raw = '';
 const stdinTimeout = setTimeout(() => {
   process.exit(0);
 }, 10000);
 
 process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => { raw += chunk; });
+// Drain stdin (puts the stream into flowing mode so 'end' fires); the
+// payload itself is unused — this hook responds unconditionally.
+process.stdin.on('data', () => {});
 process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {

package/hooks/gsd-prompt-guard.js

@@ -11,26 +11,14 @@
 // The goal is to surface suspicious content so the orchestrator can inspect it,
 // not to create false-positive deadlocks.
 
-const fs = require('fs');
 const path = require('path');
 
-// Prompt injection patterns (subset of security.cjs patterns, inlined for hook independence)
-const INJECTION_PATTERNS = [
-  /ignore\s+(all\s+)?previous\s+instructions/i,
-  /ignore\s+(all\s+)?above\s+instructions/i,
-  /disregard\s+(all\s+)?previous/i,
-  /forget\s+(all\s+)?(your\s+)?instructions/i,
-  /override\s+(system|previous)\s+(prompt|instructions)/i,
-  /you\s+are\s+now\s+(?:a|an|the)\s+/i,
-  /act\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,
-  /pretend\s+(?:you(?:'re| are)\s+|to\s+be\s+)/i,
-  /from\s+now\s+on,?\s+you\s+(?:are|will|should|must)/i,
-  /(?:print|output|reveal|show|display|repeat)\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions)/i,
-  /<\/?(?:system|assistant|human)>/i,
-  /\[SYSTEM\]/i,
-  /\[INST\]/i,
-  /<<\s*SYS\s*>>/i,
-];
+// Prompt injection patterns — shared with gsd-read-injection-scanner.js via
+// hooks/lib/injection-patterns.js so the two surfaces cannot drift (#3504).
+// Deliberately a subset of security.cjs's set: hooks stay loadable without the
+// compiled lib tree. Staging of the lib helper is allowlisted in
+// GSD_HOOK_LIB_FILES (bin/install.js).
+const { INJECTION_PATTERNS } = require('./lib/injection-patterns.js');
 
 // #2304: Kimi's native hook bus delivers Kimi's tool vocabulary in the payload
 // (Write → WriteFile, Edit/MultiEdit → StrReplaceFile) while the [[hooks]]
@@ -153,8 +141,21 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
-    // Get the content being written
-    const content = data.tool_input?.content || data.tool_input?.new_string || '';
+    // Get the content being written. #3504 (isolated review finding 3): the
+    // bare `||` chain handed a NON-STRING truthy `content` straight to
+    // pattern.test(), where ToString can throw ("Cannot convert object to a
+    // primitive value" for `{"toString": null}`) into the outer catch — the
+    // exact crash-to-allow class #2547/#2595 hardened inside
+    // normalizeKimiPayload, unreached on this read. Guarded selection: take
+    // the first field that is a string, or String-coerces without throwing,
+    // so a poisoned `content` no longer shadows a real `new_string`.
+    let content = '';
+    for (const candidate of [data.tool_input?.content, data.tool_input?.new_string]) {
+      if (typeof candidate === 'string' && candidate) { content = candidate; break; }
+      if (candidate && typeof candidate !== 'string') {
+        try { const s = String(candidate); if (s) { content = s; break; } } catch { /* keep looking */ }
+      }
+    }
     if (!content) {
       process.exit(0);
     }

package/hooks/gsd-read-injection-scanner.js

@@ -72,26 +72,29 @@ const MARKDOWN_LINK_PATTERNS = [
   },
 ];
 
-// Standard injection patterns — mirrors gsd-prompt-guard.js, inlined for hook independence.
-const INJECTION_PATTERNS = [
-  /ignore\s+(all\s+)?previous\s+instructions/i,
-  /ignore\s+(all\s+)?above\s+instructions/i,
-  /disregard\s+(all\s+)?previous/i,
-  /forget\s+(all\s+)?(your\s+)?instructions/i,
-  /override\s+(system|previous)\s+(prompt|instructions)/i,
-  /you\s+are\s+now\s+(?:a|an|the)\s+/i,
-  /act\s+as\s+(?:a|an|the)\s+(?!plan|phase|wave)/i,
-  /pretend\s+(?:you(?:'re| are)\s+|to\s+be\s+)/i,
-  /from\s+now\s+on,?\s+you\s+(?:are|will|should|must)/i,
-  /(?:print|output|reveal|show|display|repeat)\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions)/i,
-  /<\/?(?:system|assistant|human)>/i,
-  /\[SYSTEM\]/i,
-  /\[INST\]/i,
-  /<<\s*SYS\s*>>/i,
-];
+// Standard injection patterns — shared with gsd-prompt-guard.js via
+// hooks/lib/injection-patterns.js so the two surfaces cannot drift (#3504).
+// Staging of the lib helper is allowlisted in GSD_HOOK_LIB_FILES (bin/install.js).
+const { INJECTION_PATTERNS } = require('./lib/injection-patterns.js');
 
 const ALL_PATTERNS = [...INJECTION_PATTERNS, ...SUMMARISATION_PATTERNS];
 
+// #3023: the staged bundle's directory name is runtime-descriptor-driven, so a
+// literal `/<config>/hooks/` fragment cannot reliably identify GSD's own hook
+// scripts. This module lives inside the bundle, so __dirname identifies it by
+// construction. Normalized to forward slashes to match `p` below.
+const OWN_BUNDLE_PREFIX = __dirname.replace(/\\/g, '/').replace(/\/+$/, '') + '/';
+
+// Synthetic rule ids for the finding classes that have no entry in
+// MARKDOWN_LINK_PATTERNS. Frozen and referenced from BOTH the push sites and
+// renderFinding so the two can never drift — a bare literal repeated at each
+// site is how a rename silently falls through to the generic render branch.
+const RULE_IDS = Object.freeze({
+  INJECTION_PATTERN: 'INJECTION-PATTERN',
+  INVISIBLE_UNICODE: 'INVISIBLE-UNICODE',
+  UNICODE_TAG_BLOCK: 'UNICODE-TAG-BLOCK',
+});
+
 function isExcludedPath(filePath) {
   const p = filePath.replace(/\\/g, '/');
   return (
@@ -101,6 +104,7 @@ function isExcludedPath(filePath) {
     /CHECKPOINT/i.test(path.basename(p)) ||
     /[/\\](?:security|techsec|injection)[/\\.]/i.test(p) ||
     /security\.cjs$/.test(p) ||
+    p.startsWith(OWN_BUNDLE_PREFIX) ||
     p.includes('/.claude/hooks/')
   );
 }
@@ -260,12 +264,19 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // Typed findings IR — single source of truth for both the machine-readable
+    // `findings` array and the rendered advisory prose. Never build these as two
+    // parallel arrays: that invites the generative-fix-divergence defect class
+    // where the rendered text and the structured data silently drift apart.
     const findings = [];
 
     for (const pattern of ALL_PATTERNS) {
       if (pattern.test(content)) {
         // Trim pattern source for readable output
-        findings.push(pattern.source.replace(/\\s\+/g, '-').replace(/[()\\]/g, '').substring(0, 50));
+        findings.push({
+          ruleId: RULE_IDS.INJECTION_PATTERN,
+          match: pattern.source.replace(/\\s\+/g, '-').replace(/[()\\]/g, '').substring(0, 50),
+        });
       }
     }
 
@@ -277,19 +288,19 @@ process.stdin.on('end', () => {
         const m = line.match(entry.pattern);
         if (!m) continue;
         if (entry.safePredicate && entry.safePredicate(line)) continue;
-        findings.push(`${entry.ruleId}:${m[0].substring(0, 40)}`);
+        findings.push({ ruleId: entry.ruleId, match: m[0].substring(0, 40) });
       }
     }
 
     // Invisible Unicode (zero-width, RTL override, soft hyphen, BOM)
     if (/[\u200B-\u200F\u2028-\u202F\uFEFF\u00AD\u2060-\u2069]/.test(content)) {
-      findings.push('invisible-unicode');
+      findings.push({ ruleId: RULE_IDS.INVISIBLE_UNICODE, match: null });
     }
 
     // Unicode tag block U+E0000–E007F (invisible instruction injection vector)
     try {
       if (/[\u{E0000}-\u{E007F}]/u.test(content)) {
-        findings.push('unicode-tag-block');
+        findings.push({ ruleId: RULE_IDS.UNICODE_TAG_BLOCK, match: null });
       }
     } catch {
       // Engine does not support Unicode property escapes — skip this check
@@ -299,6 +310,16 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // Renders one finding back into the exact prose fragment the advisory has
+    // always embedded. Kept as the ONLY place that maps IR -> text, so the
+    // `additionalContext` string and the `findings` array can never diverge.
+    function renderFinding(f) {
+      if (f.ruleId === RULE_IDS.INVISIBLE_UNICODE) return 'invisible-unicode';
+      if (f.ruleId === RULE_IDS.UNICODE_TAG_BLOCK) return 'unicode-tag-block';
+      if (f.ruleId === RULE_IDS.INJECTION_PATTERN) return f.match;
+      return `${f.ruleId}:${f.match}`;
+    }
+
     const severity = findings.length >= 3 ? 'HIGH' : 'LOW';
     const label = toolName === 'Read' ? path.basename(source) : source;
     const detail = severity === 'HIGH'
@@ -306,7 +327,7 @@ process.stdin.on('end', () => {
       : 'Single pattern match may be a false positive (e.g., documentation). Proceed with awareness.';
     const advisory =
       `\u26a0\ufe0f INJECTION SCAN [${severity}] (${toolName}): "${label}" triggered ` +
-      `${findings.length} pattern(s): ${findings.join(', ')}. ` +
+      `${findings.length} pattern(s): ${findings.map(renderFinding).join(', ')}. ` +
       `This content is now in your conversation context. ${detail} Source: ${source}`;
 
     // Opt-in blocking: only when configured AND high-confidence
@@ -323,8 +344,8 @@ process.stdin.on('end', () => {
     const output = blocking
       ? { decision: 'block',
           reason: `Prompt-injection blocked (${toolName}). ${advisory}`,
-          hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: advisory } }
-      : { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: advisory } };
+          hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: advisory, findings } }
+      : { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: advisory, findings } };
 
     process.stdout.write(JSON.stringify(output));
   } catch {

package/hooks/gsd-statusline.js

@@ -9,9 +9,38 @@ const os = require('os');
 // Namespace (not destructured) so tests can inject spawn failures by
 // monkeypatching childProcess.execFileSync.
 const childProcess = require('child_process');
+// #3582: gsd-core/bin/lib/*.cjs (semver-compare.cjs, state-document.cjs,
+// active-workstream-store.cjs, planning-workspace.cjs — required below) and
+// package-identity.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`. The statusline renders on EVERY prompt, so a build
+// failure here must DEGRADE (print nothing, exit 0) rather than crash
+// Claude Code's per-render statusline hook. Scoped to the spawned-as-a-script
+// path (`require.main === module`) — a test `require()` of this module for
+// its pure helpers assumes a built tree, same as every other hook test.
+if (require.main === module) {
+  try {
+    const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+    ensureRuntimeBuild();
+  } catch (e) {
+    process.stdout.write('');
+    process.exit(0);
+  }
+}
 const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
 const { normalizeStateStatus } = require('../gsd-core/bin/lib/state-document.cjs');
+// #2850: reuse the existing workstream resolution seams rather than
+// re-implementing CLI>env>store precedence or path construction inline.
+// peekActiveWorkstream is the read-only sibling of the store-tier lookup
+// resolveActiveWorkstream defaults to (getActiveWorkstream) — that default
+// self-heals a stale/invalid pointer by deleting it, which is correct for a
+// command but not for a renderer invoked on every prompt. Injecting it via
+// resolveActiveWorkstream's own `getStored` override keeps the CLI>env>store
+// precedence itself fully reused (untouched); only the store tier's *write*
+// side effect is removed.
+const { resolveActiveWorkstream, peekActiveWorkstream } = require('../gsd-core/bin/lib/active-workstream-store.cjs');
+const { listAvailableWorkstreams, planningPaths } = require('../gsd-core/bin/lib/planning-workspace.cjs');
 
 // --- Config + last-command readers ------------------------------------------
 
@@ -102,21 +131,65 @@ function readLastSlashCommand(transcriptPath) {
 // --- GSD state reader -------------------------------------------------------
 
 /**
- * Walk up from dir looking for .planning/STATE.md.
- * Returns parsed state object or null.
+ * Read and parse a STATE.md if it exists. Returns the parsed state object,
+ * `null` when the file is absent, or `null` on any read/parse failure (never
+ * throws) — the single shared shape for both the flat and workstream reads
+ * in readGsdState() below.
+ */
+function readStateFileOrNull(statePath) {
+  if (!fs.existsSync(statePath)) return null;
+  try {
+    return parseStateMd(fs.readFileSync(statePath, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Walk up from dir looking for .planning/STATE.md (flat mode). If an ancestor
+ * has no flat STATE.md but IS in workstream mode (.planning/workstreams/
+ * present — the single-source-of-truth check `listAvailableWorkstreams`
+ * shares with the init.progress/phase.complete #1912/#2028 guards, so this
+ * can't drift from how every other GSD command detects the mode), resolve
+ * the active workstream and read that workstream's STATE.md instead (#2850).
+ *
+ * Resolution reuses `resolveActiveWorkstream` (active-workstream-store.cjs)
+ * called with an empty args array, so only its env>store precedence applies
+ * here — the CLI leg is inert for this renderer, which never receives argv.
+ * The store tier is `peekActiveWorkstream`, a READ-ONLY sibling of the
+ * default `getActiveWorkstream`: the default self-heals a stale/invalid
+ * pointer by deleting it, which is correct for a command but not for a
+ * renderer invoked on every prompt — a render must never write or delete.
+ *
+ * Returns:
+ *   - the parsed state object when a flat or workstream STATE.md is found
+ *   - { noActiveWorkstream: true } when workstream mode is active at an
+ *     ancestor but no workstream can be resolved — an observable signal so
+ *     this is distinguishable from "GSD isn't installed here" (#2850)
+ *   - null when no .planning marker is found at all (GSD not present), or
+ *     when a workstream DOES resolve but its STATE.md doesn't exist yet
+ *     (negative space: mirrors flat-mode's own silent pre-STATE.md window)
  */
 function readGsdState(dir) {
   const home = os.homedir();
   let current = dir;
   for (let i = 0; i < 10; i++) {
-    const candidate = path.join(current, '.planning', 'STATE.md');
-    if (fs.existsSync(candidate)) {
+    const flatState = readStateFileOrNull(path.join(current, '.planning', 'STATE.md'));
+    if (flatState !== null) return flatState;
+
+    if (listAvailableWorkstreams(current).length > 0) {
+      let resolvedWs = null;
       try {
-        return parseStateMd(fs.readFileSync(candidate, 'utf8'));
+        resolvedWs = resolveActiveWorkstream(current, [], process.env, { getStored: peekActiveWorkstream }).ws;
       } catch (e) {
-        return null;
+        resolvedWs = null;
       }
+
+      if (!resolvedWs) return { noActiveWorkstream: true };
+
+      return readStateFileOrNull(planningPaths(current, resolvedWs).state);
     }
+
     const parent = path.dirname(current);
     if (parent === current || current === home) break;
     current = parent;
@@ -217,6 +290,10 @@ function parseStateMd(content) {
   return state;
 }
 
+// #2850: shared literal for formatGsdState/formatGsdStateCompact's "nothing
+// resolvable" signal — one source of truth so the two renderers can't drift.
+const NO_ACTIVE_WORKSTREAM_LABEL = 'no active workstream';
+
 /**
  * Render a 10-segment milestone progress bar (matches the context meter style).
  *
@@ -249,6 +326,10 @@ function renderProgressBar(percent) {
  * progress.percent is present in frontmatter; absent → empty string.
  */
 function formatGsdState(s) {
+  // #2850: workstream mode with nothing resolvable — an observable signal,
+  // never silent emptiness (distinguishes from "GSD isn't installed here").
+  if (s.noActiveWorkstream) return NO_ACTIVE_WORKSTREAM_LABEL;
+
   const parts = [];
 
   // Milestone segment: version + name + (opt-in) progress bar
@@ -364,6 +445,9 @@ function shortGsdStatus(status) {
  * The default "full" format is untouched.
  */
 function formatGsdStateCompact(s) {
+  // #2850: mirrors formatGsdState's observable "nothing resolvable" signal.
+  if (s.noActiveWorkstream) return NO_ACTIVE_WORKSTREAM_LABEL;
+
   const parts = [];
 
   if (s.milestone) parts.push(s.milestone);

package/hooks/gsd-update-banner.js

@@ -15,7 +15,28 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { PACKAGE_NAME, 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 is an opt-in SessionStart
+// hook — a build failure here must DEGRADE, not crash session start. With
+// PACKAGE_NAME left null, buildBannerOutput's own lineage guard
+// (`!cache.package_name || cache.package_name !== PACKAGE_NAME`) always
+// treats the cache as untrusted, so main() falls through to its existing
+// silent "print nothing" path below — no separate degrade branch needed.
+// 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 PACKAGE_NAME = null;
+let updateCacheFileName = 'gsd-update-check.json';
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs'));
+} catch (e) {
+  // Runtime library missing/broken and could not self-build — degrade to the
+  // fallbacks above rather than crash the SessionStart hook.
+}
 
 // Suppress repeat parse-error banners for 24 hours so a genuinely broken
 // cache file doesn't nag the user every session.

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,46 @@
 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');
 
 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 +74,86 @@ 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',
   });
   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,
+  };
+  process.stdout.write(JSON.stringify(output));
+  // Kimi CLI's exit-2 protocol feeds stderr back to the model (#2304)
+  process.stderr.write(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;
@@ -180,6 +267,15 @@ 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);
@@ -192,14 +288,7 @@ process.stdin.on('end', () => {
       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);
+          emitForceAddBlock();
           process.exit(2);
         }
       }
@@ -264,8 +353,17 @@ process.stdin.on('end', () => {
     };
 
     process.stdout.write(JSON.stringify(output));
-  } catch (e) {
-    // Silent fail — never block tool execution
+  } 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), exit 2 rather than silently allowing. Everything else
+    // keeps the historical fail-open posture: a broken advisory guard must
+    // never wedge the session's tool calls.
+    if (failClosedBlockContext(input)) {
+      emitForceAddBlock('fail-closed');
+      process.exit(2);
+    }
     process.exit(0);
   }
 });

package/hooks/gsd-worktree-path-guard.js

@@ -173,7 +173,8 @@ process.stdin.on('end', () => {
     // / error → not GSD-managed → no-op.
     const branchResult = git(['symbolic-ref', '--short', 'HEAD'], cwd);
     const branch = branchResult.status === 0 && branchResult.stdout ? branchResult.stdout.trim() : '';
-    if (!/^(worktree-)?agent-[A-Za-z0-9._/-]+$/.test(branch)) {
+    // #3021: accept worktree-wf_<runid>-<n> branches (Workflow backend's naming).
+    if (!/^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$/.test(branch)) {
       process.exit(0); // not a GSD-managed executor worktree — no-op
     }