@opengsd/gsd-core 1.16.0 → 1.17.0

package/hooks/dist/gsd-statusline.js

@@ -170,6 +170,303 @@ function readStateFileOrNull(statePath) {
   }
 }
 
+/**
+ * The env vars Claude Code itself consults to switch auto-compaction off, and
+ * the values it accepts as true. Both are taken from the shipped binary's own
+ * resolution — `Boolean(truthy(DISABLE_COMPACT) || DISABLE_AUTO_COMPACT)`, and
+ * only when that is false does `autoCompactEnabled` decide — rather than
+ * guessed: an invented name reads as "not disabled" forever, which is exactly
+ * the defect this gate exists to close.
+ *
+ * The truthy set applies to both keys: in the binary (claude 2.1.292) the
+ * second operand is the env registry's `D.bool()` field, which runs the same
+ * `["1","true","yes","on"]` helper as `DISABLE_COMPACT`.
+ */
+const AUTO_COMPACT_DISABLE_ENV_KEYS = ['DISABLE_AUTO_COMPACT', 'DISABLE_COMPACT'];
+const AUTO_COMPACT_ENV_TRUTHY = ['1', 'true', 'yes', 'on'];
+
+/**
+ * Is Claude Code's auto-compact switched off for this session? When it is,
+ * the auto-compact buffer is ordinary usable context, so the meter's 100% is
+ * the model window — otherwise the bar pins at 100% early and the last of
+ * the window is invisible.
+ *
+ * The sources and their precedence mirror Claude Code's own resolution —
+ * either env var wins over the setting, and only then does the setting decide:
+ *   1. env: DISABLE_AUTO_COMPACT, or DISABLE_COMPACT (which switches off
+ *      manual `/compact` as well). Truthy is `1` / `true` / `yes` / `on`,
+ *      trimmed and case-insensitive — Claude Code's own accepted set.
+ *   2. <dir>/.claude/settings.local.json, <dir>/.claude/settings.json
+ *   3. (CLAUDE_CONFIG_DIR || ~/.claude)/settings.local.json, settings.json
+ * reading the boolean `autoCompactEnabled`. Fail-soft: anything unreadable
+ * or absent means "not disabled" (current behaviour).
+ */
+function isAutoCompactDisabled(dir, env = process.env) {
+  for (const key of AUTO_COMPACT_DISABLE_ENV_KEYS) {
+    const v = env[key];
+    if (typeof v === 'string' && AUTO_COMPACT_ENV_TRUTHY.includes(v.trim().toLowerCase())) return true;
+  }
+  return readClaudeSetting(dir, env, 'autoCompactEnabled', v => typeof v === 'boolean') === false;
+}
+
+/**
+ * The first value of `key` that `accept` takes, reading the Claude Code
+ * settings files highest precedence first:
+ *   <dir>/.claude/settings.local.json, <dir>/.claude/settings.json,
+ *   (CLAUDE_CONFIG_DIR || ~/.claude)/settings.local.json, settings.json.
+ * Fail-soft: an absent or unparseable file is skipped; nothing found is
+ * `undefined`.
+ */
+function readClaudeSetting(dir, env, key, accept) {
+  // Lazy: stop at the first file that answers, so a lower file is never read.
+  for (const file of claudeSettingsPaths(dir, env)) {
+    const settings = readSettingsFile(file);
+    if (settings && accept(settings[key])) return settings[key];
+  }
+  return undefined;
+}
+
+/**
+ * The parsed Claude Code settings files, highest precedence first. An absent,
+ * unparseable or non-object file is left out.
+ */
+function readClaudeSettingsFiles(dir, env) {
+  return claudeSettingsPaths(dir, env).map(readSettingsFile).filter(Boolean);
+}
+
+/**
+ * A settings file larger than this is treated as absent. Claude Code's own
+ * settings files are a few kilobytes; the cap keeps a hostile project's
+ * `.claude/settings.json` from bloating a read that runs on every render.
+ */
+const SETTINGS_FILE_MAX_BYTES = 1024 * 1024;
+
+/**
+ * The parsed settings object in `file`, or null. Only a regular file of at
+ * most SETTINGS_FILE_MAX_BYTES is read: the project's `.claude/` is
+ * repository content, and a FIFO there would block the statusline forever.
+ * The file is opened non-blocking and checked through its own descriptor,
+ * so the check and the read see the same file, and at most the checked size
+ * is read: a file that grew or shrank after the check is absent. A symlink
+ * is followed — a settings file linked in from a dotfiles repo is ordinary.
+ */
+function readSettingsFile(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0));
+    const st = fs.fstatSync(fd);
+    if (!st.isFile() || st.size > SETTINGS_FILE_MAX_BYTES) return null;
+    // One byte past the checked size, so growth after the check shows as a longer read.
+    const buf = Buffer.alloc(st.size + 1);
+    let n = 0;
+    for (let r; n < buf.length && (r = fs.readSync(fd, buf, n, buf.length - n, n)) > 0;) n += r;
+    if (n !== st.size) return null;
+    const settings = JSON.parse(buf.toString('utf8', 0, n));
+    return settings && typeof settings === 'object' && !Array.isArray(settings) ? settings : null;
+  } catch (e) {
+    return null; // absent, unreadable or unparseable — keep looking
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (e) { /* already closed */ }
+    }
+  }
+}
+
+/**
+ * The Claude Code settings file paths, highest precedence first:
+ *   <dir>/.claude/settings.local.json, <dir>/.claude/settings.json,
+ *   (CLAUDE_CONFIG_DIR || ~/.claude)/settings.local.json, settings.json.
+ */
+function claudeSettingsPaths(dir, env) {
+  const candidates = [];
+  if (dir) {
+    candidates.push(path.join(dir, '.claude', 'settings.local.json'));
+    candidates.push(path.join(dir, '.claude', 'settings.json'));
+  }
+  let claudeDir;
+  try {
+    claudeDir = env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  } catch (e) {
+    claudeDir = null;
+  }
+  if (claudeDir) {
+    candidates.push(path.join(claudeDir, 'settings.local.json'));
+    candidates.push(path.join(claudeDir, 'settings.json'));
+  }
+  return candidates;
+}
+
+/**
+ * Claude Code's settings key for a model: its canonical name, which also
+ * matches the dated, `[1m]`, Bedrock and Vertex spellings of it
+ * (`claude-opus-5-5[1m]`, `us.anthropic.claude-opus-5-5-v1:0` and
+ * `claude-opus-5-5@20260101` all key as `claude-opus-5-5`). A Bedrock
+ * revision suffix is stripped only after a version or date segment, so a
+ * model whose own name ends in `-v<n>` (`anthropic.claude-v2`) keeps it.
+ * The rules repeat until nothing changes, so a key is its own key: one pass
+ * left `x[1m][1m]` as `x[1m]`. Lowercasing runs once, before the loop (it
+ * can lengthen a string: `İ` becomes two characters); inside the loop every
+ * rule only removes characters, so it ends. A key longer than
+ * MODEL_KEY_MAX_LENGTH is no model's — '' — which also bounds the loop's
+ * work on a hostile settings file. '' for a non-string.
+ */
+const MODEL_KEY_MAX_LENGTH = 256;
+
+function canonicalModelKey(id) {
+  if (typeof id !== 'string') return '';
+  let key = id.toLowerCase();
+  if (key.length > MODEL_KEY_MAX_LENGTH) return '';
+  for (let prev; prev !== key;) {
+    prev = key;
+    key = key.trim()
+      .replace(/(?:\[1m\])+$/, '')
+      .replace(/^(?:[a-z]+\.)?anthropic\./, '')
+      .replace(/(\d)-v\d+(?::\d+)?$/, '$1')
+      .replace(/@\d{8}$/, '')
+      .replace(/-\d{8}$/, '');
+  }
+  return key;
+}
+
+function isAutoCompactWindowValue(v) {
+  return v === 'auto' ||
+    (Number.isInteger(v) && v >= AUTO_COMPACT_WINDOW_MIN && v <= AUTO_COMPACT_WINDOW_MAX);
+}
+
+/**
+ * The `autoCompactWindow` setting for this model, merged across the settings
+ * files the way Claude Code merges it (claude 2.1.292): lowest precedence
+ * first, each file's `modelSettings.<model>.autoCompactWindow` entries
+ * layer over the lower files', and a file that sets a top-level
+ * `autoCompactWindow` replaces the default and drops the lower files'
+ * per-model entries. The model's own entry wins over the default.
+ * `/autocompact` saves the per-model entry; older versions saved the
+ * top-level one. `"auto"` (Claude Code's tuned window) and an absent setting
+ * are null, so the caller falls back to the model window. An invalid value
+ * is treated as absent.
+ */
+function readAutoCompactWindowSetting(dir, env, modelId) {
+  let fallback;
+  let byModel = {};
+  for (const settings of readClaudeSettingsFiles(dir, env).reverse()) {
+    const own = {};
+    const perModel = settings.modelSettings;
+    if (perModel && typeof perModel === 'object' && !Array.isArray(perModel)) {
+      for (const [name, entry] of Object.entries(perModel)) {
+        const v = entry && typeof entry === 'object' ? entry.autoCompactWindow : undefined;
+        if (!isAutoCompactWindowValue(v)) continue;
+        const key = canonicalModelKey(name);
+        // A canonically spelled key wins over another spelling of it.
+        if (name === key || !Object.hasOwn(own, key)) own[key] = v;
+      }
+    }
+    if (isAutoCompactWindowValue(settings.autoCompactWindow)) {
+      fallback = settings.autoCompactWindow;
+      byModel = own;
+    } else {
+      byModel = { ...byModel, ...own };
+    }
+  }
+  const key = canonicalModelKey(modelId);
+  const value = key && Object.hasOwn(byModel, key) ? byModel[key] : fallback;
+  return Number.isInteger(value) ? value : null;
+}
+
+/**
+ * Where Claude Code auto-compacts (#4985). The meter's 100% is this token
+ * count, so it has to be resolved the way Claude Code resolves it:
+ *
+ *   window     CLAUDE_CODE_AUTO_COMPACT_WINDOW (an unparseable or non-positive
+ *              value is ignored; capped at 1M, raised to 100k), else the
+ *              `autoCompactWindow` setting `/autocompact` saves, per model or
+ *              top-level (an integer in 100k–1M; see
+ *              readAutoCompactWindowSetting), else the model window. Always
+ *              capped at the model window.
+ *   threshold  window − min(model max output, 20,000) − 13,000, lowered to
+ *              floor((window − 20,000) × pct / 100) when
+ *              CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (0 < pct ≤ 100) is lower.
+ *
+ * `/context` shows the 33,000 as "Autocompact buffer". The hardcoded 16.5%
+ * this replaces is 33,000 / 200,000, so it was right only on a 200K window
+ * with nothing configured. Every current model's max output is at least
+ * 20,000, so the reserve is taken as 20,000.
+ *
+ * Not visible to a statusline, so not modelled: the `--autocompact` launch
+ * flag, managed-policy settings, and Claude Code's server-side and per-model
+ * window defaults (what `"auto"` resolves to). Those sessions fall back to
+ * the model window.
+ */
+const AUTO_COMPACT_WINDOW_MIN = 100_000;
+const AUTO_COMPACT_WINDOW_MAX = 1_000_000;
+const AUTO_COMPACT_OUTPUT_RESERVE = 20_000;
+const AUTO_COMPACT_SUMMARY_BUFFER = 13_000;
+
+function parseAutoCompactWindowEnv(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') return null;
+  const s = raw.trim();
+  const n = /^\d[\d_,]*$/.test(s) ? parseInt(s.replace(/[_,]/g, ''), 10) : parseInt(s, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return Math.max(AUTO_COMPACT_WINDOW_MIN, Math.min(AUTO_COMPACT_WINDOW_MAX, n));
+}
+
+/**
+ * The token count at which Claude Code auto-compacts this session, or null
+ * when auto-compaction is off (see isAutoCompactDisabled).
+ */
+function resolveAutoCompactThreshold(modelWindow, dir, env = process.env, modelId) {
+  if (!(modelWindow > 0) || isAutoCompactDisabled(dir, env)) return null;
+  let window = parseAutoCompactWindowEnv(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW);
+  if (window === null) {
+    window = readAutoCompactWindowSetting(dir, env, modelId) ?? modelWindow;
+  }
+  const effective = Math.min(window, modelWindow) - AUTO_COMPACT_OUTPUT_RESERVE;
+  let threshold = effective - AUTO_COMPACT_SUMMARY_BUFFER;
+  const pct = parseFloat(env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE);
+  if (Number.isFinite(pct) && pct > 0 && pct <= 100) {
+    threshold = Math.min(threshold, Math.floor(effective * (pct / 100)));
+  }
+  return threshold > 0 ? threshold : null;
+}
+
+/**
+ * The context meter, in one scale: `used` + `remaining` = 100, where 100% is
+ * the auto-compact threshold, or the model window when compaction is off.
+ * `usedTokens` is Claude Code's own count (input + cache creation + cache
+ * read of the last turn, the sum /context reports) and `limitTokens` the
+ * token count 100% stands for.
+ *
+ * Taken from token counts, not by re-scaling `remaining_percentage`: that
+ * value is already rounded against the model window, which loses up to 5,000
+ * tokens on a 1M model. Without `current_usage` the tokens are recovered
+ * from the percentage; without `context_window_size` the window is unknown,
+ * so the meter shows Claude Code's own percentage unscaled. Returns null
+ * when there is no usage yet.
+ */
+function contextMeter(contextWindow, dir, env = process.env, modelId) {
+  if (!contextWindow || typeof contextWindow !== 'object') return null;
+  const size = Number(contextWindow.context_window_size);
+  const usage = contextWindow.current_usage;
+  const remainingPct = contextWindow.remaining_percentage;
+  if (size > 0) {
+    let usedTokens = null;
+    if (usage && typeof usage === 'object') {
+      usedTokens = (Number(usage.input_tokens) || 0) +
+        (Number(usage.cache_creation_input_tokens) || 0) +
+        (Number(usage.cache_read_input_tokens) || 0);
+    } else if (remainingPct != null) {
+      usedTokens = Math.round(((100 - remainingPct) * size) / 100);
+    }
+    if (usedTokens !== null) {
+      const limitTokens = resolveAutoCompactThreshold(size, dir, env, modelId) ?? size;
+      const used = Math.max(0, Math.min(100, Math.round((usedTokens / limitTokens) * 100)));
+      return { used, remaining: 100 - used, usedTokens, limitTokens };
+    }
+  }
+  if (remainingPct == null) return null;
+  const used = Math.max(0, Math.min(100, Math.round(100 - remainingPct)));
+  return { used, remaining: 100 - used, usedTokens: null, limitTokens: null };
+}
+
 /**
  * Walk up from dir looking for .planning/STATE.md (flat mode). If an ancestor
  * has no flat STATE.md but IS in workstream mode (.planning/workstreams/
@@ -830,28 +1127,22 @@ function runStatusline() {
     const model = compactModelName(data.model?.display_name || 'Claude');
     const dir = data.workspace?.current_dir || process.cwd();
     const session = data.session_id || '';
-    const remaining = data.context_window?.remaining_percentage;
 
     // Read .planning config once — used by the context meter (token suffix)
     // and the last-command/position block below. Fail-soft to {}.
     let cfg = {};
     try { cfg = readGsdConfig(dir); } catch (e) {}
 
-    // Context window display (shows USED percentage scaled to usable context)
-    // Claude Code reserves a buffer for autocompact. By default this is ~16.5%
-    // of the total window, but users can override it via CLAUDE_CODE_AUTO_COMPACT_WINDOW
-    // (a token count). When the env var is set, compute the buffer % dynamically so
-    // the meter correctly reflects early-compaction configurations (#2219).
-    const totalCtx = data.context_window?.total_tokens || 1_000_000;
-    const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
-    const AUTO_COMPACT_BUFFER_PCT = acw > 0
-      ? Math.min(100, Math.max(0, (1 - acw / totalCtx) * 100))
-      : 16.5;
+    // Context window display: USED percentage of the auto-compact threshold,
+    // so 100% is where Claude Code compacts — resolved from
+    // CLAUDE_CODE_AUTO_COMPACT_WINDOW, the `autoCompactWindow` setting, or the
+    // model window (#2219, #4985). With auto-compact disabled (#4844) 100% is
+    // the model window. Project settings are read from workspace.project_dir,
+    // Claude Code's launch directory, not the current directory.
+    const meter = contextMeter(data.context_window, data.workspace?.project_dir || dir, process.env, data.model?.id);
     let ctx = '';
-    if (remaining != null) {
-      // Normalize: subtract buffer from remaining, scale to usable range
-      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
-      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+    if (meter) {
+      const { used } = meter;
 
       // Write context metrics to bridge file for the context-monitor PostToolUse hook.
       // The monitor reads this file to inject agent-facing warnings when context is low.
@@ -861,15 +1152,20 @@ function runStatusline() {
       if (sessionSafe) {
         try {
           const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
-          // used_pct written to the bridge must match CC's native /context reporting:
-          // raw used = 100 - remaining_percentage (no buffer normalization applied).
-          // The normalized `used` value is correct for the statusline progress bar but
-          // inflates the context monitor warning messages by ~13 points (#2451).
-          const rawUsedPct = Math.round(100 - remaining);
+          // The bridge is on the bar's scale: remaining_percentage counts down
+          // to the auto-compact threshold, so the monitor's WARNING/CRITICAL
+          // fire before compaction rather than after it (#4985). The token
+          // counts let its message match /context, which is what #2451 kept
+          // the bridge raw for; they are absent when the payload has no
+          // context_window_size.
           const bridgeData = JSON.stringify({
             session_id: session,
-            remaining_percentage: remaining,
-            used_pct: rawUsedPct,
+            remaining_percentage: meter.remaining,
+            used_pct: used,
+            ...(meter.usedTokens !== null && {
+              used_tokens: meter.usedTokens,
+              threshold_tokens: meter.limitTokens,
+            }),
             timestamp: Math.floor(Date.now() / 1000)
           });
           fs.writeFileSync(bridgePath, bridgeData);
@@ -1097,6 +1393,9 @@ module.exports = {
   readStateHeadCommits, parseRevListCounts, deriveStateFreshness,
   formatStateFreshness, resolveStatuslineOptions,
   renderBracketPhaseDisplay, renderBracketMilestoneDisplay,
+  isAutoCompactDisabled, AUTO_COMPACT_DISABLE_ENV_KEYS, AUTO_COMPACT_ENV_TRUTHY,
+  resolveAutoCompactThreshold, contextMeter, SETTINGS_FILE_MAX_BYTES,
+  parseAutoCompactWindowEnv, canonicalModelKey, isAutoCompactWindowValue,
 };
 
 /**

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-secret-read-guard.js

@@ -103,9 +103,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).
@@ -1004,6 +1018,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 +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, ' +
@@ -1253,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.