@phnx-labs/agents-cli 1.15.0 → 1.16.0

package/dist/lib/browser/types.d.ts

@@ -16,12 +16,17 @@ export interface BrowserProfile {
 export interface ChromeOptions {
     headless?: boolean;
     args?: string[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 export interface Task {
     id: string;
+    name: string;
     profile: string;
-    windowTargetId?: string;
-    tabIds: string[];
+    tabs: Record<string, string>;
+    currentTabId?: string;
     createdAt: number;
     pid: number;
 }
@@ -36,17 +41,39 @@ export interface ProfileStatus {
     running: boolean;
     port?: number;
     pid?: number;
+    /** The port declared in the profile's first endpoint, when it differs from the running port. */
+    configuredPort?: number;
     tasks: TaskStatus[];
 }
 export interface TaskStatus {
     id: string;
+    name: string;
     tabCount: number;
+    currentTabId?: string;
     createdAt: number;
+    endedAt?: number;
+    domains?: string[];
+    tabs?: Array<{
+        id: string;
+        url: string;
+        title?: string;
+        current?: boolean;
+    }>;
 }
-export type IPCAction = 'start' | 'stop' | 'status' | 'navigate' | 'tabs' | 'close' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover';
+export interface HistoricalTask {
+    id: string;
+    name: string;
+    profile: string;
+    createdAt: number;
+    endedAt: number;
+    domains: string[];
+    tabCount: number;
+}
+export type IPCAction = 'start' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
+    taskName?: string;
     profile?: string;
     url?: string;
     tabId?: string;
@@ -57,6 +84,20 @@ export interface IPCRequest {
     key?: string;
     interactive?: boolean;
     limit?: number;
+    width?: number;
+    height?: number;
+    deviceName?: string;
+    mobile?: boolean;
+    deviceScaleFactor?: number;
+    level?: 'log' | 'info' | 'warn' | 'error';
+    clear?: boolean;
+    filter?: string;
+    urlPattern?: string;
+    maxChars?: number;
+    waitType?: 'time' | 'selector' | 'url' | 'function' | 'load';
+    waitValue?: string | number;
+    timeout?: number;
+    downloadPath?: string;
 }
 export interface IPCResponse {
     ok: boolean;
@@ -66,10 +107,47 @@ export interface IPCResponse {
     windowTargetId?: string;
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];
+    history?: HistoricalTask[];
     result?: unknown;
     path?: string;
     refs?: string;
+    logs?: ConsoleEntry[];
+    errors?: ErrorEntry[];
+    requests?: NetworkRequest[];
+    body?: string;
+    downloadPath?: string;
+    devices?: string[];
+}
+export interface ConsoleEntry {
+    level: 'log' | 'info' | 'warn' | 'error';
+    text: string;
+    timestamp: number;
+    url?: string;
+    line?: number;
+}
+export interface ErrorEntry {
+    message: string;
+    stack?: string;
+    timestamp: number;
+    url?: string;
+    line?: number;
+}
+export interface NetworkRequest {
+    id: string;
+    url: string;
+    method: string;
+    status?: number;
+    mimeType?: string;
+    timestamp: number;
+}
+export interface DeviceDescriptor {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    mobile: boolean;
 }
 export declare const TASK_ID_REGEX: RegExp;
 export declare function isValidTaskId(id: string): boolean;
 export declare function generateTaskId(): string;
+export declare function generateShortId(): string;
+export declare function generateFunName(): string;

package/dist/lib/browser/types.js

@@ -5,3 +5,19 @@ export function isValidTaskId(id) {
 export function generateTaskId() {
     return crypto.randomUUID().slice(0, 8);
 }
+export function generateShortId() {
+    return crypto.randomUUID().split('-')[0]; // 8 chars
+}
+const ADJECTIVES = [
+    'swift', 'cosmic', 'jolly', 'quiet', 'bold', 'bright', 'calm', 'eager',
+    'golden', 'happy', 'keen', 'lucky', 'noble', 'proud', 'quick', 'royal',
+];
+const NOUNS = [
+    'falcon', 'comet', 'tiger', 'nebula', 'phoenix', 'river', 'summit', 'wave',
+    'aurora', 'breeze', 'crystal', 'dragon', 'ember', 'forest', 'glacier', 'harbor',
+];
+export function generateFunName() {
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    return `${adj}-${noun}`;
+}

package/dist/lib/cloud/rush.js

@@ -9,7 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import * as yaml from 'yaml';
-import { getUserAgentsDir } from '../state.js';
+import { getCloudDir } from '../state.js';
 import { resolveDispatchRepos } from './types.js';
 import { parseSSE } from './stream.js';
 import { listInstalledVersions, getVersionHomePath } from '../versions.js';
@@ -20,7 +20,7 @@ const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
 // Created on first explicit consent (env var or flag); subsequent dispatches
 // see it and proceed without re-prompting.
-const RUSH_CONSENT_PATH = path.join(getUserAgentsDir(), 'cloud', 'rush-consent.json');
+const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
 function hasRushUploadConsent(opts) {
     if (process.env[RUSH_CONSENT_ENV] === '1')

package/dist/lib/cloud/store.js

@@ -8,8 +8,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getUserAgentsDir } from '../state.js';
-const CLOUD_DIR = path.join(getUserAgentsDir(), 'cloud');
+import { getCloudDir } from '../state.js';
+const CLOUD_DIR = getCloudDir();
 const DB_PATH = path.join(CLOUD_DIR, 'tasks.db');
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS tasks (

package/dist/lib/commands.d.ts

@@ -79,6 +79,7 @@ export declare function installCommandToVersion(agent: AgentId, version: string,
 };
 /**
  * Remove a single command from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/commands/.
  */
 export declare function removeCommandFromVersion(agent: AgentId, version: string, commandName: string): {
     success: boolean;

package/dist/lib/commands.js

@@ -11,7 +11,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { AGENTS, COMMANDS_CAPABLE_AGENTS, ensureCommandsDir } from './agents.js';
 import { markdownToToml } from './convert.js';
-import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir } from './state.js';
+import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
 /** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
@@ -279,6 +279,7 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
 }
 /**
  * Remove a single command from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/commands/.
  */
 export function removeCommandFromVersion(agent, version, commandName) {
     const versionHome = getVersionHomePath(agent, version);
@@ -292,7 +293,10 @@ export function removeCommandFromVersion(agent, version, commandName) {
         return { success: true };
     }
     try {
-        fs.unlinkSync(targetPath);
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const trashDir = path.join(getTrashCommandsDir(), agent, version, commandName);
+        fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+        fs.renameSync(targetPath, path.join(trashDir, `${commandName}${ext}.${stamp}`));
     }
     catch (err) {
         return { success: false, error: err.message };

package/dist/lib/daemon.js

@@ -10,13 +10,12 @@ import { spawn, execSync, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { getAgentsDir } from './state.js';
+import { getDaemonDir as getDaemonDirRoot } from './state.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
-const DAEMON_DIR = 'helpers/daemon';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -25,7 +24,7 @@ const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
 function getDaemonDir() {
-    const dir = path.join(getAgentsDir(), DAEMON_DIR);
+    const dir = getDaemonDirRoot();
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }

package/dist/lib/doctor-diff.js

@@ -22,7 +22,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS } from './agents.js';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getPromptcutsPath, } from './state.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, } from './versions.js';
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
@@ -426,10 +426,10 @@ function diffPresenceOnly(kind, available, synced) {
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 function diffPromptcuts() {
-    const exists = fs.existsSync(getPromptcutsPath());
-    if (!exists)
+    const sourcePath = getEffectivePromptcutsPath();
+    if (!fs.existsSync(sourcePath))
         return [];
-    return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath: getPromptcutsPath() }];
+    return [{ kind: 'promptcuts', name: 'promptcuts.yaml', status: 'ok', sourcePath }];
 }
 export function diffVersionResources(agent, version, options = {}) {
     const cwd = options.cwd ?? process.cwd();

package/dist/lib/events.js

@@ -15,8 +15,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 // ─── Constants ────────────────────────────────────────────────────────────────
-const USER_AGENTS_DIR = path.join(os.homedir(), '.agents');
-const LOGS_DIR = path.join(USER_AGENTS_DIR, 'logs');
+// Logs live under the cache bucket — they're regenerable telemetry.
+const LOGS_DIR = path.join(os.homedir(), '.agents', '.cache', 'logs');
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 30;
 /** Default max length for truncated strings. */

package/dist/lib/hooks.d.ts

@@ -66,6 +66,7 @@ export declare function installHookToVersion(agent: AgentId, version: string, ho
 };
 /**
  * Remove a single hook (script + data file) from a specific version home.
+ * Soft-deletes to ~/.agents/.trash/hooks/.
  */
 export declare function removeHookFromVersion(agent: AgentId, version: string, hookName: string): {
     success: boolean;
@@ -113,10 +114,11 @@ export declare function installHooksCentrally(source: string): Promise<{
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * 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.
  */
@@ -124,10 +126,12 @@ export declare function parseHookManifest(): Record<string, ManifestHook>;
 /**
  * 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 declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];

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 } from './state.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
+/**
+ * Resolve a hook script's absolute path by checking the user dir first
+ * (where `installHooksCentrally` lands new files) and falling back to the
+ * system dir (where npm-shipped defaults live). Returns null if neither
+ * exists. Mirrors the precedence used by `listCentralHooks`.
+ */
+function resolveHookScriptPath(script) {
+    for (const root of [getUserAgentsDir(), 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 by us" if it lives under either
+ * `~/.agents/hooks/` (user) or `~/.agents-system/hooks/` (system). Cleanup
+ * filters use this list so leftover entries from either dir get garbage
+ * collected on rewrite.
+ */
+function getManagedHookPrefixes() {
+    return [
+        path.join(getUserAgentsDir(), '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,37 @@ 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;
+    const resolveScript = (script) => {
+        if (overrideRoots) {
+            const candidate = path.join(overrideRoots[0], 'hooks', script);
+            return fs.existsSync(candidate) ? candidate : null;
+        }
+        return resolveHookScriptPath(script);
+    };
+    const managedPrefixes = overrideRoots
+        ? [path.join(overrideRoots[0], 'hooks') + path.sep]
+        : getManagedHookPrefixes();
     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 +647,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 +668,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 +684,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 +696,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 +736,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 +761,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 +783,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 +859,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 +870,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 +884,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 +895,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>;