@therocketcode/gsd-core 1.4.0

package/hooks/dist/lib/gsd-graphify-rebuild.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# gsd-graphify-rebuild.sh — detached rebuild runner for hooks/gsd-graphify-update.sh.
+#
+# Usage:
+#   gsd-graphify-rebuild.sh <STATUS_FILE> <LOCK_FILE> <HEAD_SHA> <MS_START> <GRAPHIFY_BIN>
+#
+# Writes its own PID into LOCK_FILE on start, removes LOCK_FILE on exit (any cause),
+# runs `graphify update .` from the project root (cwd inherited from caller), copies
+# the produced graphify-out/* into .planning/graphs/, and rewrites STATUS_FILE to
+# reflect the final status ("ok" if graphify exited 0, "failed" otherwise).
+#
+# Designed to be invoked via `setsid ... &` so it is reparented away from the hook
+# caller and never blocks the user-facing tool call.
+
+set -uo pipefail
+
+STATUS_FILE="${1:?STATUS_FILE required}"
+LOCK_FILE="${2:?LOCK_FILE required}"
+HEAD_SHA="${3:?HEAD_SHA required}"
+MS_START="${4:?MS_START required}"
+GRAPHIFY_BIN="${5:?GRAPHIFY_BIN required}"
+
+# Atomic-ish lock acquire: write our PID and trap cleanup
+echo "$$" > "$LOCK_FILE"
+trap 'rm -f "$LOCK_FILE"' EXIT
+
+"$GRAPHIFY_BIN" update . >/dev/null 2>&1
+EXIT_CODE=$?
+
+# Copy outputs only on success — failure path preserves the prior valid graph.
+if [ "$EXIT_CODE" -eq 0 ] && [ -f graphify-out/graph.json ]; then
+  cp graphify-out/graph.json .planning/graphs/graph.json
+  cp graphify-out/graph.html .planning/graphs/graph.html 2>/dev/null || true
+  cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md 2>/dev/null || true
+  cp .planning/graphs/graph.json .planning/graphs/.last-build-snapshot.json 2>/dev/null || true
+fi
+
+# Compute duration in ms
+MS_END=$(node -e 'process.stdout.write(String(Date.now()))' 2>/dev/null || echo "$MS_START")
+DURATION=$((MS_END - MS_START))
+
+STATUS_NAME="ok"
+[ "$EXIT_CODE" -eq 0 ] || STATUS_NAME="failed"
+
+TS_END=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+
+# Write the final status file. Use Node for safe JSON encoding.
+GSD_STATUS_TS="$TS_END" \
+GSD_STATUS_NAME="$STATUS_NAME" \
+GSD_EXIT_CODE="$EXIT_CODE" \
+GSD_DURATION="$DURATION" \
+GSD_HEAD_SHA="$HEAD_SHA" \
+GSD_STATUS_FILE="$STATUS_FILE" \
+node -e '
+  const fs = require("node:fs");
+  const status = {
+    ts: process.env.GSD_STATUS_TS,
+    status: process.env.GSD_STATUS_NAME,
+    exit_code: parseInt(process.env.GSD_EXIT_CODE, 10),
+    duration_ms: parseInt(process.env.GSD_DURATION, 10),
+    head_at_build: process.env.GSD_HEAD_SHA,
+    graphify_version: null,
+  };
+  fs.writeFileSync(process.env.GSD_STATUS_FILE, JSON.stringify(status, null, 2) + "\n");
+' 2>/dev/null || true

package/hooks/dist/managed-hooks-registry.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * Authoritative list of GSD-managed hook files.
+ *
+ * Extracted from the worker script into a shared CJS module so that:
+ *  1. gsd-check-update-worker.js can require() it directly (no source-level
+ *     duplication).
+ *  2. Tests can assert against the exported array instead of regex-parsing
+ *     the worker source (retiring the pending-migration-to-typed-ir token
+ *     on managed-hooks.test.cjs and orphaned-hooks.test.cjs, per #455).
+ *
+ * These are the files GSD ships into ~/.claude/hooks/ (or equivalent) and
+ * checks for staleness after an update. Orphaned files from removed features
+ * (e.g., gsd-intel-*.js) must NOT be listed here — that would cause permanent
+ * stale warnings for users who haven't cleaned up manually (#1750).
+ */
+const MANAGED_HOOKS = [
+  'gsd-check-update-worker.js',
+  'gsd-check-update.js',
+  'gsd-config-reload.js',
+  'gsd-context-monitor.js',
+  'gsd-cursor-post-tool.js',
+  'gsd-cursor-session-start.js',
+  'gsd-graphify-update.sh',
+  'gsd-phase-boundary.sh',
+  'gsd-prompt-guard.js',
+  'gsd-read-guard.js',
+  'gsd-read-injection-scanner.js',
+  'gsd-session-state.sh',
+  'gsd-statusline.js',
+  'gsd-update-banner.js',
+  'gsd-validate-commit.sh',
+  'gsd-workflow-guard.js',
+  'gsd-worktree-path-guard.js',
+];
+
+module.exports = { MANAGED_HOOKS };

package/hooks/gsd-check-update-worker.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// Background worker spawned by gsd-check-update.js (SessionStart hook).
+// Checks for GSD updates and stale hooks, writes result to cache file.
+// Receives paths via environment variables set by the parent hook.
+//
+// Using a separate file (rather than node -e '<inline code>') avoids the
+// template-literal regex-escaping problem: regex source is plain JS here.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
+// Latest-version lookup is delegated to the single deterministic adapter
+// (#498). checkLatestVersion() owns the npm-view call, the timeout/semver
+// policy, and the package name — sourced from the baked Package Identity seam.
+// The previous `require('../package.json').name` (#378) resolved to undefined
+// in the installed tree (only a {"type":"commonjs"} marker ships), so the
+// background check never reported updates.
+const { checkLatestVersion } = require('../gsd-core/bin/check-latest-version.cjs');
+const { PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs');
+// Authoritative list of managed hooks — shared with tests to retire source-grep
+// assertions (pending-migration-to-typed-ir [#455]).
+// NOTE: managed-hooks-registry.cjs must be in HOOKS_TO_COPY (scripts/build-hooks.js)
+// so it is present in hooks/dist/ and ships to the installed runtime hooks/ dir.
+// If it is missing (e.g., installed from an older dist), catch and degrade gracefully
+// so the worker always proceeds to compute and write the result cache record.
+let MANAGED_HOOKS = [];
+try {
+  ({ MANAGED_HOOKS } = require('./managed-hooks-registry.cjs'));
+} catch (e) {
+  // Module not found in installed runtime — stale-hook detection degrades to
+  // no-op (empty list means no hooks are checked for staleness). The worker
+  // still runs and writes package_name / installed / latest / update_available.
+}
+
+const cacheFile = process.env.GSD_CACHE_FILE;
+const projectVersionFile = process.env.GSD_PROJECT_VERSION_FILE;
+const globalVersionFile = process.env.GSD_GLOBAL_VERSION_FILE;
+
+// Check project directory first (local install), then global
+let installed = '0.0.0';
+let configDir = '';
+try {
+  if (fs.existsSync(projectVersionFile)) {
+    installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+    configDir = path.dirname(path.dirname(projectVersionFile));
+  } else if (fs.existsSync(globalVersionFile)) {
+    installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    configDir = path.dirname(path.dirname(globalVersionFile));
+  }
+} catch (e) {}
+
+// Check for stale hooks — compare hook version headers against installed VERSION
+// Hooks are installed at configDir/hooks/ (e.g. ~/.claude/hooks/) (#1421)
+// Only check hooks that GSD currently ships — orphaned files from removed features
+// (e.g., gsd-intel-*.js) must be ignored to avoid permanent stale warnings (#1750)
+// MANAGED_HOOKS is imported from ./managed-hooks-registry.cjs above.
+
+let staleHooks = [];
+if (configDir) {
+  const hooksDir = path.join(configDir, 'hooks');
+  try {
+    if (fs.existsSync(hooksDir)) {
+      const hookFiles = fs.readdirSync(hooksDir).filter(f => MANAGED_HOOKS.includes(f));
+      for (const hookFile of hookFiles) {
+        try {
+          const content = fs.readFileSync(path.join(hooksDir, hookFile), 'utf8');
+          // Match both JS (//) and bash (#) comment styles
+          const versionMatch = content.match(/(?:\/\/|#) gsd-hook-version:\s*(.+)/);
+          if (versionMatch) {
+            const hookVersion = versionMatch[1].trim();
+            if (isSemverNewer(installed, hookVersion) && !hookVersion.includes('{{')) {
+              staleHooks.push({ file: hookFile, hookVersion, installedVersion: installed });
+            }
+          } else {
+            // No version header at all — definitely stale (pre-version-tracking)
+            staleHooks.push({ file: hookFile, hookVersion: 'unknown', installedVersion: installed });
+          }
+        } catch (e) {}
+      }
+    }
+  } catch (e) {}
+}
+
+// Single adapter for the registry lookup (#498). checkLatestVersion() routes
+// through the shell-projection seam, which already owns the Windows shell-flag
+// policy, the timeout, and semver validation. A non-ok result leaves latest
+// null, exactly as the previous inline try/catch did.
+let latest = null;
+try {
+  const lv = checkLatestVersion();
+  if (lv && lv.ok) latest = lv.version;
+} catch (e) {}
+
+const result = {
+  update_available: latest && isSemverNewer(latest, installed),
+  installed,
+  latest: latest || 'unknown',
+  checked: Math.floor(Date.now() / 1000),
+  stale_hooks: staleHooks.length > 0 ? staleHooks : undefined,
+  package_name: PACKAGE_NAME,
+};
+
+if (cacheFile) {
+  try { fs.writeFileSync(cacheFile, JSON.stringify(result)); } catch (e) {}
+}

package/hooks/gsd-check-update.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// Check for GSD updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const { updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+
+// Detect runtime config directory (supports Claude, OpenCode, Kilo, Gemini)
+// Respects CLAUDE_CONFIG_DIR for custom config directory setups
+function detectConfigDir(baseDir) {
+  // Check env override first (supports multi-account setups)
+  const envDir = process.env.CLAUDE_CONFIG_DIR;
+  if (envDir && fs.existsSync(path.join(envDir, 'gsd-core', 'VERSION'))) {
+    return envDir;
+  }
+  for (const dir of ['.claude', '.gemini', '.config/kilo', '.kilo', '.config/opencode', '.opencode']) {
+    if (fs.existsSync(path.join(baseDir, dir, 'gsd-core', 'VERSION'))) {
+      return path.join(baseDir, dir);
+    }
+  }
+  return envDir || path.join(baseDir, '.claude');
+}
+
+const globalConfigDir = detectConfigDir(homeDir);
+const projectConfigDir = detectConfigDir(cwd);
+// Use a shared, tool-agnostic cache directory to avoid multi-runtime
+// resolution mismatches where check-update writes to one runtime's cache
+// but statusline reads from another (#1421).
+const cacheDir = path.join(homeDir, '.cache', 'gsd');
+const cacheFile = path.join(cacheDir, updateCacheFileName);
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(projectConfigDir, 'gsd-core', 'VERSION');
+const globalVersionFile = path.join(globalConfigDir, 'gsd-core', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  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,
+  },
+});
+
+child.unref();

package/hooks/gsd-config-reload.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// gsd-config-reload.js — FileChanged hook: hot-reload GSD config context
+// Fires when .planning/config.json is modified, created, or deleted.
+//
+// When the user edits .planning/config.json mid-session, this hook reads the
+// updated config and injects a summary as additionalContext so the agent knows
+// the new configuration without requiring a session restart.
+//
+// Input (from Claude Code):
+//   { session_id, cwd, hook_event_name: "FileChanged",
+//     file_path: "/abs/path/.planning/config.json", event: "change"|"add"|"unlink" }
+//
+// Output:
+//   { hookSpecificOutput: { hookEventName: "FileChanged", additionalContext: "..." } }
+//   or exits 0 silently (if config absent, unreadable, or event is "unlink").
+//
+// Enabled for all Claude Code installs. This hook is always-on — it is a
+// no-op when .planning/config.json is absent (ENOENT → exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+// Timeout guard: if stdin does not close within 8s exit silently rather than
+// hanging until Claude Code kills the process and reports "hook error".
+const stdinTimeout = setTimeout(() => process.exit(0), 8000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const event = data.event; // "change" | "add" | "unlink"
+    const filePath = data.file_path || '';
+    const cwd = data.cwd || process.cwd();
+
+    // Only handle the GSD planning config — verify both basename and that the
+    // resolved path is .planning/config.json relative to cwd.  The hook
+    // matcher ('config.json') fires on any watched config.json; this guard
+    // ensures an unrelated config.json in node_modules/ or elsewhere does not
+    // inject spurious additionalContext.
+    const basename = path.basename(filePath);
+    if (basename !== 'config.json') {
+      process.exit(0);
+    }
+    const expectedPath = path.resolve(cwd, '.planning', 'config.json');
+    if (path.resolve(filePath) !== expectedPath) {
+      process.exit(0);
+    }
+
+    // On unlink (deletion) emit a brief notice and exit
+    if (event === 'unlink') {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was deleted. ' +
+            'Falling back to built-in defaults for this session.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Read the updated config file
+    let config;
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      config = JSON.parse(raw);
+    } catch (e) {
+      if (e && e.code === 'ENOENT') process.exit(0);
+      // Malformed JSON — inform the agent without crashing
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'FileChanged',
+          additionalContext:
+            'GSD config (.planning/config.json) was modified but could not be parsed. ' +
+            'Check the file for JSON syntax errors.',
+        },
+      }));
+      process.exit(0);
+    }
+
+    // Build a concise summary of key config fields the agent cares about
+    const lines = ['GSD config reloaded (.planning/config.json updated):'];
+
+    if (config.runtime) lines.push(`  runtime: ${config.runtime}`);
+    if (config.mode) lines.push(`  mode: ${config.mode}`);
+
+    // hooks section (opt-in toggles agents act on)
+    if (config.hooks && typeof config.hooks === 'object') {
+      const hookKeys = Object.entries(config.hooks)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (hookKeys) lines.push(`  hooks: { ${hookKeys} }`);
+    }
+
+    // workflow section (key toggles)
+    if (config.workflow && typeof config.workflow === 'object') {
+      const wfKeys = Object.entries(config.workflow)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (wfKeys) lines.push(`  workflow: { ${wfKeys} }`);
+    }
+
+    // model overrides (agents use these)
+    if (config.models && typeof config.models === 'object') {
+      const modelKeys = Object.entries(config.models)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ');
+      if (modelKeys) lines.push(`  models: { ${modelKeys} }`);
+    }
+
+    if (lines.length === 1) {
+      // No notable fields — still confirm the reload happened
+      lines.push('  (no notable keys changed)');
+    }
+
+    const additionalContext = lines.join('\n');
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'FileChanged',
+        additionalContext,
+      },
+    }));
+  } catch (e) {
+    // Silent fail — never block the session on a config reload error
+    process.exit(0);
+  }
+});

package/hooks/gsd-context-monitor.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// Context Monitor - PostToolUse/AfterTool hook (Gemini uses AfterTool)
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. This makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const STALE_SECONDS = 60;      // ignore metrics older than 60s
+const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+
+let input = '';
+// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+// Windows/Git Bash, or slow Claude Code piping during large outputs),
+// exit silently instead of hanging until Claude Code kills the process
+// and reports "hook error". See #775, #1162.
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    // Reject session IDs that contain path traversal sequences or path separators.
+    // session_id is used to construct file paths in /tmp — an unsanitized value
+    // could escape the temp directory and read or write arbitrary files.
+    if (/[/\\]|\.\./.test(sessionId)) {
+      process.exit(0);
+    }
+
+    // Check if context warnings are disabled via config.
+    // Collapsed existsSync+readFileSync into a single read guarded by try/catch
+    // (ENOENT or parse error → use defaults, same as old "planningDir absent" branch).
+    const cwd = data.cwd || process.cwd();
+    try {
+      const configPath = path.join(cwd, '.planning', 'config.json');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.hooks?.context_warnings === false) {
+        process.exit(0);
+      }
+    } catch (e) {
+      // Missing or unparseable config → proceed with defaults (context warnings enabled)
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    // If no metrics file, this is a subagent or fresh session -- exit silently.
+    // Collapsed existsSync+readFileSync: ENOENT → exit 0 (identical to old !existsSync branch),
+    // other errors rethrow to the outer catch (swallowed → exit 0, as before).
+    let metricsRaw;
+    try {
+      metricsRaw = fs.readFileSync(metricsPath, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') process.exit(0);
+      throw e;
+    }
+    const metrics = JSON.parse(metricsRaw);
+    const now = Math.floor(Date.now() / 1000);
+
+    // Ignore stale metrics
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // No warning needed
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce: check if we warned recently
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    // Collapsed existsSync+readFileSync: ENOENT or parse error → keep default warnData
+    // (same as old "file absent" branch). firstWarn tracks whether we read a valid sentinel.
+    try {
+      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      firstWarn = false;
+    } catch (e) {
+      // Missing or corrupted sentinel → firstWarn stays true, warnData stays at defaults
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Emit immediately on first warning, then debounce subsequent ones
+    // Severity escalation (WARNING -> CRITICAL) bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      // Update counter and exit without warning
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce counter
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if GSD is active (has .planning/STATE.md in working directory)
+    const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    // On CRITICAL with active GSD project, auto-record session state as a
+    // breadcrumb for /gsd:resume-work (#1974). Fire-and-forget subprocess —
+    // doesn't block the hook or the agent. Fires ONCE per CRITICAL session,
+    // guarded by warnData.criticalRecorded to prevent repeated overwrites
+    // of the "crash moment" record on every debounce cycle.
+    if (isCritical && isGsdActive && !warnData.criticalRecorded) {
+      try {
+        // Runtime-agnostic path: this hook lives at <runtime-config>/hooks/
+        // and gsd-tools.cjs lives at <runtime-config>/gsd-core/bin/.
+        // 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]})`;
+        spawn(
+          process.execPath,
+          [gsdTools, 'state', 'record-session', '--stopped-at', stoppedAt],
+          { cwd, detached: true, stdio: 'ignore', windowsHide: true }
+        ).unref();
+        warnData.criticalRecorded = true;
+        // Persist the sentinel so subsequent debounce cycles don't re-fire
+        fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      } catch { /* non-critical — don't let state recording break the hook */ }
+    }
+
+    // Build advisory warning message (never use imperative commands that
+    // override user preferences — see #884)
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          '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 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 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}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or ' +
+          'starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: process.env.GEMINI_API_KEY ? "AfterTool" : "PostToolUse",
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail -- never block tool execution
+    process.exit(0);
+  }
+});