@phnx-labs/agents-cli 1.20.51 → 1.20.53

package/dist/lib/hooks.js

@@ -994,6 +994,18 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'kimi') {
         return registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefixes);
     }
+    if (agentId === 'copilot') {
+        return registerHooksForCopilot(versionHome, manifest, resolveScript, managedPrefixes);
+    }
+    if (agentId === 'kiro') {
+        return registerHooksForKiro(versionHome, manifest, resolveScript, managedPrefixes);
+    }
+    if (agentId === 'goose') {
+        return registerHooksForGoose(versionHome, manifest, resolveScript, managedPrefixes);
+    }
+    if (agentId === 'cursor') {
+        return registerHooksForCursor(versionHome, manifest, resolveScript, managedPrefixes);
+    }
     return { registered: [], errors: [] };
 }
 /**
@@ -1028,9 +1040,11 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     const configDir = path.join(versionHome, configDirName);
     const settingsPath = path.join(configDir, 'settings.json');
     let config = {};
+    let existingRaw;
     if (fs.existsSync(settingsPath)) {
         try {
-            config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            existingRaw = fs.readFileSync(settingsPath, 'utf-8');
+            config = JSON.parse(existingRaw);
         }
         catch {
             errors.push('Failed to parse settings.json');
@@ -1111,7 +1125,10 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
     }
     try {
         fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
+        const nextRaw = JSON.stringify(config, null, 2);
+        if (existingRaw !== nextRaw) {
+            fs.writeFileSync(settingsPath, nextRaw, 'utf-8');
+        }
     }
     catch (err) {
         errors.push(`Failed to write settings.json: ${err.message}`);
@@ -1508,9 +1525,13 @@ function registerHooksForAntigravity(versionHome, manifest, resolveScript, manag
             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 };
+            if (hookDef.matcher)
+                entry.matcher = hookDef.matcher;
             if (existingIdx >= 0) {
                 list[existingIdx] = entry;
             }
@@ -1529,9 +1550,43 @@ 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 uses per-event JSON files under .grok/hooks/ (e.g. session-start.json).
+ *
+ * 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 = [];
@@ -1563,12 +1618,33 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
             if (!grokHooks.hooks[grokEvent]) {
                 grokHooks.hooks[grokEvent] = [];
             }
-            grokHooks.hooks[grokEvent].push({
-                hooks: [{ type: 'command', command: commandPath, timeout }],
-            });
+            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: [] };
+                groups.push(group);
+            }
+            const hookEntry = { type: 'command', command: commandPath, timeout };
+            const existingIdx = group.hooks.findIndex((h) => h.command === commandPath);
+            if (existingIdx >= 0) {
+                group.hooks[existingIdx] = hookEntry;
+            }
+            else {
+                group.hooks.push(hookEntry);
+            }
             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));
@@ -1576,18 +1652,66 @@ function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefi
     catch (e) {
         errors.push(`Failed to write hooks.json: ${e.message}`);
     }
-    for (const [eventName, groups] of Object.entries(grokHooks.hooks)) {
-        const fileName = eventName.toLowerCase().replace(/([a-z])([A-Z])/g, '$1-$2') + '.json';
-        const eventFile = path.join(grokHooksDir, fileName);
-        try {
-            fs.writeFileSync(eventFile, JSON.stringify({ hooks: { [eventName]: groups } }, null, 2));
-        }
-        catch (e) {
-            errors.push(`Failed to write ${fileName}: ${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')
+                continue;
+            const filePath = path.join(grokHooksDir, file);
+            if (isManagedGrokHookFile(filePath, managedPrefixes)) {
+                fs.rmSync(filePath, { force: true });
+            }
         }
     }
+    catch (e) {
+        errors.push(`Failed to prune stale grok hook files: ${e.message}`);
+    }
     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 {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return false;
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return false;
+    const commands = [];
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            return false;
+        for (const group of groups) {
+            const entries = group.hooks;
+            if (!Array.isArray(entries))
+                return false;
+            for (const entry of entries) {
+                const cmd = entry.command;
+                if (typeof cmd !== 'string')
+                    return false;
+                commands.push(cmd);
+            }
+        }
+    }
+    if (commands.length === 0)
+        return false;
+    return commands.every((cmd) => isManagedHookCommand(cmd, managedPrefixes));
+}
 function registerHooksForKimi(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
@@ -1671,3 +1795,394 @@ 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',
+    UserPromptSubmit: 'userPromptSubmitted',
+    PreToolUse: 'preToolUse',
+    PostToolUse: 'postToolUse',
+    PostToolUseFailure: 'postToolUseFailure',
+    Stop: 'agentStop',
+    SubagentStart: 'subagentStart',
+    SubagentStop: 'subagentStop',
+    OnError: 'errorOccurred',
+    PreCompact: 'preCompact',
+    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',
+    'permissionRequest',
+    'preCompact',
+    '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 = [];
+    const copilotHooksDir = path.join(versionHome, '.copilot', 'hooks');
+    fs.mkdirSync(copilotHooksDir, { recursive: true });
+    const hooks = {};
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
+            continue;
+        }
+        const timeoutSec = hookDef.timeout ?? 30;
+        for (const event of hookDef.events) {
+            const copilotEvent = COPILOT_EVENT_MAP[event];
+            if (!copilotEvent)
+                continue; // unmapped — skip silently
+            if (!hooks[copilotEvent])
+                hooks[copilotEvent] = [];
+            const entry = {
+                type: 'command',
+                command: commandPath,
+                timeoutSec,
+            };
+            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;
+            }
+            else {
+                hooks[copilotEvent].push(entry);
+            }
+            registered.push(`${name} -> ${copilotEvent}`);
+        }
+    }
+    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) {
+        errors.push(`Failed to write ${COPILOT_MANAGED_HOOKS_FILE}: ${err.message}`);
+    }
+    return { registered, errors };
+}
+/**
+ * Canonical hooks.yaml event names → Kiro v3 trigger names.
+ * Kiro v3 uses PascalCase triggers under `.kiro/hooks/*.json`
+ * (https://kiro.dev/docs/cli/v3/hooks/). Unmapped events are skipped.
+ */
+const KIRO_EVENT_MAP = {
+    SessionStart: 'SessionStart',
+    Stop: 'Stop',
+    PreToolUse: 'PreToolUse',
+    PostToolUse: 'PostToolUse',
+    UserPromptSubmit: 'UserPromptSubmit',
+};
+/**
+ * Kiro triggers that evaluate the `matcher` regex (tool name, file path, or
+ * prompt text depending on the trigger). Lifecycle SessionStart/Stop always fire.
+ */
+const KIRO_MATCHER_EVENTS = new Set([
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+]);
+/** Managed filename under ~/.kiro/hooks/ — we own this file entirely. */
+const KIRO_MANAGED_HOOKS_FILE = 'agents-cli-hooks.json';
+/**
+ * Register hooks for Kiro CLI (v3 standalone hooks format).
+ *
+ * Each file under `~/.kiro/hooks/*.json` is:
+ *   { "version": "v1", "hooks": [ { name, trigger, matcher?, action, timeout?, enabled? } ] }
+ *
+ * We rewrite a single managed file so GC is a rewrite and user-authored sibling
+ * JSON files are never touched. Embedded agent-config hooks (2.x) still work
+ * in Kiro but we only write the v3 path.
+ */
+function registerHooksForKiro(versionHome, manifest, resolveScript, _managedPrefixes) {
+    const registered = [];
+    const errors = [];
+    const kiroHooksDir = path.join(versionHome, '.kiro', 'hooks');
+    fs.mkdirSync(kiroHooksDir, { recursive: true });
+    const hooks = [];
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
+            continue;
+        }
+        const timeout = hookDef.timeout ?? 60;
+        for (const event of hookDef.events) {
+            const trigger = KIRO_EVENT_MAP[event];
+            if (!trigger)
+                continue;
+            const entry = {
+                name,
+                trigger,
+                action: { type: 'command', command: commandPath },
+                timeout,
+                enabled: true,
+            };
+            if (KIRO_MATCHER_EVENTS.has(trigger) && hookDef.matcher) {
+                entry.matcher = hookDef.matcher;
+            }
+            // De-dupe on (name, trigger, matcher)
+            const existingIdx = hooks.findIndex((h) => h.name === entry.name &&
+                h.trigger === entry.trigger &&
+                (h.matcher ?? '') === (entry.matcher ?? ''));
+            if (existingIdx >= 0) {
+                hooks[existingIdx] = entry;
+            }
+            else {
+                hooks.push(entry);
+            }
+            registered.push(`${name} -> ${trigger}`);
+        }
+    }
+    const outPath = path.join(kiroHooksDir, KIRO_MANAGED_HOOKS_FILE);
+    try {
+        fs.writeFileSync(outPath, JSON.stringify({ version: 'v1', hooks }, null, 2) + '\n', 'utf-8');
+    }
+    catch (err) {
+        errors.push(`Failed to write ${KIRO_MANAGED_HOOKS_FILE}: ${err.message}`);
+    }
+    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',
+    Stop: 'Stop',
+    UserPromptSubmit: 'UserPromptSubmit',
+    PreToolUse: 'PreToolUse',
+    PostToolUse: 'PostToolUse',
+    PostToolUseFailure: 'PostToolUseFailure',
+    BeforeReadFile: 'BeforeReadFile',
+    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 = [];
+    const eventHooks = {};
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
+            continue;
+        }
+        const timeout = hookDef.timeout ?? 60;
+        const cmd = { type: 'command', command: commandPath, timeout };
+        for (const event of hookDef.events) {
+            const gooseEvent = GOOSE_EVENT_MAP[event];
+            if (!gooseEvent)
+                continue;
+            if (!eventHooks[gooseEvent])
+                eventHooks[gooseEvent] = [];
+            const groups = eventHooks[gooseEvent];
+            const matcher = hookDef.matcher || undefined;
+            let group = groups.find((g) => (g.matcher || undefined) === matcher);
+            if (!group) {
+                group = { hooks: [] };
+                if (matcher)
+                    group.matcher = matcher;
+                groups.push(group);
+            }
+            const existingIdx = group.hooks.findIndex((h) => h.command === cmd.command);
+            if (existingIdx >= 0) {
+                group.hooks[existingIdx] = cmd;
+            }
+            else {
+                group.hooks.push(cmd);
+            }
+            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');
+        }
+        fs.writeFileSync(outPath, JSON.stringify({ hooks: eventHooks }, null, 2) + '\n', 'utf-8');
+    }
+    catch (err) {
+        errors.push(`Failed to write goose hooks plugin: ${err.message}`);
+    }
+    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',
+    Stop: 'stop',
+    UserPromptSubmit: 'beforeSubmitPrompt',
+    PreToolUse: 'preToolUse',
+    PostToolUse: 'postToolUse',
+    PostToolUseFailure: 'postToolUseFailure',
+    PreCompact: 'preCompact',
+    SubagentStart: 'subagentStart',
+    SubagentStop: 'subagentStop',
+    BeforeShellExecution: 'beforeShellExecution',
+    AfterShellExecution: 'afterShellExecution',
+    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 = [];
+    const configDir = path.join(versionHome, '.cursor');
+    const hooksPath = path.join(configDir, 'hooks.json');
+    let existing = { version: 1, hooks: {} };
+    if (fs.existsSync(hooksPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+            if (!existing.hooks || typeof existing.hooks !== 'object')
+                existing.hooks = {};
+        }
+        catch {
+            errors.push('Failed to parse existing hooks.json');
+            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)
+            continue;
+        const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
+        if (!resolved)
+            continue;
+        for (const event of hookDef.events) {
+            const cursorEvent = CURSOR_EVENT_MAP[event];
+            if (!cursorEvent)
+                continue;
+            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))
+            continue;
+        hooks[event] = entries.filter((e) => {
+            if (typeof e?.command !== 'string')
+                return true;
+            if (!isManagedHookCommand(e.command, managedPrefixes))
+                return true;
+            return desiredManaged.has(`${event}|${e.command}|${e.matcher ?? ''}`);
+        });
+        if (hooks[event].length === 0)
+            delete hooks[event];
+    }
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveHookCommand(name, hookDef, resolveScript);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
+            continue;
+        }
+        const timeout = hookDef.timeout ?? 30;
+        for (const event of hookDef.events) {
+            const cursorEvent = CURSOR_EVENT_MAP[event];
+            if (!cursorEvent)
+                continue;
+            if (!hooks[cursorEvent])
+                hooks[cursorEvent] = [];
+            const entry = { command: commandPath, timeout };
+            if (hookDef.matcher)
+                entry.matcher = hookDef.matcher;
+            const existingIdx = hooks[cursorEvent].findIndex((h) => h.command === entry.command && (h.matcher ?? '') === (entry.matcher ?? ''));
+            if (existingIdx >= 0) {
+                hooks[cursorEvent][existingIdx] = entry;
+            }
+            else {
+                hooks[cursorEvent].push(entry);
+            }
+            registered.push(`${name} -> ${cursorEvent}`);
+        }
+    }
+    try {
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(hooksPath, JSON.stringify({ version: 1, hooks }, null, 2) + '\n', 'utf-8');
+    }
+    catch (err) {
+        errors.push(`Failed to write hooks.json: ${err.message}`);
+    }
+    return { registered, errors };
+}

package/dist/lib/hosts/passthrough.d.ts

@@ -12,9 +12,9 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * `run` and `sessions` are deliberately absent from the table below: they own
- * richer `--host` handling in their own command actions (detached run dispatch;
- * multi-host session fan-out) and must fall through to it.
+ * `run`, `sessions`, and `feed` are deliberately absent from the table below:
+ * they own richer `--host` handling in their own command actions (detached run
+ * dispatch or multi-host fan-out) and must fall through to it.
  */
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
 export declare function flagValue(args: string[], long: string, short?: string): string | undefined;

package/dist/lib/hosts/passthrough.js

@@ -12,9 +12,9 @@
  * long-running case — `teams start --watch` — dispatches detached so the remote
  * supervisor outlives a dropped connection.
  *
- * `run` and `sessions` are deliberately absent from the table below: they own
- * richer `--host` handling in their own command actions (detached run dispatch;
- * multi-host session fan-out) and must fall through to it.
+ * `run`, `sessions`, and `feed` are deliberately absent from the table below:
+ * they own richer `--host` handling in their own command actions (detached run
+ * dispatch or multi-host fan-out) and must fall through to it.
  */
 import chalk from 'chalk';
 import { assertValidSshTarget, sshStream } from '../ssh-exec.js';

package/dist/lib/mailbox-gc.d.ts

@@ -0,0 +1,22 @@
+export interface GcResult {
+    boxesScanned: number;
+    deadBoxes: number;
+    messagesDroppedExpired: number;
+    messagesDroppedDead: number;
+    consumedPruned: number;
+    blocksRemoved: number;
+}
+export interface GcOptions {
+    root?: string;
+    /** Feed store root. Defaults to getFeedDir(). */
+    feedRoot?: string;
+    now?: Date;
+    /** Age in minutes after which consumed entries are pruned. Default 24h. */
+    maxConsumedAgeMinutes?: number;
+}
+/**
+ * Sweep all mailboxes. For dead boxes (not in `activeBoxIds`), archive every
+ * pending message as `dropped: dead` and remove any feed block tied to that
+ * mailbox. For live boxes, drop expired messages and prune old consumed files.
+ */
+export declare function gcMailbox(activeBoxIds: Set<string>, options?: GcOptions): GcResult;