claude-dev-env 8.116.5 → 8.117.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/bin/ever-registered-hooks.mjs +2 -0
  2. package/bin/ever-registered-hooks.test.mjs +4 -0
  3. package/bin/install-constants.mjs +3 -1
  4. package/bin/install.cursor-rules.test.mjs +64 -2
  5. package/bin/install.mjs +15 -2
  6. package/bin/install.prune.test.mjs +92 -0
  7. package/bin/install.test.mjs +1 -0
  8. package/docs/model-choice/escalation.md +3 -3
  9. package/docs/model-choice/subagents-and-fan-out.md +2 -2
  10. package/docs/model-choice/which-model.md +1 -1
  11. package/docs/references/working-style.md +1 -0
  12. package/docs/rule-guides/question-presentation.md +6 -0
  13. package/docs/rule-guides/session-title.md +8 -9
  14. package/docs/rule-guides/subagent-model-effort.md +13 -13
  15. package/hooks/advisory/owned_pr_review_loop.py +2 -3
  16. package/hooks/blocking/bash_post_call_dispatcher.py +17 -9
  17. package/hooks/blocking/bash_pre_tool_use_dispatcher.py +12 -8
  18. package/hooks/blocking/final_reply_gate.py +5 -9
  19. package/hooks/blocking/open_tasks_stop_gate.py +9 -20
  20. package/hooks/blocking/open_tasks_transcript.py +8 -3
  21. package/hooks/blocking/pii_prevention_blocker_parts/repository_exemption.py +7 -2
  22. package/hooks/blocking/question_brief_gate.py +382 -0
  23. package/hooks/blocking/step_note_gate.py +5 -2
  24. package/hooks/blocking/task_subject_length_gate.py +111 -0
  25. package/hooks/blocking/test_bash_post_call_dispatcher.py +36 -1
  26. package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +57 -0
  27. package/hooks/blocking/test_final_reply_gate.py +26 -2
  28. package/hooks/blocking/test_open_tasks_stop_gate.py +21 -11
  29. package/hooks/blocking/test_question_brief_gate.py +916 -0
  30. package/hooks/blocking/test_step_note_gate.py +26 -0
  31. package/hooks/blocking/test_task_subject_length_gate.py +221 -0
  32. package/hooks/blocking/test_turn_review_child.py +166 -0
  33. package/hooks/blocking/test_turn_review_claim.py +194 -0
  34. package/hooks/blocking/test_turn_review_findings.py +124 -1
  35. package/hooks/blocking/test_turn_review_gate.py +1312 -10
  36. package/hooks/blocking/test_turn_review_repositories.py +65 -0
  37. package/hooks/blocking/test_turn_review_snapshot.py +8 -0
  38. package/hooks/blocking/test_turn_review_state.py +132 -0
  39. package/hooks/blocking/test_turn_review_transcript.py +125 -0
  40. package/hooks/blocking/tests/test_repository_exemption.py +11 -0
  41. package/hooks/blocking/turn_review_child.py +145 -0
  42. package/hooks/blocking/turn_review_claim.py +306 -0
  43. package/hooks/blocking/turn_review_findings.py +173 -13
  44. package/hooks/blocking/turn_review_gate.py +259 -262
  45. package/hooks/blocking/turn_review_repositories.py +58 -0
  46. package/hooks/blocking/turn_review_snapshot.py +5 -1
  47. package/hooks/blocking/turn_review_state.py +260 -0
  48. package/hooks/blocking/turn_review_transcript.py +158 -0
  49. package/hooks/features/bash-dispatchers.md +1 -3
  50. package/hooks/features/conduct-gates.md +19 -9
  51. package/hooks/features/lifecycle-cleanup.md +1 -1
  52. package/hooks/features/spawn-routing.md +1 -1
  53. package/hooks/hooks.json +24 -11
  54. package/hooks/hooks_constants/final_reply_gate_constants.py +0 -3
  55. package/hooks/hooks_constants/hook_time_budget.py +61 -0
  56. package/hooks/hooks_constants/hosted_hook_runner.py +51 -21
  57. package/hooks/hooks_constants/hosted_hook_runner_constants.py +3 -0
  58. package/hooks/hooks_constants/nested_project_hooks_constants.py +8 -0
  59. package/hooks/hooks_constants/once_per_session_constants.py +1 -0
  60. package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +0 -4
  61. package/hooks/hooks_constants/owned_pr_review_loop_constants.py +0 -4
  62. package/hooks/hooks_constants/pre_tool_use_context_runner.py +23 -3
  63. package/hooks/hooks_constants/pre_tool_use_context_runner_constants.py +5 -0
  64. package/hooks/hooks_constants/pre_tool_use_stdin.py +1 -1
  65. package/hooks/hooks_constants/question_brief_gate_constants.py +66 -0
  66. package/hooks/hooks_constants/session_title_constants.py +8 -29
  67. package/hooks/hooks_constants/stop_hook_hold.py +54 -0
  68. package/hooks/hooks_constants/stop_hook_hold_constants.py +9 -0
  69. package/hooks/hooks_constants/subagent_effort_levels.json +6 -0
  70. package/hooks/hooks_constants/subagent_effort_route_constants.py +20 -19
  71. package/hooks/hooks_constants/task_subject_length_gate_constants.py +43 -0
  72. package/hooks/hooks_constants/test_hook_time_budget.py +104 -0
  73. package/hooks/hooks_constants/test_hosted_hook_runner.py +12 -0
  74. package/hooks/hooks_constants/test_pre_tool_use_context_runner.py +16 -0
  75. package/hooks/hooks_constants/test_pre_tool_use_stdin.py +6 -0
  76. package/hooks/hooks_constants/test_stop_hook_hold.py +40 -0
  77. package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py +1 -2
  78. package/hooks/hooks_constants/turn_review_gate_constants.py +246 -12
  79. package/hooks/lifecycle/nested_project_hooks.py +34 -4
  80. package/hooks/lifecycle/test_nested_project_hooks.py +52 -0
  81. package/hooks/once_per_session.py +33 -4
  82. package/hooks/open_task_asks.py +1 -1
  83. package/hooks/owned_pr_session_record.py +1 -76
  84. package/hooks/routing/subagent_effort_route.py +107 -13
  85. package/hooks/routing/subagent_effort_route_hook.py +9 -8
  86. package/hooks/routing/test_subagent_effort_route.py +201 -14
  87. package/hooks/routing/test_subagent_effort_route_hook.py +56 -0
  88. package/hooks/routing/test_thread_spawn_pace_hook.py +32 -0
  89. package/hooks/routing/thread_spawn_pace_hook.py +3 -3
  90. package/hooks/session/background_silence_prompt.py +1 -1
  91. package/hooks/session/test_background_silence_prompt.py +8 -0
  92. package/hooks/session/test_tracking_nudge.py +125 -2
  93. package/hooks/session/tracking_nudge.py +28 -18
  94. package/hooks/session_title_transcript.py +216 -0
  95. package/hooks/test_once_per_session.py +10 -0
  96. package/hooks/test_owned_pr_session_record.py +0 -26
  97. package/hooks/test_session_title_transcript.py +142 -0
  98. package/hooks/validation/post_tool_use_dispatcher.py +38 -21
  99. package/hooks/validation/test_post_tool_use_dispatcher.py +43 -0
  100. package/package.json +1 -1
  101. package/rules/question-presentation.md +4 -4
  102. package/rules/subagent-model-effort.md +1 -1
  103. package/scripts/account_broker_support.py +24 -5
  104. package/scripts/claude_account_worker.py +4 -3
  105. package/scripts/dev_env_scripts_constants/account_broker_constants.py +1 -0
  106. package/scripts/policy_lint/adapter_configuration.py +12 -11
  107. package/scripts/policy_lint/config/approved_test_pairs.py +27 -0
  108. package/scripts/policy_lint/config/constants.py +2 -2
  109. package/scripts/test_account_broker_support.py +43 -1
  110. package/scripts/test_claude_account_worker.py +1 -0
  111. package/scripts/tests/test_adapter_configuration.py +10 -2
  112. package/scripts/tests/test_policy_lint_rules_pairing.py +24 -0
  113. package/hooks/blocking/owned_pr_merge_stop_gate.py +0 -185
  114. package/hooks/blocking/session_title_turn_gate.py +0 -417
  115. package/hooks/blocking/test_owned_pr_merge_stop_gate.py +0 -254
  116. package/hooks/blocking/test_session_title_turn_gate.py +0 -396
  117. package/hooks/hooks_constants/owned_pr_merge_stop_gate_constants.py +0 -40
@@ -4,7 +4,9 @@
4
4
  Reads the tool payload from stdin once, runs each hosted hook in-process via
5
5
  runpy in the fixed order declared in the constants module, aggregates the
6
6
  results, and emits one PostToolUse block decision when any hook blocked
7
- (carrying every blocking reason) or exits zero to allow.
7
+ (carrying every blocking reason) or exits zero to allow. When a hosted hook
8
+ exits 2, the dispatcher exits 2 after the whole roster runs, and on
9
+ PostToolUse the host then shows that hook's stderr to the model.
8
10
 
9
11
  The hosted hooks keep every side effect they have today: the formatter writes
10
12
  the reformatted file to disk, and the doc publisher uploads the gist. Running
@@ -44,6 +46,7 @@ from hooks_constants.post_tool_use_dispatcher_constants import ( # noqa: E402
44
46
  from hooks_constants.pre_tool_use_stdin import ( # noqa: E402
45
47
  read_hook_input_dictionary_from_stdin,
46
48
  )
49
+ from hooks_constants.hosted_hook_runner_constants import BLOCKING_EXIT_CODE
47
50
 
48
51
 
49
52
  @dataclass
@@ -54,11 +57,13 @@ class PostHostedHookResult:
54
57
  captured_stdout: The text the hook wrote to stdout during its run.
55
58
  did_crash: True when the hook raised a non-SystemExit exception.
56
59
  is_blocking: True when this hook's crash surfaces a blocking signal.
60
+ exit_code: The integer code the hook passed to SystemExit, else 0.
57
61
  """
58
62
 
59
63
  captured_stdout: str
60
64
  did_crash: bool = field(default=False)
61
65
  is_blocking: bool = field(default=False)
66
+ exit_code: int = field(default=0)
62
67
 
63
68
 
64
69
  def _log_hook_crash(hook_script_path: str, error: Exception) -> None:
@@ -88,8 +93,8 @@ def run_hosted_hook(
88
93
  Sets stdin to a fresh stream over payload_text, sets argv to the hook's
89
94
  script path plus its argument tail so a hook reading sys.argv resolves the
90
95
  same arguments the live entry passes, captures stdout into a buffer, runs
91
- the hook via runpy under __main__, catches SystemExit to absorb the hook's
92
- exit without ending the dispatcher, and catches a non-SystemExit exception
96
+ the hook via runpy under __main__, catches SystemExit to record the hook's
97
+ exit code without ending the dispatcher, and catches a non-SystemExit exception
93
98
  to log the crash and classify it. Always restores stdin, stdout, and argv
94
99
  in the finally block.
95
100
 
@@ -101,22 +106,23 @@ def run_hosted_hook(
101
106
  is_blocking: Whether a crash from this hook surfaces a blocking signal.
102
107
 
103
108
  Returns:
104
- A PostHostedHookResult carrying the captured stdout, crash flag, and
105
- blocking classification.
109
+ A PostHostedHookResult carrying the captured stdout, crash flag,
110
+ blocking classification, and exit code.
106
111
  """
107
112
  original_stdin = sys.stdin
108
113
  original_stdout = sys.stdout
109
114
  original_argv = sys.argv
110
115
  captured_output = io.StringIO()
111
116
  hook_did_crash = False
117
+ hook_exit_code = 0
112
118
 
113
119
  try:
114
120
  sys.stdin = io.StringIO(payload_text)
115
121
  sys.stdout = captured_output
116
122
  sys.argv = [hook_script_path, *all_hook_arguments]
117
123
  runpy.run_path(hook_script_path, run_name="__main__")
118
- except SystemExit:
119
- pass
124
+ except SystemExit as exit_signal:
125
+ hook_exit_code = exit_signal.code if isinstance(exit_signal.code, int) else 0
120
126
  except Exception as error:
121
127
  _log_hook_crash(hook_script_path, error)
122
128
  hook_did_crash = True
@@ -129,6 +135,7 @@ def run_hosted_hook(
129
135
  captured_stdout=captured_output.getvalue(),
130
136
  did_crash=hook_did_crash,
131
137
  is_blocking=is_blocking,
138
+ exit_code=hook_exit_code,
132
139
  )
133
140
 
134
141
 
@@ -288,32 +295,43 @@ def _resolve_argument_tail(each_entry: PostHostedHookEntry, plugin_root: str) ->
288
295
  return resolved_arguments
289
296
 
290
297
 
291
- def dispatch(payload_text: str, plugin_root: str) -> None:
292
- """Run all hosted PostToolUse hooks and emit one aggregated decision.
298
+ def _run_every_hosted_hook(payload_text: str, plugin_root: str) -> list[PostHostedHookResult]:
299
+ return [
300
+ run_hosted_hook(
301
+ _resolve_hook_script_path(each_entry.script_relative_path),
302
+ _resolve_argument_tail(each_entry, plugin_root),
303
+ payload_text,
304
+ each_entry.is_blocking,
305
+ )
306
+ for each_entry in ALL_POST_HOSTED_HOOK_ENTRIES
307
+ ]
308
+
309
+
310
+ def dispatch(payload_text: str, plugin_root: str) -> int:
311
+ """Run all hosted PostToolUse hooks, emit one aggregated decision, and return the exit code.
293
312
 
294
313
  Runs each hosted hook in-process via run_hosted_hook in the fixed order,
295
314
  aggregates the results, and emits a block JSON object when any hook blocked.
296
- A clean run with no block emits nothing and the caller exits zero to allow.
315
+ A clean run with no block emits nothing. Returns 2 when a hosted hook exited
316
+ 2 and 0 otherwise, and the caller exits with that code.
297
317
 
298
318
  Args:
299
319
  payload_text: The raw JSON payload text to replay to each hook.
300
320
  plugin_root: The plugin root absolute path used to resolve hook
301
321
  arguments.
302
- """
303
- all_results: list[PostHostedHookResult] = []
304
- for each_entry in ALL_POST_HOSTED_HOOK_ENTRIES:
305
- script_path = _resolve_hook_script_path(each_entry.script_relative_path)
306
- argument_tail = _resolve_argument_tail(each_entry, plugin_root)
307
- hook_result = run_hosted_hook(
308
- script_path, argument_tail, payload_text, each_entry.is_blocking
309
- )
310
- all_results.append(hook_result)
311
322
 
323
+ Returns:
324
+ The exit code the dispatcher hands the host.
325
+ """
326
+ all_results = _run_every_hosted_hook(payload_text, plugin_root)
312
327
  aggregated_decision = aggregate_post_hosted_hook_results(all_results)
313
328
  if aggregated_decision.should_block:
314
329
  _emit_block_decision(aggregated_decision)
315
330
  else:
316
331
  _emit_non_block_stdout(aggregated_decision.all_non_block_stdout, sys.stdout)
332
+ if any(each_result.exit_code == BLOCKING_EXIT_CODE for each_result in all_results):
333
+ return BLOCKING_EXIT_CODE
334
+ return 0
317
335
 
318
336
 
319
337
  def _resolve_plugin_root() -> str:
@@ -336,8 +354,7 @@ def main() -> None:
336
354
  sys.exit(0)
337
355
 
338
356
  payload_text = json.dumps(payload_dict)
339
- dispatch(payload_text, _resolve_plugin_root())
340
- sys.exit(0)
357
+ sys.exit(dispatch(payload_text, _resolve_plugin_root()))
341
358
 
342
359
 
343
360
  if __name__ == "__main__":
@@ -2,12 +2,15 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import io
5
6
  import json
6
7
  import os
7
8
  import subprocess
8
9
  import sys
9
10
  from pathlib import Path
10
11
 
12
+ import pytest
13
+
11
14
  _HOOKS_DIR = str(Path(__file__).resolve().parent.parent)
12
15
  if _HOOKS_DIR not in sys.path:
13
16
  sys.path.insert(0, _HOOKS_DIR)
@@ -368,3 +371,43 @@ def test_live_roster_contains_only_nonblocking_hooks() -> None:
368
371
  "workflow/auto_formatter.py",
369
372
  "advisory/edit_lint_context.py",
370
373
  )
374
+
375
+
376
+ _EXIT_PROBE_SOURCE = "import sys\nsys.stderr.write('probe child says stop\\n')\nsys.exit({exit_code})\n"
377
+
378
+
379
+ def _write_exit_probe(tmp_path: Path, exit_code: int) -> str:
380
+ probe_path = tmp_path / f"exit_{exit_code}_probe.py"
381
+ probe_path.write_text(_EXIT_PROBE_SOURCE.format(exit_code=exit_code), encoding="utf-8")
382
+ return str(probe_path)
383
+
384
+
385
+ @pytest.mark.parametrize(("child_exit_code", "expected_exit_code"), [(2, 2), (1, 0), (0, 0)])
386
+ def test_should_pass_a_hosted_hook_exit_two_to_the_host_with_its_stderr(
387
+ tmp_path: Path,
388
+ monkeypatch: pytest.MonkeyPatch,
389
+ capsys: pytest.CaptureFixture[str],
390
+ child_exit_code: int,
391
+ expected_exit_code: int,
392
+ ) -> None:
393
+ dispatcher_module = sys.modules[aggregate_post_hosted_hook_results.__module__]
394
+ later_marker = tmp_path / "later_hook_ran.txt"
395
+ later_probe = tmp_path / "later_probe.py"
396
+ later_probe.write_text(
397
+ f"from pathlib import Path\nPath({str(later_marker)!r}).write_text('ran')\n",
398
+ encoding="utf-8",
399
+ )
400
+ all_entries = (
401
+ PostHostedHookEntry(script_relative_path=_write_exit_probe(tmp_path, child_exit_code)),
402
+ PostHostedHookEntry(script_relative_path=str(later_probe)),
403
+ )
404
+ monkeypatch.setattr(dispatcher_module, "ALL_POST_HOSTED_HOOK_ENTRIES", all_entries)
405
+ monkeypatch.setattr(sys, "argv", [_DISPATCHER_SCRIPT])
406
+ monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps({"tool_name": _WRITE_TOOL_NAME})))
407
+
408
+ with pytest.raises(SystemExit) as raised_exit:
409
+ dispatcher_module.main()
410
+
411
+ assert (raised_exit.value.code or 0) == expected_exit_code
412
+ assert "probe child says stop" in capsys.readouterr().err
413
+ assert later_marker.exists()
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.116.5",
3
+ "version": "8.117.1",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,11 +1,11 @@
1
1
  # Present questions clearly
2
2
 
3
- Before every ask, repeats included, give a short formatted chat brief with context and each choice's effect. Add helpful visuals or artifacts.
3
+ Before every ask, repeats too, give a short chat brief with context, each choice's effect, and helpful visuals.
4
4
 
5
- Ask one short, self-contained question with two or three choices. Give each a short label and one short sentence. Reuse labels in the brief, comparison, and picker.
5
+ Ask one short question per item, never a chat list, with two or three choices, each a short label and sentence. Reuse labels in brief, comparison, and picker. Keep the turn's chat text before a question to 450 words and 15 list or table items; a Claude hook refuses more.
6
6
 
7
- Find the native question tool and schema. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question in its title or question field and choices in string or object fields. If unusable, ask in chat.
7
+ Find the native question tool. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question and choices in its fields. If unusable, ask in chat.
8
8
 
9
- When the user asks for option cards, or for a Codex visual comparison, read the full text first.
9
+ When the user asks for option cards or a Codex visual comparison, read the full text first.
10
10
 
11
11
  **Full text:** [`~/.claude/docs/rule-guides/question-presentation.md`](../docs/rule-guides/question-presentation.md).
@@ -11,7 +11,7 @@ paths:
11
11
 
12
12
  **When:** Write or change anything that starts another agent, such as an agent definition, a skill, a hook, a workflow or a `claude -p` command.
13
13
 
14
- Name both the model and the effort on every spawn. Opus runs at medium, Sonnet at high, Fable at low, medium or high, and only Haiku runs at xhigh or max. Use Anthropic models only. An advisor that is not the built-in advisor tool runs on Opus at high.
14
+ Name both the model and the effort on every spawn. The efforts each model may run at, and the effort it gets otherwise, are in [`subagent_effort_levels.json`](../hooks/hooks_constants/subagent_effort_levels.json). Use Anthropic models only. An advisor that is not the built-in advisor tool runs on Opus at high.
15
15
 
16
16
  **Enforcement:** `hooks/routing/subagent_effort_route_hook.py` sets the allowed effort on Agent and Task spawns, and `hooks/routing/thread_spawn_pace_hook.py` does it for thread spawns that name a model.
17
17
 
@@ -293,7 +293,8 @@ def read_published_meters(account: Account) -> Meters | None:
293
293
  CLAUDE_USAGE_READINGS_DIR=/readings, account home .../alpha
294
294
  /readings/meters-ALPHA.json {"read_at": "<5 minutes ago>", "accounts": [{"name": "alpha",
295
295
  "meters": {"weekly_percent_left": 45.0, ...}}]}
296
- -> Meters(weekly_percent_left=45.0, ...), and the usage endpoint is not called
296
+ -> Meters(weekly_percent_left=45.0, ..., measured_at=<5 minutes ago>),
297
+ and the usage endpoint is not called
297
298
 
298
299
  A reading matches an account when its ``name`` equals the account home's folder name.
299
300
  A reading older than ``PUBLISHED_USAGE_MAX_AGE_SECONDS``, or dated more than
@@ -303,7 +304,8 @@ def read_published_meters(account: Account) -> Meters | None:
303
304
  account: Account whose meter is read.
304
305
 
305
306
  Returns:
306
- The published meters, or None when the folder is unset or holds no fresh reading for the account.
307
+ The published meters with the reading's ``read_at`` as their ``measured_at``, or None
308
+ when the folder is unset or holds no fresh reading for the account.
307
309
  """
308
310
  folder_text = os.environ.get(PUBLISHED_USAGE_DIRECTORY_ENV_VAR)
309
311
  if not folder_text:
@@ -316,8 +318,11 @@ def read_published_meters(account: Account) -> Meters | None:
316
318
  ]
317
319
  if not all_matches:
318
320
  return None
319
- newest_row = max(all_matches, key=lambda each_match: each_match[0])[1]
320
- return _meters_from_payload(newest_row.get("meters"))
321
+ newest_read_at, newest_row = max(all_matches, key=lambda each_match: each_match[0])
322
+ meters = _meters_from_payload(newest_row.get("meters"))
323
+ if meters is None:
324
+ return None
325
+ return dataclasses.replace(meters, measured_at=newest_read_at)
321
326
 
322
327
 
323
328
  def _fresh_published_rows(folder: Path, now: datetime) -> Iterator[tuple[datetime, dict[str, object]]]:
@@ -622,7 +627,7 @@ def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict
622
627
  next_probe = datetime.fromtimestamp(retry_at, timezone.utc) if is_held else None
623
628
  return Reading(account, cached_meters, cached_reason if isinstance(cached_reason, str) else None, measured, next_probe), False
624
629
  meters, unread_reason, is_rate_limited = read_meters_with_backoff(adapter.read_meters, account)
625
- measured_at = now.timestamp()
630
+ measured_at = _measured_timestamp(meters, now)
626
631
  is_rate_limited = account.product is Product.CLAUDE and is_rate_limited
627
632
  last_good = _last_good_meters(cached, now) if is_rate_limited else None
628
633
  if last_good is not None:
@@ -634,6 +639,20 @@ def _read_one_account(account: Account, adapter: ProductAdapter, all_cache: dict
634
639
  return Reading(account, meters, unread_reason, datetime.fromtimestamp(measured_at, timezone.utc), next_probe), True
635
640
 
636
641
 
642
+ def _measured_timestamp(meters: Meters | None, now: datetime) -> float:
643
+ """Return when *meters* were measured, never later than *now*.
644
+
645
+ ::
646
+
647
+ probe read at 12:00 -> 12:00 (now)
648
+ published reading read at 11:31 -> 11:31
649
+ published reading dated 12:02 (skewed) -> 12:00 (now)
650
+ """
651
+ if meters is None or meters.measured_at is None:
652
+ return now.timestamp()
653
+ return min(meters.measured_at, now).timestamp()
654
+
655
+
637
656
  def _last_good_meters(all_cached_fields: dict[str, object], now: datetime) -> tuple[Meters, float] | None:
638
657
  unread_reason = all_cached_fields.get("unread_reason")
639
658
  if unread_reason is not None and not (isinstance(unread_reason, str) and "HTTP Error 429" in unread_reason):
@@ -40,7 +40,7 @@ from dev_env_scripts_constants.claude_account_worker_constants import (
40
40
  VERBOSE_FLAG,
41
41
  UTF8_ENCODING,
42
42
  )
43
- from subagent_effort_route import model_family, routed_effort
43
+ from subagent_effort_route import load_effort_levels, model_family, routed_effort
44
44
 
45
45
  worker_job_runner = run_job
46
46
 
@@ -84,10 +84,11 @@ def worker_effort(model: str | None, effort: str | None) -> str | None:
84
84
  The allowed effort for the model's family, or ``effort`` when the
85
85
  model has no Anthropic family.
86
86
  """
87
- family = model_family(model)
87
+ all_efforts_by_family = load_effort_levels()
88
+ family = model_family(model, all_efforts_by_family)
88
89
  if family is None:
89
90
  return effort
90
- return routed_effort(family, effort)
91
+ return routed_effort(family, effort, all_efforts_by_family)
91
92
 
92
93
 
93
94
  def _invocation(*, model: str | None, effort: str | None, permission_mode: str, is_streamed: bool) -> list[str]:
@@ -228,6 +228,7 @@ class Meters:
228
228
  has_credits: bool = False
229
229
  is_credits_unlimited: bool = False
230
230
  credit_balance: float | None = None
231
+ measured_at: datetime | None = field(default=None, compare=False)
231
232
 
232
233
  @property
233
234
  def tightest_percent_left(self) -> float | None:
@@ -136,14 +136,14 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
136
136
  hooks/blocking/session_title_format_gate.py -> exempt
137
137
  hooks/blocking/artifact_dark_mode_gate.py -> exempt
138
138
  hooks/blocking/send_user_file_worktree_root_gate.py -> exempt
139
+ hooks/blocking/question_brief_gate.py -> exempt
139
140
  hooks/blocking/build_eval_before_eval_write_gate.py -> exempt
140
141
  hooks/blocking/final_reply_gate.py -> exempt
141
142
  hooks/blocking/open_tasks_stop_gate.py -> exempt
142
- hooks/blocking/owned_pr_merge_stop_gate.py -> exempt
143
- hooks/blocking/session_title_turn_gate.py -> exempt
144
143
  hooks/blocking/resolve_thread_reply_gate.py -> exempt
145
144
  hooks/blocking/turn_review_gate.py -> exempt
146
145
  hooks/blocking/wakeup_cap_gate.py -> exempt
146
+ hooks/blocking/task_subject_length_gate.py -> exempt
147
147
  hooks/blocking/some_new_blocker.py -> flagged
148
148
 
149
149
  The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -173,10 +173,8 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
173
173
  The verify-before-acting hook runs after a mutating call has finished. It
174
174
  asks the model to check a hedged claim, and the call it reads stays in place.
175
175
 
176
- The session title gates keep the session title in its status format. One
177
- denies a malformed title, and the other asks for a new title when the
178
- shown status stops fitting. They decide the shape of a title and no code
179
- or safety policy.
176
+ The session title format gate denies a malformed title. It decides the
177
+ shape of a title and no code or safety policy.
180
178
 
181
179
  The artifact page gate denies a page publish whose text is unreadable in
182
180
  dark mode. It decides how a page renders and no code or safety policy.
@@ -185,6 +183,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
185
183
  working directory, which the desktop file pane cannot open. It decides
186
184
  where a sent file sits and no code or safety policy.
187
185
 
186
+ The question brief gate denies a question call when the chat text before
187
+ it in the same turn is too long to read at a glance. It decides the shape
188
+ of a brief and no code or safety policy.
189
+
188
190
  The eval write gate denies a write to an eval file until the session
189
191
  invokes ``/claude-api build-eval``. It holds eval writes until a skill
190
192
  loads, and it judges no code or safety content.
@@ -193,11 +195,6 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
193
195
  on an ask and made no task list call. It decides when a turn may end and
194
196
  no code or safety policy.
195
197
 
196
- The owned pull request Stop gate holds the end of a turn while a pull
197
- request the session opened on an owned repository is still open and the
198
- closing reply names no ``Blocked:`` line for it. It decides when a turn may
199
- end and no code or safety policy.
200
-
201
198
  The resolve reply gate denies a review thread resolve until a reply on the
202
199
  thread has posted. It decides the order of two review calls and no code or
203
200
  safety policy.
@@ -211,6 +208,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
211
208
  or more away, so the wake lands inside the prompt cache. It decides when a
212
209
  session wakes and no code or safety policy.
213
210
 
211
+ The task subject length gate denies a task list item whose name is over 80
212
+ characters. It decides the shape of a task subject and no code or safety
213
+ policy.
214
+
214
215
  Args:
215
216
  registered_string: One command, path, script, or entrypoint string.
216
217
  """
@@ -14,6 +14,15 @@ APPROVED_TEST_PATHS_BY_PRODUCTION_PATH: dict[
14
14
  ),
15
15
  }
16
16
  ),
17
+ PurePosixPath(
18
+ ".claude/hillclimb/subagent-effort-routing/routing_eval_support/config/constants.py"
19
+ ): frozenset(
20
+ {
21
+ PurePosixPath(
22
+ ".claude/hillclimb/subagent-effort-routing/test_grading.py"
23
+ ),
24
+ }
25
+ ),
17
26
  PurePosixPath("packages/claude-dev-env/bin/install-constants.mjs"): frozenset(
18
27
  {
19
28
  PurePosixPath("packages/claude-dev-env/bin/install.cursor-rules.test.mjs"),
@@ -71,6 +80,15 @@ APPROVED_TEST_PATHS_BY_PRODUCTION_PATH: dict[
71
80
  ),
72
81
  }
73
82
  ),
83
+ PurePosixPath(
84
+ "packages/claude-dev-env/hooks/hooks_constants/once_per_session_constants.py"
85
+ ): frozenset(
86
+ {
87
+ PurePosixPath(
88
+ "packages/claude-dev-env/hooks/test_once_per_session.py"
89
+ ),
90
+ }
91
+ ),
74
92
  PurePosixPath(
75
93
  "packages/claude-dev-env/hooks/hooks_constants/post_tool_use_dispatcher_constants.py"
76
94
  ): frozenset(
@@ -80,6 +98,15 @@ APPROVED_TEST_PATHS_BY_PRODUCTION_PATH: dict[
80
98
  ),
81
99
  }
82
100
  ),
101
+ PurePosixPath(
102
+ "packages/claude-dev-env/hooks/hooks_constants/subagent_effort_route_constants.py"
103
+ ): frozenset(
104
+ {
105
+ PurePosixPath(
106
+ "packages/claude-dev-env/hooks/routing/test_subagent_effort_route.py"
107
+ ),
108
+ }
109
+ ),
83
110
  PurePosixPath(
84
111
  "packages/claude-dev-env/scripts/automatic_advisory/checkout.py"
85
112
  ): frozenset(
@@ -74,16 +74,16 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
74
74
  "blocking/image_read_size_gate.py",
75
75
  "blocking/artifact_dark_mode_gate.py",
76
76
  "blocking/send_user_file_worktree_root_gate.py",
77
+ "blocking/question_brief_gate.py",
77
78
  "blocking/haiku_spawn_slim_gate.py",
78
79
  "blocking/build_eval_before_eval_write_gate.py",
79
80
  "blocking/final_reply_gate.py",
80
81
  "blocking/open_tasks_stop_gate.py",
81
- "blocking/owned_pr_merge_stop_gate.py",
82
- "blocking/session_title_turn_gate.py",
83
82
  "blocking/resolve_thread_reply_gate.py",
84
83
  "blocking/turn_review_gate.py",
85
84
  "blocking/wakeup_cap_gate.py",
86
85
  "blocking/transcript_root_search_gate.py",
86
+ "blocking/task_subject_length_gate.py",
87
87
  )
88
88
  ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
89
89
  ALL_TEST_FILE_PREFIXES = ("test_",)
@@ -285,13 +285,54 @@ def test_should_read_claude_meters_from_a_fresh_published_reading_without_a_prob
285
285
  assert meters.weekly_resets_at == datetime(2026, 10, 10, 6, tzinfo=timezone.utc)
286
286
 
287
287
 
288
+ def _read_published_account(
289
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, published_at: datetime, now: datetime
290
+ ) -> tuple[object, dict[str, object]]:
291
+ readings_folder = tmp_path / "readings"
292
+ _write_published_reading(readings_folder, "alpha", published_at)
293
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
294
+ monkeypatch.setattr(support, "probe_account_meters", lambda *_: pytest.fail("probe despite a fresh published reading"))
295
+ account = Account(Product.CLAUDE, "one", tmp_path / "alpha")
296
+ adapter = ProductAdapter(lambda: (account,), support.read_claude_meters, "CLAUDE_CONFIG_DIR", ())
297
+ state = support._load_state(support.broker_state_path())
298
+ reading = support.read_accounts(Product.CLAUDE, adapter, all_state=state, now=now)[0]
299
+ return reading, state["meters"][support._state_key(account)]
300
+
301
+
302
+ def test_should_report_a_published_reading_with_its_own_read_time(
303
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
304
+ ) -> None:
305
+ now = datetime.now(timezone.utc).replace(microsecond=0)
306
+ published_at = now - timedelta(minutes=29)
307
+
308
+ reading, saved_entry = _read_published_account(monkeypatch, tmp_path, published_at, now)
309
+
310
+ assert reading.meters.weekly_percent_left == 45.0
311
+ assert reading.measured_at == published_at
312
+ assert saved_entry["measured_at"] == published_at.timestamp()
313
+ assert saved_entry["read_at"] == now.timestamp()
314
+
315
+
316
+ def test_should_not_date_a_published_reading_after_the_read(
317
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
318
+ ) -> None:
319
+ now = datetime.now(timezone.utc).replace(microsecond=0)
320
+
321
+ reading, saved_entry = _read_published_account(monkeypatch, tmp_path, now + timedelta(minutes=2), now)
322
+
323
+ assert reading.meters.weekly_percent_left == 45.0
324
+ assert reading.measured_at == now
325
+ assert saved_entry["measured_at"] == now.timestamp()
326
+
327
+
288
328
  def test_should_use_the_newest_of_two_published_readings_for_one_account(
289
329
  monkeypatch: pytest.MonkeyPatch, tmp_path: Path
290
330
  ) -> None:
291
331
  readings_folder = tmp_path / "readings"
292
332
  _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc) - timedelta(minutes=20))
293
333
  newer = json.loads((readings_folder / "meters-ALPHA.json").read_text(encoding="utf-8"))
294
- newer["read_at"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
334
+ newer_read_at = datetime.now(timezone.utc).replace(microsecond=0)
335
+ newer["read_at"] = newer_read_at.strftime("%Y-%m-%dT%H:%M:%SZ")
295
336
  newer["accounts"][0]["meters"]["weekly_percent_left"] = 12.0
296
337
  (readings_folder / "meters-ZULU.json").write_text(json.dumps(newer), encoding="utf-8")
297
338
  monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
@@ -299,6 +340,7 @@ def test_should_use_the_newest_of_two_published_readings_for_one_account(
299
340
  meters = support.read_published_meters(Account(Product.CLAUDE, "one", tmp_path / "alpha"))
300
341
 
301
342
  assert meters.weekly_percent_left == 12.0
343
+ assert meters.measured_at == newer_read_at
302
344
 
303
345
 
304
346
  def test_should_find_no_published_meters_when_no_readings_folder_is_named(
@@ -121,6 +121,7 @@ def test_should_run_the_worker_at_an_allowed_effort(
121
121
  ("model", "effort", "expected_effort"),
122
122
  [
123
123
  ("opus", "xhigh", "medium"),
124
+ ("opus", "high", "high"),
124
125
  ("sonnet", None, "high"),
125
126
  ("haiku", "max", "max"),
126
127
  ("gpt-5", "xhigh", "xhigh"),
@@ -130,9 +130,9 @@ def test_new_session_title_gate_registration_is_clean(tmp_path: Path) -> None:
130
130
  assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
131
131
 
132
132
 
133
- def test_new_session_title_turn_gate_registration_is_clean(tmp_path: Path) -> None:
133
+ def test_new_task_subject_gate_registration_is_clean(tmp_path: Path) -> None:
134
134
  current_document = _hook_document(
135
- ["hooks/blocking/session_title_turn_gate.py"],
135
+ ["hooks/blocking/task_subject_length_gate.py"],
136
136
  '{"hooks": {}}',
137
137
  )
138
138
  assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
@@ -154,6 +154,14 @@ def test_new_send_user_file_gate_registration_is_clean(tmp_path: Path) -> None:
154
154
  assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
155
155
 
156
156
 
157
+ def test_new_question_brief_gate_registration_is_clean(tmp_path: Path) -> None:
158
+ current_document = _hook_document(
159
+ ["hooks/blocking/question_brief_gate.py"],
160
+ '{"hooks": {}}',
161
+ )
162
+ assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
163
+
164
+
157
165
  def test_new_eval_write_gate_registration_is_clean(tmp_path: Path) -> None:
158
166
  current_document = _hook_document(
159
167
  ["hooks/blocking/build_eval_before_eval_write_gate.py"],
@@ -248,6 +248,30 @@ def test_cursor_verifier_constants_require_the_changed_driver_suite(
248
248
  ) == ()
249
249
 
250
250
 
251
+ def test_constants_behind_a_differently_named_suite_require_that_changed_suite(
252
+ tmp_path: Path,
253
+ ) -> None:
254
+ all_suite_paths_by_constants_path = {
255
+ PurePosixPath(
256
+ ".claude/hillclimb/subagent-effort-routing/routing_eval_support/config/constants.py"
257
+ ): PurePosixPath(".claude/hillclimb/subagent-effort-routing/test_grading.py"),
258
+ PurePosixPath(
259
+ "packages/claude-dev-env/hooks/hooks_constants/once_per_session_constants.py"
260
+ ): PurePosixPath("packages/claude-dev-env/hooks/test_once_per_session.py"),
261
+ PurePosixPath(
262
+ "packages/claude-dev-env/hooks/hooks_constants/subagent_effort_route_constants.py"
263
+ ): PurePosixPath(
264
+ "packages/claude-dev-env/hooks/routing/test_subagent_effort_route.py"
265
+ ),
266
+ }
267
+ for each_constants_path, each_suite_path in all_suite_paths_by_constants_path.items():
268
+ constants_change = _body_change_at(each_constants_path)
269
+ assert _diagnostic_paths(tmp_path, constants_change) == (each_constants_path,)
270
+ assert _diagnostic_paths(
271
+ tmp_path, constants_change, _body_change_at(each_suite_path)
272
+ ) == ()
273
+
274
+
251
275
  def test_pairing_rejects_an_unrelated_module_beside_a_changed_approved_suite(
252
276
  tmp_path: Path,
253
277
  ) -> None: