@opengsd/gsd-core 1.9.1 → 1.11.0

package/hooks/gsd-write-guard.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// GSD Write Guard — PreToolUse hook
+// Blocks a whole-file Write that catastrophically shrinks a curated .planning/
+// artifact (ROADMAP.md, milestone roadmaps, STATE.md).
+//
+// Problem (#973, fix 3 of 3): a planner read a ~16-line window of ROADMAP.md
+// and Write-overwrote the whole 292-line file with it — three milestones of
+// committed history destroyed. Fixes 1 and 2 (PR #989) are instructions to a
+// model: they lower the probability of a clobber but cannot prevent one, and
+// they protect only the agents that were audited. This hook is enforced by
+// code rather than by instruction: it compares the pending Write payload
+// against the file on disk and hard-blocks a catastrophic shrink BEFORE it
+// happens. An advisory will not do — #973 records an agent reading the
+// advisory, classifying it as non-binding, and reasoning past it while
+// holding a false model of what Write does.
+//
+// The guarantee is bounded, and the bound is worth stating where the code
+// lives: this stops accidental and single-shot collapse, not a determined
+// agent. The sentinel hatch below is a plain file, so an agent that would
+// reason past an advisory can arm one with a single Bash call it is already
+// permitted to make. What ships is the conversion of "ignore a sentence" into
+// "take one deliberate, path-bound, single-use, auditable action" — a real
+// improvement against the confused-agent threat #973 records, not a defense
+// against an evader.
+//
+// Deliberately narrow trigger:
+//   - Write only (Edit/MultiEdit are scoped by construction);
+//   - the target already exists on disk;
+//   - the target is a curated .planning/ artifact — the project ROADMAP.md,
+//     milestone roadmaps (.planning/milestones/*-ROADMAP.md), and STATE.md.
+//     NOT arbitrary markdown: free-prose docs get legitimately rewritten
+//     wholesale, and a guard that fires on those trains override-fatigue
+//     until nobody reads it.
+//
+// Threshold: block when the pending payload carries fewer than SHRINK_RATIO
+// (40%) of the on-disk line count. The docs-update fix-loop's 90% bar is far
+// too permissive for a curated artifact — the #973 incident was a ~94.5%
+// collapse and clears a 90% bar only barely. The same ~40%/floor-40 tuning
+// has run clean (no false positives) as a commit-time twin downstream.
+//
+// Floor: files under FLOOR_LINES are exempt, so a 10 → 2 line stub never
+// trips the ratio check.
+//
+// Escape hatches — both named in the block message; a guard whose bypass is
+// undocumented gets bypassed with the blunt instrument instead, with every
+// other guard disabled at the same time:
+//   - GSD_ALLOW_PLANNING_SHRINK=1 (env) — for a human running interactively,
+//     where the variable can actually reach the hook's environment.
+//   - .planning/.gsd-allow-shrink (single-use sentinel file) — for workflow
+//     steps. A PreToolUse hook inherits the RUNTIME's environment, so a
+//     per-step env prefix can never reach it (#2255 round 5 M1); the sentinel
+//     is a transport that code consults, not prose an agent obeys. The step
+//     writes the target's path into the sentinel; at the block point the
+//     guard checks it is fresh (15 min) and names the pending target, then
+//     CONSUMES it and allows that one write. Path-bound + single-use +
+//     freshness is what keeps it from becoming a standing unlock left on disk.
+//
+// Known design limits (out of #2255's scope by review, disclosed here AND in
+// the changeset + USER-GUIDE — round 9 required the user-facing docs to match):
+//   - Stateless per-write: sequential shrinks (292→120→50) each clear the 40%
+//     floor against CURRENT disk state, so cumulative erosion is invisible.
+//   - Unconditionally case-insensitive matching (required on the
+//     case-insensitive filesystems macOS/Windows default to): on
+//     case-sensitive Linux a genuinely distinct '.planning/roadmap.md' is
+//     also treated as curated. Narrow, accepted cost.
+// (A third limit — a symlinked path into a curated file escaping the lexical
+// match — was closed in round 9: the target is realpath-resolved before the
+// curated match.)
+//
+// Triggers on: Write tool calls
+// Action: BLOCK (decision: 'block', exit 2) on catastrophic shrink of a curated file
+// No-op: other tools, new files, non-curated paths, sub-floor files, override set,
+//        hook errors (silent fail)
+
+const fs = require('fs');
+const path = require('path');
+
+// Block when the pending payload has fewer than this fraction of the on-disk
+// line count (0.4 → a Write shrinking a file below 40% of its current size).
+const SHRINK_RATIO = 0.4;
+
+// Files with fewer lines than this are exempt — small stubs get legitimately
+// rewritten far below any ratio.
+const FLOOR_LINES = 40;
+
+// Curated .planning/ artifacts, matched against the resolved target path with
+// separators normalized to '/'. Deliberately a closed set (see header).
+// Case-insensitive: on the case-insensitive filesystems macOS and Windows
+// default to, a differently-cased path is the SAME real file — a Write to
+// '.planning/roadmap.md' clobbers ROADMAP.md while a case-sensitive match
+// waves it through.
+const CURATED_PATTERNS = [
+  /(?:^|\/)\.planning\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/milestones\/[^/]+-ROADMAP\.md$/i,
+];
+
+// Count logical lines, ignoring a single trailing newline so that
+// "a\nb\n" and "a\nb" both count as 2.
+function countLines(text) {
+  if (!text) return 0;
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines.length;
+}
+
+function isOverrideSet() {
+  const v = process.env.GSD_ALLOW_PLANNING_SHRINK;
+  return typeof v === 'string' && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
+}
+
+// Single-use sentinel (see header). Consulted ONLY at the shrink-block point —
+// a write that would pass anyway never burns the token, so first-shrink-wins
+// for the write the workflow armed it for.
+const SENTINEL_NAME = '.gsd-allow-shrink';
+const SENTINEL_REL = '.planning/' + SENTINEL_NAME;
+const SENTINEL_TTL_MS = 15 * 60 * 1000;
+
+function consumeSentinelFor(filePath, normalized) {
+  try {
+    // The curated match guarantees the target lives under a .planning/ dir;
+    // normalized is filePath with separators flipped, so offsets line up.
+    const m = normalized.match(/^(.*\/\.planning)\//i);
+    if (!m) return false;
+    const planningDir = filePath.slice(0, m[1].length);
+    const sentinelPath = path.join(planningDir, SENTINEL_NAME);
+    let st;
+    try {
+      st = fs.statSync(sentinelPath);
+    } catch {
+      return false; // not armed
+    }
+    if (Date.now() - st.mtimeMs > SENTINEL_TTL_MS) {
+      // A stale token is a leftover, not an authorization — housekeep it.
+      try { fs.unlinkSync(sentinelPath); } catch { /* best-effort */ }
+      return false;
+    }
+    const token = fs.readFileSync(sentinelPath, 'utf8').split('\n')[0].trim();
+    if (!token) return false;
+    // Path-bound: the token names exactly one file, resolved against the
+    // .planning/ dir's parent (repo root) — same case-insensitive stance as
+    // the curated match itself.
+    const namedNorm = path.resolve(path.join(planningDir, '..'), token).replace(/\\/g, '/').toLowerCase();
+    if (namedNorm !== normalized.toLowerCase()) {
+      return false; // armed for a different file — leave it for that write
+    }
+    // Consume BEFORE allowing: even if the Write then fails, the safe
+    // direction is a spent token, never a lingering one.
+    fs.unlinkSync(sentinelPath);
+    return true;
+  } catch {
+    // Any sentinel-machinery error means "not exempt" — the guard's normal
+    // (blocking) flow proceeds; the hatch may never fail a guard open.
+    return false;
+  }
+}
+
+// m2 (round 5): the block emission must itself be exception-safe. An EPIPE
+// from writeSync inside the outer try would land in the fail-OPEN catch —
+// the one outcome the fail-closed branches exist to prevent. The decision
+// stands regardless of whether the payload could be delivered.
+function emitBlock(output) {
+  try {
+    // writeSync: pipe writes via process.stdout/stderr are async on Windows
+    // and process.exit() does not flush them — a truncated block payload is
+    // a guard that silently half-fired.
+    fs.writeSync(1, JSON.stringify(output));
+    // Kimi feeds stderr (not stdout) back to the model on exit 2.
+    fs.writeSync(2, output.reason);
+  } catch {
+    // Emission failed; the block still stands.
+  }
+  process.exit(2);
+}
+
+// #2304: Kimi's native hook bus delivers Kimi's tool vocabulary in the payload
+// (Write → WriteFile, Edit/MultiEdit → StrReplaceFile) while the [[hooks]]
+// matcher is registered pre-translated (runtime-hooks-surface.cts
+// buildKimiHooksTomlBlock) — so without normalizing the payload too, the
+// matcher fires but the tool_name check below exits 0 and the guard is dormant
+// on Kimi. The tool_input field names differ as well (kimi-cli
+// src/kimi_cli/tools/file/write.py): WriteFile takes `path`/`content`, and
+// kimi-cli's hooks/events.py forwards tool_input verbatim, so both layers need
+// mapping. Only WriteFile is mapped: this guard exits 0 for any tool but
+// Write, so an Edit-class mapping here would be dead code. Accepts bare and
+// module-qualified ('kimi_cli.tools.file:WriteFile') names; unknown names fall
+// through untouched. Inlined per guard (not hooks/lib/): hook scripts are
+// staged as standalone files, and a sibling require is a staging dependency
+// that can fail silently.
+// A Map, not an object literal: bare bracket lookup resolves prototype keys
+// ('constructor', '__proto__', 'toString') to truthy functions/objects, so the
+// !mapped fall-through never fires for them; Map.get returns undefined (same
+// shape as canonicalizeRuntimeName in src/runtime-name-policy.cts).
+const KIMI_TOOL_NAMES = new Map([['WriteFile', 'Write']]);
+function normalizeKimiPayload(data) {
+  // #2595: total over everything JSON can express — JSON.parse('null') is
+  // null, and reading .tool_name off a primitive would throw into the outer
+  // fail-open catch. A null payload has nothing to guard; pass it through
+  // deliberately rather than by crash.
+  if (data === null || typeof data !== 'object') return data;
+  const raw = data.tool_name;
+  if (typeof raw !== 'string') return data;
+  const mapped = KIMI_TOOL_NAMES.get(raw.slice(raw.lastIndexOf(':') + 1));
+  if (!mapped) return data;
+  data.tool_name = mapped;
+  const input = data.tool_input;
+  if (input && typeof input === 'object') {
+    // #2595 (review): Kimi's `path` is AUTHORITATIVE — it must win outright,
+    // not merely fill in when `file_path` happens to be absent. kimi-cli's
+    // WriteFile schema carries no `file_path` at all (src/kimi_cli/tools/
+    // file/write.py), so a `file_path` in a Kimi payload is ALWAYS
+    // model-supplied; under the old `=== undefined` condition a payload
+    // pairing a curated `path` with a spurious `file_path: ""` left this
+    // guard reading '' and exiting 0 while kimi-cli wrote to `path` — a
+    // one-key bypass needing no crash. Overwriting can only narrow what the
+    // guard inspects to the path that will actually be written.
+    if (typeof input.path === 'string') {
+      input.file_path = input.path;
+    }
+  }
+  return data;
+}
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 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));
+
+    // A null/primitive payload has nothing to guard — exit deliberately
+    // rather than throwing into the fail-open catch below (#2595 class).
+    if (data === null || typeof data !== 'object') {
+      process.exit(0);
+    }
+
+    // Only whole-file Write is catastrophic-by-construction; Edit/MultiEdit
+    // replace bounded spans and are out of scope by design (#2255).
+    if (data.tool_name !== 'Write') {
+      process.exit(0);
+    }
+
+    if (isOverrideSet()) {
+      process.exit(0); // documented escape hatch — legitimate reset in progress
+    }
+
+    // Typed read (#2547 class): `[]`/`{}` are truthy, pass a `!value`
+    // early-out, then throw inside path.resolve() — crash-to-allow via the
+    // outer catch. A non-string path field degrades to '' and exits here.
+    const rawInput = data.tool_input;
+    const rawFilePath = typeof rawInput?.file_path === 'string' ? rawInput.file_path : '';
+    const content = rawInput?.content;
+    if (!rawFilePath || typeof content !== 'string') {
+      process.exit(0);
+    }
+
+    // Resolve relative paths against the session cwd (the same base the
+    // runtime uses), then normalize separators for the curated match.
+    const cwd = data.cwd || process.cwd();
+    let filePath = path.resolve(cwd, rawFilePath);
+    // Resolve symlinks before the curated match (round 9, Minor 1): a Write
+    // to a non-curated path that symlinks into a curated file was not
+    // matched, while writeFileSync follows the link and clobbers the real
+    // target. ENOENT (new file) keeps the lexical resolution; any other
+    // realpath error also keeps it, and the read below then fails closed.
+    try {
+      filePath = fs.realpathSync(filePath);
+    } catch { /* keep the lexical path */ }
+    const normalized = filePath.replace(/\\/g, '/');
+
+    if (!CURATED_PATTERNS.some(re => re.test(normalized))) {
+      process.exit(0); // not a curated planning artifact
+    }
+
+    // Only guard overwrites — creating a curated file fresh is fine.
+    // ENOENT alone fails open (no baseline to protect); any OTHER read error
+    // (EACCES, EISDIR, ELOOP, EMFILE, a Windows lock) fails CLOSED — a guard
+    // that waves a curated Write through on a transient read error is not
+    // enforced by code at all, it is a race away from #973.
+    let onDisk;
+    try {
+      onDisk = fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        process.exit(0); // does not exist — new-file Write, nothing to clobber
+      }
+      emitBlock({
+        decision: 'block',
+        readError: err && err.code ? String(err.code) : 'UNKNOWN',
+        overrideEnvVar: 'GSD_ALLOW_PLANNING_SHRINK',
+        overrideSentinel: SENTINEL_REL,
+        reason:
+          `Write guard: could not read '${filePath}' to compare against the pending ` +
+          `Write (${err && err.code ? err.code : 'unknown read error'}). ` +
+          `'${path.basename(filePath)}' is a curated planning artifact, so this guard ` +
+          `fails closed rather than risk a blind overwrite. Retry once the file is ` +
+          `readable, or — if this overwrite is intentional — re-run with the ` +
+          `environment variable GSD_ALLOW_PLANNING_SHRINK=1 to bypass this guard once.`,
+      });
+    }
+
+    const oldLines = countLines(onDisk);
+    const newLines = countLines(content);
+
+    if (oldLines < FLOOR_LINES) {
+      process.exit(0); // sub-floor stub — ratio checks are meaningless here
+    }
+
+    if (newLines >= oldLines * SHRINK_RATIO) {
+      process.exit(0); // shrink (if any) is within tolerance
+    }
+
+    // The mechanical hatch for workflow steps (see header): consulted only
+    // here, at the block point, so a within-tolerance write never burns it.
+    if (consumeSentinelFor(filePath, normalized)) {
+      process.exit(0); // armed for exactly this file, fresh, now consumed
+    }
+
+    const pct = Math.round((newLines / oldLines) * 100);
+    // Typed fields (oldLines/newLines/overrideEnvVar/overrideSentinel) ride
+    // alongside the free-form reason so consumers — including this repo's
+    // tests — never have to regex the prose (CONTRIBUTING.md: no raw text
+    // matching).
+    emitBlock({
+      decision: 'block',
+      oldLines,
+      newLines,
+      overrideEnvVar: 'GSD_ALLOW_PLANNING_SHRINK',
+      overrideSentinel: SENTINEL_REL,
+      // Round 9 Major 2: the denial deliberately does NOT explain how to arm
+      // the sentinel — #973 was an agent reasoning past an advisory, and a
+      // block message that prints the bypass recipe hands that same agent a
+      // mechanical self-authorization at the moment it is blocked. The
+      // sentinel transport stays documented where humans and the workflow
+      // engine read (USER-GUIDE, complete-milestone.md); the typed
+      // overrideSentinel field above stays for the binding tests. The env
+      // var stays named per #2255's acceptance criterion ("the override must
+      // be real and its name must appear in the block message") — it cannot
+      // reach a hook from a per-step prefix, so naming it does not hand the
+      // blocked agent a same-tool bypass.
+      reason:
+        `Write guard: this Write would shrink '${filePath}' from ${oldLines} lines to ` +
+        `${newLines} (${pct}% of current). '${path.basename(filePath)}' is a curated planning ` +
+        `artifact; a whole-file Write this much smaller usually means the payload was built ` +
+        `from a partial read of the file and would destroy the sections outside that window ` +
+        `(#973: a planner collapsed ROADMAP.md 292 → 16 lines this way). To fix: use Edit for ` +
+        `a scoped change, or Read the full file and include every section in the Write. ` +
+        `Intentional milestone resets go through the workflow's documented escape hatch; ` +
+        `interactively, re-run with the environment variable GSD_ALLOW_PLANNING_SHRINK=1 ` +
+        `to bypass this guard once.`,
+    });
+  } catch {
+    // Silent fail — never block valid tool calls due to hook errors
+    process.exit(0);
+  }
+});

package/hooks/hooks.json

@@ -21,6 +21,18 @@
         "hooks": [
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-worktree-path-guard.js\"", "timeout": 5 }
         ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-write-guard.js\"", "timeout": 5 }
+        ]
+      },
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-agent-isolation-guard.js\"", "timeout": 5 }
+        ]
       }
     ],
     "PostToolUse": [

package/hooks/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/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/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 };