@opengsd/gsd-core 1.10.0 → 1.11.0

package/hooks/dist/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/dist/lib/git-cmd.js

@@ -19,9 +19,19 @@
  * hook's own __dirname:
  *
  *   const { isGitSubcommand } = require(path.join(__dirname, 'lib', 'git-cmd.js'));
+ *
+ * `tokenize()` delegates to the shared `src/token-scanner.cts` seam (ADR-3212
+ * §4, epic #3212 Phase 3, #3414) — the built `gsd-core/bin/lib/token-scanner.cjs`
+ * artifact, not a sibling hooks/-tree file, because hook scripts are staged as
+ * standalone files at install time and a sibling require is a staging
+ * dependency that can fail silently (see gsd-workflow-guard.js's own
+ * KIMI_TOOL_NAMES comment for the precedent this follows). Re-exported here
+ * unchanged — every existing caller's behavior is identical (parity-asserted
+ * in tests/token-scanner.test.cjs row 5).
  */
 
 const path = require('path');
+const { tokenizeShellLike } = require(path.join(__dirname, '..', '..', 'gsd-core', 'bin', 'lib', 'token-scanner.cjs'));
 
 /**
  * Git global options that take a following argument.
@@ -29,6 +39,7 @@ const path = require('path');
  */
 const ARGUMENT_TAKING_FLAGS = new Set([
   '-C',                // working directory
+  '-c',                // config override (separate-arg form: `git -c k=v …`; #3504)
   '--git-dir',         // path to git repository
   '--work-tree',       // path to working tree
   '--namespace',       // git namespace
@@ -57,94 +68,116 @@ const BOOLEAN_FLAGS = new Set([
  * Handles single-quoted strings, double-quoted strings, and unquoted tokens.
  * Does NOT perform variable expansion or brace expansion.
  *
+ * Delegates to the shared `src/token-scanner.cts` seam — see the module
+ * header comment for why the built artifact, not a sibling require, is used.
+ *
  * @param {string} cmd
  * @returns {string[]}
  */
 function tokenize(cmd) {
-  const tokens = [];
-  let i = 0;
-  const len = cmd.length;
-
-  while (i < len) {
-    // Skip whitespace
-    while (i < len && /\s/.test(cmd[i])) i++;
-    if (i >= len) break;
-
-    let token = '';
-    while (i < len && !/\s/.test(cmd[i])) {
-      if (cmd[i] === "'") {
-        // Single-quoted string: take everything until closing '
-        i++;
-        while (i < len && cmd[i] !== "'") token += cmd[i++];
-        if (i < len) i++; // consume closing '
-      } else if (cmd[i] === '"') {
-        // Double-quoted string: take everything until closing " (no escape handling)
-        i++;
-        while (i < len && cmd[i] !== '"') token += cmd[i++];
-        if (i < len) i++; // consume closing "
-      } else {
-        token += cmd[i++];
-      }
-    }
-    if (token) tokens.push(token);
-  }
-
-  return tokens;
+  return tokenizeShellLike(cmd);
 }
 
 /**
- * Return true if `cmd` invokes the git subcommand `sub`.
+ * Walk past leading env-prefix assignments and global git options, same as
+ * `isGitSubcommand`'s phases 1-3. Returns the index of the subcommand token,
+ * or -1 if the command does not resolve to a git invocation at all.
  *
- * @param {string} cmd  - Full shell command string (may include env vars, full paths)
- * @param {string} sub  - Subcommand to test for, e.g. 'commit'
- * @returns {boolean}
+ * @param {string[]} tokens
+ * @returns {number}
  */
-function isGitSubcommand(cmd, sub) {
-  if (!cmd || !sub) return false;
-
-  const tokens = tokenize(cmd);
+function skipToSubcommand(tokens) {
   let i = 0;
-
-  // Phase 1: skip leading VAR=VALUE environment assignments
   while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) {
     i++;
   }
-
-  // Phase 2: the next token must be the git executable
-  if (i >= tokens.length) return false;
+  if (i >= tokens.length) return -1;
   const gitToken = tokens[i++];
-  if (path.basename(gitToken) !== 'git') return false;
+  if (path.basename(gitToken) !== 'git') return -1;
 
-  // Phase 3: consume git global options
   while (i < tokens.length) {
     const t = tokens[i];
-
-    // --flag=value form for argument-taking flags
     const eqIdx = t.indexOf('=');
     const flagName = eqIdx !== -1 ? t.slice(0, eqIdx) : t;
     if (ARGUMENT_TAKING_FLAGS.has(flagName)) {
-      if (eqIdx !== -1) {
-        // consumed as one token: --git-dir=.git
-        i++;
-      } else {
-        // consumed as two tokens: -C /path
-        i += 2;
-      }
+      i += eqIdx !== -1 ? 1 : 2;
+      continue;
+    }
+    // #3504: glued `-ckey=value` form — git accepts the config override with
+    // its argument attached (`git -cfoo.bar=1 …`). The eq-slice above yields
+    // flagName `-cfoo`, which no set contains, so without this arm the walk
+    // stops and the whole invocation is misclassified as not-git.
+    if (/^-c\S*=/.test(t)) {
+      i++;
       continue;
     }
-
     if (BOOLEAN_FLAGS.has(t)) {
       i++;
       continue;
     }
-
-    // Not a global option — this is the subcommand
     break;
   }
+  return i;
+}
+
+/**
+ * Extract the branch-name argument from a git command line that creates or
+ * references one — `git checkout -b <name>` or `git branch <name>`. Returns
+ * null for any other command, including plain `git checkout <ref>` (switches
+ * branches, does not create one) and commands where a checkout/branch-shaped
+ * substring appears only inside a quoted argument (e.g. a commit message).
+ *
+ * New capability (ADR-3212 §4, epic #3212 Phase 3, #3414) exercising the
+ * shared scanner on the domain the ADR names ("a branch name... [is] not
+ * regular") — not a migration of existing duplicated logic; no prior
+ * implementation of this existed in the repo (design doc §1.2).
+ *
+ * @param {string} cmd
+ * @returns {string | null}
+ */
+function extractBranchArgument(cmd) {
+  if (!cmd) return null;
+  const tokens = tokenizeShellLike(cmd);
+  const subIdx = skipToSubcommand(tokens);
+  if (subIdx === -1 || subIdx >= tokens.length) return null;
+  const sub = tokens[subIdx];
+
+  if (sub === 'checkout') {
+    for (let j = subIdx + 1; j < tokens.length; j++) {
+      if (tokens[j] === '-b' && j + 1 < tokens.length) return tokens[j + 1];
+    }
+    return null;
+  }
+
+  if (sub === 'branch') {
+    for (let j = subIdx + 1; j < tokens.length; j++) {
+      if (!tokens[j].startsWith('-')) return tokens[j];
+    }
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Return true if `cmd` invokes the git subcommand `sub`.
+ *
+ * @param {string} cmd  - Full shell command string (may include env vars, full paths)
+ * @param {string} sub  - Subcommand to test for, e.g. 'commit'
+ * @returns {boolean}
+ */
+function isGitSubcommand(cmd, sub) {
+  if (!cmd || !sub) return false;
+
+  // Phases 1-3 (env-prefix skip, git-executable check, global-option consume)
+  // extracted verbatim into skipToSubcommand — byte-identical logic, shared
+  // with extractBranchArgument rather than a second copy (#3212 Phase 3).
+  const tokens = tokenizeShellLike(cmd);
+  const subIdx = skipToSubcommand(tokens);
 
   // Phase 4: check the subcommand
-  if (i >= tokens.length) return false;
-  return tokens[i] === sub;
+  if (subIdx === -1 || subIdx >= tokens.length) return false;
+  return tokens[subIdx] === sub;
 }
 
-module.exports = { isGitSubcommand, tokenize };
+module.exports = { isGitSubcommand, tokenize, extractBranchArgument, skipToSubcommand };

package/hooks/dist/lib/injection-patterns.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * injection-patterns.js — the shared prompt-injection pattern list (#3504, epic #1900).
+ *
+ * Single source of truth for the standard injection signatures used by BOTH
+ * gsd-prompt-guard.js (PreToolUse scan of writes into .planning/) and
+ * gsd-read-injection-scanner.js (PostToolUse scan of Read/WebFetch/WebSearch
+ * content). Previously each hook carried a byte-identical copy ("inlined for
+ * hook independence") that could silently drift — a pattern tightened in one
+ * would stop protecting the other surface.
+ *
+ * Why a shared lib require is safe here (the old inlining rationale, retired):
+ * the installer stages hooks/lib/ from the GSD_HOOK_LIB_FILES allowlist for the
+ * shared-bundle surfaces (Claude-family settings.json runtimes and Kimi), the
+ * Cursor stager auto-discovers require('./lib/...') in staged scripts and fails
+ * the install loudly when a helper is missing (#2587), and the plugin path
+ * ships this directory wholesale.
+ *
+ * Deliberately NOT unified with src/security.cts's scanForInjection set: that
+ * set runs inside the compiled lib tree; hooks must stay loadable standalone
+ * without it. The two lists are different surfaces by design, not drift.
+ *
+ * Keep this file free of literal 'gsd:' text — the stager rewrites that marker
+ * in staged hook content.
+ */
+
+const INJECTION_PATTERNS = Object.freeze([
+  /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,
+]);
+
+module.exports = { INJECTION_PATTERNS };

package/hooks/dist/lib/isolation-deny-reason.js

@@ -0,0 +1,39 @@
+'use strict';
+// hooks/lib/isolation-deny-reason.js — shared, frozen reason-code enum for
+// the #3045 dispatch-isolation guards' block/deny decisions
+// (hooks/gsd-agent-isolation-guard.js, hooks/gsd-cursor-subagent-start.js).
+//
+// CONTRIBUTING.md ("Prohibited: Raw Text Matching on Test Outputs") bans
+// asserting on a hook's free-form, human-readable reason/user_message prose
+// — that text is for the operator/model reading the denial and may change
+// wording without notice. Every block/deny decision therefore ALSO carries
+// one of these STABLE codes (surfaced on the hook's stdout JSON as
+// `reason_code`), so tests assert `out.reason_code === REASON_CODE.X`
+// instead of regexing the message (mirrors the REASON enum convention in
+// gsd-core/bin/verify-reapply-patches.cjs).
+//
+// Adding a new code requires updating this enum AND any test that locks the
+// documented set.
+const REASON_CODE = Object.freeze({
+  // The compiled runtime library (gsd-core/bin/lib/*.cjs) is missing and
+  // could not be self-built (ensure-runtime-build.cjs's RuntimeBuildError).
+  RUNTIME_BUILD_FAILED: 'runtime_build_failed',
+  // The project's dispatch-isolation configuration ('.planning/config.json')
+  // could not be read or resolved for a reason OTHER than a runtime-build
+  // failure (unreadable/malformed config, unexpected resolver error).
+  CONFIG_UNREADABLE: 'config_unreadable',
+  // Isolation resolves to "harness-worktree" but the Agent()/Task() dispatch
+  // is missing the harness's isolation flag/kwarg.
+  HARNESS_FLAG_MISSING: 'harness_flag_missing',
+  // Isolation resolves to "harness-worktree" but the dispatch payload carries
+  // no usable subagent_type, so the guard cannot confirm it is a GSD executor.
+  NO_SUBAGENT_TYPE: 'no_subagent_type',
+  // Isolation resolves to "harness-worktree" but whether the workspace root
+  // is an isolated worktree could not be determined (e.g. git unresponsive).
+  CANNOT_DETERMINE_ISOLATION: 'cannot_determine_isolation',
+  // Isolation resolves to "harness-worktree" and the workspace root is
+  // confirmed NOT an isolated worktree.
+  NOT_ISOLATED_WORKTREE: 'not_isolated_worktree',
+});
+
+module.exports = { REASON_CODE };

package/hooks/dist/lib/isolation-sentinel.js

@@ -130,6 +130,15 @@ function resolveSentinelRoot(cwd) {
     if (fs.existsSync(path.join(cwd, '.planning'))) {
       return cwd;
     }
+    // #3582: worktree-safety.cjs / project-root.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`. Self-heal before either
+    // require below; a RuntimeBuildError (or any other failure) falls through
+    // to the existing catch's degrade-to-raw-`cwd` — unchanged behavior, just
+    // now attempted-healed-first rather than silently degrading on the first
+    // cold-tree encounter.
+    const { ensureRuntimeBuild } = require('../../gsd-core/bin/ensure-runtime-build.cjs');
+    ensureRuntimeBuild();
     const { resolveWorktreeRoot } = require('../../gsd-core/bin/lib/worktree-safety.cjs');
     const { root } = resolveWorktreeRoot(cwd);
     const { findProjectRoot } = require('../../gsd-core/bin/lib/project-root.cjs');