claude-dev-env 8.115.0 → 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.
@@ -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
@@ -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
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": [