@holmes-lab/holmes-kit 0.35.0 → 0.35.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 +61 -0
- package/README.md +5 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/codex-oracle.js +36 -2
- package/dist/holmes/cli/doctor.d.ts +14 -1
- package/dist/holmes/cli/doctor.js +335 -71
- package/dist/holmes/cli/index.d.ts +1 -1
- package/dist/holmes/cli/index.js +38 -5
- package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
- package/dist/holmes/cli/runtime-binding-approval.js +102 -0
- package/dist/holmes/cli/runtime-binding.d.ts +29 -0
- package/dist/holmes/cli/runtime-binding.js +570 -0
- package/dist/holmes/governance/approval-queue.d.ts +2 -0
- package/dist/holmes/governance/approval-queue.js +11 -4
- package/dist/holmes/guardrail/risk-classifier.js +45 -24
- package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
- package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
- package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
- package/dist/holmes/guardrail/shell-syntax.js +489 -0
- package/dist/holmes/guardrail/shell-words.d.ts +2 -18
- package/dist/holmes/guardrail/shell-words.js +15 -441
- package/dist/holmes/guardrail/write-target.d.ts +54 -0
- package/dist/holmes/guardrail/write-target.js +327 -1
- package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
- package/dist/holmes/hooks/pre-tool-use.js +377 -66
- package/dist/holmes/mcp/handlers.d.ts +9 -1
- package/dist/holmes/mcp/handlers.js +6 -4
- package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
- package/dist/holmes/mcp/operator-recovery.js +63 -0
- package/dist/holmes/runtime/binding.d.ts +30 -0
- package/dist/holmes/runtime/binding.js +164 -0
- package/dist/holmes/runtime/dispatch.d.ts +9 -0
- package/dist/holmes/runtime/dispatch.js +169 -0
- package/dist/holmes/runtime/hook-process.d.ts +11 -0
- package/dist/holmes/runtime/hook-process.js +130 -0
- package/docs/install-guide.md +65 -0
- package/package.json +1 -1
|
@@ -39,6 +39,7 @@ exports.readApprovalFromEnv = readApprovalFromEnv;
|
|
|
39
39
|
exports.sedInPlaceFiles = sedInPlaceFiles;
|
|
40
40
|
exports.hookOutputFor = hookOutputFor;
|
|
41
41
|
exports.dumpsEnvInCommandPosition = dumpsEnvInCommandPosition;
|
|
42
|
+
exports.ledgerSummaryOf = ledgerSummaryOf;
|
|
42
43
|
exports.normalizeHookInput = normalizeHookInput;
|
|
43
44
|
exports.preEditEvidenceGate = preEditEvidenceGate;
|
|
44
45
|
exports.decideOnGateError = decideOnGateError;
|
|
@@ -47,7 +48,8 @@ exports.gateErrorDecision = gateErrorDecision;
|
|
|
47
48
|
exports.wiredSpecsDir = wiredSpecsDir;
|
|
48
49
|
exports.evaluateHook = evaluateHook;
|
|
49
50
|
exports.readSpecsSync = readSpecsSync;
|
|
50
|
-
// @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747
|
|
51
|
+
// @implements A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753
|
|
52
|
+
const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
|
|
51
53
|
// @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
|
|
52
54
|
// evaluateHook in this file to prove it.
|
|
53
55
|
// @implements A-SPEC-643
|
|
@@ -73,11 +75,13 @@ const forbidden_edges_1 = require("../cpg/forbidden-edges");
|
|
|
73
75
|
const required_calls_1 = require("../cpg/required-calls");
|
|
74
76
|
const language_parser_1 = require("../cpg/language-parser");
|
|
75
77
|
const write_target_1 = require("../guardrail/write-target");
|
|
78
|
+
const shell_syntax_1 = require("../guardrail/shell-syntax");
|
|
76
79
|
const anchors_1 = require("../guardrail/anchors");
|
|
77
80
|
const governance_history_1 = require("../guardrail/governance-history");
|
|
78
81
|
const rtm_check_1 = require("../rtm/rtm-check");
|
|
79
82
|
const ledger_store_1 = require("../governance/ledger-store");
|
|
80
83
|
const provenance_chain_1 = require("../governance/provenance-chain");
|
|
84
|
+
const ledger_lock_1 = require("../governance/ledger-lock");
|
|
81
85
|
// @implements A-SPEC-574.3 — the caller owns the store and hands the chain the question.
|
|
82
86
|
const ledger_store_2 = require("../governance/ledger-store");
|
|
83
87
|
const risk_gate_1 = require("../guardrail/risk-gate");
|
|
@@ -514,6 +518,7 @@ function wrappedServerWord(normalized) {
|
|
|
514
518
|
return false;
|
|
515
519
|
}
|
|
516
520
|
function startsHolmesServer(command) {
|
|
521
|
+
command = (0, shell_argument_roles_1.shellArgumentRoles)(command).serverText;
|
|
517
522
|
if (SERVER_RUNNERS.some((t) => t.test(command)))
|
|
518
523
|
return true;
|
|
519
524
|
const normalized = normalizedCommand(command);
|
|
@@ -801,6 +806,161 @@ function incomingSetsApproved(ti) {
|
|
|
801
806
|
const text = `${ti.content ?? ''}\n${ti.new_string ?? ''}\n${(ti.edits ?? []).map((e) => e.new_string ?? '').join('\n')}`;
|
|
802
807
|
return (0, linear_match_1.setsApprovedStatus)(text); // A-SPEC-728 rule 38: the regex it replaces, in one pass
|
|
803
808
|
}
|
|
809
|
+
/** @implements A-SPEC-163.2 — the shell form of a patch: the command names the tool as a word. No pattern to back-track on. */
|
|
810
|
+
const APPLY_PATCH_WORD = /(?:^|[^\w-])(?:apply_patch|applypatch)(?![\w-])/;
|
|
811
|
+
const isBlankChar = (c) => c === ' ' || c === '\t' || c === '\r' || c === '\n';
|
|
812
|
+
/**
|
|
813
|
+
* The patch a shell command applies: its text, `'unreadable'`, or null when the command runs no patch tool.
|
|
814
|
+
*
|
|
815
|
+
* @implements A-SPEC-163.4 (rule 3)
|
|
816
|
+
* A shell can rewrite what a patch tool receives — an unquoted heredoc expands its body, a `cd` or a second
|
|
817
|
+
* invocation moves the base, an argument or a file carries text this gate never sees. So one form is read: the whole
|
|
818
|
+
* command line is `apply_patch <<'D'`, the patch, `D`. When the command line runs the tool in any other way — or
|
|
819
|
+
* cannot be parsed into commands and names it — it is unreadable. A command that only mentions the name is not a patch.
|
|
820
|
+
* Walked by index and by line: no pattern over the whole command, nothing to back-track on.
|
|
821
|
+
*/
|
|
822
|
+
function shellPatchOf(command) {
|
|
823
|
+
let i = 0;
|
|
824
|
+
while (i < command.length && isBlankChar(command.charAt(i)))
|
|
825
|
+
i++;
|
|
826
|
+
const word = ['apply_patch', 'applypatch'].find((w) => command.startsWith(w, i));
|
|
827
|
+
if (word !== undefined) {
|
|
828
|
+
let j = i + word.length;
|
|
829
|
+
const spaced = j;
|
|
830
|
+
while (j < command.length && (command.charAt(j) === ' ' || command.charAt(j) === '\t'))
|
|
831
|
+
j++;
|
|
832
|
+
const quote = command.charAt(j + 2);
|
|
833
|
+
if (j > spaced && command.startsWith('<<', j) && (quote === "'" || quote === '"')) {
|
|
834
|
+
const close = command.indexOf(quote, j + 3);
|
|
835
|
+
const delimiter = close === -1 ? '' : command.slice(j + 3, close);
|
|
836
|
+
// @implements A-SPEC-163.6 (rule 1) — a line feed directly after the quote: a carriage return there would be
|
|
837
|
+
// part of the delimiter for a shell, which then never finds the closing line this gate found.
|
|
838
|
+
const k = close + 1;
|
|
839
|
+
if (close !== -1 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(delimiter) && command.charAt(k) === '\n') {
|
|
840
|
+
const lines = command.slice(k + 1).split('\n');
|
|
841
|
+
// Exactly the delimiter: a shell does not end a heredoc on `EOF` followed by a carriage return or a space.
|
|
842
|
+
const end = lines.findIndex((line) => line === delimiter);
|
|
843
|
+
if (end !== -1 && lines.slice(end + 1).every((line) => line.trim() === ''))
|
|
844
|
+
return { text: lines.slice(0, end).join('\n') };
|
|
845
|
+
}
|
|
846
|
+
}
|
|
847
|
+
}
|
|
848
|
+
// @implements A-SPEC-163.5, A-SPEC-163.6 — not the one form. Which word a shell runs is not decidable from its text,
|
|
849
|
+
// and four review rounds showed that asking the parser is the deny-list again (a substitution skipped the word
|
|
850
|
+
// test, a heredoc body reshaped the words, the envelope was looked for only at line starts, a reader's option ran
|
|
851
|
+
// a program). So the TEXT is asked (163.6 rule 2): quotes and backslashes are how a shell lets a name be spelled
|
|
852
|
+
// apart; with them removed, a statically written name or envelope marker is a substring whatever the parse. A
|
|
853
|
+
// marked command line is unreadable unless it is one plain read (rule 3), a shape that cannot run anything.
|
|
854
|
+
//
|
|
855
|
+
// Fifth re-review (2026-10-04; measured natively the same day: codex-cli 0.160.0 puts `apply_patch` on the shell
|
|
856
|
+
// PATH): the exemption still trusted the parser (the operand of `<<<` was dropped, an attached `<(` was not a
|
|
857
|
+
// substitution), a backslash-newline split a marker, and ANSI-C quoting spelled one with no marker in the text.
|
|
858
|
+
// So the plain read is decided on the raw text too — only characters that cannot start an expansion, a redirect, a
|
|
859
|
+
// group or a second command — and a marker is also looked for in the words as the parser decodes them.
|
|
860
|
+
let parsed = null;
|
|
861
|
+
try {
|
|
862
|
+
parsed = (0, shell_syntax_1.shellWords)(command);
|
|
863
|
+
}
|
|
864
|
+
catch {
|
|
865
|
+
parsed = null;
|
|
866
|
+
}
|
|
867
|
+
const decodedMark = parsed === null
|
|
868
|
+
? PATCH_DECODE_HINT.test(command)
|
|
869
|
+
: parsed.commands.some((c) => c.words.some((w) => patchMarked(w.text))) || parsed.subs.some((s) => patchMarked(s));
|
|
870
|
+
// Sixth re-review (2026-10-04): the parser decodes ANSI-C quoting only in top-level words — not in a substitution
|
|
871
|
+
// body, a here-string operand, or after a heredoc body has flipped its quote state. So the escapes are decoded in
|
|
872
|
+
// the TEXT, wherever they sit, whenever the command uses `$'`.
|
|
873
|
+
const ansiMark = command.includes("$'") && patchMarked(command.replace(PATCH_ANSI_ESCAPE, patchAnsiChar));
|
|
874
|
+
if (!patchMarked(command) && !decodedMark && !ansiMark)
|
|
875
|
+
return null;
|
|
876
|
+
if (!PATCH_PLAIN_READ.test(command))
|
|
877
|
+
return 'unreadable';
|
|
878
|
+
try {
|
|
879
|
+
if (parsed === null)
|
|
880
|
+
return 'unreadable';
|
|
881
|
+
if (parsed.overflow || parsed.subs.length > 0 || parsed.commands.length !== 1)
|
|
882
|
+
return 'unreadable';
|
|
883
|
+
const only = parsed.commands[0];
|
|
884
|
+
if (only.redirects.length > 0 || only.words.length === 0 || !only.words.every((w) => w.known && !w.glob))
|
|
885
|
+
return 'unreadable';
|
|
886
|
+
if (!PATCH_READERS.has(only.words[0].text))
|
|
887
|
+
return 'unreadable';
|
|
888
|
+
// An option word may not hold a marker, and no long option is a plain read: a long option can hand the next word
|
|
889
|
+
// to a program (`rg --pre <command>`), which the spec's own test point refuses.
|
|
890
|
+
if (only.words.slice(1).some((w) => w.text.startsWith('--') || (w.text.startsWith('-') && patchMarked(w.text))))
|
|
891
|
+
return 'unreadable';
|
|
892
|
+
return null;
|
|
893
|
+
}
|
|
894
|
+
catch {
|
|
895
|
+
return 'unreadable';
|
|
896
|
+
}
|
|
897
|
+
}
|
|
898
|
+
/** The tool's names and the envelope markers, lower case (A-SPEC-163.6 rule 2). */
|
|
899
|
+
const PATCH_MARKERS = ['apply_patch', 'applypatch', '*** begin patch', '*** add file:', '*** update file:', '*** delete file:', '*** move to:'];
|
|
900
|
+
/** Whether a text shows a marker once its quotes and backslashes are removed and its letters lowered. Substring tests only. */
|
|
901
|
+
function patchMarked(text) {
|
|
902
|
+
// A backslash before a line feed is a line continuation: the shell removes both, so both are removed here.
|
|
903
|
+
const plain = text.split('\\\n').join('').split('"').join('').split("'").join('').split('\\').join('').toLowerCase();
|
|
904
|
+
// `$'…'` and `$"…"` leave their `$` behind once the quotes are gone (`apply$'_patch'` reads `apply$_patch`), so the
|
|
905
|
+
// text is tested with the dollars removed as well.
|
|
906
|
+
const undollared = plain.split('$').join('');
|
|
907
|
+
return PATCH_MARKERS.some((marker) => plain.includes(marker) || undollared.includes(marker));
|
|
908
|
+
}
|
|
909
|
+
/**
|
|
910
|
+
* The whole text of a plain read: letters, digits, spaces, tabs, quotes and `_ . / - : = , + @ % * ?`. Nothing that
|
|
911
|
+
* starts an expansion, a redirect, a group, a comment, a home directory or a second command — and no line break.
|
|
912
|
+
* One character class under one anchored repeat: linear.
|
|
913
|
+
*/
|
|
914
|
+
const PATCH_PLAIN_READ = /^[A-Za-z0-9 \t'"_.\/\-:=,+@%*?]*$/;
|
|
915
|
+
/** The numeric escapes of ANSI-C quoting: hex, octal and the two Unicode forms. Alternation of bounded repeats: linear. */
|
|
916
|
+
const PATCH_ANSI_ESCAPE = /\\(?:x\{([0-9A-Fa-f]{1,8})\}?|x([0-9A-Fa-f]{1,2})|([0-7]{1,3})|u([0-9A-Fa-f]{1,4})|U([0-9A-Fa-f]{1,8}))/g;
|
|
917
|
+
function patchAnsiChar(_match, braced, hex, octal, short, long) {
|
|
918
|
+
const code = braced !== undefined ? parseInt(braced, 16) : hex !== undefined ? parseInt(hex, 16)
|
|
919
|
+
: octal !== undefined ? parseInt(octal, 8) : parseInt(short ?? long ?? '0', 16);
|
|
920
|
+
try {
|
|
921
|
+
return String.fromCodePoint(code);
|
|
922
|
+
}
|
|
923
|
+
catch {
|
|
924
|
+
return '';
|
|
925
|
+
}
|
|
926
|
+
}
|
|
927
|
+
/** When the command line does not parse at all: ANSI-C quoting is the one static spelling that hides a marker from the text. */
|
|
928
|
+
const PATCH_DECODE_HINT = /\$'/;
|
|
929
|
+
/** First words of a command that only reads its operands (A-SPEC-163.6 rule 3). */
|
|
930
|
+
const PATCH_READERS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'cat', 'head', 'tail', 'wc', 'ls']);
|
|
931
|
+
/** One key per file: links resolved on the longest existing part, letter case folded (A-SPEC-163.4 rule 5). */
|
|
932
|
+
function patchFileKey(file) {
|
|
933
|
+
// The path is handed to the OS as written: folding `..` first would step back from a link's NAME, not from where
|
|
934
|
+
// the link leads. An existing file is its device and inode, so a link of either kind names the same key.
|
|
935
|
+
try {
|
|
936
|
+
const stat = fs.statSync(file);
|
|
937
|
+
return 'inode:' + stat.dev + ':' + stat.ino;
|
|
938
|
+
}
|
|
939
|
+
catch { /* not there yet: its real parent and its name */ }
|
|
940
|
+
const slash = file.lastIndexOf('/');
|
|
941
|
+
const parent = slash <= 0 ? '/' : file.slice(0, slash);
|
|
942
|
+
const name = file.slice(slash + 1);
|
|
943
|
+
let real = path.resolve(file);
|
|
944
|
+
try {
|
|
945
|
+
real = fs.realpathSync(parent) + '/' + name;
|
|
946
|
+
}
|
|
947
|
+
catch { /* the parent is not there either: the lexical path */ }
|
|
948
|
+
return 'path:' + real.normalize('NFC').toLowerCase();
|
|
949
|
+
}
|
|
950
|
+
/** Strings read from one payload; more than this is not a payload a tool sends. */
|
|
951
|
+
const PATCH_STRINGS_MAX = 256;
|
|
952
|
+
/** A file an update hunk is applied to; a larger one is not judged by its result. */
|
|
953
|
+
const PATCH_UPDATE_BYTES_MAX = 8 * 1024 * 1024;
|
|
954
|
+
const PATCH_UNREADABLE_REASON = '[Holmes-Kit] cannot read the edit target path, so it cannot be judged (file_path missing or not a string)';
|
|
955
|
+
/**
|
|
956
|
+
* @implements A-SPEC-753.2 — what a denial leaves in the provenance ledger: the reason up to the operator command.
|
|
957
|
+
* The installer refusal (A-SPEC-753.1) carries the raw command after ` Operator: ` for the operator to run; the ledger
|
|
958
|
+
* is the one artefact meant to carry no raw command. The reason printed to the harness is unchanged.
|
|
959
|
+
*/
|
|
960
|
+
function ledgerSummaryOf(reason) {
|
|
961
|
+
const at = reason.indexOf(' Operator: ');
|
|
962
|
+
return at === -1 ? reason : reason.slice(0, at);
|
|
963
|
+
}
|
|
804
964
|
function normalizeHookInput(raw) {
|
|
805
965
|
const str = (v) => (typeof v === 'string' ? v : undefined);
|
|
806
966
|
if (!raw || typeof raw !== 'object')
|
|
@@ -858,7 +1018,58 @@ function normalizeHookInput(raw) {
|
|
|
858
1018
|
}
|
|
859
1019
|
const cwdRaw = str(r.cwd);
|
|
860
1020
|
const cwd = cwdRaw === undefined ? undefined : (cwdRaw.trim() || undefined);
|
|
861
|
-
|
|
1021
|
+
// @implements A-SPEC-163.1, A-SPEC-163.2 — a patch names its targets only inside the patch text, under a key no
|
|
1022
|
+
// contract of ours pins. Measured 2026-10-04: Codex `apply_patch` wrote an unanchored code file past this gate.
|
|
1023
|
+
// 163.2 (rule 1): strings are taken at any nesting to depth 4. A patch tool: every string with an envelope line.
|
|
1024
|
+
// The shell tool: its command when it runs `apply_patch`, and any nested whole patch. Any other write tool: only a
|
|
1025
|
+
// whole patch — prose that quotes patch lines is not a write. A path field does not hide the patch beside it.
|
|
1026
|
+
// A patch that cannot be read one way (no target, an empty path, too many, an indented header) is unreadable.
|
|
1027
|
+
const toolName = (str(r.tool_name) ?? '').toLowerCase();
|
|
1028
|
+
let patchUnreadable = false;
|
|
1029
|
+
if (!write_target_1.READ_ONLY_TOOLS.includes(toolName)) {
|
|
1030
|
+
const strings = [];
|
|
1031
|
+
const collect = (v, depth) => {
|
|
1032
|
+
if (typeof v === 'string') {
|
|
1033
|
+
if (!v.includes('*** '))
|
|
1034
|
+
return;
|
|
1035
|
+
// @implements A-SPEC-163.3 (rule 6) — more than the gate reads is unreadable, never unread.
|
|
1036
|
+
if (strings.length >= PATCH_STRINGS_MAX)
|
|
1037
|
+
patchUnreadable = true;
|
|
1038
|
+
else
|
|
1039
|
+
strings.push(v);
|
|
1040
|
+
return;
|
|
1041
|
+
}
|
|
1042
|
+
if (patchUnreadable)
|
|
1043
|
+
return;
|
|
1044
|
+
if (depth >= 4 || !v || typeof v !== 'object')
|
|
1045
|
+
return;
|
|
1046
|
+
for (const item of Array.isArray(v) ? v : Object.values(v))
|
|
1047
|
+
collect(item, depth + 1);
|
|
1048
|
+
};
|
|
1049
|
+
collect(ti, 0);
|
|
1050
|
+
const isPatchTool = toolName.includes('patch');
|
|
1051
|
+
const isShell = toolName === 'bash';
|
|
1052
|
+
// @implements A-SPEC-163.4 — which strings are patches is 163.2's rule; whether one is JUDGED is one positive
|
|
1053
|
+
// grammar. The shell tool's command is a patch only as one quoted-heredoc `apply_patch` (rule 3); every string
|
|
1054
|
+
// read as a patch must be canonical (rules 1-2). Anything else is unreadable, not unread.
|
|
1055
|
+
const patches = strings.filter((text) => !(isShell && text === cmd) && (isPatchTool ? (0, write_target_1.hasPatchEnvelope)(text) : (0, write_target_1.isWholePatch)(text)));
|
|
1056
|
+
if (isShell && cmd !== undefined) {
|
|
1057
|
+
const shellPatch = shellPatchOf(cmd);
|
|
1058
|
+
if (shellPatch === 'unreadable')
|
|
1059
|
+
patchUnreadable = true;
|
|
1060
|
+
else if (shellPatch !== null)
|
|
1061
|
+
patches.push(shellPatch.text);
|
|
1062
|
+
}
|
|
1063
|
+
if (patches.length > 0) {
|
|
1064
|
+
const targets = patches.flatMap((text) => (0, write_target_1.patchTargetsOf)(text));
|
|
1065
|
+
if (targets.length === 0 || targets.length > write_target_1.PATCH_TARGETS_MAX || patches.some((text) => !(0, write_target_1.canonicalPatch)(text)))
|
|
1066
|
+
patchUnreadable = true;
|
|
1067
|
+
else
|
|
1068
|
+
out.patch_targets = targets;
|
|
1069
|
+
}
|
|
1070
|
+
}
|
|
1071
|
+
return { tool_name: str(r.tool_name) ?? '', tool_input: out, ...(cwd === undefined ? {} : { cwd }), ...(malformed ? { malformed: true } : {}),
|
|
1072
|
+
...(patchUnreadable ? { patchUnreadable: true } : {}) };
|
|
862
1073
|
}
|
|
863
1074
|
/**
|
|
864
1075
|
* Which way to fail when the gate itself throws.
|
|
@@ -1003,6 +1214,70 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1003
1214
|
// @implements A-SPEC-728 (rule 40) — a spec edit's result is shared within this call only: a caller that hands the same
|
|
1004
1215
|
// tool_input object back changed must not be judged on the earlier result.
|
|
1005
1216
|
editedMemo = null;
|
|
1217
|
+
// @implements A-SPEC-163.1 — each file a patch names is judged by the same path as a `file_path` write of it;
|
|
1218
|
+
// the first denial is the decision. A relative target is where the tool would write it: from the payload cwd.
|
|
1219
|
+
// @implements A-SPEC-163.2 — an update or a move is judged on the file it produces (the hunk applied to the file on
|
|
1220
|
+
// disk); a move's source is judged as a delete; a relative target is `<base>/<path>` as written, not folded first;
|
|
1221
|
+
// a patch that cannot be read or applied is denied. When no target is denied, a payload with a path field or a
|
|
1222
|
+
// shell command is then judged as before.
|
|
1223
|
+
if (input.patchUnreadable)
|
|
1224
|
+
return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
|
|
1225
|
+
const patchTargets = input.tool_input.patch_targets;
|
|
1226
|
+
if (patchTargets !== undefined && !input.malformed) {
|
|
1227
|
+
const isShell = (input.tool_name ?? '').toLowerCase() === 'bash';
|
|
1228
|
+
// A relative `workdir` is relative to the payload cwd, never to wherever this hook process happens to run.
|
|
1229
|
+
const outer = input.cwd ?? opts.projectRoot;
|
|
1230
|
+
const workdir = isShell ? input.tool_input.workdir : undefined;
|
|
1231
|
+
const base = workdir === undefined ? outer : (path.isAbsolute(workdir) ? workdir : outer.replace(/\/+$/, '') + '/' + workdir);
|
|
1232
|
+
const at = (p) => (path.isAbsolute(p) ? p : base.replace(/\/+$/, '') + '/' + p);
|
|
1233
|
+
const resultOf = (source, hunk) => {
|
|
1234
|
+
try {
|
|
1235
|
+
// @implements A-SPEC-163.3 (rule 7) — only a regular file is read: a FIFO or a device would hold the hook.
|
|
1236
|
+
const stat = fs.statSync(source);
|
|
1237
|
+
if (!stat.isFile() || stat.size > PATCH_UPDATE_BYTES_MAX)
|
|
1238
|
+
return null;
|
|
1239
|
+
return (0, write_target_1.applyPatchUpdate)(fs.readFileSync(source, 'utf8'), hunk);
|
|
1240
|
+
}
|
|
1241
|
+
catch {
|
|
1242
|
+
return null;
|
|
1243
|
+
}
|
|
1244
|
+
};
|
|
1245
|
+
// @implements A-SPEC-163.3 (rule 1), A-SPEC-163.4 (rule 5) — two targets on one file have no one result: the tool
|
|
1246
|
+
// applies them in sequence, the gate reads the disk once. One file is one key whatever link or letter case names it.
|
|
1247
|
+
// (What a shell could rewrite is settled before this point: only the one quoted-heredoc form reaches here.)
|
|
1248
|
+
const files = new Set();
|
|
1249
|
+
for (const t of patchTargets) {
|
|
1250
|
+
const file = patchFileKey(at(t.path));
|
|
1251
|
+
if (files.has(file))
|
|
1252
|
+
return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
|
|
1253
|
+
files.add(file);
|
|
1254
|
+
}
|
|
1255
|
+
for (const t of patchTargets) {
|
|
1256
|
+
let content;
|
|
1257
|
+
if (t.kind === 'add')
|
|
1258
|
+
content = t.content;
|
|
1259
|
+
else if (t.kind === 'update' && t.movedTo === undefined) {
|
|
1260
|
+
const result = resultOf(at(t.path), t.hunk ?? '');
|
|
1261
|
+
if (result === null)
|
|
1262
|
+
return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
|
|
1263
|
+
content = result;
|
|
1264
|
+
}
|
|
1265
|
+
else if (t.kind === 'move') {
|
|
1266
|
+
const result = t.from === undefined ? null : resultOf(at(t.from), t.hunk ?? '');
|
|
1267
|
+
if (result === null)
|
|
1268
|
+
return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
|
|
1269
|
+
content = result;
|
|
1270
|
+
}
|
|
1271
|
+
// Judged as a patch tool's write whichever tool carried the patch, so the shell branch below is not re-entered.
|
|
1272
|
+
const verdict = evaluateHook({ tool_name: 'apply_patch', tool_input: { file_path: at(t.path), ...(content === undefined ? {} : { content }) },
|
|
1273
|
+
...(input.cwd === undefined ? {} : { cwd: input.cwd }) }, specsDir, opts);
|
|
1274
|
+
if (verdict.permissionDecision === 'deny')
|
|
1275
|
+
return verdict;
|
|
1276
|
+
}
|
|
1277
|
+
const hasPathField = typeof input.tool_input.file_path === 'string' || typeof input.tool_input.notebook_path === 'string';
|
|
1278
|
+
if (!hasPathField && !isShell)
|
|
1279
|
+
return { permissionDecision: 'allow' };
|
|
1280
|
+
}
|
|
1006
1281
|
// @implements A-SPEC-133 — resolved once so every gate in this call shares one timestamp.
|
|
1007
1282
|
const nowTs = opts?.now ?? new Date().toISOString();
|
|
1008
1283
|
// @implements A-SPEC-125.4
|
|
@@ -1060,13 +1335,16 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1060
1335
|
// replayed token denies exactly as an absent one — one token stops being a master key.
|
|
1061
1336
|
// @implements A-SPEC-728 — an operator who approved THIS exact hard-hitl command (e.g. a covered
|
|
1062
1337
|
// `rm -rf /`) has already judged its deletions; the wiring-deletion rule below must not re-deny it.
|
|
1338
|
+
// @implements A-SPEC-477.1 — spend only after every shell check succeeds.
|
|
1339
|
+
const pendingApprovals = [];
|
|
1340
|
+
const legacySessionApproval = approval?.scope === undefined
|
|
1341
|
+
&& (0, risk_gate_1.approvalCovers)(approval, { kind: 'config-write', target: command }, nowTs);
|
|
1063
1342
|
let hardHitlCovered = false;
|
|
1064
1343
|
if (assessment.level === 'hard-hitl') {
|
|
1065
1344
|
// @implements A-SPEC-245 — env first, then the grant files. The grant's mandatory nonce rides
|
|
1066
1345
|
// the SAME atomic ledger consumption below, so hard-hitl single-use needs no new machinery.
|
|
1067
1346
|
const resolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'shell', target: command }, nowTs);
|
|
1068
1347
|
const covers = resolved !== undefined;
|
|
1069
|
-
const acting = resolved?.approval ?? approval;
|
|
1070
1348
|
const deny = (why) => ({
|
|
1071
1349
|
permissionDecision: 'deny',
|
|
1072
1350
|
permissionDecisionReason: `[Holmes-Kit] hard-hitl risk: ${assessment.reasons.join('; ')} — ${why}`,
|
|
@@ -1081,60 +1359,12 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1081
1359
|
return deny(base
|
|
1082
1360
|
+ (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'shell', target: command, why: assessment.reasons.join('; ') }, { baseReasonBytes: base.length }));
|
|
1083
1361
|
}
|
|
1084
|
-
|
|
1085
|
-
// Check and spend in ONE atomic operation. The previous shape asked `isNonceConsumed(...)`
|
|
1086
|
-
// and only afterwards appended the consumption record, so two concurrent agents both saw
|
|
1087
|
-
// "not consumed" and both proceeded — measured, the same single-use approval was honoured
|
|
1088
|
-
// twice in 20 of 20 barrier-synchronized trials. That is a TOCTOU on the authorization gate,
|
|
1089
|
-
// not a logging problem, so the fix belongs here rather than around the append.
|
|
1090
|
-
// @implements A-SPEC-191 §15 (round 11) — NOT a refusal here, deliberately, and this is the
|
|
1091
|
-
// reasoning: the MCP consumers refuse a nonce they cannot record in a bound project (§13b),
|
|
1092
|
-
// and round-10 flagged the hook for lacking the same rule. But this consumer's anchor now
|
|
1093
|
-
// walks UP (§14a), so a subdirectory resolves to the real project and the only case left is a
|
|
1094
|
-
// directory with no project above it at all — a fresh project's first guarded command, where
|
|
1095
|
-
// creating `.ax/ledger` is the wiring working, not a plant. Refusing there would deny the
|
|
1096
|
-
// first legitimate use in every new project. The single-use guarantee still holds: the record
|
|
1097
|
-
// lands in the resolved root, which is the same file every later call resolves to.
|
|
1098
|
-
// @implements A-SPEC-643 — the writer's replica chain, resolved only on this path so ordinary hook
|
|
1099
|
-
// calls leave no footprint; the spent check below still spans every chain in the directory.
|
|
1100
|
-
const ledgerFile = (0, ledger_store_2.writerChainFile)(path.join(opts.projectRoot, '.ax', 'ledger'));
|
|
1101
|
-
// @implements A-SPEC-642 — a covered command is still denied, and no nonce spent, while the
|
|
1102
|
-
// merged ledger holds an unreconciled cross-replica double-spend; the reason names the exit.
|
|
1103
|
-
{
|
|
1104
|
-
const conflict = (0, ledger_store_2.ledgerConflictReason)(path.dirname(ledgerFile));
|
|
1105
|
-
if (conflict)
|
|
1106
|
-
return deny(conflict);
|
|
1107
|
-
}
|
|
1108
|
-
if ((0, provenance_chain_1.blankNonce)(acting?.nonce)) {
|
|
1109
|
-
return deny('the approval declared single-use (nonce) but the value is empty — single-use cannot be enforced, so it is denied');
|
|
1110
|
-
}
|
|
1111
|
-
if (acting?.nonce) {
|
|
1112
|
-
let won;
|
|
1113
|
-
try {
|
|
1114
|
-
won = (0, provenance_chain_1.consumeNonceExclusively)(acting.nonce, ledgerFile, {
|
|
1115
|
-
ts: nowTs, actor: acting.actor, kind: 'nonce-consumed',
|
|
1116
|
-
summary: `consumed single-use approval for: ${(0, provenance_chain_1.redactTarget)('command', command)}`.slice(0, 200),
|
|
1117
|
-
inputs: [(0, provenance_chain_1.nonceFingerprint)(acting.nonce)], rationale: acting.rationale, authorization: (0, provenance_chain_1.authorizationRef)(acting.actor, acting.token),
|
|
1118
|
-
}, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
|
|
1119
|
-
}
|
|
1120
|
-
catch (err) {
|
|
1121
|
-
// FAIL CLOSED. A gate that cannot prove exclusivity must not grant — degrading to an
|
|
1122
|
-
// allow here would restore exactly the race this exists to remove. The wording is
|
|
1123
|
-
// deliberately DIFFERENT from the replay wording: an operator debugging a wedged agent
|
|
1124
|
-
// needs to tell "someone already used this token" from "the ledger was busy".
|
|
1125
|
-
return deny(`could not obtain exclusive ledger access to spend the single-use approval (${err instanceof Error ? err.message : String(err)})`);
|
|
1126
|
-
}
|
|
1127
|
-
if (!won)
|
|
1128
|
-
return deny('single-use approval already consumed (replay)');
|
|
1129
|
-
// The ledger consumption is the authority; removing the file is cleanup for the next reader.
|
|
1130
|
-
if (resolved?.source === 'grant')
|
|
1131
|
-
(0, approval_grants_1.consumeGrantFile)(opts.projectRoot, acting.nonce);
|
|
1132
|
-
}
|
|
1362
|
+
pendingApprovals.push(resolved);
|
|
1133
1363
|
}
|
|
1134
1364
|
// Bash BYPASS gates (adversarial review: `cat > evil.ts` created ungoverned files, `echo x >
|
|
1135
1365
|
// .claude/settings.json` forged hook config, and `echo $HOLMES_LEDGER_KEY` harvested the very
|
|
1136
1366
|
// secrets the out-of-band channel depends on). All override-able by a valid approval.
|
|
1137
|
-
|
|
1367
|
+
{
|
|
1138
1368
|
// (a) Reading/dumping the out-of-band secrets: possession of the approval token or ledger key
|
|
1139
1369
|
// lets the agent forge approvals / re-sign history. Best-effort (a determined exfil via an
|
|
1140
1370
|
// interpreter remains — documented residual); raises the cost from one echo to a gated act.
|
|
@@ -1169,7 +1399,8 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1169
1399
|
// Which of the two harms this is. Setting a role or a bypass is not reading a secret, it is
|
|
1170
1400
|
// self-granting authority — reporting both as "reads the environment" sends an operator to
|
|
1171
1401
|
// hunt a leak that never happened.
|
|
1172
|
-
const GRANTS_SELF =
|
|
1402
|
+
const GRANTS_SELF = /\bHOLMES_(?:ROLE|GATE_BYPASS|AUTONOMOUS_APPROVAL|SEMANTIC_API_KEY)\b/.test(command);
|
|
1403
|
+
const providerCredential = /\b(?:GEMINI_API_KEY|GOOGLE_API_KEY)\b/.test(command);
|
|
1173
1404
|
const usesSecret =
|
|
1174
1405
|
// @implements A-SPEC-477 — the credential file is the same secret at rest; reading,
|
|
1175
1406
|
// copying or redirecting it is the harvest in file form. Path-usage only, so mentioning
|
|
@@ -1208,21 +1439,43 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1208
1439
|
tailAfterFirst(command, /\n/, /\b(?:node|python[0-9.]*|ruby|perl|deno|bun|php|awk|gawk)\b/, /(?<![.\w])ENV\b/);
|
|
1209
1440
|
// @implements A-SPEC-732 (round 2) — an agent starting its own copy of the MCP server can pose as a
|
|
1210
1441
|
// harness and answer its own approval; no agent task needs that copy (doctor starts one internally).
|
|
1211
|
-
|
|
1442
|
+
// @implements A-SPEC-753.1 — the documented installer without --dry-run starts no server: it changes which
|
|
1443
|
+
// build governs a workspace. Measured 2026-10-04, it was refused under the server-start wording below with
|
|
1444
|
+
// nothing for the operator to run. It stays refused; the reason names the act and carries the command. No
|
|
1445
|
+
// request id is printed: none exists until the operator runs the command, which files it.
|
|
1446
|
+
if (!legacySessionApproval && (0, shell_argument_roles_1.installerInvocationOf)(command) === 'apply') {
|
|
1212
1447
|
return {
|
|
1213
1448
|
permissionDecision: 'deny',
|
|
1214
|
-
permissionDecisionReason: '[Holmes-Kit]
|
|
1449
|
+
permissionDecisionReason: '[Holmes-Kit] runtime-binding setup/remove changes which Holmes build governs a workspace (governance wiring); the operator runs it, not the session. It prints the request id to approve; after the grant the operator runs the same command again. Use --dry-run to preview it here. Operator: ' + command,
|
|
1215
1450
|
};
|
|
1216
1451
|
}
|
|
1217
|
-
if (
|
|
1452
|
+
if (!legacySessionApproval && startsHolmesServer(command)) {
|
|
1218
1453
|
return {
|
|
1219
1454
|
permissionDecision: 'deny',
|
|
1220
|
-
permissionDecisionReason:
|
|
1221
|
-
? '[Holmes-Kit] the command sets or reads HOLMES_ROLE/HOLMES_GATE_BYPASS — a path by which a session grants itself authority.'
|
|
1222
|
-
+ ' Roles are set out-of-band by whoever launches the agent. To run it by operator judgment, an approval that includes config-write is required.'
|
|
1223
|
-
: '[Holmes-Kit] command reads or dumps process environment (holds the out-of-band HOLMES_APPROVAL / HOLMES_LEDGER_KEY secrets) — requires out-of-band approval',
|
|
1455
|
+
permissionDecisionReason: '[Holmes-Kit] the command starts the Holmes MCP server (or loads its handlers) itself — a copy the agent drives could answer its own approval (A-SPEC-732). The harness starts the server; use its tools. To run it by operator judgment, an approval that covers this command is required.',
|
|
1224
1456
|
};
|
|
1225
1457
|
}
|
|
1458
|
+
if (dumpsEnv) {
|
|
1459
|
+
const reason = GRANTS_SELF
|
|
1460
|
+
? '[Holmes-Kit] the command accesses Holmes authority or semantic-egress configuration — requires operator approval'
|
|
1461
|
+
: providerCredential
|
|
1462
|
+
? '[Holmes-Kit] the command accesses a protected provider credential — requires operator approval'
|
|
1463
|
+
: '[Holmes-Kit] command reads or dumps process environment (holds out-of-band approval secrets) — requires operator approval';
|
|
1464
|
+
const resolved = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'config-write', target: command }, nowTs);
|
|
1465
|
+
if (!resolved) {
|
|
1466
|
+
let hint = (0, approval_queue_1.queueHint)(opts.projectRoot, { kind: 'config-write', target: command, why: reason });
|
|
1467
|
+
// The queue deliberately suppresses duplicate writes, not the pending operator decision.
|
|
1468
|
+
const id = (0, approval_queue_1.approvalRequestId)('config-write', command);
|
|
1469
|
+
if (!hint && (0, approval_queue_1.readQueue)(opts.projectRoot).pending.some((request) => request.id === id)) {
|
|
1470
|
+
hint = ` — approval request ${id} is pending; retry after operator approval`;
|
|
1471
|
+
}
|
|
1472
|
+
return { permissionDecision: 'deny', permissionDecisionReason: reason
|
|
1473
|
+
+ (hint || ' — could not persist the approval request; ask the operator to check the project approval queue storage') };
|
|
1474
|
+
}
|
|
1475
|
+
pendingApprovals.push(resolved);
|
|
1476
|
+
}
|
|
1477
|
+
}
|
|
1478
|
+
if (!legacySessionApproval) {
|
|
1226
1479
|
// (b) Shell-writing hook/approval CONFIG (the F6a surface, previously Write/Edit-only).
|
|
1227
1480
|
// @implements A-SPEC-191 §28 (round 13) — the rule matched only redirection and `tee`, and
|
|
1228
1481
|
// `cp`, `mv`, `install`, `ln -f`, `dd of=`, `rsync` and `sed -i` write the same file just as
|
|
@@ -1415,8 +1668,7 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1415
1668
|
const liftByConfigWrite = (why) => {
|
|
1416
1669
|
const r = (0, approval_grants_1.resolveApproval)(opts.projectRoot, approval, { kind: 'config-write', target: command }, nowTs);
|
|
1417
1670
|
if (r !== undefined) {
|
|
1418
|
-
|
|
1419
|
-
(0, approval_grants_1.consumeGrantFile)(opts.projectRoot, r.approval.nonce);
|
|
1671
|
+
pendingApprovals.push(r);
|
|
1420
1672
|
return null;
|
|
1421
1673
|
}
|
|
1422
1674
|
return { permissionDecision: 'deny', permissionDecisionReason: `[Holmes-Kit] ${why} — an out-of-band approval that includes config-write is required (A-SPEC-728)`
|
|
@@ -1593,6 +1845,52 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
1593
1845
|
}
|
|
1594
1846
|
}
|
|
1595
1847
|
}
|
|
1848
|
+
if (pendingApprovals.length > 0) {
|
|
1849
|
+
const deny = (why) => ({ permissionDecision: 'deny',
|
|
1850
|
+
permissionDecisionReason: `[Holmes-Kit] ${why}` });
|
|
1851
|
+
// @implements A-SPEC-477.1 — a later invalid approval must not spend an earlier valid one.
|
|
1852
|
+
// Validate the complete set, then check all replays and append under ONE existing ledger hold.
|
|
1853
|
+
// This coordinates validation; it does not promise rollback after an I/O failure during append.
|
|
1854
|
+
if (pendingApprovals.some(({ approval }) => (0, provenance_chain_1.blankNonce)(approval.nonce))) {
|
|
1855
|
+
return deny('the approval declared single-use (nonce) but the value is empty — single-use cannot be enforced, so it is denied');
|
|
1856
|
+
}
|
|
1857
|
+
const ledgerFile = (0, ledger_store_2.writerChainFile)(path.join(opts.projectRoot, '.ax', 'ledger'));
|
|
1858
|
+
const unique = new Map(pendingApprovals.filter(({ approval }) => !!approval.nonce)
|
|
1859
|
+
.map(({ approval }) => [approval.nonce, approval]));
|
|
1860
|
+
const check = () => {
|
|
1861
|
+
const conflict = (0, ledger_store_2.ledgerConflictReason)(path.dirname(ledgerFile));
|
|
1862
|
+
if (conflict)
|
|
1863
|
+
return conflict;
|
|
1864
|
+
const consumed = (0, ledger_store_2.nonceConsumedIn)(ledgerFile);
|
|
1865
|
+
if ([...unique.keys()].some(consumed))
|
|
1866
|
+
return 'single-use approval already consumed (replay)';
|
|
1867
|
+
return null;
|
|
1868
|
+
};
|
|
1869
|
+
try {
|
|
1870
|
+
const chain = new provenance_chain_1.ProvenanceChain(ledgerFile);
|
|
1871
|
+
const failure = unique.size === 0 ? check() : (0, ledger_lock_1.withLedgerLock)(ledgerFile, () => {
|
|
1872
|
+
const reason = check();
|
|
1873
|
+
if (reason)
|
|
1874
|
+
return reason;
|
|
1875
|
+
for (const [nonce, acting] of unique)
|
|
1876
|
+
chain.appendInsideLock({
|
|
1877
|
+
ts: nowTs, actor: acting.actor, kind: 'nonce-consumed',
|
|
1878
|
+
summary: `consumed single-use approval for: ${(0, provenance_chain_1.redactTarget)('command', command)}`.slice(0, 200),
|
|
1879
|
+
inputs: [(0, provenance_chain_1.nonceFingerprint)(nonce)], rationale: acting.rationale, authorization: (0, provenance_chain_1.authorizationRef)(acting.actor, acting.token),
|
|
1880
|
+
});
|
|
1881
|
+
return null;
|
|
1882
|
+
}, { onStaleBreak: chain.staleBreakRecorder() });
|
|
1883
|
+
if (failure)
|
|
1884
|
+
return deny(failure);
|
|
1885
|
+
}
|
|
1886
|
+
catch (err) {
|
|
1887
|
+
return deny(`could not obtain exclusive ledger access to spend the single-use approval (${err instanceof Error ? err.message : String(err)})`);
|
|
1888
|
+
}
|
|
1889
|
+
for (const { source, approval } of pendingApprovals) {
|
|
1890
|
+
if (source === 'grant' && approval.nonce)
|
|
1891
|
+
(0, approval_grants_1.consumeGrantFile)(opts.projectRoot, approval.nonce);
|
|
1892
|
+
}
|
|
1893
|
+
}
|
|
1596
1894
|
// auto/notify/confirm, or hard-hitl with a valid approval: this slice blocks only
|
|
1597
1895
|
// hard-hitl; confirm is advisory here.
|
|
1598
1896
|
return { permissionDecision: 'allow' };
|
|
@@ -2254,12 +2552,25 @@ function evaluateHook(input, specsDir, opts) {
|
|
|
2254
2552
|
// new CODE must not be layered on top of it. WRITE_TEST and spec authoring stay open — you must be
|
|
2255
2553
|
// able to fix the tests/specs that clear the debt. A covering approval overrides; a clean Stop
|
|
2256
2554
|
// clears the debt and code resumes.
|
|
2555
|
+
//
|
|
2556
|
+
// @implements A-SPEC-134.1 — measured 2026-10-04: an open critical (ART-7) became debt, its fix was sealed source
|
|
2557
|
+
// work, and this branch refused every edit that fixes it; the refusal filed no request, so neither the session nor
|
|
2558
|
+
// `holmes-kit approve` could act. (1) Debt that is ART-7 alone does not deny: a critical is cleared only by changing
|
|
2559
|
+
// source, and every other gate still judges the write. (2) Any other debt denies as before, and (3) that denial is
|
|
2560
|
+
// grantable — a queue grant for this exact path lifts THIS branch only (the seal, role, scope and evidence gates
|
|
2561
|
+
// keep `codeWriteCovered`, the environment approval); it is not consumed, so a fix of several edits is one operator
|
|
2562
|
+
// act per file. The refusal files the request and prints its id and the operator command.
|
|
2257
2563
|
if (action === 'WRITE_CODE' && !codeWriteCovered) {
|
|
2258
2564
|
const debt = (0, constitution_debt_1.readDebt)(projectRoot);
|
|
2259
|
-
|
|
2565
|
+
const cureOnly = !!debt && debt.length > 0 && debt.every((a) => a === 'ART-7');
|
|
2566
|
+
if (debt && debt.length > 0 && !cureOnly
|
|
2567
|
+
&& (0, approval_grants_1.resolveApproval)(projectRoot, weApproval, { kind: 'code-write', target: relPath }, nowTs) === undefined) {
|
|
2568
|
+
const why = `code write under constitution debt (${debt.join(', ')})`;
|
|
2260
2569
|
return {
|
|
2261
2570
|
permissionDecision: 'deny',
|
|
2262
|
-
permissionDecisionReason: `[Holmes-Kit] constitution-debt outstanding (${debt.join(', ')}) — resolve the constitution (a clean turn clears it) before writing new code, or supply a covering approval
|
|
2571
|
+
permissionDecisionReason: `[Holmes-Kit] constitution-debt outstanding (${debt.join(', ')}) — resolve the constitution (a clean turn clears it) before writing new code, or supply a covering approval`
|
|
2572
|
+
+ ((0, approval_queue_1.queueHint)(projectRoot, { kind: 'code-write', target: relPath, why })
|
|
2573
|
+
|| ' — could not persist the approval request; ask the operator to check the project approval queue storage'),
|
|
2263
2574
|
};
|
|
2264
2575
|
}
|
|
2265
2576
|
}
|
|
@@ -2541,7 +2852,7 @@ if (require.main === module) {
|
|
|
2541
2852
|
// trail was the one artefact guaranteed to accumulate the secrets the gate protects.
|
|
2542
2853
|
// `summary` keeps the human-readable classification, which is the auditable part.
|
|
2543
2854
|
summary: out.permissionDecision === 'deny'
|
|
2544
|
-
? (out.permissionDecisionReason ?? 'denied')
|
|
2855
|
+
? ledgerSummaryOf(out.permissionDecisionReason ?? 'denied')
|
|
2545
2856
|
: `approved action: ${input.tool_name} ${target}`.slice(0, 300),
|
|
2546
2857
|
// @implements A-SPEC-133 — a master-key use becomes an audit line: the approval's
|
|
2547
2858
|
// narrowing (or its absence) travels with the record (r7-191: promised, never shipped).
|
|
@@ -406,7 +406,15 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
|
|
|
406
406
|
root: string;
|
|
407
407
|
base?: string;
|
|
408
408
|
head?: string;
|
|
409
|
-
since
|
|
409
|
+
since
|
|
410
|
+
/**
|
|
411
|
+
* A root the caller named that this process cannot read is the CALLER'S mistake, not a fault.
|
|
412
|
+
* @implements A-SPEC-189 §10 (round 11)
|
|
413
|
+
*/
|
|
414
|
+
? /**
|
|
415
|
+
* A root the caller named that this process cannot read is the CALLER'S mistake, not a fault.
|
|
416
|
+
* @implements A-SPEC-189 §10 (round 11)
|
|
417
|
+
*/: string;
|
|
410
418
|
}) => Promise<{
|
|
411
419
|
requirementSemanticWarm?: {
|
|
412
420
|
tier: string;
|
|
@@ -38,7 +38,8 @@ exports.isHandlerRefusal = isHandlerRefusal;
|
|
|
38
38
|
exports.unreadableAmong = unreadableAmong;
|
|
39
39
|
exports.makeHandlers = makeHandlers;
|
|
40
40
|
exports.collectDecisions = collectDecisions;
|
|
41
|
-
// @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732
|
|
41
|
+
// @implements A-SPEC-723, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754
|
|
42
|
+
const operator_recovery_1 = require("./operator-recovery");
|
|
42
43
|
// @implements A-SPEC-643
|
|
43
44
|
// @implements A-SPEC-642
|
|
44
45
|
// @implements A-SPEC-642
|
|
@@ -213,7 +214,7 @@ function resolveHandlerApproval(rootArg, store, envApproval, action, now) {
|
|
|
213
214
|
const r = (0, approval_grants_1.resolveApproval)(root, envApproval, action, now);
|
|
214
215
|
return r ? { ...r, root } : undefined;
|
|
215
216
|
}
|
|
216
|
-
function refusalQueueHint(rootArg, store, req) {
|
|
217
|
+
function refusalQueueHint(rootArg, store, req, operation) {
|
|
217
218
|
try {
|
|
218
219
|
// The SpecStore interface carries no root; the file-backed store exposes one. A store without a
|
|
219
220
|
// root files nothing — the queue lives on disk, and with no disk location there is nothing to do.
|
|
@@ -221,7 +222,8 @@ function refusalQueueHint(rootArg, store, req) {
|
|
|
221
222
|
const base = rootArg !== undefined ? rootArg : (typeof storeRoot === 'string' ? storeRoot : undefined);
|
|
222
223
|
if (base === undefined)
|
|
223
224
|
return '';
|
|
224
|
-
|
|
225
|
+
const root = projectRootOf(base);
|
|
226
|
+
return (0, approval_queue_1.queueHint)(root, req, (0, operator_recovery_1.operatorRecovery)(root, req.target, operation));
|
|
225
227
|
}
|
|
226
228
|
catch {
|
|
227
229
|
return '';
|
|
@@ -873,7 +875,7 @@ function makeRawHandlers(store, opts) {
|
|
|
873
875
|
prepareHostApproval,
|
|
874
876
|
consumeHostApproval,
|
|
875
877
|
resolveHandlerApproval: (root, approval, action, now) => resolveHandlerApproval(root, store, approval, action, now),
|
|
876
|
-
refusalQueueHint: (root, request) => refusalQueueHint(root, store, request),
|
|
878
|
+
refusalQueueHint: (root, request) => refusalQueueHint(root, store, request, 'spec_approve'),
|
|
877
879
|
foreignRootReason: (root) => foreignRootReason(store, root),
|
|
878
880
|
});
|
|
879
881
|
/**
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** Formatting only: the caller must return pending text only after a successful enqueue. */
|
|
2
|
+
export declare function operatorRecovery(root: string, target: string, operation?: string, options?: {
|
|
3
|
+
platform?: NodeJS.Platform;
|
|
4
|
+
executable?: string;
|
|
5
|
+
cli?: string;
|
|
6
|
+
}): {
|
|
7
|
+
reviewCommand: string;
|
|
8
|
+
pendingHint(id: string): string;
|
|
9
|
+
};
|