peaks-loop 4.1.15 → 4.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.15"
4
+ "version": "4.1.17"
5
5
  },
6
6
  "plugins": [
7
7
  {
8
8
  "name": "peaks-loop",
9
9
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
10
- "version": "4.1.15",
10
+ "version": "4.1.17",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,114 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.17 — 2026-10-22(相对路径按它**在哪个目录**判,不按它**怎么拼写**判)
4
+
5
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
6
+ 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
7
+ peaks-code 的 11 步工序与 Gate A–G **一字不改**。
8
+ 上一版(4.1.16)把相对路径的**基准**改成了"工具调用实际所在的目录",但**基准与项目根是按字面比较的** ——
9
+ 本次把这个洞收口。
10
+
11
+ ### 1. 一个目录可以有两种拼法,判决不能因此不同
12
+
13
+ - 此前:相对路径的**基准**(工具调用的目录)与**项目根**按**字面**比较。路径里有符号链接时,
14
+ 两者对不上 ⇒ 门禁判定"文件在项目外" ⇒ 退回**按拼写读** ⇒ 拼得像 `src/` 的写法**被放行**。
15
+ - **macOS 上这不是假设**:测试 harness 的项目根来自 `mkdtempSync(tmpdir())`,是**非规范**的
16
+ `/var/folders/...`;而门禁进程自己的工作目录是**规范**的 `/private/var/...`(`/var` 是
17
+ `private/var` 的符号链接)。两者一错配就中招 ⇒ **4.1.16 推上去时 `macos-latest` 那条 job 是红的**,
18
+ 8 个用例失败。**Windows 一个月没暴露,只因为本机 temp 路径里没有符号链接。**
19
+ - 现在:路径读**两遍** —— **词面**(怎么写的)与**规范**(文件真实在哪)—— 判决取**最严**的那个。
20
+ **白名单是每一遍各自先判的**:一遍命中白名单不会因为另一遍命中族而变成拒绝。
21
+ - **裁决原则用的是本仓库自己的那条**(见 4.1.15):**误放是漏洞,误拒只是碍事**。
22
+ 所以**不是**"规范读法当权威"——那会在 `src` → `shared/src` 这种常见布局里**放宽**门禁
23
+ (词面 `src/x.ts` 拒、规范 `shared/src/x.ts` 放行);而是**任一遍命中族就拒**。
24
+
25
+ ### 2. `.sh` 兄弟实现也走同一条规则
26
+
27
+ 它原本只按**拼写**判,于是和 Node 版**越漂越远**:Node 拒的写法它放行。
28
+ 现在它取同样两遍读法、取同样的最严判决,而且**规范读法相对的是它自己解析出来的那个基准** ——
29
+ 两套实现因此不可能对"文件在哪"给出不同答案。
30
+ **两个实现同一条规则,就必须互相测,而不是各自对着自己的预期测。**
31
+
32
+ ### 3. 被有意接受的取舍(写在这里以免看起来像疏漏)
33
+
34
+ - **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁。
35
+ - **一个被纠正的误拒**:当**基准在非族目录**(例如 `<root>/docs`)时,旧的拼写锚定规则会把
36
+ `src/x.ts` 这类写法**拒**掉,而那些文件其实落在 `<root>/docs/…`、**在所有硬阻断族之外**。
37
+ 现在按文件真实所在判 ⇒ **放行**。这是**放宽**,方向是裁定自己的不变量(判决跟文件走,不跟拼写走),
38
+ **已接受并记录**(不 claim 掉)。
39
+ - **兄弟实现还有三处已知短板**(它**读不到** payload 顶层 `cwd`、**推导**项目根、**无法相对化绝对路径**),
40
+ 归在 backlog §19.1/§19.2 的 owner 决策里,不在本次收口。
41
+
42
+ ### 4. 验证
43
+
44
+ - 与**改动前**的代码逐行对照:**896 行里 0 行**让任一实现放行了落在拒绝族里的文件。
45
+ - **不得放宽**:Node 命令**收紧 92 / 放宽 0**;兄弟实现**收紧 76 / 放宽 0**。
46
+ 相对**切片前**的代码,Node 112/40、兄弟 108/36 —— 那 76 个放宽**全部**在非族目录的基准上,
47
+ 每个文件都落在所有族之外(§3 那个被纠正的误拒),**不是洞**。
48
+ - 家族成员零行改动,fail-open 不变,fast lane 仍然打开这些族。
49
+ - **顺手订正一句注释**:它描述了一种代码并不做的比较(审计里的第六条 LOW)——现在它说的是代码做的事。
50
+ - 另附一条**实测**:门禁读的 payload 顶层 `cwd` **确实是 PreToolUse payload 的顶层字段**
51
+ (对着本机装的 Claude Code 二进制读到构造点,不是推断);**任何 IDE 都会这么发**这一条**仍未实测**。
52
+
53
+ ## 4.1.16 — 2026-10-22(相对路径按工具调用实际所在的目录解析)
54
+
55
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
56
+ 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
57
+ peaks-code 的 11 步工序与 Gate A–G **一字不改**。
58
+ 上一版(4.1.15)在 QA 复核里**诚实记下了一个洞**:工具调用的工作目录不是项目根时,
59
+ 相对路径落在 `src/` 里却被放行 —— "判定只由文件落在哪个目录决定"这条不变量**还没有完全成立**。
60
+ **本次把它收口。**
61
+
62
+ ### 1. 相对路径的基准:工具调用实际所在的目录
63
+
64
+ - 此前:相对路径按**调用方指定的项目根**解析。于是 cwd 是 `<root>/src`、payload 是
65
+ `deep/x.ts` 时,这个路径其实指向 `<root>/src/deep/x.ts` —— **落在 `src/` 里、应当被拒**,
66
+ 而门禁**放行**了。逃逸是**静默**的。
67
+ - 现在:相对路径按**工具调用实际所在的目录**解析。来源有两条,先用前者:
68
+ payload **顶层**的 `cwd`(IDE 给了就用),否则**门禁进程自己的工作目录**。
69
+ **族仍然相对调用方指定的项目根**比;**绝对路径规则不变**;**嵌在 git 仓库里的项目仍然判自己**。
70
+ - **代价(有意接受,写在这里以免看起来像疏漏)**:基准选错会误拒邻近目录的文件。而回退基准是
71
+ 门禁进程的 cwd —— 正常调用里 hook 就跑在工具调用的目录上,所以那条回退**就是**工具调用的目录。
72
+
73
+ ### 2. 两个逃逸
74
+
75
+ - ⚠️ **`.sh` 兄弟实现的 `./` 剥离**:它把 `.//deep/x.ts` 剥成前导 `/`,于是被当成**绝对路径**、
76
+ **永不相对化** ⇒ 落在所有族之外 ⇒ **放行**。而那个文件在 `<root>/src/deep/x.ts`,**在 `src/` 里**。
77
+ **同一个文件的 10 种拼法里 6 种,两套实现的判决相反** —— 而**两套实现各自的单测都是绿的**。
78
+ 现在:"是不是绝对路径"按**未经剥离的原样拼写**判定。
79
+ - ⚠️ **Node 命令信任了一个不是目录的 payload `cwd`**:payload 说了一个不存在、或者不是目录、
80
+ 或者相对的地方,路径因此解析到项目之外,"按拼写回退"那条老路又被走到 ⇒ **逃逸重新打开**。
81
+ 现在 payload `cwd` **只有**在"**绝对路径 + 存在的目录 + 在指名的项目之内**"三件事同时成立时才被采信;
82
+ 否则用**门禁进程自己的工作目录**。⇒ **修复不依赖 payload 的 `cwd` 存在或正确**。
83
+
84
+ ### 3. 必须保持的性质(逐条复验)
85
+
86
+ - **fail-open 策略不变**:payload 判不了时**仍然放行**,stderr 上仍留 `PEAKS_CODE_GATE_UNDECIDABLE`。
87
+ - **六个族的成员不变**:`HARD_BLOCKED_PATH_FAMILIES` 与 `ALLOW_LISTED_PATH_PATTERNS` **零行改动**。
88
+ - **fast lane 仍然打开这些族**:租约是 `peaks-race-code` 时,`src/` 的编辑仍然**放行**。
89
+ - **门禁没有被削弱**:本次**多拒**了原先放行的(那正是逃逸),方向是**收紧**而不是放宽。
90
+
91
+ ### 4. 留下的东西(写清楚,免得看起来像漏了)
92
+
93
+ - **落在项目之外的相对路径**仍按"拼写相对项目根"读 ⇒ **不会放宽**门禁:它会拒一个拼得像族、
94
+ 而文件其实没落在那里的路径 —— **误拒只是碍事,误放才是漏洞**。
95
+ - **一个残留**:payload `cwd` 不可用**且**门禁进程不在工具调用的目录里时,路径会按错误的树解析,
96
+ 项目内的文件**可能**被放行。**改动前同样放行**(它按项目根解析)⇒ **残留,不是回归**;
97
+ 而门禁本来就不装在那个位置。**这个形状与 §2.13 的根 `dist/` 轴同源**:拿一个不属于自己的基准去解析。
98
+ - **任何 IDE 报的顶层 `cwd` 至今未实测**(PATH 上的 `claude.exe` 是个 546 KB 启动器,没有 payload
99
+ 字符串;本机装的 `@anthropic-ai/claude-code` 二进制里读到的 hook-input 形状是**一次 grep 的转述**,
100
+ QA **没能复现**它)⇒ 所以修复**不依赖**它,回退路径自己扛得住。
101
+
102
+ ### 5. QA 独立复核
103
+
104
+ **PASS**(8 条验收标准)。两轮 RD、两轮 QA:QA 第一轮 `return-to-rd`,给的两条缺陷都被独立复现过。
105
+ 证据:
106
+
107
+ - 与**改动前**的代码逐行对照 **72 组(action + reason):0 处差异**;
108
+ - 两套实现在 **29 种拼法上 29/29 一致**,**65 行族矩阵 65/65 都拒**;
109
+ - **10 种拼法 0 分歧**(改动前 6 种分歧);
110
+ - **六种不可用的 `cwd` + 完全没有 `cwd`:全部拒**。
111
+
3
112
  ## 4.1.15 — 2026-10-22(门禁剩下的三种写法也不再决定判定)
4
113
 
5
114
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
@@ -22,6 +22,7 @@
22
22
  import { resolve } from 'node:path';
23
23
  import { addJsonOption, printResult } from '../cli-helpers.js';
24
24
  import { decideGateAction, extractFilePath, isGatedTool } from '../../services/hooks/pre-tool-code-gate.js';
25
+ import { resolveToolCallBaseDir } from '../../services/hooks/hook-payload-cwd.js';
25
26
  import { hasLeaseForCaller, resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
26
27
  import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
27
28
  import { pluckObject, pluckString } from '../../services/ide/hook-translator.js';
@@ -60,6 +61,16 @@ function resolveDriver(projectRoot, payload) {
60
61
  return null;
61
62
  return resolveActiveSkillForCaller(projectRoot, { callerId }).skill;
62
63
  }
64
+ /**
65
+ * The directory the tool call runs in: the payload's own `cwd` when it names
66
+ * a usable one, and the gate process's own working directory otherwise — the
67
+ * directory the harness ran the hook in. Neither source is guessed: the
68
+ * payload is read at its top level, and the process's own directory is a fact
69
+ * about this process.
70
+ */
71
+ function resolveToolCallDir(payload, projectRoot) {
72
+ return resolveToolCallBaseDir(payload, projectRoot, process.cwd());
73
+ }
63
74
  /**
64
75
  * The marker the gate leaves on stderr when it could not decide.
65
76
  *
@@ -172,9 +183,13 @@ export function registerCodeGateCommand(program, io) {
172
183
  // is judged against ITSELF, not against the git root above it. One file
173
184
  // must not get two verdicts from two spellings, and a project that is not
174
185
  // the git root is exactly where the two would differ.
186
+ // The tool call's OWN directory is a third fact: it is the base a
187
+ // relative path is read against.
175
188
  const namedRoot = resolve(opts.project ?? process.cwd());
176
189
  const canonicalRoot = resolveCanonicalProjectRoot(namedRoot);
177
- const verdict = decideGateAction(tool, input, resolveDriver(canonicalRoot, parsed), namedRoot);
190
+ const driver = resolveDriver(canonicalRoot, parsed);
191
+ const toolCwd = resolveToolCallDir(parsed, namedRoot);
192
+ const verdict = decideGateAction(tool, input, driver, { projectRoot: namedRoot, toolCwd });
178
193
  if (opts.dryRun === true) {
179
194
  printDryRunVerdict(io, opts.json === true, { tool, input, verdict, undecidable });
180
195
  return;
@@ -0,0 +1,91 @@
1
+ /**
2
+ * The ONE spelling-independent form of a target path, and the roots a
3
+ * verdict is taken against.
4
+ *
5
+ * The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
6
+ * so how the incoming path happens to be SPELLED must not decide the verdict:
7
+ * `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
8
+ * file and must get one verdict. Without this, the same edit is denied in one
9
+ * spelling and allowed in another — and the allow is the one that happens.
10
+ *
11
+ * A RELATIVE path is read against the directory the tool call RUNS IN, not
12
+ * against the project root: the file the call writes is the one that
13
+ * directory names, and the two differ whenever the call runs in a
14
+ * subdirectory. The file it lands in is then judged by where it sits inside
15
+ * the project, so the families still name this project's directories.
16
+ *
17
+ * Two readings of one file are offered: the LEXICAL one (`normalizeGatePath`)
18
+ * and the CANONICAL one (`canonicalGatePath`). One directory can be named
19
+ * two ways, and the caller takes the STRICTEST of the two — a wrongly
20
+ * allowed edit is a hole in the gate, a wrongly refused one is only an
21
+ * inconvenience.
22
+ *
23
+ * The arithmetic lives apart from the decision on purpose: the decision is
24
+ * the gate's rule, and this is the path arithmetic it rests on. The file the
25
+ * decision sits in was at its size cap, and the arithmetic needs room.
26
+ */
27
+ /**
28
+ * The roots a verdict is taken against: the project the caller named, and
29
+ * the directory the tool call runs in. A bare string is the project root
30
+ * alone — the shape every earlier call used.
31
+ */
32
+ export interface GateRootPair {
33
+ readonly projectRoot?: string | null;
34
+ readonly toolCwd?: string | null;
35
+ }
36
+ /** The roots, in either of the two spellings. */
37
+ export type GateRoots = string | null | GateRootPair;
38
+ /**
39
+ * The one form of a target path the families are written in.
40
+ *
41
+ * - separators fold to `/` (a Windows payload spells `src\x.ts`)
42
+ * - a leading `./` is dropped
43
+ * - a `..` segment is resolved
44
+ * - an ABSOLUTE path inside `projectRoot` becomes project-relative
45
+ * - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
46
+ * THIS project's directories, and a path in another repository is another
47
+ * project's business. That is also what the gate already did with every
48
+ * absolute path, so it is not a widening.
49
+ * - with no `projectRoot` an absolute path cannot be made relative and is
50
+ * left as it is
51
+ *
52
+ * A RELATIVE path is read against `toolCwd` — the directory the tool call
53
+ * runs in — and the file it lands in is judged by where it sits inside the
54
+ * project. A path that lands OUTSIDE the project keeps the older reading,
55
+ * the spelling read against the project root, which never widens the gate:
56
+ * it refuses a spelled family the file itself never reached.
57
+ *
58
+ * "Inside" and "outside" are asked LEXICALLY first and CANONICALLY second
59
+ * (see `relativizeInsideRoot`), so two spellings of one directory reach one
60
+ * verdict.
61
+ *
62
+ * This is the LEXICAL reading. The CANONICAL reading — the file named by the
63
+ * directory it really sits in — is a separate question, asked by
64
+ * `canonicalGatePath`.
65
+ */
66
+ export declare function normalizeGatePath(filePath: string, projectRoot?: string | null, toolCwd?: string | null): string;
67
+ /** The roots, whichever of the two spellings the caller used. */
68
+ export declare function rootPair(roots: GateRoots | undefined): GateRootPair;
69
+ /**
70
+ * The CANONICAL project-relative form of a target path: the file the call
71
+ * really touches, named by the directory it REALLY sits in.
72
+ *
73
+ * The lexical form says how the path is WRITTEN; this one says where the
74
+ * file IS. The two differ whenever a directory is named two ways — a
75
+ * symlink, a junction, macOS's `/var` → `/private/var` — and the difference
76
+ * is what a symlinked BASE inside the project looks like: the call runs in
77
+ * `link/`, the file is in `src/`, and the lexical form says `link/x.ts`
78
+ * (no family) while this one says `src/x.ts` (a family).
79
+ *
80
+ * The two sides are compared as they are CANONICALLY spelled, so the answer
81
+ * is the directory the file is in and not the spelling the caller used to
82
+ * reach it. The LEXICAL-first-then-canonical retry belongs to the other
83
+ * reading (`relativizeInsideRoot`), which needs it because a lexical answer
84
+ * can be a statement about the SPELLING rather than about the directory.
85
+ *
86
+ * `null` when the file is outside the project: the project has no name for
87
+ * it, and the spelling-anchored reading the caller already holds is the one
88
+ * that applies. `null` also when there is no project root at all, for the
89
+ * same reason — a path cannot be made relative to nothing.
90
+ */
91
+ export declare function canonicalGatePath(filePath: string, projectRoot?: string | null, toolCwd?: string | null): string | null;
@@ -0,0 +1,191 @@
1
+ /**
2
+ * The ONE spelling-independent form of a target path, and the roots a
3
+ * verdict is taken against.
4
+ *
5
+ * The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
6
+ * so how the incoming path happens to be SPELLED must not decide the verdict:
7
+ * `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
8
+ * file and must get one verdict. Without this, the same edit is denied in one
9
+ * spelling and allowed in another — and the allow is the one that happens.
10
+ *
11
+ * A RELATIVE path is read against the directory the tool call RUNS IN, not
12
+ * against the project root: the file the call writes is the one that
13
+ * directory names, and the two differ whenever the call runs in a
14
+ * subdirectory. The file it lands in is then judged by where it sits inside
15
+ * the project, so the families still name this project's directories.
16
+ *
17
+ * Two readings of one file are offered: the LEXICAL one (`normalizeGatePath`)
18
+ * and the CANONICAL one (`canonicalGatePath`). One directory can be named
19
+ * two ways, and the caller takes the STRICTEST of the two — a wrongly
20
+ * allowed edit is a hole in the gate, a wrongly refused one is only an
21
+ * inconvenience.
22
+ *
23
+ * The arithmetic lives apart from the decision on purpose: the decision is
24
+ * the gate's rule, and this is the path arithmetic it rests on. The file the
25
+ * decision sits in was at its size cap, and the arithmetic needs room.
26
+ */
27
+ import { isAbsolute, relative, resolve } from 'node:path';
28
+ import { normalizePath, stablePath } from '../../shared/path-utils.js';
29
+ /** The directory a path is resolved against, or `null` when there is none. */
30
+ function resolvedDirectory(value) {
31
+ return typeof value === 'string' && value.length > 0 ? resolve(value) : null;
32
+ }
33
+ /** Drop every leading `./` segment: `./src/x.ts` and `src/x.ts` are one path. */
34
+ function stripLeadingDotSegments(path) {
35
+ let out = path;
36
+ while (out.startsWith('./'))
37
+ out = out.slice(2);
38
+ return out;
39
+ }
40
+ /**
41
+ * Collapse the `.` and `..` segments of a RELATIVE path, lexically.
42
+ *
43
+ * The base directory does not enter the answer for a path that stays inside
44
+ * it: a `..` cancels the segment before it, for every base. A `..` that would
45
+ * leave the base is KEPT, so the result still reads as "outside", and a path
46
+ * outside the project belongs to no family.
47
+ */
48
+ function collapseRelativeDotSegments(path) {
49
+ const out = [];
50
+ for (const segment of path.split('/')) {
51
+ if (segment === '' || segment === '.')
52
+ continue;
53
+ if (segment === '..') {
54
+ const last = out.length > 0 ? out[out.length - 1] : null;
55
+ if (last !== null && last !== '..')
56
+ out.pop();
57
+ else
58
+ out.push('..');
59
+ continue;
60
+ }
61
+ out.push(segment);
62
+ }
63
+ return out.join('/');
64
+ }
65
+ /**
66
+ * The path of `target` relative to `root`, compared LEXICALLY: `null` when
67
+ * `target` is not inside `root` — it is outside the root, or it is the root.
68
+ */
69
+ function relativizeLexically(target, root) {
70
+ const relativePath = normalizePath(relative(root, target));
71
+ if (relativePath.length === 0)
72
+ return null;
73
+ if (relativePath.startsWith('..') || isAbsolute(relativePath))
74
+ return null;
75
+ return stripLeadingDotSegments(relativePath);
76
+ }
77
+ /**
78
+ * The path of `target` relative to `root`, when `target` is INSIDE `root`;
79
+ * `null` when it is not — the target is outside the root, or it is the root.
80
+ *
81
+ * The answer is LEXICAL first: the two sides are compared as they are
82
+ * written, so the common case costs no syscall. When the lexical answer is
83
+ * "outside", the question is asked again with the CANONICAL spelling of both
84
+ * sides, because one directory can be named two ways — a symlink, a junction,
85
+ * macOS's `/var` → `/private/var` — and then the lexical answer is a
86
+ * statement about the SPELLING, not about the directory the file is in. The
87
+ * retry can only turn "outside" into "inside", so it can only tighten the
88
+ * gate; whenever the lexical answer says "inside", that answer stands.
89
+ *
90
+ * The canonical answer is relativized against the CANONICAL root, because
91
+ * the project-relative spelling it produces is what the deny families are
92
+ * matched against.
93
+ */
94
+ function relativizeInsideRoot(target, root) {
95
+ const lexical = relativizeLexically(target, root);
96
+ if (lexical !== null)
97
+ return lexical;
98
+ return relativizeLexically(stablePath(target), stablePath(root));
99
+ }
100
+ /**
101
+ * The one form of a target path the families are written in.
102
+ *
103
+ * - separators fold to `/` (a Windows payload spells `src\x.ts`)
104
+ * - a leading `./` is dropped
105
+ * - a `..` segment is resolved
106
+ * - an ABSOLUTE path inside `projectRoot` becomes project-relative
107
+ * - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
108
+ * THIS project's directories, and a path in another repository is another
109
+ * project's business. That is also what the gate already did with every
110
+ * absolute path, so it is not a widening.
111
+ * - with no `projectRoot` an absolute path cannot be made relative and is
112
+ * left as it is
113
+ *
114
+ * A RELATIVE path is read against `toolCwd` — the directory the tool call
115
+ * runs in — and the file it lands in is judged by where it sits inside the
116
+ * project. A path that lands OUTSIDE the project keeps the older reading,
117
+ * the spelling read against the project root, which never widens the gate:
118
+ * it refuses a spelled family the file itself never reached.
119
+ *
120
+ * "Inside" and "outside" are asked LEXICALLY first and CANONICALLY second
121
+ * (see `relativizeInsideRoot`), so two spellings of one directory reach one
122
+ * verdict.
123
+ *
124
+ * This is the LEXICAL reading. The CANONICAL reading — the file named by the
125
+ * directory it really sits in — is a separate question, asked by
126
+ * `canonicalGatePath`.
127
+ */
128
+ export function normalizeGatePath(filePath, projectRoot, toolCwd) {
129
+ if (filePath.length === 0)
130
+ return '';
131
+ const slashed = normalizePath(filePath);
132
+ const root = resolvedDirectory(projectRoot);
133
+ if (root === null) {
134
+ return isAbsolute(slashed)
135
+ ? slashed
136
+ : collapseRelativeDotSegments(stripLeadingDotSegments(slashed));
137
+ }
138
+ if (isAbsolute(slashed)) {
139
+ return relativizeInsideRoot(resolve(slashed), root) ?? slashed;
140
+ }
141
+ // The file the call will really touch: the relative path read against the
142
+ // tool call's own directory, then judged by where it lands in the project.
143
+ const base = resolvedDirectory(toolCwd) ?? root;
144
+ const inside = relativizeInsideRoot(resolve(base, slashed), root);
145
+ if (inside !== null)
146
+ return inside;
147
+ // The file is outside the project: the project reads the spelling instead.
148
+ const spelled = resolve(root, slashed);
149
+ return relativizeInsideRoot(spelled, root) ?? normalizePath(spelled);
150
+ }
151
+ /** The roots, whichever of the two spellings the caller used. */
152
+ export function rootPair(roots) {
153
+ if (roots === null || roots === undefined)
154
+ return { projectRoot: null };
155
+ if (typeof roots === 'string')
156
+ return { projectRoot: roots };
157
+ return roots;
158
+ }
159
+ /**
160
+ * The CANONICAL project-relative form of a target path: the file the call
161
+ * really touches, named by the directory it REALLY sits in.
162
+ *
163
+ * The lexical form says how the path is WRITTEN; this one says where the
164
+ * file IS. The two differ whenever a directory is named two ways — a
165
+ * symlink, a junction, macOS's `/var` → `/private/var` — and the difference
166
+ * is what a symlinked BASE inside the project looks like: the call runs in
167
+ * `link/`, the file is in `src/`, and the lexical form says `link/x.ts`
168
+ * (no family) while this one says `src/x.ts` (a family).
169
+ *
170
+ * The two sides are compared as they are CANONICALLY spelled, so the answer
171
+ * is the directory the file is in and not the spelling the caller used to
172
+ * reach it. The LEXICAL-first-then-canonical retry belongs to the other
173
+ * reading (`relativizeInsideRoot`), which needs it because a lexical answer
174
+ * can be a statement about the SPELLING rather than about the directory.
175
+ *
176
+ * `null` when the file is outside the project: the project has no name for
177
+ * it, and the spelling-anchored reading the caller already holds is the one
178
+ * that applies. `null` also when there is no project root at all, for the
179
+ * same reason — a path cannot be made relative to nothing.
180
+ */
181
+ export function canonicalGatePath(filePath, projectRoot, toolCwd) {
182
+ if (filePath.length === 0)
183
+ return null;
184
+ const slashed = normalizePath(filePath);
185
+ const root = resolvedDirectory(projectRoot);
186
+ if (root === null)
187
+ return null;
188
+ const base = resolvedDirectory(toolCwd) ?? root;
189
+ const target = isAbsolute(slashed) ? resolve(slashed) : resolve(base, slashed);
190
+ return relativizeLexically(stablePath(target), stablePath(root));
191
+ }
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The tool call's own directory, read from a hook payload.
3
+ *
4
+ * A relative target path belongs to the directory the tool call RUNS in: the
5
+ * file a call writes is the one that directory names, not the one the project
6
+ * root would name. The gate needs that directory to say which file a payload
7
+ * really points at, and the payload is where a harness states it.
8
+ *
9
+ * The read is deliberately narrow — one key, at the top level, holding a
10
+ * string. A `cwd` nested inside the tool's own arguments is an ARGUMENT the
11
+ * tool was handed, not the directory the call runs in, so only the top-level
12
+ * key counts.
13
+ *
14
+ * The absence of the key is not an error: the caller then uses the process's
15
+ * own working directory, which is the same directory whenever the harness runs
16
+ * the hook where the tool call runs.
17
+ */
18
+ export declare function readToolCallCwd(payload: Readonly<Record<string, unknown>>): string | null;
19
+ /**
20
+ * The directory a relative target path is read against.
21
+ *
22
+ * The payload's own `cwd` is the base only when it is a USABLE one: an
23
+ * absolute path naming an existing directory inside the project the caller
24
+ * named. A `cwd` that is missing, relative, names a file, names a directory
25
+ * that is not there, or names a directory outside the project is not a
26
+ * directory this project can judge the file against — and a base that is not
27
+ * the call's own directory resolves the path against the wrong tree, which is
28
+ * how an edit into a hard-blocked family slipped through.
29
+ *
30
+ * The rule ASSUMES the tool call runs inside the named project, which is
31
+ * where the gate is installed. When it does not, the payload `cwd` is
32
+ * rejected and the path is read against the gate's own working directory
33
+ * instead — a different tree — and the error is one-directional: a file that
34
+ * lies outside every family can be denied. It is never the other way round,
35
+ * and that is the trade the gate makes everywhere else: a wrongly allowed
36
+ * edit is a hole, a wrongly refused one is an inconvenience.
37
+ *
38
+ * The fallback is the gate process's own working directory: that is where the
39
+ * hook runs, and in the normal invocation it IS the tool call's directory.
40
+ * The gate does not fail closed here — it uses the best base it has, and a
41
+ * file that lands outside the project is judged by its spelling, which never
42
+ * widens the gate.
43
+ */
44
+ export declare function resolveToolCallBaseDir(payload: Readonly<Record<string, unknown>>, projectRoot: string, fallback: string): string;
@@ -0,0 +1,113 @@
1
+ /**
2
+ * The tool call's own directory, read from a hook payload.
3
+ *
4
+ * A relative target path belongs to the directory the tool call RUNS in: the
5
+ * file a call writes is the one that directory names, not the one the project
6
+ * root would name. The gate needs that directory to say which file a payload
7
+ * really points at, and the payload is where a harness states it.
8
+ *
9
+ * The read is deliberately narrow — one key, at the top level, holding a
10
+ * string. A `cwd` nested inside the tool's own arguments is an ARGUMENT the
11
+ * tool was handed, not the directory the call runs in, so only the top-level
12
+ * key counts.
13
+ *
14
+ * The absence of the key is not an error: the caller then uses the process's
15
+ * own working directory, which is the same directory whenever the harness runs
16
+ * the hook where the tool call runs.
17
+ */
18
+ import { statSync } from 'node:fs';
19
+ import { isAbsolute, relative, resolve } from 'node:path';
20
+ import { normalizePath, stablePath } from '../../shared/path-utils.js';
21
+ export function readToolCallCwd(payload) {
22
+ const cwd = payload['cwd'];
23
+ if (typeof cwd !== 'string')
24
+ return null;
25
+ const trimmed = cwd.trim();
26
+ return trimmed.length > 0 ? trimmed : null;
27
+ }
28
+ /**
29
+ * Does `dir` name a directory that exists?
30
+ *
31
+ * A path that is not there, or that names a file, is not a directory a tool
32
+ * call can run in, and the gate cannot resolve a relative path against it.
33
+ * The read fails CLOSED on a path it cannot stat: an unreadable directory is
34
+ * not a usable base.
35
+ */
36
+ function isExistingDirectory(dir) {
37
+ try {
38
+ return statSync(dir, { throwIfNoEntry: false })?.isDirectory() === true;
39
+ }
40
+ catch {
41
+ return false;
42
+ }
43
+ }
44
+ /**
45
+ * Is `dir` the project root itself, or a directory inside it? Compared
46
+ * LEXICALLY: the two are compared as they are written.
47
+ */
48
+ function isInsideLexically(root, dir) {
49
+ const rel = normalizePath(relative(resolve(root), resolve(dir)));
50
+ if (rel.length === 0)
51
+ return true;
52
+ if (rel === '..' || rel.startsWith('../'))
53
+ return false;
54
+ return !isAbsolute(rel);
55
+ }
56
+ /**
57
+ * Is `dir` the project root itself, or a directory inside it?
58
+ *
59
+ * The check is LEXICAL first, like the path arithmetic it feeds: a symlink
60
+ * inside the project that points outside it passes here. A base outside the
61
+ * project resolves the path against a tree the families do not name, so the
62
+ * file it lands in cannot be judged by where it sits in the project — which
63
+ * is the invariant the gate is built on.
64
+ *
65
+ * When the lexical answer says "outside", the question is asked again with the
66
+ * CANONICAL spelling of both sides, because one directory can be named two
67
+ * ways — a symlink, a junction, macOS's `/var` → `/private/var` — and then
68
+ * the lexical answer is a statement about the SPELLING, not about the
69
+ * directory. The retry can only turn "outside" into "inside", so the base it
70
+ * accepts is one that really is inside the project.
71
+ */
72
+ function isInsideProject(root, dir) {
73
+ if (isInsideLexically(root, dir))
74
+ return true;
75
+ return isInsideLexically(stablePath(root), stablePath(dir));
76
+ }
77
+ /**
78
+ * The directory a relative target path is read against.
79
+ *
80
+ * The payload's own `cwd` is the base only when it is a USABLE one: an
81
+ * absolute path naming an existing directory inside the project the caller
82
+ * named. A `cwd` that is missing, relative, names a file, names a directory
83
+ * that is not there, or names a directory outside the project is not a
84
+ * directory this project can judge the file against — and a base that is not
85
+ * the call's own directory resolves the path against the wrong tree, which is
86
+ * how an edit into a hard-blocked family slipped through.
87
+ *
88
+ * The rule ASSUMES the tool call runs inside the named project, which is
89
+ * where the gate is installed. When it does not, the payload `cwd` is
90
+ * rejected and the path is read against the gate's own working directory
91
+ * instead — a different tree — and the error is one-directional: a file that
92
+ * lies outside every family can be denied. It is never the other way round,
93
+ * and that is the trade the gate makes everywhere else: a wrongly allowed
94
+ * edit is a hole, a wrongly refused one is an inconvenience.
95
+ *
96
+ * The fallback is the gate process's own working directory: that is where the
97
+ * hook runs, and in the normal invocation it IS the tool call's directory.
98
+ * The gate does not fail closed here — it uses the best base it has, and a
99
+ * file that lands outside the project is judged by its spelling, which never
100
+ * widens the gate.
101
+ */
102
+ export function resolveToolCallBaseDir(payload, projectRoot, fallback) {
103
+ const cwd = readToolCallCwd(payload);
104
+ if (cwd === null)
105
+ return fallback;
106
+ if (!isAbsolute(cwd))
107
+ return fallback;
108
+ if (!isExistingDirectory(cwd))
109
+ return fallback;
110
+ if (!isInsideProject(projectRoot, cwd))
111
+ return fallback;
112
+ return cwd;
113
+ }
@@ -18,6 +18,9 @@
18
18
  * logic, usable from any non-Node harness. Both share the same
19
19
  * hard-blocked + allow-listed path families.
20
20
  */
21
+ import { normalizeGatePath, type GateRoots } from './gate-path-normalize.js';
22
+ export { normalizeGatePath };
23
+ export type { GateRoots };
21
24
  export type GateToolName = 'Edit' | 'Write' | 'MultiEdit' | string;
22
25
  export type GatePathKey = 'file_path' | 'path' | 'notebook_path';
23
26
  export interface GateInput {
@@ -42,37 +45,6 @@ export type GateVerdict = {
42
45
  };
43
46
  /** Pull the target file path from `input.file_path | input.path | input.notebook_path`. */
44
47
  export declare function extractFilePath(input: Readonly<Record<string, unknown>>): string;
45
- /**
46
- * The ONE spelling-independent form of a target path.
47
- *
48
- * The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
49
- * so how the incoming path happens to be SPELLED must not decide the verdict:
50
- * `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
51
- * file and must get one verdict. Without this, the same edit is denied in one
52
- * spelling and allowed in another — and the allow is the one that happens.
53
- *
54
- * - separators fold to `/` (a Windows payload spells `src\x.ts`)
55
- * - a leading `./` is dropped
56
- * - a `..` segment is resolved
57
- * - an ABSOLUTE path inside `projectRoot` becomes project-relative
58
- * - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
59
- * THIS project's directories, and a path in another repository is another
60
- * project's business. That is also what the gate already did with every
61
- * absolute path, so it is not a widening.
62
- * - with no `projectRoot` an absolute path cannot be made relative and is
63
- * left as it is
64
- *
65
- * The base a `..` is resolved against is the PROJECT ROOT the caller named,
66
- * and that is a fact about the caller rather than a guess: the IDE invokes
67
- * `peaks code-gate --project "<the project directory>"`, and the tool call's
68
- * own working directory is that same project directory. A `..` that resolves
69
- * OUTSIDE the root names a file outside the project, so it belongs to no
70
- * family and is allowed - the same rule an absolute path outside the root
71
- * follows. The trade-off is written down rather than left implicit: a base
72
- * chosen wrongly would refuse files of a neighbouring directory, and the
73
- * project root is the one base both the caller and the tool call agree on.
74
- */
75
- export declare function normalizeGatePath(filePath: string, projectRoot?: string | null): string;
76
48
  /**
77
49
  * Pure decision function. Given the tool name + input object, return
78
50
  * the gate verdict. Tolerates malformed payloads (allow).
@@ -83,12 +55,40 @@ export declare function normalizeGatePath(filePath: string, projectRoot?: string
83
55
  * hard-blocked families deny. Resolution is the caller's job, so this
84
56
  * module keeps no session, lease or filesystem state.
85
57
  *
86
- * `projectRoot` is the root the deny families are relative to. It is what
87
- * lets an ABSOLUTE path be judged like its relative spelling; without it an
88
- * absolute path cannot be related to the project and is left alone. It is the
89
- * project root the CALLER named, not the canonical root above it: a project
90
- * nested inside a git repository is judged against itself, and the canonical
91
- * root - where the session and the leases live - is a different question
92
- * that this parameter does not answer.
58
+ * `roots` is where the verdict is taken: the root the deny families are
59
+ * relative to, and the directory the tool call runs in. A bare string is the
60
+ * project root alone, which is how every earlier call spelled it.
61
+ *
62
+ * The project root is what lets an ABSOLUTE path be judged like its relative
63
+ * spelling; without it an absolute path cannot be related to the project and
64
+ * is left alone. It is the project root the CALLER named, not the canonical
65
+ * root above it: a project nested inside a git repository is judged against
66
+ * itself, and the canonical root - where the session and the leases live - is
67
+ * a different question that this parameter does not answer.
68
+ *
69
+ * The tool call's directory is the base a RELATIVE path is read against: the
70
+ * file a call writes is the one that directory names. It does not move the
71
+ * families - those stay relative to the project root - it only says which
72
+ * file the payload points at.
73
+ *
74
+ * THE VERDICT IS THE STRICTEST OF THE TWO READINGS. The path is read
75
+ * LEXICALLY - how it is written - and, when that reading has not already
76
+ * denied the file, CANONICALLY - where the file really is. A directory can
77
+ * be named two ways, and the difference is what a symlinked base looks like:
78
+ * a call that runs in `link/` and writes `deep/x.ts` lands in `src/deep/x.ts`
79
+ * when `link` points at `src`, and the lexical reading says `link/deep/x.ts`
80
+ * - no family at all. §18.1 rules that the verdict depends on WHICH
81
+ * DIRECTORY the file is in, not on how the path is written.
82
+ *
83
+ * Strictest, and not "canonical wins": making the canonical reading
84
+ * authoritative would WIDEN the gate in a layout this repository supports.
85
+ * When `src` is a symlink to `shared/src`, the lexical reading is
86
+ * `src/x.ts` (a family) and the canonical one is `shared/src/x.ts` (not
87
+ * one), and the file the gate denies today must stay denied. The tie-breaker
88
+ * is the repository's own: a wrongly ALLOWED edit is a hole, a wrongly
89
+ * REFUSED one is only an inconvenience. So a file reached through a
90
+ * directory NAMED `src` stays refused even when it really sits in `docs/` -
91
+ * the spelling is what the path says in this project's terms, and the gate
92
+ * refuses it rather than resolve it.
93
93
  */
94
- export declare function decideGateAction(tool: GateToolName, input: Readonly<Record<string, unknown>>, driver?: string | null, projectRoot?: string | null): GateVerdict;
94
+ export declare function decideGateAction(tool: GateToolName, input: Readonly<Record<string, unknown>>, driver?: string | null, roots?: GateRoots): GateVerdict;
@@ -18,8 +18,8 @@
18
18
  * logic, usable from any non-Node harness. Both share the same
19
19
  * hard-blocked + allow-listed path families.
20
20
  */
21
- import { isAbsolute, relative, resolve } from 'node:path';
22
- import { normalizePath } from '../../shared/path-utils.js';
21
+ import { canonicalGatePath, normalizeGatePath, rootPair } from './gate-path-normalize.js';
22
+ export { normalizeGatePath };
23
23
  /** Hard-blocked path families — orchestrator MUST NOT Edit/Write these. */
24
24
  export const HARD_BLOCKED_PATH_FAMILIES = [
25
25
  'src/',
@@ -91,98 +91,39 @@ function matchesAny(path, families) {
91
91
  }
92
92
  return null;
93
93
  }
94
- /** Drop every leading `./` segment: `./src/x.ts` and `src/x.ts` are one path. */
95
- function stripLeadingDotSegments(path) {
96
- let out = path;
97
- while (out.startsWith('./'))
98
- out = out.slice(2);
99
- return out;
100
- }
101
94
  /**
102
- * Collapse the `.` and `..` segments of a RELATIVE path, lexically.
95
+ * The hard-blocked family a reading of the path names, or `null` when it
96
+ * names none.
103
97
  *
104
- * The base directory does not enter the answer for a path that stays inside
105
- * it: a `..` cancels the segment before it, for every base. A `..` that would
106
- * leave the base is KEPT, so the result still reads as "outside", and a path
107
- * outside the project belongs to no family.
108
- */
109
- function collapseRelativeDotSegments(path) {
110
- const out = [];
111
- for (const segment of path.split('/')) {
112
- if (segment === '' || segment === '.')
113
- continue;
114
- if (segment === '..') {
115
- const last = out.length > 0 ? out[out.length - 1] : null;
116
- if (last !== null && last !== '..')
117
- out.pop();
118
- else
119
- out.push('..');
120
- continue;
121
- }
122
- out.push(segment);
123
- }
124
- return out.join('/');
125
- }
126
- /**
127
- * The path of `target` relative to `root`, when `target` is INSIDE `root`;
128
- * `null` when it is not — the target is outside the root, or it is the root.
98
+ * The ALLOW-LIST is read FIRST, for each reading on its own: a path the
99
+ * project allows is allowed, and a reading that names an allow-listed
100
+ * directory does not become a deny because ANOTHER reading names a family.
101
+ * That is what keeps `src/x.md` allowed, exactly as it was before.
102
+ *
103
+ * The family comparison folds CASE, because every family name is written in
104
+ * lower case and the filesystem holding the file may not be.
129
105
  */
130
- function relativizeInsideRoot(target, root) {
131
- const relativePath = normalizePath(relative(root, target));
132
- if (relativePath.length === 0)
106
+ function hardBlockedFamilyOf(reading) {
107
+ if (matchesAny(reading, ALLOW_LISTED_PATH_PATTERNS) !== null)
133
108
  return null;
134
- if (relativePath.startsWith('..') || isAbsolute(relativePath))
135
- return null;
136
- return stripLeadingDotSegments(relativePath);
109
+ return matchesAny(reading, HARD_BLOCKED_PATH_FAMILIES);
137
110
  }
138
111
  /**
139
- * The ONE spelling-independent form of a target path.
140
- *
141
- * The deny families are project-relative prefixes (`src/`, `tests/unit/`, …),
142
- * so how the incoming path happens to be SPELLED must not decide the verdict:
143
- * `src/x.ts`, `./src/x.ts` and the absolute spelling of that same file are one
144
- * file and must get one verdict. Without this, the same edit is denied in one
145
- * spelling and allowed in another — and the allow is the one that happens.
112
+ * The verdict for a file that one reading of the path placed in a
113
+ * hard-blocked family.
146
114
  *
147
- * - separators fold to `/` (a Windows payload spells `src\x.ts`)
148
- * - a leading `./` is dropped
149
- * - a `..` segment is resolved
150
- * - an ABSOLUTE path inside `projectRoot` becomes project-relative
151
- * - an absolute path OUTSIDE `projectRoot` stays absolute: the families name
152
- * THIS project's directories, and a path in another repository is another
153
- * project's business. That is also what the gate already did with every
154
- * absolute path, so it is not a widening.
155
- * - with no `projectRoot` an absolute path cannot be made relative and is
156
- * left as it is
157
- *
158
- * The base a `..` is resolved against is the PROJECT ROOT the caller named,
159
- * and that is a fact about the caller rather than a guess: the IDE invokes
160
- * `peaks code-gate --project "<the project directory>"`, and the tool call's
161
- * own working directory is that same project directory. A `..` that resolves
162
- * OUTSIDE the root names a file outside the project, so it belongs to no
163
- * family and is allowed - the same rule an absolute path outside the root
164
- * follows. The trade-off is written down rather than left implicit: a base
165
- * chosen wrongly would refuse files of a neighbouring directory, and the
166
- * project root is the one base both the caller and the tool call agree on.
115
+ * A driver that is not the fast lane falls through to the same deny a
116
+ * two-argument call produces, so an unresolvable identity can never become a
117
+ * silent pass.
167
118
  */
168
- export function normalizeGatePath(filePath, projectRoot) {
169
- if (filePath.length === 0)
170
- return '';
171
- const slashed = normalizePath(filePath);
172
- const root = typeof projectRoot === 'string' && projectRoot.length > 0 ? resolve(projectRoot) : null;
173
- if (isAbsolute(slashed)) {
174
- if (root === null)
175
- return slashed;
176
- return relativizeInsideRoot(resolve(slashed), root) ?? slashed;
119
+ function denyVerdict(family, requestedPath, driver) {
120
+ if (driver === FAST_LANE_DRIVER) {
121
+ return { action: 'allow' };
177
122
  }
178
- if (root === null)
179
- return collapseRelativeDotSegments(stripLeadingDotSegments(slashed));
180
- const resolved = resolve(root, slashed);
181
- const inside = relativizeInsideRoot(resolved, root);
182
- if (inside !== null)
183
- return inside;
184
- // The `..` left the project root: the target is another project's file.
185
- return normalizePath(resolved);
123
+ const reason = `${family} (orchestrator's hard-blocked path family)`;
124
+ const message = `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: ${requestedPath} matches hard-blocked path family ${reason}; ` +
125
+ `orchestrator MUST NOT Edit/Write these directly. Use: peaks sub-agent dispatch rd --prompt '<your task>' --request-id <rid> --project . --batch-id <uuid>`;
126
+ return { action: 'deny', filePath: requestedPath, reason, message };
186
127
  }
187
128
  /**
188
129
  * Pure decision function. Given the tool name + input object, return
@@ -194,15 +135,43 @@ export function normalizeGatePath(filePath, projectRoot) {
194
135
  * hard-blocked families deny. Resolution is the caller's job, so this
195
136
  * module keeps no session, lease or filesystem state.
196
137
  *
197
- * `projectRoot` is the root the deny families are relative to. It is what
198
- * lets an ABSOLUTE path be judged like its relative spelling; without it an
199
- * absolute path cannot be related to the project and is left alone. It is the
200
- * project root the CALLER named, not the canonical root above it: a project
201
- * nested inside a git repository is judged against itself, and the canonical
202
- * root - where the session and the leases live - is a different question
203
- * that this parameter does not answer.
138
+ * `roots` is where the verdict is taken: the root the deny families are
139
+ * relative to, and the directory the tool call runs in. A bare string is the
140
+ * project root alone, which is how every earlier call spelled it.
141
+ *
142
+ * The project root is what lets an ABSOLUTE path be judged like its relative
143
+ * spelling; without it an absolute path cannot be related to the project and
144
+ * is left alone. It is the project root the CALLER named, not the canonical
145
+ * root above it: a project nested inside a git repository is judged against
146
+ * itself, and the canonical root - where the session and the leases live - is
147
+ * a different question that this parameter does not answer.
148
+ *
149
+ * The tool call's directory is the base a RELATIVE path is read against: the
150
+ * file a call writes is the one that directory names. It does not move the
151
+ * families - those stay relative to the project root - it only says which
152
+ * file the payload points at.
153
+ *
154
+ * THE VERDICT IS THE STRICTEST OF THE TWO READINGS. The path is read
155
+ * LEXICALLY - how it is written - and, when that reading has not already
156
+ * denied the file, CANONICALLY - where the file really is. A directory can
157
+ * be named two ways, and the difference is what a symlinked base looks like:
158
+ * a call that runs in `link/` and writes `deep/x.ts` lands in `src/deep/x.ts`
159
+ * when `link` points at `src`, and the lexical reading says `link/deep/x.ts`
160
+ * - no family at all. §18.1 rules that the verdict depends on WHICH
161
+ * DIRECTORY the file is in, not on how the path is written.
162
+ *
163
+ * Strictest, and not "canonical wins": making the canonical reading
164
+ * authoritative would WIDEN the gate in a layout this repository supports.
165
+ * When `src` is a symlink to `shared/src`, the lexical reading is
166
+ * `src/x.ts` (a family) and the canonical one is `shared/src/x.ts` (not
167
+ * one), and the file the gate denies today must stay denied. The tie-breaker
168
+ * is the repository's own: a wrongly ALLOWED edit is a hole, a wrongly
169
+ * REFUSED one is only an inconvenience. So a file reached through a
170
+ * directory NAMED `src` stays refused even when it really sits in `docs/` -
171
+ * the spelling is what the path says in this project's terms, and the gate
172
+ * refuses it rather than resolve it.
204
173
  */
205
- export function decideGateAction(tool, input, driver, projectRoot) {
174
+ export function decideGateAction(tool, input, driver, roots) {
206
175
  // Only gate Edit / Write / MultiEdit.
207
176
  if (!isGatedTool(tool)) {
208
177
  return { action: 'allow' };
@@ -218,26 +187,23 @@ export function decideGateAction(tool, input, driver, projectRoot) {
218
187
  // names it, so the path is reduced to the project-relative form the
219
188
  // families are written in before anything is matched. The verdict still
220
189
  // echoes the path the tool actually asked for.
221
- const filePath = normalizeGatePath(requestedPath, projectRoot);
222
- // Allow-list check first — short-circuits any deny, for every driver.
223
- const allowMatch = matchesAny(filePath, ALLOW_LISTED_PATH_PATTERNS);
224
- if (allowMatch !== null) {
225
- return { action: 'allow' };
226
- }
227
- // Hard-blocked family check — case-insensitively, because every family name
228
- // is lower-case and the filesystem holding the file may not be.
229
- const denyMatch = matchesAny(filePath, HARD_BLOCKED_PATH_FAMILIES);
190
+ const pair = rootPair(roots);
191
+ const filePath = normalizeGatePath(requestedPath, pair.projectRoot, pair.toolCwd);
192
+ // The LEXICAL reading: the allow-list first — it short-circuits any deny,
193
+ // for every driver — and then the hard-blocked families.
194
+ const denyMatch = hardBlockedFamilyOf(filePath);
230
195
  if (denyMatch !== null) {
231
- // A driver that is not the fast lane falls through to the same deny a
232
- // two-argument call produces, so an unresolvable identity can never
233
- // become a silent pass.
234
- if (driver === FAST_LANE_DRIVER) {
235
- return { action: 'allow' };
196
+ return denyVerdict(denyMatch, requestedPath, driver ?? null);
197
+ }
198
+ // The CANONICAL reading, asked only when the lexical one has not already
199
+ // denied the file: it costs two filesystem lookups, and the file it names
200
+ // is the one the lexical reading could not place.
201
+ const canonical = canonicalGatePath(requestedPath, pair.projectRoot, pair.toolCwd);
202
+ if (canonical !== null) {
203
+ const canonicalMatch = hardBlockedFamilyOf(canonical);
204
+ if (canonicalMatch !== null) {
205
+ return denyVerdict(canonicalMatch, requestedPath, driver ?? null);
236
206
  }
237
- const reason = `${denyMatch} (orchestrator's hard-blocked path family)`;
238
- const message = `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: ${requestedPath} matches hard-blocked path family ${reason}; ` +
239
- `orchestrator MUST NOT Edit/Write these directly. Use: peaks sub-agent dispatch rd --prompt '<your task>' --request-id <rid> --project . --batch-id <uuid>`;
240
- return { action: 'deny', filePath: requestedPath, reason, message };
241
207
  }
242
208
  // Anything not in the deny list → allow (e.g. CHANGELOG, README, top-level files).
243
209
  return { action: 'allow' };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.15",
3
+ "version": "4.1.17",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -129,10 +129,10 @@
129
129
  "picomatch": "4.0.7",
130
130
  "yaml": "^2.9.1",
131
131
  "zod": "^4.6.7",
132
- "peaks-loop-mut": "0.1.69",
133
- "peaks-loop-shared": "0.0.104",
134
- "peaks-loop-internal-runtime": "0.0.55",
135
- "peaks-loop-shared-channel": "0.0.72"
132
+ "peaks-loop-internal-runtime": "0.0.57",
133
+ "peaks-loop-shared": "0.0.106",
134
+ "peaks-loop-shared-channel": "0.0.74",
135
+ "peaks-loop-mut": "0.1.71"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",