@opengsd/gsd-core 1.5.0-rc.1 → 1.5.0-rc.2

package/bin/install.js

@@ -37,7 +37,7 @@ const {
   applyWorktreeBaseRef,
   readBaseRefFromSettings,
 } = require('../gsd-core/bin/lib/worktree-base-ref.cjs');
-const { resolveRuntimeConfigIntent } = require('../gsd-core/bin/lib/runtime-config-adapter-registry.cjs');
+const { resolveInstallPlan } = require('../gsd-core/bin/lib/runtime-config-adapter-registry.cjs');
 // Canonical set of hook files shipped to users. Imported here so writeManifest()
 // records exactly the same set that build-hooks.js copies to hooks/dist/, making
 // the manifest and the installed hooks/ dir structurally identical. Avoids the
@@ -45,6 +45,11 @@ const { resolveRuntimeConfigIntent } = require('../gsd-core/bin/lib/runtime-conf
 const { HOOKS_TO_COPY: _HOOKS_TO_COPY } = require('../scripts/build-hooks.js');
 const INSTALLED_HOOK_FILES = new Set(_HOOKS_TO_COPY);
 
+// ADR-857 phase 5f-1: hook-surface writer functions extracted to a dedicated module.
+// bin/install.js re-exports everything from hooksSurface so existing callers
+// (require('../bin/install.js').writeCursorHooksJson etc.) continue to work.
+const hooksSurface = require('../gsd-core/bin/lib/runtime-hooks-surface.cjs');
+
 /**
  * Runtimes that register hyphen-form `name:` per #2808 AND copy agent bodies
  * verbatim (only branding swaps, no namespace conversion), so retired
@@ -405,7 +410,7 @@ function selectRuntimesFromArgs(runtimeArgs) {
   if (runtimeArgs.includes('--copilot')) selected.push('copilot');
   if (runtimeArgs.includes('--antigravity')) selected.push('antigravity');
   if (runtimeArgs.includes('--cursor')) selected.push('cursor');
-  if (runtimeArgs.includes('--windsurf')) selected.push('windsurf');
+  if (runtimeArgs.includes('--windsurf') || runtimeArgs.includes('--devin-desktop')) selected.push('windsurf');
   if (runtimeArgs.includes('--augment')) selected.push('augment');
   if (runtimeArgs.includes('--trae')) selected.push('trae');
   if (runtimeArgs.includes('--qwen')) selected.push('qwen');
@@ -460,9 +465,9 @@ function getDirName(runtime) {
   if (runtime === 'gemini') return '.gemini';
   if (runtime === 'kilo') return '.kilo';
   if (runtime === 'codex') return '.codex';
-  if (runtime === 'antigravity') return '.agent';
+  if (runtime === 'antigravity') return '.agents';
   if (runtime === 'cursor') return '.cursor';
-  if (runtime === 'windsurf') return '.windsurf';
+  if (runtime === 'windsurf') return '.devin';
   if (runtime === 'augment') return '.augment';
   if (runtime === 'trae') return '.trae';
   if (runtime === 'qwen') return '.qwen';
@@ -495,7 +500,7 @@ function getConfigDirFromHome(runtime, isGlobal) {
   if (runtime === 'kilo') return "'.config', 'kilo'";
   if (runtime === 'codex') return "'.codex'";
   if (runtime === 'antigravity') {
-    if (!isGlobal) return "'.agent'";
+    if (!isGlobal) return "'.agents'";
     const antigravityDir = resolveAntigravityGlobalDir();
     const rel = path.relative(os.homedir(), antigravityDir);
     const segments = rel.split(path.sep).filter(Boolean);
@@ -622,215 +627,22 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
   return `${resolvedTarget}/`;
 }
 
-/**
- * Normalize a raw `process.execPath` to a stable, upgrade-safe node binary
- * path. On Homebrew installs, `process.execPath` resolves symlinks and returns
- * the versioned Cellar path (e.g.
- * `/usr/local/Cellar/node/25.8.1/bin/node`). Baking that path into hook
- * commands causes `dyld: Library not loaded` errors after `brew upgrade node`
- * because the shared libraries referenced by the Cellar binary have changed
- * SOVERSION. (#3181)
- *
- * The stable Homebrew symlinks (`/usr/local/bin/node` for Intel,
- * `/opt/homebrew/bin/node` for Apple Silicon) survive upgrades — Homebrew
- * re-points them atomically. We prefer those when a Cellar path is detected.
- *
- * Non-Homebrew installs (NVM, system node, Windows, etc.) are returned as-is.
- */
-function normalizeNodePath(execPath, opts) {
-  if (!execPath) return execPath;
-  const env = (opts && opts.env) || process.env;
-  const existsSync = (opts && opts.existsSync) || fs.existsSync;
-
-  // fnm multishell shim: C:/Users/<u>/AppData/Local/fnm_multishells/<pid>_<ts>/node.exe
-  // These are per-shell-session ephemeral directories that fnm cleans up on shell exit.
-  // Probe the stable fnm alias paths instead so baked hook commands survive shell restarts.
-  // (#977)
-  // TODO: Volta (~/.volta/bin/node → ~/.volta/tools/image/node/<ver>/bin/node) and
-  // nvm-windows (AppData/Roaming/nvm/<ver>/node.exe) have analogous issues — future work.
-  const normalizedForMatch = execPath.replace(/\\/g, '/');
-  if (/\/fnm_multishells\/[0-9]+_[0-9]+\/node(\.exe)?$/i.test(normalizedForMatch)) {
-    const candidates = [];
-    if (env.FNM_DIR) {
-      // Preferred: alias installed directly under FNM_DIR/aliases/default/
-      candidates.push(`${env.FNM_DIR}/aliases/default/node.exe`);
-      // POSIX layout (no .exe)
-      candidates.push(`${env.FNM_DIR}/aliases/default/bin/node`);
-    }
-    if (env.APPDATA) {
-      // Fallback: fnm default location on Windows when FNM_DIR is not set
-      candidates.push(`${env.APPDATA}/fnm/aliases/default/node.exe`);
-    }
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) return candidate;
-    }
-    // No stable alias found — return raw path unchanged (graceful fallback)
-    return execPath;
-  }
-
-  // Intel Homebrew: /usr/local/Cellar/node/<version>/bin/node
-  // or /usr/local/Cellar/node@20/<version>/bin/node
-  if (/^\/usr\/local\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
-    return '/usr/local/bin/node';
-  }
-  // Apple Silicon Homebrew: /opt/homebrew/Cellar/node/<version>/bin/node
-  // or /opt/homebrew/Cellar/node@18/<version>/bin/node
-  if (/^\/opt\/homebrew\/Cellar\/node(@\d+)?\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
-    return '/opt/homebrew/bin/node';
-  }
-  return execPath;
-}
-
-/**
- * Resolve the absolute path to the node binary running the installer.
- * Used as the runner for .js hooks so they execute in GUI/minimal-PATH
- * runtimes (Gemini, Antigravity, Codex CLIs launched from a Finder
- * shortcut etc.) where bare `node` is not on `/usr/bin:/bin:/usr/sbin:/sbin`
- * and the hook would fail with `node: command not found` (#2979).
- *
- * Returns a forward-slash-normalized, double-quoted path so the emitted
- * command is shell-safe across POSIX and Windows. `process.execPath`
- * gives the absolute path of the node binary actively running the
- * installer — that is the version the user just installed under, and
- * the right default runtime for hooks invoked under the same install.
- *
- * When `process.execPath` is a versioned Homebrew Cellar path, the stable
- * Homebrew symlink is returned instead to survive `brew upgrade node` (#3181).
- *
- * When `process.execPath` is an ephemeral fnm multishell shim, the stable fnm
- * alias path is returned instead so managed hook commands survive shell restarts
- * (#977). An optional `opts` bag (`{ env, existsSync }`) is accepted for
- * testability; production callers omit it to get real env / fs.
- */
-function resolveNodeRunner(opts) {
-  const execPath = typeof process.execPath === 'string' ? process.execPath : '';
-  if (!execPath) return null;
-  const stablePath = normalizeNodePath(execPath, opts);
-  // JSON.stringify produces a properly escaped double-quoted shell token,
-  // safe for paths containing spaces or unusual characters.
-  return JSON.stringify(stablePath.replace(/\\/g, '/'));
-}
-
-/**
- * Rewrite legacy `node .../gsd-*.js` command strings in settings.hooks to use
- * the absolute Node binary path (#2979 follow-up: CR feedback on #3002).
- *
- * The original #2979 fix only emitted absolute paths for *newly registered*
- * hooks. Pre-existing entries kept their bare `node ` prefix on reinstall,
- * which left them broken under minimal-PATH GUI runtimes — exactly the
- * failure mode the original fix was meant to close. This walker normalizes
- * any managed-hook entry whose command starts with bare `node ` to
- * `<absoluteRunner> <script>` while leaving non-managed and non-bare-node
- * entries (user-authored hooks, shell scripts, etc.) untouched.
- *
- * Returns true if any entry was rewritten.
- */
-function resolveBashRunner(opts) {
-  const platform = (opts && opts.platform) || process.platform;
-  if (platform !== 'win32') return 'bash';
-
-  const env = (opts && opts.env) || process.env;
-  const exists = (opts && opts.existsSync) || fs.existsSync;
-  const candidates = [];
-  if (env.GSD_BASH_PATH) candidates.push(env.GSD_BASH_PATH);
-  if (env.ProgramFiles) candidates.push(path.win32.join(env.ProgramFiles, 'Git', 'bin', 'bash.exe'));
-  if (env['ProgramFiles(x86)']) candidates.push(path.win32.join(env['ProgramFiles(x86)'], 'Git', 'bin', 'bash.exe'));
-  if (env.SystemDrive) {
-    candidates.push(path.win32.join(env.SystemDrive, 'Program Files', 'Git', 'bin', 'bash.exe'));
-    candidates.push(path.win32.join(env.SystemDrive, 'Program Files (x86)', 'Git', 'bin', 'bash.exe'));
-  }
-
-  for (const candidate of candidates) {
-    if (candidate && exists(candidate)) {
-      return JSON.stringify(candidate.replace(/\\/g, '/'));
-    }
-  }
-  return null;
-}
+// normalizeNodePath, resolveNodeRunner, resolveBashRunner, referencesHook are
+// now owned by the runtime-hooks-surface module. Import them here so
+// install.js callers continue to work and so there is a single implementation
+// of these helpers.
+const normalizeNodePath = hooksSurface.normalizeNodePath;
+const resolveNodeRunner = hooksSurface.resolveNodeRunner;
+const resolveBashRunner = hooksSurface.resolveBashRunner;
+// referencesHook: pure predicate over hook entry objects, shared between
+// install() and finishInstall() (ADR-857 phase 5f-1b).
+const referencesHook = hooksSurface.referencesHook;
+// applySettingsJsonHooks: mutates settings.hooks.* in place with all GSD-managed
+// hook registrations for settings.json-surface runtimes (ADR-857 phase 5f-1b).
+const applySettingsJsonHooks = hooksSurface.applySettingsJsonHooks;
 
 function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
-  if (!settings || !settings.hooks || !absoluteRunner) return false;
-  if (!opts) opts = {};
-  const platform = opts.platform || process.platform;
-  let changed = false;
-  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 (!h || typeof h.command !== 'string') continue;
-        // args-form entries have the script path in h.args[] and h.command is
-        // the launcher executable (not a managed hook command).  These are
-        // intentional user wrappers — do not rewrite them. (#976)
-        if (Array.isArray(h.args) && h.args.length > 0) continue;
-        let trimmed = h.command.trim();
-        const hadPowerShellCallOperator = platform === 'win32' && /^&\s+/.test(trimmed);
-        if (hadPowerShellCallOperator) {
-          trimmed = trimmed.replace(/^&\s+/, '').trim();
-        }
-        // Match two runner forms:
-        //   1. Legacy bare-node form: `node <script>` (#2979/#3002)
-        //   2. Cellar-path form: `"/usr/local/Cellar/node/<v>/bin/node" <script>`
-        //      or `"/opt/homebrew/Cellar/node/<v>/bin/node" <script>` (#3181)
-        //
-        // Both patterns use the same script-token capture group so the rewrite
-        // is uniform. We detect the Cellar form by extracting the runner token
-        // and running it through normalizeNodePath.
-        //
-        // The previous shape used `trimmed.includes(<filename>)` which would
-        // false-positive on user-authored hooks whose path merely contained
-        // a managed filename as a substring (e.g.
-        // /home/me/scripts/wraps-gsd-check-update.js-and-more.js). #3002 CR.
-        const m = trimmed.match(/^node\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/) ||
-                  trimmed.match(/^("([^"]+)"|'([^']+)'|(\S+))\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/);
-        if (!m) continue;
-
-        let runnerToken, scriptToken, scriptPath;
-        if (/^node\s+/.test(trimmed)) {
-          // bare-node form
-          runnerToken = 'node';
-          scriptToken = m[1];
-          scriptPath = m[2] || m[3] || m[4] || '';
-        } else {
-          // quoted/unquoted runner form — check whether runner is a Cellar path
-          runnerToken = m[1];
-          const runnerPath = (m[2] || m[3] || m[4] || '').replace(/\\/g, '/');
-          const stableRunner = normalizeNodePath(runnerPath);
-          // Process Cellar paths so they normalize to a stable symlink. On
-          // Windows, already-absolute runners still flow through the projection
-          // seam because some runtimes need additional wrapper policy while
-          // others must stay shell-neutral (#3362, #3413).
-          if (stableRunner === runnerPath && platform !== 'win32') continue;
-          scriptToken = m[5];
-          scriptPath = m[6] || m[7] || m[8] || '';
-        }
-
-        // Take the basename — match against MANAGED_HOOK_FILES by exact
-        // equality, not substring containment. Handles both forward and
-        // backslash separators (Windows).
-        if (!isManagedHookBasename(scriptPath, { surface: 'settings-json' })) continue;
-
-        const projectedCommand = projectLegacySettingsHookCommand({
-          absoluteRunner,
-          scriptPath,
-          scriptToken,
-          runtime: opts.runtime || 'generic',
-          platform,
-        });
-        if (!projectedCommand) continue;
-
-        // Skip only when the existing managed command already matches the
-        // desired runtime-aware projected shape. This preserves Gemini's
-        // required PowerShell prefix while still letting Claude strip stale
-        // prefixes on reinstall (#3413).
-        if (h.command === projectedCommand) continue;
-
-        h.command = projectedCommand;
-        changed = true;
-      }
-    }
-  }
-  return changed;
+  return hooksSurface.rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts);
 }
 
 /**
@@ -856,22 +668,7 @@ function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner, opts) {
  * @returns {string|null} The toml block to append, or null on missing runner.
  */
 function buildCodexHookBlock(targetDir, opts) {
-  const absoluteRunner = opts && opts.absoluteRunner;
-  if (!absoluteRunner) return null;
-  const eol = (opts && opts.eol) || '\n';
-  const platform = (opts && opts.platform) || process.platform;
-  const updateCheckScript = path.resolve(targetDir, 'hooks', 'gsd-check-update.js');
-  const commandValue = projectCodexHookTomlCommand({
-    absoluteRunner,
-    scriptPath: updateCheckScript,
-    platform,
-  });
-  return `${eol}# GSD Hooks${eol}` +
-    `[[hooks.SessionStart]]${eol}` +
-    `${eol}` +
-    `[[hooks.SessionStart.hooks]]${eol}` +
-    `type = "command"${eol}` +
-    `command = "${commandValue}"${eol}`;
+  return hooksSurface.buildCodexHookBlock(targetDir, opts);
 }
 
 /**
@@ -888,45 +685,7 @@ function buildCodexHookBlock(targetDir, opts) {
  * @returns {{ content: string, changed: boolean }}
  */
 function rewriteLegacyCodexHookBlock(content, absoluteRunner, opts) {
-  if (!content || !absoluteRunner) return { content, changed: false };
-  const platform = (opts && opts.platform) || process.platform;
-  let changed = false;
-  // Match `command = "node <scriptToken>"` lines where scriptToken is
-  // either an unquoted path (no spaces) or a toml-escaped quoted path.
-  // The whole RHS is a toml-double-quoted string; interior quotes are \".
-  // Examples we want to migrate:
-  //   command = "node /Users/x/.codex/hooks/gsd-check-update.js"
-  //   command = "node \"/Users/x/.codex/hooks/gsd-check-update.js\""
-  // Examples we must leave alone:
-  //   command = "\"/usr/local/bin/node\" \"/path/to/gsd-check-update.js\""  ← already absolute
-  //   command = "node /home/me/my-custom.js"                                ← user-owned filename
-  const updated = content.replace(
-    /^(command\s*=\s*")node\s+((?:\\"[^"]+\\"|\S+))("\s*)$/gm,
-    (full, prefix, scriptToken, suffix) => {
-      // Extract the underlying script path from the captured token —
-      // either the bare token or the decoded inner content of \"...\".
-      const quoted = scriptToken.match(/^\\"([\s\S]+)\\"$/);
-      let scriptPath = scriptToken;
-      if (quoted) {
-        try {
-          scriptPath = String(parseTomlValue(`"${quoted[1]}"`, 0).value);
-        } catch {
-          scriptPath = quoted[1];
-        }
-      }
-      if (!isManagedHookBasename(scriptPath, { surface: 'codex-toml' })) return full;
-      const desiredCommand = projectCodexHookTomlCommand({
-        absoluteRunner,
-        scriptPath,
-        platform,
-      });
-      const currentCommand = `${prefix}${scriptToken}${suffix}`.replace(/^(command\s*=\s*")|("\s*)$/g, '');
-      if (currentCommand === desiredCommand) return full;
-      changed = true;
-      return `${prefix}${desiredCommand}${suffix}`;
-    },
-  );
-  return { content: updated, changed };
+  return hooksSurface.rewriteLegacyCodexHookBlock(content, absoluteRunner, opts);
 }
 
 /**
@@ -949,83 +708,7 @@ function rewriteLegacyCodexHookBlock(content, absoluteRunner, opts) {
  * @returns {{ changed: boolean, wrote: boolean, path: string }}
  */
 function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
-  const hooksJsonPath = path.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;
-  let parsed = {};
-  let currentContent = null;
-  if (fs.existsSync(hooksJsonPath)) {
-    const raw = fs.readFileSync(hooksJsonPath, 'utf8');
-    currentContent = raw;
-    if (raw.trim()) {
-      try {
-        parsed = JSON.parse(raw);
-      } catch (err) {
-        throw new Error(`hooks.json parse failed: ${err && err.message ? err.message : String(err)}`);
-      }
-    }
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) parsed = {};
-
-  const usesNestedHooksObject =
-    parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks);
-  const hookTable = usesNestedHooksObject ? parsed.hooks : parsed;
-  const eventEntries = Array.isArray(hookTable[eventName]) ? hookTable[eventName] : [];
-
-  let removedLegacy = false;
-  const sanitizedEntries = [];
-  for (const entry of eventEntries) {
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
-    const originalHooks = Array.isArray(entry.hooks) ? entry.hooks : [];
-    if (originalHooks.length === 0) {
-      sanitizedEntries.push(entry);
-      continue;
-    }
-    const keptHooks = originalHooks.filter((hook) => {
-      const cmd = hook && typeof hook === 'object' ? hook.command : null;
-      const managed = isManagedHookCommand(cmd, {
-        surface: 'codex-hooks-json',
-        includeLegacyAliases: true,
-        configDir: targetDir,
-      });
-      if (managed) removedLegacy = true;
-      return !managed;
-    });
-    if (keptHooks.length === 0) continue;
-    const nextEntry = { ...entry, hooks: keptHooks };
-    sanitizedEntries.push(nextEntry);
-  }
-
-  if (managedCommand) {
-    const hookEntry = { type: 'command', command: managedCommand };
-    // #772: emit commandWindows so Codex picks the .cmd shim on Windows and
-    // the POSIX command on other platforms — without requiring per-OS config
-    // regeneration. Sourced from HookHandlerConfig.command_windows field in
-    // codex-rs/config/src/hook_config.rs (alias: commandWindows).
-    if (commandWindows) hookEntry.commandWindows = commandWindows;
-    if (timeout !== undefined) hookEntry.timeout = timeout;
-    const newEntry = { hooks: [hookEntry] };
-    if (matcher !== undefined) newEntry.matcher = matcher;
-    sanitizedEntries.push(newEntry);
-  }
-
-  if (sanitizedEntries.length > 0) {
-    hookTable[eventName] = sanitizedEntries;
-  } else {
-    delete hookTable[eventName];
-  }
-  if (usesNestedHooksObject) parsed.hooks = hookTable;
-
-  const nextContent = `${JSON.stringify(parsed, null, 2)}\n`;
-  const changed = currentContent !== nextContent;
-  const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
-  if (shouldWrite) {
-    atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
-  }
-
-  return { changed: changed || removedLegacy, wrote: shouldWrite, path: hooksJsonPath };
+  return hooksSurface.reconcileCodexHooksJsonEvent(targetDir, eventName, opts);
 }
 
 /**
@@ -1037,7 +720,7 @@ function reconcileCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
  * @returns {{ changed: boolean, wrote: boolean, path: string }}
  */
 function reconcileCodexHooksJsonSessionStart(targetDir, opts = {}) {
-  return reconcileCodexHooksJsonEvent(targetDir, 'SessionStart', opts);
+  return hooksSurface.reconcileCodexHooksJsonSessionStart(targetDir, opts);
 }
 
 /**
@@ -1070,41 +753,7 @@ function reconcileCodexHooksJsonSessionStart(targetDir, opts = {}) {
  * @returns {{ invocation: { interpreter: string, target: string }, cmdPath: string, hookCommand: string, render: { cmd: () => string } }|null}
  */
 function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
-  if (!absoluteRunnerToken) return null;
-  // absoluteRunnerToken is JSON-quoted (e.g. '"C:/path/node.exe"'). Unwrap to
-  // get the raw interpreter path for the invocation record and render output.
-  let interpreter;
-  try {
-    interpreter = JSON.parse(absoluteRunnerToken);
-  } catch {
-    interpreter = absoluteRunnerToken;
-  }
-  // Normalise to forward slashes for cross-shell safety (same as other Windows
-  // hook path normalisations in this codebase).
-  const targetAbs = scriptAbsPath.replace(/\\/g, '/');
-  const scriptQuoted = JSON.stringify(targetAbs);
-  // .cmd shim lives alongside the .js file, replacing the extension.
-  const cmdPath = scriptAbsPath.replace(/\.js$/, '.cmd');
-  // The hook command written to hooks.json is just the .cmd path (double-quoted
-  // for spaces-in-path safety). cmd.exe executes .cmd files natively via
-  // CreateProcess — no runner prefix required.
-  const hookCommand = JSON.stringify(cmdPath.replace(/\\/g, '/'));
-  const runnerQuoted = JSON.stringify(interpreter);
-  return {
-    invocation: { interpreter, target: scriptAbsPath },
-    cmdPath,
-    hookCommand,
-    // Typed fields for IR-level assertions (CONTRIBUTING.md L558-L565).
-    // These describe the render semantics in a structured way so tests can
-    // assert on the generator contract without coupling to rendered text.
-    eol: { cmd: '\r\n' },            // CRLF — canonical for cmd.exe .cmd files
-    passthroughArgs: true,           // the shim forwards all args via %*
-    render: {
-      // Use CRLF line endings for strict cmd.exe compatibility (LF-only
-      // .cmd files work in modern Windows but CRLF is the canonical format).
-      cmd: () => `@ECHO OFF\r\n@SETLOCAL\r\n@${runnerQuoted} ${scriptQuoted} %*\r\n`,
-    },
-  };
+  return hooksSurface.buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken);
 }
 
 /**
@@ -1135,69 +784,7 @@ function buildCodexHookWindowsShimIR(scriptAbsPath, absoluteRunnerToken) {
  * @returns {{ changed: boolean, wrote: boolean, path: string }}
  */
 function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
-  const platform = opts.platform || process.platform;
-  const absoluteRunner = opts.absoluteRunner || null;
-  const hooksJsonPath = path.join(targetDir, 'hooks.json');
-  if (!absoluteRunner) return { changed: false, wrote: false, path: hooksJsonPath };
-
-  // Normalize backslashes to forward slashes so isManagedHookCommand can
-  // match stored commands against configDir on Windows CI runners where
-  // path.resolve returns backslash paths but the stored command may use
-  // forward slashes (or vice versa). Forward-slash paths are always valid on
-  // Windows for both Node.js and Codex, so this normalization is safe for all
-  // platforms. (#772 — same fix applied to ensureCodexHooksJsonEvent.)
-  const scriptPath = path.resolve(targetDir, 'hooks', 'gsd-check-update.js').replace(/\\/g, '/');
-
-  // #772: compute the Windows .cmd shim path cross-platform so that
-  // `commandWindows` can be emitted in hooks.json regardless of the host OS.
-  // The .cmd path is always the .js script path with extension replaced.
-  const cmdShimPath = scriptPath.replace(/\.js$/, '.cmd');
-
-  let managedCommand;
-  if (platform === 'win32') {
-    // #3426 fix: on Windows, write a .cmd shim and use its path as the hook
-    // command. This avoids the MSYS bash.exe POSIX-exec failure when Codex's
-    // hook dispatcher tries to run node.exe through the Git Bash exec layer.
-    const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
-    if (!shimIR) return { changed: false, wrote: false, path: hooksJsonPath };
-    try {
-      atomicWriteFileSync(shimIR.cmdPath, shimIR.render.cmd(), 'utf8');
-    } catch (shimWriteErr) {
-      // Shim write failed — do NOT fall back to the old "node.exe script.js"
-      // command. That form triggers the `bash.exe: cannot execute binary file`
-      // failure that #3426 exists to fix, so a silent fallback would silently
-      // restore the original bug. Instead: warn loudly and skip the registration
-      // for this runtime so the user sees an actionable message rather than a
-      // successful install that fails at hook-dispatch time.
-      const reason = shimWriteErr && shimWriteErr.message ? shimWriteErr.message : String(shimWriteErr);
-      console.warn(
-        `  ${yellow}⚠${reset}  Codex Windows hook NOT installed — .cmd shim write failed: ${reason}. ` +
-          `Fix the write error (permissions? disk full?) and re-run the installer. ` +
-          `Do NOT use the legacy node.exe command path — it triggers the #3426 bash.exe POSIX-exec failure.`,
-      );
-      return { changed: false, wrote: false, path: hooksJsonPath };
-    }
-    managedCommand = shimIR.hookCommand;
-  } else {
-    managedCommand = projectManagedHookCommand({
-      absoluteRunner,
-      scriptPath,
-      runtime: 'codex',
-      platform,
-    });
-  }
-
-  if (!managedCommand) return { changed: false, wrote: false, path: hooksJsonPath };
-
-  // #772: emit commandWindows — the .cmd shim path — but ONLY on Windows where
-  // the shim was actually written. On POSIX, commandWindows is omitted to avoid
-  // pointing Windows Codex at a non-existent .cmd file (the shim is only present
-  // when install() ran natively on Windows and wrote it via buildCodexHookWindowsShimIR).
-  const commandWindows = platform === 'win32'
-    ? JSON.stringify(cmdShimPath.replace(/\\/g, '/'))
-    : undefined;
-
-  return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand, commandWindows });
+  return hooksSurface.ensureCodexHooksJsonSessionStart(targetDir, opts);
 }
 
 /**
@@ -1224,50 +811,7 @@ function ensureCodexHooksJsonSessionStart(targetDir, opts = {}) {
  * @returns {{ changed: boolean, wrote: boolean, path: string }}
  */
 function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
-  const platform = opts.platform || process.platform;
-  const absoluteRunner = opts.absoluteRunner || null;
-  const hooksJsonPath = path.join(targetDir, 'hooks.json');
-  if (!absoluteRunner) return { changed: false, wrote: false, path: hooksJsonPath };
-
-  // Normalize backslashes to forward slashes so that isManagedHookCommand can
-  // match the stored command against configDir on Windows. path.resolve on
-  // Windows returns backslash paths, but when platform is not 'win32'
-  // (e.g. platform: 'linux' in a test running on a Windows CI runner),
-  // projectManagedHookCommand does not normalize them — producing a mismatch
-  // between the stored command and the configDir-based hook-dir prefix used
-  // for deduplication. Forward-slash paths are always valid on Windows (Node.js
-  // and Codex both accept them), so normalizing here is safe for all platforms.
-  const scriptPath = path.resolve(targetDir, 'hooks', 'gsd-context-monitor.js').replace(/\\/g, '/');
-
-  let managedCommand;
-  if (platform === 'win32') {
-    // #3426 fix pattern: on Windows, write a .cmd shim and use its path as the
-    // hook command. The same bash.exe POSIX-exec failure that affects
-    // gsd-check-update.js also affects gsd-context-monitor.js.
-    const shimIR = buildCodexHookWindowsShimIR(scriptPath, absoluteRunner);
-    if (!shimIR) return { changed: false, wrote: false, path: hooksJsonPath };
-    try {
-      atomicWriteFileSync(shimIR.cmdPath, shimIR.render.cmd(), 'utf8');
-    } catch (shimWriteErr) {
-      const reason = shimWriteErr && shimWriteErr.message ? shimWriteErr.message : String(shimWriteErr);
-      console.warn(
-        `  ${yellow}⚠${reset}  Codex Windows hook NOT installed — .cmd shim write failed for ${eventName}: ${reason}. ` +
-          `Fix the write error (permissions? disk full?) and re-run the installer.`,
-      );
-      return { changed: false, wrote: false, path: hooksJsonPath };
-    }
-    managedCommand = shimIR.hookCommand;
-  } else {
-    managedCommand = projectManagedHookCommand({
-      absoluteRunner,
-      scriptPath,
-      runtime: 'codex',
-      platform,
-    });
-  }
-
-  if (!managedCommand) return { changed: false, wrote: false, path: hooksJsonPath };
-  return reconcileCodexHooksJsonEvent(targetDir, eventName, { managedCommand, timeout: 10 });
+  return hooksSurface.ensureCodexHooksJsonEvent(targetDir, eventName, opts);
 }
 
 /**
@@ -1277,11 +821,11 @@ function ensureCodexHooksJsonEvent(targetDir, eventName, opts = {}) {
  * @param {string} eventName
  */
 function removeCodexHooksJsonEvent(targetDir, eventName) {
-  return reconcileCodexHooksJsonEvent(targetDir, eventName, { managedCommand: null });
+  return hooksSurface.removeCodexHooksJsonEvent(targetDir, eventName);
 }
 
 function removeCodexHooksJsonSessionStart(targetDir) {
-  return reconcileCodexHooksJsonSessionStart(targetDir, { managedCommand: null });
+  return hooksSurface.removeCodexHooksJsonSessionStart(targetDir);
 }
 
 /**
@@ -1298,62 +842,7 @@ function removeCodexHooksJsonSessionStart(targetDir) {
  *   runtime: target runtime name for shell projection policy.
  */
 function buildHookCommand(configDir, hookName, opts) {
-  if (!opts) opts = {};
-  const platform = opts.platform || process.platform;
-  const runtime = opts.runtime || 'generic';
-  const isShellHook = hookName.endsWith('.sh');
-
-  // #166: Claude Code executes these hook commands inside a bash context on
-  // Windows, so wrapping `.sh` hooks with an explicit `bash.exe` path can
-  // trigger `bash.exe: ... cannot execute binary file`. Emit only the quoted
-  // script path for Claude on Windows.
-  if (shellHookOmitsBashRunner({ platform, runtime, isShellHook })) {
-    if (opts.portableHooks) {
-      const portableBaseDir = projectPortableHookBaseDir({
-        configDir,
-        homeDir: os.homedir(),
-      });
-      return JSON.stringify(`${portableBaseDir}/hooks/${hookName}`);
-    }
-    return JSON.stringify(configDir.replace(/\\/g, '/') + '/hooks/' + hookName);
-  }
-
-  // POSIX .sh hooks run under PATH-resolved `bash`: POSIX guarantees /bin/sh
-  // but not /bin/bash, and distros like NixOS do not ship /bin/bash by default.
-  // Windows Codex launches hooks from PowerShell/cmd environments where bare
-  // `bash` may not be on PATH, so resolve Git Bash explicitly or return null so
-  // callers skip registration instead of installing a known-broken hook (#3393).
-  // .js hooks still need the absolute node path because GUI-launched runtimes
-  // start with a minimal PATH that may not include nvm/Homebrew/Volta node
-  // binaries (#2979).
-  const nodeRunner = resolveNodeRunner();
-  const runner = isShellHook ? resolveBashRunner(opts) : nodeRunner;
-  // Runner resolvers return null when the executable path is unavailable.
-  // Fall through with null so callers can skip registration with a warning
-  // instead of emitting a command that recreates the original hook failure.
-  if (runner === null) return null;
-
-  if (opts.portableHooks) {
-    const portableBaseDir = projectPortableHookBaseDir({
-      configDir,
-      homeDir: os.homedir(),
-    });
-    return projectManagedHookCommand({
-      absoluteRunner: runner,
-      scriptPath: `${portableBaseDir}/hooks/${hookName}`,
-      runtime: opts.runtime || 'generic',
-      platform,
-    });
-  }
-
-  // Default: absolute path with forward slashes (Windows-safe, fixes #2045/#2046).
-  const hooksPath = configDir.replace(/\\/g, '/') + '/hooks/' + hookName;
-  return projectManagedHookCommand({
-    absoluteRunner: runner,
-    scriptPath: hooksPath,
-    runtime,
-    platform,
-  });
+  return hooksSurface.buildHookCommand(configDir, hookName, opts);
 }
 
 /**
@@ -1720,6 +1209,52 @@ function injectEffortFrontmatter(content, effortValue) {
   return `${before}effort: ${effortValue}${eol}${after}`;
 }
 
+/**
+ * #767 — Inject `disallowedTools: <value>` into the YAML frontmatter of a Claude .md agent.
+ * Mirrors injectEffortFrontmatter: idempotent (skips if disallowedTools: already present),
+ * inserts immediately before the closing `---`. Claude-only — never call for other runtimes,
+ * which break on unknown frontmatter keys.
+ */
+function injectDisallowedToolsFrontmatter(content, disallowedValue) {
+  // Detect the dominant EOL from the first line (the opening `---`).
+  // If the very first `---` is followed by \r\n, treat the whole file as CRLF.
+  const eol = /^---\r\n/.test(content) ? '\r\n' : '\n';
+
+  // Build a frontmatter-matching regex that tolerates an optional \r before
+  // each \n, so we handle both LF and CRLF files without needing to normalise
+  // the whole content.
+  const fmRe = /^---\r?\n([\s\S]*?)^---\r?$/m;
+  const match = fmRe.exec(content);
+  if (!match) return content; // no YAML frontmatter — leave unchanged
+
+  // Idempotency guard: don't insert a second disallowedTools: line.
+  const fmBody = match[1]; // content between the two `---` lines
+  if (/^disallowedTools:/m.test(fmBody)) return content;
+
+  // Locate the exact position of the closing `---` line so we can insert
+  // before it using a simple string splice.
+  const openLen = 3 + eol.length; // "---" + eol
+  const closingStart = match.index + openLen + fmBody.length;
+
+  const before = content.slice(0, closingStart);
+  const after = content.slice(closingStart);
+  return `${before}disallowedTools: ${disallowedValue}${eol}${after}`;
+}
+
+// #767 — Read-only verifier/auditor agents get a Claude-Code disallowedTools deny-list.
+// Group A (pure read-only) deny Write,Edit,MultiEdit. Group B report-writers Write one
+// output file so they deny only Edit,MultiEdit. gsd-nyquist-auditor is intentionally
+// excluded (it legitimately uses Write AND Edit to create/patch test files).
+const READONLY_AGENT_DISALLOWED_TOOLS = {
+  'gsd-plan-checker': 'Write, Edit, MultiEdit',
+  'gsd-integration-checker': 'Write, Edit, MultiEdit',
+  'gsd-ui-checker': 'Write, Edit, MultiEdit',
+  'gsd-verifier': 'Edit, MultiEdit',
+  'gsd-doc-verifier': 'Edit, MultiEdit',
+  'gsd-eval-auditor': 'Edit, MultiEdit',
+  'gsd-ui-auditor': 'Edit, MultiEdit',
+};
+
 /**
  * #2517 — Read a single GSD config file (defaults.json or per-project
  * config.json) into a plain object, returning null on missing/empty files
@@ -2202,12 +1737,13 @@ function convertClaudeToCopilotContent(content, isGlobal = false) {
   return c;
 }
 
+// isGlobal is the 5th positional arg (3rd/4th are runtime/cmdNames passed by the skills wrapper). See runtime-artifact-layout skillsKind.
 /**
  * Convert a Claude command (.md) to a Copilot skill (SKILL.md).
  * Transforms frontmatter only — body passes through with CONV-06/07 applied.
  * Skills keep original tool names (no mapping) per CONTEXT.md decision.
  */
-function convertClaudeCommandToCopilotSkill(content, skillName, isGlobal = false) {
+function convertClaudeCommandToCopilotSkill(content, skillName, _runtime = null, _cmdNames = null, isGlobal = false) {
   const converted = convertClaudeToCopilotContent(content, isGlobal);
   const { frontmatter, body } = extractFrontmatterAndBody(converted);
   if (!frontmatter) return converted;
@@ -2675,8 +2211,8 @@ function convertClaudeAgentToCopilotAgent(content, isGlobal = false) {
 /**
  * Apply Antigravity-specific content conversion — path replacement + command name conversion.
  * Path mappings depend on install mode:
- *   Global: ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agent/
- *   Local:  ~/.claude/ → .agent/, ./.claude/ → ./.agent/
+ *   Global: ~/.claude/ → ~/.gemini/antigravity/, ./.claude/ → ./.agents/
+ *   Local:  ~/.claude/ → .agents/, ./.claude/ → ./.agents/
  * Applied to ALL Antigravity content (skills, agents, engine files).
  * @param {string} content - Source content to convert
  * @param {boolean} [isGlobal=false] - Whether this is a global install
@@ -2690,14 +2226,14 @@ function convertClaudeToAntigravityContent(content, isGlobal = false) {
     c = c.replace(/\$HOME\/\.claude\b/g, '$HOME/.gemini/antigravity');
     c = c.replace(/~\/\.claude\b/g, '~/.gemini/antigravity');
   } else {
-    c = c.replace(/\$HOME\/\.claude\//g, '.agent/');
-    c = c.replace(/~\/\.claude\//g, '.agent/');
+    c = c.replace(/\$HOME\/\.claude\//g, '.agents/');
+    c = c.replace(/~\/\.claude\//g, '.agents/');
     // Bare form (no trailing slash) — must come after slash form to avoid double-replace
-    c = c.replace(/\$HOME\/\.claude\b/g, '.agent');
-    c = c.replace(/~\/\.claude\b/g, '.agent');
+    c = c.replace(/\$HOME\/\.claude\b/g, '.agents');
+    c = c.replace(/~\/\.claude\b/g, '.agents');
   }
-  c = c.replace(/\.\/\.claude\//g, './.agent/');
-  c = c.replace(/\.claude\//g, '.agent/');
+  c = c.replace(/\.\/\.claude\//g, './.agents/');
+  c = c.replace(/\.claude\//g, '.agents/');
   // Command name conversion (all gsd: references → gsd-)
   c = c.replace(/gsd:/g, 'gsd-');
   // Runtime-neutral agent name replacement (#766)
@@ -2705,12 +2241,13 @@ function convertClaudeToAntigravityContent(content, isGlobal = false) {
   return c;
 }
 
+// isGlobal is the 5th positional arg (3rd/4th are runtime/cmdNames passed by the skills wrapper). See runtime-artifact-layout skillsKind.
 /**
  * Convert a Claude command (.md) to an Antigravity skill (SKILL.md).
  * Transforms frontmatter to minimal name + description only.
  * Body passes through with path/command conversions applied.
  */
-function convertClaudeCommandToAntigravitySkill(content, skillName, isGlobal = false) {
+function convertClaudeCommandToAntigravitySkill(content, skillName, _runtime = null, _cmdNames = null, isGlobal = false) {
   const converted = convertClaudeToAntigravityContent(content, isGlobal);
   const { frontmatter, body } = extractFrontmatterAndBody(converted);
   if (!frontmatter) return converted;
@@ -2969,18 +2506,20 @@ function convertClaudeToWindsurfMarkdown(content) {
   // Replace subagent_type from Claude to Windsurf format
   converted = converted.replace(/subagent_type="general-purpose"/g, 'subagent_type="generalPurpose"');
   converted = converted.replace(/\$ARGUMENTS\b/g, '{{GSD_ARGS}}');
-  // Replace project-level Claude conventions with Windsurf equivalents
-  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.windsurf/rules`');
-  converted = converted.replace(/\.\/CLAUDE\.md/g, '.windsurf/rules');
-  converted = converted.replace(/`CLAUDE\.md`/g, '`.windsurf/rules`');
-  converted = converted.replace(/\bCLAUDE\.md\b/g, '.windsurf/rules');
-  converted = converted.replace(/\.claude\/skills\//g, '.windsurf/skills/');
-  converted = converted.replace(/\.\/\.claude\//g, './.windsurf/');
-  converted = converted.replace(/\.claude\//g, '.windsurf/');
+  // Replace project-level Claude conventions with Windsurf/Devin equivalents
+  // Workspace skills install to .devin/ (Devin Desktop preferred dir, #1085).
+  // Legacy .windsurf/ is still recognized on read but new installs use .devin/.
+  converted = converted.replace(/`\.\/CLAUDE\.md`/g, '`.devin/rules`');
+  converted = converted.replace(/\.\/CLAUDE\.md/g, '.devin/rules');
+  converted = converted.replace(/`CLAUDE\.md`/g, '`.devin/rules`');
+  converted = converted.replace(/\bCLAUDE\.md\b/g, '.devin/rules');
+  converted = converted.replace(/\.claude\/skills\//g, '.devin/skills/');
+  converted = converted.replace(/\.\/\.claude\//g, './.devin/');
+  converted = converted.replace(/\.claude\//g, '.devin/');
   // Bare forms (no trailing slash) — after slash forms to avoid double-rewrite.
   // Use negative lookahead (?![\w-]) to preserve .claude-plugin and .claudeignore.
-  converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.windsurf');
-  converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.windsurf');
+  converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.devin');
+  converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.devin');
   // Environment variable name rewrite
   converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'WINDSURF_CONFIG_DIR');
   // Remove Claude Code-specific bug workarounds before brand replacement
@@ -5671,36 +5210,14 @@ function rewriteTomlKeyLines(content, matches, key) {
   return rewritten;
 }
 
-/**
- * Atomic write — write to <target>.tmp-<pid>-<n> first, then renameSync over
- * the target. Eliminates the partial-write corruption window: an interrupted
- * write leaves the temp file (which we clean up) but never truncates the
- * original target. Used for any mutation of Codex config.toml so we cannot
- * leave the user with a half-written file (#2760 fix 4).
- *
- * Every temp path written is recorded in __atomicWrittenTmps so that
- * _cleanTmpFiles() can scope cleanup to files this installer process actually
- * created, avoiding accidental deletion of unrelated tools' temp files.
- */
-let __atomicWriteCounter = 0;
-// Set<string> — absolute paths of .tmp-<pid>-<n> files this process created.
-const __atomicWrittenTmps = new Set();
-function atomicWriteFileSync(target, data, options) {
-  __atomicWriteCounter += 1;
-  const tmp = `${target}.tmp-${process.pid}-${__atomicWriteCounter}`;
-  __atomicWrittenTmps.add(tmp);
-  try {
-    fs.writeFileSync(tmp, data, options);
-    fs.renameSync(tmp, target);
-    // Successful rename: the tmp path no longer exists, but leave it in the
-    // Set so _cleanTmpFiles can recognise it as installer-owned if it somehow
-    // lingers (e.g. a rename succeeded but left a stale entry on some FS).
-  } catch (e) {
-    // Best-effort cleanup of the partial temp file; never mask the real error.
-    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* ignore */ }
-    throw e;
-  }
-}
+// atomicWriteFileSync and __atomicWrittenTmps are now owned by the
+// runtime-hooks-surface module and imported here so both install.js's
+// direct config.toml writes and the module's Cursor/Codex hooks.json
+// writes share the SAME tracking Set. _cleanTmpFiles() below reads
+// hooksSurface.__atomicWrittenTmps to scope cleanup to installer-owned
+// temps only.
+const atomicWriteFileSync = hooksSurface.atomicWriteFileSync;
+const __atomicWrittenTmps = hooksSurface.__atomicWrittenTmps;
 
 /**
  * Merge GSD config block into an existing or new config.toml.
@@ -5748,7 +5265,7 @@ function mergeCodexConfig(configPath, gsdBlock) {
 
 /**
  * Repair config.toml files corrupted by pre-#1346 GSD installs.
- * Non-boolean keys (e.g. model = "gpt-5.3-codex") that ended up under [features]
+ * Non-boolean keys (e.g. model = "gpt-5.4") that ended up under [features]
  * are relocated before the [features] header so Codex can parse them correctly.
  * Returns the content unchanged if no trapped keys are found.
  */
@@ -6038,23 +5555,12 @@ const GSD_AGENTS_MD_CLOSE_MARKER = '<!-- End GSD Configuration -->';
  * engine layout, not the (separate) #782 Cline skills directory.
  */
 function buildClineRulesBody() {
-  return [
-    '# GSD Core — Git. Ship. Done.',
-    '',
-    '- GSD workflows live in `gsd-core/workflows/`. Load the relevant workflow when',
-    '  the user runs a `/gsd-*` command.',
-    '- GSD agents live in `agents/`. Use the matching agent when spawning subagents.',
-    '- GSD tools are at `gsd-core/bin/gsd-tools.cjs`. Run with `node`.',
-    '- Planning artifacts live in `.planning/`. Never edit them outside a GSD workflow.',
-    '- Do not apply GSD workflows unless the user explicitly asks for them.',
-    '- When a GSD command triggers a deliverable (feature, fix, docs), offer the next',
-    '  step to the user using Cline\'s ask_user tool after completing it.',
-  ].join('\n') + '\n';
+  return hooksSurface.buildClineRulesBody();
 }
 
 /** AGENTS.md body for the cross-tool global instruction target (`~/.agents/AGENTS.md`). */
 function buildClineAgentsMdBody() {
-  return buildClineRulesBody();
+  return hooksSurface.buildClineAgentsMdBody();
 }
 
 /**
@@ -6070,53 +5576,7 @@ function buildClineAgentsMdBody() {
  * hook bug can never wedge the user. No dependency on the #782 skills work.
  */
 function buildClinePreToolUseHook() {
-  return `#!/usr/bin/env node
-'use strict';
-/* GSD-managed Cline PreToolUse hook — gsd-core issue #787.
- * Protocol: JSON on stdin -> JSON decision on stdout.
- * Honored fields: { cancel, errorMessage, contextModification }.
- * Fails open: any error allows the operation. */
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (c) => { raw += c; });
-process.stdin.on('end', () => {
-  const allow = () => process.stdout.write(JSON.stringify({ cancel: false }));
-  let input;
-  try { input = JSON.parse(raw || '{}'); } catch { return allow(); }
-  try {
-    const tool = String(
-      input.toolName || input.tool_name || input.tool ||
-      (input.toolInput && input.toolInput.name) || (input.tool_input && input.tool_input.name) || ''
-    ).toLowerCase();
-    const isWrite = /write|edit|replace|create|delete|remove|append|apply|patch|insert|mkdir/.test(tool);
-    // Collect only PATH-bearing field values (not free-form content), so a doc
-    // that merely mentions ".planning/" in its body is never falsely blocked.
-    const paths = [];
-    const PATH_KEY = /^(path|file|file_?path|filepath|target_?path|target|dir|directory|uri|filename)$/i;
-    const walk = (v, depth) => {
-      if (depth > 5 || paths.length > 64) return;
-      if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
-      if (v && typeof v === 'object') {
-        for (const k of Object.keys(v)) {
-          const val = v[k];
-          if (typeof val === 'string' && PATH_KEY.test(k)) paths.push(val);
-          else walk(val, depth + 1);
-        }
-      }
-    };
-    walk(input, 0);
-    const isPlanningPath = (s) => /(^|[\\\\/])\\.planning([\\\\/]|$)/.test(s);
-    if (isWrite && paths.some(isPlanningPath)) {
-      return process.stdout.write(JSON.stringify({
-        cancel: true,
-        errorMessage:
-          'GSD: .planning/ artifacts are managed by GSD workflows. Edit them only through a /gsd-* command, not directly.',
-      }));
-    }
-  } catch { /* fall through to allow */ }
-  return allow();
-});
-`;
+  return hooksSurface.buildClinePreToolUseHook();
 }
 
 /**
@@ -6124,31 +5584,7 @@ process.stdin.on('end', () => {
  * any user content. Mirrors mergeCopilotInstructions: marker-delimited, idempotent.
  */
 function mergeGsdAgentsMd(filePath, gsdContent) {
-  const gsdBlock = GSD_AGENTS_MD_MARKER + '\n' + gsdContent.trim() + '\n' + GSD_AGENTS_MD_CLOSE_MARKER;
-
-  if (!fs.existsSync(filePath)) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, gsdBlock + '\n');
-    return;
-  }
-
-  const existing = fs.readFileSync(filePath, 'utf8');
-  const openIndex = existing.indexOf(GSD_AGENTS_MD_MARKER);
-  const closeIndex = existing.indexOf(GSD_AGENTS_MD_CLOSE_MARKER);
-
-  if (openIndex !== -1 && closeIndex !== -1) {
-    const before = existing.substring(0, openIndex).trimEnd();
-    const after = existing.substring(closeIndex + GSD_AGENTS_MD_CLOSE_MARKER.length).trimStart();
-    let newContent = '';
-    if (before) newContent += before + '\n\n';
-    newContent += gsdBlock;
-    if (after) newContent += '\n\n' + after;
-    newContent += '\n';
-    fs.writeFileSync(filePath, newContent);
-    return;
-  }
-
-  fs.writeFileSync(filePath, existing.trimEnd() + '\n\n' + gsdBlock + '\n');
+  return hooksSurface.mergeGsdAgentsMd(filePath, gsdContent);
 }
 
 /**
@@ -6178,53 +5614,7 @@ function stripGsdFromAgentsMd(content) {
  * caller can hash-track them).
  */
 function writeClineArtifacts(targetDir, isGlobalInstall) {
-  const written = [];
-  const clinerulesDir = path.join(targetDir, '.clinerules');
-
-  // Migrate a pre-#787 single-file `.clinerules` — a path cannot be both a
-  // file and a directory, so the legacy file must be removed first. The legacy
-  // file is GSD-authored (the installer wrote its full contents with no user
-  // merge surface), so replacing it with the newer directory form is the
-  // intended upgrade. Use lstat so a symlink is unlinked in place rather than
-  // followed (which would write GSD files through the link into an external dir).
-  try {
-    if (fs.existsSync(clinerulesDir)) {
-      const st = fs.lstatSync(clinerulesDir);
-      if (st.isFile() || st.isSymbolicLink()) {
-        fs.unlinkSync(clinerulesDir);
-        console.log(`  ${green}✓${reset} Migrated legacy .clinerules to directory form`);
-      }
-    }
-  } catch { /* best-effort migration */ }
-
-  fs.mkdirSync(clinerulesDir, { recursive: true });
-  fs.writeFileSync(path.join(clinerulesDir, 'gsd.md'), buildClineRulesBody());
-  written.push('.clinerules/gsd.md');
-  console.log(`  ${green}✓${reset} Wrote .clinerules/gsd.md`);
-
-  const hooksDir = path.join(clinerulesDir, 'hooks');
-  fs.mkdirSync(hooksDir, { recursive: true });
-  const hookPath = path.join(hooksDir, 'PreToolUse');
-  fs.writeFileSync(hookPath, buildClinePreToolUseHook());
-  try { fs.chmodSync(hookPath, 0o755); } catch { /* Windows: hooks unsupported anyway */ }
-  written.push('.clinerules/hooks/PreToolUse');
-  console.log(`  ${green}✓${reset} Wrote .clinerules/hooks/PreToolUse`);
-
-  // Global cross-tool instruction target. Cline reads ~/.agents/AGENTS.md
-  // (docs.cline.bot/customization/cline-rules). Merge-safe so we never clobber
-  // a user's or another tool's AGENTS.md. Tracked via markers (like copilot),
-  // not the per-configDir manifest, since it lives outside configDir.
-  if (isGlobalInstall) {
-    try {
-      const agentsPath = path.join(os.homedir(), '.agents', 'AGENTS.md');
-      mergeGsdAgentsMd(agentsPath, buildClineAgentsMdBody());
-      console.log(`  ${green}✓${reset} Merged GSD instructions into ~/.agents/AGENTS.md`);
-    } catch (err) {
-      console.warn(`  ${yellow}⚠${reset} Could not write ~/.agents/AGENTS.md: ${err.message}`);
-    }
-  }
-
-  return written;
+  return hooksSurface.writeClineArtifacts(targetDir, isGlobalInstall);
 }
 
 // ── Cursor hooks.json reconciler (issue #777) ────────────────────────────────
@@ -6254,11 +5644,7 @@ function writeClineArtifacts(targetDir, isGlobalInstall) {
  * @returns {object} Cursor hook entry object
  */
 function buildCursorHookEntry(scriptPath) {
-  return {
-    type: 'command',
-    command: scriptPath.replace(/\\/g, '/'),
-    [GSD_CURSOR_HOOK_MARKER]: true,
-  };
+  return hooksSurface.buildCursorHookEntry(scriptPath);
 }
 
 /**
@@ -6269,7 +5655,7 @@ function buildCursorHookEntry(scriptPath) {
  * @returns {boolean}
  */
 function isManagedCursorHookEntry(entry) {
-  return Boolean(entry && typeof entry === 'object' && entry[GSD_CURSOR_HOOK_MARKER]);
+  return hooksSurface.isManagedCursorHookEntry(entry);
 }
 
 /**
@@ -6290,74 +5676,7 @@ function isManagedCursorHookEntry(entry) {
  * @returns {{ changed: boolean, wrote: boolean, path: string }}
  */
 function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
-  let parsed = {};
-  let currentContent = null;
-
-  if (fs.existsSync(hooksJsonPath)) {
-    const raw = fs.readFileSync(hooksJsonPath, 'utf8');
-    currentContent = raw;
-    if (raw.trim()) {
-      try {
-        parsed = JSON.parse(raw);
-      } catch (err) {
-        throw new Error(`Cursor hooks.json parse failed: ${err && err.message ? err.message : String(err)}`);
-      }
-    }
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) parsed = {};
-
-  // Cursor's canonical hooks.json schema is { "version": 1, "hooks": { ... } }.
-  // GSD always writes (and migrates to) the nested shape so Cursor reads it correctly.
-  // The flat shape { "sessionStart": [...] } is accepted on read for backwards compat
-  // with manually-written files, but the output always uses the nested form.
-  const hasNestedHooksObject =
-    parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks);
-  if (!hasNestedHooksObject) {
-    // Migrate flat shape (or empty {}) to nested: lift event keys into hooks:{}.
-    const eventKeys = ['sessionStart', 'postToolUse'];
-    const lifted = {};
-    for (const k of eventKeys) {
-      if (Array.isArray(parsed[k])) {
-        lifted[k] = parsed[k];
-        delete parsed[k];
-      }
-    }
-    parsed.hooks = lifted;
-  }
-  if (!parsed.version) parsed.version = 1;
-  const hookTable = parsed.hooks;
-
-  // Events GSD manages.
-  const MANAGED_EVENTS = ['sessionStart', 'postToolUse'];
-  const entries = managedEntries || {};
-
-  for (const event of MANAGED_EVENTS) {
-    const existing = Array.isArray(hookTable[event]) ? hookTable[event] : [];
-    // Strip all prior GSD-managed entries for this event.
-    const userOwned = existing.filter((e) => !isManagedCursorHookEntry(e));
-    const newEntry = entries[event] || null;
-    if (newEntry) {
-      hookTable[event] = [...userOwned, newEntry];
-    } else {
-      // Remove-only: keep user entries, or delete the key if it would be empty.
-      if (userOwned.length > 0) {
-        hookTable[event] = userOwned;
-      } else {
-        delete hookTable[event];
-      }
-    }
-  }
-
-  // hookTable is parsed.hooks (always nested now); no reassignment needed.
-  // Write only if content changed or if we're creating the file for the first time.
-  const nextContent = `${JSON.stringify(parsed, null, 2)}\n`;
-  const changed = currentContent !== nextContent;
-  const shouldWrite = changed && (currentContent !== null || Object.keys(parsed).length > 0);
-  if (shouldWrite) {
-    atomicWriteFileSync(hooksJsonPath, nextContent, 'utf8');
-  }
-
-  return { changed: changed, wrote: shouldWrite, path: hooksJsonPath };
+  return hooksSurface.reconcileCursorHooksJson(hooksJsonPath, managedEntries);
 }
 
 /**
@@ -6373,65 +5692,7 @@ function reconcileCursorHooksJson(hooksJsonPath, managedEntries) {
  * @returns {{ hooksJsonPath: string, changed: boolean }}
  */
 function writeCursorHooksJson(targetDir, src, opts) {
-  opts = opts || {};
-  const hooksDir = path.join(targetDir, 'hooks');
-  fs.mkdirSync(hooksDir, { recursive: true });
-
-  // Copy the two GSD-managed hook scripts from the GSD source hooks/ directory.
-  // Apply the same /gsd:/gi → gsd- rewrite used by copyWithPathReplacement for Cursor
-  // JS files, so the installed hook scripts contain no /gsd: colon refs (bug-376 2b).
-  // Track which scripts were successfully installed so we never register a hook entry
-  // that references a script that wasn't copied (dangling command guard).
-  const hookScripts = [GSD_CURSOR_SESSION_HOOK_SCRIPT, GSD_CURSOR_POST_TOOL_HOOK_SCRIPT];
-  const srcHooksDir = path.join(src, 'hooks');
-  const installedScripts = new Set();
-  for (const script of hookScripts) {
-    const srcPath = path.join(srcHooksDir, script);
-    const destPath = path.join(hooksDir, script);
-    if (fs.existsSync(srcPath)) {
-      let content = fs.readFileSync(srcPath, 'utf8');
-      // Rewrite /gsd:<cmd> → gsd-<cmd> so installed hook scripts are consistent
-      // with the Cursor convention (no colon-form slash commands in agent context).
-      content = content.replace(/gsd:/gi, 'gsd-');
-      fs.writeFileSync(destPath, content);
-      try { fs.chmodSync(destPath, 0o755); } catch { /* Windows: ignore chmod */ }
-      installedScripts.add(script);
-    }
-  }
-
-  // Build command strings using the same buildHookCommand helper used by other runtimes.
-  // buildHookCommand resolves the node runner + emits "<runner>" "<targetDir>/hooks/<name>".
-  const hookOpts = { runtime: 'cursor', platform: opts.platform || process.platform };
-  // buildHookCommand('gsd-cursor-session-start.js', ...): sessionStart → context injection
-  // Only register the hook entry if the script was actually installed (dangling guard).
-  const sessionStartCmd = installedScripts.has('gsd-cursor-session-start.js')
-    ? buildHookCommand(targetDir, 'gsd-cursor-session-start.js', hookOpts)
-    : null;
-  // buildHookCommand('gsd-cursor-post-tool.js', ...): postToolUse → STATE.md update monitor
-  const postToolCmd = installedScripts.has('gsd-cursor-post-tool.js')
-    ? buildHookCommand(targetDir, 'gsd-cursor-post-tool.js', hookOpts)
-    : null;
-
-  // Build managed entries; skip events whose command couldn't be resolved (e.g. no node).
-  const managedEntries = {};
-  if (sessionStartCmd) {
-    managedEntries.sessionStart = {
-      type: 'command',
-      command: sessionStartCmd,
-      [GSD_CURSOR_HOOK_MARKER]: true,
-    };
-  }
-  if (postToolCmd) {
-    managedEntries.postToolUse = {
-      type: 'command',
-      command: postToolCmd,
-      [GSD_CURSOR_HOOK_MARKER]: true,
-    };
-  }
-
-  const hooksJsonPath = path.join(targetDir, 'hooks.json');
-  const result = reconcileCursorHooksJson(hooksJsonPath, managedEntries);
-  return { hooksJsonPath, changed: result.changed };
+  return hooksSurface.writeCursorHooksJson(targetDir, src, opts);
 }
 
 /**
@@ -6442,31 +5703,7 @@ function writeCursorHooksJson(targetDir, src, opts) {
  * @returns {{ changed: boolean }}
  */
 function removeCursorHooksJson(targetDir) {
-  const hooksJsonPath = path.join(targetDir, 'hooks.json');
-  if (!fs.existsSync(hooksJsonPath)) return { changed: false };
-  const result = reconcileCursorHooksJson(hooksJsonPath, null);
-  // If the resulting file has no meaningful hook content, remove it.
-  // A file is "empty" if it contains only the scaffolding (version, empty hooks
-  // object, or a bare {}) with no user-authored hook entries.
-  if (result.changed) {
-    try {
-      const contentRaw = fs.readFileSync(hooksJsonPath, 'utf8');
-      const parsed = JSON.parse(contentRaw);
-      // reconcileCursorHooksJson always writes the nested { version, hooks:{} } shape.
-      // The file is "empty" when there are no remaining hook events with entries.
-      const hookTable = (parsed.hooks && typeof parsed.hooks === 'object' && !Array.isArray(parsed.hooks))
-        ? parsed.hooks
-        : {};
-      const hasAnyEvents = Object.keys(hookTable).some(
-        (k) => Array.isArray(hookTable[k]) && hookTable[k].length > 0,
-      );
-      if (!hasAnyEvents) {
-        fs.unlinkSync(hooksJsonPath);
-        return { changed: true };
-      }
-    } catch { /* best-effort: leave the file */ }
-  }
-  return { changed: result.changed };
+  return hooksSurface.removeCursorHooksJson(targetDir);
 }
 
 /**
@@ -6484,19 +5721,7 @@ function removeCursorHooksJson(targetDir) {
  * @returns {object} Copilot hooks-configuration object
  */
 function buildCopilotHookConfig() {
-  return {
-    version: 1,
-    hooks: {
-      sessionStart: [
-        {
-          type: 'command',
-          bash: GSD_COPILOT_SESSION_HOOK_BASH,
-          powershell: GSD_COPILOT_SESSION_HOOK_PWSH,
-          timeoutSec: 10,
-        },
-      ],
-    },
-  };
+  return hooksSurface.buildCopilotHookConfig();
 }
 
 /**
@@ -6513,11 +5738,7 @@ function buildCopilotHookConfig() {
  * @returns {string} The path the hook config was written to
  */
 function writeCopilotHookConfig(targetDir) {
-  const hooksDir = path.join(targetDir, 'hooks');
-  fs.mkdirSync(hooksDir, { recursive: true });
-  const hookPath = path.join(hooksDir, GSD_COPILOT_HOOK_FILE);
-  fs.writeFileSync(hookPath, JSON.stringify(buildCopilotHookConfig(), null, 2) + '\n');
-  return hookPath;
+  return hooksSurface.writeCopilotHookConfig(targetDir);
 }
 
 /**
@@ -7565,8 +6786,9 @@ function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = '
  * @param {string} stagedDir
  * @param {string} runtime
  * @param {string} pathPrefix  e.g. "~/.codex/" — trailing-slash string
+ * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
  */
-function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix) {
+function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGlobal = false) {
   if (!fs.existsSync(stagedDir)) return;
 
   // Walk all SKILL.md files under stagedDir
@@ -7577,7 +6799,7 @@ function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix) {
         walkAndRewrite(fullPath);
       } else if (entry.name.endsWith('.md')) {
         let content = fs.readFileSync(fullPath, 'utf8');
-        content = _applyRuntimeRewrites(content, runtime, pathPrefix);
+        content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal);
         fs.writeFileSync(fullPath, content);
       }
     }
@@ -7598,9 +6820,10 @@ function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix) {
  * @param {string} stagedDir  directory of staged flat .md command files (may be source dir)
  * @param {string} runtime
  * @param {string} pathPrefix
+ * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
  * @returns {string}  path to a temp dir with rewritten files (caller is responsible for cleanup)
  */
-function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix) {
+function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathPrefix, isGlobal = false) {
   if (!fs.existsSync(stagedDir)) return stagedDir;
   // Always copy to a temp dir — stageSkillsForProfile() returns the original source
   // dir on full/default profile (skills === '*'), so writing in-place would corrupt the
@@ -7610,7 +6833,7 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
     for (const entry of fs.readdirSync(stagedDir, { withFileTypes: true })) {
       if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
       let content = fs.readFileSync(path.join(stagedDir, entry.name), 'utf8');
-      content = _applyRuntimeRewrites(content, runtime, pathPrefix);
+      content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal);
       // For augment commands, apply the markdown conversion so tool references
       // and skill paths use Augment equivalents.
       if (runtime === 'augment') {
@@ -7632,9 +6855,10 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
  * @param {string} content
  * @param {string} runtime
  * @param {string} pathPrefix  trailing-slash string
+ * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
  * @returns {string}
  */
-function _applyRuntimeRewrites(content, runtime, pathPrefix) {
+function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
   const dirName = getDirName(runtime);
   const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
 
@@ -7671,18 +6895,30 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix) {
       content = processAttribution(content, getCommitAttribution(runtime));
       break;
 
-    case 'windsurf':
+    case 'windsurf': {
       content = content.replace(/~\/\.claude\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
       content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
       // Bare forms (no trailing slash) — use (?![\w-]) instead of \b so that
       // .claude-plugin / .claudeignore are NOT corrupted (the \b word-boundary
-      // fires between 'e' and '-', which rewrites .claude-plugin → .windsurf-plugin).
+      // fires between 'e' and '-', which rewrites .claude-plugin → .devin-plugin).
       content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
       content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
       content = content.replace(/~\/\.codeium\/windsurf\//g, pathPrefix);
+      // Stage-1 converter rewrites .claude/skills/ → .devin/skills/ (workspace-relative
+      // form). For global installs the real path is pathPrefix + skills/, so fix that up
+      // here using the real isGlobal flag (threaded from installRuntimeArtifacts scope,
+      // not derived from pathPrefix substring which misclassifies custom config dirs).
+      // For local installs, the relative .devin/ form is correct — leave it. (#1085)
+      if (isGlobal) {
+        content = content.replace(/\.devin\/skills\//g, `${pathPrefix}skills/`);
+        content = content.replace(/\.\/\.devin\//g, pathPrefix);
+        content = content.replace(/~\/\.devin(?![\w-])/g, normalizedPathPrefix);
+        content = content.replace(/\$HOME\/\.devin(?![\w-])/g, normalizedPathPrefix);
+      }
       content = processAttribution(content, getCommitAttribution(runtime));
       break;
+    }
 
     case 'augment':
       content = content.replace(/~\/\.claude\//g, pathPrefix);
@@ -8114,11 +7350,12 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile) {
     // stagedForCopy: the directory to copy from (may differ from staged if rewrites
     // produce a temp copy — see applyRuntimeContentRewritesForCommandsInPlace).
     let stagedForCopy = staged;
+    const isGlobal = scope === 'global';
     if (kind.kind === 'skills' || kind.kind === 'kimi-agents') {
-      applyRuntimeContentRewritesInPlace(staged, runtime, pathPrefix);
+      applyRuntimeContentRewritesInPlace(staged, runtime, pathPrefix, isGlobal);
     } else if (kind.kind === 'commands') {
       // Returns a temp dir with rewritten content so source files are never mutated.
-      stagedForCopy = applyRuntimeContentRewritesForCommandsInPlace(staged, runtime, pathPrefix);
+      stagedForCopy = applyRuntimeContentRewritesForCommandsInPlace(staged, runtime, pathPrefix, isGlobal);
     }
     // applyRuntimeContentRewritesForCommandsInPlace() returns a fresh mkdtemp dir under
     // os.tmpdir() (gsd-cmd-rewrites-*); remove it once copied so it does not accumulate (#856).
@@ -8453,11 +7690,12 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       jsContent = jsContent.replace(/\bClaude Code\b/g, 'Cursor');
       fs.writeFileSync(destPath, jsContent);
     } else if (isWindsurf && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
-      // For Windsurf, also convert Claude references in JS/CJS utility scripts
+      // For Windsurf/Devin, also convert Claude references in JS/CJS utility scripts.
+      // Workspace skills install to .devin/ (Devin Desktop preferred dir, #1085).
       let jsContent = fs.readFileSync(srcPath, 'utf8');
       jsContent = jsContent.replace(/gsd:/gi, 'gsd-');
-      jsContent = jsContent.replace(/\.claude\/skills\//g, '.windsurf/skills/');
-      jsContent = jsContent.replace(/CLAUDE\.md/g, '.windsurf/rules');
+      jsContent = jsContent.replace(/\.claude\/skills\//g, '.devin/skills/');
+      jsContent = jsContent.replace(/CLAUDE\.md/g, '.devin/rules');
       jsContent = jsContent.replace(/\bClaude Code\b/g, 'Windsurf');
       fs.writeFileSync(destPath, jsContent);
     } else if (isTrae && (entry.name.endsWith('.cjs') || entry.name.endsWith('.js'))) {
@@ -10166,7 +9404,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   const isHermes = runtime === 'hermes';
   const isCodebuddy = runtime === 'codebuddy';
   const isCline = runtime === 'cline';
-  const configIntent = resolveRuntimeConfigIntent(runtime);
+  const plan = resolveInstallPlan(runtime);
   const dirName = getDirName(runtime);
   const src = path.join(__dirname, '..');
 
@@ -10220,6 +9458,10 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // Get the target directory based on runtime and install type.
   // Cline local installs write to the project root (like Claude Code) — .clinerules
   // lives at the root, not inside a .cline/ subdirectory.
+  // #791: antigravity local installs write to .agents/ (canonical). The legacy .agent/
+  // directory is recognized by RUNTIME_DIRS (update-context) and _LEGACY_SCAN_SUBDIR_NAMES
+  // but NOT auto-removed here; legacy .agent/ gsd artifacts are recognized but not
+  // auto-removed on reinstall (dual-read fallback per issue #791 spec).
   const targetDir = isGlobal
     ? getGlobalConfigDir(runtime, explicitConfigDir)
     : isCline
@@ -11010,6 +10252,8 @@ function install(isGlobal, runtime = 'claude', options = {}) {
           const _universalEffort = resolveInstallTimeEffort(_effortCfg, _agentName);
           const _renderedEffort = _getGsdEffortCatalog().renderEffortForRuntime('claude', _universalEffort).value;
           content = injectEffortFrontmatter(content, _renderedEffort);
+          const _disallowedTools = READONLY_AGENT_DISALLOWED_TOOLS[_agentName];
+          if (_disallowedTools) content = injectDisallowedToolsFrontmatter(content, _disallowedTools);
         }
         // #3677 — normalize retired `/gsd:<cmd>` colon refs in the agent body
         // to the canonical hyphen form `/gsd-<cmd>` for hyphen-`name:`
@@ -11307,7 +10551,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     throw _earlyInstallErr;
   }
 
-  if (configIntent.installSurface === 'codex-toml' && !isMinimalMode(_effectiveInstallMode)) {
+  if (plan.installSurface === 'codex-toml' && !isMinimalMode(_effectiveInstallMode)) {
     // Capture pre-install snapshots before ANY GSD mutation
     // (#2760 fix 3). On post-write schema-validation failure OR any throw
     // during the mutation sequence (write failure, merge throw, etc.) we
@@ -11686,7 +10930,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
   }
 
-  if (configIntent.installSurface === 'copilot-instructions') {
+  if (plan.installSurface === 'copilot-instructions') {
     // Generate copilot-instructions.md
     const templatePath = path.join(targetDir, 'gsd-core', 'templates', 'copilot-instructions.md');
     const instructionsPath = path.join(targetDir, 'copilot-instructions.md');
@@ -11716,7 +10960,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
   }
 
-  if (configIntent.installSurface === 'cursor-hooks-json') {
+  if (plan.installSurface === 'cursor-hooks-json') {
     // #777: Cursor v2.4+ supports hooks.json. Register sessionStart + postToolUse.
     // Hook scripts are copied to <targetDir>/hooks/ and referenced by hooks.json.
     const cursorHookResult = writeCursorHooksJson(targetDir, src, {});
@@ -11731,13 +10975,13 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
   }
 
-  if (configIntent.installSurface === 'profile-marker-only') {
+  if (plan.installSurface === 'profile-marker-only') {
     // Windsurf/Trae/Kimi use artifact-only surfaces — no config.toml or settings.json hooks needed.
     persistActiveProfileMarker();
     return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
   }
 
-  if (configIntent.installSurface === 'cline-rules') {
+  if (plan.installSurface === 'cline-rules') {
     // Cline uses the `.clinerules/` directory form (issue #787): GSD rules live
     // at .clinerules/gsd.md and a PreToolUse lifecycle hook at
     // .clinerules/hooks/PreToolUse. Global installs also get ~/.agents/AGENTS.md.
@@ -11750,8 +10994,12 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   }
 
   // Configure statusline and hooks in settings.json (or settings.local.json for local Claude installs).
-  // Gemini and Antigravity use AfterTool instead of PostToolUse for post-tool hooks
-  const postToolEvent = (runtime === 'gemini' || runtime === 'antigravity') ? 'AfterTool' : 'PostToolUse';
+  // ADR-857 phase 5f-2: drive the hook event dialect from the registry descriptor.
+  // runtimes with hookEvents='gemini' use AfterTool/BeforeTool; all others use PostToolUse/PreToolUse.
+  // Equivalence: hookEvents='gemini' iff runtime∈{gemini,antigravity} — identical to the old check.
+  // A missing registry or missing descriptor defaults to 'not gemini' → PostToolUse (safe).
+  const _hookEventsDialect = plan.hookEvents;
+  const postToolEvent = _hookEventsDialect === 'gemini' ? 'AfterTool' : 'PostToolUse';
   // #338: local Claude installs write to settings.local.json (Claude Code's per-user/gitignored slot)
   // so engineer-specific absolute paths (Node binary, home dir) never land in the repo-shared
   // settings.json. Global installs and all other runtimes continue to use settings.json.
@@ -11925,476 +11173,27 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     }
   }
 
-  // Helper: detect whether a hook entry references a managed hook by name.
-  // Checks both the plain command string (standard form) and the args array
-  // (command+args / wrapped-launcher form used by windowless launchers on
-  // Windows and some custom PATH-less environments).  Without this check the
-  // presence guards below only inspect h.command, so an args-form wrapper is
-  // invisible and a stock string-command entry is appended on every
-  // install/update, running the hook twice. (#976)
-  function referencesHook(h, hookName) {
-    return (typeof h.command === 'string' && h.command.includes(hookName)) ||
-      (Array.isArray(h.args) && h.args.some(a => typeof a === 'string' && a.includes(hookName)));
-  }
-
-  // Configure SessionStart hook for update checking (skip for opencode)
-  if (!isOpencode && !isKilo) {
-    if (!settings.hooks) {
-      settings.hooks = {};
-    }
-    if (!settings.hooks.SessionStart) {
-      settings.hooks.SessionStart = [];
-    }
-
-    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 = path.join(targetDir, 'hooks', 'gsd-check-update.js');
-    if (!hasGsdUpdateHook && fs.existsSync(checkUpdateFile) && updateCheckCommand) {
-      settings.hooks.SessionStart.push({
-        hooks: [
-          {
-            type: 'command',
-            command: updateCheckCommand
-          }
-        ]
-      });
-      console.log(`  ${green}✓${reset} Configured update check hook`);
-    } else if (!hasGsdUpdateHook && !fs.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 = path.join(targetDir, 'hooks', 'gsd-context-monitor.js');
-    if (!hasContextMonitorHook && fs.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`);
-    } else if (!hasContextMonitorHook && !fs.existsSync(contextMonitorFile)) {
-      console.warn(`  ${yellow}⚠${reset}  Skipped context monitor hook — gsd-context-monitor.js 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)`);
-          }
-        }
-      }
-    }
-
-    // Configure PreToolUse hook for prompt injection detection
-    // Gemini and Antigravity use BeforeTool instead of PreToolUse for pre-tool hooks
-    const preToolEvent = (runtime === 'gemini' || runtime === 'antigravity') ? '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 = path.join(targetDir, 'hooks', 'gsd-prompt-guard.js');
-    if (!hasPromptGuardHook && fs.existsSync(promptGuardFile) && promptGuardCommand) {
-      settings.hooks[preToolEvent].push({
-        matcher: 'Write|Edit',
-        hooks: [
-          {
-            type: 'command',
-            command: promptGuardCommand,
-            timeout: 5
-          }
-        ]
-      });
-      console.log(`  ${green}✓${reset} Configured prompt injection guard hook`);
-    } else if (!hasPromptGuardHook && !fs.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 = path.join(targetDir, 'hooks', 'gsd-read-guard.js');
-    if (!hasReadGuardHook && fs.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 && !fs.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 = path.join(targetDir, 'hooks', 'gsd-read-injection-scanner.js');
-    if (!hasReadInjectionScannerHook && fs.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 && !fs.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 = path.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 && fs.existsSync(workflowGuardFile) && workflowGuardCommand) {
-      settings.hooks[preToolEvent].push({
-        matcher: workflowGuardMatcher,
-        hooks: [
-          {
-            type: 'command',
-            command: workflowGuardCommand,
-            timeout: 5
-          }
-        ]
-      });
-      console.log(`  ${green}✓${reset} Configured workflow guard hook (opt-in via hooks.workflow_guard)`);
-    } else if (!hasWorkflowGuardHook && !fs.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 = path.join(targetDir, 'hooks', 'gsd-worktree-path-guard.js');
-    if (!hasWorktreePathGuardHook && fs.existsSync(worktreePathGuardFile) && worktreePathGuardCommand) {
-      settings.hooks[preToolEvent].push({
-        matcher: 'Write|Edit|MultiEdit',
-        hooks: [
-          {
-            type: 'command',
-            command: worktreePathGuardCommand,
-            timeout: 5
-          }
-        ]
-      });
-      console.log(`  ${green}✓${reset} Configured worktree path guard hook`);
-    } else if (!hasWorktreePathGuardHook && !fs.existsSync(worktreePathGuardFile)) {
-      console.warn(`  ${yellow}⚠${reset}  Skipped worktree path guard hook — gsd-worktree-path-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 = path.join(targetDir, 'hooks', 'gsd-validate-commit.sh');
-    if (!hasValidateCommitHook && fs.existsSync(validateCommitFile) && validateCommitCommand) {
-      settings.hooks[preToolEvent].push({
-        matcher: 'Bash',
-        hooks: [
-          {
-            type: 'command',
-            command: validateCommitCommand,
-            timeout: 5
-          }
-        ]
-      });
-      console.log(`  ${green}✓${reset} Configured commit validation hook (opt-in via config)`);
-    } else if (!hasValidateCommitHook && !fs.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 = path.join(targetDir, 'hooks', 'gsd-graphify-update.sh');
-    if (!hasGraphifyUpdateHook && fs.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 && !fs.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 = path.join(targetDir, 'hooks', 'gsd-session-state.sh');
-    if (!hasSessionStateHook && fs.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 && !fs.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 = path.join(targetDir, 'hooks', 'gsd-phase-boundary.sh');
-    if (!hasPhaseBoundaryHook && fs.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 && !fs.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)`);
-    }
-
-    // ── Extended hook events: SubagentStop / Stop / PreCompact (#788 + #770) ──
-    // Claude Code (since #770) and Qwen Code (since #788) both support these
-    // three lifecycle events.  Wire gsd-context-monitor so agents get context-
-    // headroom warnings at subagent completion, model stop, and pre-compaction
-    // (the most critical moment to surface headroom info).
-    //
-    //   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.
-    if (isQwen || runtime === 'claude') {
-      const runtimeLabel = isQwen ? 'Qwen Code' : 'Claude Code';
-      // SubagentStop, Stop, PreCompact — route through the context monitor.
-      for (const event of ['SubagentStop', 'Stop', 'PreCompact']) {
-        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 && fs.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 && !fs.existsSync(contextMonitorFile)) {
-          console.warn(`  ${yellow}⚠${reset}  Skipped ${event} hook — gsd-context-monitor.js not found at target`);
-        }
-      }
-    }
-    // ── end SubagentStop / Stop / PreCompact events ────────────────────────────
-
-    // ── Gemini-only extended hook events (#776) ───────────────────────────────
-    // Gemini CLI exposes several hook events beyond BeforeTool/AfterTool that
-    // gsd previously did not register.  Three high-value events are added 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: isGemini is defined at the top of install() (line ~8696).
-    if (isGemini) {
-      for (const geminiEvent of ['BeforeAgent', 'AfterAgent', 'BeforeModel']) {
-        if (!Array.isArray(settings.hooks[geminiEvent])) {
-          settings.hooks[geminiEvent] = [];
-        }
-        const alreadyHasContextMonitor = settings.hooks[geminiEvent].some(entry =>
-          entry.hooks && entry.hooks.some(h => referencesHook(h, 'gsd-context-monitor'))
-        );
-        if (!alreadyHasContextMonitor && fs.existsSync(contextMonitorFile) && contextMonitorCommand) {
-          settings.hooks[geminiEvent].push({
-            hooks: [
-              {
-                type: 'command',
-                command: contextMonitorCommand,
-                timeout: 10
-              }
-            ]
-          });
-          console.log(`  ${green}✓${reset} Configured ${geminiEvent} context monitor hook (Gemini)`);
-        } else if (!alreadyHasContextMonitor && !fs.existsSync(contextMonitorFile)) {
-          console.warn(`  ${yellow}⚠${reset}  Skipped ${geminiEvent} hook — gsd-context-monitor.js not found at target`);
-        }
-      }
-    }
-    // ── end Gemini-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 (runtime === 'claude') {
-      if (!settings.hooks.FileChanged) {
-        settings.hooks.FileChanged = [];
-      }
-      const configReloadFile = path.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 && fs.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 && !fs.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`);
-      }
-    }
-    // ── end FileChanged hook ────────────────────────────────────────────────────
-  }
+  // Register all GSD-managed hook entries into settings.hooks.* for runtimes
+  // that use the settings.json hook surface (ADR-857 phase 5f-1b).
+  // settings is mutated in place by applySettingsJsonHooks.
+  applySettingsJsonHooks(settings, {
+    runtime,
+    isGlobal,
+    targetDir,
+    postToolEvent,
+    hookEvents: _hookEventsDialect,
+    extendedHookEvents: plan.extendedHookEvents,
+    hooksSurface: plan.hooksSurface,
+    updateCheckCommand,
+    contextMonitorCommand,
+    promptGuardCommand,
+    readGuardCommand,
+    readInjectionScannerCommand,
+    configReloadCommand,
+    hookOpts,
+    localCmd,
+    localShellCmd,
+  });
 
   // ── Gemini hooksConfig.enabled check (#776) ───────────────────────────────
   // Detect `hooksConfig.enabled: false` in the already-loaded settings object
@@ -12509,9 +11308,9 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   const isWindsurf = runtime === 'windsurf';
   const isTrae = runtime === 'trae';
   const isCline = runtime === 'cline';
-  const configIntent = resolveRuntimeConfigIntent(runtime);
+  const plan = resolveInstallPlan(runtime);
 
-  if (shouldInstallStatusline && configIntent.writesSharedSettings && !isOpencode) {
+  if (shouldInstallStatusline && plan.writesSharedSettings && !isOpencode) {
     if (!isGlobal && !forceStatusline) {
       // Local installs skip statusLine by default: repo settings.json takes precedence over
       // profile-level settings.json in Claude Code, so writing here would silently clobber
@@ -12537,7 +11336,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // settings.json hooks block — opencode/kilo/codex/cursor/windsurf/trae/
   // cline either lack the surface or use a different config schema.
   const { shouldInstallBanner, bannerCommand } = bannerOpts;
-  if (shouldInstallBanner && settings && configIntent.writesSharedSettings && !isOpencode) {
+  if (shouldInstallBanner && settings && plan.writesSharedSettings && !isOpencode) {
     if (!bannerCommand) {
       console.warn(`  ${yellow}⚠${reset}  Skipped update banner registration — Node executable path unavailable. See #2979 / #3002.`);
     } else {
@@ -12577,17 +11376,17 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // {type: 'command', command: null} items that the runtime hook schema
   // rejects at parse time. validateHookFields filters those out so the file
   // we write is always schema-valid.
-  if (settingsPath && settings && configIntent.writesSharedSettings) {
+  if (settingsPath && settings && plan.writesSharedSettings) {
     writeSettings(settingsPath, validateHookFields(settings));
   }
 
   // Configure OpenCode permissions
-  if (configIntent.finishPermissionWriter === 'opencode' && !process.env.GSD_TEST_MODE) {
+  if (plan.finishPermissionWriter === 'opencode' && !process.env.GSD_TEST_MODE) {
     configureOpencodePermissions(isGlobal, configDir);
   }
 
   // Configure Kilo permissions
-  if (configIntent.finishPermissionWriter === 'kilo') {
+  if (plan.finishPermissionWriter === 'kilo') {
     configureKiloPermissions(isGlobal, configDir);
   }
 
@@ -13126,9 +11925,11 @@ const _LEGACY_SCAN_SUBDIR_NAMES = [
   '.codex',
   '.copilot',
   '.github',    // copilot local form
-  '.agent',     // antigravity local form
+  '.agents',    // antigravity local form (canonical, #791)
+  '.agent',     // antigravity local form (legacy, backward-compat)
   '.cursor',
-  '.windsurf',
+  '.devin',     // windsurf local form (canonical, #1085; Devin Desktop preferred dir)
+  '.windsurf',  // windsurf local form (legacy, backward-compat with pre-#1085 installs)
   '.codeium/windsurf',
   '.augment',
   '.trae',
@@ -13447,6 +12248,8 @@ module.exports = {
     buildHookCommand,
     normalizeNodePath,
     resolveNodeRunner,
+    referencesHook,
+    applySettingsJsonHooks,
     rewriteLegacyManagedNodeHookCommands,
     buildCodexHookBlock,
     rewriteLegacyCodexHookBlock,