@opengsd/gsd-core 1.11.0 → 1.12.0

package/hooks/gsd-workflow-guard.js

@@ -21,6 +21,18 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+const { reportIfUndetermined } = require('./lib/git-probe.js');
+
+// This guard is almost entirely advisory (fail open — a broken advisory must
+// never wedge every tool call), with ONE hard block (#3504 force-add-on-
+// agent-branch) that fails CLOSED on internal error instead. That split is
+// re-derived dynamically inside the outer catch (failClosedBlockContext), not
+// a fixed per-hook policy, so ON_CRASH names only the FINAL, unconditional
+// fallback reached when the fail-closed context does not apply — i.e. the
+// historical exit(0). Declared ONCE here so that fallback states its policy
+// explicitly rather than inheriting a default (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 function forceGitAddCwds(command, defaultCwd) {
   const tokens = tokenize(command || '');
@@ -82,6 +94,12 @@ function currentBranch(cwd) {
     timeout: 2000,
     killSignal: 'SIGTERM',
   });
+  // #3911: a timeout/spawn-failure here previously degraded to '' exactly
+  // like a clean "not on a branch" answer — indistinguishable from the
+  // caller's point of view. reportIfUndetermined is a no-op on a genuine
+  // negative and only emits a diagnostic when the probe itself could not
+  // run; the '' fallback (and therefore this hook's exit code) is unchanged.
+  reportIfUndetermined('gsd-workflow-guard', 'git branch --show-current', result);
   if (result.status !== 0) return '';
   return result.stdout.trim();
 }
@@ -114,9 +132,10 @@ function emitForceAddBlock(origin) {
     origin: failClosed ? 'fail-closed' : 'force-add-detected',
     reason,
   };
-  process.stdout.write(JSON.stringify(output));
-  // Kimi CLI's exit-2 protocol feeds stderr back to the model (#2304)
-  process.stderr.write(output.reason);
+  // Kimi CLI's exit-2 protocol feeds stderr back to the model (#2304) — deny's
+  // stderrPayload keeps fd 2 to the plain reason string, matching the
+  // pre-migration two-write byte-for-byte.
+  deny(output, output.reason);
 }
 
 // #3504 fail-closed context re-derivation. Runs INSIDE the outer catch, after
@@ -260,7 +279,7 @@ function normalizeKimiPayload(data) {
 }
 
 let input = '';
-const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+const stdinTimeout = setTimeout(() => allow(undefined), 3000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
@@ -282,29 +301,28 @@ process.stdin.on('end', () => {
 
     if (toolName === 'Bash') {
       if (!isWorkflowGuardEnabled) {
-        process.exit(0);
+        allow(undefined);
       }
       const command = data.tool_input?.command || '';
       for (const gitCwd of forceGitAddCwds(command, cwd)) {
         const branch = currentBranch(gitCwd);
         if (/^(worktree-)?agent-/.test(branch)) {
           emitForceAddBlock();
-          process.exit(2);
         }
       }
-      process.exit(0);
+      allow(undefined);
     }
 
     // Only guard Write, Edit, and MultiEdit tool calls
     if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Check if we're inside a GSD workflow (Task subagent or /gsd- skill)
     // Subagents have a session_id that differs from the parent
     // and typically have a description field set by the orchestrator
     if (data.tool_input?.is_subagent || data.session_type === 'task') {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Check the file being edited
@@ -319,7 +337,7 @@ process.stdin.on('end', () => {
 
     // Allow edits to .planning/ files (GSD state management)
     if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Allow edits to common config/docs files that don't need GSD tracking
@@ -332,11 +350,11 @@ process.stdin.on('end', () => {
       /settings\.json$/,
     ];
     if (allowedPatterns.some(p => p.test(filePath))) {
-      process.exit(0);
+      allow(undefined);
     }
 
     if (!isWorkflowGuardEnabled) {
-      process.exit(0); // Guard disabled (default) or no GSD project
+      allow(undefined); // Guard disabled (default) or no GSD project
     }
 
     // If we get here: GSD project, guard enabled, file edit outside .planning/,
@@ -357,13 +375,13 @@ process.stdin.on('end', () => {
     // #3504: split posture on internal error. The ONE hard block in this hook
     // (force-add on agent branches) fails CLOSED — if the blocking context can
     // be re-derived from the payload (Bash tool + guard enabled + determinably
-    // an agent branch), exit 2 rather than silently allowing. Everything else
+    // an agent branch), deny rather than silently allowing. Everything else
     // keeps the historical fail-open posture: a broken advisory guard must
-    // never wedge the session's tool calls.
+    // never wedge the session's tool calls. ON_CRASH is declared ALLOW at
+    // module top for exactly that unconditional fallback (#3911).
     if (failClosedBlockContext(input)) {
       emitForceAddBlock('fail-closed');
-      process.exit(2);
     }
-    process.exit(0);
+    crash(ON_CRASH, undefined);
   }
 });

package/hooks/gsd-worktree-path-guard.js

@@ -17,6 +17,16 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+const { reportIfUndetermined } = require('./lib/git-probe.js');
+
+// This guard's outer catch has always exited 0 (fail open): a path guard that
+// cannot resolve the worktree must not block the user's edit — its whole job
+// is a targeted containment check, not a general-purpose file-write blocker,
+// and an unresolved worktree root gives it nothing to check against. Declared
+// ONCE here so the outer catch's crash() call states its policy explicitly
+// rather than inheriting a default (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
 const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, windowsHide: true };
 
@@ -132,7 +142,7 @@ function normalizeKimiPayload(data) {
 }
 
 let input = '';
-const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+const stdinTimeout = setTimeout(() => allow(undefined), 3000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
@@ -143,7 +153,7 @@ process.stdin.on('end', () => {
 
     // Only guard Edit, Write, and MultiEdit tool calls
     if (toolName !== 'Edit' && toolName !== 'Write' && toolName !== 'MultiEdit') {
-      process.exit(0);
+      allow(undefined);
     }
 
     const cwd = data.cwd || process.cwd();
@@ -154,15 +164,20 @@ process.stdin.on('end', () => {
     // In the main repo or a submodule it returns .git (or a path without /worktrees/).
     // This approach works even when cwd is a subdirectory of the worktree.
     const gitDirResult = git(['rev-parse', '--git-dir'], cwd);
+    // #3911: a timeout/spawn-failure result is indistinguishable from a clean
+    // "not a git repo" answer by status/stdout alone — reportIfUndetermined
+    // is a no-op on a genuine negative and only fires the diagnostic when the
+    // probe itself could not run. The allow() below is UNCHANGED either way.
+    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --git-dir', gitDirResult);
     if (gitDirResult.status !== 0 || !gitDirResult.stdout) {
-      process.exit(0); // not a git repo — pass through
+      allow(undefined); // not a git repo — pass through
     }
 
     const gitDir = gitDirResult.stdout.trim();
     // A linked worktree's --git-dir contains .git/worktrees/ as a path component
     const isLinkedWorktree = /[/\\]\.git[/\\]worktrees[/\\]/.test(gitDir);
     if (!isLinkedWorktree) {
-      process.exit(0); // main repo, submodule, or separate-git-dir — no-op
+      allow(undefined); // main repo, submodule, or separate-git-dir — no-op
     }
 
     // #1342: Only enforce inside a GSD-managed isolated executor worktree. Those
@@ -172,18 +187,20 @@ process.stdin.on('end', () => {
     // on the user's own branch, so the guard must be a no-op there. Detached HEAD
     // / error → not GSD-managed → no-op.
     const branchResult = git(['symbolic-ref', '--short', 'HEAD'], cwd);
+    reportIfUndetermined('gsd-worktree-path-guard', 'git symbolic-ref --short HEAD', branchResult);
     const branch = branchResult.status === 0 && branchResult.stdout ? branchResult.stdout.trim() : '';
     // #3021: accept worktree-wf_<runid>-<n> branches (Workflow backend's naming).
     if (!/^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$/.test(branch)) {
-      process.exit(0); // not a GSD-managed executor worktree — no-op
+      allow(undefined); // not a GSD-managed executor worktree — no-op
     }
 
     // Get the raw --show-toplevel output for the worktree (cwd).
     // We keep it raw (not path.resolve'd) to compare directly with the
     // file's toplevel — same git binary, same format, no normalization needed.
     const wtTopResult = git(['rev-parse', '--show-toplevel'], cwd);
+    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --show-toplevel (worktree cwd)', wtTopResult);
     if (wtTopResult.status !== 0 || !wtTopResult.stdout) {
-      process.exit(0); // can't determine root — fail open
+      allow(undefined); // can't determine root — fail open
     }
     const wtTopRaw = wtTopResult.stdout.trim();
 
@@ -201,7 +218,7 @@ process.stdin.on('end', () => {
       ? data.tool_input.file_path
       : '';
     if (!rawFilePath) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Relative paths resolve against the tool's CWD, which is inside the worktree
@@ -219,7 +236,7 @@ process.stdin.on('end', () => {
     // `../`-laden path exits 0 at this line and escapes the worktree. Stating a
     // mechanism and an unverified premise — not asserting a live bypass.
     if (!path.isAbsolute(rawFilePath)) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Normalise .. traversal so /worktree/src/../../../main/file
@@ -244,7 +261,7 @@ process.stdin.on('end', () => {
       // Walked to root without finding any directory — path is synthetic.
       // A path with no existing ancestor is not the #260 main-repo vector;
       // #260 is caught by the different-git-root branch below. Fail open. (#1342)
-      process.exit(0);
+      allow(undefined);
     }
 
     // Ask git for the toplevel of the file's location.
@@ -254,6 +271,7 @@ process.stdin.on('end', () => {
     // back-slash inconsistencies) — both values come from the same git binary
     // in the same format by definition.
     const fileTopResult = git(['rev-parse', '--show-toplevel'], checkDir);
+    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --show-toplevel (file location)', fileTopResult);
 
     if (fileTopResult.status !== 0 || !fileTopResult.stdout) {
       // The target's location is not a git work tree. Two sub-cases:
@@ -263,6 +281,7 @@ process.stdin.on('end', () => {
       //  - Truly outside all git repositories (e.g. ~/.claude/plans/) → not the
       //    main-repo vector → fail open. (#1342)
       const insideGitDir = git(['rev-parse', '--is-inside-git-dir'], checkDir);
+      reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --is-inside-git-dir', insideGitDir);
       if (insideGitDir.status === 0 && insideGitDir.stdout && insideGitDir.stdout.trim() === 'true') {
         const output = {
           decision: 'block',
@@ -271,20 +290,17 @@ process.stdin.on('end', () => {
             `not the active worktree at '${wtTopRaw}'. Writing to repository internals via an ` +
             `absolute path is not permitted from an isolated executor worktree. Use a relative path.`,
         };
-        process.stdout.write(JSON.stringify(output));
-        // Kimi feeds stderr (not stdout) back to the model on exit 2.
-        process.stderr.write(output.reason);
-        process.exit(2);
+        deny(output, output.reason);
       }
       // Outside all git repositories — fail open (#1342).
-      process.exit(0);
+      allow(undefined);
     }
 
     const fileTopRaw = fileTopResult.stdout.trim();
 
     // Same git toplevel → file is inside the worktree → allow
     if (fileTopRaw === wtTopRaw) {
-      process.exit(0);
+      allow(undefined);
     }
 
     // BLOCK: file resolves to a different git root than the active worktree
@@ -299,12 +315,11 @@ process.stdin.on('end', () => {
         `(hook cwd: '${cwd}').`,
     };
 
-    process.stdout.write(JSON.stringify(output));
-    // Kimi feeds stderr (not stdout) back to the model on exit 2.
-    process.stderr.write(output.reason);
-    process.exit(2);
+    deny(output, output.reason);
   } catch {
-    // Silent fail — never block valid tool calls due to hook errors
-    process.exit(0);
+    // Silent fail — never block valid tool calls due to hook errors.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });

package/hooks/gsd-write-guard.js

@@ -75,6 +75,21 @@
 
 const fs = require('fs');
 const path = require('path');
+const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+
+// This guard's outer catch has always exited 0 (fail open — a hook error
+// must never block a legitimate tool call; see the emitBlock/consumeSentinelFor
+// header comments). Declared ONCE here so the outer catch's crash() call
+// states its policy explicitly rather than inheriting a default (#3911).
+const ON_CRASH = HOOK_ON_CRASH.ALLOW;
+
+// #3911 (ADR-3889 Phase 7) NOTE: the exit(2) call site (emitBlock, below) is
+// migrated to hooks/lib/hook-exit.js's deny(), using its `stderrPayload`
+// param (added for exactly this site): fd 1 still gets the full JSON
+// `output`, fd 2 gets ONLY the plain-text `output.reason` string — because
+// Kimi's native hook bus reads stderr verbatim back to the model, and a raw
+// JSON-stringified object on stderr is not the same reason text a model
+// should read. Byte-identical to the pre-migration emitBlock.
 
 // Block when the pending payload has fewer than this fraction of the on-disk
 // line count (0.4 → a Write shrinking a file below 40% of its current size).
@@ -158,20 +173,13 @@ function consumeSentinelFor(filePath, normalized) {
 
 // m2 (round 5): the block emission must itself be exception-safe. An EPIPE
 // from writeSync inside the outer try would land in the fail-OPEN catch —
-// the one outcome the fail-closed branches exist to prevent. The decision
-// stands regardless of whether the payload could be delivered.
+// the one outcome the fail-closed branches exist to prevent. terminateNow
+// (via deny()) already guarantees this: a failed write never changes the
+// exit code and never throws out of the call. `output.reason` is passed as
+// the distinct stderrPayload so fd 2 gets the plain reason string — not the
+// full JSON `output` fd 1 gets — matching the pre-migration byte-for-byte.
 function emitBlock(output) {
-  try {
-    // writeSync: pipe writes via process.stdout/stderr are async on Windows
-    // and process.exit() does not flush them — a truncated block payload is
-    // a guard that silently half-fired.
-    fs.writeSync(1, JSON.stringify(output));
-    // Kimi feeds stderr (not stdout) back to the model on exit 2.
-    fs.writeSync(2, output.reason);
-  } catch {
-    // Emission failed; the block still stands.
-  }
-  process.exit(2);
+  deny(output, output.reason);
 }
 
 // #2304: Kimi's native hook bus delivers Kimi's tool vocabulary in the payload
@@ -223,7 +231,7 @@ function normalizeKimiPayload(data) {
 }
 
 let input = '';
-const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+const stdinTimeout = setTimeout(() => allow(undefined), 3000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
@@ -234,17 +242,17 @@ process.stdin.on('end', () => {
     // A null/primitive payload has nothing to guard — exit deliberately
     // rather than throwing into the fail-open catch below (#2595 class).
     if (data === null || typeof data !== 'object') {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Only whole-file Write is catastrophic-by-construction; Edit/MultiEdit
     // replace bounded spans and are out of scope by design (#2255).
     if (data.tool_name !== 'Write') {
-      process.exit(0);
+      allow(undefined);
     }
 
     if (isOverrideSet()) {
-      process.exit(0); // documented escape hatch — legitimate reset in progress
+      allow(undefined); // documented escape hatch — legitimate reset in progress
     }
 
     // Typed read (#2547 class): `[]`/`{}` are truthy, pass a `!value`
@@ -254,7 +262,7 @@ process.stdin.on('end', () => {
     const rawFilePath = typeof rawInput?.file_path === 'string' ? rawInput.file_path : '';
     const content = rawInput?.content;
     if (!rawFilePath || typeof content !== 'string') {
-      process.exit(0);
+      allow(undefined);
     }
 
     // Resolve relative paths against the session cwd (the same base the
@@ -272,7 +280,7 @@ process.stdin.on('end', () => {
     const normalized = filePath.replace(/\\/g, '/');
 
     if (!CURATED_PATTERNS.some(re => re.test(normalized))) {
-      process.exit(0); // not a curated planning artifact
+      allow(undefined); // not a curated planning artifact
     }
 
     // Only guard overwrites — creating a curated file fresh is fine.
@@ -285,7 +293,7 @@ process.stdin.on('end', () => {
       onDisk = fs.readFileSync(filePath, 'utf8');
     } catch (err) {
       if (err && err.code === 'ENOENT') {
-        process.exit(0); // does not exist — new-file Write, nothing to clobber
+        allow(undefined); // does not exist — new-file Write, nothing to clobber
       }
       emitBlock({
         decision: 'block',
@@ -306,17 +314,17 @@ process.stdin.on('end', () => {
     const newLines = countLines(content);
 
     if (oldLines < FLOOR_LINES) {
-      process.exit(0); // sub-floor stub — ratio checks are meaningless here
+      allow(undefined); // sub-floor stub — ratio checks are meaningless here
     }
 
     if (newLines >= oldLines * SHRINK_RATIO) {
-      process.exit(0); // shrink (if any) is within tolerance
+      allow(undefined); // shrink (if any) is within tolerance
     }
 
     // The mechanical hatch for workflow steps (see header): consulted only
     // here, at the block point, so a within-tolerance write never burns it.
     if (consumeSentinelFor(filePath, normalized)) {
-      process.exit(0); // armed for exactly this file, fresh, now consumed
+      allow(undefined); // armed for exactly this file, fresh, now consumed
     }
 
     const pct = Math.round((newLines / oldLines) * 100);
@@ -353,7 +361,9 @@ process.stdin.on('end', () => {
         `to bypass this guard once.`,
     });
   } catch {
-    // Silent fail — never block valid tool calls due to hook errors
-    process.exit(0);
+    // Silent fail — never block valid tool calls due to hook errors.
+    // ON_CRASH is declared ALLOW at module top: this preserves today's
+    // exit(0) fail-open behavior exactly (#3911).
+    crash(ON_CRASH, undefined);
   }
 });