@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/hooks/match.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hook predicate evaluator.
+ *
+ * Evaluates the optional `matches:` block on a hook manifest entry against
+ * the runtime input passed by the agent CLI on a hook event. All declared
+ * predicates AND together — the hook fires only if every one passes.
+ *
+ * Empty/missing matches => always passes (backward compat with hooks
+ * authored before predicate support).
+ *
+ * Used at hook-fire time by either:
+ *   (a) generated hook wrappers we install alongside the script, or
+ *   (b) the script itself, by calling shouldFire() with parsed JSON input.
+ */
+import type { HookMatches } from '../types.js';
+/** Runtime context passed to a hook by the agent CLI. */
+export interface HookInput {
+    hook_event_name?: string;
+    prompt?: string;
+    tool_name?: string;
+    tool_args?: unknown;
+    cwd?: string;
+}
+/**
+ * Decide whether a hook with the given match config should fire on this input.
+ * Pure function — no side effects, no IO except git/cwd checks for predicates
+ * that explicitly require them.
+ *
+ * Returns true if the hook should fire (all declared predicates pass), false
+ * if it should be skipped.
+ */
+export declare function shouldFire(matches: HookMatches | undefined, input: HookInput): boolean;

package/dist/lib/hooks/match.js

@@ -0,0 +1,120 @@
+/**
+ * Hook predicate evaluator.
+ *
+ * Evaluates the optional `matches:` block on a hook manifest entry against
+ * the runtime input passed by the agent CLI on a hook event. All declared
+ * predicates AND together — the hook fires only if every one passes.
+ *
+ * Empty/missing matches => always passes (backward compat with hooks
+ * authored before predicate support).
+ *
+ * Used at hook-fire time by either:
+ *   (a) generated hook wrappers we install alongside the script, or
+ *   (b) the script itself, by calling shouldFire() with parsed JSON input.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+function arrayOf(v) {
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+function isGitDirty(cwd) {
+    try {
+        const out = execSync('git status --porcelain', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+        });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function findProjectRoot(start) {
+    let dir = path.resolve(start);
+    while (true) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Decide whether a hook with the given match config should fire on this input.
+ * Pure function — no side effects, no IO except git/cwd checks for predicates
+ * that explicitly require them.
+ *
+ * Returns true if the hook should fire (all declared predicates pass), false
+ * if it should be skipped.
+ */
+export function shouldFire(matches, input) {
+    if (!matches)
+        return true;
+    const cwd = input.cwd || process.cwd();
+    if (matches.prompt_contains !== undefined) {
+        const prompt = input.prompt ?? '';
+        if (!prompt.includes(matches.prompt_contains))
+            return false;
+    }
+    if (matches.prompt_matches !== undefined) {
+        const prompt = input.prompt ?? '';
+        let re;
+        try {
+            re = new RegExp(matches.prompt_matches);
+        }
+        catch {
+            return false;
+        }
+        if (!re.test(prompt))
+            return false;
+    }
+    if (matches.tool_name !== undefined) {
+        const allowed = arrayOf(matches.tool_name);
+        if (allowed.length > 0) {
+            if (!input.tool_name)
+                return false;
+            if (!allowed.includes(input.tool_name))
+                return false;
+        }
+    }
+    if (matches.tool_args_match !== undefined) {
+        const serialized = typeof input.tool_args === 'string'
+            ? input.tool_args
+            : JSON.stringify(input.tool_args ?? '');
+        let re;
+        try {
+            re = new RegExp(matches.tool_args_match);
+        }
+        catch {
+            return false;
+        }
+        if (!re.test(serialized))
+            return false;
+    }
+    if (matches.cwd_includes !== undefined) {
+        const needles = arrayOf(matches.cwd_includes);
+        if (needles.length > 0) {
+            const hit = needles.some((n) => cwd.includes(n));
+            if (!hit)
+                return false;
+        }
+    }
+    if (matches.project_has !== undefined) {
+        const root = findProjectRoot(cwd);
+        if (!root)
+            return false;
+        if (!fs.existsSync(path.join(root, matches.project_has)))
+            return false;
+    }
+    if (matches.git_dirty !== undefined) {
+        const dirty = isGitDirty(cwd);
+        if (matches.git_dirty !== dirty)
+            return false;
+    }
+    return true;
+}

package/dist/lib/hooks.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 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 type { AgentId, InstalledHook, ManifestHook } from './types.js';
 export type HookEntry = {
     name: string;
@@ -93,12 +102,17 @@ export declare function installHooksCentrally(source: string): Promise<{
     errors: string[];
 }>;
 /**
- * List hooks from central ~/.agents/hooks/ directory.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralHooks(): HookEntry[];
 /**
- * Parse ~/.agents/hooks.yaml manifest.
- * Returns hook definitions with lifecycle event metadata.
+ * 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.
+ *
+ * Hooks marked `enabled: false` are dropped from the returned map.
  */
 export declare function parseHookManifest(): Record<string, ManifestHook>;
 /**
@@ -113,4 +127,3 @@ export declare function registerHooksToSettings(agentId: AgentId, versionHome: s
     registered: string[];
     errors: string[];
 };
-//# sourceMappingURL=hooks.d.ts.map

package/dist/lib/hooks.js

@@ -1,9 +1,21 @@
+/**
+ * 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 fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
 import { AGENTS, HOOKS_CAPABLE_AGENTS } from './agents.js';
-import { getAgentsDir, getHooksDir as getCentralHooksDir, getProjectAgentsDir } from './state.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';
+function getCentralHooksDir() { return getUserHooksDir(); }
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 const SCRIPT_EXTENSIONS = new Set([
     '.sh',
@@ -329,6 +341,10 @@ export function diffVersionHooks(agent, version) {
  * Install a single hook from central into a specific version home.
  */
 export function installHookToVersion(agent, version, hookName) {
+    const gate = supports(agent, 'hooks', version);
+    if (!gate.ok) {
+        return { success: false, error: explainSkip(agent, 'hooks', gate, version) };
+    }
     const central = listHookEntriesFromDir(getCentralHooksDir()).find((e) => e.name === hookName);
     if (!central) {
         return { success: false, error: `Hook '${hookName}' not found in central` };
@@ -464,28 +480,56 @@ export async function installHooksCentrally(source) {
     return { installed, errors };
 }
 /**
- * List hooks from central ~/.agents/hooks/ directory.
+ * List hooks from user (~/.agents/hooks/) and system (~/.agents-system/hooks/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralHooks() {
-    return listHookEntriesFromDir(getCentralHooksDir());
+    const seen = new Set();
+    const results = [];
+    for (const dir of [getUserHooksDir(), getSystemHooksDir()]) {
+        for (const entry of listHookEntriesFromDir(dir)) {
+            if (!seen.has(entry.name)) {
+                seen.add(entry.name);
+                results.push(entry);
+            }
+        }
+    }
+    return results;
 }
 /**
- * Parse ~/.agents/hooks.yaml manifest.
- * Returns hook definitions with lifecycle event metadata.
+ * 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.
+ *
+ * Hooks marked `enabled: false` are dropped from the returned map.
  */
 export function parseHookManifest() {
-    const manifestPath = path.join(getAgentsDir(), 'hooks.yaml');
-    if (!fs.existsSync(manifestPath)) {
-        return {};
-    }
-    try {
-        const content = fs.readFileSync(manifestPath, 'utf-8');
-        const parsed = yaml.parse(content);
-        return parsed || {};
+    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;
+        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;
+            }
+        }
+        catch {
+            /* skip unreadable manifest, keep going */
+        }
     }
-    catch {
-        return {};
+    // Strip disabled hooks so they never reach the registrar.
+    for (const [name, def] of Object.entries(merged)) {
+        if (def.enabled === false)
+            delete merged[name];
     }
+    return merged;
 }
 // Codex events that support a matcher field (matches tool name or session type).
 // UserPromptSubmit and Stop never include a matcher.
@@ -549,8 +593,6 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
     const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
     const currentManifestPaths = new Set();
     for (const hookDef of Object.values(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('claude'))
-            continue;
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
@@ -573,8 +615,6 @@ function registerHooksForClaude(versionHome, manifest, agentsDir) {
         hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
     }
     for (const [name, hookDef] of Object.entries(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('claude'))
-            continue;
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
@@ -645,8 +685,6 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
     const managedHooksPrefix = path.join(agentsDir, 'hooks') + path.sep;
     const currentManifestPaths = new Set();
     for (const hookDef of Object.values(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('codex'))
-            continue;
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
@@ -663,8 +701,6 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
         hooksFile.hooks[event] = eventGroups.filter((g) => g.hooks && g.hooks.length > 0);
     }
     for (const [name, hookDef] of Object.entries(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('codex'))
-            continue;
         if (!hookDef.events || hookDef.events.length === 0)
             continue;
         const commandPath = path.join(agentsDir, 'hooks', hookDef.script);
@@ -746,92 +782,74 @@ function registerHooksForCodex(versionHome, manifest, agentsDir) {
 function registerHooksForGemini(versionHome, manifest, agentsDir) {
     const registered = [];
     const errors = [];
-    const configDir = path.join(versionHome, '.gemini');
-    const settingsPath = path.join(configDir, 'settings.json');
-    let config = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-        }
-        catch {
-            errors.push('Failed to parse gemini settings.json');
-            return { registered, errors };
-        }
-    }
-    if (!config.hooks || typeof config.hooks !== 'object') {
-        config.hooks = {};
-    }
-    const hooks = config.hooks;
-    // Build set of current manifest command paths for gemini 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.agents && !hookDef.agents.includes('gemini'))
-            continue;
-        if (!hookDef.events || hookDef.events.length === 0)
-            continue;
-        currentManifestPaths.add(path.join(agentsDir, 'hooks', hookDef.script));
-    }
-    // Remove stale entries
-    for (const eventEntries of Object.values(hooks)) {
-        if (!Array.isArray(eventEntries))
-            continue;
-        for (const group of eventEntries) {
-            if (!group.hooks)
-                continue;
-            group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
-        }
-    }
-    for (const [event, eventEntries] of Object.entries(hooks)) {
-        if (!Array.isArray(eventEntries))
-            continue;
-        hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
-    }
-    for (const [name, hookDef] of Object.entries(manifest)) {
-        if (hookDef.agents && !hookDef.agents.includes('gemini'))
-            continue;
-        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}`);
-            continue;
-        }
-        // Gemini timeouts are in milliseconds; manifest timeouts are seconds.
-        const timeoutMs = (hookDef.timeout || 600) * 1000;
-        for (const event of hookDef.events) {
-            const geminiEvent = GEMINI_EVENT_MAP[event] ?? event;
-            if (!hooks[geminiEvent]) {
-                hooks[geminiEvent] = [];
+    const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
+    try {
+        updateGeminiSettings(settingsPath, (config) => {
+            setGeminiAutoUpdateDisabled(config);
+            if (!config.hooks || typeof config.hooks !== 'object') {
+                config.hooks = {};
             }
-            const eventEntries = hooks[geminiEvent];
-            const matcher = hookDef.matcher || '';
-            let matcherGroup = eventEntries.find((e) => (e.matcher || '') === matcher);
-            if (!matcherGroup) {
-                matcherGroup = { matcher, hooks: [] };
-                eventEntries.push(matcherGroup);
+            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));
             }
-            if (!matcherGroup.hooks) {
-                matcherGroup.hooks = [];
+            for (const eventEntries of Object.values(hooks)) {
+                if (!Array.isArray(eventEntries))
+                    continue;
+                for (const group of eventEntries) {
+                    if (!group.hooks)
+                        continue;
+                    group.hooks = group.hooks.filter((h) => !h.command.startsWith(managedHooksPrefix) || currentManifestPaths.has(h.command));
+                }
             }
-            const existingIdx = matcherGroup.hooks.findIndex((h) => h.command === commandPath);
-            const hookEntry = { name, type: 'command', command: commandPath, timeout: timeoutMs };
-            if (existingIdx >= 0) {
-                matcherGroup.hooks[existingIdx] = hookEntry;
+            for (const [event, eventEntries] of Object.entries(hooks)) {
+                if (!Array.isArray(eventEntries))
+                    continue;
+                hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
             }
-            else {
-                matcherGroup.hooks.push(hookEntry);
+            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}`);
+                    continue;
+                }
+                const timeoutMs = (hookDef.timeout || 600) * 1000;
+                for (const event of hookDef.events) {
+                    const geminiEvent = GEMINI_EVENT_MAP[event] ?? event;
+                    if (!hooks[geminiEvent]) {
+                        hooks[geminiEvent] = [];
+                    }
+                    const eventEntries = hooks[geminiEvent];
+                    const matcher = hookDef.matcher || '';
+                    let matcherGroup = eventEntries.find((e) => (e.matcher || '') === matcher);
+                    if (!matcherGroup) {
+                        matcherGroup = { matcher, hooks: [] };
+                        eventEntries.push(matcherGroup);
+                    }
+                    if (!matcherGroup.hooks) {
+                        matcherGroup.hooks = [];
+                    }
+                    const existingIdx = matcherGroup.hooks.findIndex((h) => h.command === commandPath);
+                    const hookEntry = { name, type: 'command', command: commandPath, timeout: timeoutMs };
+                    if (existingIdx >= 0) {
+                        matcherGroup.hooks[existingIdx] = hookEntry;
+                    }
+                    else {
+                        matcherGroup.hooks.push(hookEntry);
+                    }
+                    registered.push(`${name} -> ${geminiEvent}`);
+                }
             }
-            registered.push(`${name} -> ${geminiEvent}`);
-        }
-    }
-    try {
-        fs.mkdirSync(configDir, { recursive: true });
-        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2), 'utf-8');
+        });
     }
     catch (err) {
         errors.push(`Failed to write gemini settings.json: ${err.message}`);
     }
     return { registered, errors };
 }
-//# sourceMappingURL=hooks.js.map

package/dist/lib/manifest.d.ts

@@ -1,8 +1,13 @@
 import type { Manifest } from './types.js';
+/** Canonical filename for the manifest in any agents repo or project root. */
 export declare const MANIFEST_FILENAME = "agents.yaml";
+/** Parse a YAML string into a typed Manifest object. */
 export declare function parseManifest(content: string): Manifest;
+/** Serialize a Manifest object to a YAML string with 2-space indentation. */
 export declare function serializeManifest(manifest: Manifest): string;
+/** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export declare function readManifest(repoPath: string): Manifest | null;
+/** Write a Manifest object to agents.yaml in the given directory. */
 export declare function writeManifest(repoPath: string, manifest: Manifest): void;
+/** Create a Manifest with sensible defaults for a fresh agents repo. */
 export declare function createDefaultManifest(): Manifest;
-//# sourceMappingURL=manifest.d.ts.map

package/dist/lib/manifest.js

@@ -1,26 +1,38 @@
+/**
+ * agents.yaml manifest reading, writing, and serialization.
+ *
+ * The manifest file (agents.yaml) is the central configuration for version defaults,
+ * repository overrides, dependencies, and MCP server declarations.
+ */
 import * as fs from 'fs';
-import * as path from 'path';
 import * as yaml from 'yaml';
+import { safeJoin } from './paths.js';
+/** Canonical filename for the manifest in any agents repo or project root. */
 export const MANIFEST_FILENAME = 'agents.yaml';
+/** Parse a YAML string into a typed Manifest object. */
 export function parseManifest(content) {
     return yaml.parse(content);
 }
+/** Serialize a Manifest object to a YAML string with 2-space indentation. */
 export function serializeManifest(manifest) {
     return yaml.stringify(manifest, { indent: 2 });
 }
+/** Read and parse agents.yaml from a directory. Returns null if the file does not exist. */
 export function readManifest(repoPath) {
-    const manifestPath = path.join(repoPath, MANIFEST_FILENAME);
+    const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
     if (!fs.existsSync(manifestPath)) {
         return null;
     }
     const content = fs.readFileSync(manifestPath, 'utf-8');
     return parseManifest(content);
 }
+/** Write a Manifest object to agents.yaml in the given directory. */
 export function writeManifest(repoPath, manifest) {
-    const manifestPath = path.join(repoPath, MANIFEST_FILENAME);
+    const manifestPath = safeJoin(repoPath, MANIFEST_FILENAME);
     const content = serializeManifest(manifest);
     fs.writeFileSync(manifestPath, content, 'utf-8');
 }
+/** Create a Manifest with sensible defaults for a fresh agents repo. */
 export function createDefaultManifest() {
     return {
         agents: {},
@@ -33,4 +45,3 @@ export function createDefaultManifest() {
         },
     };
 }
-//# sourceMappingURL=manifest.js.map

package/dist/lib/markdown.d.ts

@@ -2,4 +2,3 @@
  * Render markdown content for terminal display.
  */
 export declare function renderMarkdown(content: string): string;
-//# sourceMappingURL=markdown.d.ts.map

package/dist/lib/markdown.js

@@ -1,3 +1,9 @@
+/**
+ * Terminal-aware Markdown rendering using marked and marked-terminal.
+ *
+ * Provides a single function for converting Markdown content into
+ * ANSI-formatted text suitable for terminal output.
+ */
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 // @ts-expect-error - marked-terminal types don't match marked's MarkedExtension
@@ -8,4 +14,3 @@ marked.use(markedTerminal());
 export function renderMarkdown(content) {
     return marked.parse(content);
 }
-//# sourceMappingURL=markdown.js.map

package/dist/lib/mcp.d.ts

@@ -61,4 +61,3 @@ export declare function writeMcpServerConfig(config: McpYamlConfig): string;
  * Remove an MCP server config from ~/.agents/mcp/.
  */
 export declare function removeMcpServerConfig(name: string): boolean;
-//# sourceMappingURL=mcp.d.ts.map