@phnx-labs/agents-cli 1.15.0 → 1.17.0

package/dist/lib/hooks.js

@@ -14,8 +14,42 @@ import * as TOML from 'smol-toml';
 import { AGENTS, HOOKS_CAPABLE_AGENTS } from './agents.js';
 import { supports, explainSkip } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getAgentsDir, getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getProjectAgentsDir } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos } from './state.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 resolveHookScriptPath(script) {
+    const extraDirs = getEnabledExtraRepos().map(e => e.dir);
+    for (const root of [getUserAgentsDir(), ...extraDirs, getSystemAgentsDir()]) {
+        const candidate = path.join(root, 'hooks', script);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    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,
+    ];
+}
+function isManagedHookCommand(command, prefixes) {
+    for (const prefix of prefixes) {
+        if (command.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 const SCRIPT_EXTENSIONS = new Set([
     '.sh',
@@ -366,10 +400,32 @@ export function installHookToVersion(agent, version, hookName) {
 }
 /**
  * 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 {
-        removeHookFiles(getVersionHooksDir(agent, version), hookName);
+        const hooksDir = getVersionHooksDir(agent, version);
+        if (!fs.existsSync(hooksDir))
+            return { success: true };
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const trashDir = path.join(getTrashHooksDir(), agent, version, hookName, stamp);
+        let moved = false;
+        const files = fs.readdirSync(hooksDir);
+        for (const file of files) {
+            const ext = path.extname(file);
+            const base = path.basename(file, ext);
+            if (base === hookName) {
+                const fullPath = path.join(hooksDir, file);
+                const stat = fs.statSync(fullPath);
+                if (stat.isFile()) {
+                    if (!moved) {
+                        fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+                        moved = true;
+                    }
+                    fs.renameSync(fullPath, path.join(trashDir, file));
+                }
+            }
+        }
     }
     catch (err) {
         return { success: false, error: err.message };
@@ -502,32 +558,37 @@ export function listCentralHooks() {
     return results;
 }
 /**
- * Parse hooks.yaml manifests. Reads BOTH system (~/.agents-system/hooks.yaml)
- * and user (~/.agents/hooks.yaml), merging 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.
+ * 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.
  */
 export function parseHookManifest() {
     const merged = {};
-    // System first (lower precedence), user second (overrides).
-    for (const dir of [getAgentsDir(), getUserAgentsDir()]) {
-        const manifestPath = path.join(dir, 'hooks.yaml');
-        if (!fs.existsSync(manifestPath))
-            continue;
+    // System layer: hooks: section of agents.yaml (npm-shipped, separate repo).
+    const systemPath = path.join(getSystemAgentsDir(), 'agents.yaml');
+    if (fs.existsSync(systemPath)) {
         try {
-            const content = fs.readFileSync(manifestPath, 'utf-8');
-            const parsed = yaml.parse(content);
-            if (!parsed)
-                continue;
-            for (const [name, def] of Object.entries(parsed)) {
-                merged[name] = def;
-            }
+            const meta = yaml.parse(fs.readFileSync(systemPath, 'utf-8'));
+            if (meta?.hooks)
+                for (const [name, def] of Object.entries(meta.hooks))
+                    merged[name] = def;
         }
-        catch {
-            /* skip unreadable manifest, keep going */
+        catch { /* skip unreadable manifest */ }
+    }
+    // User layer: hooks: section of agents.yaml.
+    const userMetaPath = path.join(getUserAgentsDir(), 'agents.yaml');
+    if (fs.existsSync(userMetaPath)) {
+        try {
+            const meta = yaml.parse(fs.readFileSync(userMetaPath, 'utf-8'));
+            if (meta?.hooks)
+                for (const [name, def] of Object.entries(meta.hooks))
+                    merged[name] = def;
         }
+        catch { /* skip unreadable meta */ }
     }
     // Strip disabled hooks so they never reach the registrar.
     for (const [name, def] of Object.entries(merged)) {
@@ -542,25 +603,50 @@ const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart
 /**
  * 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/.
- * Does not remove user-added hooks.
+ * Only manages hooks whose command paths are under ~/.agents/hooks/ or
+ * ~/.agents-system/hooks/. Does not remove user-added hooks.
  *
- * @param agentsDirOverride - Override the agents dir (used in tests to inject a temp path).
+ * @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.
  */
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
     const manifest = hookManifest || parseHookManifest();
     if (Object.keys(manifest).length === 0) {
         return { registered: [], errors: [] };
     }
-    const agentsDir = agentsDirOverride ?? getAgentsDir();
+    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
+        ? path.join(versionHome, `.${agentId}`, AGENTS[agentId].hooksDir)
+        : null;
+    const resolveScript = (script) => {
+        if (overrideRoots) {
+            const candidate = path.join(overrideRoots[0], 'hooks', script);
+            return fs.existsSync(candidate) ? candidate : null;
+        }
+        if (localHooksDir) {
+            const local = path.join(localHooksDir, script);
+            if (fs.existsSync(local))
+                return local;
+        }
+        return resolveHookScriptPath(script);
+    };
+    const managedPrefixes = overrideRoots
+        ? [path.join(overrideRoots[0], 'hooks') + path.sep]
+        : [
+            ...getManagedHookPrefixes(),
+            ...(localHooksDir ? [localHooksDir + path.sep] : []),
+        ];
     if (agentId === 'claude') {
-        return registerHooksForClaude(versionHome, manifest, agentsDir);
+        return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes);
     }
     if (agentId === 'codex') {
-        return registerHooksForCodex(versionHome, manifest, agentsDir);
+        return registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes);
     }
     if (agentId === 'gemini') {
-        return registerHooksForGemini(versionHome, manifest, agentsDir);
+        return registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes);
     }
     return { registered: [], errors: [] };
 }
@@ -574,7 +660,7 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
 const GEMINI_EVENT_MAP = {
     UserPromptSubmit: 'BeforeAgent',
 };
-function registerHooksForClaude(versionHome, manifest, agentsDir) {
+function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
     const configDir = path.join(versionHome, '.claude');
@@ -595,14 +681,15 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
     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.
-    const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
     const currentManifestPaths = new Set();
     for (const hookDef of Object.values(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
+        const resolved = resolveScript(hookDef.script);
+        if (resolved)
+            currentManifestPaths.add(resolved);
     }
-    // Remove stale entries: any hook command under ~/.agents/hooks/ that isn't
+    // 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.
     for (const eventEntries of Object.values(hooks)) {
         if (!Array.isArray(eventEntries))
@@ -610,7 +697,7 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
         for (const group of eventEntries) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+            group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
         }
     }
     // Remove empty matcher groups left after cleanup
@@ -622,9 +709,9 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
-        if (!fs.existsSync(commandPath)) {
-            errors.push(`${name}: script not found at ${commandPath}`);
+        const commandPath = resolveScript(hookDef.script);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
             continue;
         }
         for (const event of hookDef.events) {
@@ -662,7 +749,7 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
     }
     return { registered, errors };
 }
-function registerHooksForCodex(versionHome, manifest, agentsDir) {
+function registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
     const configDir = path.join(versionHome, '.codex');
@@ -687,19 +774,20 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
         }
     }
     // Build set of current manifest command paths for codex to GC stale entries
-    const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
     const currentManifestPaths = new Set();
     for (const hookDef of Object.values(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
+        const resolved = resolveScript(hookDef.script);
+        if (resolved)
+            currentManifestPaths.add(resolved);
     }
     // Remove stale entries from all event groups
     for (const eventGroups of Object.values(hooksFile.hooks)) {
         for (const group of eventGroups) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+            group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
         }
     }
     for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
@@ -708,9 +796,9 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
     for (const [name, hookDef] of Object.entries(manifest)) {
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
-        const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
-        if (!fs.existsSync(commandPath)) {
-            errors.push(`${name}: script not found at ${commandPath}`);
+        const commandPath = resolveScript(hookDef.script);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
             continue;
         }
         const timeout = hookDef.timeout || 600;
@@ -784,7 +872,7 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
     }
     return { registered, errors };
 }
-function registerHooksForGemini(versionHome, manifest, agentsDir) {
+function registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes) {
     const registered = [];
     const errors = [];
     const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
@@ -795,12 +883,13 @@ function registerHooksForGemini(versionHome, manifest, agentsDir) {
                 config.hooks = {};
             }
             const hooks = config.hooks;
-            const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
             const currentManifestPaths = new Set();
             for (const hookDef of Object.values(manifest)) {
                 if (!hookDef.events || hookDef.events.length === 0)
                     continue;
-                currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
+                const resolved = resolveScript(hookDef.script);
+                if (resolved)
+                    currentManifestPaths.add(resolved);
             }
             for (const eventEntries of Object.values(hooks)) {
                 if (!Array.isArray(eventEntries))
@@ -808,7 +897,7 @@ function registerHooksForGemini(versionHome, manifest, agentsDir) {
                 for (const group of eventEntries) {
                     if (!group.hooks)
                         continue;
-                    group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+                    group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
                 }
             }
             for (const [event, eventEntries] of Object.entries(hooks)) {
@@ -819,9 +908,9 @@ function registerHooksForGemini(versionHome, manifest, agentsDir) {
             for (const [name, hookDef] of Object.entries(manifest)) {
                 if (!hookDef.events || hookDef.events.length === 0)
                     continue;
-                const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
-                if (!fs.existsSync(commandPath)) {
-                    errors.push(`${name}: script not found at ${commandPath}`);
+                const commandPath = resolveScript(hookDef.script);
+                if (!commandPath) {
+                    errors.push(`${name}: script not found in user or system hooks dir`);
                     continue;
                 }
                 const timeoutMs = (hookDef.timeout || 600) * 1000;

package/dist/lib/migrate.d.ts

@@ -5,4 +5,4 @@
  * Each migration is guarded by an existence check so re-running is safe.
  */
 /** Run all idempotent migrations. Safe to call multiple times. */
-export declare function runMigration(): void;
+export declare function runMigration(): Promise<void>;