@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -38,7 +38,7 @@ 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");
-const { isManagedHookBasename, isManagedHookCommand, projectLegacySettingsHookCommand, projectManagedHookCommand, projectPortableHookBaseDir, projectCodexHookTomlCommand, shellHookOmitsBashRunner, escapeTomlDoubleQuotedString, escapePosixDoubleQuoted, } = shellCmdProjection;
+const { isManagedHookBasename, isManagedHookCommand, projectLegacySettingsHookCommand, projectManagedHookCommand, projectPortableHookBaseDir, projectCodexHookTomlCommand, shellHookOmitsBashRunner, escapeTomlDoubleQuotedString, escapePosixDoubleQuoted, resolveExecutableBinary, } = shellCmdProjection;
 // ---------------------------------------------------------------------------
 // Terminal color constants (mirrors install.js for console output parity)
 // ---------------------------------------------------------------------------
@@ -576,7 +576,15 @@ function buildBakedNodeToken(opts) {
  * guarantee), ahead of `command -v node` and the well-known fallback list.
  */
 const NODE_RUNNER_RESOLVER_HOOK = 'gsd-node-runner.sh';
-function resolveBashRunner(opts) {
+/**
+ * The one Git Bash policy: `bash` off win32; on win32 GSD_BASH_PATH, then the
+ * well-known Git for Windows install locations, never a PATH lookup (which
+ * can reach WSL's System32 launcher). null when win32 has no Git Bash.
+ * #5082: the test process seam (tests/helpers/process-seam.cjs) resolves
+ * `bash` through this too, so hooks and bash-driven tests run under the same
+ * bash.
+ */
+function resolveBashExecutable(opts) {
     const platform = (opts && opts.platform) || process.platform;
     if (platform !== 'win32')
         return 'bash';
@@ -594,12 +602,19 @@ function resolveBashRunner(opts) {
         candidates.push(node_path_1.default.win32.join(env.SystemDrive, 'Program Files (x86)', 'Git', 'bin', 'bash.exe'));
     }
     for (const candidate of candidates) {
-        if (candidate && exists(candidate)) {
-            return JSON.stringify(shellCmdProjection.posixNormalize(candidate));
-        }
+        if (candidate && exists(candidate))
+            return shellCmdProjection.posixNormalize(candidate);
     }
     return null;
 }
+function resolveBashRunner(opts) {
+    const executable = resolveBashExecutable(opts);
+    if (executable === null)
+        return null;
+    return ((opts && opts.platform) || process.platform) === 'win32'
+        ? JSON.stringify(executable)
+        : executable;
+}
 // #3662 — recognize the two runtime-resolving command shapes the installer
 // emits, so the rewriter never churns (or un-does) an entry that already
 // works in every environment sharing the config root.
@@ -961,16 +976,18 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
 function reconcileCodexHooksJsonSessionStart(targetDir, opts = {}) {
     return reconcileCodexHooksJsonEvent(targetDir, 'SessionStart', opts);
 }
-function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
-    if (!absoluteRunnerToken)
-        return null;
-    let interpreter;
+function parseAbsoluteRunnerToken(absoluteRunnerToken) {
     try {
-        interpreter = JSON.parse(absoluteRunnerToken);
+        return JSON.parse(absoluteRunnerToken);
     }
     catch {
-        interpreter = absoluteRunnerToken;
+        return absoluteRunnerToken;
     }
+}
+function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
+    if (!absoluteRunnerToken)
+        return null;
+    const interpreter = parseAbsoluteRunnerToken(absoluteRunnerToken);
     const targetAbs = shellCmdProjection.posixNormalize(scriptAbsPath);
     const scriptQuoted = JSON.stringify(targetAbs);
     const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
@@ -995,6 +1012,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
         return { changed: false, wrote: false, path: hooksJsonPath };
     const scriptPath = shellCmdProjection.posixNormalize(node_path_1.default.resolve(targetDir, 'hooks', 'gsd-check-update.js'));
     const cmdShimPath = scriptPath.replace(/\.js$/, '.cmd');
+    const configuredEntrypoints = [];
     let managedCommand;
     if (platform === 'win32') {
         const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
@@ -1011,6 +1029,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
             return { changed: false, wrote: false, path: hooksJsonPath };
         }
         managedCommand = shimIR.hookCommand;
+        configuredEntrypoints.push({ runtime: 'codex', configPath: hooksJsonPath, scriptPath: shimIR.cmdPath, platform, selfExecutable: true }, { runtime: 'codex', configPath: hooksJsonPath, scriptPath, interpreterCandidates: [parseAbsoluteRunnerToken(absoluteRunner)], platform });
     }
     else {
         managedCommand = projectManagedHookCommand({
@@ -1019,13 +1038,23 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
             runtime: 'codex',
             platform,
         }) ?? undefined;
+        if (managedCommand) {
+            configuredEntrypoints.push({
+                runtime: 'codex',
+                configPath: hooksJsonPath,
+                scriptPath,
+                interpreterCandidates: [parseAbsoluteRunnerToken(absoluteRunner)],
+                platform,
+            });
+        }
     }
     if (!managedCommand)
         return { changed: false, wrote: false, path: hooksJsonPath };
     const commandWindows = platform === 'win32'
         ? JSON.stringify(shellCmdProjection.posixNormalize(cmdShimPath))
         : undefined;
-    return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
+    const result = reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
+    return { ...result, configuredEntrypoints };
 }
 function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
     const platform = opts.platform || process.platform;
@@ -1201,6 +1230,56 @@ function cleanupOrphanedCodexContextMonitorScript(targetDir) {
     }
     return result;
 }
+function configuredEntrypointsForHook(configDir, hookName, opts) {
+    const platform = opts.platform || process.platform;
+    const runtime = opts.runtime || 'generic';
+    const configPath = opts.configPath || configDir;
+    const target = {
+        runtime,
+        configPath,
+        scriptPath: node_path_1.default.join(configDir, 'hooks', hookName),
+        platform,
+    };
+    const isShellHook = hookName.endsWith('.sh');
+    if (shellHookOmitsBashRunner({ platform, runtime, isShellHook }))
+        return [{ ...target, selfExecutable: true }];
+    const bash = resolveBashExecutable(opts);
+    if (isShellHook) {
+        // An unresolved bash must still surface as an interpreterCandidates entry
+        // (the literal token, same as the portableHooks runner below) so
+        // validateConfiguredEntrypoints reports 'unresolved-interpreter' instead
+        // of silently skipping the check because the field is absent.
+        return [{ ...target, interpreterCandidates: [bash === null ? 'bash' : bash] }];
+    }
+    // #4249: check the SAME stable alias buildNodeRunnerChainToken bakes as its
+    // first candidate (normalizeNodePath rewrites a version-manager shim like
+    // fnm/nvm/mise/volta into its persistent path), not the raw, currently-
+    // running process.execPath — which always trivially resolves regardless of
+    // whether the alias actually baked into the persisted command still does.
+    const nodeCandidates = [
+        normalizeNodePath(opts.execPath || process.execPath, opts),
+        'node',
+        '/usr/local/bin/node',
+        '/usr/bin/node',
+    ].filter((candidate) => Boolean(candidate));
+    if (!opts.portableHooks) {
+        return [{ ...target, interpreterCandidates: nodeCandidates }];
+    }
+    const runner = {
+        runtime,
+        configPath,
+        scriptPath: node_path_1.default.join(configDir, 'hooks', NODE_RUNNER_RESOLVER_HOOK),
+        interpreterCandidates: bash === null ? ['bash'] : [bash],
+        platform,
+    };
+    return [runner, { ...target, interpreterCandidates: nodeCandidates }];
+}
+function recordConfiguredHookCommand(command, configDir, hookName, opts) {
+    if (command && opts.configuredEntrypoints) {
+        opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts).map(entry => ({ ...entry, command })));
+    }
+    return command;
+}
 function buildHookCommand(configDir, hookName, opts) {
     if (!opts)
         opts = {};
@@ -1208,44 +1287,56 @@ function buildHookCommand(configDir, hookName, opts) {
     const runtime = opts.runtime || 'generic';
     const hookShell = opts.hookShell;
     const isShellHook = hookName.endsWith('.sh');
+    const track = (command) => recordConfiguredHookCommand(command, configDir, hookName, opts);
     if (shellHookOmitsBashRunner({ platform, runtime, isShellHook })) {
         if (opts.portableHooks) {
             const portableBaseDir = projectPortableHookBaseDir({
                 configDir,
                 homeDir: node_os_1.default.homedir(),
             });
-            return JSON.stringify(`${portableBaseDir}/hooks/${hookName}`);
+            return track(JSON.stringify(`${portableBaseDir}/hooks/${hookName}`));
         }
-        return JSON.stringify(shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName);
+        return track(JSON.stringify(shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName));
     }
     // .sh hooks keep the pre-#3662 shape everywhere: the bash runner resolves
     // at install time like today, and `bash` itself is a PATH-stable binary
     // (the absolute Git-Bash discovery covers win32 — #580/#3393).
     if (isShellHook) {
         const runner = resolveBashRunner(opts);
-        if (runner === null)
+        if (runner === null) {
+            // #4249 (antigravity review): this early return skips `track()` below,
+            // so an unresolved bash on win32 (no Git Bash found) previously left
+            // this hook silently unregistered with nothing for
+            // validateConfiguredEntrypoints to reject — configuredEntrypointsForHook's
+            // own 'unresolved bash must still surface' comment describes intent this
+            // return never reached. Push the entry directly (no `command`, since
+            // none was ever built) so the gate actually sees it.
+            if (opts.configuredEntrypoints) {
+                opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts));
+            }
             return null;
+        }
         if (opts.portableHooks) {
             const portableBaseDir = projectPortableHookBaseDir({
                 configDir,
                 homeDir: node_os_1.default.homedir(),
             });
-            return projectManagedHookCommand({
+            return track(projectManagedHookCommand({
                 absoluteRunner: runner,
                 scriptPath: `${portableBaseDir}/hooks/${hookName}`,
                 runtime: opts.runtime || 'generic',
                 platform,
                 hookShell,
-            });
+            }));
         }
         const hooksPath = shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName;
-        return projectManagedHookCommand({
+        return track(projectManagedHookCommand({
             absoluteRunner: runner,
             scriptPath: hooksPath,
             runtime,
             platform,
             hookShell,
-        });
+        }));
     }
     // JS hooks (#3662): the node runner is resolved at hook-fire time, never
     // baked as a bare absolute path — an install-environment absolute path is
@@ -1268,7 +1359,7 @@ function buildHookCommand(configDir, hookName, opts) {
         // Absolute Git-Bash discovery on win32 when available (#580); `bash` on
         // PATH otherwise — the same assumption .sh hooks already make.
         const resolverRunner = resolveBashRunner(opts) || 'bash';
-        return shellCmdProjection.projectShellCommandText({
+        return track(shellCmdProjection.projectShellCommandText({
             runnerToken: resolverRunner,
             argTokens: [
                 JSON.stringify(`${portableBaseDir}/hooks/${NODE_RUNNER_RESOLVER_HOOK}`),
@@ -1278,19 +1369,19 @@ function buildHookCommand(configDir, hookName, opts) {
             runtime,
             platform,
             hookShell,
-        });
+        }));
     }
     const chainRunner = buildNodeRunnerChainToken(opts);
     if (chainRunner === null)
         return null;
     const hooksPath = shellCmdProjection.posixNormalize(configDir) + '/hooks/' + hookName;
-    return shellCmdProjection.projectShellCommandText({
+    return track(shellCmdProjection.projectShellCommandText({
         runnerToken: chainRunner,
         argTokens: [JSON.stringify(hooksPath)],
         runtime,
         platform,
         hookShell,
-    });
+    }));
 }
 // ---------------------------------------------------------------------------
 // Cline helpers
@@ -1391,6 +1482,7 @@ function mergeGsdAgentsMd(filePath, gsdContent) {
 // ---------------------------------------------------------------------------
 function writeClineArtifacts(targetDir, isGlobalInstall) {
     const written = [];
+    const configuredEntrypoints = [];
     const clinerulesDir = node_path_1.default.join(targetDir, '.clinerules');
     try {
         if (node_fs_1.default.existsSync(clinerulesDir)) {
@@ -1416,6 +1508,20 @@ function writeClineArtifacts(targetDir, isGlobalInstall) {
     catch { /* Windows: hooks unsupported anyway */ }
     written.push('.clinerules/hooks/PreToolUse');
     console.log(`  ${green}✓${reset} Wrote .clinerules/hooks/PreToolUse`);
+    // #4249 (CodeRabbit): Cline invokes this file directly via its own
+    // `#!/usr/bin/env node` shebang — a hybrid case. The script itself still
+    // needs the execute bit (selfExecutable), but unlike GSD's other JS hooks
+    // (which bake an absolute, install-time-resolved node path specifically to
+    // avoid this) its interpreter is looked up on PATH by `env` at hook-fire
+    // time, so `node` must also resolve or the hook can never run.
+    configuredEntrypoints.push({
+        runtime: 'cline',
+        configPath: hookPath,
+        scriptPath: hookPath,
+        interpreterCandidates: ['node'],
+        selfExecutable: true,
+        platform: process.platform,
+    });
     if (isGlobalInstall) {
         try {
             const agentsPath = node_path_1.default.join(node_os_1.default.homedir(), '.agents', 'AGENTS.md');
@@ -1426,7 +1532,7 @@ function writeClineArtifacts(targetDir, isGlobalInstall) {
             console.warn(`  ${yellow}⚠${reset} Could not write ~/.agents/AGENTS.md: ${err.message}`);
         }
     }
-    return written;
+    return { written, configuredEntrypoints };
 }
 // ---------------------------------------------------------------------------
 // Cursor hook functions
@@ -1677,7 +1783,13 @@ function writeCursorHooksJson(targetDir, src, opts) {
     if (installedScripts.size > 0) {
         ensureCommonJsMarker(hooksDir);
     }
-    const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
+    const configuredEntrypoints = [];
+    const hookOpts = {
+        runtime: 'cursor',
+        platform: opts.platform || process.platform,
+        configPath: node_path_1.default.join(targetDir, 'hooks.json'),
+        configuredEntrypoints,
+    };
     const commands = {};
     for (const ev of events) {
         const script = imperative_hook_bus_cjs_1.CURSOR_EVENT_SCRIPT_MAP[ev];
@@ -1691,7 +1803,7 @@ function writeCursorHooksJson(targetDir, src, opts) {
     const managedEntries = (0, imperative_hook_bus_cjs_1.buildHookBusEntries)(events, commands);
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const result = reconcileCursorHooksJson(hooksJsonPath, managedEntries);
-    return { hooksJsonPath, changed: result.changed };
+    return { hooksJsonPath, changed: result.changed, configuredEntrypoints };
 }
 function removeCursorHooksJson(targetDir) {
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
@@ -1896,7 +2008,13 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
     if (installedScripts.size > 0) {
         ensureCommonJsMarker(hooksDir);
     }
-    const hookOpts = { runtime: 'windsurf', platform: opts.platform || process.platform };
+    const configuredEntrypoints = [];
+    const hookOpts = {
+        runtime: 'windsurf',
+        platform: opts.platform || process.platform,
+        configPath: node_path_1.default.join(targetDir, 'hooks.json'),
+        configuredEntrypoints,
+    };
     const commands = {};
     for (const ev of WINDSURF_HOOK_EVENTS) {
         const script = WINDSURF_EVENT_SCRIPT_MAP[ev];
@@ -1910,7 +2028,7 @@ function writeWindsurfHooksJson(targetDir, src, opts) {
     }
     const hooksJsonPath = node_path_1.default.join(targetDir, 'hooks.json');
     const result = reconcileWindsurfHooksJson(hooksJsonPath, managedEntries);
-    return { hooksJsonPath, changed: result.changed };
+    return { hooksJsonPath, changed: result.changed, configuredEntrypoints };
 }
 /**
  * Remove all GSD-managed Cascade hook entries from hooks.json. User-owned
@@ -2008,608 +2126,268 @@ function writeCopilotHookConfig(targetDir) {
     node_fs_1.default.writeFileSync(hookPath, JSON.stringify(buildCopilotHookConfig(), null, 2) + '\n');
     return hookPath;
 }
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function applySettingsJsonHooks(settings, opts) {
-    /* eslint-disable @typescript-eslint/no-unsafe-member-access,
-                      @typescript-eslint/no-unsafe-call,
-                      @typescript-eslint/no-unsafe-assignment */
-    const { runtime, isGlobal, targetDir, postToolEvent, hookEvents, extendedHookEvents, hooksSurface, updateCheckCommand, contextMonitorCommand, promptGuardCommand, readGuardCommand, readInjectionScannerCommand, configReloadCommand, hookOpts, localCmd, localShellCmd, } = opts;
-    // ADR-857 phase 5f-3: extended hook events are now driven by the registry
+const BASH_UNAVAILABLE_MESSAGE = 'Bash executable path unavailable (#3393)';
+// The tables are exported as a contract; freeze every row (and its nested
+// objects) so no consumer can mutate a matcher or timeout at runtime.
+function deepFreeze(value) {
+    for (const child of Object.values(value)) {
+        if (child !== null && typeof child === 'object')
+            deepFreeze(child);
+    }
+    return Object.freeze(value);
+}
+const SETTINGS_JSON_HOOK_ROWS = deepFreeze([
+    // Guard: only register if the hook file was actually installed (#1754, #1817).
+    { file: 'gsd-check-update.js', event: 'SessionStart', command: { opts: 'updateCheckCommand' },
+        configuredMessage: 'Configured update check hook', skipLabel: 'update check hook' },
+    { file: 'gsd-context-monitor.js', event: 'post', matcher: 'Bash|Edit|Write|MultiEdit|Agent|Task', timeout: 10,
+        command: { opts: 'contextMonitorCommand' },
+        configuredMessage: 'Configured context window monitor hook', skipLabel: 'context monitor hook',
+        onPresent: { kind: 'migrate-matcher-timeout', message: 'Updated context monitor hook (added matcher + timeout)' } },
+    { file: 'gsd-prompt-guard.js', event: 'pre', matcher: 'Write|Edit', timeout: 'blocking',
+        command: { opts: 'promptGuardCommand' },
+        configuredMessage: 'Configured prompt injection guard hook', skipLabel: 'prompt guard hook' },
+    // Read-before-edit guidance (#1628): advisory-only, does not block.
+    { file: 'gsd-read-guard.js', event: 'pre', matcher: 'Write|Edit', timeout: 5,
+        command: { opts: 'readGuardCommand' },
+        configuredMessage: 'Configured read-before-edit guard hook', skipLabel: 'read guard hook' },
+    // Read-time prompt injection scanning (#2201).
+    { file: 'gsd-read-injection-scanner.js', event: 'post', matcher: 'Read', timeout: 5,
+        command: { opts: 'readInjectionScannerCommand' },
+        configuredMessage: 'Configured read injection scanner hook', skipLabel: 'read injection scanner hook' },
+    // Community hooks — registered on install but opt-in at runtime via .planning/config.json.
+    { file: 'gsd-workflow-guard.js', event: 'pre', matcher: 'Bash|Edit|Write|MultiEdit', timeout: 'blocking',
+        command: { build: 'js' },
+        configuredMessage: 'Configured workflow guard hook (opt-in via hooks.workflow_guard)', skipLabel: 'workflow guard hook',
+        onPresent: { kind: 'repair-matcher', message: 'Updated workflow guard hook matcher' } },
+    // Worktree absolute-path safety (#260).
+    { file: 'gsd-worktree-path-guard.js', event: 'pre', matcher: 'Write|Edit|MultiEdit', timeout: 'blocking',
+        command: { build: 'js' },
+        configuredMessage: 'Configured worktree path guard hook', skipLabel: 'worktree path guard hook' },
+    // Agent-dispatch isolation (#3045); matcher widened to Agent|Task (#3045 MAJOR 1).
+    { file: 'gsd-agent-isolation-guard.js', event: 'pre', matcher: 'Agent|Task', timeout: 'blocking',
+        command: { build: 'js' },
+        configuredMessage: 'Configured agent isolation dispatch guard hook', skipLabel: 'agent isolation guard hook' },
+    // Catastrophic-shrink protection (#2255, fix 3 of #973).
+    { file: 'gsd-write-guard.js', event: 'pre', matcher: 'Write', timeout: 'blocking',
+        command: { build: 'js' },
+        configuredMessage: 'Configured write guard hook (catastrophic-shrink protection)', skipLabel: 'write guard hook' },
+    // Secret-file read protection (#4221).
+    { file: 'gsd-secret-read-guard.js', event: 'pre', matcher: 'Read|Grep|Bash', timeout: 'blocking',
+        command: { build: 'js' },
+        configuredMessage: 'Configured secret read guard hook (.env / .secrets read protection)', skipLabel: 'secret read guard hook' },
+    // The four `.sh` rows: their built commands also feed the #3329 reconcile.
+    { file: 'gsd-validate-commit.sh', event: 'pre', matcher: 'Bash', timeout: 'blocking',
+        command: { build: 'sh' },
+        configuredMessage: 'Configured commit validation hook (opt-in via config)', skipLabel: 'commit validation hook',
+        noCommandMessage: BASH_UNAVAILABLE_MESSAGE },
+    { file: 'gsd-graphify-update.sh', event: 'post', matcher: 'Bash', timeout: 5,
+        command: { build: 'sh' },
+        configuredMessage: 'Configured graphify auto-update hook (opt-in via graphify.auto_update)', skipLabel: 'graphify auto-update hook',
+        noCommandMessage: BASH_UNAVAILABLE_MESSAGE },
+    { file: 'gsd-session-state.sh', event: 'SessionStart',
+        command: { build: 'sh' },
+        configuredMessage: 'Configured session state orientation hook (opt-in via config)', skipLabel: 'session state hook',
+        noCommandMessage: BASH_UNAVAILABLE_MESSAGE },
+    { file: 'gsd-phase-boundary.sh', event: 'post', matcher: 'Write|Edit', timeout: 5,
+        command: { build: 'sh' },
+        configuredMessage: 'Configured phase boundary detection hook (opt-in via config)', skipLabel: 'phase boundary hook',
+        noCommandMessage: BASH_UNAVAILABLE_MESSAGE },
+]);
+// Extended lifecycle events are descriptor-gated (`extendedHookEvents`): a row
+// registers only for runtimes whose descriptor lists its event. SubagentStart
+// is qwen/codebuddy-only today; the Before/After Agent/Model rows are an inert
+// seam (no runtime declares them) that re-activates if one does (#776, #1928).
+// FileChanged hot-reloads the gsd config on .planning/config.json edits.
+function contextMonitorRow(event, runtimeLabelSuffix) {
+    return {
+        event,
+        file: 'gsd-context-monitor.js',
+        command: { opts: 'contextMonitorCommand' },
+        timeout: 10,
+        configuredMessage: `Configured ${event} context monitor hook`,
+        ...(runtimeLabelSuffix ? { runtimeLabelSuffix } : {}),
+    };
+}
+const SETTINGS_JSON_EXTENDED_ROWS = deepFreeze([
+    contextMonitorRow('SubagentStop', true),
+    contextMonitorRow('Stop', true),
+    contextMonitorRow('PreCompact', true),
+    contextMonitorRow('SubagentStart', true),
+    contextMonitorRow('BeforeAgent', false),
+    contextMonitorRow('AfterAgent', false),
+    contextMonitorRow('BeforeModel', false),
+    { event: 'FileChanged', file: 'gsd-config-reload.js', command: { opts: 'configReloadCommand' }, matcher: 'config.json', timeout: 8,
+        configuredMessage: 'Configured FileChanged config-reload hook (Claude Code)',
+        noCommandMessage: 'Node executable path unavailable' },
+]);
+function hookStem(file) {
+    return file.replace(/\.(?:js|sh)$/, '');
+}
+/* eslint-disable @typescript-eslint/no-unsafe-member-access,
+                  @typescript-eslint/no-unsafe-call,
+                  @typescript-eslint/no-unsafe-assignment,
+                  @typescript-eslint/no-explicit-any */
+function groupReferencesHook(entry, stem) {
+    return Boolean(entry.hooks && entry.hooks.some((h) => referencesHook(h, stem)));
+}
+function resolveRowTimeout(timeout) {
+    return timeout === 'blocking' ? BLOCKING_GUARD_TIMEOUT_S : timeout;
+}
+function resolveRowCommand(row, opts) {
+    if ('opts' in row.command)
+        return opts[row.command.opts];
+    if (opts.isGlobal)
+        return buildHookCommand(opts.targetDir, row.file, opts.hookOpts);
+    return row.command.build === 'sh' ? opts.localShellCmd(row.file) : opts.localCmd(row.file);
+}
+function reconcilePresentHook(row, entries, existing) {
+    const present = row.onPresent;
+    if (!present)
+        return;
+    if (present.kind === 'repair-matcher') {
+        if (existing.matcher !== row.matcher) {
+            existing.matcher = row.matcher;
+            console.log(`  ${green}✓${reset} ${present.message}`);
+        }
+        return;
+    }
+    // migrate-matcher-timeout: add the matcher and timeout an older installer omitted.
+    const stem = hookStem(row.file);
+    const timeout = resolveRowTimeout(row.timeout);
+    for (const entry of entries) {
+        if (!groupReferencesHook(entry, stem))
+            continue;
+        let migrated = false;
+        if (!entry.matcher) {
+            entry.matcher = row.matcher;
+            migrated = true;
+        }
+        for (const h of entry.hooks) {
+            if (referencesHook(h, stem) && !h.timeout) {
+                h.timeout = timeout;
+                migrated = true;
+            }
+        }
+        if (migrated)
+            console.log(`  ${green}✓${reset} ${present.message}`);
+    }
+}
+function pushHookGroup(entries, matcher, command, timeout) {
+    const hook = { type: 'command', command };
+    if (timeout !== undefined)
+        hook['timeout'] = timeout;
+    entries.push(matcher === undefined ? { hooks: [hook] } : { matcher, hooks: [hook] });
+}
+function applySettingsJsonHookTables(settings, opts, tables) {
+    const { runtime, postToolEvent, hookEvents, extendedHookEvents, hooksSurface, targetDir, hookOpts } = opts;
+    // ADR-857 phase 5f-3: extended hook events are driven by the registry
     // descriptor field rather than hardcoded runtime-name checks.
     const extendedEvents = Array.isArray(extendedHookEvents) ? extendedHookEvents : [];
     // ADR-857 phase 5g drive 3: hook-skip guard is driven by the hooksSurface
     // descriptor field. Only runtimes with hooksSurface === 'settings-json'
-    // register settings.json hooks; runtimes with hooksSurface === 'none'
-    // (opencode, kilo) are skipped. Equivalence: hooksSurface !== 'none' iff
-    // the old !isOpencode && !isKilo check.
+    // register settings.json hooks; 'none' (opencode, kilo) is skipped.
     // #2095: kimi's hooksSurface is 'kimi-hooks-toml' — it registers hooks into
-    // its own native config.toml via writeKimiHooksToml, not settings.json (kimi
-    // never writes settings.json at all: writesSharedSettings stays false). This
-    // guard must also skip kimi's surface so applySettingsJsonHooks doesn't log
-    // misleading "Configured ..." console messages for a settings object that
-    // finishInstall() will never persist for kimi.
-    if (hooksSurface !== 'none' && hooksSurface !== 'kimi-hooks-toml') {
-        if (!settings.hooks) {
-            settings.hooks = {};
-        }
-        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))
+    // its own native config.toml via writeKimiHooksToml and never writes
+    // settings.json, so this guard must skip it too, or the console would log
+    // "Configured ..." for a settings object finishInstall() never persists.
+    if (hooksSurface === 'none' || hooksSurface === 'kimi-hooks-toml')
+        return;
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    if (!settings.hooks.SessionStart) {
+        settings.hooks.SessionStart = [];
+    }
+    // #3981: raise existing managed blocking-guard entries still on the old
+    // 5 s budget to BLOCKING_GUARD_TIMEOUT_S (module-level; rationale there).
+    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 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;
-                    }
+            for (const h of entry.hooks) {
+                if (BLOCKING_GUARD_NAMES.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
-        // copy step produces no files but the registration step ran unconditionally,
-        // causing "hook error" on every tool invocation.
-        const checkUpdateFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-check-update.js');
-        if (!hasGsdUpdateHook && node_fs_1.default.existsSync(checkUpdateFile) && updateCheckCommand) {
-            settings.hooks.SessionStart.push({
-                hooks: [
-                    {
-                        type: 'command',
-                        command: updateCheckCommand
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured update check hook`);
-        }
-        else if (!hasGsdUpdateHook && !node_fs_1.default.existsSync(checkUpdateFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped update check hook — gsd-check-update.js not found at target`);
-        }
-        // Configure post-tool hook for context window monitoring
-        if (!settings.hooks[postToolEvent]) {
-            settings.hooks[postToolEvent] = [];
-        }
-        const hasContextMonitorHook = settings.hooks[postToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-context-monitor')));
-        const contextMonitorFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-context-monitor.js');
-        if (!hasContextMonitorHook && node_fs_1.default.existsSync(contextMonitorFile) && contextMonitorCommand) {
-            settings.hooks[postToolEvent].push({
-                matcher: 'Bash|Edit|Write|MultiEdit|Agent|Task',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: contextMonitorCommand,
-                        timeout: 10
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured context window monitor hook`);
+    }
+    // hookEvents='gemini' → BeforeTool/AfterTool; all others → PreToolUse/PostToolUse.
+    const preToolEvent = hookEvents === 'gemini' ? 'BeforeTool' : 'PreToolUse';
+    const eventKey = (event) => event === 'SessionStart' ? 'SessionStart' : event === 'post' ? postToolEvent : preToolEvent;
+    // Built `.sh` commands, in row order, feed the #3329 reconcile below.
+    const shellCommands = {};
+    for (const row of tables.rows) {
+        const key = eventKey(row.event);
+        if (!settings.hooks[key]) {
+            settings.hooks[key] = [];
+        }
+        const entries = settings.hooks[key];
+        const command = resolveRowCommand(row, opts);
+        if ('build' in row.command && row.command.build === 'sh')
+            shellCommands[row.file] = command;
+        const stem = hookStem(row.file);
+        const existing = entries.find((entry) => groupReferencesHook(entry, stem));
+        if (existing) {
+            reconcilePresentHook(row, entries, existing);
+            continue;
         }
-        else if (!hasContextMonitorHook && !node_fs_1.default.existsSync(contextMonitorFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped context monitor hook — gsd-context-monitor.js not found at target`);
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(targetDir, 'hooks', row.file))) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped ${row.skipLabel} — ${row.file} not found at target`);
         }
-        else {
-            // Migrate existing context monitor hooks: add matcher and timeout if missing
-            for (const entry of settings.hooks[postToolEvent]) {
-                if (entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-context-monitor'))) {
-                    let migrated = false;
-                    if (!entry.matcher) {
-                        entry.matcher = 'Bash|Edit|Write|MultiEdit|Agent|Task';
-                        migrated = true;
-                    }
-                    for (const h of entry.hooks) {
-                        if (referencesHook(h, 'gsd-context-monitor') && !h.timeout) {
-                            h.timeout = 10;
-                            migrated = true;
-                        }
-                    }
-                    if (migrated) {
-                        console.log(`  ${green}✓${reset} Updated context monitor hook (added matcher + timeout)`);
-                    }
-                }
-            }
+        else if (command) {
+            pushHookGroup(entries, row.matcher, command, resolveRowTimeout(row.timeout));
+            console.log(`  ${green}✓${reset} ${row.configuredMessage}`);
         }
-        // Configure PreToolUse hook for prompt injection detection
-        // ADR-857 phase 5f-2: drive dialect from opts.hookEvents (registry descriptor).
-        // hookEvents='gemini' → BeforeTool; all others → PreToolUse.
-        // Equivalence: hookEvents='gemini' iff runtime===antigravity (same as old check).
-        const preToolEvent = hookEvents === 'gemini' ? 'BeforeTool' : 'PreToolUse';
-        if (!settings.hooks[preToolEvent]) {
-            settings.hooks[preToolEvent] = [];
-        }
-        const hasPromptGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-prompt-guard')));
-        const promptGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-prompt-guard.js');
-        if (!hasPromptGuardHook && node_fs_1.default.existsSync(promptGuardFile) && promptGuardCommand) {
-            settings.hooks[preToolEvent].push({
-                matcher: 'Write|Edit',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: promptGuardCommand,
-                        timeout: BLOCKING_GUARD_TIMEOUT_S
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured prompt injection guard hook`);
-        }
-        else if (!hasPromptGuardHook && !node_fs_1.default.existsSync(promptGuardFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped prompt guard hook — gsd-prompt-guard.js not found at target`);
-        }
-        // Configure PreToolUse hook for read-before-edit guidance (#1628)
-        // Prevents infinite retry loops when non-Claude models attempt to edit
-        // files without reading them first. Advisory-only — does not block.
-        const hasReadGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-read-guard')));
-        const readGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-read-guard.js');
-        if (!hasReadGuardHook && node_fs_1.default.existsSync(readGuardFile) && readGuardCommand) {
-            settings.hooks[preToolEvent].push({
-                matcher: 'Write|Edit',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: readGuardCommand,
-                        timeout: 5
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured read-before-edit guard hook`);
-        }
-        else if (!hasReadGuardHook && !node_fs_1.default.existsSync(readGuardFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped read guard hook — gsd-read-guard.js not found at target`);
-        }
-        // Configure PostToolUse hook for read-time prompt injection scanning (#2201)
-        // Scans content returned by the Read tool for injection patterns, including
-        // summarisation-specific patterns that survive context compression.
-        const hasReadInjectionScannerHook = settings.hooks[postToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-read-injection-scanner')));
-        const readInjectionScannerFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-read-injection-scanner.js');
-        if (!hasReadInjectionScannerHook && node_fs_1.default.existsSync(readInjectionScannerFile) && readInjectionScannerCommand) {
-            settings.hooks[postToolEvent].push({
-                matcher: 'Read',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: readInjectionScannerCommand,
-                        timeout: 5
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured read injection scanner hook`);
-        }
-        else if (!hasReadInjectionScannerHook && !node_fs_1.default.existsSync(readInjectionScannerFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped read injection scanner hook — gsd-read-injection-scanner.js not found at target`);
-        }
-        // Community hooks — registered on install but opt-in at runtime.
-        // Each hook checks .planning/config.json for hooks.community: true
-        // and exits silently (no-op) if not enabled. This lets users enable
-        // them per-project by adding: "hooks": { "community": true }
-        // Configure workflow guard hook (opt-in via hooks.workflow_guard: true)
-        // Detects file edits outside GSD workflow context and advises using
-        // /gsd-quick or /gsd-fast for state-tracked changes. Also hard-blocks
-        // unsafe Bash commands that violate worktree-agent isolation.
-        const workflowGuardCommand = isGlobal
-            ? buildHookCommand(targetDir, 'gsd-workflow-guard.js', hookOpts)
-            : localCmd('gsd-workflow-guard.js');
-        const workflowGuardMatcher = 'Bash|Edit|Write|MultiEdit';
-        const workflowGuardHookEntry = settings.hooks[preToolEvent].find((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-workflow-guard')));
-        const hasWorkflowGuardHook = Boolean(workflowGuardHookEntry);
-        const workflowGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-workflow-guard.js');
-        if (hasWorkflowGuardHook && workflowGuardHookEntry.matcher !== workflowGuardMatcher) {
-            workflowGuardHookEntry.matcher = workflowGuardMatcher;
-            console.log(`  ${green}✓${reset} Updated workflow guard hook matcher`);
-        }
-        else if (!hasWorkflowGuardHook && node_fs_1.default.existsSync(workflowGuardFile) && workflowGuardCommand) {
-            settings.hooks[preToolEvent].push({
-                matcher: workflowGuardMatcher,
-                hooks: [
-                    {
-                        type: 'command',
-                        command: workflowGuardCommand,
-                        timeout: BLOCKING_GUARD_TIMEOUT_S
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured workflow guard hook (opt-in via hooks.workflow_guard)`);
-        }
-        else if (!hasWorkflowGuardHook && !node_fs_1.default.existsSync(workflowGuardFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped workflow guard hook — gsd-workflow-guard.js not found at target`);
-        }
-        // Configure PreToolUse hook for worktree absolute-path safety (#260)
-        // Hard-blocks Edit/Write/MultiEdit tool calls with absolute paths that resolve
-        // outside the current worktree root. Prevents executor agents from
-        // accidentally writing to the main checkout when running in isolation="worktree".
-        const worktreePathGuardCommand = isGlobal
-            ? buildHookCommand(targetDir, 'gsd-worktree-path-guard.js', hookOpts)
-            : localCmd('gsd-worktree-path-guard.js');
-        const hasWorktreePathGuardHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-worktree-path-guard')));
-        const worktreePathGuardFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-worktree-path-guard.js');
-        if (!hasWorktreePathGuardHook && node_fs_1.default.existsSync(worktreePathGuardFile) && worktreePathGuardCommand) {
-            settings.hooks[preToolEvent].push({
-                matcher: 'Write|Edit|MultiEdit',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: worktreePathGuardCommand,
-                        timeout: BLOCKING_GUARD_TIMEOUT_S
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured worktree path guard hook`);
-        }
-        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: BLOCKING_GUARD_TIMEOUT_S
-                    }
-                ]
-            });
-            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: BLOCKING_GUARD_TIMEOUT_S
-                    }
-                ]
-            });
-            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 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)
-            : localShellCmd('gsd-validate-commit.sh');
-        const hasValidateCommitHook = settings.hooks[preToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-validate-commit')));
-        // Guard: only register if the .sh file was actually installed. If the npm package
-        // omitted the file (as happened in v1.32.0, bug #1817), registering a missing hook
-        // causes a hook error on every Bash tool invocation.
-        const validateCommitFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-validate-commit.sh');
-        if (!hasValidateCommitHook && node_fs_1.default.existsSync(validateCommitFile) && validateCommitCommand) {
-            settings.hooks[preToolEvent].push({
-                matcher: 'Bash',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: validateCommitCommand,
-                        timeout: BLOCKING_GUARD_TIMEOUT_S
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured commit validation hook (opt-in via config)`);
-        }
-        else if (!hasValidateCommitHook && !node_fs_1.default.existsSync(validateCommitFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped commit validation hook — gsd-validate-commit.sh not found at target`);
-        }
-        else if (!hasValidateCommitHook && !validateCommitCommand) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped commit validation hook — Bash executable path unavailable (#3393)`);
-        }
-        // Configure graphify auto-update hook (opt-in via graphify.auto_update; default false, #3347).
-        // PostToolUse Bash matcher — fires after git commit/merge/pull/rebase --continue/cherry-pick
-        // on the default branch, dispatches `graphify update .` in a detached subprocess. No-op unless
-        // .planning/config.json has BOTH graphify.enabled=true AND graphify.auto_update=true.
-        const graphifyUpdateCommand = isGlobal
-            ? buildHookCommand(targetDir, 'gsd-graphify-update.sh', hookOpts)
-            : localShellCmd('gsd-graphify-update.sh');
-        const hasGraphifyUpdateHook = settings.hooks[postToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-graphify-update')));
-        const graphifyUpdateFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-graphify-update.sh');
-        if (!hasGraphifyUpdateHook && node_fs_1.default.existsSync(graphifyUpdateFile) && graphifyUpdateCommand) {
-            settings.hooks[postToolEvent].push({
-                matcher: 'Bash',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: graphifyUpdateCommand,
-                        timeout: 5
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured graphify auto-update hook (opt-in via graphify.auto_update)`);
-        }
-        else if (!hasGraphifyUpdateHook && !node_fs_1.default.existsSync(graphifyUpdateFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped graphify auto-update hook — gsd-graphify-update.sh not found at target`);
-        }
-        else if (!hasGraphifyUpdateHook && !graphifyUpdateCommand) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped graphify auto-update hook — Bash executable path unavailable (#3393)`);
-        }
-        // Configure session state orientation hook (opt-in)
-        const sessionStateCommand = isGlobal
-            ? buildHookCommand(targetDir, 'gsd-session-state.sh', hookOpts)
-            : localShellCmd('gsd-session-state.sh');
-        const hasSessionStateHook = settings.hooks.SessionStart.some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-session-state')));
-        const sessionStateFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-session-state.sh');
-        if (!hasSessionStateHook && node_fs_1.default.existsSync(sessionStateFile) && sessionStateCommand) {
-            settings.hooks.SessionStart.push({
-                hooks: [
-                    {
-                        type: 'command',
-                        command: sessionStateCommand
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured session state orientation hook (opt-in via config)`);
-        }
-        else if (!hasSessionStateHook && !node_fs_1.default.existsSync(sessionStateFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped session state hook — gsd-session-state.sh not found at target`);
-        }
-        else if (!hasSessionStateHook && !sessionStateCommand) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped session state hook — Bash executable path unavailable (#3393)`);
-        }
-        // Configure phase boundary detection hook (opt-in)
-        const phaseBoundaryCommand = isGlobal
-            ? buildHookCommand(targetDir, 'gsd-phase-boundary.sh', hookOpts)
-            : localShellCmd('gsd-phase-boundary.sh');
-        const hasPhaseBoundaryHook = settings.hooks[postToolEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-phase-boundary')));
-        const phaseBoundaryFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-phase-boundary.sh');
-        if (!hasPhaseBoundaryHook && node_fs_1.default.existsSync(phaseBoundaryFile) && phaseBoundaryCommand) {
-            settings.hooks[postToolEvent].push({
-                matcher: 'Write|Edit',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: phaseBoundaryCommand,
-                        timeout: 5
-                    }
-                ]
-            });
-            console.log(`  ${green}✓${reset} Configured phase boundary detection hook (opt-in via config)`);
-        }
-        else if (!hasPhaseBoundaryHook && !node_fs_1.default.existsSync(phaseBoundaryFile)) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped phase boundary hook — gsd-phase-boundary.sh not found at target`);
-        }
-        else if (!hasPhaseBoundaryHook && !phaseBoundaryCommand) {
-            console.warn(`  ${yellow}⚠${reset}  Skipped phase boundary hook — Bash executable path unavailable (#3393)`);
-        }
-        // #3329: the four `.sh` sites above register only-if-absent, so an entry
-        // registered by an older installer keeps its old command forever —
-        // /gsd-update (which re-invokes the installer) never re-derived it. On
-        // Claude/win32 that left the pre-#580/#3393 bash-runner-prefixed commands
-        // in settings.json indefinitely. Reconcile existing managed `.sh` entries
-        // to the command this install would generate today. Inert wherever the
-        // bash runner is still the correct shape; scoped to exact managed
-        // basenames so user-authored hooks are never touched.
-        if (reconcileManagedShellHookCommands(settings, {
-            'gsd-validate-commit.sh': validateCommitCommand,
-            'gsd-graphify-update.sh': graphifyUpdateCommand,
-            'gsd-session-state.sh': sessionStateCommand,
-            'gsd-phase-boundary.sh': phaseBoundaryCommand,
-        }, { platform: hookOpts.platform, runtime })) {
-            console.log(`  ${green}✓${reset} Reconciled managed .sh hook commands to current format (#3329)`);
-        }
-        // ── Extended hook events: SubagentStop / Stop / PreCompact / SubagentStart
-        //    (#788 + #770 + #2092) ────────────────────────────────────────────────
-        // Claude Code (since #770) and Qwen Code (since #788) both support the
-        // SubagentStop / Stop / PreCompact lifecycle events. Qwen Code additionally
-        // supports SubagentStart (#2092 Phase B, Upgrade 2). Wire gsd-context-
-        // monitor so agents get context-headroom warnings at subagent start,
-        // subagent completion, model stop, and pre-compaction (the most critical
-        // moment to surface headroom info).
-        //
-        //   SubagentStart — subagent lifecycle start (context headroom tracking;
-        //                   qwen-only today — no other runtime declares it in
-        //                   extendedHookEvents)
-        //   SubagentStop  — subagent lifecycle completion (context headroom tracking)
-        //   Stop          — model stop / final-response moment (context headroom)
-        //   PreCompact    — fires before conversation compaction (most critical
-        //                   moment to surface context headroom warnings)
-        //
-        // Note: UserPromptSubmit is NOT wired here.  That event carries the raw
-        // user prompt text, not a tool invocation, so gsd-prompt-guard (which
-        // exits unless tool_name is Write/Edit) would be a silent no-op.  A
-        // dedicated handler for UserPromptSubmit is deferred to a follow-on issue.
-        // SubagentStart, SubagentStop, Stop, PreCompact — route through the context monitor.
-        // Guard is descriptor-driven: only events present in extendedEvents are wired,
-        // so this loop is a no-op for every runtime that doesn't list SubagentStart.
-        {
-            // Descriptor-driven (ADR-1239 / #2092): folded from a hardcoded
-            // `runtime === 'qwen' ? ... : ...` ternary into a capability-title
-            // lookup (see _capabilityTitle above).
-            const runtimeLabel = _capabilityTitle(runtime);
-            for (const event of ['SubagentStop', 'Stop', 'PreCompact', 'SubagentStart']) {
-                if (!extendedEvents.includes(event))
-                    continue;
-                if (!settings.hooks[event]) {
-                    settings.hooks[event] = [];
-                }
-                const alreadyHasContextMonitor = settings.hooks[event].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-context-monitor')));
-                if (!alreadyHasContextMonitor && node_fs_1.default.existsSync(contextMonitorFile) && contextMonitorCommand) {
-                    settings.hooks[event].push({
-                        hooks: [
-                            {
-                                type: 'command',
-                                command: contextMonitorCommand,
-                                timeout: 10
-                            }
-                        ]
-                    });
-                    console.log(`  ${green}✓${reset} Configured ${event} context monitor hook (${runtimeLabel})`);
-                }
-                else if (!alreadyHasContextMonitor && !node_fs_1.default.existsSync(contextMonitorFile)) {
-                    console.warn(`  ${yellow}⚠${reset}  Skipped ${event} hook — gsd-context-monitor.js not found at target`);
-                }
-            }
+        else if (row.noCommandMessage) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped ${row.skipLabel} — ${row.noCommandMessage}`);
         }
-        // ── end SubagentStop / Stop / PreCompact / SubagentStart events ────────────
-        // ── Extended hook events (#776; Gemini runtime removed #1928) ──────────────
-        // The Gemini-3-backend dialect exposes several hook events beyond
-        // BeforeTool/AfterTool. These were added for the now-removed Gemini CLI
-        // runtime (#776). No currently supported runtime declares them —
-        // Antigravity's descriptor carries `extendedHookEvents: []` — so this loop
-        // is an inert, descriptor-driven seam: it no-ops for every present runtime
-        // and re-activates automatically if a future runtime declares any of them.
-        // Three high-value events would be wired here:
-        //
-        //   BeforeAgent  — fires after user submits a prompt, before the agent
-        //                  plans.  Wire gsd-context-monitor for context headroom
-        //                  awareness at prompt time.
-        //   AfterAgent   — fires once per turn after the model generates its final
-        //                  response.  Wire gsd-context-monitor to track headroom
-        //                  after each agent turn completes.
-        //   BeforeModel  — fires before each LLM call (per-turn, not per-session).
-        //                  Wire gsd-context-monitor for per-turn context injection
-        //                  — more precise than session-start-only injection.
-        //
-        // All three reuse gsd-context-monitor.js — no new hook files needed.
-        // The `decision:"deny"` retry capability of AfterAgent is intentionally
-        // left to the hook script to implement when triggered (gsd-context-monitor
-        // exits 0 / advisory-only today; an active quality gate is a follow-on).
-        //
-        // Note: BeforeToolSelection is NOT wired.  That event does not map to a
-        // gsd hook use case at this time; deferred to a follow-on issue.
-        //
-        // Guard is now descriptor-driven: only events present in extendedEvents are wired.
-        for (const extendedEvent of ['BeforeAgent', 'AfterAgent', 'BeforeModel']) {
-            if (!extendedEvents.includes(extendedEvent))
-                continue;
-            if (!Array.isArray(settings.hooks[extendedEvent])) {
-                settings.hooks[extendedEvent] = [];
-            }
-            const alreadyHasContextMonitor = settings.hooks[extendedEvent].some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-context-monitor')));
-            if (!alreadyHasContextMonitor && node_fs_1.default.existsSync(contextMonitorFile) && contextMonitorCommand) {
-                settings.hooks[extendedEvent].push({
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: contextMonitorCommand,
-                            timeout: 10
-                        }
-                    ]
-                });
-                console.log(`  ${green}✓${reset} Configured ${extendedEvent} context monitor hook`);
-            }
-            else if (!alreadyHasContextMonitor && !node_fs_1.default.existsSync(contextMonitorFile)) {
-                console.warn(`  ${yellow}⚠${reset}  Skipped ${extendedEvent} hook — gsd-context-monitor.js not found at target`);
-            }
+    }
+    // #3329: `.sh` rows register only-if-absent, so an entry registered by an
+    // older installer keeps its old command forever — /gsd-update (which
+    // re-invokes the installer) never re-derived it. On Claude/win32 that left
+    // the pre-#580/#3393 bash-runner-prefixed commands in settings.json
+    // indefinitely. Reconcile existing managed `.sh` entries to the command this
+    // install would generate today. Inert wherever the bash runner is still the
+    // correct shape; scoped to exact managed basenames so user-authored hooks
+    // are never touched.
+    if (reconcileManagedShellHookCommands(settings, shellCommands, { platform: hookOpts.platform, runtime })) {
+        console.log(`  ${green}✓${reset} Reconciled managed .sh hook commands to current format (#3329)`);
+    }
+    // Descriptor-driven (ADR-1239 / #2092): the runtime's capability title.
+    const runtimeLabel = _capabilityTitle(runtime);
+    for (const row of tables.extendedRows) {
+        if (!extendedEvents.includes(row.event))
+            continue;
+        if (!Array.isArray(settings.hooks[row.event])) {
+            settings.hooks[row.event] = [];
         }
-        // ── end Antigravity-only extended hook events ──────────────────────────────
-        // ── FileChanged hook: hot-reload gsd config on .planning/config.json edits ─
-        // Claude Code fires FileChanged when a watched file changes on disk.  Wire
-        // gsd-config-reload.js to reload the gsd config context whenever the user
-        // edits .planning/config.json mid-session, eliminating the need to restart.
-        //
-        // The matcher "config.json" watches for changes to any file named config.json
-        // (Claude Code matches by filename, not full path).  The hook exits silently
-        // when the changed file is not the gsd config.
-        //
-        // Scoped to Claude Code only: Qwen Code's FileChanged support is not yet
-        // verified; extend in a follow-on if empirically confirmed.
-        if (extendedEvents.includes('FileChanged')) {
-            if (!settings.hooks.FileChanged) {
-                settings.hooks.FileChanged = [];
-            }
-            const configReloadFile = node_path_1.default.join(targetDir, 'hooks', 'gsd-config-reload.js');
-            const alreadyHasConfigReload = settings.hooks.FileChanged.some((entry) => entry.hooks && entry.hooks.some((h) => referencesHook(h, 'gsd-config-reload')));
-            if (!alreadyHasConfigReload && node_fs_1.default.existsSync(configReloadFile) && configReloadCommand) {
-                settings.hooks.FileChanged.push({
-                    matcher: 'config.json',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: configReloadCommand,
-                            timeout: 8
-                        }
-                    ]
-                });
-                console.log(`  ${green}✓${reset} Configured FileChanged config-reload hook (Claude Code)`);
-            }
-            else if (!alreadyHasConfigReload && !node_fs_1.default.existsSync(configReloadFile)) {
-                console.warn(`  ${yellow}⚠${reset}  Skipped FileChanged hook — gsd-config-reload.js not found at target`);
-            }
-            else if (!alreadyHasConfigReload && !configReloadCommand) {
-                console.warn(`  ${yellow}⚠${reset}  Skipped FileChanged hook — Node executable path unavailable`);
-            }
+        const entries = settings.hooks[row.event];
+        if (entries.some((entry) => groupReferencesHook(entry, hookStem(row.file))))
+            continue;
+        const command = opts[row.command.opts];
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(targetDir, 'hooks', row.file))) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped ${row.event} hook — ${row.file} not found at target`);
+        }
+        else if (command) {
+            pushHookGroup(entries, row.matcher, command, row.timeout);
+            console.log(`  ${green}✓${reset} ${row.configuredMessage}${row.runtimeLabelSuffix ? ` (${runtimeLabel})` : ''}`);
+        }
+        else if (row.noCommandMessage) {
+            console.warn(`  ${yellow}⚠${reset}  Skipped ${row.event} hook — ${row.noCommandMessage}`);
         }
-        // ── end FileChanged hook ────────────────────────────────────────────────────
     }
-    /* eslint-enable @typescript-eslint/no-unsafe-member-access,
-                     @typescript-eslint/no-unsafe-call,
-                     @typescript-eslint/no-unsafe-assignment */
 }
+function applySettingsJsonHooks(settings, opts) {
+    applySettingsJsonHookTables(settings, opts, { rows: SETTINGS_JSON_HOOK_ROWS, extendedRows: SETTINGS_JSON_EXTENDED_ROWS });
+}
+/* eslint-enable @typescript-eslint/no-unsafe-member-access,
+                 @typescript-eslint/no-unsafe-call,
+                 @typescript-eslint/no-unsafe-assignment,
+                 @typescript-eslint/no-explicit-any */
 // ---------------------------------------------------------------------------
 // Kimi hooks.toml (#2095 EoS/kimi Upgrade 1 — native hook bus)
 //
@@ -2682,13 +2460,13 @@ function buildKimiHooksTomlBlock(targetDir, opts) {
         { event: 'SessionStart', command: cmd('gsd-check-update.js') },
         { event: 'SessionStart', command: cmd('gsd-session-state.sh') },
         // PreToolUse
-        { event: 'PreToolUse', command: cmd('gsd-prompt-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
+        { event: 'PreToolUse', command: cmd('gsd-prompt-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: kimiBlockingGuardTimeout('gsd-prompt-guard.js') },
         { 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 },
+        { event: 'PreToolUse', command: cmd('gsd-worktree-path-guard.js'), matcher: 'WriteFile|StrReplaceFile', timeout: kimiBlockingGuardTimeout('gsd-worktree-path-guard.js') },
+        { event: 'PreToolUse', command: cmd('gsd-write-guard.js'), matcher: 'WriteFile', timeout: kimiBlockingGuardTimeout('gsd-write-guard.js') },
+        { event: 'PreToolUse', command: cmd('gsd-secret-read-guard.js'), matcher: 'ReadFile|Grep|Shell', timeout: kimiBlockingGuardTimeout('gsd-secret-read-guard.js') },
+        { event: 'PreToolUse', command: cmd('gsd-workflow-guard.js'), matcher: 'Shell|WriteFile|StrReplaceFile', timeout: kimiBlockingGuardTimeout('gsd-workflow-guard.js') },
+        { event: 'PreToolUse', command: cmd('gsd-validate-commit.sh'), matcher: 'Shell', timeout: kimiBlockingGuardTimeout('gsd-validate-commit.sh') },
         // PostToolUse
         { event: 'PostToolUse', command: cmd('gsd-context-monitor.js'), timeout: 10 },
         { event: 'PostToolUse', command: cmd('gsd-phase-boundary.sh'), matcher: 'WriteFile|StrReplaceFile', timeout: 5 },
@@ -2761,13 +2539,21 @@ function stripKimiHooksTomlBlock(content) {
  * touch the file's mtime for no reason.
  */
 function writeKimiHooksToml(configPath, targetDir, opts) {
+    const configuredEntrypoints = [];
+    const trackedOpts = {
+        hookOpts: {
+            ...opts.hookOpts,
+            configPath,
+            configuredEntrypoints,
+        },
+    };
     const existing = node_fs_1.default.existsSync(configPath) ? node_fs_1.default.readFileSync(configPath, 'utf8') : '';
     const stripped = stripKimiHooksTomlBlock(existing) ?? '';
-    const block = buildKimiHooksTomlBlock(targetDir, opts);
+    const block = buildKimiHooksTomlBlock(targetDir, trackedOpts);
     const entryCount = block ? (block.match(/\[\[hooks\]\]/g) || []).length : 0;
     if (!block) {
         if (stripped === existing)
-            return { changed: false, path: configPath, entryCount: 0 };
+            return { changed: false, path: configPath, entryCount: 0, configuredEntrypoints };
         if (stripped.trim() === '') {
             if (node_fs_1.default.existsSync(configPath))
                 node_fs_1.default.unlinkSync(configPath);
@@ -2776,15 +2562,15 @@ function writeKimiHooksToml(configPath, targetDir, opts) {
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(configPath), { recursive: true });
             atomicWriteFileSync(configPath, stripped, 'utf8');
         }
-        return { changed: true, path: configPath, entryCount: 0 };
+        return { changed: true, path: configPath, entryCount: 0, configuredEntrypoints };
     }
     const separator = stripped.trim() === '' ? '' : (stripped.endsWith('\n') ? '\n' : '\n\n');
     const next = stripped.trim() === '' ? `${block}\n` : `${stripped}${separator}${block}\n`;
     if (next === existing)
-        return { changed: false, path: configPath, entryCount };
+        return { changed: false, path: configPath, entryCount, configuredEntrypoints };
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(configPath), { recursive: true });
     atomicWriteFileSync(configPath, next, 'utf8');
-    return { changed: true, path: configPath, entryCount };
+    return { changed: true, path: configPath, entryCount, configuredEntrypoints };
 }
 /**
  * Uninstall-time counterpart to writeKimiHooksToml: strips the GSD block and
@@ -2806,6 +2592,45 @@ function removeKimiHooksToml(configPath) {
     return { changed: true };
 }
 // ---------------------------------------------------------------------------
+// Blocking-guard host budget (#3981, #5180)
+//
+// 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. ONE constant and ONE name list, shared by every registration
+// surface that carries a host timeout (settings.json install + migration,
+// Kimi config.toml) so a future change cannot diverge between them.
+// ---------------------------------------------------------------------------
+const BLOCKING_GUARD_TIMEOUT_S = 120;
+const BLOCKING_GUARD_NAMES = [
+    'gsd-prompt-guard',
+    'gsd-workflow-guard',
+    'gsd-worktree-path-guard',
+    'gsd-agent-isolation-guard',
+    'gsd-write-guard',
+    'gsd-secret-read-guard',
+    'gsd-validate-commit',
+];
+// Kimi registers every blocking guard EXCEPT the ones named here: Claude's
+// Agent|Task (subagent-dispatch) matcher segment has no confirmed Kimi tool
+// name, so gsd-agent-isolation-guard has nothing to attach to there (see the
+// buildKimiHooksTomlBlock doc). The divergence from the installer's set is
+// intentional and explicit, not an accident of two hand-kept lists.
+const KIMI_UNREGISTERED_BLOCKING_GUARDS = ['gsd-agent-isolation-guard'];
+const KIMI_BLOCKING_GUARD_NAMES = BLOCKING_GUARD_NAMES.filter((name) => !KIMI_UNREGISTERED_BLOCKING_GUARDS.includes(name));
+// Host budget for a Kimi blocking-guard entry, by script file name. Throws for
+// a script outside KIMI_BLOCKING_GUARD_NAMES so a spec cannot claim the
+// blocking budget for a hook the shared list does not name.
+function kimiBlockingGuardTimeout(scriptFile) {
+    const name = scriptFile.replace(/\.(?:js|sh)$/, '');
+    if (!KIMI_BLOCKING_GUARD_NAMES.includes(name)) {
+        throw new Error(`runtime-hooks-surface: ${scriptFile} is not a Kimi blocking guard (KIMI_BLOCKING_GUARD_NAMES)`);
+    }
+    return BLOCKING_GUARD_TIMEOUT_S;
+}
+// ---------------------------------------------------------------------------
 // referencesHook
 //
 // Pure predicate — checks whether a hook entry object references a managed
@@ -2830,6 +2655,68 @@ function referencesHook(h, hookName) {
         (Array.isArray(args) && args.some(a => typeof a === 'string' && a.includes(hookName))) ||
         (typeof url === 'string' && url.includes(hookName));
 }
+function validateConfiguredEntrypoints(entries, deps = {}) {
+    const statSync = deps.statSync ?? node_fs_1.default.statSync;
+    const accessSync = deps.accessSync ?? node_fs_1.default.accessSync;
+    const resolve = deps.resolveExecutableBinary ?? resolveExecutableBinary;
+    const invalid = [];
+    for (const entry of entries) {
+        let scriptOk = false;
+        try {
+            scriptOk = statSync(entry.scriptPath).isFile();
+            if (!scriptOk) {
+                invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'wrong-file-type' });
+            }
+            else {
+                // #4249: statSync only needs search permission on the parent dirs, so
+                // it succeeds even for a chmod-000 file — the EACCES catch below
+                // never fires for that case. Read permission on the file itself must
+                // be checked explicitly: an interpreter opens the script directly,
+                // and even a self-executable shebang script is opened and read by
+                // its kernel-invoked interpreter, not just exec'd — X_OK alone does
+                // not prove it's readable.
+                try {
+                    accessSync(entry.scriptPath, node_fs_1.default.constants.R_OK);
+                }
+                catch {
+                    scriptOk = false;
+                    invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'unreadable' });
+                }
+            }
+        }
+        catch (statErr) {
+            // #4249 Nit: EACCES means a parent directory couldn't be searched —
+            // a real (if rare) permission problem, distinct from ENOENT's "missing".
+            // EPERM: Windows' equivalent permission-denied code for a directory a
+            // parent path couldn't be traversed into.
+            const code = statErr?.code;
+            const reason = code === 'EACCES' || code === 'EPERM' ? 'unreadable' : 'missing';
+            invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason });
+        }
+        // #4249: selfExecutable is the sole source of truth for whether the OS
+        // execs scriptPath directly via its own shebang (set explicitly by every
+        // producer that needs it — a Windows-Claude .sh hook, Codex's Windows
+        // .cmd shim, Cline's hybrid `env node` hook — rather than inferred from
+        // the absence of interpreterCandidates, which Cline's hybrid case also
+        // carries). Skip on win32 like resolveExecutableBinary's own X_OK
+        // carve-out does: POSIX mode bits don't mean executable on Windows, and a
+        // real accessSync(X_OK) there would fail a .cmd shim under a test that
+        // simulates win32 on a POSIX runner (Node's own no-op only protects an
+        // actual Windows machine). Cline is the only producer where this runs.
+        if (scriptOk && entry.selfExecutable && (entry.platform ?? process.platform) !== 'win32') {
+            try {
+                accessSync(entry.scriptPath, node_fs_1.default.constants.X_OK);
+            }
+            catch {
+                invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'not-executable' });
+            }
+        }
+        if (entry.interpreterCandidates && !entry.interpreterCandidates.some(candidate => resolve(candidate, { platform: entry.platform, requireExecutable: true }) !== null)) {
+            invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'interpreter', path: entry.interpreterCandidates.join(' | '), reason: 'unresolved-interpreter' });
+        }
+    }
+    return invalid.length === 0 ? { ok: true } : { ok: false, invalid };
+}
 module.exports = {
     // Cline
     buildClineRulesBody,
@@ -2891,16 +2778,27 @@ module.exports = {
     removeKimiHooksToml,
     KIMI_HOOKS_TOML_MARKER_BEGIN,
     KIMI_HOOKS_TOML_MARKER_END,
+    // Blocking-guard host budget (#3981, #5180)
+    BLOCKING_GUARD_TIMEOUT_S,
+    BLOCKING_GUARD_NAMES,
+    KIMI_UNREGISTERED_BLOCKING_GUARDS,
+    KIMI_BLOCKING_GUARD_NAMES,
     // Shared
     stageTransitiveHookLibs,
     buildHookCommand,
+    recordConfiguredHookCommand,
     applySettingsJsonHooks,
+    applySettingsJsonHookTables,
+    SETTINGS_JSON_HOOK_ROWS,
+    SETTINGS_JSON_EXTENDED_ROWS,
+    validateConfiguredEntrypoints,
     referencesHook,
     rewriteLegacyManagedNodeHookCommands,
     reconcileManagedShellHookCommands,
     normalizeNodePath,
     resolveNodeRunner,
     buildNodeRunnerChainToken,
+    resolveBashExecutable,
     resolveBashRunner,
     NODE_RUNNER_RESOLVER_HOOK,
     // Atomic write seam (shared with bin/install.js so all writes participate