@phnx-labs/agents-cli 1.20.13 → 1.20.14

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+**`agents inspect` summary: expanded detail for hooks, plugins, and MCP**
+
+- The bare `agents inspect <agent>` / `agents inspect <repo>` summary no longer collapses everything to a count table. Simple kinds (commands, skills, rules, subagents, workflows) keep a count line but now preview a few names; the rich kinds get their own expanded sections: **hooks** show their events + `matches:` predicates + cache (`PreToolUse(Bash) · git_dirty · prompt~"deploy" (5m cache)`), **plugins** show version + bundle contents (`v2.1.0  skills:6 commands:5 hooks:2 mcp:1`), and **MCP** show transport + url/command. Drill-down flags (`--hooks`, `--plugins`, `--mcp`) and `--brief` are unchanged; `--json` gains the structured detail additively (existing keys retained).
+- Hook detail joins installed hooks to the manifest by **script basename** (installed hooks are named after their script file while the manifest keys on the logical name), and the repo Hooks section uses the grouped hook reader so a script + its data file collapse to one clean entry.
+
+**Plugin hooks were misreported — fixed**
+
+- `discoverPluginHooks` read the **top-level** keys of a plugin's `hooks/hooks.json`, so the official `{ description, hooks: { SessionStart: [...] } }` format surfaced as `description, hooks` instead of the real events. It now reads the `hooks` wrapper when present (falling back to top-level keys for the flat format), so `agents inspect --plugin <name>` and the plugin row show the actual lifecycle events (e.g. `SessionStart, PreToolUse, …`).
+
+**`agents doctor` / `agents prune`: precise orphan-hooks detection**
+
+- Orphan-hook detection now flags hook scripts present in a version home that **no `agents.yaml`/`hooks.yaml` entry registers** — i.e. scripts that sync to disk but are never wired to a lifecycle event, so they never fire. This replaces the source-diff heuristic, which compared only against the user hooks dir and so **false-flagged valid system-sourced, registered hooks** (e.g. `03-linear-inject`, `04-capture`) as orphans — meaning `agents prune cleanup` could have deleted live hooks. Doctor's Orphans section and `prune cleanup hooks` now share this single manifest-based definition. `parseHookManifest` gained a silent (`{ warn: false }`) option so the diagnostic doesn't emit shadow/override warnings.
+
+**Regression coverage: resource sync from extras repos**
+
+- Added end-to-end regression tests (`src/lib/__tests__/extras-sync.test.ts`) locking in two behaviors for repos registered via `agents repo add` (`~/.agents-<alias>/`): a top-level `commands/<name>.md` is written into the agent's version home on `agents sync`, and plugins under `plugins/<name>/` are synthesized into a registered `agents-<alias>` marketplace on launch. Both already work in `main`; the tests exercise the real sync path (no mocking, isolated `$HOME`) so the extras-repo behavior can't silently regress (#313, #314).
+
 **Windows: `agents` is discoverable right after `npm i -g`**
 
 - On a global Windows install, postinstall now prepends npm's global-bin dir (where `agents.cmd`/`agents.ps1` live) to the **User PATH** via the .NET environment API. Node's installer normally adds it, but winget / portable / nvm-windows setups often don't — and then `npm i -g @phnx-labs/agents-cli` succeeds yet `agents` is "not recognized". The shims dir (claude/codex/…) is still left to `agents setup`, which the user can now run because `agents` resolves.

package/dist/commands/doctor.js

@@ -5,9 +5,10 @@ import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalled
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
-import { diffVersionHooks, iterHooksCapableVersions } from '../lib/hooks.js';
+import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from '../lib/hooks.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
+import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
@@ -53,16 +54,20 @@ function countOrphans() {
         if (diff.orphans.length > 0)
             ensure(agent, version).skills = diff.orphans.length;
     }
+    // Orphan hooks are scripts in the version home that no agents.yaml/hooks.yaml
+    // entry registers — so the registrar never wires them to an event and they
+    // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
+    // which false-flags valid system-sourced registered hooks.)
     for (const { agent, version } of iterHooksCapableVersions()) {
         if (version !== getGlobalDefault(agent))
             continue;
-        const diff = diffVersionHooks(agent, version);
-        if (diff.orphans.length > 0)
-            ensure(agent, version).hooks = diff.orphans.length;
+        const dead = listUnmanagedHooksInVersionHome(agent, version);
+        if (dead.length > 0)
+            ensure(agent, version).hooks = dead.length;
     }
     return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
 }
-function renderOverviewText(clis, syncRows, orphanRows) {
+function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     console.log(chalk.bold('Agent CLIs'));
     if (Object.keys(clis).length === 0) {
         console.log(chalk.gray('  (no agents reported)'));
@@ -116,6 +121,31 @@ function renderOverviewText(clis, syncRows, orphanRows) {
         }
         console.log(chalk.gray('  Run `agents prune cleanup` to remove.'));
     }
+    console.log();
+    // Host CLIs are host-global (declared in any DotAgents repo's cli/, installed
+    // to PATH — not synced into version homes), so they live in the overview, not
+    // the per-version resource diff. Source tag shows which repo layer declared
+    // each, including user-level and extra repos.
+    console.log(chalk.bold('Host CLIs'));
+    if (hostClis.statuses.length === 0) {
+        console.log(chalk.gray('  (none declared — add one with `agents cli add <name>`)'));
+    }
+    else {
+        const nameWidth = Math.max(...hostClis.statuses.map((s) => s.manifest.name.length));
+        for (const { manifest, installed } of hostClis.statuses) {
+            const label = manifest.name.padEnd(nameWidth);
+            const src = chalk.gray(`[${manifest.source}]`);
+            if (installed) {
+                console.log(`  ${chalk.green('ready')}  ${label}  ${src}  ${chalk.gray(manifest.description || '')}`);
+            }
+            else {
+                console.log(`  ${chalk.red('miss ')}  ${label}  ${src}  ${chalk.gray(`not installed — run \`agents cli install ${manifest.name}\``)}`);
+            }
+        }
+    }
+    for (const err of hostClis.errors) {
+        console.log(`  ${chalk.red('err  ')}  ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
+    }
 }
 function parseTargetArg(arg) {
     const at = arg.indexOf('@');
@@ -346,11 +376,25 @@ export function registerDoctorCommand(program) {
             const clis = checkAllClis();
             const syncRows = checkSyncStatus(cwd);
             const orphanRows = countOrphans();
+            const hostClis = listCliStatus(cwd);
             if (opts.json) {
-                console.log(JSON.stringify({ clis, sync: syncRows, orphans: orphanRows }, null, 2));
+                console.log(JSON.stringify({
+                    clis,
+                    sync: syncRows,
+                    orphans: orphanRows,
+                    hostClis: {
+                        statuses: hostClis.statuses.map((s) => ({
+                            name: s.manifest.name,
+                            source: s.manifest.source,
+                            description: s.manifest.description ?? null,
+                            installed: s.installed,
+                        })),
+                        errors: hostClis.errors,
+                    },
+                }, null, 2));
                 return;
             }
-            renderOverviewText(clis, syncRows, orphanRows);
+            renderOverviewText(clis, syncRows, orphanRows, hostClis);
             return;
         }
         const parsed = parseTargetArg(target);

package/dist/commands/inspect.d.ts

@@ -12,6 +12,8 @@
  * AGENT.md / the file itself) so users can click straight to the source.
  */
 import { Command } from 'commander';
+import type { ManifestHook } from '../lib/types.js';
+import { type McpYamlConfig } from '../lib/mcp.js';
 import { type PluginResourceGroup } from '../lib/plugins.js';
 /** Resource kinds the inspect command can drill into. */
 declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents"];
@@ -101,4 +103,19 @@ export interface RepoGitInfo {
     behind: number | null;
 }
 export declare function repoGitInfo(root: string): RepoGitInfo | null;
+/**
+ * Compact one-liner for a hook from its manifest entry: the firing events (with
+ * the matcher/tool-name in parens), then a `·`-separated predicate summary, then
+ * an optional cache tail. Plain text — the caller applies color.
+ */
+export declare function summarizeHook(hook: ManifestHook): string;
+/** Compact one-liner for an MCP server: padded transport + the url (http) or command line (stdio). */
+export declare function summarizeMcp(cfg: McpYamlConfig): string;
+/**
+ * Index a hook manifest by script basename (no extension). Installed hooks are
+ * named after their script file (`04-capture-…`), while the manifest is keyed by
+ * logical name (`capture-…`) with the filename in `script:` — so we join on the
+ * script basename, not the manifest key.
+ */
+export declare function hookManifestByScript(manifest: Record<string, ManifestHook>): Map<string, ManifestHook>;
 export {};

package/dist/commands/inspect.js

@@ -23,6 +23,8 @@ import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, ge
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
+import { listHookEntriesFromDir } from '../lib/hooks.js';
+import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js';
 import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
@@ -38,6 +40,14 @@ const DRILLABLE_KINDS = [
     'workflows',
     'subagents',
 ];
+/**
+ * Summary-view partition. SIMPLE kinds render as a one-line count + name preview;
+ * RICH kinds (hooks/plugins/mcp) get their own expanded section showing each
+ * item's key detail (events/predicates, bundle contents, transport/url). Together
+ * they cover every DrillableKind.
+ */
+const SIMPLE_KINDS = ['commands', 'skills', 'rules', 'subagents', 'workflows'];
+const RICH_KINDS = ['hooks', 'plugins', 'mcp'];
 /**
  * Singular aliases for the plural drill-down flags. `--plugin code` reads as
  * "show the one plugin named code" — a required-value flag that always lands in
@@ -355,6 +365,9 @@ function renderRepoSummary(repo, options) {
     const manifest = repoManifestSummary(repo.root);
     const kindData = {};
     let totalBytes = 0, totalFiles = 0;
+    let repoHookByScript = new Map();
+    let repoHookItemList = [];
+    let repoMcpConfigs = new Map();
     if (!options.brief) {
         for (const kind of DRILLABLE_KINDS) {
             const items = collectRepoKind(repo, kind);
@@ -363,6 +376,9 @@ function renderRepoSummary(repo, options) {
             totalBytes += size.bytes;
             totalFiles += size.files;
         }
+        repoHookByScript = hookManifestByScript(hookManifestFromFile(path.join(repo.root, 'agents.yaml')));
+        repoHookItemList = repoHookItems(repo);
+        repoMcpConfigs = new Map(discoverMcpConfigsFromRepo(repo.root).map(s => [s.name, s.config]));
     }
     if (options.json) {
         console.log(JSON.stringify({
@@ -372,12 +388,34 @@ function renderRepoSummary(repo, options) {
             manifests,
             manifest,
             size: options.brief ? null : { bytes: totalBytes, files: totalFiles },
-            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => [kind, {
-                    count: kindData[kind].items.length,
-                    bytes: kindData[kind].size.bytes,
-                    files: kindData[kind].size.files,
-                    names: kindData[kind].items.map(i => i.name),
-                }])),
+            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => {
+                const size = kindData[kind].size;
+                // Hooks use the grouped reader (clean names) instead of the raw readdir.
+                const items = kind === 'hooks' ? repoHookItemList : kindData[kind].items;
+                const base = {
+                    count: items.length,
+                    bytes: size.bytes,
+                    files: size.files,
+                    names: items.map(i => i.name),
+                };
+                if (kind === 'hooks')
+                    return [kind, { ...base, items: items.map(i => {
+                                const h = repoHookByScript.get(i.name);
+                                return { name: i.name, events: h?.events ?? [], matcher: h?.matcher, matches: h?.matches, cache: h?.cache };
+                            }) }];
+                if (kind === 'mcp')
+                    return [kind, { ...base, items: items.map(i => {
+                                const c = repoMcpConfigs.get(i.name);
+                                return { name: i.name, transport: c?.transport, url: c?.url, command: c?.command, args: c?.args };
+                            }) }];
+                if (kind === 'plugins')
+                    return [kind, { ...base, items: items.map(i => ({
+                                name: i.name,
+                                version: i.extra?.find(([k]) => k === 'version')?.[1],
+                                groups: Object.fromEntries((i.groups ?? []).map(g => [g.label, g.items.length])),
+                            })) }];
+                return [kind, base];
+            })),
         }, null, 2));
         return;
     }
@@ -416,13 +454,16 @@ function renderRepoSummary(repo, options) {
     if (!options.brief) {
         console.log(`  ${'size'.padEnd(10)} ${formatBytes(totalBytes)} ${chalk.gray('·')} ${totalFiles} files`);
         console.log('\n' + chalk.bold('Resources'));
-        for (const kind of DRILLABLE_KINDS) {
+        for (const kind of SIMPLE_KINDS) {
             const { items, size } = kindData[kind];
             const count = String(items.length).padStart(4);
             const sz = items.length > 0 ? formatBytes(size.bytes).padStart(8) : ''.padEnd(8);
             const preview = items.length > 0 ? chalk.gray(truncate(previewNames(items, 4), 60)) : '';
             console.log(`  ${kind.padEnd(10)} ${count}  ${sz}  ${preview}`.trimEnd());
         }
+        printExpandedSection('Hooks', hookRows(repoHookItemList, repoHookByScript));
+        printExpandedSection('Plugins', pluginRows(kindData.plugins.items));
+        printExpandedSection('MCP', mcpRows(kindData.mcp.items, repoMcpConfigs));
     }
     console.log('');
     console.log(chalk.gray(`Drill in:   agents inspect ${repo.label} --skills <query>`));
@@ -480,7 +521,9 @@ async function renderSummary(agent, version, versionHome, options) {
     const shimPath = path.join(getShimsDir(), AGENTS[agent].cliCommand);
     const aliasPath = getVersionedAliasPath(agent, version);
     const capabilities = collectCapabilities(agent, version);
-    const counts = options.brief ? null : collectCounts(agent, versionHome);
+    const itemsByKind = options.brief ? null : collectItemsByKind(agent, versionHome);
+    const hookByScript = options.brief ? null : hookManifestByScript(loadCentralHookManifest());
+    const mcpConfigs = options.brief ? null : new Map(listMcpServerConfigs().map(s => [s.name, s.config]));
     const sessions = options.brief ? null : {
         total: safeCountSessions(agent),
     };
@@ -496,7 +539,7 @@ async function renderSummary(agent, version, versionHome, options) {
             strategy,
             installedShim: cliState?.installed === true ? cliState.path : null,
             capabilities,
-            resources: counts,
+            resources: itemsByKind ? summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) : null,
             sessions,
         };
         console.log(JSON.stringify(json, null, 2));
@@ -521,15 +564,14 @@ async function renderSummary(agent, version, versionHome, options) {
         const reason = res.ok ? '' : chalk.gray(`(${res.reason}${res.need ? ' ' + res.need : ''})`);
         console.log(`  ${cap.padEnd(10)} ${mark} ${reason}`);
     }
-    if (counts) {
+    if (itemsByKind) {
         console.log('\n' + chalk.bold('Resources'));
-        for (const kind of DRILLABLE_KINDS) {
-            const c = counts[kind];
-            if (!c)
-                continue;
-            const breakdown = formatScopeBreakdown(c.bySource);
-            console.log(`  ${kind.padEnd(10)} ${String(c.total).padStart(4)}   ${chalk.gray(breakdown)}`);
+        for (const kind of SIMPLE_KINDS) {
+            printSimpleResourceRow(kind, itemsByKind[kind]);
         }
+        printExpandedSection('Hooks', hookRows(itemsByKind.hooks, hookByScript));
+        printExpandedSection('Plugins', pluginRows(itemsByKind.plugins));
+        printExpandedSection('MCP', mcpRows(itemsByKind.mcp, mcpConfigs));
     }
     if (sessions) {
         console.log('\n' + chalk.bold('Sessions'));
@@ -649,14 +691,52 @@ function collectCapabilities(agent, version) {
     }
     return out;
 }
-function collectCounts(agent, versionHome) {
+function collectItemsByKind(agent, versionHome) {
+    const out = {};
+    for (const kind of DRILLABLE_KINDS)
+        out[kind] = collectKind(agent, versionHome, kind);
+    return out;
+}
+/** A simple-kind count row: `kind  N   user:30 system:12   name, name …(+K)`. */
+function printSimpleResourceRow(kind, items) {
+    const count = String(items.length).padStart(4);
+    const breakdown = chalk.gray(scopeBreakdownPlain(countBySource(items.map(i => i.source))).padEnd(18));
+    const preview = items.length > 0 ? chalk.gray(truncate(previewNames(items, 3), 48)) : '';
+    console.log(`  ${kind.padEnd(10)} ${count}   ${breakdown}  ${preview}`.trimEnd());
+}
+/**
+ * Build the `resources` JSON: every kind keeps `total` + `bySource` (back-compat),
+ * simple kinds add `names`, and the rich kinds add structured `items` (hook
+ * events/predicates, mcp transport/url/command, plugin version + group counts).
+ */
+function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) {
     const out = {};
     for (const kind of DRILLABLE_KINDS) {
-        const items = collectKind(agent, versionHome, kind);
-        const bySource = {};
-        for (const item of items)
-            bySource[item.source] = (bySource[item.source] || 0) + 1;
-        out[kind] = { total: items.length, bySource };
+        const items = itemsByKind[kind];
+        const base = { total: items.length, bySource: countBySource(items.map(i => i.source)) };
+        if (kind === 'hooks') {
+            out[kind] = { ...base, items: items.map(i => {
+                    const h = hookByScript.get(i.name);
+                    return { name: i.name, source: i.source, events: h?.events ?? [], matcher: h?.matcher, matches: h?.matches, cache: h?.cache };
+                }) };
+        }
+        else if (kind === 'mcp') {
+            out[kind] = { ...base, items: items.map(i => {
+                    const c = mcpConfigs.get(i.name);
+                    return { name: i.name, source: i.source, transport: c?.transport, url: c?.url, command: c?.command, args: c?.args };
+                }) };
+        }
+        else if (kind === 'plugins') {
+            out[kind] = { ...base, items: items.map(i => ({
+                    name: i.name,
+                    source: i.source,
+                    version: i.extra?.find(([k]) => k === 'version')?.[1],
+                    groups: Object.fromEntries((i.groups ?? []).map(g => [g.label, g.items.length])),
+                })) };
+        }
+        else {
+            out[kind] = { ...base, names: items.map(i => i.name) };
+        }
     }
     return out;
 }
@@ -782,6 +862,181 @@ function buildDetailRows(item, kind) {
     }
     return rows;
 }
+/** `system` → `sys`; everything else unchanged. Keeps the tag column narrow. */
+function abbrevSource(s) {
+    return s === 'system' ? 'sys' : s;
+}
+/**
+ * Compact one-liner for a hook from its manifest entry: the firing events (with
+ * the matcher/tool-name in parens), then a `·`-separated predicate summary, then
+ * an optional cache tail. Plain text — the caller applies color.
+ */
+export function summarizeHook(hook) {
+    const events = (hook.events ?? []).join('/') || '(no event)';
+    let matcher = hook.matcher;
+    if (!matcher && hook.matches?.tool_name) {
+        const tn = hook.matches.tool_name;
+        matcher = Array.isArray(tn) ? tn.join('|') : tn;
+    }
+    const head = matcher ? `${events}(${matcher})` : events;
+    const parts = [head];
+    const preds = summarizeMatches(hook.matches);
+    if (preds)
+        parts.push(preds);
+    let line = parts.join(' · ');
+    const ttl = hookCacheTtl(hook.cache);
+    if (ttl)
+        line += ` (${ttl} cache)`;
+    return line;
+}
+/** `·`-separated predicate summary from a hook's `matches:` block (tool_name omitted — shown in the matcher parens). */
+function summarizeMatches(m) {
+    if (!m)
+        return '';
+    const bits = [];
+    if (m.git_dirty)
+        bits.push('git_dirty');
+    if (m.prompt_contains)
+        bits.push(`prompt~"${truncate(m.prompt_contains, 24)}"`);
+    if (m.prompt_matches)
+        bits.push(`prompt=/${truncate(m.prompt_matches, 24)}/`);
+    if (m.tool_args_match)
+        bits.push(`args=/${truncate(m.tool_args_match, 20)}/`);
+    if (m.cwd_includes) {
+        const c = Array.isArray(m.cwd_includes) ? m.cwd_includes.join('|') : m.cwd_includes;
+        bits.push(`cwd~${truncate(c, 24)}`);
+    }
+    if (m.project_has)
+        bits.push(`has ${m.project_has}`);
+    return bits.join(' · ');
+}
+/** Normalize a hook cache shorthand/object to a display ttl ("5m", "1h"); null when uncached. */
+function hookCacheTtl(cache) {
+    if (cache === undefined || cache === null)
+        return null;
+    if (typeof cache === 'string')
+        return cache.replace(/-bg$/, '');
+    return String(cache.ttl);
+}
+/** Compact one-liner for an MCP server: padded transport + the url (http) or command line (stdio). */
+export function summarizeMcp(cfg) {
+    const target = cfg.transport === 'http'
+        ? (cfg.url ?? '')
+        : [cfg.command, ...(cfg.args ?? [])].filter(Boolean).join(' ');
+    return `${cfg.transport.padEnd(5)}  ${truncate(target, 60)}`.trimEnd();
+}
+/** Print `Title (N)` then up to `max` aligned `[source] name  detail` rows with a `…(+K)` tail. */
+function printExpandedSection(title, rows, max = 6) {
+    console.log('\n' + chalk.bold(title) + chalk.gray(` (${rows.length})`));
+    if (rows.length === 0) {
+        console.log(chalk.gray('  (none)'));
+        return;
+    }
+    const shown = rows.slice(0, max);
+    const nameW = Math.max(...shown.map(r => r.name.length));
+    for (const r of shown) {
+        const tag = chalk.gray(`[${abbrevSource(r.source)}]`.padEnd(8));
+        const padded = r.name.padEnd(nameW);
+        const name = r.linkTarget ? termLink(chalk.cyan(padded), r.linkTarget) : chalk.cyan(padded);
+        const detail = r.detail ? '  ' + chalk.gray(r.detail) : '';
+        console.log(`  ${tag} ${name}${detail}`);
+    }
+    if (rows.length > max)
+        console.log(chalk.gray(`  …(+${rows.length - max})`));
+}
+/** Tally a source list into `{user: n, system: m}`. */
+function countBySource(sources) {
+    const out = {};
+    for (const s of sources)
+        out[s] = (out[s] || 0) + 1;
+    return out;
+}
+/** Unbracketed scope breakdown for the simple count rows: `user:30 system:12`. */
+function scopeBreakdownPlain(bySource) {
+    return Object.entries(bySource).map(([k, v]) => `${k}:${v}`).join(' ');
+}
+/**
+ * Index a hook manifest by script basename (no extension). Installed hooks are
+ * named after their script file (`04-capture-…`), while the manifest is keyed by
+ * logical name (`capture-…`) with the filename in `script:` — so we join on the
+ * script basename, not the manifest key.
+ */
+export function hookManifestByScript(manifest) {
+    const out = new Map();
+    for (const hook of Object.values(manifest)) {
+        if (hook && typeof hook.script === 'string') {
+            out.set(path.basename(hook.script).replace(/\.[^.]+$/, ''), hook);
+        }
+    }
+    return out;
+}
+/** Build hook rows by enriching the installed hook items with manifest events/predicates. */
+function hookRows(items, byScript) {
+    return items.map(item => {
+        const hook = byScript.get(item.name);
+        return {
+            source: item.source,
+            name: item.name,
+            linkTarget: item.linkTarget,
+            // Hooks are shell scripts with no human description — show events/predicates
+            // from the manifest, or nothing rather than a meaningless shebang line.
+            detail: hook ? summarizeHook(hook) : '',
+        };
+    });
+}
+/** Build plugin rows: `vVERSION  skills:6 commands:5 …` from the bundle's groups. */
+function pluginRows(items) {
+    return items.map(item => {
+        const version = item.extra?.find(([k]) => k === 'version')?.[1];
+        const counts = (item.groups ?? []).map(g => `${g.label}:${g.items.length}`).join(' ');
+        const detail = [version ? `v${version}` : '', counts].filter(Boolean).join('  ');
+        return { source: item.source, name: item.name, detail, linkTarget: item.linkTarget };
+    });
+}
+/** Build MCP rows by joining the installed mcp items with their full configs (transport/url/command). */
+function mcpRows(items, configs) {
+    return items.map(item => {
+        const cfg = configs.get(item.name);
+        return { source: item.source, name: item.name, detail: cfg ? summarizeMcp(cfg) : item.description };
+    });
+}
+/** Read a repo/agents.yaml `hooks:` section into a name→ManifestHook map (best-effort). */
+function hookManifestFromFile(agentsYamlPath) {
+    try {
+        const meta = yaml.parse(fs.readFileSync(agentsYamlPath, 'utf-8'));
+        return meta?.hooks ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge the system + user `agents.yaml` hook manifests (user wins on key
+ * collision). Built directly from the two layer files rather than via
+ * `parseHookManifest()` so inspecting never emits the shadow/override warnings
+ * that the registrar path prints.
+ */
+function loadCentralHookManifest() {
+    return {
+        ...hookManifestFromFile(path.join(getSystemAgentsDir(), 'agents.yaml')),
+        ...hookManifestFromFile(path.join(getUserAgentsDir(), 'agents.yaml')),
+    };
+}
+/**
+ * Hook items for a repo's Hooks section. Uses the grouped hook reader (script +
+ * data file collapsed into one entry, non-hook files like promptcuts.yaml or
+ * README.md filtered out) rather than a naive readdir, so names are clean and
+ * join cleanly against the manifest by script basename.
+ */
+function repoHookItems(repo) {
+    return listHookEntriesFromDir(path.join(repo.root, 'hooks')).map(h => ({
+        name: h.name,
+        source: repo.label,
+        path: h.scriptPath,
+        linkTarget: h.scriptPath,
+        description: '',
+    }));
+}
 function findMatches(items, query) {
     const q = query.toLowerCase();
     const out = [];
@@ -979,9 +1234,3 @@ function truncate(s, n) {
         return s;
     return s.slice(0, n - 1) + '…';
 }
-function formatScopeBreakdown(bySource) {
-    const entries = Object.entries(bySource);
-    if (entries.length === 0)
-        return '';
-    return '[' + entries.map(([k, v]) => `${k}:${v}`).join(' ') + ']';
-}

package/dist/commands/prune.js

@@ -26,7 +26,7 @@ import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
 import { diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
-import { diffVersionHooks, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
+import { listUnmanagedHooksInVersionHome, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
 import { diffVersionPlugins, iterPluginsCapableVersions, removePluginSkillFromVersion, } from '../lib/plugins.js';
 import { diffVersionSubagents, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
 import { getGlobalDefault } from '../lib/versions.js';
@@ -64,9 +64,12 @@ function collectOrphans(types, all) {
     }
     if (types.includes('hooks')) {
         for (const { agent, version } of scopePairs(iterHooksCapableVersions(), all)) {
-            const diff = diffVersionHooks(agent, version);
-            if (diff.orphans.length > 0) {
-                groups.push({ type: 'hooks', agent, version, orphans: diff.orphans });
+            // Orphan hooks = scripts present in the version home that no
+            // agents.yaml/hooks.yaml entry registers, so they never fire. Same
+            // definition the doctor overview reports.
+            const orphans = listUnmanagedHooksInVersionHome(agent, version);
+            if (orphans.length > 0) {
+                groups.push({ type: 'hooks', agent, version, orphans });
             }
         }
     }
@@ -210,7 +213,7 @@ async function runOrphanPrune(resourceTypes, options) {
         return;
     }
     const total = groups.reduce((n, g) => n + g.orphans.length, 0);
-    console.log(chalk.bold('Orphans (in version home, not in any source)\n'));
+    console.log(chalk.bold('Orphans (in version home, unmanaged by any source)\n'));
     for (const g of groups) {
         const label = `${g.type} · ${g.agent}@${g.version}`;
         console.log(`  ${chalk.cyan(label)}  ${g.orphans.join(', ')}`);

package/dist/commands/view.d.ts

@@ -19,6 +19,7 @@ export interface ViewSectionFilter {
     rules?: boolean;
     hooks?: boolean;
     promptcuts?: boolean;
+    cli?: boolean;
 }
 /** Machine-readable entry for a single installed version. */
 export interface ViewJsonVersion {

package/dist/commands/view.js

@@ -8,6 +8,7 @@ import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
+import { listCliStatus } from '../lib/cli-resources.js';
 import { isCapable } from '../lib/capabilities.js';
 import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts } from '../lib/state.js';
@@ -114,7 +115,7 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
-const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts'];
+const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'cli'];
 /**
  * Decide whether a section should render given the filter. If no flags are set,
  * everything renders (current behavior). If any flag is set, only those sections
@@ -167,6 +168,51 @@ function renderProfilesSection(profiles) {
  * Show installed versions for one or all agents.
  * Called when: `agents view` or `agents view claude`
  */
+/** Color the source-layer tag for a host CLI, matching the rules-section convention. */
+function hostCliSourceTag(source) {
+    if (source === 'project')
+        return chalk.blue('[project]');
+    if (source === 'user')
+        return chalk.cyan('[user]');
+    if (source === 'system')
+        return chalk.gray('[system]');
+    // Anything else is an extra repo, tagged by its alias.
+    return chalk.magenta(`[${source}]`);
+}
+/**
+ * Render the host-CLI section. Host CLIs are host-global: declared in any
+ * DotAgents repo's `cli/` (project > user > system > extras), installed to PATH
+ * rather than copied into a version home. They render identically in the overview
+ * and in a per-agent detail view because every agent on the host shares them.
+ * The source tag shows which repo layer declared each — so user-level and
+ * extra-repo manifests are visibly supported.
+ */
+function renderHostClisSection(cwd) {
+    const { statuses, errors } = listCliStatus(cwd);
+    console.log(chalk.bold('\nHost CLIs\n'));
+    if (statuses.length === 0) {
+        console.log(`  ${chalk.gray('none declared')} ${chalk.gray('— add one with `agents cli add <name>`')}`);
+    }
+    else {
+        const nameWidth = Math.max(...statuses.map((s) => s.manifest.name.length));
+        let anyMissing = false;
+        for (const { manifest, installed } of statuses) {
+            if (!installed)
+                anyMissing = true;
+            const status = installed ? chalk.green('installed') : chalk.red('missing  ');
+            const linkedName = termLink(manifest.name.padEnd(nameWidth), linkTarget(manifest.path));
+            const tag = hostCliSourceTag(manifest.source);
+            const desc = manifest.description ? chalk.gray(`  ${summarizeDescription(manifest.description, 60)}`) : '';
+            console.log(`  ${status}  ${chalk.cyan(linkedName)} ${tag}${desc}`);
+        }
+        if (anyMissing) {
+            console.log(chalk.gray('  Install missing with `agents cli install`'));
+        }
+    }
+    for (const err of errors) {
+        console.log(`  ${chalk.red('error')}      ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
+    }
+}
 async function showInstalledVersions(filterAgentId) {
     const spinnerText = filterAgentId
         ? `Checking ${agentLabel(filterAgentId)} agents...`
@@ -537,6 +583,10 @@ async function showInstalledVersions(filterAgentId) {
         console.log(chalk.gray('  Run: agents add claude@latest'));
         console.log();
     }
+    // Host CLIs are host-global, not per-agent — show them once in the overview.
+    if (!filterAgentId) {
+        renderHostClisSection(process.cwd());
+    }
     // Check for new resources when viewing a specific agent
     if (filterAgentId && versionManaged.length > 0) {
         const defaultVersion = getGlobalDefault(filterAgentId);
@@ -892,6 +942,9 @@ async function showAgentResources(agentId, requestedVersion, filter) {
     if (shouldRenderSection('promptcuts', filter)) {
         renderPromptcuts();
     }
+    if (shouldRenderSection('cli', filter)) {
+        renderHostClisSection(cwd);
+    }
     // Show legend at the end if git repo exists and we showed all sections.
     // Filtered single-section views skip it — noise for promptcuts or plugins.
     if (hasGitRepo && !anyFilterSet) {
@@ -1183,6 +1236,7 @@ export async function viewAction(agentArg, options) {
         rules: options?.rules,
         hooks: options?.hooks,
         promptcuts: options?.promptcuts,
+        cli: options?.cli,
     };
     const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
     if (!agentArg) {
@@ -1263,6 +1317,7 @@ export function registerViewCommand(program) {
         .option('--rules', 'Show only rules in the detail view.')
         .option('--hooks', 'Show only hooks in the detail view.')
         .option('--promptcuts', 'Show only promptcuts in the detail view.')
+        .option('--cli', 'Show only host CLIs (declared in cli/, installed to PATH).')
         .addHelpText('after', `
 Examples:
   # Show all installed agents with versions, accounts, and usage

package/dist/lib/hooks.d.ts

@@ -123,7 +123,27 @@ export declare function listCentralHooks(): HookEntry[];
  *
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
-export declare function parseHookManifest(): Record<string, ManifestHook>;
+export declare function parseHookManifest(opts?: {
+    warn?: boolean;
+}): Record<string, ManifestHook>;
+/**
+ * Hook script files present on disk that no manifest entry declares — "dead"
+ * hooks. The registrar only wires manifest-declared hooks into an agent's
+ * native config (settings.json / config.toml), matching the installed file to a
+ * manifest entry by script basename. So a file whose basename matches no
+ * manifest `script:` is never registered: it occupies the hooks dir and shows
+ * up in listings, but no lifecycle event ever fires it.
+ *
+ * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
+ * installed hook names and the manifest's script paths.
+ */
+export declare function unmanagedHookNames(installedHookNames: string[], manifestScripts: string[]): string[];
+/**
+ * The dead hooks (see {@link unmanagedHookNames}) sitting in one version home.
+ * Reads the merged hook manifest silently — a diagnostic must not emit the
+ * shadow/override warnings the registrar path prints.
+ */
+export declare function listUnmanagedHooksInVersionHome(agent: AgentId, version: string): string[];
 export declare function registerHooksToSettings(agentId: AgentId, versionHome: string, hookManifest?: Record<string, ManifestHook>, agentsDirOverride?: string): {
     registered: string[];
     errors: string[];

package/dist/lib/hooks.js

@@ -650,7 +650,8 @@ export function listCentralHooks() {
  *
  * Hooks marked `enabled: false` are dropped from the returned map.
  */
-export function parseHookManifest() {
+export function parseHookManifest(opts = {}) {
+    const warn = opts.warn !== false;
     const merged = {};
     const systemHooks = {};
     // System layer: hooks: section of agents.yaml (npm-shipped, separate repo).
@@ -673,7 +674,7 @@ export function parseHookManifest() {
             const meta = yaml.parse(fs.readFileSync(userMetaPath, 'utf-8'));
             if (meta?.hooks)
                 for (const [name, def] of Object.entries(meta.hooks)) {
-                    if (systemHooks[name] && def.override !== true) {
+                    if (warn && systemHooks[name] && def.override !== true) {
                         const action = def.enabled === false ? 'disables' : 'shadows';
                         console.warn(`[agents hooks] User-layer hook '${name}' ${action} system-shipped hook. Set 'override: true' to silence this warning.`);
                     }
@@ -689,6 +690,35 @@ export function parseHookManifest() {
     }
     return merged;
 }
+/**
+ * Hook script files present on disk that no manifest entry declares — "dead"
+ * hooks. The registrar only wires manifest-declared hooks into an agent's
+ * native config (settings.json / config.toml), matching the installed file to a
+ * manifest entry by script basename. So a file whose basename matches no
+ * manifest `script:` is never registered: it occupies the hooks dir and shows
+ * up in listings, but no lifecycle event ever fires it.
+ *
+ * Pure on purpose (no disk reads) so it is trivially testable; callers pass the
+ * installed hook names and the manifest's script paths.
+ */
+export function unmanagedHookNames(installedHookNames, manifestScripts) {
+    const managed = new Set(manifestScripts.map((s) => path.basename(s).replace(/\.[^.]+$/, '')));
+    return installedHookNames.filter((name) => !managed.has(name)).sort();
+}
+/**
+ * The dead hooks (see {@link unmanagedHookNames}) sitting in one version home.
+ * Reads the merged hook manifest silently — a diagnostic must not emit the
+ * shadow/override warnings the registrar path prints.
+ */
+export function listUnmanagedHooksInVersionHome(agent, version) {
+    if (!AGENTS[agent].supportsHooks)
+        return [];
+    const scripts = Object.values(parseHookManifest({ warn: false }))
+        .map((h) => h.script)
+        .filter((s) => typeof s === 'string');
+    const installed = listHooksInVersionHome(agent, version).map((e) => e.name);
+    return unmanagedHookNames(installed, scripts);
+}
 // Codex events that support a matcher field (matches tool name or session type).
 // UserPromptSubmit and Stop never include a matcher.
 const CODEX_MATCHER_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart']);

package/dist/lib/plugins.d.ts

@@ -74,6 +74,16 @@ export declare function getPlugin(name: string): DiscoveredPlugin | null;
  * Otherwise defaults to all plugin-capable agents.
  */
 export declare function pluginSupportsAgent(plugin: DiscoveredPlugin, agent: AgentId): boolean;
+/**
+ * The lifecycle events a plugin hooks into, read from hooks/hooks.json.
+ *
+ * The official plugin format wraps the event map under a `hooks` key
+ * (`{ description, hooks: { SessionStart: [...], PreToolUse: [...] } }`), so the
+ * meaningful keys are the events — NOT the top-level keys (`description`,
+ * `hooks`). Older/flat files put the event names at the top level directly; we
+ * read whichever object actually holds the event map.
+ */
+export declare function discoverPluginHooks(pluginRoot: string): string[];
 /** Discover command .md files inside a plugin's commands/ directory. */
 export declare function discoverPluginCommands(pluginRoot: string): string[];
 /** Discover agent definition .md files inside a plugin's agents/ directory. */

package/dist/lib/plugins.js

@@ -213,13 +213,25 @@ function discoverPluginSkills(pluginRoot) {
         .filter(d => d.isDirectory() && !d.name.startsWith('.'))
         .map(d => d.name);
 }
-function discoverPluginHooks(pluginRoot) {
+/**
+ * The lifecycle events a plugin hooks into, read from hooks/hooks.json.
+ *
+ * The official plugin format wraps the event map under a `hooks` key
+ * (`{ description, hooks: { SessionStart: [...], PreToolUse: [...] } }`), so the
+ * meaningful keys are the events — NOT the top-level keys (`description`,
+ * `hooks`). Older/flat files put the event names at the top level directly; we
+ * read whichever object actually holds the event map.
+ */
+export function discoverPluginHooks(pluginRoot) {
     const hooksFile = path.join(pluginRoot, 'hooks', 'hooks.json');
     if (!fs.existsSync(hooksFile))
         return [];
     try {
         const content = JSON.parse(fs.readFileSync(hooksFile, 'utf-8'));
-        return Object.keys(content);
+        const eventMap = content.hooks && typeof content.hooks === 'object' && !Array.isArray(content.hooks)
+            ? content.hooks
+            : content;
+        return Object.keys(eventMap);
     }
     catch {
         return [];

package/dist/lib/rotate.d.ts

@@ -11,6 +11,13 @@ export interface RotateCandidate {
     agent: AgentId;
     version: string;
     email: string | null;
+    /**
+     * Per-org usage/quota key (e.g. `claude:org=<orgUuid>`) — the unit rate
+     * limits are actually measured in. Distinct orgs signed in under the same
+     * email have distinct keys, so this is the correct dedup boundary; null when
+     * no usage identity is available (then we fall back to email).
+     */
+    usageKey: string | null;
     usageStatus: AccountInfo['usageStatus'];
     usageSnapshot: UsageSnapshot | null;
     authValid: boolean;

package/dist/lib/rotate.js

@@ -105,19 +105,29 @@ function compareCandidates(a, b) {
         return ta - tb;
     return Math.random() - 0.5;
 }
+/**
+ * Identity a candidate dedups on. Quota is tracked per-org, so two versions
+ * that share an org are the same rate-limit bucket and must collapse — but two
+ * orgs under the same email (e.g. Enterprise + Personal on one Google identity)
+ * are genuinely separate buckets and must stay distinct. Prefer the org usage
+ * key; fall back to email only when no usage identity is available.
+ */
+function candidateIdentity(c) {
+    return c.usageKey ?? c.email;
+}
 function dedupeAndSortCandidates(candidates) {
-    const byEmail = new Map();
+    const byIdentity = new Map();
     for (const c of candidates) {
-        const email = c.email;
-        const existing = byEmail.get(email);
+        const id = candidateIdentity(c);
+        const existing = byIdentity.get(id);
         if (!existing) {
-            byEmail.set(email, c);
+            byIdentity.set(id, c);
             continue;
         }
         if (compareCandidates(c, existing) < 0)
-            byEmail.set(email, c);
+            byIdentity.set(id, c);
     }
-    return [...byEmail.values()].sort(compareCandidates);
+    return [...byIdentity.values()].sort(compareCandidates);
 }
 /**
  * Pick a healthy candidate using weighted random by remaining capacity.
@@ -252,7 +262,7 @@ async function collectRunCandidates(agent) {
         const usageSnapshot = usageKey
             ? usageByKey.get(usageKey)?.snapshot ?? null
             : null;
-        return { ...candidate, usageSnapshot };
+        return { ...candidate, usageKey, usageSnapshot };
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.13",
+  "version": "1.20.14",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",