@opengsd/gsd-core 1.15.0 → 1.17.0

package/hooks/gsd-check-update.js

@@ -3,6 +3,14 @@
 // Check for GSD updates in background, write result to cache
 // Called by SessionStart hook - runs once per session
 
+// #5183: Node's on-disk compile cache, so later runs reuse V8's compiled code
+// for unchanged modules. Only as the entry (a test require() is unaffected),
+// skipped under V8 coverage, optional (Bun stubs it), and never fatal.
+// NODE_DISABLE_COMPILE_CACHE (any value) turns it off.
+if (require.main === module && !process.env.NODE_V8_COVERAGE) {
+  try { require('node:module').enableCompileCache?.(); } catch { /* optimization only */ }
+}
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -59,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.
@@ -201,6 +203,29 @@ function writeSentinel(target, payload) {
   } catch (e) { /* best effort — see above */ }
 }
 
+// The calendar day the CRITICAL auto-record writes into STATE.md (#4905): the
+// operator's LOCAL day through the clock seam, which honors GSD_NOW_MS under
+// GSD_TEST_MODE, like every other date GSD stamps into planning files. The
+// clock is compiled into gsd-core/bin/lib/, so it is reached through the
+// self-healing build seam (#3582). If the library is missing and cannot
+// self-build, the host's local day stands in — still never the UTC day.
+function localDayStamp() {
+  try {
+    const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+    ensureRuntimeBuild();
+    return require('../gsd-core/bin/lib/clock.cjs').realClock.localToday();
+  } catch {
+    const now = new Date();
+    return [now.getFullYear(), String(now.getMonth() + 1).padStart(2, '0'), String(now.getDate()).padStart(2, '0')].join('-');
+  }
+}
+
+// The Stopped At breadcrumb for /gsd:resume-work (#1974). usedPct is coerced to
+// a safe number in case the bridge file is malformed.
+function criticalStoppedAt(usedPct) {
+  return `context exhaustion at ${Number(usedPct) || 0}% (${localDayStamp()})`;
+}
+
 let input = '';
 // Assigned by main(); the handler below clears it. Declared out here rather
 // than inside main() because the handler closes over it.
@@ -464,9 +489,7 @@ const handleStdinEnd = () => {
         // Using __dirname makes this work on Claude Code, OpenCode, Gemini,
         // Kilo, etc. without hardcoding ~/.claude/.
         const gsdTools = path.join(__dirname, '..', 'gsd-core', 'bin', 'gsd-tools.cjs');
-        // Coerce usedPct to a safe number in case bridge file is malformed
-        const safeUsedPct = Number(usedPct) || 0;
-        const stoppedAt = `context exhaustion at ${safeUsedPct}% (${new Date().toISOString().split('T')[0]})`;
+        const stoppedAt = criticalStoppedAt(usedPct);
         spawn(
           process.execPath,
           [gsdTools, 'state', 'record-session', '--stopped-at', stoppedAt],
@@ -479,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.';
     }
@@ -560,8 +590,10 @@ if (require.main === module) {
   main();
 }
 
-// Exported for the #4285 property test only. The two constants ride along so a
-// test asserts the fallback pair against the SOURCE of truth rather than
-// re-hardcoding 35/25 — a test carrying its own copy of the defaults would stay
-// green if the constants were edited.
-module.exports = { resolveThresholds, WARNING_THRESHOLD, CRITICAL_THRESHOLD };
+// Exported for tests only. resolveThresholds and the two constants serve the
+// #4285 property test; the constants ride along so a test asserts the fallback
+// pair against the SOURCE of truth rather than re-hardcoding 35/25 — a test
+// carrying its own copy of the defaults would stay green if the constants were
+// edited. criticalStoppedAt lets the #4905 test pin the breadcrumb's day
+// without waiting on the detached record-session writer (#3726).
+module.exports = { resolveThresholds, WARNING_THRESHOLD, CRITICAL_THRESHOLD, criticalStoppedAt };

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

@@ -53,6 +53,14 @@
 
 'use strict';
 
+// #5183: Node's on-disk compile cache, so later runs reuse V8's compiled code
+// for unchanged modules. Only as the entry (a test require() is unaffected),
+// skipped under V8 coverage, optional (Bun stubs it), and never fatal.
+// NODE_DISABLE_COMPILE_CACHE (any value) turns it off.
+if (require.main === module && !process.env.NODE_V8_COVERAGE) {
+  try { require('node:module').enableCompileCache?.(); } catch { /* optimization only */ }
+}
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');

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

@@ -61,7 +61,13 @@
 //   segment's operands — `[ -f .env ]` and `ls .env*` are existence checks
 //   GSD's own agents run — while `cp`/`mv`/`ln`/`git` are deliberately NOT
 //   exempt (`cp .env x && cat x` launders the name; `git show HEAD:.env`
-//   reads). A shell interpreter (bash/sh/zsh/dash/ksh/su) has its script scanned
+//   reads). Narrower carve-outs exempt single operand POSITIONS that are
+//   names, never contents, and keep checking the rest of the segment: the
+//   `--env-file` value under a container runtime (#4639), the pathspecs of
+//   `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 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
 //   (`echo cat .env | bash`); `eval` scans its joined operands; `source`/`.`
@@ -91,11 +97,29 @@
 //   container's own command can print the interpolated environment
 //   (`alpine printenv`, `docker compose config`) — the same exposure class
 //   as the pre-existing volume-mount gap (`-v .env:/s`); the flag's value
-//   itself is a name, never contents.)
+//   itself is a name, never contents. #4856 adds another: the `cp`/`mv`
+//   destination exemption can move a link prepared under a non-secret name
+//   onto a secret name (`ln -s .env.example l && mv l .env`), so a later
+//   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).
@@ -141,6 +165,57 @@ const NON_READING_COMMANDS = new Set([
 const CONTAINER_RUNTIMES = new Set(['docker', 'docker-compose', 'podman', 'nerdctl']);
 const ENV_FILE_FLAG_RE = /^--env-file(=|$)/;
 
+// #4856: git subcommands that report or drop a path's ignore / tracking
+// status and never print the file, so their pathspec operands are names —
+// the category NON_READING_COMMANDS encodes. Each carries the closed set of
+// its NO-VALUE options (from `git <subcommand> -h`, git 2.49). Any other
+// option withdraws the exemption from the whole segment, so an option value
+// is never mistaken for a pathspec: `-X <file>` reads the file, and
+// `--pathspec-from-file=<file>` echoes its lines in the "did not match"
+// error. `requires` names the option without which the subcommand stays
+// checked (#4856 scopes `git rm` to `--cached`).
+const GIT_PATHSPEC_SUBCOMMANDS = new Map([
+  ['check-ignore', {
+    flags: new Set(['-q', '--quiet', '-v', '--verbose', '--stdin', '-z', '-n', '--non-matching', '--no-index', '--index']),
+  }],
+  ['ls-files', {
+    flags: new Set([
+      '-z', '-t', '-v', '-f', '-c', '--cached', '-d', '--deleted', '-m', '--modified', '-o', '--others',
+      '-i', '--ignored', '-s', '--stage', '-k', '--killed', '-u', '--unmerged', '--directory', '--eol',
+      '--no-empty-directory', '--resolve-undo', '--exclude-standard', '--full-name',
+      '--recurse-submodules', '--error-unmatch', '--abbrev', '--debug', '--deduplicate', '--sparse',
+    ]),
+  }],
+  ['rm', {
+    flags: new Set(['--cached', '-f', '--force', '-n', '--dry-run', '-q', '--quiet', '-r', '--ignore-unmatch', '--sparse']),
+    requires: '--cached',
+  }],
+]);
+
+// 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']);
+const GIT_GLOBAL_FLAGS = new Set([
+  '-p', '--paginate', '-P', '--no-pager', '--no-replace-objects', '--no-lazy-fetch',
+  '--no-optional-locks', '--no-advice', '--bare',
+]);
+
+// #4856: `cp`/`mv` write their destination and never print it, so a secret
+// name that is ONLY the destination of a one-source copy or move is a name
+// (`cp .env.example .env`). The exemption holds for exactly two operands
+// behind options from this closed set; anything else keeps the whole segment
+// checked — `-t`/`--target-directory` (every operand becomes a source), a
+// backup (`-b`, `--backup`, `-S`: the old secret survives as `.env~`, a name
+// the predicate does not classify), a link (`-l`, `-s`) or `--exchange`
+// (the destination shares or swaps the secret). Options must precede the
+// operands: a trailing one is an option under GNU getopt's permutation but
+// an operand under POSIXLY_CORRECT (`cp a .env -f` then copies `.env` INTO
+// `-f/`), so which word is the destination would hang on an environment
+// the hook cannot see.
+const COPY_NAME_ONLY_FLAGS = new Set(['-f', '--force', '-i', '--interactive', '-n', '--no-clobber', '-v', '--verbose']);
+
 // Shell interpreters that run a script from `-c`, a file operand, or stdin
 // (heredoc / here-string / piped `echo`|`printf`). `su` is here for its `-c`
 // form (`su [user] -c 'cmd'`); a bare `su user` resolves to file mode, which
@@ -714,6 +789,86 @@ function resolveCommand(words) {
   return { base: lastSegment(words[idx].text).toLowerCase(), operands: words.slice(idx + 1) };
 }
 
+// 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
+// elsewhere in the segment.
+function nameOnlyOperandIndices(base, operands) {
+  if (CONTAINER_RUNTIMES.has(base)) return envFileValueIndices(operands);
+  if (base === 'git') return gitPathspecIndices(operands);
+  if (base === 'cp' || base === 'mv') return copyDestinationIndices(operands);
+  return new Set();
+}
+
+// #4639: the `--env-file` word, plus the next operand for the bare flag
+// (`--env-file=<value>` is a single word).
+function envFileValueIndices(operands) {
+  const exempt = new Set();
+  for (let k = 0; k < operands.length; k++) {
+    if (!ENV_FILE_FLAG_RE.test(operands[k].text)) continue;
+    exempt.add(k);
+    if (!operands[k].text.includes('=')) exempt.add(++k);
+  }
+  return exempt;
+}
+
+// True when `text` is a listed long option, or a short cluster (`-co`) whose
+// every letter is listed. `--opt=value`, an abbreviation, or a cluster
+// holding a value option (`-ciX`) is not.
+function isListedFlag(text, flags) {
+  if (text.startsWith('--')) return flags.has(text);
+  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) {
+  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 (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;
+  }
+  return -1;
+}
+
+// #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 spec = sub === -1 ? undefined : GIT_PATHSPEC_SUBCOMMANDS.get(operands[sub].text);
+  if (!spec) return new Set();
+  const pathspecs = new Set();
+  let required = spec.requires === undefined;
+  let endOfOptions = false;
+  for (let k = sub + 1; k < operands.length; k++) {
+    const t = operands[k].text;
+    if (endOfOptions || !t.startsWith('-') || t === '-') pathspecs.add(k);
+    else if (t === '--') endOfOptions = true;
+    else if (!isListedFlag(t, spec.flags)) return new Set();
+    else if (t === spec.requires) required = true;
+  }
+  return required ? pathspecs : new Set();
+}
+
+// #4856: the destination of a one-source `cp`/`mv` (see COPY_NAME_ONLY_FLAGS).
+function copyDestinationIndices(operands) {
+  const positional = [];
+  let endOfOptions = false;
+  for (let k = 0; k < operands.length; k++) {
+    const t = operands[k].text;
+    if (endOfOptions || !t.startsWith('-') || t === '-') positional.push(k);
+    else if (positional.length) return new Set(); // an option or `--` after an operand
+    else if (t === '--') endOfOptions = true;
+    else if (!isListedFlag(t, COPY_NAME_ONLY_FLAGS)) return new Set();
+  }
+  return positional.length === 2 ? new Set([positional[1]]) : new Set();
+}
+
 // The statically-knowable stdin a segment writes: `echo`/`printf` operands
 // joined by a space (for `echo`, leading `-neE` flags dropped). Any other
 // source (`cat gen.sh | bash`, `curl … | sh`) is not knowable → null.
@@ -854,20 +1009,104 @@ function findSecretRead(command, depth) {
 
     if (NON_READING_COMMANDS.has(base)) continue;
 
-    // #4639: exempt ONLY the value of `--env-file`, and only when the
-    // segment's command word is a container runtime. A bare `--env-file`
-    // consumes the next operand; `--env-file=<value>` is a single word.
-    const envFileExempt = CONTAINER_RUNTIMES.has(base);
-    let skipNext = false;
-    for (const w of operands) {
-      if (envFileExempt) {
-        if (skipNext) { skipNext = false; continue; }
-        if (ENV_FILE_FLAG_RE.test(w.text)) {
-          if (!w.text.includes('=')) skipNext = true; // bare flag consumes the next operand
-          continue;
-        }
+    const nameOnly = nameOnlyOperandIndices(base, operands);
+    for (let k = 0; k < operands.length; k++) {
+      if (nameOnly.has(k)) continue;
+      if (namesSecret(normalizeOperand(operands[k].text))) return operands[k].text;
+    }
+  }
+  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);
       }
-      if (namesSecret(normalizeOperand(w.text))) return w.text;
     }
   }
   return null;
@@ -971,6 +1210,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, ' +
@@ -1122,6 +1367,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.