@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,802 @@
|
|
|
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.defaultCodexHooksPath = defaultCodexHooksPath;
|
|
37
|
+
exports.holmesKernelScript = holmesKernelScript;
|
|
38
|
+
exports.decodeCodexHooksBytes = decodeCodexHooksBytes;
|
|
39
|
+
exports.codexMatcherCompiles = codexMatcherCompiles;
|
|
40
|
+
exports.holmesCommandsPresent = holmesCommandsPresent;
|
|
41
|
+
exports.mergeCodexUserHooks = mergeCodexUserHooks;
|
|
42
|
+
exports.codexHooksTrustChanges = codexHooksTrustChanges;
|
|
43
|
+
exports.removeCodexUserHooks = removeCodexUserHooks;
|
|
44
|
+
exports.hasHolmesCodexHooks = hasHolmesCodexHooks;
|
|
45
|
+
exports.inspectCodexUserHooks = inspectCodexUserHooks;
|
|
46
|
+
exports.codexKernelScripts = codexKernelScripts;
|
|
47
|
+
// @implements A-SPEC-727
|
|
48
|
+
// codex-cli 0.155 removed plugin hooks (`plugin_hooks: removed`, measured 2026-09-23), so the Holmes
|
|
49
|
+
// gate reaches Codex only through a hooks file Codex loads for every workspace: the user-level
|
|
50
|
+
// `$CODEX_HOME/hooks.json`. Codex runs a non-managed hook only after the user trusts its exact
|
|
51
|
+
// definition (`/hooks`); Holmes never writes that trust — it wires the file and says so.
|
|
52
|
+
const os = __importStar(require("node:os"));
|
|
53
|
+
const path = __importStar(require("node:path"));
|
|
54
|
+
/** `$CODEX_HOME/hooks.json`, else `<home>/.codex/hooks.json`. Injectable for deterministic tests. */
|
|
55
|
+
function defaultCodexHooksPath(env = process.env, home = os.homedir()) {
|
|
56
|
+
return path.join(env.CODEX_HOME || path.join(home, '.codex'), 'hooks.json');
|
|
57
|
+
}
|
|
58
|
+
const KERNELS = ['pre-tool-use.js', 'stop.js'];
|
|
59
|
+
const kernelCommand = (packageRoot, script) => `node "${path.join(packageRoot, 'dist', 'holmes', 'hooks', script)}"`;
|
|
60
|
+
/**
|
|
61
|
+
* The kernel script a command runs, or null. Holmes owns ONLY the exact shape it writes —
|
|
62
|
+
* `node "<abs>/dist/holmes/hooks/(pre-tool-use|stop).js"` — so a user's wrapper that merely
|
|
63
|
+
* contains a kernel path (a `bash -c` chain, extra flags) is never claimed as Holmes's.
|
|
64
|
+
*/
|
|
65
|
+
function holmesKernelScript(command) {
|
|
66
|
+
if (typeof command !== 'string')
|
|
67
|
+
return null;
|
|
68
|
+
const m = /^node(?:\.exe)? "([^"]+)"$/.exec(command.trim());
|
|
69
|
+
if (!m)
|
|
70
|
+
return null;
|
|
71
|
+
const script = m[1];
|
|
72
|
+
const normalized = script.replace(/\\/g, '/');
|
|
73
|
+
if (!path.isAbsolute(script) && !/^[A-Za-z]:\//.test(normalized))
|
|
74
|
+
return null;
|
|
75
|
+
return KERNELS.some((k) => normalized.endsWith(`/dist/holmes/hooks/${k}`)) ? script : null;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* @implements A-SPEC-727 (round 6) — the file's bytes as Codex reads them: strict UTF-8 (serde refuses
|
|
79
|
+
* an invalid byte; a lenient 'utf8' read turned it into U+FFFD and reported the gate wired).
|
|
80
|
+
*/
|
|
81
|
+
function decodeCodexHooksBytes(bytes) {
|
|
82
|
+
// Round 8: `ignoreBOM` keeps a leading BOM in the text — Codex ignores such a file (measured), and a
|
|
83
|
+
// silent strip here hid it (and a second BOM behind it).
|
|
84
|
+
try {
|
|
85
|
+
return { ok: true, text: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) };
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
return { ok: false, reason: 'not valid UTF-8', lossy: bytes.toString('latin1') };
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
|
|
92
|
+
/** Own-property assignment: a user event named `__proto__` is data, not the object's prototype. */
|
|
93
|
+
const put = (o, k, v) => { Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true }); };
|
|
94
|
+
const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
|
|
95
|
+
/**
|
|
96
|
+
* @implements A-SPEC-727 (round 8) — what Codex 0.155.1 knows (live measurement): only these events,
|
|
97
|
+
* group keys and hook keys are deserialized; anything else is skipped, so it is never refused here.
|
|
98
|
+
*/
|
|
99
|
+
const KNOWN_EVENTS = new Set(['PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'SessionStart',
|
|
100
|
+
'SessionEnd', 'UserPromptSubmit', 'SubagentStart', 'SubagentStop', 'Stop', 'Interrupt']);
|
|
101
|
+
const GROUP_KEYS = new Set(['matcher', 'hooks']);
|
|
102
|
+
const HOOK_KEYS = new Set(['type', 'command', 'timeout', 'statusMessage', 'async', 'commandWindows', 'additionalContextLimit', 'server', 'tool', 'prompt', 'model']);
|
|
103
|
+
const UINT_KEYS = new Set(['timeout', 'additionalContextLimit']);
|
|
104
|
+
const HOOK_KEYS_BY_TYPE = {
|
|
105
|
+
command: new Set(['type', 'command', 'timeout', 'statusMessage', 'async', 'commandWindows', 'additionalContextLimit']),
|
|
106
|
+
mcp_tool: new Set(['type', 'server', 'tool', 'timeout', 'statusMessage']),
|
|
107
|
+
prompt: new Set(['type']),
|
|
108
|
+
agent: new Set(['type']),
|
|
109
|
+
};
|
|
110
|
+
const U63 = BigInt(2) ** BigInt(63);
|
|
111
|
+
/**
|
|
112
|
+
* @implements A-SPEC-727 (round 8) — what JSON.parse hides but Codex refuses, checked only where Codex
|
|
113
|
+
* looks: a duplicate KNOWN key, a lone surrogate in a KNOWN string, a fraction/exponent or >2^53 spelling
|
|
114
|
+
* for a KNOWN integer. Values under unknown keys or events are skipped iteratively (no recursion, so no
|
|
115
|
+
* depth limit applies to them — Codex accepts 130-deep nesting there, measured). The text is valid JSON.
|
|
116
|
+
*/
|
|
117
|
+
function knownShapeProblem(text) {
|
|
118
|
+
let i = 0;
|
|
119
|
+
const ws = () => { while (i < text.length && (text[i] === ' ' || text[i] === '\t' || text[i] === '\n' || text[i] === '\r'))
|
|
120
|
+
i++; };
|
|
121
|
+
const readString = () => {
|
|
122
|
+
const start = i;
|
|
123
|
+
i++;
|
|
124
|
+
while (i < text.length && text[i] !== '"') {
|
|
125
|
+
if (text[i] === '\\')
|
|
126
|
+
i++;
|
|
127
|
+
i++;
|
|
128
|
+
}
|
|
129
|
+
i++;
|
|
130
|
+
return JSON.parse(text.slice(start, i));
|
|
131
|
+
};
|
|
132
|
+
const skip = () => {
|
|
133
|
+
ws();
|
|
134
|
+
const c0 = text[i];
|
|
135
|
+
if (c0 !== '"' && c0 !== '{' && c0 !== '[') { // a scalar: consume the whole token
|
|
136
|
+
while (i < text.length && !/[,}\]\s]/.test(text[i]))
|
|
137
|
+
i++;
|
|
138
|
+
return;
|
|
139
|
+
}
|
|
140
|
+
let depth = 0;
|
|
141
|
+
do {
|
|
142
|
+
const c = text[i];
|
|
143
|
+
if (c === '"') {
|
|
144
|
+
readRaw();
|
|
145
|
+
}
|
|
146
|
+
else if (c === '{' || c === '[') {
|
|
147
|
+
depth++;
|
|
148
|
+
i++;
|
|
149
|
+
}
|
|
150
|
+
else if (c === '}' || c === ']') {
|
|
151
|
+
depth--;
|
|
152
|
+
i++;
|
|
153
|
+
}
|
|
154
|
+
else
|
|
155
|
+
i++;
|
|
156
|
+
if (depth > 0)
|
|
157
|
+
ws();
|
|
158
|
+
} while (depth > 0 && i < text.length);
|
|
159
|
+
};
|
|
160
|
+
const readRaw = () => { i++; while (i < text.length && text[i] !== '"') {
|
|
161
|
+
if (text[i] === '\\')
|
|
162
|
+
i++;
|
|
163
|
+
i++;
|
|
164
|
+
} i++; };
|
|
165
|
+
// An object whose known keys get `onKnown`; unknown keys are skipped.
|
|
166
|
+
const object = (known, onKnown, where) => {
|
|
167
|
+
ws();
|
|
168
|
+
if (text[i] !== '{') {
|
|
169
|
+
skip();
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
i++;
|
|
173
|
+
ws();
|
|
174
|
+
const seen = new Set();
|
|
175
|
+
if (text[i] === '}') {
|
|
176
|
+
i++;
|
|
177
|
+
return null;
|
|
178
|
+
}
|
|
179
|
+
for (;;) {
|
|
180
|
+
ws();
|
|
181
|
+
const k = readString();
|
|
182
|
+
ws();
|
|
183
|
+
i++;
|
|
184
|
+
ws(); // ':'
|
|
185
|
+
// @implements A-SPEC-727 (round 9) — keys at every validated level are read as strings by
|
|
186
|
+
// Codex: a lone surrogate in one drops the whole file (measured).
|
|
187
|
+
if (LONE_SURROGATE.test(k))
|
|
188
|
+
return `a key in ${where} holds a lone UTF-16 surrogate escape`;
|
|
189
|
+
if (known(k)) {
|
|
190
|
+
if (seen.has(k))
|
|
191
|
+
return `duplicate key \`${k}\` in ${where}`;
|
|
192
|
+
seen.add(k);
|
|
193
|
+
const p = onKnown(k);
|
|
194
|
+
if (p)
|
|
195
|
+
return p;
|
|
196
|
+
}
|
|
197
|
+
else
|
|
198
|
+
skip();
|
|
199
|
+
ws();
|
|
200
|
+
if (text[i] === ',') {
|
|
201
|
+
i++;
|
|
202
|
+
continue;
|
|
203
|
+
}
|
|
204
|
+
i++;
|
|
205
|
+
return null;
|
|
206
|
+
}
|
|
207
|
+
};
|
|
208
|
+
const array = (each) => {
|
|
209
|
+
ws();
|
|
210
|
+
if (text[i] !== '[') {
|
|
211
|
+
skip();
|
|
212
|
+
return null;
|
|
213
|
+
}
|
|
214
|
+
i++;
|
|
215
|
+
ws();
|
|
216
|
+
if (text[i] === ']') {
|
|
217
|
+
i++;
|
|
218
|
+
return null;
|
|
219
|
+
}
|
|
220
|
+
for (let n = 0;; n++) {
|
|
221
|
+
const p = each(n);
|
|
222
|
+
if (p)
|
|
223
|
+
return p;
|
|
224
|
+
ws();
|
|
225
|
+
if (text[i] === ',') {
|
|
226
|
+
i++;
|
|
227
|
+
continue;
|
|
228
|
+
}
|
|
229
|
+
i++;
|
|
230
|
+
return null;
|
|
231
|
+
}
|
|
232
|
+
};
|
|
233
|
+
const knownString = (where) => {
|
|
234
|
+
ws();
|
|
235
|
+
if (text[i] !== '"') {
|
|
236
|
+
skip();
|
|
237
|
+
return null;
|
|
238
|
+
}
|
|
239
|
+
return LONE_SURROGATE.test(readString()) ? `${where} holds a lone UTF-16 surrogate escape` : null;
|
|
240
|
+
};
|
|
241
|
+
const knownValue = (key, where) => {
|
|
242
|
+
ws();
|
|
243
|
+
if (text[i] === '"')
|
|
244
|
+
return knownString(where);
|
|
245
|
+
if (UINT_KEYS.has(key)) {
|
|
246
|
+
const m = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(i, i + 64));
|
|
247
|
+
if (m) {
|
|
248
|
+
i += m[0].length;
|
|
249
|
+
if (/[.eE]/.test(m[0]))
|
|
250
|
+
return `${where} \`${m[0]}\` is not an integer spelling`;
|
|
251
|
+
// Round 10 (measured): 2^53..2^63-1 load; at 2^63 Codex's app-server panics.
|
|
252
|
+
if (!m[0].startsWith('-') && BigInt(m[0]) >= U63)
|
|
253
|
+
return `${where} \`${m[0]}\` is 2^63 or beyond`;
|
|
254
|
+
return null;
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
skip();
|
|
258
|
+
return null;
|
|
259
|
+
};
|
|
260
|
+
// @implements A-SPEC-727 (round 9) — Codex buffers a hook object WHOLE (an internally tagged enum):
|
|
261
|
+
// a lone surrogate anywhere inside it, or nesting past serde's limit, drops the whole file.
|
|
262
|
+
const hook = (where) => {
|
|
263
|
+
ws();
|
|
264
|
+
const start = i;
|
|
265
|
+
skip();
|
|
266
|
+
const body = text.slice(start, i);
|
|
267
|
+
const end = i;
|
|
268
|
+
if (nestingDeeperThan(body, HOOK_DEPTH_LIMIT))
|
|
269
|
+
return `${where} nests deeper than Codex reads (serde recursion limit)`;
|
|
270
|
+
// @implements A-SPEC-727 (round 10) — fields are known per hook TYPE, as Codex validates them: a
|
|
271
|
+
// prompt/agent hook is skipped whole, an mcp_tool hook reads server/tool/timeout/statusMessage.
|
|
272
|
+
let type;
|
|
273
|
+
try {
|
|
274
|
+
type = JSON.parse(body)?.type;
|
|
275
|
+
}
|
|
276
|
+
catch {
|
|
277
|
+
type = undefined;
|
|
278
|
+
}
|
|
279
|
+
const known = HOOK_KEYS_BY_TYPE[typeof type === 'string' ? type : ''] ?? HOOK_KEYS_BY_TYPE.command;
|
|
280
|
+
i = start;
|
|
281
|
+
const p = object((k) => known.has(k), (k) => knownValue(k, `${where}.${k}`), where);
|
|
282
|
+
if (p)
|
|
283
|
+
return p;
|
|
284
|
+
i = end;
|
|
285
|
+
for (let j = 0; j < body.length; j++) {
|
|
286
|
+
if (body[j] !== '"')
|
|
287
|
+
continue;
|
|
288
|
+
const s0 = j;
|
|
289
|
+
j++;
|
|
290
|
+
while (j < body.length && body[j] !== '"') {
|
|
291
|
+
if (body[j] === '\\')
|
|
292
|
+
j++;
|
|
293
|
+
j++;
|
|
294
|
+
}
|
|
295
|
+
let str;
|
|
296
|
+
try {
|
|
297
|
+
str = JSON.parse(body.slice(s0, j + 1));
|
|
298
|
+
}
|
|
299
|
+
catch {
|
|
300
|
+
continue;
|
|
301
|
+
}
|
|
302
|
+
if (LONE_SURROGATE.test(str))
|
|
303
|
+
return `${where} holds a lone UTF-16 surrogate escape`;
|
|
304
|
+
}
|
|
305
|
+
return null;
|
|
306
|
+
};
|
|
307
|
+
const group = (where) => object((k) => GROUP_KEYS.has(k), (k) => (k === 'matcher'
|
|
308
|
+
? knownValue(k, `${where}.matcher`)
|
|
309
|
+
: array((n) => hook(`${where}.hooks[${n}]`))), where);
|
|
310
|
+
const hooksObj = () => object((k) => KNOWN_EVENTS.has(k), (e) => array((n) => group(`hooks.${e}[${n}]`)), '`hooks`');
|
|
311
|
+
const top = () => object((k) => k === 'hooks' || k === 'description', (k) => (k === 'hooks' ? hooksObj() : knownValue(k, '`description`')), 'the document');
|
|
312
|
+
return top();
|
|
313
|
+
}
|
|
314
|
+
/** A hook object sits five containers deep (document, hooks, event, group, hooks); 127 is the total. */
|
|
315
|
+
const HOOK_DEPTH_LIMIT = 127 - 5;
|
|
316
|
+
/** Linear and string-aware: whether containers nest deeper than `max`. */
|
|
317
|
+
function nestingDeeperThan(text, max) {
|
|
318
|
+
let depth = 0, inStr = false;
|
|
319
|
+
for (let i = 0; i < text.length; i++) {
|
|
320
|
+
const c = text[i];
|
|
321
|
+
if (inStr) {
|
|
322
|
+
if (c === '\\')
|
|
323
|
+
i++;
|
|
324
|
+
else if (c === '"')
|
|
325
|
+
inStr = false;
|
|
326
|
+
continue;
|
|
327
|
+
}
|
|
328
|
+
if (c === '"')
|
|
329
|
+
inStr = true;
|
|
330
|
+
else if (c === '[' || c === '{') {
|
|
331
|
+
if (++depth > max)
|
|
332
|
+
return true;
|
|
333
|
+
}
|
|
334
|
+
else if (c === ']' || c === '}')
|
|
335
|
+
depth--;
|
|
336
|
+
}
|
|
337
|
+
return false;
|
|
338
|
+
}
|
|
339
|
+
const HOOK_TYPES = new Set(['command', 'mcp_tool', 'prompt', 'agent']);
|
|
340
|
+
const strOrNull = (v) => v === undefined || v === null || typeof v === 'string';
|
|
341
|
+
// `-0` is a float to serde (round 6), though JavaScript calls it a safe integer.
|
|
342
|
+
// Round 10 (measured): -0 and integers up to 2^63-1 load in Codex (precision beyond 2^53 is the scanner's to judge).
|
|
343
|
+
const uintOrNull = (v) => v === undefined || v === null || (typeof v === 'number' && Number.isInteger(v) && v >= 0 && v <= 2 ** 63);
|
|
344
|
+
function parse(before) {
|
|
345
|
+
if (before === null || before.trim() === '')
|
|
346
|
+
return { ok: true, doc: {}, hadBom: false };
|
|
347
|
+
let doc;
|
|
348
|
+
// Round 8 (measured): Codex 0.155.1 ignores a hooks.json that starts with a BOM. One is stripped to
|
|
349
|
+
// read the rest; callers treat `hadBom` as a load problem (doctor) or rewrite without it (merge).
|
|
350
|
+
const hadBom = before.startsWith('');
|
|
351
|
+
const text = hadBom ? before.slice(1) : before;
|
|
352
|
+
// Beyond any real file, and beyond what JSON.stringify can walk: refused before any recursive step.
|
|
353
|
+
if (nestingDeeperThan(text, 1000))
|
|
354
|
+
return { ok: false, reason: 'nesting deeper than 1000 levels' };
|
|
355
|
+
try {
|
|
356
|
+
doc = JSON.parse(text);
|
|
357
|
+
}
|
|
358
|
+
catch {
|
|
359
|
+
return { ok: false, reason: 'not valid JSON' };
|
|
360
|
+
}
|
|
361
|
+
let shape;
|
|
362
|
+
try {
|
|
363
|
+
shape = knownShapeProblem(text);
|
|
364
|
+
}
|
|
365
|
+
catch {
|
|
366
|
+
shape = 'not valid JSON';
|
|
367
|
+
}
|
|
368
|
+
if (shape)
|
|
369
|
+
return { ok: false, reason: shape };
|
|
370
|
+
if (!doc || typeof doc !== 'object' || Array.isArray(doc))
|
|
371
|
+
return { ok: false, reason: 'not a JSON object' };
|
|
372
|
+
const hooks = doc.hooks;
|
|
373
|
+
if (hooks !== undefined && (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))) {
|
|
374
|
+
return { ok: false, reason: '`hooks` is not an object' };
|
|
375
|
+
}
|
|
376
|
+
// What makes codex-cli 0.155.1 drop the WHOLE file (measured), and only that. Unknown events and
|
|
377
|
+
// unknown keys are skipped by Codex, so they are skipped here (round 8).
|
|
378
|
+
const extra = Object.keys(doc).find((k) => k !== 'hooks' && k !== 'description');
|
|
379
|
+
if (extra !== undefined)
|
|
380
|
+
return { ok: false, reason: `unknown top-level key \`${extra}\` (Codex accepts only hooks and description)` };
|
|
381
|
+
if (!strOrNull(doc.description))
|
|
382
|
+
return { ok: false, reason: '`description` is not a string' };
|
|
383
|
+
for (const [event, groups] of Object.entries(hooks ?? {})) {
|
|
384
|
+
if (!KNOWN_EVENTS.has(event))
|
|
385
|
+
continue;
|
|
386
|
+
if (!Array.isArray(groups))
|
|
387
|
+
return { ok: false, reason: `\`hooks.${event}\` is not an array` };
|
|
388
|
+
for (const [i, g] of groups.entries()) {
|
|
389
|
+
if (!g || typeof g !== 'object' || Array.isArray(g))
|
|
390
|
+
return { ok: false, reason: `\`hooks.${event}[${i}]\` is not an object` };
|
|
391
|
+
const { matcher, hooks: inner } = g;
|
|
392
|
+
if (!strOrNull(matcher))
|
|
393
|
+
return { ok: false, reason: `\`hooks.${event}[${i}].matcher\` is not a string` };
|
|
394
|
+
if (inner !== undefined && !Array.isArray(inner))
|
|
395
|
+
return { ok: false, reason: `\`hooks.${event}[${i}].hooks\` is not an array` };
|
|
396
|
+
for (const [j, h] of (inner ?? []).entries()) {
|
|
397
|
+
const at = `\`hooks.${event}[${i}].hooks[${j}]`;
|
|
398
|
+
if (!h || typeof h !== 'object' || Array.isArray(h))
|
|
399
|
+
return { ok: false, reason: `${at}\` is not an object` };
|
|
400
|
+
const o = h;
|
|
401
|
+
if (typeof o.type !== 'string' || !HOOK_TYPES.has(o.type))
|
|
402
|
+
return { ok: false, reason: `${at}.type\` is not one of command, mcp_tool, prompt, agent` };
|
|
403
|
+
if (o.type === 'command' && typeof o.command !== 'string')
|
|
404
|
+
return { ok: false, reason: `${at}.command\` is missing or not a string` };
|
|
405
|
+
if (o.type === 'mcp_tool' && (typeof o.server !== 'string' || typeof o.tool !== 'string'))
|
|
406
|
+
return { ok: false, reason: `${at}\` mcp_tool needs string server and tool` };
|
|
407
|
+
// Round 10: per type — a prompt/agent hook is skipped by Codex without reading its fields.
|
|
408
|
+
if (o.type === 'command' || o.type === 'mcp_tool') {
|
|
409
|
+
if (!uintOrNull(o.timeout))
|
|
410
|
+
return { ok: false, reason: `${at}.timeout\` is not a non-negative integer` };
|
|
411
|
+
if (!strOrNull(o.statusMessage))
|
|
412
|
+
return { ok: false, reason: `${at}.statusMessage\` is not a string` };
|
|
413
|
+
}
|
|
414
|
+
if (o.type === 'command') {
|
|
415
|
+
if (!uintOrNull(o.additionalContextLimit))
|
|
416
|
+
return { ok: false, reason: `${at}.additionalContextLimit\` is not a non-negative integer` };
|
|
417
|
+
if (!strOrNull(o.commandWindows))
|
|
418
|
+
return { ok: false, reason: `${at}.commandWindows\` is not a string` };
|
|
419
|
+
if (o.async !== undefined && typeof o.async !== 'boolean')
|
|
420
|
+
return { ok: false, reason: `${at}.async\` is not a boolean` };
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
return { ok: true, doc: doc, hadBom };
|
|
426
|
+
}
|
|
427
|
+
/** Holmes owns a hook only as a `command` hook in its exact shape (round 8: not an mcp_tool look-alike). */
|
|
428
|
+
const holmesOwned = (h) => !!h && typeof h === 'object' && h.type === 'command' && holmesKernelScript(h.command) !== null;
|
|
429
|
+
/**
|
|
430
|
+
* @implements A-SPEC-727 (round 8) — whether Codex's Rust regex compiles a matcher: no lookaround, no
|
|
431
|
+
* backreference; leading inline flags (`(?i)`) are allowed. A group whose matcher fails is skipped.
|
|
432
|
+
*/
|
|
433
|
+
function codexMatcherCompiles(matcher) {
|
|
434
|
+
if (matcher === undefined || matcher === null)
|
|
435
|
+
return true;
|
|
436
|
+
if (typeof matcher !== 'string')
|
|
437
|
+
return false;
|
|
438
|
+
if (matcher === '*')
|
|
439
|
+
return true; // Codex treats a bare `*` as match-all (measured)
|
|
440
|
+
return rustRegexRefuses(matcher) === null;
|
|
441
|
+
}
|
|
442
|
+
/** Escapes Rust's regex defines with a letter; any other letter escape is refused (`\h`, `\e`, `\Z`, `\c`). */
|
|
443
|
+
const RUST_ESCAPE_LETTERS = new Set([...'dDwWsSbBAzntrfvaxuUpP']);
|
|
444
|
+
const RUST_NEST_LIMIT = 250;
|
|
445
|
+
/**
|
|
446
|
+
* @implements A-SPEC-727 (round 10) — what Rust's regex MEASURABLY refuses, and nothing else: compiling
|
|
447
|
+
* the pattern as JavaScript disagreed both ways (`\-`, `\pL`, `[[:alpha:]]`, `\x{41}` falsely failed;
|
|
448
|
+
* `[]`, duplicate names, huge counts falsely passed). Named residual: the compiled-size limit.
|
|
449
|
+
*/
|
|
450
|
+
function rustRegexRefuses(p) {
|
|
451
|
+
let depth = 0;
|
|
452
|
+
const names = new Set();
|
|
453
|
+
let prevAtom = false;
|
|
454
|
+
const skipBraces = (j) => { const e = p.indexOf('}', j); return e < 0 ? -1 : e + 1; };
|
|
455
|
+
for (let i = 0; i < p.length;) {
|
|
456
|
+
const c = p[i];
|
|
457
|
+
if (c === '\\') {
|
|
458
|
+
const e = p[i + 1];
|
|
459
|
+
if (e === undefined)
|
|
460
|
+
return 'trailing backslash';
|
|
461
|
+
if (/[0-9]/.test(e))
|
|
462
|
+
return `\\${e} (backreference or octal)`;
|
|
463
|
+
if (/[A-Za-z]/.test(e) && !RUST_ESCAPE_LETTERS.has(e))
|
|
464
|
+
return `unknown escape \\${e}`;
|
|
465
|
+
i += 2;
|
|
466
|
+
if (/[xuUpPb]/.test(e) && p[i] === '{') {
|
|
467
|
+
const n = skipBraces(i);
|
|
468
|
+
if (n < 0)
|
|
469
|
+
return 'unclosed escape brace';
|
|
470
|
+
i = n;
|
|
471
|
+
}
|
|
472
|
+
else if (/[pP]/.test(e))
|
|
473
|
+
i += 1;
|
|
474
|
+
prevAtom = true;
|
|
475
|
+
continue;
|
|
476
|
+
}
|
|
477
|
+
if (c === '[') {
|
|
478
|
+
// A character class; `]` right after `[` or `[^` is a literal member, nested classes nest.
|
|
479
|
+
let j = i + 1;
|
|
480
|
+
let classDepth = 1;
|
|
481
|
+
if (p[j] === '^')
|
|
482
|
+
j++;
|
|
483
|
+
if (p[j] === ']')
|
|
484
|
+
j++;
|
|
485
|
+
let prevWasChar = false;
|
|
486
|
+
while (j < p.length && classDepth > 0) {
|
|
487
|
+
const d = p[j];
|
|
488
|
+
if (d === '\\') {
|
|
489
|
+
const e = p[j + 1];
|
|
490
|
+
if (e === undefined)
|
|
491
|
+
return 'trailing backslash';
|
|
492
|
+
if (/[A-Za-z]/.test(e) && !RUST_ESCAPE_LETTERS.has(e))
|
|
493
|
+
return `unknown escape \\${e}`;
|
|
494
|
+
if (/[0-9]/.test(e))
|
|
495
|
+
return `\\${e} (octal)`;
|
|
496
|
+
if (/[dDwWsS]/.test(e) && p[j - 1] === '-' && prevWasChar)
|
|
497
|
+
return 'a range bounded by a class';
|
|
498
|
+
j += 2;
|
|
499
|
+
if (/[xuUpP]/.test(e) && p[j] === '{') {
|
|
500
|
+
const n = skipBraces(j);
|
|
501
|
+
if (n < 0)
|
|
502
|
+
return 'unclosed escape brace';
|
|
503
|
+
j = n;
|
|
504
|
+
}
|
|
505
|
+
prevWasChar = true;
|
|
506
|
+
continue;
|
|
507
|
+
}
|
|
508
|
+
if (d === '[' && p[j + 1] === ':') {
|
|
509
|
+
const e = p.indexOf(':]', j + 2);
|
|
510
|
+
if (e < 0)
|
|
511
|
+
return 'unclosed POSIX class';
|
|
512
|
+
j = e + 2;
|
|
513
|
+
prevWasChar = true;
|
|
514
|
+
continue;
|
|
515
|
+
}
|
|
516
|
+
if (d === '[') {
|
|
517
|
+
classDepth++;
|
|
518
|
+
j++;
|
|
519
|
+
if (p[j] === '^')
|
|
520
|
+
j++;
|
|
521
|
+
if (p[j] === ']')
|
|
522
|
+
j++;
|
|
523
|
+
continue;
|
|
524
|
+
}
|
|
525
|
+
if (d === ']') {
|
|
526
|
+
classDepth--;
|
|
527
|
+
j++;
|
|
528
|
+
continue;
|
|
529
|
+
}
|
|
530
|
+
prevWasChar = d !== '-';
|
|
531
|
+
j++;
|
|
532
|
+
}
|
|
533
|
+
if (classDepth > 0)
|
|
534
|
+
return 'unclosed character class';
|
|
535
|
+
i = j;
|
|
536
|
+
prevAtom = true;
|
|
537
|
+
continue;
|
|
538
|
+
}
|
|
539
|
+
if (c === '(') {
|
|
540
|
+
if (/^\(\?<?[=!]/.test(p.slice(i, i + 4)))
|
|
541
|
+
return 'lookaround';
|
|
542
|
+
const named = /^\(\?P?<([A-Za-z_][A-Za-z0-9_]*)>/.exec(p.slice(i, i + 80));
|
|
543
|
+
if (named) {
|
|
544
|
+
if (names.has(named[1]))
|
|
545
|
+
return `duplicate group name ${named[1]}`;
|
|
546
|
+
names.add(named[1]);
|
|
547
|
+
}
|
|
548
|
+
if (++depth > RUST_NEST_LIMIT)
|
|
549
|
+
return 'nesting beyond 250';
|
|
550
|
+
i += named ? named[0].length : 1;
|
|
551
|
+
prevAtom = false;
|
|
552
|
+
continue;
|
|
553
|
+
}
|
|
554
|
+
if (c === ')') {
|
|
555
|
+
if (--depth < 0)
|
|
556
|
+
return 'unbalanced )';
|
|
557
|
+
i++;
|
|
558
|
+
prevAtom = true;
|
|
559
|
+
continue;
|
|
560
|
+
}
|
|
561
|
+
if (c === '{') {
|
|
562
|
+
const m = /^\{(\d+)(?:,(\d*))?\}/.exec(p.slice(i, i + 40));
|
|
563
|
+
if (!m || !prevAtom)
|
|
564
|
+
return 'a { that is not a counted repetition';
|
|
565
|
+
if (Number(m[1]) > 4294967295 || (m[2] && Number(m[2]) > 4294967295))
|
|
566
|
+
return 'a repetition count beyond 2^32-1';
|
|
567
|
+
i += m[0].length;
|
|
568
|
+
continue;
|
|
569
|
+
}
|
|
570
|
+
prevAtom = !/[|*+?]/.test(c) || prevAtom;
|
|
571
|
+
if (c === '|')
|
|
572
|
+
prevAtom = false;
|
|
573
|
+
i++;
|
|
574
|
+
}
|
|
575
|
+
return depth === 0 ? null : 'unclosed group';
|
|
576
|
+
}
|
|
577
|
+
/**
|
|
578
|
+
* @implements A-SPEC-727 (round 5) — whether the text holds any Holmes-shaped command, WITHOUT requiring
|
|
579
|
+
* it to pass `parse` — so a file Holmes refuses to rewrite still counts as wired for removal and for the
|
|
580
|
+
* self-disarm approval.
|
|
581
|
+
*/
|
|
582
|
+
function holmesCommandsPresent(raw) {
|
|
583
|
+
// Round 6: a text that does not parse, or that repeats a key (JSON.parse keeps only the last), is
|
|
584
|
+
// judged by its text — a Holmes kernel path anywhere in it counts.
|
|
585
|
+
const text = raw.replace(/^\uFEFF+/, '');
|
|
586
|
+
// Round 8: JSON may escape the slashes (`\/`); a file refused for ANY reason is judged by its text.
|
|
587
|
+
const byText = () => /dist(?:\\\/|\/|\\\\)+holmes(?:\\\/|\/|\\\\)+hooks(?:\\\/|\/|\\\\)+(?:pre-tool-use|stop)\.js/.test(text);
|
|
588
|
+
const parsed = parse(text);
|
|
589
|
+
if (!parsed.ok)
|
|
590
|
+
return byText();
|
|
591
|
+
const hooks = parsed.doc.hooks;
|
|
592
|
+
if (!hooks || typeof hooks !== 'object')
|
|
593
|
+
return false;
|
|
594
|
+
for (const groups of Object.values(hooks)) {
|
|
595
|
+
if (!Array.isArray(groups))
|
|
596
|
+
continue;
|
|
597
|
+
for (const g of groups)
|
|
598
|
+
for (const h of Array.isArray(g?.hooks) ? g.hooks : []) {
|
|
599
|
+
if (holmesOwned(h))
|
|
600
|
+
return true;
|
|
601
|
+
}
|
|
602
|
+
}
|
|
603
|
+
return false;
|
|
604
|
+
}
|
|
605
|
+
/**
|
|
606
|
+
* Removes every Holmes-shaped command. A group left with no command is dropped; a group that still
|
|
607
|
+
* holds the user's own commands is kept with only those — so a hand-mixed group can neither make the
|
|
608
|
+
* kernel run twice after a merge nor keep it alive after --remove.
|
|
609
|
+
*/
|
|
610
|
+
function withoutHolmes(hooks) {
|
|
611
|
+
const out = {};
|
|
612
|
+
for (const [event, groups] of Object.entries(hooks)) {
|
|
613
|
+
if (!Array.isArray(groups)) {
|
|
614
|
+
put(out, event, groups);
|
|
615
|
+
continue;
|
|
616
|
+
}
|
|
617
|
+
const kept = [];
|
|
618
|
+
let touched = false;
|
|
619
|
+
for (const g of groups) {
|
|
620
|
+
const inner = g?.hooks;
|
|
621
|
+
if (!Array.isArray(inner) || !inner.some(holmesOwned)) {
|
|
622
|
+
kept.push(g);
|
|
623
|
+
continue;
|
|
624
|
+
}
|
|
625
|
+
touched = true;
|
|
626
|
+
const rest = inner.filter((h) => !holmesOwned(h));
|
|
627
|
+
if (rest.length > 0)
|
|
628
|
+
kept.push({ ...g, hooks: rest });
|
|
629
|
+
}
|
|
630
|
+
// Round 8: a user's event array (even an empty one) stays; only one we emptied is dropped.
|
|
631
|
+
if (kept.length > 0 || !touched)
|
|
632
|
+
put(out, event, kept);
|
|
633
|
+
}
|
|
634
|
+
return out;
|
|
635
|
+
}
|
|
636
|
+
const render = (doc) => `${JSON.stringify(doc, null, 2)}\n`;
|
|
637
|
+
const shippedGroup = (event, packageRoot) => event === 'PreToolUse'
|
|
638
|
+
? { matcher: '.*', hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'pre-tool-use.js'), timeout: 30 }] }
|
|
639
|
+
: { hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'stop.js'), timeout: 30 }] };
|
|
640
|
+
/**
|
|
641
|
+
* One Holmes PreToolUse and one Holmes Stop group, IN PLACE. Codex keys trust by (file, event, group
|
|
642
|
+
* index, hook index) plus a hash of the definition, so the first Holmes-only group of an event is
|
|
643
|
+
* replaced at its own index and a group is appended only when the event had none. When nothing
|
|
644
|
+
* changes structurally the input text is returned as is — a re-run never reformats the user's file.
|
|
645
|
+
*/
|
|
646
|
+
function mergeCodexUserHooks(before, packageRoot) {
|
|
647
|
+
const parsed = parse(before);
|
|
648
|
+
if (!parsed.ok)
|
|
649
|
+
return parsed;
|
|
650
|
+
const src = parsed.doc.hooks ?? {};
|
|
651
|
+
const hooks = {};
|
|
652
|
+
for (const [event, groups] of Object.entries(src)) {
|
|
653
|
+
if (event === 'PreToolUse' || event === 'Stop')
|
|
654
|
+
continue;
|
|
655
|
+
const cleaned = withoutHolmes({ [event]: groups });
|
|
656
|
+
if (has(cleaned, event))
|
|
657
|
+
put(hooks, event, cleaned[event]);
|
|
658
|
+
}
|
|
659
|
+
for (const event of ['PreToolUse', 'Stop']) {
|
|
660
|
+
const out = [];
|
|
661
|
+
let placed = false;
|
|
662
|
+
for (const g of (has(src, event) ? src[event] : undefined) ?? []) {
|
|
663
|
+
const inner = Array.isArray(g.hooks) ? g.hooks : [];
|
|
664
|
+
if (!inner.some(holmesOwned)) {
|
|
665
|
+
out.push(g);
|
|
666
|
+
continue;
|
|
667
|
+
}
|
|
668
|
+
const rest = inner.filter((h) => !holmesOwned(h));
|
|
669
|
+
if (rest.length > 0) {
|
|
670
|
+
out.push({ ...g, hooks: rest });
|
|
671
|
+
continue;
|
|
672
|
+
}
|
|
673
|
+
if (!placed) {
|
|
674
|
+
// Keep the group's and the hook's own extra fields (statusMessage, async, …): Codex hashes
|
|
675
|
+
// them into the trust identity, so dropping one would silently untrust the gate (round 4).
|
|
676
|
+
const shipped = shippedGroup(event, packageRoot);
|
|
677
|
+
const oldHook = inner.find(holmesOwned);
|
|
678
|
+
const merged = { ...g, ...(shipped.matcher !== undefined ? { matcher: shipped.matcher } : {}),
|
|
679
|
+
// Round 5: never `async` (an async pre-tool hook cannot block) and never a stale commandWindows.
|
|
680
|
+
hooks: [(() => { const { async: _a, commandWindows: _w, ...keep } = (oldHook ?? {}); return { ...keep, ...shipped.hooks[0] }; })()] };
|
|
681
|
+
out.push(merged);
|
|
682
|
+
placed = true;
|
|
683
|
+
}
|
|
684
|
+
}
|
|
685
|
+
if (!placed)
|
|
686
|
+
out.push(shippedGroup(event, packageRoot));
|
|
687
|
+
put(hooks, event, out);
|
|
688
|
+
}
|
|
689
|
+
// Keep the original event order; new events go last.
|
|
690
|
+
const ordered = {};
|
|
691
|
+
for (const k of Object.keys(src))
|
|
692
|
+
if (has(hooks, k))
|
|
693
|
+
put(ordered, k, hooks[k]);
|
|
694
|
+
for (const k of Object.keys(hooks))
|
|
695
|
+
if (!has(ordered, k))
|
|
696
|
+
put(ordered, k, hooks[k]);
|
|
697
|
+
const doc = { ...parsed.doc, hooks: ordered };
|
|
698
|
+
// Round 8: a BOM file is never returned as is — Codex ignores it; the rewrite is trust-neutral.
|
|
699
|
+
if (before !== null && before.trim() !== '' && !parsed.hadBom && JSON.stringify(doc) === JSON.stringify(parsed.doc)) {
|
|
700
|
+
return { ok: true, content: before, empty: false };
|
|
701
|
+
}
|
|
702
|
+
return { ok: true, content: render(doc), empty: false };
|
|
703
|
+
}
|
|
704
|
+
/** Every hook's Codex trust identity: event, group index, hook index and the hashed definition. */
|
|
705
|
+
function trustIdentities(raw) {
|
|
706
|
+
const out = new Set();
|
|
707
|
+
const parsed = parse(raw);
|
|
708
|
+
if (!parsed.ok)
|
|
709
|
+
return out;
|
|
710
|
+
// @implements A-SPEC-727 (round 9) — known events only, and only well-formed arrays/objects: an
|
|
711
|
+
// unknown event holding `5`, `[null]` or `[{"hooks":{}}]` (which Codex loads) crashed init here.
|
|
712
|
+
for (const [event, groups] of Object.entries(parsed.doc.hooks ?? {})) {
|
|
713
|
+
if (!KNOWN_EVENTS.has(event) || !Array.isArray(groups))
|
|
714
|
+
continue;
|
|
715
|
+
for (const [gi, g] of groups.entries()) {
|
|
716
|
+
if (!g || typeof g !== 'object' || !Array.isArray(g.hooks))
|
|
717
|
+
continue;
|
|
718
|
+
for (const [hi, h] of g.hooks.entries()) {
|
|
719
|
+
if (!h || typeof h !== 'object')
|
|
720
|
+
continue;
|
|
721
|
+
// Codex's hash covers the whole hook (measured: statusMessage, async count; key order and
|
|
722
|
+
// group-level fields do not; timeout defaults to 600, async to false).
|
|
723
|
+
const hook = { timeout: 600, async: false, ...h };
|
|
724
|
+
const canonical = Object.keys(hook).sort().map((k) => [k, hook[k]]);
|
|
725
|
+
out.add(JSON.stringify([event, gi, hi, g.matcher ?? null, canonical]));
|
|
726
|
+
}
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
return out;
|
|
730
|
+
}
|
|
731
|
+
/**
|
|
732
|
+
* @implements A-SPEC-727
|
|
733
|
+
* Whether writing `after` over `before` would change the trust identity of any hook that is already
|
|
734
|
+
* there (Holmes's or the user's). Such a hook stops running in every workspace until it is trusted
|
|
735
|
+
* again with `/hooks` — a disarm by Holmes's own CLI, so init asks for approval first.
|
|
736
|
+
*/
|
|
737
|
+
function codexHooksTrustChanges(before, after) {
|
|
738
|
+
const was = trustIdentities(before);
|
|
739
|
+
const now = trustIdentities(after);
|
|
740
|
+
for (const id of was)
|
|
741
|
+
if (!now.has(id))
|
|
742
|
+
return true;
|
|
743
|
+
return false;
|
|
744
|
+
}
|
|
745
|
+
/** Remove only Holmes-owned commands. `empty` means nothing but an empty `hooks` object is left. */
|
|
746
|
+
function removeCodexUserHooks(before) {
|
|
747
|
+
const parsed = parse(before);
|
|
748
|
+
if (!parsed.ok)
|
|
749
|
+
return parsed;
|
|
750
|
+
const hooks = withoutHolmes(parsed.doc.hooks ?? {});
|
|
751
|
+
const doc = { ...parsed.doc, hooks };
|
|
752
|
+
const empty = Object.keys(hooks).length === 0 && Object.keys(doc).every((k) => k === 'hooks');
|
|
753
|
+
return { ok: true, content: render(doc), empty };
|
|
754
|
+
}
|
|
755
|
+
/** Whether the file holds any Holmes-owned command, in ANY event — the same set removal acts on. */
|
|
756
|
+
function hasHolmesCodexHooks(raw) {
|
|
757
|
+
return inspectCodexUserHooks(raw).state === 'wired';
|
|
758
|
+
}
|
|
759
|
+
/**
|
|
760
|
+
* doctor's evidence. `all` is every Holmes kernel script in any event; `preToolUse` only the
|
|
761
|
+
* pre-tool-use kernel under PreToolUse and `stop` only the stop kernel under Stop — a kernel in the
|
|
762
|
+
* wrong event gates nothing. `preMatchers` are the matchers of the groups that run the gate.
|
|
763
|
+
*/
|
|
764
|
+
function inspectCodexUserHooks(raw) {
|
|
765
|
+
const parsed = parse(raw);
|
|
766
|
+
if (!parsed.ok)
|
|
767
|
+
return { state: 'invalid', reason: parsed.reason };
|
|
768
|
+
if (parsed.hadBom)
|
|
769
|
+
return { state: 'invalid', reason: 'the file starts with a UTF-8 BOM — codex-cli 0.155.1 ignores such a hooks.json entirely (measured); re-run holmes-kit init --agent codex to rewrite it without one' };
|
|
770
|
+
const hooks = parsed.doc.hooks ?? {};
|
|
771
|
+
const all = [], preToolUse = [], stop = [], preMatchers = [];
|
|
772
|
+
for (const [event, groups] of Object.entries(hooks)) {
|
|
773
|
+
if (!Array.isArray(groups))
|
|
774
|
+
continue;
|
|
775
|
+
for (const g of groups) {
|
|
776
|
+
const inner = Array.isArray(g?.hooks) ? g.hooks : [];
|
|
777
|
+
// Round 6: Codex skips a group holding a prompt/agent hook, calls an mcp_tool hook's tool (not
|
|
778
|
+
// its command), and an async hook cannot block — none of those RUNS the gate.
|
|
779
|
+
// Round 8: nor does a group whose matcher Codex's Rust regex cannot compile.
|
|
780
|
+
const groupRuns = !inner.some((h) => h?.type === 'prompt' || h?.type === 'agent') && codexMatcherCompiles(g?.matcher);
|
|
781
|
+
for (const h of inner) {
|
|
782
|
+
const script = holmesKernelScript(h?.command);
|
|
783
|
+
if (script === null)
|
|
784
|
+
continue;
|
|
785
|
+
all.push(script);
|
|
786
|
+
const kernel = script.replace(/\\/g, '/').split('/').pop();
|
|
787
|
+
const runs = groupRuns && h.type === 'command' && h.async !== true;
|
|
788
|
+
if (event === 'PreToolUse' && kernel === 'pre-tool-use.js' && runs) {
|
|
789
|
+
preToolUse.push(script);
|
|
790
|
+
preMatchers.push(typeof g.matcher === 'string' ? g.matcher : '');
|
|
791
|
+
}
|
|
792
|
+
if (event === 'Stop' && kernel === 'stop.js')
|
|
793
|
+
stop.push(script);
|
|
794
|
+
}
|
|
795
|
+
}
|
|
796
|
+
}
|
|
797
|
+
return all.length === 0 ? { state: 'absent' } : { state: 'wired', all, preToolUse, stop, preMatchers };
|
|
798
|
+
}
|
|
799
|
+
/** The kernel scripts `mergeCodexUserHooks` would write for this install. */
|
|
800
|
+
function codexKernelScripts(packageRoot) {
|
|
801
|
+
return KERNELS.map((k) => path.join(packageRoot, 'dist', 'holmes', 'hooks', k));
|
|
802
|
+
}
|