claude-dev-env 8.114.10 → 8.116.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/rule-guides/verified-work.md +1 -1
- package/hooks/advisory/commit_and_pull_request_words.py +346 -0
- package/hooks/advisory/piece_clauses.py +248 -0
- package/hooks/advisory/pieces_per_level_analysis.py +192 -0
- package/hooks/advisory/pieces_per_level_note.py +265 -0
- package/hooks/advisory/test_commit_and_pull_request_words.py +126 -0
- package/hooks/advisory/test_piece_clauses.py +183 -0
- package/hooks/advisory/test_pieces_per_level_note.py +389 -0
- package/hooks/advisory/test_pieces_per_level_note_bounds.py +215 -0
- package/hooks/advisory/test_pieces_per_level_note_deadline.py +282 -0
- package/hooks/features/README.md +1 -1
- package/hooks/features/session-context.md +4 -1
- package/hooks/features/spawn-routing.md +1 -1
- package/hooks/hooks.json +10 -0
- package/hooks/hooks_constants/pieces_per_level_note_constants.py +255 -0
- package/hooks/hooks_constants/shell_command_wrappers.py +20 -8
- package/hooks/hooks_constants/spawn_oversight_hook_constants.py +5 -1
- package/hooks/hooks_constants/test_shell_command_wrappers.py +7 -0
- package/hooks/routing/test_spawn_oversight_hook.py +15 -0
- package/package.json +1 -1
- package/scripts/tests/test_verified_work_rule.py +13 -0
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
"""Bound tests for the pieces-per-level note.
|
|
2
|
+
|
|
3
|
+
The analysis reads its input only up to fixed caps. These tests feed the
|
|
4
|
+
analysis and the hook inputs that were slow before the caps existed and read the
|
|
5
|
+
silence, the exit status, and the wall time.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
import subprocess
|
|
12
|
+
import sys
|
|
13
|
+
import time
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
import pytest
|
|
17
|
+
|
|
18
|
+
hooks_root_directory = str(Path(__file__).resolve().parent.parent)
|
|
19
|
+
if hooks_root_directory not in sys.path:
|
|
20
|
+
sys.path.insert(0, hooks_root_directory)
|
|
21
|
+
advisory_directory = str(Path(__file__).resolve().parent)
|
|
22
|
+
if advisory_directory not in sys.path:
|
|
23
|
+
sys.path.insert(0, advisory_directory)
|
|
24
|
+
|
|
25
|
+
import commit_and_pull_request_words
|
|
26
|
+
import piece_clauses
|
|
27
|
+
import pieces_per_level_analysis
|
|
28
|
+
from hooks_constants.pieces_per_level_note_constants import (
|
|
29
|
+
COMMIT_NEXT_COMMAND,
|
|
30
|
+
MAXIMUM_BODY_CHARACTERS,
|
|
31
|
+
MAXIMUM_TITLE_CHARACTERS,
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
SCRIPT_PATH = Path(__file__).resolve().parent / "pieces_per_level_note.py"
|
|
35
|
+
ENTRY_SECONDS_BOUND = 1.0
|
|
36
|
+
OVER_BARE_START_SECONDS_BOUND = 1.0
|
|
37
|
+
INTERPRETER_STARTS_PER_RUN = 2
|
|
38
|
+
RUNS_PER_INPUT = 3
|
|
39
|
+
MIXED_SUBJECT = (
|
|
40
|
+
"fix(convert): always publish drawn icons, put Tips on the tray, stop the label smear"
|
|
41
|
+
)
|
|
42
|
+
MANY_SUBSTITUTIONS = "$(" * 3_900 + " git commit -m x"
|
|
43
|
+
PROOF_HEADING = "## Proof in practice"
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _bare_start_seconds() -> float:
|
|
47
|
+
all_runs = []
|
|
48
|
+
for _ in range(3):
|
|
49
|
+
started_at = time.perf_counter()
|
|
50
|
+
subprocess.run([sys.executable, "-c", "pass"], check=False)
|
|
51
|
+
all_runs.append(time.perf_counter() - started_at)
|
|
52
|
+
return min(all_runs)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _run_hook(payload: dict[str, object]) -> tuple[subprocess.CompletedProcess[str], float]:
|
|
56
|
+
started_at = time.perf_counter()
|
|
57
|
+
completed = subprocess.run(
|
|
58
|
+
[sys.executable, str(SCRIPT_PATH)],
|
|
59
|
+
input=json.dumps(payload),
|
|
60
|
+
capture_output=True,
|
|
61
|
+
text=True,
|
|
62
|
+
timeout=60,
|
|
63
|
+
check=False,
|
|
64
|
+
)
|
|
65
|
+
return completed, time.perf_counter() - started_at
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _shell_payload(command: str) -> dict[str, object]:
|
|
69
|
+
return {"tool_name": "Bash", "tool_input": {"command": command}}
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _mcp_payload(title: str, body: str) -> dict[str, object]:
|
|
73
|
+
return {
|
|
74
|
+
"tool_name": "mcp__github__create_pull_request",
|
|
75
|
+
"tool_input": {"title": title, "body": body},
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _seconds_of(call, *all_arguments: object) -> tuple[object, float]:
|
|
80
|
+
started_at = time.perf_counter()
|
|
81
|
+
result = call(*all_arguments)
|
|
82
|
+
return result, time.perf_counter() - started_at
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
@pytest.mark.parametrize(
|
|
86
|
+
"payload",
|
|
87
|
+
[
|
|
88
|
+
_shell_payload(MANY_SUBSTITUTIONS),
|
|
89
|
+
_mcp_payload("fix: a" + " " * 100_000 + "b", ""),
|
|
90
|
+
_mcp_payload("fix: a" + "(" * 200_000, ""),
|
|
91
|
+
_mcp_payload("fix: a", PROOF_HEADING + " " * 60_000 + "x"),
|
|
92
|
+
],
|
|
93
|
+
ids=["substitutions", "title spaces", "title parentheses", "body heading spaces"],
|
|
94
|
+
)
|
|
95
|
+
def test_an_input_that_was_slow_gives_silence_exit_zero_and_a_short_wall_time(
|
|
96
|
+
payload: dict[str, object],
|
|
97
|
+
) -> None:
|
|
98
|
+
bare_start_seconds = _bare_start_seconds()
|
|
99
|
+
all_runs = [_run_hook(payload) for _ in range(RUNS_PER_INPUT)]
|
|
100
|
+
for each_completed, _each_seconds in all_runs:
|
|
101
|
+
assert each_completed.returncode == 0
|
|
102
|
+
assert each_completed.stdout == ""
|
|
103
|
+
assert each_completed.stderr == ""
|
|
104
|
+
fastest_seconds = min(each_seconds for _each_completed, each_seconds in all_runs)
|
|
105
|
+
assert fastest_seconds - INTERPRETER_STARTS_PER_RUN * bare_start_seconds < OVER_BARE_START_SECONDS_BOUND
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def test_a_commit_with_many_substitutions_gets_no_note_within_the_entry_bound() -> None:
|
|
109
|
+
all_fields = {"tool_name": "Bash", "tool_input": {"command": MANY_SUBSTITUTIONS}, "cwd": ""}
|
|
110
|
+
output, elapsed_seconds = _seconds_of(pieces_per_level_analysis.decide_hook_output, all_fields)
|
|
111
|
+
assert output is None
|
|
112
|
+
assert elapsed_seconds < ENTRY_SECONDS_BOUND
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def test_a_heredoc_message_still_gets_the_note_with_one_substitution() -> None:
|
|
116
|
+
command = f"git commit -m \"$(cat <<'EOF'{chr(10)}{MIXED_SUBJECT}{chr(10)}EOF{chr(10)})\""
|
|
117
|
+
all_fields = {"tool_name": "Bash", "tool_input": {"command": command}, "cwd": ""}
|
|
118
|
+
assert "stop the label smear" in json.dumps(
|
|
119
|
+
pieces_per_level_analysis.decide_hook_output(all_fields)
|
|
120
|
+
)
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def test_the_commit_and_pull_request_readers_unwrap_the_command_once(
|
|
124
|
+
monkeypatch: pytest.MonkeyPatch,
|
|
125
|
+
) -> None:
|
|
126
|
+
all_calls: list[str] = []
|
|
127
|
+
real_unwrap = commit_and_pull_request_words.all_wrapped_command_texts
|
|
128
|
+
|
|
129
|
+
def counting_unwrap(command: str, *all_arguments: object) -> list[str]:
|
|
130
|
+
all_calls.append(command)
|
|
131
|
+
return real_unwrap(command, *all_arguments)
|
|
132
|
+
|
|
133
|
+
monkeypatch.setattr(commit_and_pull_request_words, "all_wrapped_command_texts", counting_unwrap)
|
|
134
|
+
commit_and_pull_request_words.clear_parse_cache()
|
|
135
|
+
command = "git commit -m 'fix(x): one thing' && gh pr create --title t"
|
|
136
|
+
all_fields = {"tool_name": "Bash", "tool_input": {"command": command}, "cwd": ""}
|
|
137
|
+
assert pieces_per_level_analysis.decide_hook_output(all_fields) is None
|
|
138
|
+
assert len(all_calls) == 1
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def test_a_command_with_many_substitution_markers_is_not_unwrapped(
|
|
142
|
+
monkeypatch: pytest.MonkeyPatch,
|
|
143
|
+
) -> None:
|
|
144
|
+
all_calls: list[str] = []
|
|
145
|
+
monkeypatch.setattr(
|
|
146
|
+
commit_and_pull_request_words,
|
|
147
|
+
"all_wrapped_command_texts",
|
|
148
|
+
lambda command, *_all_arguments: all_calls.append(command) or [command],
|
|
149
|
+
)
|
|
150
|
+
commit_and_pull_request_words.clear_parse_cache()
|
|
151
|
+
commit_and_pull_request_words.commit_subjects(MANY_SUBSTITUTIONS, "")
|
|
152
|
+
assert all_calls == []
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
@pytest.mark.parametrize(
|
|
156
|
+
"title",
|
|
157
|
+
[
|
|
158
|
+
"fix: a" + " " * 20_000 + "b",
|
|
159
|
+
"fix: a" + " " * 100_000 + "b",
|
|
160
|
+
"fix: a" + "(" * 200_000,
|
|
161
|
+
"fix: a" + "`" * 100_000,
|
|
162
|
+
"fix: a" + ", " * 100_000,
|
|
163
|
+
],
|
|
164
|
+
ids=["20k spaces", "100k spaces", "200k parentheses", "100k backticks", "100k commas"],
|
|
165
|
+
)
|
|
166
|
+
def test_a_long_title_names_no_pieces_within_the_entry_bound(title: str) -> None:
|
|
167
|
+
all_pieces, elapsed_seconds = _seconds_of(piece_clauses.subject_pieces, title)
|
|
168
|
+
assert all_pieces == []
|
|
169
|
+
assert elapsed_seconds < ENTRY_SECONDS_BOUND
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def test_a_title_at_the_cap_still_names_its_pieces() -> None:
|
|
173
|
+
assert len(MIXED_SUBJECT) < MAXIMUM_TITLE_CHARACTERS
|
|
174
|
+
assert len(piece_clauses.subject_pieces(MIXED_SUBJECT)) == 3
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
@pytest.mark.parametrize(
|
|
178
|
+
"body",
|
|
179
|
+
[
|
|
180
|
+
PROOF_HEADING + " " * 60_000 + "x",
|
|
181
|
+
"## What this does" + " " * 60_000 + "x",
|
|
182
|
+
PROOF_HEADING + chr(10) + "Without it " + ";" * 100_000,
|
|
183
|
+
PROOF_HEADING + chr(10) + "- " + "**a " * 100_000,
|
|
184
|
+
(PROOF_HEADING + chr(10) + "Without the change: x" + chr(10)) * 5_000,
|
|
185
|
+
],
|
|
186
|
+
ids=["proof heading", "what heading", "semicolons", "bold bullets", "many lines"],
|
|
187
|
+
)
|
|
188
|
+
def test_a_hostile_body_is_read_within_the_entry_bound(body: str) -> None:
|
|
189
|
+
all_counts, elapsed_seconds = _seconds_of(
|
|
190
|
+
lambda text: (piece_clauses.proof_pair_count(text), piece_clauses.topic_bullets(text)),
|
|
191
|
+
body,
|
|
192
|
+
)
|
|
193
|
+
assert all_counts[0] <= len(body)
|
|
194
|
+
assert elapsed_seconds < ENTRY_SECONDS_BOUND
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def test_a_body_is_read_only_up_to_the_character_cap() -> None:
|
|
198
|
+
pair = chr(10).join(["Without the change: a failed.", "With the change: a passed."])
|
|
199
|
+
filler = chr(10) + "x" * (MAXIMUM_BODY_CHARACTERS + 10)
|
|
200
|
+
body = PROOF_HEADING + chr(10) + pair + chr(10) + filler + chr(10) + pair
|
|
201
|
+
assert piece_clauses.proof_pair_count(body) == 1
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def test_a_heading_line_padded_past_the_line_cap_still_opens_its_section() -> None:
|
|
205
|
+
pair = chr(10).join(["Without the change: a failed.", "With the change: a passed."])
|
|
206
|
+
body = PROOF_HEADING + " " * 5_000 + chr(10) + pair + chr(10) + pair
|
|
207
|
+
assert piece_clauses.proof_pair_count(body) == 2
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def test_the_commit_note_holds_the_commit_and_names_the_split_commands() -> None:
|
|
211
|
+
assert "git add -p" not in COMMIT_NEXT_COMMAND
|
|
212
|
+
assert "The commit that is running holds every piece." in COMMIT_NEXT_COMMAND
|
|
213
|
+
assert "`git reset --soft HEAD~1`" in COMMIT_NEXT_COMMAND
|
|
214
|
+
assert "`git add <paths of the first piece>`" in COMMIT_NEXT_COMMAND
|
|
215
|
+
|
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
"""Deadline tests for the pieces-per-level note.
|
|
2
|
+
|
|
3
|
+
The hook runs its analysis in a child process under one wall-clock deadline for
|
|
4
|
+
the whole child, from start to exit. These tests use fake children that stall
|
|
5
|
+
at each stage and read the silence, the exit status, the wall time, and whether
|
|
6
|
+
a child was started.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import subprocess
|
|
13
|
+
import sys
|
|
14
|
+
import time
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
import pytest
|
|
18
|
+
|
|
19
|
+
hooks_root_directory = str(Path(__file__).resolve().parent.parent)
|
|
20
|
+
if hooks_root_directory not in sys.path:
|
|
21
|
+
sys.path.insert(0, hooks_root_directory)
|
|
22
|
+
advisory_directory = str(Path(__file__).resolve().parent)
|
|
23
|
+
if advisory_directory not in sys.path:
|
|
24
|
+
sys.path.insert(0, advisory_directory)
|
|
25
|
+
|
|
26
|
+
import pieces_per_level_note
|
|
27
|
+
from hooks_constants.pieces_per_level_note_constants import (
|
|
28
|
+
DEADLINE_ENVIRONMENT_VARIABLE,
|
|
29
|
+
EXIT_WAIT_SECONDS,
|
|
30
|
+
TOTAL_DEADLINE_SECONDS,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
STALL_SECONDS = 30
|
|
34
|
+
SHORT_DEADLINE_SECONDS = 0.5
|
|
35
|
+
RETURN_BOUND_SECONDS = STALL_SECONDS / 3
|
|
36
|
+
MIXED_SUBJECT = (
|
|
37
|
+
"fix(convert): always publish drawn icons, put Tips on the tray, stop the label smear"
|
|
38
|
+
)
|
|
39
|
+
ALL_RUNNER_SOURCE = (
|
|
40
|
+
"import sys; sys.path.insert(0, {advisory!r}); import pieces_per_level_note as hook; "
|
|
41
|
+
"hook._child_arguments = lambda: [sys.executable, '-c', {child!r}]; sys.exit(hook.main())"
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _child_arguments(code: str) -> list[str]:
|
|
46
|
+
return [sys.executable, "-c", code]
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _shell_fields(command: str) -> dict[str, object]:
|
|
50
|
+
return {"tool_name": "Bash", "tool_input": {"command": command}}
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _mcp_fields(title: str, body: str) -> dict[str, object]:
|
|
54
|
+
return {
|
|
55
|
+
"tool_name": "mcp__github__create_pull_request",
|
|
56
|
+
"tool_input": {"title": title, "body": body},
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _bare_start_seconds() -> float:
|
|
61
|
+
all_runs = []
|
|
62
|
+
for _ in range(3):
|
|
63
|
+
started_at = time.perf_counter()
|
|
64
|
+
subprocess.run([sys.executable, "-c", "pass"], check=False)
|
|
65
|
+
all_runs.append(time.perf_counter() - started_at)
|
|
66
|
+
return min(all_runs)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _run_hook_with_fake_child(
|
|
70
|
+
fields: dict[str, object], child_code: str
|
|
71
|
+
) -> tuple[subprocess.CompletedProcess[str], float]:
|
|
72
|
+
runner_source = ALL_RUNNER_SOURCE.format(advisory=advisory_directory, child=child_code)
|
|
73
|
+
started_at = time.perf_counter()
|
|
74
|
+
completed = subprocess.run(
|
|
75
|
+
[sys.executable, "-c", runner_source],
|
|
76
|
+
input=json.dumps(fields),
|
|
77
|
+
capture_output=True,
|
|
78
|
+
text=True,
|
|
79
|
+
timeout=60,
|
|
80
|
+
check=False,
|
|
81
|
+
)
|
|
82
|
+
return completed, time.perf_counter() - started_at
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _marker_child_code(marker_path: Path) -> str:
|
|
86
|
+
return (
|
|
87
|
+
f"open({str(marker_path)!r}, 'w').write('started'); "
|
|
88
|
+
f"import time; time.sleep({STALL_SECONDS})"
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def test_the_default_deadline_is_about_one_second_and_the_exit_wait_fits_inside_it() -> None:
|
|
93
|
+
assert 0.5 <= TOTAL_DEADLINE_SECONDS <= 1.5
|
|
94
|
+
assert 0 < EXIT_WAIT_SECONDS <= TOTAL_DEADLINE_SECONDS / 2
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def test_a_child_that_never_prints_is_killed_at_the_deadline() -> None:
|
|
98
|
+
started_at = time.perf_counter()
|
|
99
|
+
output = pieces_per_level_note.analysis_output(
|
|
100
|
+
b"{}", _child_arguments(f"import time; time.sleep({STALL_SECONDS})"), SHORT_DEADLINE_SECONDS
|
|
101
|
+
)
|
|
102
|
+
assert output == b""
|
|
103
|
+
assert time.perf_counter() - started_at < RETURN_BOUND_SECONDS
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def test_a_child_that_never_reads_a_large_payload_is_killed_at_the_deadline() -> None:
|
|
107
|
+
started_at = time.perf_counter()
|
|
108
|
+
output = pieces_per_level_note.analysis_output(
|
|
109
|
+
b"x" * 20_000_000,
|
|
110
|
+
_child_arguments(f"import time; time.sleep({STALL_SECONDS})"),
|
|
111
|
+
SHORT_DEADLINE_SECONDS,
|
|
112
|
+
)
|
|
113
|
+
assert output == b""
|
|
114
|
+
assert time.perf_counter() - started_at < RETURN_BOUND_SECONDS
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def test_a_child_that_prints_then_hangs_after_closing_its_output_is_cut_off_at_the_exit_wait() -> (
|
|
118
|
+
None
|
|
119
|
+
):
|
|
120
|
+
all_arguments = _child_arguments(
|
|
121
|
+
"import os, sys, time; sys.stdin.read(); sys.stdout.write('late'); sys.stdout.flush(); "
|
|
122
|
+
f"os.close(1); time.sleep({STALL_SECONDS})"
|
|
123
|
+
)
|
|
124
|
+
started_at = time.perf_counter()
|
|
125
|
+
output = pieces_per_level_note.analysis_output(b"{}", all_arguments, 3)
|
|
126
|
+
assert output == b""
|
|
127
|
+
assert time.perf_counter() - started_at < RETURN_BOUND_SECONDS
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def test_a_child_that_starts_slowly_still_inside_the_deadline_passes_its_output_through() -> None:
|
|
131
|
+
all_arguments = _child_arguments(
|
|
132
|
+
"import sys, time; time.sleep(0.3); sys.stdin.read(); sys.stdout.write('done')"
|
|
133
|
+
)
|
|
134
|
+
assert pieces_per_level_note.analysis_output(b"{}", all_arguments, 20) == b"done"
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def test_a_child_past_the_deadline_is_killed_and_does_not_finish_its_work(tmp_path: Path) -> None:
|
|
138
|
+
marker_path = tmp_path / "finished.txt"
|
|
139
|
+
all_arguments = _child_arguments(
|
|
140
|
+
f"import time; time.sleep(2.0); open({str(marker_path)!r}, 'w').write('finished')"
|
|
141
|
+
)
|
|
142
|
+
assert (
|
|
143
|
+
pieces_per_level_note.analysis_output(b"{}", all_arguments, SHORT_DEADLINE_SECONDS) == b""
|
|
144
|
+
)
|
|
145
|
+
time.sleep(3.0)
|
|
146
|
+
assert not marker_path.exists()
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def test_an_analysis_that_exits_non_zero_gives_no_output() -> None:
|
|
150
|
+
all_arguments = _child_arguments(
|
|
151
|
+
"import sys; sys.stdin.read(); sys.stdout.write('x'); sys.exit(3)"
|
|
152
|
+
)
|
|
153
|
+
assert pieces_per_level_note.analysis_output(b"{}", all_arguments, 20) == b""
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def test_a_child_that_cannot_start_gives_no_output() -> None:
|
|
157
|
+
assert (
|
|
158
|
+
pieces_per_level_note.analysis_output(b"{}", ["definitely-not-a-program-name"], 20) == b""
|
|
159
|
+
)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def test_the_hook_prints_nothing_and_exits_zero_when_its_child_never_prints(tmp_path: Path) -> None:
|
|
163
|
+
marker_path = tmp_path / "started.txt"
|
|
164
|
+
bare_start_seconds = _bare_start_seconds()
|
|
165
|
+
all_runs = [
|
|
166
|
+
_run_hook_with_fake_child(
|
|
167
|
+
_shell_fields(f'git commit -m "{MIXED_SUBJECT}"'), _marker_child_code(marker_path)
|
|
168
|
+
)
|
|
169
|
+
for _ in range(3)
|
|
170
|
+
]
|
|
171
|
+
for each_completed, _each_seconds in all_runs:
|
|
172
|
+
assert each_completed.returncode == 0
|
|
173
|
+
assert each_completed.stdout == ""
|
|
174
|
+
assert each_completed.stderr == ""
|
|
175
|
+
assert marker_path.exists()
|
|
176
|
+
fastest_seconds = min(each_seconds for _each_completed, each_seconds in all_runs)
|
|
177
|
+
assert fastest_seconds < 3 * bare_start_seconds + TOTAL_DEADLINE_SECONDS + 1.0
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
@pytest.mark.parametrize(
|
|
181
|
+
"command",
|
|
182
|
+
[
|
|
183
|
+
"ls -la",
|
|
184
|
+
"git status",
|
|
185
|
+
"git log --grep=commit",
|
|
186
|
+
"mkdir createdir",
|
|
187
|
+
"npm run create-app",
|
|
188
|
+
'git commit -m "fix(icons): put Tips on the tray"',
|
|
189
|
+
"git commit",
|
|
190
|
+
],
|
|
191
|
+
)
|
|
192
|
+
def test_a_call_that_cannot_name_several_pieces_starts_no_child(
|
|
193
|
+
command: str, tmp_path: Path
|
|
194
|
+
) -> None:
|
|
195
|
+
marker_path = tmp_path / "started.txt"
|
|
196
|
+
completed, _elapsed_seconds = _run_hook_with_fake_child(
|
|
197
|
+
_shell_fields(command), _marker_child_code(marker_path)
|
|
198
|
+
)
|
|
199
|
+
assert (completed.returncode, completed.stdout, completed.stderr) == (0, "", "")
|
|
200
|
+
assert not marker_path.exists()
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
@pytest.mark.parametrize(
|
|
204
|
+
"fields",
|
|
205
|
+
[
|
|
206
|
+
_shell_fields(f'git commit -m "{MIXED_SUBJECT}"'),
|
|
207
|
+
_shell_fields("git commit -F message.txt"),
|
|
208
|
+
_shell_fields("git commit -am 'fix: add a and b'"),
|
|
209
|
+
_shell_fields('git add x && git commit --message="fix: a; b"'),
|
|
210
|
+
_shell_fields('gh pr create --title "fix: a, b" --body-file body.md'),
|
|
211
|
+
_shell_fields("gh pr create --title t --body-file body.md"),
|
|
212
|
+
_shell_fields('python pull_request.py create --title "fix: a, b"'),
|
|
213
|
+
_mcp_fields(MIXED_SUBJECT, ""),
|
|
214
|
+
_mcp_fields("fix: one thing", "## What this does"),
|
|
215
|
+
],
|
|
216
|
+
)
|
|
217
|
+
def test_a_call_that_may_name_several_pieces_is_worth_analysing(fields: dict[str, object]) -> None:
|
|
218
|
+
assert pieces_per_level_note.could_hold_a_note(fields)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
@pytest.mark.parametrize(
|
|
222
|
+
"fields",
|
|
223
|
+
[
|
|
224
|
+
_shell_fields("ls -la"),
|
|
225
|
+
_shell_fields("git log --grep=commit"),
|
|
226
|
+
_shell_fields("npm run create-app"),
|
|
227
|
+
_shell_fields('git commit -m "fix(icons): put Tips on the tray"'),
|
|
228
|
+
_shell_fields("git status, git diff"),
|
|
229
|
+
_shell_fields("a, b " + "x" * 20_000 + " git commit -m y"),
|
|
230
|
+
_mcp_fields("fix: one thing", ""),
|
|
231
|
+
{"tool_name": "Bash", "tool_input": "git commit -m 'a, b'"},
|
|
232
|
+
{"tool_name": "Bash"},
|
|
233
|
+
{"tool_input": {}},
|
|
234
|
+
],
|
|
235
|
+
)
|
|
236
|
+
def test_a_call_that_cannot_name_several_pieces_is_not_worth_analysing(
|
|
237
|
+
fields: dict[str, object],
|
|
238
|
+
) -> None:
|
|
239
|
+
assert not pieces_per_level_note.could_hold_a_note(fields)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def test_the_parent_imports_none_of_the_analysis_modules() -> None:
|
|
243
|
+
source = (
|
|
244
|
+
f"import sys; sys.path.insert(0, {advisory_directory!r}); import pieces_per_level_note; "
|
|
245
|
+
"all_names = ('commit_and_pull_request_words', 'piece_clauses', 'pieces_per_level_analysis', "
|
|
246
|
+
"'hooks_constants.pre_tool_use_context_runner'); "
|
|
247
|
+
"print([each for each in all_names if each in sys.modules])"
|
|
248
|
+
)
|
|
249
|
+
completed = subprocess.run(
|
|
250
|
+
[sys.executable, "-c", source], capture_output=True, text=True, check=False
|
|
251
|
+
)
|
|
252
|
+
assert completed.stdout.strip() == "[]"
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
@pytest.mark.parametrize(
|
|
256
|
+
"raw_payload",
|
|
257
|
+
["[" * 200_000, "{" * 200_000, '{"a":' * 100_000],
|
|
258
|
+
ids=["brackets", "braces", "nested keys"],
|
|
259
|
+
)
|
|
260
|
+
def test_a_payload_that_breaks_the_json_parser_gives_silence_and_exit_zero(
|
|
261
|
+
raw_payload: str,
|
|
262
|
+
) -> None:
|
|
263
|
+
completed = subprocess.run(
|
|
264
|
+
[sys.executable, str(Path(advisory_directory) / "pieces_per_level_note.py")],
|
|
265
|
+
input=raw_payload,
|
|
266
|
+
capture_output=True,
|
|
267
|
+
text=True,
|
|
268
|
+
timeout=60,
|
|
269
|
+
check=False,
|
|
270
|
+
)
|
|
271
|
+
assert (completed.returncode, completed.stdout, completed.stderr) == (0, "", "")
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def test_the_test_only_environment_variable_sets_the_deadline() -> None:
|
|
275
|
+
assert pieces_per_level_note.deadline_seconds({}) == TOTAL_DEADLINE_SECONDS
|
|
276
|
+
assert pieces_per_level_note.deadline_seconds({DEADLINE_ENVIRONMENT_VARIABLE: "30"}) == 30.0
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
@pytest.mark.parametrize("raw_value", ["", "soon", "0", "-2", "nan", "inf"])
|
|
280
|
+
def test_a_bad_environment_value_keeps_the_default_deadline(raw_value: str) -> None:
|
|
281
|
+
all_environment = {DEADLINE_ENVIRONMENT_VARIABLE: raw_value}
|
|
282
|
+
assert pieces_per_level_note.deadline_seconds(all_environment) == TOTAL_DEADLINE_SECONDS
|
package/hooks/features/README.md
CHANGED
|
@@ -26,7 +26,7 @@ Each family page starts with a title and an agent-facing behavior summary. Its f
|
|
|
26
26
|
- [Bash dispatchers](./bash-dispatchers.md) covers command rewriting and the post-call reminder.
|
|
27
27
|
- [Post-write validation](./post-write-validation.md) covers the after-write dispatcher and formatter.
|
|
28
28
|
- [Conduct gates](./conduct-gates.md) covers chat replies, edit markers, step notes, checked claims, and the pull request lifecycle skill.
|
|
29
|
-
- [Session context](./session-context.md) covers skill reminders, startup guidance, the npx_pele_guidance hook, and the auto mode denial quick fix.
|
|
29
|
+
- [Session context](./session-context.md) covers skill reminders, startup guidance, the npx_pele_guidance hook, the pieces_per_level_note hook, and the auto mode denial quick fix.
|
|
30
30
|
- [Spawn routing](./spawn-routing.md) covers spawn readiness, pacing, and model selection.
|
|
31
31
|
- [Observability](./observability.md) covers instruction loads and edited files.
|
|
32
32
|
- [Read gates](./read-gates.md) covers the image size cap on Read.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Session context
|
|
2
2
|
|
|
3
|
-
This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, starts a workflow helper, starts an artifact page, runs `npx pele`, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
|
|
3
|
+
This family injects reminders and task guidance when an agent starts, resumes, submits a prompt, starts a workflow helper, starts an artifact page, runs `npx pele`, commits or opens a pull request whose words name several pieces, or hits an auto mode denial. The startup scripts leave the session quiet when their opt-in conditions fail.
|
|
4
4
|
|
|
5
5
|
## Checks
|
|
6
6
|
|
|
@@ -14,6 +14,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
|
|
|
14
14
|
- `session/plugin_change_warning.py` compares `installed_plugins.json` with that baseline before each prompt. It names each plugin whose version or install path changed, or that the baseline lacks, once per session, and tells the user to restart Claude Code.
|
|
15
15
|
- `session/artifact_template_pointer.py` routes an agent that starts an artifact page by scope. A status or progress report prefers the status flowchart from `docs/templates/artifact-page/status-flowchart.html`, unless the person asks for another shape. One flow or one comparison is an inline SVG flowchart with minimal text. A multi-part plan or evidence is an html-plan page from `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
|
|
16
16
|
- `session/npx_pele_guidance.py` tells an agent that runs `npx pele` how to render Mermaid instead. Pele is a library with no command, so the hook names the installed copy and a Node snippet that renders with it. When no copy is installed, it points to the pele.run playground.
|
|
17
|
+
- `advisory/pieces_per_level_note.py` adds one context note when a `git commit` subject or a pull request create call names several pieces in the author's own words: a conventional subject or title whose description joins two or more verb-led clauses with commas, semicolons or "and", a "Proof in practice" section with more than one without/with pair, or a "What this does" section with more than one bold-led topic bullet. The note names the pieces, says each gets its own commit and stack level, and gives the commands that split the commit or the pull request into levels. It never blocks, denies or exits non-zero, and a message or body it cannot read gets no note. A command over 8,000 characters gets no note; a title is read to 300 characters, a body to 20,000, and a body line to 500; and a `-F`, `--file` or `--body-file` path is read only when it is a regular file, and only its first 64 KB. A cheap linear check on the payload comes first: the call must hold a `git commit` with a message flag, or a pull request create, as whole words, with a comma, a semicolon, "and", or a body option in its text (the MCP create tool needs a separator in its title or a body), and any other call starts no child process. A call that passes runs its analysis in a child process under one wall-clock deadline of 1 second for the whole child, start to exit, with at most 0.2 seconds of it spent waiting for the exit. A child past the deadline is killed, and the hook prints nothing and exits 0; so does any error in the parent. The environment variable `PIECES_NOTE_TEST_DEADLINE_SECONDS` sets the deadline for tests only.
|
|
17
18
|
- `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
|
|
18
19
|
|
|
19
20
|
## When it fires
|
|
@@ -24,6 +25,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
|
|
|
24
25
|
- `session/plugin_session_baseline_writer.py` runs on `SessionStart`, matcher empty, at `10` seconds, so it sees every source. `session/plugin_change_warning.py` runs on `UserPromptSubmit`, matcher empty, at `10` seconds in `hooks.json`.
|
|
25
26
|
- `session/artifact_template_pointer.py` runs on `PreToolUse` matcher `Artifact|Skill` at `10` seconds in `hooks.json`. It speaks only on an `Artifact` call with action `quickstart` or a `Skill` call that loads `artifact-design`.
|
|
26
27
|
- `session/npx_pele_guidance.py` runs on `PreToolUse` matcher `Bash|PowerShell` at `10` seconds in `hooks.json`. It speaks only on an `npx` command with a `pele` argument, or an `npm exec` or `npm x` command with one after `exec` or `x`.
|
|
28
|
+
- `advisory/pieces_per_level_note.py` (with its analysis in `advisory/pieces_per_level_analysis.py`) runs on `PreToolUse` matcher `Bash|PowerShell|mcp__.*__create_pull_request` at `10` seconds in `hooks.json`. It reads `-m`, `--message`, `-F` and `--file` of `git commit`, the `--title` and `--body-file` of the `gh` and `pull_request.py` create calls, and the `title` and `body` of a `create_pull_request` tool.
|
|
27
29
|
- `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
|
|
28
30
|
|
|
29
31
|
## Proving it
|
|
@@ -41,6 +43,7 @@ Preconditions:
|
|
|
41
43
|
- **Plugin restart warning.** Input is a SessionStart event, an `installed_plugins.json` change, and a prompt. Run `python -m pytest packages/claude-dev-env/hooks/session/test_plugin_session_baseline_writer.py packages/claude-dev-env/hooks/session/test_plugin_change_warning.py packages/claude-dev-env/hooks/test_plugin_session_baseline.py -q`. The tests observe one warning for a changed version, a changed install path, and a plugin new since start, silence on a `lastUpdated` refresh and on a second prompt, and a warning that still fires after a `compact` SessionStart.
|
|
42
44
|
- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
|
|
43
45
|
- **npx pele guidance.** Input is a `Bash` or `PowerShell` call whose command runs `npx pele`. Run `python -m pytest packages/claude-dev-env/hooks/session/test_npx_pele_guidance.py -q`. The adjacent test observes the guidance for each install state, a snippet that renders an SVG file under node, and silence on other commands and malformed input.
|
|
46
|
+
- **Pieces per level note.** Input is a commit subject or pull request title that joins verb-led clauses, a body with three without/with pairs, three single-behaviour subjects, and a malformed payload. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_pieces_per_level_note.py packages/claude-dev-env/hooks/advisory/test_piece_clauses.py -q`. The adjacent tests observe a note and exit 0 for the first two, and no output with exit 0 for the rest.
|
|
44
47
|
- **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
|
|
45
48
|
|
|
46
49
|
## Gotchas
|
|
@@ -5,7 +5,7 @@ This family reminds the agent to gather context before a spawn, refuses a brief
|
|
|
5
5
|
## Checks
|
|
6
6
|
|
|
7
7
|
- `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
|
|
8
|
-
- `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. The first passing spawn of a session, the first of each subagent, and the first after each compaction get the orchestrator oversight directive; the brief check runs on every spawn. The directive says: run each piece through the verified-work flow, with a fresh verifier agent that checks the research, the plan, and the fix, reproduces the issue before it confirms the fix, and leaves the worker's conclusion out of its brief; ask the user before new scope; report as done only what a verifier passed; and watch the agent while it runs. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
|
|
8
|
+
- `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. The first passing spawn of a session, the first of each subagent, and the first after each compaction get the orchestrator oversight directive; the brief check runs on every spawn. The directive says: run each piece through the verified-work flow, with a fresh verifier agent that checks the research, the plan, and the fix, reproduces the issue before it confirms the fix, and leaves the worker's conclusion out of its brief; where the brief allows commits, commit each piece a verifier passed alone, as its own stack level, and otherwise hand it back uncommitted and say so; ask the user before new scope; report as done only what a verifier passed; and watch the agent while it runs. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
|
|
9
9
|
- `routing/thread_spawn_pace_hook.py` reshapes a thread request to Opus at medium when usage is over pace or unreadable. Under pace, a thread request that names a model gets the effort its model allows.
|
|
10
10
|
- `routing/subagent_effort_route_hook.py` sets an allowed effort on an Agent or Task spawn: Opus medium, Sonnet high, Fable low, medium or high, and Haiku any effort. A spawn with no effort or one outside its model's list gets Opus medium, Sonnet high, Fable high, or Haiku medium. `routing/subagent_effort_route.py` holds the rule for this hook and the pace hook.
|
|
11
11
|
- `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
|
package/hooks/hooks.json
CHANGED
|
@@ -127,6 +127,16 @@
|
|
|
127
127
|
}
|
|
128
128
|
]
|
|
129
129
|
},
|
|
130
|
+
{
|
|
131
|
+
"matcher": "Bash|PowerShell|mcp__.*__create_pull_request",
|
|
132
|
+
"hooks": [
|
|
133
|
+
{
|
|
134
|
+
"type": "command",
|
|
135
|
+
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/advisory/pieces_per_level_note.py",
|
|
136
|
+
"timeout": 10
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
},
|
|
130
140
|
{
|
|
131
141
|
"matcher": "Write|Edit|MultiEdit|NotebookEdit|apply_patch",
|
|
132
142
|
"hooks": [
|