@prave/cli 1.4.15 → 1.6.0

package/README.md

@@ -63,7 +63,7 @@ Syncing 12 Skills — this takes about 15 seconds.
 Synced 12 · failed 0
 ```
 
-The `last_sync_at` watermark persists at `~/.prave/state.json`. Pass `--yes` to skip the prompt in CI scripts.
+The `last_sync_at` watermark persists at `~/.prave/state.json`.
 
 ## Commands
 

package/dist/commands/hooks.js

@@ -0,0 +1,234 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { track } from '../lib/analytics.js';
+import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
+import { detectCollisions, installRegistryHook, listForeignHooks, listRegistryHooks, removeRegistryHook, } from '../lib/hook.js';
+import { assertSlug, InvalidSlugError } from '../lib/slug.js';
+import { log } from '../utils/logger.js';
+/* ─── install ─────────────────────────────────────────────────── */
+export async function hooksInstallCommand(slug, opts = {}) {
+    track('cli_hooks_install', { slug, dry_run: !!opts.dryRun });
+    try {
+        assertSlug(slug);
+    }
+    catch (err) {
+        if (err instanceof InvalidSlugError) {
+            log.error(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    await requireAuth('hooks');
+    const spinner = ora(`Fetching hook ${chalk.cyan(slug)}…`).start();
+    let hook;
+    try {
+        const { data } = await api.get(`/api/v1/hooks/${encodeURIComponent(slug)}`);
+        hook = data;
+    }
+    catch (err) {
+        spinner.fail(`Hook ${chalk.cyan(slug)} not found`);
+        if (err instanceof ApiError && err.status !== 404)
+            log.error(err.message);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed(`Fetched ${chalk.cyan(hook.name)}`);
+    const def = {
+        slug: hook.slug,
+        event: hook.event,
+        matcher: hook.matcher,
+        command: hook.command,
+        timeout_seconds: hook.timeout_seconds,
+    };
+    const result = await installRegistryHook(def, { dryRun: opts.dryRun });
+    if (opts.dryRun) {
+        printDryRunDiff(result.before, result.after);
+        log.info(`(dry-run) ${result.changed ? 'Would install' : 'No change needed for'} ${chalk.cyan(slug)}.`);
+        return;
+    }
+    if (!result.changed) {
+        log.info(`Already installed: ${chalk.cyan(slug)} — no change.`);
+        return;
+    }
+    // Record the install receipt so the dashboard count + trending sort
+    // stay accurate. Best-effort: a network blip here must not undo the
+    // local install.
+    try {
+        await api.post(`/api/v1/hooks/${encodeURIComponent(slug)}/install`, {}, true);
+    }
+    catch (err) {
+        log.warn(`Local install succeeded but server receipt failed: ${err.message}`);
+    }
+    log.success(`Installed ${chalk.cyan(slug)} → ${result.settingsPath}`);
+}
+/* ─── remove ──────────────────────────────────────────────────── */
+export async function hooksRemoveCommand(slug, opts = {}) {
+    track('cli_hooks_remove', { slug, dry_run: !!opts.dryRun });
+    try {
+        assertSlug(slug);
+    }
+    catch (err) {
+        if (err instanceof InvalidSlugError) {
+            log.error(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    const result = await removeRegistryHook(slug, { dryRun: opts.dryRun });
+    if (opts.dryRun) {
+        printDryRunDiff(result.before, result.after);
+        log.info(`(dry-run) ${result.changed ? 'Would remove' : 'No matching hook for'} ${chalk.cyan(slug)}.`);
+        return;
+    }
+    if (!result.changed) {
+        log.info(`No installed hook with slug ${chalk.cyan(slug)} — nothing to remove.`);
+        return;
+    }
+    log.success(`Removed ${chalk.cyan(slug)} from ${result.settingsPath}`);
+    // Soft uninstall on the server so the user's dashboard count drops.
+    try {
+        await requireAuth('hooks');
+        await api.del(`/api/v1/hooks/${encodeURIComponent(slug)}/install`, true);
+    }
+    catch {
+        /* offline / not logged in — local state is what matters */
+    }
+}
+/* ─── list ────────────────────────────────────────────────────── */
+export async function hooksListCommand() {
+    track('cli_hooks_list', {});
+    const installed = await listRegistryHooks();
+    if (installed.length === 0) {
+        log.info('No prave-managed hooks installed locally.');
+        return;
+    }
+    log.info(`${chalk.bold(installed.length)} prave-managed hook${installed.length === 1 ? '' : 's'} installed:\n`);
+    for (const h of installed) {
+        console.log(`  ${chalk.cyan(h.slug)}  ${chalk.dim(h.channel + (h.matcher ? `:${h.matcher}` : ''))}` +
+            (h.timeout ? chalk.dim(`  (${h.timeout}s)`) : ''));
+        console.log(`    ${chalk.gray(h.command)}`);
+    }
+}
+/* ─── sync ────────────────────────────────────────────────────── */
+export async function hooksSyncCommand(opts = {}) {
+    track('cli_hooks_sync', { dry_run: !!opts.dryRun });
+    await requireAuth('hooks');
+    const installed = await listRegistryHooks();
+    if (installed.length === 0) {
+        log.info('No local prave-managed hooks to sync.');
+        return;
+    }
+    const slugs = installed.map((h) => h.slug);
+    const spinner = ora(`Syncing ${slugs.length} hook${slugs.length === 1 ? '' : 's'}…`).start();
+    let bulk;
+    try {
+        const { data } = await api.post('/api/v1/hooks/bulk/sync', { slugs }, true);
+        bulk = data;
+    }
+    catch (err) {
+        spinner.fail('Sync failed');
+        log.error(err.message);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed('Sync received');
+    let updated = 0;
+    for (const item of bulk.items) {
+        if (!item.hook)
+            continue;
+        const def = {
+            slug: item.hook.slug,
+            event: item.hook.event,
+            matcher: item.hook.matcher,
+            command: item.hook.command,
+            timeout_seconds: item.hook.timeout_seconds,
+        };
+        const result = await installRegistryHook(def, { dryRun: opts.dryRun });
+        if (result.changed)
+            updated++;
+    }
+    if (bulk.missing.length) {
+        log.warn(`Skipped ${bulk.missing.length} unknown slug${bulk.missing.length === 1 ? '' : 's'}: ${bulk.missing.join(', ')}`);
+    }
+    log.success(`${opts.dryRun ? '(dry-run) ' : ''}Updated ${updated} of ${slugs.length} hook${slugs.length === 1 ? '' : 's'}.`);
+}
+/* ─── audit ───────────────────────────────────────────────────── */
+export async function hooksAuditCommand() {
+    track('cli_hooks_audit', {});
+    const installed = await listRegistryHooks();
+    const foreign = await listForeignHooks();
+    const collisions = detectCollisions(installed);
+    log.info(chalk.bold(`Prave-managed registry hooks: ${installed.length}`));
+    for (const h of installed) {
+        console.log(`  ${chalk.cyan(h.slug)}  ${chalk.dim(h.channel + (h.matcher ? `:${h.matcher}` : ''))}`);
+    }
+    if (foreign.length) {
+        console.log();
+        log.info(chalk.bold(`User-owned hooks (untouched): ${foreign.length}`));
+        for (const h of foreign) {
+            console.log(`  ${chalk.dim(h.channel + (h.matcher ? `:${h.matcher}` : ''))}  ${chalk.gray(h.command)}`);
+        }
+    }
+    if (collisions.length) {
+        console.log();
+        log.warn(`${collisions.length} collision${collisions.length === 1 ? '' : 's'} detected — multiple registry hooks share an event+matcher pair:`);
+        for (const c of collisions) {
+            console.log(`  ${chalk.yellow(`${c.channel}:${c.matcher ?? '*'}`)}  →  ${c.slugs.map((s) => chalk.cyan(s)).join(', ')}`);
+        }
+    }
+    else {
+        console.log();
+        log.success('No collisions detected.');
+    }
+}
+/* ─── update ──────────────────────────────────────────────────── */
+export async function hooksUpdateCommand(slug, opts = {}) {
+    track('cli_hooks_update', { slug: slug ?? null, dry_run: !!opts.dryRun });
+    await requireAuth('hooks');
+    const installed = await listRegistryHooks();
+    const targets = slug ? installed.filter((h) => h.slug === slug) : installed;
+    if (targets.length === 0) {
+        log.info(slug ? `${chalk.cyan(slug)} is not installed.` : 'No installed registry hooks to update.');
+        return;
+    }
+    let updated = 0;
+    for (const local of targets) {
+        let remote;
+        try {
+            const { data } = await api.get(`/api/v1/hooks/${encodeURIComponent(local.slug)}`);
+            remote = data;
+        }
+        catch (err) {
+            log.warn(`Skipping ${chalk.cyan(local.slug)} — ${err.message}`);
+            continue;
+        }
+        const def = {
+            slug: remote.slug,
+            event: remote.event,
+            matcher: remote.matcher,
+            command: remote.command,
+            timeout_seconds: remote.timeout_seconds,
+        };
+        const result = await installRegistryHook(def, { dryRun: opts.dryRun });
+        if (result.changed) {
+            updated++;
+            log.info(`${opts.dryRun ? '(dry-run) ' : ''}Updated ${chalk.cyan(local.slug)} → v${remote.version}`);
+        }
+        else {
+            log.info(`${chalk.cyan(local.slug)} already current.`);
+        }
+    }
+    log.success(`${opts.dryRun ? '(dry-run) ' : ''}${updated} hook${updated === 1 ? '' : 's'} updated.`);
+}
+/* ─── helpers ─────────────────────────────────────────────────── */
+function printDryRunDiff(before, after) {
+    const b = JSON.stringify(before, null, 2);
+    const a = JSON.stringify(after, null, 2);
+    console.log(chalk.gray('--- before ---'));
+    console.log(chalk.red(b));
+    console.log(chalk.gray('--- after ---'));
+    console.log(chalk.green(a));
+}

package/dist/commands/sync.js

@@ -3,9 +3,9 @@ import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import ora from 'ora';
+import { resolveAgentTargets } from '../lib/agent-paths.js';
 import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
-import { CONFIG } from '../lib/config.js';
 import { requireAuth } from '../lib/credentials.js';
 import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
 import { readState, writeState } from '../lib/state.js';
@@ -111,28 +111,49 @@ export async function syncCommand() {
             return;
         }
     }
+    // Resolve every on-disk target the user has enabled in web settings.
+    // Pre-2026-06-05 sync was hard-pinned to ~/.claude/skills/ — users
+    // with Codex / Cline / Amp enabled saw nothing land in those dirs.
+    // Now we read the server-side agent settings and write to every
+    // enabled (non-conversion) path. Cursor is excluded for now because
+    // it needs format conversion.
+    const targets = await resolveAgentTargets();
+    const targetSummary = targets.map((t) => t.agent).join(', ');
     const spinner = ora('Scanning local Skills…').start();
-    let entries = [];
-    try {
-        entries = await readdir(CONFIG.skillsDir);
+    // Union of slugs across all enabled targets — a skill that only
+    // exists in ~/.claude/skills is still "installed", and one we
+    // pulled into ~/.codex/skills the last sync should re-sync too.
+    const slugSet = new Set();
+    let scannedAny = false;
+    for (const target of targets) {
+        let entries = [];
+        try {
+            entries = await readdir(target.dir);
+            scannedAny = true;
+        }
+        catch {
+            // Missing dir → user enabled the agent in settings but never
+            // installed a skill there. Sync will create it on first write.
+            continue;
+        }
+        for (const name of entries) {
+            const dir = join(target.dir, name);
+            if ((await stat(dir).catch(() => null))?.isDirectory())
+                slugSet.add(name);
+        }
     }
-    catch {
-        spinner.warn(`No Skills directory at ${CONFIG.skillsDir}`);
+    if (!scannedAny && slugSet.size === 0) {
+        spinner.warn(`No Skills directory found across ${targetSummary || 'claude'}.`);
         return;
     }
-    const slugs = [];
-    for (const name of entries) {
-        const dir = join(CONFIG.skillsDir, name);
-        if ((await stat(dir).catch(() => null))?.isDirectory())
-            slugs.push(name);
-    }
+    const slugs = Array.from(slugSet);
     if (!slugs.length) {
         spinner.warn('No installed Skills to sync.');
         return;
     }
-    spinner.succeed(`Found ${slugs.length} installed Skill${slugs.length === 1 ? '' : 's'}.`);
+    spinner.succeed(`Found ${slugs.length} installed Skill${slugs.length === 1 ? '' : 's'} across ${targetSummary || 'claude'}.`);
     const estSeconds = estimateSeconds(slugs.length);
-    console.log(chalk.dim(`Syncing ${slugs.length} Skill${slugs.length === 1 ? '' : 's'} — this takes about ${estSeconds} seconds.`));
+    console.log(chalk.dim(`Syncing ${slugs.length} Skill${slugs.length === 1 ? '' : 's'} → ${targets.length} agent dir${targets.length === 1 ? '' : 's'} — this takes about ${estSeconds} seconds.`));
     const progress = ora(`Synced 0 / ${slugs.length}`).start();
     let updated = 0;
     let paywalled = 0;
@@ -170,7 +191,10 @@ export async function syncCommand() {
         // Track per-slug verdicts for the final summary line.
         missing += response.missing.length;
         missingSlugs.push(...response.missing);
-        // Write files in parallel, bounded.
+        // Write files in parallel, bounded. Each successful item gets
+        // written to EVERY target dir (claude + codex + …) — failures on
+        // a single target don't abort the others; we just count a skill
+        // as updated when at least one write succeeded.
         await runWithConcurrency(response.items, WRITE_CONCURRENCY, async (item) => {
             if (item.error === 'paid_unpurchased') {
                 paywalled += 1;
@@ -181,15 +205,23 @@ export async function syncCommand() {
                 noContent += 1;
                 return;
             }
-            const targetDir = join(CONFIG.skillsDir, item.slug);
-            try {
-                await mkdir(targetDir, { recursive: true });
-                await writeFile(join(targetDir, 'SKILL.md'), item.content, 'utf8');
+            let anyWritten = false;
+            for (const target of targets) {
+                const dir = join(target.dir, item.slug);
+                try {
+                    await mkdir(dir, { recursive: true });
+                    await writeFile(join(dir, 'SKILL.md'), item.content, 'utf8');
+                    anyWritten = true;
+                }
+                catch {
+                    /* per-target write failure — continue with other targets */
+                }
+            }
+            if (anyWritten) {
                 updated += 1;
                 progress.text = `Synced ${updated} / ${slugs.length} — ${item.slug}`;
             }
-            catch {
-                // Disk-level failure — surface in the summary, don't crash.
+            else {
                 noContent += 1;
             }
         });

package/dist/index.js

@@ -6,6 +6,7 @@ import { Command } from 'commander';
 import { conflictsCommand } from './commands/conflicts.js';
 import { diffCommand } from './commands/diff.js';
 import { docsCommand } from './commands/docs.js';
+import { hooksAuditCommand, hooksInstallCommand, hooksListCommand, hooksRemoveCommand, hooksSyncCommand, hooksUpdateCommand, } from './commands/hooks.js';
 import { importCommand } from './commands/import.js';
 import { installCommand } from './commands/install.js';
 import { listCommand } from './commands/list.js';
@@ -144,6 +145,38 @@ hook
     .command('uninstall')
     .description('Disable real-time invocation tracking')
     .action(usageHookUninstallCommand);
+/* ─── Hooks Manager — discover, install, sync registry hooks ─── */
+const hooks = program
+    .command('hooks')
+    .description('Manage Claude Code hooks from the Prave registry (separate from `prave usage hook` which tracks Skill invocations)');
+hooks
+    .command('install <slug>')
+    .description('Install a registry hook into ~/.claude/settings.json')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((slug, opts) => hooksInstallCommand(slug, opts));
+hooks
+    .command('remove <slug>')
+    .description('Remove a registry hook (only the entry with this slug — never touches the tracking hook)')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((slug, opts) => hooksRemoveCommand(slug, opts));
+hooks
+    .command('list')
+    .description('List prave-managed registry hooks installed locally')
+    .action(hooksListCommand);
+hooks
+    .command('sync')
+    .description('Pull the latest content for every installed registry hook')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((opts) => hooksSyncCommand(opts));
+hooks
+    .command('audit')
+    .description('List installed registry + foreign hooks and flag collisions')
+    .action(hooksAuditCommand);
+hooks
+    .command('update [slug]')
+    .description('Refresh installed registry hooks against the server (one slug or all)')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((slug, opts) => hooksUpdateCommand(slug, opts));
 program
     .command('mcp-server')
     .description('Run the Prave MCP server over stdio. Wire into Claude Desktop / Cursor MCP / Continue.dev via { "command": "npx", "args": ["-y", "@prave/cli", "mcp-server"] }. Exposes search, install, audit, my-skills, whatdoes as MCP tools.')

package/dist/lib/agent-paths.js

@@ -0,0 +1,56 @@
+import { homedir } from 'node:os';
+import { AGENT_REGISTRY } from '@prave/shared';
+import { api, ApiError } from './api.js';
+import { CONFIG } from './config.js';
+const isWindows = process.platform === 'win32';
+function expandTilde(p) {
+    if (!p)
+        return p;
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return homedir() + p.slice(1);
+    }
+    return p;
+}
+function pickOsPath(paths) {
+    return isWindows ? paths.windows : paths.mac;
+}
+export async function resolveAgentTargets() {
+    try {
+        const { data: settings } = await api.get('/api/v1/settings/agents', true);
+        const enabled = settings.enabled_agents ?? [];
+        if (enabled.length === 0) {
+            return [{ agent: 'claude', dir: CONFIG.skillsDir }];
+        }
+        const seen = new Set();
+        const targets = [];
+        for (const agent of enabled) {
+            const meta = AGENT_REGISTRY[agent];
+            if (!meta)
+                continue;
+            if (meta.conversionRequired)
+                continue;
+            const stored = settings.skill_paths?.[agent];
+            const raw = stored
+                ? pickOsPath(stored)
+                : pickOsPath(meta.defaultPath);
+            const dir = expandTilde(raw).replace(/[\\/]+$/, '');
+            if (!dir || seen.has(dir))
+                continue;
+            seen.add(dir);
+            targets.push({ agent, dir });
+        }
+        if (targets.length === 0) {
+            return [{ agent: 'claude', dir: CONFIG.skillsDir }];
+        }
+        return targets;
+    }
+    catch (err) {
+        // Fail-safe path: legacy single-claude behaviour. A 401 here just
+        // means the user isn't authed and the caller will surface that
+        // through requireAuth() anyway.
+        void (err instanceof ApiError);
+        return [{ agent: 'claude', dir: CONFIG.skillsDir }];
+    }
+}

package/dist/lib/hook.js

@@ -14,6 +14,18 @@ import { dirname, join } from 'node:path';
  */
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
 const HOOK_MARKER = '__prave_managed';
+/**
+ * Per-entry slug marker added in the Hooks Manager (V1, migration
+ * 060). The tracking hook installed by `prave usage hook install`
+ * deliberately leaves this field undefined — every "registry" hook
+ * installed via `prave hooks install <slug>` stamps its slug here.
+ *
+ * That discrimination is what makes `prave hooks remove <slug>` safe:
+ * it only targets entries with a matching `__prave_slug`, so the
+ * tracking hook can never be removed by mistake. Tests in
+ * `hook.test.ts` pin this invariant.
+ */
+const HOOK_SLUG_MARKER = '__prave_slug';
 /**
  * Agents that currently support a real-time invocation hook. Adding a new
  * agent to this list means implementing its `installFor<Agent>` branch
@@ -21,6 +33,16 @@ const HOOK_MARKER = '__prave_managed';
  * misled about what's actually being instrumented.
  */
 export const HOOK_SUPPORTED = ['claude'];
+const REGISTRY_CHANNELS = [
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'SubagentStop',
+    'Notification',
+    'PreCompact',
+    'SessionStart',
+];
 const HOOK_COMMAND = 'prave usage report';
 // Companion command for the UserPromptSubmit channel so a typed-slash
 // `/graphify` is captured even when the Skill tool path doesn't fire a
@@ -127,7 +149,15 @@ export async function uninstallSkillHook() {
             return;
         const beforeCounts = blocks.map((b) => b.hooks?.length ?? 0);
         const filtered = blocks
-            .map((b) => ({ ...b, hooks: b.hooks?.filter((h) => !h[HOOK_MARKER]) }))
+            .map((b) => ({
+            ...b,
+            // ONLY strip tracking-hook entries — those with
+            // `__prave_managed: true` AND no `__prave_slug`. Registry hooks
+            // installed via `prave hooks install <slug>` carry a
+            // `__prave_slug` and are guarded here so this code path can
+            // never remove them by accident.
+            hooks: b.hooks?.filter((h) => !(h[HOOK_MARKER] && !h[HOOK_SLUG_MARKER])),
+        }))
             .filter((b) => (b.hooks?.length ?? 0) > 0);
         const lengthChanged = filtered.length !== blocks.length;
         const innerChanged = !lengthChanged &&
@@ -164,3 +194,179 @@ async function writeSettings(settings) {
     await mkdir(dirname(SETTINGS_PATH), { recursive: true });
     await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf8');
 }
+/**
+ * Install / upsert a registry hook into `~/.claude/settings.json`.
+ * Read-modify-write is atomic-ish (single fs write) and guarded by
+ * the `__prave_slug` marker so we can:
+ *   • Update an existing entry for the same slug in-place.
+ *   • Never collide with the tracking hook (which has no slug
+ *     marker) or with a hand-written user hook (which has neither
+ *     marker).
+ *
+ * Returns the unified diff representation when `dryRun` is true so
+ * `prave hooks install --dry-run` can show what would change without
+ * actually writing.
+ */
+export async function installRegistryHook(def, opts = {}) {
+    const before = await readSettings();
+    // Defensive deep clone — operating on a copy keeps `before` clean
+    // for the diff output.
+    const after = JSON.parse(JSON.stringify(before));
+    after.hooks ??= {};
+    const channelBlocks = (after.hooks[def.event] ??= []);
+    const entry = {
+        type: 'command',
+        command: def.command,
+        [HOOK_MARKER]: true,
+        [HOOK_SLUG_MARKER]: def.slug,
+    };
+    if (def.timeout_seconds != null)
+        entry.timeout = def.timeout_seconds;
+    // Look for an existing block matching (channel, matcher) AND
+    // already carrying our slug. Upsert vs append accordingly.
+    const matcherKey = def.matcher ?? undefined;
+    const blockIdx = channelBlocks.findIndex((b) => (b.matcher ?? undefined) === matcherKey);
+    let changed = false;
+    if (blockIdx >= 0) {
+        const block = channelBlocks[blockIdx];
+        block.hooks ??= [];
+        const entryIdx = block.hooks.findIndex((h) => h[HOOK_SLUG_MARKER] === def.slug);
+        if (entryIdx >= 0) {
+            const prev = block.hooks[entryIdx];
+            if (prev.command !== entry.command || prev.timeout !== entry.timeout) {
+                block.hooks[entryIdx] = entry;
+                changed = true;
+            }
+        }
+        else {
+            block.hooks.push(entry);
+            changed = true;
+        }
+    }
+    else {
+        channelBlocks.push({
+            matcher: matcherKey,
+            hooks: [entry],
+        });
+        changed = true;
+    }
+    if (changed && !opts.dryRun)
+        await writeSettings(after);
+    return { changed, settingsPath: SETTINGS_PATH, before, after };
+}
+/**
+ * Remove the registry hook with the given slug. Filters by
+ * `__prave_slug === slug` so the tracking hook (no slug) and any
+ * foreign user hook (no marker) are NEVER touched.
+ */
+export async function removeRegistryHook(slug, opts = {}) {
+    const before = await readSettings();
+    const after = JSON.parse(JSON.stringify(before));
+    if (!after.hooks)
+        return { changed: false, settingsPath: SETTINGS_PATH, before, after };
+    let touched = false;
+    for (const channel of REGISTRY_CHANNELS) {
+        const blocks = after.hooks[channel];
+        if (!blocks?.length)
+            continue;
+        const filtered = blocks
+            .map((b) => ({
+            ...b,
+            hooks: b.hooks?.filter((h) => h[HOOK_SLUG_MARKER] !== slug),
+        }))
+            .filter((b) => (b.hooks?.length ?? 0) > 0);
+        if (filtered.length !== blocks.length ||
+            filtered.some((b, i) => (b.hooks?.length ?? 0) !== (blocks[i]?.hooks?.length ?? 0))) {
+            touched = true;
+            if (after.hooks) {
+                if (filtered.length)
+                    after.hooks[channel] = filtered;
+                else
+                    delete after.hooks[channel];
+            }
+        }
+    }
+    if (after.hooks && Object.keys(after.hooks).length === 0)
+        delete after.hooks;
+    if (touched && !opts.dryRun)
+        await writeSettings(after);
+    return { changed: touched, settingsPath: SETTINGS_PATH, before, after };
+}
+/**
+ * Enumerate the registry hooks currently installed locally — used by
+ * `prave hooks list` and `prave hooks audit`.
+ */
+export async function listRegistryHooks() {
+    const settings = await readSettings();
+    const out = [];
+    if (!settings.hooks)
+        return out;
+    for (const channel of REGISTRY_CHANNELS) {
+        const blocks = settings.hooks[channel];
+        if (!blocks?.length)
+            continue;
+        for (const b of blocks) {
+            for (const h of b.hooks ?? []) {
+                if (!h[HOOK_SLUG_MARKER])
+                    continue;
+                out.push({
+                    channel,
+                    matcher: b.matcher ?? null,
+                    slug: h[HOOK_SLUG_MARKER],
+                    command: h.command,
+                    timeout: h.timeout ?? null,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Foreign (user-authored) hooks living alongside our managed entries.
+ * Surfaced by `prave hooks audit` as informational context — never
+ * touched by any of the write helpers above.
+ */
+export async function listForeignHooks() {
+    const settings = await readSettings();
+    const out = [];
+    if (!settings.hooks)
+        return out;
+    for (const channel of REGISTRY_CHANNELS) {
+        const blocks = settings.hooks[channel];
+        if (!blocks?.length)
+            continue;
+        for (const b of blocks) {
+            for (const h of b.hooks ?? []) {
+                if (h[HOOK_MARKER])
+                    continue;
+                out.push({ channel, matcher: b.matcher ?? null, command: h.command });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Detect duplicate-coverage collisions inside the registry: two
+ * different prave-managed slugs writing to the same
+ * (channel, matcher) pair. The audit command surfaces these so the
+ * user can manually decide which one to keep.
+ */
+export function detectCollisions(installed) {
+    const buckets = new Map();
+    for (const h of installed) {
+        const key = `${h.channel}|${h.matcher ?? '*'}`;
+        const list = buckets.get(key) ?? [];
+        list.push(h.slug);
+        buckets.set(key, list);
+    }
+    const out = [];
+    for (const [key, slugs] of buckets) {
+        if (slugs.length < 2)
+            continue;
+        const parts = key.split('|');
+        const channel = parts[0];
+        const matcher = parts[1] === '*' ? null : (parts[1] ?? null);
+        out.push({ channel, matcher, slugs });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.4.15",
+  "version": "1.6.0",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -54,7 +54,7 @@
     "ora": "^8.0.1",
     "tar": "^7.4.3",
     "undici": "^6.18.0",
-    "@prave/shared": "1.4.15"
+    "@prave/shared": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",