@opengsd/gsd-core 1.16.0 → 1.18.0

package/hooks/dist/gsd-validate-commit.sh

@@ -39,6 +39,27 @@ cleanup_temp_files() {
 }
 trap cleanup_temp_files EXIT
 
+# The first line of $1 (everything before the first newline), matched BYTE-wise.
+#
+# `${1%%$'\n'*}` is a longest-suffix glob match, and on bash 3.2 (macOS's
+# /bin/bash) in a multibyte locale such as en_US.UTF-8 it costs ~3.5 s on a
+# 112KB value (#5473, measured inside the macOS conformance job: the same hook
+# on the same 114750-byte command took ~5.6 s under LC_ALL=en_US.UTF-8 and
+# ~0.55 s under LC_ALL=C, and a trace put 3.5 s of it on this expansion). A
+# newline is the same single byte in every locale, so matching it byte-wise
+# changes no result.
+#
+# ONLY call this inside a command substitution, `SUBJECT=$(gsd_first_line "$MSG")`:
+# the substitution's subshell is what keeps LC_ALL=C from leaking into the rest
+# of the hook, whose regexes and length arithmetic keep the caller's locale. A
+# substitution is a fork with no pipe between two processes, so it keeps the
+# property the pure-expansion form was chosen for (no `head -1` SIGPIPE race
+# under `set -euo pipefail`, #4429); printf is a builtin, so no exec either.
+gsd_first_line() {
+  LC_ALL=C
+  printf '%s' "${1%%$'\n'*}"
+}
+
 # The 10 built-in Conventional Commits types — the SINGLE declaration (#3811
 # review finding: this was previously hand-typed a second time inside the
 # node -e script below, a generative-fix-divergence risk per CLAUDE.md's
@@ -575,18 +596,19 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
       SUBJECT=$(GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" MSG="$MSG" node -e "
         const {resolveCommitSubject}=require(process.env.GIT_CMD_LIB);
         process.stdout.write(resolveCommitSubject(process.env.MSG));
-      " 2>/dev/null) || SUBJECT="${MSG%%$'\n'*}"
+      " 2>/dev/null) || SUBJECT=$(gsd_first_line "$MSG")
     else
-      # Pure parameter expansion, not `echo "$MSG" | head -1`: that pipeline
+      # Pure parameter expansion (in gsd_first_line), not
+      # `echo "$MSG" | head -1`: that pipeline
       # raced a SIGPIPE under `set -euo pipefail` whenever $MSG had a body
       # (the common case) — `head -1` can close its read end as soon as it
       # has the first line, and if `echo`'s write lands after that close,
       # `echo` dies with signal 13 (exit 141), which is NOT suppressed by
       # `set -e` and aborted the whole hook intermittently (observed in
-      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). Zero
-      # subprocesses here means zero pipe/race surface. Equivalent to
+      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). No pipe
+      # means no race surface. Equivalent to
       # `head -1` for single-line, multi-line, and trailing-newline input.
-      SUBJECT="${MSG%%$'\n'*}"
+      SUBJECT=$(gsd_first_line "$MSG")
     fi
     # Single source of truth for the accepted commit-type list (#3811): the
     # 10 built-ins plus whatever passed the safe-token filter above. Both the

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

@@ -227,7 +227,9 @@ function resolveRuntimeIdentity(cwd, configPath, resolveRuntimeNameFromCandidate
   // never a resolution failure (this function only ever throws for the
   // config.json read above, which the caller's catch already handles).
   try {
-    const defaultsPath = path.join(os.homedir(), '.gsd', 'defaults.json');
+    // #5017: the store root is GSD_HOME when set and non-blank, else the home
+    // directory — the config loader's rule (src/runtime-homes.cts resolveGsdHome).
+    const defaultsPath = path.join(process.env.GSD_HOME || os.homedir(), '.gsd', 'defaults.json');
     const defaultsRaw = fs.readFileSync(defaultsPath, 'utf-8');
     const defaultsParsed = JSON.parse(defaultsRaw);
     if (defaultsParsed && typeof defaultsParsed === 'object' && 'runtime' in defaultsParsed) {

package/hooks/gsd-check-update.js

@@ -67,26 +67,32 @@ const cacheFile = path.join(cacheDir, updateCacheFileName);
 const projectVersionFile = path.join(projectConfigDir, 'gsd-core', 'VERSION');
 const globalVersionFile = path.join(globalConfigDir, 'gsd-core', 'VERSION');
 
-// Ensure cache directory exists
-if (!fs.existsSync(cacheDir)) {
+// This background check is advisory. Cache or worker failures must not make
+// the SessionStart hook fail. Recursive mkdir is safe if another session
+// creates the directory concurrently.
+try {
   fs.mkdirSync(cacheDir, { recursive: true });
-}
 
-// Run check in background via a dedicated worker script.
-// Spawning a file (rather than node -e '<inline code>') keeps the worker logic
-// in plain JS with no template-literal regex-escaping concerns, and makes the
-// worker independently testable.
-const workerPath = path.join(__dirname, 'gsd-check-update-worker.js');
-const child = spawn(process.execPath, [workerPath], {
-  stdio: 'ignore',
-  windowsHide: true,
-  detached: true,  // Required on Windows for proper process detachment
-  env: {
-    ...process.env,
-    GSD_CACHE_FILE: cacheFile,
-    GSD_PROJECT_VERSION_FILE: projectVersionFile,
-    GSD_GLOBAL_VERSION_FILE: globalVersionFile,
-  },
-});
+  // Run check in background via a dedicated worker script.
+  // Spawning a file (rather than node -e '<inline code>') keeps the worker logic
+  // in plain JS with no template-literal regex-escaping concerns, and makes the
+  // worker independently testable.
+  const workerPath = path.join(__dirname, 'gsd-check-update-worker.js');
+  const child = spawn(process.execPath, [workerPath], {
+    stdio: 'ignore',
+    windowsHide: true,
+    detached: true,  // Required on Windows for proper process detachment
+    env: {
+      ...process.env,
+      GSD_CACHE_FILE: cacheFile,
+      GSD_PROJECT_VERSION_FILE: projectVersionFile,
+      GSD_GLOBAL_VERSION_FILE: globalVersionFile,
+    },
+  });
 
-child.unref();
+  // A spawn failure can also arrive asynchronously on the child process.
+  child.on('error', () => {});
+  child.unref();
+} catch {
+  // Update hints are best effort; a failed check must not interrupt startup.
+}

package/hooks/gsd-context-monitor.js

@@ -14,6 +14,8 @@
 // Thresholds:
 //   WARNING  (remaining <= 35%): Agent should wrap up current task
 //   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+// "remaining" is of the auto-compact threshold — the statusline puts the
+// bridge on that scale (#4985), so both fire before Claude Code compacts.
 // Both fire-points are overridable per project via .planning/config.json
 // (hooks.context_warning_threshold / hooks.context_critical_threshold, #4285);
 // the values above are the defaults used when the keys are absent or unusable.
@@ -500,23 +502,30 @@ const handleStdinEnd = () => {
     }
 
     // Build advisory warning message (never use imperative commands that
-    // override user preferences — see #884)
+    // override user preferences — see #884). The percentages are of the
+    // auto-compact threshold (#4985); the token counts, when the bridge has
+    // them, are the ones /context shows (#2451).
+    const kTokens = n => `${Math.round(n / 1000)}k`;
+    const tokenDetail = Number.isFinite(metrics.used_tokens) && Number.isFinite(metrics.threshold_tokens)
+      ? ` (${kTokens(metrics.used_tokens)} of ${kTokens(metrics.threshold_tokens)} usable tokens)`
+      : '';
+    const usage = `Usage at ${usedPct}%${tokenDetail}. Remaining: ${remaining}%. `;
     let message;
     if (isCritical) {
       message = isGsdActive
-        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        ? `CONTEXT CRITICAL: ${usage}` +
           'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
           'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
           '/gsd:pause-work at the next natural stopping point.'
-        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        : `CONTEXT CRITICAL: ${usage}` +
           'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
           'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';
     } else {
       message = isGsdActive
-        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        ? `CONTEXT WARNING: ${usage}` +
           'Context is getting limited. Avoid starting new complex work. If not between ' +
           'defined plan steps, inform the user so they can prepare to pause.'
-        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+        : `CONTEXT WARNING: ${usage}` +
           'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
           'starting new complex work.';
     }

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

@@ -435,7 +435,8 @@ function resolveFallbackIsolation(root, configPath) {
   }
   if (!runtimeId) {
     try {
-      const defaultsPath = path.join(os.homedir(), '.gsd', 'defaults.json');
+      // #5017: GSD_HOME when set and non-blank, else the home directory — the loader's rule.
+      const defaultsPath = path.join(process.env.GSD_HOME || os.homedir(), '.gsd', 'defaults.json');
       const defaultsParsed = JSON.parse(fs.readFileSync(defaultsPath, 'utf-8'));
       if (defaultsParsed && typeof defaultsParsed === 'object' && 'runtime' in defaultsParsed) {
         runtimeId = resolveRuntimeNameFromCandidates(defaultsParsed.runtime) || null;

package/hooks/gsd-secret-read-guard.js

@@ -67,6 +67,8 @@
 //   `git check-ignore` / `git ls-files` / `git rm --cached`, and the
 //   destination of a one-source `cp`/`mv` (#4856). The #4856 carve-outs
 //   fail closed: an option they do not list withdraws them from the segment.
+//   A git global option the walker does not know also keeps the #5045 `-c`
+//   scan running over every later word (see walkGitGlobals).
 //   A shell interpreter (bash/sh/zsh/dash/ksh/su) has its script scanned
 //   whether it arrives via `-c '…'`, a `<( )` file operand, a heredoc /
 //   here-string, or a pipe from a knowable `echo`/`printf` source
@@ -103,9 +105,23 @@
 //   edit of `.env` lands in the link target — a write redirection, the
 //   out-of-scope write class, not a read.)
 //
+// A second, unrelated contract is enforced on the Bash leg because this is the
+// one hook that already parses EVERY Bash command (#5214): a Bash command that
+// launches the debugger as a CLI process — `claude … --agent gsd-debugger` — is
+// denied (`debugger-cli-spawn`). The debug session manager is required to spawn
+// gsd-debugger with `Agent(run_in_background=false)` so it can read the
+// debugger's structured return; on a captured 1.15.0 run it routed around that
+// literal and shelled out with the Bash parameter `run_in_background: true`,
+// so no return ever came back and the checkpoint never advanced. Prose in the
+// agent file cannot stop an improvised tool call; a PreToolUse denial can, and
+// Claude Code runs plugin hooks for a subagent's tool calls too. A person
+// running `claude --agent gsd-debugger` in their own terminal never reaches
+// this hook. Only the debugger is named: it is the agent whose blocking return
+// the managed debug loop depends on.
+//
 // Triggers on: Read, Grep, Bash tool calls (Kimi: ReadFile, Grep, Shell)
 // Action: BLOCK (decision: 'block', exit 2) — codes secret-read |
-//         glob-too-complex | command-too-large
+//         glob-too-complex | command-too-large | debugger-cli-spawn
 // No-op: other tools, non-secret targets, hook errors (fail open — a parser
 //        bug in a hook that runs on EVERY Bash call must never brick a
 //        session; the crash policy is declared once below).
@@ -178,14 +194,29 @@ const GIT_PATHSPEC_SUBCOMMANDS = new Map([
   }],
 ]);
 
-// git's global options (its own usage line, git 2.49), needed to locate the
-// subcommand. A value option consumes the next word unless written
-// `--opt=value`; an option in neither set fails closed, so a value is never
-// read as the subcommand (`git -C ls-files show HEAD:.env` runs `show`).
-const GIT_GLOBAL_VALUE_OPTIONS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env']);
+// git's global options (git.c handle_options, git 2.49) — the ONE vocabulary
+// both the #4856 pathspec exemption and the #5045 -c scan walk, via
+// walkGitGlobals. A value option consumes the next word; the long options in
+// GIT_GLOBAL_EQUALS_FORM_OPTIONS also take it attached as `--opt=value`.
+// `-C`, `-c` and the hidden `--shallow-file` accept only the separate word
+// (git rejects `--shallow-file=x` and `-c<name>=<value>`), and
+// `--exec-path` runs a subcommand only as `--exec-path=<path>` (bare, it
+// prints the path and exits). Any other option fails closed for both
+// consumers: its arity is unknown, so its value could be read as the
+// subcommand (`git -C ls-files show HEAD:.env` runs `show`). The pathspec
+// exemption is withdrawn, and the -c scan keeps collecting every later
+// `-c <value>` pair instead of stopping.
+const GIT_GLOBAL_VALUE_OPTIONS = new Set([
+  '-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env', '--attr-source',
+  '--shallow-file',
+]);
+const GIT_GLOBAL_EQUALS_FORM_OPTIONS = new Set([
+  '--git-dir', '--work-tree', '--namespace', '--config-env', '--attr-source', '--exec-path',
+]);
 const GIT_GLOBAL_FLAGS = new Set([
   '-p', '--paginate', '-P', '--no-pager', '--no-replace-objects', '--no-lazy-fetch',
   '--no-optional-locks', '--no-advice', '--bare',
+  '--literal-pathspecs', '--glob-pathspecs', '--noglob-pathspecs', '--icase-pathspecs',
 ]);
 
 // #4856: `cp`/`mv` write their destination and never print it, so a secret
@@ -775,6 +806,29 @@ function resolveCommand(words) {
   return { base: lastSegment(words[idx].text).toLowerCase(), operands: words.slice(idx + 1) };
 }
 
+/**
+ * Rescan only the command-valued -c keys selected by #5045. This deliberately
+ * does not resolve config files, --config-env/GIT_CONFIG_* values, or other
+ * executing keys (diff drivers, filters, credential helpers, ssh, gpg).
+ * Those are documented gaps, not a promise of complete Git config analysis.
+ * Global option values and subcommand arguments are data, not more -c flags.
+ */
+function scanGitConfig(operands, depth) {
+  for (const config of walkGitGlobals(operands).configs) {
+    const eq = config.indexOf('=');
+    if (eq === -1) continue;
+    const key = config.slice(0, eq).toLowerCase();
+    const value = config.slice(eq + 1);
+    let script;
+    if (key.startsWith('alias.') && value.startsWith('!')) script = value.slice(1);
+    else if (key === 'diff.external') script = value;
+    else continue;
+    const hit = findSecretRead(script, depth + 1);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 // Operand indices the segment's command consumes as a NAME, never as
 // CONTENTS (#4639, #4856). Only these positions skip the operand check;
 // every other operand is still checked, so a carve-out cannot launder a read
@@ -806,26 +860,38 @@ function isListedFlag(text, flags) {
   return /^-[A-Za-z]+$/.test(text) && [...text.slice(1)].every((ch) => flags.has(`-${ch}`));
 }
 
-// Index of git's subcommand past its global options, or -1 when an option
-// outside GIT_GLOBAL_VALUE_OPTIONS / GIT_GLOBAL_FLAGS precedes it.
-function gitSubcommandIndex(operands) {
+// Walks git's global options (see GIT_GLOBAL_VALUE_OPTIONS). `sub` is the
+// subcommand's index, or -1 when an unlisted option (or the end of the words)
+// comes first; `configs` holds every `-c` value seen on the way, in order.
+// Past an unlisted option the subcommand cannot be located, so `configs`
+// conservatively takes the word after every later `-c` as well: a read
+// still needs a command-valued key, so a harmless value stays allowed.
+function walkGitGlobals(operands) {
+  const configs = [];
   for (let k = 0; k < operands.length; k++) {
     const t = operands[k].text;
-    if (!t.startsWith('-')) return k;
-    if (GIT_GLOBAL_VALUE_OPTIONS.has(t)) { k++; continue; }
+    if (!t.startsWith('-')) return { sub: k, configs };
+    if (GIT_GLOBAL_VALUE_OPTIONS.has(t)) {
+      if (t === '-c' && k + 1 < operands.length) configs.push(operands[k + 1].text);
+      k++;
+      continue;
+    }
     if (GIT_GLOBAL_FLAGS.has(t)) continue;
     const eq = t.indexOf('=');
-    const isLongValueForm = t.startsWith('--') && eq !== -1 && GIT_GLOBAL_VALUE_OPTIONS.has(t.slice(0, eq));
-    if (!isLongValueForm) return -1;
+    if (t.startsWith('--') && eq !== -1 && GIT_GLOBAL_EQUALS_FORM_OPTIONS.has(t.slice(0, eq))) continue;
+    for (let j = k + 1; j + 1 < operands.length; j++) {
+      if (operands[j].text === '-c') configs.push(operands[++j].text);
+    }
+    return { sub: -1, configs };
   }
-  return -1;
+  return { sub: -1, configs };
 }
 
 // #4856: the pathspec operands of a GIT_PATHSPEC_SUBCOMMANDS invocation. git
 // permutes options, so one may follow a pathspec; after `--` every word is a
 // pathspec. The subcommand is matched case-sensitively, as git looks it up.
 function gitPathspecIndices(operands) {
-  const sub = gitSubcommandIndex(operands);
+  const { sub } = walkGitGlobals(operands);
   const spec = sub === -1 ? undefined : GIT_PATHSPEC_SUBCOMMANDS.get(operands[sub].text);
   if (!spec) return new Set();
   const pathspecs = new Set();
@@ -993,6 +1059,12 @@ function findSecretRead(command, depth) {
       // `bash .env` (file mode) is caught by the operand check below.
     }
 
+    // Git -c can carry a shell script instead of a file-name operand (#5045).
+    if ((base === 'git' || base === 'git.exe') && depth < MAX_NESTING_DEPTH) {
+      const hit = scanGitConfig(operands, depth);
+      if (hit) return hit;
+    }
+
     if (NON_READING_COMMANDS.has(base)) continue;
 
     const nameOnly = nameOnlyOperandIndices(base, operands);
@@ -1004,6 +1076,100 @@ function findSecretRead(command, depth) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// gsd-debugger CLI spawn scan (#5214)
+// ---------------------------------------------------------------------------
+
+const DEBUGGER_AGENT_NAME = 'gsd-debugger';
+const CLAUDE_BINARY_RE = /^claude(\.exe)?$/;
+
+// `gsd-debugger`, or a plugin-namespaced `<plugin>:gsd-debugger`.
+function isDebuggerAgent(value) {
+  return value.slice(value.lastIndexOf(':') + 1) === DEBUGGER_AGENT_NAME;
+}
+
+// `timeout [flags] DURATION cmd …` is not in CMD_PREFIXES because its first
+// operand is a duration, not the command. Returns the command that follows it.
+function unwrapTimeout(cmd) {
+  let { base, operands } = cmd;
+  while (base === 'timeout') {
+    let k = 0;
+    while (k < operands.length && operands[k].text.startsWith('-')) k++;
+    k++; // the DURATION operand
+    const rest = resolveCommand(operands.slice(k));
+    if (!rest) return null;
+    ({ base, operands } = rest);
+  }
+  return { base, operands };
+}
+
+// Returns the `--agent` value text of a debugger launch, or null.
+function findDebuggerCliSpawn(command, depth) {
+  const { tokens, nested } = tokenize(command);
+
+  for (const sub of nested) {
+    if (depth < MAX_NESTING_DEPTH) {
+      const hit = findDebuggerCliSpawn(sub, depth + 1);
+      if (hit) return hit;
+    }
+  }
+
+  const bySeg = new Map();
+  for (const t of tokens) {
+    if (t.kind !== 'word' && t.kind !== 'op') continue;
+    if (!bySeg.has(t.seg)) bySeg.set(t.seg, []);
+    bySeg.get(t.seg).push(t);
+  }
+
+  for (const segTokens of bySeg.values()) {
+    const words = [];
+    for (let k = 0; k < segTokens.length; k++) {
+      const t = segTokens[k];
+      if (t.kind === 'op') {
+        // A redirect consumes its target word; it is never the command.
+        if (!t.dup && segTokens[k + 1] && segTokens[k + 1].kind === 'word') k++;
+        continue;
+      }
+      words.push(t);
+    }
+    if (!words.length) continue;
+
+    const first = resolveCommand(words);
+    const cmd = first && unwrapTimeout(first);
+    if (!cmd) continue;
+    const { base, operands } = cmd;
+
+    if (base === 'eval') {
+      if (depth < MAX_NESTING_DEPTH) {
+        const hit = findDebuggerCliSpawn(operands.map((w) => w.text).join(' '), depth + 1);
+        if (hit) return hit;
+      }
+      continue;
+    }
+
+    if (SHELL_INTERPRETERS.has(base)) {
+      const cIdx = operands.findIndex((w) => DASH_C_RE.test(w.text));
+      if (cIdx !== -1 && operands[cIdx + 1] && depth < MAX_NESTING_DEPTH) {
+        const hit = findDebuggerCliSpawn(operands[cIdx + 1].text, depth + 1);
+        if (hit) return hit;
+      }
+      continue;
+    }
+
+    if (!CLAUDE_BINARY_RE.test(base)) continue;
+    for (let k = 0; k < operands.length; k++) {
+      const text = operands[k].text;
+      if (text === '--agent') {
+        const value = operands[k + 1];
+        if (value && isDebuggerAgent(value.text)) return value.text;
+      } else if (text.startsWith('--agent=') && isDebuggerAgent(text.slice('--agent='.length))) {
+        return text.slice('--agent='.length);
+      }
+    }
+  }
+  return null;
+}
+
 // A shell interpreter's script comes from `-c`, a file operand, or stdin.
 function scanShellInterpreter(operands, heredocs, hereStrings, s, bySeg, sepAfter, depth) {
   const cIdx = operands.findIndex((w) => DASH_C_RE.test(w.text));
@@ -1102,6 +1268,12 @@ function reasonFor(code, tool, target) {
     return `Secret read guard: the Grep glob '${target}' expands to more than ${MAX_GLOB_ALTERNATIVES} ` +
       'alternatives and cannot be checked for secret-file matches. Use a narrower glob.';
   }
+  if (code === 'debugger-cli-spawn') {
+    return `Debugger spawn guard: this Bash command launches the debugger as a CLI process ('--agent ${target}'). ` +
+      'A shell-spawned debugger runs detached, returns no structured result, and the debug checkpoint never advances. ' +
+      'Spawn it with the Agent tool instead: Agent(subagent_type="gsd-debugger", run_in_background=false, ...) ' +
+      'and wait for its structured return.';
+  }
   return `Secret read guard: ${tool} would read '${target}', which matches a protected secret-file ` +
     `pattern (${PATTERN_TEXT}). Secret values must not be read into the conversation. ` +
     'If you need a specific value, ask the user for it; if you need the variable NAMES, ' +
@@ -1253,6 +1425,8 @@ process.stdin.on('end', () => {
     if (command.length > MAX_COMMAND_LENGTH) emitBlock('command-too-large', tool, '');
     const hit = findSecretRead(command, 0);
     if (hit !== null) emitBlock('secret-read', tool, hit);
+    const spawn = findDebuggerCliSpawn(command, 0);
+    if (spawn !== null) emitBlock('debugger-cli-spawn', tool, spawn);
     allow(undefined);
   } catch {
     // Fail open — never block valid tool calls due to hook errors.