peaks-loop 4.0.37 → 4.0.38

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 4.0.38 — 2026-09-11 (适配外部闸门 + 多语言评审复活 + 测试不再弹窗)
+
+**Highlights**:
+
+1. **子代理被事先告知"先读再改",闸门不再被误判** — 外部插件（ECC）注册了一个 `PreToolUse` 闸门，会在编辑一个文件时要求 LLM 先建立事实，否则**拒绝**。问题不在闸门本身，而在它的提示词**读起来像工具坏了**——它从不说"你的编辑没有被应用"，也从不点名真正的前置动作是**先读文件**。现在每个派发出去的子代理的前缀里都有一段 ~693 B 的说明，**规矩在前、范围点名、失败声明在后**：先说"编辑前先读这个文件，这是这里的正常工作方式"，点名作用范围（`.peaks/**` 之外的所有路径），**最后**才说万一跳过会撞上什么、以及那不是失败、编辑未被应用。
+
+   - **代价如实记录**：这段是 7 个角色各加 694 B，大致**把 4.0.36 那一轮省下的 18% 还了回去**。这是用户明确要求的适配，它值这些字节（否则每次首次编辑都要多一轮往返），但提示词经济性的账今天倒退了，这件事应当被看见。
+
+2. **`.peaks/**` 豁免被自动声明** — peaks-loop **从 `2.0.1-bug3` 起就已经决定了** `.peaks/**` 不该被 fact-gate（那个切片就叫 *fact-forcing bypass*），只是外部闸门从没听说过。现在 `peaks hooks install` / `workspace init` 会把豁免写进**机器本地**的 `settings.local.json`。四条约束都做到了：**第三方变量名全仓库只出现一处**（adapter 单点映射）、**只进机器本地**（绝不进已提交的共享模板——一个第三方变量名不该推给每个消费者）、**合并而非覆盖**（用户已有的豁免取并集，无关 `env` 键保留）、范围用 **`.peaks/**` 而非 `_runtime/`**。15 个用例覆盖，含 uninstall（只剥自己的 glob）与非 Claude Code IDE（不写）。
+
+3. **测试套件不再往桌面弹 PowerShell 窗口** — `write-gate-decision-table.test.ts` 是全仓库唯一 spawn `powershell` 的测试，**没设 `windowsHide`**，且**对决策表每一行都 spawn 一次**。决定性的证据是它的隔壁文件：`gate-enforce-machine-local-shell.test.ts` 的开头就写明了"执行 hook 就是弹窗的原因"，因此**刻意不执行**——一个文件知道并回避，另一个照做。修法是**加 `windowsHide` 但保留执行**（真的把命令跑过每个 shell 正是当初抓出 C5 `argv` 反转的原因）。6 处已修，并确认仍在真实执行（`✓ given bash … 1583ms`、`✓ given powershell … 3755ms`）。
+
+4. **多语言评审在 Windows 上复活** — `peaks code-review detect-ocr-18` 在一台 `npx --version` 正常返回 `11.9.0` 的机器上报 `npxAvailable: false`，于是**八种语言**（python/go/java/rust/cpp/csharp/ruby/php，经 `@alibaba-group/open-code-review`）的评审路径**在这个平台上从未可达**。三处仍在 spawn 裸 `npx`（Windows 上是 `.cmd`，无法这样启动）——而**同一个目录里 `detect-eslint.ts` 早就改成正确形式了**。现在三处都走既有的 `resolveNpxInvocation`，并且**"npx 不存在"与"启动不了"分开报**（正是这个混淆让一台正常的机器报成缺工具）。修前 `ocr18-missing / npxAvailable:false` → 修后 **`ready / npxAvailable:true`**。
+
+5. **`peaks hooks install --global` 此前从未成功过** — ESM 包里用了裸 `__dirname`，抛 `__dirname is not defined`，于是**每一次** `--global` 都返回失败——而且是**在 settings 已经写完之后**才失败，把半成品报成失败。同时 `--dry-run --global` **真的会往 `~/.claude/` 拷文件**。两者都已修。
+
+**验证**：build clean、`tsc -p tsconfig.build.json` exit 0、宽口径 `tsconfig.json` 维持既有 142；全量 **179 files / 1736 passed（3 skipped）**；版本三处常量（`package.json` / `CLI_VERSION` / `RUNTIME_VERSION`）一致——4.0.37 补上的那条 sync 与那个"能真失败"的守卫当场兑现。
+
 ## 4.0.37 — 2026-09-10 (Windows spawn 根因 + 会话解析 + 诚实性修复)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.37 (2026-09-10) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.38 (2026-09-11) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.37(2026-09-10) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.38(2026-09-11) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

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

@@ -1,5 +1,6 @@
 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';
@@ -7,6 +8,16 @@ import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntries
 import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * This module's own directory — `<root>/src/cli/commands` in the source tree,
+ * `<root>/dist/cli/commands` in a build. Same reason as
+ * `claude-settings-template.ts`: `package.json#type` is `module`, so the CJS
+ * module-directory global does not exist here (it is a ReferenceError under
+ * both tsx and the shipped `dist` build — see the guard in
+ * `tests/unit/hooks/gate-enforce-machine-local-shell.test.ts`), and
+ * `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';
 }
@@ -97,12 +108,15 @@ function readOnDiskDenyEntries(settings) {
         return [];
     return deny.filter((d) => typeof d === 'string');
 }
-function copyBridgeHookIfPresent(userHome) {
-    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
+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');
     if (!existsSync(source)) {
         return { copied: false, source, target };
     }
+    if (dryRun) {
+        return { copied: true, source, target };
+    }
     mkdirSync(dirname(target), { recursive: true });
     copyFileSync(source, target);
     return { copied: true, source, target };
@@ -117,12 +131,15 @@ function copyBridgeHookIfPresent(userHome) {
  * runtime entry; the shell script is the canonical artifact distributed
  * alongside the bridge hook.
  */
-function copyCodeGateHookIfPresent(userHome) {
-    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-code-gate.sh');
+function copyCodeGateHookIfPresent(userHome, dryRun = false) {
+    const source = resolve(MODULE_DIR, '..', '..', 'services', 'hooks', 'pre-tool-code-gate.sh');
     const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-code-gate.sh');
     if (!existsSync(source)) {
         return { copied: false, source, target };
     }
+    if (dryRun) {
+        return { copied: true, source, target };
+    }
     mkdirSync(dirname(target), { recursive: true });
     copyFileSync(source, target);
     return { copied: true, source, target };
@@ -147,8 +164,10 @@ export function registerHooksCommands(program, io) {
             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 ?? '')
+                    ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
                     : { copied: false, source: '', target: '' };
                 // Slice 2026-08-06-codegate-vendor-neutral: also copy the
                 // code-gate hook script. The runtime gate lives at
@@ -156,7 +175,7 @@ export function registerHooksCommands(program, io) {
                 // 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 ?? '')
+                    ? copyCodeGateHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
                     : { copied: false, source: '', target: '' };
                 printResult(io, ok('hooks.install', {
                     ...plan,
@@ -176,6 +195,12 @@ export function registerHooksCommands(program, io) {
                     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)`,
                     bridgeCopy.copied
                         ? `would copy bridge hook from ${bridgeCopy.source} to ${bridgeCopy.target}`

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -150,6 +150,40 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * the ones the orchestrator must have to decide the next gate.
  */
 export declare const REPORT_CAP_BLOCK = "## Final report cap (mandatory)\n\nYour FINAL report to the parent MUST be \u2264 40 lines and \u2264 2 KB. Write any longer detail into the artifact file you already own \u2014 the parent can `Read` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.\n";
+/**
+ * Slice 2026-09-10-fact-force-gate-adaptation: stand IN FRONT of an external
+ * `PreToolUse` gate instead of explaining its denial after the fact.
+ *
+ * ECC (a third-party plugin under `~/.claude/plugins/`) registers
+ * `gateguard-fact-force.js` on `Edit|Write|MultiEdit`. It denies the first
+ * edit of a file whose facts the agent has not established, and its four-item
+ * message never says two things the agent needs: that the file must be READ
+ * first, and that the edit was NOT applied. Measured failure mode
+ * (session 2026-09-10-session-528a63): the sub-agent reads the denial as
+ * "the tool is broken" and abandons the edit.
+ *
+ * So the block below leads with the STANDING RULE (read before you edit) and
+ * names the paths it covers, and mentions the denial only as the consequence
+ * of skipping that rule. A sub-agent that has never seen the gate can read
+ * this once and never trip it.
+ *
+ * The gate itself is untouched: peaks-loop adapts to it, and does NOT disable,
+ * bypass, or re-implement it. Nor is `ECC_GATEGUARD=off` part of this.
+ *
+ * Always rendered — no opt-out flag and no role split. Every role edits files
+ * outside `.peaks/**`, and only sub-agent #1 of a session sees a denial (the
+ * gate fires once per file), so a role-scoped or opt-in block would leave the
+ * rest of the fleet untold. It joins the stable boilerplate prefix: constant
+ * bytes for every dispatch, prompt-cache friendly.
+ *
+ * The `.peaks/**` exemption is real and pre-dates this slice — peaks-loop
+ * materialises `.claude/settings.local.json` so the gate skips `.peaks/**`
+ * (slice 2.0.1-bug3-fact-forcing-bypass; see
+ * `src/cli/commands/workspace/init-command.ts`).
+ */
+export declare const FACT_FORCE_GATE_BLOCK = "## Read before you edit (Fact-Forcing Gate)\n\nRead a file BEFORE your first `Edit` / `Write` / `MultiEdit` on it \u2014 the normal way to work here, not an optional step. It applies to every path OUTSIDE `.peaks/**` (source, tests, docs, config); `.peaks/**` writes are exempt.\n\nSkipping that read trips a `PreToolUse` plugin gate (ECC's \"Fact-Forcing Gate\"), which denies the edit. A denial is NOT a failure and the tool is NOT broken \u2014 your edit was NOT applied. Read the file, state the four facts the gate asks for (importers, affected API, data schemas if any, the user's verbatim instruction), then retry the same operation. Do not switch tools, do not give up, do not re-attempt blindly.\n";
+/** Always-on renderer for {@link FACT_FORCE_GATE_BLOCK}. */
+export declare function renderFactForceGateBlock(): string;
 /**
  * Compose the system-prompt body for a sub-agent dispatch.
  *
@@ -161,7 +195,7 @@ export declare const REPORT_CAP_BLOCK = "## Final report cap (mandatory)\n\nYour
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
  * controller brief): when the memory block is unavailable, the composed body is
  * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
- * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * "\n" + REPORT_CAP + "\n" + FACT_FORCE_GATE + "\n" + contextBlock + taskBody`, so the unavailable
  * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
  * (REPORT_CAP joined the stable prefix in slice
  * 2026-09-10-context-audit-and-discipline, Slice C.)

package/dist/services/context/build-dispatch-system-prompt.js

@@ -93,6 +93,47 @@ export const REPORT_CAP_BLOCK = `## Final report cap (mandatory)
 
 Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any longer detail into the artifact file you already own — the parent can \`Read\` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.
 `;
+/**
+ * Slice 2026-09-10-fact-force-gate-adaptation: stand IN FRONT of an external
+ * `PreToolUse` gate instead of explaining its denial after the fact.
+ *
+ * ECC (a third-party plugin under `~/.claude/plugins/`) registers
+ * `gateguard-fact-force.js` on `Edit|Write|MultiEdit`. It denies the first
+ * edit of a file whose facts the agent has not established, and its four-item
+ * message never says two things the agent needs: that the file must be READ
+ * first, and that the edit was NOT applied. Measured failure mode
+ * (session 2026-09-10-session-528a63): the sub-agent reads the denial as
+ * "the tool is broken" and abandons the edit.
+ *
+ * So the block below leads with the STANDING RULE (read before you edit) and
+ * names the paths it covers, and mentions the denial only as the consequence
+ * of skipping that rule. A sub-agent that has never seen the gate can read
+ * this once and never trip it.
+ *
+ * The gate itself is untouched: peaks-loop adapts to it, and does NOT disable,
+ * bypass, or re-implement it. Nor is `ECC_GATEGUARD=off` part of this.
+ *
+ * Always rendered — no opt-out flag and no role split. Every role edits files
+ * outside `.peaks/**`, and only sub-agent #1 of a session sees a denial (the
+ * gate fires once per file), so a role-scoped or opt-in block would leave the
+ * rest of the fleet untold. It joins the stable boilerplate prefix: constant
+ * bytes for every dispatch, prompt-cache friendly.
+ *
+ * The `.peaks/**` exemption is real and pre-dates this slice — peaks-loop
+ * materialises `.claude/settings.local.json` so the gate skips `.peaks/**`
+ * (slice 2.0.1-bug3-fact-forcing-bypass; see
+ * `src/cli/commands/workspace/init-command.ts`).
+ */
+export const FACT_FORCE_GATE_BLOCK = `## Read before you edit (Fact-Forcing Gate)
+
+Read a file BEFORE your first \`Edit\` / \`Write\` / \`MultiEdit\` on it — the normal way to work here, not an optional step. It applies to every path OUTSIDE \`.peaks/**\` (source, tests, docs, config); \`.peaks/**\` writes are exempt.
+
+Skipping that read trips a \`PreToolUse\` plugin gate (ECC's "Fact-Forcing Gate"), which denies the edit. A denial is NOT a failure and the tool is NOT broken — your edit was NOT applied. Read the file, state the four facts the gate asks for (importers, affected API, data schemas if any, the user's verbatim instruction), then retry the same operation. Do not switch tools, do not give up, do not re-attempt blindly.
+`;
+/** Always-on renderer for {@link FACT_FORCE_GATE_BLOCK}. */
+export function renderFactForceGateBlock() {
+    return `${FACT_FORCE_GATE_BLOCK}\n`;
+}
 /**
  * Compose the system-prompt body for a sub-agent dispatch.
  *
@@ -104,7 +145,7 @@ Your FINAL report to the parent MUST be ≤ 40 lines and ≤ 2 KB. Write any lon
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
  * controller brief): when the memory block is unavailable, the composed body is
  * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
- * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * "\n" + REPORT_CAP + "\n" + FACT_FORCE_GATE + "\n" + contextBlock + taskBody`, so the unavailable
  * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
  * (REPORT_CAP joined the stable prefix in slice
  * 2026-09-10-context-audit-and-discipline, Slice C.)
@@ -128,15 +169,17 @@ export function buildDispatchSystemPrompt(input) {
     // for every role — the composer owns the injection so callers MUST NOT
     // prepend `formatTestToolDetection()` themselves (double injection).
     const testToolText = `${formatTestToolDetection()}\n\n`;
+    // 2026-09-10-fact-force-gate-adaptation: always-on, both branches.
+    const factForceGateText = renderFactForceGateBlock();
     const contextBlock = renderContextBlock(contextProbe ?? null);
     const codegraphText = renderCodegraphBlock(codegraphBlock);
     const projectStackText = renderProjectStackBlock(projectStackBlock);
     const freshContextText = renderFreshContextBlock(freshContextBlock);
     const capsuleText = renderCapsulePointer(capsule);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${factForceGateText}${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
+    return `${testToolText}${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${REPORT_CAP_BLOCK}\n${factForceGateText}${contextBlock}${codegraphText}${projectStackText}${freshContextText}${capsuleText}${taskBody}`;
 }
 /**
  * Slice 2026-09-10-dispatch-token-and-swarm §4 — session capsule pointer.
@@ -294,6 +337,15 @@ export const BINDING_RULE_TOKENS = [
     'changed files (one line each)',
     'pass/fail counts',
     'tsc status',
+    // fact-forcing gate (slice 2026-09-10-fact-force-gate-adaptation)
+    '## Read before you edit (Fact-Forcing Gate)',
+    'Read a file BEFORE your first `Edit` / `Write` / `MultiEdit` on it',
+    'every path OUTSIDE `.peaks/**`',
+    '`PreToolUse` plugin gate',
+    'A denial is NOT a failure and the tool is NOT broken',
+    'your edit was NOT applied',
+    'retry the same operation',
+    'do not re-attempt blindly',
     // test scope — ONE unified block, byte-identical for EVERY role
     '## Test Tool Detection (mandatory)',
     '`package.json#scripts.test`',

package/dist/services/lint/detect-ocr-18.d.ts

@@ -7,4 +7,6 @@ export type Ocr18DetectResult = {
     readonly warnings: readonly string[];
     readonly nextActions: readonly string[];
 };
+/** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
+export declare const NPX_PROBE_UNRESOLVED_CODE = "NPX_PROBE_UNRESOLVED";
 export declare function detectOcr18(): Ocr18DetectResult;

package/dist/services/lint/detect-ocr-18.js

@@ -2,22 +2,53 @@
  * 5-state OCR 1.8.x detect. Mirrors the ECC detect shape.
  */
 import { spawnSync } from 'node:child_process';
+import { resolveNpxInvocation } from './npx-resolver.js';
 import { OCR_18_PACKAGE } from './ocr-multilang-adapter.js';
+/** Named code for "npx itself could not be launched" — distinct from "npx is absent". */
+export const NPX_PROBE_UNRESOLVED_CODE = 'NPX_PROBE_UNRESOLVED';
+// 2026-09-10: `npx` on Windows is an `npx.cmd` shim, which Node refuses to spawn
+// without `shell: true` — a bare `spawnSync('npx', …)` failed with ENOENT and was
+// then reported as "npx is not on PATH" on machines where `npx --version` exits 0.
+// The shim is bypassed through `resolveNpxInvocation` (same helper as
+// `detect-eslint.ts`), and a launch failure is reported as its OWN reason rather
+// than being collapsed into "absent".
 function probeNpx() {
-    const probe = spawnSync('npx', ['--version'], { encoding: 'utf8' });
-    return probe.status === 0;
+    const { command, args, baseEnv } = resolveNpxInvocation(['--version']);
+    const probe = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
+    if (probe.status === 0)
+        return { available: true };
+    const error = probe.error;
+    if (error !== undefined && error !== null) {
+        // `command !== 'npx'` ⇒ the resolver located a real npx CLI entry and it STILL
+        // could not be launched — a different failure from "npx is not on PATH".
+        return command !== 'npx'
+            ? { available: false, reason: 'not-launchable', detail: error.message }
+            : { available: false, reason: 'not-on-path', detail: error.message };
+    }
+    return { available: false, reason: 'probe-failed', detail: `npx --version exited ${probe.status ?? 'null'}` };
 }
 function probeOcr18() {
-    const result = spawnSync('npx', ['--package', OCR_18_PACKAGE, '--', 'ocr', 'version'], { encoding: 'utf8' });
+    const { command, args, baseEnv } = resolveNpxInvocation(['--package', OCR_18_PACKAGE, '--', 'ocr', 'version']);
+    const result = spawnSync(command, args, { encoding: 'utf8', env: baseEnv });
     return result.status === 0;
 }
 export function detectOcr18() {
-    if (!probeNpx()) {
+    const probe = probeNpx();
+    if (!probe.available) {
+        if (probe.reason === 'not-launchable') {
+            return {
+                state: 'detection-failed',
+                npxAvailable: false,
+                package: OCR_18_PACKAGE,
+                warnings: [`${NPX_PROBE_UNRESOLVED_CODE}: could not launch npx to probe (${probe.detail}).`],
+                nextActions: ['Ensure Node.js >= 20 with its bundled npm is installed; `npx --version` must succeed.']
+            };
+        }
         return {
             state: 'ocr18-missing',
             npxAvailable: false,
             package: OCR_18_PACKAGE,
-            warnings: ['npx is not on PATH'],
+            warnings: [probe.reason === 'not-on-path' ? 'npx is not on PATH' : probe.detail],
             nextActions: ['Install Node.js ≥ 20 with npm to enable `npx --package`.']
         };
     }

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/skills/hooks-codegate-superpowers.d.ts

@@ -95,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

@@ -233,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 };
+}

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

@@ -68,6 +68,20 @@ export type HookInstallOptions = {
 };
 /** Default (claude-code) hook command — kept as a stable export for tests. */
 export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\" --json";
+/**
+ * One peaks-managed entry paired with the settings file it is (or will be)
+ * written to.
+ *
+ * `entries` is a flat list of the same matcher/sentinel pairs, which reads as
+ * "written to `settingsPath`" even when the entry is routed to the other file
+ * (see `resolveHookTargets`). This carries the routing explicitly so the
+ * dry-run can name the real target without a real run.
+ */
+export type HookEntryTarget = {
+    matcher: string;
+    sentinel: string;
+    settingsPath: string;
+};
 export type HookInstallPlan = {
     scope: HookScope;
     settingsPath: string;
@@ -83,6 +97,8 @@ export type HookInstallPlan = {
      * machine-local). See `resolveHookTargets`.
      */
     localSettingsPath?: string;
+    /** Every entry the install writes, paired with its target file. */
+    entryTargets: ReadonlyArray<HookEntryTarget>;
 };
 export type HookInstallResult = HookInstallPlan & {
     applied: boolean;

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

@@ -4,7 +4,7 @@ import { join, resolve } from 'node:path';
 import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
 import { atomicWriteJson, readJsonObjectFile } from '../ide/shared/atomic-json.js';
 import { getAdapter } from '../ide/ide-registry.js';
-import { resolveHookSpec, resolveHookEntries, resolveLegacySentinels, SUPERPOWERS_DENIED_SKILLS, formatSuperpowersDenyEntry, SUPERPOWERS_DENY_SENTINELS } from './hooks-codegate-superpowers.js';
+import { resolveHookSpec, resolveHookEntries, resolveLegacySentinels, SUPERPOWERS_DENIED_SKILLS, formatSuperpowersDenyEntry, SUPERPOWERS_DENY_SENTINELS, hasExternalGateExemptions, withExternalGateExemptions, withoutExternalGateExemptions } from './hooks-codegate-superpowers.js';
 export { HOOK_ENFORCE_SENTINEL, HOOK_CODE_GATE_SENTINEL, HOOK_CODE_GATE_MATCHER, HOOK_CODE_GATE_EVENT, HOOK_CODE_GATE_COMMAND, SUPERPOWERS_DENIED_SKILLS } from './hooks-codegate-superpowers.js';
 // --- Module-level defaults (claude-code) -----------------------------------
 // These exports remain for backward compat — tests and downstream callers
@@ -67,16 +67,30 @@ function resolveLocalSettingsPath(scope, ide, projectRoot) {
 function resolveHookTargets(scope, ide, projectRoot) {
     const sharedPath = resolveSettingsPath(scope, ide, projectRoot);
     const localPath = resolveLocalSettingsPath(scope, ide, projectRoot);
-    const shared = { settingsPath: sharedPath, entries: [] };
+    const wantsEnvExemptions = ide === 'claude-code';
     if (localPath === undefined || localPath === sharedPath) {
-        return [{ settingsPath: sharedPath, entries: [...resolveHookEntries(ide)] }];
+        // Global scope lands here: the user-level file is already machine-local,
+        // so it is the safe target (there is no sibling to prefer).
+        return [{ settingsPath: sharedPath, entries: [...resolveHookEntries(ide)], envExemptions: wantsEnvExemptions }];
     }
-    const local = { settingsPath: localPath, entries: [] };
+    const shared = { settingsPath: sharedPath, entries: [] };
+    const local = { settingsPath: localPath, entries: [], envExemptions: wantsEnvExemptions };
     for (const entry of resolveHookEntries(ide)) {
         (entry.machineLocal === true ? local : shared).entries.push(entry);
     }
     return [shared, local];
 }
+/** True when `target` already holds everything the install would write to it. */
+function targetIsSatisfied(target, allSentinels) {
+    const settings = readSettingsFile(target.settingsPath);
+    if (!shapeMatchesDesired(settings, target.entries, allSentinels))
+        return false;
+    return target.envExemptions !== true || hasExternalGateExemptions(settings);
+}
+/** Flatten the resolved targets into one `{ matcher, sentinel, settingsPath }` row per entry. */
+function describeEntryTargets(targets) {
+    return targets.flatMap((target) => target.entries.map((entry) => ({ matcher: entry.matcher, sentinel: entry.sentinel, settingsPath: target.settingsPath })));
+}
 /** Read a settings file as an object, or `{}` when it does not exist yet. */
 function readSettingsFile(settingsPath) {
     return existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
@@ -307,11 +321,17 @@ export function planHookInstall(scope, projectRoot, options) {
         scope,
         settingsPath,
         exists,
-        alreadyInstalled: targets.every((t) => isInstalledForEntries(readSettingsFile(t.settingsPath), t.entries)),
+        // The env clause mirrors `applyHookInstall`'s: without it the dry-run would
+        // claim "nothing to do" about a file the install is going to write.
+        alreadyInstalled: targets.every((t) => {
+            const settings = readSettingsFile(t.settingsPath);
+            return isInstalledForEntries(settings, t.entries) && (t.envExemptions !== true || hasExternalGateExemptions(settings));
+        }),
         desiredCommand: spec.hookEnforceCommand,
         sentinel: spec.hookEnforceSentinel,
         matcher: spec.hookEnforceMatcher,
-        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {})
+        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {}),
+        entryTargets: describeEntryTargets(targets)
     };
 }
 /**
@@ -379,7 +399,10 @@ export function applyHookInstall(scope, projectRoot, options) {
     // as not-yet-installed, so the merge strips the stale entry on the
     // next install call. This is the only path that converges the file
     // on the new shape; pure presence-checks are insufficient.
-    const alreadyInstalled = targets.every((t) => shapeMatchesDesired(readSettingsFile(t.settingsPath), t.entries, allSentinels));
+    //
+    // The external-gate exemption is part of the desired shape too, so a project
+    // installed by a release that predates it still converges on upgrade.
+    const alreadyInstalled = targets.every((t) => targetIsSatisfied(t, allSentinels));
     const baseResult = {
         scope,
         settingsPath,
@@ -388,7 +411,8 @@ export function applyHookInstall(scope, projectRoot, options) {
         desiredCommand: spec.hookEnforceCommand,
         sentinel: spec.hookEnforceSentinel,
         matcher: spec.hookEnforceMatcher,
-        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {})
+        ...(localTarget !== undefined ? { localSettingsPath: localTarget.settingsPath } : {}),
+        entryTargets: describeEntryTargets(targets)
     };
     if (baseResult.alreadyInstalled) {
         return { ...baseResult, applied: false };
@@ -409,9 +433,14 @@ export function applyHookInstall(scope, projectRoot, options) {
     //
     // The `permissions.deny` block lives in the adapter's settings file
     // only (as it always has) — it is committed, so the deny list is
-    // shared; the machine-local file carries hook entries only.
+    // shared; the machine-local file carries hook entries plus, for Claude
+    // Code, the third-party gate exemptions (machine-local by the same
+    // argument as the hook `shell` pin).
     for (const target of targets) {
-        const next = withHooksInstalled(readSettingsFile(target.settingsPath), target.entries, allSentinels);
+        let next = withHooksInstalled(readSettingsFile(target.settingsPath), target.entries, allSentinels);
+        if (target.envExemptions === true) {
+            next = withExternalGateExemptions(next);
+        }
         const merged = target.settingsPath === settingsPath
             ? withTriggeredDenyList(withSuperpowersSkillDenylist(next))
             : next;
@@ -478,9 +507,13 @@ export function removeHookInstall(scope, projectRoot, options) {
         // trigger-style deny entries via withoutTriggeredDenyList. The
         // chain of helpers is order-independent (each is idempotent and
         // additive over the same set of peaks-managed entries).
-        const finalSettings = target.settingsPath === settingsPath
-            ? withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(nextSettings))
-            : nextSettings;
+        let finalSettings = nextSettings;
+        if (target.envExemptions === true) {
+            finalSettings = withoutExternalGateExemptions(finalSettings);
+        }
+        if (target.settingsPath === settingsPath) {
+            finalSettings = withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(finalSettings));
+        }
         atomicWriteJson(target.settingsPath, finalSettings);
     }
     return {

package/dist/services/workspace/claude-settings-template.d.ts

@@ -75,14 +75,23 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  *           string carries no shell-escaped payload at all and the handler
  *           can take the same platform `shell` pin as its siblings. The
  *           decision itself is a verbatim relocation — see that file.
+ *   1.7.0 — added the `env` block declaring Peaks' workspace tree exempt
+ *           from a THIRD-PARTY PreToolUse fact-forcing gate
+ *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
+ *           on-disk file to declare those exemptions too, so a project
+ *           installed by an earlier release refreshes once and converges.
  */
-export declare const TEMPLATE_VERSION = "1.6.0";
+export declare const TEMPLATE_VERSION = "1.7.0";
 /**
- * Compare two serialized template strings for semantic equivalence.
+ * Compare two serialized template strings for semantic equivalence: does the
+ * on-disk file already declare everything the generated template declares?
  *
  * Returns `true` iff both strings parse to objects whose
  * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) AND the
+ * on-disk `env` already carries every exemption the template declares (extra
+ * on-disk keys and extra globs are allowed — a user may exempt other trees,
+ * and a requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -120,6 +129,13 @@ type ClaudeSettingsLocal = {
     hooks: {
         PreToolUse: ClaudePreToolUseEntry[];
     };
+    /**
+     * Exemptions declared to the third-party PreToolUse gate peaks does not own
+     * (`EXTERNAL_GATE_EXEMPT_ENV`). They belong in THIS file because it is
+     * machine-local and gitignored: a third-party variable name in the committed
+     * shared `settings.json` would be pushed to every consumer of the project.
+     */
+    env: Record<string, string>;
 };
 /**
  * Build the full template object. The shape is the subset of Claude

package/dist/services/workspace/claude-settings-template.js

@@ -35,7 +35,7 @@
  */
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
+import { EXTERNAL_GATE_EXEMPT_ENV, hasExternalGateExemptions, resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
 export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
 /**
  * Informational version of the offline template shape. Bumped when the
@@ -78,14 +78,23 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           string carries no shell-escaped payload at all and the handler
  *           can take the same platform `shell` pin as its siblings. The
  *           decision itself is a verbatim relocation — see that file.
+ *   1.7.0 — added the `env` block declaring Peaks' workspace tree exempt
+ *           from a THIRD-PARTY PreToolUse fact-forcing gate
+ *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
+ *           on-disk file to declare those exemptions too, so a project
+ *           installed by an earlier release refreshes once and converges.
  */
-export const TEMPLATE_VERSION = '1.6.0';
+export const TEMPLATE_VERSION = '1.7.0';
 /**
- * Compare two serialized template strings for semantic equivalence.
+ * Compare two serialized template strings for semantic equivalence: does the
+ * on-disk file already declare everything the generated template declares?
  *
  * Returns `true` iff both strings parse to objects whose
  * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) AND the
+ * on-disk `env` already carries every exemption the template declares (extra
+ * on-disk keys and extra globs are allowed — a user may exempt other trees,
+ * and a requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -127,7 +136,12 @@ export function templateContentMatches(generated, onDisk) {
             return false;
         }
     }
-    return true;
+    // A project installed by a release that predates a template-declared
+    // exemption still needs the refresh this comparator gates — otherwise the
+    // entry would only ever appear on a machine that re-ran `peaks hooks
+    // install`. `hasExternalGateExemptions` is the same predicate the installer
+    // uses, so the two writers cannot drift apart.
+    return hasExternalGateExemptions({ env: parsedOnDisk.env });
 }
 function isTemplateShape(value) {
     if (typeof value !== 'object' || value === null) {
@@ -234,6 +248,12 @@ export function buildClaudeSettingsLocalJson() {
     // the key entirely.
     const writeShell = resolveHookShell();
     return {
+        // Slice emit-gateguard-exemption — the third-party gate exemption. Peaks
+        // already bypasses its OWN fact-forcing gate for `.peaks/**` (the
+        // Write|Edit|MultiEdit handler below); this is the same intent declared in
+        // the currency an external PreToolUse gate reads. `peaks hooks install`
+        // merges the same row into this file, so the two writers agree.
+        env: { ...EXTERNAL_GATE_EXEMPT_ENV },
         hooks: {
             PreToolUse: [
                 {

package/dist/services/workspace/workspace-claude-settings-materializer.js

@@ -9,10 +9,37 @@
  * the parent module and calls into this sibling. Function signatures
  * and behaviour are unchanged (verbatim move).
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { withExternalGateExemptions } from '../skills/hooks-codegate-superpowers.js';
 import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
+/** Read a file as text, or `undefined` when it cannot be read. */
+function readTextIfPresent(filePath) {
+    try {
+        return readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `env` object of a serialized settings file, or `undefined` when the file
+ * is malformed or has no `env` object. Tolerant on purpose: a bad on-disk file
+ * must not stop the materialization.
+ */
+function readEnvObject(serialized) {
+    try {
+        const parsed = JSON.parse(serialized);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const env = parsed.env;
+        return typeof env === 'object' && env !== null && !Array.isArray(env) ? env : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * The peaks-managed snippet appended to the consumer project's
  * `.peaks/.gitignore` so the local-only settings file never lands
@@ -66,7 +93,15 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
     const settingsRel = CLAUDE_SETTINGS_LOCAL_FILENAME;
     const settingsPath = join(projectRoot, settingsRel);
     const template = buildClaudeSettingsLocalJson();
-    const serialized = JSON.stringify(template, null, 2) + '\n';
+    const fileExists = existsSync(settingsPath);
+    const existing = fileExists ? readTextIfPresent(settingsPath) : undefined;
+    // `.claude/settings.local.json` has a second writer: `peaks hooks install`
+    // unions the user's own exemption globs into `env`. Carry that value across
+    // the rewrite this function is about to do, or a refresh would silently
+    // drop someone else's exemptions. The template's own row is added on top, so
+    // the result is a union either way.
+    const onDiskEnv = existing === undefined ? undefined : readEnvObject(existing);
+    const serialized = JSON.stringify(withExternalGateExemptions(onDiskEnv === undefined ? template : { ...template, env: onDiskEnv }), null, 2) + '\n';
     // Always drop (or self-heal) a copy of the template under .peaks/
     // so the --no-claude-hooks recovery flow has a known source-of-truth
     // on disk. The file is gitignored by the snippet below.
@@ -84,27 +119,15 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
     // hooks-settings-service applies the safety check for the Bash
     // gate-enforce path).
     await mkdir(join(projectRoot, '.claude'), { recursive: true });
-    let action = 'written';
-    if (existsSync(settingsPath)) {
-        try {
-            const { readFile } = await import('node:fs/promises');
-            const existing = await readFile(settingsPath, 'utf8');
-            // Structural comparison (not a byte comparison): `peaks hooks
-            // install` also writes this file, through a different serializer, so
-            // an equal hooks tree must be recognized as current or every init
-            // would rewrite the file and drop the installer's entries.
-            if (templateContentMatches(serialized, existing)) {
-                action = 'already-current';
-            }
-            else {
-                action = 'refreshed';
-            }
-        }
-        catch {
-            // Treat any read failure as "needs refresh" so the consumer
-            // always ends up with a valid template on disk.
-            action = 'refreshed';
-        }
+    // An existing-but-unreadable file is treated as drifted, so the consumer
+    // always ends up with a valid template on disk.
+    let action = fileExists ? 'refreshed' : 'written';
+    // Structural comparison (not a byte comparison): `peaks hooks install` also
+    // writes this file, through a different serializer, so an equal hooks tree
+    // must be recognized as current or every init would rewrite the file and
+    // drop the installer's entries.
+    if (existing !== undefined && templateContentMatches(serialized, existing)) {
+        action = 'already-current';
     }
     if (action !== 'already-current') {
         await writeFile(settingsPath, serialized, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.37",
+  "version": "4.0.38",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-mut": "0.1.35",
-    "peaks-loop-internal-runtime": "0.0.22",
-    "peaks-loop-shared-channel": "0.0.39",
-    "peaks-loop-shared": "0.0.71"
+    "peaks-loop-internal-runtime": "0.0.23",
+    "peaks-loop-shared": "0.0.72",
+    "peaks-loop-mut": "0.1.36",
+    "peaks-loop-shared-channel": "0.0.40"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",