claude-dev-env 8.114.2 → 8.114.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/.agents/agents/test_agent_frontmatter.py +6 -4
  2. package/.agents/skills/build-eval/SKILL.md +1 -0
  3. package/.agents/skills/e-code-review/SKILL.md +2 -0
  4. package/.agents/skills/e-code-review/reference/max.md +1 -1
  5. package/.agents/skills/efficient-review/SKILL.md +2 -0
  6. package/.agents/skills/orchestrator/SKILL.md +2 -1
  7. package/.agents/skills/orchestrator/reference/host-detect.md +3 -3
  8. package/.agents/skills/orchestrator/reference/oversee-delegated-work.md +1 -0
  9. package/.agents/skills/orchestrator/reference/recovery.md +1 -0
  10. package/.agents/skills/second-account-workers/SKILL.md +8 -0
  11. package/.agents/skills/team-advisor/reference/advisor-docs-review.md +6 -0
  12. package/_shared/advisor/reference/cli-chain.md +2 -0
  13. package/commands/sr-loop.md +4 -2
  14. package/docs/agent-spawn-protocol.md +1 -1
  15. package/docs/model-choice/README.md +12 -0
  16. package/docs/model-choice/api-compatibility.md +21 -0
  17. package/docs/model-choice/context-and-caching.md +46 -0
  18. package/docs/model-choice/escalation.md +57 -0
  19. package/docs/model-choice/measuring.md +43 -0
  20. package/docs/model-choice/subagents-and-fan-out.md +55 -0
  21. package/docs/model-choice/which-model.md +62 -0
  22. package/docs/references/advisor-tool.md +6 -2
  23. package/docs/rule-guides/long-horizon-autonomy.md +1 -1
  24. package/docs/rule-guides/subagent-model-effort.md +2 -2
  25. package/hooks/features/session-context.md +1 -1
  26. package/hooks/features/spawn-routing.md +1 -1
  27. package/package.json +1 -1
  28. package/rules/subagent-model-effort.md +1 -1
  29. package/scripts/claude_account_worker.py +40 -2
  30. package/scripts/dev_env_scripts_constants/claude_account_worker_constants.py +4 -0
  31. package/scripts/test_claude_account_worker.py +62 -1
@@ -82,6 +82,7 @@ ACCEPTED_FRONTMATTER_KEYS = frozenset({"name", "description", "tools", "color"})
82
82
  CODE_QUALITY_AGENT_FILENAME = "code-quality-agent.md"
83
83
  CODE_QUALITY_READ_ONLY_TOOLS = ("Read", "Grep", "Glob")
84
84
  INSTRUCTION_ALIAS_FILENAMES = frozenset({"AGENTS.md", "CLAUDE.md", "ARCHIVE-MANIFEST.md"})
85
+ AGENT_DEFINITION_FOLDER_NAMES = ("agents", "agents-archived")
85
86
  FRONTMATTER_FENCE_LINE = "---"
86
87
  MATERIALIZER_MODULE_NAME = "codex_compat_materializer"
87
88
  MATERIALIZER_MODULE_PATH = (
@@ -115,19 +116,20 @@ def _extract_frontmatter_block(markdown_text: str) -> str | None:
115
116
 
116
117
  @cache
117
118
  def _agent_definition_candidate_paths() -> tuple[Path, ...]:
118
- """Return every markdown file in this directory that is an agent definition.
119
+ """Return every markdown file in the live and archived agent folders that is an agent definition.
119
120
 
120
121
  This is the floor the parametrized checks are measured against: each of
121
122
  these files is expected to yield a frontmatter block, so one that does not
122
123
  is a broken definition rather than a file to pass over.
123
124
 
124
125
  Returns:
125
- Every agent-definition `*.md` path in this directory, sorted.
126
+ Every agent-definition `*.md` path in `agents` and `agents-archived`, sorted.
126
127
  """
127
- agents_directory = Path(__file__).parent.parent / "agents-archived"
128
+ agents_root = Path(__file__).parent.parent
128
129
  return tuple(
129
130
  each_markdown_file
130
- for each_markdown_file in sorted(agents_directory.glob("*.md"))
131
+ for each_folder_name in AGENT_DEFINITION_FOLDER_NAMES
132
+ for each_markdown_file in sorted((agents_root / each_folder_name).glob("*.md"))
131
133
  if each_markdown_file.name not in INSTRUCTION_ALIAS_FILENAMES
132
134
  )
133
135
 
@@ -18,6 +18,7 @@ grading. Start with its validation command and two-case smoke. Preserve the dist
18
18
  between grader validation, stored replay, a fresh recipe run and a complete workflow run.
19
19
  Use the plugin process below when measuring skill discovery or with/without-plugin contribution.
20
20
  To check whether a context file is thin enough, follow [the context budget page](reference/context-budget.md).
21
+ To compare models, follow [Measuring model choice](~/.claude/docs/model-choice/measuring.md): run each pair in its own session and score against spend by cost per finished task.
21
22
 
22
23
  ## Contents
23
24
 
@@ -22,6 +22,8 @@ description: >-
22
22
 
23
23
  With no level, or an unknown one, run `high`.
24
24
 
25
+ The level sets review depth. Child agents take their model and effort from [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md).
26
+
25
27
  ## Target
26
28
 
27
29
  A PR number, branch name, or file path after the level is the review target. With no target, the review reads the current diff.
@@ -18,7 +18,7 @@ review that target instead. Treat this diff as the review scope.
18
18
  Run **10 independent finder angles** via the Agent tool. Each
19
19
  surfaces **up to 8 candidate findings**. Do NOT let one angle's conclusions
20
20
  suppress another's — if two angles flag the same line for different reasons,
21
- record both. If the Agent tool is not available in your current tool set, do not error — perform each angle (and each verification) yourself, sequentially, in this context.
21
+ record both. Run each finder on Sonnet at high and each Phase 2 verifier on Opus at medium, per [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md). If the Agent tool is not available in your current tool set, do not error — perform each angle (and each verification) yourself, sequentially, in this context.
22
22
 
23
23
  ### Angle A — line-by-line diff scan
24
24
 
@@ -19,6 +19,8 @@ When the plan runtime is `claude`, the model is haiku and the profile is the sli
19
19
 
20
20
  When the plan runtime is `other`, the model is deferred. The running agent applies [reference/criteria.md](reference/criteria.md) and picks the model.
21
21
 
22
+ Every spawn names model and effort as an allowed pair from [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md).
23
+
22
24
  ## Loop
23
25
 
24
26
  Check each finding against the code. Fix every one that holds. Run the review again until a pass reports none. Before a merge, [the pr-lifecycle review loop](../pr-lifecycle/reference/review-loop-before-merge.md) sets how many full passes run. The steps are in [reference/criteria.md](reference/criteria.md).
@@ -91,7 +91,8 @@ Treat attachments, web pages, tool output, and reports as evidence under the act
91
91
 
92
92
  Keep short answers and bounded actions inline within the current tool and ownership rules.
93
93
  Delegate bulk or independent work when delegation is available and permitted.
94
- Use the configured runtime model policy. Read [host capabilities](reference/host-detect.md) when the executor changes.
94
+ Name model and effort on every worker and verifier, per [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md). Send workers that read to cheaper models. The lead keeps decisions and edits. Read [Subagents and fan-out](~/.claude/docs/model-choice/subagents-and-fan-out.md) for fan-out and when to skip it, and [Escalation ladder](~/.claude/docs/model-choice/escalation.md) when a result falls short.
95
+ Read [host capabilities](reference/host-detect.md) when the executor changes.
95
96
  Reuse a reachable worker whose context fits. Give a fresh worker the saved assignment and partial results.
96
97
 
97
98
  Register each delegated task before spawn and set one owner before the worker writes.
@@ -4,9 +4,9 @@ Read the session's declared runtime and exposed tools.
4
4
  Record the executor and available task, worker, contact, and wake tools in the run record.
5
5
  Use callable capabilities as evidence. Product names alone do not prove tool availability.
6
6
 
7
- Follow the current user's model choices and configured runtime routing policy.
8
- When policy permits default inheritance, keep it.
9
- Apply explicit model or effort overrides only when that policy or the user calls for them.
7
+ Follow the current user's model choices.
8
+ Name model and effort on every spawn, per [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md).
9
+ A spawn that names neither inherits the parent pair, so an Opus parent at high hands the child Opus at high.
10
10
  Resolve agent type names through the current runtime's supported tool schema.
11
11
 
12
12
  Load pstack's runtime mapping when pstack instructions apply.
@@ -6,6 +6,7 @@ The `spawn_oversight_hook` adds this duty to every spawn, at every level of the
6
6
 
7
7
  - Run each piece through the verified-work flow in `~/.claude/docs/rule-guides/verified-work.md`: research, verify, plan, verify, implement, verify.
8
8
  - Brief each worker with the user's own words, the standards that apply, and the acceptance check.
9
+ - Name model and effort on each worker and verifier, per [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md). A verifier judges, so it runs on Opus at medium.
9
10
  - Brief each verifier with the issue, the sources, the old state, and the new state. Leave the worker's conclusion out.
10
11
  - While a worker runs, read its progress. Wake a quiet agent with one concrete next step.
11
12
  - A fix passes only when its verifier reproduced the issue on the old state and confirmed it gone on the new state.
@@ -2,6 +2,7 @@
2
2
 
3
3
  Use this procedure after compaction, handoff, parent replacement, or a gap in ownership evidence.
4
4
  Re-read current instructions. A summary helps locate evidence but cannot replace it.
5
+ When the restart also changes the model, start the new model with a short summary. The prompt cache belongs to the old model, per [Context and caching](~/.claude/docs/model-choice/context-and-caching.md).
5
6
 
6
7
  ## Locate the run
7
8
 
@@ -49,6 +49,9 @@ worker_exit=$?
49
49
  cat "<report>"
50
50
  ```
51
51
 
52
+ Add `--model "<model>"` with a model from an allowed pair in
53
+ [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md).
54
+
52
55
  Add `--live-log "<events.jsonl>"` to watch the worker while it runs. The worker
53
56
  then writes one JSON event per line into that file as it happens. Every event
54
57
  carries the `session_id`, from the first startup hook line on. Each `assistant` line names the tool
@@ -56,6 +59,11 @@ calls and text, and the last line is the `result` event. Read new lines with
56
59
  `tail -n 20 "<events.jsonl>"` and skip screenshots unless a check needs to see
57
60
  the screen.
58
61
 
62
+ Add `--effort "<level>"` to set the worker's effort. With `--model` set, the
63
+ script keeps the effort inside
64
+ [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md).
65
+ `--model opus --effort xhigh` runs at `medium`, and `--model sonnet` alone runs at `high`.
66
+
59
67
  Read the JSON report and worker log after the process ends. The JSON fields are
60
68
  `account`, `reason`, `exit_code`, `duration_seconds`, `result`, and `is_error`.
61
69
  The runner writes one summary line with the selected account, exit code, and
@@ -85,6 +85,12 @@ advisor achieves intelligence comparable to Sonnet at default effort, at
85
85
  lower cost. For maximum intelligence, keep the executor at default effort.
86
86
  ```
87
87
 
88
+ The docs pair Sonnet at medium. Here Sonnet runs at high only, per
89
+ [Subagent model and effort](~/.claude/docs/rule-guides/subagent-model-effort.md).
90
+ In the model choice article's advisor runs, no pairing clearly beat the executor alone.
91
+ Measure the consult rate first, per
92
+ [Subagents and fan-out](~/.claude/docs/model-choice/subagents-and-fan-out.md).
93
+
88
94
  Page 3 footnotes the benchmark condition: the Sonnet-plus-advisor SWE-bench
89
95
  Multilingual run uses the suggested system prompt "with thinking turned
90
96
  off" — a consult substitutes for extended thinking in that run.
@@ -26,6 +26,8 @@ Source of truth: `ALL_CLI_MODEL_ID_BY_TIER` and `resolve_cli_model_id(tier)` in
26
26
  | Haiku | `haiku` |
27
27
  | ThirdParty (third-party session model field only) | `third-party` |
28
28
 
29
+ On Bedrock, Google Cloud, Microsoft Foundry and Claude Platform on AWS, the `haiku` alias resolves to Haiku 4.5. Set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to pin it.
30
+
29
31
  `resolve_cli_model_id(tier)` accepts any letter case and raises `ValueError` on a tier outside the map.
30
32
 
31
33
  ## Brief piping
@@ -20,8 +20,10 @@ new user instruction.
20
20
 
21
21
  ## Effort
22
22
 
23
- Run each model call at the session's effort level. Raise a call to `xhigh` or
24
- `max` only where a measured run shows a quality gain at that level.
23
+ Run each model call at an allowed pair from
24
+ `docs/rule-guides/subagent-model-effort.md`. When a measured run shows a gain,
25
+ move up one rung of the ladder in `docs/model-choice/escalation.md`. Measure
26
+ per `docs/model-choice/measuring.md`.
25
27
 
26
28
  ## Stack context
27
29
 
@@ -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. Set the model and the effort from [Subagent model and effort](rule-guides/subagent-model-effort.md).
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). The work decides the model, as [Which model for which job](model-choice/which-model.md) says, and a side task such as search or log reading goes to a cheaper model, as [Subagents and fan-out](model-choice/subagents-and-fan-out.md) says.
31
31
 
32
32
  ## Why
33
33
 
@@ -0,0 +1,12 @@
1
+ Back to [Subagent model and effort](../rule-guides/subagent-model-effort.md).
2
+
3
+ # Model choice guides
4
+
5
+ Open the page that matches your question. Each page adapts [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/) to the allowed pairs in [Subagent model and effort](../rule-guides/subagent-model-effort.md). Where the article and that table differ, the table wins.
6
+
7
+ - [Which model for which job](which-model.md): the starting model for a task, and when to move down or up.
8
+ - [Escalation ladder](escalation.md): what to try, in order, when a result is not good enough.
9
+ - [Context and caching](context-and-caching.md): keep the lead's context small, and switch models only at a break.
10
+ - [Subagents and fan-out](subagents-and-fan-out.md): put side work on smaller models, and split bulk work across workers.
11
+ - [Measuring model choice](measuring.md): compare models on your own tasks by cost per finished task.
12
+ - [API compatibility](api-compatibility.md): request changes to check before a script moves to a new model.
@@ -0,0 +1,21 @@
1
+ Back to [Model choice guides](README.md).
2
+
3
+ # API compatibility
4
+
5
+ ## In brief
6
+
7
+ A script or app that calls the API can break when it moves to a new model. Check each item below before the switch. The source is [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/).
8
+
9
+ **When this applies:** Your own code sends Messages API requests and you change its model.
10
+
11
+ ## Checklist
12
+
13
+ - **Fable 5.2 keeps its thinking.** The API returns 400 if anything before a Fable thinking block changes. You can opt in to dropping those blocks. Claude Code, the Agent SDK and Managed Agents handle this. Keep custom history append-only.
14
+ - **Opus and Fable always think.** You cannot turn thinking off. Read content blocks by their `type` field.
15
+ - **Forced tool choice fails.** `tool_choice` `any` or `tool` returns 400 on Sonnet 5.5, Opus 5.5 and Fable 5.2. Use `auto` with `strict: true`, and say in the prompt when to call the tool.
16
+ - **Computer use has one route.** Use `computer_toolset_20260801` only.
17
+ - **Haiku 4.5 to Haiku 5.5.** Replace `budget_tokens` with an effort level. Drop any non-default `temperature`, `top_p` or `top_k`. End `messages` with a user turn.
18
+ - **Safety fallbacks.** Claude Code can rerun a flagged request on an older model. Cybersecurity requests rerun on Opus 4.8, and biology requests rerun on Opus 5. The transcript notes the fallback.
19
+ - **Multi-model systems.** Build every request for the strictest model. When the routing rule is simple, let code pick the model.
20
+
21
+ Thinking blocks also move between models in a session. Read [Context and caching](context-and-caching.md).
@@ -0,0 +1,46 @@
1
+ Back to [Model choice guides](README.md).
2
+
3
+ # Context and caching
4
+
5
+ ## In brief
6
+
7
+ Every turn resends the whole context, so a long context costs money on every turn. Keep the costly model's context small and let cheaper subagents do the long reading. Switch the main model only at a natural break, because the prompt cache belongs to the model that wrote it.
8
+
9
+ **When this applies:** A long session, a lead agent that reads a lot, or a plan to change the session's model partway through.
10
+
11
+ ## Context costs every turn
12
+
13
+ The source is [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/).
14
+
15
+ - The API keeps no state. Each turn sends the full conversation again.
16
+ - On a long run, most input bills as cache reads. The article gives about $0.03 a turn at 150K context and about $0.004 at 20K.
17
+ - Keep the costly model's context for decisions. Cheaper subagents do the long reading and hand back a short summary. [Subagents and fan-out](subagents-and-fan-out.md) shows how to spawn them here.
18
+ - Haiku is the only model with prompt-length price tiers. Its price goes up above a 100K prompt. When prompts are long, compare models by cost per finished task. [Measuring model choice](measuring.md) shows how.
19
+
20
+ This package's `settings.json` sets `autoCompactWindow` to 350000. Haiku 5.5 and Haiku 4.5 compact at 250000 through `modelSettings`.
21
+
22
+ For cache layout, such as a stable prefix first and new content appended, read the cache section of the [harnessing inventory](https://github.com/jl-cmd-projects/claude-dev-env/blob/main/docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md).
23
+
24
+ ## Switching models
25
+
26
+ - The prompt cache belongs to the model that wrote it.
27
+ - The first turn on a new model pays the cache-write price on the full conversation.
28
+ - Switch only at a natural break, such as the end of a plan or a finished step.
29
+ - Run `/compact` first, or start the new model with a short summary.
30
+ - For cheaper side work inside one session, spawn a subagent. The main model and its cache stay as they are.
31
+
32
+ ## Thinking blocks across models
33
+
34
+ The API reads earlier thinking only when the new model can read the old model's blocks.
35
+
36
+ | New model | Reads thinking from |
37
+ | --- | --- |
38
+ | Opus 5.5 | Sonnet and Haiku |
39
+ | Sonnet 5.5 | Haiku |
40
+ | Fable 5.2 | Opus, Sonnet and Haiku |
41
+
42
+ - A move down a tier loses the earlier reasoning.
43
+ - A move away from Fable 5.2 drops its reasoning.
44
+ - The API drops blocks the new model cannot read. The request still succeeds.
45
+
46
+ A script that keeps its own history has more to check. Read [API compatibility](api-compatibility.md).
@@ -0,0 +1,57 @@
1
+ Back to [Model choice guides](README.md).
2
+
3
+ # Escalation ladder
4
+
5
+ ## In brief
6
+
7
+ When a result is not good enough, first give the agent a way to check its own work. Then raise effort where the model has a step. Then move up one model at a lower effort.
8
+
9
+ **When this applies:** A task fails or comes back weak on its current model and effort, and you want to try again. Every rung uses a pair from [Subagent model and effort](../rule-guides/subagent-model-effort.md).
10
+
11
+ ## The ladder
12
+
13
+ The order comes from [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/). The rungs are adapted to the allowed pairs.
14
+
15
+ 1. Add self-verification. Give the agent a test, a build or a script that tells it when the work is done.
16
+ 2. Raise effort one level, where the model has a step. Haiku steps up through low, medium, high, xhigh and max. Fable steps up from low to medium to high.
17
+ 3. Move up one model, at a lower effort. Opus and Sonnet have one effort each here, so for them step 2 is this step.
18
+
19
+ The model rungs, in order:
20
+
21
+ - Haiku max to Sonnet high.
22
+ - Sonnet high to Opus medium.
23
+ - Opus medium to Fable low or Fable medium. Start Fable at a lower effort, as the article says.
24
+ - Fable medium to Fable high.
25
+
26
+ To confirm that a rung helps, follow [Measuring model choice](measuring.md).
27
+
28
+ ## Effort before a bigger model
29
+
30
+ The article says to try effort before you change models. Past high, one more effort level can cost as much as a bigger model.
31
+
32
+ - In the article's SWE-bench Pro run, Opus at medium scored about 2.5 points below Opus at high, at about 70% of the cost.
33
+ - In the same run, Opus at xhigh scored about 1.4 points above high, at about 2.5 times the cost of high.
34
+ - In the article's FrontierCode 2.0 run, Fable at high scored 45.3%. Opus at max scored 45.5% at about twice the cost per task.
35
+ - In the article's Terminal-Bench 3.0 run, Opus at high scored 58.9%. Fable 5.1 at max scored 58.0% and used about twice the tokens. Max effort added cost and no score.
36
+
37
+ These numbers fit the allowed pairs, which cap Opus at medium. Medium keeps most of the score for less spend. Past that point, Fable at high gives the same score for less cost.
38
+
39
+ ## Low first, then retry the failures
40
+
41
+ The article runs every task at low effort, then reruns only the failures at high. That run passed about 97% of tasks at about $0.17 a task. Running every task at high passed 95.3% at $0.29 a task.
42
+
43
+ Here, run the cheaper pair first, then rerun only the failures on the next pair up:
44
+
45
+ - Haiku low, then Haiku high.
46
+ - Fable low, then Fable high.
47
+ - Sonnet high, then Opus medium.
48
+ - Opus medium, then Fable.
49
+
50
+ This works only when a check can tell which tasks failed. Add that check first, as step 1 says.
51
+
52
+ ## Price the hardest tasks
53
+
54
+ A few hard tasks can drive most of the spend. On one 20-problem benchmark in the article, two problems were 43% of the total spend.
55
+
56
+ - Record cost per task, and find the tasks that cost the most.
57
+ - Put the hardest tasks in the sample when you compare pairs. A sample of easy tasks hides most of the spend.
@@ -0,0 +1,43 @@
1
+ Back to [Model choice guides](README.md).
2
+
3
+ # Measuring model choice
4
+
5
+ ## In brief
6
+
7
+ Compare models on your own tasks by cost per finished task. Run each candidate pair in its own session, record cost and outcome, and keep the pair that gives the best score for its spend.
8
+
9
+ **When this applies:** You want to change the default pair for a kind of work, or you want proof that a rung of the [escalation ladder](escalation.md) helps. Test only pairs from [Subagent model and effort](../rule-guides/subagent-model-effort.md).
10
+
11
+ ## Steps
12
+
13
+ The steps adapt [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/). The article tests each model at two or three effort levels. Here, test only the allowed pairs.
14
+
15
+ 1. Sample tasks from your own work. Give each task an outcome check, such as a test, a build or a script. Decide the check before you read any answer.
16
+ 2. Run each candidate pair on each task, each run in its own session. A session keeps its own prompt cache, so separate sessions keep caches from mixing.
17
+ 3. Record the cost of each task. Read token use from `usage`, or from `modelUsage` on the result event of a headless run.
18
+ 4. Plot score against spend for each pair. Keep a setup that mixes models only when it beats every single-model point.
19
+ 5. Shadow the winner on a slice of work before you switch the default. Compare its results with the current pair on the same tasks.
20
+
21
+ ## Quick check in a session
22
+
23
+ For one task, you can compare two models in Claude Code:
24
+
25
+ - Pick one task from the backlog.
26
+ - Run it once on each model. Use `/model` to switch, and start a new session for each run.
27
+ - Compare the spend of the two runs with `/usage`.
28
+
29
+ One task gives a hint. Use the steps above before you change a default.
30
+
31
+ ## Tools in this repo
32
+
33
+ - [Report task usage](https://github.com/jl-cmd-projects/claude-dev-env/blob/main/docs/guides/task-usage-report.md): record token use, cost and pass or fail for each attempt. The script is [task_usage_report.py](../../scripts/task_usage_report.py).
34
+ - [Proof before pull request](../rule-guides/proof-before-pull-request.md): spawn headless runs through the account broker, with `--model` and `--effort` on every call.
35
+ - [build-eval skill](../../.agents/skills/build-eval/SKILL.md): design an eval with labeled cases and fixed grading.
36
+ - [Subagent effort routing eval](https://github.com/jl-cmd-projects/claude-dev-env/blob/main/.claude/hillclimb/subagent-effort-routing/results.md): a worked example. It runs each case as a fresh headless session and grades the pair that each child ran at. Its metrics are in [metrics.md](https://github.com/jl-cmd-projects/claude-dev-env/blob/main/.claude/hillclimb/subagent-effort-routing/metrics.md).
37
+
38
+ ## What to record
39
+
40
+ - The task ID, the pair, and the run ID for each attempt.
41
+ - The outcome from the check: pass or fail.
42
+ - Input, output and cache-read tokens, and the cost.
43
+ - The served model from `modelUsage`. A run can serve a model other than the one you named.
@@ -0,0 +1,55 @@
1
+ Back to [Model choice guides](README.md).
2
+
3
+ # Subagents and fan-out
4
+
5
+ ## In brief
6
+
7
+ A subagent bills at its own model's rate, so side work on a small model costs less. Keep small models on work that is cheap to check, and keep code edits and judgment on the lead's model. For work bigger than one context window, a top-tier lead can split the task across many cheaper workers.
8
+
9
+ **When this applies:** You start a subagent, or you plan a task too big for one context window.
10
+
11
+ ## Put side work on smaller models
12
+
13
+ The source is [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/).
14
+
15
+ - Small models suit search, test runs, log reading and summaries. A wrong answer there is cheap to spot.
16
+ - Code edits and judgment calls stay on the lead's model.
17
+ - The subagent hands back a short summary. The lead's context stays small, as [Context and caching](context-and-caching.md) explains.
18
+
19
+ ## How this repo does it
20
+
21
+ The allowed pairs are in [Subagent model and effort](../rule-guides/subagent-model-effort.md). The hooks are in [Spawn routing](../../hooks/features/spawn-routing.md).
22
+
23
+ - Name the model and the effort on every spawn.
24
+ - Agent definitions carry no `model` key, and `effort` is no frontmatter key.
25
+ - A Haiku spawn in a session uses `subagent_type` `lean-worker`. Other Haiku work runs headless through the account broker slim profile.
26
+ - The effort route hook fills in an allowed effort when a spawn leaves it out or names one outside its model's list.
27
+ - A built-in agent such as Explore runs on the session's model unless the spawn names one. Name the model on every Explore spawn.
28
+
29
+ The article sets `model: haiku` in agent frontmatter, defines a custom Explore agent on Haiku, and sets `CLAUDE_CODE_SUBAGENT_MODEL`. This repo uses none of them. For the same goal, spawn `lean-worker` with model `haiku` for search, log reading, test runs and summaries.
30
+
31
+ ## Model aliases
32
+
33
+ - The `haiku` alias is Haiku 5.5 on the Anthropic API from Claude Code v2.1.293.
34
+ - On Bedrock, Google Cloud, Microsoft Foundry and Claude Platform on AWS, `haiku` is still Haiku 4.5.
35
+ - `ANTHROPIC_DEFAULT_HAIKU_MODEL` pins the alias to one model.
36
+ - `opusplan` plans with Opus and executes with Sonnet. That is the opposite of the article's advice. Measure it before you make it a default, as [Measuring model choice](measuring.md) shows.
37
+
38
+ ## Fan-out for bulk work
39
+
40
+ For work bigger than one context window, a top-tier lead splits the task across many cheaper workers and merges the results.
41
+
42
+ - In the article's defect search over about 22M tokens, an Opus lead with up to 25 parallel Sonnet workers cost about a third less than Opus alone. The score was the same.
43
+ - The article ran both at default effort. Here the lead is Opus medium or Fable, and the workers are Sonnet high or Haiku.
44
+ - Skip fan-out for one chain of dependent steps, or for work that fits one context.
45
+ - The lead stays open until every worker's result is merged. Read [Workers done before complete](../rule-guides/workers-done-before-complete.md).
46
+ - For a long run with no one watching, read [Long-horizon autonomy](../rule-guides/long-horizon-autonomy.md).
47
+ - The [orchestrator skill](../../.agents/skills/orchestrator/SKILL.md) gives the steps for a lead.
48
+
49
+ ## Advisor pairs
50
+
51
+ - In the article, none of four advisor pairings clearly beat the executor alone.
52
+ - An Opus high executor with a Fable 5.1 advisor scored 90.1% at $2.92 an attempt. That is 1.7 points above Opus alone, for about 2.1 times the cost. Here an Opus executor runs at medium.
53
+ - Measure how often the executor consults the advisor before you add one.
54
+
55
+ The call rules are in [Advisor tool](../references/advisor-tool.md). The advisor exception is in [Subagent model and effort](../rule-guides/subagent-model-effort.md).
@@ -0,0 +1,62 @@
1
+ Back to [Model choice guides](README.md).
2
+
3
+ # Which model for which job
4
+
5
+ ## In brief
6
+
7
+ Start most work on Opus at medium. Move down to Sonnet or Haiku when the work is well scoped or cheap to check. Move up to Fable when Opus falls short or the work is very large.
8
+
9
+ **When this applies:** You pick the model and effort for a session, a subagent or a headless run. The allowed pairs are in [Subagent model and effort](../rule-guides/subagent-model-effort.md).
10
+
11
+ ## Starting pair by job
12
+
13
+ This table adapts [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/). The note says where this repo differs from the article.
14
+
15
+ | Job | Start here | Note |
16
+ | --- | --- | --- |
17
+ | Everyday engineering, debugging, features over many PRs | Opus medium | The article raises Opus to high next. Here the next step is Fable. |
18
+ | Well-scoped coding, such as a bug fix or a feature built to a spec | Sonnet high | The article starts Sonnet at medium. Here Sonnet runs at high. |
19
+ | Classification, routing, tagging, data extraction | Haiku medium | Same as the article. |
20
+ | Side-task subagents: file search, log reading, summaries | Haiku through `lean-worker`, or Sonnet high | Adapted. See [Subagents and fan-out](subagents-and-fan-out.md). |
21
+ | Chat and interactive work | Sonnet high, or Haiku for simple chat at volume | The article starts Sonnet at low or medium. Here Sonnet runs at high. |
22
+ | Everyday docs, slides and sheets | Sonnet high | Use Opus medium for complex financial models or large source docs. |
23
+ | Repeated agent tasks: review, investigation, drafting | Sonnet high | The article uses Sonnet at medium. Here Sonnet runs at high. |
24
+ | Computer use and vision | Opus medium | Same as the article. |
25
+ | Major refactor, migration, architecture, leading many subagents | Fable medium, then Fable high | Same as the article. |
26
+ | Deep research, quantitative analysis | Fable medium, then Fable high | Same as the article. |
27
+ | You are not sure | Opus medium | Same as the article. |
28
+
29
+ ## Move down
30
+
31
+ - Move to Sonnet high for well-scoped work, such as bug fixes and features built to a spec.
32
+ - Migrations and performance work can still need Opus. A major one can need Fable.
33
+ - Move to Haiku for high-volume work that a check can confirm, such as classification, routing and extraction.
34
+ - Move to Haiku for subagents that do side tasks. A wrong Haiku answer is cheap to spot.
35
+ - Keep small models off long agent loops. They suit short, checkable steps.
36
+
37
+ ## Move up
38
+
39
+ - Move to Fable for the hardest coding, finance and science work.
40
+ - Move to Fable when Opus medium falls short on a task. The article says "when Opus at high falls short". Here Opus runs at medium only.
41
+ - Move to Fable for long runs with no one watching.
42
+ - Before you move up, follow the [escalation ladder](escalation.md).
43
+
44
+ ## Prices
45
+
46
+ Source: the article, Nov 2026. Prices change, so check the current price list before you plan spend.
47
+
48
+ | Model | Input per million tokens | Output per million tokens | Cache read per million tokens |
49
+ | --- | --- | --- | --- |
50
+ | Haiku, prompt up to 100K tokens | $0.10 | $0.50 | $0.01 |
51
+ | Haiku, prompt over 100K tokens | $0.50 | $2.50 | $0.05 |
52
+ | Sonnet | $2 | $10 | $0.10 |
53
+ | Opus | $4 | $20 | $0.20 |
54
+ | Fable | $8 | $40 | $0.20 |
55
+
56
+ - Opus costs half of what Fable costs per token.
57
+ - Only Haiku has price tiers by prompt length. For long prompts, compare models on cost per finished task. See [Measuring model choice](measuring.md).
58
+
59
+ ## Thinking
60
+
61
+ - Opus and Fable always think. You cannot turn thinking off on them.
62
+ - Sonnet and Haiku use adaptive thinking. They think more on harder steps.
@@ -73,17 +73,21 @@ The repair fields preserve the reference-path result. The fallback fields preser
73
73
 
74
74
  ## Escalation shapes
75
75
 
76
- Four shapes cover how a harder task gets more strength behind it. Route to the one that matches the work, not by default to the advisor.
76
+ Four shapes cover how a harder task gets more strength behind it. Route to the one that matches the work. The advisor is one choice among four.
77
77
 
78
78
  | Shape | Fits when |
79
79
  |---|---|
80
80
  | Advisor | The task needs intermittent strategy and review, and one executor keeps the task from start to finish. |
81
81
  | Subagent | A piece of the task is a bounded subtask that benefits from its own context and its own loop. |
82
82
  | Stronger-model planning phase | The plan needs the strong model's judgment; the fast model can carry it out once written. |
83
- | Full model switch | Every step of the task needs the stronger tier, not just the hard decisions. |
83
+ | Full model switch | Every step of the task needs the stronger tier, including the easy ones. |
84
84
 
85
85
  Spawn a subagent when the work is a delegable bounded subtask. Switch the whole task to the stronger model when every turn needs that tier.
86
86
 
87
+ A full model switch pays the cache-write price on the whole conversation, so switch at a natural break. See [Context and caching](../model-choice/context-and-caching.md). A stronger-model planning phase is the `opusplan` shape. The article says to measure that shape before you make it a default. See [Subagents and fan-out](../model-choice/subagents-and-fan-out.md).
88
+
89
+ In the article's advisor runs, none of four executor and advisor pairings clearly beat the executor alone. Measure the consult rate before you add an advisor for cost or score. See [Measuring model choice](../model-choice/measuring.md).
90
+
87
91
  ## Brevity cue
88
92
 
89
93
  When the consult path supports a free-text brief, append:
@@ -29,7 +29,7 @@ In an autonomous pipeline, the user cannot answer during the run. Reversible act
29
29
 
30
30
  ## Delegate and keep working
31
31
 
32
- A large independent track can run in a subagent while the lead handles other work. A few reads, a handful of edits, or a simple check fit in the lead's turn. Reusing a long-lived subagent across related tasks preserves its context. The lead steps in when that agent drifts or lacks context.
32
+ A large independent track can run in a subagent while the lead handles other work. A few reads, a handful of edits, or a simple check fit in the lead's turn. Reusing a long-lived subagent across related tasks preserves its context. The lead steps in when that agent drifts or lacks context. [Subagents and fan-out](../model-choice/subagents-and-fan-out.md) says when fan-out pays and when one chain of steps stays in one agent.
33
33
 
34
34
  For a task that spawned workers, the completion condition and checklist live in the [workers-done-before-complete guide](workers-done-before-complete.md).
35
35
 
@@ -39,8 +39,8 @@ Opus and Sonnet have one effort each here, so pick the model by the work.
39
39
  - Sonnet: well-scoped work, such as a bug fix or a feature built to a clear spec.
40
40
  - Opus: code edits, judgment calls, and decisions that rest on what other subagents report.
41
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
42
  - A built-in agent such as Explore runs on the session's model unless the spawn names one, so name the model.
45
43
 
44
+ The [model choice guides](../model-choice/README.md) cover which model, escalation, context and caching, subagents and fan-out, measuring, and API compatibility.
45
+
46
46
  Source for the work split: [Which Claude model should you build with](https://claude.dev/blog/which-claude-model-should-you-build-with/).
@@ -8,7 +8,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
8
8
  - `session/compaction_recall_prompt.py` returns every message the user typed after a compaction. `session/compaction_user_messages.py` reads them from a Claude Code transcript or a Codex rollout. `session/compaction_trim.py` trims each one in Python: it drops filler, articles, and gratitude, keeps approvals, continuation requests, backtick spans, and paths as typed, and marks a reversed message `(overruled by #N)`. No model runs, so the hook works on Claude Code and Codex with no account.
9
9
  - `session/task_tool_prompt.py` injects a task tracking directive at session start.
10
10
  - `session/working_style_prompt.py` injects the session's working style at session start.
11
- - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
11
+ - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled. For evidence on when an advisor pays, see [Subagents and fan-out](../../docs/model-choice/subagents-and-fan-out.md).
12
12
  - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
13
13
  - `session/plugin_session_baseline_writer.py` records each plugin's `version` and `installPath` from `installed_plugins.json` to a per-session file in the system temp folder. It writes on `startup`, or when the session has no baseline yet, and leaves an existing baseline alone on `resume`, `clear`, and `compact`.
14
14
  - `session/plugin_change_warning.py` compares `installed_plugins.json` with that baseline before each prompt. It names each plugin whose version or install path changed, or that the baseline lacks, once per session, and tells the user to restart Claude Code.
@@ -39,6 +39,6 @@ Preconditions:
39
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.
40
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.
41
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.
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. [Subagents and fan-out](../../docs/model-choice/subagents-and-fan-out.md) says which model a spawn should name.
43
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.
44
44
  - The model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.114.2",
3
+ "version": "8.114.4",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -15,4 +15,4 @@ Name both the model and the effort on every spawn. Opus runs at medium, Sonnet a
15
15
 
16
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
17
 
18
- **Full text:** [guide](../docs/rule-guides/subagent-model-effort.md). Read it when choosing which model gets which work.
18
+ **Full text:** [guide](../docs/rule-guides/subagent-model-effort.md). Read it when choosing which model gets which work. The [model choice guides](../docs/model-choice/README.md) cover escalation, caching, fan-out and measuring.
@@ -6,6 +6,10 @@ import argparse
6
6
  import sys
7
7
  from pathlib import Path
8
8
 
9
+ hooks_routing_directory = str(Path(__file__).resolve().parent.parent / "hooks" / "routing")
10
+ if hooks_routing_directory not in sys.path:
11
+ sys.path.insert(0, hooks_routing_directory)
12
+
9
13
  from account_broker import run_job
10
14
  from claude_account_worker_process import invoke_worker
11
15
  from claude_account_worker_report import finalize_report, make_report, pre_launch_failure_report, wait_report
@@ -14,9 +18,11 @@ from dev_env_scripts_constants.claude_account_worker_constants import (
14
18
  CLAUDE_BINARY_NAME,
15
19
  CLI_DESCRIPTION,
16
20
  CONFIGURATION_FAILURE_EXIT_CODE,
21
+ ALL_EFFORT_LEVELS,
17
22
  CWD_FLAG,
18
23
  DEFAULT_PERMISSION_MODE,
19
24
  DEFAULT_TIMEOUT_MINUTES,
25
+ EFFORT_FLAG,
20
26
  INVALID_TIMEOUT_MESSAGE,
21
27
  LAUNCH_FAILURE_EXIT_CODE,
22
28
  LIVE_LOG_FLAG,
@@ -34,6 +40,7 @@ from dev_env_scripts_constants.claude_account_worker_constants import (
34
40
  VERBOSE_FLAG,
35
41
  UTF8_ENCODING,
36
42
  )
43
+ from subagent_effort_route import model_family, routed_effort
37
44
 
38
45
  worker_job_runner = run_job
39
46
 
@@ -52,13 +59,38 @@ def build_argument_parser() -> argparse.ArgumentParser:
52
59
  parser.add_argument(CWD_FLAG, type=Path, default=Path.cwd())
53
60
  parser.add_argument(REPORT_FILE_FLAG, type=Path, required=True)
54
61
  parser.add_argument(MODEL_FLAG)
62
+ parser.add_argument(EFFORT_FLAG, choices=ALL_EFFORT_LEVELS)
55
63
  parser.add_argument(PERMISSION_MODE_FLAG, default=DEFAULT_PERMISSION_MODE)
56
64
  parser.add_argument(TIMEOUT_MINUTES_FLAG, type=_positive_timeout_minutes, default=DEFAULT_TIMEOUT_MINUTES)
57
65
  parser.add_argument(LIVE_LOG_FLAG, type=Path)
58
66
  return parser
59
67
 
60
68
 
61
- def _invocation(*, model: str | None, permission_mode: str, is_streamed: bool) -> list[str]:
69
+ def worker_effort(model: str | None, effort: str | None) -> str | None:
70
+ """Return the effort the worker runs at, inside the subagent model and effort rule.
71
+
72
+ ::
73
+
74
+ ("opus", "xhigh") -> "medium" ("sonnet", None) -> "high"
75
+ ("haiku", "max") -> "max" (None, "low") -> "low"
76
+
77
+ A model outside every Anthropic family keeps the effort it was given.
78
+
79
+ Args:
80
+ model: The model the worker runs on, or None for the account default.
81
+ effort: The effort the caller named, or None.
82
+
83
+ Returns:
84
+ The allowed effort for the model's family, or ``effort`` when the
85
+ model has no Anthropic family.
86
+ """
87
+ family = model_family(model)
88
+ if family is None:
89
+ return effort
90
+ return routed_effort(family, effort)
91
+
92
+
93
+ def _invocation(*, model: str | None, effort: str | None, permission_mode: str, is_streamed: bool) -> list[str]:
62
94
  format_flags = [OUTPUT_FORMAT_FLAG, OUTPUT_FORMAT_STREAM_JSON, VERBOSE_FLAG] if is_streamed else [OUTPUT_FORMAT_FLAG, OUTPUT_FORMAT_JSON]
63
95
  arguments = [
64
96
  CLAUDE_BINARY_NAME,
@@ -69,6 +101,9 @@ def _invocation(*, model: str | None, permission_mode: str, is_streamed: bool) -
69
101
  ]
70
102
  if model is not None:
71
103
  arguments.extend([MODEL_FLAG, model])
104
+ routed_worker_effort = worker_effort(model, effort)
105
+ if routed_worker_effort is not None:
106
+ arguments.extend([EFFORT_FLAG, routed_worker_effort])
72
107
  return arguments
73
108
 
74
109
 
@@ -87,12 +122,14 @@ def run_worker(
87
122
  permission_mode: str,
88
123
  timeout_minutes: int,
89
124
  live_log: Path | None = None,
125
+ effort: str | None = None,
90
126
  ) -> int:
91
127
  """Run one worker and write its structured report.
92
128
 
93
129
  With ``live_log`` set, the worker streams one JSON event per line into that
94
130
  file while it runs, so a watching session can read progress before the end.
95
131
  A live log that cannot be written ends the run before the broker starts.
132
+ The worker runs at the effort ``worker_effort`` returns for ``model``.
96
133
  """
97
134
  try:
98
135
  prompt_text = prompt_file.read_text(encoding=UTF8_ENCODING)
@@ -107,7 +144,7 @@ def run_worker(
107
144
  return finalize_report(report_file, report)
108
145
  try:
109
146
  outcome, duration_seconds = invoke_worker(
110
- all_arguments=_invocation(model=model, permission_mode=permission_mode, is_streamed=live_log is not None),
147
+ all_arguments=_invocation(model=model, effort=effort, permission_mode=permission_mode, is_streamed=live_log is not None),
111
148
  cwd=cwd,
112
149
  prompt_text=prompt_text,
113
150
  timeout_minutes=timeout_minutes,
@@ -138,6 +175,7 @@ def main() -> int:
138
175
  cwd=arguments.cwd,
139
176
  report_file=arguments.report_file,
140
177
  model=arguments.model,
178
+ effort=arguments.effort,
141
179
  permission_mode=arguments.permission_mode,
142
180
  timeout_minutes=arguments.timeout_minutes,
143
181
  live_log=arguments.live_log,
@@ -35,6 +35,10 @@ REPORT_FILE_FLAG: str = "--report-file"
35
35
 
36
36
  MODEL_FLAG: str = "--model"
37
37
 
38
+ EFFORT_FLAG: str = "--effort"
39
+
40
+ ALL_EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high", "xhigh", "max")
41
+
38
42
  PERMISSION_MODE_FLAG: str = "--permission-mode"
39
43
 
40
44
  TIMEOUT_MINUTES_FLAG: str = "--timeout-minutes"
@@ -44,6 +44,7 @@ def _run_worker(
44
44
  outcome: JobOutcome | Exception,
45
45
  *,
46
46
  model: str | None = None,
47
+ effort: str | None = None,
47
48
  permission_mode: str = "auto",
48
49
  live_log: Path | None = None,
49
50
  ) -> tuple[int, dict[str, object], dict[str, object]]:
@@ -67,6 +68,7 @@ def _run_worker(
67
68
  permission_mode=permission_mode,
68
69
  timeout_minutes=60,
69
70
  live_log=live_log,
71
+ effort=effort,
70
72
  )
71
73
  return exit_code, json.loads(report_file.read_text(encoding="utf-8")), captured
72
74
 
@@ -83,13 +85,71 @@ def test_should_send_prompt_and_flags_to_broker(
83
85
  assert report["result"] == "ready"
84
86
  assert captured["product"] is Product.CLAUDE
85
87
  assert captured["argv"] == [
86
- "claude", "-p", "--output-format", "json", "--permission-mode", "plan", "--model", "sonnet"
88
+ "claude", "-p", "--output-format", "json", "--permission-mode", "plan", "--model", "sonnet",
89
+ "--effort", "high",
87
90
  ]
88
91
  assert captured["stdin_text"] == "standalone brief"
89
92
  assert captured["cwd"] == tmp_path
90
93
  assert captured["timeout_seconds"] == 3600
91
94
 
92
95
 
96
+ @pytest.mark.parametrize(
97
+ ("model", "effort", "expected_tail"),
98
+ [
99
+ ("opus", "xhigh", ["--model", "opus", "--effort", "medium"]),
100
+ ("claude-fable-5-2", "low", ["--model", "claude-fable-5-2", "--effort", "low"]),
101
+ ("fable", "max", ["--model", "fable", "--effort", "high"]),
102
+ ("haiku", "max", ["--model", "haiku", "--effort", "max"]),
103
+ (None, "low", ["--effort", "low"]),
104
+ ],
105
+ )
106
+ def test_should_run_the_worker_at_an_allowed_effort(
107
+ monkeypatch: pytest.MonkeyPatch,
108
+ tmp_path: Path,
109
+ model: str | None,
110
+ effort: str,
111
+ expected_tail: list[str],
112
+ ) -> None:
113
+ _, _, captured = _run_worker(monkeypatch, tmp_path, _outcome(), model=model, effort=effort)
114
+
115
+ all_arguments = captured["argv"]
116
+ assert isinstance(all_arguments, list)
117
+ assert all_arguments[-len(expected_tail):] == expected_tail
118
+
119
+
120
+ @pytest.mark.parametrize(
121
+ ("model", "effort", "expected_effort"),
122
+ [
123
+ ("opus", "xhigh", "medium"),
124
+ ("sonnet", None, "high"),
125
+ ("haiku", "max", "max"),
126
+ ("gpt-5", "xhigh", "xhigh"),
127
+ (None, None, None),
128
+ ],
129
+ )
130
+ def test_worker_effort_keeps_the_effort_inside_the_rule(
131
+ model: str | None, effort: str | None, expected_effort: str | None
132
+ ) -> None:
133
+ assert worker.worker_effort(model, effort) == expected_effort
134
+
135
+
136
+ def test_should_pass_no_effort_when_neither_model_nor_effort_is_named(
137
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
138
+ ) -> None:
139
+ _, _, captured = _run_worker(monkeypatch, tmp_path, _outcome())
140
+
141
+ all_arguments = captured["argv"]
142
+ assert isinstance(all_arguments, list)
143
+ assert "--effort" not in all_arguments
144
+
145
+
146
+ def test_should_reject_an_effort_outside_the_cli_levels() -> None:
147
+ with pytest.raises(SystemExit):
148
+ worker.build_argument_parser().parse_args(
149
+ ["--prompt-file", "brief.md", "--report-file", "report.json", "--effort", "extreme"]
150
+ )
151
+
152
+
93
153
  def test_should_stream_events_into_the_live_log_when_one_is_named(
94
154
  monkeypatch: pytest.MonkeyPatch, tmp_path: Path
95
155
  ) -> None:
@@ -273,3 +333,4 @@ def test_should_require_prompt_and_report_flags() -> None:
273
333
  assert arguments.prompt_file == Path("brief.md")
274
334
  assert arguments.report_file == Path("report.json")
275
335
  assert arguments.permission_mode == "auto"
336
+ assert arguments.effort is None