@holmes-lab/holmes-kit 0.30.0 → 0.31.1
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.
- package/CHANGELOG.md +505 -0
- package/README.md +10 -1
- package/bin/holmes-hook-antigravity.js +4 -0
- package/bin/holmes-kit.js +4 -0
- package/bin/holmes-pre-push.js +3 -0
- package/bin/holmes-stop-antigravity.js +4 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/agents.d.ts +41 -0
- package/dist/holmes/cli/agents.js +382 -2
- package/dist/holmes/cli/attest.d.ts +2 -0
- package/dist/holmes/cli/attest.js +66 -15
- package/dist/holmes/cli/ci-gate.js +16 -1
- package/dist/holmes/cli/claude-switches.d.ts +95 -0
- package/dist/holmes/cli/claude-switches.js +967 -0
- package/dist/holmes/cli/codex-hooks.d.ts +77 -0
- package/dist/holmes/cli/codex-hooks.js +802 -0
- package/dist/holmes/cli/codex-oracle.d.ts +194 -0
- package/dist/holmes/cli/codex-oracle.js +1245 -0
- package/dist/holmes/cli/codex-toml.d.ts +35 -0
- package/dist/holmes/cli/codex-toml.js +321 -52
- package/dist/holmes/cli/doctor.d.ts +98 -8
- package/dist/holmes/cli/doctor.js +1328 -94
- package/dist/holmes/cli/index.js +26 -11
- package/dist/holmes/cli/init.d.ts +11 -0
- package/dist/holmes/cli/init.js +736 -44
- package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
- package/dist/holmes/cli/mcp-launcher.js +189 -6
- package/dist/holmes/cli/mcp-version.js +13 -2
- package/dist/holmes/cli/settings-merge.js +8 -2
- package/dist/holmes/cli/upgrade.d.ts +18 -0
- package/dist/holmes/cli/upgrade.js +129 -24
- package/dist/holmes/cli/workspace-scope.d.ts +22 -0
- package/dist/holmes/cli/workspace-scope.js +375 -0
- package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
- package/dist/holmes/cpg/cpg-scanner.js +403 -3
- package/dist/holmes/cpg/cycle-detect.js +2 -1
- package/dist/holmes/cpg/forbidden-edges.js +9 -2
- package/dist/holmes/cpg/required-calls.js +8 -1
- package/dist/holmes/governance/constitution-debt.js +3 -2
- package/dist/holmes/governance/constitution.js +15 -3
- package/dist/holmes/governance/provenance-chain.js +3 -2
- package/dist/holmes/governance/push-gate-runner.js +4 -3
- package/dist/holmes/guardrail/dependency-delta.js +4 -3
- package/dist/holmes/guardrail/linear-match.d.ts +57 -0
- package/dist/holmes/guardrail/linear-match.js +256 -0
- package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
- package/dist/holmes/guardrail/risk-classifier.js +931 -44
- package/dist/holmes/guardrail/risk-types.d.ts +6 -0
- package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
- package/dist/holmes/guardrail/scope-judgment.js +100 -23
- package/dist/holmes/guardrail/shell-words.d.ts +42 -0
- package/dist/holmes/guardrail/shell-words.js +1720 -0
- package/dist/holmes/guardrail/write-target.d.ts +168 -3
- package/dist/holmes/guardrail/write-target.js +2379 -87
- package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
- package/dist/holmes/hooks/adapters/antigravity.js +115 -11
- package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
- package/dist/holmes/hooks/pre-tool-use.js +923 -87
- package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
- package/dist/holmes/hooks/rtm-refresh.js +8 -4
- package/dist/holmes/hooks/session-start.d.ts +10 -0
- package/dist/holmes/hooks/session-start.js +31 -7
- package/dist/holmes/hooks/stop.d.ts +2 -1
- package/dist/holmes/hooks/stop.js +197 -91
- package/dist/holmes/mcp/approval-commit.d.ts +5 -6
- package/dist/holmes/mcp/approval-commit.js +18 -2
- package/dist/holmes/mcp/elicit-approval.js +4 -2
- package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
- package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
- package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
- package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
- package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
- package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
- package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
- package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
- package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
- package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
- package/dist/holmes/mcp/handlers/test-execution.js +9 -3
- package/dist/holmes/mcp/handlers.d.ts +81 -9
- package/dist/holmes/mcp/handlers.js +70 -23
- package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
- package/dist/holmes/mcp/harness-attestation.js +179 -0
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
- package/dist/holmes/mcp/server.js +20 -1
- package/dist/holmes/mcp/tool-schemas.js +26 -9
- package/dist/holmes/mcp/validate-args.js +12 -0
- package/dist/holmes/project/bounded-io.d.ts +102 -0
- package/dist/holmes/project/bounded-io.js +212 -0
- package/dist/holmes/project/change-source.js +3 -1
- package/dist/holmes/project/ci-runs.js +3 -2
- package/dist/holmes/project/ignore.d.ts +31 -2
- package/dist/holmes/project/ignore.js +409 -50
- package/dist/holmes/project/regular-file-guard.d.ts +13 -0
- package/dist/holmes/project/regular-file-guard.js +149 -0
- package/dist/holmes/project/root.js +12 -3
- package/dist/holmes/reverse/anchor.js +4 -3
- package/dist/holmes/reverse/scan.js +6 -2
- package/dist/holmes/review/commit-text.js +3 -2
- package/dist/holmes/review/condition-hunk-replay.js +3 -2
- package/dist/holmes/review/failed-test-names.js +13 -10
- package/dist/holmes/review/findings.js +3 -1
- package/dist/holmes/review/kills-check.js +6 -1
- package/dist/holmes/review/point-in-time-replay.js +5 -4
- package/dist/holmes/review/replay-corpus.js +5 -4
- package/dist/holmes/review/run-replay.js +3 -2
- package/dist/holmes/review/temporal-prior.js +3 -2
- package/dist/holmes/review/test-evidence.js +3 -2
- package/dist/holmes/review/test-outcomes.js +3 -2
- package/dist/holmes/review/test-runner.d.ts +6 -0
- package/dist/holmes/review/test-runner.js +36 -15
- package/dist/holmes/rtm/advisory-outcomes.js +3 -2
- package/dist/holmes/rtm/anchor-ids.js +42 -2
- package/dist/holmes/rtm/file-anchors.js +4 -1
- package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
- package/dist/holmes/rtm/git-changes.js +3 -1
- package/dist/holmes/rtm/graph-store.js +3 -2
- package/dist/holmes/rtm/test-scope.js +9 -4
- package/dist/holmes/spec/compat-impact.d.ts +25 -4
- package/dist/holmes/spec/compat-impact.js +682 -11
- package/dist/holmes/spec/entity-git-snapshot.js +3 -2
- package/dist/holmes/spec/entity-integration.js +3 -2
- package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
- package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
- package/dist/holmes/spec/remote-spec-refs.js +3 -2
- package/dist/holmes/spec/renumber.js +25 -10
- package/dist/holmes/spec/spec-parser.js +9 -3
- package/dist/holmes/spec/yaml-scalar.js +2 -2
- package/dist/holmes/update/refresh.d.ts +5 -0
- package/dist/holmes/update/refresh.js +26 -1
- package/dist/holmes/update/update-notice.d.ts +6 -0
- package/dist/holmes/update/update-notice.js +18 -1
- package/dist/holmes/update/upgrade-plan.d.ts +28 -0
- package/dist/holmes/update/upgrade-plan.js +31 -2
- package/package.json +11 -4
|
@@ -0,0 +1,967 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.CLAUDE_SETTINGS_MAX_BYTES = void 0;
|
|
37
|
+
exports.managedSettingsDirs = managedSettingsDirs;
|
|
38
|
+
exports.claudeSwitchEnv = claudeSwitchEnv;
|
|
39
|
+
exports.claudeUserSettingsPath = claudeUserSettingsPath;
|
|
40
|
+
exports.readFileHead = readFileHead;
|
|
41
|
+
exports.localPhysicalRealpath = localPhysicalRealpath;
|
|
42
|
+
exports.isClaudeEvent = isClaudeEvent;
|
|
43
|
+
exports.canonicalLocalSettingsPath = canonicalLocalSettingsPath;
|
|
44
|
+
exports.claudeDropsFile = claudeDropsFile;
|
|
45
|
+
exports.isAbsoluteScript = isAbsoluteScript;
|
|
46
|
+
exports.printable = printable;
|
|
47
|
+
exports.claudeSwitches = claudeSwitches;
|
|
48
|
+
exports.claudeHookSwitchesCheck = claudeHookSwitchesCheck;
|
|
49
|
+
// @implements A-SPEC-251.2
|
|
50
|
+
// @implements A-SPEC-251.1
|
|
51
|
+
/**
|
|
52
|
+
* The settings that switch Claude Code's hooks, or Holmes's tools, off (A-SPEC-251.2 round 30).
|
|
53
|
+
*
|
|
54
|
+
* Measured: a committed `.claude/settings.json` holding `{"disableAllHooks": true}` switched every Claude hook off —
|
|
55
|
+
* the Holmes gate included — while init said "the gate is enforced" and every doctor check passed. Claude Code reads
|
|
56
|
+
* `disableAllHooks` as a restrictive setting: `true` in any source (managed policy, user, `--settings`, project, local)
|
|
57
|
+
* holds, and a managed `allowManagedHooksOnly: true` leaves only managed hooks (read from the installed 2.1.281
|
|
58
|
+
* binary). Only the file tier is read here: MDM, server-managed policy and `--settings` are named as not read.
|
|
59
|
+
*/
|
|
60
|
+
const fs = __importStar(require("node:fs"));
|
|
61
|
+
const os = __importStar(require("node:os"));
|
|
62
|
+
const path = __importStar(require("node:path"));
|
|
63
|
+
const bounded_io_1 = require("../project/bounded-io");
|
|
64
|
+
const codex_oracle_1 = require("./codex-oracle");
|
|
65
|
+
/** The managed-settings folders Claude Code reads on each platform. */
|
|
66
|
+
function managedSettingsDirs(platform = process.platform) {
|
|
67
|
+
if (platform === 'darwin')
|
|
68
|
+
return ['/Library/Application Support/ClaudeCode'];
|
|
69
|
+
if (platform === 'win32')
|
|
70
|
+
return ['C:\\Program Files\\ClaudeCode'];
|
|
71
|
+
return ['/etc/claude-code'];
|
|
72
|
+
}
|
|
73
|
+
function claudeSwitchEnv() {
|
|
74
|
+
const home = (() => { try {
|
|
75
|
+
return os.homedir();
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
return '';
|
|
79
|
+
} })();
|
|
80
|
+
const cfg = process.env.CLAUDE_CONFIG_DIR;
|
|
81
|
+
const oauth = process.env.CLAUDE_CODE_CUSTOM_OAUTH_URL;
|
|
82
|
+
return { home, claudeConfigDir: cfg !== undefined && cfg.trim() !== '' ? cfg : undefined, managedDirs: managedSettingsDirs(),
|
|
83
|
+
...(typeof oauth === 'string' && oauth !== '' ? { customOauth: true } : {}), ...(cfg !== undefined ? { rawConfigDir: cfg } : {}) };
|
|
84
|
+
}
|
|
85
|
+
/** Claude's user settings file: `$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. */
|
|
86
|
+
function claudeUserSettingsPath(env) {
|
|
87
|
+
// @implements A-SPEC-251.2 (round 44) — from the raw CLAUDE_CONFIG_DIR as Claude computes it (`(raw ?? ~/.claude)
|
|
88
|
+
// .normalize("NFC")`); a directory that is not absolute depends on the session's directory, so it is not read (an empty
|
|
89
|
+
// value read `~/.claude/settings.json` and reported a FAIL Claude would not have — measured).
|
|
90
|
+
if ('rawConfigDir' in env) {
|
|
91
|
+
const dir = (env.rawConfigDir ?? path.join(env.home, '.claude')).normalize('NFC');
|
|
92
|
+
return path.isAbsolute(dir) ? path.join(dir, 'settings.json') : null;
|
|
93
|
+
}
|
|
94
|
+
return path.join(env.claudeConfigDir ?? path.join(env.home, '.claude'), 'settings.json');
|
|
95
|
+
}
|
|
96
|
+
const SETTINGS_MAX_BYTES = 8 * 1024 * 1024;
|
|
97
|
+
/**
|
|
98
|
+
* @implements A-SPEC-251.2 (round 35) — the largest settings file Claude Code 2.1.281 reads (`size > maxBytes` is
|
|
99
|
+
* ERR_FILE_TOO_LARGE, and the file applies nothing): a 3 MiB file holding Holmes's hooks read PASS and "enforced" (measured).
|
|
100
|
+
*/
|
|
101
|
+
exports.CLAUDE_SETTINGS_MAX_BYTES = 2 * 1024 * 1024;
|
|
102
|
+
/** The first `max` bytes of a regular file as text (a `.git` file, `commondir`, `gitdir`), or null. Never blocks on a FIFO. */
|
|
103
|
+
function readFileHead(file, max = 64 * 1024) {
|
|
104
|
+
let fd;
|
|
105
|
+
try {
|
|
106
|
+
fd = fs.openSync(file, fs.constants.O_RDONLY | (typeof fs.constants.O_NONBLOCK === 'number' ? fs.constants.O_NONBLOCK : 0));
|
|
107
|
+
}
|
|
108
|
+
catch {
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
111
|
+
try {
|
|
112
|
+
if (!fs.fstatSync(fd).isFile())
|
|
113
|
+
return null;
|
|
114
|
+
const buf = Buffer.alloc(max);
|
|
115
|
+
const n = fs.readSync(fd, buf, 0, max, 0);
|
|
116
|
+
return buf.subarray(0, n).toString('utf8');
|
|
117
|
+
}
|
|
118
|
+
catch {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
finally {
|
|
122
|
+
fs.closeSync(fd);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* @implements A-SPEC-251.2 (round 35) — a path resolved one component at a time as the kernel resolves a command (`..` from
|
|
127
|
+
* the real path so far), never looking up a network or device path (`/net/<host>`, `//host`, `\\host`): Claude's and
|
|
128
|
+
* Antigravity's wirings reached `realpath` on an automounter path (code reading, lookups intercepted — measured).
|
|
129
|
+
*/
|
|
130
|
+
function localPhysicalRealpath(p, budget) {
|
|
131
|
+
if (p.length > 64 * 1024 || !(path.isAbsolute(p) || path.win32.isAbsolute(p)))
|
|
132
|
+
return { path: null, refused: false };
|
|
133
|
+
if (!(0, codex_oracle_1.openableLocalPath)(p))
|
|
134
|
+
return { path: null, refused: true };
|
|
135
|
+
const split = (q) => (process.platform === 'win32' ? q.split(/[\\/]+/) : q.split('/')).filter((c) => c !== '' && c !== '.');
|
|
136
|
+
const root0 = path.parse(p).root;
|
|
137
|
+
let done = root0;
|
|
138
|
+
const queue = split(p.slice(root0.length)).reverse();
|
|
139
|
+
let hops = 0;
|
|
140
|
+
while (queue.length > 0) {
|
|
141
|
+
const c = queue.pop();
|
|
142
|
+
if (c === '..') {
|
|
143
|
+
done = path.dirname(done);
|
|
144
|
+
continue;
|
|
145
|
+
}
|
|
146
|
+
const next = path.join(done, c);
|
|
147
|
+
if (next.length > 4096)
|
|
148
|
+
return { path: null, refused: false };
|
|
149
|
+
if (!(0, codex_oracle_1.openableLocalPath)(next))
|
|
150
|
+
return { path: null, refused: true };
|
|
151
|
+
// Round 36: a caller walking many paths bounds their total components.
|
|
152
|
+
if (budget !== undefined && --budget.left < 0)
|
|
153
|
+
return { path: null, refused: false, exhausted: true };
|
|
154
|
+
let st;
|
|
155
|
+
try {
|
|
156
|
+
st = fs.lstatSync(next);
|
|
157
|
+
}
|
|
158
|
+
catch {
|
|
159
|
+
return { path: null, refused: false };
|
|
160
|
+
}
|
|
161
|
+
if (!st.isSymbolicLink()) {
|
|
162
|
+
done = next;
|
|
163
|
+
continue;
|
|
164
|
+
}
|
|
165
|
+
if (++hops > 40)
|
|
166
|
+
return { path: null, refused: false };
|
|
167
|
+
let target;
|
|
168
|
+
try {
|
|
169
|
+
target = fs.readlinkSync(next);
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
return { path: null, refused: false };
|
|
173
|
+
}
|
|
174
|
+
if (path.isAbsolute(target) || path.win32.isAbsolute(target)) {
|
|
175
|
+
if (!(0, codex_oracle_1.openableLocalPath)(target))
|
|
176
|
+
return { path: null, refused: true };
|
|
177
|
+
const r = path.parse(target).root;
|
|
178
|
+
done = r;
|
|
179
|
+
queue.push(...split(target.slice(r.length)).reverse());
|
|
180
|
+
}
|
|
181
|
+
else
|
|
182
|
+
queue.push(...split(target).reverse());
|
|
183
|
+
}
|
|
184
|
+
try {
|
|
185
|
+
return { path: fs.realpathSync.native(done), refused: false };
|
|
186
|
+
}
|
|
187
|
+
catch {
|
|
188
|
+
return { path: null, refused: false };
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
function readSettings(file, planned) {
|
|
192
|
+
let text;
|
|
193
|
+
let tooLarge = false;
|
|
194
|
+
// Round 50: the content init is about to write stands for the file (`planned`).
|
|
195
|
+
if (planned !== undefined) {
|
|
196
|
+
text = planned;
|
|
197
|
+
tooLarge = Buffer.byteLength(planned) > exports.CLAUDE_SETTINGS_MAX_BYTES;
|
|
198
|
+
}
|
|
199
|
+
else
|
|
200
|
+
try {
|
|
201
|
+
const size = fs.statSync(file).size;
|
|
202
|
+
if (size > SETTINGS_MAX_BYTES)
|
|
203
|
+
return { file, unreadable: 'larger than 8 MiB, which Claude does not read either' };
|
|
204
|
+
tooLarge = size > exports.CLAUDE_SETTINGS_MAX_BYTES;
|
|
205
|
+
text = (0, bounded_io_1.readRegularTextSync)(file);
|
|
206
|
+
}
|
|
207
|
+
catch (e) {
|
|
208
|
+
if (e.code === 'ENOENT' || e.code === 'ENOTDIR')
|
|
209
|
+
return null;
|
|
210
|
+
return { file, unreadable: e.code ?? 'unreadable' };
|
|
211
|
+
}
|
|
212
|
+
try {
|
|
213
|
+
// Round 34: an empty file is empty settings, as Claude reads it.
|
|
214
|
+
if (text.replace(/^\uFEFF/, '').trim() === '')
|
|
215
|
+
return { file, value: {} };
|
|
216
|
+
const value = JSON.parse(text.replace(/^\uFEFF/, ''));
|
|
217
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value))
|
|
218
|
+
return { file, unreadable: 'not a JSON object' };
|
|
219
|
+
return { file, value: value, ...(tooLarge ? { tooLarge: true } : {}) };
|
|
220
|
+
}
|
|
221
|
+
catch {
|
|
222
|
+
return { file, unreadable: 'not valid JSON' };
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
/** Hook types Claude Code 2.1.281 loads (its settings schema: command, prompt, agent, mcp_tool, http). */
|
|
226
|
+
const HOOK_TYPES = new Set(['command', 'prompt', 'agent', 'mcp_tool', 'http']);
|
|
227
|
+
/** Claude Code 2.1.281's hook events (`mm`). */
|
|
228
|
+
const CLAUDE_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PostToolBatch', 'Notification', 'UserPromptSubmit',
|
|
229
|
+
'UserPromptExpansion', 'SessionStart', 'SessionEnd', 'Stop', 'StopFailure', 'SubagentStart', 'SubagentStop', 'PreCompact', 'PostCompact',
|
|
230
|
+
'PreModelSwitch', 'PostModelSwitch', 'PermissionRequest', 'PermissionDenied', 'Setup', 'TeammateIdle', 'TaskCreated', 'TaskCompleted',
|
|
231
|
+
'Elicitation', 'ElicitationResult', 'ConfigChange', 'WorktreeCreate', 'WorktreeRemove', 'InstructionsLoaded', 'CwdChanged', 'FileChanged',
|
|
232
|
+
'DirectoryAdded', 'MessageDisplay']);
|
|
233
|
+
function isClaudeEvent(name) { return CLAUDE_EVENTS.has(name); }
|
|
234
|
+
const GUARD_EVENTS = new Set(['PreToolUse', 'PermissionRequest']);
|
|
235
|
+
/** The top-level keys Claude does not scan for misplaced guards (`qs`). */
|
|
236
|
+
const UNSCANNED = new Set(['mcpServers', 'managedMcpServers', 'lspServers', 'pluginConfigs', 'enabledPlugins', 'extraKnownMarketplaces', 'env',
|
|
237
|
+
'skillOverrides', 'modelSettings']);
|
|
238
|
+
const NONE = new Set();
|
|
239
|
+
const isObject = (e) => e !== null && typeof e === 'object' && !Array.isArray(e);
|
|
240
|
+
/** `Zs`: an object with a PreToolUse/PermissionRequest key that holds something. */
|
|
241
|
+
function holdsGuardKey(e) {
|
|
242
|
+
return isObject(e) && Object.entries(e).some(([k, v]) => GUARD_EVENTS.has(k) && v !== null && v !== undefined && !(Array.isArray(v) && v.length === 0));
|
|
243
|
+
}
|
|
244
|
+
/** `WZ`: shaped like one matcher group. */
|
|
245
|
+
function looksLikeMatcher(e) {
|
|
246
|
+
if (!isObject(e))
|
|
247
|
+
return false;
|
|
248
|
+
if (!('matcher' in e) && Object.keys(e).some((k) => CLAUDE_EVENTS.has(k)))
|
|
249
|
+
return false;
|
|
250
|
+
const n = e.hooks;
|
|
251
|
+
if (Array.isArray(n))
|
|
252
|
+
return n.length > 0;
|
|
253
|
+
return !!n && typeof n === 'object' && ('matcher' in e || typeof n.type === 'string');
|
|
254
|
+
}
|
|
255
|
+
/** `Ome`: whether a value holds PreToolUse/PermissionRequest hooks within `n` levels. */
|
|
256
|
+
function holdsGuards(e, n, o = {}) {
|
|
257
|
+
const matchersCount = o.matchersCount ?? true, unscanned = o.unscanned ?? NONE, inHooksList = o.inHooksList ?? false;
|
|
258
|
+
if (holdsGuardKey(e))
|
|
259
|
+
return true;
|
|
260
|
+
if (matchersCount && looksLikeMatcher(e))
|
|
261
|
+
return true;
|
|
262
|
+
if (n === 0 || !e || typeof e !== 'object')
|
|
263
|
+
return false;
|
|
264
|
+
if (Array.isArray(e))
|
|
265
|
+
return e.some((c) => holdsGuards(c, n - 1, { matchersCount, unscanned, inHooksList }));
|
|
266
|
+
if (inHooksList && typeof e.type === 'string')
|
|
267
|
+
return false;
|
|
268
|
+
return Object.entries(e).some(([c, u]) => !unscanned.has(c)
|
|
269
|
+
&& holdsGuards(u, n - 1, { unscanned, matchersCount: matchersCount && !CLAUDE_EVENTS.has(c), inHooksList: c === 'hooks' && Array.isArray(u) }));
|
|
270
|
+
}
|
|
271
|
+
/** `Dme`, bounded (Claude recurses without a bound; a deep list here is read as not holding one). */
|
|
272
|
+
function holdsMatcherOrGuard(e, depth = 0) {
|
|
273
|
+
if (depth > 256)
|
|
274
|
+
return false;
|
|
275
|
+
if (looksLikeMatcher(e))
|
|
276
|
+
return true;
|
|
277
|
+
if (Array.isArray(e))
|
|
278
|
+
return e.some((x) => holdsMatcherOrGuard(x, depth + 1));
|
|
279
|
+
return holdsGuardKey(e);
|
|
280
|
+
}
|
|
281
|
+
const str = (v) => typeof v === 'string';
|
|
282
|
+
const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
|
|
283
|
+
const bool = (v) => typeof v === 'boolean';
|
|
284
|
+
// Round 35: zod v4 numbers are finite (`1e999` parses to Infinity and drops the file).
|
|
285
|
+
const positive = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
|
|
286
|
+
const strings = (v) => Array.isArray(v) && v.every(str);
|
|
287
|
+
// Round 35: as zod v4 parses them — a record skips a `__proto__` key; a URL is trimmed before it is parsed.
|
|
288
|
+
const recordOf = (value) => (v) => isObject(v) && Object.entries(v).every(([k, x]) => k === '__proto__' || value(x));
|
|
289
|
+
const url = (v) => { if (typeof v !== 'string')
|
|
290
|
+
return false; try {
|
|
291
|
+
new URL(v.trim());
|
|
292
|
+
return true;
|
|
293
|
+
}
|
|
294
|
+
catch {
|
|
295
|
+
return false;
|
|
296
|
+
} };
|
|
297
|
+
/** Each hook type's schema in 2.1.281 (`pc`): required and optional fields; an unknown field is dropped, `cloud` never fails. */
|
|
298
|
+
const HOOK_SCHEMA = {
|
|
299
|
+
command: { required: { command: str }, optional: { args: strings, if: str, shell: (v) => v === 'bash' || v === 'powershell', timeout: positive,
|
|
300
|
+
statusMessage: str, once: bool, async: bool, asyncRewake: bool, rewakeMessage: nonEmpty, rewakeSummary: nonEmpty } },
|
|
301
|
+
prompt: { required: { prompt: str }, optional: { if: str, timeout: positive, model: str, continueOnBlock: bool, statusMessage: str, once: bool } },
|
|
302
|
+
mcp_tool: { required: { server: str, tool: str }, optional: { input: recordOf(() => true), if: str, timeout: positive, statusMessage: str, once: bool } },
|
|
303
|
+
http: { required: { url }, optional: { if: str, timeout: positive, headers: recordOf(str), allowedEnvVars: strings, statusMessage: str, once: bool } },
|
|
304
|
+
agent: { required: { prompt: str }, optional: { if: str, timeout: positive, model: str, statusMessage: str, once: bool } },
|
|
305
|
+
};
|
|
306
|
+
/** `gc`: why Claude cannot load one hook entry, or null. */
|
|
307
|
+
function hookEntryProblem(h) {
|
|
308
|
+
if (!isObject(h))
|
|
309
|
+
return 'is not an object';
|
|
310
|
+
const type = h.type;
|
|
311
|
+
if (typeof type !== 'string')
|
|
312
|
+
return 'has no string "type"';
|
|
313
|
+
const schema = Object.prototype.hasOwnProperty.call(HOOK_SCHEMA, type) && HOOK_TYPES.has(type) ? HOOK_SCHEMA[type] : undefined;
|
|
314
|
+
if (schema === undefined)
|
|
315
|
+
return `has a hook type Claude does not load (${JSON.stringify(type).slice(0, 40)})`;
|
|
316
|
+
for (const [k, check] of Object.entries(schema.required))
|
|
317
|
+
if (!Object.prototype.hasOwnProperty.call(h, k) || !check(h[k]))
|
|
318
|
+
return `has no valid \`${k}\``;
|
|
319
|
+
for (const [k, check] of Object.entries(schema.optional))
|
|
320
|
+
if (Object.prototype.hasOwnProperty.call(h, k) && !check(h[k]))
|
|
321
|
+
return `has an invalid \`${k}\``;
|
|
322
|
+
return null;
|
|
323
|
+
}
|
|
324
|
+
/** `zt`: the first entry of one event's matcher list that makes Claude drop the file, or null. */
|
|
325
|
+
function unloadableIn(list, event) {
|
|
326
|
+
const guard = GUARD_EVENTS.has(event);
|
|
327
|
+
for (const [p, g] of list.entries()) {
|
|
328
|
+
const at = `\`hooks.${event.slice(0, 64)}[${p}]`;
|
|
329
|
+
if (holdsGuards(g, 3, { matchersCount: false }))
|
|
330
|
+
return `${at}\` holds PreToolUse/PermissionRequest hooks where a matcher was expected`;
|
|
331
|
+
if (!guard)
|
|
332
|
+
continue; // another event's bad group or entry is ignored, not fatal
|
|
333
|
+
if (!isObject(g))
|
|
334
|
+
return `${at}\` is not an object`;
|
|
335
|
+
if (!Array.isArray(g.hooks))
|
|
336
|
+
return `${at}.hooks\` is not a list`;
|
|
337
|
+
for (const [k, h] of g.hooks.entries()) {
|
|
338
|
+
const problem = hookEntryProblem(h);
|
|
339
|
+
if (problem !== null)
|
|
340
|
+
return `${at}.hooks[${k}]\` ${problem}`;
|
|
341
|
+
}
|
|
342
|
+
if (Object.prototype.hasOwnProperty.call(g, 'matcher') && typeof g.matcher !== 'string')
|
|
343
|
+
return `${at}.matcher\` is not a string`;
|
|
344
|
+
}
|
|
345
|
+
return null;
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* A non-managed settings file as Claude 2.1.281 cleans it before it scans it (`Sl`, `JZ`, `Lf`, `Rf`): `isolation` and
|
|
349
|
+
* `managedMcpServers` are dropped, the marketplace aliases renamed, null marketplace lists dropped, and the permission lists
|
|
350
|
+
* keep only strings. Shallow: nothing the caller holds is changed.
|
|
351
|
+
*
|
|
352
|
+
* @implements A-SPEC-251.2 (round 35) — scanning the raw object read `{"isolation": {"PreToolUse": …}}` and
|
|
353
|
+
* `permissions.allow: [{"PreToolUse": …}]` as dropping a file Claude loads (measured).
|
|
354
|
+
*/
|
|
355
|
+
function asClaudeCleans(v) {
|
|
356
|
+
const e = { ...v };
|
|
357
|
+
for (const k of ['managedMcpServers', 'isolation'])
|
|
358
|
+
delete e[k];
|
|
359
|
+
for (const [alias, canonical] of [['additionalMarketplaces', 'extraKnownMarketplaces'], ['allowedMarketplaces', 'strictKnownMarketplaces']]) {
|
|
360
|
+
if (!Object.prototype.hasOwnProperty.call(e, alias))
|
|
361
|
+
continue;
|
|
362
|
+
if (e[alias] !== null && !(Object.prototype.hasOwnProperty.call(e, canonical) && e[canonical] !== null))
|
|
363
|
+
e[canonical] = e[alias];
|
|
364
|
+
delete e[alias];
|
|
365
|
+
}
|
|
366
|
+
for (const k of ['strictKnownMarketplaces', 'blockedMarketplaces', 'disableSideloadFlags'])
|
|
367
|
+
if (e[k] === null)
|
|
368
|
+
delete e[k];
|
|
369
|
+
if (e.permissions !== null && typeof e.permissions === 'object') {
|
|
370
|
+
const perms = (Array.isArray(e.permissions) ? e.permissions : { ...e.permissions });
|
|
371
|
+
for (const c of ['allow', 'deny', 'ask']) {
|
|
372
|
+
const u = perms[c];
|
|
373
|
+
if (Array.isArray(u))
|
|
374
|
+
perms[c] = u.filter((x) => typeof x === 'string');
|
|
375
|
+
}
|
|
376
|
+
e.permissions = perms;
|
|
377
|
+
}
|
|
378
|
+
return e;
|
|
379
|
+
}
|
|
380
|
+
/**
|
|
381
|
+
* @implements A-SPEC-251.2 (round 35) — where Claude 2.1.281 also reads local settings (`lU`, `pOo`, `Bme`): the canonical git
|
|
382
|
+
* root — the nearest `.git` directory's checkout, or a `.git` file's main checkout (its `commondir` named `.git`) — when it is
|
|
383
|
+
* neither the target nor the home directory and, on POSIX, it, its `.git` and its `.claude` (if any) belong to this user. A
|
|
384
|
+
* root's `disableAllHooks` read PASS from a monorepo package and a linked worktree (measured). Network paths are not followed.
|
|
385
|
+
*/
|
|
386
|
+
function canonicalLocalSettingsPath(target, home) {
|
|
387
|
+
const uid = typeof process.geteuid === 'function' ? process.geteuid() : typeof process.getuid === 'function' ? process.getuid() : null;
|
|
388
|
+
if (uid === null)
|
|
389
|
+
return null;
|
|
390
|
+
const cwd = localPhysicalRealpath(path.resolve(target)).path;
|
|
391
|
+
if (cwd === null)
|
|
392
|
+
return null;
|
|
393
|
+
const root = claudeCanonicalRoot(cwd);
|
|
394
|
+
if (root === null)
|
|
395
|
+
return null;
|
|
396
|
+
const rootReal = localPhysicalRealpath(root).path;
|
|
397
|
+
if (rootReal === null || rootReal === cwd || rootReal === (localPhysicalRealpath(home).path ?? home))
|
|
398
|
+
return null;
|
|
399
|
+
try {
|
|
400
|
+
if (fs.statSync(rootReal).uid !== uid || fs.lstatSync(path.join(rootReal, '.git')).uid !== uid)
|
|
401
|
+
return null;
|
|
402
|
+
try {
|
|
403
|
+
if (fs.lstatSync(path.join(rootReal, '.claude')).uid !== uid)
|
|
404
|
+
return null;
|
|
405
|
+
}
|
|
406
|
+
catch (e) {
|
|
407
|
+
if (e.code !== 'ENOENT')
|
|
408
|
+
return null;
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
catch {
|
|
412
|
+
return null;
|
|
413
|
+
}
|
|
414
|
+
return path.join(rootReal, '.claude', 'settings.local.json');
|
|
415
|
+
}
|
|
416
|
+
/** `ke`: a `.git` entry git would use — a directory or file, or a link to one (a dangling link, a FIFO, a network link: no). */
|
|
417
|
+
function isGitEntry(p) {
|
|
418
|
+
let st;
|
|
419
|
+
try {
|
|
420
|
+
st = fs.lstatSync(p);
|
|
421
|
+
}
|
|
422
|
+
catch {
|
|
423
|
+
return false;
|
|
424
|
+
}
|
|
425
|
+
if (!st.isSymbolicLink())
|
|
426
|
+
return st.isDirectory() || st.isFile();
|
|
427
|
+
const walked = localPhysicalRealpath(p);
|
|
428
|
+
if (walked.path === null)
|
|
429
|
+
return false;
|
|
430
|
+
try {
|
|
431
|
+
const t = fs.statSync(walked.path);
|
|
432
|
+
return t.isDirectory() || t.isFile();
|
|
433
|
+
}
|
|
434
|
+
catch {
|
|
435
|
+
return false;
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
/** A regular file that is not a link (`YR` negated). */
|
|
439
|
+
const plainFile = (p) => { try {
|
|
440
|
+
return fs.lstatSync(p).isFile();
|
|
441
|
+
}
|
|
442
|
+
catch {
|
|
443
|
+
return false;
|
|
444
|
+
} };
|
|
445
|
+
/**
|
|
446
|
+
* Claude 2.1.281's canonical git root for a directory (`Gt`, `ke`, `Ce`, `Ht`), or null outside a repository.
|
|
447
|
+
*
|
|
448
|
+
* @implements A-SPEC-251.2 (round 36) — the nearest usable `.git` (a dangling link or FIFO is skipped); a `.git` file names its
|
|
449
|
+
* main checkout only when `gitdir:` leads to `<common>/worktrees/<id>` with plain `commondir` and `gitdir` files whose
|
|
450
|
+
* back-pointer is this checkout's `.git` — round 35 skipped these and read a moved worktree and a `--separate-git-dir`
|
|
451
|
+
* directory as canonical (false FAIL — measured). Every path is walked without network lookups.
|
|
452
|
+
*/
|
|
453
|
+
function claudeCanonicalRoot(cwd) {
|
|
454
|
+
let root = null;
|
|
455
|
+
for (let d = cwd, i = 0; i < 256; i++) {
|
|
456
|
+
if (isGitEntry(path.join(d, '.git'))) {
|
|
457
|
+
root = d;
|
|
458
|
+
break;
|
|
459
|
+
}
|
|
460
|
+
const parent = path.dirname(d);
|
|
461
|
+
if (parent === d)
|
|
462
|
+
break;
|
|
463
|
+
d = parent;
|
|
464
|
+
}
|
|
465
|
+
if (root === null)
|
|
466
|
+
return null;
|
|
467
|
+
const r = (readFileHead(path.join(root, '.git')) ?? '').trim();
|
|
468
|
+
if (!r.startsWith('gitdir:'))
|
|
469
|
+
return root;
|
|
470
|
+
// Round 37: as `Ht` does — the git and common directories are compared and returned as text; walks only refuse the network
|
|
471
|
+
// and read the back-pointer's real path (comparing real paths disagreed with Claude on linked git directories — measured).
|
|
472
|
+
const s = path.resolve(root, r.slice(7).trim());
|
|
473
|
+
const sWalk = localPhysicalRealpath(s);
|
|
474
|
+
if (sWalk.refused || sWalk.path === null || !plainFile(path.join(sWalk.path, 'commondir')))
|
|
475
|
+
return root;
|
|
476
|
+
const a = path.resolve(s, (readFileHead(path.join(sWalk.path, 'commondir')) ?? '').trim());
|
|
477
|
+
if (!(0, codex_oracle_1.openableLocalPath)(a) || path.dirname(s) !== path.join(a, 'worktrees'))
|
|
478
|
+
return root;
|
|
479
|
+
if (!plainFile(path.join(sWalk.path, 'gitdir')))
|
|
480
|
+
return root;
|
|
481
|
+
const back = path.resolve(s, (readFileHead(path.join(sWalk.path, 'gitdir')) ?? '').trim());
|
|
482
|
+
const backReal = (0, codex_oracle_1.openableLocalPath)(back) ? localPhysicalRealpath(back).path : null;
|
|
483
|
+
const rootReal = localPhysicalRealpath(root).path;
|
|
484
|
+
if (backReal === null || rootReal === null || backReal !== path.join(rootReal, '.git'))
|
|
485
|
+
return root;
|
|
486
|
+
if (path.basename(a) !== '.git')
|
|
487
|
+
return isGitEntry(path.join(a, '.git')) ? root : a;
|
|
488
|
+
return path.dirname(a);
|
|
489
|
+
}
|
|
490
|
+
/**
|
|
491
|
+
* Why Claude Code applies NOTHING from this settings file, or null.
|
|
492
|
+
*
|
|
493
|
+
* @implements A-SPEC-251.2 (round 34) — Claude 2.1.281's loader (`Pf`, `Tf`, `zt`, `gc`) transcribed: a PreToolUse/
|
|
494
|
+
* PermissionRequest hook it cannot load, or one declared outside `hooks`, makes it apply nothing in the file ("nothing it
|
|
495
|
+
* sits in is applied"). Round 33 read a few shapes and PASSed 24 others (`timeout: 0`, `matcher: null`, a top-level
|
|
496
|
+
* `"PreToolUse"` — measured); it also refused files Claude loads (a `"matcher"` key beside the events). What Claude only warns
|
|
497
|
+
* about and drops (an unknown event, another event's bad group) does not drop the file. The rest of Claude's settings schema
|
|
498
|
+
* (which can also drop a file) is not read.
|
|
499
|
+
*/
|
|
500
|
+
function claudeDropsFile(raw) {
|
|
501
|
+
if (!isObject(raw))
|
|
502
|
+
return null;
|
|
503
|
+
const settings = asClaudeCleans(raw);
|
|
504
|
+
if (holdsGuardKey(settings) || Object.entries(settings).some(([k, v]) => k !== 'hooks' && !UNSCANNED.has(k)
|
|
505
|
+
&& holdsGuards(v, 3, { unscanned: UNSCANNED, matchersCount: !CLAUDE_EVENTS.has(k) }))) {
|
|
506
|
+
return 'PreToolUse/PermissionRequest hooks are declared outside `hooks`';
|
|
507
|
+
}
|
|
508
|
+
if (!Object.prototype.hasOwnProperty.call(settings, 'hooks'))
|
|
509
|
+
return null;
|
|
510
|
+
const hooks = settings.hooks;
|
|
511
|
+
if (!isObject(hooks))
|
|
512
|
+
return Array.isArray(hooks) && (hooks.some(isObject) || holdsMatcherOrGuard(hooks)) ? '`hooks` is a list of matchers, not an object of events' : null;
|
|
513
|
+
if (looksLikeMatcher(hooks))
|
|
514
|
+
return '`hooks` is a single matcher, not an object of events';
|
|
515
|
+
for (const [event, value] of Object.entries(hooks)) {
|
|
516
|
+
const at = `\`hooks.${event.slice(0, 64)}\``;
|
|
517
|
+
if (!CLAUDE_EVENTS.has(event)) {
|
|
518
|
+
if (holdsGuards(value, 3, { matchersCount: !Array.isArray(value) }))
|
|
519
|
+
return `${at} is not a hook event but holds PreToolUse/PermissionRequest hooks`;
|
|
520
|
+
continue;
|
|
521
|
+
}
|
|
522
|
+
if (!Array.isArray(value)) {
|
|
523
|
+
if ((GUARD_EVENTS.has(event) && value !== null) || holdsGuards(value, 3, { matchersCount: false }))
|
|
524
|
+
return `${at} is not a list of matchers`;
|
|
525
|
+
continue;
|
|
526
|
+
}
|
|
527
|
+
const problem = unloadableIn(value, event);
|
|
528
|
+
if (problem !== null)
|
|
529
|
+
return problem;
|
|
530
|
+
}
|
|
531
|
+
return null;
|
|
532
|
+
}
|
|
533
|
+
/**
|
|
534
|
+
* @implements A-SPEC-251.2 (round 39) — the gate entry `init` writes, and nothing else, is CONFIRMED to block: `{ "type":
|
|
535
|
+
* "command", "command": "node \"<…>/dist/holmes/hooks/pre-tool-use.js\"" }` (with init's own `--specs "<dir>"`). Owner
|
|
536
|
+
* decision 2026-09-26: rounds 37–39 each found another piece of Claude 2.1.281's hook runner doctor did not model — `async`
|
|
537
|
+
* and `if`, the de-duplication key, the platform default `shell`, `CLAUDE_CODE_SHELL_PREFIX`, managed hooks in their own
|
|
538
|
+
* pass, matcher scope, node's non-executing modes — so any other shape is "not confirmed" (WARN), never a PASS.
|
|
539
|
+
*/
|
|
540
|
+
const CANONICAL_GATE = /^node "[^"]*[/\\]dist[/\\]holmes[/\\]hooks[/\\]pre-tool-use\.js"(?: --specs "[^"]*")?$/;
|
|
541
|
+
// Round 40: inside the double quotes the shell still reads `$`, a backtick and a backslash before one of `$`, a backtick,
|
|
542
|
+
// `"`, `\` or a newline — a path holding them is not run as written (an install under `pkg$x` ran `pkg` — measured).
|
|
543
|
+
const SHELL_SPECIAL_IN_QUOTES = /[$`]|\\[$`"\\\n]/;
|
|
544
|
+
/**
|
|
545
|
+
* @implements A-SPEC-251.2 (round 42) — a script path that does not depend on the directory the harness runs its hook in:
|
|
546
|
+
* POSIX `/…`, Windows `X:\…` or UNC. Claude runs a command hook in the session's current directory, so a relative gate script
|
|
547
|
+
* failed with "Cannot find module" (exit 1, non-blocking) after one `cd src` while doctor read PASS (measured).
|
|
548
|
+
*/
|
|
549
|
+
function isAbsoluteScript(p) {
|
|
550
|
+
return /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(p);
|
|
551
|
+
}
|
|
552
|
+
/** Matchers under which the gate sees every tool (Claude reads an absent, empty or `*` matcher as all; `.*` is init's). */
|
|
553
|
+
const ALL_TOOLS = new Set(['', '*', '.*']);
|
|
554
|
+
/** A hook entry that names Holmes's gate in any shape (command text or exec-form `args`). */
|
|
555
|
+
const namesGate = (h) => [h.command, ...(Array.isArray(h.args) ? h.args : [])]
|
|
556
|
+
.some((x) => typeof x === 'string' && /dist[/\\]holmes[/\\]hooks[/\\]pre-tool-use\.js|\bholmes-pre-tool-use\b/.test(x));
|
|
557
|
+
/**
|
|
558
|
+
* The Holmes gate entries of a file's loadable PreToolUse groups (after Claude's cleaning): the canonical entry, one Claude
|
|
559
|
+
* does not wait for (`async`/`asyncRewake` — backgrounded; PreToolUse is never forced synchronous), one that runs only under
|
|
560
|
+
* a non-empty `if`, or any other shape.
|
|
561
|
+
*
|
|
562
|
+
* @implements A-SPEC-251.2 (round 37) — an async or `if` gate read PASS and "enforced" (measured).
|
|
563
|
+
*/
|
|
564
|
+
function gateEntries(v, file, managed) {
|
|
565
|
+
const out = [];
|
|
566
|
+
const hooks = asClaudeCleans(v).hooks;
|
|
567
|
+
if (!isObject(hooks) || !Array.isArray(hooks.PreToolUse))
|
|
568
|
+
return out;
|
|
569
|
+
for (const g of hooks.PreToolUse) {
|
|
570
|
+
if (!isObject(g) || !Array.isArray(g.hooks) || !(g.matcher === undefined || typeof g.matcher === 'string'))
|
|
571
|
+
continue;
|
|
572
|
+
for (const h of g.hooks) {
|
|
573
|
+
if (hookEntryProblem(h) !== null || !isObject(h) || !namesGate(h))
|
|
574
|
+
continue;
|
|
575
|
+
const keys = Object.keys(h);
|
|
576
|
+
// Round 40: under a matcher that lets every tool through, and with nothing the shell rewrites inside the quotes.
|
|
577
|
+
const canonical = h.type === 'command' && typeof h.command === 'string' && CANONICAL_GATE.test(h.command)
|
|
578
|
+
&& !SHELL_SPECIAL_IN_QUOTES.test(h.command) && keys.every((k) => k === 'type' || k === 'command')
|
|
579
|
+
&& ALL_TOOLS.has(typeof g.matcher === 'string' ? g.matcher : '')
|
|
580
|
+
&& isAbsoluteScript(/^node "([^"]*)"/.exec(h.command)?.[1] ?? '');
|
|
581
|
+
const kind = canonical ? 'canonical' : h.async === true || h.asyncRewake === true ? 'background'
|
|
582
|
+
: typeof h.if === 'string' && h.if !== '' ? 'conditional' : 'other';
|
|
583
|
+
out.push({ kind, file, managed, ...(canonical ? { script: /^node "([^"]*)"/.exec(h.command)?.[1] } : {}) });
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
return out;
|
|
587
|
+
}
|
|
588
|
+
/** Whether a `hooks` value carries a Holmes hook command, in any shape (round 34: a list of matchers read WARN). */
|
|
589
|
+
function holdsHolmes(v, depth = 0) {
|
|
590
|
+
if (depth > 8 || v === null || typeof v !== 'object')
|
|
591
|
+
return false;
|
|
592
|
+
if (Array.isArray(v))
|
|
593
|
+
return v.some((x) => holdsHolmes(x, depth + 1));
|
|
594
|
+
const c = v.command;
|
|
595
|
+
if (typeof c === 'string' && /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js|\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(c))
|
|
596
|
+
return true;
|
|
597
|
+
return Object.values(v).some((x) => holdsHolmes(x, depth + 1));
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* @implements A-SPEC-251.2 (round 40) — a settings `env` that changes how Claude runs the gate's command leaves the gate
|
|
601
|
+
* unconfirmed (`NODE_OPTIONS=--require ./x.js` ran `x.js` and exited 0, a `PATH` without Homebrew exited 127,
|
|
602
|
+
* `CLAUDE_CODE_SHELL_PREFIX: true` ran `true` — each with doctor PASS, measured).
|
|
603
|
+
* @implements A-SPEC-251.2 (round 41) — judged by a list of HARMLESS keys, not of harmful ones: round 40's list missed
|
|
604
|
+
* `SHELLOPTS=noexec` (the gate was read and never run — exit 0), `BASH_FUNC_node%%` and an empty `PATH` (measured). Harmless:
|
|
605
|
+
* Claude's own settings for the model, authentication, time limits, telemetry and output limits (named one by one — several
|
|
606
|
+
* `CLAUDE_*` keys choose the shell or the settings Claude reads), display-only keys and proxies. Any other key, whatever its
|
|
607
|
+
* value, is not confirmed; an empty `CLAUDE_CODE_SHELL_PREFIX` is no prefix. Compared case-insensitively on Windows.
|
|
608
|
+
*/
|
|
609
|
+
const HARMLESS_ENV = new RegExp('^(?:' + [
|
|
610
|
+
'ANTHROPIC_(?:API_KEY|AUTH_TOKEN|CUSTOM_HEADERS|MODEL|SMALL_FAST_MODEL(?:_AWS_REGION)?|DEFAULT_(?:HAIKU|SONNET|OPUS)_MODEL|BASE_URL|BEDROCK_BASE_URL|VERTEX_BASE_URL|VERTEX_PROJECT_ID)',
|
|
611
|
+
'AWS_(?:BEARER_TOKEN_BEDROCK|REGION|PROFILE)', 'VERTEX_REGION_[A-Z0-9_]+', 'CLOUD_ML_REGION',
|
|
612
|
+
'BASH_(?:DEFAULT_TIMEOUT_MS|MAX_TIMEOUT_MS|MAX_OUTPUT_LENGTH)',
|
|
613
|
+
'CLAUDE_CODE_(?:API_KEY_HELPER_TTL_MS|AUTO_CONNECT_IDE|DISABLE_NONESSENTIAL_TRAFFIC|DISABLE_TERMINAL_TITLE|ENABLE_TELEMETRY|IDE_SKIP_AUTO_INSTALL|MAX_OUTPUT_TOKENS|SKIP_BEDROCK_AUTH|SKIP_VERTEX_AUTH|SUBAGENT_MODEL|USE_BEDROCK|USE_VERTEX|EFFORT_LEVEL)',
|
|
614
|
+
'DISABLE_(?:AUTOUPDATER|BUG_COMMAND|COST_WARNINGS|ERROR_REPORTING|NON_ESSENTIAL_MODEL_CALLS|TELEMETRY|PROMPT_CACHING(?:_[A-Z]+)?)',
|
|
615
|
+
'MAX_THINKING_TOKENS', 'MAX_MCP_OUTPUT_TOKENS', 'MCP_TIMEOUT', 'MCP_TOOL_TIMEOUT', 'USE_BUILTIN_RIPGREP', 'OTEL_[A-Z0-9_]+',
|
|
616
|
+
// Round 42: Claude's own everyday keys (all in the 2.1.281 binary; round 41 made them WARN — regression). `TZ` left the list:
|
|
617
|
+
// `TZ=":/path/fifo"` stalled the gate (node reads that file; Claude cancels a command hook after 600 s, non-blocking).
|
|
618
|
+
'CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR', 'CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY', 'ENABLE_TOOL_SEARCH', 'API_TIMEOUT_MS',
|
|
619
|
+
'AWS_(?:ACCESS_KEY_ID|SECRET_ACCESS_KEY|SESSION_TOKEN)', 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS', 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE',
|
|
620
|
+
'CLAUDE_CODE_USE_FOUNDRY',
|
|
621
|
+
'NO_COLOR', 'FORCE_COLOR', 'COLUMNS', 'LINES', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
|
|
622
|
+
].join('|') + ')$');
|
|
623
|
+
/**
|
|
624
|
+
* @implements A-SPEC-251.2 (round 43) — a string from a file, safe to print: control characters are escaped (an `env` key holding
|
|
625
|
+
* ESC and BEL retitled the terminal and cleared the screen through doctor and init — measured).
|
|
626
|
+
*/
|
|
627
|
+
function printable(s) {
|
|
628
|
+
return s.replace(/[\u0000-\u001f\u007f-\u009f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
629
|
+
}
|
|
630
|
+
/** Round 42: at most eight names, each clipped — one 70,000-character key cut `doctor --json` at 64 KiB (measured). */
|
|
631
|
+
function namedKeys(keys, clip = 64) {
|
|
632
|
+
const shown = keys.slice(0, 8).map((k) => printable(k.length > clip ? `${k.slice(0, clip)}…` : k)).join(', ');
|
|
633
|
+
return keys.length > 8 ? `${shown} and ${keys.length - 8} more` : shown;
|
|
634
|
+
}
|
|
635
|
+
function execEnvKeys(e, platform = process.platform) {
|
|
636
|
+
if (!isObject(e))
|
|
637
|
+
return [];
|
|
638
|
+
return Object.entries(e)
|
|
639
|
+
.filter(([k, v]) => {
|
|
640
|
+
const key = platform === 'win32' ? k.toUpperCase() : k;
|
|
641
|
+
// Claude applies strings, numbers and booleans (as strings); anything else it drops.
|
|
642
|
+
if (!(typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'))
|
|
643
|
+
return false;
|
|
644
|
+
if (key === 'CLAUDE_CODE_SHELL_PREFIX' && v === '')
|
|
645
|
+
return false;
|
|
646
|
+
return !HARMLESS_ENV.test(key);
|
|
647
|
+
})
|
|
648
|
+
.map(([k]) => k);
|
|
649
|
+
}
|
|
650
|
+
/**
|
|
651
|
+
* Claude's global config, whose `env` Claude applies at start.
|
|
652
|
+
*
|
|
653
|
+
* @implements A-SPEC-251.2 (round 42) — the ONE file Claude 2.1.281 reads (`Tt()`): `<config home>/.config.json` when it exists
|
|
654
|
+
* (the config home is `$CLAUDE_CONFIG_DIR`, else `~/.claude`), else `.claude.json` — `.claude-custom-oauth.json` under
|
|
655
|
+
* `$CLAUDE_CODE_CUSTOM_OAUTH_URL` — in `$CLAUDE_CONFIG_DIR`, else the home directory. Round 41 looked for `.config.json` in the
|
|
656
|
+
* home directory and read both: `~/.claude/.config.json` with `SHELLOPTS=noexec` read PASS (the gate never ran — measured).
|
|
657
|
+
* Read as Claude reads it: a leading BOM is dropped, an empty file has no `env`, a dangling link is no file; a file that is
|
|
658
|
+
* not a regular file of at most 64 MiB, or does not parse, is unreadable. Opened without blocking.
|
|
659
|
+
*/
|
|
660
|
+
function globalConfigEnvs(env) {
|
|
661
|
+
// Round 43: from the raw value, as Claude computes it — the legacy file from `(raw ?? ~/.claude).normalize("NFC")`, the other
|
|
662
|
+
// from `raw || home`; an empty or relative value makes either depend on the session's directory (an empty CLAUDE_CONFIG_DIR
|
|
663
|
+
// read `~/.claude/.config.json` here while Claude read `~/.claude.json` — measured regression).
|
|
664
|
+
const raw = 'rawConfigDir' in env ? env.rawConfigDir : env.claudeConfigDir;
|
|
665
|
+
const legacyDir = (raw ?? path.join(env.home, '.claude')).normalize('NFC');
|
|
666
|
+
const fallbackDir = raw || env.home;
|
|
667
|
+
if (!path.isAbsolute(legacyDir) || !path.isAbsolute(fallbackDir)) {
|
|
668
|
+
return [{ file: `CLAUDE_CONFIG_DIR (${raw === '' ? 'empty' : printable(String(raw))})`, unreadable: true,
|
|
669
|
+
why: "is not an absolute path, so the global config Claude reads depends on the session's directory" }];
|
|
670
|
+
}
|
|
671
|
+
const legacy = path.join(legacyDir, '.config.json');
|
|
672
|
+
let legacyExists = false;
|
|
673
|
+
try {
|
|
674
|
+
legacyExists = fs.existsSync(legacy);
|
|
675
|
+
}
|
|
676
|
+
catch {
|
|
677
|
+
legacyExists = false;
|
|
678
|
+
}
|
|
679
|
+
const file = legacyExists ? legacy : path.join(fallbackDir, `.claude${env.customOauth === true ? '-custom-oauth' : ''}.json`);
|
|
680
|
+
let fd;
|
|
681
|
+
try {
|
|
682
|
+
fd = fs.openSync(file, fs.constants.O_RDONLY | (typeof fs.constants.O_NONBLOCK === 'number' ? fs.constants.O_NONBLOCK : 0));
|
|
683
|
+
}
|
|
684
|
+
catch (e) {
|
|
685
|
+
const code = e.code;
|
|
686
|
+
return code === 'ENOENT' || code === 'ENOTDIR' ? [] : [{ file, unreadable: true }];
|
|
687
|
+
}
|
|
688
|
+
try {
|
|
689
|
+
const fst = fs.fstatSync(fd);
|
|
690
|
+
if (!fst.isFile() || fst.size > 64 * 1024 * 1024)
|
|
691
|
+
return [{ file, unreadable: true }];
|
|
692
|
+
const text = fs.readFileSync(fd, 'utf8').replace(/^\uFEFF/, '');
|
|
693
|
+
if (text.trim() === '')
|
|
694
|
+
return [{ file, env: undefined }];
|
|
695
|
+
const v = JSON.parse(text);
|
|
696
|
+
return [{ file, env: isObject(v) ? v.env : undefined }];
|
|
697
|
+
}
|
|
698
|
+
catch {
|
|
699
|
+
return [{ file, unreadable: true }];
|
|
700
|
+
}
|
|
701
|
+
finally {
|
|
702
|
+
try {
|
|
703
|
+
fs.closeSync(fd);
|
|
704
|
+
}
|
|
705
|
+
catch { /* closed */ }
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
/**
|
|
709
|
+
* @implements A-SPEC-251.2 (round 50) — `planned`: settings files by path with the content init is about to write, judged in
|
|
710
|
+
* place of what is on disk (a first init said "enforced" over an entry doctor and the next init called not confirmed).
|
|
711
|
+
*/
|
|
712
|
+
function claudeSwitches(target, env = claudeSwitchEnv(), planned) {
|
|
713
|
+
const managed = [];
|
|
714
|
+
for (const dir of env.managedDirs) {
|
|
715
|
+
managed.push(path.join(dir, 'managed-settings.json'));
|
|
716
|
+
try {
|
|
717
|
+
// Round 31: as Claude reads them — a `.json` ending (case-sensitive), not a dotfile.
|
|
718
|
+
for (const f of fs.readdirSync(path.join(dir, 'managed-settings.d')).filter((n) => n.endsWith('.json') && !n.startsWith('.')).sort()) {
|
|
719
|
+
// Round 32: files and links only, as Claude reads them (a directory `x.json` read as "unreadable" — measured).
|
|
720
|
+
const at = path.join(dir, 'managed-settings.d', f);
|
|
721
|
+
try {
|
|
722
|
+
const st = fs.lstatSync(at);
|
|
723
|
+
if (st.isFile() || st.isSymbolicLink())
|
|
724
|
+
managed.push(at);
|
|
725
|
+
}
|
|
726
|
+
catch { /* gone */ }
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
catch { /* no drop-in folder */ }
|
|
730
|
+
}
|
|
731
|
+
const sources = [
|
|
732
|
+
...managed.map((file) => ({ file, managed: true })),
|
|
733
|
+
...(() => { const u = claudeUserSettingsPath(env); return u === null ? [] : [{ file: u, managed: false }]; })(),
|
|
734
|
+
{ file: path.join(target, '.claude', 'settings.json'), managed: false },
|
|
735
|
+
{ file: path.join(target, '.claude', 'settings.local.json'), managed: false },
|
|
736
|
+
];
|
|
737
|
+
// Round 35: and the canonical git root's local settings, as Claude reads them.
|
|
738
|
+
const canonical = canonicalLocalSettingsPath(target, env.home);
|
|
739
|
+
if (canonical !== null)
|
|
740
|
+
sources.push({ file: canonical, managed: false });
|
|
741
|
+
const out = { hooksOff: [], toolsOff: [], unreadable: [], notApplied: [], unconfirmed: [], spared: [], gateScripts: [], noGate: [] };
|
|
742
|
+
// Round 40: switches that turn every hook off (a managed `disableAllHooks`) and those that spare managed hooks.
|
|
743
|
+
const offAll = [];
|
|
744
|
+
const offNonManaged = [];
|
|
745
|
+
const holmesFiles = [];
|
|
746
|
+
// Round 35: a dropped file holding Holmes's hooks is FAIL only when no applied file holds them (they still run from there).
|
|
747
|
+
const droppedFiles = [];
|
|
748
|
+
let appliedHolmes = false;
|
|
749
|
+
// Round 37: gates Claude does not make block; FAIL when no applied gate blocks.
|
|
750
|
+
// Round 39: every applied file's gate entries, and any shell prefix Claude runs hooks through (settings `env`, then the
|
|
751
|
+
// process environment).
|
|
752
|
+
const gates = [];
|
|
753
|
+
const envRisks = [];
|
|
754
|
+
if (claudeUserSettingsPath(env) === null)
|
|
755
|
+
envRisks.push(`CLAUDE_CONFIG_DIR (${env.rawConfigDir === '' ? 'empty' : printable(String(env.rawConfigDir))}) is not an absolute path, so the user settings Claude reads depend on the session's directory and are not read`);
|
|
756
|
+
const underIt = ": Claude runs the gate's command under it";
|
|
757
|
+
if (typeof process.env.CLAUDE_CODE_SHELL_PREFIX === 'string' && process.env.CLAUDE_CODE_SHELL_PREFIX !== '')
|
|
758
|
+
envRisks.push(`the environment (CLAUDE_CODE_SHELL_PREFIX)${underIt}`);
|
|
759
|
+
for (const g of globalConfigEnvs(env)) {
|
|
760
|
+
if ('unreadable' in g) {
|
|
761
|
+
envRisks.push(`${g.file} ${g.why ?? 'could not be read'}, so the environment Claude runs the gate's command under is unknown`);
|
|
762
|
+
continue;
|
|
763
|
+
}
|
|
764
|
+
const keys = execEnvKeys(g.env);
|
|
765
|
+
if (keys.length > 0)
|
|
766
|
+
envRisks.push(`${g.file} (env ${namedKeys(keys)})${underIt}`);
|
|
767
|
+
}
|
|
768
|
+
// Round 33: Holmes's own launch, for the command entries of the MCP lists.
|
|
769
|
+
const holmesCmd = (() => {
|
|
770
|
+
const r = readSettings(path.join(target, '.mcp.json'));
|
|
771
|
+
if (r === null || 'unreadable' in r)
|
|
772
|
+
return null;
|
|
773
|
+
const e = r.value.mcpServers?.['holmes-kit'];
|
|
774
|
+
if (e === undefined || typeof e.command !== 'string' || !Array.isArray(e.args) || !e.args.every((a) => typeof a === 'string'))
|
|
775
|
+
return null;
|
|
776
|
+
return [e.command, ...e.args];
|
|
777
|
+
})();
|
|
778
|
+
const sameCommand = (c) => holmesCmd !== null && Array.isArray(c) && c.length === holmesCmd.length && c.every((x, i) => x === holmesCmd[i]);
|
|
779
|
+
const validEntry = (e) => {
|
|
780
|
+
if (e === null || typeof e !== 'object' || Array.isArray(e))
|
|
781
|
+
return false;
|
|
782
|
+
const keys = ['serverName', 'serverCommand', 'serverUrl'].filter((k) => e[k] !== undefined);
|
|
783
|
+
if (keys.length !== 1)
|
|
784
|
+
return false;
|
|
785
|
+
const x = e;
|
|
786
|
+
if (keys[0] === 'serverName')
|
|
787
|
+
return typeof x.serverName === 'string' && /^[A-Za-z0-9_-]+$/.test(x.serverName);
|
|
788
|
+
if (keys[0] === 'serverCommand')
|
|
789
|
+
return Array.isArray(x.serverCommand) && x.serverCommand.length > 0 && x.serverCommand.every((c) => typeof c === 'string');
|
|
790
|
+
return typeof x.serverUrl === 'string';
|
|
791
|
+
};
|
|
792
|
+
const allowLists = [];
|
|
793
|
+
let managedOnly = false;
|
|
794
|
+
for (const s of sources) {
|
|
795
|
+
const r = readSettings(s.file, planned?.get(s.file));
|
|
796
|
+
if (r === null)
|
|
797
|
+
continue;
|
|
798
|
+
if ('unreadable' in r) {
|
|
799
|
+
out.unreadable.push(`${r.file} (${r.unreadable})`);
|
|
800
|
+
continue;
|
|
801
|
+
}
|
|
802
|
+
const v = r.value;
|
|
803
|
+
// Round 35: a managed file is salvaged by Claude (`co`), never dropped for a hook entry; a file over 2 MiB is not read.
|
|
804
|
+
// Round 36: a managed file over 2 MiB is not read either.
|
|
805
|
+
const dropped = r.tooLarge ? `larger than ${exports.CLAUDE_SETTINGS_MAX_BYTES / (1024 * 1024)} MiB, which Claude does not read` : s.managed ? null : claudeDropsFile(v);
|
|
806
|
+
if (dropped !== null) {
|
|
807
|
+
// Round 35: none of its switches applies either (2.1.281 reads `disableAllHooks` from validated per-source settings).
|
|
808
|
+
droppedFiles.push({ line: `${r.file} (${dropped}: Claude applies nothing in this file)`, holmes: holdsHolmes(v.hooks) });
|
|
809
|
+
continue;
|
|
810
|
+
}
|
|
811
|
+
// Round 36: only this install's gate in a PreToolUse group Claude loads (a `holmes-kit status` SessionStart hook hid a
|
|
812
|
+
// dropped gate file — measured).
|
|
813
|
+
gates.push(...gateEntries(v, r.file, s.managed));
|
|
814
|
+
const risky = execEnvKeys(v.env);
|
|
815
|
+
if (risky.length > 0)
|
|
816
|
+
envRisks.push(`${r.file} (env ${namedKeys(risky)})${underIt}`);
|
|
817
|
+
if (holdsHolmes(v.hooks))
|
|
818
|
+
holmesFiles.push(r.file);
|
|
819
|
+
// Round 40: a non-managed `disableAllHooks` spares managed hooks (2.1.281: "they run even under a non-managed disableAllHooks").
|
|
820
|
+
if (v.disableAllHooks === true)
|
|
821
|
+
(s.managed ? offAll : offNonManaged).push(`${r.file} (disableAllHooks)`);
|
|
822
|
+
// Round 47: a managed value that is not true or false — 2.1.283 reads "true" as true and any other invalid value as its
|
|
823
|
+
// restrictive value; 2.1.281 has no such rule (both binaries read).
|
|
824
|
+
else if (s.managed && v.disableAllHooks !== undefined && typeof v.disableAllHooks !== 'boolean')
|
|
825
|
+
out.unconfirmed.push(`${r.file} (disableAllHooks is not true or false — Claude versions read it differently)`);
|
|
826
|
+
// Round 31: Claude treats a present non-boolean `allowManagedHooksOnly` as true, and a managed
|
|
827
|
+
// `strictPluginOnlyCustomization` (true, or an array holding "hooks") also leaves only managed hooks (read from 2.1.281).
|
|
828
|
+
const only = v.allowManagedHooksOnly;
|
|
829
|
+
// @implements A-SPEC-251.2 (round 46) — values Claude versions read differently are not confirmed: 2.1.281 read every present
|
|
830
|
+
// non-boolean `allowManagedHooksOnly` as true and ignored an invalid `strictPluginOnlyCustomization`; 2.1.283 reads `"false"`
|
|
831
|
+
// and `null` in the former as false and absent, any other invalid value of either as its restrictive value (true — both
|
|
832
|
+
// binaries read). `"true"`, `1` and the like are true in both.
|
|
833
|
+
const drift = (key) => { out.unconfirmed.push(`${r.file} (${key} is not true or false — Claude versions read it differently)`); };
|
|
834
|
+
// Round 47: exactly `"false"` — 2.1.283 coerces no other spelling, so `"False"` is true in both versions.
|
|
835
|
+
const versionsDiffer = only === null || only === 'false';
|
|
836
|
+
if (s.managed && versionsDiffer)
|
|
837
|
+
drift('allowManagedHooksOnly');
|
|
838
|
+
else if (s.managed && (only === true || (only !== undefined && typeof only !== 'boolean')))
|
|
839
|
+
offNonManaged.push(`${r.file} (allowManagedHooksOnly)`);
|
|
840
|
+
const strict = v.strictPluginOnlyCustomization;
|
|
841
|
+
const strictList = Array.isArray(strict) && strict.every((e) => typeof e === 'string');
|
|
842
|
+
if (s.managed && (strict === true || (strictList && strict.includes('hooks'))))
|
|
843
|
+
offNonManaged.push(`${r.file} (strictPluginOnlyCustomization)`);
|
|
844
|
+
else if (s.managed && strict !== undefined && typeof strict !== 'boolean' && !strictList)
|
|
845
|
+
drift('strictPluginOnlyCustomization');
|
|
846
|
+
if (Array.isArray(v.deniedMcpServers) && v.deniedMcpServers.some((e) => validEntry(e) && (e.serverName === 'holmes-kit' || sameCommand(e.serverCommand))))
|
|
847
|
+
out.toolsOff.push(`${r.file} (deniedMcpServers)`);
|
|
848
|
+
// Round 34: Claude drops a non-array list from a user or project file ("This field was ignored"); a managed file keeps
|
|
849
|
+
// it and enforces an empty allow list (round 32).
|
|
850
|
+
if (v.allowedMcpServers !== undefined && (s.managed || Array.isArray(v.allowedMcpServers))) {
|
|
851
|
+
const entries = Array.isArray(v.allowedMcpServers) ? v.allowedMcpServers.filter(validEntry) : [];
|
|
852
|
+
allowLists.push({ file: r.file, managed: s.managed, entries });
|
|
853
|
+
}
|
|
854
|
+
const mOnly = v.allowManagedMcpServersOnly;
|
|
855
|
+
if (s.managed && (mOnly === true || (mOnly !== undefined && typeof mOnly !== 'boolean')))
|
|
856
|
+
managedOnly = true;
|
|
857
|
+
// Round 32: a managed `strictPluginOnlyCustomization` holding "mcp" keeps project `.mcp.json` servers out.
|
|
858
|
+
if (s.managed && Array.isArray(strict) && strict.includes('mcp'))
|
|
859
|
+
out.toolsOff.push(`${r.file} (strictPluginOnlyCustomization: mcp)`);
|
|
860
|
+
const rejected = Array.isArray(v.disabledMcpjsonServers) && v.disabledMcpjsonServers.some((n) => n === 'holmes-kit');
|
|
861
|
+
const deny = v.permissions?.deny;
|
|
862
|
+
const denied = Array.isArray(deny) && deny.some((d) => typeof d === 'string' && /^mcp__holmes-kit(?:__.*)?$/.test(d.trim()));
|
|
863
|
+
if (rejected)
|
|
864
|
+
out.toolsOff.push(`${r.file} (disabledMcpjsonServers)`);
|
|
865
|
+
if (denied)
|
|
866
|
+
out.toolsOff.push(`${r.file} (permissions.deny)`);
|
|
867
|
+
}
|
|
868
|
+
// Round 39 (owner decision): only init's canonical entry is confirmed; a gate of another shape beside it, or a shell prefix,
|
|
869
|
+
// leaves it unconfirmed (WARN). Without it, gates that Claude does not wait for (async, a non-empty `if`) are FAIL as in
|
|
870
|
+
// round 37, and any other shape is unconfirmed.
|
|
871
|
+
// Round 40: switches that spare managed hooks leave a managed canonical gate running (2.1.281 runs managed hooks in their
|
|
872
|
+
// own pass — a false FAIL, measured); every other hook of the target is still off (WARN).
|
|
873
|
+
const managedGate = gates.some((e) => e.kind === 'canonical' && e.managed);
|
|
874
|
+
if (managedGate && offAll.length === 0)
|
|
875
|
+
out.spared.push(...offNonManaged);
|
|
876
|
+
else
|
|
877
|
+
out.hooksOff.push(...offAll, ...offNonManaged);
|
|
878
|
+
const live = managedGate && offAll.length === 0 && offNonManaged.length > 0 ? gates.filter((e) => e.managed) : gates;
|
|
879
|
+
const confirmed = live.some((e) => e.kind === 'canonical');
|
|
880
|
+
const other = live.filter((e) => e.kind === 'other');
|
|
881
|
+
const nonBlocking = live.filter((e) => e.kind === 'background' || e.kind === 'conditional');
|
|
882
|
+
appliedHolmes = confirmed || other.length > 0;
|
|
883
|
+
out.gateScripts.push(...new Set(live.filter((e) => e.kind === 'canonical').map((e) => e.script ?? '')));
|
|
884
|
+
const said = (e) => e.kind === 'background'
|
|
885
|
+
? `${e.file} (a Holmes gate entry that runs in the background — async — so Claude does not wait for it)`
|
|
886
|
+
: e.kind === 'conditional' ? `${e.file} (a Holmes gate entry that runs only when its \`if\` condition matches)`
|
|
887
|
+
: `${e.file} (a Holmes gate entry of another shape than the one init writes)`;
|
|
888
|
+
for (const d of droppedFiles)
|
|
889
|
+
(d.holmes && !appliedHolmes ? out.hooksOff : out.notApplied).push(d.line);
|
|
890
|
+
if (!appliedHolmes)
|
|
891
|
+
out.hooksOff.push(...[...new Set(nonBlocking.map(said))]);
|
|
892
|
+
else
|
|
893
|
+
out.unconfirmed.push(...[...new Set([...other, ...(confirmed ? nonBlocking : [])].map(said))]);
|
|
894
|
+
// Round 40: Holmes's hooks wired with no gate entry at all — Claude runs no gate (all three checks read PASS; the Codex and
|
|
895
|
+
// Antigravity checks FAIL the same shape).
|
|
896
|
+
if (gates.length === 0 && holmesFiles.length > 0)
|
|
897
|
+
out.noGate.push(...holmesFiles);
|
|
898
|
+
// Round 40: reported whether or not a gate is wired yet (init judges before its own write).
|
|
899
|
+
out.unconfirmed.push(...envRisks);
|
|
900
|
+
const counted = managedOnly ? allowLists.filter((l) => l.managed) : allowLists;
|
|
901
|
+
const entries = counted.flatMap((l) => l.entries);
|
|
902
|
+
const admits = entries.some((e) => e.serverCommand !== undefined)
|
|
903
|
+
? entries.some((e) => sameCommand(e.serverCommand))
|
|
904
|
+
: entries.some((e) => e.serverName === 'holmes-kit');
|
|
905
|
+
if (counted.length > 0 && !admits)
|
|
906
|
+
out.toolsOff.push(`${counted.map((l) => l.file).join(', ')} (allowedMcpServers${managedOnly ? ', managed only' : ''})`);
|
|
907
|
+
// Round 32: a managed `managed-mcp.json` takes exclusive control of MCP servers.
|
|
908
|
+
for (const dir of env.managedDirs) {
|
|
909
|
+
const r = readSettings(path.join(dir, 'managed-mcp.json'));
|
|
910
|
+
if (r === null)
|
|
911
|
+
continue;
|
|
912
|
+
if ('unreadable' in r) {
|
|
913
|
+
out.unreadable.push(`${r.file} (${r.unreadable})`);
|
|
914
|
+
continue;
|
|
915
|
+
}
|
|
916
|
+
const servers = r.value.mcpServers;
|
|
917
|
+
if (servers === null || typeof servers !== 'object' || !Object.prototype.hasOwnProperty.call(servers, 'holmes-kit'))
|
|
918
|
+
out.toolsOff.push(`${r.file} (exclusive control of MCP servers)`);
|
|
919
|
+
}
|
|
920
|
+
return out;
|
|
921
|
+
}
|
|
922
|
+
const NOT_READ = 'MDM, server-managed policy, a managed policyHelper, --settings, --mcp-config, safe mode, --bare, Cowork-mode settings, a host project-config root, the Windows managed folder seen from WSL and an empty CLAUDE_CONFIG_DIR are not read, nor is the rest of Claude\'s settings schema, which can also make it drop a file';
|
|
923
|
+
/** Round 43: distinct gate scripts judged against an install per run (1,000 committed entries held doctor for 106 s). */
|
|
924
|
+
const GATE_SCRIPTS_JUDGED = 16;
|
|
925
|
+
function claudeHookSwitchesCheck(target, env = claudeSwitchEnv(), owner) {
|
|
926
|
+
const name = 'claude hook switches';
|
|
927
|
+
const s = claudeSwitches(target, env);
|
|
928
|
+
const judged = s.gateScripts.slice(0, GATE_SCRIPTS_JUDGED);
|
|
929
|
+
const overflow = s.gateScripts.length > GATE_SCRIPTS_JUDGED
|
|
930
|
+
? [`${s.gateScripts.length} distinct Holmes gate scripts, of which only the first ${GATE_SCRIPTS_JUDGED} were judged`] : [];
|
|
931
|
+
// @implements A-SPEC-251.2 (round 40) — Holmes's other hooks with no gate, or a gate whose every script is missing: Claude
|
|
932
|
+
// runs no gate (both read PASS — measured; the Codex and Antigravity checks FAIL the same shapes).
|
|
933
|
+
const owners = owner === undefined ? [] : judged.map(owner);
|
|
934
|
+
const missing = owners.length > 0 && overflow.length === 0 && owners.every((o) => o === 'missing');
|
|
935
|
+
// Round 44: a script is named up to 512 characters (at 64 the part that says which install was cut — measured).
|
|
936
|
+
const scripts = (want) => namedKeys(want === undefined ? judged : judged.filter((_, i) => owners[i] === want), 512);
|
|
937
|
+
if (s.hooksOff.length > 0 || s.noGate.length > 0 || missing) {
|
|
938
|
+
const why = s.hooksOff.length > 0 ? `switched off by ${s.hooksOff.join(', ')}`
|
|
939
|
+
: s.noGate.length > 0 ? `${s.noGate.join(', ')} wire Holmes's hooks but no Holmes PreToolUse gate`
|
|
940
|
+
: `the Holmes gate entry runs a missing script (${scripts()})`;
|
|
941
|
+
return { name, level: 'FAIL', detail: `Claude runs no Holmes gate here — ${why}; the gate is not enforced`,
|
|
942
|
+
fix: s.hooksOff.length > 0
|
|
943
|
+
? 'Fix or remove the named hook entry (Claude applies nothing in a file holding a PreToolUse/PermissionRequest hook it cannot load), and remove disableAllHooks (and, in managed settings, allowManagedHooksOnly) from the named file, or ask its owner to.'
|
|
944
|
+
: 'Run holmes-kit init --target <dir> --agent claude --force from the install you mean to use.' };
|
|
945
|
+
}
|
|
946
|
+
// Round 42: a script on a path doctor does not look up (network) is unknown, not missing — if it is there Claude runs it.
|
|
947
|
+
const foreign = owners.length > 0 && !owners.includes('this')
|
|
948
|
+
? [owners.includes('other') ? `the Holmes gate entry runs another install's script (${scripts('other')})`
|
|
949
|
+
: owners.includes('unknown') ? `the Holmes gate entry runs a script on a path doctor does not look up (${scripts('unknown')})`
|
|
950
|
+
: `the Holmes gate entry runs a missing script (${scripts('missing')})`] : [];
|
|
951
|
+
const unconfirmed = [...s.unconfirmed, ...foreign, ...overflow];
|
|
952
|
+
if (s.toolsOff.length > 0 || s.unreadable.length > 0 || s.notApplied.length > 0 || unconfirmed.length > 0 || s.spared.length > 0) {
|
|
953
|
+
const parts = [
|
|
954
|
+
...(unconfirmed.length > 0 ? [`whether Claude's gate blocks is not confirmed — ${unconfirmed.join(', ')}`] : []),
|
|
955
|
+
...(s.spared.length > 0 ? [`${s.spared.join(', ')} switch every non-managed hook off; the managed Holmes gate still runs`] : []),
|
|
956
|
+
...(s.notApplied.length > 0 ? [`Claude applies nothing from ${s.notApplied.join(', ')}`] : []),
|
|
957
|
+
...(s.toolsOff.length > 0 ? [`Holmes's MCP tools are rejected or denied by ${s.toolsOff.join(', ')} (the hooks still gate)`] : []),
|
|
958
|
+
...(s.unreadable.length > 0 ? [`could not read ${s.unreadable.join(', ')}, so its switches are unknown`] : []),
|
|
959
|
+
];
|
|
960
|
+
return { name, level: 'WARN', detail: parts.join('; '),
|
|
961
|
+
fix: s.toolsOff.length > 0 ? 'Remove holmes-kit from disabledMcpjsonServers / permissions.deny in the named file.'
|
|
962
|
+
: unconfirmed.length > 0 ? 'Keep only the gate entry holmes-kit init writes (run holmes-kit init --target <dir> --agent claude --force) and remove the named env settings, or confirm by hand that the gate blocks.'
|
|
963
|
+
: s.spared.length > 0 ? 'Remove the named switch if Holmes\'s other hooks (Stop, SessionStart) should run too.'
|
|
964
|
+
: 'Make the named file a readable JSON object.' };
|
|
965
|
+
}
|
|
966
|
+
return { name, level: 'PASS', detail: `no settings file switches Claude's hooks or Holmes's tools off (${NOT_READ})` };
|
|
967
|
+
}
|