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.
- package/.agents/skills/team-advisor/SKILL.md +1 -1
- package/_shared/advisor/advisor-protocol.md +2 -2
- package/_shared/advisor/reference/advisor-block.md +1 -1
- package/_shared/advisor/reference/third-party-bind.md +1 -1
- package/_shared/advisor/reference/warm-up.md +1 -0
- package/docs/agent-spawn-protocol.md +1 -1
- package/docs/rule-guides/proof-before-pull-request.md +2 -2
- package/docs/rule-guides/subagent-model-effort.md +46 -0
- package/docs/subagent-model-routing.md +3 -0
- package/hooks/blocking/test_verify_before_acting.py +52 -2
- package/hooks/blocking/verify_before_acting.py +20 -2
- package/hooks/features/conduct-gates.md +3 -3
- package/hooks/features/spawn-routing.md +8 -3
- package/hooks/hooks.json +5 -0
- package/hooks/hooks_constants/subagent_effort_route_constants.py +45 -0
- package/hooks/hooks_constants/test_verify_before_acting_constants.py +5 -0
- package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py +4 -3
- package/hooks/hooks_constants/verify_before_acting_constants.py +7 -0
- package/hooks/routing/subagent_effort_route.py +97 -0
- package/hooks/routing/subagent_effort_route_hook.py +139 -0
- package/hooks/routing/test_subagent_effort_route.py +74 -0
- package/hooks/routing/test_subagent_effort_route_hook.py +85 -0
- package/hooks/routing/test_thread_spawn_pace_hook.py +39 -2
- package/hooks/routing/thread_spawn_pace_hook.py +26 -8
- package/package.json +1 -1
- package/rules/subagent-model-effort.md +18 -0
- package/scripts/account_broker_support.py +64 -1
- package/scripts/dev_env_scripts_constants/account_broker_constants.py +4 -0
- 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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 = "
|
|
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
|
|
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": "
|
|
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
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
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": "
|
|
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
|
-
|
|
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
|
@@ -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
|
-
"""
|
|
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:
|