@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/hooks/install.js

@@ -1,12 +1,3 @@
-/**
- * Hook management -- discovery, registration, and syncing of event hooks.
- *
- * Hooks are shell scripts in ~/.agents/hooks/ that fire on agent events
- * (tool calls, session start, etc.). Each hook directory contains a manifest
- * (agents.yaml) declaring events, matchers, and timeout. This module handles
- * parsing those manifests, registering hooks into agent-native settings files,
- * and syncing them across version switches.
- */
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -22,10 +13,6 @@ import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, ge
 import { collectSubruleHooksFromState } from '../rules/compose.js';
 import { codexShortKey, resolveCodexHome } from '../codex-home.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
-/**
- * Resolve a hook script's absolute path. Checks user dir first, then enabled
- * extra repos in insertion order, then system dir. Returns null if not found.
- */
 function resolveContainedHookPath(hooksRoot, script) {
     const resolvedRoot = path.resolve(hooksRoot);
     const candidate = path.join(hooksRoot, script);
@@ -36,11 +23,6 @@ function resolveContainedHookPath(hooksRoot, script) {
         return null;
     return resolved;
 }
-/**
- * Subdirectories under hooks/ that group event families (e.g. session-starts/).
- * Scripts one level down are first-class hooks; their install name remains the
- * file basename so version-home copies stay flat and doctor/diff keep matching.
- */
 const HOOK_GROUP_SKIP_DIRS = new Set(['node_modules', '.git', '.cache']);
 export function resolveHookScriptPath(script) {
     const extraDirs = getEnabledExtraRepos().map(e => e.dir);
@@ -49,8 +31,6 @@ export function resolveHookScriptPath(script) {
         const resolved = resolveContainedHookPath(hooksRoot, script);
         if (resolved)
             return resolved;
-        // Basename fallback: manifests may say `session-starts/foo.sh` or just
-        // `foo.sh` while the file lives under a one-level group dir.
         const base = path.basename(script);
         const nested = findHookScriptInGroupDirs(hooksRoot, base);
         if (nested)
@@ -58,10 +38,6 @@ export function resolveHookScriptPath(script) {
     }
     return null;
 }
-/**
- * Find `basename` under hooks/<group>/ (one level). Skips known non-group dirs.
- * Returns the first match in sorted group order for stability.
- */
 function findHookScriptInGroupDirs(hooksRoot, basename) {
     if (!fs.existsSync(hooksRoot))
         return null;
@@ -85,8 +61,6 @@ function findHookScriptInGroupDirs(hooksRoot, basename) {
         }
         if (!st.isDirectory() || st.isSymbolicLink())
             continue;
-        // Only treat dirs that themselves contain scripts as groups (session-starts/),
-        // not fixture-only directory bundles (tests/).
         let hasScript = false;
         try {
             for (const child of fs.readdirSync(groupDir)) {
@@ -110,38 +84,17 @@ function findHookScriptInGroupDirs(hooksRoot, basename) {
     }
     return null;
 }
-/**
- * Prefixes used for stale-entry cleanup in agent settings files. A registered
- * hook command is considered "managed" if it lives under any known hooks dir
- * (user, extra repos, or system). Entries from removed extra repos are also
- * garbage-collected because they won't appear in this list any more.
- */
 function getManagedHookPrefixes() {
     const extraDirs = getEnabledExtraRepos().map(e => e.dir);
     return [
         path.join(getUserAgentsDir(), 'hooks') + path.sep,
         ...extraDirs.map(d => path.join(d, 'hooks') + path.sep),
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
-        // Subrule-dir hook scripts register by their absolute source path under a
-        // rules `subrules/` tree. Cover those trees so a removed subrule/hook's
-        // stale settings entry gets garbage-collected like any other managed hook.
         path.join(getUserRulesDir(), 'subrules') + path.sep,
         ...extraDirs.map(d => path.join(d, 'rules', 'subrules') + path.sep),
         path.join(getResolvedRulesDir(), 'subrules') + path.sep,
     ];
 }
-/**
- * Convert an absolute path under HOME to a portable ~/... form with forward
- * slashes. Hook commands stored this way work on both macOS and Windows:
- * absolute Windows paths break in bash because backslashes are stripped as
- * escape characters, whereas ~/... paths expand correctly via the ~/.claude
- * symlink/junction on both platforms.
- *
- * `home` and `sep` are injectable so the Windows behavior (backslash sep,
- * drive-letter home) is unit-testable on a POSIX CI host — pass sep='\\' to
- * simulate Windows. With the defaults this is byte-identical to reading
- * os.homedir()/path.sep at the call site.
- */
 export function toPortableCommand(absPath, home = os.homedir(), sep = path.sep) {
     const normalized = absPath.split(sep).join('/');
     const homeNorm = home.split(sep).join('/');
@@ -150,123 +103,64 @@ export function toPortableCommand(absPath, home = os.homedir(), sep = path.sep)
     }
     return normalized;
 }
+const AGENTS_HOME_HOOK_RE = /\/\.agents\/\.history\/(?:versions\/[^/]+\/[^/]+\/home|accounts\/[^/]+\/[^/]+)\//;
 function isManagedHookCommand(command, prefixes) {
-    // Expand ~/... so tilde-form portable commands can be matched against
-    // absolute managed prefixes.
     let expanded = command;
     if (command.startsWith('~/')) {
         expanded = path.join(os.homedir(), command.slice(2));
     }
-    // Resolve the directory through symlinks/junctions (e.g. ~/.claude on
-    // Windows is a junction to the versioned home dir where prefixes live).
-    // Resolve the dir, not the full path — the file may not exist after removal.
+    if (AGENTS_HOME_HOOK_RE.test(expanded.split(path.sep).join('/')))
+        return true;
     const dir = path.dirname(expanded);
     let resolvedDir = dir;
     try {
         resolvedDir = fs.realpathSync(dir);
     }
-    catch { /* absent or broken link */ }
+    catch { }
     const resolved = path.join(resolvedDir, path.basename(expanded));
     for (const prefix of prefixes) {
         if (resolved.startsWith(prefix))
             return true;
-        // The command dir above is realpath-resolved, but a raw prefix may still
-        // point through a symlink (macOS TMPDIR /var -> /private/var, or a
-        // symlinked ~/.agents). Compare against a realpath-normalized prefix too
-        // so the two sides match. Strip the trailing sep, resolve the dir, re-add.
         const rawPrefixDir = prefix.endsWith(path.sep) ? prefix.slice(0, -path.sep.length) : prefix;
         let resolvedPrefix = prefix;
         try {
             resolvedPrefix = fs.realpathSync(rawPrefixDir) + path.sep;
         }
-        catch { /* absent or broken link */ }
+        catch { }
         if (resolvedPrefix !== prefix && resolved.startsWith(resolvedPrefix))
             return true;
     }
     return false;
 }
-/**
- * Per-version-home command detection. Sync copies each hook script into the
- * active version's home and registers the command by that version-scoped path
- * (`~/.agents/.history/versions/<agent>/<version>/home/…`). Because the path
- * embeds the version number, a later version's sync appends a fresh set whose
- * paths never string-match (and thus never prune) the prior version's entries —
- * so entries for every version installed over time pile up in one settings
- * file, and once a version is removed its entries become dead hooks that error
- * on every tool call. `versionHomeIdentity` extracts the `<agent>/<version>` a
- * command (or home path) belongs to so stale sibling-version entries can be
- * pruned. Returns null for any path outside a per-version home (system hooks,
- * the user's own custom hooks) — those are never a prune target.
- */
 const VERSION_HOME_SEGMENT_RE = /\.history\/versions\/([^/]+)\/([^/]+)\/home(?:\/|$)/;
 function versionHomeIdentity(commandOrPath) {
     const norm = commandOrPath.split(/[\\/]/).join('/');
     const m = VERSION_HOME_SEGMENT_RE.exec(norm);
     return m ? { agent: m[1], version: m[2] } : null;
 }
-/**
- * True when `command` points into a DIFFERENT version home of the same agent as
- * `current` — i.e. a stale entry left behind by an earlier version's sync.
- * Non-version-home commands (system + user-custom hooks) always return false.
- */
-function isStaleSiblingVersionCommand(command, current) {
-    if (!current)
-        return false;
-    const id = versionHomeIdentity(command);
-    return id !== null && id.agent === current.agent && id.version !== current.version;
-}
-function hookResourceName(command) {
-    const withoutArgs = command.trim().split(/\s+/)[0];
-    return path.basename(withoutArgs).replace(/\.[^.]+$/, '');
-}
-/**
- * Collapse version-scoped registrations by logical resource identity rather
- * than absolute command path. When the same resource is present in several
- * homes, the active home's command wins even if it appears later. Commands
- * outside version homes are user-owned and remain untouched.
- */
-export function deduplicateVersionHookCommands(commands, activeVersionHome) {
-    const active = versionHomeIdentity(activeVersionHome);
-    if (!active)
-        return [...commands];
-    const selected = new Map();
-    const passthrough = [];
-    for (const command of commands) {
-        const identity = versionHomeIdentity(command);
-        if (!identity || identity.agent !== active.agent) {
-            passthrough.push(command);
-            continue;
-        }
-        const key = `${identity.agent}\0${hookResourceName(command)}`;
-        const candidateIsActive = identity.version === active.version;
-        const prior = selected.get(key);
-        if (!prior || (!prior.active && candidateIsActive)) {
-            selected.set(key, { command, active: candidateIsActive });
-        }
-    }
-    return [...passthrough, ...Array.from(selected.values(), ({ command }) => command)];
-}
-/**
- * Collapse a matcher group's hook entries down to the deduplicated command
- * multiset {@link deduplicateVersionHookCommands} returns, preserving order and
- * the concrete entry objects. The deduped list is honored as a per-command
- * budget, NOT a membership set: two identical active-version entries collapse to
- * one because the budget for that command is one. (A membership `Set.has` test
- * would keep both — the bug this replaces.) Passthrough (user / non-version-home)
- * commands keep their original multiplicity, so genuine user hooks are untouched.
- */
-function collapseVersionHookEntries(entries, activeVersionHome) {
-    const budget = new Map();
-    for (const command of deduplicateVersionHookCommands(entries.map((e) => e.command), activeVersionHome)) {
-        budget.set(command, (budget.get(command) ?? 0) + 1);
-    }
-    return entries.filter((e) => {
-        const remaining = budget.get(e.command) ?? 0;
-        if (remaining <= 0)
-            return false;
-        budget.set(e.command, remaining - 1);
-        return true;
-    });
+function hookEntryKey(event, matcher, command) {
+    return `${event}\0${matcher ?? ''}\0${command}`;
+}
+function pruneManagedHookEntries(hooks, expected, managedPrefixes) {
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!group.hooks)
+                continue;
+            const seen = new Set();
+            group.hooks = group.hooks.filter((h) => {
+                if (!isManagedHookCommand(h.command, managedPrefixes))
+                    return true;
+                const key = hookEntryKey(event, group.matcher, h.command);
+                if (!expected.has(key) || seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            });
+        }
+        hooks[event] = groups.filter((g) => g.hooks && g.hooks.length > 0);
+    }
 }
 import { getEffectiveHome, getGlobalDefault, getVersionHomePath, isVersionIsolated, listInstalledVersions, resolveVersion, } from '../installations/versions.js';
 import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './cache.js';
@@ -274,12 +168,6 @@ import { getHookShimsDir } from '../state.js';
 function hookContentHash(scriptPath) {
     return crypto.createHash('sha256').update(fs.readFileSync(scriptPath)).digest('hex');
 }
-/**
- * Inspect every installed hooks-capable harness without assuming a native
- * settings format. Same-name copies with one content hash are installation
- * noise; multiple hashes are drift. The active version is always selected as
- * the authoritative copy when it participates in the group.
- */
 export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
     const byResource = new Map();
     for (const { agent, version } of iterHooksCapableVersions()) {
@@ -322,24 +210,6 @@ export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
     }
     return findings.sort((a, b) => `${a.agent}/${a.name}`.localeCompare(`${b.agent}/${b.name}`));
 }
-/**
- * Resolve the command path to register for a hook.
- *
- * Returns either the raw script path (no `cache:`, `matches:`, or `matcher:`
- * set — a bare lifecycle hook with nothing to gate or time) or the path to a
- * generated wrapper shim. The shim is written as a side effect when `cache:`
- * and/or `matches:` is configured — it enforces the `matches:` gate at fire
- * time and layers the caching/timing machinery when `cache:` is set.
- *
- * A hook that declares only `matcher:` (e.g. git-guard/rm-guard scoped to the
- * `Bash` tool, no `cache:`/`matches:`) also gets a shim now — a pass-through
- * one with no gate and no cache, whose only job is the trailing timing sample
- * (see PASSTHROUGH_TAIL in hooks/cache.ts). Before this, a matcher-only hook
- * took the raw-path branch and fired completely uninstrumented: `agents perf
- * hooks` showed zero samples for it no matter how often it ran. The agent-
- * native settings file gets the same shape either way — just a different
- * command path.
- */
 function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
     if (!scriptPath)
@@ -351,18 +221,9 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     const hasMatches = matches != null && Object.keys(matches).length > 0;
     const hasMatcher = !!hookDef.matcher;
     if (!cache && !hasMatches && !hasMatcher) {
-        // Nothing to gate, cache, or time: make sure a previously generated shim
-        // from an earlier cache:/matches:/matcher config is gone so the JSONL
-        // doesn't keep claiming hits.
         removeHookShim(name);
         return toPortableCommand(scriptPath);
     }
-    // A shim is generated when the hook opts into caching, declares `matches:`
-    // predicates, or declares a `matcher:` (even alone — see the doc comment
-    // above). The shim enforces the `matches:` gate at fire time (skipping the
-    // script when predicates don't hold) and, when `cache:` is set, layers the
-    // cache/timing machinery on top; with neither, it is a pure pass-through
-    // timing wrapper.
     return toPortableCommand(generateHookShim({
         name,
         scriptPath,
@@ -371,23 +232,10 @@ function resolveHookCommand(name, hookDef, resolveScript) {
         failClosed: hookDef.events.includes('PreToolUse'),
     }));
 }
-/**
- * Extensions that are NEVER hooks — docs, configuration, plain data. A file
- * in hooks/ with one of these extensions is auxiliary content (e.g., the
- * `promptcuts.yaml` data file read directly by the expand-promptcuts
- * script, or the `README.md` that documents the hooks directory). They
- * sometimes carry an exec bit by accident (older sync runs chmod 0o755'd
- * everything) but they are not scripts.
- */
 const NON_SCRIPT_EXTENSIONS = new Set([
     '.md', '.markdown', '.rst', '.txt',
     '.yaml', '.yml', '.json', '.toml', '.ini', '.conf',
 ]);
-// Documentation siblings of a hook (e.g. `git-guard.md` next to `git-guard.sh`)
-// are human-readable docs the hook never reads at runtime — NOT a data sidecar.
-// Treating them as the hook's `dataFile` made the installer's correct omission
-// of docs look like perpetual drift in `agents doctor` that no sync could fix.
-// Structured siblings (.yaml/.json/.toml/...) remain valid data files.
 const DOC_EXTENSIONS = new Set(['.md', '.markdown', '.rst']);
 const SCRIPT_EXTENSIONS = new Set([
     '.sh',
@@ -407,18 +255,13 @@ const SCRIPT_EXTENSIONS = new Set([
 function isExecutable(mode) {
     return (mode & 0o111) !== 0;
 }
-/**
- * Ensure a script file carries an exec bit. Subrule-dir hook scripts are
- * registered by their source path (not copied), so they must be executable in
- * place. Best-effort: a chmod failure (read-only fs, foreign owner) is ignored.
- */
 function ensureExecutable(scriptPath) {
     try {
         const mode = fs.statSync(scriptPath).mode;
         if (!isExecutable(mode))
             fs.chmodSync(scriptPath, mode | 0o755);
     }
-    catch { /* best effort */ }
+    catch { }
 }
 function getHooksDir(agentId) {
     const agent = AGENTS[agentId];
@@ -457,12 +300,6 @@ function removeHookFiles(dir, name) {
         }
     }
 }
-/**
- * Collect hook-adjacent files from a hooks root: top-level files plus files in
- * one-level group subdirs (e.g. hooks/session-starts/*.sh). Group dirs exist
- * only for layout; the install/list name stays the file basename so sync and
- * doctor keep a flat version-home model.
- */
 function collectHookFilesFromRoot(dir) {
     const files = [];
     const pushFile = (fullPath, fileName, mode) => {
@@ -502,8 +339,6 @@ function collectHookFilesFromRoot(dir) {
         }
         if (!stat.isDirectory() || HOOK_GROUP_SKIP_DIRS.has(file))
             continue;
-        // One-level event-group layout: hooks/<group>/<script>. Only dirs that
-        // contain top-level scripts are groups; fixture-only dirs (tests/) are not.
         let nested;
         try {
             nested = fs.readdirSync(fullPath);
@@ -537,23 +372,14 @@ function collectHookFilesFromRoot(dir) {
     }
     return files;
 }
-/**
- * List hook entries in a single directory, grouping script + data files by
- * basename. Also discovers scripts in one-level group subdirs
- * (hooks/session-starts/). Exported so doctor-diff can reuse the same grouping
- * the sync path applies; without this, doctor would double-count `foo.sh` and
- * `foo.yaml`. On basename collision, the top-level file wins over a nested one.
- */
 export function listHookEntriesFromDir(dir) {
     if (!fs.existsSync(dir)) {
         return [];
     }
     const files = collectHookFilesFromRoot(dir);
-    // Prefer top-level over nested when basenames collide (stable install name).
     const byBase = new Map();
     for (const file of files) {
         const list = byBase.get(file.base) || [];
-        // Top-level files sit directly under dir; nested have an extra path segment.
         const isTop = path.dirname(file.fullPath) === path.resolve(dir);
         if (isTop)
             list.unshift(file);
@@ -563,9 +389,6 @@ export function listHookEntriesFromDir(dir) {
     }
     const entries = [];
     for (const [base, groupAll] of byBase) {
-        // Keep only files that share the winning script's directory so a nested
-        // data sidecar next to a nested script still pairs, and a top-level
-        // winner is not paired with a nested yaml of the same basename.
         const winnerScript = groupAll.find((f) => SCRIPT_EXTENSIONS.has(f.ext.toLowerCase())) ||
             groupAll.find((f) => f.isExec && !NON_SCRIPT_EXTENSIONS.has(f.ext.toLowerCase()));
         if (!winnerScript)
@@ -573,13 +396,6 @@ export function listHookEntriesFromDir(dir) {
         const groupDir = path.dirname(winnerScript.fullPath);
         const group = groupAll.filter((f) => path.dirname(f.fullPath) === groupDir);
         group.sort((a, b) => a.name.localeCompare(b.name));
-        // A group is a hook only if it has an actual script: a script extension,
-        // OR an executable bit on a file whose extension is not a known data /
-        // docs type. Files like `README.md` (docs) or `promptcuts.yaml` (data
-        // the expand-promptcuts hook reads directly) sit alongside hooks but
-        // are NOT hooks themselves and must not surface in the hooks list
-        // anywhere — doctor, sync, view, or otherwise. Older sync runs may have
-        // chmod 0o755'd these files; an exec bit alone is not enough.
         const script = group.find((f) => SCRIPT_EXTENSIONS.has(f.ext.toLowerCase())) ||
             group.find((f) => f.isExec && !NON_SCRIPT_EXTENSIONS.has(f.ext.toLowerCase()));
         if (!script)
@@ -613,19 +429,9 @@ function copyHook(entry, targetDir) {
         fs.copyFileSync(entry.dataFile, dataTarget);
     }
 }
-/**
- * Normalize content for comparison (trim, normalize line endings).
- */
 function normalizeContent(content) {
     return content.replace(/\r\n/g, '\n').trim();
 }
-/**
- * Hooks dir for an agent under an arbitrary home (version home or effective
- * home). An agent whose `hooksDir` is configured absolute under `$HOME` (grok,
- * kimi) must be translated to config-dir-relative first — a raw `path.join`
- * would embed the absolute path as a relative segment and produce a hybrid
- * path that never exists (RUSH-2237).
- */
 export function getHooksDirInHome(agentId, home) {
     const config = AGENTS[agentId];
     const hooksDir = path.isAbsolute(config.hooksDir)
@@ -652,7 +458,6 @@ export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), option
         });
         seen.add(hook.name);
     };
-    // Project-scoped hooks (project .agents overrides agent-specific dirs)
     const projectDirs = getProjectHooksDirs(agentId, cwd);
     for (const dir of projectDirs) {
         const projectHooks = listHookEntriesFromDir(dir);
@@ -660,7 +465,6 @@ export function listInstalledHooksWithScope(agentId, cwd = process.cwd(), option
             addHook(hook, 'project', agentId);
         }
     }
-    // User-scoped hooks (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
     const userDir = getHooksDirInHome(agentId, home);
     const userHooks = listHookEntriesFromDir(userDir);
@@ -696,33 +500,15 @@ export async function installHooks(source, agents, options = {}) {
     }
     return { installed, errors };
 }
-/**
- * Path to the hooks dir of a specific version home (not the active one).
- */
 export function getVersionHooksDir(agent, version) {
     return getHooksDirInHome(agent, getVersionHomePath(agent, version));
 }
-/**
- * List hook entries in a specific version home.
- */
 export function listHooksInVersionHome(agent, version) {
     return listHookEntriesFromDir(getVersionHooksDir(agent, version));
 }
-// ─── wiring inspection ────────────────────────────────────────────────────────
-/**
- * Native hook-config families understood by this read-only inspector. Claude,
- * Droid, and Muse share settings.json; Grok uses the same grouped event shape
- * in hooks/hooks.json; Kimi stores one hook per [[hooks]] config.toml table.
- * Other harnesses report unsupported rather than risk a false verdict.
- */
 const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid', 'muse'];
 const HOOKS_JSON_HOOK_FAMILY = ['grok'];
 const TOML_ARRAY_HOOK_FAMILY = ['kimi'];
-/**
- * Check the filesystem properties a shell hook needs without invoking it. A
- * dangling symlink is deliberately distinguished from an absent file because
- * the repair/remediation is the same but the diagnostic is materially clearer.
- */
 function shellQuoteForHookShim(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -736,7 +522,6 @@ function hookRuntimeProblem(artifact, platform = process.platform) {
         const code = err.code;
         if (code === 'ENOENT')
             return 'missing';
-        // Stable: errno code only — never absolute path text (fleet/menu aggregation).
         return `cannot inspect (${code || 'error'})`;
     }
     let target;
@@ -751,18 +536,12 @@ function hookRuntimeProblem(artifact, platform = process.platform) {
     }
     if (!target.isFile())
         return 'not a regular file';
-    // Generation always writes non-empty content; an empty placeholder is broken.
     if (target.size === 0)
         return 'broken (empty)';
-    // Windows does not use a POSIX executable bit; requiring it there would
-    // continuously rewrite healthy .sh files on Windows hosts.
     if (platform !== 'win32' && (target.mode & 0o111) === 0)
         return 'not executable';
     try {
         const body = fs.readFileSync(shimPath, 'utf-8');
-        // The global shim must name the selected live version-home script. A
-        // wrapper can remain executable while its SOURCE points to an older or
-        // deleted version; detect that without running either script.
         if (!body.includes(`SOURCE=${shellQuoteForHookShim(artifact.scriptPath)}`)) {
             return 'source mismatch';
         }
@@ -773,12 +552,6 @@ function hookRuntimeProblem(artifact, platform = process.platform) {
     }
     return null;
 }
-/**
- * Gather managed generated-shim expectations for one installed version. The
- * script must resolve inside that version home (or be an existing absolute
- * subrule), matching the registrar's selection rules. This function never
- * creates a shim or runs a hook.
- */
 function managedHookRuntimeArtifactsForVersion(agent, version) {
     if (!AGENTS[agent].supportsHooks)
         return [];
@@ -811,12 +584,7 @@ function managedHookRuntimeArtifactsForVersion(agent, version) {
     }
     return artifacts;
 }
-/** Inspect managed generated hook wrappers without executing user hook code. */
 export function inspectBrokenManagedHookRuntimeArtifacts(filter, platform = process.platform) {
-    // Generated destinations are shared across every harness. Always select the
-    // owner from the global population first; an agent-scoped doctor call may
-    // restrict which shim names are relevant, but must not change the expected
-    // SOURCE for a shared wrapper.
     const versions = iterHooksCapableVersions();
     if (filter?.agent &&
         filter.version &&
@@ -845,12 +613,6 @@ export function inspectBrokenManagedHookRuntimeArtifacts(filter, platform = proc
     return broken.sort((a, b) => a.shimPath.localeCompare(b.shimPath) ||
         `${a.agent}@${a.version}/${a.name}`.localeCompare(`${b.agent}@${b.version}/${b.name}`));
 }
-/**
- * Prefer the agent's global default when it appears in the candidate set;
- * otherwise the newest non-isolated version. Shared shim paths embed a single
- * SOURCE script — picking the wrong version permanently points every harness
- * at a stale or dead path.
- */
 function pickCanonicalHookRuntimeArtifact(candidates) {
     if (candidates.length === 1)
         return candidates[0];
@@ -863,8 +625,6 @@ function pickCanonicalHookRuntimeArtifact(candidates) {
         if (active)
             return active;
     }
-    // listInstalledVersions is the canonical semver ordering. Scan backward
-    // rather than inventing another version comparator at this call site.
     for (const agent of agents) {
         for (const version of [...listInstalledVersions(agent)].reverse()) {
             const newest = candidates.find((c) => c.agent === agent && c.version === version);
@@ -874,14 +634,7 @@ function pickCanonicalHookRuntimeArtifact(candidates) {
     }
     return candidates[0];
 }
-/**
- * One repair target per unique shim path. Generated shims are global, so both
- * unattended and explicit repair leave isolated/private version homes out.
- */
 function selectCanonicalHookRuntimeArtifacts(artifacts) {
-    // No hook runtime exists for a version that does not support hooks. Isolated
-    // versions never own a global generated shim, even when a caller names one:
-    // selecting it would repoint every harness at a private version home.
     const pool = eligibleHookRuntimeArtifacts(artifacts);
     const byPath = new Map();
     for (const artifact of pool) {
@@ -895,33 +648,16 @@ function selectCanonicalHookRuntimeArtifacts(artifacts) {
     }
     return selected;
 }
-/** Versions that may own — and therefore diagnose — a shared generated shim. */
 function eligibleHookRuntimeArtifacts(artifacts) {
     return artifacts.filter((artifact) => supports(artifact.agent, 'hooks', artifact.version).ok &&
         !isVersionIsolated(artifact.agent, artifact.version));
 }
-/**
- * Stable failure text: errno code + detector reason only.
- * Never include absolute paths or randomized atomic-temp basenames — those
- * break cross-device / menu-bar aggregation of identical failures. The hook
- * name is attached by the caller (`hook shim <name>: …`).
- */
 function stableHookRuntimeRepairFailure(before, err) {
     const code = err?.code;
     return `repair failed [${code || 'UNKNOWN'}]: ${before}`;
 }
-/**
- * Regenerate one known-broken wrapper and prove the result is usable. Callers
- * provide a snapshot from inspectBrokenManagedHookRuntimeArtifacts; this never
- * loops or retries and returns a stable error for the current pass.
- *
- * Generation is delegated to generateHookShim (idempotent — preserves mtime when
- * content already matches). This path never calls registerHooksToSettings,
- * installHooks, or any sync routine.
- */
 function repairManagedHookRuntimeArtifact(artifact, platform = process.platform) {
     const before = hookRuntimeProblem(artifact, platform);
-    // Already healthy (e.g. race with another pass) — no-op, no needsAttention.
     if (!before)
         return { repaired: false };
     try {
@@ -935,24 +671,11 @@ function repairManagedHookRuntimeArtifact(artifact, platform = process.platform)
     catch (err) {
         return { repaired: false, reason: stableHookRuntimeRepairFailure(before, err) };
     }
-    // Post-repair reinspection — prove the artifact is usable without executing it.
     const after = hookRuntimeProblem(artifact, platform);
     return after
         ? { repaired: false, reason: `${before}; repair did not produce a usable shim (${after})` }
         : { repaired: true };
 }
-/**
- * Bounded repair of all broken agents-managed generated hook shims.
- *
- * - Inspect first (read-only, no hook execution).
- * - One generation attempt per unique shim path per call (no retry, no timer).
- * - Canonical owner per shared path: global default, else newest non-isolated.
- * - Post-repair reinspection; unresolved findings become stable needsAttention.
- * - Never recurses into resource sync / registerHooksToSettings.
- *
- * This is the shared routine used by the self-heal `hook-runtime` check and
- * exported for the doctor track.
- */
 export function repairManagedHookRuntimeArtifacts(opts = {}) {
     const platform = opts.platform ?? process.platform;
     const dryRun = opts.dryRun ?? false;
@@ -965,8 +688,6 @@ export function repairManagedHookRuntimeArtifacts(opts = {}) {
     for (const artifact of targets) {
         attemptedPaths.push(artifact.shimPath);
         if (dryRun) {
-            // Would-fix: same shape as a real fix so doctor dry-run and daemon previews
-            // stay consistent with other HealChecks.
             attempts.push({
                 name: artifact.name,
                 path: artifact.shimPath,
@@ -990,31 +711,12 @@ export function repairManagedHookRuntimeArtifacts(opts = {}) {
             fixed.push(`hook shim ${artifact.name}`);
         }
         else if (result.reason) {
-            // Stable needs-attention wording for aggregation across devices / menubar.
-            // No reason means already-healthy no-op (race) — do not emit attention noise.
             needsAttention.push(`hook shim ${artifact.name}: ${result.reason}`);
         }
     }
     return { brokenBefore, attemptedPaths, attempts, fixed, needsAttention };
 }
-/**
- * Verify that every hook the manifest says should be wired is actually
- * referenced in that version's harness-native config, not merely present as a
- * file on disk.
- *
- * `agents doctor` compares hook FILES against source (see diffHooks in
- * doctor-diff.ts) but never checks the wiring, so a hook whose script is
- * byte-identical to source yet missing from settings.json's PreToolUse/Stop/…
- * array reads as "ok" while it never fires. This closes that blind spot.
- *
- * Read-only by construction: it mirrors registerHooksForClaude's command
- * resolution WITHOUT the shim-generation / chmod side effects that
- * resolveHookCommand performs, so it never mutates the version home.
- */
 export function checkVersionHookWiring(agent, version) {
-    // Runtime verification does not rely on parsing a native settings format.
-    // That lets doctor catch a deleted generated shim for every hooks-capable
-    // harness, including families whose wiring schema is intentionally unsupported.
     const runtimeBroken = inspectBrokenManagedHookRuntimeArtifacts({ agent, version })
         .map(({ name, shimPath, reason }) => ({ name, path: shimPath, reason }));
     if (!AGENTS[agent].supportsHooks ||
@@ -1030,21 +732,11 @@ export function checkVersionHookWiring(agent, version) {
             ? path.join(versionHome, '.kimi-code', 'config.toml')
             : path.join(versionHome, agentConfigDirName(agent), 'settings.json');
     const localHooksDir = getVersionHooksDir(agent, version);
-    // Resolve ONLY to a script that was actually synced for THIS agent+version: the
-    // copy in the version home hooks dir, or an absolute subrule-dir path (those are
-    // registered in place, never copied). Deliberately NO central-source fallback —
-    // sync wires `selectHookManifest(parseHookManifest(), hooksToSync)` where
-    // hooksToSync is the per-agent selected set (versions.ts), so a hook the manifest
-    // declares but that was never synced into THIS version home (e.g. a claude-scoped
-    // hook viewed for droid) must not be expected here. A missing-but-declared hook
-    // is a FILE gap that diffHooks reports as `missing`, not a wiring gap.
-    // No ensureExecutable — that chmods, and this path must not touch disk.
     const resolveScript = (script) => {
         if (path.isAbsolute(script) && fs.existsSync(script))
             return script;
         return resolveContainedHookPath(localHooksDir, script);
     };
-    // Read-only mirror of resolveHookCommand — same command string, no shim write.
     const expectedCommand = (name, hookDef) => {
         const scriptPath = resolveScript(hookDef.script);
         if (!scriptPath)
@@ -1064,7 +756,7 @@ export function checkVersionHookWiring(agent, version) {
             continue;
         const command = expectedCommand(name, hookDef);
         if (!command)
-            continue; // script unresolved — a file gap, reported by diffHooks
+            continue;
         for (const event of hookDef.events) {
             if (HOOKS_JSON_HOOK_FAMILY.includes(agent)) {
                 const matcher = GROK_MATCHER_EVENTS.has(event)
@@ -1106,9 +798,6 @@ export function checkVersionHookWiring(agent, version) {
             runtimeBroken,
         };
     }
-    // Command strings actually referenced, keyed by (event, matcher) — a hook wired
-    // under the WRONG matcher group must NOT read as wired, so scope by matcher and
-    // not just by event.
     const wiredByGroup = new Map();
     const groupKey = (event, matcher) => `${event}\n${matcher}`;
     if (TOML_ARRAY_HOOK_FAMILY.includes(agent)) {
@@ -1155,9 +844,6 @@ export function checkVersionHookWiring(agent, version) {
     const wired = expected.filter(isWired);
     return { supported: true, settingsPath, expected: expected.length, unwired, wired, runtimeBroken };
 }
-/**
- * Check if a hook installed in a specific version matches central content.
- */
 function versionHookMatches(agent, version, hookName) {
     const central = listHookEntriesFromDir(getCentralHooksDir()).find((e) => e.name === hookName);
     if (!central)
@@ -1184,9 +870,6 @@ function versionHookMatches(agent, version, hookName) {
         return false;
     }
 }
-/**
- * Compare a version home's hooks against central. Returns the reconciliation diff.
- */
 export function diffVersionHooks(agent, version) {
     const central = new Set(listHookEntriesFromDir(getCentralHooksDir()).map((e) => e.name));
     const installed = new Set(listHooksInVersionHome(agent, version).map((e) => e.name));
@@ -1211,10 +894,6 @@ export function diffVersionHooks(agent, version) {
     }
     return { agent, version, toAdd: toAdd.sort(), toUpdate: toUpdate.sort(), matched, orphans: orphans.sort() };
 }
-/**
- * Remove a single hook (script + data file) from a specific version home.
- * Soft-deletes to ~/.agents/.trash/hooks/.
- */
 export function removeHookFromVersion(agent, version, hookName) {
     try {
         const hooksDir = getVersionHooksDir(agent, version);
@@ -1245,10 +924,6 @@ export function removeHookFromVersion(agent, version, hookName) {
     }
     return { success: true };
 }
-/**
- * Iterate all (agent, version) pairs that support hooks and are installed,
- * optionally scoped to a single agent/version.
- */
 export function iterHooksCapableVersions(filter) {
     const pairs = [];
     const hookAgents = capableAgents('hooks');
@@ -1290,23 +965,18 @@ export async function removeHook(name, agents) {
     }
     return { removed, errors };
 }
-/**
- * Get detailed info about a hook from central storage.
- */
 export function getHookInfo(name) {
     const centralDir = getCentralHooksDir();
     const hookPath = path.join(centralDir, name);
     if (!fs.existsSync(hookPath)) {
         return null;
     }
-    // Read hook content - it could be a file or directory
     let content = '';
     const stat = fs.statSync(hookPath);
     if (stat.isFile()) {
         content = fs.readFileSync(hookPath, 'utf-8');
     }
     else if (stat.isDirectory()) {
-        // For directory hooks, list the files
         const files = fs.readdirSync(hookPath);
         content = `Directory hook containing:\n${files.map((f) => `  - ${f}`).join('\n')}`;
     }
@@ -1320,10 +990,6 @@ export function discoverHooksFromRepo(repoPath) {
     const hooksDir = path.join(repoPath, 'hooks');
     return listHookEntriesFromDir(hooksDir).map((h) => h.name);
 }
-/**
- * Install hooks to central ~/.agents/hooks/ directory.
- * Shims will symlink this to per-agent directories for synced agents.
- */
 export async function installHooksCentrally(source) {
     const installed = [];
     const errors = [];
@@ -1331,7 +997,6 @@ export async function installHooksCentrally(source) {
     if (!fs.existsSync(centralDir)) {
         fs.mkdirSync(centralDir, { recursive: true });
     }
-    // Collect all hooks from shared directory
     const sharedDir = path.join(source, 'hooks');
     const sharedHooks = listHookEntriesFromDir(sharedDir);
     for (const entry of sharedHooks) {
@@ -1345,10 +1010,6 @@ export async function installHooksCentrally(source) {
     }
     return { installed, errors };
 }
-/**
- * List hooks from user (~/.agents/hooks/) and system (~/.agents/.system/hooks/) dirs.
- * User dir takes priority; deduplication preserves first occurrence.
- */
 export function listCentralHooks() {
     const seen = new Set();
     const results = [];
@@ -1363,21 +1024,6 @@ export function listCentralHooks() {
     return results;
 }
 const MAX_HOOK_DURATION_SECONDS = 24 * 60 * 60;
-/**
- * Normalize a hook `timeout` from agents.yaml into a whole number of seconds.
- *
- * A bare number stays seconds (`timeout: 30` → 30) for backward compatibility.
- * A Go-style duration string is parsed into seconds: `5s`, `2m`, `1h30m`,
- * `90s`, `1h`. Suffixed durations longer than 24 hours are rejected as likely
- * typos, while bare seconds stay uncapped for backward compatibility. This
- * intentionally does NOT reuse {@link parseTimeout} from routines.ts — that one
- * returns milliseconds, has no seconds (`s`) unit, and floors at one minute,
- * none of which fit hook timeouts (typically 5–600s).
- *
- * Returns the seconds value, or `null` when the input is not a positive number,
- * is not parseable, or is a suffixed duration longer than 24 hours — the caller
- * decides how to surface that.
- */
 export function normalizeHookTimeoutSeconds(value) {
     if (typeof value === 'number') {
         return Number.isFinite(value) && value > 0 ? value : null;
@@ -1386,7 +1032,6 @@ export function normalizeHookTimeoutSeconds(value) {
         const s = value.trim();
         if (s === '')
             return null;
-        // A bare integer string means seconds, matching the bare-number form.
         if (/^\d+$/.test(s)) {
             const n = Number(s);
             return n > 0 ? n : null;
@@ -1404,31 +1049,16 @@ export function normalizeHookTimeoutSeconds(value) {
     }
     return null;
 }
-/**
- * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
- * (npm-shipped defaults) and user hooks from the `hooks:` section of
- * ~/.agents/agents.yaml. Merges with user-wins-on-key-collision precedence.
- * A user entry with `enabled: false` disables the system-shipped hook of
- * the same name without forking the system file.
- *
- * Hooks marked `enabled: false` are dropped from the returned map. A hook
- * `timeout` written as a duration string (`5s`, `2m`) is normalized to a
- * seconds number here, so every downstream serializer keeps reading a number.
- */
 export function parseHookManifest(opts = {}) {
     const warn = opts.warn !== false;
     const merged = {};
     const systemHooks = {};
-    // Lowest-precedence layer: hooks declared inside active subrule directories.
-    // Seeded first so any same-key entry from system/user agents.yaml wins.
-    // Gated so a malformed hooks.yaml never breaks rule sync.
     try {
         const subruleHooks = collectSubruleHooksFromState();
         for (const [name, def] of Object.entries(subruleHooks))
             merged[name] = def;
     }
-    catch { /* subrule hook collection is best-effort */ }
-    // System layer: hooks: section of agents.yaml (npm-shipped, separate repo).
+    catch { }
     const systemPath = path.join(getSystemAgentsDir(), 'agents.yaml');
     if (fs.existsSync(systemPath)) {
         try {
@@ -1439,14 +1069,8 @@ export function parseHookManifest(opts = {}) {
                     merged[name] = def;
                 }
         }
-        catch { /* skip unreadable manifest */ }
+        catch { }
     }
-    // Extra-repo layer: hooks: section of each enabled extra repo's agents.yaml.
-    // Sits above system but below user, mirroring resolveHookScriptPath's
-    // first-found order (user > extra > system). Without this layer the script
-    // path of an extra-repo hook resolves but its events never register (#602).
-    // Earlier extras win over later ones, so iterate in reverse: the last write
-    // for a given name comes from the earliest-registered repo.
     for (const { dir } of [...getEnabledExtraRepos()].reverse()) {
         const extraMetaPath = path.join(dir, 'agents.yaml');
         if (!fs.existsSync(extraMetaPath))
@@ -1457,9 +1081,8 @@ export function parseHookManifest(opts = {}) {
                 for (const [name, def] of Object.entries(meta.hooks))
                     merged[name] = def;
         }
-        catch { /* skip unreadable extra-repo manifest */ }
+        catch { }
     }
-    // User layer: hooks: section of agents.yaml.
     const userMetaPath = path.join(getUserAgentsDir(), 'agents.yaml');
     if (fs.existsSync(userMetaPath)) {
         try {
@@ -1473,17 +1096,12 @@ export function parseHookManifest(opts = {}) {
                     merged[name] = def;
                 }
         }
-        catch { /* skip unreadable meta */ }
+        catch { }
     }
-    // Strip disabled hooks so they never reach the registrar.
     for (const [name, def] of Object.entries(merged)) {
         if (def.enabled === false)
             delete merged[name];
     }
-    // Normalize each surviving hook's timeout to a seconds number, so the raw
-    // agents.yaml can express it as a duration string (`5s`, `2m`) while every
-    // downstream serializer keeps consuming a plain number. An unparseable value
-    // is dropped with a warning rather than silently coerced to a wrong duration.
     for (const [name, def] of Object.entries(merged)) {
         const raw = def.timeout;
         if (raw === undefined)
@@ -1506,37 +1124,10 @@ export function selectHookManifest(manifest, selected) {
     const selectedHooks = new Set(selected);
     return Object.fromEntries(Object.entries(manifest).filter(([name, hook]) => selectedHooks.has(name) || selectedHooks.has(path.basename(hook.script))));
 }
-/**
- * Hook files present in a version home but absent from every configured
- * SOURCE — genuine orphans left behind by a removed/renamed source hook.
- *
- * The definition is deliberately source-based, not manifest-based (PHNX-2693).
- * Sync copies EVERY source hook file into a version home — registered hooks AND
- * the helper / test / benchmark scripts that sit alongside them — but only the
- * registered ones appear in `parseHookManifest`. Diffing installed names against
- * the manifest therefore flagged every source-present-but-unregistered file
- * (e.g. `permission-handler`, `verify-work-state`, `*_test`, `benchmark_*`) as
- * an orphan, so `agents prune cleanup` offered to trash ~1000 in-use files. An
- * installed hook is only truly orphaned when NO configured source still carries
- * a file of that name — which is exactly what the `prune`/`doctor` help already
- * promised ("present in a version home but missing from every configured
- * source").
- *
- * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
- * installed hook names and the source hook script paths.
- */
 export function unmanagedHookNames(installedHookNames, sourceHookScripts) {
     const inSource = new Set(sourceHookScripts.map((s) => path.basename(s).replace(/\.[^.]+$/, '')));
     return installedHookNames.filter((name) => !inSource.has(name)).sort();
 }
-/**
- * Every hook script path across the resolved SOURCE roots — user
- * (`~/.agents/hooks`), system (`~/.agents/.system/hooks`), and each enabled
- * extra repo's `hooks/` — grouped the same way sync materializes them
- * ({@link listHookEntriesFromDir}, which also descends one-level event-group
- * dirs). This is the set an installed hook must be absent from to count as an
- * orphan.
- */
 function listResolvedSourceHookScripts() {
     const roots = [
         getUserHooksDir(),
@@ -1550,22 +1141,13 @@ function listResolvedSourceHookScripts() {
     }
     return scripts;
 }
-/**
- * The orphan hooks (see {@link unmanagedHookNames}) sitting in one version home:
- * installed hook files whose name matches no file in any configured source root.
- */
 export function listUnmanagedHooksInVersionHome(agent, version) {
     if (!AGENTS[agent].supportsHooks)
         return [];
     const installed = listHooksInVersionHome(agent, version).map((e) => e.name);
     return unmanagedHookNames(installed, listResolvedSourceHookScripts());
 }
-// Codex events that support a matcher field (matches tool name or session type).
-// UserPromptSubmit and Stop never include a matcher.
 const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart']);
-// Maps PascalCase hook event names (as written in hooks.json) to the
-// snake_case labels Codex uses in its persisted [hooks.state] keys.
-// Mirrors hook_event_key_label() in codex-rs/hooks/src/lib.rs.
 const CODEX_EVENT_KEY_LABELS = {
     PreToolUse: 'pre_tool_use',
     PermissionRequest: 'permission_request',
@@ -1578,9 +1160,6 @@ const CODEX_EVENT_KEY_LABELS = {
     SubagentStop: 'subagent_stop',
     Stop: 'stop',
 };
-// Recursively sort object keys alphabetically at every level, mirroring
-// canonical_json() in codex-rs/config/src/fingerprint.rs. Codex hashes the
-// canonical JSON form so trust survives key-order differences.
 function canonicalizeForHash(value) {
     if (Array.isArray(value)) {
         return value.map(canonicalizeForHash);
@@ -1594,22 +1173,6 @@ function canonicalizeForHash(value) {
     }
     return value;
 }
-/**
- * Compute the trust hash Codex expects for a single command hook handler, so
- * agents-cli can pre-trust the hooks it registers. Without a matching
- * trusted_hash in [hooks.state], Codex classifies the hook Untrusted and
- * silently drops it in non-interactive (`codex exec`) mode where there is no
- * TUI prompt to approve it.
- *
- * Mirrors command_hook_hash() in codex-rs/hooks/src/engine/discovery.rs +
- * version_for_toml() in codex-rs/config/src/fingerprint.rs:
- *   sha256( canonicalJson( NormalizedHookIdentity ) ) prefixed with "sha256:".
- *
- * The identity passes through TOML on the Codex side, which drops None fields
- * (commandWindows, statusMessage, and matcher when absent). `async` is always
- * false (async hooks are not yet supported) and is always present. `timeout`
- * is normalized to >= 1 (Codex: unwrap_or(600).max(1)).
- */
 export function computeCodexHookTrustHash(eventKeyLabel, command, timeout, matcher) {
     const handler = {
         type: 'command',
@@ -1628,22 +1191,6 @@ export function computeCodexHookTrustHash(eventKeyLabel, command, timeout, match
     const hex = crypto.createHash('sha256').update(JSON.stringify(canonical), 'utf-8').digest('hex');
     return `sha256:${hex}`;
 }
-/**
- * Register hooks as lifecycle events in an agent's config.
- * Reads hooks.yaml manifest, merges into the agent's config file(s).
- * Only manages hooks whose command paths are under ~/.agents/hooks/ or
- * ~/.agents/.system/hooks/. Does not remove user-added hooks.
- *
- * @param agentsDirOverride - When provided, treats this single dir as the
- *   only managed hook root. Used by tests to inject a temp path. In normal
- *   operation, both user and system roots are consulted with user precedence.
- */
-/**
- * Delete shim files for hooks that no longer exist in the manifest.
- * managedPrefixes already GCs the settings.json entries pointing at orphaned
- * shims, but the .sh files on disk would otherwise persist forever. Called
- * once per registerHooksToSettings invocation — cheap (a single readdir).
- */
 function sweepOrphanShims(manifest) {
     const shimsDir = getHookShimsDir();
     if (!fs.existsSync(shimsDir))
@@ -1658,7 +1205,7 @@ function sweepOrphanShims(manifest) {
         try {
             fs.unlinkSync(path.join(shimsDir, file));
         }
-        catch { /* best effort */ }
+        catch { }
     }
 }
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride, options) {
@@ -1681,14 +1228,10 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (!options?.skipGlobalShimSweep)
         sweepOrphanShims(manifest);
     const overrideRoots = agentsDirOverride ? [agentsDirOverride] : null;
-    // Scripts are copied into the version home during sync — prefer that stable
-    // local path so registered commands don't break when source dirs change.
     const localHooksDir = !overrideRoots
         ? getHooksDirInHome(agentId, versionHome)
         : null;
     const resolveScript = (script) => {
-        // Subrule-dir hooks declare an already-absolute script path. Use it
-        // directly (made executable) — these are not copied into the version home.
         if (path.isAbsolute(script) && fs.existsSync(script)) {
             ensureExecutable(script);
             return script;
@@ -1697,8 +1240,6 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
             return resolveContainedHookPath(path.join(overrideRoots[0], 'hooks'), script);
         }
         if (localHooksDir) {
-            // Prefer the exact relative path, then a flat basename copy (sync flattens
-            // group-dir scripts into the version-home hooks/ root).
             const local = resolveContainedHookPath(localHooksDir, script) ||
                 resolveContainedHookPath(localHooksDir, path.basename(script));
             if (local)
@@ -1709,36 +1250,20 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     const managedPrefixes = overrideRoots
         ? [
             path.join(overrideRoots[0], 'hooks') + path.sep,
-            // The shim dir is one global location regardless of which hooks
-            // source (agentsDirOverride vs the normal user/system dirs) resolved
-            // the underlying script, so it belongs in every managedPrefixes
-            // shape — omitting it here left a shim path unrecognized as managed
-            // under the override branch, so a hook's matcher/event change never
-            // GC'd its stale shim-path entry (only reachable via a caller that
-            // passes agentsDirOverride; no production call site does today).
             getHookShimsDir() + path.sep,
         ]
         : [
             ...getManagedHookPrefixes(),
             ...(localHooksDir ? [localHooksDir + path.sep] : []),
-            // Generated cache/timing shims live here; needs GC coverage so that a
-            // hook whose `cache:` field is removed gets its stale shim path purged
-            // from the agent's settings file (see resolveHookCommand).
             getHookShimsDir() + path.sep,
         ];
     if (agentId === 'claude') {
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes);
     }
     if (agentId === 'droid') {
-        // Droid's settings.json hooks schema is identical to Claude's (top-level
-        // `hooks` object → event → matcher-group array), so reuse the Claude
-        // registrar targeting `.factory/settings.json` (agentConfigDirName('droid')).
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, agentConfigDirName('droid'));
     }
     if (agentId === 'muse') {
-        // Muse Code: Claude-compatible hooks block in ~/.config/muse/settings.json
-        // (events SessionStart / PreToolUse / …, matcher groups, command hooks).
-        // settings.json MUST carry schema_version: 1 or Muse refuses to start.
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, agentConfigDirName('muse'), { schemaVersion: 1 });
     }
     if (agentId === 'codex') {
@@ -1770,19 +1295,6 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     }
     return { registered: [], errors: [] };
 }
-/**
- * The concrete config file(s) `registerHooksToSettings` writes for `agentId` in
- * `home` — the settings/registrar leaves, NOT the per-hook script copies. A
- * caller materializing into an UNTRUSTED home (the portable-agent materializer)
- * uses this to verify none of those leaves is a preplanted symlink before the
- * registrar follows it and overwrites a file outside the home.
- *
- * This MUST mirror the `registerHooksToSettings` dispatch above — each arm's
- * write target is reproduced here, so a new registrar branch adds its leaf here
- * too. It intentionally returns only the primary settings/registrar file(s); the
- * per-event/script files a registrar also writes live under the hooks dir the
- * caller already guards. An agent with no hooks registrar returns `[]`.
- */
 export function hookRegistrationTargets(agentId, home) {
     switch (agentId) {
         case 'claude':
@@ -1824,15 +1336,6 @@ const OPENCODE_LIFECYCLE_EVENT_MAP = {
     OnError: ['session.error'],
     Notification: ['permission.asked'],
 };
-/**
- * Compile canonical hooks.yaml entries into a local OpenCode plugin.
- *
- * OpenCode has no declarative shell-hook config block. It auto-loads direct
- * TS/JS modules from ~/.config/opencode/plugins/, and supplies Bun's `$` shell
- * primitive to each plugin. The generated module subscribes to native plugin
- * events, sends the event payload to the managed hook script as JSON on stdin,
- * and surfaces a non-zero script exit as a plugin error.
- */
 function registerHooksForOpenCode(versionHome, manifest, resolveScript) {
     const registered = [];
     const errors = [];
@@ -1870,8 +1373,6 @@ function registerHooksForOpenCode(versionHome, manifest, resolveScript) {
     }
     const serializedDirect = JSON.stringify(Object.fromEntries(direct), null, 2);
     const serializedLifecycle = JSON.stringify(Object.fromEntries(lifecycle), null, 2);
-    // Same disposable perf spool the bash shims (hooks/cache.ts) append to — see
-    // the timedOut branch below for why OpenCode needs its own writer.
     const perfSpoolPath = path.join(getPerfDir(), 'spool.jsonl');
     const pluginSource = `// Generated by agents-cli. Re-run agents sync to update.
 import fs from "node:fs"
@@ -1988,18 +1489,8 @@ export const AgentsCliHooks = async ({ $ }) => ({
     }
     return { registered, errors };
 }
-/**
- * Antigravity (agy) event names differ from agents-cli manifest names. The
- * mapping below is the documented agy schema. PostToolUse has no exact
- * agy equivalent — agy fires `after_model_call` after the model finishes a
- * turn (which includes any tool calls in that turn), so it's the closest
- * lifecycle phase but not a 1:1 match. Manifest events not in this map are
- * skipped silently (the manifest may declare events for other agents).
- */
 const ANTIGRAVITY_EVENT_MAP = {
     PreToolUse: 'before_tool_call',
-    // Imperfect mapping: agy has no per-tool post-event. after_model_call
-    // fires once at the end of the turn, after all tool calls completed.
     PostToolUse: 'after_model_call',
     Stop: 'on_loop_stop',
     OnError: 'on_error',
@@ -2021,7 +1512,6 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
             return { registered, errors };
         }
     }
-    // Muse (and any future agent that pins a settings schema) requires this key.
     if (options?.schemaVersion !== undefined && config.schema_version === undefined) {
         config.schema_version = options.schemaVersion;
     }
@@ -2029,41 +1519,17 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
         config.hooks = {};
     }
     const hooks = config.hooks;
-    // Build set of all command paths the current manifest will register.
-    // Used to garbage-collect stale entries left behind after hook renames
-    // or after a `cache:` field is added/removed (raw script vs shim path).
-    const currentManifestPaths = new Set();
+    const expected = new Set();
     for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
-        if (resolved)
-            currentManifestPaths.add(resolved);
-    }
-    // Identity of the version home being synced. Used to prune entries that point
-    // at a DIFFERENT version home of the same agent (see isStaleSiblingVersionCommand).
-    const currentVh = versionHomeIdentity(versionHome);
-    // Remove stale entries: any hook command under a managed root that isn't in
-    // the current manifest is a leftover from a renamed/deleted hook script; any
-    // command pointing at a sibling version's home is a leftover from that
-    // version's sync (its version-scoped path never matches the current set).
-    for (const eventEntries of Object.values(hooks)) {
-        if (!Array.isArray(eventEntries))
-            continue;
-        for (const group of eventEntries) {
-            if (!group.hooks)
-                continue;
-            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
-                !isStaleSiblingVersionCommand(h.command, currentVh));
-            group.hooks = collapseVersionHookEntries(managed, versionHome);
-        }
-    }
-    // Remove empty matcher groups left after cleanup
-    for (const [event, eventEntries] of Object.entries(hooks)) {
-        if (!Array.isArray(eventEntries))
+        if (!resolved)
             continue;
-        hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
+        for (const event of hookDef.events)
+            expected.add(hookEntryKey(event, hookDef.matcher, resolved));
     }
+    pruneManagedHookEntries(hooks, expected, managedPrefixes);
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
@@ -2110,19 +1576,6 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     }
     return { registered, errors };
 }
-/**
- * Prune every Claude-family (`settings.json`) hook entry whose command lives
- * under a removed version's home
- * (`~/.agents/.history/versions/<agent>/<removedVersion>/home/…`).
- *
- * `agents remove <agent>@<version>` soft-deletes the version's files but leaves
- * the hook entries other version homes registered against it — dead hooks that
- * error on every tool call ("No such file or directory") until the next sync.
- * This clears them from a remaining version's settings immediately. Only the
- * removed version's entries are touched; the current version's entries, system
- * hooks, and the user's own custom hooks are left intact. Returns the number of
- * entries removed.
- */
 export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, removedVersion) {
     if (!fs.existsSync(settingsPath))
         return 0;
@@ -2153,7 +1606,6 @@ export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, rem
     }
     if (removed === 0)
         return 0;
-    // Drop matcher groups left empty by the prune.
     for (const [event, eventEntries] of Object.entries(hooks)) {
         if (!Array.isArray(eventEntries))
             continue;
@@ -2163,8 +1615,6 @@ export function pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, rem
         fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
     }
     catch {
-        // Best-effort cleanup: a write failure leaves the dead entry to be pruned
-        // on the next sync (see isStaleSiblingVersionCommand).
         return 0;
     }
     return removed;
@@ -2180,16 +1630,9 @@ function trustCodexHooks(hooksPath) {
     if (!tomlConfig.features || typeof tomlConfig.features !== 'object') {
         tomlConfig.features = {};
     }
-    // Codex 0.116+ feature flag is `hooks` (the legacy `codex_hooks` name is
-    // an unrecognized key that triggers a deprecation error and is ignored).
     const features = tomlConfig.features;
     delete features.codex_hooks;
     features.hooks = true;
-    // Pre-trust hooks. The [hooks.state] key is keyed by the hooks.json path
-    // exactly as Codex resolves it (the absolute CODEX_HOME path), the
-    // snake_case event label, and the per-event group/handler indices — which
-    // must match Codex's parse order, so we iterate the just-written
-    // hooksFile structure in array order.
     if (!tomlConfig.hooks || typeof tomlConfig.hooks !== 'object') {
         tomlConfig.hooks = {};
     }
@@ -2210,8 +1653,6 @@ function trustCodexHooks(hooksPath) {
                     return;
                 const keys = hookPaths.map((file) => `${file}:${eventKeyLabel}:${groupIdx}:${handlerIdx}`);
                 const trustedHash = computeCodexHookTrustHash(eventKeyLabel, handler.command, handler.timeout, group.matcher);
-                // Preserve a user's explicit `enabled = false` for this exact hook;
-                // only (re)write the trust hash.
                 const entry = { trusted_hash: trustedHash };
                 if (keys.some((key) => existingState[key]?.enabled === false)) {
                     entry.enabled = false;
@@ -2221,8 +1662,6 @@ function trustCodexHooks(hooksPath) {
             });
         });
     }
-    // Carry forward trust state for any hooks we did not (re)register this
-    // pass — e.g. user-added hooks under a different command path.
     for (const [key, entry] of Object.entries(existingState)) {
         if (!(key in hookState)) {
             hookState[key] = entry;
@@ -2236,7 +1675,6 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     const errors = [];
     const configDir = path.join(versionHome, '.codex');
     const hooksPath = path.join(configDir, 'hooks.json');
-    // Read existing hooks.json — must have top-level "hooks" wrapper key
     let hooksFile = { hooks: {} };
     if (fs.existsSync(hooksPath)) {
         try {
@@ -2254,33 +1692,19 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
             return { registered, errors };
         }
     }
-    // Build set of current manifest command paths for codex to GC stale entries.
-    // Uses resolveHookCommand so cached hooks resolve to their shim path.
-    const currentManifestPaths = new Set();
+    const expected = new Set();
     for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
-        if (resolved)
-            currentManifestPaths.add(resolved);
-    }
-    // Identity of the version home being synced. Codex stores hooks in a shared
-    // hooks.json per CODEX_HOME, but agents-cli registers version-scoped command
-    // paths; without this, old version entries keep firing after upgrades.
-    const currentVh = versionHomeIdentity(versionHome);
-    // Remove stale entries from all event groups
-    for (const eventGroups of Object.values(hooksFile.hooks)) {
-        for (const group of eventGroups) {
-            if (!group.hooks)
-                continue;
-            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
-                !isStaleSiblingVersionCommand(h.command, currentVh));
-            group.hooks = collapseVersionHookEntries(managed, versionHome);
+        if (!resolved)
+            continue;
+        for (const event of hookDef.events) {
+            const matcher = CODEX_MATCHER_EVENTS.has(event) ? hookDef.matcher : undefined;
+            expected.add(hookEntryKey(event, matcher, resolved));
         }
     }
-    for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
-        hooksFile.hooks[event] = eventGroups.filter((g) => g.hooks && g.hooks.length > 0);
-    }
+    pruneManagedHookEntries(hooksFile.hooks, expected, managedPrefixes);
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
@@ -2295,11 +1719,8 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
                 hooksFile.hooks[event] = [];
             }
             const eventGroups = hooksFile.hooks[event];
-            // PreToolUse / PostToolUse / SessionStart use a matcher field.
-            // UserPromptSubmit / Stop never include a matcher.
             const usesMatcher = CODEX_MATCHER_EVENTS.has(event);
             const matcherValue = usesMatcher ? (hookDef.matcher ?? '') : undefined;
-            // Find the group for this matcher (or the sole no-matcher group)
             let group;
             if (matcherValue !== undefined) {
                 group = eventGroups.find((g) => (g.matcher ?? '') === matcherValue);
@@ -2341,11 +1762,6 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         errors.push(`Failed to write hooks.json: ${err.message}`);
         return { registered, errors };
     }
-    // Ensure [features] hooks = true and pre-trust every registered hook in
-    // config.toml. Codex only runs hooks that are enabled AND trusted; in
-    // non-interactive (`codex exec`) mode there is no TUI prompt to approve
-    // them, so an untrusted hook is silently dropped. We compute the same
-    // trust hash Codex would and persist it under [hooks.state].
     try {
         trustCodexHooks(hooksPath);
     }
@@ -2354,14 +1770,6 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     }
     return { registered, errors };
 }
-/**
- * Register hooks into antigravity's (agy) settings.json. Unlike gemini, agy uses
- * a flat per-event array of `{ command }` entries (no matcher groups). Events
- * are renamed via ANTIGRAVITY_EVENT_MAP; unmapped manifest events are skipped.
- *
- * settings.json lives at `${versionHome}/.gemini/antigravity-cli/settings.json`
- * because agy nests its config under the shared `.gemini` parent dir.
- */
 function registerHooksForAntigravity(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
@@ -2384,16 +1792,10 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
         config.hooks = {};
     }
     const hooks = config.hooks;
-    // Build set of all command paths the current manifest will register, so we
-    // can garbage-collect stale managed entries left over from renamed/deleted
-    // hooks. Only managed paths are considered for removal — user-added entries
-    // outside managedPrefixes are preserved.
     const currentManifestPaths = new Set();
     for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        // Only paths whose events map to a known agy event would actually be
-        // registered, so only those should survive GC.
         const anyMapped = hookDef.events.some((e) => ANTIGRAVITY_EVENT_MAP[e]);
         if (!anyMapped)
             continue;
@@ -2430,12 +1832,10 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
         for (const event of hookDef.events) {
             const agyEvent = ANTIGRAVITY_EVENT_MAP[event];
             if (!agyEvent)
-                continue; // unmapped event — silently skip
+                continue;
             if (!hooks[agyEvent]) {
                 hooks[agyEvent] = [];
             }
-            // Antigravity settings entries: command + optional matcher (tool scope).
-            // Without matcher every PreToolUse guard fires on ALL tools (RUSH-1353).
             const list = hooks[agyEvent];
             const existingIdx = list.findIndex((e) => e && typeof e === 'object' && e.command === commandPath);
             const entry = { command: commandPath };
@@ -2459,44 +1859,10 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
     }
     return { registered, errors };
 }
-/**
- * Grok events that accept a `matcher` field. Per the Grok hooks guide
- * (docs/user-guide/10-hooks.md, "Key Fields"): the matcher applies to the tool
- * events — `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionDenied`
- * (matches the tool name) — and to `Notification` (matches the notification
- * type). The lifecycle events `SessionStart`, `SessionEnd`, `Stop`,
- * `UserPromptSubmit` REJECT a matcher (they raise loading errors); other events
- * ignore it. Of the events this registrar emits (see GROK_EVENT_MAP), only these
- * three accept a matcher, so we emit it for these alone.
- */
 const GROK_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'Notification']);
-/**
- * Tool-name matcher aliases for tools Grok does NOT auto-alias. Grok maps common
- * Claude tool names to its own (Bash → run_terminal_command, Read → read_file,
- * etc. — docs/user-guide/10-hooks.md, "Tool Name Aliases") and "a matcher keeps
- * its original name too", so most matchers need no translation. But there is no
- * alias for `ExitPlanMode`: Grok's plan tools are `enter_plan_mode` /
- * `exit_plan_mode` (docs/user-guide/19-plan-mode.md line 14), so a bare
- * `ExitPlanMode` matcher would never fire. Broaden it to a regex that matches
- * both names. Keep this an explicit, minimal map — not a general translation
- * engine.
- */
 const GROK_MATCHER_ALIASES = {
     ExitPlanMode: 'ExitPlanMode|exit_plan_mode',
 };
-/**
- * Register hooks for Grok Build.
- *
- * Grok merges ALL of `~/.grok/hooks/*.json` (docs/user-guide/10-hooks.md, "Hook
- * Locations"), so this registrar writes exactly ONE manifest file, `hooks.json`,
- * and prunes any stale per-event files (`pretooluse.json`, …) that an older
- * build wrote — otherwise every hook would run twice per event, forever, on
- * already-synced installs.
- *
- * Matchers are grouped one-per-distinct-matcher (like the Claude writer) and are
- * emitted only for the events that accept them (GROK_MATCHER_EVENTS); tool-name
- * matchers Grok does not auto-alias are translated via GROK_MATCHER_ALIASES.
- */
 function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
@@ -2528,14 +1894,10 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
                 grokHooks.hooks[grokEvent] = [];
             }
             const groups = grokHooks.hooks[grokEvent];
-            // Emit the matcher only for events that accept one; translate tool names
-            // Grok does not auto-alias. Empty/omitted matcher matches everything.
             let matcher;
             if (GROK_MATCHER_EVENTS.has(grokEvent) && hookDef.matcher) {
                 matcher = GROK_MATCHER_ALIASES[hookDef.matcher] ?? hookDef.matcher;
             }
-            // Group by matcher the way the Claude writer does: one group per distinct
-            // matcher, hooks appended into the group — not one group per hook.
             let group = groups.find((g) => (g.matcher ?? '') === (matcher ?? ''));
             if (!group) {
                 group = matcher ? { matcher, hooks: [] } : { hooks: [] };
@@ -2552,8 +1914,6 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
             registered.push(`${name} -> ${grokEvent}`);
         }
     }
-    // Single source of truth: hooks.json. Written fresh from the manifest every
-    // sync, so the registrar owns it outright.
     const mainHooksPath = path.join(grokHooksDir, 'hooks.json');
     try {
         fs.writeFileSync(mainHooksPath, JSON.stringify(grokHooks, null, 2));
@@ -2561,11 +1921,6 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
     catch (e) {
         errors.push(`Failed to write hooks.json: ${e.message}`);
     }
-    // Clean up stale per-event files (pretooluse.json, session-start.json, …) that
-    // older builds double-wrote. Grok merges every *.json in this dir, so leaving
-    // them would run each hook twice per event. Only remove files whose contents
-    // are entirely managed by us (a lone `hooks` object referencing our managed
-    // command paths); a user's own custom *.json is left untouched.
     try {
         for (const file of fs.readdirSync(grokHooksDir)) {
             if (!file.endsWith('.json') || file === 'hooks.json')
@@ -2581,13 +1936,6 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
     }
     return { registered, errors };
 }
-/**
- * A per-event Grok hook file is "ours" (safe to prune) when it is a
- * `{ hooks: { <Event>: [...] } }` document in which every command entry points
- * at a managed path (see isManagedHookCommand). This is exactly the shape older
- * builds double-wrote; a user's hand-authored *.json that mixes in unmanaged
- * commands is preserved. A file we can't parse is treated as not-ours.
- */
 function isManagedGrokHookFile(filePath, managedPrefixes) {
     let parsed;
     try {
@@ -2625,7 +1973,6 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
     const registered = [];
     const errors = [];
     const configPath = path.join(versionHome, '.kimi-code', 'config.toml');
-    // Read existing config.toml
     let config = {};
     if (fs.existsSync(configPath)) {
         try {
@@ -2636,7 +1983,6 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
             return { registered, errors };
         }
     }
-    // Build set of current manifest command paths for GC
     const currentManifestPaths = new Set();
     for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
@@ -2645,7 +1991,6 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
         if (resolved)
             currentManifestPaths.add(resolved);
     }
-    // Remove stale managed hooks from existing hooks array
     let hooksArray = [];
     if (Array.isArray(config.hooks)) {
         hooksArray = config.hooks;
@@ -2658,7 +2003,6 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
             return true;
         return currentManifestPaths.has(cmd);
     });
-    // Add/update hooks from manifest
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
@@ -2670,7 +2014,6 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
         const timeout = hookDef.timeout ?? 30;
         for (const event of hookDef.events) {
             const matcher = hookDef.matcher;
-            // Find existing hook with same event, command, and matcher
             const existingIdx = filteredHooks.findIndex((h) => {
                 const sameEvent = h.event === event;
                 const sameCmd = h.command === commandPath;
@@ -2704,13 +2047,6 @@ function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefi
     }
     return { registered, errors };
 }
-/**
- * Canonical hooks.yaml event names → Copilot camelCase event names.
- * Copilot accepts both camelCase (native) and PascalCase (VS Code-compatible).
- * We emit camelCase, the format documented at
- * https://docs.github.com/en/copilot/reference/hooks-configuration.
- * Unmapped events are skipped so a Claude-only event does not land in the file.
- */
 const COPILOT_EVENT_MAP = {
     SessionStart: 'sessionStart',
     SessionEnd: 'sessionEnd',
@@ -2726,10 +2062,6 @@ const COPILOT_EVENT_MAP = {
     Notification: 'notification',
     PermissionRequest: 'permissionRequest',
 };
-/**
- * Copilot events that accept a `matcher` field (regex, full-string match).
- * See "Matcher filtering" in the Copilot hooks reference.
- */
 const COPILOT_MATCHER_EVENTS = new Set([
     'preToolUse',
     'postToolUse',
@@ -2738,18 +2070,7 @@ const COPILOT_MATCHER_EVENTS = new Set([
     'notification',
     'subagentStart',
 ]);
-/** Managed filename under ~/.copilot/hooks/ — we own this file entirely. */
 const COPILOT_MANAGED_HOOKS_FILE = 'agents-cli-hooks.json';
-/**
- * Register hooks for GitHub Copilot CLI.
- *
- * Copilot loads every `*.json` under `~/.copilot/hooks/` (and project
- * `.github/hooks/`). Schema: `{ "version": 1, "hooks": { event: [entries] } }`
- * with command entries `{ type: "command", bash|command, timeoutSec?, matcher? }`.
- *
- * We rewrite a single managed file (`agents-cli-hooks.json`) on every sync so
- * GC is trivial — user-authored sibling JSON files are never touched.
- */
 function registerHooksForCopilot(versionHome, manifest, resolveScript, _managedPrefixes) {
     const registered = [];
     const errors = [];
@@ -2768,7 +2089,7 @@ function registerHooksForCopilot(versionHome, manifest, resolveScript, _managedP
         for (const event of hookDef.events) {
             const copilotEvent = COPILOT_EVENT_MAP[event];
             if (!copilotEvent)
-                continue; // unmapped — skip silently
+                continue;
             if (!hooks[copilotEvent])
                 hooks[copilotEvent] = [];
             const entry = {
@@ -2779,7 +2100,6 @@ function registerHooksForCopilot(versionHome, manifest, resolveScript, _managedP
             if (COPILOT_MATCHER_EVENTS.has(copilotEvent) && hookDef.matcher) {
                 entry.matcher = hookDef.matcher;
             }
-            // De-dupe on (event, command, matcher) so repeated sync is idempotent.
             const existingIdx = hooks[copilotEvent].findIndex((h) => h.command === entry.command && (h.matcher ?? '') === (entry.matcher ?? ''));
             if (existingIdx >= 0) {
                 hooks[copilotEvent][existingIdx] = entry;
@@ -2792,7 +2112,6 @@ function registerHooksForCopilot(versionHome, manifest, resolveScript, _managedP
     }
     const outPath = path.join(copilotHooksDir, COPILOT_MANAGED_HOOKS_FILE);
     try {
-        // Always rewrite: empty manifest → empty hooks object (GC of prior managed entries).
         fs.writeFileSync(outPath, JSON.stringify({ version: 1, hooks }, null, 2) + '\n', 'utf-8');
     }
     catch (err) {
@@ -2800,10 +2119,6 @@ function registerHooksForCopilot(versionHome, manifest, resolveScript, _managedP
     }
     return { registered, errors };
 }
-/**
- * Canonical hooks.yaml event names that goose supports (Open Plugins PascalCase).
- * Unmapped events are skipped. Goose ≥ 1.34.0.
- */
 const GOOSE_EVENT_MAP = {
     SessionStart: 'SessionStart',
     SessionEnd: 'SessionEnd',
@@ -2816,22 +2131,8 @@ const GOOSE_EVENT_MAP = {
     AfterFileEdit: 'AfterFileEdit',
     BeforeShellExecution: 'BeforeShellExecution',
     AfterShellExecution: 'AfterShellExecution',
-    // SubagentStart/SubagentStop are not emitted by Goose — do not advertise them.
 };
-/** Managed Open Plugins directory name under ~/.agents/plugins/. */
 const GOOSE_MANAGED_PLUGIN_NAME = 'agents-cli-hooks';
-/**
- * Register hooks for Goose (block-goose-cli ≥ 1.34.0).
- *
- * Goose auto-discovers Open Plugins under `$HOME/.agents/plugins/<name>/` that
- * contain `hooks/hooks.json` (HOME is the version home under the agents-cli
- * shim). Schema (Open Plugins / Claude-shaped):
- *   { "hooks": { Event: [ { matcher?, hooks: [{ type: "command", command }] } ] } }
- *
- * We own a single managed plugin (`agents-cli-hooks`) under the version home
- * and rewrite its hooks.json on every sync. Command paths are absolute
- * (portable ~/ form) pointing at the already-copied hook scripts.
- */
 function registerHooksForGoose(versionHome, manifest, resolveScript, _managedPrefixes) {
     const registered = [];
     const errors = [];
@@ -2871,15 +2172,11 @@ function registerHooksForGoose(versionHome, manifest, resolveScript, _managedPre
             registered.push(`${name} -> ${gooseEvent}`);
         }
     }
-    // Goose discovers Open Plugins at ~/.agents/plugins/<name>/ when HOME is the
-    // version home (shim sets HOME). Write under versionHome so each installed
-    // goose version gets its own managed plugin and tests stay hermetic.
     const pluginRoot = path.join(versionHome, '.agents', 'plugins', GOOSE_MANAGED_PLUGIN_NAME);
     const hooksDir = path.join(pluginRoot, 'hooks');
     const outPath = path.join(hooksDir, 'hooks.json');
     try {
         fs.mkdirSync(hooksDir, { recursive: true });
-        // Minimal plugin marker so the directory is a valid Open Plugins bundle.
         const markerPath = path.join(pluginRoot, '.agents-cli-managed');
         if (!fs.existsSync(markerPath)) {
             fs.writeFileSync(markerPath, 'managed by agents-cli hooks sync\n', 'utf-8');
@@ -2891,16 +2188,6 @@ function registerHooksForGoose(versionHome, manifest, resolveScript, _managedPre
     }
     return { registered, errors };
 }
-/**
- * Canonical → Cursor CLI camelCase events.
- *
- * Only events verified to fire in cursor-agent CLI (not full IDE parity).
- * Ticket RUSH-1326 note (2026-06): working = sessionStart, stop, preToolUse,
- * postToolUse, beforeShellExecution, afterShellExecution, beforeReadFile,
- * afterFileEdit. Also map SessionEnd / beforeSubmitPrompt / preCompact /
- * subagent* which Cursor documents for agent hooks.
- * Unmapped events (e.g. afterAgentResponse) are skipped.
- */
 const CURSOR_EVENT_MAP = {
     SessionStart: 'sessionStart',
     SessionEnd: 'sessionEnd',
@@ -2917,15 +2204,6 @@ const CURSOR_EVENT_MAP = {
     BeforeReadFile: 'beforeReadFile',
     AfterFileEdit: 'afterFileEdit',
 };
-/**
- * Register hooks for Cursor CLI (`cursor-agent`).
- *
- * Writes `~/.cursor/hooks.json` (under version home):
- *   { "version": 1, "hooks": { event: [{ command, timeout?, matcher? }] } }
- *
- * GC: rewrite managed entries by command path under managedPrefixes; preserve
- * user-authored entries whose command is outside managed roots.
- */
 function registerHooksForCursor(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
@@ -2943,8 +2221,6 @@ function registerHooksForCursor(versionHome, manifest, resolveScript, managedPre
             return { registered, errors };
         }
     }
-    // Desired managed entries keyed by event|command|matcher so a matcher or
-    // event change drops the stale entry instead of retaining it by command path alone.
     const desiredManaged = new Set();
     for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
@@ -2959,7 +2235,6 @@ function registerHooksForCursor(versionHome, manifest, resolveScript, managedPre
             desiredManaged.add(`${cursorEvent}|${resolved}|${hookDef.matcher ?? ''}`);
         }
     }
-    // GC managed entries that are no longer in the manifest (by event+command+matcher)
     const hooks = {};
     for (const [event, entries] of Object.entries(existing.hooks || {})) {
         if (!Array.isArray(entries))
@@ -3011,15 +2286,6 @@ function registerHooksForCursor(versionHome, manifest, resolveScript, managedPre
     }
     return { registered, errors };
 }
-/**
- * Canonical → Hermes (Nous Research) snake_case lifecycle events.
- *
- * Hermes ≥ 0.11.0 runs configurable hooks declared under `hooks:` in
- * ~/.hermes/config.yaml. Only events with a documented Hermes equivalent are
- * mapped; unmapped canonical events (the manifest may declare events for other
- * agents) are skipped silently. UserPromptSubmit maps to `pre_llm_call` (the
- * closest pre-turn phase) and Stop to `on_session_finalize`.
- */
 const HERMES_EVENT_MAP = {
     SessionStart: 'on_session_start',
     SessionEnd: 'on_session_end',
@@ -3029,29 +2295,13 @@ const HERMES_EVENT_MAP = {
     UserPromptSubmit: 'pre_llm_call',
     Stop: 'on_session_finalize',
 };
-/** Hermes caps hook timeouts at 300s (default 60s). */
 const HERMES_TIMEOUT_CAP = 300;
 const HERMES_TIMEOUT_DEFAULT = 60;
-/**
- * Register hooks for Hermes Agent (Nous Research ≥ 0.11.0).
- *
- * Read-modify-writes the shared `~/.hermes/config.yaml` (under the version
- * home): it merges a `hooks:` block of the form
- *   hooks: { <event>: [ { command, timeout, matcher? } ] }
- * into the YAML doc WITHOUT touching sibling keys (`mcp_servers` in
- * particular — a naive overwrite would wipe the user's MCP servers). No
- * `version` wrapper: Hermes' config is a flat YAML map.
- *
- * GC: rewrite managed entries by command path under managedPrefixes; preserve
- * user-authored entries whose command is outside managed roots. Keyed by
- * event|command|matcher so a matcher or event change drops the stale entry.
- */
 function registerHooksForHermes(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
     const configDir = path.join(versionHome, '.hermes');
     const configPath = path.join(configDir, 'config.yaml');
-    // Read-modify-write: preserve the full existing YAML doc (mcp_servers, etc.).
     let config = {};
     if (fs.existsSync(configPath)) {
         try {
@@ -3068,8 +2318,6 @@ function registerHooksForHermes(versionHome, manifest, resolveScript, managedPre
     const existingHooks = config.hooks && typeof config.hooks === 'object' && !Array.isArray(config.hooks)
         ? config.hooks
         : {};
-    // Desired managed entries keyed by event|command|matcher so a matcher or
-    // event change drops the stale entry instead of retaining it by command alone.
     const desiredManaged = new Set();
     for (const [hookName, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
@@ -3084,7 +2332,6 @@ function registerHooksForHermes(versionHome, manifest, resolveScript, managedPre
             desiredManaged.add(`${hermesEvent}|${resolved}|${hookDef.matcher ?? ''}`);
         }
     }
-    // GC managed entries that are no longer in the manifest; preserve user entries.
     const hooks = {};
     for (const [event, entries] of Object.entries(existingHooks)) {
         if (!Array.isArray(entries))
@@ -3145,12 +2392,10 @@ function registerHooksForHermes(versionHome, manifest, resolveScript, managedPre
 const execFileAsync = promisify(execFile);
 function resolveSessionTrackerRoot() {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    // Built/installed layout: dist/lib/hooks/ -> dist/session-tracker
     const built = path.resolve(here, '..', '..', 'session-tracker');
     if (fs.existsSync(path.join(built, 'dist', 'hook.sh'))) {
         return built;
     }
-    // Source layout: cli/src/lib/hooks/ -> repo root (4 up) -> packages/session-tracker
     const source = path.resolve(here, '..', '..', '..', '..', 'packages', 'session-tracker');
     if (fs.existsSync(path.join(source, 'src', 'hook.sh'))) {
         return source;
@@ -3176,14 +2421,6 @@ function buildInstallHookInvocation(trackerRoot, agent) {
         args: [loader, path.join(trackerRoot, 'src', 'install-hook.ts'), agent],
     };
 }
-/**
- * Install the shared SessionStart state-writer hook (`packages/session-tracker`)
- * into the harness's native config. Gated by `supports(agent, 'hooks', version)`;
- * unsupported agents return `installed: false` with a reason instead of throwing.
- *
- * This is the bridge that makes bare `claude` / `codex` / `kimi` launches write
- * `~/.agents/.cache/terminals/sessions/<pid>.json`, not just `agents run` launches.
- */
 export async function installSessionTrackerHook(agent, version, home) {
     const gate = supports(agent, 'hooks', version);
     if (!gate.ok) {
@@ -3211,11 +2448,6 @@ export async function installSessionTrackerHook(agent, version, home) {
         return { installed: false, error: installFailureMessage(err) };
     }
 }
-/**
- * The child reports its refusal reason on stdout (its HOOK_SUPPORT table), not
- * stderr — and a Buffer-typed empty stderr is truthy, so a bare `err.stderr ??
- * err.message` surfaced an empty string. Prefer the first NON-EMPTY stream.
- */
 function installFailureMessage(err) {
     const e = err;
     for (const stream of [e.stderr, e.stdout]) {
@@ -3225,10 +2457,6 @@ function installFailureMessage(err) {
     }
     return e.message;
 }
-/**
- * Synchronous variant for callers that cannot be made async (e.g.
- * `syncResourcesToVersion`). Best-effort: failures are returned, not thrown.
- */
 export function installSessionTrackerHookSync(agent, version, home) {
     const gate = supports(agent, 'hooks', version);
     if (!gate.ok) {
@@ -3257,7 +2485,6 @@ export function installSessionTrackerHookSync(agent, version, home) {
         return { installed: false, error: installFailureMessage(err) };
     }
 }
-/** The hook installer must target this account, not the current global home. */
 function sessionTrackerInstallEnv(agent, version, home) {
     const target = home ?? (version ? getVersionHomePath(agent, version) : undefined);
     if (agent === 'codex' && target && version) {