claude-dev-env 8.113.1 → 8.114.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 (29) hide show
  1. package/.agents/skills/team-advisor/SKILL.md +1 -1
  2. package/_shared/advisor/advisor-protocol.md +2 -2
  3. package/_shared/advisor/reference/advisor-block.md +1 -1
  4. package/_shared/advisor/reference/third-party-bind.md +1 -1
  5. package/_shared/advisor/reference/warm-up.md +1 -0
  6. package/docs/agent-spawn-protocol.md +1 -1
  7. package/docs/rule-guides/proof-before-pull-request.md +2 -2
  8. package/docs/rule-guides/subagent-model-effort.md +46 -0
  9. package/docs/subagent-model-routing.md +3 -0
  10. package/hooks/blocking/test_verify_before_acting.py +52 -2
  11. package/hooks/blocking/verify_before_acting.py +20 -2
  12. package/hooks/features/conduct-gates.md +3 -3
  13. package/hooks/features/spawn-routing.md +8 -3
  14. package/hooks/hooks.json +5 -0
  15. package/hooks/hooks_constants/subagent_effort_route_constants.py +45 -0
  16. package/hooks/hooks_constants/test_verify_before_acting_constants.py +5 -0
  17. package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py +4 -3
  18. package/hooks/hooks_constants/verify_before_acting_constants.py +7 -0
  19. package/hooks/routing/subagent_effort_route.py +97 -0
  20. package/hooks/routing/subagent_effort_route_hook.py +139 -0
  21. package/hooks/routing/test_subagent_effort_route.py +74 -0
  22. package/hooks/routing/test_subagent_effort_route_hook.py +85 -0
  23. package/hooks/routing/test_thread_spawn_pace_hook.py +39 -2
  24. package/hooks/routing/thread_spawn_pace_hook.py +26 -8
  25. package/package.json +1 -1
  26. package/rules/subagent-model-effort.md +18 -0
  27. package/scripts/account_broker_support.py +64 -1
  28. package/scripts/dev_env_scripts_constants/account_broker_constants.py +4 -0
  29. package/scripts/test_account_broker_support.py +84 -0
@@ -22,7 +22,7 @@ One warm advisor at the strongest tier this session can reach. This session is t
22
22
  ## Bind
23
23
 
24
24
  1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
25
- 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default xhigh) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
25
+ 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at Opus high with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
26
26
  3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path and the spawn tool has a `flags` field, pass `flags: ["--advisor"]` with Astra and record `advisor_flag: passed`. A spawn that skips an offered flag is a failed bind. When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `advisor_flag: unavailable`, and treat it as bound.
27
27
  4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
28
28
  5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
@@ -47,9 +47,9 @@ Mechanical override for scripts:
47
47
 
48
48
  ### Shared effort, any host
49
49
 
50
- Opus and Astra both read `ADVISOR_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`). Opus keeps its xhigh default. Astra uses the policy default, Medium.
50
+ Astra reads `ADVISOR_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`) and uses the policy default, Medium. Opus always runs at high, the advisor exception in [Subagent model and effort](../../docs/rule-guides/subagent-model-effort.md).
51
51
  Pass `--effort <level>` on the Astra helper to set effort for that Astra run.
52
- Pass `--effort <level>` on the Claude CLI bind for Opus. An unset or unrecognized Opus value uses `xhigh`.
52
+ Pass `--effort high` on the Claude CLI bind for Opus, whatever `ADVISOR_EFFORT` holds.
53
53
 
54
54
  ### Astra rung
55
55
 
@@ -26,7 +26,7 @@ Subagents inherit the session's advisor tool, so the executor calls it directly.
26
26
  ## Transport preamble for a third-party host
27
27
 
28
28
  > The orchestrating session owns a standing advisor for this run.
29
- > The advisor chain: Claude Opus, then Astra through the Codex CLI when Opus is out of usage and the Astra flag and its preflight open that rung. Opus uses its xhigh default. Astra uses the policy default, Medium. When neither binds, there is no advisor.
29
+ > The advisor chain: Claude Opus, then Astra through the Codex CLI when Opus is out of usage and the Astra flag and its preflight open that rung. Opus runs at high. Astra uses the policy default, Medium. When neither binds, there is no advisor.
30
30
  > The orchestrating session is your one path to it: send each consult as a report to the session that assigned you, and it relays the advisor's reply.
31
31
 
32
32
  ## Shared core for every host
@@ -25,7 +25,7 @@ When the Astra flag is off, follow the Claude-chain steps below.
25
25
  python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude -p --model <alias> --effort <effort> --output-format json
26
26
  ```
27
27
 
28
- Use `--model opus --effort` with the value of `ADVISOR_EFFORT` (default `xhigh`) on Opus.
28
+ Use `--model opus --effort high` on Opus.
29
29
  User-facing wording follows [`docs/rule-guides/asd-ste100-language.md`](../../../docs/rule-guides/asd-ste100-language.md).
30
30
  Account choice, failover, and the `advisor_blocked` status are in [`cli-chain.md`](cli-chain.md).
31
31
  4. Stop at the first successful bind.
@@ -9,6 +9,7 @@ The consuming skill's session tries Opus first. Spawn with:
9
9
 
10
10
  - `subagent_type: pstack:poteto-agent`. The charter below carries the signal contract.
11
11
  - `model`: the short alias via `resolve_cli_model_id("Opus")` (alias table: [`cli-chain.md`](cli-chain.md)): `opus`. When Opus is out of usage and the Astra rung is open, continue with the Codex helper in [`astra-rung.md`](astra-rung.md) as the Astra fallback.
12
+ - `effort`: `high`.
12
13
  - `name`: a name the session and every consumer will use to reach it (e.g. `team-advisor-agent`).
13
14
  - `run_in_background: true`.
14
15
  - `prompt`: the charter below.
@@ -27,7 +27,7 @@ Use the brief as the agent's `prompt` parameter.
27
27
 
28
28
  ## Step 3: Spawn the agent
29
29
 
30
- Pass the structured prompt from Step 2 to the Agent or Task tool.
30
+ Pass the structured prompt from Step 2 to the Agent or Task tool. Set the model and the effort from [Subagent model and effort](rule-guides/subagent-model-effort.md).
31
31
 
32
32
  ## Why
33
33
 
@@ -24,9 +24,9 @@ Unit tests are welcome as extra evidence. The live run is the proof. A test you
24
24
 
25
25
  For a change to Claude Code behavior, such as a hook, skill, rule, setting, prompt or output style:
26
26
  - Spawn every session through the account broker, with the stream saved to a file:
27
- python ~/.claude/scripts/account_broker.py run --product claude --report <broker-report.json> -- claude -p "<request>" --model claude-opus-5-5 --effort <level> --output-format stream-json --verbose > <stream.jsonl>
27
+ python ~/.claude/scripts/account_broker.py run --product claude --report <broker-report.json> -- claude -p "<request>" --model claude-opus-5-5 --effort medium --output-format stream-json --verbose > <stream.jsonl>
28
28
  - Run each later turn the same way with `--resume <session id>`. The broker resumes a session on the account that started it when that account has room.
29
- - Keep `--model` and `--effort` on every call. Without them the headless run uses claude-sonnet-5-5. Confirm the served model in the result's `modelUsage`.
29
+ - Keep `--model` and `--effort` on every call, with a pair from [Subagent model and effort](subagent-model-effort.md). Without them the headless run uses claude-sonnet-5-5. Confirm the served model in the result's `modelUsage`.
30
30
  - Start the broker from your own shell, with your environment as is. The broker reads the account meters with your session's credentials and starts Claude without your session's variables.
31
31
  - Leave out `--bare` and `claude plugin eval`. Both drop the hooks and settings the user runs with.
32
32
  - Read the broker report for the account it chose. Read the stream for the hook events and their output, `permission_denials`, the final result, and the token usage on the result event.
@@ -0,0 +1,46 @@
1
+ Back to the [rules index](../../rules/index.md).
2
+
3
+ # Subagent model and effort
4
+
5
+ ## In brief
6
+
7
+ Every agent you start runs on an Anthropic model at an allowed effort. Opus runs at medium. Sonnet runs at high. Fable runs at low, medium or high. Only Haiku runs at xhigh or max. Name the model and the effort on every spawn.
8
+
9
+ **When this applies:** Every time one agent starts another on a Claude host. That covers the Agent and Task tools, a thread or session spawn, a Workflow agent, an advisor bind, and a headless `claude -p` run.
10
+
11
+ ## Allowed pairs
12
+
13
+ | Model | Effort |
14
+ | --- | --- |
15
+ | Opus | medium |
16
+ | Sonnet | high |
17
+ | Fable | low, medium or high |
18
+ | Haiku | low, medium, high, xhigh or max |
19
+
20
+ - Use Anthropic models only.
21
+ - xhigh and max are for Haiku only.
22
+ - Any pair outside the table is out.
23
+ - One exception: an advisor that is not the built-in advisor tool runs on Opus at high. The built-in advisor follows the `advisorModel` setting.
24
+
25
+ Codex spawns follow their own policy in [Automatic child model choices](../subagent-model-routing.md).
26
+
27
+ ## Rule
28
+
29
+ - Name both the model and the effort. A spawn that leaves either one out takes the parent's, and an Opus parent at high hands the child Opus high.
30
+ - A fork always takes its parent's model and effort. Fork only from a parent whose own pair is in the table.
31
+ - For `claude -p`, pass the pair as flags, such as `--model claude-opus-5-5 --effort medium` or `--model claude-sonnet-5-5 --effort high`.
32
+ - When a brief, skill, hook, setting or default gives a pair outside the table, use the allowed pair for that model and say so in your report.
33
+
34
+ ## Which model gets which work
35
+
36
+ Opus and Sonnet have one effort each here, so pick the model by the work.
37
+
38
+ - Haiku: finding files, reading logs, running tests, summing up, and sorting or pulling data out of many items. A Haiku mistake is cheap to spot.
39
+ - Sonnet: well-scoped work, such as a bug fix or a feature built to a clear spec.
40
+ - Opus: code edits, judgment calls, and decisions that rest on what other subagents report.
41
+ - Fable: the hardest work, such as a large migration, planning a design, leading many subagents, or a long run with no one watching.
42
+ - Keep the costly model's context lean. Cheaper subagents do the long reading and hand back a short summary.
43
+ - Before you move work to a bigger model, give the agent a way to check its own work, such as a test, a build or a script.
44
+ - A built-in agent such as Explore runs on the session's model unless the spawn names one, so name the model.
45
+
46
+ Source for the work split: [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/).
@@ -4,6 +4,9 @@ The package routes native subagent requests before the child starts. It keeps
4
4
  approved pairs, aliases, replacements, selector exclusions, and the advisor
5
5
  default in one file.
6
6
 
7
+ This page covers Codex children. Claude children follow
8
+ [Subagent model and effort](rule-guides/subagent-model-effort.md).
9
+
7
10
  The source policy is
8
11
  `packages/claude-dev-env/rules/subagent-model-policy.json`.
9
12
 
@@ -120,6 +120,19 @@ def expected_block(tool_name: str, quoted_sentence: str) -> dict[str, object]:
120
120
  }
121
121
 
122
122
 
123
+ def expected_advisory(tool_name: str, quoted_sentence: str) -> dict[str, object]:
124
+ return {
125
+ "hookSpecificOutput": {
126
+ "hookEventName": "PostToolUse",
127
+ "additionalContext": (
128
+ f'The reasoning behind this {tool_name} call hedges: "{quoted_sentence}" '
129
+ "Check that claim with a read-only tool before you act on the agent's result. "
130
+ "If it is wrong, send the agent a correction or stop it."
131
+ ),
132
+ }
133
+ }
134
+
135
+
123
136
  @pytest.fixture(autouse=True)
124
137
  def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
125
138
  monkeypatch.setenv("HOME", str(tmp_path))
@@ -438,8 +451,6 @@ def test_should_block_a_git_change_behind_a_wrapper(
438
451
  "Edit",
439
452
  "MultiEdit",
440
453
  "NotebookEdit",
441
- "Agent",
442
- "Task",
443
454
  "apply_patch",
444
455
  "mcp__gmail__send_message",
445
456
  "mcp__github__issue_write",
@@ -463,6 +474,45 @@ def test_should_block_each_always_mutating_tool_after_hedged_reasoning(
463
474
  assert json.loads(stdout_text)["decision"] == "block"
464
475
 
465
476
 
477
+ AGENT_INPUT = {"description": "Find the config", "prompt": "Read settings.json and report."}
478
+
479
+
480
+ @pytest.mark.parametrize("tool_name", ["Agent", "Task"])
481
+ def test_should_advise_without_blocking_a_spawn_after_hedged_reasoning(
482
+ monkeypatch: pytest.MonkeyPatch,
483
+ capsys: pytest.CaptureFixture[str],
484
+ tmp_path: Path,
485
+ tool_name: str,
486
+ ) -> None:
487
+ transcript_path = acting_transcript(tmp_path, HEDGED_SENTENCE, tool_name, AGENT_INPUT)
488
+ exit_code, stdout_text = run_hook(monkeypatch, capsys, tool_name, AGENT_INPUT, transcript_path)
489
+ output = json.loads(stdout_text)
490
+ assert exit_code == 0
491
+ assert "decision" not in output
492
+ assert output == expected_advisory(tool_name, HEDGED_SENTENCE)
493
+ assert logged_outcomes(tmp_path) == ["advised"]
494
+
495
+
496
+ def test_should_allow_a_spawn_after_clean_reasoning(
497
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
498
+ ) -> None:
499
+ transcript_path = acting_transcript(tmp_path, CLEAN_SENTENCE, "Agent", AGENT_INPUT)
500
+ exit_code, stdout_text = run_hook(monkeypatch, capsys, "Agent", AGENT_INPUT, transcript_path)
501
+ assert (exit_code, stdout_text) == (0, "")
502
+ assert logged_outcomes(tmp_path) == ["allowed_clean"]
503
+
504
+
505
+ def test_should_still_block_an_edit_after_the_same_hedge_that_advises_a_spawn(
506
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
507
+ ) -> None:
508
+ edit_input = {"file_path": "settings.json", "old_string": "a", "new_string": "b"}
509
+ transcript_path = acting_transcript(tmp_path, HEDGED_SENTENCE, "Edit", edit_input)
510
+ exit_code, stdout_text = run_hook(monkeypatch, capsys, "Edit", edit_input, transcript_path)
511
+ assert exit_code == 0
512
+ assert json.loads(stdout_text) == expected_block("Edit", HEDGED_SENTENCE)
513
+ assert logged_outcomes(tmp_path) == ["blocked"]
514
+
515
+
466
516
  def test_should_register_a_matcher_covering_every_mutating_tool_name() -> None:
467
517
  hooks_configuration = json.loads(
468
518
  (Path(__file__).resolve().parent.parent / "hooks.json").read_text(encoding="utf-8")
@@ -6,12 +6,16 @@ found in the session transcript by the call's ``tool_use_id``. When that
6
6
  reasoning hedges, the hook blocks and quotes the hedge sentence::
7
7
 
8
8
  flag: The config probably lives in settings.json. -> Write blocks
9
+ note: The config probably lives in settings.json. -> Agent gets advice
9
10
  ok: The config lives in settings.json, as read. -> Write passes
10
11
  ok: The config probably lives in settings.json. -> gh pr view passes
11
12
 
12
13
  The tool has already run, so the block reason tells the model to check the
13
14
  claim now with a read-only tool and to undo the change when the check
14
- contradicts it.
15
+ contradicts it. A spawn in ALL_ADVISORY_TOOL_NAMES (Agent, Task) has also
16
+ already run, so a block stops nothing there; the hook adds the same quote as
17
+ additionalContext with no decision, and asks the model to check the claim
18
+ before it acts on the agent's result.
15
19
 
16
20
  A call counts as mutating when its tool is in ALL_ALWAYS_MUTATING_TOOL_NAMES
17
21
  (Write, Edit, MultiEdit, NotebookEdit, apply_patch, Agent, Task), when a
@@ -24,7 +28,7 @@ from the quote-aware parser after every wrapper is stepped over, so
24
28
  is a check and passes with no log line.
25
29
 
26
30
  Each mutating call writes one JSON line to DECISION_LOG_RELATIVE_PATH under
27
- the home directory: blocked, allowed_clean, or reasoning_unseen when the
31
+ the home directory: blocked, advised, allowed_clean, or reasoning_unseen when the
28
32
  transcript record is missing or its thinking text is empty. A missing or
29
33
  unreadable input always allows, so the hook never fails closed.
30
34
  """
@@ -49,9 +53,12 @@ from hooks_constants.hook_specific_output_keys import (
49
53
  HOOK_SPECIFIC_OUTPUT_KEY,
50
54
  )
51
55
  from hooks_constants.hook_block_logger import log_hook_block
56
+ from hooks_constants.post_tool_use_context import write_post_tool_use_context_to_stdout
52
57
  from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
53
58
  from hooks_constants.shell_command_mutation import is_mutating_shell_command
54
59
  from hooks_constants.verify_before_acting_constants import (
60
+ ADVISORY_CONTEXT_TEMPLATE,
61
+ ALL_ADVISORY_TOOL_NAMES,
55
62
  ALL_ALWAYS_MUTATING_TOOL_NAMES,
56
63
  ALL_MCP_MUTATING_ACTION_NAMES,
57
64
  ALL_MCP_MUTATING_VERBS,
@@ -80,6 +87,7 @@ from hooks_constants.verify_before_acting_constants import (
80
87
  MCP_TOOL_PREFIX,
81
88
  MESSAGE_ID_KEY,
82
89
  MESSAGE_KEY,
90
+ OUTCOME_ADVISED,
83
91
  OUTCOME_ALLOWED_CLEAN,
84
92
  OUTCOME_BLOCKED,
85
93
  OUTCOME_REASONING_UNSEEN,
@@ -299,6 +307,13 @@ def _emit_block(tool_name: str, tool_use_id: object, hedge_sentence: str) -> Non
299
307
  sys.stdout.write(json.dumps(block_payload))
300
308
 
301
309
 
310
+ def _emit_advisory(tool_name: str, tool_use_id: object, hedge_sentence: str) -> None:
311
+ _log_decision(tool_name, tool_use_id, OUTCOME_ADVISED, hedge_sentence)
312
+ write_post_tool_use_context_to_stdout(
313
+ ADVISORY_CONTEXT_TEMPLATE.format(tool_name=tool_name, hedge_sentence=hedge_sentence)
314
+ )
315
+
316
+
302
317
  def main() -> int:
303
318
  hook_input = read_hook_input_dictionary_from_stdin()
304
319
  if hook_input is None:
@@ -317,6 +332,9 @@ def main() -> int:
317
332
  if hedge_sentence is None:
318
333
  _log_decision(tool_name, tool_use_id, OUTCOME_ALLOWED_CLEAN, None)
319
334
  return ALLOW_EXIT_CODE
335
+ if tool_name in ALL_ADVISORY_TOOL_NAMES:
336
+ _emit_advisory(tool_name, tool_use_id, hedge_sentence)
337
+ return ALLOW_EXIT_CODE
320
338
  _emit_block(tool_name, tool_use_id, hedge_sentence)
321
339
  return ALLOW_EXIT_CODE
322
340
 
@@ -17,7 +17,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
17
17
  - `blocking/session_title_turn_gate.py` holds the end of a turn once, in a session that has a `__set_session_title` tool, when the shown title does not fit the session's state: no title yet, a red flag after a prompt that asks for work, a check mark while the task list has open items, or an hourglass once every item is completed or deleted. A turn that set a title passes. A turn that called no tool other than the title tool passes, and so does a held turn.
18
18
  - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
19
19
  - `blocking/wakeup_cap_gate.py` keeps a self-wakeup inside the 1-hour prompt cache. A wake over the step-down (57 minutes for `send_later` and Routines, 3480 seconds for `ScheduleWakeup`) and at most 60 minutes away runs with its delay rewritten to the step-down. A wake over 60 minutes away, or a cron with more than 57 minutes between wakes, is denied with a reason that says to stack wakes under the cap. A Routine that starts a fresh session on each firing passes.
20
- - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
20
+ - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim. For an `Agent` or `Task` spawn it adds the same quote as an advisory note and does not block.
21
21
  - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction. Read-only `gh pr` subcommands (`view`, `list`, `checks`, `diff`, `status`) pass without it, unless a later argument names another `gh pr` subcommand.
22
22
  - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
23
23
  - `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call whose result comes back without an error, or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, test files, or `.json`, `.jsonl`, `.yaml`, `.yml`, or `.csv` files under a `docs` folder.
@@ -72,7 +72,7 @@ Preconditions:
72
72
  - **Stale title.** Input is a transcript that lists the title tool, an earlier turn that set the red flag, and a work prompt whose turn ran a tool and set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_turn_gate.py -q`. The adjacent test observes a `block` decision that names the shown title, the tool, and the four status emoji. A carried hourglass with an item in progress passes, and so does a turn whose title call came back without an error.
73
73
  - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
74
74
  - **Wakeup cap.** Input is a `send_later` call with `delay_minutes` of 60, then 90, then 45. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_wakeup_cap_gate.py -q`. The adjacent test observes 60 rewritten to 57 through `updatedInput`, 90 denied with the stacking instruction, and 45 passing untouched.
75
- - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
75
+ - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome. The same hedge before an `Agent` call gives `additionalContext`, no `decision`, and a logged advised outcome.
76
76
  - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
77
77
  - **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a commit of data files under a `docs` folder, a tests-only commit, and a repository with no verify skill pass. A `.py` file under `docs` and a `.json` file outside `docs` still deny.
78
78
  - **Eval write.** Input is a Write to `evals/cases.json` with no build-eval call in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_build_eval_before_eval_write_gate.py -q`. The adjacent test observes a denial, then an allow once the call appears; a write outside an eval path passes.
@@ -89,7 +89,7 @@ Preconditions:
89
89
  - Each review run calls a model and costs about $0.03. Leave `CLAUDE_TURN_REVIEW_REPOSITORIES` unset and the gate makes no snapshot and no call.
90
90
  - `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
91
91
  - `blocking/wakeup_cap_gate.py` lets an `update_trigger` cron change pass, because that input does not say whether the Routine wakes a session. Its step-down values come from fire-time probes: `send_later` rounds its fire time up to the next minute and polls once a minute, so a 1-minute request landed 123 and 158 seconds later. `ScheduleWakeup` rounds its fire time up to the next minute, so requests of 60 and 90 seconds landed 70 and 121 seconds later.
92
- - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
92
+ - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change. A spawn has already started when the hook runs, so a block would stop nothing. The advisory note asks the agent to check the claim before it acts on the spawned agent's result.
93
93
  - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
94
94
  - The final reply gate blocks the stop and returns its reason to the model, which rewrites the reply. Claude Code ends the turn anyway after eight blocks in a row. The cited number checks in both gates skip when the transcript cannot be read.
95
95
  - The edit marker gate scans replacement cards as well as the message text.
@@ -1,12 +1,13 @@
1
1
  # Spawn routing
2
2
 
3
- This family reminds the agent to gather context before a spawn, refuses a brief without the user's outcome and a blocker clause, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, selects an allowed subagent model, and lets a Haiku spawn through only when it names the `lean-worker` subagent type, sending other Haiku spawns to a headless slim-profile run.
3
+ This family reminds the agent to gather context before a spawn, refuses a brief without the user's outcome and a blocker clause, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, sets an allowed effort for each Anthropic model, selects an allowed subagent model, and lets a Haiku spawn through only when it names the `lean-worker` subagent type, sending other Haiku spawns to a headless slim-profile run.
4
4
 
5
5
  ## Checks
6
6
 
7
7
  - `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
8
8
  - `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. A spawn that passes gets the orchestrator oversight directive: run each piece through the verified-work flow, with a fresh verifier agent that checks the research, the plan, and the fix, reproduces the issue before it confirms the fix, and leaves the worker's conclusion out of its brief; ask the user before new scope; report as done only what a verifier passed; and watch the agent while it runs. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
9
- - `routing/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
9
+ - `routing/thread_spawn_pace_hook.py` reshapes a thread request to Opus at medium when usage is over pace or unreadable. Under pace, a thread request that names a model gets the effort its model allows.
10
+ - `routing/subagent_effort_route_hook.py` sets an allowed effort on an Agent or Task spawn: Opus medium, Sonnet high, Fable low, medium or high, and Haiku any effort. A spawn with no effort or one outside its model's list gets Opus medium, Sonnet high, Fable high, or Haiku medium. `routing/subagent_effort_route.py` holds the rule for this hook and the pace hook.
10
11
  - `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
11
12
  - `blocking/haiku_spawn_slim_gate.py` denies an Agent, Task, or thread spawn whose `model` names Haiku, except an Agent or Task spawn with `subagent_type` `lean-worker`. The deny reason gives two routes: the `lean-worker` subagent type, and the headless `claude -p` command that loads the slim profile through the account broker.
12
13
 
@@ -15,6 +16,7 @@ This family reminds the agent to gather context before a spawn, refuses a brief
15
16
  - `routing/spawn_readiness_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
16
17
  - `routing/spawn_oversight_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, `mcp__hearthbot__start_thread_session`, and `mcp__hearthbot__start_rc_session|mcp__hearthbot__start_remote_control`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
17
18
  - `routing/thread_spawn_pace_hook.py` runs on `PreToolUse`, matcher `mcp__hearthbot__start_thread_session`, timeout `30` seconds in `hooks.json`.
19
+ - `routing/subagent_effort_route_hook.py` runs on `PreToolUse`, matcher `Agent|Task`, timeout `10` seconds in `hooks.json`, right after the Haiku slim gate.
18
20
  - `routing/subagent_model_routing.mjs` runs on `PreToolUse`, matcher `multi_agent_v1__spawn_agent`, timeout `10` seconds through the quoted Node command in `hooks.json`.
19
21
  - `blocking/haiku_spawn_slim_gate.py` runs on `PreToolUse` with matchers `Agent|Task` and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`.
20
22
 
@@ -26,7 +28,8 @@ Preconditions:
26
28
 
27
29
  - **Spawn readiness.** Input is a spawn after a read, a question, and its answer. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_readiness_hook.py -q`. The adjacent test observes no output for a ready spawn and reminder context for each missing step.
28
30
  - **Spawn oversight.** Input is a route-only brief, a brief with both clauses, and briefs with one clause, on each registered tool, plus a non-spawn call. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_oversight_hook.py packages/claude-dev-env/hooks/routing/test_spawn_brief_text.py -q`. The adjacent test observes a deny for each brief missing a clause, the directive for the passing brief, and no output for the other calls.
29
- - **Thread pace.** Input is a thread spawn with usage over pace. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes updated tool input with the selected model, effort, and advisor line.
31
+ - **Thread pace.** Input is a thread spawn with usage over pace, and thread spawns under pace that name a model. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes Opus at medium over pace, the allowed effort under pace, and no output for an allowed pair.
32
+ - **Subagent effort route.** Input is an Agent spawn on each model family at allowed and outside efforts, a spawn with no model and a transcript, a fork, and stdin that is not an object. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_subagent_effort_route.py packages/claude-dev-env/hooks/routing/test_subagent_effort_route_hook.py -q`. The adjacent test observes updated tool input with the allowed effort and a context line, and no output for an allowed pair, a fork, or an unknown model.
30
33
  - **Haiku slim gate.** Input is a spawn with a Haiku alias or model ID, with `subagent_type` set to `lean-worker` or to another type, and spawns on other models or with no model. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_haiku_spawn_slim_gate.py -q`. The adjacent test observes no output for a Haiku spawn of `lean-worker`, a deny with both routes for each other Haiku spawn, and no output for the rest.
31
34
  - **Model routing.** Input is a `multi_agent_v1__spawn_agent` payload with a model choice. Run `node --test packages/claude-dev-env/hooks/routing/subagent_model_routing.test.mjs`. The adjacent test observes an allow or deny decision with the routed model.
32
35
 
@@ -36,4 +39,6 @@ Preconditions:
36
39
  - The oversight hook fires inside subagents and on read-only helper types too, so every brief at every level carries the outcome and the blocker clause. A `Workflow` call with no script text, such as a saved or resumed run, passes with the directive.
37
40
  - The readiness hook emits `additionalContext` only, so it never blocks. It passes subagent calls, read-only helper types, a non-object tool input, and unreadable transcripts.
38
41
  - The Haiku slim gate reads the spawn's `model` and `subagent_type` fields. A spawn that names no model passes, even when its agent definition or `CLAUDE_CODE_SUBAGENT_MODEL` resolves it to Haiku.
42
+ - The effort route reads the parent model with `last_assistant_model`, from the newest assistant line of the transcript when a spawn names no model. An agent definition that sets its own model is not seen, so the route can pick that family wrong. Name the model on every spawn.
43
+ - The effort route changes only the effort, never the model, and it leaves a model it does not know, such as a Codex model, as it is. A thread spawn that names no model is left as it is.
39
44
  - The model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.
package/hooks/hooks.json CHANGED
@@ -10,6 +10,11 @@
10
10
  "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/haiku_spawn_slim_gate.py",
11
11
  "timeout": 10
12
12
  },
13
+ {
14
+ "type": "command",
15
+ "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/subagent_effort_route_hook.py",
16
+ "timeout": 10
17
+ },
13
18
  {
14
19
  "type": "command",
15
20
  "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
@@ -0,0 +1,45 @@
1
+ """Constants for the subagent effort route.
2
+
3
+ Groups: the allowed effort for each Anthropic model family, the effort a spawn
4
+ gets when it names none or names one outside its family's list, the tool
5
+ input keys, and the hook output text.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ OPUS_MODEL_FAMILY = "opus"
11
+ SONNET_MODEL_FAMILY = "sonnet"
12
+ FABLE_MODEL_FAMILY = "fable"
13
+ HAIKU_MODEL_FAMILY = "haiku"
14
+
15
+ ALL_ALLOWED_EFFORTS_BY_FAMILY: dict[str, tuple[str, ...]] = {
16
+ OPUS_MODEL_FAMILY: ("medium",),
17
+ SONNET_MODEL_FAMILY: ("high",),
18
+ FABLE_MODEL_FAMILY: ("low", "medium", "high"),
19
+ HAIKU_MODEL_FAMILY: ("low", "medium", "high", "xhigh", "max"),
20
+ }
21
+
22
+ ALL_ROUTED_EFFORT_BY_FAMILY: dict[str, str] = {
23
+ OPUS_MODEL_FAMILY: "medium",
24
+ SONNET_MODEL_FAMILY: "high",
25
+ FABLE_MODEL_FAMILY: "high",
26
+ HAIKU_MODEL_FAMILY: "medium",
27
+ }
28
+
29
+ MODEL_INPUT_KEY = "model"
30
+ EFFORT_INPUT_KEY = "effort"
31
+ SUBAGENT_TYPE_INPUT_KEY = "subagent_type"
32
+ FORK_SUBAGENT_TYPE = "fork"
33
+
34
+ TOOL_INPUT_KEY = "tool_input"
35
+ TRANSCRIPT_PATH_KEY = "transcript_path"
36
+ TRANSCRIPT_ENTRY_TYPE_KEY = "type"
37
+ TRANSCRIPT_ASSISTANT_TYPE = "assistant"
38
+ TRANSCRIPT_MESSAGE_KEY = "message"
39
+ TRANSCRIPT_TAIL_BYTES = 2_000_000
40
+ SEEK_FROM_FILE_END = 2
41
+
42
+ ADDITIONAL_CONTEXT_KEY = "additionalContext"
43
+ ROUTED_CONTEXT_TEMPLATE = (
44
+ "Subagent model and effort rule: this {family} spawn now runs at {effort} effort."
45
+ )
@@ -12,6 +12,11 @@ def test_mutating_tool_and_mcp_names_are_classified() -> None:
12
12
  assert "create" in constants.ALL_MCP_MUTATING_VERBS
13
13
 
14
14
 
15
+ def test_advisory_tools_are_scanned_as_mutating_calls() -> None:
16
+ assert {"Agent", "Task"} == constants.ALL_ADVISORY_TOOL_NAMES
17
+ assert constants.ALL_ADVISORY_TOOL_NAMES <= constants.ALL_ALWAYS_MUTATING_TOOL_NAMES
18
+
19
+
15
20
  def test_hedge_pattern_matches_a_hedged_claim_only() -> None:
16
21
  assert constants.HEDGE_PATTERN.search("Perhaps the command writes a file.")
17
22
  assert constants.HEDGE_PATTERN.search("I might be mistaken.")
@@ -1,7 +1,8 @@
1
1
  """Constants for the thread spawn pace PreToolUse hook.
2
2
 
3
3
  Groups: the usage-pace script it runs, the reshape values for an over-pace
4
- spawn, and the hook output keys and messages.
4
+ spawn, and the hook output keys and messages. Opus runs at medium only,
5
+ per the Subagent model and effort rule.
5
6
  """
6
7
 
7
8
  from __future__ import annotations
@@ -12,7 +13,7 @@ USAGE_PACE_TIMEOUT_SECONDS = 15
12
13
 
13
14
  TOOL_INPUT_KEY = "tool_input"
14
15
  THREAD_MODEL_WHEN_OVER_PACE = "claude-opus-5-5"
15
- THREAD_EFFORT_WHEN_OVER_PACE = "low"
16
+ THREAD_EFFORT_WHEN_OVER_PACE = "medium"
16
17
  MODEL_INPUT_KEY = "model"
17
18
  EFFORT_INPUT_KEY = "effort"
18
19
 
@@ -22,7 +23,7 @@ ADDITIONAL_CONTEXT_KEY = "additionalContext"
22
23
  NOT_AN_OBJECT_REASON = "start_thread_session input is not a JSON object"
23
24
  RESHAPE_CONTEXT_PREFIX = (
24
25
  "Usage over pace or unreadable: this thread spawn now runs on "
25
- "claude-opus-5-5 at low effort. Pace verdict: "
26
+ "claude-opus-5-5 at medium effort. Pace verdict: "
26
27
  )
27
28
  PACE_VERDICT_CONTEXT_MAXIMUM_CHARACTERS = 600
28
29
  LAUNCH_FAILURE_ERROR_TEMPLATE = "usage pace did not finish: {failure_type}"
@@ -27,6 +27,7 @@ TRANSCRIPT_POLL_LIMIT_SECONDS = 5.0
27
27
  ALL_ALWAYS_MUTATING_TOOL_NAMES = frozenset(
28
28
  {"Write", "Edit", "MultiEdit", "NotebookEdit", "Agent", "Task", APPLY_PATCH_TOOL_NAME}
29
29
  )
30
+ ALL_ADVISORY_TOOL_NAMES = frozenset({"Agent", "Task"})
30
31
  ALL_SHELL_TOOL_NAMES = frozenset({"Bash", "PowerShell"})
31
32
  MCP_TOOL_PREFIX = "mcp__"
32
33
  MCP_SEGMENT_SEPARATOR = "__"
@@ -156,6 +157,11 @@ BLOCK_REASON_TEMPLATE = (
156
157
  "Check that claim now with a read-only tool, then continue. "
157
158
  "If the check contradicts it, undo this change first."
158
159
  )
160
+ ADVISORY_CONTEXT_TEMPLATE = (
161
+ 'The reasoning behind this {tool_name} call hedges: "{hedge_sentence}" '
162
+ "Check that claim with a read-only tool before you act on the agent's result. "
163
+ "If it is wrong, send the agent a correction or stop it."
164
+ )
159
165
 
160
166
  DECISION_LOG_RELATIVE_PATH = ".claude/logs/verify-before-acting.jsonl"
161
167
  LOG_APPEND_MODE = "a"
@@ -166,5 +172,6 @@ LOG_TOOL_USE_ID_KEY = "tool_use_id"
166
172
  LOG_OUTCOME_KEY = "outcome"
167
173
  LOG_HEDGE_SENTENCE_KEY = "hedge_sentence"
168
174
  OUTCOME_BLOCKED = "blocked"
175
+ OUTCOME_ADVISED = "advised"
169
176
  OUTCOME_ALLOWED_CLEAN = "allowed_clean"
170
177
  OUTCOME_REASONING_UNSEEN = "reasoning_unseen"
@@ -0,0 +1,97 @@
1
+ """Give a spawn an effort its Anthropic model family allows.
2
+
3
+ ::
4
+
5
+ {"model": "opus", "effort": "xhigh"} -> effort "medium"
6
+ {"model": "claude-sonnet-5-5"} -> effort "high"
7
+ {"model": "fable", "effort": "max"} -> effort "high"
8
+ {"model": "haiku", "effort": "max"} -> unchanged
9
+ {"subagent_type": "fork"} -> unchanged
10
+ {} with the parent on Opus -> effort "medium"
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import sys
16
+ from pathlib import Path
17
+
18
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
19
+ if hooks_root_directory not in sys.path:
20
+ sys.path.insert(0, hooks_root_directory)
21
+
22
+ from hooks_constants.subagent_effort_route_constants import (
23
+ ALL_ALLOWED_EFFORTS_BY_FAMILY,
24
+ ALL_ROUTED_EFFORT_BY_FAMILY,
25
+ EFFORT_INPUT_KEY,
26
+ FORK_SUBAGENT_TYPE,
27
+ MODEL_INPUT_KEY,
28
+ SUBAGENT_TYPE_INPUT_KEY,
29
+ )
30
+
31
+
32
+ def model_family(model: object) -> str | None:
33
+ """Return the Anthropic family a model name or alias belongs to.
34
+
35
+ ::
36
+
37
+ "opus" -> "opus" "claude-fable-5-2" -> "fable"
38
+ "inherit" -> None None -> None
39
+
40
+ Args:
41
+ model: A model alias or full model id, or anything else.
42
+ """
43
+ if not isinstance(model, str):
44
+ return None
45
+ lowered_model = model.lower()
46
+ for each_family in ALL_ALLOWED_EFFORTS_BY_FAMILY:
47
+ if each_family in lowered_model:
48
+ return each_family
49
+ return None
50
+
51
+
52
+ def routed_effort(family: str, effort: object) -> str:
53
+ """Return the effort a spawn of this family runs at.
54
+
55
+ ::
56
+
57
+ ("opus", "xhigh") -> "medium" ("fable", "low") -> "low"
58
+ ("sonnet", None) -> "high"
59
+
60
+ Args:
61
+ family: An Anthropic model family.
62
+ effort: The effort the spawn named, or None.
63
+ """
64
+ if effort in ALL_ALLOWED_EFFORTS_BY_FAMILY[family]:
65
+ return str(effort)
66
+ return ALL_ROUTED_EFFORT_BY_FAMILY[family]
67
+
68
+
69
+ def route_spawn_input(
70
+ tool_input: object, parent_model: str | None
71
+ ) -> tuple[dict[str, object], str, str] | None:
72
+ """Return the spawn input with an allowed effort, or None to leave it.
73
+
74
+ A fork keeps its parent's model and effort. A spawn whose model resolves
75
+ to no Anthropic family, from its own field or from the parent's model,
76
+ is left as it is.
77
+
78
+ Args:
79
+ tool_input: The spawn tool's input.
80
+ parent_model: The model of the session that spawns, when known.
81
+
82
+ Returns:
83
+ The updated input, the family, and the effort, or None when the
84
+ input already holds an allowed effort or cannot be routed.
85
+ """
86
+ if not isinstance(tool_input, dict):
87
+ return None
88
+ if tool_input.get(SUBAGENT_TYPE_INPUT_KEY) == FORK_SUBAGENT_TYPE:
89
+ return None
90
+ family = model_family(tool_input.get(MODEL_INPUT_KEY)) or model_family(parent_model)
91
+ if family is None:
92
+ return None
93
+ current_effort = tool_input.get(EFFORT_INPUT_KEY)
94
+ allowed_effort = routed_effort(family, current_effort)
95
+ if allowed_effort == current_effort:
96
+ return None
97
+ return {**tool_input, EFFORT_INPUT_KEY: allowed_effort}, family, allowed_effort
@@ -0,0 +1,139 @@
1
+ #!/usr/bin/env python3
2
+ """PreToolUse hook: give an Agent or Task spawn an allowed effort.
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.
8
+
9
+ ::
10
+
11
+ model "opus", effort "xhigh" -> updatedInput with effort "medium"
12
+ model "sonnet", no effort -> updatedInput with effort "high"
13
+ model "haiku", effort "max" -> no output
14
+ subagent_type "fork" -> no output
15
+ no model, unreadable transcript -> no output
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import json
21
+ import sys
22
+ from pathlib import Path
23
+
24
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
25
+ if hooks_root_directory not in sys.path:
26
+ sys.path.insert(0, hooks_root_directory)
27
+ routing_directory = str(Path(__file__).resolve().parent)
28
+ if routing_directory not in sys.path:
29
+ sys.path.insert(0, routing_directory)
30
+
31
+ from hooks_constants.bash_pre_tool_use_dispatcher_constants import HOOK_EVENT_NAME
32
+ from hooks_constants.hook_specific_output_keys import (
33
+ HOOK_EVENT_NAME_KEY,
34
+ HOOK_SPECIFIC_OUTPUT_KEY,
35
+ UPDATED_INPUT_KEY,
36
+ )
37
+ from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
38
+ from hooks_constants.subagent_effort_route_constants import (
39
+ ADDITIONAL_CONTEXT_KEY,
40
+ MODEL_INPUT_KEY,
41
+ ROUTED_CONTEXT_TEMPLATE,
42
+ TOOL_INPUT_KEY,
43
+ TRANSCRIPT_ASSISTANT_TYPE,
44
+ TRANSCRIPT_ENTRY_TYPE_KEY,
45
+ TRANSCRIPT_MESSAGE_KEY,
46
+ TRANSCRIPT_PATH_KEY,
47
+ SEEK_FROM_FILE_END,
48
+ TRANSCRIPT_TAIL_BYTES,
49
+ )
50
+ from subagent_effort_route import route_spawn_input
51
+
52
+
53
+ def last_assistant_model(transcript_path: object) -> str | None:
54
+ """Return the model of the transcript's last assistant entry.
55
+
56
+ Args:
57
+ transcript_path: The payload's ``transcript_path``.
58
+
59
+ Returns:
60
+ The model id, or None when the file is missing, unreadable, or holds
61
+ no assistant entry with a model.
62
+ """
63
+ if not isinstance(transcript_path, str) or not transcript_path:
64
+ return None
65
+ try:
66
+ with open(transcript_path, "rb") as transcript_file:
67
+ transcript_file.seek(0, SEEK_FROM_FILE_END)
68
+ file_size = transcript_file.tell()
69
+ transcript_file.seek(max(0, file_size - TRANSCRIPT_TAIL_BYTES))
70
+ tail_text = transcript_file.read().decode("utf-8", errors="replace")
71
+ except OSError:
72
+ return None
73
+ return newest_assistant_model(tail_text)
74
+
75
+
76
+ def newest_assistant_model(transcript_text: str) -> str | None:
77
+ """Return the model of the newest assistant line in transcript text.
78
+
79
+ Args:
80
+ transcript_text: JSONL transcript lines, oldest first.
81
+
82
+ Returns:
83
+ The model id, or None when no assistant line names a model.
84
+ """
85
+ for each_line in reversed(transcript_text.splitlines()):
86
+ try:
87
+ entry = json.loads(each_line)
88
+ except json.JSONDecodeError:
89
+ continue
90
+ if not isinstance(entry, dict) or entry.get(TRANSCRIPT_ENTRY_TYPE_KEY) != TRANSCRIPT_ASSISTANT_TYPE:
91
+ continue
92
+ message = entry.get(TRANSCRIPT_MESSAGE_KEY)
93
+ if isinstance(message, dict) and isinstance(message.get(MODEL_INPUT_KEY), str):
94
+ return message[MODEL_INPUT_KEY]
95
+ return None
96
+
97
+
98
+ def decide_hook_output(all_hook_payload: dict[str, object] | None) -> dict[str, object] | None:
99
+ """Choose the hook output for one spawn payload.
100
+
101
+ Args:
102
+ all_hook_payload: The PreToolUse payload, or None when stdin held no object.
103
+
104
+ Returns:
105
+ None to pass the call through unchanged, else the hook JSON output.
106
+ """
107
+ if all_hook_payload is None:
108
+ return None
109
+ routed = route_spawn_input(
110
+ all_hook_payload.get(TOOL_INPUT_KEY),
111
+ last_assistant_model(all_hook_payload.get(TRANSCRIPT_PATH_KEY)),
112
+ )
113
+ if routed is None:
114
+ return None
115
+ routed_input, family, effort = routed
116
+ return {
117
+ HOOK_SPECIFIC_OUTPUT_KEY: {
118
+ HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME,
119
+ UPDATED_INPUT_KEY: routed_input,
120
+ ADDITIONAL_CONTEXT_KEY: ROUTED_CONTEXT_TEMPLATE.format(family=family, effort=effort),
121
+ }
122
+ }
123
+
124
+
125
+ def main() -> int:
126
+ """Read the PreToolUse payload and print the routing decision.
127
+
128
+ Returns:
129
+ 0 in every case.
130
+ """
131
+ hook_output = decide_hook_output(read_hook_input_dictionary_from_stdin())
132
+ if hook_output is not None:
133
+ sys.stdout.write(json.dumps(hook_output))
134
+ sys.stdout.flush()
135
+ return 0
136
+
137
+
138
+ if __name__ == "__main__":
139
+ sys.exit(main())
@@ -0,0 +1,74 @@
1
+ import pytest
2
+
3
+ from subagent_effort_route import model_family, route_spawn_input, routed_effort
4
+
5
+
6
+ @pytest.mark.parametrize(
7
+ ("model", "family"),
8
+ [
9
+ ("opus", "opus"),
10
+ ("claude-opus-5-5", "opus"),
11
+ ("Sonnet", "sonnet"),
12
+ ("claude-fable-5-2", "fable"),
13
+ ("claude-haiku-5-5", "haiku"),
14
+ ("inherit", None),
15
+ ("gpt-5", None),
16
+ (None, None),
17
+ (7, None),
18
+ ],
19
+ )
20
+ def test_should_name_the_family_of_a_model(model: object, family: str | None) -> None:
21
+ assert model_family(model) == family
22
+
23
+
24
+ @pytest.mark.parametrize(
25
+ ("family", "effort", "expected"),
26
+ [
27
+ ("opus", "xhigh", "medium"),
28
+ ("opus", "low", "medium"),
29
+ ("opus", None, "medium"),
30
+ ("sonnet", "medium", "high"),
31
+ ("sonnet", None, "high"),
32
+ ("fable", "low", "low"),
33
+ ("fable", "medium", "medium"),
34
+ ("fable", "max", "high"),
35
+ ("haiku", "max", "max"),
36
+ ("haiku", None, "medium"),
37
+ ],
38
+ )
39
+ def test_should_pick_an_allowed_effort(family: str, effort: object, expected: str) -> None:
40
+ assert routed_effort(family, effort) == expected
41
+
42
+
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) == (
46
+ {"model": "opus", "effort": "medium", "prompt": "Do X."},
47
+ "opus",
48
+ "medium",
49
+ )
50
+
51
+
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")
54
+ assert routed == ({"prompt": "Do X.", "effort": "high"}, "sonnet", "high")
55
+
56
+
57
+ def test_should_prefer_the_spawn_model_over_the_parent_model() -> None:
58
+ routed = route_spawn_input({"model": "haiku"}, "claude-opus-5-5")
59
+ assert routed == ({"model": "haiku", "effort": "medium"}, "haiku", "medium")
60
+
61
+
62
+ @pytest.mark.parametrize(
63
+ ("tool_input", "parent_model"),
64
+ [
65
+ ({"model": "opus", "effort": "medium"}, None),
66
+ ({"model": "haiku", "effort": "xhigh"}, None),
67
+ ({"subagent_type": "fork", "effort": "max"}, "claude-opus-5-5"),
68
+ ({"prompt": "Do X."}, None),
69
+ ({"model": "gpt-5", "effort": "max"}, None),
70
+ (["not", "an", "object"], "claude-opus-5-5"),
71
+ ],
72
+ )
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
@@ -0,0 +1,85 @@
1
+ import json
2
+ import subprocess
3
+ import sys
4
+ from pathlib import Path
5
+
6
+ HOOK_SCRIPT = Path(__file__).resolve().parent / "subagent_effort_route_hook.py"
7
+
8
+
9
+ def _write_transcript(tmp_path: Path, parent_model: str) -> Path:
10
+ transcript_path = tmp_path / "transcript.jsonl"
11
+ all_entries = [
12
+ {"type": "user", "message": {"role": "user", "content": "hi"}},
13
+ {"type": "assistant", "message": {"model": "claude-fable-5-2", "content": []}},
14
+ {"type": "assistant", "message": {"model": parent_model, "content": []}},
15
+ {"type": "user", "message": {"role": "user", "content": "tool result"}},
16
+ ]
17
+ transcript_path.write_text(
18
+ "\n".join(json.dumps(each_entry) for each_entry in all_entries) + "\nnot json\n",
19
+ encoding="utf-8",
20
+ )
21
+ return transcript_path
22
+
23
+
24
+ def _run_hook(tool_input: object, transcript_path: Path | None = None) -> str:
25
+ hook_payload: dict[str, object] = {
26
+ "hook_event_name": "PreToolUse",
27
+ "tool_name": "Agent",
28
+ "tool_input": tool_input,
29
+ }
30
+ if transcript_path is not None:
31
+ hook_payload["transcript_path"] = str(transcript_path)
32
+ completed = subprocess.run(
33
+ [sys.executable, str(HOOK_SCRIPT)],
34
+ input=json.dumps(hook_payload),
35
+ capture_output=True,
36
+ text=True,
37
+ check=True,
38
+ )
39
+ return completed.stdout
40
+
41
+
42
+ def _hook_specific_output(stdout: str) -> dict[str, object]:
43
+ return json.loads(stdout)["hookSpecificOutput"]
44
+
45
+
46
+ def test_should_move_an_opus_spawn_at_xhigh_to_medium() -> None:
47
+ spawn_input = {"subagent_type": "general-purpose", "model": "opus", "effort": "xhigh", "prompt": "Do X."}
48
+ decision = _hook_specific_output(_run_hook(spawn_input))
49
+ assert decision["hookEventName"] == "PreToolUse"
50
+ assert decision["updatedInput"] == {**spawn_input, "effort": "medium"}
51
+ assert decision["additionalContext"] == (
52
+ "Subagent model and effort rule: this opus spawn now runs at medium effort."
53
+ )
54
+ assert "permissionDecision" not in decision
55
+
56
+
57
+ def test_should_give_a_sonnet_spawn_with_no_effort_high() -> None:
58
+ decision = _hook_specific_output(_run_hook({"model": "sonnet", "prompt": "Do X."}))
59
+ assert decision["updatedInput"]["effort"] == "high"
60
+
61
+
62
+ def test_should_use_the_last_parent_model_when_the_spawn_names_none(tmp_path: Path) -> None:
63
+ decision = _hook_specific_output(
64
+ _run_hook({"subagent_type": "Explore", "prompt": "Find X."}, _write_transcript(tmp_path, "claude-opus-5-5"))
65
+ )
66
+ assert decision["updatedInput"] == {"subagent_type": "Explore", "prompt": "Find X.", "effort": "medium"}
67
+
68
+
69
+ def test_should_print_nothing_for_an_allowed_pair() -> None:
70
+ assert _run_hook({"model": "haiku", "effort": "max", "prompt": "Do X."}) == ""
71
+
72
+
73
+ def test_should_print_nothing_for_a_fork(tmp_path: Path) -> None:
74
+ assert _run_hook({"subagent_type": "fork", "prompt": "Do X."}, _write_transcript(tmp_path, "claude-opus-5-5")) == ""
75
+
76
+
77
+ def test_should_print_nothing_when_no_model_is_known(tmp_path: Path) -> None:
78
+ assert _run_hook({"prompt": "Do X."}, tmp_path / "absent.jsonl") == ""
79
+
80
+
81
+ def test_should_print_nothing_for_stdin_that_is_not_an_object() -> None:
82
+ completed = subprocess.run(
83
+ [sys.executable, str(HOOK_SCRIPT)], input="[1, 2]", capture_output=True, text=True, check=True
84
+ )
85
+ assert completed.stdout == ""
@@ -55,7 +55,7 @@ def _assert_reshaped(stdout: str) -> None:
55
55
  assert decision["updatedInput"] == {
56
56
  **SPAWN_INPUT,
57
57
  "model": "claude-opus-5-5",
58
- "effort": "low",
58
+ "effort": "medium",
59
59
  }
60
60
 
61
61
 
@@ -74,6 +74,43 @@ def test_should_pass_the_spawn_through_unchanged_when_usage_is_under_pace(
74
74
  )
75
75
 
76
76
 
77
+ @pytest.mark.parametrize(
78
+ ("spawn_pair", "routed_effort"),
79
+ [
80
+ ({"model": "claude-opus-5-5", "effort": "xhigh"}, "medium"),
81
+ ({"model": "claude-sonnet-5-5"}, "high"),
82
+ ({"model": "claude-fable-5-2", "effort": "max"}, "high"),
83
+ ],
84
+ )
85
+ def test_should_route_an_effort_outside_the_rule_when_usage_is_under_pace(
86
+ tmp_path: Path, spawn_pair: dict[str, str], routed_effort: str
87
+ ) -> None:
88
+ spawn_input = {**SPAWN_INPUT, **spawn_pair}
89
+ decision = _hook_specific_output(
90
+ _run_hook(_write_pace_stub(tmp_path, 1, {"over_pace": False}), spawn_input)
91
+ )
92
+ assert decision["updatedInput"] == {**spawn_input, "effort": routed_effort}
93
+ assert "permissionDecision" not in decision
94
+
95
+
96
+ @pytest.mark.parametrize(
97
+ "spawn_pair",
98
+ [
99
+ {"model": "claude-opus-5-5", "effort": "medium"},
100
+ {"model": "claude-fable-5-2", "effort": "low"},
101
+ {"model": "claude-haiku-5-5", "effort": "max"},
102
+ ],
103
+ )
104
+ def test_should_pass_an_allowed_pair_through_when_usage_is_under_pace(
105
+ tmp_path: Path, spawn_pair: dict[str, str]
106
+ ) -> None:
107
+ spawn_input = {**SPAWN_INPUT, **spawn_pair}
108
+ assert (
109
+ _run_hook(_write_pace_stub(tmp_path, 1, {"over_pace": False}), spawn_input)
110
+ == ""
111
+ )
112
+
113
+
77
114
  def test_should_reshape_the_spawn_when_usage_is_unreadable(tmp_path: Path) -> None:
78
115
  _assert_reshaped(
79
116
  _run_hook(
@@ -101,7 +138,7 @@ def test_should_quote_a_capped_pace_verdict_in_the_reshape_context(tmp_path: Pat
101
138
  )
102
139
  context_prefix = (
103
140
  "Usage over pace or unreadable: this thread spawn now runs on "
104
- "claude-opus-5-5 at low effort. Pace verdict: "
141
+ "claude-opus-5-5 at medium effort. Pace verdict: "
105
142
  )
106
143
  assert decision["additionalContext"] == context_prefix + json.dumps(long_verdict)[:600]
107
144
 
@@ -6,10 +6,11 @@ beside it, or the script ``COORDINATOR_USAGE_PACE_SCRIPT`` names.
6
6
 
7
7
  ::
8
8
 
9
- usage under pace (exit 1) -> no output; the call runs unchanged
10
- over pace (exit 0) or unreadable -> updatedInput:
11
- model "claude-opus-5-5", effort "low"
12
- input that cannot be reshaped -> deny with a one-line reason
9
+ under pace, allowed pair or no model -> no output; the call runs unchanged
10
+ under pace, effort outside the rule -> updatedInput with the allowed effort
11
+ over pace (exit 0) or unreadable -> updatedInput:
12
+ model "claude-opus-5-5", effort "medium"
13
+ input that cannot be reshaped -> deny with a one-line reason
13
14
 
14
15
  ``updatedInput`` is the whole tool input the call runs with, so it carries
15
16
  every original key.
@@ -26,6 +27,9 @@ from pathlib import Path
26
27
  hooks_root_directory = str(Path(__file__).resolve().parent.parent)
27
28
  if hooks_root_directory not in sys.path:
28
29
  sys.path.insert(0, hooks_root_directory)
30
+ routing_directory = str(Path(__file__).resolve().parent)
31
+ if routing_directory not in sys.path:
32
+ sys.path.insert(0, routing_directory)
29
33
 
30
34
  from hooks_constants.bash_pre_tool_use_dispatcher_constants import HOOK_EVENT_NAME
31
35
  from hooks_constants.hook_specific_output_keys import (
@@ -52,12 +56,14 @@ from hooks_constants.thread_spawn_pace_hook_constants import (
52
56
  USAGE_PACE_SCRIPT_FILE_NAME,
53
57
  USAGE_PACE_TIMEOUT_SECONDS,
54
58
  )
59
+ from hooks_constants.subagent_effort_route_constants import ROUTED_CONTEXT_TEMPLATE
55
60
  from hooks_constants.usage_pace_constants import (
56
61
  EXIT_CODE_UNDER_PACE,
57
62
  EXIT_CODE_UNREADABLE,
58
63
  RESULT_KEY_ERROR,
59
64
  RESULT_KEY_OVER_PACE,
60
65
  )
66
+ from subagent_effort_route import route_spawn_input
61
67
 
62
68
 
63
69
  class SpawnNotReshapable(Exception):
@@ -65,13 +71,13 @@ class SpawnNotReshapable(Exception):
65
71
 
66
72
 
67
73
  def reshape_thread_spawn(tool_input: object) -> dict[str, object]:
68
- """Move a thread spawn to Opus 5.5 at low effort.
74
+ """Move a thread spawn to Opus 5.5 at medium effort.
69
75
 
70
76
  ::
71
77
 
72
78
  {"title": "t", "instructions": "Do X."}
73
79
  -> {"title": "t", "instructions": "Do X.",
74
- "model": "claude-opus-5-5", "effort": "low"}
80
+ "model": "claude-opus-5-5", "effort": "medium"}
75
81
 
76
82
  Args:
77
83
  tool_input: The ``tool_input`` object of the start_thread_session call.
@@ -112,14 +118,26 @@ def decide_hook_output(
112
118
  tool_input: The ``tool_input`` of the PreToolUse payload, or None when
113
119
  stdin held no JSON object.
114
120
  pace_exit_code: The usage-pace exit code; anything but under pace
115
- counts as over pace.
121
+ counts as over pace. Under pace, a spawn that names a model gets
122
+ the effort the Subagent model and effort rule allows.
116
123
  pace_verdict_text: The usage-pace stdout, quoted into the context.
117
124
 
118
125
  Returns:
119
126
  None to pass the call through unchanged, else the hook JSON output.
120
127
  """
121
128
  if pace_exit_code == EXIT_CODE_UNDER_PACE:
122
- return None
129
+ routed = route_spawn_input(tool_input, None)
130
+ if routed is None:
131
+ return None
132
+ routed_input, family, effort = routed
133
+ return _hook_output(
134
+ {
135
+ UPDATED_INPUT_KEY: routed_input,
136
+ ADDITIONAL_CONTEXT_KEY: ROUTED_CONTEXT_TEMPLATE.format(
137
+ family=family, effort=effort
138
+ ),
139
+ }
140
+ )
123
141
  try:
124
142
  reshaped_input = reshape_thread_spawn(tool_input)
125
143
  except SpawnNotReshapable as not_reshapable:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.113.1",
3
+ "version": "8.114.1",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,18 @@
1
+ ---
2
+ paths:
3
+ - "**/agents/**"
4
+ - "**/skills/**"
5
+ - "**/hooks/**"
6
+ - "**/workflows/**"
7
+ - "**/docs/agent-spawn-protocol.md"
8
+ ---
9
+
10
+ # Subagent model and effort
11
+
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
+
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.
15
+
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
+
18
+ **Full text:** [guide](../docs/rule-guides/subagent-model-effort.md). Read it when choosing which model gets which work.
@@ -49,6 +49,10 @@ from dev_env_scripts_constants.account_broker_constants import (
49
49
  Meters,
50
50
  Product,
51
51
  ProductAdapter,
52
+ PUBLISHED_USAGE_DIRECTORY_ENV_VAR,
53
+ PUBLISHED_USAGE_FILE_PATTERN,
54
+ PUBLISHED_USAGE_CLOCK_SKEW_SECONDS,
55
+ PUBLISHED_USAGE_MAX_AGE_SECONDS,
52
56
  Reading,
53
57
  Report,
54
58
  REPORT_INDENT_SPACES,
@@ -281,8 +285,64 @@ def refresh_claude_login(account_home: Path) -> bool:
281
285
  return True
282
286
 
283
287
 
288
+ def read_published_meters(account: Account) -> Meters | None:
289
+ """Read one account's meters from the readings a single usage reader publishes.
290
+
291
+ ::
292
+
293
+ CLAUDE_USAGE_READINGS_DIR=/readings, account home .../alpha
294
+ /readings/meters-ALPHA.json {"read_at": "<5 minutes ago>", "accounts": [{"name": "alpha",
295
+ "meters": {"weekly_percent_left": 45.0, ...}}]}
296
+ -> Meters(weekly_percent_left=45.0, ...), and the usage endpoint is not called
297
+
298
+ A reading matches an account when its ``name`` equals the account home's folder name.
299
+ A reading older than ``PUBLISHED_USAGE_MAX_AGE_SECONDS``, or dated more than
300
+ ``PUBLISHED_USAGE_CLOCK_SKEW_SECONDS`` ahead of now, is ignored. The newest match wins.
301
+
302
+ Args:
303
+ account: Account whose meter is read.
304
+
305
+ Returns:
306
+ The published meters, or None when the folder is unset or holds no fresh reading for the account.
307
+ """
308
+ folder_text = os.environ.get(PUBLISHED_USAGE_DIRECTORY_ENV_VAR)
309
+ if not folder_text:
310
+ return None
311
+ home_name = account.home.name.casefold()
312
+ all_matches = [
313
+ (each_read_at, each_row)
314
+ for each_read_at, each_row in _fresh_published_rows(Path(folder_text), datetime.now(timezone.utc))
315
+ if str(each_row.get("name", "")).casefold() == home_name
316
+ ]
317
+ if not all_matches:
318
+ 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
+
322
+
323
+ def _fresh_published_rows(folder: Path, now: datetime) -> Iterator[tuple[datetime, dict[str, object]]]:
324
+ for each_path in sorted(folder.glob(PUBLISHED_USAGE_FILE_PATTERN)):
325
+ yield from _fresh_rows_of(each_path, now)
326
+
327
+
328
+ def _fresh_rows_of(reading_path: Path, now: datetime) -> list[tuple[datetime, dict[str, object]]]:
329
+ try:
330
+ reading = json.loads(reading_path.read_text(encoding="utf-8-sig"))
331
+ except (OSError, ValueError):
332
+ return []
333
+ if not isinstance(reading, dict) or not isinstance(reading.get("accounts"), list):
334
+ return []
335
+ read_at = parse_utc_time(reading.get("read_at"))
336
+ if read_at is None:
337
+ return []
338
+ age_seconds = (now - read_at).total_seconds()
339
+ if not -PUBLISHED_USAGE_CLOCK_SKEW_SECONDS <= age_seconds <= PUBLISHED_USAGE_MAX_AGE_SECONDS:
340
+ return []
341
+ return [(read_at, each_row) for each_row in reading["accounts"] if isinstance(each_row, dict)]
342
+
343
+
284
344
  def read_claude_meters(account: Account) -> Meters | None:
285
- """Probe one Claude account.
345
+ """Read one Claude account's meters, from a published reading when one is fresh.
286
346
 
287
347
  Args:
288
348
  account: Account whose meter is read.
@@ -294,6 +354,9 @@ def read_claude_meters(account: Account) -> Meters | None:
294
354
  WeeklyUtilizationProbeError: The usage meters could not be measured.
295
355
  OSError: The credentials file could not be read.
296
356
  """
357
+ published_meters = read_published_meters(account)
358
+ if published_meters is not None:
359
+ return published_meters
297
360
  usage = probe_account_meters(account.home / CREDENTIALS_FILE_NAME, refresh_claude_login)
298
361
  return Meters(
299
362
  FULL_PERCENT - usage.session_utilization if usage.session_utilization is not None else None,
@@ -61,6 +61,10 @@ METER_READ_DELAY_FACTOR = 2.0
61
61
  METER_READ_MAX_DELAY_SECONDS = 8.0
62
62
  LAST_GOOD_METER_MAX_AGE_SECONDS = 1800.0
63
63
  METER_RATE_LIMIT_COOLDOWN_SECONDS = 300.0
64
+ PUBLISHED_USAGE_DIRECTORY_ENV_VAR = "CLAUDE_USAGE_READINGS_DIR"
65
+ PUBLISHED_USAGE_FILE_PATTERN = "meters-*.json"
66
+ PUBLISHED_USAGE_MAX_AGE_SECONDS = 1800.0
67
+ PUBLISHED_USAGE_CLOCK_SKEW_SECONDS = 300.0
64
68
  WAIT_EXIT_CODE = 3
65
69
  COMMAND_MISSING_EXIT_CODE = 127
66
70
  TIMEOUT_EXIT_CODE = 124
@@ -249,6 +249,90 @@ def test_should_load_codex_roster_without_meter_reads(
249
249
  assert [each_account.name for each_account in support.load_codex_accounts()] == ["one"]
250
250
 
251
251
 
252
+ def _write_published_reading(folder: Path, profile_name: str, read_at: datetime) -> None:
253
+ folder.mkdir(exist_ok=True)
254
+ reading = {
255
+ "read_at": read_at.strftime("%Y-%m-%dT%H:%M:%SZ"),
256
+ "accounts": [
257
+ {
258
+ "name": profile_name,
259
+ "meters": {
260
+ "session_percent_left": None,
261
+ "session_resets_at": None,
262
+ "weekly_percent_left": 45.0,
263
+ "weekly_resets_at": "2026-10-10T06:00:00Z",
264
+ },
265
+ }
266
+ ],
267
+ }
268
+ (folder / f"meters-{profile_name.upper()}.json").write_text(json.dumps(reading), encoding="utf-8")
269
+
270
+
271
+ def test_should_read_claude_meters_from_a_fresh_published_reading_without_a_probe(
272
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
273
+ ) -> None:
274
+ readings_folder = tmp_path / "readings"
275
+ _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc))
276
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
277
+ all_probed_paths: list[object] = []
278
+ monkeypatch.setattr(support, "probe_account_meters", lambda path, _: all_probed_paths.append(path))
279
+
280
+ meters = support.read_claude_meters(Account(Product.CLAUDE, "one", tmp_path / "Alpha"))
281
+
282
+ assert all_probed_paths == []
283
+ assert meters.weekly_percent_left == 45.0
284
+ assert meters.session_percent_left is None
285
+ assert meters.weekly_resets_at == datetime(2026, 10, 10, 6, tzinfo=timezone.utc)
286
+
287
+
288
+ def test_should_use_the_newest_of_two_published_readings_for_one_account(
289
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
290
+ ) -> None:
291
+ readings_folder = tmp_path / "readings"
292
+ _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc) - timedelta(minutes=20))
293
+ 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")
295
+ newer["accounts"][0]["meters"]["weekly_percent_left"] = 12.0
296
+ (readings_folder / "meters-ZULU.json").write_text(json.dumps(newer), encoding="utf-8")
297
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
298
+
299
+ meters = support.read_published_meters(Account(Product.CLAUDE, "one", tmp_path / "alpha"))
300
+
301
+ assert meters.weekly_percent_left == 12.0
302
+
303
+
304
+ def test_should_find_no_published_meters_when_no_readings_folder_is_named(
305
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
306
+ ) -> None:
307
+ readings_folder = tmp_path / "readings"
308
+ _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc))
309
+ account = Account(Product.CLAUDE, "one", tmp_path / "alpha")
310
+ monkeypatch.delenv("CLAUDE_USAGE_READINGS_DIR", raising=False)
311
+ assert support.read_published_meters(account) is None
312
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
313
+ assert support.read_published_meters(account).weekly_percent_left == 45.0
314
+
315
+
316
+ @pytest.mark.parametrize(
317
+ ("profile_name", "age_minutes"),
318
+ [("alpha", 45), ("beta", 1), ("alpha", -60)],
319
+ )
320
+ def test_should_probe_when_the_published_reading_is_old_or_for_another_account(
321
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, profile_name: str, age_minutes: int
322
+ ) -> None:
323
+ readings_folder = tmp_path / "readings"
324
+ _write_published_reading(
325
+ readings_folder, profile_name, datetime.now(timezone.utc) - timedelta(minutes=age_minutes)
326
+ )
327
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
328
+ usage = SimpleNamespace(session_utilization=None, session_resets_at=None, weekly_utilization=30.0, weekly_resets_at=None)
329
+ monkeypatch.setattr(support, "probe_account_meters", lambda _, refresh_login: usage)
330
+
331
+ meters = support.read_claude_meters(Account(Product.CLAUDE, "one", tmp_path / "alpha"))
332
+
333
+ assert meters.weekly_percent_left == 70.0
334
+
335
+
252
336
  def test_should_read_claude_meters_through_injected_probe(
253
337
  monkeypatch: pytest.MonkeyPatch, tmp_path: Path
254
338
  ) -> None: