peaks-loop 4.1.2 → 4.1.4

package/dist/services/readonly-surface/whitelist-generator.d.ts

@@ -0,0 +1,64 @@
+import type { Command } from 'commander';
+import { z } from 'zod';
+import { type ReadOnlyWhitelist } from './readonly-whitelist.js';
+/** The hand-authored input, relative to the package root. */
+export declare const READONLY_SURFACE_RELATIVE_PATH = "contracts/readonly-surface.json";
+/** The schema version of the artifact this module emits. */
+export declare const READONLY_WHITELIST_SCHEMA_VERSION = 1;
+declare const SurfaceEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    commandPath: z.ZodArray<z.ZodString>;
+    argv: z.ZodArray<z.ZodString>;
+    params: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            enum: "enum";
+            path: "path";
+            token: "token";
+            slug: "slug";
+            integer: "integer";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ReadOnlySurfaceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    readOnlyDefinition: z.ZodString;
+    note: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tools: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        entries: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            commandPath: z.ZodArray<z.ZodString>;
+            argv: z.ZodArray<z.ZodString>;
+            params: z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodEnum<{
+                    enum: "enum";
+                    path: "path";
+                    token: "token";
+                    slug: "slug";
+                    integer: "integer";
+                }>;
+                pattern: z.ZodOptional<z.ZodString>;
+                values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                min: z.ZodOptional<z.ZodNumber>;
+                max: z.ZodOptional<z.ZodNumber>;
+                default: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReadOnlySurface = z.infer<typeof ReadOnlySurfaceSchema>;
+export type ReadOnlySurfaceEntry = z.infer<typeof SurfaceEntrySchema>;
+/** Build the artifact object from a surface declaration and a live program. */
+export declare function generateReadOnlyWhitelist(surface: ReadOnlySurface, program: Command): ReadOnlyWhitelist;
+/** Byte-stable serialization: two runs over the same input MUST match. */
+export declare function serializeReadOnlyWhitelist(whitelist: ReadOnlyWhitelist): string;
+/** Read + validate the hand-authored surface declaration. */
+export declare function loadReadOnlySurface(root?: string): ReadOnlySurface;
+/** Absolute path of the generated artifact. */
+export declare function readonlyWhitelistPath(root?: string): string;
+export {};

package/dist/services/readonly-surface/whitelist-generator.js

@@ -0,0 +1,212 @@
+/**
+ * The schema introspector (spec §3 row 2): turns the hand-authored surface
+ * declaration into the generated whitelist artifact by READING the live Commander
+ * registry - never by restating it.
+ *
+ * Everything the registry can answer is taken from it:
+ *   - does the command path exist,
+ *   - does each `--flag` in the template exist on that command,
+ *   - is that flag mandatory, and does it take a value,
+ *   - which positionals does the command declare, and are they required.
+ * A template that disagrees with the registry is a BUILD FAILURE, not a warning:
+ * that is the whole point of generating the artifact instead of typing it.
+ *
+ * What the registry CANNOT answer is the constraint on a placeholder's value
+ * (`^[a-z0-9-]+$` for a request id). Those constraints come from the surface file
+ * and are marked `constraintSource: 'handwritten'`, so the one place drift can
+ * enter is visible in the artifact. When a command later declares `.choices()`,
+ * the same field flips to `introspected` with no artifact edit.
+ *
+ * DETERMINISM: no timestamps, no `Date`, no unordered iteration. Record
+ * keys follow argv order and entries follow the surface file's order, so two
+ * consecutive runs are byte-identical.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { repoRoot } from 'peaks-loop-shared/paths';
+import { READONLY_WHITELIST_RELATIVE_PATH } from './readonly-whitelist.js';
+/** The hand-authored input, relative to the package root. */
+export const READONLY_SURFACE_RELATIVE_PATH = 'contracts/readonly-surface.json';
+/** The schema version of the artifact this module emits. */
+export const READONLY_WHITELIST_SCHEMA_VERSION = 1;
+const SurfaceParamSchema = z.object({
+    type: z.enum(['slug', 'enum', 'token', 'integer', 'path']),
+    pattern: z.string().min(1).optional(),
+    values: z.array(z.string().min(1)).min(1).optional(),
+    min: z.number().int().optional(),
+    max: z.number().int().optional(),
+    default: z.number().int().optional()
+});
+const SurfaceEntrySchema = z.object({
+    id: z.string().min(1),
+    commandPath: z.array(z.string().min(1)).min(1),
+    argv: z.array(z.string().min(1)).min(1),
+    params: z.record(z.string(), SurfaceParamSchema)
+});
+export const ReadOnlySurfaceSchema = z.object({
+    schemaVersion: z.literal(1),
+    readOnlyDefinition: z.string().min(1),
+    note: z.array(z.string()).default([]),
+    tools: z.array(z.object({ tool: z.string().min(1), entries: z.array(SurfaceEntrySchema).min(1) }))
+});
+/** `<name>` marks a placeholder token in a surface `argv` element. */
+const PLACEHOLDER_TOKEN = /^<([a-z][a-z0-9-]*)>$/;
+class SurfaceDriftError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SurfaceDriftError';
+    }
+}
+function resolveCommand(program, path) {
+    let current = program;
+    for (const name of path) {
+        current = current.commands.find((candidate) => candidate.name() === name);
+        if (current === undefined) {
+            throw new SurfaceDriftError(`No command registered at path: ${path.join(' ')}`);
+        }
+    }
+    return current;
+}
+function hasOption(command, token) {
+    return command.options.some((option) => option.long === token || option.short === token);
+}
+function optionTakingValue(command, token) {
+    return command.options.find((option) => {
+        if (option.long !== token && option.short !== token)
+            return false;
+        return /[<[].+[>\]]/.test(option.flags);
+    });
+}
+/** Placeholders the registry supplies a constraint for are marked as such. */
+function constraintSourceOf(declared, option) {
+    if (declared.type === 'enum' && option?.argChoices !== undefined)
+        return 'introspected';
+    if (option?.defaultValue !== undefined && declared.default !== undefined)
+        return 'introspected';
+    return 'handwritten';
+}
+/** The constraint fields the surface declares, copied without inventing absent ones. */
+function constraintsOf(declared) {
+    return {
+        type: declared.type,
+        ...(declared.pattern === undefined ? {} : { pattern: declared.pattern }),
+        ...(declared.values === undefined ? {} : { values: declared.values }),
+        ...(declared.min === undefined ? {} : { min: declared.min }),
+        ...(declared.max === undefined ? {} : { max: declared.max }),
+        ...(declared.default === undefined ? {} : { default: declared.default })
+    };
+}
+/**
+ * Bind one placeholder either to the value-taking flag before it or to the next
+ * positional the command declares. Membership in the template is what makes a
+ * value required; `binding.required` carries the REGISTRY's opinion, which is a
+ * different fact (`--limit` is not mandatory, yet the template pins it).
+ */
+function bindPlaceholder(slot) {
+    const { entryId, name, declared, command, previousToken, cursor } = slot;
+    if (declared === undefined) {
+        throw new SurfaceDriftError(`Entry ${entryId}: placeholder <${name}> has no params spec`);
+    }
+    const boundOption = previousToken === undefined ? undefined : optionTakingValue(command, previousToken);
+    if (boundOption !== undefined && previousToken !== undefined) {
+        return {
+            ...constraintsOf(declared),
+            binding: { kind: 'option', token: previousToken, required: boundOption.mandatory },
+            constraintSource: constraintSourceOf(declared, boundOption)
+        };
+    }
+    const registered = command.registeredArguments[cursor.positionalIndex];
+    if (registered === undefined) {
+        throw new SurfaceDriftError(`Entry ${entryId}: <${name}> is positional ${cursor.positionalIndex + 1} but the command declares ${command.registeredArguments.length}`);
+    }
+    cursor.positionalIndex += 1;
+    cursor.positionalNames.push(registered.name());
+    return {
+        ...constraintsOf(declared),
+        binding: { kind: 'positional', token: registered.name(), required: registered.required },
+        constraintSource: 'handwritten'
+    };
+}
+/** The non-flag words a template opens with, which must be the command path. */
+function leadingLiteralsOf(argv) {
+    return argv.flatMap((segment) => segment.kind === 'literal' && !segment.value.startsWith('-') ? [segment.value] : []);
+}
+function assertTemplateDrivesCommand(surface, command, argv, cursor) {
+    const leading = leadingLiteralsOf(argv);
+    if (leading.join('\u0000') !== surface.commandPath.join('\u0000')) {
+        throw new SurfaceDriftError(`Entry ${surface.id}: argv opens with [${leading.join(', ')}] but commandPath is [${surface.commandPath.join(', ')}]`);
+    }
+    if (cursor.positionalIndex !== command.registeredArguments.length) {
+        throw new SurfaceDriftError(`Entry ${surface.id}: template fills ${cursor.positionalIndex} positional(s); ${surface.commandPath.join(' ')} declares ${command.registeredArguments.length}`);
+    }
+}
+function buildEntry(program, tool, surface) {
+    const command = resolveCommand(program, surface.commandPath);
+    const optionTokens = [];
+    const argv = [];
+    const params = {};
+    const cursor = { positionalIndex: 0, positionalNames: [] };
+    for (let index = 0; index < surface.argv.length; index += 1) {
+        const token = surface.argv[index];
+        if (token === undefined)
+            continue;
+        const placeholder = PLACEHOLDER_TOKEN.exec(token);
+        const name = placeholder?.[1];
+        if (placeholder !== null && name !== undefined) {
+            params[name] = bindPlaceholder({
+                entryId: surface.id,
+                name,
+                declared: surface.params[name],
+                command,
+                previousToken: index > 0 ? surface.argv[index - 1] : undefined,
+                cursor
+            });
+            argv.push({ kind: 'param', name });
+            continue;
+        }
+        if (token.startsWith('-')) {
+            if (!hasOption(command, token)) {
+                throw new SurfaceDriftError(`Entry ${surface.id}: no such option ${token} on ${surface.commandPath.join(' ')}`);
+            }
+            optionTokens.push(token);
+        }
+        argv.push({ kind: 'literal', value: token });
+    }
+    assertTemplateDrivesCommand(surface, command, argv, cursor);
+    return {
+        id: surface.id,
+        tool,
+        commandPath: [...surface.commandPath],
+        argv,
+        params,
+        introspection: { optionTokens, positionalCount: cursor.positionalNames.length }
+    };
+}
+/** Build the artifact object from a surface declaration and a live program. */
+export function generateReadOnlyWhitelist(surface, program) {
+    const entries = surface.tools.flatMap((group) => group.entries.map((entry) => buildEntry(program, group.tool, entry)));
+    const ids = new Set(entries.map((entry) => entry.id));
+    if (ids.size !== entries.length) {
+        throw new SurfaceDriftError('Entry ids must be unique across the whole surface');
+    }
+    return {
+        schemaVersion: READONLY_WHITELIST_SCHEMA_VERSION,
+        source: READONLY_SURFACE_RELATIVE_PATH,
+        readOnlyDefinition: surface.readOnlyDefinition,
+        entries
+    };
+}
+/** Byte-stable serialization: two runs over the same input MUST match. */
+export function serializeReadOnlyWhitelist(whitelist) {
+    return `${JSON.stringify(whitelist, null, 2)}\n`;
+}
+/** Read + validate the hand-authored surface declaration. */
+export function loadReadOnlySurface(root = repoRoot) {
+    const text = readFileSync(join(root, READONLY_SURFACE_RELATIVE_PATH), 'utf8');
+    return ReadOnlySurfaceSchema.parse(JSON.parse(text));
+}
+/** Absolute path of the generated artifact. */
+export function readonlyWhitelistPath(root = repoRoot) {
+    return join(root, READONLY_WHITELIST_RELATIVE_PATH);
+}

package/dist/services/skills/hooks-codegate-superpowers.d.ts

@@ -15,6 +15,7 @@ interface ResolvedHookSpec {
     readonly hookEnforceSentinel: string;
     readonly hookEnforceMatcher: string;
     readonly hookEnforceEvent: string;
+    readonly hookEnforceMcpMatcher: string | undefined;
     /**
      * True when the gate-enforce entry must be materialized into the IDE's
      * MACHINE-LOCAL settings file rather than the shared one (see

package/dist/services/skills/hooks-codegate-superpowers.js

@@ -8,6 +8,7 @@
  * type contract re-exported by the caller.
  */
 import { getAdapter } from '../ide/ide-registry.js';
+import { mcpHookMatcher } from '../ide/mcp-tool-matcher.js';
 import { HOOK_COMPACT_SETTLE_COMMAND, HOOK_COMPACT_SETTLE_EVENT, HOOK_COMPACT_SETTLE_MATCHER, HOOK_COMPACT_SETTLE_SENTINEL, HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_SENTINEL, HOOK_POST_COMPACT_REINJECT_COMMAND, HOOK_POST_COMPACT_REINJECT_EVENT, HOOK_POST_COMPACT_REINJECT_MATCHER, HOOK_POST_COMPACT_REINJECT_SENTINEL, HOOK_WORKSPACE_INIT_COMMAND, HOOK_WORKSPACE_INIT_EVENT, HOOK_WORKSPACE_INIT_SENTINEL } from './session-start-hook-constants.js';
 /** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
@@ -87,6 +88,7 @@ export function resolveHookSpec(ide) {
         hookEnforceSentinel: spec.sentinel,
         hookEnforceMatcher: adapter.toolMatcher,
         hookEnforceEvent: adapter.hookEvent,
+        hookEnforceMcpMatcher: mcpHookMatcher(adapter),
         // Only Claude Code has the machine-local sibling settings file the
         // routing depends on, and only Claude Code's hook schema accepts a
         // `shell` key.
@@ -105,6 +107,27 @@ export const HOOK_CODE_GATE_SENTINEL = 'peaks code-gate';
 export const HOOK_CODE_GATE_MATCHER = 'Edit|Write|MultiEdit';
 export const HOOK_CODE_GATE_EVENT = 'PreToolUse';
 export const HOOK_CODE_GATE_COMMAND = `peaks code-gate --json`;
+/**
+ * The read-only MCP surface as a hook entry: the same command under the
+ * adapter's MCP matcher, or `undefined` for a harness that declares no MCP
+ * naming. A hook fires only for the matchers its OWN entry names, so without this
+ * entry the fail-closed branch in `mcp-surface-gate.ts` never runs on a live
+ * harness. A second entry rather than a wider matcher on the Bash one: that entry
+ * is mirrored by the workspace-init template, and widening it would put installer
+ * and template out of step.
+ */
+function mcpMatcherEntry(spec) {
+    if (spec.hookEnforceMcpMatcher === undefined)
+        return undefined;
+    return {
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMcpMatcher,
+        command: spec.hookEnforceCommand,
+        event: spec.hookEnforceEvent,
+        machineLocal: spec.hookEnforceMachineLocal,
+        ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
+    };
+}
 export function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
     const entries = [
@@ -117,6 +140,9 @@ export function resolveHookEntries(ide, _skipProgress = false) {
             ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
         }
     ];
+    const mcpEntry = mcpMatcherEntry(spec);
+    if (mcpEntry !== undefined)
+        entries.push(mcpEntry);
     // ── Why the three SessionStart entries below carry NO `shell` pin ─────────
     //
     // The gate-enforce entry above is shell-pinned on Windows (see

package/dist/services/skills/hooks-settings-deny-list.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Merge the peaks-managed Skill denylist into the existing settings object.
+ * Preserves every other `permissions.deny` entry the user (or another tool)
+ * has written so the install is additive, not destructive. The output is
+ * always deterministic: the same input always yields the same output,
+ * regardless of insertion order in the source array.
+ *
+ * Defensive behavior:
+ * - `settings.permissions` is missing or non-object → install creates a
+ *   fresh `permissions: { deny: [...our entries] }` object.
+ * - `settings.permissions.deny` is missing or non-array → install replaces
+ *   the field with a fresh array containing only our entries.
+ * - Duplicate entries (any source) are collapsed to one via `new Set`.
+ *
+ * The function is pure: it does not mutate the input. Atomic write happens
+ * at the call site (`applyHookInstall`).
+ */
+export declare function withSuperpowersSkillDenylist(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Inverse of `withSuperpowersSkillDenylist`. Removes every peaks-managed
+ * `UseSkill(...)` entry from the deny list. If the resulting deny list is
+ * empty, the `deny` field itself is deleted; if the `permissions` object
+ * becomes empty, the `permissions` field itself is deleted. This is the
+ * uninstall path: every field we wrote must be removed exactly, and no
+ * other field may be touched.
+ *
+ * Pure (no mutation).
+ */
+export declare function withoutSuperpowersSkillDenylist(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Read-only introspection. Returns the deny entries that `peaks hooks
+ * install` would write today. Useful for `peaks hooks status` and the
+ * dry-run envelope.
+ */
+export declare function listSuperpowersDenyEntries(): ReadonlyArray<string>;
+/**
+ *
+ * In addition to the static SUPERPOWERS_DENIED_SKILLS list, peaks
+ * scans the existing settings file for "trigger phrases" that
+ * indicate the user has configured the superpowers chain (or
+ * any other auto-run worktree-creating tool) and appends a
+ * defensive deny to prevent the chain from running raw
+ * `git worktree add` (or `podman run`) directly.
+ *
+ * Triggers detected (substring match on the existing
+ * permissions.deny / permissions.allow list):
+ *
+ *  - `superpowers:using-git-worktrees` — the chain's ground zero
+ *  - `superpowers:brainstorming` etc. — the upstream skill
+ *  - `Bash(git worktree add` — the user has explicitly
+ *    allowed raw git worktree, which our L2 lease-aware gate
+ *    would also intercept (defense in depth)
+ *
+ * Append-only — never replaces, never re-orders, never removes
+ * existing entries. Idempotent: re-running the install with
+ * the same input yields the same output.
+ */
+export declare const TRIGGER_PHRASES: ReadonlyArray<string>;
+export declare function withTriggeredDenyList(settings: Record<string, unknown>): Record<string, unknown>;
+/** Inverse of withTriggeredDenyList: strip every deny-trigger entry. */
+export declare function withoutTriggeredDenyList(settings: Record<string, unknown>): Record<string, unknown>;

package/dist/services/skills/hooks-settings-deny-list.js

@@ -0,0 +1,173 @@
+/**
+ * The peaks-managed `permissions.deny` entries, and their inverses.
+ *
+ * Split out of `hooks-settings-service.ts` (file-size cap campaign). The
+ * service re-exports every name declared here, so existing importers keep
+ * using `./hooks-settings-service.js` unchanged.
+ */
+import { SUPERPOWERS_DENIED_SKILLS, SUPERPOWERS_DENY_SENTINELS, formatSuperpowersDenyEntry } from './hooks-codegate-superpowers.js';
+/**
+ * Merge the peaks-managed Skill denylist into the existing settings object.
+ * Preserves every other `permissions.deny` entry the user (or another tool)
+ * has written so the install is additive, not destructive. The output is
+ * always deterministic: the same input always yields the same output,
+ * regardless of insertion order in the source array.
+ *
+ * Defensive behavior:
+ * - `settings.permissions` is missing or non-object → install creates a
+ *   fresh `permissions: { deny: [...our entries] }` object.
+ * - `settings.permissions.deny` is missing or non-array → install replaces
+ *   the field with a fresh array containing only our entries.
+ * - Duplicate entries (any source) are collapsed to one via `new Set`.
+ *
+ * The function is pure: it does not mutate the input. Atomic write happens
+ * at the call site (`applyHookInstall`).
+ */
+export function withSuperpowersSkillDenylist(settings) {
+    const ourEntries = SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry);
+    const permissions = settings.permissions &&
+        typeof settings.permissions === 'object' &&
+        !Array.isArray(settings.permissions)
+        ? settings.permissions
+        : {};
+    const existingDeny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    const otherDeny = existingDeny.filter((d) => !SUPERPOWERS_DENY_SENTINELS.has(d));
+    const finalDeny = [...new Set([...otherDeny, ...ourEntries])];
+    return {
+        ...settings,
+        permissions: { ...permissions, deny: finalDeny }
+    };
+}
+/**
+ * Inverse of `withSuperpowersSkillDenylist`. Removes every peaks-managed
+ * `UseSkill(...)` entry from the deny list. If the resulting deny list is
+ * empty, the `deny` field itself is deleted; if the `permissions` object
+ * becomes empty, the `permissions` field itself is deleted. This is the
+ * uninstall path: every field we wrote must be removed exactly, and no
+ * other field may be touched.
+ *
+ * Pure (no mutation).
+ */
+export function withoutSuperpowersSkillDenylist(settings) {
+    const permissions = settings.permissions &&
+        typeof settings.permissions === 'object' &&
+        !Array.isArray(settings.permissions)
+        ? settings.permissions
+        : {};
+    if (!Array.isArray(permissions.deny)) {
+        return settings;
+    }
+    const remainingDeny = permissions.deny
+        .filter((d) => typeof d === 'string')
+        .filter((d) => !SUPERPOWERS_DENY_SENTINELS.has(d));
+    const nextPermissions = { ...permissions };
+    if (remainingDeny.length > 0) {
+        nextPermissions.deny = remainingDeny;
+    }
+    else {
+        delete nextPermissions.deny;
+    }
+    if (Object.keys(nextPermissions).length === 0) {
+        // The whole `permissions` object is empty (no deny, no allow, no other
+        // sub-fields). Drop it to avoid leaving an empty object on disk.
+        const rest = { ...settings };
+        delete rest['permissions'];
+        return rest;
+    }
+    return { ...settings, permissions: nextPermissions };
+}
+/**
+ * Read-only introspection. Returns the deny entries that `peaks hooks
+ * install` would write today. Useful for `peaks hooks status` and the
+ * dry-run envelope.
+ */
+export function listSuperpowersDenyEntries() {
+    return SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry);
+}
+/**
+ *
+ * In addition to the static SUPERPOWERS_DENIED_SKILLS list, peaks
+ * scans the existing settings file for "trigger phrases" that
+ * indicate the user has configured the superpowers chain (or
+ * any other auto-run worktree-creating tool) and appends a
+ * defensive deny to prevent the chain from running raw
+ * `git worktree add` (or `podman run`) directly.
+ *
+ * Triggers detected (substring match on the existing
+ * permissions.deny / permissions.allow list):
+ *
+ *  - `superpowers:using-git-worktrees` — the chain's ground zero
+ *  - `superpowers:brainstorming` etc. — the upstream skill
+ *  - `Bash(git worktree add` — the user has explicitly
+ *    allowed raw git worktree, which our L2 lease-aware gate
+ *    would also intercept (defense in depth)
+ *
+ * Append-only — never replaces, never re-orders, never removes
+ * existing entries. Idempotent: re-running the install with
+ * the same input yields the same output.
+ */
+export const TRIGGER_PHRASES = Object.freeze([
+    'superpowers:using-git-worktrees',
+    'superpowers:brainstorming',
+    'superpowers:writing-plans',
+    'superpowers:subagent-driven-development',
+    'Bash(git worktree add',
+    'Bash(podman run'
+]);
+/**
+ * Format a trigger-phrase into a stable `Edit` deny entry. We deny
+ * `Edit` (not `Bash`) on the *settings file* itself, so the
+ * user cannot edit the trigger away without an explicit
+ * `peaks hooks uninstall` first. The skill name (when
+ * applicable) is the value after the colon.
+ */
+function formatTriggerDenyEntry(phrase) {
+    return `Edit(deny-trigger:${phrase})`;
+}
+export function withTriggeredDenyList(settings) {
+    const existingDeny = Array.isArray(settings.permissions?.deny)
+        ? settings.permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    // Detect triggers in the existing allow + deny lists.
+    const existingAllow = Array.isArray(settings.permissions?.allow)
+        ? settings.permissions.allow.filter((d) => typeof d === 'string')
+        : [];
+    const haystack = [...existingDeny, ...existingAllow].join('|');
+    const triggered = TRIGGER_PHRASES.filter((p) => haystack.includes(p));
+    if (triggered.length === 0)
+        return settings;
+    const triggeredEntries = triggered.map(formatTriggerDenyEntry);
+    const permissions = settings.permissions &&
+        typeof settings.permissions === 'object' &&
+        !Array.isArray(settings.permissions)
+        ? settings.permissions
+        : {};
+    const otherDeny = existingDeny.filter((d) => !triggeredEntries.includes(d));
+    return {
+        ...settings,
+        permissions: { ...permissions, deny: [...new Set([...otherDeny, ...triggeredEntries])] }
+    };
+}
+/** Inverse of withTriggeredDenyList: strip every deny-trigger entry. */
+export function withoutTriggeredDenyList(settings) {
+    const permissions = settings.permissions &&
+        typeof settings.permissions === 'object' &&
+        !Array.isArray(settings.permissions)
+        ? settings.permissions
+        : {};
+    const existingDeny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    const kept = existingDeny.filter((d) => !d.startsWith('Edit(deny-trigger:'));
+    const next = { ...permissions, deny: kept };
+    if (kept.length === 0)
+        delete next.deny;
+    if (Object.keys(next).length === 0) {
+        const out = { ...settings };
+        delete out.permissions;
+        return out;
+    }
+    return { ...settings, permissions: next };
+}

package/dist/services/skills/hooks-settings-envelopes.d.ts

@@ -0,0 +1,20 @@
+import type { HookScope } from '../ide/shared/safe-path.js';
+import type { HookRemoveResult, HookStatus, HookTarget } from './hooks-settings-types.js';
+/** The uninstall envelope; a `localPath` is reported only when it is a distinct file. */
+export declare function removedResult(scope: HookScope, settingsPath: string, localPath: string | undefined, removed: boolean): HookRemoveResult;
+/**
+ * Strip every peaks-managed row from one target's file and write it back.
+ *
+ * The deny-list helpers run only on the SHARED settings file (the one that
+ * carries the committed `permissions.deny` block); the machine-local file
+ * carries hook entries plus, for Claude Code, the gate exemptions.
+ */
+export declare function applyRemovalToTarget(target: HookTarget, sentinels: ReadonlyArray<string>, isSharedFile: boolean): boolean;
+/**
+ * The status envelope for an IDE that can never carry a peaks hook: the query
+ * ran, the disk was read, and the honest reply is "nothing, and nothing ever
+ * will be".
+ */
+export declare function unsupportedHookStatus(scope: HookScope, settingsPath: string, localPath: string | undefined): HookStatus;
+/** The status envelope for a set of resolved targets. */
+export declare function hookStatusFromTargets(scope: HookScope, settingsPath: string, targets: ReadonlyArray<HookTarget>): HookStatus;

package/dist/services/skills/hooks-settings-envelopes.js

@@ -0,0 +1,79 @@
+/**
+ * The result envelopes the uninstall and status verbs return.
+ *
+ * Split out of `hooks-settings-service.ts` (file-size cap campaign). The
+ * service re-exports every name declared here, so existing importers keep
+ * using `./hooks-settings-service.js` unchanged.
+ */
+import { existsSync } from 'node:fs';
+import { atomicWriteJson } from '../ide/shared/atomic-json.js';
+import { withoutExternalGateExemptions } from './hooks-codegate-superpowers.js';
+import { withoutSuperpowersSkillDenylist, withoutTriggeredDenyList } from './hooks-settings-deny-list.js';
+import { isInstalledForEntries, readSettingsFile, stripPeaksEntries } from './hooks-settings-file-shape.js';
+/** The uninstall envelope; a `localPath` is reported only when it is a distinct file. */
+export function removedResult(scope, settingsPath, localPath, removed) {
+    return {
+        scope,
+        settingsPath,
+        removed,
+        ...(localPath !== undefined && localPath !== settingsPath
+            ? { localSettingsPath: localPath }
+            : {})
+    };
+}
+/**
+ * Strip every peaks-managed row from one target's file and write it back.
+ *
+ * The deny-list helpers run only on the SHARED settings file (the one that
+ * carries the committed `permissions.deny` block); the machine-local file
+ * carries hook entries plus, for Claude Code, the gate exemptions.
+ */
+export function applyRemovalToTarget(target, sentinels, isSharedFile) {
+    const { settings, removed } = stripPeaksEntries(target, sentinels);
+    let finalSettings = settings;
+    if (target.envExemptions === true) {
+        finalSettings = withoutExternalGateExemptions(finalSettings);
+    }
+    if (isSharedFile) {
+        finalSettings = withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(finalSettings));
+    }
+    atomicWriteJson(target.settingsPath, finalSettings);
+    return removed;
+}
+/**
+ * The status envelope for an IDE that can never carry a peaks hook: the query
+ * ran, the disk was read, and the honest reply is "nothing, and nothing ever
+ * will be".
+ */
+export function unsupportedHookStatus(scope, settingsPath, localPath) {
+    return {
+        scope,
+        settingsPath,
+        exists: existsSync(settingsPath),
+        ...(localPath !== undefined && localPath !== settingsPath
+            ? { localSettingsPath: localPath, localExists: existsSync(localPath) }
+            : {}),
+        installed: false,
+        supportsHooks: false
+    };
+}
+/** The status envelope for a set of resolved targets. */
+export function hookStatusFromTargets(scope, settingsPath, targets) {
+    const localTarget = targets.find((t) => t.settingsPath !== settingsPath);
+    return {
+        scope,
+        settingsPath,
+        exists: existsSync(settingsPath),
+        ...(localTarget !== undefined
+            ? {
+                localSettingsPath: localTarget.settingsPath,
+                localExists: existsSync(localTarget.settingsPath)
+            }
+            : {}),
+        installed: targets.some((t) => {
+            const settings = readSettingsFile(t.settingsPath);
+            return Object.keys(settings).length > 0 && isInstalledForEntries(settings, t.entries);
+        }),
+        supportsHooks: true
+    };
+}