peaks-loop 4.0.41 → 4.0.42

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 4.0.42 — 2026-09-12 (peaks 自己的钩子在每次编辑时报错)
+
+**Highlights**:
+
+1. **`write-gate.js` 每次编辑都向模型报一次"钩子错误" —— 已修。** 这个钩子挂在 `Write|Edit|MultiEdit` 上,判定是 `p.includes('.peaks/_runtime/') ? 0 : 1`。**而开发者真正编辑的每一个文件都不在 `.peaks/_runtime/` 下**,所以它**每次编辑都返回退出码 1**。
+
+   Claude Code 的协议里,**只有 exit 2 会阻断**;任何其他非零退出码都是**非阻断错误** —— 工具照跑,但 transcript 里出现 `<hook> hook error` 加 `Failed with non-blocking status code:` 和 stderr 首行;stderr 为空时显示 `No stderr output`。**这正是用户 Mac 日志里那行。**
+
+   - 更糟的是**文档把它写成了契约**。`HOOKS.md` 与文件头都写着 *"exit 1 = fall through to the gate"* —— **没有 fall-through 这个概念**:所有匹配的 PreToolUse 钩子**并行运行**,结果按 `deny > defer > ask > allow` 合并,不存在"交给下一个"。正确的弃权是 **exit 0 + 无输出**,文档定义为 *"no decision"*。
+   - 所以"静默的 fall-through"实际上是**当时可用的最响的结果**。**行为对所有路径完全不变**(它从不阻断),变的只是它不再一边弃权一边报错。
+   - **同行早就做对了**:`pre-tool-code-gate.sh` 用 exit 0 弃权、只在拒绝路径用 exit 2;`pre-tool-superpowers-bridge.sh` 全路径 exit 0。`write-gate.js` 是唯一的异类 —— 这是收敛一个文件的偏差,不是重新设计。
+   - 三处一起改:代码、`.claude/HOOKS.md` 契约行、以及**钉着 exit-1 映射的 32 用例判定表**(已实测对旧 `decide` 会失败)。判定表现在是"路径清单 + 一条真属性":每条路径都弃权,且两个流都为空。
+
+2. **一个必须说明的保留。** 已知有**独立**报告称钩子 exit 0 时标签仍显示 `hook error`。所以**修完不等于那行必然消失** —— 需要实测;若仍在,用 `claude --debug-file` 查看每个钩子的真实退出码。
+
+**验证**:三个版本常量一致(4.0.42);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **188 files / 1794 passed / 3 skipped / 0 failed**。
+
 ## 4.0.41 — 2026-09-11 (闸门指导不再鼓励"每次编辑前念一遍")
 
 **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.41 (2026-09-11) |
+| **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.42 (2026-09-12) |
 | **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.41(2026-09-11) |
+| **最新版本** | [![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.42(2026-09-12) |
 | **覆盖域** | 代码(`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/services/hooks/write-gate.js

@@ -31,10 +31,11 @@
  *     `scripts/copy-templates.mjs`), which lets one emitted path string be
  *     valid for both the repo and an installed consumer.
  *
- * Contract (`.claude/HOOKS.md`): exit 0 = allow, exit 1 = fall through to the
- * gate — NOT a deny. Only exit 2 blocks a tool call, and this handler never
- * returns it. This handler's job is to stay silent on the paths the gate is
- * meant to skip.
+ * Contract (`.claude/HOOKS.md`): this handler ALWAYS ABSTAINS: exit 0, no
+ * output, on every path. Only exit 2 blocks a tool call, and this handler
+ * never returns it, so any other non-zero exit is a non-blocking ERROR
+ * rather than a decision. See `decide` below for the correction this file
+ * went through.
  *
  * Path source: the hook payload arrives as JSON on STDIN (Claude Code's
  * documented channel; it appends no argv). `process.argv[2]` is honoured as a
@@ -57,11 +58,31 @@ function candidatePath(payload) {
 }
 
 /**
- * The gate decision: allow (0) only for paths under `.peaks/_runtime/`;
- * everything else falls through to the gate (1).
+ * This handler ABSTAINS on every path, including `.peaks/_runtime/`.
+ *
+ * It used to return 1 for anything outside `.peaks/_runtime/`, documented as
+ * "fall through to the gate". That concept does not exist in the Claude Code
+ * hook protocol. Exit 2 is the only code that blocks; every other non-zero
+ * exit is a NON-BLOCKING ERROR — the action still proceeds, but the transcript
+ * shows `<hook> hook error` followed by `Failed with non-blocking status code:
+ * No stderr output`. The "silent fall-through" was therefore the LOUDEST
+ * available outcome, reported once per edit for every path a developer
+ * actually touches.
+ *
+ * The documented abstention is exit 0 with no output: "no decision". All
+ * matching PreToolUse hooks run in parallel and their results are merged
+ * (`deny` > `defer` > `ask` > `allow`), so abstaining neither approves the call
+ * nor suppresses a sibling's deny — the fact gate still applies to every path
+ * it always applied to.
+ *
+ * Runtime behaviour is unchanged for every path. What changes is that the
+ * handler stops reporting a spurious error while abstaining.
  */
 function decide(p) {
-  return p.includes('.peaks/_runtime/') ? 0 : 1;
+  // The path is still read (it is the payload's whole point) but no longer
+  // branches: every path abstains.
+  void p;
+  return 0;
 }
 
 const ARGV_PATH = typeof process.argv[2] === 'string' ? process.argv[2] : '';
@@ -80,8 +101,10 @@ process.stdin.on('end', () => {
   try {
     payload = JSON.parse(raw);
   } catch {
-    // Malformed or empty payload → no path → deny, which is the same
-    // outcome the old form produced for an absent `process.argv[1]`.
+    // Malformed or empty payload → no path. This is NOT a deny: `decide`
+    // abstains for every input including the empty string, and a deny would
+    // take exit 2. The old comment here said "deny" while returning 1, which
+    // is the non-blocking error — the same misreading this file corrects.
     payload = undefined;
   }
   process.exit(decide(candidatePath(payload) || ARGV_PATH));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.41",
+  "version": "4.0.42",
   "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-internal-runtime": "0.0.26",
-    "peaks-loop-shared-channel": "0.0.43",
-    "peaks-loop-mut": "0.1.39",
-    "peaks-loop-shared": "0.0.75"
+    "peaks-loop-internal-runtime": "0.0.27",
+    "peaks-loop-shared": "0.0.76",
+    "peaks-loop-mut": "0.1.40",
+    "peaks-loop-shared-channel": "0.0.44"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",