@opengsd/gsd-core 1.12.0 → 1.14.0

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

@@ -459,9 +459,18 @@ function normalizeNodePath(execPath, opts) {
     // survives the upgrade. Derive <prefix> from the path itself (more reliable
     // than HOMEBREW_PREFIX env — the path IS the install location) so every layout
     // is covered by one branch instead of one per known prefix (#2185).
+    //
+    // #4137: rewrite only when the symlink exists; otherwise fall through to the
+    // raw execPath, exactly like the mise and volta branches. A keg-only/versioned
+    // formula (node@24 installed but never `brew link`ed) has no <prefix>/bin/node
+    // at all, so the unconditional rewrite handed every managed hook a path that
+    // fails at invocation — a rewrite must never turn a working keg path into an
+    // immediately broken one.
     const homebrewMatch = normalizedForMatch.match(/^(.+)\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/i);
     if (homebrewMatch) {
-        return `${homebrewMatch[1]}/bin/node${homebrewMatch[3] || ''}`;
+        const homebrewStable = `${homebrewMatch[1]}/bin/node${homebrewMatch[3] || ''}`;
+        if (existsSync(homebrewStable))
+            return homebrewStable;
     }
     // mise pins a concrete node version at <data>/installs/node/<ver>/bin/node
     // (Windows: <data>/installs/node/<ver>/node.exe). Node realpaths
@@ -802,16 +811,52 @@ function rewriteLegacyCodexHookBlock(content, absoluteRunner, opts) {
     });
     return { content: updated, changed };
 }
+function _installEngineSymlinkGuard() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const mod = require('./install-engine.cjs');
+    return mod;
+}
 function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const managedCommand = typeof opts.managedCommand === 'string' ? opts.managedCommand : null;
     const commandWindows = typeof opts.commandWindows === 'string' ? opts.commandWindows : null;
     const matcher = typeof opts.matcher === 'string' ? opts.matcher : undefined;
     const timeout = typeof opts.timeout === 'number' ? opts.timeout : undefined;
+    // #2586 Major 2: every Codex hooks.json writer funnels through this one
+    // function, and atomicWriteFileSync's final step is a rename(2) onto
+    // `hooksJsonPath` — which, when that path is a symlink, REPLACES the
+    // symlink with a plain file rather than writing through it. Refuse (with
+    // the same GSD_ALLOW_SYMLINKED_DEST opt-in every other install call site
+    // honors) before reading or writing, so a symlinked hooks.json is neither
+    // silently destroyed nor left the caller no escape hatch.
+    const symlinkGuard = _installEngineSymlinkGuard();
+    // The path this function actually reads/writes. Defaults to the nominal
+    // hooks.json path; reassigned below to the symlink's real target when the
+    // opt-in is active, so the write lands on the file the user's symlink
+    // points at instead of clobbering the symlink itself (see note below).
+    let effectiveHooksJsonPath = hooksJsonPath;
+    if (node_fs_1.default.existsSync(hooksJsonPath) && node_fs_1.default.lstatSync(hooksJsonPath).isSymbolicLink()) {
+        if (symlinkGuard.hasExistingSymlinkBetween(targetDir, hooksJsonPath, {
+            allowOptInFollow: symlinkGuard.isSymlinkedDestOptIn(),
+        })) {
+            throw new Error(`hooks.json at "${hooksJsonPath}" contains a symlink the install root "${targetDir}" does not trust — ` +
+                'refusing to read or write it. If this is an intentional user-owned symlink layout, re-run with ' +
+                'GSD_ALLOW_SYMLINKED_DEST=1.');
+        }
+        // hasExistingSymlinkBetween returned false only because the opt-in is
+        // active (a symlinked leaf always trips it otherwise) — so this IS a
+        // symlink and we are cleared to follow it. atomicWriteFileSync's final
+        // step is a rename(2) onto its target, which REPLACES an existing
+        // symlink at that path rather than writing through it; resolving to the
+        // real path here makes the read AND the write operate on the symlink's
+        // target, leaving the symlink itself untouched, matching what "follow"
+        // is supposed to mean.
+        effectiveHooksJsonPath = node_fs_1.default.realpathSync(hooksJsonPath);
+    }
     let parsed = {};
     let currentContent = null;
-    if (node_fs_1.default.existsSync(hooksJsonPath)) {
-        const raw = node_fs_1.default.readFileSync(hooksJsonPath, 'utf8');
+    if (node_fs_1.default.existsSync(effectiveHooksJsonPath)) {
+        const raw = node_fs_1.default.readFileSync(effectiveHooksJsonPath, 'utf8');
         currentContent = raw;
         if (raw.trim()) {
             try {
@@ -845,6 +890,12 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     }
     parsed['hooks'] = hookTable;
     const eventEntries = Array.isArray(hookTable[eventName]) ? hookTable[eventName] : [];
+    // Minor 5 (#2586 review): an event key the user already had, already
+    // holding an empty array, must survive removal as an empty array — not be
+    // deleted outright. Deleting is only correct when OUR removal is what
+    // emptied a previously non-empty array. Tracked before the loop below can
+    // mutate anything.
+    const wasArrayEmpty = Array.isArray(hookTable[eventName]) && eventEntries.length === 0;
     let removedLegacy = false;
     const sanitizedEntries = [];
     for (const entry of eventEntries) {
@@ -886,6 +937,11 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     if (sanitizedEntries.length > 0) {
         hookTable[eventName] = sanitizedEntries;
     }
+    else if (wasArrayEmpty) {
+        // Nothing of ours was ever here to remove — preserve the user's own
+        // empty array exactly as found (Minor 5).
+        hookTable[eventName] = [];
+    }
     else {
         delete hookTable[eventName];
     }
@@ -898,7 +954,7 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const changed = currentContent !== nextContent;
     const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
     if (shouldWrite) {
-        atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
+        atomicWriteFileSync(effectiveHooksJsonPath, nextContent, 'utf8');
     }
     return { changed: changed || removedLegacy, wrote: shouldWrite, path: hooksJsonPath };
 }
@@ -1015,6 +1071,136 @@ function removeCodexHooksJsonEvent(targetDir, eventName) {
 function removeCodexHooksJsonSessionStart(targetDir) {
     return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand: null });
 }
+// Literal, version-stable markers every shipped gsd-context-monitor.js
+// carries. Stable across the {{GSD_VERSION}} and runtime-path substitutions
+// the Codex copy step applies (#2586 design doc "Ownership check" — a raw
+// content hash would differ per runtime/version by construction, so a marker
+// check is used instead of manifest-membership, which has a bootstrap gap on
+// the exact case that matters most: a pre-#2586 install's manifest never
+// recorded this file at all).
+const CODEX_CONTEXT_MONITOR_OWNERSHIP_MARKERS = [
+    '#!/usr/bin/env node',
+    '// gsd-hook-version:',
+    '// Context Monitor - PostToolUse/AfterTool hook',
+];
+function isGsdOwnedCodexContextMonitorScript(filePath) {
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    // The .cmd shim (buildCodexHookWindowsShimIR) is a tiny generated batch
+    // wrapper, not the JS file itself — it never carries the JS markers above,
+    // so it gets its own narrower, still-specific signature: the exact
+    // "@ECHO OFF" / "@SETLOCAL" preamble the shim generator emits, invoking a
+    // script path that ends in gsd-context-monitor.js.
+    if (filePath.endsWith('.cmd')) {
+        return content.startsWith('@ECHO OFF') && content.includes('@SETLOCAL')
+            && /gsd-context-monitor\.js/.test(content);
+    }
+    return CODEX_CONTEXT_MONITOR_OWNERSHIP_MARKERS.every((marker) => content.includes(marker));
+}
+/**
+ * Scan every event in hooks.json for a surviving reference to the
+ * context-monitor script or its Windows .cmd shim, by basename — not scoped
+ * to CODEX_EXTENDED_HOOK_EVENTS, so a user who hand-registered it under an
+ * unrelated event key is still detected as "referenced" and the script is
+ * preserved.
+ */
+function hooksJsonReferencesCodexContextMonitor(targetDir) {
+    const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
+    if (!node_fs_1.default.existsSync(hooksJsonPath))
+        return false;
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(hooksJsonPath, 'utf8');
+    }
+    catch {
+        return true; // unreadable — conservatively assume referenced, never delete
+    }
+    if (!raw.trim())
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return true; // unparseable — conservatively assume referenced
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return false;
+    const hooks = parsed['hooks'];
+    const table = hooks && typeof hooks === 'object' && !Array.isArray(hooks)
+        ? hooks
+        : parsed;
+    for (const key of Object.keys(table)) {
+        const entries = table[key];
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const entryHooks = entry['hooks'];
+            const hookList = Array.isArray(entryHooks) ? entryHooks : [entry];
+            for (const hook of hookList) {
+                if (!hook || typeof hook !== 'object')
+                    continue;
+                const values = [
+                    hook['command'],
+                    hook['commandWindows'],
+                ];
+                for (const value of values) {
+                    if (typeof value === 'string' && /gsd-context-monitor(\.js|\.cmd)?/.test(value)) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * #2586 must-have #4/#8: after hooks.json registrations for
+ * CODEX_EXTENDED_HOOK_EVENTS have been reconciled away (by the caller, via
+ * removeCodexHooksJsonEvent), delete `hooks/gsd-context-monitor.js` and its
+ * `.cmd` shim ONLY when (a) no surviving hooks.json registration under ANY
+ * event still references either basename, and (b) the on-disk file carries
+ * GSD's own ownership markers (a user's hand-edited or unrelated file at that
+ * path is left alone). Each file is deleted independently — a failure
+ * deleting one is reported as a warning and never rolls back the (already
+ * safe, already-written) hooks.json deregistration the caller performed
+ * first.
+ */
+function cleanupOrphanedCodexContextMonitorScript(targetDir) {
+    const result = { deleted: [], warnings: [], stillReferenced: false };
+    if (hooksJsonReferencesCodexContextMonitor(targetDir)) {
+        result.stillReferenced = true;
+        return result;
+    }
+    const candidates = [
+        node_path_1.default.join(targetDir, 'hooks', 'gsd-context-monitor.js'),
+        node_path_1.default.join(targetDir, 'hooks', 'gsd-context-monitor.cmd'),
+    ];
+    for (const candidate of candidates) {
+        if (!node_fs_1.default.existsSync(candidate))
+            continue;
+        if (!isGsdOwnedCodexContextMonitorScript(candidate))
+            continue;
+        try {
+            node_fs_1.default.unlinkSync(candidate);
+            result.deleted.push(candidate);
+        }
+        catch (err) {
+            result.warnings.push({
+                path: candidate,
+                reason: err && err.message ? err.message : String(err),
+            });
+        }
+    }
+    return result;
+}
 function buildHookCommand(configDir, hookName, opts) {
     if (!opts)
         opts = {};
@@ -1311,6 +1497,128 @@ function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
     }
     return { changed: changed, wrote: shouldWrite, path: hooksJsonPath };
 }
+/**
+ * Stage the `hooks/lib/` helpers a set of staged hook scripts require, walking
+ * the require graph TRANSITIVELY to a fixed point.
+ *
+ * Extracted from writeCursorHooksJson (#3911 review, commit 704859e9c) so the
+ * reduced Codex hook bundle can share one implementation instead of growing a
+ * second, divergent copy (#4087 / #4098). Both reduced bundles hand-pick which
+ * hook SCRIPTS they ship, and neither can hand-pick their helpers correctly for
+ * long: `hooks/lib/hook-exit.js` requires `./cli-exit.js`, which requires
+ * `./exit-code-registry.js` — with NO `./lib/` prefix, because from inside
+ * `lib/` the sibling is already local. A single-pass scan for the `./lib/…`
+ * spelling used FROM a hook script stages hook-exit.js and stops, and the
+ * installed hook then dies on MODULE_NOT_FOUND at load, before its own
+ * try/catch, on every event it is registered for.
+ *
+ * Scans CONTENT rather than paths so a caller can seed from whatever it staged,
+ * transformed or not, without this helper knowing the caller's layout.
+ *
+ * @returns the lib filenames actually staged, in staging order.
+ */
+function stageTransitiveHookLibs(opts) {
+    const { seedSources, srcLibDir, destLibDir, runtimeLabel, transform } = opts;
+    const requiredLibFiles = new Set();
+    const scannedLibFiles = new Set();
+    const staged = [];
+    // `./X` means DIFFERENT things depending on where the scanned file lives, and
+    // conflating them stages the wrong file. From a hook SCRIPT in hooks/, a bare
+    // `./X` is a sibling hook-level artifact — Codex's gsd-check-update-worker.js
+    // requires `./managed-hooks-registry.cjs`, which lives in hooks/, not
+    // hooks/lib/ — so only the explicit `./lib/X` spelling is a lib requirement.
+    // From inside a LIB file, the sibling is already local, so `./X` IS a lib
+    // requirement (hook-exit.js -> ./cli-exit.js -> ./exit-code-registry.js); that
+    // is the case 704859e9c added and it must keep working. Cursor never exposed
+    // the difference because none of its staged scripts has a bare sibling
+    // require; Codex's does, and the fail-loud guard below caught it immediately
+    // by demanding managed-hooks-registry.cjs out of hooks/dist/lib.
+    // Fresh per call: a module-level /g regex carries lastIndex across calls and
+    // would silently skip matches on the second install in one process.
+    const seedRequireRe = /require\(\s*['"]\.\/lib\/([A-Za-z0-9._-]+)['"]\s*\)/g;
+    const libRequireRe = /require\(\s*['"]\.\/(?:lib\/)?([A-Za-z0-9._-]+)['"]\s*\)/g;
+    // A NESTED helper path is outside the flat layout hooks/lib/ has and the
+    // build emits, and the character classes above cannot express it — so it
+    // would be a SILENT miss, staging nothing and shipping a hook that dies at
+    // load. Detected separately and refused loudly instead: a silent miss is the
+    // failure mode this whole function exists to remove (review of #4087).
+    const nestedRequireRe = /require\(\s*['"]\.\/lib\/[A-Za-z0-9._-]+\/[^'"]*['"]\s*\)/;
+    const scanForLibRequires = (source, fromLib) => {
+        if (nestedRequireRe.test(source)) {
+            throw new Error(`A staged ${runtimeLabel} hook requires a NESTED hooks/lib path. hooks/lib/ is flat and `
+                + 'this stager only resolves flat helper names, so the nested helper would never be '
+                + 'staged and the hook would throw MODULE_NOT_FOUND at load. Flatten the helper or '
+                + 'extend this stager deliberately.');
+        }
+        const re = fromLib ? libRequireRe : seedRequireRe;
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const candidate = m[1];
+            // A capture with no alphanumeric character is not a module name — it is
+            // prose. This scan reads whole file text, comments included, and
+            // hooks/lib/injection-patterns.js's own header documents this mechanism
+            // with the literal string `require('./lib/...')`, which captures `...`
+            // and would send the resolver hunting for `hooks/lib/...` and fail the
+            // install (measured; that helper is not staged for either reduced bundle
+            // today, so it is latent rather than live).
+            //
+            // KNOWN LIMIT, disclosed rather than papered over: this does NOT make the
+            // scan comment-aware. A comment naming a REAL helper — `require(
+            // './lib/git-cmd.js')` in prose — still registers it and would over-stage
+            // that helper. Closing that needs a comment-stripping pass; the
+            // line-based stripper in scripts/lint-hooks-runtime-build-seam.cjs is the
+            // precedent (its header explains why the naive two-regex strip corrupts
+            // these very files), but promoting a lint-script helper into installer
+            // runtime code is a larger change than this fix.
+            if (!/[A-Za-z0-9]/.test(candidate))
+                continue;
+            requiredLibFiles.add(candidate);
+        }
+    };
+    for (const source of seedSources)
+        scanForLibRequires(source, false);
+    if (requiredLibFiles.size === 0)
+        return staged;
+    node_fs_1.default.mkdirSync(destLibDir, { recursive: true });
+    // Iterate to a fixed point: staging a lib file can add MORE required lib
+    // files (its own requires), which must themselves be staged and scanned.
+    let libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
+    while (libFile !== undefined) {
+        scannedLibFiles.add(libFile);
+        // Node's own extension resolution: `require('./lib/x')` is a valid, working
+        // CommonJS spelling today, and matching only the extension-bearing form
+        // resolved `x` literally, found nothing, and failed the install on a
+        // legitimate require (review of #4087). Try the bare name first so an
+        // extension-bearing capture still wins, then .js/.cjs.
+        let resolvedName;
+        for (const candidate of [libFile, `${libFile}.js`, `${libFile}.cjs`]) {
+            if (node_fs_1.default.existsSync(node_path_1.default.join(srcLibDir, candidate))) {
+                resolvedName = candidate;
+                break;
+            }
+        }
+        const libSrc = node_path_1.default.join(srcLibDir, resolvedName ?? libFile);
+        if (resolvedName === undefined) {
+            // FAIL LOUD. Skipping here would ship hook scripts whose top-level
+            // require() throws before their own try/catch, wedging every session —
+            // and the install would still exit 0, so nobody would know until a user
+            // hit it. A missing helper source is a packaging bug; surface it.
+            throw new Error(`hooks/lib/${libFile} is required by a staged ${runtimeLabel} hook but is missing from ${srcLibDir}. `
+                + 'Installing would ship a hook that throws MODULE_NOT_FOUND at load.');
+        }
+        let libContent = node_fs_1.default.readFileSync(libSrc, 'utf8');
+        if (transform)
+            libContent = transform(libContent);
+        // Written under its RESOLVED name so an extensionless require still lands a
+        // file Node can resolve at the destination.
+        node_fs_1.default.writeFileSync(node_path_1.default.join(destLibDir, resolvedName), libContent);
+        staged.push(resolvedName);
+        scanForLibRequires(libContent, true);
+        libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
+    }
+    return staged;
+}
 function writeCursorHooksJson(targetDir, src, opts) {
     opts = opts || {};
     const hooksDir = node_path_1.default.join(targetDir, 'hooks');
@@ -1348,43 +1656,13 @@ function writeCursorHooksJson(targetDir, src, opts) {
     // "./lib/X" requires, and every lib file staged is itself scanned for further
     // "./lib/X" OR bare "./X" (sibling-within-lib) requires, so the requirement
     // graph is derived to a fixed point instead of one hand-tuned level deep.
-    const requiredLibFiles = new Set();
-    const scannedLibFiles = new Set();
-    const libRequireRe = /require\(\s*['"]\.\/(?:lib\/)?([A-Za-z0-9._-]+)['"]\s*\)/g;
-    function scanForLibRequires(source) {
-        libRequireRe.lastIndex = 0;
-        let m;
-        while ((m = libRequireRe.exec(source)) !== null)
-            requiredLibFiles.add(m[1]);
-    }
-    for (const script of installedScripts) {
-        scanForLibRequires(node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8'));
-    }
-    if (requiredLibFiles.size > 0) {
-        const srcLibDir = node_path_1.default.join(srcHooksDir, 'lib');
-        const destLibDir = node_path_1.default.join(hooksDir, 'lib');
-        node_fs_1.default.mkdirSync(destLibDir, { recursive: true });
-        // Iterate to a fixed point: staging a lib file can add MORE required lib
-        // files (its own requires), which must themselves be staged and scanned.
-        let libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
-        while (libFile !== undefined) {
-            scannedLibFiles.add(libFile);
-            const libSrc = node_path_1.default.join(srcLibDir, libFile);
-            if (!node_fs_1.default.existsSync(libSrc)) {
-                // FAIL LOUD. Skipping here would ship hook scripts whose top-level
-                // require() throws before their own try/catch, wedging every session —
-                // and the install would still exit 0, so nobody would know until a user
-                // hit it. A missing helper source is a packaging bug; surface it.
-                throw new Error(`hooks/lib/${libFile} is required by a staged Cursor hook but is missing from ${srcLibDir}. `
-                    + 'Installing would ship a hook that throws MODULE_NOT_FOUND at load.');
-            }
-            let libContent = node_fs_1.default.readFileSync(libSrc, 'utf8');
-            libContent = libContent.replace(/gsd:/gi, 'gsd-');
-            node_fs_1.default.writeFileSync(node_path_1.default.join(destLibDir, libFile), libContent);
-            scanForLibRequires(libContent);
-            libFile = [...requiredLibFiles].find((f) => !scannedLibFiles.has(f));
-        }
-    }
+    stageTransitiveHookLibs({
+        seedSources: [...installedScripts].map((script) => node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8')),
+        srcLibDir: node_path_1.default.join(srcHooksDir, 'lib'),
+        destLibDir: node_path_1.default.join(hooksDir, 'lib'),
+        runtimeLabel: 'Cursor',
+        transform: (content) => content.replace(/gsd:/gi, 'gsd-'),
+    });
     // #2717: write the CommonJS marker into hooks/ alongside the staged .js
     // scripts. Cursor sets skipSharedHooksInstall, so it never reaches
     // installSharedHooksBundle (the only other writer of this marker); without
@@ -1587,6 +1865,26 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
             installedScripts.add(script);
         }
     }
+    // Stage the hooks/lib/ helpers these scripts require (#4087 review). Windsurf
+    // sets hostBehaviors.skipSharedHooksInstall, so like Cursor it never reaches
+    // installSharedHooksBundle — the only other stager of hooks/lib — and it was
+    // staging neither. Both Cascade guards require helpers at module load:
+    // gsd-windsurf-pre-write.js requires ./lib/hook-exit.js and ./lib/git-probe.js,
+    // gsd-windsurf-pre-command.js requires ./lib/hook-exit.js. Measured against a
+    // real `--windsurf --global` install before this call existed: the installer
+    // exited 0, hooks/ held only the two scripts, and running either one exited 1
+    // with "Cannot find module './lib/hook-exit.js'" — the same failure #4087
+    // reports for Codex, on every pre_write_code / pre_run_command event.
+    //
+    // The transform matches the one applied to the scripts above: a helper must be
+    // rewritten the same way as its caller or the two disagree on the spelling.
+    stageTransitiveHookLibs({
+        seedSources: [...installedScripts].map((script) => node_fs_1.default.readFileSync(node_path_1.default.join(hooksDir, script), 'utf8')),
+        srcLibDir: node_path_1.default.join(srcHooksDir, 'lib'),
+        destLibDir: node_path_1.default.join(hooksDir, 'lib'),
+        runtimeLabel: 'Windsurf',
+        transform: (content) => content.replace(/gsd:/gi, 'gsd-'),
+    });
     // #2717: write the CommonJS marker into hooks/ alongside the staged .js
     // scripts. Windsurf sets skipSharedHooksInstall, so it never reaches
     // installSharedHooksBundle (the only other writer of this marker); without
@@ -1737,6 +2035,37 @@ function applySettingsJsonHooks(settings, opts) {
         if (!settings.hooks.SessionStart) {
             settings.hooks.SessionStart = [];
         }
+        // #3981: Claude Code treats a timed-out hook as NON-blocking — the tool
+        // call continues through the normal permission flow. The blocking
+        // PreToolUse guards therefore need a budget a host stall cannot exceed,
+        // not one sized to the hook's own ~0.1 s runtime. Observed stalls reached
+        // 84.3 s; 120 s is the top of the issue's prescribed 60–120 range and
+        // returns every observed verdict. Registration below uses this constant,
+        // and the migration pass right here raises existing managed entries.
+        const BLOCKING_GUARD_TIMEOUT_S = 120;
+        const blockingGuardNames = [
+            'gsd-prompt-guard',
+            'gsd-workflow-guard',
+            'gsd-worktree-path-guard',
+            'gsd-agent-isolation-guard',
+            'gsd-write-guard',
+            'gsd-secret-read-guard',
+            'gsd-validate-commit',
+        ];
+        for (const entries of Object.values(settings.hooks)) {
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                if (!entry || !Array.isArray(entry.hooks))
+                    continue;
+                for (const h of entry.hooks) {
+                    if (blockingGuardNames.some((name) => referencesHook(h, name)) &&
+                        h.timeout === 5) {
+                        h.timeout = BLOCKING_GUARD_TIMEOUT_S;
+                    }
+                }
+            }
+        }
         const hasGsdUpdateHook = settings.hooks.SessionStart.some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-check-update')));
         // Guard: only register if the hook file was actually installed (#1754).
         // When hooks/dist/ is missing from the npm package (as in v1.32.0), the
@@ -1817,7 +2146,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: promptGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1894,7 +2223,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: workflowGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1919,7 +2248,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: worktreePathGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1949,7 +2278,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: agentIsolationGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1976,7 +2305,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: writeGuardCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -1985,6 +2314,33 @@ function applySettingsJsonHooks(settings, opts) {
         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 PreToolUse hook for secret-file read protection (#4221).
+        // Hard-blocks Read/Grep/Bash reads of .env, .env.<suffix> and .secrets.
+        // Replaces the Read(.env*) permission deny rules the installer used to
+        // write (#768): on Claude Code >= 2.1.259 ANY Read() deny rule makes every
+        // `cd DIR && grep …` compound prompt for approval, even in auto mode; a
+        // hook denial is not a permission rule and never arms that check.
+        const secretReadGuardCommand = isGlobal
+            ? buildHookCommand(targetDir, 'gsd-secret-read-guard.js', hookOpts)
+            : localCmd('gsd-secret-read-guard.js');
+        const hasSecretReadGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-secret-read-guard')));
+        const secretReadGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-secret-read-guard.js');
+        if (!hasSecretReadGuardHook && node_fs_1.default.existsSync(secretReadGuardFile) && secretReadGuardCommand) {
+            settings.hooks[preToolEvent].push({
+                matcher: 'Read|Grep|Bash',
+                hooks: [
+                    {
+                        type: 'command',
+                        command: secretReadGuardCommand,
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
+                    }
+                ]
+            });
+            console.log(`  ${green}✓${reset} Configured secret read guard hook (.env / .secrets read protection)`);
+        }
+        else if (!hasSecretReadGuardHook && !node_fs_1.default.existsSync(secretReadGuardFile)) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped secret read guard hook — gsd-secret-read-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)
@@ -2001,7 +2357,7 @@ function applySettingsJsonHooks(settings, opts) {
                     {
                         type: 'command',
                         command: validateCommitCommand,
-                        timeout: 5
+                        timeout: BLOCKING_GUARD_TIMEOUT_S
                     }
                 ]
             });
@@ -2330,6 +2686,7 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { 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-secret-read-guard.js'), matcher: 'ReadFile|Grep|Shell', 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
@@ -2521,6 +2878,9 @@ module.exports = {
     removeCodexHooksJsonEvent,
     removeCodexHooksJsonSessionStart,
     buildCodexHookWindowsShimIR,
+    cleanupOrphanedCodexContextMonitorScript,
+    isGsdOwnedCodexContextMonitorScript,
+    hooksJsonReferencesCodexContextMonitor,
     // Codex TOML
     buildCodexHookBlock,
     rewriteLegacyCodexHookBlock,
@@ -2532,6 +2892,7 @@ module.exports = {
     KIMI_HOOKS_TOML_MARKER_BEGIN,
     KIMI_HOOKS_TOML_MARKER_END,
     // Shared
+    stageTransitiveHookLibs,
     buildHookCommand,
     applySettingsJsonHooks,
     referencesHook,