@opengsd/gsd-core 1.7.0 → 1.9.0

package/hooks/gsd-read-guard.js

@@ -21,6 +21,100 @@
 const fs = require('fs');
 const path = require('path');
 
+// #2304: Kimi's native hook bus delivers Kimi's tool vocabulary in the payload
+// (Write → WriteFile, Edit/MultiEdit → StrReplaceFile) while the [[hooks]]
+// matcher is registered pre-translated (runtime-hooks-surface.cts
+// buildKimiHooksTomlBlock) — so without normalizing the payload too, the
+// matcher fires but the tool_name check below exits 0 and the guard is dormant
+// on Kimi. The tool_input field names differ as well (kimi-cli
+// src/kimi_cli/tools/file/{write,replace}.py): WriteFile takes `path`/`content`,
+// StrReplaceFile takes `path` + `edit: Edit | list[Edit]` with `old`/`new` —
+// kimi-cli's hooks/events.py forwards tool_input verbatim, so both layers need
+// mapping. Accepts bare and module-qualified ('kimi_cli.tools.file:WriteFile')
+// names; unknown names fall through untouched. Inlined per guard (not
+// hooks/lib/): hook scripts are staged as standalone files, and a sibling
+// require is a staging dependency that can fail silently.
+// A Map, not an object literal: bare bracket lookup resolves prototype keys
+// ('constructor', '__proto__', 'toString') to truthy functions/objects, so the
+// !mapped fall-through never fires for them; Map.get returns undefined (same
+// shape as canonicalizeRuntimeName in src/runtime-name-policy.cts).
+const KIMI_TOOL_NAMES = new Map([['WriteFile', 'Write'], ['StrReplaceFile', 'Edit'], ['ReadFile', 'Read'], ['Shell', 'Bash']]);
+function normalizeKimiPayload(data) {
+  // #2595 (review nit): `JSON.parse('null')` is null, and null/primitive
+  // payloads reached the `data.tool_name` read below and threw — falsifying
+  // this function's own "total over the inputs JSON can express" claim, which
+  // property (e) now tests directly. Harmless in practice (a null payload has
+  // nothing to guard, and the throw landed in the same fail-open catch as the
+  // exit-0 it now takes deliberately) but the claim should be true as stated.
+  if (data === null || typeof data !== 'object') return data;
+  const raw = data.tool_name;
+  if (typeof raw !== 'string') return data;
+  const mapped = KIMI_TOOL_NAMES.get(raw.slice(raw.lastIndexOf(':') + 1));
+  if (!mapped) return data;
+  data.tool_name = mapped;
+  if (data.tool_response === undefined && data.tool_output !== undefined) {
+    data.tool_response = data.tool_output;
+  }
+  const input = data.tool_input;
+  if (input && typeof input === 'object') {
+    // #2547 (review): Kimi's `path` is AUTHORITATIVE — it must win outright,
+    // not merely fill in when `file_path` happens to be absent. kimi-cli's file
+    // tools carry no `file_path` field at all (src/kimi_cli/tools/file/write.py,
+    // replace.py, @ 4a550ef — the SHA #2547 pins), and soul/toolset.py hands the
+    // model's raw json-parsed
+    // arguments to PreToolUse verbatim, doing typed validation only later inside
+    // tool.call() — after the hook has already decided. So a `file_path` in a
+    // Kimi payload is ALWAYS model-supplied, and under the old `=== undefined`
+    // condition it SHADOWED the field kimi-cli actually executes on. A payload
+    // pairing a cross-root `path` with a spurious `file_path: ""` left every
+    // guard reading an empty string and exiting 0, while the identical write
+    // without the extra key blocked — a bypass needing no crash at all. The same
+    // shadowing also preserved a NON-STRING `file_path` (`[]`), which threw
+    // inside gsd-worktree-path-guard's path.isAbsolute() and reached its outer
+    // `catch { process.exit(0) }`: the same crash-to-allow this fix closes
+    // elsewhere, reached through the guard's own read rather than through
+    // normalization. Overwriting can only ever narrow what a guard inspects to
+    // the path that will actually be written, so it cannot under-block.
+    if (typeof input.path === 'string') {
+      input.file_path = input.path;
+    }
+    const edits = Array.isArray(input.edit) ? input.edit
+      : (input.edit && typeof input.edit === 'object') ? [input.edit] : [];
+    if (edits.length) {
+      // #2547: `e?.old`, not `e.old` — `??` guards the value, not the
+      // dereference, so a NULLISH entry (`edit: [null]`) threw a TypeError
+      // here. normalizeKimiPayload runs before any tool dispatch, so that throw
+      // reached each guard's outer `catch { process.exit(0) }` and silently
+      // downgraded a should-BLOCK call into an allow. (A string/number entry
+      // never threw — `('x').old` is a legal read yielding undefined.)
+      //
+      // The String() coercion is guarded for the same reason: `{"toString":
+      // null}` is valid JSON that throws "Cannot convert object to primitive
+      // value", which is the identical crash-to-allow with a different
+      // trigger. Degrading only the non-coercible entry to '' keeps
+      // stringification intact for every value that CAN coerce (numbers,
+      // arrays, plain objects), so nothing downstream — including
+      // gsd-prompt-guard's scan of new_string — loses content it saw before.
+      const editText = (v) => { try { return String(v ?? ''); } catch { return ''; } };
+      // #2595 (review Major 2): reconstruct UNCONDITIONALLY, mirroring the
+      // `path` decision above rather than merely filling in when the field
+      // happens to be absent. kimi-cli's StrReplaceFile schema is `path` +
+      // `edit` only (src/kimi_cli/tools/file/replace.py @ 4a550ef) — it carries
+      // no `old_string`/`new_string` at all, so either field appearing in a
+      // Kimi payload is ALWAYS model-supplied, exactly like `file_path`. Under
+      // the old `=== undefined` condition a model-supplied `new_string: ""`
+      // SHADOWED the reconstruction, leaving gsd-prompt-guard's injection scan
+      // reading '' and exiting at its `if (!content)` before it ever saw the
+      // real `edit[].new` — a one-key bypass of the very scan this fix's
+      // guarded coercion exists to keep fed. A `typeof` test would NOT close
+      // it: a benign non-empty string shadows just as effectively as ''.
+      input.old_string = edits.map((e) => editText(e?.old)).join('\n');
+      input.new_string = edits.map((e) => editText(e?.new)).join('\n');
+    }
+  }
+  return data;
+}
+
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
@@ -28,7 +122,7 @@ process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {
-    const data = JSON.parse(input);
+    const data = normalizeKimiPayload(JSON.parse(input));
     const toolName = data.tool_name;
 
     // Only intercept Write and Edit tool calls
@@ -60,7 +154,11 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
-    const filePath = data.tool_input?.file_path || '';
+    // #2595 (review Major 3, sibling sweep): typed read — same class as the
+    // worktree guard's, advisory-only here (no exit(2) path in this hook).
+    const filePath = typeof data.tool_input?.file_path === 'string'
+      ? data.tool_input.file_path
+      : '';
     if (!filePath) {
       process.exit(0);
     }

package/hooks/gsd-read-injection-scanner.js

@@ -105,6 +105,109 @@ function isExcludedPath(filePath) {
   );
 }
 
+// Kimi CLI delivers the tool vocabulary the matcher was registered with —
+// the scanner's Kimi matcher is 'ReadFile' (runtime-hooks-surface.cts), so
+// tool_name arrives as 'ReadFile' (possibly module-qualified) and tool_input
+// carries `path` (kimi-cli src/kimi_cli/tools/file/read.py Params), not
+// `file_path`. Without normalization the SCANNED_TOOLS check below never
+// matches on Kimi and the scanner is silently dormant (#2304).
+//
+// SCOPE ON KIMI (#2547): normalization makes this scanner's CHECKS run on
+// Kimi. It does NOT make its block effective there. This is a PostToolUse
+// hook, and kimi-cli's dispatch never inspects PostToolUse hook results —
+// src/kimi_cli/soul/toolset.py fires them via asyncio.create_task() and
+// returns the ToolResult without awaiting, whereas PreToolUse results are
+// awaited and honoured. So `security.injection_blocking` cannot take effect
+// on Kimi regardless of the shape emitted below; reshaping the output would
+// not change that. Blocking prompt injection on Kimi needs a PreToolUse
+// mechanism, or an upstream kimi-cli change. Do not describe this hook as
+// "engaged" or "blocking" on Kimi. This block is
+// kept byte-identical with the copies in gsd-prompt-guard.js,
+// gsd-read-guard.js, and gsd-worktree-path-guard.js — a parity test binds
+// them (tests/kimi-guard-normalization-parity.test.cjs). Inlined per guard
+// (not hooks/lib/): hook scripts are staged as standalone files, and a
+// sibling require is a staging dependency that can fail silently.
+// A Map, not an object literal: bare bracket lookup resolves prototype keys
+// ('constructor', '__proto__', 'toString') to truthy functions/objects, so the
+// !mapped fall-through never fires for them; Map.get returns undefined (same
+// shape as canonicalizeRuntimeName in src/runtime-name-policy.cts).
+const KIMI_TOOL_NAMES = new Map([['WriteFile', 'Write'], ['StrReplaceFile', 'Edit'], ['ReadFile', 'Read'], ['Shell', 'Bash']]);
+function normalizeKimiPayload(data) {
+  // #2595 (review nit): `JSON.parse('null')` is null, and null/primitive
+  // payloads reached the `data.tool_name` read below and threw — falsifying
+  // this function's own "total over the inputs JSON can express" claim, which
+  // property (e) now tests directly. Harmless in practice (a null payload has
+  // nothing to guard, and the throw landed in the same fail-open catch as the
+  // exit-0 it now takes deliberately) but the claim should be true as stated.
+  if (data === null || typeof data !== 'object') return data;
+  const raw = data.tool_name;
+  if (typeof raw !== 'string') return data;
+  const mapped = KIMI_TOOL_NAMES.get(raw.slice(raw.lastIndexOf(':') + 1));
+  if (!mapped) return data;
+  data.tool_name = mapped;
+  if (data.tool_response === undefined && data.tool_output !== undefined) {
+    data.tool_response = data.tool_output;
+  }
+  const input = data.tool_input;
+  if (input && typeof input === 'object') {
+    // #2547 (review): Kimi's `path` is AUTHORITATIVE — it must win outright,
+    // not merely fill in when `file_path` happens to be absent. kimi-cli's file
+    // tools carry no `file_path` field at all (src/kimi_cli/tools/file/write.py,
+    // replace.py, @ 4a550ef — the SHA #2547 pins), and soul/toolset.py hands the
+    // model's raw json-parsed
+    // arguments to PreToolUse verbatim, doing typed validation only later inside
+    // tool.call() — after the hook has already decided. So a `file_path` in a
+    // Kimi payload is ALWAYS model-supplied, and under the old `=== undefined`
+    // condition it SHADOWED the field kimi-cli actually executes on. A payload
+    // pairing a cross-root `path` with a spurious `file_path: ""` left every
+    // guard reading an empty string and exiting 0, while the identical write
+    // without the extra key blocked — a bypass needing no crash at all. The same
+    // shadowing also preserved a NON-STRING `file_path` (`[]`), which threw
+    // inside gsd-worktree-path-guard's path.isAbsolute() and reached its outer
+    // `catch { process.exit(0) }`: the same crash-to-allow this fix closes
+    // elsewhere, reached through the guard's own read rather than through
+    // normalization. Overwriting can only ever narrow what a guard inspects to
+    // the path that will actually be written, so it cannot under-block.
+    if (typeof input.path === 'string') {
+      input.file_path = input.path;
+    }
+    const edits = Array.isArray(input.edit) ? input.edit
+      : (input.edit && typeof input.edit === 'object') ? [input.edit] : [];
+    if (edits.length) {
+      // #2547: `e?.old`, not `e.old` — `??` guards the value, not the
+      // dereference, so a NULLISH entry (`edit: [null]`) threw a TypeError
+      // here. normalizeKimiPayload runs before any tool dispatch, so that throw
+      // reached each guard's outer `catch { process.exit(0) }` and silently
+      // downgraded a should-BLOCK call into an allow. (A string/number entry
+      // never threw — `('x').old` is a legal read yielding undefined.)
+      //
+      // The String() coercion is guarded for the same reason: `{"toString":
+      // null}` is valid JSON that throws "Cannot convert object to primitive
+      // value", which is the identical crash-to-allow with a different
+      // trigger. Degrading only the non-coercible entry to '' keeps
+      // stringification intact for every value that CAN coerce (numbers,
+      // arrays, plain objects), so nothing downstream — including
+      // gsd-prompt-guard's scan of new_string — loses content it saw before.
+      const editText = (v) => { try { return String(v ?? ''); } catch { return ''; } };
+      // #2595 (review Major 2): reconstruct UNCONDITIONALLY, mirroring the
+      // `path` decision above rather than merely filling in when the field
+      // happens to be absent. kimi-cli's StrReplaceFile schema is `path` +
+      // `edit` only (src/kimi_cli/tools/file/replace.py @ 4a550ef) — it carries
+      // no `old_string`/`new_string` at all, so either field appearing in a
+      // Kimi payload is ALWAYS model-supplied, exactly like `file_path`. Under
+      // the old `=== undefined` condition a model-supplied `new_string: ""`
+      // SHADOWED the reconstruction, leaving gsd-prompt-guard's injection scan
+      // reading '' and exiting at its `if (!content)` before it ever saw the
+      // real `edit[].new` — a one-key bypass of the very scan this fix's
+      // guarded coercion exists to keep fed. A `typeof` test would NOT close
+      // it: a benign non-empty string shadows just as effectively as ''.
+      input.old_string = edits.map((e) => editText(e?.old)).join('\n');
+      input.new_string = edits.map((e) => editText(e?.new)).join('\n');
+    }
+  }
+  return data;
+}
+
 let inputBuf = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 5000);
 process.stdin.setEncoding('utf8');
@@ -112,7 +215,7 @@ process.stdin.on('data', chunk => { inputBuf += chunk; });
 process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {
-    const data = JSON.parse(inputBuf);
+    const data = normalizeKimiPayload(JSON.parse(inputBuf));
 
     const toolName = data.tool_name;
     const SCANNED_TOOLS = new Set(['Read', 'WebFetch', 'WebSearch']);
@@ -123,7 +226,11 @@ process.stdin.on('end', () => {
     // Source label + path-exclusion (path-exclusion applies to file reads only)
     let source;
     if (toolName === 'Read') {
-      source = data.tool_input?.file_path || '';
+      // #2595 (review Major 3, sibling sweep): typed read — a non-string
+      // threw inside isExcludedPath()'s .replace() into the outer catch.
+      source = typeof data.tool_input?.file_path === 'string'
+        ? data.tool_input.file_path
+        : '';
       if (!source) process.exit(0);
       if (isExcludedPath(source)) process.exit(0);
     } else if (toolName === 'WebFetch') {

package/hooks/gsd-statusline.js

@@ -11,6 +11,7 @@ const os = require('os');
 const childProcess = require('child_process');
 const { isSemverNewer } = require('../gsd-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../gsd-core/bin/lib/package-identity.cjs');
+const { normalizeStateStatus } = require('../gsd-core/bin/lib/state-document.cjs');
 
 // --- Config + last-command readers ------------------------------------------
 
@@ -142,12 +143,15 @@ function readGsdState(dir) {
 function parseStateMd(content) {
   const state = {};
 
-  // YAML frontmatter between --- markers (anchored at file start)
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  // YAML frontmatter between --- markers (anchored at file start).
+  // #2754: \r?\n (not literal \n) so a CRLF STATE.md (Windows-authored) parses
+  // identically to LF — pre-fix the literal-\n fence dropped the ENTIRE block.
+  // Mirrors the CRLF-safe extractFrontmatter in src/frontmatter.cts.
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (fmMatch) {
     const fm = fmMatch[1];
     // Top-level scalar key: value
-    for (const line of fm.split('\n')) {
+    for (const line of fm.split(/\r?\n/)) {
       const m = line.match(/^(\w+):\s*(.+)/);
       if (!m) continue;
       const [, key, val] = m;
@@ -168,10 +172,10 @@ function parseStateMd(content) {
       const items = npFlowMatch[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
       state.nextPhases = items.length > 0 ? items : null;
     } else {
-      const npBlockMatch = fm.match(/^next_phases:\s*\n((?:[ \t]*-[ \t]*[^\n]+\n?)*)/m);
+      const npBlockMatch = fm.match(/^next_phases:\s*\r?\n((?:[ \t]*-[ \t]*[^\r\n]+\r?\n?)*)/m);
       if (npBlockMatch) {
         const items = npBlockMatch[1]
-          .split('\n')
+          .split(/\r?\n/)
           .map(line => line.match(/^[ \t]*-[ \t]*(.+)$/))
           .filter(Boolean)
           .map(m => m[1].trim().replace(/^["']|["']$/g, ''))
@@ -180,7 +184,7 @@ function parseStateMd(content) {
       }
     }
     // progress nested block: completed_phases / total_phases / percent (2-space indent)
-    const progMatch = fm.match(/^progress:\s*\n((?:[ \t]+\w+:.+\n?)+)/m);
+    const progMatch = fm.match(/^progress:\s*\r?\n((?:[ \t]+\w+:.+\r?\n?)+)/m);
     if (progMatch) {
       const cp = progMatch[1].match(/^[ \t]+completed_phases:\s*(\d+)/m);
       const tp = progMatch[1].match(/^[ \t]+total_phases:\s*(\d+)/m);
@@ -319,6 +323,78 @@ function contextTokenSuffix(currentUsage) {
   return total > 0 ? ` (${formatTokens(total)})` : '';
 }
 
+// --- Compact state format (opt-in) ---------------------------------------------
+
+/**
+ * Collapse GSD's free-text status (often a multi-sentence narrative) to a
+ * single keyword, built on the canonical normalizer (#2162 approval
+ * condition): normalizeStateStatus() in state-document.cjs owns the status
+ * vocabulary (discussing / planning / executing / verifying / completed /
+ * paused) so the two can't drift. "paused" — the canonical stuck state — is
+ * uppercased to PAUSED, the one state worth shouting about. Statuses the
+ * normalizer passes through unrecognized fall back to their first word,
+ * capped at 16 chars so a rogue STATE.md can't blow up the line.
+ * Returns null for empty input.
+ */
+const CANONICAL_STATUSES = ['discussing', 'planning', 'executing', 'verifying', 'completed', 'paused'];
+
+function shortGsdStatus(status) {
+  if (!status) return null;
+  const norm = normalizeStateStatus(status, null);
+  if (CANONICAL_STATUSES.includes(norm)) {
+    return norm === 'paused' ? 'PAUSED' : norm;
+  }
+  // Unrecognized free text passes through normalizeStateStatus verbatim —
+  // fall back to the first word, capped.
+  const first = String(norm).trim().split(/[\s\u2014\u2013-]+/)[0] || '';
+  return first ? first.slice(0, 16) : null;
+}
+
+/**
+ * Compact alternative to formatGsdState, selected via
+ * `statusline.state_format: "compact"`:
+ *
+ *   "v1.12 · P7/12 · executing"     (phase active)
+ *   "v2.0 · P4.5 · BLOCKED"         (no total known)
+ *   "v2.0 · complete"               (milestone done)
+ *   "v2.0 · next execute-phase 4.5" (idle with a queued action)
+ *
+ * Drops the milestone name and progress bar — the biggest width costs in the
+ * default format — and collapses narrative statuses via shortGsdStatus().
+ * The default "full" format is untouched.
+ */
+function formatGsdStateCompact(s) {
+  const parts = [];
+
+  if (s.milestone) parts.push(s.milestone);
+
+  const phaseId = s.activePhase || s.phaseNum;
+  if (phaseId) {
+    parts.push(s.phaseTotal ? `P${phaseId}/${s.phaseTotal}` : `P${phaseId}`);
+  }
+
+  // Scene exclusivity mirrors formatGsdState's if/else chain: an in-flight
+  // phase (Scene 1, gated on activePhase ONLY — the legacy phaseNum shape
+  // still completes) wins over milestone-complete (Scene 3), even if a
+  // non-atomic STATE.md edit leaves percent=100 alongside a lifecycle phase.
+  const done = !s.activePhase && (Number(s.percent) === 100 ||
+    (s.completedPhases && s.totalPhases && s.completedPhases === s.totalPhases));
+
+  if (done) {
+    parts.push('complete');
+  } else {
+    const st = shortGsdStatus(s.status);
+    if (st) {
+      parts.push(st);
+    } else if (!phaseId && s.nextAction) {
+      const phasesStr = (s.nextPhases && s.nextPhases.length > 0) ? s.nextPhases.join('/') : '';
+      parts.push(`next ${s.nextAction}${phasesStr ? ' ' + phasesStr : ''}`);
+    }
+  }
+
+  return parts.join(' \u00b7 ');
+}
+
 // --- Model name --------------------------------------------------------------
 
 /**
@@ -529,8 +605,9 @@ function runStatusline() {
       }
     }
 
-    // GSD state (milestone · status · phase) — shown when no todo task
-    const gsdStateStr = task ? '' : formatGsdState(readGsdState(dir) || {});
+    // GSD state (milestone · status · phase) — shown when no todo task.
+    // Format resolved below once config is read (statusline.state_format).
+    let gsdStateStr = '';
 
     // GSD update available?
     // Read only the per-package shared cache file (#607). The legacy
@@ -558,6 +635,7 @@ function runStatusline() {
     // Failure here must never break the statusline — wrap the entire lookup.
     let lastCmdSuffix = '';
     let position = 'end';
+    let stateFormat = 'full';
     let gitSuffix = '';
     try {
       if (getConfigValue(cfg, 'statusline.show_last_command') === true) {
@@ -569,6 +647,7 @@ function runStatusline() {
       }
       const cfgPos = getConfigValue(cfg, 'statusline.context_position');
       if (cfgPos != null) position = cfgPos;
+      if (getConfigValue(cfg, 'statusline.state_format') === 'compact') stateFormat = 'compact';
       if (getConfigValue(cfg, 'statusline.show_git') === true) {
         gitSuffix = buildGitSegment(parseGitStatus(readGitStatus(dir)));
       }
@@ -576,6 +655,11 @@ function runStatusline() {
       // Never break the statusline on config/transcript/git errors
     }
 
+    if (!task) {
+      const state = readGsdState(dir) || {};
+      gsdStateStr = stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
+    }
+
     // Output
     const dirname = path.basename(dir);
     const middle = task
@@ -675,6 +759,7 @@ module.exports = {
   evaluateUpdateCache,
   formatTokens,
   contextTokenSuffix,
+  shortGsdStatus, formatGsdStateCompact,
   compactModelName,
   readGitStatus, parseGitStatus, buildGitSegment,
 };
@@ -690,6 +775,7 @@ function renderStatusline(data) {
 
   let lastCmdSuffix = '';
   let position = 'end';
+  let stateFormat = 'full';
   let gitSuffix = '';
   try {
     const cfg = readGsdConfig(dir);
@@ -701,12 +787,14 @@ function renderStatusline(data) {
     }
     const cfgPos = getConfigValue(cfg, 'statusline.context_position');
     if (cfgPos != null) position = cfgPos;
+    if (getConfigValue(cfg, 'statusline.state_format') === 'compact') stateFormat = 'compact';
     if (getConfigValue(cfg, 'statusline.show_git') === true) {
       gitSuffix = buildGitSegment(parseGitStatus(readGitStatus(dir)));
     }
   } catch (e) { /* swallow */ }
 
-  const gsdStateStr = formatGsdState(readGsdState(dir) || {});
+  const state = readGsdState(dir) || {};
+  const gsdStateStr = stateFormat === 'compact' ? formatGsdStateCompact(state) : formatGsdState(state);
   const middle = gsdStateStr ? `\x1b[2m${gsdStateStr}\x1b[0m` : null;
   return composeStatusline({ model, ctx: '', middle, dirname, lastCmdSuffix, gitSuffix, position });
 }

package/hooks/gsd-workflow-guard.js

@@ -78,6 +78,100 @@ function workflowGuardEnabled(cwd) {
   }
 }
 
+// Kimi CLI delivers the tool vocabulary the matcher was registered with —
+// this guard's Kimi matcher is 'Shell|WriteFile|StrReplaceFile'
+// (runtime-hooks-surface.cts), so tool_name arrives in Kimi vocabulary
+// (possibly module-qualified) and neither the Bash branch nor the
+// Write/Edit/MultiEdit allowlist below ever matched on Kimi (#2304).
+// kimi-cli's Shell.Params names its field `command`
+// (src/kimi_cli/tools/shell/__init__.py), same as Claude's Bash, so the
+// Shell leg needs only the name mapping. This block is kept byte-identical
+// with the copies in gsd-prompt-guard.js, gsd-read-guard.js,
+// gsd-worktree-path-guard.js, and gsd-read-injection-scanner.js — a parity
+// test binds them (tests/kimi-guard-normalization-parity.test.cjs). Inlined
+// per guard (not hooks/lib/): hook scripts are staged as standalone files,
+// and a sibling require is a staging dependency that can fail silently.
+// A Map, not an object literal: bare bracket lookup resolves prototype keys
+// ('constructor', '__proto__', 'toString') to truthy functions/objects, so the
+// !mapped fall-through never fires for them; Map.get returns undefined (same
+// shape as canonicalizeRuntimeName in src/runtime-name-policy.cts).
+const KIMI_TOOL_NAMES = new Map([['WriteFile', 'Write'], ['StrReplaceFile', 'Edit'], ['ReadFile', 'Read'], ['Shell', 'Bash']]);
+function normalizeKimiPayload(data) {
+  // #2595 (review nit): `JSON.parse('null')` is null, and null/primitive
+  // payloads reached the `data.tool_name` read below and threw — falsifying
+  // this function's own "total over the inputs JSON can express" claim, which
+  // property (e) now tests directly. Harmless in practice (a null payload has
+  // nothing to guard, and the throw landed in the same fail-open catch as the
+  // exit-0 it now takes deliberately) but the claim should be true as stated.
+  if (data === null || typeof data !== 'object') return data;
+  const raw = data.tool_name;
+  if (typeof raw !== 'string') return data;
+  const mapped = KIMI_TOOL_NAMES.get(raw.slice(raw.lastIndexOf(':') + 1));
+  if (!mapped) return data;
+  data.tool_name = mapped;
+  if (data.tool_response === undefined && data.tool_output !== undefined) {
+    data.tool_response = data.tool_output;
+  }
+  const input = data.tool_input;
+  if (input && typeof input === 'object') {
+    // #2547 (review): Kimi's `path` is AUTHORITATIVE — it must win outright,
+    // not merely fill in when `file_path` happens to be absent. kimi-cli's file
+    // tools carry no `file_path` field at all (src/kimi_cli/tools/file/write.py,
+    // replace.py, @ 4a550ef — the SHA #2547 pins), and soul/toolset.py hands the
+    // model's raw json-parsed
+    // arguments to PreToolUse verbatim, doing typed validation only later inside
+    // tool.call() — after the hook has already decided. So a `file_path` in a
+    // Kimi payload is ALWAYS model-supplied, and under the old `=== undefined`
+    // condition it SHADOWED the field kimi-cli actually executes on. A payload
+    // pairing a cross-root `path` with a spurious `file_path: ""` left every
+    // guard reading an empty string and exiting 0, while the identical write
+    // without the extra key blocked — a bypass needing no crash at all. The same
+    // shadowing also preserved a NON-STRING `file_path` (`[]`), which threw
+    // inside gsd-worktree-path-guard's path.isAbsolute() and reached its outer
+    // `catch { process.exit(0) }`: the same crash-to-allow this fix closes
+    // elsewhere, reached through the guard's own read rather than through
+    // normalization. Overwriting can only ever narrow what a guard inspects to
+    // the path that will actually be written, so it cannot under-block.
+    if (typeof input.path === 'string') {
+      input.file_path = input.path;
+    }
+    const edits = Array.isArray(input.edit) ? input.edit
+      : (input.edit && typeof input.edit === 'object') ? [input.edit] : [];
+    if (edits.length) {
+      // #2547: `e?.old`, not `e.old` — `??` guards the value, not the
+      // dereference, so a NULLISH entry (`edit: [null]`) threw a TypeError
+      // here. normalizeKimiPayload runs before any tool dispatch, so that throw
+      // reached each guard's outer `catch { process.exit(0) }` and silently
+      // downgraded a should-BLOCK call into an allow. (A string/number entry
+      // never threw — `('x').old` is a legal read yielding undefined.)
+      //
+      // The String() coercion is guarded for the same reason: `{"toString":
+      // null}` is valid JSON that throws "Cannot convert object to primitive
+      // value", which is the identical crash-to-allow with a different
+      // trigger. Degrading only the non-coercible entry to '' keeps
+      // stringification intact for every value that CAN coerce (numbers,
+      // arrays, plain objects), so nothing downstream — including
+      // gsd-prompt-guard's scan of new_string — loses content it saw before.
+      const editText = (v) => { try { return String(v ?? ''); } catch { return ''; } };
+      // #2595 (review Major 2): reconstruct UNCONDITIONALLY, mirroring the
+      // `path` decision above rather than merely filling in when the field
+      // happens to be absent. kimi-cli's StrReplaceFile schema is `path` +
+      // `edit` only (src/kimi_cli/tools/file/replace.py @ 4a550ef) — it carries
+      // no `old_string`/`new_string` at all, so either field appearing in a
+      // Kimi payload is ALWAYS model-supplied, exactly like `file_path`. Under
+      // the old `=== undefined` condition a model-supplied `new_string: ""`
+      // SHADOWED the reconstruction, leaving gsd-prompt-guard's injection scan
+      // reading '' and exiting at its `if (!content)` before it ever saw the
+      // real `edit[].new` — a one-key bypass of the very scan this fix's
+      // guarded coercion exists to keep fed. A `typeof` test would NOT close
+      // it: a benign non-empty string shadows just as effectively as ''.
+      input.old_string = edits.map((e) => editText(e?.old)).join('\n');
+      input.new_string = edits.map((e) => editText(e?.new)).join('\n');
+    }
+  }
+  return data;
+}
+
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
@@ -85,7 +179,7 @@ process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
   clearTimeout(stdinTimeout);
   try {
-    const data = JSON.parse(input);
+    const data = normalizeKimiPayload(JSON.parse(input));
     const toolName = data.tool_name;
     const cwd = data.cwd || process.cwd();
     const isWorkflowGuardEnabled = workflowGuardEnabled(cwd);
@@ -97,12 +191,15 @@ process.stdin.on('end', () => {
       const command = data.tool_input?.command || '';
       for (const gitCwd of forceGitAddCwds(command, cwd)) {
         const branch = currentBranch(gitCwd);
-        if (branch.startsWith('worktree-agent-')) {
-          process.stdout.write(JSON.stringify({
+        if (/^(worktree-)?agent-/.test(branch)) {
+          const output = {
             decision: 'block',
             code: 'WORKTREE_AGENT_FORCE_ADD_FORBIDDEN',
-            reason: 'worktree-agent branches must not run git add -f or git add --force. Respect the SDK skipped_gitignored/skipped_commit_docs_false contract and leave gitignored files untracked.',
-          }));
+            reason: 'agent/worktree-agent branches must not run git add -f or git add --force. Respect the SDK skipped_gitignored/skipped_commit_docs_false contract and leave gitignored files untracked.',
+          };
+          process.stdout.write(JSON.stringify(output));
+          // Kimi CLI's exit-2 protocol feeds stderr back to the model (#2304)
+          process.stderr.write(output.reason);
           process.exit(2);
         }
       }
@@ -122,7 +219,14 @@ process.stdin.on('end', () => {
     }
 
     // Check the file being edited
-    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+    // #2595 (review Major 3, sibling sweep): typed read on BOTH fields. The
+    // `&& value` keeps the original truthiness fallback intact — an empty
+    // file_path must still fall through to `path`, which a bare typeof test
+    // would have broken.
+    const filePath =
+      (typeof data.tool_input?.file_path === 'string' && data.tool_input.file_path) ||
+      (typeof data.tool_input?.path === 'string' && data.tool_input.path) ||
+      '';
 
     // Allow edits to .planning/ files (GSD state management)
     if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {