claude-dev-env 8.113.1 → 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.
@@ -22,7 +22,7 @@ One warm advisor at the strongest tier this session can reach. This session is t
22
22
  ## Bind
23
23
 
24
24
  1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
25
- 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default xhigh) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
25
+ 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at Opus high with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
26
26
  3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path and the spawn tool has a `flags` field, pass `flags: ["--advisor"]` with Astra and record `advisor_flag: passed`. A spawn that skips an offered flag is a failed bind. When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `advisor_flag: unavailable`, and treat it as bound.
27
27
  4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
28
28
  5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
@@ -47,9 +47,9 @@ Mechanical override for scripts:
47
47
 
48
48
  ### Shared effort, any host
49
49
 
50
- Opus and Astra both read `ADVISOR_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`). Opus keeps its xhigh default. Astra uses the policy default, Medium.
50
+ Astra reads `ADVISOR_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`) and uses the policy default, Medium. Opus always runs at high, the advisor exception in [Subagent model and effort](../../docs/rule-guides/subagent-model-effort.md).
51
51
  Pass `--effort <level>` on the Astra helper to set effort for that Astra run.
52
- Pass `--effort <level>` on the Claude CLI bind for Opus. An unset or unrecognized Opus value uses `xhigh`.
52
+ Pass `--effort high` on the Claude CLI bind for Opus, whatever `ADVISOR_EFFORT` holds.
53
53
 
54
54
  ### Astra rung
55
55
 
@@ -26,7 +26,7 @@ Subagents inherit the session's advisor tool, so the executor calls it directly.
26
26
  ## Transport preamble for a third-party host
27
27
 
28
28
  > The orchestrating session owns a standing advisor for this run.
29
- > The advisor chain: Claude Opus, then Astra through the Codex CLI when Opus is out of usage and the Astra flag and its preflight open that rung. Opus uses its xhigh default. Astra uses the policy default, Medium. When neither binds, there is no advisor.
29
+ > The advisor chain: Claude Opus, then Astra through the Codex CLI when Opus is out of usage and the Astra flag and its preflight open that rung. Opus runs at high. Astra uses the policy default, Medium. When neither binds, there is no advisor.
30
30
  > The orchestrating session is your one path to it: send each consult as a report to the session that assigned you, and it relays the advisor's reply.
31
31
 
32
32
  ## Shared core for every host
@@ -25,7 +25,7 @@ When the Astra flag is off, follow the Claude-chain steps below.
25
25
  python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude -p --model <alias> --effort <effort> --output-format json
26
26
  ```
27
27
 
28
- Use `--model opus --effort` with the value of `ADVISOR_EFFORT` (default `xhigh`) on Opus.
28
+ Use `--model opus --effort high` on Opus.
29
29
  User-facing wording follows [`docs/rule-guides/asd-ste100-language.md`](../../../docs/rule-guides/asd-ste100-language.md).
30
30
  Account choice, failover, and the `advisor_blocked` status are in [`cli-chain.md`](cli-chain.md).
31
31
  4. Stop at the first successful bind.
@@ -9,6 +9,7 @@ The consuming skill's session tries Opus first. Spawn with:
9
9
 
10
10
  - `subagent_type: pstack:poteto-agent`. The charter below carries the signal contract.
11
11
  - `model`: the short alias via `resolve_cli_model_id("Opus")` (alias table: [`cli-chain.md`](cli-chain.md)): `opus`. When Opus is out of usage and the Astra rung is open, continue with the Codex helper in [`astra-rung.md`](astra-rung.md) as the Astra fallback.
12
+ - `effort`: `high`.
12
13
  - `name`: a name the session and every consumer will use to reach it (e.g. `team-advisor-agent`).
13
14
  - `run_in_background: true`.
14
15
  - `prompt`: the charter below.
@@ -27,7 +27,7 @@ Use the brief as the agent's `prompt` parameter.
27
27
 
28
28
  ## Step 3: Spawn the agent
29
29
 
30
- Pass the structured prompt from Step 2 to the Agent or Task tool.
30
+ Pass the structured prompt from Step 2 to the Agent or Task tool. Set the model and the effort from [Subagent model and effort](rule-guides/subagent-model-effort.md).
31
31
 
32
32
  ## Why
33
33
 
@@ -24,9 +24,9 @@ Unit tests are welcome as extra evidence. The live run is the proof. A test you
24
24
 
25
25
  For a change to Claude Code behavior, such as a hook, skill, rule, setting, prompt or output style:
26
26
  - Spawn every session through the account broker, with the stream saved to a file:
27
- python ~/.claude/scripts/account_broker.py run --product claude --report <broker-report.json> -- claude -p "<request>" --model claude-opus-5-5 --effort <level> --output-format stream-json --verbose > <stream.jsonl>
27
+ python ~/.claude/scripts/account_broker.py run --product claude --report <broker-report.json> -- claude -p "<request>" --model claude-opus-5-5 --effort medium --output-format stream-json --verbose > <stream.jsonl>
28
28
  - Run each later turn the same way with `--resume <session id>`. The broker resumes a session on the account that started it when that account has room.
29
- - Keep `--model` and `--effort` on every call. Without them the headless run uses claude-sonnet-5-5. Confirm the served model in the result's `modelUsage`.
29
+ - Keep `--model` and `--effort` on every call, with a pair from [Subagent model and effort](subagent-model-effort.md). Without them the headless run uses claude-sonnet-5-5. Confirm the served model in the result's `modelUsage`.
30
30
  - Start the broker from your own shell, with your environment as is. The broker reads the account meters with your session's credentials and starts Claude without your session's variables.
31
31
  - Leave out `--bare` and `claude plugin eval`. Both drop the hooks and settings the user runs with.
32
32
  - Read the broker report for the account it chose. Read the stream for the hook events and their output, `permission_denials`, the final result, and the token usage on the result event.
@@ -0,0 +1,46 @@
1
+ Back to the [rules index](../../rules/index.md).
2
+
3
+ # Subagent model and effort
4
+
5
+ ## In brief
6
+
7
+ Every agent you start runs on an Anthropic model at an allowed effort. Opus runs at medium. Sonnet runs at high. Fable runs at low, medium or high. Only Haiku runs at xhigh or max. Name the model and the effort on every spawn.
8
+
9
+ **When this applies:** Every time one agent starts another on a Claude host. That covers the Agent and Task tools, a thread or session spawn, a Workflow agent, an advisor bind, and a headless `claude -p` run.
10
+
11
+ ## Allowed pairs
12
+
13
+ | Model | Effort |
14
+ | --- | --- |
15
+ | Opus | medium |
16
+ | Sonnet | high |
17
+ | Fable | low, medium or high |
18
+ | Haiku | low, medium, high, xhigh or max |
19
+
20
+ - Use Anthropic models only.
21
+ - xhigh and max are for Haiku only.
22
+ - Any pair outside the table is out.
23
+ - One exception: an advisor that is not the built-in advisor tool runs on Opus at high. The built-in advisor follows the `advisorModel` setting.
24
+
25
+ Codex spawns follow their own policy in [Automatic child model choices](../subagent-model-routing.md).
26
+
27
+ ## Rule
28
+
29
+ - Name both the model and the effort. A spawn that leaves either one out takes the parent's, and an Opus parent at high hands the child Opus high.
30
+ - A fork always takes its parent's model and effort. Fork only from a parent whose own pair is in the table.
31
+ - For `claude -p`, pass the pair as flags, such as `--model claude-opus-5-5 --effort medium` or `--model claude-sonnet-5-5 --effort high`.
32
+ - When a brief, skill, hook, setting or default gives a pair outside the table, use the allowed pair for that model and say so in your report.
33
+
34
+ ## Which model gets which work
35
+
36
+ Opus and Sonnet have one effort each here, so pick the model by the work.
37
+
38
+ - Haiku: finding files, reading logs, running tests, summing up, and sorting or pulling data out of many items. A Haiku mistake is cheap to spot.
39
+ - Sonnet: well-scoped work, such as a bug fix or a feature built to a clear spec.
40
+ - Opus: code edits, judgment calls, and decisions that rest on what other subagents report.
41
+ - Fable: the hardest work, such as a large migration, planning a design, leading many subagents, or a long run with no one watching.
42
+ - Keep the costly model's context lean. Cheaper subagents do the long reading and hand back a short summary.
43
+ - Before you move work to a bigger model, give the agent a way to check its own work, such as a test, a build or a script.
44
+ - A built-in agent such as Explore runs on the session's model unless the spawn names one, so name the model.
45
+
46
+ Source for the work split: [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/).
@@ -4,6 +4,9 @@ The package routes native subagent requests before the child starts. It keeps
4
4
  approved pairs, aliases, replacements, selector exclusions, and the advisor
5
5
  default in one file.
6
6
 
7
+ This page covers Codex children. Claude children follow
8
+ [Subagent model and effort](rule-guides/subagent-model-effort.md).
9
+
7
10
  The source policy is
8
11
  `packages/claude-dev-env/rules/subagent-model-policy.json`.
9
12
 
@@ -1,12 +1,13 @@
1
1
  # Spawn routing
2
2
 
3
- This family reminds the agent to gather context before a spawn, refuses a brief without the user's outcome and a blocker clause, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, selects an allowed subagent model, and lets a Haiku spawn through only when it names the `lean-worker` subagent type, sending other Haiku spawns to a headless slim-profile run.
3
+ This family reminds the agent to gather context before a spawn, refuses a brief without the user's outcome and a blocker clause, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, sets an allowed effort for each Anthropic model, selects an allowed subagent model, and lets a Haiku spawn through only when it names the `lean-worker` subagent type, sending other Haiku spawns to a headless slim-profile run.
4
4
 
5
5
  ## Checks
6
6
 
7
7
  - `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
8
8
  - `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. A spawn that passes gets the orchestrator oversight directive: run each piece through the verified-work flow, with a fresh verifier agent that checks the research, the plan, and the fix, reproduces the issue before it confirms the fix, and leaves the worker's conclusion out of its brief; ask the user before new scope; report as done only what a verifier passed; and watch the agent while it runs. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
9
- - `routing/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
9
+ - `routing/thread_spawn_pace_hook.py` reshapes a thread request to Opus at medium when usage is over pace or unreadable. Under pace, a thread request that names a model gets the effort its model allows.
10
+ - `routing/subagent_effort_route_hook.py` sets an allowed effort on an Agent or Task spawn: Opus medium, Sonnet high, Fable low, medium or high, and Haiku any effort. A spawn with no effort or one outside its model's list gets Opus medium, Sonnet high, Fable high, or Haiku medium. `routing/subagent_effort_route.py` holds the rule for this hook and the pace hook.
10
11
  - `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
11
12
  - `blocking/haiku_spawn_slim_gate.py` denies an Agent, Task, or thread spawn whose `model` names Haiku, except an Agent or Task spawn with `subagent_type` `lean-worker`. The deny reason gives two routes: the `lean-worker` subagent type, and the headless `claude -p` command that loads the slim profile through the account broker.
12
13
 
@@ -15,6 +16,7 @@ This family reminds the agent to gather context before a spawn, refuses a brief
15
16
  - `routing/spawn_readiness_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
16
17
  - `routing/spawn_oversight_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, `mcp__hearthbot__start_thread_session`, and `mcp__hearthbot__start_rc_session|mcp__hearthbot__start_remote_control`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
17
18
  - `routing/thread_spawn_pace_hook.py` runs on `PreToolUse`, matcher `mcp__hearthbot__start_thread_session`, timeout `30` seconds in `hooks.json`.
19
+ - `routing/subagent_effort_route_hook.py` runs on `PreToolUse`, matcher `Agent|Task`, timeout `10` seconds in `hooks.json`, right after the Haiku slim gate.
18
20
  - `routing/subagent_model_routing.mjs` runs on `PreToolUse`, matcher `multi_agent_v1__spawn_agent`, timeout `10` seconds through the quoted Node command in `hooks.json`.
19
21
  - `blocking/haiku_spawn_slim_gate.py` runs on `PreToolUse` with matchers `Agent|Task` and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`.
20
22
 
@@ -26,7 +28,8 @@ Preconditions:
26
28
 
27
29
  - **Spawn readiness.** Input is a spawn after a read, a question, and its answer. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_readiness_hook.py -q`. The adjacent test observes no output for a ready spawn and reminder context for each missing step.
28
30
  - **Spawn oversight.** Input is a route-only brief, a brief with both clauses, and briefs with one clause, on each registered tool, plus a non-spawn call. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_oversight_hook.py packages/claude-dev-env/hooks/routing/test_spawn_brief_text.py -q`. The adjacent test observes a deny for each brief missing a clause, the directive for the passing brief, and no output for the other calls.
29
- - **Thread pace.** Input is a thread spawn with usage over pace. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes updated tool input with the selected model, effort, and advisor line.
31
+ - **Thread pace.** Input is a thread spawn with usage over pace, and thread spawns under pace that name a model. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes Opus at medium over pace, the allowed effort under pace, and no output for an allowed pair.
32
+ - **Subagent effort route.** Input is an Agent spawn on each model family at allowed and outside efforts, a spawn with no model and a transcript, a fork, and stdin that is not an object. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_subagent_effort_route.py packages/claude-dev-env/hooks/routing/test_subagent_effort_route_hook.py -q`. The adjacent test observes updated tool input with the allowed effort and a context line, and no output for an allowed pair, a fork, or an unknown model.
30
33
  - **Haiku slim gate.** Input is a spawn with a Haiku alias or model ID, with `subagent_type` set to `lean-worker` or to another type, and spawns on other models or with no model. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_haiku_spawn_slim_gate.py -q`. The adjacent test observes no output for a Haiku spawn of `lean-worker`, a deny with both routes for each other Haiku spawn, and no output for the rest.
31
34
  - **Model routing.** Input is a `multi_agent_v1__spawn_agent` payload with a model choice. Run `node --test packages/claude-dev-env/hooks/routing/subagent_model_routing.test.mjs`. The adjacent test observes an allow or deny decision with the routed model.
32
35
 
@@ -36,4 +39,6 @@ Preconditions:
36
39
  - The oversight hook fires inside subagents and on read-only helper types too, so every brief at every level carries the outcome and the blocker clause. A `Workflow` call with no script text, such as a saved or resumed run, passes with the directive.
37
40
  - The readiness hook emits `additionalContext` only, so it never blocks. It passes subagent calls, read-only helper types, a non-object tool input, and unreadable transcripts.
38
41
  - The Haiku slim gate reads the spawn's `model` and `subagent_type` fields. A spawn that names no model passes, even when its agent definition or `CLAUDE_CODE_SUBAGENT_MODEL` resolves it to Haiku.
42
+ - The effort route reads the parent model with `last_assistant_model`, from the newest assistant line of the transcript when a spawn names no model. An agent definition that sets its own model is not seen, so the route can pick that family wrong. Name the model on every spawn.
43
+ - The effort route changes only the effort, never the model, and it leaves a model it does not know, such as a Codex model, as it is. A thread spawn that names no model is left as it is.
39
44
  - The model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.
package/hooks/hooks.json CHANGED
@@ -10,6 +10,11 @@
10
10
  "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/haiku_spawn_slim_gate.py",
11
11
  "timeout": 10
12
12
  },
13
+ {
14
+ "type": "command",
15
+ "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/subagent_effort_route_hook.py",
16
+ "timeout": 10
17
+ },
13
18
  {
14
19
  "type": "command",
15
20
  "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
@@ -0,0 +1,45 @@
1
+ """Constants for the subagent effort route.
2
+
3
+ Groups: the allowed effort for each Anthropic model family, the effort a spawn
4
+ gets when it names none or names one outside its family's list, the tool
5
+ input keys, and the hook output text.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ OPUS_MODEL_FAMILY = "opus"
11
+ SONNET_MODEL_FAMILY = "sonnet"
12
+ FABLE_MODEL_FAMILY = "fable"
13
+ HAIKU_MODEL_FAMILY = "haiku"
14
+
15
+ ALL_ALLOWED_EFFORTS_BY_FAMILY: dict[str, tuple[str, ...]] = {
16
+ OPUS_MODEL_FAMILY: ("medium",),
17
+ SONNET_MODEL_FAMILY: ("high",),
18
+ FABLE_MODEL_FAMILY: ("low", "medium", "high"),
19
+ HAIKU_MODEL_FAMILY: ("low", "medium", "high", "xhigh", "max"),
20
+ }
21
+
22
+ ALL_ROUTED_EFFORT_BY_FAMILY: dict[str, str] = {
23
+ OPUS_MODEL_FAMILY: "medium",
24
+ SONNET_MODEL_FAMILY: "high",
25
+ FABLE_MODEL_FAMILY: "high",
26
+ HAIKU_MODEL_FAMILY: "medium",
27
+ }
28
+
29
+ MODEL_INPUT_KEY = "model"
30
+ EFFORT_INPUT_KEY = "effort"
31
+ SUBAGENT_TYPE_INPUT_KEY = "subagent_type"
32
+ FORK_SUBAGENT_TYPE = "fork"
33
+
34
+ TOOL_INPUT_KEY = "tool_input"
35
+ TRANSCRIPT_PATH_KEY = "transcript_path"
36
+ TRANSCRIPT_ENTRY_TYPE_KEY = "type"
37
+ TRANSCRIPT_ASSISTANT_TYPE = "assistant"
38
+ TRANSCRIPT_MESSAGE_KEY = "message"
39
+ TRANSCRIPT_TAIL_BYTES = 2_000_000
40
+ SEEK_FROM_FILE_END = 2
41
+
42
+ ADDITIONAL_CONTEXT_KEY = "additionalContext"
43
+ ROUTED_CONTEXT_TEMPLATE = (
44
+ "Subagent model and effort rule: this {family} spawn now runs at {effort} effort."
45
+ )
@@ -1,7 +1,8 @@
1
1
  """Constants for the thread spawn pace PreToolUse hook.
2
2
 
3
3
  Groups: the usage-pace script it runs, the reshape values for an over-pace
4
- spawn, and the hook output keys and messages.
4
+ spawn, and the hook output keys and messages. Opus runs at medium only,
5
+ per the Subagent model and effort rule.
5
6
  """
6
7
 
7
8
  from __future__ import annotations
@@ -12,7 +13,7 @@ USAGE_PACE_TIMEOUT_SECONDS = 15
12
13
 
13
14
  TOOL_INPUT_KEY = "tool_input"
14
15
  THREAD_MODEL_WHEN_OVER_PACE = "claude-opus-5-5"
15
- THREAD_EFFORT_WHEN_OVER_PACE = "low"
16
+ THREAD_EFFORT_WHEN_OVER_PACE = "medium"
16
17
  MODEL_INPUT_KEY = "model"
17
18
  EFFORT_INPUT_KEY = "effort"
18
19
 
@@ -22,7 +23,7 @@ ADDITIONAL_CONTEXT_KEY = "additionalContext"
22
23
  NOT_AN_OBJECT_REASON = "start_thread_session input is not a JSON object"
23
24
  RESHAPE_CONTEXT_PREFIX = (
24
25
  "Usage over pace or unreadable: this thread spawn now runs on "
25
- "claude-opus-5-5 at low effort. Pace verdict: "
26
+ "claude-opus-5-5 at medium effort. Pace verdict: "
26
27
  )
27
28
  PACE_VERDICT_CONTEXT_MAXIMUM_CHARACTERS = 600
28
29
  LAUNCH_FAILURE_ERROR_TEMPLATE = "usage pace did not finish: {failure_type}"
@@ -0,0 +1,97 @@
1
+ """Give a spawn an effort its Anthropic model family allows.
2
+
3
+ ::
4
+
5
+ {"model": "opus", "effort": "xhigh"} -> effort "medium"
6
+ {"model": "claude-sonnet-5-5"} -> effort "high"
7
+ {"model": "fable", "effort": "max"} -> effort "high"
8
+ {"model": "haiku", "effort": "max"} -> unchanged
9
+ {"subagent_type": "fork"} -> unchanged
10
+ {} with the parent on Opus -> effort "medium"
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import sys
16
+ from pathlib import Path
17
+
18
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
19
+ if hooks_root_directory not in sys.path:
20
+ sys.path.insert(0, hooks_root_directory)
21
+
22
+ from hooks_constants.subagent_effort_route_constants import (
23
+ ALL_ALLOWED_EFFORTS_BY_FAMILY,
24
+ ALL_ROUTED_EFFORT_BY_FAMILY,
25
+ EFFORT_INPUT_KEY,
26
+ FORK_SUBAGENT_TYPE,
27
+ MODEL_INPUT_KEY,
28
+ SUBAGENT_TYPE_INPUT_KEY,
29
+ )
30
+
31
+
32
+ def model_family(model: object) -> str | None:
33
+ """Return the Anthropic family a model name or alias belongs to.
34
+
35
+ ::
36
+
37
+ "opus" -> "opus" "claude-fable-5-2" -> "fable"
38
+ "inherit" -> None None -> None
39
+
40
+ Args:
41
+ model: A model alias or full model id, or anything else.
42
+ """
43
+ if not isinstance(model, str):
44
+ return None
45
+ lowered_model = model.lower()
46
+ for each_family in ALL_ALLOWED_EFFORTS_BY_FAMILY:
47
+ if each_family in lowered_model:
48
+ return each_family
49
+ return None
50
+
51
+
52
+ def routed_effort(family: str, effort: object) -> str:
53
+ """Return the effort a spawn of this family runs at.
54
+
55
+ ::
56
+
57
+ ("opus", "xhigh") -> "medium" ("fable", "low") -> "low"
58
+ ("sonnet", None) -> "high"
59
+
60
+ Args:
61
+ family: An Anthropic model family.
62
+ effort: The effort the spawn named, or None.
63
+ """
64
+ if effort in ALL_ALLOWED_EFFORTS_BY_FAMILY[family]:
65
+ return str(effort)
66
+ return ALL_ROUTED_EFFORT_BY_FAMILY[family]
67
+
68
+
69
+ def route_spawn_input(
70
+ tool_input: object, parent_model: str | None
71
+ ) -> tuple[dict[str, object], str, str] | None:
72
+ """Return the spawn input with an allowed effort, or None to leave it.
73
+
74
+ A fork keeps its parent's model and effort. A spawn whose model resolves
75
+ to no Anthropic family, from its own field or from the parent's model,
76
+ is left as it is.
77
+
78
+ Args:
79
+ tool_input: The spawn tool's input.
80
+ parent_model: The model of the session that spawns, when known.
81
+
82
+ Returns:
83
+ The updated input, the family, and the effort, or None when the
84
+ input already holds an allowed effort or cannot be routed.
85
+ """
86
+ if not isinstance(tool_input, dict):
87
+ return None
88
+ if tool_input.get(SUBAGENT_TYPE_INPUT_KEY) == FORK_SUBAGENT_TYPE:
89
+ return None
90
+ family = model_family(tool_input.get(MODEL_INPUT_KEY)) or model_family(parent_model)
91
+ if family is None:
92
+ return None
93
+ current_effort = tool_input.get(EFFORT_INPUT_KEY)
94
+ allowed_effort = routed_effort(family, current_effort)
95
+ if allowed_effort == current_effort:
96
+ return None
97
+ return {**tool_input, EFFORT_INPUT_KEY: allowed_effort}, family, allowed_effort
@@ -0,0 +1,139 @@
1
+ #!/usr/bin/env python3
2
+ """PreToolUse hook: give an Agent or Task spawn an allowed effort.
3
+
4
+ Registered on ``Agent|Task``. It applies the Subagent model and effort rule:
5
+ Opus runs at medium, Sonnet at high, Fable at low to high, and Haiku at any
6
+ effort. A spawn that names no model takes the family of the session's last
7
+ assistant model from the transcript.
8
+
9
+ ::
10
+
11
+ model "opus", effort "xhigh" -> updatedInput with effort "medium"
12
+ model "sonnet", no effort -> updatedInput with effort "high"
13
+ model "haiku", effort "max" -> no output
14
+ subagent_type "fork" -> no output
15
+ no model, unreadable transcript -> no output
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import json
21
+ import sys
22
+ from pathlib import Path
23
+
24
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
25
+ if hooks_root_directory not in sys.path:
26
+ sys.path.insert(0, hooks_root_directory)
27
+ routing_directory = str(Path(__file__).resolve().parent)
28
+ if routing_directory not in sys.path:
29
+ sys.path.insert(0, routing_directory)
30
+
31
+ from hooks_constants.bash_pre_tool_use_dispatcher_constants import HOOK_EVENT_NAME
32
+ from hooks_constants.hook_specific_output_keys import (
33
+ HOOK_EVENT_NAME_KEY,
34
+ HOOK_SPECIFIC_OUTPUT_KEY,
35
+ UPDATED_INPUT_KEY,
36
+ )
37
+ from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
38
+ from hooks_constants.subagent_effort_route_constants import (
39
+ ADDITIONAL_CONTEXT_KEY,
40
+ MODEL_INPUT_KEY,
41
+ ROUTED_CONTEXT_TEMPLATE,
42
+ TOOL_INPUT_KEY,
43
+ TRANSCRIPT_ASSISTANT_TYPE,
44
+ TRANSCRIPT_ENTRY_TYPE_KEY,
45
+ TRANSCRIPT_MESSAGE_KEY,
46
+ TRANSCRIPT_PATH_KEY,
47
+ SEEK_FROM_FILE_END,
48
+ TRANSCRIPT_TAIL_BYTES,
49
+ )
50
+ from subagent_effort_route import route_spawn_input
51
+
52
+
53
+ def last_assistant_model(transcript_path: object) -> str | None:
54
+ """Return the model of the transcript's last assistant entry.
55
+
56
+ Args:
57
+ transcript_path: The payload's ``transcript_path``.
58
+
59
+ Returns:
60
+ The model id, or None when the file is missing, unreadable, or holds
61
+ no assistant entry with a model.
62
+ """
63
+ if not isinstance(transcript_path, str) or not transcript_path:
64
+ return None
65
+ try:
66
+ with open(transcript_path, "rb") as transcript_file:
67
+ transcript_file.seek(0, SEEK_FROM_FILE_END)
68
+ file_size = transcript_file.tell()
69
+ transcript_file.seek(max(0, file_size - TRANSCRIPT_TAIL_BYTES))
70
+ tail_text = transcript_file.read().decode("utf-8", errors="replace")
71
+ except OSError:
72
+ return None
73
+ return newest_assistant_model(tail_text)
74
+
75
+
76
+ def newest_assistant_model(transcript_text: str) -> str | None:
77
+ """Return the model of the newest assistant line in transcript text.
78
+
79
+ Args:
80
+ transcript_text: JSONL transcript lines, oldest first.
81
+
82
+ Returns:
83
+ The model id, or None when no assistant line names a model.
84
+ """
85
+ for each_line in reversed(transcript_text.splitlines()):
86
+ try:
87
+ entry = json.loads(each_line)
88
+ except json.JSONDecodeError:
89
+ continue
90
+ if not isinstance(entry, dict) or entry.get(TRANSCRIPT_ENTRY_TYPE_KEY) != TRANSCRIPT_ASSISTANT_TYPE:
91
+ continue
92
+ message = entry.get(TRANSCRIPT_MESSAGE_KEY)
93
+ if isinstance(message, dict) and isinstance(message.get(MODEL_INPUT_KEY), str):
94
+ return message[MODEL_INPUT_KEY]
95
+ return None
96
+
97
+
98
+ def decide_hook_output(all_hook_payload: dict[str, object] | None) -> dict[str, object] | None:
99
+ """Choose the hook output for one spawn payload.
100
+
101
+ Args:
102
+ all_hook_payload: The PreToolUse payload, or None when stdin held no object.
103
+
104
+ Returns:
105
+ None to pass the call through unchanged, else the hook JSON output.
106
+ """
107
+ if all_hook_payload is None:
108
+ return None
109
+ routed = route_spawn_input(
110
+ all_hook_payload.get(TOOL_INPUT_KEY),
111
+ last_assistant_model(all_hook_payload.get(TRANSCRIPT_PATH_KEY)),
112
+ )
113
+ if routed is None:
114
+ return None
115
+ routed_input, family, effort = routed
116
+ return {
117
+ HOOK_SPECIFIC_OUTPUT_KEY: {
118
+ HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME,
119
+ UPDATED_INPUT_KEY: routed_input,
120
+ ADDITIONAL_CONTEXT_KEY: ROUTED_CONTEXT_TEMPLATE.format(family=family, effort=effort),
121
+ }
122
+ }
123
+
124
+
125
+ def main() -> int:
126
+ """Read the PreToolUse payload and print the routing decision.
127
+
128
+ Returns:
129
+ 0 in every case.
130
+ """
131
+ hook_output = decide_hook_output(read_hook_input_dictionary_from_stdin())
132
+ if hook_output is not None:
133
+ sys.stdout.write(json.dumps(hook_output))
134
+ sys.stdout.flush()
135
+ return 0
136
+
137
+
138
+ if __name__ == "__main__":
139
+ sys.exit(main())
@@ -0,0 +1,74 @@
1
+ import pytest
2
+
3
+ from subagent_effort_route import model_family, route_spawn_input, routed_effort
4
+
5
+
6
+ @pytest.mark.parametrize(
7
+ ("model", "family"),
8
+ [
9
+ ("opus", "opus"),
10
+ ("claude-opus-5-5", "opus"),
11
+ ("Sonnet", "sonnet"),
12
+ ("claude-fable-5-2", "fable"),
13
+ ("claude-haiku-5-5", "haiku"),
14
+ ("inherit", None),
15
+ ("gpt-5", None),
16
+ (None, None),
17
+ (7, None),
18
+ ],
19
+ )
20
+ def test_should_name_the_family_of_a_model(model: object, family: str | None) -> None:
21
+ assert model_family(model) == family
22
+
23
+
24
+ @pytest.mark.parametrize(
25
+ ("family", "effort", "expected"),
26
+ [
27
+ ("opus", "xhigh", "medium"),
28
+ ("opus", "low", "medium"),
29
+ ("opus", None, "medium"),
30
+ ("sonnet", "medium", "high"),
31
+ ("sonnet", None, "high"),
32
+ ("fable", "low", "low"),
33
+ ("fable", "medium", "medium"),
34
+ ("fable", "max", "high"),
35
+ ("haiku", "max", "max"),
36
+ ("haiku", None, "medium"),
37
+ ],
38
+ )
39
+ def test_should_pick_an_allowed_effort(family: str, effort: object, expected: str) -> None:
40
+ assert routed_effort(family, effort) == expected
41
+
42
+
43
+ def test_should_set_the_allowed_effort_and_keep_every_other_key() -> None:
44
+ spawn_input = {"model": "opus", "effort": "high", "prompt": "Do X."}
45
+ assert route_spawn_input(spawn_input, None) == (
46
+ {"model": "opus", "effort": "medium", "prompt": "Do X."},
47
+ "opus",
48
+ "medium",
49
+ )
50
+
51
+
52
+ def test_should_use_the_parent_family_when_the_spawn_names_no_model() -> None:
53
+ routed = route_spawn_input({"prompt": "Do X."}, "claude-sonnet-5-5")
54
+ assert routed == ({"prompt": "Do X.", "effort": "high"}, "sonnet", "high")
55
+
56
+
57
+ def test_should_prefer_the_spawn_model_over_the_parent_model() -> None:
58
+ routed = route_spawn_input({"model": "haiku"}, "claude-opus-5-5")
59
+ assert routed == ({"model": "haiku", "effort": "medium"}, "haiku", "medium")
60
+
61
+
62
+ @pytest.mark.parametrize(
63
+ ("tool_input", "parent_model"),
64
+ [
65
+ ({"model": "opus", "effort": "medium"}, None),
66
+ ({"model": "haiku", "effort": "xhigh"}, None),
67
+ ({"subagent_type": "fork", "effort": "max"}, "claude-opus-5-5"),
68
+ ({"prompt": "Do X."}, None),
69
+ ({"model": "gpt-5", "effort": "max"}, None),
70
+ (["not", "an", "object"], "claude-opus-5-5"),
71
+ ],
72
+ )
73
+ def test_should_leave_the_spawn_as_it_is(tool_input: object, parent_model: str | None) -> None:
74
+ assert route_spawn_input(tool_input, parent_model) is None
@@ -0,0 +1,85 @@
1
+ import json
2
+ import subprocess
3
+ import sys
4
+ from pathlib import Path
5
+
6
+ HOOK_SCRIPT = Path(__file__).resolve().parent / "subagent_effort_route_hook.py"
7
+
8
+
9
+ def _write_transcript(tmp_path: Path, parent_model: str) -> Path:
10
+ transcript_path = tmp_path / "transcript.jsonl"
11
+ all_entries = [
12
+ {"type": "user", "message": {"role": "user", "content": "hi"}},
13
+ {"type": "assistant", "message": {"model": "claude-fable-5-2", "content": []}},
14
+ {"type": "assistant", "message": {"model": parent_model, "content": []}},
15
+ {"type": "user", "message": {"role": "user", "content": "tool result"}},
16
+ ]
17
+ transcript_path.write_text(
18
+ "\n".join(json.dumps(each_entry) for each_entry in all_entries) + "\nnot json\n",
19
+ encoding="utf-8",
20
+ )
21
+ return transcript_path
22
+
23
+
24
+ def _run_hook(tool_input: object, transcript_path: Path | None = None) -> str:
25
+ hook_payload: dict[str, object] = {
26
+ "hook_event_name": "PreToolUse",
27
+ "tool_name": "Agent",
28
+ "tool_input": tool_input,
29
+ }
30
+ if transcript_path is not None:
31
+ hook_payload["transcript_path"] = str(transcript_path)
32
+ completed = subprocess.run(
33
+ [sys.executable, str(HOOK_SCRIPT)],
34
+ input=json.dumps(hook_payload),
35
+ capture_output=True,
36
+ text=True,
37
+ check=True,
38
+ )
39
+ return completed.stdout
40
+
41
+
42
+ def _hook_specific_output(stdout: str) -> dict[str, object]:
43
+ return json.loads(stdout)["hookSpecificOutput"]
44
+
45
+
46
+ def test_should_move_an_opus_spawn_at_xhigh_to_medium() -> None:
47
+ spawn_input = {"subagent_type": "general-purpose", "model": "opus", "effort": "xhigh", "prompt": "Do X."}
48
+ decision = _hook_specific_output(_run_hook(spawn_input))
49
+ assert decision["hookEventName"] == "PreToolUse"
50
+ assert decision["updatedInput"] == {**spawn_input, "effort": "medium"}
51
+ assert decision["additionalContext"] == (
52
+ "Subagent model and effort rule: this opus spawn now runs at medium effort."
53
+ )
54
+ assert "permissionDecision" not in decision
55
+
56
+
57
+ def test_should_give_a_sonnet_spawn_with_no_effort_high() -> None:
58
+ decision = _hook_specific_output(_run_hook({"model": "sonnet", "prompt": "Do X."}))
59
+ assert decision["updatedInput"]["effort"] == "high"
60
+
61
+
62
+ def test_should_use_the_last_parent_model_when_the_spawn_names_none(tmp_path: Path) -> None:
63
+ decision = _hook_specific_output(
64
+ _run_hook({"subagent_type": "Explore", "prompt": "Find X."}, _write_transcript(tmp_path, "claude-opus-5-5"))
65
+ )
66
+ assert decision["updatedInput"] == {"subagent_type": "Explore", "prompt": "Find X.", "effort": "medium"}
67
+
68
+
69
+ def test_should_print_nothing_for_an_allowed_pair() -> None:
70
+ assert _run_hook({"model": "haiku", "effort": "max", "prompt": "Do X."}) == ""
71
+
72
+
73
+ def test_should_print_nothing_for_a_fork(tmp_path: Path) -> None:
74
+ assert _run_hook({"subagent_type": "fork", "prompt": "Do X."}, _write_transcript(tmp_path, "claude-opus-5-5")) == ""
75
+
76
+
77
+ def test_should_print_nothing_when_no_model_is_known(tmp_path: Path) -> None:
78
+ assert _run_hook({"prompt": "Do X."}, tmp_path / "absent.jsonl") == ""
79
+
80
+
81
+ def test_should_print_nothing_for_stdin_that_is_not_an_object() -> None:
82
+ completed = subprocess.run(
83
+ [sys.executable, str(HOOK_SCRIPT)], input="[1, 2]", capture_output=True, text=True, check=True
84
+ )
85
+ assert completed.stdout == ""
@@ -55,7 +55,7 @@ def _assert_reshaped(stdout: str) -> None:
55
55
  assert decision["updatedInput"] == {
56
56
  **SPAWN_INPUT,
57
57
  "model": "claude-opus-5-5",
58
- "effort": "low",
58
+ "effort": "medium",
59
59
  }
60
60
 
61
61
 
@@ -74,6 +74,43 @@ def test_should_pass_the_spawn_through_unchanged_when_usage_is_under_pace(
74
74
  )
75
75
 
76
76
 
77
+ @pytest.mark.parametrize(
78
+ ("spawn_pair", "routed_effort"),
79
+ [
80
+ ({"model": "claude-opus-5-5", "effort": "xhigh"}, "medium"),
81
+ ({"model": "claude-sonnet-5-5"}, "high"),
82
+ ({"model": "claude-fable-5-2", "effort": "max"}, "high"),
83
+ ],
84
+ )
85
+ def test_should_route_an_effort_outside_the_rule_when_usage_is_under_pace(
86
+ tmp_path: Path, spawn_pair: dict[str, str], routed_effort: str
87
+ ) -> None:
88
+ spawn_input = {**SPAWN_INPUT, **spawn_pair}
89
+ decision = _hook_specific_output(
90
+ _run_hook(_write_pace_stub(tmp_path, 1, {"over_pace": False}), spawn_input)
91
+ )
92
+ assert decision["updatedInput"] == {**spawn_input, "effort": routed_effort}
93
+ assert "permissionDecision" not in decision
94
+
95
+
96
+ @pytest.mark.parametrize(
97
+ "spawn_pair",
98
+ [
99
+ {"model": "claude-opus-5-5", "effort": "medium"},
100
+ {"model": "claude-fable-5-2", "effort": "low"},
101
+ {"model": "claude-haiku-5-5", "effort": "max"},
102
+ ],
103
+ )
104
+ def test_should_pass_an_allowed_pair_through_when_usage_is_under_pace(
105
+ tmp_path: Path, spawn_pair: dict[str, str]
106
+ ) -> None:
107
+ spawn_input = {**SPAWN_INPUT, **spawn_pair}
108
+ assert (
109
+ _run_hook(_write_pace_stub(tmp_path, 1, {"over_pace": False}), spawn_input)
110
+ == ""
111
+ )
112
+
113
+
77
114
  def test_should_reshape_the_spawn_when_usage_is_unreadable(tmp_path: Path) -> None:
78
115
  _assert_reshaped(
79
116
  _run_hook(
@@ -101,7 +138,7 @@ def test_should_quote_a_capped_pace_verdict_in_the_reshape_context(tmp_path: Pat
101
138
  )
102
139
  context_prefix = (
103
140
  "Usage over pace or unreadable: this thread spawn now runs on "
104
- "claude-opus-5-5 at low effort. Pace verdict: "
141
+ "claude-opus-5-5 at medium effort. Pace verdict: "
105
142
  )
106
143
  assert decision["additionalContext"] == context_prefix + json.dumps(long_verdict)[:600]
107
144
 
@@ -6,10 +6,11 @@ beside it, or the script ``COORDINATOR_USAGE_PACE_SCRIPT`` names.
6
6
 
7
7
  ::
8
8
 
9
- usage under pace (exit 1) -> no output; the call runs unchanged
10
- over pace (exit 0) or unreadable -> updatedInput:
11
- model "claude-opus-5-5", effort "low"
12
- input that cannot be reshaped -> deny with a one-line reason
9
+ under pace, allowed pair or no model -> no output; the call runs unchanged
10
+ under pace, effort outside the rule -> updatedInput with the allowed effort
11
+ over pace (exit 0) or unreadable -> updatedInput:
12
+ model "claude-opus-5-5", effort "medium"
13
+ input that cannot be reshaped -> deny with a one-line reason
13
14
 
14
15
  ``updatedInput`` is the whole tool input the call runs with, so it carries
15
16
  every original key.
@@ -26,6 +27,9 @@ from pathlib import Path
26
27
  hooks_root_directory = str(Path(__file__).resolve().parent.parent)
27
28
  if hooks_root_directory not in sys.path:
28
29
  sys.path.insert(0, hooks_root_directory)
30
+ routing_directory = str(Path(__file__).resolve().parent)
31
+ if routing_directory not in sys.path:
32
+ sys.path.insert(0, routing_directory)
29
33
 
30
34
  from hooks_constants.bash_pre_tool_use_dispatcher_constants import HOOK_EVENT_NAME
31
35
  from hooks_constants.hook_specific_output_keys import (
@@ -52,12 +56,14 @@ from hooks_constants.thread_spawn_pace_hook_constants import (
52
56
  USAGE_PACE_SCRIPT_FILE_NAME,
53
57
  USAGE_PACE_TIMEOUT_SECONDS,
54
58
  )
59
+ from hooks_constants.subagent_effort_route_constants import ROUTED_CONTEXT_TEMPLATE
55
60
  from hooks_constants.usage_pace_constants import (
56
61
  EXIT_CODE_UNDER_PACE,
57
62
  EXIT_CODE_UNREADABLE,
58
63
  RESULT_KEY_ERROR,
59
64
  RESULT_KEY_OVER_PACE,
60
65
  )
66
+ from subagent_effort_route import route_spawn_input
61
67
 
62
68
 
63
69
  class SpawnNotReshapable(Exception):
@@ -65,13 +71,13 @@ class SpawnNotReshapable(Exception):
65
71
 
66
72
 
67
73
  def reshape_thread_spawn(tool_input: object) -> dict[str, object]:
68
- """Move a thread spawn to Opus 5.5 at low effort.
74
+ """Move a thread spawn to Opus 5.5 at medium effort.
69
75
 
70
76
  ::
71
77
 
72
78
  {"title": "t", "instructions": "Do X."}
73
79
  -> {"title": "t", "instructions": "Do X.",
74
- "model": "claude-opus-5-5", "effort": "low"}
80
+ "model": "claude-opus-5-5", "effort": "medium"}
75
81
 
76
82
  Args:
77
83
  tool_input: The ``tool_input`` object of the start_thread_session call.
@@ -112,14 +118,26 @@ def decide_hook_output(
112
118
  tool_input: The ``tool_input`` of the PreToolUse payload, or None when
113
119
  stdin held no JSON object.
114
120
  pace_exit_code: The usage-pace exit code; anything but under pace
115
- counts as over pace.
121
+ counts as over pace. Under pace, a spawn that names a model gets
122
+ the effort the Subagent model and effort rule allows.
116
123
  pace_verdict_text: The usage-pace stdout, quoted into the context.
117
124
 
118
125
  Returns:
119
126
  None to pass the call through unchanged, else the hook JSON output.
120
127
  """
121
128
  if pace_exit_code == EXIT_CODE_UNDER_PACE:
122
- return None
129
+ routed = route_spawn_input(tool_input, None)
130
+ if routed is None:
131
+ return None
132
+ routed_input, family, effort = routed
133
+ return _hook_output(
134
+ {
135
+ UPDATED_INPUT_KEY: routed_input,
136
+ ADDITIONAL_CONTEXT_KEY: ROUTED_CONTEXT_TEMPLATE.format(
137
+ family=family, effort=effort
138
+ ),
139
+ }
140
+ )
123
141
  try:
124
142
  reshaped_input = reshape_thread_spawn(tool_input)
125
143
  except SpawnNotReshapable as not_reshapable:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.113.1",
3
+ "version": "8.114.0",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,18 @@
1
+ ---
2
+ paths:
3
+ - "**/agents/**"
4
+ - "**/skills/**"
5
+ - "**/hooks/**"
6
+ - "**/workflows/**"
7
+ - "**/docs/agent-spawn-protocol.md"
8
+ ---
9
+
10
+ # Subagent model and effort
11
+
12
+ **When:** Write or change anything that starts another agent, such as an agent definition, a skill, a hook, a workflow or a `claude -p` command.
13
+
14
+ Name both the model and the effort on every spawn. Opus runs at medium, Sonnet at high, Fable at low, medium or high, and only Haiku runs at xhigh or max. Use Anthropic models only. An advisor that is not the built-in advisor tool runs on Opus at high.
15
+
16
+ **Enforcement:** `hooks/routing/subagent_effort_route_hook.py` sets the allowed effort on Agent and Task spawns, and `hooks/routing/thread_spawn_pace_hook.py` does it for thread spawns that name a model.
17
+
18
+ **Full text:** [guide](../docs/rule-guides/subagent-model-effort.md). Read it when choosing which model gets which work.