@holmes-lab/holmes-kit 0.35.25 → 0.36.0

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.
Files changed (125) hide show
  1. package/CHANGELOG.md +298 -0
  2. package/README.md +3 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +31 -1
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +25 -1
  13. package/dist/holmes/cli/doctor.js +153 -7
  14. package/dist/holmes/cli/index.js +99 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  27. package/dist/holmes/cli/runtime-binding.js +96 -7
  28. package/dist/holmes/cli/test-platform.d.ts +16 -0
  29. package/dist/holmes/cli/test-platform.js +31 -1
  30. package/dist/holmes/config/config.d.ts +49 -0
  31. package/dist/holmes/config/config.js +146 -3
  32. package/dist/holmes/config/project-caps.d.ts +21 -0
  33. package/dist/holmes/config/project-caps.js +114 -0
  34. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  35. package/dist/holmes/governance/approval-queue.js +48 -6
  36. package/dist/holmes/governance/autonomy.d.ts +6 -0
  37. package/dist/holmes/governance/autonomy.js +21 -0
  38. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  39. package/dist/holmes/governance/push-gate-runner.js +49 -1
  40. package/dist/holmes/governance/replica-id.d.ts +9 -0
  41. package/dist/holmes/governance/replica-id.js +44 -7
  42. package/dist/holmes/governance/role-policy.d.ts +41 -1
  43. package/dist/holmes/governance/role-policy.js +137 -20
  44. package/dist/holmes/governance/run-mode.d.ts +14 -0
  45. package/dist/holmes/governance/run-mode.js +120 -0
  46. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  47. package/dist/holmes/governance/tool-actions.js +121 -0
  48. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  49. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  50. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  51. package/dist/holmes/guardrail/classification-mode.js +135 -0
  52. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  53. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  54. package/dist/holmes/guardrail/phase.d.ts +2 -1
  55. package/dist/holmes/guardrail/phase.js +22 -8
  56. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  57. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  58. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  59. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  60. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  61. package/dist/holmes/guardrail/risk-classifier.js +242 -26
  62. package/dist/holmes/guardrail/risk-types.d.ts +15 -0
  63. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  64. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  65. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  66. package/dist/holmes/guardrail/run-refusals.js +348 -0
  67. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  68. package/dist/holmes/guardrail/run-stages.js +188 -0
  69. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  70. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  71. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  72. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  73. package/dist/holmes/guardrail/shell-words.js +7 -7
  74. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  75. package/dist/holmes/guardrail/write-target.js +118 -16
  76. package/dist/holmes/hooks/pre-tool-use.d.ts +35 -1
  77. package/dist/holmes/hooks/pre-tool-use.js +702 -81
  78. package/dist/holmes/hooks/session-start.js +5 -3
  79. package/dist/holmes/hooks/stop.d.ts +32 -0
  80. package/dist/holmes/hooks/stop.js +129 -4
  81. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  82. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  83. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  84. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  85. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  86. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  87. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  88. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  89. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  90. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  91. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  92. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  93. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  94. package/dist/holmes/mcp/handlers.d.ts +2 -3
  95. package/dist/holmes/mcp/handlers.js +22 -2
  96. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  97. package/dist/holmes/mcp/harness-attestation.js +3 -1
  98. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  99. package/dist/holmes/mcp/operator-recovery.js +4 -3
  100. package/dist/holmes/mcp/server.js +9 -0
  101. package/dist/holmes/mcp/tool-schemas.js +6 -3
  102. package/dist/holmes/project/root.js +6 -1
  103. package/dist/holmes/project/run-records.d.ts +17 -0
  104. package/dist/holmes/project/run-records.js +126 -0
  105. package/dist/holmes/review/mrp.d.ts +35 -0
  106. package/dist/holmes/review/mrp.js +119 -0
  107. package/dist/holmes/review/verdicts.d.ts +117 -0
  108. package/dist/holmes/review/verdicts.js +345 -0
  109. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  110. package/dist/holmes/semantic/cloud-usage.js +106 -0
  111. package/dist/holmes/semantic/embedder.d.ts +15 -6
  112. package/dist/holmes/semantic/embedder.js +84 -3
  113. package/dist/holmes/semantic/local-model.d.ts +21 -2
  114. package/dist/holmes/semantic/local-model.js +14 -3
  115. package/dist/holmes/semantic/tier.d.ts +25 -0
  116. package/dist/holmes/semantic/tier.js +86 -1
  117. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  118. package/dist/holmes/semantic/vector-cache.js +4 -1
  119. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  120. package/dist/holmes/spec/approval-blockers.js +70 -2
  121. package/dist/holmes/spec/renumber.d.ts +1 -1
  122. package/dist/holmes/spec/renumber.js +5 -2
  123. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  124. package/dist/holmes/spec/transition-policy.js +17 -2
  125. package/package.json +1 -1
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.AX_CLIMB_BASES_MAX = exports.WIRING_FILE_NAMES = exports.WIRING_DIR_NAMES = exports.GOVERNANCE_STORE_LABEL = exports.AX_PROTECTED_CHILDREN = exports.PATCH_TARGETS_MAX = exports.PATH_FIELDS = exports.READ_ONLY_TOOLS = void 0;
36
+ exports.AX_CLIMB_BASES_MAX = exports.WIRING_FILE_NAMES = exports.PROJECT_CAPS_LABEL = exports.WIRING_DIR_NAMES = exports.GOVERNANCE_STORE_LABEL = exports.AX_PROTECTED_CHILDREN = exports.PATCH_TARGETS_MAX = exports.PATH_FIELDS = exports.READ_ONLY_TOOLS = void 0;
37
37
  exports.absoluteKindOf = absoluteKindOf;
38
38
  exports.foldsCaseBySyntax = foldsCaseBySyntax;
39
39
  exports.writesFiles = writesFiles;
@@ -46,11 +46,15 @@ exports.patchTargetsOf = patchTargetsOf;
46
46
  exports.applyPatchUpdate = applyPatchUpdate;
47
47
  exports.applyPatchUpdateDetailed = applyPatchUpdateDetailed;
48
48
  exports.pathFlavorFor = pathFlavorFor;
49
+ exports.hostFlavor = hostFlavor;
49
50
  exports.resolveTarget = resolveTarget;
50
51
  exports.isProtectedTarget = isProtectedTarget;
51
52
  exports.specTargetOf = specTargetOf;
53
+ exports.isProjectConfigTarget = isProjectConfigTarget;
52
54
  exports.protectedFileKindOf = protectedFileKindOf;
53
55
  exports.expandHomeSpelling = expandHomeSpelling;
56
+ exports.wiringFileNames = wiringFileNames;
57
+ exports.withoutProjectCaps = withoutProjectCaps;
54
58
  exports.withIdentCache = withIdentCache;
55
59
  exports.userHarnessConfigKindOf = userHarnessConfigKindOf;
56
60
  exports.globPatternRe = globPatternRe;
@@ -68,7 +72,8 @@ exports.joinShellText = joinShellText;
68
72
  exports.commandBases = commandBases;
69
73
  exports.shellSegments = shellSegments;
70
74
  exports.resolvesInside = resolvesInside;
71
- // @implements A-SPEC-728, A-SPEC-733, A-SPEC-163, A-SPEC-627, A-SPEC-768.2, A-SPEC-768.3
75
+ exports.foreignMcpPaths = foreignMcpPaths;
76
+ // @implements A-SPEC-728, A-SPEC-733, A-SPEC-163, A-SPEC-627, A-SPEC-768.2, A-SPEC-768.3, A-SPEC-163.8, A-SPEC-476.3, A-SPEC-476.7
72
77
  const fs = __importStar(require("node:fs"));
73
78
  const path = __importStar(require("node:path"));
74
79
  const os = __importStar(require("node:os"));
@@ -233,14 +238,21 @@ function patchLoose(line) {
233
238
  .replace(PATCH_DASHES, '-').replace(PATCH_SINGLE_QUOTES, "'").replace(PATCH_DOUBLE_QUOTES, '"').replace(PATCH_SPACE_FOLD, ' ');
234
239
  }
235
240
  /** A character a header path may not hold: quotes, expansion and glob characters, a backslash, controls, any white space but a plain space. */
236
- const PATCH_PATH_FORBIDDEN = new RegExp('["' + "'" + '`$*?' + String.fromCharCode(0x5c, 0x5c) + codeClass(PATCH_INVISIBLE) + codeClass(PATCH_SPACES)
237
- + codeClass([0x0009, 0x2028, 0x2029]) + ']');
241
+ const patchPathForbidden = (backslash) => new RegExp('["' + "'" + '`$*?' + (backslash ? String.fromCharCode(0x5c, 0x5c) : '')
242
+ + codeClass(PATCH_INVISIBLE) + codeClass(PATCH_SPACES) + codeClass([0x0009, 0x2028, 0x2029]) + ']');
243
+ const PATCH_PATH_FORBIDDEN = patchPathForbidden(true);
244
+ // @implements A-SPEC-163.8 — where a backslash is the separator (a win32 host) only it leaves the set: on POSIX it is a
245
+ // legal file-name character and a shell escape, so reading it as a separator would judge another file than the one
246
+ // written. Every other character stays forbidden on both hosts.
247
+ const PATCH_PATH_FORBIDDEN_WIN32 = patchPathForbidden(false);
238
248
  const PATCH_END = '*** End Patch';
239
249
  const PATCH_FILE_HEADERS = [
240
250
  ['*** Add File: ', 'add'], ['*** Update File: ', 'update'], ['*** Delete File: ', 'delete'],
241
251
  ];
242
252
  const PATCH_MOVE = '*** Move to: ';
243
- const canonicalPath = (p) => p !== '' && !p.startsWith(' ') && !p.endsWith(' ') && !PATCH_PATH_FORBIDDEN.test(p);
253
+ // The host's separator decides, not object identity (resolveTarget records why identity misleads).
254
+ const canonicalPath = (p, host) => p !== '' && !p.startsWith(' ') && !p.endsWith(' ')
255
+ && !(host.sep === '\\' ? PATCH_PATH_FORBIDDEN_WIN32 : PATCH_PATH_FORBIDDEN).test(p);
244
256
  /**
245
257
  * Whether a text is the one patch form the gate judges.
246
258
  *
@@ -251,7 +263,8 @@ const canonicalPath = (p) => p !== '' && !p.startsWith(' ') && !p.endsWith(' ')
251
263
  * header behind anything — makes the text not canonical, and the caller refuses it. A line-by-line prefix walk: no
252
264
  * pattern over the whole text, nothing to back-track on.
253
265
  */
254
- function canonicalPatch(text) {
266
+ function canonicalPatch(text, opts = {}) {
267
+ const host = opts.host ?? hostFlavor(); // @implements A-SPEC-163.8
255
268
  const lines = text.split('\n').map(unCR);
256
269
  let start = 0;
257
270
  let end = lines.length;
@@ -282,14 +295,14 @@ function canonicalPatch(text) {
282
295
  continue;
283
296
  }
284
297
  if (line.startsWith(PATCH_MOVE)) {
285
- if (block !== 'update' || sinceHeader !== 0 || moved || !canonicalPath(line.slice(PATCH_MOVE.length)))
298
+ if (block !== 'update' || sinceHeader !== 0 || moved || !canonicalPath(line.slice(PATCH_MOVE.length), host))
286
299
  return false;
287
300
  moved = true;
288
301
  sinceHeader++;
289
302
  continue;
290
303
  }
291
304
  const header = PATCH_FILE_HEADERS.find(([prefix]) => line.startsWith(prefix));
292
- if (header === undefined || !canonicalPath(line.slice(header[0].length)) || !closes())
305
+ if (header === undefined || !canonicalPath(line.slice(header[0].length), host) || !closes())
293
306
  return false;
294
307
  block = header[1];
295
308
  content = 0;
@@ -325,7 +338,8 @@ function canonicalPatch(text) {
325
338
  * block that closes with zero content lines is counted instead of refused, and an add block that adds nothing stays a
326
339
  * grammar fault (an add must add). This function changes no gate decision — only the reason text a caller prints.
327
340
  */
328
- function canonicalPatchReason(text) {
341
+ function canonicalPatchReason(text, opts = {}) {
342
+ const host = opts.host ?? hostFlavor(); // @implements A-SPEC-163.8
329
343
  const lines = text.split('\n').map(unCR);
330
344
  let start = 0;
331
345
  let end = lines.length;
@@ -361,14 +375,14 @@ function canonicalPatchReason(text) {
361
375
  continue;
362
376
  }
363
377
  if (line.startsWith(PATCH_MOVE)) {
364
- if (block !== 'update' || sinceHeader !== 0 || moved || !canonicalPath(line.slice(PATCH_MOVE.length)))
378
+ if (block !== 'update' || sinceHeader !== 0 || moved || !canonicalPath(line.slice(PATCH_MOVE.length), host))
365
379
  return 'grammar';
366
380
  moved = true;
367
381
  sinceHeader++;
368
382
  continue;
369
383
  }
370
384
  const header = PATCH_FILE_HEADERS.find(([prefix]) => line.startsWith(prefix));
371
- if (header === undefined || !canonicalPath(line.slice(header[0].length)) || !closes())
385
+ if (header === undefined || !canonicalPath(line.slice(header[0].length), host) || !closes())
372
386
  return 'grammar';
373
387
  block = header[1];
374
388
  content = 0;
@@ -588,6 +602,17 @@ function pathFlavorFor(root, raw) {
588
602
  const kind = absoluteKindOf(raw) ?? absoluteKindOf(root);
589
603
  return kind === 'drive' || kind === 'unc' ? path.win32 : path.posix;
590
604
  }
605
+ /**
606
+ * The path grammar of the host this process runs on — the one place this module asks.
607
+ *
608
+ * @implements A-SPEC-163.8
609
+ * Read off `path.sep` at call time: not `process.platform`, and not module identity (see `resolveTarget`). Every caller
610
+ * takes it as a default it lets a test override, so a POSIX run asserts the win32 answers and a Windows run the POSIX
611
+ * ones. `pathFlavorFor` answers a different question — which grammar a STRING is written in.
612
+ */
613
+ function hostFlavor() {
614
+ return path.sep === '\\' ? path.win32 : path.posix;
615
+ }
591
616
  /** Compare paths in one spelling — win32 hands back backslashes that must not defeat a prefix test. */
592
617
  const foldSep = (p) => p.replace(/\\/g, '/');
593
618
  function resolveTarget(root, raw, depth = 0, opts = {}) {
@@ -605,7 +630,7 @@ function resolveTarget(root, raw, depth = 0, opts = {}) {
605
630
  // never `===` path.posix, which silently turned every posix resolution string-only and broke the
606
631
  // symlink rule, caught by the A-SPEC-163 corner test). Injectable so the cross-flavor case is
607
632
  // testable from either host.
608
- const host = opts.host ?? (path.sep === '\\' ? path.win32 : path.posix);
633
+ const host = opts.host ?? hostFlavor();
609
634
  if (pp !== host)
610
635
  return abs;
611
636
  const fsi = opts.fs ?? fs;
@@ -737,6 +762,10 @@ function specTargetOf(root, specsDir, raw) {
737
762
  * resolution is `resolveTarget`'s — it follows links, including dangling ones, because a write
738
763
  * through a dangling link creates exactly the file it names.
739
764
  */
765
+ /** @implements A-SPEC-476.3 — whether a write lands on `<root>/ax.config.json`, by identity (links followed, case folded). */
766
+ function isProjectConfigTarget(root, raw) {
767
+ return foldSep(resolveTarget(root, raw)).toLowerCase() === foldSep(resolveTarget(root, exports.PROJECT_CAPS_LABEL)).toLowerCase();
768
+ }
740
769
  function protectedFileKindOf(root, raw) {
741
770
  // @implements A-SPEC-220.2
742
771
  const pp = pathFlavorFor(root, raw);
@@ -807,7 +836,28 @@ exports.GOVERNANCE_STORE_LABEL = '.ax (the spec store and ledger)';
807
836
  /** Every directory name that is judged as a whole: the session wiring directories and `.ax`. */
808
837
  exports.WIRING_DIR_NAMES = ['.claude', '.agents', '.codex', '.ax'];
809
838
  /** Every file name a wiring target can carry — `xargs`/`find` judge by name when paths are unknowable. */
810
- exports.WIRING_FILE_NAMES = ['settings.json', 'settings.local.json', '.mcp.json', 'hooks.json', 'mcp_config.json', 'config.toml'];
839
+ // @implements A-SPEC-476.3 — ax.config.json carries the owner's caps; the hook decides by the caps on disk (PROJECT_CAPS_LABEL).
840
+ exports.PROJECT_CAPS_LABEL = 'ax.config.json';
841
+ exports.WIRING_FILE_NAMES = ['settings.json', 'settings.local.json', '.mcp.json', 'hooks.json', 'mcp_config.json', 'config.toml', exports.PROJECT_CAPS_LABEL];
842
+ /**
843
+ * @implements A-SPEC-476.7 — the wiring scan returns its first act; once the cap branch has allowed an ax.config.json act,
844
+ * the hook scans again with the caps file out of the wiring set so an act after it is judged (`printf '{}' >
845
+ * ax.config.json; unlink .claude/settings.local.json` was allowed — independent review, 2026-10-19).
846
+ */
847
+ let capsOutOfScope = false;
848
+ function wiringFileNames() {
849
+ return capsOutOfScope ? exports.WIRING_FILE_NAMES.filter((n) => n !== exports.PROJECT_CAPS_LABEL) : exports.WIRING_FILE_NAMES;
850
+ }
851
+ function withoutProjectCaps(fn) {
852
+ const prev = capsOutOfScope;
853
+ capsOutOfScope = true;
854
+ try {
855
+ return fn();
856
+ }
857
+ finally {
858
+ capsOutOfScope = prev;
859
+ }
860
+ }
811
861
  /** Every directory holding a harness file that loads or configures this session's gate. */
812
862
  function wiringDirs(root, env, home) {
813
863
  const out = [
@@ -815,7 +865,7 @@ function wiringDirs(root, env, home) {
815
865
  ...codexHomes(env, home).map((dir) => ({ dir, name: /^(?:config\.toml|hooks\.json)$/i, known: ['config.toml', 'hooks.json'], label: (n) => `Codex user ${n}`, dirIsWiring: true })),
816
866
  ];
817
867
  if (root !== null) {
818
- out.push({ dir: path.join(root, '.claude'), name: SETTINGS_NAME, known: ['settings.json', 'settings.local.json'], label: (n) => `.claude/${n}`, dirIsWiring: true }, { dir: root, name: /^\.mcp\.json$/i, known: ['.mcp.json'], label: () => '.mcp.json', dirIsWiring: false }, { dir: path.join(root, '.agents'), name: /^(?:hooks|mcp_config)\.json$/i, known: ['hooks.json', 'mcp_config.json'], label: (n) => `.agents/${n}`, dirIsWiring: true }, { dir: path.join(root, '.codex'), name: /^(?:config\.toml|mcp_config\.json)$/i, known: ['config.toml', 'mcp_config.json'], label: (n) => `.codex/${n}`, dirIsWiring: true },
868
+ out.push({ dir: path.join(root, '.claude'), name: SETTINGS_NAME, known: ['settings.json', 'settings.local.json'], label: (n) => `.claude/${n}`, dirIsWiring: true }, { dir: root, name: /^\.mcp\.json$/i, known: ['.mcp.json'], label: () => '.mcp.json', dirIsWiring: false }, ...(capsOutOfScope ? [] : [{ dir: root, name: /^ax\.config\.json$/i, known: [exports.PROJECT_CAPS_LABEL], label: () => exports.PROJECT_CAPS_LABEL, dirIsWiring: false }]), { dir: path.join(root, '.agents'), name: /^(?:hooks|mcp_config)\.json$/i, known: ['hooks.json', 'mcp_config.json'], label: (n) => `.agents/${n}`, dirIsWiring: true }, { dir: path.join(root, '.codex'), name: /^(?:config\.toml|mcp_config\.json)$/i, known: ['config.toml', 'mcp_config.json'], label: (n) => `.codex/${n}`, dirIsWiring: true },
819
869
  // @implements A-SPEC-728 (round 9) — `.ax` ITSELF: moving it away turned No-Spec-No-Code off in one
820
870
  // call (measured: the next code Write was allowed), and a bulk copy into it replaces the specs and
821
871
  // ledger. Files inside keep their own rules; only the directory as a whole is judged here.
@@ -1183,7 +1233,7 @@ function wiringDeletionKindOf(root, base, arg, env = process.env, home = os.home
1183
1233
  return null;
1184
1234
  if (s.length > MAX_PATH_CHARS) {
1185
1235
  const n = lastName(s);
1186
- return exports.WIRING_FILE_NAMES.includes(n) || (recursive && exports.WIRING_DIR_NAMES.includes(n)) ? `${n} (a path too long to resolve)` : null;
1236
+ return wiringFileNames().includes(n) || (recursive && exports.WIRING_DIR_NAMES.includes(n)) ? `${n} (a path too long to resolve)` : null;
1187
1237
  }
1188
1238
  if (base === null && absoluteKindOf(s) === null)
1189
1239
  return null;
@@ -1423,7 +1473,7 @@ function wiringWriteKindOf(root, base, arg, env = process.env, home = os.homedir
1423
1473
  return null;
1424
1474
  if (s.length > MAX_PATH_CHARS) {
1425
1475
  const n = lastName(s);
1426
- return exports.WIRING_FILE_NAMES.includes(n) ? `${n} (a path too long to resolve)` : null;
1476
+ return wiringFileNames().includes(n) ? `${n} (a path too long to resolve)` : null;
1427
1477
  }
1428
1478
  // A write through a link writes its target; otherwise the entry is the file (cheap: no realpath).
1429
1479
  // The link test is memoised with the identities (45 000 redirects to one name: 0.5 s of lstat, round 4).
@@ -3264,3 +3314,55 @@ function resolvesInside(raw, roots, impl = path) {
3264
3314
  }
3265
3315
  return false;
3266
3316
  }
3317
+ const FOREIGN_READ_VERB = /^(?:read|get|list|search|find|view|show|stat|describe|query|fetch|count|glob|grep|exists|info|inspect|lookup|check|diff)(?:_|-|[A-Z]|$)/i;
3318
+ const PATH_LIKE_KEY = /^(?:path|paths|file|files|filepath|file_path|filename|uri|target|targetpath|destination|dest|source|src|dir|directory|output|outputpath)$/i;
3319
+ /**
3320
+ * @implements A-SPEC-776 — the paths a foreign MCP call names, read from whatever field its author chose.
3321
+ * `null` for a call that is not a foreign (non-holmes-kit) MCP tool, or whose tool name is a recognisable read. A
3322
+ * `file://` URI becomes its path; any other `scheme://` value is unresolvable, and the caller refuses it.
3323
+ * Measured 2026-10-18: write_file{path}, write{filePath}, save{uri}, create{target} and move{destination} all wrote a
3324
+ * code file the gate never saw, because it read only `file_path` and `notebook_path`.
3325
+ */
3326
+ function foreignMcpPaths(toolName, input) {
3327
+ const m = typeof toolName === 'string' ? /^mcp__(.+?)__(.+)$/.exec(toolName) : null;
3328
+ if (!m || /^holmes[-_]kit$/i.test(m[1]) || FOREIGN_READ_VERB.test(m[2]))
3329
+ return null;
3330
+ const paths = [];
3331
+ const unresolvable = [];
3332
+ const take = (v) => {
3333
+ for (const s of Array.isArray(v) ? v : [v]) {
3334
+ if (typeof s !== 'string' || s.trim() === '')
3335
+ continue;
3336
+ const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(s);
3337
+ if (!scheme) {
3338
+ paths.push(s);
3339
+ continue;
3340
+ }
3341
+ if (scheme[1].toLowerCase() !== 'file') {
3342
+ unresolvable.push(s);
3343
+ continue;
3344
+ }
3345
+ try {
3346
+ paths.push(decodeURIComponent(new URL(s).pathname).replace(/^\/([A-Za-z]:\/)/, '$1'));
3347
+ }
3348
+ catch {
3349
+ unresolvable.push(s);
3350
+ }
3351
+ }
3352
+ };
3353
+ const scan = (o) => {
3354
+ if (!o || typeof o !== 'object' || Array.isArray(o))
3355
+ return;
3356
+ for (const [k, v] of Object.entries(o))
3357
+ if (PATH_LIKE_KEY.test(k))
3358
+ take(v);
3359
+ };
3360
+ if (input && typeof input === 'object' && !Array.isArray(input)) {
3361
+ scan(input);
3362
+ for (const v of Object.values(input))
3363
+ if (Array.isArray(v))
3364
+ for (const e of v)
3365
+ scan(e);
3366
+ }
3367
+ return { paths, unresolvable };
3368
+ }
@@ -1,9 +1,15 @@
1
1
  import { Spec } from '../spec/spec-parser';
2
2
  import { PatchTarget } from '../guardrail/write-target';
3
3
  import { Approval } from '../guardrail/risk-gate';
4
- import { RiskAction, RiskAssessment, RmSignal } from '../guardrail/risk-types';
4
+ import { RiskAction, RiskAssessment, RmSignal, StagedStoreSignal } from '../guardrail/risk-types';
5
5
  import { type PreEditEvidenceMode } from '../guardrail/impact-gate';
6
6
  export declare function resolveRmSignals(command: string, cwd: string, projectRoot?: string, specsDir?: string, scratchTmpdir?: string): Record<string, RmSignal> | undefined;
7
+ /**
8
+ * @implements A-SPEC-226.3 — what `git status` says about the spec store, for a command that holds a staging verb. One
9
+ * child, none of the command's options (`-c core.fsmonitor=…` would run a program), the fsmonitor hook off and no
10
+ * optional index write. No repository is `undefined` (nothing can be staged); any other failure is `unanswered`.
11
+ */
12
+ export declare function resolveStagedStore(command: string, projectRoot: string, specsDir: string): StagedStoreSignal | undefined;
7
13
  /**
8
14
  * @implements A-SPEC-149
9
15
  * The out-of-band approval channel, read at the ENTRY only. `evaluateHook` no longer calls this on
@@ -41,6 +47,25 @@ export declare function hookOutputFor(_toolName: string, out: {
41
47
  permissionDecision: string;
42
48
  permissionDecisionReason?: string;
43
49
  } & Record<string, unknown>): Record<string, unknown>;
50
+ /**
51
+ * @implements A-SPEC-774.2 §1 — an authority name ANYWHERE, once shell quoting is removed. The usage-shape rule
52
+ * (`NAME=`, `$NAME`, `['NAME'`) missed `printf -v`, `read`, `export "$n=…"` and `HOLMES_\ROLE` (measured 2026-10-17):
53
+ * every builtin and every quoting is a new shape, while the name is the one thing they share.
54
+ */
55
+ export declare function authorityMention(command: string): boolean;
56
+ /**
57
+ * @implements A-SPEC-774.2 §2 — the one exception: a pipeline that only searches or reads files. No substitution, no
58
+ * eval/source/exec, no redirect beyond `2>/dev/null` / `2>&1`, and every segment starts with a reader. The
59
+ * environment-dump rules still run on it, so `grep NAME /proc/self/environ` stays refused.
60
+ */
61
+ export declare function readOnlySearch(command: string): boolean;
62
+ export declare function psShowsEnvironment(command: string): boolean;
63
+ /**
64
+ * @implements A-SPEC-774.2 §3 — whether the command starts another agent CLI. A name can be assembled at run time
65
+ * (`n=HOLMES_RO; export "${n}LE=x"`), so no text rule over the name is complete; the act the name exists for is a child
66
+ * agent with a different authority, and that act is refused on its own. `--version`/`--help` alone is not a launch.
67
+ */
68
+ export declare function agentCliLaunch(command: string): boolean;
44
69
  export declare function dumpsEnvInCommandPosition(command: string, depth?: number): boolean;
45
70
  /**
46
71
  * Coerce a hook envelope into known shapes so a type surprise cannot become an exception.
@@ -74,12 +99,19 @@ export interface HookInput {
74
99
  workdir?: string;
75
100
  /** @implements A-SPEC-163.1 — the files a patch tool names in its patch text; judged one by one like `file_path`. */
76
101
  patch_targets?: PatchTarget[];
102
+ /** @implements A-SPEC-776 — the paths a foreign MCP write tool names in its own fields, read before they are dropped. */
103
+ foreign_paths?: {
104
+ paths: string[];
105
+ unresolvable: string[];
106
+ };
77
107
  };
78
108
  /**
79
109
  * @implements A-SPEC-728 (round 17) — the directory the harness runs the shell in (every harness
80
110
  * sends it). The shell base for relative words when it lies inside the project; the root otherwise.
81
111
  */
82
112
  cwd?: string;
113
+ /** @implements A-SPEC-774.9 — the harness session id, so a run record can bind the session itself. */
114
+ session_id?: string;
83
115
  /**
84
116
  * @implements A-SPEC-163
85
117
  * The raw payload carried a path field that was NOT a string, or `tool_input` was not an object.
@@ -211,6 +243,7 @@ export declare function evaluateHook(input: {
211
243
  patch_targets?: PatchTarget[];
212
244
  };
213
245
  cwd?: string;
246
+ session_id?: string;
214
247
  }, specsDir: string, opts: {
215
248
  assess?: (a: RiskAction) => RiskAssessment;
216
249
  /**
@@ -223,6 +256,7 @@ export declare function evaluateHook(input: {
223
256
  */
224
257
  approval: Approval | undefined;
225
258
  resolveRmSignals?: (command: string) => Record<string, RmSignal> | undefined;
259
+ resolveStagedStore?: (command: string) => StagedStoreSignal | undefined;
226
260
  /**
227
261
  * @implements A-SPEC-149
228
262
  * REQUIRED. The implicit `process.cwd()` fallback is gone: it made the gate read whichever