peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/hooks-commands.js

@@ -1,14 +1,33 @@
+/**
+ * `peaks hooks *` — the Peaks-managed hook entry in the adapter's settings.json.
+ *
+ * The `install` verb and the hook-script distribution stay in this file because
+ * three source-scanning guards pin file-level facts to this exact path:
+ *
+ *   - `tests/unit/cli/ide-option-help-lists-the-registry.test.ts` needs an
+ *     `--ide` option declaration here whose help is derived from the registry;
+ *   - `tests/unit/runtime/vendor-neutral-identity-guard.test.ts` pins the two
+ *     user-global Claude Code skill-bridge copy targets to this file
+ *     (`settingsPaths: 2` in its `KNOWN_DEBT` census);
+ *   - `tests/unit/hooks/gate-enforce-machine-local-shell.test.ts` scans this
+ *     file for the CJS module-directory global, because this is where the hook
+ *     script sources are resolved.
+ *
+ * The other verbs live beside it: `hooks-uninstall-command.ts`,
+ * `hooks-status-command.ts`, the two install envelopes in
+ * `hooks-install-envelopes.ts`, and the scope / IDE resolution in
+ * `hooks-command-shared.ts`.
+ */
 import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall, listSuperpowersDenyEntries } from '../../services/skills/hooks-settings-service.js';
-import { resolveHookEntries, resolveHookSpec } from '../../services/skills/hooks-codegate-superpowers.js';
-import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
-import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
 import { resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
+import { fail } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { resolveIdeForCommand, resolveProjectRoot, resolveScope } from './hooks-command-shared.js';
+import { printInstallApplied, printInstallDryRun } from './hooks-install-envelopes.js';
+import { registerHooksStatusCommand } from './hooks-status-command.js';
+import { registerHooksUninstallCommand } from './hooks-uninstall-command.js';
 /**
  * This module's own directory — `<root>/src/cli/commands` in the source tree,
  * `<root>/dist/cli/commands` in a build. Same reason as
@@ -19,73 +38,17 @@ import { resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
  * `process.argv[1]` names a different file per entry point.
  */
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
-function resolveScope(options) {
-    return options.global ? 'global' : 'project';
-}
-function resolveProjectRoot(scope, project) {
-    return scope === 'project'
-        ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd())
-        : undefined;
-}
-/**
- * Resolve the IDE the install should target. The CLI user can override with
- * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
- * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
- * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks hooks
- * install` is not invoked from inside an IDE hook — there's no stdin payload.
- */
-function resolveIdeForCommand(options, projectRoot) {
-    if (options.ide !== undefined && options.ide.length > 0) {
-        return options.ide;
-    }
-    return detectIdeFromContext({
-        env: process.env,
-        cwd: projectRoot ?? process.cwd(),
-        parsedStdin: null
-    });
-}
 /**
- * Slice #014: compute the per-IDE peaks hook entries for the install /
- * dry-run RESPONSE SUMMARY. This is the *desired* shape (what the install
- * WOULD write), not what is on disk. The status command uses a different
- * helper (`readInstalledEntriesFromSettings`) that reads the actual
- * settings.json.
+ * `src/services/hooks/pre-tool-superpowers-bridge.sh` from the peaks-loop repo
+ * into the user-global `<userHome>/.claude/skills/peaks-code/hooks/` directory.
+ * The user-global copy is treated as a build artifact: it MUST be
+ * byte-identical to the repo source after install, and the source of truth is
+ * the repo file.
  *
- * After slice #014 only the gate-enforce entry is ever installed
- * (the legacy progress-start surface is gone). The summary mirrors
- * the install shape so the JSON envelope doesn't claim a hook the
- * service did not write.
- */
-function listExpectedEntriesForIde(ide, _skipProgress = false) {
-    // Derived from `resolveHookEntries(ide)` — the same function `planHookInstall`
-    // / `applyHookInstall` write from — so the summary can only ever report a
-    // shape the install actually produces. The previous version was a
-    // hand-written literal under a comment claiming it "mirrors the install
-    // shape, NOT a hardcoded expected list" (diagnosis 2026-09-15, C4); the
-    // literal had drifted from that claim in both directions: it re-typed the
-    // code-gate matcher instead of reading `HOOK_CODE_GATE_MATCHER`, and it
-    // reported 2 of the 6 entries a claude-code install writes.
-    //
-    // The filter is the tool-call event. `resolveHookEntries` also returns the
-    // once-per-session SessionStart / PostCompact entries; those are not what a
-    // per-call hook-entry summary is read for, and leaving them out is the only
-    // place this summary is narrower than the install.
-    const event = resolveHookSpec(ide).hookEnforceEvent;
-    return resolveHookEntries(ide, _skipProgress)
-        .filter((entry) => entry.event === event)
-        .map((entry) => ({ matcher: entry.matcher, sentinel: entry.sentinel }));
-}
-/**
- * superpowers-bridge hook source from the peaks-loop repo
- * (src/services/hooks/pre-tool-superpowers-bridge.sh) into the user-global
- * `<userHome>/.claude/skills/peaks-code/hooks/` directory. The user-global
- * copy is treated as a build artifact: it MUST be byte-identical to the
- * repo source after install, and the source of truth is the repo file.
- *
- * Why this lives in the install command: the install is the single
- * declared surface where the user-global directory is touched. Adding it
- * here keeps the "hooks only ship from src/services/hooks/" invariant
- * (G10 / AC10) — no other code path writes to `~/.claude/skills/peaks-code/hooks/`.
+ * Why this lives in the install command: the install is the single declared
+ * surface where the user-global directory is touched. Adding it here keeps the
+ * "hooks only ship from src/services/hooks/" invariant (G10 / AC10) — no other
+ * code path writes to `~/.claude/skills/peaks-code/hooks/`.
  *
  * Failure modes:
  *   - Source file missing (build not run yet) → silently skip and emit a
@@ -100,49 +63,6 @@ function listExpectedEntriesForIde(ide, _skipProgress = false) {
  * Returns `{ copied, source, target }` so the install envelope can report
  * it without forcing the caller to inspect the filesystem.
  */
-/**
- * `permissions.deny` block from a settings.json object and return
- * every peaks-managed entry currently present. Used by `hooks status`
- * to surface Layer 3 governance state without forcing the caller to
- * re-read the file. Tolerant of missing / malformed `permissions` —
- * a missing field returns an empty array, never throws.
- */
-function readOnDiskDenyEntries(settings) {
-    const permissions = settings.permissions;
-    if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions))
-        return [];
-    const deny = permissions.deny;
-    if (!Array.isArray(deny))
-        return [];
-    return deny.filter((d) => typeof d === 'string');
-}
-/**
- * One `nextActions` line for a hook-script copy, or `null` when there is
- * nothing to say.
- *
- * Diagnosis 2026-09-15 (C7): the copy failure used to be reported as a single
- * sentence — `'<x> hook not copied (source missing or non-global scope)'` —
- * which merged a real build failure into the expected project-scope no-op.
- * Only `scope === 'global'` copies these scripts at all (see the call sites),
- * so in project scope the sentence described normal behaviour in the wording
- * of a fault, and a healthy `peaks hooks install` read as broken.
- *
- * Scope is therefore what decides the sentence, and it is knowable here — the
- * copy helper cannot tell the two cases apart because both return
- * `copied: false`, but the caller can. Project scope emits no line: there is
- * no action to take, and the envelope's `bridgeHookCopy` / `codeGateHookCopy`
- * field still reports `copied: false` for anyone reading the JSON.
- */
-function describeHookCopy(label, copy, scope, dryRun) {
-    if (scope !== 'global')
-        return null;
-    if (copy.copied) {
-        return dryRun
-            ? `would copy ${label} from ${copy.source} to ${copy.target}`
-            : `Copied ${label}: ${copy.target}`;
-    }
-    return `${label} NOT copied — source missing at ${copy.source}. Run the build (\`pnpm build\`) so the script ships with the package.`;
-}
 function copyBridgeHookIfPresent(userHome, dryRun = false) {
     const source = resolve(MODULE_DIR, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
     const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-superpowers-bridge.sh');
@@ -157,6 +77,7 @@ function copyBridgeHookIfPresent(userHome, dryRun = false) {
     return { copied: true, source, target };
 }
 /**
+ * The same distribution for the code-gate hook
  * source (`src/services/hooks/pre-tool-code-gate.sh`) into the user-
  * global peaks-code hooks dir, mirroring the bridge-hook copy. The
  * hook itself is vendor-neutral (no `claude` / `anthropic` strings in
@@ -178,6 +99,42 @@ function copyCodeGateHookIfPresent(userHome, dryRun = false) {
     copyFileSync(source, target);
     return { copied: true, source, target };
 }
+/** The `{ copied: false, source: '', target: '' }` a non-global scope reports. */
+const NO_COPY = { copied: false, source: '', target: '' };
+/**
+ * The two hook-script copies for this scope. Only a global install distributes
+ * them; a project install reports the no-op shape the envelope has always
+ * carried. In `--dry-run` the copies report what they WOULD do and write
+ * nothing — their target is the user's home directory.
+ */
+function hookScriptCopies(scope, dryRun) {
+    const home = process.env.USERPROFILE ?? process.env.HOME ?? '';
+    return {
+        bridgeCopy: scope === 'global' ? copyBridgeHookIfPresent(home, dryRun) : NO_COPY,
+        codeGateCopy: scope === 'global' ? copyCodeGateHookIfPresent(home, dryRun) : NO_COPY
+    };
+}
+function runHooksInstall(io, options) {
+    const scope = resolveScope(options);
+    const projectRoot = resolveProjectRoot(scope, options.project);
+    const ide = resolveIdeForCommand(options, projectRoot);
+    const skipProgress = options.progress === false;
+    const ctx = { scope, projectRoot, ide, skipProgress };
+    try {
+        const dryRun = options.dryRun === true;
+        const copies = hookScriptCopies(scope, dryRun);
+        if (dryRun) {
+            printInstallDryRun(io, options, ctx, copies);
+            return;
+        }
+        printInstallApplied(io, options, ctx, copies);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, ide, applied: false, skipProgress }, [message]), options.json);
+        process.exitCode = 1;
+    }
+}
 export function registerHooksCommands(program, io) {
     const hooks = program
         .command('hooks')
@@ -189,198 +146,7 @@ export function registerHooksCommands(program, io) {
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
         .option('--ide <id>', resolveIdeOptionHelp())
         .option('--dry-run', 'show what would change without writing')
-        .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => {
-        const scope = resolveScope(options);
-        const projectRoot = resolveProjectRoot(scope, options.project);
-        const ide = resolveIdeForCommand(options, projectRoot);
-        const skipProgress = options.progress === false;
-        try {
-            if (options.dryRun === true) {
-                const plan = planHookInstall(scope, projectRoot, { ide, skipProgress });
-                const dryRunEntries = listExpectedEntriesForIde(ide, skipProgress);
-                // `dryRun: true` — a --dry-run must not write anything, and these
-                // helpers' target is the user's home directory.
-                const bridgeCopy = scope === 'global'
-                    ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
-                    : { copied: false, source: '', target: '' };
-                // code-gate hook script. The runtime gate lives at
-                // `peaks code-gate --json` (registered as a PreToolUse entry
-                // in the install output); the script is the build artifact
-                // distributed alongside the bridge hook.
-                const codeGateCopy = scope === 'global'
-                    ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
-                    : { copied: false, source: '', target: '' };
-                printResult(io, ok('hooks.install', {
-                    ...plan,
-                    ide,
-                    applied: false,
-                    dryRun: true,
-                    skipProgress,
-                    entries: dryRunEntries,
-                    bridgeHookCopy: bridgeCopy,
-                    codeGateHookCopy: codeGateCopy,
-                    // Layer 3 deny entries the install WOULD write. The
-                    // dry-run branch never actually invokes
-                    // `applyHookInstall`, so the on-disk snapshot is not
-                    // consulted here — the list is the desired-state
-                    // constant for clarity in the JSON envelope.
-                    permissionsDenyEntries: listSuperpowersDenyEntries()
-                }, [], [
-                    `would install ${dryRunEntries.length} peaks-managed hook entries`,
-                    // Name the target file of every entry: the gate-enforce entry is
-                    // routed to the machine-local settings file (see
-                    // `resolveHookTargets`), so a summary that only listed
-                    // `settingsPath` + the entry names read as if it landed in the
-                    // committed, shared file.
-                    ...plan.entryTargets.map((entry) => `would write ${entry.matcher || '(no matcher)'} → ${entry.sentinel} to ${entry.settingsPath}`),
-                    `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
-                    describeHookCopy('bridge hook', bridgeCopy, scope, true),
-                    describeHookCopy('code-gate hook', codeGateCopy, scope, true)
-                ].filter((line) => line !== null)), options.json);
-                return;
-            }
-            const result = applyHookInstall(scope, projectRoot, { ide, skipProgress });
-            // Slice #3: build the per-IDE entries summary for the IDE the user
-            // targeted, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
-            // claude-code default). The summary is derived from the install's own
-            // entry table — see `listExpectedEntriesForIde`.
-            const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
-            // the install targets global scope, also copy the superpowers-bridge
-            // hook script from src/services/hooks/ to the user-global hooks
-            // directory. Project scope does not need this — project's
-            // .claude/skills/peaks-code is already a junction into the npm source.
-            const bridgeCopy = scope === 'global'
-                ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
-                : { copied: false, source: '', target: '' };
-            // code-gate hook script. The runtime gate lives at
-            // `peaks code-gate --json` (registered as a PreToolUse entry
-            // in the install output); the script is the build artifact
-            // distributed alongside the bridge hook.
-            const codeGateCopy = scope === 'global'
-                ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
-                : { copied: false, source: '', target: '' };
-            const nextActions = result.applied
-                ? [
-                    'Restart the IDE (or reload the workspace) so the hook entries take effect',
-                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`,
-                    // write alongside the hook install — single atomic write.
-                    `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
-                    describeHookCopy('bridge hook', bridgeCopy, scope, false),
-                    describeHookCopy('code-gate hook', codeGateCopy, scope, false)
-                ].filter((line) => line !== null)
-                : [describeHookCopy('bridge hook', bridgeCopy, scope, false)].filter((line) => line !== null);
-            // in the JSON envelope so downstream automation (audit / sc) can
-            // confirm Layer 3 was applied without re-reading the file. When
-            // the install is a no-op (`applied: false`) the deny block was
-            // already on disk from a prior install; we still emit the
-            // current desired list for symmetry with the dry-run envelope.
-            const denyEntries = listSuperpowersDenyEntries();
-            printResult(io, ok('hooks.install', {
-                ...result,
-                ide,
-                dryRun: false,
-                skipProgress,
-                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel })),
-                bridgeHookCopy: bridgeCopy,
-                codeGateHookCopy: codeGateCopy,
-                permissionsDenyApplied: result.applied,
-                permissionsDenyEntries: denyEntries
-            }, [], nextActions), options.json);
-        }
-        catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, ide, applied: false, skipProgress }, [message]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(hooks
-        .command('uninstall')
-        .description('Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.')
-        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
-        const scope = resolveScope(options);
-        const projectRoot = resolveProjectRoot(scope, options.project);
-        const ide = resolveIdeForCommand(options, projectRoot);
-        try {
-            const result = removeHookInstall(scope, projectRoot, { ide });
-            // bookkeeping. `permissionsDenyRemoved` mirrors `removed` (the
-            // service strips deny entries on the same atomic write that
-            // strips the hook entries; they share the same boolean).
-            printResult(io, ok('hooks.uninstall', {
-                ...result,
-                ide,
-                permissionsDenyRemoved: result.removed,
-                permissionsDenyEntries: listSuperpowersDenyEntries()
-            }), options.json);
-        }
-        catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [
-                message
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(hooks
-        .command('status')
-        .description('Report which peaks-managed hook entries are installed.')
-        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
-        .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
-        const scope = resolveScope(options);
-        const projectRoot = resolveProjectRoot(scope, options.project);
-        const ide = resolveIdeForCommand(options, projectRoot);
-        try {
-            const status = readHookStatus(scope, projectRoot, { ide });
-            // Slice #014: read the ACTUAL on-disk entries (post-install shape),
-            // not the IDE-EXPECTED list. Pre-#014 `listInstalledEntriesForIde`
-            // returned the expected list and reported `entries: [Bash, Task]`
-            // even when the file only had `Bash`. The new helper reads the
-            // file and reports whatever peaks-managed entries are present,
-            // including any legacy progress-start entry that a pre-#014
-            // install left behind.
-            const settingsPath = status.settingsPath;
-            const settings = existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
-            // The gate-enforce entry is materialized into the machine-local
-            // settings file (see `resolveHookTargets`), so the on-disk entry list
-            // must be read from both files or `status` would report it missing.
-            const localSettings = status.localSettingsPath !== undefined && existsSync(status.localSettingsPath)
-                ? readJsonObjectFile(status.localSettingsPath)
-                : {};
-            // entries actually on disk. We read the existing settings.json
-            // (above) and surface its `permissions.deny` block. Any entry
-            // that matches the current `SUPERPOWERS_DENIED_SKILLS` set is
-            // considered "peaks-managed"; user-written entries are passed
-            // through verbatim so the envelope reflects reality. The desired
-            // list is also included for parity with install / uninstall.
-            const onDiskDeny = readOnDiskDenyEntries(settings);
-            // `status` reports the state of the world; for an IDE that cannot host a
-            // hook the state of the world is "none, and none is possible". The exit
-            // code stays 0 (the query succeeded) and the payload carries the finding
-            // — `supportsHooks: false` on the data, plus a warning naming the IDE, so
-            // the negative fact is not confused with "supported IDE, nothing
-            // installed yet".
-            const warnings = status.supportsHooks
-                ? []
-                : [
-                    `IDE '${ide}' cannot host peaks hooks (no HOOK_COMMAND_BY_IDE entry); nothing can be installed for it, which is why none is.`
-                ];
-            printResult(io, ok('hooks.status', {
-                ...status,
-                ide,
-                entries: [
-                    ...readInstalledEntriesFromSettings(settings, ide),
-                    ...readInstalledEntriesFromSettings(localSettings, ide)
-                ],
-                permissionsDenyEntries: listSuperpowersDenyEntries(),
-                permissionsDenyOnDisk: onDiskDeny
-            }, warnings), options.json);
-        }
-        catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
-            process.exitCode = 1;
-        }
-    });
+        .option('--no-progress', 'skip the progress-start PreToolUse hook entry; install ONLY the gate-enforce entry')).action((options) => runHooksInstall(io, options));
+    registerHooksUninstallCommand(hooks, io);
+    registerHooksStatusCommand(hooks, io);
 }

package/dist/cli/commands/hooks-install-envelopes.d.ts

@@ -0,0 +1,6 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { HookCliOptions, HookScriptCopies, InstallContext } from './hooks-command-shared.js';
+/** The `--dry-run` envelope: what the install WOULD write, and nothing written. */
+export declare function printInstallDryRun(io: ProgramIO, options: HookCliOptions, ctx: InstallContext, copies: HookScriptCopies): void;
+/** The applying envelope: the install's own result plus the copies and the deny state. */
+export declare function printInstallApplied(io: ProgramIO, options: HookCliOptions, ctx: InstallContext, copies: HookScriptCopies): void;

package/dist/cli/commands/hooks-install-envelopes.js

@@ -0,0 +1,144 @@
+// src/cli/commands/hooks-install-envelopes.ts
+//
+// The two envelopes `peaks hooks install` renders: the `--dry-run` preview and
+// the applied result. Split out of `hooks-commands.ts`; the per-IDE entry
+// summary, the Layer 3 deny lines and every envelope key are unchanged. The
+// hook-script copies are computed by the caller (`hooks-commands.ts`, which owns
+// the two user-global paths) and handed in.
+import { listSuperpowersDenyEntries, planHookInstall, applyHookInstall } from '../../services/skills/hooks-settings-service.js';
+import { resolveHookEntries, resolveHookSpec } from '../../services/skills/hooks-codegate-superpowers.js';
+import { ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+/**
+ * Slice #014: compute the per-IDE peaks hook entries for the install /
+ * dry-run RESPONSE SUMMARY. This is the *desired* shape (what the install
+ * WOULD write), not what is on disk. The status command uses a different
+ * helper (`readInstalledEntriesFromSettings`) that reads the actual
+ * settings.json.
+ *
+ * After slice #014 only the gate-enforce entry is ever installed
+ * (the legacy progress-start surface is gone). The summary mirrors
+ * the install shape so the JSON envelope doesn't claim a hook the
+ * service did not write.
+ */
+function listExpectedEntriesForIde(ide, _skipProgress = false) {
+    // Derived from `resolveHookEntries(ide)` — the same function `planHookInstall`
+    // / `applyHookInstall` write from — so the summary can only ever report a
+    // shape the install actually produces. The previous version was a
+    // hand-written literal under a comment claiming it "mirrors the install
+    // shape, NOT a hardcoded expected list" (diagnosis 2026-09-15, C4); the
+    // literal had drifted from that claim in both directions: it re-typed the
+    // code-gate matcher instead of reading `HOOK_CODE_GATE_MATCHER`, and it
+    // reported 2 of the 6 entries a claude-code install writes.
+    //
+    // The filter is the tool-call event. `resolveHookEntries` also returns the
+    // once-per-session SessionStart / PostCompact entries; those are not what a
+    // per-call hook-entry summary is read for, and leaving them out is the only
+    // place this summary is narrower than the install.
+    const event = resolveHookSpec(ide).hookEnforceEvent;
+    return resolveHookEntries(ide, _skipProgress)
+        .filter((entry) => entry.event === event)
+        .map((entry) => ({ matcher: entry.matcher, sentinel: entry.sentinel }));
+}
+/**
+ * One `nextActions` line for a hook-script copy, or `null` when there is
+ * nothing to say.
+ *
+ * Diagnosis 2026-09-15 (C7): the copy failure used to be reported as a single
+ * sentence — `'<x> hook not copied (source missing or non-global scope)'` —
+ * which merged a real build failure into the expected project-scope no-op.
+ * Only `scope === 'global'` copies these scripts at all (see the call sites),
+ * so in project scope the sentence described normal behaviour in the wording
+ * of a fault, and a healthy `peaks hooks install` read as broken.
+ *
+ * Scope is therefore what decides the sentence, and it is knowable here — the
+ * copy helper cannot tell the two cases apart because both return
+ * `copied: false`, but the caller can. Project scope emits no line: there is
+ * no action to take, and the envelope's `bridgeHookCopy` / `codeGateHookCopy`
+ * field still reports `copied: false` for anyone reading the JSON.
+ */
+function describeHookCopy(label, copy, scope, dryRun) {
+    if (scope !== 'global')
+        return null;
+    if (copy.copied) {
+        return dryRun
+            ? `would copy ${label} from ${copy.source} to ${copy.target}`
+            : `Copied ${label}: ${copy.target}`;
+    }
+    return `${label} NOT copied — source missing at ${copy.source}. Run the build (\`pnpm build\`) so the script ships with the package.`;
+}
+/** The `--dry-run` envelope: what the install WOULD write, and nothing written. */
+export function printInstallDryRun(io, options, ctx, copies) {
+    const plan = planHookInstall(ctx.scope, ctx.projectRoot, {
+        ide: ctx.ide,
+        skipProgress: ctx.skipProgress
+    });
+    const dryRunEntries = listExpectedEntriesForIde(ctx.ide, ctx.skipProgress);
+    const { bridgeCopy, codeGateCopy } = copies;
+    printResult(io, ok('hooks.install', {
+        ...plan,
+        ide: ctx.ide,
+        applied: false,
+        dryRun: true,
+        skipProgress: ctx.skipProgress,
+        entries: dryRunEntries,
+        bridgeHookCopy: bridgeCopy,
+        codeGateHookCopy: codeGateCopy,
+        // Layer 3 deny entries the install WOULD write. The
+        // dry-run branch never actually invokes
+        // `applyHookInstall`, so the on-disk snapshot is not
+        // consulted here — the list is the desired-state
+        // constant for clarity in the JSON envelope.
+        permissionsDenyEntries: listSuperpowersDenyEntries()
+    }, [], [
+        `would install ${dryRunEntries.length} peaks-managed hook entries`,
+        // Name the target file of every entry: the gate-enforce entry is
+        // routed to the machine-local settings file (see
+        // `resolveHookTargets`), so a summary that only listed
+        // `settingsPath` + the entry names read as if it landed in the
+        // committed, shared file.
+        ...plan.entryTargets.map((entry) => `would write ${entry.matcher || '(no matcher)'} → ${entry.sentinel} to ${entry.settingsPath}`),
+        `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
+        describeHookCopy('bridge hook', bridgeCopy, ctx.scope, true),
+        describeHookCopy('code-gate hook', codeGateCopy, ctx.scope, true)
+    ].filter((line) => line !== null)), options.json);
+}
+/** The applying envelope: the install's own result plus the copies and the deny state. */
+export function printInstallApplied(io, options, ctx, copies) {
+    const result = applyHookInstall(ctx.scope, ctx.projectRoot, {
+        ide: ctx.ide,
+        skipProgress: ctx.skipProgress
+    });
+    // Slice #3: build the per-IDE entries summary for the IDE the user
+    // targeted, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
+    // claude-code default). The summary is derived from the install's own
+    // entry table — see `listExpectedEntriesForIde`.
+    const installedEntries = listExpectedEntriesForIde(ctx.ide, ctx.skipProgress);
+    const { bridgeCopy, codeGateCopy } = copies;
+    const nextActions = result.applied
+        ? [
+            'Restart the IDE (or reload the workspace) so the hook entries take effect',
+            `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`,
+            // write alongside the hook install — single atomic write.
+            `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
+            describeHookCopy('bridge hook', bridgeCopy, ctx.scope, false),
+            describeHookCopy('code-gate hook', codeGateCopy, ctx.scope, false)
+        ].filter((line) => line !== null)
+        : [describeHookCopy('bridge hook', bridgeCopy, ctx.scope, false)].filter((line) => line !== null);
+    // in the JSON envelope so downstream automation (audit / sc) can
+    // confirm Layer 3 was applied without re-reading the file. When
+    // the install is a no-op (`applied: false`) the deny block was
+    // already on disk from a prior install; we still emit the
+    // current desired list for symmetry with the dry-run envelope.
+    printResult(io, ok('hooks.install', {
+        ...result,
+        ide: ctx.ide,
+        dryRun: false,
+        skipProgress: ctx.skipProgress,
+        entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel })),
+        bridgeHookCopy: bridgeCopy,
+        codeGateHookCopy: codeGateCopy,
+        permissionsDenyApplied: result.applied,
+        permissionsDenyEntries: listSuperpowersDenyEntries()
+    }, [], nextActions), options.json);
+}

package/dist/cli/commands/hooks-status-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerHooksStatusCommand(hooks: Command, io: ProgramIO): void;