claude-dev-env 8.119.2 → 8.121.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.
Files changed (44) hide show
  1. package/bin/ever-registered-hooks.mjs +1 -0
  2. package/hooks/advisory/auto_mode_denial_quick_fix.py +275 -27
  3. package/hooks/advisory/auto_mode_rule_flow_eval/auto_mode_rule_flow_cases.json +3475 -0
  4. package/hooks/advisory/auto_mode_rule_flow_eval/auto_mode_rule_flow_runner.py +849 -0
  5. package/hooks/advisory/auto_mode_rule_flow_eval/stub_allow_hook.py +20 -0
  6. package/hooks/advisory/auto_mode_rule_flow_eval/stub_hold_hook.py +54 -0
  7. package/hooks/advisory/auto_mode_rule_flow_eval/test_auto_mode_rule_flow_runner.py +143 -0
  8. package/hooks/advisory/test_auto_mode_denial_quick_fix.py +533 -9
  9. package/hooks/auto_mode_question_transcript.py +215 -0
  10. package/hooks/auto_mode_refusal_ledger.py +481 -0
  11. package/hooks/auto_mode_refusal_ledger_files.py +336 -0
  12. package/hooks/auto_mode_rule_steps.py +177 -0
  13. package/hooks/blocking/auto_mode_refusal_stop_gate.py +384 -0
  14. package/hooks/blocking/gh_api_budget_gate.py +286 -0
  15. package/hooks/blocking/test_auto_mode_refusal_stop_gate.py +484 -0
  16. package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py +8 -3
  17. package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +1 -0
  18. package/hooks/blocking/test_gh_api_budget_gate.py +602 -0
  19. package/hooks/features/README.md +1 -1
  20. package/hooks/features/bash-dispatchers.md +3 -0
  21. package/hooks/features/session-context.md +5 -2
  22. package/hooks/hooks.json +5 -0
  23. package/hooks/hooks_constants/auto_mode_denial_quick_fix_constants.py +51 -3
  24. package/hooks/hooks_constants/auto_mode_refusal_ledger_constants.py +85 -0
  25. package/hooks/hooks_constants/auto_mode_refusal_stop_gate_constants.py +80 -0
  26. package/hooks/hooks_constants/auto_mode_rule_flow_runner_constants.py +225 -0
  27. package/hooks/hooks_constants/auto_mode_rule_steps_constants.py +82 -0
  28. package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py +4 -0
  29. package/hooks/hooks_constants/gh_api_budget.py +186 -0
  30. package/hooks/hooks_constants/gh_api_budget_gate_constants.py +215 -0
  31. package/hooks/hooks_constants/gh_argument_lists.py +169 -0
  32. package/hooks/hooks_constants/gh_shell_loop_scan.py +386 -0
  33. package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py +5 -1
  34. package/hooks/hooks_constants/test_gh_api_budget.py +125 -0
  35. package/hooks/hooks_constants/test_gh_argument_lists.py +49 -0
  36. package/hooks/hooks_constants/test_gh_shell_loop_scan.py +50 -0
  37. package/hooks/test_auto_mode_question_transcript.py +113 -0
  38. package/hooks/test_auto_mode_refusal_ledger.py +398 -0
  39. package/hooks/test_auto_mode_refusal_ledger_files.py +155 -0
  40. package/hooks/test_auto_mode_rule_steps.py +210 -0
  41. package/package.json +1 -1
  42. package/scripts/policy_lint/adapter_configuration.py +5 -0
  43. package/scripts/policy_lint/config/constants.py +1 -0
  44. package/scripts/tests/test_adapter_configuration.py +8 -0
@@ -0,0 +1,602 @@
1
+ """Tests for gh_api_budget_gate, which keeps agents from draining the GitHub API limit."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import subprocess
7
+ import time
8
+ from io import StringIO
9
+ from pathlib import Path
10
+ from unittest.mock import patch
11
+
12
+ import pytest
13
+
14
+ import gh_api_budget_gate as gate
15
+ import hooks_constants.gh_api_budget as budget_reader
16
+
17
+ _FIVE_MINUTES_IN_SECONDS = 300
18
+ _RESET_EPOCH_SECONDS = 1_900_000_000
19
+
20
+
21
+ class _RateLimitQueries:
22
+ """Stand-in for the ``gh api rate_limit`` subprocess that counts its calls."""
23
+
24
+ def __init__(self) -> None:
25
+ self.call_count = 0
26
+ self.stdout_text = ""
27
+ self.raised_error: BaseException | None = None
28
+ self.return_code = 0
29
+
30
+ def answer_with(self, limit: int, used: int) -> None:
31
+ self.stdout_text = json.dumps(
32
+ {"resources": {"core": {"limit": limit, "used": used, "reset": _RESET_EPOCH_SECONDS}}}
33
+ )
34
+
35
+ def __call__(
36
+ self, *all_arguments: object, **all_options: object
37
+ ) -> subprocess.CompletedProcess[str]:
38
+ self.call_count += 1
39
+ if self.raised_error is not None:
40
+ raise self.raised_error
41
+ return subprocess.CompletedProcess(
42
+ args=all_arguments, returncode=self.return_code, stdout=self.stdout_text, stderr=""
43
+ )
44
+
45
+
46
+ @pytest.fixture
47
+ def config_root(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
48
+ """Point the managed root at a temporary folder."""
49
+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
50
+ return tmp_path
51
+
52
+
53
+ @pytest.fixture
54
+ def rate_queries(monkeypatch: pytest.MonkeyPatch, config_root: Path) -> _RateLimitQueries:
55
+ """Replace the rate limit subprocess with a counting stand-in that reports a fresh limit."""
56
+ queries = _RateLimitQueries()
57
+ queries.answer_with(limit=5000, used=10)
58
+ monkeypatch.setattr(budget_reader.subprocess, "run", queries)
59
+ return queries
60
+
61
+
62
+ def _cache_path(config_root: Path) -> Path:
63
+ return config_root / "cache" / "gh_api_budget.json"
64
+
65
+
66
+ def _write_cache(config_root: Path, read_at: float, limit: int | None, used: int | None) -> None:
67
+ cache_path = _cache_path(config_root)
68
+ cache_path.parent.mkdir(parents=True, exist_ok=True)
69
+ cache_path.write_text(
70
+ json.dumps(
71
+ {"read_at": read_at, "limit": limit, "used": used, "reset": _RESET_EPOCH_SECONDS}
72
+ ),
73
+ encoding="utf-8",
74
+ )
75
+
76
+
77
+ def _stdout_from_main(payload: dict[str, object]) -> str:
78
+ """Return what main() wrote to stdout for one hook payload."""
79
+ captured_stdout = StringIO()
80
+ with (
81
+ patch("sys.stdin", StringIO(json.dumps(payload))),
82
+ patch("sys.stdout", captured_stdout),
83
+ patch.object(gate, "log_hook_block"),
84
+ ):
85
+ gate.main()
86
+ return captured_stdout.getvalue()
87
+
88
+
89
+ def _bash_reason(command: str) -> str:
90
+ """Return the deny reason main() gives a Bash command, or an empty string when it passes."""
91
+ stdout_text = _stdout_from_main({"tool_name": "Bash", "tool_input": {"command": command}})
92
+ if not stdout_text:
93
+ return ""
94
+ specific_output = json.loads(stdout_text)["hookSpecificOutput"]
95
+ assert specific_output["permissionDecision"] == "deny"
96
+ return specific_output["permissionDecisionReason"]
97
+
98
+
99
+ @pytest.mark.parametrize(
100
+ "command",
101
+ [
102
+ "gh run watch 123",
103
+ "gh run watch",
104
+ "gh -R o/r run watch 123 --exit-status",
105
+ "gh.exe run watch 123",
106
+ "gh pr checks 12 --watch",
107
+ "gh pr checks --watch --interval 10",
108
+ "cd repo && gh run watch 123",
109
+ 'bash -c "gh run watch 1"',
110
+ 'pwsh -Command "gh pr checks 12 --watch"',
111
+ ],
112
+ )
113
+ def test_should_detect_watch_commands(command: str) -> None:
114
+ assert gate.runs_gh_watch_command(command) is True
115
+
116
+
117
+ @pytest.mark.parametrize(
118
+ "command",
119
+ [
120
+ "gh pr checks 12",
121
+ "gh run view 123",
122
+ "gh run watch --help",
123
+ 'echo "gh run watch"',
124
+ 'git commit -m "gh run watch"',
125
+ 'grep "gh pr checks --watch" notes.md',
126
+ "watch -n 120 date",
127
+ ],
128
+ )
129
+ def test_should_not_detect_watch_in_other_commands(command: str) -> None:
130
+ assert gate.runs_gh_watch_command(command) is False
131
+
132
+
133
+ @pytest.mark.parametrize(
134
+ "command",
135
+ [
136
+ "while true; do gh run view 1; sleep 30; done",
137
+ "while true; do gh run view 1; sleep 0.5; done",
138
+ "while true; do gh run view 1; sleep 30s; sleep 20; done",
139
+ 'while true; do gh run view "1"; sleep "30"; done',
140
+ "sleep 120 && while :; do gh run view 1; sleep 10; done",
141
+ 'while :; do bash -c "gh run view 1"; sleep 10; done',
142
+ "until gh run view 1 --exit-status; do sleep 10; done",
143
+ "for i in 1 2 3; do gh run view 1; sleep 5; done",
144
+ "while true\ndo\n gh run view 1\n sleep 30\ndone",
145
+ "while true; do gh run view 1; done",
146
+ "while :; do gh api repos/o/r/actions/runs; done",
147
+ "for ((;;)); do gh run view 1; done",
148
+ "until gh run view 1 --exit-status; do :; done",
149
+ 'while [ "$(gh run view 1 --json status -q .status)" != completed ]; do sleep 5; done',
150
+ 'bash -c "while true; do gh run view 1; sleep 5; done"',
151
+ "while ($true) { gh run view 1; Start-Sleep 30 }",
152
+ "while ($true) { gh run view 1; Start-Sleep -Seconds 30 }",
153
+ "for (;;) { gh run view 1; Start-Sleep -Milliseconds 500 }",
154
+ "while ($true) { gh run view 1 }",
155
+ "do { gh run view 1; Start-Sleep 5 } while ($true)",
156
+ "foreach ($each in 1..5) { gh run view 1; Start-Sleep -s 2 }",
157
+ "watch -n 5 gh run view 1",
158
+ "watch -n5 'gh run view 1'",
159
+ "watch gh run view 1",
160
+ "watch --interval=30 gh pr checks 12",
161
+ "while :; do for i in 1 2; do gh run view $i; done; sleep 5; done",
162
+ ],
163
+ )
164
+ def test_should_detect_tight_gh_polling_loops(command: str) -> None:
165
+ assert gate.runs_tight_gh_polling_loop(command) is True
166
+
167
+
168
+ @pytest.mark.parametrize(
169
+ "command",
170
+ [
171
+ "while ($true) { gh run view 1; Start-Sleep 5}",
172
+ "while ($true) { gh run view 1; Start-Sleep -Seconds 5}",
173
+ "while ($true) {gh run view 1}",
174
+ "while($true){gh run view 1; Start-Sleep 5}",
175
+ "foreach ($i in 1..9) {gh run view $i; Start-Sleep 5}",
176
+ ],
177
+ )
178
+ def test_should_detect_powershell_loops_with_glued_braces(command: str) -> None:
179
+ assert gate.runs_tight_gh_polling_loop(command) is True
180
+
181
+
182
+ @pytest.mark.parametrize(
183
+ "command",
184
+ [
185
+ "1..100 | ForEach-Object { gh run view $_; Start-Sleep 5 }",
186
+ "1..100 | % { gh run view $_; Start-Sleep 5 }",
187
+ ],
188
+ )
189
+ def test_should_detect_tight_powershell_pipeline_loops(command: str) -> None:
190
+ assert gate.runs_tight_gh_polling_loop(command) is True
191
+
192
+
193
+ @pytest.mark.parametrize(
194
+ "command",
195
+ [
196
+ "1..100 | ForEach-Object { gh run view $_; Start-Sleep 60 }",
197
+ "1..100 | % { gh run view $_; Start-Sleep 60 }",
198
+ "1..100 | ForEach-Object { gh run view $_ }",
199
+ "1..100 | % { gh run view $_ }",
200
+ ],
201
+ )
202
+ def test_should_pass_slow_and_sleepless_powershell_pipeline_loops(command: str) -> None:
203
+ assert gate.runs_tight_gh_polling_loop(command) is False
204
+
205
+
206
+ @pytest.mark.parametrize(
207
+ "command",
208
+ [
209
+ "for i in 1 2 3; do gh pr view $i; done; while [ ! -f x ]; do sleep 5; done",
210
+ "for i in 1 2 3; do gh pr view $i; done; for j in 1 2; do sleep 2; done",
211
+ "while :; do gh run view ${id}; sleep 60; done",
212
+ "while :; do { gh run view 1; }; sleep 90; done",
213
+ "while ($true) { if ($x) { gh run view 1 }; Start-Sleep 90 }",
214
+ "while ($true) { do { gh run view 1 } while ($x); Start-Sleep 90 }",
215
+ ],
216
+ )
217
+ def test_should_read_each_separate_loop_on_its_own(command: str) -> None:
218
+ assert gate.runs_tight_gh_polling_loop(command) is False
219
+
220
+
221
+ @pytest.mark.parametrize(
222
+ "command",
223
+ [
224
+ "while ($true) { gh run view 1 }; Start-Sleep 60",
225
+ "while ($true) { gh run view 1 }\nStart-Sleep 60",
226
+ "while ($true) { $s = gh run view 1; Start-Sleep 5 }",
227
+ "while ($true) { $s = gh run view 1 | ConvertFrom-Json; Start-Sleep 5 }",
228
+ ],
229
+ )
230
+ def test_should_close_a_one_segment_loop_body_and_read_assigned_gh_in_loops(
231
+ command: str,
232
+ ) -> None:
233
+ assert gate.runs_tight_gh_polling_loop(command) is True
234
+
235
+
236
+ @pytest.mark.parametrize(
237
+ "command",
238
+ [
239
+ "foreach ($i in 1..9) { gh run view $i }; Start-Sleep 5",
240
+ "while ($x) { gh run view 1 }; Start-Sleep 5",
241
+ "1..100 | ForEach-Object { gh run view $_ }; Start-Sleep 5",
242
+ "1..100 | ForEach-Object { gh run view $_ } | Out-Null; Start-Sleep 5",
243
+ ],
244
+ )
245
+ def test_should_not_count_a_sleep_after_a_one_segment_loop_body(command: str) -> None:
246
+ assert gate.runs_tight_gh_polling_loop(command) is False
247
+
248
+
249
+ @pytest.mark.parametrize(
250
+ "command",
251
+ ["$s = gh run watch 1", "$script:s = gh run watch 1", "$s += gh run watch 1"],
252
+ )
253
+ def test_should_deny_a_watch_assigned_to_a_powershell_variable(
254
+ config_root: Path, rate_queries: _RateLimitQueries, command: str
255
+ ) -> None:
256
+ assert _bash_reason(command) == _bash_reason("gh run watch 1") != ""
257
+
258
+
259
+ @pytest.mark.parametrize("command", ['$s = "gh run watch 1"', "$s = 'gh'"])
260
+ def test_should_pass_gh_text_assigned_to_a_powershell_variable(
261
+ config_root: Path, rate_queries: _RateLimitQueries, command: str
262
+ ) -> None:
263
+ _write_cache(config_root, time.time(), limit=5000, used=4999)
264
+ assert _bash_reason(command) == ""
265
+
266
+
267
+ def test_should_deny_an_assigned_read_on_a_spent_budget(
268
+ config_root: Path, rate_queries: _RateLimitQueries
269
+ ) -> None:
270
+ _write_cache(config_root, time.time(), limit=5000, used=4000)
271
+ assert "4000 of 5000" in _bash_reason("$s = gh pr view 1")
272
+
273
+
274
+ def test_should_pass_an_assigned_read_just_under_four_fifths(
275
+ config_root: Path, rate_queries: _RateLimitQueries
276
+ ) -> None:
277
+ _write_cache(config_root, time.time(), limit=5000, used=3999)
278
+ assert _bash_reason("$s = gh pr view 1") == ""
279
+
280
+
281
+ def test_should_pass_a_token_assignment_with_no_cache_and_no_gh_on_path(
282
+ config_root: Path, rate_queries: _RateLimitQueries
283
+ ) -> None:
284
+ rate_queries.raised_error = FileNotFoundError("gh")
285
+ command = "$env:GH_TOKEN = gh auth token -u account-a; gh repo list; Remove-Item Env:GH_TOKEN"
286
+ assert _bash_reason(command) == ""
287
+ assert rate_queries.call_count == 1
288
+
289
+
290
+ @pytest.mark.parametrize(
291
+ "command",
292
+ ["if ($x) {gh run watch 1}", "try {gh run watch 1} catch {}"],
293
+ )
294
+ def test_should_detect_watch_behind_a_glued_brace(command: str) -> None:
295
+ assert gate.runs_gh_watch_command(command) is True
296
+
297
+
298
+ def test_should_not_detect_watch_in_quoted_braced_text() -> None:
299
+ assert gate.runs_gh_watch_command('echo "{gh run watch}"') is False
300
+
301
+
302
+ def test_should_classify_a_read_behind_a_glued_brace_as_budgeted() -> None:
303
+ assert gate.runs_budgeted_gh_read("if ($x) {gh pr view 1}") is True
304
+
305
+
306
+ @pytest.mark.parametrize(
307
+ "command",
308
+ [
309
+ "for x in a b c; do gh pr view $x; done",
310
+ "foreach ($x in $all) { gh pr view $x }",
311
+ "while read pr; do gh pr view $pr; done < prs.txt",
312
+ "while true; do gh run view 1; sleep 60; done",
313
+ "while true; do gh run view 1; sleep 1m; done",
314
+ "while :; do gh run view 1; sleep 30; sleep 30; done",
315
+ "gh pr list | while read n; do echo $n; sleep 1; done",
316
+ "gh run view 1; for f in a b; do echo $f; sleep 1; done",
317
+ "until gh run view 1 --exit-status; do sleep 60; done",
318
+ "while ($true) { gh run view 1; Start-Sleep -Seconds 90 }",
319
+ "while ($true) { gh run view 1; Start-Sleep -Milliseconds 60000 }",
320
+ "while true; do gh run view 1; sleep $delay; done",
321
+ "while true; do date; sleep 1; done",
322
+ "watch -n 60 gh run view 1",
323
+ "watch -n 1 date",
324
+ "gh run view 1",
325
+ 'echo "while true; do gh run view 1; sleep 1; done"',
326
+ ],
327
+ )
328
+ def test_should_pass_finite_slow_and_gh_free_loops(command: str) -> None:
329
+ assert gate.runs_tight_gh_polling_loop(command) is False
330
+
331
+
332
+ def test_watch_reason_names_a_loop_form_that_passes_the_loop_check(config_root: Path) -> None:
333
+ reason = _bash_reason("gh run watch 123")
334
+ assert "60" in reason
335
+ assert "gh run view" in reason
336
+ suggested_loop = reason.split("`")[1]
337
+ assert "gh run view" in suggested_loop
338
+ assert gate.runs_tight_gh_polling_loop(suggested_loop) is False
339
+ assert gate.runs_gh_watch_command(suggested_loop) is False
340
+
341
+
342
+ @pytest.mark.parametrize(
343
+ "command",
344
+ [
345
+ "gh api repos/o/r/pulls",
346
+ "gh api -X GET repos/o/r/pulls -f state=open",
347
+ "gh api --paginate repos/o/r/issues",
348
+ "gh pr view 12",
349
+ "gh pr list",
350
+ "gh pr status",
351
+ "gh pr checks 12",
352
+ "gh pr diff 12",
353
+ "gh issue view 4",
354
+ "gh run view 123",
355
+ "gh run list -L 5",
356
+ "gh run download 123",
357
+ "gh release view v1",
358
+ "gh search prs repo:o/r",
359
+ "gh status",
360
+ "gh -R o/r repo view",
361
+ "cd repo && gh pr view 12",
362
+ "x=$(gh api user -q .login)",
363
+ ],
364
+ )
365
+ def test_should_classify_remote_reads_as_budgeted(command: str) -> None:
366
+ assert gate.runs_budgeted_gh_read(command) is True
367
+
368
+
369
+ @pytest.mark.parametrize(
370
+ "command",
371
+ [
372
+ "gh pr create --title t --body b",
373
+ "gh pr merge 12 --squash",
374
+ "gh pr comment 12 --body hi",
375
+ "gh pr ready 12",
376
+ "gh workflow run ci.yml",
377
+ "gh api -X POST repos/o/r/issues -f title=t",
378
+ "gh api --method=PATCH repos/o/r/issues/1",
379
+ "gh api repos/o/r/issues -f title=t",
380
+ "gh api repos/o/r/issues --input body.json",
381
+ "gh api graphql -f query='query{viewer{login}}'",
382
+ "gh api rate_limit",
383
+ "gh auth status",
384
+ "gh auth token",
385
+ "gh --version",
386
+ "gh help",
387
+ "gh pr view 12 --help",
388
+ "gh",
389
+ 'echo "gh pr view 12"',
390
+ "git log --oneline",
391
+ ],
392
+ )
393
+ def test_should_not_budget_writes_local_calls_and_other_buckets(command: str) -> None:
394
+ assert gate.runs_budgeted_gh_read(command) is False
395
+
396
+
397
+ def test_fresh_cache_at_four_fifths_denies_a_read_with_used_limit_and_reset(
398
+ config_root: Path, rate_queries: _RateLimitQueries
399
+ ) -> None:
400
+ _write_cache(config_root, time.time(), limit=5000, used=4000)
401
+ reason = _bash_reason("gh pr view 12")
402
+ assert "4000" in reason
403
+ assert "5000" in reason
404
+ assert time.strftime("%H:%M", time.gmtime(_RESET_EPOCH_SECONDS)) in reason
405
+ assert "git" in reason
406
+ assert "wait" in reason.lower()
407
+ assert rate_queries.call_count == 0
408
+
409
+
410
+ def test_out_of_range_reset_still_denies_without_a_reset_time(
411
+ config_root: Path, rate_queries: _RateLimitQueries
412
+ ) -> None:
413
+ cache_path = _cache_path(config_root)
414
+ cache_path.parent.mkdir(parents=True)
415
+ cache_path.write_text(
416
+ json.dumps({"read_at": time.time(), "limit": 5000, "used": 4500, "reset": 10**30}),
417
+ encoding="utf-8",
418
+ )
419
+ reason = _bash_reason("gh pr view 12")
420
+ assert "4500 of 5000" in reason
421
+ assert "resets at" not in reason
422
+
423
+
424
+ def test_fresh_cache_just_under_four_fifths_passes(
425
+ config_root: Path, rate_queries: _RateLimitQueries
426
+ ) -> None:
427
+ _write_cache(config_root, time.time(), limit=5000, used=3999)
428
+ assert _bash_reason("gh pr view 12") == ""
429
+ assert rate_queries.call_count == 0
430
+
431
+
432
+ @pytest.mark.parametrize(
433
+ "command",
434
+ [
435
+ "gh pr create --title t --body b",
436
+ "gh pr merge 12 --squash",
437
+ "gh api -X POST repos/o/r/issues -f title=t",
438
+ "gh api graphql -f query='query{viewer{login}}'",
439
+ "gh api rate_limit",
440
+ "gh auth status",
441
+ "gh --version",
442
+ "gh pr view 12 --help",
443
+ ],
444
+ )
445
+ def test_spent_budget_still_passes_writes_and_unbudgeted_calls(
446
+ config_root: Path, rate_queries: _RateLimitQueries, command: str
447
+ ) -> None:
448
+ _write_cache(config_root, time.time(), limit=5000, used=4999)
449
+ assert _bash_reason(command) == ""
450
+
451
+
452
+ def test_stale_cache_triggers_one_query_and_rewrites_the_file(
453
+ config_root: Path, rate_queries: _RateLimitQueries
454
+ ) -> None:
455
+ _write_cache(config_root, time.time() - _FIVE_MINUTES_IN_SECONDS - 1, limit=5000, used=4500)
456
+ assert _bash_reason("gh pr view 12") == ""
457
+ assert _bash_reason("gh pr view 13") == ""
458
+ assert rate_queries.call_count == 1
459
+ rewritten_cache = json.loads(_cache_path(config_root).read_text(encoding="utf-8"))
460
+ assert rewritten_cache["used"] == 10
461
+ assert rewritten_cache["limit"] == 5000
462
+ assert rewritten_cache["reset"] == _RESET_EPOCH_SECONDS
463
+ assert time.time() - rewritten_cache["read_at"] < _FIVE_MINUTES_IN_SECONDS
464
+
465
+
466
+ def test_missing_cache_query_that_reports_a_spent_budget_denies(
467
+ config_root: Path, rate_queries: _RateLimitQueries
468
+ ) -> None:
469
+ rate_queries.answer_with(limit=5000, used=4800)
470
+ assert "4800" in _bash_reason("gh run view 1")
471
+ assert rate_queries.call_count == 1
472
+
473
+
474
+ @pytest.mark.parametrize(
475
+ "raised_error",
476
+ [
477
+ subprocess.TimeoutExpired(cmd="gh", timeout=10),
478
+ FileNotFoundError("gh"),
479
+ PermissionError("gh"),
480
+ ],
481
+ )
482
+ def test_failed_query_allows_and_is_not_retried_inside_five_minutes(
483
+ config_root: Path, rate_queries: _RateLimitQueries, raised_error: BaseException
484
+ ) -> None:
485
+ rate_queries.raised_error = raised_error
486
+ assert _bash_reason("gh pr view 12") == ""
487
+ assert _bash_reason("gh pr view 12") == ""
488
+ assert rate_queries.call_count == 1
489
+
490
+
491
+ def test_nonzero_query_exit_allows(config_root: Path, rate_queries: _RateLimitQueries) -> None:
492
+ rate_queries.answer_with(limit=5000, used=4900)
493
+ rate_queries.return_code = 1
494
+ assert _bash_reason("gh pr view 12") == ""
495
+ assert rate_queries.call_count == 1
496
+
497
+
498
+ @pytest.mark.parametrize(
499
+ "stdout_text",
500
+ [
501
+ "not json",
502
+ "{}",
503
+ json.dumps({"resources": {"core": {"limit": 0, "used": 0}}}),
504
+ json.dumps({"resources": {"core": {"used": 4900}}}),
505
+ json.dumps([1, 2]),
506
+ ],
507
+ )
508
+ def test_unreadable_query_output_allows(
509
+ config_root: Path, rate_queries: _RateLimitQueries, stdout_text: str
510
+ ) -> None:
511
+ rate_queries.stdout_text = stdout_text
512
+ assert _bash_reason("gh pr view 12") == ""
513
+ assert rate_queries.call_count == 1
514
+
515
+
516
+ @pytest.mark.parametrize(
517
+ "cache_text", ["{", "[]", '{"read_at": "soon", "limit": 5000, "used": 4900}', ""]
518
+ )
519
+ def test_corrupt_cache_counts_as_stale(
520
+ config_root: Path, rate_queries: _RateLimitQueries, cache_text: str
521
+ ) -> None:
522
+ cache_path = _cache_path(config_root)
523
+ cache_path.parent.mkdir(parents=True)
524
+ cache_path.write_text(cache_text, encoding="utf-8")
525
+ assert _bash_reason("gh pr view 12") == ""
526
+ assert rate_queries.call_count == 1
527
+
528
+
529
+ def test_unwritable_cache_folder_allows(
530
+ config_root: Path, rate_queries: _RateLimitQueries, monkeypatch: pytest.MonkeyPatch
531
+ ) -> None:
532
+ def _refuse_replace(*all_arguments: object) -> None:
533
+ raise PermissionError("cache")
534
+
535
+ monkeypatch.setattr(budget_reader.os, "replace", _refuse_replace)
536
+ rate_queries.answer_with(limit=5000, used=10)
537
+ assert _bash_reason("gh pr view 12") == ""
538
+
539
+
540
+ def test_unreadable_cache_file_allows(
541
+ config_root: Path, rate_queries: _RateLimitQueries, monkeypatch: pytest.MonkeyPatch
542
+ ) -> None:
543
+ _write_cache(config_root, time.time(), limit=5000, used=4900)
544
+
545
+ def _refuse_read(*all_arguments: object, **all_options: object) -> str:
546
+ raise PermissionError("cache")
547
+
548
+ monkeypatch.setattr(Path, "read_text", _refuse_read)
549
+ assert _bash_reason("gh pr view 12") == ""
550
+
551
+
552
+ def test_command_without_gh_reads_no_cache_and_runs_no_query(
553
+ config_root: Path, rate_queries: _RateLimitQueries
554
+ ) -> None:
555
+ _write_cache(config_root, time.time() - _FIVE_MINUTES_IN_SECONDS - 1, limit=5000, used=4900)
556
+ assert _bash_reason("git log --oneline; while true; do date; sleep 1; done") == ""
557
+ assert rate_queries.call_count == 0
558
+
559
+
560
+ def test_watch_command_is_denied_with_the_timed_read_advice(
561
+ config_root: Path, rate_queries: _RateLimitQueries
562
+ ) -> None:
563
+ reason = _bash_reason("gh run watch 123")
564
+ assert "watch" in reason
565
+ assert "60" in reason
566
+ assert "task notification" in reason
567
+ assert rate_queries.call_count == 0
568
+
569
+
570
+ def test_tight_loop_is_denied_with_the_sixty_second_advice(
571
+ config_root: Path, rate_queries: _RateLimitQueries
572
+ ) -> None:
573
+ reason = _bash_reason("while true; do gh run view 1; sleep 10; done")
574
+ assert "60" in reason
575
+ assert "sleep" in reason
576
+ assert reason != _bash_reason("gh run watch 1")
577
+
578
+
579
+ def test_watch_refusal_comes_before_the_loop_refusal(
580
+ config_root: Path, rate_queries: _RateLimitQueries
581
+ ) -> None:
582
+ watch_reason = _bash_reason("gh run watch 1")
583
+ assert _bash_reason("while true; do gh run watch 1; sleep 5; done") == watch_reason
584
+
585
+
586
+ def test_powershell_payload_with_watch_is_denied(
587
+ config_root: Path, rate_queries: _RateLimitQueries
588
+ ) -> None:
589
+ stdout_text = _stdout_from_main(
590
+ {"tool_name": "PowerShell", "tool_input": {"command": "gh pr checks 12 --watch"}}
591
+ )
592
+ assert json.loads(stdout_text)["hookSpecificOutput"]["permissionDecision"] == "deny"
593
+
594
+
595
+ def test_other_tool_payload_emits_nothing(
596
+ config_root: Path, rate_queries: _RateLimitQueries
597
+ ) -> None:
598
+ _write_cache(config_root, time.time(), limit=5000, used=4900)
599
+ assert (
600
+ _stdout_from_main({"tool_name": "Write", "tool_input": {"command": "gh run watch 1"}}) == ""
601
+ )
602
+ assert rate_queries.call_count == 0
@@ -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, the pieces_per_level_note 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, the auto mode denial quick fix, and the refusal Stop gate that holds a turn, twice at most for each kind, to ask the refusal question and, after `Allow it`, to add the durable rule.
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.
@@ -8,6 +8,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
8
8
  - `blocking/msys_rev_path_rewriter.py` adds a narrow `MSYS2_ARG_CONV_EXCL` prefix for affected revision and path tokens.
9
9
  - `blocking/headless_claude_broker_gate.py` denies a headless `claude -p` or `claude --print` call and names the broker command to run instead.
10
10
  - `blocking/gh_global_account_switch_gate.py` denies `gh auth switch`, `gh auth login`, and `gh auth logout` and names the per-command `GH_TOKEN` form to run instead.
11
+ - `blocking/gh_api_budget_gate.py` keeps an agent from draining the GitHub API limit. It denies `gh run watch` and `gh pr checks --watch` and names a background loop that sleeps 60 seconds between `gh run view` calls. It denies a Bash `while`, `until` or `for` loop, a PowerShell `while`, `do`, `for` or `foreach` loop, or `watch`, that calls `gh` with under 60 seconds of `sleep` or `Start-Sleep` per pass, and an endless loop such as `while :` or `for (;;)` that calls `gh` with no sleep. It denies a `gh` read on the core REST limit, such as `gh pr view` or a `gh api` GET, while four fifths or more of that limit is used. `hooks_constants/gh_api_budget.py` reads the limit from `gh api rate_limit` at most once every five minutes and caches it in `<managed root>/cache/gh_api_budget.json`. Writes, local commands, `gh api graphql` and `gh api rate_limit` pass, and a limit it cannot read lets the call through.
11
12
  - `blocking/cloud_graphql_gate.py` denies the `gh` commands that call GraphQL (`gh api graphql` with any flags before the endpoint, `gh pr`, `gh issue`, `gh project` and `gh discussion` except `gh pr diff` and `gh pr list --web`, `gh status`, `gh org list`, `gh release list`, `gh release view` with a tag, `gh workflow run` without `--ref`, and a few `repo`, `label`, `search`, `ruleset` and `gist` commands, read past `if`, `!` and command substitutions) and an HTTP client or `python -c` style call to `api.github.com/graphql`, with or without a port, inside a cloud session, where the proxy answers GraphQL with HTTP 403, and names the REST routes to run instead.
12
13
  - `blocking/python_windows_invocation_gate.py` denies, on a Windows host, `python`, `python3` or `py` run with `-I` and without `-X utf8`, because `-I` ignores `PYTHONUTF8` and non-ASCII output then stops with `UnicodeEncodeError: 'charmap'`. Under the PowerShell tool it also denies a `python -c "..."` argument that holds `\"`, because PowerShell ends the string at that quote, and names a script file or a single-quoted here-string to use instead.
13
14
  - `blocking/transcript_root_search_gate.py` denies a recursive walk or content search that starts at a Claude transcript root, a `projects` folder directly under `.claude`, `.claude-<name>` or `.claude-profiles/<profile>`, with no project folder after it, or with a bare `*` or `**` segment that descends into every project folder. It reads `find`, `grep -r`, `rg`, `ls -R`, `Get-ChildItem -Recurse` or `-Depth`, `Select-String`, and the Grep and Glob tools, and expands variables the command assigns, such as `$p="..."`. A one-level name listing, such as `Get-ChildItem <root> -Directory -Filter "*id*"`, passes. The deny reason names the fix: list the project folders by name, then read the one transcript. The gate reads the root path as the command spells it, so a walk that starts above the root, or a glob that spells the root name or a project-name prefix such as `pro*` or `C--*`, passes.
@@ -22,6 +23,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
22
23
  - `blocking/msys_rev_path_rewriter.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds. `ALL_BASH_HOSTED_HOOK_ENTRIES` selects the `Bash` tool.
23
24
  - `blocking/headless_claude_broker_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
24
25
  - `blocking/gh_global_account_switch_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
26
+ - `blocking/gh_api_budget_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, when the command calls `gh`. Its `gh api rate_limit` query times out after `10` seconds.
25
27
  - `blocking/cloud_graphql_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, when `CLAUDE_CODE_REMOTE` is `true`.
26
28
  - `blocking/python_windows_invocation_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools. The `-I` check runs only when `os.name` is `nt`.
27
29
  - `blocking/transcript_root_search_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, and on its own on `PreToolUse`, matcher `Grep|Glob`, timeout `10` seconds in `hooks.json`.
@@ -38,6 +40,7 @@ Preconditions:
38
40
  - **Pre-call dispatch.** Input is a clean Bash command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_pre_tool_use_dispatcher.py -q`. The adjacent test observes the combined decision and hosted precedence.
39
41
  - **Revision rewrite.** Input is a Git command with `origin/main:.claude/settings.json`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_msys_rev_path_rewriter.py -q`. The adjacent test observes the `origin/main:` exclusion prefix.
40
42
  - **Broker gate.** Input is a `claude -p task` command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_headless_claude_broker_gate.py -q`. The adjacent test observes a denial that names the broker command.
43
+ - **GitHub API budget gate.** Input is `gh run watch 123`, `while :; do gh run view 1; sleep 10; done`, and `gh pr view 12` with a fresh cache file at 4000 of 5000 used. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_gh_api_budget_gate.py -q`. The adjacent test observes each denial and its reason, a pass for writes, `gh api graphql` and a 60 second loop, and one rate limit query per five minutes.
41
44
  - **Cloud GraphQL gate.** Input is a `gh api graphql` command with `CLAUDE_CODE_REMOTE=true`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_cloud_graphql_gate.py -q`. The adjacent test observes a denial that names the REST routes, and silence outside a cloud session.
42
45
  - **Python Windows invocation gate.** Input is `python -I s.py` on Windows, and a PowerShell `python -c "print(\"x\")"`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_python_windows_invocation_gate.py -q`. The adjacent test observes a denial that names `-X utf8` or the here-string, and a pass for `-IX utf8`, `-I -X utf8`, and the Bash tool.
43
46
  - **Transcript root search gate.** Input is `Get-ChildItem $p -Recurse -File -Filter *.jsonl` with `$p` bound to `~/.claude-profiles/work/projects`, and a Grep call whose path is `~/.claude/projects`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_transcript_root_search_gate.py -q`. The adjacent test observes a denial that names the list-then-read fix, and a pass for `Get-ChildItem $p -Directory -Filter "*01WUQeBG*"` and a walk inside one project folder.