peaks-loop 4.0.36 → 4.0.38

package/dist/services/lint/npx-resolver.js

@@ -1,26 +1,28 @@
 /**
- * Cross-platform `npx` resolver.
+ * Cross-platform `npm` / `npx` resolver.
  *
- * On Windows, `npm` installs `npx` as a `.cmd` shim; Node 22's
- * `child_process.spawnSync` refuses to invoke it unless `shell: true`
- * is set, and `shell: true` corrupts quoted `--package` arguments.
- * Rather than depend on shell quoting, this helper resolves the
- * npx script bundled with the user's `npm` install and invokes it
- * via `node <npx-cli.js>` with the same argv. macOS / Linux continue
- * to use the regular `npx` binary.
+ * On Windows, `npm` installs `npx` and `npm` as `.cmd` shims; Node's
+ * `child_process.spawnSync` refuses to invoke a `.cmd` unless `shell: true`
+ * is set, and `shell: true` concatenates (does not escape) the argv — it
+ * corrupts quoted `--package` arguments, splits any argument containing a
+ * space, and emits DEP0190 on every call. Rather than depend on shell
+ * quoting, these helpers resolve the CLI script bundled with the user's
+ * `npm` install and invoke it via `node <npm|npx>-cli.js` with the same
+ * argv. macOS / Linux continue to use the regular binaries.
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
-function locateNpxCliScript() {
+/** Locate `<npm install>/bin/<scriptFile>`, or `null` when not on disk. */
+function locateNpmCliScript(scriptFile) {
     const candidates = process.platform === 'win32'
         ? [
-            join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', 'npx-cli.js'),
-            'C:/nvm4w/nodejs/node_modules/npm/bin/npx-cli.js',
-            'C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js'
+            join(process.execPath, '..', '..', 'node_modules', 'npm', 'bin', scriptFile),
+            `C:/nvm4w/nodejs/node_modules/npm/bin/${scriptFile}`,
+            `C:/Program Files/nodejs/node_modules/npm/bin/${scriptFile}`
         ]
         : [
-            join(process.execPath, '..', '..', 'lib', 'node_modules', 'npm', 'bin', 'npx-cli.js')
+            join(process.execPath, '..', '..', 'lib', 'node_modules', 'npm', 'bin', scriptFile)
         ];
     for (const candidate of candidates) {
         if (existsSync(candidate))
@@ -30,7 +32,7 @@ function locateNpxCliScript() {
 }
 export function resolveNpxInvocation(npxArgs) {
     if (process.platform === 'win32') {
-        const cliScript = locateNpxCliScript();
+        const cliScript = locateNpmCliScript('npx-cli.js');
         if (cliScript !== null) {
             return {
                 command: process.execPath,
@@ -45,3 +47,25 @@ export function resolveNpxInvocation(npxArgs) {
         baseEnv: process.env
     };
 }
+/**
+ * `npm` sibling of `resolveNpxInvocation`, same shim bypass: `node
+ * <npm-cli.js> <args>`. A caller must NOT reach for bare `npm` + `shell: true`
+ * instead — the shim is the defect, not the justification.
+ */
+export function resolveNpmInvocation(npmArgs) {
+    if (process.platform === 'win32') {
+        const cliScript = locateNpmCliScript('npm-cli.js');
+        if (cliScript !== null) {
+            return {
+                command: process.execPath,
+                args: [cliScript, ...npmArgs],
+                baseEnv: process.env
+            };
+        }
+    }
+    return {
+        command: 'npm',
+        args: npmArgs,
+        baseEnv: process.env
+    };
+}

package/dist/services/lint/ocr-multilang-adapter.js

@@ -3,6 +3,7 @@
  * 8 supported languages to the corresponding `ocr review` filter.
  */
 import { spawnSync } from 'node:child_process';
+import { resolveNpxInvocation } from './npx-resolver.js';
 export const OCR_18_PACKAGE = '@alibaba-group/open-code-review@1.8.9';
 export const OCR_18_LANGUAGES = [
     'python',
@@ -78,7 +79,12 @@ export function runOcr18(options) {
         timeout: options.timeoutMs ?? 60_000,
         maxBuffer: 32 * 1024 * 1024
     };
-    const result = spawnSync('npx', args, spawnOptions);
+    // 2026-09-10: bare `spawnSync('npx', …)` cannot launch the Windows `npx.cmd`
+    // shim (ENOENT, no shell) — same fix and same helper as `detect-ocr-18.ts` /
+    // `detect-eslint.ts`. `shell: true` is NOT an option: it would concatenate the
+    // argv unescaped and split the `--package` flag.
+    const { command, args: npxArgs, baseEnv } = resolveNpxInvocation(args);
+    const result = spawnSync(command, npxArgs, { ...spawnOptions, env: baseEnv });
     const stdout = typeof result.stdout === 'string' ? result.stdout : '';
     const stderr = typeof result.stderr === 'string' ? result.stderr : '';
     if (result.error !== undefined && result.error !== null) {
@@ -87,7 +93,8 @@ export function runOcr18(options) {
             findings: [],
             summary: null,
             durationMs: Date.now() - start,
-            rawOutput: stderr || stdout
+            // Never discard WHY the launch failed — stdout/stderr are both empty here.
+            rawOutput: stderr || stdout || result.error.message
         };
     }
     if (result.status !== 0) {

package/dist/services/release/version-precheck-service.js

@@ -114,9 +114,16 @@ export function runRootVsShared(opts) {
 export function runTagCollision(opts) {
     const rootVersion = readRootVersion(opts.projectRoot);
     const tagName = `v${rootVersion}`;
-    // Windows shell wrapping convention: 5 prior occurrences in tests/unit/release/.
+    // 2026-09-10: no shell. `git` is `git.exe` on Windows, so the wrapper bought
+    // nothing — and it actively broke this layer, because `projectRoot` is an
+    // ARGUMENT to git and a shell wraps the command line unescaped. On a project
+    // whose path contains a space the shell split it, git exited 128
+    // ("cannot change to '…'"), and the layer fell through to its
+    // "git tag --list exited with code 128; layer skipped" WARNING — so a real
+    // tag collision was reported as merely deferred. Reproduced on
+    // `…\Temp\peaks space demo` with tag v9.9.9 present: warning (should be
+    // blocker). It also emitted DEP0190 on every run, on every layer.
     const res = spawnSync('git', ['-C', opts.projectRoot, 'tag', '--list', tagName], {
-        shell: process.platform === 'win32',
         encoding: 'utf8',
         timeout: 5_000
     });

package/dist/services/scan/file-size-scan.d.ts

@@ -1,4 +1,29 @@
 export declare const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+/**
+ * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
+ * First": it exists to make a human *simplify* an over-long file. A path is
+ * therefore exempt exactly when no such simplification exists — which is two
+ * kinds of file, both listed below so the reason is visible next to the rule.
+ *
+ * Tool output (whole-cloth generated, nobody maintains it by hand):
+ * `.peaks/**` is Peaks-Loop's own state store and holds three derived indexes
+ * already over the cap (`memory/index.json`, `lint/baseline.json`,
+ * `retrospective/index.json`); exempting only `memory/` would leave the other
+ * two false positives intact. No source module lives there, and its largest
+ * hand-authored file is under 500 lines. Lockfiles are regenerated on every
+ * install.
+ *
+ * Append-only records: `CHANGELOG.md` is history, so its length is a function
+ * of how long the project has existed, not of anyone's design choices — the
+ * only way to "fix" a violation would be to delete the record. Left checked,
+ * this gate is reliably red on every release, precisely when it cannot be
+ * acted on, which trains people to ignore it. A nested changelog under
+ * `packages/` is the same kind of record.
+ *
+ * Declared once, here — do not add special-cases in the scan loop.
+ */
+export declare const SIZE_CAP_EXEMPT_PATTERNS: readonly string[];
+export declare function isSizeCapExempt(file: string): boolean;
 export type FileSizeViolation = {
     file: string;
     lines: number;
@@ -7,6 +32,10 @@ export type FileSizeScanResult = {
     ok: boolean;
     threshold: number;
     checkedFiles: number;
+    /** Paths skipped by SIZE_CAP_EXEMPT_PATTERNS (tool output + append-only
+     *  records). Reported so the exemption is auditable rather than a silent
+     *  skip. */
+    exemptFiles: string[];
     /** Files that appeared in `git diff` but no longer exist on disk (e.g.
      *  deleted in the working tree). Pre-#015 the scan crashed on these via
      *  ENOENT; now they are reported here as informational data. */

package/dist/services/scan/file-size-scan.js

@@ -2,6 +2,63 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+/**
+ * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
+ * First": it exists to make a human *simplify* an over-long file. A path is
+ * therefore exempt exactly when no such simplification exists — which is two
+ * kinds of file, both listed below so the reason is visible next to the rule.
+ *
+ * Tool output (whole-cloth generated, nobody maintains it by hand):
+ * `.peaks/**` is Peaks-Loop's own state store and holds three derived indexes
+ * already over the cap (`memory/index.json`, `lint/baseline.json`,
+ * `retrospective/index.json`); exempting only `memory/` would leave the other
+ * two false positives intact. No source module lives there, and its largest
+ * hand-authored file is under 500 lines. Lockfiles are regenerated on every
+ * install.
+ *
+ * Append-only records: `CHANGELOG.md` is history, so its length is a function
+ * of how long the project has existed, not of anyone's design choices — the
+ * only way to "fix" a violation would be to delete the record. Left checked,
+ * this gate is reliably red on every release, precisely when it cannot be
+ * acted on, which trains people to ignore it. A nested changelog under
+ * `packages/` is the same kind of record.
+ *
+ * Declared once, here — do not add special-cases in the scan loop.
+ */
+export const SIZE_CAP_EXEMPT_PATTERNS = [
+    // tool output
+    '.peaks/**',
+    '**/pnpm-lock.yaml',
+    '**/package-lock.json',
+    '**/yarn.lock',
+    // append-only records
+    '**/CHANGELOG.md'
+];
+/**
+ * Glob → RegExp for the shapes above only, in a single split pass (chained
+ * string replaces would re-expand the `.*` they had just produced). The
+ * directory-wildcard prefix matches zero directories, so a root-level
+ * lockfile still counts.
+ */
+function exemptPatternToRegExp(pattern) {
+    const body = pattern
+        .split(/(\*\*\/|\*\*|\*)/)
+        .map((part) => {
+        if (part === '**/')
+            return '(?:.*/)?';
+        if (part === '**')
+            return '.*';
+        if (part === '*')
+            return '[^/]*';
+        return part.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+        .join('');
+    return new RegExp(`^${body}$`);
+}
+export function isSizeCapExempt(file) {
+    const normalized = file.replace(/\\/g, '/');
+    return SIZE_CAP_EXEMPT_PATTERNS.some((pattern) => exemptPatternToRegExp(pattern).test(normalized));
+}
 function getChangedFiles(projectRoot, baseRef) {
     try {
         // --diff-filter=AM keeps only Added + Modified entries. Deleted files
@@ -28,8 +85,13 @@ export function scanFileSize(options) {
     const files = getChangedFiles(options.projectRoot, baseRef);
     const violations = [];
     const deletedFiles = [];
+    const exemptFiles = [];
     let checkedFiles = 0;
     for (const file of files) {
+        if (isSizeCapExempt(file)) {
+            exemptFiles.push(file);
+            continue;
+        }
         const absolute = join(options.projectRoot, file);
         // Pre-#015: readFileSync threw ENOENT for files that appear in
         // `git diff --name-only` but no longer exist on disk (e.g. a refactor
@@ -62,6 +124,7 @@ export function scanFileSize(options) {
         ok: violations.length === 0,
         threshold,
         checkedFiles,
+        exemptFiles,
         deletedFiles,
         violations
     };

package/dist/services/session/caller-binding-service.d.ts

@@ -68,6 +68,30 @@ export declare function getCallerBinding(projectRoot: string, callerId: string):
  * documented 4.0.14 carry-forward micro-fix from QA's issue #1.
  */
 export declare function setCallerBinding(projectRoot: string, callerId: string, binding: CallerBinding): void;
+/**
+ * Repoint an EXISTING per-caller binding at a new peak session id.
+ *
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an explicit
+ * `peaks workspace init --session-id <X> --allow-session-rebind` rewrites
+ * the project-global `.peaks/_runtime/session.json`. Without this call the
+ * per-caller file keeps shadowing it for `getSessionIdCanonical`, so the
+ * rebind silently did not take for every command that resolves through
+ * that variant (`peaks session checkpoint`, `peaks session 24h-mode`, ...)
+ * while `getCurrentSessionId` reported the new session.
+ *
+ * Only the binding of the caller that performed the rebind is repointed —
+ * a second caller keeps its own session, which is the multi-caller
+ * isolation the per-caller design exists for.
+ *
+ * Every other field is preserved: `createdAt` is the session creation
+ * stamp the legacy `session.json` dual-write reuses, and `skill` / `mode`
+ * / `gate` are live presence state.
+ *
+ * @returns `true` when a binding existed and was repointed, `false` when
+ *   the caller had no binding file (nothing was shadowing the rebind, and
+ *   we do not create one speculatively).
+ */
+export declare function updateCallerBindingSessionId(projectRoot: string, callerId: string, peakSessionId: string): boolean;
 /**
  * Enumerate the per-caller binding files under
  * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the

package/dist/services/session/caller-binding-service.js

@@ -120,6 +120,40 @@ export function setCallerBinding(projectRoot, callerId, binding) {
     };
     atomicWriteJson(bindingPath, payload);
 }
+/**
+ * Repoint an EXISTING per-caller binding at a new peak session id.
+ *
+ * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): an explicit
+ * `peaks workspace init --session-id <X> --allow-session-rebind` rewrites
+ * the project-global `.peaks/_runtime/session.json`. Without this call the
+ * per-caller file keeps shadowing it for `getSessionIdCanonical`, so the
+ * rebind silently did not take for every command that resolves through
+ * that variant (`peaks session checkpoint`, `peaks session 24h-mode`, ...)
+ * while `getCurrentSessionId` reported the new session.
+ *
+ * Only the binding of the caller that performed the rebind is repointed —
+ * a second caller keeps its own session, which is the multi-caller
+ * isolation the per-caller design exists for.
+ *
+ * Every other field is preserved: `createdAt` is the session creation
+ * stamp the legacy `session.json` dual-write reuses, and `skill` / `mode`
+ * / `gate` are live presence state.
+ *
+ * @returns `true` when a binding existed and was repointed, `false` when
+ *   the caller had no binding file (nothing was shadowing the rebind, and
+ *   we do not create one speculatively).
+ */
+export function updateCallerBindingSessionId(projectRoot, callerId, peakSessionId) {
+    const existing = getCallerBinding(projectRoot, callerId);
+    if (existing === null)
+        return false;
+    setCallerBinding(projectRoot, callerId, {
+        ...existing,
+        peakSessionId,
+        lastActivityAt: new Date().toISOString()
+    });
+    return true;
+}
 /**
  * Enumerate the per-caller binding files under
  * `.peaks/_runtime/callers/`. Returns the parsed bindings plus the

package/dist/services/session/getSessionDir.js

@@ -2,20 +2,25 @@
  * Canonical session-directory resolver.
  *
  * As of slice 2026-06-05-peaks-runtime-layer the per-session workspace
- * lives at `<root>/.peaks/_runtime/<sessionId>/` (NOT at the legacy
- * `<root>/.peaks/_runtime/<sessionId>/` location). All **write** paths MUST route
- * through this helper. The legacy top-level path is preserved as a
- * back-compat **read** fallback only (see
- * `src/services/artifacts/request-artifact-service.ts:662` etc.).
+ * lives at `<root>/.peaks/_runtime/<sessionId>/`, NOT at the legacy
+ * `<root>/.peaks/<sessionId>/` location. All **write** paths MUST route
+ * through this helper. The legacy top-level path survives only as a
+ * back-compat **read** fallback (see `legacySessionRoot` in
+ * `src/services/artifacts/artifact-prerequisites.ts` and `sessionOwnsSlice`
+ * in `src/services/sc/sc-service.ts`).
  *
- * The corresponding test in
  * `tests/unit/services/session/session-dir-canonical.test.ts` enforces
- * two invariants:
+ * three invariants:
  *
  *   (a) `getSessionDir(root, sid)` returns `<root>/.peaks/_runtime/<sid>`.
- *   (b) A static scan of `src/` flags any direct join of `.peaks` +
- *       `sessionId` that does NOT route through this resolver. The
- *       back-compat **read** sites are excluded by explicit allow-list.
+ *   (b) A static scan of `src/**` flags any `join()` chain that names
+ *       `.peaks` plus a session id without routing through this resolver,
+ *       wherever the id sits in the chain. The back-compat **read** sites
+ *       are exempted by an allow-list whose entries are asserted to be
+ *       load-bearing (an inert entry fails the scan).
+ *   (c) A static scan of every markdown file under `skills/` flags a
+ *       legacy `.peaks/<sid>/...` artifact path that a sub-agent would
+ *       follow verbatim.
  *
  * @param projectRoot - Absolute path to the project root.
  * @param sessionId - The session identifier (e.g. `2026-06-06-session-5b1095`).

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

@@ -15,7 +15,32 @@ interface ResolvedHookSpec {
     readonly hookEnforceSentinel: string;
     readonly hookEnforceMatcher: string;
     readonly hookEnforceEvent: string;
+    /**
+     * True when the gate-enforce entry must be materialized into the IDE's
+     * MACHINE-LOCAL settings file rather than the shared one (see
+     * `hookEnforceShell` below). Set for Claude Code, whose project-scope
+     * hooks have a gitignored per-machine sibling file.
+     */
+    readonly hookEnforceMachineLocal: boolean;
+    /**
+     * The `shell` field for the gate-enforce handler, or `undefined` to omit
+     * the key entirely and let the IDE use its documented default.
+     *
+     * Claude Code only. See `resolveHookShell` for why Windows needs this.
+     */
+    readonly hookEnforceShell: string | undefined;
 }
+/**
+ * Claude Code runs a shell-form hook command through a shell that defaults
+ * to bash — which on Windows means Git Bash, and MSYS2's bash
+ * force-allocates its own console window. The result is a visible window on
+ * EVERY Bash tool call. The window is created by the spawner (Claude Code)
+ * before any peaks code runs, so `windowsHide` and any in-process hiding
+ * cannot help; pinning the hook's `shell` is the only lever the hook schema
+ * offers. The platform-neutral default (`undefined` → omit the key) is kept
+ * everywhere else.
+ */
+export declare function resolveHookShell(platform?: NodeJS.Platform): string | undefined;
 export declare function resolveHookSpec(ide: IdeId): ResolvedHookSpec;
 /** A typed descriptor for a single peaks-managed hook entry. */
 export type PeaksHookEntry = {
@@ -23,6 +48,14 @@ export type PeaksHookEntry = {
     matcher: string;
     command: string;
     event: string;
+    /**
+     * When true the entry is written to the machine-local, gitignored settings
+     * file (`.claude/settings.local.json`) instead of the shared one, because
+     * the entry carries a machine-specific value (the `shell` field).
+     */
+    machineLocal?: boolean;
+    /** Optional `shell` field for the emitted handler. */
+    shell?: string;
 };
 /**
  * Slice 2026-08-06-codegate-vendor-neutral — code-gate hook entry.
@@ -62,4 +95,45 @@ export declare function resolveLegacySentinels(ide: IdeId): ReadonlyArray<string
 export declare const SUPERPOWERS_DENIED_SKILLS: ReadonlyArray<string>;
 export declare function formatSuperpowersDenyEntry(skillId: string): string;
 export declare const SUPERPOWERS_DENY_SENTINELS: ReadonlySet<string>;
+/**
+ * Adapter table: a Peaks *concept* → the settings value an EXTERNAL,
+ * non-Peaks PreToolUse gate must read to honour it.
+ *
+ * The concept Peaks holds is "the `.peaks/**` workspace tree is not project
+ * source, so 'who imports this / what schema' carries no signal there".
+ * Peaks already enforces it for its own hooks: slice 2.0.1-bug3 materializes
+ * a `Write|Edit|MultiEdit` bypass in `.claude/settings.local.json` precisely
+ * so the first workspace write is never fact-gated. This table is that same
+ * intent declared to a gate Peaks does not own.
+ *
+ * The mapped key is read by the ECC plugin's `gateguard-fact-force` hook: a
+ * comma-separated glob list matched against the normalized (forward-slash,
+ * lowercased) path, where a match skips first-touch fact-forcing. The row is
+ * INERT when that plugin is absent — an env var nothing reads.
+ *
+ * The key below is the ONLY occurrence of that third-party name in the source
+ * tree (a test pins the count). Vendor-specific translation belongs in the
+ * adapter layer, next to `HOOK_COMMAND_BY_IDE` and `resolveHookShell` — never
+ * scattered through the installer. And it is emitted into a MACHINE-LOCAL
+ * settings file only (see `resolveHookTargets`): a third-party variable name in
+ * the COMMITTED shared settings would be pushed to every consumer of this repo.
+ */
+export declare const EXTERNAL_GATE_EXEMPT_ENV: Readonly<Record<string, string>>;
+/** True when every `EXTERNAL_GATE_EXEMPT_ENV` glob is already declared in `settings.env`. */
+export declare function hasExternalGateExemptions(settings: Record<string, unknown>): boolean;
+/**
+ * Union every `EXTERNAL_GATE_EXEMPT_ENV` row into `settings.env`. An existing
+ * value is EXTENDED, never replaced, so a user who exempted other trees keeps
+ * them; unrelated `env` keys are untouched. Rows already carrying our glob are
+ * left byte-identical (so a re-run cannot churn the file), and the input object
+ * is returned unchanged when there is nothing to add. Pure.
+ */
+export declare function withExternalGateExemptions(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Inverse of `withExternalGateExemptions`: remove exactly the globs this repo
+ * added, keeping any the user wrote. The key is deleted once it holds nothing
+ * of ours, and `env` itself is dropped when it becomes empty — so uninstall
+ * leaves no orphan field behind. Pure.
+ */
+export declare function withoutExternalGateExemptions(settings: Record<string, unknown>): Record<string, unknown>;
 export {};

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

@@ -11,6 +11,19 @@ import { getAdapter } from '../ide/ide-registry.js';
 import { HOOK_OUTER_CACHE_COMMAND, HOOK_OUTER_CACHE_EVENT, HOOK_OUTER_CACHE_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';
+/**
+ * Claude Code runs a shell-form hook command through a shell that defaults
+ * to bash — which on Windows means Git Bash, and MSYS2's bash
+ * force-allocates its own console window. The result is a visible window on
+ * EVERY Bash tool call. The window is created by the spawner (Claude Code)
+ * before any peaks code runs, so `windowsHide` and any in-process hiding
+ * cannot help; pinning the hook's `shell` is the only lever the hook schema
+ * offers. The platform-neutral default (`undefined` → omit the key) is kept
+ * everywhere else.
+ */
+export function resolveHookShell(platform = process.platform) {
+    return platform === 'win32' ? 'powershell' : undefined;
+}
 /**
  * Per-IDE hook command + sentinel. The default (Claude Code) uses the
  * legacy `peaks gate enforce` surface; Trae / Cursor / Codex (Cursor-style
@@ -42,11 +55,22 @@ export function resolveHookSpec(ide) {
         // silently writing a Claude-shaped entry to a non-Claude settings.json.
         throw new Error(`peaks hooks install: unsupported IDE '${ide}' (no HOOK_COMMAND_BY_IDE entry; add one to hooks-settings-service.ts)`);
     }
+    const isClaudeCode = ide === 'claude-code';
+    // Claude Code's gate hook must emit its structured decision as JSON:
+    // without `--json` the hook validator rejects the plain `{}` stdout with
+    // "Hook JSON output validation failed". See
+    // .peaks/memory/bash-pretooluse-hook-json-error-fix.md.
+    const jsonFlag = isClaudeCode ? ' --json' : '';
     return {
-        hookEnforceCommand: `${spec.command} --project "\${${adapter.envVar}}"`,
+        hookEnforceCommand: `${spec.command} --project "\${${adapter.envVar}}"${jsonFlag}`,
         hookEnforceSentinel: spec.sentinel,
         hookEnforceMatcher: adapter.toolMatcher,
-        hookEnforceEvent: adapter.hookEvent
+        hookEnforceEvent: adapter.hookEvent,
+        // 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.
+        hookEnforceMachineLocal: isClaudeCode,
+        hookEnforceShell: isClaudeCode ? resolveHookShell() : undefined
     };
 }
 /**
@@ -64,7 +88,14 @@ export const HOOK_CODE_GATE_COMMAND = `peaks code-gate --json`;
 export function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
     const entries = [
-        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
+        {
+            sentinel: spec.hookEnforceSentinel,
+            matcher: spec.hookEnforceMatcher,
+            command: spec.hookEnforceCommand,
+            event: spec.hookEnforceEvent,
+            machineLocal: spec.hookEnforceMachineLocal,
+            ...(spec.hookEnforceShell !== undefined ? { shell: spec.hookEnforceShell } : {})
+        }
     ];
     if (ide === 'claude-code') {
         entries.push({
@@ -202,3 +233,98 @@ export function formatSuperpowersDenyEntry(skillId) {
     return `UseSkill(${skillId})`;
 }
 export const SUPERPOWERS_DENY_SENTINELS = new Set(SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry));
+// --- External (third-party) PreToolUse gate exemptions ---------------------
+/**
+ * Adapter table: a Peaks *concept* → the settings value an EXTERNAL,
+ * non-Peaks PreToolUse gate must read to honour it.
+ *
+ * The concept Peaks holds is "the `.peaks/**` workspace tree is not project
+ * source, so 'who imports this / what schema' carries no signal there".
+ * Peaks already enforces it for its own hooks: slice 2.0.1-bug3 materializes
+ * a `Write|Edit|MultiEdit` bypass in `.claude/settings.local.json` precisely
+ * so the first workspace write is never fact-gated. This table is that same
+ * intent declared to a gate Peaks does not own.
+ *
+ * The mapped key is read by the ECC plugin's `gateguard-fact-force` hook: a
+ * comma-separated glob list matched against the normalized (forward-slash,
+ * lowercased) path, where a match skips first-touch fact-forcing. The row is
+ * INERT when that plugin is absent — an env var nothing reads.
+ *
+ * The key below is the ONLY occurrence of that third-party name in the source
+ * tree (a test pins the count). Vendor-specific translation belongs in the
+ * adapter layer, next to `HOOK_COMMAND_BY_IDE` and `resolveHookShell` — never
+ * scattered through the installer. And it is emitted into a MACHINE-LOCAL
+ * settings file only (see `resolveHookTargets`): a third-party variable name in
+ * the COMMITTED shared settings would be pushed to every consumer of this repo.
+ */
+export const EXTERNAL_GATE_EXEMPT_ENV = Object.freeze({
+    // peaks' `.peaks/**` workspace tree is not project source → skip fact-forcing
+    GATEGUARD_EXEMPT_GLOBS: '.peaks/**'
+});
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Split a comma-separated glob list, dropping blanks and surrounding space. */
+function splitGlobList(value) {
+    return value.split(',').map((glob) => glob.trim()).filter((glob) => glob.length > 0);
+}
+/** True when every `EXTERNAL_GATE_EXEMPT_ENV` glob is already declared in `settings.env`. */
+export function hasExternalGateExemptions(settings) {
+    const env = isPlainObject(settings.env) ? settings.env : {};
+    return Object.entries(EXTERNAL_GATE_EXEMPT_ENV).every(([key, glob]) => {
+        const current = env[key];
+        return typeof current === 'string' && splitGlobList(current).includes(glob);
+    });
+}
+/**
+ * Union every `EXTERNAL_GATE_EXEMPT_ENV` row into `settings.env`. An existing
+ * value is EXTENDED, never replaced, so a user who exempted other trees keeps
+ * them; unrelated `env` keys are untouched. Rows already carrying our glob are
+ * left byte-identical (so a re-run cannot churn the file), and the input object
+ * is returned unchanged when there is nothing to add. Pure.
+ */
+export function withExternalGateExemptions(settings) {
+    const env = isPlainObject(settings.env) ? { ...settings.env } : {};
+    let changed = false;
+    for (const [key, glob] of Object.entries(EXTERNAL_GATE_EXEMPT_ENV)) {
+        const current = typeof env[key] === 'string' ? env[key] : '';
+        const existing = splitGlobList(current);
+        if (existing.includes(glob))
+            continue;
+        env[key] = [...existing, glob].join(',');
+        changed = true;
+    }
+    return changed ? { ...settings, env } : settings;
+}
+/**
+ * Inverse of `withExternalGateExemptions`: remove exactly the globs this repo
+ * added, keeping any the user wrote. The key is deleted once it holds nothing
+ * of ours, and `env` itself is dropped when it becomes empty — so uninstall
+ * leaves no orphan field behind. Pure.
+ */
+export function withoutExternalGateExemptions(settings) {
+    if (!isPlainObject(settings.env))
+        return settings;
+    const env = { ...settings.env };
+    let changed = false;
+    for (const [key, glob] of Object.entries(EXTERNAL_GATE_EXEMPT_ENV)) {
+        const current = env[key];
+        if (typeof current !== 'string')
+            continue;
+        const kept = splitGlobList(current).filter((entry) => entry !== glob);
+        changed = true;
+        if (kept.length > 0) {
+            env[key] = kept.join(',');
+        }
+        else {
+            delete env[key];
+        }
+    }
+    if (!changed)
+        return settings;
+    if (Object.keys(env).length === 0) {
+        const { env: _omit, ...rest } = settings;
+        return rest;
+    }
+    return { ...settings, env };
+}