claude-dev-env 8.117.2 → 8.117.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/_shared/pr-loop/scripts/pyproject.toml +1 -1
  2. package/_shared/process-tree/scripts/pyproject.toml +1 -1
  3. package/bin/cde.mjs +4 -3
  4. package/bin/cde.test.mjs +87 -1
  5. package/bin/codex-compat.mjs +4 -3
  6. package/bin/codex-compat.test.mjs +91 -1
  7. package/bin/install-plan.mjs +2 -1
  8. package/bin/install.mjs +24 -7
  9. package/bin/install.plan.test.mjs +15 -0
  10. package/bin/install.test.mjs +61 -0
  11. package/bin/python-probe.mjs +42 -0
  12. package/bin/python-probe.test.mjs +19 -2
  13. package/docs/rule-guides/features-start-with-an-eval.md +3 -3
  14. package/docs/rule-guides/proof-before-pull-request.md +2 -2
  15. package/hooks/blocking/bash_pre_tool_use_dispatcher.py +11 -4
  16. package/hooks/blocking/build_eval_before_eval_write_gate.py +10 -4
  17. package/hooks/blocking/followup_pr_dedupe.py +381 -64
  18. package/hooks/blocking/gate_child_process.py +187 -0
  19. package/hooks/blocking/gate_run_reads.py +116 -35
  20. package/hooks/blocking/merge_review_gate.py +93 -10
  21. package/hooks/blocking/merge_review_gate_parts/create_folders.py +346 -0
  22. package/hooks/blocking/merge_review_gate_parts/create_options.py +86 -0
  23. package/hooks/blocking/merge_review_gate_parts/folder_state.py +107 -0
  24. package/hooks/blocking/merge_review_gate_parts/open_request.py +199 -64
  25. package/hooks/blocking/merge_review_gate_parts/quoted_lines.py +283 -0
  26. package/hooks/blocking/merge_review_gate_parts/wrapped_creates.py +126 -0
  27. package/hooks/blocking/pr_lifecycle_skill_gate.py +61 -18
  28. package/hooks/blocking/pre_tool_use_dispatcher.py +25 -3
  29. package/hooks/blocking/pull_request_proof.py +5 -51
  30. package/hooks/blocking/pull_request_proof_edit_gate.py +19 -5
  31. package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +54 -0
  32. package/hooks/blocking/test_build_eval_before_eval_write_gate.py +64 -0
  33. package/hooks/blocking/test_followup_pr_dedupe.py +464 -1
  34. package/hooks/blocking/test_gate_child_process.py +64 -0
  35. package/hooks/blocking/test_gate_run_reads.py +364 -4
  36. package/hooks/blocking/test_merge_review_gate.py +832 -39
  37. package/hooks/blocking/test_pr_lifecycle_skill_gate.py +130 -4
  38. package/hooks/blocking/test_pre_tool_use_dispatcher.py +64 -0
  39. package/hooks/blocking/test_pull_request_proof.py +16 -0
  40. package/hooks/blocking/test_pull_request_proof_edit_gate.py +60 -0
  41. package/hooks/blocking/tests/test_create_folders.py +290 -0
  42. package/hooks/blocking/tests/test_create_options.py +34 -0
  43. package/hooks/blocking/tests/test_folder_state.py +40 -0
  44. package/hooks/blocking/tests/test_open_request.py +350 -44
  45. package/hooks/blocking/tests/test_quoted_lines.py +86 -0
  46. package/hooks/blocking/tests/test_wrapped_creates.py +42 -0
  47. package/hooks/features/bash-dispatchers.md +1 -1
  48. package/hooks/features/conduct-gates.md +7 -7
  49. package/hooks/features/write-edit-blocking.md +3 -3
  50. package/hooks/hooks_constants/build_eval_before_eval_write_gate_constants.py +5 -0
  51. package/hooks/hooks_constants/followup_pr_dedupe_constants.py +34 -1
  52. package/hooks/hooks_constants/gate_fault.py +52 -0
  53. package/hooks/hooks_constants/gate_fault_constants.py +13 -0
  54. package/hooks/hooks_constants/gate_run_reads_constants.py +9 -1
  55. package/hooks/hooks_constants/merge_review_gate_constants.py +94 -1
  56. package/hooks/hooks_constants/piped_pytest_blocker_constants.py +2 -0
  57. package/hooks/hooks_constants/pr_lifecycle_skill_gate_constants.py +6 -1
  58. package/hooks/hooks_constants/pre_tool_use_stdin.py +23 -3
  59. package/hooks/hooks_constants/shell_command_pipeline.py +68 -8
  60. package/hooks/hooks_constants/shell_command_segments.py +2 -2
  61. package/hooks/hooks_constants/shell_command_wrappers.py +3 -2
  62. package/hooks/hooks_constants/test_followup_pr_dedupe_constants.py +7 -0
  63. package/hooks/hooks_constants/test_gate_fault.py +41 -0
  64. package/hooks/hooks_constants/test_piped_pytest_blocker_constants.py +5 -0
  65. package/hooks/hooks_constants/test_pr_lifecycle_skill_gate_constants.py +10 -0
  66. package/hooks/hooks_constants/test_pre_tool_use_stdin.py +97 -0
  67. package/hooks/hooks_constants/test_shell_command_pipeline.py +55 -0
  68. package/hooks/hooks_constants/test_shell_command_segments.py +15 -0
  69. package/hooks/hooks_constants/test_shell_command_wrappers.py +6 -0
  70. package/hooks/hooks_constants/transcript_skill_scan_constants.py +6 -0
  71. package/hooks/pyproject.toml +2 -3
  72. package/hooks/test_python_floor.py +197 -0
  73. package/hooks/test_transcript_skill_scan.py +324 -0
  74. package/hooks/transcript_skill_scan.py +233 -2
  75. package/hooks/validators/code_quality_checks.py +119 -17
  76. package/hooks/validators/test_code_quality_checks.py +110 -4
  77. package/package.json +1 -1
@@ -5,7 +5,7 @@
5
5
 
6
6
  [tool.mypy]
7
7
  mypy_path = "."
8
- python_version = "3.13"
8
+ python_version = "3.11"
9
9
  ignore_missing_imports = true
10
10
  warn_unused_ignores = false
11
11
  warn_redundant_casts = true
@@ -5,7 +5,7 @@
5
5
 
6
6
  [tool.mypy]
7
7
  mypy_path = ".:config"
8
- python_version = "3.13"
8
+ python_version = "3.11"
9
9
  ignore_missing_imports = true
10
10
  warn_unused_ignores = true
11
11
  warn_redundant_casts = true
package/bin/cde.mjs CHANGED
@@ -1,8 +1,9 @@
1
1
  #!/usr/bin/env node
2
- import { spawn, spawnSync } from "node:child_process";
2
+ import { spawn } from "node:child_process";
3
3
  import { constants as osConstants } from "node:os";
4
4
  import { fileURLToPath } from "node:url";
5
5
  import path from "node:path";
6
+ import { MINIMUM_PYTHON_VERSION, pythonCommandMeetsFloor } from "./python-probe.mjs";
6
7
 
7
8
  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
8
9
  const lintScriptPath = path.join(packageRoot, "scripts", "cde_lint.py");
@@ -60,7 +61,7 @@ export function pythonInterpreterNames(platformName = process.platform) {
60
61
 
61
62
  export function findPython(
62
63
  commandNames = pythonInterpreterNames(),
63
- canRun = (commandName) => spawnSync(commandName, ["--version"], { stdio: "ignore", shell: false }).status === 0,
64
+ canRun = pythonCommandMeetsFloor,
64
65
  ) {
65
66
  for (const eachCommand of commandNames) {
66
67
  if (canRun(eachCommand)) return eachCommand;
@@ -224,7 +225,7 @@ export async function main(argumentsList = process.argv.slice(2), dependencies =
224
225
  const resolvePython = dependencies.findPython ?? findPython;
225
226
  const interpreter = interpreterOverride ?? process.env[pythonEnvironmentName] ?? await resolvePython();
226
227
  if (!interpreter) {
227
- process.stderr.write("No usable Python interpreter found. Use --python or CDE_PYTHON.\n");
228
+ process.stderr.write(`No usable Python ${MINIMUM_PYTHON_VERSION}+ interpreter found. Use --python or CDE_PYTHON.\n`);
228
229
  return 2;
229
230
  }
230
231
  const command = buildCommandByName[argumentsList[0]](interpreter, remainingArguments);
package/bin/cde.test.mjs CHANGED
@@ -1,5 +1,6 @@
1
1
  import { EventEmitter } from "node:events";
2
- import { readFileSync } from "node:fs";
2
+ import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
3
4
  import { fileURLToPath } from "node:url";
4
5
  import assert from "node:assert/strict";
5
6
  import path from "node:path";
@@ -294,3 +295,88 @@ test("help names the followup command", () => {
294
295
  assert.match(createHelpText(), /cde followup count/);
295
296
  assert.match(createHelpText(), /cde followup dedupe +Give each finding its own file, once/);
296
297
  });
298
+
299
+
300
+ const posixShellStubSkip = process.platform === "win32" ? "the Python stubs are POSIX shell scripts" : false;
301
+
302
+
303
+ async function withStubPythons(versionByName, overrideEnvironmentName, action) {
304
+ const stubDirectory = mkdtempSync(path.join(tmpdir(), "launcher-python-stub-"));
305
+ for (const [eachName, eachVersion] of Object.entries(versionByName)) {
306
+ const stubPath = path.join(stubDirectory, eachName);
307
+ writeFileSync(stubPath, `#!/bin/sh\necho "${eachVersion}"\n`);
308
+ chmodSync(stubPath, 0o755);
309
+ }
310
+ const originalPath = process.env.PATH;
311
+ const originalOverride = process.env[overrideEnvironmentName];
312
+ process.env.PATH = stubDirectory;
313
+ delete process.env[overrideEnvironmentName];
314
+ try {
315
+ return await action(stubDirectory);
316
+ } finally {
317
+ process.env.PATH = originalPath;
318
+ if (originalOverride !== undefined) process.env[overrideEnvironmentName] = originalOverride;
319
+ rmSync(stubDirectory, { recursive: true, force: true });
320
+ }
321
+ }
322
+
323
+
324
+ async function captureStandardError(action) {
325
+ const allMessages = [];
326
+ const originalWrite = process.stderr.write;
327
+ process.stderr.write = (message) => {
328
+ allMessages.push(String(message));
329
+ return true;
330
+ };
331
+ try {
332
+ const exitCode = await action();
333
+ return { exitCode, standardError: allMessages.join("") };
334
+ } finally {
335
+ process.stderr.write = originalWrite;
336
+ }
337
+ }
338
+
339
+
340
+ test("findPython skips a python3 below the floor and picks the next interpreter at the floor", { skip: posixShellStubSkip }, async () => {
341
+ const selectedName = await withStubPythons(
342
+ { python3: "Python 3.9.0", python: "Python 3.11.0" },
343
+ "CDE_PYTHON",
344
+ () => findPython(),
345
+ );
346
+ assert.equal(selectedName, "python");
347
+ });
348
+
349
+
350
+ test("no interpreter at the floor prints the floor and runs nothing", { skip: posixShellStubSkip }, async () => {
351
+ let wasRun = false;
352
+ const { exitCode, standardError } = await withStubPythons(
353
+ { python3: "Python 3.9.0", python: "Python 3.10.4" },
354
+ "CDE_PYTHON",
355
+ () => captureStandardError(() => main(["lint", "--staged"], {
356
+ runCommand: async () => {
357
+ wasRun = true;
358
+ return 0;
359
+ },
360
+ })),
361
+ );
362
+ assert.equal(exitCode, 2);
363
+ assert.match(standardError, /No usable Python 3\.11\+ interpreter found/);
364
+ assert.equal(wasRun, false);
365
+ });
366
+
367
+
368
+ test("an explicit python override below the floor is still honored", { skip: posixShellStubSkip }, async () => {
369
+ let receivedCommand;
370
+ const exitCode = await withStubPythons(
371
+ { python3: "Python 3.9.0" },
372
+ "CDE_PYTHON",
373
+ (stubDirectory) => main(["lint", "--python", path.join(stubDirectory, "python3"), "--staged"], {
374
+ runCommand: async (command) => {
375
+ receivedCommand = command;
376
+ return 0;
377
+ },
378
+ }),
379
+ );
380
+ assert.equal(exitCode, 0);
381
+ assert.match(receivedCommand.executable, /python3$/);
382
+ });
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
- import { spawn, spawnSync } from "node:child_process";
2
+ import { spawn } from "node:child_process";
3
3
  import { fileURLToPath } from "node:url";
4
4
  import path from "node:path";
5
+ import { MINIMUM_PYTHON_VERSION, pythonCommandMeetsFloor } from "./python-probe.mjs";
5
6
 
6
7
  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
7
8
  const materializerPath = path.join(packageRoot, "scripts", "codex_compat_materializer.py");
@@ -65,7 +66,7 @@ export function buildCommand(commandName, argumentsList, interpreter) {
65
66
  throw new Error(`Unknown command: ${commandName}`);
66
67
  }
67
68
 
68
- export function findPython(commandNames = pythonNames, canRun = (command) => spawnSync(command, ["--version"], { stdio: "ignore" }).status === 0) {
69
+ export function findPython(commandNames = pythonNames, canRun = pythonCommandMeetsFloor) {
69
70
  for (const eachCommand of commandNames) {
70
71
  if (canRun(eachCommand)) return eachCommand;
71
72
  }
@@ -89,7 +90,7 @@ export async function main(argumentsList = process.argv.slice(2), dependencies =
89
90
  try {
90
91
  const interpreter = readOption(commandArguments, "--python") ?? process.env.CODEX_COMPAT_PYTHON ?? await (dependencies.findPython ?? findPython)();
91
92
  if (!interpreter) {
92
- writeErrorRecord("python_unavailable", "No usable Python interpreter found. Use --python or CODEX_COMPAT_PYTHON.");
93
+ writeErrorRecord("python_unavailable", `No usable Python ${MINIMUM_PYTHON_VERSION}+ interpreter found. Use --python or CODEX_COMPAT_PYTHON.`);
93
94
  return 1;
94
95
  }
95
96
  const command = buildCommand(commandName, commandArguments, interpreter);
@@ -1,6 +1,9 @@
1
1
  import test from "node:test";
2
2
  import assert from "node:assert/strict";
3
- import { buildCommand, createHelpText, main } from "./codex-compat.mjs";
3
+ import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import path from "node:path";
6
+ import { buildCommand, createHelpText, findPython, main } from "./codex-compat.mjs";
4
7
 
5
8
  test("help describes both compatibility commands", () => {
6
9
  assert.match(createHelpText(), /materialize/);
@@ -49,3 +52,90 @@ test("bridge forwarding and child status use injected runners", async () => {
49
52
  assert.equal(receivedCommand.executable, "python-test");
50
53
  assert.equal(receivedCommand.arguments.at(-1), '{"name":"ship","status":"pending"}');
51
54
  });
55
+
56
+
57
+ const posixShellStubSkip = process.platform === "win32" ? "the Python stubs are POSIX shell scripts" : false;
58
+
59
+
60
+ async function withStubPythons(versionByName, overrideEnvironmentName, action) {
61
+ const stubDirectory = mkdtempSync(path.join(tmpdir(), "launcher-python-stub-"));
62
+ for (const [eachName, eachVersion] of Object.entries(versionByName)) {
63
+ const stubPath = path.join(stubDirectory, eachName);
64
+ writeFileSync(stubPath, `#!/bin/sh\necho "${eachVersion}"\n`);
65
+ chmodSync(stubPath, 0o755);
66
+ }
67
+ const originalPath = process.env.PATH;
68
+ const originalOverride = process.env[overrideEnvironmentName];
69
+ process.env.PATH = stubDirectory;
70
+ delete process.env[overrideEnvironmentName];
71
+ try {
72
+ return await action(stubDirectory);
73
+ } finally {
74
+ process.env.PATH = originalPath;
75
+ if (originalOverride !== undefined) process.env[overrideEnvironmentName] = originalOverride;
76
+ rmSync(stubDirectory, { recursive: true, force: true });
77
+ }
78
+ }
79
+
80
+
81
+ async function captureStandardError(action) {
82
+ const allMessages = [];
83
+ const originalWrite = process.stderr.write;
84
+ process.stderr.write = (message) => {
85
+ allMessages.push(String(message));
86
+ return true;
87
+ };
88
+ try {
89
+ const exitCode = await action();
90
+ return { exitCode, standardError: allMessages.join("") };
91
+ } finally {
92
+ process.stderr.write = originalWrite;
93
+ }
94
+ }
95
+
96
+
97
+ test("findPython skips a python3 below the floor and picks the next interpreter at the floor", { skip: posixShellStubSkip }, async () => {
98
+ const selectedName = await withStubPythons(
99
+ { python3: "Python 3.9.0", python: "Python 3.11.0" },
100
+ "CODEX_COMPAT_PYTHON",
101
+ () => findPython(),
102
+ );
103
+ assert.equal(selectedName, "python");
104
+ });
105
+
106
+
107
+ test("no interpreter at the floor reports the floor and runs nothing", { skip: posixShellStubSkip }, async () => {
108
+ let wasRun = false;
109
+ const { exitCode, standardError } = await withStubPythons(
110
+ { python3: "Python 3.9.0", python: "Python 3.10.4" },
111
+ "CODEX_COMPAT_PYTHON",
112
+ () => captureStandardError(() => main(["bridge", "--surface", "TaskCreate", "--payload", "{}"], {
113
+ runCommand: async () => {
114
+ wasRun = true;
115
+ return 0;
116
+ },
117
+ })),
118
+ );
119
+ assert.equal(exitCode, 1);
120
+ const errorRecord = JSON.parse(standardError).error;
121
+ assert.equal(errorRecord.code, "python_unavailable");
122
+ assert.match(errorRecord.message, /No usable Python 3\.11\+ interpreter found/);
123
+ assert.equal(wasRun, false);
124
+ });
125
+
126
+
127
+ test("an explicit python override below the floor is still honored", { skip: posixShellStubSkip }, async () => {
128
+ let receivedCommand;
129
+ const exitCode = await withStubPythons(
130
+ { python3: "Python 3.9.0" },
131
+ "CODEX_COMPAT_PYTHON",
132
+ (stubDirectory) => main(["bridge", "--python", path.join(stubDirectory, "python3"), "--surface", "TaskCreate", "--payload", "{}"], {
133
+ runCommand: async (command) => {
134
+ receivedCommand = command;
135
+ return 0;
136
+ },
137
+ }),
138
+ );
139
+ assert.equal(exitCode, 0);
140
+ assert.match(receivedCommand.executable, /python3$/);
141
+ });
@@ -19,6 +19,7 @@
19
19
  import { existsSync, readFileSync, statSync } from 'node:fs';
20
20
  import { join } from 'node:path';
21
21
  import { SETTINGS_FILE_NAME } from './install-constants.mjs';
22
+ import { MINIMUM_PYTHON_VERSION } from './python-probe.mjs';
22
23
  import {
23
24
  emptyManagedPermissions,
24
25
  managedPermissionsFromPackageSettings,
@@ -34,7 +35,7 @@ export const PREFLIGHT_ERROR_CODES = Object.freeze({
34
35
  });
35
36
 
36
37
  export const MISSING_PYTHON_ERROR_MESSAGE =
37
- 'ERROR: No usable Python 3 found. Install Python 3.8+ from python.org and ensure py, python3, or python is on PATH. On Windows the Microsoft Store python.exe alias is rejected because it cannot run hooks.';
38
+ `ERROR: No usable Python 3 found. Install Python ${MINIMUM_PYTHON_VERSION}+ from python.org and ensure py, python3, or python is on PATH. On Windows the Microsoft Store python.exe alias is rejected because it cannot run hooks.`;
38
39
 
39
40
  export const MALFORMED_SETTINGS_ERROR_MESSAGE =
40
41
  'ERROR: settings.json is malformed JSON. Fix it and rerun.';
package/bin/install.mjs CHANGED
@@ -152,7 +152,7 @@ import {
152
152
  splitUnreadableProfileSettings,
153
153
  unparsedSettingsMayHoldGate,
154
154
  } from './profile-stop-gate.mjs';
155
- import { pythonExecutableProbeCommand } from './python-probe.mjs';
155
+ import { pythonExecutableProbeCommand, pythonVersionMeetsFloor } from './python-probe.mjs';
156
156
 
157
157
  const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
158
158
  const INSTALL_ROOT_RESOLUTION = resolveInstallRoot({
@@ -594,8 +594,23 @@ function quoteStandalonePluginRootHookPath(commandString, pluginRootForward) {
594
594
  );
595
595
  }
596
596
 
597
+ export { pythonVersionMeetsFloor };
598
+
599
+ /**
600
+ * Runs one Python probe command and returns its trimmed standard output.
601
+ *
602
+ * @param {string} commandLine The shell command to run.
603
+ * @returns {string} The trimmed output.
604
+ */
605
+ function runPythonProbe(commandLine) {
606
+ return execSync(commandLine, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: PYTHON_PROBE_TIMEOUT_MILLISECONDS }).trim();
607
+ }
608
+
597
609
  /**
598
610
  * Picks the interpreter command baked into every managed hook in settings.json.
611
+ * A candidate below the package Python floor (MINIMUM_PYTHON_VERSION) is
612
+ * skipped, so an install on an older Python stops with the missing-Python
613
+ * message and installs no hooks that cannot start there.
599
614
  * On win32 the first working candidate is resolved to its absolute
600
615
  * sys.executable and that path is baked in, so a later PATH change or Microsoft
601
616
  * Store update that re-points the `py`/`python` launcher cannot silently break
@@ -604,16 +619,18 @@ function quoteStandalonePluginRootHookPath(commandString, pluginRootForward) {
604
619
  * runs from cannot slow or change it. Other platforms keep the bare command
605
620
  * (e.g. `python3`).
606
621
  *
622
+ * @param {(commandLine: string) => string} [runProbe] Runs one probe command and returns its output.
623
+ * @param {string} [platform] The platform whose candidates and path rules apply.
607
624
  * @returns {string|null} The interpreter command, or null when none is usable.
608
625
  */
609
- export function detectPython() {
610
- const candidates = pythonCandidatesForPlatform(process.platform);
626
+ export function detectPython(runProbe = runPythonProbe, platform = process.platform) {
627
+ const candidates = pythonCandidatesForPlatform(platform);
611
628
  for (const { command, versionFlag } of candidates) {
612
629
  try {
613
- const version = execSync(`${command} ${versionFlag}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: PYTHON_PROBE_TIMEOUT_MILLISECONDS }).trim();
614
- if (!version.includes('Python 3.')) continue;
615
- if (process.platform !== 'win32') return command;
616
- const executablePath = execSync(pythonExecutableProbeCommand(command), { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: PYTHON_PROBE_TIMEOUT_MILLISECONDS }).trim();
630
+ const version = runProbe(`${command} ${versionFlag}`);
631
+ if (!pythonVersionMeetsFloor(version)) continue;
632
+ if (platform !== 'win32') return command;
633
+ const executablePath = runProbe(pythonExecutableProbeCommand(command));
617
634
  if (!executablePath || isWindowsStorePythonStub(executablePath)) continue;
618
635
  return interpreterCommandFromPath(executablePath);
619
636
  } catch { /* try next */ }
@@ -73,6 +73,21 @@ function planInput(packageRoot, managedRoot, overrides = {}) {
73
73
  };
74
74
  }
75
75
 
76
+ test('preflight without a Python at the floor names the 3.11 floor in its message', () => {
77
+ const { root, managedRoot, packageRoot } = sandbox();
78
+ try {
79
+ assert.throws(
80
+ () => buildInstallPlan(planInput(packageRoot, managedRoot, {
81
+ detectPythonCommand: () => null,
82
+ })),
83
+ (error) => error.code === PREFLIGHT_ERROR_CODES.MISSING_PYTHON
84
+ && error.message.includes('Install Python 3.11+ from python.org'),
85
+ );
86
+ } finally {
87
+ rmSync(root, { recursive: true, force: true });
88
+ }
89
+ });
90
+
76
91
  test('planShouldInstallHooks covers full, core, and journal', () => {
77
92
  assert.equal(planShouldInstallHooks(null, GROUPS), true);
78
93
  assert.equal(planShouldInstallHooks(['core'], GROUPS), true);
@@ -52,6 +52,7 @@ import {
52
52
  commandNamesOwnedHookScript,
53
53
  hookCommandComparisonSpelling,
54
54
  detectPython,
55
+ pythonVersionMeetsFloor,
55
56
  pythonFileAndPrefixArguments,
56
57
  retainNewestRunBackupOnly,
57
58
  unshippedEverRegisteredHookRelativePaths,
@@ -356,6 +357,66 @@ test('pythonCandidatesForPlatform still offers python as a win32 fallback when p
356
357
  });
357
358
 
358
359
 
360
+ test('pythonVersionMeetsFloor accepts 3.11 and newer and refuses older minors by number', () => {
361
+ assert.equal(pythonVersionMeetsFloor('Python 3.11.0'), true);
362
+ assert.equal(pythonVersionMeetsFloor('Python 3.13.5'), true);
363
+ assert.equal(pythonVersionMeetsFloor('Python 3.10.14'), false);
364
+ assert.equal(pythonVersionMeetsFloor('Python 3.8.10'), false);
365
+ assert.equal(pythonVersionMeetsFloor('Python 3.9.18'), false);
366
+ assert.equal(pythonVersionMeetsFloor('Python 2.7.18'), false);
367
+ assert.equal(pythonVersionMeetsFloor(''), false);
368
+ });
369
+
370
+
371
+ function probeRunnerFromVersions(versionByCommand) {
372
+ const allProbedCommandLines = [];
373
+ const runProbe = (commandLine) => {
374
+ allProbedCommandLines.push(commandLine);
375
+ const matchedCommand = Object.keys(versionByCommand).find(
376
+ (eachCommand) => commandLine === `${eachCommand} --version`,
377
+ );
378
+ if (matchedCommand === undefined) throw new Error(`no stub for ${commandLine}`);
379
+ return versionByCommand[matchedCommand];
380
+ };
381
+ return { runProbe, allProbedCommandLines };
382
+ }
383
+
384
+
385
+ test('detectPython skips a candidate below the floor and takes the next one at the floor', () => {
386
+ const { runProbe, allProbedCommandLines } = probeRunnerFromVersions({
387
+ python3: 'Python 3.8.10',
388
+ python: 'Python 3.11.9',
389
+ });
390
+ assert.equal(detectPython(runProbe, 'linux'), 'python');
391
+ assert.deepEqual(allProbedCommandLines, ['python3 --version', 'python --version']);
392
+ });
393
+
394
+
395
+ test('detectPython takes the first candidate when it is at the floor', () => {
396
+ const { runProbe } = probeRunnerFromVersions({ python3: 'Python 3.11.0' });
397
+ assert.equal(detectPython(runProbe, 'linux'), 'python3');
398
+ });
399
+
400
+
401
+ test('detectPython finds no interpreter when every candidate is below the floor', () => {
402
+ const { runProbe } = probeRunnerFromVersions({
403
+ python3: 'Python 3.8.10',
404
+ python: 'Python 3.10.12',
405
+ 'py -3': 'Python 3.9.2',
406
+ });
407
+ assert.equal(detectPython(runProbe, 'linux'), null);
408
+ });
409
+
410
+
411
+ test('detectPython on win32 never resolves the path of a candidate below the floor', () => {
412
+ const { runProbe, allProbedCommandLines } = probeRunnerFromVersions({
413
+ 'py -3': 'Python 3.8.10',
414
+ });
415
+ assert.equal(detectPython(runProbe, 'win32'), null);
416
+ assert.deepEqual(allProbedCommandLines, ['py -3 --version', 'python --version']);
417
+ });
418
+
419
+
359
420
  test('isWindowsStorePythonStub flags the Microsoft Store WindowsApps alias paths', () => {
360
421
  assert.equal(
361
422
  isWindowsStorePythonStub('C:\\Program Files\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_3.13.3824.0_x64__qbz5n2kfra8p0\\python3.13.exe'),
@@ -1,3 +1,45 @@
1
+ import { spawnSync } from 'node:child_process';
2
+
3
+ export const MINIMUM_PYTHON_VERSION = '3.11';
4
+
5
+ /**
6
+ * Reports whether a `--version` line names a Python at or above the package floor.
7
+ *
8
+ * The floor is MINIMUM_PYTHON_VERSION, the `requires-python` bound of the package.
9
+ * Major and minor compare as numbers, so 3.9 sits below 3.11::
10
+ *
11
+ * 'Python 3.11.0' -> true
12
+ * 'Python 3.9.18' -> false
13
+ * 'Python 2.7.18' -> false
14
+ *
15
+ * @param {string} versionOutput The text a `python --version` probe printed.
16
+ * @returns {boolean} True when the version is at or above the floor.
17
+ */
18
+ export function pythonVersionMeetsFloor(versionOutput) {
19
+ const versionMatch = /Python (\d+)\.(\d+)/.exec(versionOutput);
20
+ if (!versionMatch) return false;
21
+ const [floorMajor, floorMinor] = MINIMUM_PYTHON_VERSION.split('.').map(Number);
22
+ const candidateMajor = Number(versionMatch[1]);
23
+ const candidateMinor = Number(versionMatch[2]);
24
+ if (candidateMajor !== floorMajor) return candidateMajor > floorMajor;
25
+ return candidateMinor >= floorMinor;
26
+ }
27
+
28
+ /**
29
+ * Reports whether a Python command starts and is at or above the package floor.
30
+ *
31
+ * The command runs as `<command> --version` with no shell. It passes when it
32
+ * exits 0 and its standard output names a version at or above
33
+ * MINIMUM_PYTHON_VERSION. A missing command fails.
34
+ *
35
+ * @param {string} commandName The interpreter command or path to probe.
36
+ * @returns {boolean} True when the command meets the floor.
37
+ */
38
+ export function pythonCommandMeetsFloor(commandName) {
39
+ const versionRun = spawnSync(commandName, ['--version'], { encoding: 'utf8', shell: false });
40
+ return versionRun.status === 0 && pythonVersionMeetsFloor(versionRun.stdout ?? '');
41
+ }
42
+
1
43
  /**
2
44
  * Command line for the probe that asks a Python candidate for its absolute
3
45
  * interpreter path.
@@ -1,11 +1,11 @@
1
1
  import { test } from 'node:test';
2
2
  import { strict as assert } from 'node:assert';
3
3
  import { execSync } from 'node:child_process';
4
- import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
4
+ import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
5
5
  import { tmpdir } from 'node:os';
6
6
  import { join } from 'node:path';
7
7
  import { detectPython } from './install.mjs';
8
- import { pythonExecutableProbeCommand } from './python-probe.mjs';
8
+ import { pythonCommandMeetsFloor, pythonExecutableProbeCommand } from './python-probe.mjs';
9
9
 
10
10
  const SHADOWED_STANDARD_LIBRARY_MODULES = ['linecache.py', 'encodings.py', 'site.py', 'os.py'];
11
11
 
@@ -35,3 +35,20 @@ test('the interpreter path probe runs Python in isolated mode', () => {
35
35
  'py -3 -I -c "import sys; print(sys.executable)"',
36
36
  );
37
37
  });
38
+
39
+ test('pythonCommandMeetsFloor accepts an interpreter at the floor and refuses one below it', { skip: process.platform === 'win32' ? 'the Python stubs are POSIX shell scripts' : false }, () => {
40
+ const stubDirectory = mkdtempSync(join(tmpdir(), 'cde-python-floor-'));
41
+ try {
42
+ const atFloorPath = join(stubDirectory, 'at-floor');
43
+ const belowFloorPath = join(stubDirectory, 'below-floor');
44
+ writeFileSync(atFloorPath, '#!/bin/sh\necho "Python 3.11.0"\n');
45
+ writeFileSync(belowFloorPath, '#!/bin/sh\necho "Python 3.9.0"\n');
46
+ chmodSync(atFloorPath, 0o755);
47
+ chmodSync(belowFloorPath, 0o755);
48
+ assert.equal(pythonCommandMeetsFloor(atFloorPath), true);
49
+ assert.equal(pythonCommandMeetsFloor(belowFloorPath), false);
50
+ assert.equal(pythonCommandMeetsFloor(join(stubDirectory, 'missing-python')), false);
51
+ } finally {
52
+ rmSync(stubDirectory, { recursive: true, force: true });
53
+ }
54
+ });
@@ -38,11 +38,11 @@ You own that session's result. Check its pull request, and link it from your own
38
38
 
39
39
  ## Enforcement
40
40
 
41
- `hooks/blocking/pull_request_proof.py` reads each new pull request before it opens, through `pr_lifecycle_skill_gate.py`. A new pull request is a `gh pr create` command, a GitHub MCP create call, or a GitHub MCP `run_workflow` dispatch whose inputs name a `head` branch and a `title`, because that workflow opens the pull request. A pull request whose title starts with `feat` (`feat:`, `feat(scope):`, `feat!:`) is denied when:
41
+ `hooks/blocking/pull_request_proof.py` reads each new pull request before it opens, through `pr_lifecycle_skill_gate.py`. A new pull request is a `gh pr create` command, a `pull_request.py create` command, any other create spelling `followup_pr_dedupe.py` reads (such as `gh pr new` or `gh -R <owner/name> pr create`), a GitHub MCP create call, or a GitHub MCP `run_workflow` dispatch whose inputs name a `head` branch and a `title`, because that workflow opens the pull request. A pull request whose title starts with `feat` (`feat:`, `feat(scope):`, `feat!:`) is denied when:
42
42
 
43
43
  - its body has no "Eval" heading, or the text under that heading names no command in backticks;
44
- - the session's transcript is readable and shows no `claude-api` Skill call with args `build-eval`, and no `/claude-api build-eval` command.
44
+ - the session's transcript is readable and shows no `claude-api` Skill call with args `build-eval`, and no `/claude-api build-eval` command. A scan the gate's 20 s deadline stops counts as none shown, and that deny says to call build-eval again.
45
45
 
46
- `hooks/blocking/build_eval_before_eval_write_gate.py` runs before each Write, Edit, MultiEdit, NotebookEdit, and apply_patch call. It denies a write to an eval file while the session's readable transcript shows no build-eval call. An eval file sits under an `eval`, `evals`, or `hillclimb` folder, or has a file name that starts with `eval` or `evals` before a separator, such as `eval_runner.py`, or carries `.eval.` or `.evals.`, such as `search.eval.json`. Only a Skill call named exactly `claude-api` counts; a plugin-prefixed name such as `plugin:claude-api` does not.
46
+ `hooks/blocking/build_eval_before_eval_write_gate.py` runs before each Write, Edit, MultiEdit, NotebookEdit, and apply_patch call. It denies a write to an eval file while the session's readable transcript shows no build-eval call. Its transcript scan reads the clock before each block and each line, and stops at the first such read after 5 s, so a line already being parsed finishes first. The registered timeout in `hooks.json` is 10 s. A scan ended by that stop, or by a line over 16 MiB, counts as no call shown, and that deny says to call build-eval again. An eval file sits under an `eval`, `evals`, or `hillclimb` folder, or has a file name that starts with `eval` or `evals` before a separator, such as `eval_runner.py`, or carries `.eval.` or `.evals.`, such as `search.eval.json`. Only a Skill call named exactly `claude-api` counts; a plugin-prefixed name such as `plugin:claude-api` does not.
47
47
 
48
48
  The gate checks that the section and the call are there. Whether the eval measures the feature stays a judgment for the author and the reviewer. Edits outside eval files before the build-eval call and the separate session for an existing feature are not checked by a hook, so the agent applies them.
@@ -40,10 +40,10 @@ When you cannot prove it, leave the pull request unopened. Tell the owner in thr
40
40
 
41
41
  ## Enforcement
42
42
 
43
- `hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on `gh pr create`, the `pull_request.py create` script, and each `mcp__*__create_pull_request` tool. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. The gate also denies a section whose only commands run a test runner, such as `pytest`, `python -m unittest`, `uv run pytest`, `npm test`, `npx vitest`, `jest`, `go test` or `cargo test`. Quotes around a runner word, interpreter flags before `-m`, and `coverage run -m unittest` are still test runs. A command is an inline backticked span or a `$ ` line inside a fenced block. A span that starts with a path and line, such as `gate.py:12`, is not a command. A span that holds one path or file name, such as `src/x.py`, is not a command unless that span runs a test runner, such as `py.test` or `pytest.exe`. A test run piped into `tee`, `tail`, `head`, `grep` or `cat` is still a test run. The deny quotes the line "Unit tests are welcome as extra evidence. The live run is the proof." and asks for a run of the changed thing the way its user runs it, without the change and with it. The gate also denies a section whose prose says part of the change is not proven, not tested or not verified, with "yet", "been" or "fully" allowed after the "not", or says unproven, untested or unverified. The line passes only for a workflow file the branch adds, when the body's "After merge" heading plans that file's first run; `pull_request_proof.py` and `hooks_constants/pull_request_proof_constants.py` hold the exact conditions. Otherwise the deny quotes that line, and asks for the run before the pull request opens, or for the line under a "Not covered" heading when the change does not target it. The same denial covers a proof line that opens with "not run", "not exercised" or "not executed" (a "yet" or "been" may follow the "not") or says "has not been run". A proof line with a merge word (merge, merged, merges or merging, so post-merge too) is denied with its own reason: run the check on the branch, and put a file or command name that contains merge in backticks. A step that needs the merged code to exist goes under a "Not covered" heading at the same level as the proof heading, as a line that opens with "not run". `UNPROVEN_ADMISSION_PATTERN` and `MERGE_WORD_PATTERN` list the shapes. Words inside backticks or a fenced block are quoted output and do not count. A section with one command that is not a test run, and no such line, passes. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. A body edit through `update_pull_request`, `gh pr edit` or the `pull_request.py edit` script gets the same checks on its proof section that a new pull request gets, so an edit cannot swap in a proof that a new pull request would be denied. An edit with no proof section passes. The gate also denies a new pull request whose "What this does" section holds no flowchart: a closed `mermaid` block whose first line starts with `flowchart` and that joins two nodes with an arrow. A body edit meets the same check when its body carries a "What this does" heading. A body the gate cannot read passes, such as an inline multi-line `--body`, a body from standard input, or a body written through `gh api`. A `--body-file` that is not a regular file (a pipe, a device or a directory) counts as no body: a create is denied with the request for the body, and an edit passes. Merges and pushes pass.
43
+ `hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on each create spelling `hooks/blocking/followup_pr_dedupe.py` reads, and on each `mcp__*__create_pull_request` tool. The spellings are `gh pr create`, `gh pr new`, `gh` with a root `-R` or `--repo` before `pr`, a `GH_REPO=` prefix, and the `pull_request.py create` script run by any `python`, `python3.x`, `py` or `uv run` launcher, with interpreter options or a path to the script. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. The gate also denies a section whose only commands run a test runner, such as `pytest`, `python -m unittest`, `uv run pytest`, `npm test`, `npx vitest`, `jest`, `go test` or `cargo test`. Quotes around a runner word, interpreter flags before `-m`, and `coverage run -m unittest` are still test runs. A command is an inline backticked span or a `$ ` line inside a fenced block. A span that starts with a path and line, such as `gate.py:12`, is not a command. A span that holds one path or file name, such as `src/x.py`, is not a command unless that span runs a test runner, such as `py.test` or `pytest.exe`. A test run piped into `tee`, `tail`, `head`, `grep` or `cat` is still a test run. The deny quotes the line "Unit tests are welcome as extra evidence. The live run is the proof." and asks for a run of the changed thing the way its user runs it, without the change and with it. The gate also denies a section whose prose says part of the change is not proven, not tested or not verified, with "yet", "been" or "fully" allowed after the "not", or says unproven, untested or unverified. The line passes only for a workflow file the branch adds, when the body's "After merge" heading plans that file's first run; `pull_request_proof.py` and `hooks_constants/pull_request_proof_constants.py` hold the exact conditions. Otherwise the deny quotes that line, and asks for the run before the pull request opens, or for the line under a "Not covered" heading when the change does not target it. The same denial covers a proof line that opens with "not run", "not exercised" or "not executed" (a "yet" or "been" may follow the "not") or says "has not been run". A proof line with a merge word (merge, merged, merges or merging, so post-merge too) is denied with its own reason: run the check on the branch, and put a file or command name that contains merge in backticks. A step that needs the merged code to exist goes under a "Not covered" heading at the same level as the proof heading, as a line that opens with "not run". `UNPROVEN_ADMISSION_PATTERN` and `MERGE_WORD_PATTERN` list the shapes. Words inside backticks or a fenced block are quoted output and do not count. A section with one command that is not a test run, and no such line, passes. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. A body edit through `update_pull_request`, `gh pr edit` or the `pull_request.py edit` script gets the same checks on its proof section that a new pull request gets, so an edit cannot swap in a proof that a new pull request would be denied. An edit with no proof section passes. The gate also denies a new pull request whose "What this does" section holds no flowchart: a closed `mermaid` block whose first line starts with `flowchart` and that joins two nodes with an arrow. A body edit meets the same check when its body carries a "What this does" heading. A body the gate cannot read passes, such as an inline multi-line `--body`, a body from standard input, or a body written through `gh api`. A `--body-file` that is not a regular file (a pipe, a device or a directory) counts as no body: a create is denied with the request for the body, and an edit passes. Merges and pushes pass.
44
44
 
45
45
  When the checked-out branch changes a file people see (`.html`, `.htm`, `.css`, `.scss`, `.tsx`, `.jsx`, `.vue`, `.svelte`), the gate also denies a body whose proof section holds no picture: a markdown image, an image URL, or an Artifact page link that shows the screenshots. Render the change, read the screenshot, and put it in the section, so the reader sees what you looked at. A page the branch only moves to another folder or name that ends the same way, with every byte kept (`R100` in `git diff --name-status`), changes nothing people see, so the gate leaves it out; a moved page that also changed, or a file that becomes a page by a change of name ending, still needs the picture. When git in the session directory cannot list the branch's changed files, the gate asks for the picture as well. The gate looks for the picture first, so a proof section that holds one passes this check with no git read.
46
46
 
47
- The gate's git, GitHub CLI and web reads share one budget, counted from the gate start: the proof and picture reads have a deadline at 12 s, and the follow-up reads at 20 s. A stopped child read gets 1 s more to close its pipes, so the reads end by 21 s. The registered timeout in `hooks.json` is 30 s. A read the budget cuts short comes back unanswered, and the check that asked for it decides from that. A deny from such a run ends with a sentence that says the reads ran out of time, so a second run may pass.
47
+ The gate's git, GitHub CLI and web reads share one budget, counted from the gate start: the proof and picture reads have a deadline at 12 s, and the follow-up reads at 20 s. A stopped child read gets 1 s more to close its pipes, and a scan finishes the line it is parsing before it stops. The registered timeout in `hooks.json` is 30 s, and the budget test in `test_gate_run_reads.py` reserves two such graces and a 5 s margin inside it. A read the budget cuts short comes back unanswered, and the check that asked for it decides from that. A deny from such a run ends with a sentence that says the reads ran out of time, so a second run may pass. The transcript scans answer to the same deadlines: the `pr-lifecycle` scan to 12 s and the build-eval scan to 20 s. A scan reads the clock before each file block and before each line, and a line over 16 MiB ends the scan as a passed deadline does. A scan the deadline stops counts as not found, and its deny says to load the skill, or call build-eval, again. A transcript that cannot seek to its end is first copied forward into memory, and a copy that passes 64 MiB ends the scan as a passed deadline does. On POSIX a stopped child read is killed with its process group, and a process that left that group by starting its own session is outside it. On Windows the child joins a job object right after it starts, and the gate ends the job, which also ends a grandchild that still holds the pipe after the child exited. When no job could be made or ended, a bounded `taskkill /T /F` runs instead. A process the child starts before it joins the job is outside the job. A follow-up create is refused when the read of open pull requests gives no answer in time, or when the create names no repository and the origin remote cannot be read.
48
48
 
49
49
  The gate checks that the section is there, names a command, and admits no unproven part. Whether the run proves the change stays a judgment for the author and the reviewer.
@@ -160,7 +160,9 @@ def aggregate_bash_hook_results(
160
160
  ) -> BashDispatcherDecision:
161
161
  """Aggregate hosted-hook runs into one deny>ask>allow decision.
162
162
 
163
- Crashed hooks fail open: they contribute no decision. Reasons are collected
163
+ Crashed hooks fail open: they contribute no decision. When no hook decides,
164
+ the result still keeps every systemMessage, such as the warning a gate
165
+ prints when its check raised. Reasons are collected
164
166
  from deny and ask outputs. When the winning decision is allow, the first
165
167
  non-empty updatedInput among allow results is carried through so rewriters
166
168
  keep their contract. systemMessage, additionalContext, and suppressOutput
@@ -180,9 +182,6 @@ def aggregate_bash_hook_results(
180
182
  winning_decision = each_candidate
181
183
  break
182
184
 
183
- if not winning_decision:
184
- return BashDispatcherDecision(decision="")
185
-
186
185
  all_reasons = [
187
186
  each_parsed.reason
188
187
  for each_parsed in all_parsed
@@ -198,6 +197,8 @@ def aggregate_bash_hook_results(
198
197
  all_system_messages = [
199
198
  each_parsed.system_message for each_parsed in all_parsed if each_parsed.system_message
200
199
  ]
200
+ if not winning_decision:
201
+ return BashDispatcherDecision(decision="", all_system_messages=all_system_messages)
201
202
  all_additional_context = [
202
203
  each_parsed.additional_context
203
204
  for each_parsed in all_parsed
@@ -222,8 +223,14 @@ def _emit_decision(decision: BashDispatcherDecision) -> None:
222
223
 
223
224
  A rewrite carries updatedInput with no permissionDecision, so the harness
224
225
  applies the rewritten command and then runs its normal permission prompt.
226
+ With no decision, the hooks' systemMessage lines go out alone, with no
227
+ permissionDecision. With no decision and no message, nothing is written.
225
228
  """
226
229
  if not decision.decision:
230
+ if decision.all_system_messages:
231
+ message_payload = {_SYSTEM_MESSAGE_KEY: CONTEXT_JOIN_SEPARATOR.join(decision.all_system_messages)}
232
+ sys.stdout.write(json.dumps(message_payload) + "\n")
233
+ sys.stdout.flush()
227
234
  return
228
235
  hook_specific: dict[str, object] = {"hookEventName": HOOK_EVENT_NAME}
229
236
  is_rewrite = decision.decision == ALLOW_DECISION and decision.updated_input is not None