@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -34,6 +34,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = void 0;
+exports.isRegisteredRuntimeId = isRegisteredRuntimeId;
 exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
 exports.detectAntigravityDirAmbiguity = detectAntigravityDirAmbiguity;
@@ -48,15 +50,36 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
 /**
- * Expand a leading ~ to os.homedir().
+ * Expand a leading ~ to the given home directory (defaults to os.homedir()).
+ * Every call site inside resolveConfigHomeFromDescriptor threads its
+ * resolved `home` local through here so an injected opts.home (used by
+ * hermetic tests) is honored instead of silently falling back to the real
+ * home directory.
  */
-function expandTilde(p) {
+function expandTilde(p, home = node_os_1.default.homedir()) {
     if (!p)
         return p;
     if (p.startsWith('~/') || p === '~')
-        return node_path_1.default.join(node_os_1.default.homedir(), p.slice(1));
+        return node_path_1.default.join(home, p.slice(1));
     return p;
 }
+/**
+ * True when `val` is a usable env-var override: a real string that contains
+ * at least one non-whitespace character. Every env-override consumption site
+ * in resolveConfigHomeFromDescriptor gates on this instead of a bare truthy
+ * check, so `FOO_DIR=''` (empty), `FOO_DIR` unset (`undefined`), and
+ * `FOO_DIR='   '` (whitespace-only — e.g. from a shell templating bug that
+ * leaves a variable substitution blank but quoted) all fall back to the
+ * descriptor default identically. Deliberately does NOT trim: a value that
+ * merely has leading/trailing whitespace around otherwise-real content (or
+ * interior whitespace, e.g. `~/My Agent Dir`) is passed through byte-for-byte
+ * unchanged, exactly as this module already treats every other env-var
+ * override (no site here or elsewhere in this file trims a path value) — so
+ * default behavior for every non-whitespace value is unaffected by this guard.
+ */
+function hasNonBlankOverride(val) {
+    return typeof val === 'string' && val.trim() !== '';
+}
 function resolveDescriptorWithOptions(configHome) {
     return resolveConfigHomeFromDescriptor(configHome, {
         env: process.env,
@@ -68,6 +91,64 @@ function getRegistry() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return require('./capability-registry.cjs');
 }
+/**
+ * Legacy runtime ids that have a genuine, dedicated resolution branch
+ * elsewhere in this module but no capability-registry descriptor (#3024
+ * review BLOCKER, finding 1).
+ *
+ * `isRegisteredRuntimeId`'s real contract is "does this id resolve to a
+ * real, runtime-specific path?", not "is it a key in the registry map" —
+ * registry membership is only a proxy for that, and the proxy is wrong for
+ * `grok`: `getGlobalConfigDir` has a live hardcoded branch for it (`~/.agents`,
+ * overridable via `GROK_AGENTS_HOME`), predating the capability-registry
+ * descriptor system, and it is documented end-user-facing surface
+ * (pre-fix `gsd-core/workflows/sync-skills.md` listed it explicitly, and
+ * `docs/discussions/grok-build-support-2026-05.md` records the support
+ * decision). Rejecting it here would silently remove working, documented
+ * `--skills-root`/`sync-skills` support for a runtime that never regressed.
+ *
+ * This set is enumerated by hand, not derived, and MUST stay in lockstep
+ * with `getGlobalConfigDir`'s hardcoded branches: as of #3024, `grok` is
+ * the ONLY id in this position (verified by reading the full function body
+ * — every other unregistered id there falls through to the claude
+ * fallback, which is the behavior this validator exists to reject). Do
+ * NOT add an id here just because it "should" work — add it only after
+ * confirming `getGlobalConfigDir` has a real dedicated branch for it, the
+ * way `grok`'s is confirmed above. Do not "clean this up" by removing it;
+ * that is exactly the regression this constant guards against.
+ */
+exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = new Set(['grok']);
+/**
+ * True when `runtime` is a real runtime id with a genuine, runtime-specific
+ * resolution path — either a registered id in the capability registry
+ * (`capability-registry.cjs`'s `runtimes` object) or one of the small,
+ * explicitly named `LEGACY_NON_REGISTRY_RUNTIME_IDS` set (currently just
+ * `grok`) that resolves via a dedicated hardcoded branch instead of a
+ * registry descriptor.
+ *
+ * Guarded with an own-property lookup — never a bare index — so a
+ * prototype-chain id (`__proto__`, `constructor`, `prototype`, `toString`,
+ * …) can never resolve to an inherited value and be mistaken for a real
+ * entry. Without this, `getGlobalSkillsBase`/`getGlobalConfigDir`'s bare
+ * `runtimes[runtime]` lookups fall through the prototype chain for those
+ * ids, find no usable descriptor, and silently resolve to claude's
+ * fallback path instead of failing loudly (#3024).
+ *
+ * Single shared validator for every `--skills-root` entry point
+ * (`gsd-tools query skills-root`'s `routeSkillsRoot`, `install.js
+ * --skills-root`) so the two surfaces can never diverge on which runtime
+ * ids they accept.
+ */
+function isRegisteredRuntimeId(runtime) {
+    if (typeof runtime !== 'string')
+        return false;
+    const trimmed = runtime.trim();
+    if (!trimmed)
+        return false;
+    if (Object.prototype.hasOwnProperty.call(getRegistry().runtimes, trimmed))
+        return true;
+    return exports.LEGACY_NON_REGISTRY_RUNTIME_IDS.has(trimmed);
+}
 /**
  * Resolve a configHome descriptor to an absolute directory path.
  *
@@ -86,16 +167,16 @@ function resolveConfigHomeFromDescriptor(configHome, opts = {}) {
             // First env var that is set wins
             for (const varName of configHome.env) {
                 const val = env[varName];
-                if (val)
-                    return expandTilde(val);
+                if (hasNonBlankOverride(val))
+                    return expandTilde(val, home);
             }
             return node_path_1.default.join(home, configHome.name);
         }
         case 'dot-home-nested': {
             // env override
             const nestedEnv0Val = env[configHome.env[0]];
-            if (configHome.env[0] && nestedEnv0Val) {
-                return expandTilde(nestedEnv0Val);
+            if (configHome.env[0] && hasNonBlankOverride(nestedEnv0Val)) {
+                return expandTilde(nestedEnv0Val, home);
             }
             const base = node_path_1.default.join(home, configHome.parent);
             if (configHome.probe && configHome.probe.length > 0) {
@@ -127,49 +208,50 @@ function resolveConfigHomeFromDescriptor(configHome, opts = {}) {
         case 'xdg': {
             // env[0]: direct override dir
             const xdgEnv0Val = env[configHome.env[0]];
-            if (configHome.env[0] && xdgEnv0Val) {
-                return expandTilde(xdgEnv0Val);
+            if (configHome.env[0] && hasNonBlankOverride(xdgEnv0Val)) {
+                return expandTilde(xdgEnv0Val, home);
             }
             // env[1]: FILE path → dirname
             const xdgEnv1Val = env[configHome.env[1]];
-            if (configHome.env[1] && xdgEnv1Val) {
-                return node_path_1.default.dirname(expandTilde(xdgEnv1Val));
+            if (configHome.env[1] && hasNonBlankOverride(xdgEnv1Val)) {
+                return node_path_1.default.dirname(expandTilde(xdgEnv1Val, home));
             }
             // env[2]: XDG_CONFIG_HOME → subdir
             const xdgEnv2Val = env[configHome.env[2]];
-            if (configHome.env[2] && xdgEnv2Val) {
-                return node_path_1.default.join(expandTilde(xdgEnv2Val), configHome.name);
+            if (configHome.env[2] && hasNonBlankOverride(xdgEnv2Val)) {
+                return node_path_1.default.join(expandTilde(xdgEnv2Val, home), configHome.name);
             }
             return node_path_1.default.join(home, '.config', configHome.name);
         }
         case 'generic-agents-root': {
             // env override
             const garEnv0Val = env[configHome.env[0]];
-            if (configHome.env[0] && garEnv0Val) {
-                return expandTilde(garEnv0Val);
+            if (configHome.env[0] && hasNonBlankOverride(garEnv0Val)) {
+                return expandTilde(garEnv0Val, home);
             }
             // probe each candidate; return first where probeExists subpath exists
             for (const candidate of configHome.probe) {
-                const resolved = expandTildeWithHome(candidate, home);
+                const resolved = expandTilde(candidate, home);
                 if (existsSyncFn(node_path_1.default.join(resolved, configHome.probeExists))) {
                     return resolved;
                 }
             }
             // fallback: first probe candidate
-            return expandTildeWithHome(configHome.probe[0], home);
+            return expandTilde(configHome.probe[0], home);
+        }
+        case 'none': {
+            // #2103: no file-projected config directory exists for this runtime
+            // (e.g. vscode). Previously this kind had no matching case, so the
+            // switch fell through and implicitly returned `undefined` — which
+            // then crashed a downstream `path.join(undefined, ...)` with a
+            // cryptic `TypeError [ERR_INVALID_ARG_TYPE]` far from the real cause.
+            // Throwing here makes the failure mode explicit; callers that need a
+            // nullable result (getGlobalSkillsBase) check `configHome.kind` and
+            // short-circuit BEFORE ever reaching this function.
+            throw new Error(`Runtime "${configHome.name}" has no config-home directory (configHome.kind === "none")`);
         }
     }
 }
-/**
- * Expand ~ using an explicit home directory (for hermetic testing).
- */
-function expandTildeWithHome(p, home) {
-    if (!p)
-        return p;
-    if (p.startsWith('~/') || p === '~')
-        return node_path_1.default.join(home, p.slice(1));
-    return p;
-}
 /**
  * Resolve Antigravity global config dir across 1.x and 2.x layouts.
  *
@@ -257,25 +339,45 @@ function resolveKimiGlobalDir(opts = {}) {
     }, { env, home, existsSync: existsSyncFn });
 }
 /**
- * Resolve the directory holding Kimi CLI's OWN native config.toml (the file
- * Kimi itself reads for providers/models/hooks/etc — see
- * moonshotai.github.io/kimi-cli/en/configuration/data-locations.html and
- * .../reference/kimi-command.html). Default `~/.kimi`, overridden by
- * `KIMI_SHARE_DIR` per Kimi's own upstream env-var (NOT `KIMI_CONFIG_DIR`,
- * which is a GSD-installer write-location override for the unrelated generic
- * Agent-Skills root resolved by resolveKimiGlobalDir above).
+ * Resolve the directory holding the Kimi product's OWN native config.toml —
+ * the file that product itself reads for providers/models/hooks/etc, and the
+ * one GSD writes its `[[hooks]]` block, hooks bundle and CommonJS marker into.
+ *
+ * The two Kimi runtimes share `hooksSurface: "kimi-hooks-toml"` but are
+ * different products with different roots, and this must be selected by
+ * `runtime` (#2755). Before that fix this function was unparameterized and a
+ * `--kimi-code` install wrote its hooks into Kimi CLI's `~/.kimi`, leaving Kimi
+ * Code with none:
+ *
+ *   kimi       → `~/.kimi`,      overridden by `KIMI_SHARE_DIR`
+ *                (moonshotai.github.io/kimi-cli/en/configuration/data-locations.html)
+ *   kimi-code  → `~/.kimi-code`, overridden by `KIMI_CODE_HOME`
+ *                (moonshotai/kimi-code docs/en/configuration/data-locations.md;
+ *                 its hooks doc places `[[hooks]]` in `~/.kimi-code/config.toml`)
  *
- * This is deliberately a SEPARATE directory from GSD's kimi configHome
- * (~/.config/agents): Kimi's own docs confirm the Agent-Skills search path is
- * independent of KIMI_SHARE_DIR ("This variable does not affect Agent Skills
- * search paths, which are handled separately"). #2095 Upgrade 1 writes GSD's
- * native [[hooks]] entries into `<this dir>/config.toml`, never into the
- * skills configDir.
+ * Each product's env var is scoped to that product: `KIMI_SHARE_DIR` is Kimi
+ * CLI's own upstream variable and must NOT redirect kimi-code, nor vice versa.
+ *
+ * An unrecognised `runtime` (and an omitted one) falls back to `~/.kimi`, which
+ * preserves the pre-#2755 behaviour for every existing caller that passes no
+ * runtime — this function is exported, so that default is a contract.
+ *
+ * For BOTH runtimes this is deliberately a SEPARATE directory from the generic
+ * Agent-Skills root resolved by `resolveKimiGlobalDir` (`~/.config/agents`):
+ * both vendors' docs confirm the Agent-Skills search path is independent of the
+ * data-root env var. GSD's native `[[hooks]]` entries go in
+ * `<this dir>/config.toml`, never into the skills configDir.
  */
 function resolveKimiHooksTomlDir(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? node_os_1.default.homedir();
-    return resolveConfigHomeFromDescriptor({ kind: 'dot-home', name: '.kimi', env: ['KIMI_SHARE_DIR'] }, { env, home });
+    // Explicit comparison rather than an object lookup keyed on `runtime`: the
+    // value originates from argv, and an index would resolve inherited keys
+    // (`constructor`, `__proto__`) to something that is not a descriptor.
+    const descriptor = opts.runtime === 'kimi-code'
+        ? { kind: 'dot-home', name: '.kimi-code', env: ['KIMI_CODE_HOME'] }
+        : { kind: 'dot-home', name: '.kimi', env: ['KIMI_SHARE_DIR'] };
+    return resolveConfigHomeFromDescriptor(descriptor, { env, home });
 }
 /**
  * Return the global config base directory for the given runtime.
@@ -317,6 +419,17 @@ function resolveSkillsBaseFromDescriptor(configHome, opts = {}, skillsDestSubpat
 function getGlobalSkillsBase(runtime) {
     const runtimeEntry = getRegistry().runtimes[runtime];
     const descriptor = runtimeEntry?.runtime;
+    // #2103: a runtime with `configHome.kind === 'none'` (e.g. vscode —
+    // Marketplace/VSIX extension, installSurface:'none') has no file-projected
+    // config directory at all, and therefore no skills root. Short-circuit to
+    // null BEFORE falling through to getGlobalConfigDir below, which would
+    // otherwise throw resolving a 'none' configHome (see
+    // resolveConfigHomeFromDescriptor's 'none' case). null is the correct
+    // answer here, not a crash — the `=== null` guard at every call site
+    // (bin/install.js --skills-root, gsd-tools routeSkillsRoot) already
+    // handles it as "this runtime does not use a skills directory".
+    if (descriptor?.configHome?.kind === 'none')
+        return null;
     const globalSkillsKind = descriptor?.artifactLayout?.global?.find((entry) => entry.kind === 'skills');
     // ADR-1239 upgrade 3 (#2088): honor a skills-kind `home` override (e.g. Codex
     // → $HOME/.agents/skills, independent of $CODEX_HOME) so the reported skills

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -28,6 +28,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+// #2544: the single source of truth for the CommonJS module-type marker. The
+// two helpers below are thin boolean-returning shims over these — see the
+// marker section for why this file no longer carries its own copy.
+const commonjs_marker_cjs_1 = require("./commonjs-marker.cjs");
 const imperative_hook_bus_cjs_1 = require("./host-integration-adapters/imperative-hook-bus.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCmdProjection = require("./shell-command-projection.cjs");
@@ -166,62 +170,51 @@ function atomicWriteFileSync(target, data, options) {
 //
 // The marker content is byte-identical to installSharedHooksBundle's
 // (bin/install.js installSharedHooksBundle): {"type":"commonjs"}\n.
+//
+// #2544: the two helpers below no longer carry their own copy of the write and
+// remove rules — they DELEGATE to src/commonjs-marker.cts, which #2544 makes the
+// single place both rules are enforced. Keeping a second copy here was not
+// merely redundant; the copies had drifted apart on exactly the two properties
+// that matter:
+//
+//   - ownership probe: `fs.existsSync` FOLLOWS symlinks and reports `false` for
+//     a DANGLING one, so a dangling `package.json` symlink classified as absent
+//     and the write below followed the link outside the directory GSD owns.
+//     `classifyMarker` uses `lstat` + `isFile()`, so a symlink or a directory at
+//     the marker path is classified `foreign` and left strictly alone.
+//   - create: a plain `writeFileSync` leaves the classify->write window open.
+//     `ensureCommonJsMarker` creates with `flag: 'wx'` (O_EXCL), so anything
+//     that appears at the path in between fails with EEXIST instead of being
+//     followed or overwritten.
+//
+// The exported signatures are unchanged (both still return a boolean), so every
+// caller and the #2717 tests are unaffected.
 // ---------------------------------------------------------------------------
-/** The exact marker content GSD writes, matching installSharedHooksBundle. */
-const COMMONJS_MARKER_CONTENT = '{"type":"commonjs"}\n';
 /**
  * Ensure a `package.json` forcing CommonJS mode exists in `dir` (the directory
  * holding GSD-staged `.js` hook scripts). Idempotent: a no-op if the marker is
- * already present with GSD's content. Overwrites only when the file is absent
- * or already carries GSD's exact marker — it never clobbers a distinct
- * user-authored package.json (it leaves such a file in place; the user owns it).
+ * already present with GSD's content. Never clobbers a distinct user-authored
+ * package.json (it leaves such a file in place; the user owns it).
  *
  * @param dir - absolute path to the directory holding the staged .js hooks
- * @returns `true` if the marker is present after the call (written or already there)
+ * @returns `true` if GSD's marker is present after the call (written or already there)
  */
 function ensureCommonJsMarker(dir) {
-    const markerPath = node_path_1.default.join(dir, 'package.json');
-    try {
-        if (node_fs_1.default.existsSync(markerPath)) {
-            const existing = node_fs_1.default.readFileSync(markerPath, 'utf8');
-            // Already GSD's marker (tolerant of trailing-whitespace variants) — done.
-            if (existing.trim() === '{"type":"commonjs"}')
-                return true;
-            // A distinct package.json the user owns — do NOT clobber. The hook will
-            // load as whatever type the user declared; that is the user's choice.
-            return false;
-        }
-        node_fs_1.default.writeFileSync(markerPath, COMMONJS_MARKER_CONTENT);
-        return true;
-    }
-    catch {
-        // Best-effort: a marker write failure must not fail the whole install.
-        return false;
-    }
+    // 'written' | 'unchanged' -> the marker is ours and present.
+    // 'preserved-foreign'     -> a file GSD does not own is there; left untouched.
+    // 'failed'                -> environmental (EACCES/EROFS/ENOSPC); best-effort.
+    const outcome = (0, commonjs_marker_cjs_1.ensureCommonJsMarker)(dir);
+    return outcome === 'written' || outcome === 'unchanged';
 }
 /**
  * Remove the CommonJS marker from `dir` on uninstall — but ONLY if it carries
  * GSD's exact marker content. A user-authored package.json is never deleted.
- * Mirrors the kimi uninstall guard in bin/install.js.
  *
  * @param dir - absolute path to the directory that held the staged .js hooks
  * @returns `true` if a GSD-owned marker was removed
  */
 function removeCommonJsMarkerIfGsdOwned(dir) {
-    const markerPath = node_path_1.default.join(dir, 'package.json');
-    try {
-        if (!node_fs_1.default.existsSync(markerPath))
-            return false;
-        const content = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
-        if (content === '{"type":"commonjs"}') {
-            node_fs_1.default.unlinkSync(markerPath);
-            return true;
-        }
-        return false;
-    }
-    catch {
-        return false;
-    }
+    return (0, commonjs_marker_cjs_1.removeCommonJsMarker)(dir);
 }
 // ---------------------------------------------------------------------------
 // parseTomlValue + findMultilineBasicStringClose
@@ -1072,7 +1065,15 @@ function writeCursorHooksJson(targetDir, src, opts) {
     // installSharedHooksBundle (the only other writer of this marker); without
     // it, a ~/.cursor/package.json declaring {"type":"module"} makes Node load
     // these require()-using scripts as ESM and every Cursor hook fails silently.
-    ensureCommonJsMarker(hooksDir);
+    //
+    // #2544: gated on having actually staged a script, mirroring
+    // installSharedHooksBundle's `stagedHooks` gate. hooks/ is shared space, and
+    // this function mkdirs it unconditionally — so an ungated write drops a GSD
+    // marker into a directory GSD created but did not fill, which is the same
+    // write-into-someone-else's-territory this issue is about.
+    if (installedScripts.size > 0) {
+        ensureCommonJsMarker(hooksDir);
+    }
     const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
     const commands = {};
     for (const ev of events) {
@@ -1266,7 +1267,12 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
     // installSharedHooksBundle (the only other writer of this marker); without
     // it, a config-root package.json declaring {"type":"module"} makes Node load
     // these require()-using scripts as ESM and the Windsurf hooks fail silently.
-    ensureCommonJsMarker(hooksDir);
+    //
+    // #2544: gated on having actually staged a script — see the identical gate in
+    // the Cursor writer above and `stagedHooks` in installSharedHooksBundle.
+    if (installedScripts.size > 0) {
+        ensureCommonJsMarker(hooksDir);
+    }
     const hookOpts = { runtime: 'windsurf', platform: opts.platform || process.platform };
     const commands = {};
     for (const ev of WINDSURF_HOOK_EVENTS) {
@@ -1597,6 +1603,63 @@ function applySettingsJsonHooks(settings, opts) {
         else if (!hasWorktreePathGuardHook && !node_fs_1.default.existsSync(worktreePathGuardFile)) {
             console.warn(`  ${yellow}⚠${reset}  Skipped worktree path guard hook — gsd-worktree-path-guard.js not found at target`);
         }
+        // Configure PreToolUse hook for Agent-dispatch isolation (#3045)
+        // Hard-blocks an executor Agent() dispatch (subagent_type="gsd-executor")
+        // missing its harness isolation parameter when this project's resolved
+        // dispatch isolation is harness-worktree. Prevents the executor from
+        // silently running and committing in the primary checkout when the
+        // model-authored dispatch omits isolation="worktree".
+        const agentIsolationGuardCommand = isGlobal
+            ? buildHookCommand(targetDir, 'gsd-agent-isolation-guard.js', hookOpts)
+            : localCmd('gsd-agent-isolation-guard.js');
+        const hasAgentIsolationGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-agent-isolation-guard')));
+        const agentIsolationGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-agent-isolation-guard.js');
+        if (!hasAgentIsolationGuardHook && node_fs_1.default.existsSync(agentIsolationGuardFile) && agentIsolationGuardCommand) {
+            settings.hooks[preToolEvent].push({
+                // #3045 MAJOR 1: widened from "Agent"-only — hooks.json's own
+                // PostToolUse precedent (context-monitor) already hedges both names,
+                // and the hook itself now accepts tool_name "Task" too.
+                matcher: 'Agent|Task',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: agentIsolationGuardCommand,
+                        timeout: 5
+                    }
+                ]
+            });
+            console.log(`  ${green}✓${reset} Configured agent isolation dispatch guard hook`);
+        }
+        else if (!hasAgentIsolationGuardHook && !node_fs_1.default.existsSync(agentIsolationGuardFile)) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped agent isolation guard hook — gsd-agent-isolation-guard.js not found at target`);
+        }
+        // Configure PreToolUse hook for catastrophic-shrink protection (#2255, fix 3 of #973)
+        // Hard-blocks a whole-file Write that collapses a curated .planning/ artifact
+        // (ROADMAP.md, milestone roadmaps, STATE.md) far below its on-disk size.
+        // Escape hatches (both named in the block message): the single-use
+        // sentinel .planning/.gsd-allow-shrink (workflow steps — a per-step env
+        // cannot reach a hook) and GSD_ALLOW_PLANNING_SHRINK=1 (interactive).
+        const writeGuardCommand = isGlobal
+            ? buildHookCommand(targetDir, 'gsd-write-guard.js', hookOpts)
+            : localCmd('gsd-write-guard.js');
+        const hasWriteGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-write-guard')));
+        const writeGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-write-guard.js');
+        if (!hasWriteGuardHook && node_fs_1.default.existsSync(writeGuardFile) && writeGuardCommand) {
+            settings.hooks[preToolEvent].push({
+                matcher: 'Write',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: writeGuardCommand,
+                        timeout: 5
+                    }
+                ]
+            });
+            console.log(`  ${green}✓${reset} Configured write guard hook (catastrophic-shrink protection)`);
+        }
+        else if (!hasWriteGuardHook && !node_fs_1.default.existsSync(writeGuardFile)) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped write guard hook — gsd-write-guard.js not found at target`);
+        }
         // Configure commit validation hook (Conventional Commits enforcement, opt-in)
         const validateCommitCommand = isGlobal
             ? buildHookCommand(targetDir, 'gsd-validate-commit.sh', hookOpts)
@@ -1925,6 +1988,7 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { event: 'PreToolUse', command: cmd('gsd-prompt-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-read-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-worktree-path-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
+        { event: 'PreToolUse', command: cmd('gsd-write-guard.js'), matcher: 'WriteFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-workflow-guard.js'), matcher: 'Shell|WriteFile|StrReplaceFile', timeout: 5 },
         { event: 'PreToolUse', command: cmd('gsd-validate-commit.sh'), matcher: 'Shell', timeout: 5 },
         // PostToolUse