claude-dev-env 8.113.0 → 8.114.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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/features/spawn-routing.md +8 -3
- package/hooks/hooks.json +5 -0
- package/hooks/hooks_constants/background_silence_prompt_constants.py +2 -0
- package/hooks/hooks_constants/subagent_effort_route_constants.py +45 -0
- package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py +4 -3
- 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/hooks/session/background_silence_prompt.py +4 -0
- package/hooks/session/test_background_silence_prompt.py +7 -0
- package/package.json +1 -1
- package/rules/subagent-model-effort.md +18 -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
|
|
|
@@ -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",
|
|
@@ -7,6 +7,8 @@ import re
|
|
|
7
7
|
ORIGIN_KEY = "origin"
|
|
8
8
|
ORIGIN_KIND_KEY = "kind"
|
|
9
9
|
HUMAN_ORIGIN_KIND = "human"
|
|
10
|
+
RECORD_TYPE_KEY = "type"
|
|
11
|
+
USER_RECORD_TYPE = "user"
|
|
10
12
|
TASK_NOTIFICATION_MARKER = "<task-notification"
|
|
11
13
|
BACKGROUND_EVENT_PATTERN = re.compile(
|
|
12
14
|
r"(?:\A\s*|<system-reminder>\s*)" + re.escape("[SYSTEM NOTIFICATION - NOT USER INPUT]")
|
|
@@ -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
|
+
)
|
|
@@ -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}"
|
|
@@ -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:
|
|
@@ -44,9 +44,11 @@ from hooks_constants.background_silence_prompt_constants import (
|
|
|
44
44
|
ORIGIN_KEY,
|
|
45
45
|
ORIGIN_KIND_KEY,
|
|
46
46
|
QUOTED_LINE_PATTERN,
|
|
47
|
+
RECORD_TYPE_KEY,
|
|
47
48
|
SILENCE_NOTE_TEMPLATE,
|
|
48
49
|
SILENCE_NOTE_WITHOUT_EXCEPTION,
|
|
49
50
|
TASK_NOTIFICATION_MARKER,
|
|
51
|
+
USER_RECORD_TYPE,
|
|
50
52
|
)
|
|
51
53
|
from hooks_constants.hook_specific_output_keys import (
|
|
52
54
|
HOOK_EVENT_NAME_KEY,
|
|
@@ -81,6 +83,8 @@ def _is_user_typed_text(prompt_text: str) -> bool:
|
|
|
81
83
|
|
|
82
84
|
|
|
83
85
|
def _user_words(all_record_fields: dict[str, object]) -> str | None:
|
|
86
|
+
if all_record_fields.get(RECORD_TYPE_KEY) != USER_RECORD_TYPE:
|
|
87
|
+
return None
|
|
84
88
|
origin = all_record_fields.get(ORIGIN_KEY)
|
|
85
89
|
if isinstance(origin, dict) and origin.get(ORIGIN_KIND_KEY) not in (None, HUMAN_ORIGIN_KIND):
|
|
86
90
|
return None
|
|
@@ -171,6 +171,13 @@ def test_should_keep_silence_through_text_that_is_not_the_user_lifting_it(
|
|
|
171
171
|
notification_entry("<task-notification>stay silent unless blocked</task-notification>"),
|
|
172
172
|
typed_entry('<agent-message from="a1">stay silent unless blocked</agent-message>'),
|
|
173
173
|
typed_entry("> stay silent unless blocked\n\nwhy is this so loud?"),
|
|
174
|
+
{
|
|
175
|
+
"type": "api-request-blob",
|
|
176
|
+
"message": {
|
|
177
|
+
"role": "user",
|
|
178
|
+
"content": [{"type": "text", "text": "Summary: stay silent unless blocked"}],
|
|
179
|
+
},
|
|
180
|
+
},
|
|
174
181
|
],
|
|
175
182
|
)
|
|
176
183
|
def test_should_not_set_silence_from_text_that_is_not_the_users_own(
|
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.
|