claude-dev-env 8.116.5 → 8.117.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 (99) hide show
  1. package/bin/ever-registered-hooks.mjs +2 -0
  2. package/bin/install-constants.mjs +3 -1
  3. package/bin/install.cursor-rules.test.mjs +64 -2
  4. package/bin/install.mjs +15 -2
  5. package/bin/install.prune.test.mjs +92 -0
  6. package/bin/install.test.mjs +1 -0
  7. package/docs/model-choice/escalation.md +3 -3
  8. package/docs/model-choice/subagents-and-fan-out.md +2 -2
  9. package/docs/model-choice/which-model.md +1 -1
  10. package/docs/references/working-style.md +1 -0
  11. package/docs/rule-guides/question-presentation.md +6 -0
  12. package/docs/rule-guides/session-title.md +8 -9
  13. package/docs/rule-guides/subagent-model-effort.md +13 -13
  14. package/hooks/advisory/owned_pr_review_loop.py +2 -3
  15. package/hooks/blocking/bash_post_call_dispatcher.py +17 -9
  16. package/hooks/blocking/bash_pre_tool_use_dispatcher.py +12 -8
  17. package/hooks/blocking/final_reply_gate.py +5 -9
  18. package/hooks/blocking/open_tasks_stop_gate.py +9 -20
  19. package/hooks/blocking/open_tasks_transcript.py +8 -3
  20. package/hooks/blocking/pii_prevention_blocker_parts/repository_exemption.py +7 -2
  21. package/hooks/blocking/question_brief_gate.py +382 -0
  22. package/hooks/blocking/step_note_gate.py +5 -2
  23. package/hooks/blocking/task_subject_length_gate.py +111 -0
  24. package/hooks/blocking/test_bash_post_call_dispatcher.py +36 -1
  25. package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py +57 -0
  26. package/hooks/blocking/test_final_reply_gate.py +26 -2
  27. package/hooks/blocking/test_open_tasks_stop_gate.py +21 -11
  28. package/hooks/blocking/test_question_brief_gate.py +916 -0
  29. package/hooks/blocking/test_step_note_gate.py +26 -0
  30. package/hooks/blocking/test_task_subject_length_gate.py +221 -0
  31. package/hooks/blocking/test_turn_review_findings.py +124 -1
  32. package/hooks/blocking/test_turn_review_gate.py +1312 -10
  33. package/hooks/blocking/test_turn_review_snapshot.py +8 -0
  34. package/hooks/blocking/tests/test_repository_exemption.py +11 -0
  35. package/hooks/blocking/turn_review_findings.py +173 -13
  36. package/hooks/blocking/turn_review_gate.py +878 -105
  37. package/hooks/blocking/turn_review_snapshot.py +5 -1
  38. package/hooks/features/bash-dispatchers.md +1 -3
  39. package/hooks/features/conduct-gates.md +19 -9
  40. package/hooks/features/lifecycle-cleanup.md +1 -1
  41. package/hooks/features/spawn-routing.md +1 -1
  42. package/hooks/hooks.json +24 -11
  43. package/hooks/hooks_constants/final_reply_gate_constants.py +0 -3
  44. package/hooks/hooks_constants/hook_time_budget.py +61 -0
  45. package/hooks/hooks_constants/hosted_hook_runner.py +51 -21
  46. package/hooks/hooks_constants/hosted_hook_runner_constants.py +3 -0
  47. package/hooks/hooks_constants/nested_project_hooks_constants.py +8 -0
  48. package/hooks/hooks_constants/once_per_session_constants.py +1 -0
  49. package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +0 -4
  50. package/hooks/hooks_constants/owned_pr_review_loop_constants.py +0 -4
  51. package/hooks/hooks_constants/pre_tool_use_context_runner.py +23 -3
  52. package/hooks/hooks_constants/pre_tool_use_context_runner_constants.py +5 -0
  53. package/hooks/hooks_constants/pre_tool_use_stdin.py +1 -1
  54. package/hooks/hooks_constants/question_brief_gate_constants.py +66 -0
  55. package/hooks/hooks_constants/session_title_constants.py +6 -27
  56. package/hooks/hooks_constants/stop_hook_hold.py +54 -0
  57. package/hooks/hooks_constants/stop_hook_hold_constants.py +9 -0
  58. package/hooks/hooks_constants/subagent_effort_levels.json +6 -0
  59. package/hooks/hooks_constants/subagent_effort_route_constants.py +20 -19
  60. package/hooks/hooks_constants/task_subject_length_gate_constants.py +43 -0
  61. package/hooks/hooks_constants/test_hook_time_budget.py +104 -0
  62. package/hooks/hooks_constants/test_hosted_hook_runner.py +12 -0
  63. package/hooks/hooks_constants/test_pre_tool_use_context_runner.py +16 -0
  64. package/hooks/hooks_constants/test_pre_tool_use_stdin.py +6 -0
  65. package/hooks/hooks_constants/test_stop_hook_hold.py +40 -0
  66. package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py +1 -2
  67. package/hooks/hooks_constants/turn_review_gate_constants.py +246 -12
  68. package/hooks/lifecycle/nested_project_hooks.py +34 -4
  69. package/hooks/lifecycle/test_nested_project_hooks.py +52 -0
  70. package/hooks/once_per_session.py +33 -4
  71. package/hooks/open_task_asks.py +1 -1
  72. package/hooks/owned_pr_session_record.py +1 -76
  73. package/hooks/routing/subagent_effort_route.py +107 -13
  74. package/hooks/routing/subagent_effort_route_hook.py +9 -8
  75. package/hooks/routing/test_subagent_effort_route.py +201 -14
  76. package/hooks/routing/test_subagent_effort_route_hook.py +56 -0
  77. package/hooks/routing/thread_spawn_pace_hook.py +3 -3
  78. package/hooks/session/background_silence_prompt.py +1 -1
  79. package/hooks/session/test_tracking_nudge.py +114 -2
  80. package/hooks/session/tracking_nudge.py +28 -18
  81. package/hooks/session_title_transcript.py +195 -0
  82. package/hooks/test_once_per_session.py +10 -0
  83. package/hooks/test_owned_pr_session_record.py +0 -26
  84. package/hooks/test_session_title_transcript.py +111 -0
  85. package/hooks/validation/post_tool_use_dispatcher.py +38 -21
  86. package/hooks/validation/test_post_tool_use_dispatcher.py +43 -0
  87. package/package.json +1 -1
  88. package/rules/question-presentation.md +4 -4
  89. package/rules/subagent-model-effort.md +1 -1
  90. package/scripts/claude_account_worker.py +4 -3
  91. package/scripts/policy_lint/adapter_configuration.py +12 -11
  92. package/scripts/policy_lint/config/constants.py +2 -2
  93. package/scripts/test_claude_account_worker.py +1 -0
  94. package/scripts/tests/test_adapter_configuration.py +10 -2
  95. package/hooks/blocking/owned_pr_merge_stop_gate.py +0 -185
  96. package/hooks/blocking/session_title_turn_gate.py +0 -417
  97. package/hooks/blocking/test_owned_pr_merge_stop_gate.py +0 -254
  98. package/hooks/blocking/test_session_title_turn_gate.py +0 -396
  99. package/hooks/hooks_constants/owned_pr_merge_stop_gate_constants.py +0 -40
@@ -1,8 +1,11 @@
1
1
  """Give a spawn an effort its Anthropic model family allows.
2
2
 
3
- ::
3
+ The allowed efforts and the default for each family come from the
4
+ hand-edited ``hooks_constants/subagent_effort_levels.json``. With the
5
+ shipped file::
4
6
 
5
- {"model": "opus", "effort": "xhigh"} -> effort "medium"
7
+ {"model": "opus", "effort": "max"} -> effort "medium"
8
+ {"model": "opus", "effort": "high"} -> unchanged
6
9
  {"model": "claude-sonnet-5-5"} -> effort "high"
7
10
  {"model": "fable", "effort": "max"} -> effort "high"
8
11
  {"model": "haiku", "effort": "max"} -> unchanged
@@ -12,24 +15,109 @@
12
15
 
13
16
  from __future__ import annotations
14
17
 
18
+ import json
15
19
  import sys
20
+ from collections.abc import Mapping, Sequence
16
21
  from pathlib import Path
22
+ from typing import NamedTuple
17
23
 
18
24
  hooks_root_directory = str(Path(__file__).resolve().parent.parent)
19
25
  if hooks_root_directory not in sys.path:
20
26
  sys.path.insert(0, hooks_root_directory)
21
27
 
22
28
  from hooks_constants.subagent_effort_route_constants import (
23
- ALL_ALLOWED_EFFORTS_BY_FAMILY,
24
- ALL_ROUTED_EFFORT_BY_FAMILY,
29
+ ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY,
30
+ ALL_KNOWN_EFFORT_NAMES,
31
+ ALLOWED_EFFORTS_KEY,
32
+ DEFAULT_EFFORT_KEY,
25
33
  EFFORT_INPUT_KEY,
34
+ EFFORT_LEVELS_FALLBACK_DIAGNOSTIC,
35
+ EFFORT_LEVELS_PATH,
26
36
  FORK_SUBAGENT_TYPE,
27
37
  MODEL_INPUT_KEY,
28
38
  SUBAGENT_TYPE_INPUT_KEY,
29
39
  )
30
40
 
31
41
 
32
- def model_family(model: object) -> str | None:
42
+ class FamilyEfforts(NamedTuple):
43
+ """The efforts one model family may run at, and the one it gets otherwise."""
44
+
45
+ allowed: tuple[str, ...]
46
+ default: str
47
+
48
+
49
+ class EffortLevelsInvalid(ValueError):
50
+ """Raised when an effort levels table does not hold the expected shape."""
51
+
52
+
53
+ def _family_efforts(family: object, family_fields: object) -> FamilyEfforts:
54
+ if not isinstance(family, str) or not family or not isinstance(family_fields, Mapping):
55
+ raise EffortLevelsInvalid(f"entry {family!r} is not a family name with an object")
56
+ all_allowed = family_fields.get(ALLOWED_EFFORTS_KEY)
57
+ default_effort = family_fields.get(DEFAULT_EFFORT_KEY)
58
+ if (
59
+ not isinstance(all_allowed, Sequence)
60
+ or isinstance(all_allowed, str)
61
+ or not all_allowed
62
+ or not all(isinstance(each_effort, str) for each_effort in all_allowed)
63
+ ):
64
+ raise EffortLevelsInvalid(f"{family} {ALLOWED_EFFORTS_KEY} is not a list of effort names")
65
+ for each_effort in all_allowed:
66
+ if each_effort not in ALL_KNOWN_EFFORT_NAMES:
67
+ raise EffortLevelsInvalid(f"{family} {ALLOWED_EFFORTS_KEY} holds unknown effort {each_effort!r}")
68
+ if default_effort not in all_allowed:
69
+ raise EffortLevelsInvalid(f"{family} {DEFAULT_EFFORT_KEY} is not in its {ALLOWED_EFFORTS_KEY} list")
70
+ return FamilyEfforts(tuple(all_allowed), str(default_effort))
71
+
72
+
73
+ def parsed_effort_levels(levels_table: object) -> dict[str, FamilyEfforts]:
74
+ """Return the effort levels a table holds, keyed by lowercase family.
75
+
76
+ ::
77
+
78
+ {"opus": {"allowed": ["medium", "high"], "default": "medium"}}
79
+ -> {"opus": FamilyEfforts(("medium", "high"), "medium")}
80
+
81
+ Args:
82
+ levels_table: The parsed effort levels file, or the built-in table.
83
+
84
+ Raises:
85
+ EffortLevelsInvalid: The table is not an object, leaves out a built-in
86
+ family, or holds a family whose allowed list is empty, names an
87
+ effort outside ``ALL_KNOWN_EFFORT_NAMES``, or leaves out its default.
88
+ """
89
+ if not isinstance(levels_table, Mapping) or not levels_table:
90
+ raise EffortLevelsInvalid("the file is not an object with at least one family")
91
+ all_efforts_by_family = {
92
+ str(each_family).lower(): _family_efforts(each_family, each_fields)
93
+ for each_family, each_fields in levels_table.items()
94
+ }
95
+ for each_built_in_family in ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY:
96
+ if each_built_in_family not in all_efforts_by_family:
97
+ raise EffortLevelsInvalid(f"family {each_built_in_family} is missing")
98
+ return all_efforts_by_family
99
+
100
+
101
+ def load_effort_levels(levels_path: Path = EFFORT_LEVELS_PATH) -> dict[str, FamilyEfforts]:
102
+ """Read the effort levels file, or fall back to the built-in levels.
103
+
104
+ A missing, unreadable, or invalid file, a path that is not a regular
105
+ file, or a file nested too deep to parse writes one diagnostic line naming the file and the fault to stderr and
106
+ returns the built-in levels.
107
+
108
+ Args:
109
+ levels_path: The effort levels JSON file, the shipped one by default.
110
+ """
111
+ try:
112
+ if not levels_path.is_file():
113
+ raise EffortLevelsInvalid("the path is not a regular file")
114
+ return parsed_effort_levels(json.loads(levels_path.read_text(encoding="utf-8")))
115
+ except (OSError, ValueError, RecursionError) as load_error:
116
+ sys.stderr.write(EFFORT_LEVELS_FALLBACK_DIAGNOSTIC.format(path=levels_path, problem=load_error))
117
+ return parsed_effort_levels(ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY)
118
+
119
+
120
+ def model_family(model: object, all_efforts_by_family: Mapping[str, FamilyEfforts]) -> str | None:
33
121
  """Return the Anthropic family a model name or alias belongs to.
34
122
 
35
123
  ::
@@ -39,35 +127,38 @@ def model_family(model: object) -> str | None:
39
127
 
40
128
  Args:
41
129
  model: A model alias or full model id, or anything else.
130
+ all_efforts_by_family: The effort levels by family.
42
131
  """
43
132
  if not isinstance(model, str):
44
133
  return None
45
134
  lowered_model = model.lower()
46
- for each_family in ALL_ALLOWED_EFFORTS_BY_FAMILY:
135
+ for each_family in all_efforts_by_family:
47
136
  if each_family in lowered_model:
48
137
  return each_family
49
138
  return None
50
139
 
51
140
 
52
- def routed_effort(family: str, effort: object) -> str:
141
+ def routed_effort(family: str, effort: object, all_efforts_by_family: Mapping[str, FamilyEfforts]) -> str:
53
142
  """Return the effort a spawn of this family runs at.
54
143
 
55
144
  ::
56
145
 
57
- ("opus", "xhigh") -> "medium" ("fable", "low") -> "low"
146
+ ("opus", "max") -> "medium" ("fable", "low") -> "low"
58
147
  ("sonnet", None) -> "high"
59
148
 
60
149
  Args:
61
150
  family: An Anthropic model family.
62
151
  effort: The effort the spawn named, or None.
152
+ all_efforts_by_family: The effort levels by family.
63
153
  """
64
- if effort in ALL_ALLOWED_EFFORTS_BY_FAMILY[family]:
154
+ family_efforts = all_efforts_by_family[family]
155
+ if effort in family_efforts.allowed:
65
156
  return str(effort)
66
- return ALL_ROUTED_EFFORT_BY_FAMILY[family]
157
+ return family_efforts.default
67
158
 
68
159
 
69
160
  def route_spawn_input(
70
- tool_input: object, parent_model: str | None
161
+ tool_input: object, parent_model: str | None, all_efforts_by_family: Mapping[str, FamilyEfforts]
71
162
  ) -> tuple[dict[str, object], str, str] | None:
72
163
  """Return the spawn input with an allowed effort, or None to leave it.
73
164
 
@@ -78,6 +169,7 @@ def route_spawn_input(
78
169
  Args:
79
170
  tool_input: The spawn tool's input.
80
171
  parent_model: The model of the session that spawns, when known.
172
+ all_efforts_by_family: The effort levels by family, from ``load_effort_levels``.
81
173
 
82
174
  Returns:
83
175
  The updated input, the family, and the effort, or None when the
@@ -87,11 +179,13 @@ def route_spawn_input(
87
179
  return None
88
180
  if tool_input.get(SUBAGENT_TYPE_INPUT_KEY) == FORK_SUBAGENT_TYPE:
89
181
  return None
90
- family = model_family(tool_input.get(MODEL_INPUT_KEY)) or model_family(parent_model)
182
+ family = model_family(tool_input.get(MODEL_INPUT_KEY), all_efforts_by_family) or model_family(
183
+ parent_model, all_efforts_by_family
184
+ )
91
185
  if family is None:
92
186
  return None
93
187
  current_effort = tool_input.get(EFFORT_INPUT_KEY)
94
- allowed_effort = routed_effort(family, current_effort)
188
+ allowed_effort = routed_effort(family, current_effort, all_efforts_by_family)
95
189
  if allowed_effort == current_effort:
96
190
  return None
97
191
  return {**tool_input, EFFORT_INPUT_KEY: allowed_effort}, family, allowed_effort
@@ -1,14 +1,13 @@
1
1
  #!/usr/bin/env python3
2
2
  """PreToolUse hook: give an Agent or Task spawn an allowed effort.
3
3
 
4
- Registered on ``Agent|Task``. It applies the Subagent model and effort rule:
5
- Opus runs at medium, Sonnet at high, Fable at low to high, and Haiku at any
6
- effort. A spawn that names no model takes the family of the session's last
7
- assistant model from the transcript.
4
+ Registered on ``Agent|Task``. It applies the Subagent model and effort rule
5
+ with the effort levels in ``hooks_constants/subagent_effort_levels.json``,
6
+ read on every run. A spawn that names no model takes the family of the
7
+ session's last assistant model from the transcript. With the shipped file::
8
8
 
9
- ::
10
-
11
- model "opus", effort "xhigh" -> updatedInput with effort "medium"
9
+ model "opus", effort "max" -> updatedInput with effort "medium"
10
+ model "opus", effort "high" -> no output
12
11
  model "sonnet", no effort -> updatedInput with effort "high"
13
12
  model "haiku", effort "max" -> no output
14
13
  subagent_type "fork" -> no output
@@ -37,6 +36,7 @@ from hooks_constants.hook_specific_output_keys import (
37
36
  from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
38
37
  from hooks_constants.subagent_effort_route_constants import (
39
38
  ADDITIONAL_CONTEXT_KEY,
39
+ EFFORT_LEVELS_PATH,
40
40
  MODEL_INPUT_KEY,
41
41
  ROUTED_CONTEXT_TEMPLATE,
42
42
  TOOL_INPUT_KEY,
@@ -47,7 +47,7 @@ from hooks_constants.subagent_effort_route_constants import (
47
47
  SEEK_FROM_FILE_END,
48
48
  TRANSCRIPT_TAIL_BYTES,
49
49
  )
50
- from subagent_effort_route import route_spawn_input
50
+ from subagent_effort_route import load_effort_levels, route_spawn_input
51
51
 
52
52
 
53
53
  def last_assistant_model(transcript_path: object) -> str | None:
@@ -109,6 +109,7 @@ def decide_hook_output(all_hook_payload: dict[str, object] | None) -> dict[str,
109
109
  routed = route_spawn_input(
110
110
  all_hook_payload.get(TOOL_INPUT_KEY),
111
111
  last_assistant_model(all_hook_payload.get(TRANSCRIPT_PATH_KEY)),
112
+ load_effort_levels(EFFORT_LEVELS_PATH),
112
113
  )
113
114
  if routed is None:
114
115
  return None
@@ -1,6 +1,47 @@
1
+ import json
2
+ import os
3
+ import subprocess
4
+ import sys
5
+ from pathlib import Path
6
+
1
7
  import pytest
2
8
 
3
- from subagent_effort_route import model_family, route_spawn_input, routed_effort
9
+ from hooks_constants.subagent_effort_route_constants import ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY
10
+ from subagent_effort_route import (
11
+ FamilyEfforts,
12
+ load_effort_levels,
13
+ model_family,
14
+ parsed_effort_levels,
15
+ route_spawn_input,
16
+ routed_effort,
17
+ )
18
+
19
+ EFFORT_LEVELS_TABLE = {
20
+ "opus": {"allowed": ["medium", "high"], "default": "medium"},
21
+ "sonnet": {"allowed": ["high"], "default": "high"},
22
+ "fable": {"allowed": ["low", "medium", "high"], "default": "high"},
23
+ "haiku": {"allowed": ["low", "medium", "high", "xhigh", "max"], "default": "medium"},
24
+ }
25
+ SHIPPED_EFFORT_LEVELS_PATH = (
26
+ Path(__file__).resolve().parent.parent / "hooks_constants" / "subagent_effort_levels.json"
27
+ )
28
+ ROUTING_DIRECTORY = Path(__file__).resolve().parent
29
+ FIFO_RUN_TIMEOUT_SECONDS = 5
30
+ LOAD_LEVELS_SCRIPT = (
31
+ "import sys; from pathlib import Path; from subagent_effort_route import load_effort_levels; "
32
+ "print(sorted(load_effort_levels(Path(sys.argv[1]))))"
33
+ )
34
+
35
+
36
+ def _write_levels(tmp_path: Path, levels_text: str) -> Path:
37
+ levels_path = tmp_path / "subagent_effort_levels.json"
38
+ levels_path.write_text(levels_text, encoding="utf-8")
39
+ return levels_path
40
+
41
+
42
+ @pytest.fixture
43
+ def effort_levels(tmp_path: Path) -> dict[str, FamilyEfforts]:
44
+ return load_effort_levels(_write_levels(tmp_path, json.dumps(EFFORT_LEVELS_TABLE)))
4
45
 
5
46
 
6
47
  @pytest.mark.parametrize(
@@ -17,13 +58,18 @@ from subagent_effort_route import model_family, route_spawn_input, routed_effort
17
58
  (7, None),
18
59
  ],
19
60
  )
20
- def test_should_name_the_family_of_a_model(model: object, family: str | None) -> None:
21
- assert model_family(model) == family
61
+ def test_should_name_the_family_of_a_model(
62
+ effort_levels: dict[str, FamilyEfforts], model: object, family: str | None
63
+ ) -> None:
64
+ assert model_family(model, effort_levels) == family
22
65
 
23
66
 
24
67
  @pytest.mark.parametrize(
25
68
  ("family", "effort", "expected"),
26
69
  [
70
+ ("opus", "high", "high"),
71
+ ("opus", "medium", "medium"),
72
+ ("opus", "max", "medium"),
27
73
  ("opus", "xhigh", "medium"),
28
74
  ("opus", "low", "medium"),
29
75
  ("opus", None, "medium"),
@@ -36,26 +82,34 @@ def test_should_name_the_family_of_a_model(model: object, family: str | None) ->
36
82
  ("haiku", None, "medium"),
37
83
  ],
38
84
  )
39
- def test_should_pick_an_allowed_effort(family: str, effort: object, expected: str) -> None:
40
- assert routed_effort(family, effort) == expected
85
+ def test_should_pick_an_allowed_effort(
86
+ effort_levels: dict[str, FamilyEfforts], family: str, effort: object, expected: str
87
+ ) -> None:
88
+ assert routed_effort(family, effort, effort_levels) == expected
41
89
 
42
90
 
43
- def test_should_set_the_allowed_effort_and_keep_every_other_key() -> None:
44
- spawn_input = {"model": "opus", "effort": "high", "prompt": "Do X."}
45
- assert route_spawn_input(spawn_input, None) == (
91
+ def test_should_set_the_allowed_effort_and_keep_every_other_key(
92
+ effort_levels: dict[str, FamilyEfforts],
93
+ ) -> None:
94
+ spawn_input = {"model": "opus", "effort": "max", "prompt": "Do X."}
95
+ assert route_spawn_input(spawn_input, None, effort_levels) == (
46
96
  {"model": "opus", "effort": "medium", "prompt": "Do X."},
47
97
  "opus",
48
98
  "medium",
49
99
  )
50
100
 
51
101
 
52
- def test_should_use_the_parent_family_when_the_spawn_names_no_model() -> None:
53
- routed = route_spawn_input({"prompt": "Do X."}, "claude-sonnet-5-5")
102
+ def test_should_use_the_parent_family_when_the_spawn_names_no_model(
103
+ effort_levels: dict[str, FamilyEfforts],
104
+ ) -> None:
105
+ routed = route_spawn_input({"prompt": "Do X."}, "claude-sonnet-5-5", effort_levels)
54
106
  assert routed == ({"prompt": "Do X.", "effort": "high"}, "sonnet", "high")
55
107
 
56
108
 
57
- def test_should_prefer_the_spawn_model_over_the_parent_model() -> None:
58
- routed = route_spawn_input({"model": "haiku"}, "claude-opus-5-5")
109
+ def test_should_prefer_the_spawn_model_over_the_parent_model(
110
+ effort_levels: dict[str, FamilyEfforts],
111
+ ) -> None:
112
+ routed = route_spawn_input({"model": "haiku"}, "claude-opus-5-5", effort_levels)
59
113
  assert routed == ({"model": "haiku", "effort": "medium"}, "haiku", "medium")
60
114
 
61
115
 
@@ -63,6 +117,9 @@ def test_should_prefer_the_spawn_model_over_the_parent_model() -> None:
63
117
  ("tool_input", "parent_model"),
64
118
  [
65
119
  ({"model": "opus", "effort": "medium"}, None),
120
+ ({"model": "opus", "effort": "high"}, None),
121
+ ({"model": "claude-opus-5-5", "effort": "high"}, None),
122
+ ({"effort": "high"}, "claude-opus-5-5"),
66
123
  ({"model": "haiku", "effort": "xhigh"}, None),
67
124
  ({"subagent_type": "fork", "effort": "max"}, "claude-opus-5-5"),
68
125
  ({"prompt": "Do X."}, None),
@@ -70,5 +127,135 @@ def test_should_prefer_the_spawn_model_over_the_parent_model() -> None:
70
127
  (["not", "an", "object"], "claude-opus-5-5"),
71
128
  ],
72
129
  )
73
- def test_should_leave_the_spawn_as_it_is(tool_input: object, parent_model: str | None) -> None:
74
- assert route_spawn_input(tool_input, parent_model) is None
130
+ def test_should_leave_the_spawn_as_it_is(
131
+ effort_levels: dict[str, FamilyEfforts], tool_input: object, parent_model: str | None
132
+ ) -> None:
133
+ assert route_spawn_input(tool_input, parent_model, effort_levels) is None
134
+
135
+
136
+ def test_should_follow_an_edited_file_with_no_code_change(tmp_path: Path) -> None:
137
+ edited_table = {
138
+ **EFFORT_LEVELS_TABLE,
139
+ "opus": {"allowed": ["xhigh"], "default": "xhigh"},
140
+ "mythos": {"allowed": ["low"], "default": "low"},
141
+ }
142
+ edited_levels = load_effort_levels(_write_levels(tmp_path, json.dumps(edited_table)))
143
+ assert route_spawn_input({"model": "opus", "effort": "high"}, None, edited_levels) == (
144
+ {"model": "opus", "effort": "xhigh"},
145
+ "opus",
146
+ "xhigh",
147
+ )
148
+ assert route_spawn_input({"model": "claude-mythos-1"}, None, edited_levels) == (
149
+ {"model": "claude-mythos-1", "effort": "low"},
150
+ "mythos",
151
+ "low",
152
+ )
153
+
154
+
155
+ def test_should_load_the_shipped_file_with_no_diagnostic(capsys: pytest.CaptureFixture[str]) -> None:
156
+ shipped_levels = load_effort_levels(SHIPPED_EFFORT_LEVELS_PATH)
157
+ assert set(shipped_levels) >= {"opus", "sonnet", "fable", "haiku"}
158
+ assert capsys.readouterr().err == ""
159
+
160
+
161
+ def _table_with(family: str, family_fields: object) -> str:
162
+ return json.dumps({**EFFORT_LEVELS_TABLE, family: family_fields})
163
+
164
+
165
+ def _table_without(family: str) -> str:
166
+ return json.dumps({each_family: each_fields for each_family, each_fields in EFFORT_LEVELS_TABLE.items() if each_family != family})
167
+
168
+
169
+ @pytest.mark.parametrize(
170
+ ("levels_text", "fault_fragment"),
171
+ [
172
+ ("{not json", "Expecting"),
173
+ ("[]", "not an object"),
174
+ ("{}", "not an object"),
175
+ ("[" * 100_000, "recursion"),
176
+ (_table_with("opus", {"allowed": ["turbo"], "default": "turbo"}), "unknown effort 'turbo'"),
177
+ (_table_with("opus", {"allowed": ["medium", "hihg"], "default": "medium"}), "unknown effort 'hihg'"),
178
+ (_table_with("opus", {"allowed": [], "default": "medium"}), "opus allowed"),
179
+ (_table_with("opus", {"allowed": "medium", "default": "medium"}), "opus allowed"),
180
+ (_table_with("opus", {"allowed": ["medium", 5], "default": "medium"}), "opus allowed"),
181
+ (_table_with("opus", {"allowed": ["medium"], "default": 5}), "opus default"),
182
+ (_table_with("opus", {"allowed": ["medium"], "default": "high"}), "opus default"),
183
+ (_table_with("opus", ["medium"]), "'opus'"),
184
+ (_table_with("opus", None), "'opus'"),
185
+ (_table_without("sonnet"), "sonnet"),
186
+ ],
187
+ )
188
+ def test_should_fall_back_to_the_built_in_levels_with_one_line_naming_the_fault(
189
+ tmp_path: Path, capsys: pytest.CaptureFixture[str], levels_text: str, fault_fragment: str
190
+ ) -> None:
191
+ levels_path = _write_levels(tmp_path, levels_text)
192
+ fallback_levels = load_effort_levels(levels_path)
193
+ assert fallback_levels == load_effort_levels(SHIPPED_EFFORT_LEVELS_PATH)
194
+ assert route_spawn_input({"model": "opus", "effort": "high"}, None, fallback_levels) is None
195
+ assert route_spawn_input({"model": "opus", "effort": "max"}, None, fallback_levels) == (
196
+ {"model": "opus", "effort": "medium"},
197
+ "opus",
198
+ "medium",
199
+ )
200
+ diagnostic_lines = capsys.readouterr().err.splitlines()
201
+ assert len(diagnostic_lines) == 1
202
+ assert str(levels_path) in diagnostic_lines[0]
203
+ assert fault_fragment in diagnostic_lines[0]
204
+
205
+
206
+ def test_should_keep_the_built_in_levels_equal_to_the_shipped_file() -> None:
207
+ shipped_table = json.loads(SHIPPED_EFFORT_LEVELS_PATH.read_text(encoding="utf-8"))
208
+ assert parsed_effort_levels(shipped_table) == parsed_effort_levels(ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY)
209
+
210
+
211
+ def test_should_load_the_shipped_file_with_the_default_path(capsys: pytest.CaptureFixture[str]) -> None:
212
+ assert load_effort_levels() == load_effort_levels(SHIPPED_EFFORT_LEVELS_PATH)
213
+ assert capsys.readouterr().err == ""
214
+
215
+
216
+ def test_should_fall_back_when_the_file_is_missing(
217
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
218
+ ) -> None:
219
+ missing_path = tmp_path / "absent.json"
220
+ fallback_levels = load_effort_levels(missing_path)
221
+ assert route_spawn_input({"model": "sonnet"}, None, fallback_levels) == (
222
+ {"model": "sonnet", "effort": "high"},
223
+ "sonnet",
224
+ "high",
225
+ )
226
+ diagnostic_lines = capsys.readouterr().err.splitlines()
227
+ assert len(diagnostic_lines) == 1
228
+ assert str(missing_path) in diagnostic_lines[0]
229
+
230
+
231
+ def test_should_fall_back_when_the_file_cannot_be_read(
232
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
233
+ ) -> None:
234
+ levels_path = _write_levels(tmp_path, json.dumps(EFFORT_LEVELS_TABLE))
235
+
236
+ def refuse_to_read(*_arguments: object, **_keywords: object) -> str:
237
+ raise PermissionError("permission denied")
238
+
239
+ monkeypatch.setattr(Path, "read_text", refuse_to_read)
240
+ assert load_effort_levels(levels_path) == parsed_effort_levels(ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY)
241
+ diagnostic_lines = capsys.readouterr().err.splitlines()
242
+ assert len(diagnostic_lines) == 1
243
+ assert "permission denied" in diagnostic_lines[0]
244
+
245
+
246
+ def test_should_fall_back_at_once_when_the_file_is_a_named_pipe(tmp_path: Path) -> None:
247
+ pipe_path = tmp_path / "subagent_effort_levels.json"
248
+ os.mkfifo(pipe_path)
249
+ completed = subprocess.run(
250
+ [sys.executable, "-c", LOAD_LEVELS_SCRIPT, str(pipe_path)],
251
+ cwd=ROUTING_DIRECTORY,
252
+ capture_output=True,
253
+ text=True,
254
+ check=False,
255
+ timeout=FIFO_RUN_TIMEOUT_SECONDS,
256
+ )
257
+ assert completed.returncode == 0
258
+ assert completed.stdout.strip() == str(sorted(ALL_BUILT_IN_EFFORT_LEVELS_BY_FAMILY))
259
+ diagnostic_lines = completed.stderr.splitlines()
260
+ assert len(diagnostic_lines) == 1
261
+ assert str(pipe_path) in diagnostic_lines[0]
@@ -3,6 +3,10 @@ import subprocess
3
3
  import sys
4
4
  from pathlib import Path
5
5
 
6
+ import pytest
7
+
8
+ import subagent_effort_route_hook
9
+
6
10
  HOOK_SCRIPT = Path(__file__).resolve().parent / "subagent_effort_route_hook.py"
7
11
 
8
12
 
@@ -70,6 +74,58 @@ def test_should_print_nothing_for_an_allowed_pair() -> None:
70
74
  assert _run_hook({"model": "haiku", "effort": "max", "prompt": "Do X."}) == ""
71
75
 
72
76
 
77
+ def test_should_print_nothing_for_an_opus_spawn_at_high() -> None:
78
+ assert _run_hook({"model": "opus", "effort": "high", "prompt": "Do X."}) == ""
79
+
80
+
81
+ def test_should_move_an_opus_spawn_at_max_to_medium() -> None:
82
+ spawn_input = {"model": "claude-opus-5-5", "effort": "max", "prompt": "Do X."}
83
+ decision = _hook_specific_output(_run_hook(spawn_input))
84
+ assert decision["updatedInput"] == {**spawn_input, "effort": "medium"}
85
+
86
+
87
+ def _levels_text(opus_fields: dict[str, object]) -> str:
88
+ return json.dumps(
89
+ {
90
+ "opus": opus_fields,
91
+ "sonnet": {"allowed": ["high"], "default": "high"},
92
+ "fable": {"allowed": ["low", "medium", "high"], "default": "high"},
93
+ "haiku": {"allowed": ["low", "medium", "high", "xhigh", "max"], "default": "medium"},
94
+ }
95
+ )
96
+
97
+
98
+ def _payload(tool_input: dict[str, object]) -> dict[str, object]:
99
+ return {"hook_event_name": "PreToolUse", "tool_name": "Agent", "tool_input": tool_input}
100
+
101
+
102
+ def test_should_read_the_effort_file_each_time_it_runs(
103
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
104
+ ) -> None:
105
+ levels_path = tmp_path / "subagent_effort_levels.json"
106
+ monkeypatch.setattr(subagent_effort_route_hook, "EFFORT_LEVELS_PATH", levels_path)
107
+ spawn_input = {"model": "opus", "effort": "high"}
108
+ levels_path.write_text(_levels_text({"allowed": ["high"], "default": "high"}), encoding="utf-8")
109
+ assert subagent_effort_route_hook.decide_hook_output(_payload(spawn_input)) is None
110
+ levels_path.write_text(_levels_text({"allowed": ["low"], "default": "low"}), encoding="utf-8")
111
+ decision = subagent_effort_route_hook.decide_hook_output(_payload(spawn_input))
112
+ assert decision is not None
113
+ assert decision["hookSpecificOutput"]["updatedInput"] == {"model": "opus", "effort": "low"}
114
+
115
+
116
+ def test_should_route_with_the_built_in_levels_when_the_file_is_broken(
117
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
118
+ ) -> None:
119
+ levels_path = tmp_path / "subagent_effort_levels.json"
120
+ levels_path.write_text("{broken", encoding="utf-8")
121
+ monkeypatch.setattr(subagent_effort_route_hook, "EFFORT_LEVELS_PATH", levels_path)
122
+ decision = subagent_effort_route_hook.decide_hook_output(_payload({"model": "opus", "effort": "max"}))
123
+ assert decision is not None
124
+ assert json.loads(json.dumps(decision))["hookSpecificOutput"]["updatedInput"]["effort"] == "medium"
125
+ assert subagent_effort_route_hook.decide_hook_output(_payload({"model": "opus", "effort": "high"})) is None
126
+ assert capsys.readouterr().err.count(str(levels_path)) == 2
127
+
128
+
73
129
  def test_should_print_nothing_for_a_fork(tmp_path: Path) -> None:
74
130
  assert _run_hook({"subagent_type": "fork", "prompt": "Do X."}, _write_transcript(tmp_path, "claude-opus-5-5")) == ""
75
131
 
@@ -56,14 +56,14 @@ from hooks_constants.thread_spawn_pace_hook_constants import (
56
56
  USAGE_PACE_SCRIPT_FILE_NAME,
57
57
  USAGE_PACE_TIMEOUT_SECONDS,
58
58
  )
59
- from hooks_constants.subagent_effort_route_constants import ROUTED_CONTEXT_TEMPLATE
59
+ from hooks_constants.subagent_effort_route_constants import EFFORT_LEVELS_PATH, ROUTED_CONTEXT_TEMPLATE
60
60
  from hooks_constants.usage_pace_constants import (
61
61
  EXIT_CODE_UNDER_PACE,
62
62
  EXIT_CODE_UNREADABLE,
63
63
  RESULT_KEY_ERROR,
64
64
  RESULT_KEY_OVER_PACE,
65
65
  )
66
- from subagent_effort_route import route_spawn_input
66
+ from subagent_effort_route import load_effort_levels, route_spawn_input
67
67
 
68
68
 
69
69
  class SpawnNotReshapable(Exception):
@@ -126,7 +126,7 @@ def decide_hook_output(
126
126
  None to pass the call through unchanged, else the hook JSON output.
127
127
  """
128
128
  if pace_exit_code == EXIT_CODE_UNDER_PACE:
129
- routed = route_spawn_input(tool_input, None)
129
+ routed = route_spawn_input(tool_input, None, load_effort_levels(EFFORT_LEVELS_PATH))
130
130
  if routed is None:
131
131
  return None
132
132
  routed_input, family, effort = routed
@@ -70,7 +70,7 @@ from hooks_constants.spawn_readiness_hook_constants import (
70
70
  )
71
71
  from open_task_asks import prompt_without_reminders
72
72
  from open_tasks_transcript import claude_prompt_text
73
- from session_title_turn_gate import read_transcript_entries
73
+ from session_title_transcript import read_transcript_entries
74
74
 
75
75
 
76
76
  def _is_user_typed_text(prompt_text: str) -> bool: