agent-bios 0.14.0 → 0.16.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.
Files changed (60) hide show
  1. package/DEPENDENCIES.md +35 -12
  2. package/README.md +346 -31
  3. package/claude/CLAUDE.md +2 -2
  4. package/claude/agents/frontier.md +1 -1
  5. package/claude/agents/sweep.md +3 -3
  6. package/claude/agents/workhorse.md +2 -2
  7. package/claude/guides/claude-prompting.md +119 -34
  8. package/claude/guides/cli-multi-model-workflow.md +33 -15
  9. package/claude/guides/gpt-prompting.md +148 -28
  10. package/claude/guides/review-request.md +27 -0
  11. package/claude/guides/session-distill-workflow.md +54 -2
  12. package/claude/guides/slide-writing/RUNBOOK.md +137 -0
  13. package/claude/guides/slide-writing/scripts/pair.py +979 -0
  14. package/claude/guides/slide-writing/scripts/render.mjs +82 -0
  15. package/claude/guides/slide-writing.md +195 -0
  16. package/claude/guides/svg-visualization-guide.md +9 -0
  17. package/claude/guides/verification-discipline.md +5 -1
  18. package/claude/hooks/tooling-gotchas-hook.py +7 -5
  19. package/codex/AGENTS.md +2 -2
  20. package/codex/agents/frontier.toml +2 -1
  21. package/codex/agents/reviewer.toml +1 -1
  22. package/codex/agents/sweep.toml +3 -3
  23. package/codex/agents/workhorse.toml +1 -1
  24. package/codex/config-additions.toml +1 -1
  25. package/codex/guides/claude-prompting.md +119 -34
  26. package/codex/guides/cli-multi-model-workflow.md +33 -15
  27. package/codex/guides/gpt-prompting.md +148 -28
  28. package/codex/guides/review-request.md +27 -0
  29. package/codex/guides/session-distill-workflow.md +54 -2
  30. package/codex/guides/slide-writing/RUNBOOK.md +137 -0
  31. package/codex/guides/slide-writing/scripts/pair.py +979 -0
  32. package/codex/guides/slide-writing/scripts/render.mjs +82 -0
  33. package/codex/guides/slide-writing.md +195 -0
  34. package/codex/guides/svg-visualization-guide.md +9 -0
  35. package/codex/guides/verification-discipline.md +5 -1
  36. package/compose/assemble.py +290 -14
  37. package/compose/bootstrap/SKILL.md +119 -0
  38. package/compose/check-domains.py +102 -9
  39. package/compose/corpus-state.py +1174 -0
  40. package/compose/corpus.py +387 -0
  41. package/compose/corpus_catalog.py +882 -0
  42. package/compose/corpus_install.py +1617 -0
  43. package/compose/corpus_session.py +726 -0
  44. package/compose/corpus_store.py +1414 -0
  45. package/compose/corpus_transaction.py +236 -0
  46. package/compose/corpus_ui.py +644 -0
  47. package/compose/domains.json +101 -100
  48. package/compose/write-update-cache.py +53 -0
  49. package/install.sh +174 -24
  50. package/launch/agent-launch.py +1327 -184
  51. package/launch/agent-launch.toml +12 -16
  52. package/launch/i18n/en.toml +113 -7
  53. package/launch/i18n/ja.toml +113 -7
  54. package/launch/i18n/ko.toml +113 -7
  55. package/learn/collect-learning.py +46 -19
  56. package/learn/migrate-learnings.py +10 -1
  57. package/package.json +13 -3
  58. package/provenance.json +1 -1
  59. package/session-cost.py +22 -2
  60. package/wrappers/codex-helm.sh +3 -3
package/claude/CLAUDE.md CHANGED
@@ -84,8 +84,8 @@
84
84
 
85
85
  ## Multi-Model Workflow
86
86
 
87
- - Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: verifying or reviewing your own work always spawns, and you raise it yourself — before presenting a load-bearing conclusion or taking an irreversible step, propose the cross-check unprompted; the user should never have to ask for it. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
88
- - Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and briefing-plus-verifying clearly cheaper than doing. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
87
+ - Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: before presenting a load-bearing conclusion or taking an irreversible step, propose the cross-check unprompted; the user should never have to ask for it. Independence comes from the seat you dispatch to, so name it. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
88
+ - Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and a tier pinned before dispatch. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
89
89
  - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
90
90
  - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/gpt-prompting.md` for gpt-family targets and `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
91
91
  - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: frontier
3
3
  description: FRONTIER tier — bounded hardest decisions, first-of-kind design, triage gates, and final verdicts. Spawn when the Escalation gate fires — an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives — with a blind packet (evidence, constraints, rubric, neutral alternatives; no draft conclusion) and a pre-noted change condition.
4
- model: claude-fable-5
4
+ model: claude-fable-5-1
5
5
  effort: max
6
6
  disallowedTools: [Edit, Write, NotebookEdit]
7
7
  ---
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: sweep
3
- description: SWEEP tier — cheap wide scans, candidate finding, mechanical checks, and closed-form summaries. Spawn when each item applies one explicit rule; ambiguity returns as an exception, never resolved.
3
+ description: SWEEP tier — read-only checks applying one explicit rule to each item. Ambiguity returns as an exception, never resolved.
4
4
  model: claude-haiku-4-5
5
- effort: low
5
+ tools: [Read, Glob, Grep]
6
6
  disallowedTools: [Edit, Write, NotebookEdit]
7
7
  ---
8
8
 
9
- Run one clear repeatable scan, candidate pass, mechanical check, or closed summary over exact inputs, rules, stop condition, and output shape. Read-only: do not edit, broaden scope, choose architecture, or seek authority. Parallelize independent reads. Surface ambiguity as an exception instead of inferring intent. Report: status, the non-empty items_checked, findings with proving evidence or command, risks_or_escalations.
9
+ Apply one explicit rule to each item in the supplied inputs and stop at the declared boundary. Read-only: do not edit, broaden scope, choose architecture, or seek authority. Parallelize independent reads. Surface ambiguity as an exception instead of inferring intent. Report: status, the non-empty items_checked, findings with proving evidence or command, risks_or_escalations.
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: workhorse
3
3
  description: WORKHORSE tier — bounded implementation, fixes, tests, and per-item judgment. Spawn decision-complete work with frozen scope/interfaces and a machine-checkable done-when; two or more independent items spawn in parallel.
4
- model: claude-opus-5
5
- effort: medium
4
+ model: claude-sonnet-5
5
+ effort: xhigh
6
6
  ---
7
7
 
8
8
  Complete one bounded implementation, fix, or per-item judgment from a packet naming objective, frozen scope and inputs, allowed actions, output, done-when, and verification. Preserve out-of-scope behavior; batch independent reads; escalate missing decisions or authority instead of resolving them. Stage output for the main's acceptance — no external irreversible actions (push, install, credential, or remote mutation). Run the narrowest reliable changed-path check. Report: status, files_or_items_touched, evidence, verification or gap, risks_or_escalations.
@@ -9,13 +9,26 @@ use_when:
9
9
  - porting a prompt written for an older claude model
10
10
  - deciding a reasoning-effort level for claude work
11
11
  core_rules:
12
+ - choose guidance by the actual target model — Fable 5.1 and Opus 5 need different progress, delegation, and verification tuning
12
13
  - state the goal, the constraints, and the reason behind the request; let the model choose the route
13
- - de-prescribe ported prompts — step-by-step scaffolding written for older models reduces output quality on this tier
14
+ - compare inherited process scaffolding on the target model before keeping or removing it
14
15
  - put the full task specification in the first turn for long-horizon work rather than revealing it across turns
15
16
  - make tool descriptions prescriptive about when to call, not only what the tool does
16
17
  - require progress claims to be audited against a tool result from the same session
17
18
  - name the boundary explicitly — what to do without asking, and what to stop and ask about
19
+ derived_at: 2026-09-07
20
+ source_pins:
21
+ - doc: prompting-claude-opus-5
22
+ sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
23
+ pinned_at: 2026-09-07
24
+ - doc: claude-prompting-best-practices
25
+ sha256: f98aa130a7974b2edf98f8c3babe806ab140d5cdd3933a506f5211335b431c5f
26
+ pinned_at: 2026-09-07
27
+ - doc: prompting-claude-fable-5-1
28
+ sha256: 4aa645dd26fe9efebdaaff7462563bfac1f27782ce2d71dd5afffeaf02a80c62
29
+ pinned_at: 2026-09-07
18
30
  targets:
31
+ - claude-fable-5-1
19
32
  - claude-fable-5
20
33
  - claude-opus-5
21
34
  - claude-sonnet-5
@@ -24,6 +37,7 @@ verification_focus:
24
37
  - prompt changes are A/B'd against the prior scaffolding rather than assumed
25
38
  - effort changes are swept across levels on a real eval set, not chosen by reputation
26
39
  - per-model constraints are confirmed against the live surface before use
40
+ - model-specific advice stays within its named section, including after assembly
27
41
  ---
28
42
 
29
43
  # Claude Prompting Guide
@@ -33,26 +47,56 @@ composing a prompt for a claude-tier model — a review packet dispatched
33
47
  cross-family, a subagent brief, or the main's own instructions when the main is
34
48
  Claude.
35
49
 
36
- The central shift: this tier is more autonomous and more literal than its
37
- predecessors, and prompts written for older models are often too prescriptive
38
- they measurably reduce output quality. Porting a prompt means removing
39
- scaffolding, not adding to it. State the goal and the constraints; let the model
40
- pick the path.
50
+ Use the shared recipe and checklist together with the section for the model being
51
+ prompted, even when a subagent uses a different model from the main. Model-specific
52
+ tuning preserves the corpus's permission boundaries and required verification.
53
+
54
+ | Target | Apply |
55
+ | --- | --- |
56
+ | `claude-fable-5-1` | Shared recipe and Claude Fable 5.1 |
57
+ | `claude-opus-5` | Shared recipe and Claude Opus 5 |
58
+ | `claude-fable-5`, `claude-sonnet-5`, `claude-haiku-4-5` | Shared recipe; consult the target's own guidance before borrowing another model's tuning |
41
59
 
42
60
  ## Default prompt recipe
43
61
 
44
- - `Goal` and the **reason behind it** — this tier connects a task to relevant
45
- context when it knows the intent, instead of inferring intent on its own.
46
- "I'm doing X for Y, who needs Z; with that in mind: …" outperforms the bare
47
- request, most of all for long-running agents holding several workstreams.
62
+ - `Goal` and the **reason behind it** — provide the audience, purpose, and relevant
63
+ context so the model does not have to infer the intent.
48
64
  - `Success criteria` — what done means and how it is checked.
49
- - `Constraints and boundaries` — say what not to do. This tier sometimes takes
50
- unrequested-but-adjacent actions; naming the boundary is the fix.
65
+ - `Constraints and boundaries` — state the permitted scope and approval conditions.
51
66
  - `Tools` — each description states **when to call it**, not only what it does.
52
- Prescriptive trigger conditions give measurable lift here.
67
+ Name prerequisite retrieval and validation when correctness depends on them.
53
68
  - `Output` — the artifact shape and the register.
54
69
 
55
- ## When to add blocks
70
+ ## Claude Fable 5.1
71
+
72
+ - Begin effort experiments at `high`; compare supported levels afresh. Identical
73
+ effort names need not have identical costs across models.
74
+ - Request brief start, progress, and final updates; first verify the client renders
75
+ updates and remove conflicting silence instructions.
76
+ - Batch independent tool calls. Let the lead do independent work while subagents run.
77
+ - Complete authorized requests, including promised next steps. State genuine approval
78
+ boundaries and whether a person is available; avoid unnecessary pauses.
79
+ - Ask for literal prose and useful formatting. Demonstrate how retrieved quotations
80
+ should be marked and attributed.
81
+ - Keep edits targeted and tests proportional to the requested behavior; report
82
+ unrelated issues separately.
83
+ - At `low`, explicitly trigger retrieval for current facts instead of trusting name
84
+ recognition. Compare higher effort when retrieval still fails.
85
+ - Preserve decisions, constraints, open work, and exact details in compaction summaries.
86
+ - Append API history unchanged; use supported compaction instead of replaying thinking
87
+ against an edited prefix.
88
+ - At `xhigh`/`max`, budget tokens for thinking and the deliverable; compare `high` for
89
+ long outputs.
90
+ - Give dense-image work crop and zoom tools.
91
+
92
+ These are prompt and harness tuning choices, not changes to the configured seat's
93
+ effort or permissions. The Opus-specific advice below does not apply to this model.
94
+
95
+ ## Claude Opus 5
96
+
97
+ The following behavior claims and tuning recommendations apply to `claude-opus-5`.
98
+
99
+ ### When to add blocks
56
100
 
57
101
  - Long-horizon or autonomous work: give the full spec up front in one
58
102
  well-specified turn and run at a high effort. Do **not** add a self-check
@@ -68,7 +112,12 @@ pick the path.
68
112
  - Delegation: say when *not* to delegate, and cap the spawn count. The helm
69
113
  binding reaches for subagents readily — the reverse of the binding it replaced
70
114
  — and every spawn rebuilds context, reports back, and is then re-read, so
71
- unbounded delegation multiplies cost and latency. File-based memory and custom
115
+ unbounded delegation multiplies cost and latency. Where the harness offers
116
+ deterministic caps, prefer them to prose: under Claude Code and the Agent SDK
117
+ these are `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`,
118
+ `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and the SDK's `max_budget_usd` — a
119
+ limit the model cannot talk itself past. Confirm the harness version supports
120
+ them before relying on it. File-based memory and custom
72
121
  tools are the opposite case: they still need an explicit when-to-use trigger.
73
122
  - Autonomous runs with no human watching: say so. Otherwise it asks permission
74
123
  it does not need and blocks. Grant autonomy on minor choices (naming,
@@ -77,21 +126,18 @@ pick the path.
77
126
  - Progress reporting: require each claim to be traceable to a tool result from
78
127
  the session, and unverified work to be labeled as such.
79
128
 
80
- ## How to choose prompt shape
129
+ ### How to choose prompt shape
81
130
 
82
131
  - One bounded question with a self-contained packet → a single run. Default for
83
132
  review.
84
133
  - Independent workstreams → delegate, and prefer asynchronous subagents over
85
134
  spawn-and-block: long-lived agents keep their context instead of rebuilding it
86
135
  per subtask, and the orchestrator is not pinned to the slowest one.
87
- - Effort ladder `low`, `medium`, `high`, `xhigh`, `max` on the frontier, helm,
88
- and workhorse bindings; `xhigh` is the best setting for most coding and
89
- agentic work, `high` a sound default, `low` for cheap subagent scans. Start
90
- there and sweep *down* on a real eval set rather than reaching for the top: the
91
- lower rungs are unusually strong on the helm binding, higher effort up front
92
- often *reduces* turn count and total cost on agentic work, and some tasks land
93
- equally well a level down. Effort does not control response length — see
94
- Working rules.
136
+ - Start effort experiments at `high`; compare lower settings on representative
137
+ tasks and step up to `xhigh` for demanding coding or agentic work when quality
138
+ improves. Re-test inherited defaults. The configured seat's effort remains an
139
+ explicit workload choice. Effort does not control response length see Working
140
+ rules.
95
141
  - Per-model constraints differ across the `targets` bindings — thinking
96
142
  configuration, sampling parameters, and effort support are not uniform, and
97
143
  the sweep binding is the most restricted. On the helm binding, for instance,
@@ -100,14 +146,16 @@ pick the path.
100
146
  live surface before relying on it in a dispatch; do not assume the frontier
101
147
  binding's rules apply to the sweep one.
102
148
 
103
- ## Working rules
149
+ ### Working rules
104
150
 
105
151
  - Expect long turns. A single request on a hard task at high effort can run for
106
152
  minutes; plan timeouts, streaming, and progress UX around that rather than
107
153
  treating a quiet call as a hang.
108
154
  - Do not add "summarize every N tool calls" scaffolding — this tier narrates on
109
155
  its own. If it narrates too much for a coding agent, set a silence default
110
- instead: text only on a finding, a direction change, or a blocker.
156
+ instead: text only on a finding, a direction change, or a blocker. Describe the
157
+ cadence you want by example; a positive description of the style outperforms a
158
+ list of what not to do.
111
159
  - Length is a prompting lever, not an effort lever. This tier writes longer
112
160
  answers and longer files than its predecessors, and lowering `effort` does not
113
161
  reliably shorten visible output — only an explicit instruction does. Calibrate
@@ -121,6 +169,36 @@ pick the path.
121
169
  work they did not watch. Lead with the outcome; drop the working shorthand.
122
170
  - Do not show a remaining-context countdown. This tier can start conserving and
123
171
  suggest a fresh session instead of finishing.
172
+ - Re-validate prompt-side vision workarounds carried from older bindings; this
173
+ tier is strong on charts, documents, diagrams, and UI replication, and the
174
+ workaround may now be the thing costing quality. Tools that let it crop and
175
+ visually verify beat thinking alone here.
176
+ - Instruction following stays consistent across the full context window, so a
177
+ rule does not need restating near the end to survive a long session.
178
+
179
+ ### Running with thinking disabled
180
+
181
+ Disabling thinking is accepted only at `high` effort or below, and it is usually
182
+ the wrong lever: thinking on at `low` effort generally beats thinking off at
183
+ comparable cost. Reach for lower effort before reaching for the switch.
184
+
185
+ Two artifacts appear when it is off, and both are prompt-fixable:
186
+
187
+ - A tool call written as **user-facing text** instead of a structured call. The
188
+ turn completes, the call never runs, and in an agentic loop the leaked text
189
+ stays in history and contaminates later turns. Most common on tool-heavy work.
190
+ - Internal XML tags leaking into the visible response.
191
+
192
+ One instruction mitigates both — permission to speak before a call, an out when
193
+ no tool fits, and a general ban on internal tags:
194
+
195
+ > When you use a tool, you may say a brief sentence first. If no tool can express
196
+ > what the user asked for, say so instead of guessing. Do not include internal or
197
+ > system XML tags in your response.
198
+
199
+ Two traps. Naming the tags specifically is **less** effective than the general
200
+ form. And if a prompt anywhere tells this tier not to think or not to reason,
201
+ delete it: that instruction increases tag leakage rather than suppressing it.
124
202
 
125
203
  ## Prompt assembly checklist
126
204
 
@@ -128,14 +206,21 @@ pick the path.
128
206
  2. Name the boundaries — what to do freely, what to stop and ask about.
129
207
  3. Give each tool a when-to-call description.
130
208
  4. Say how progress claims must be grounded, and how the deliverable should read.
131
- 5. Delete the step-by-step scaffolding inherited from older models including
132
- any verify-your-work step and any encouragement to delegate then A/B the
133
- prompt with it removed before keeping either version.
209
+ 5. Apply the target model's section and check for contradictions. Compare changes
210
+ on the same tasks; remove inherited scaffolding only when the target benefits,
211
+ keeping required repository checks and permission boundaries intact.
134
212
 
135
213
  ## Sources
136
214
 
137
- Derived from the vendor's published guidance for the `targets` models above.
138
- When a `targets` model changes, re-derive this guide from current vendor
139
- guidance rather than editing around the old rules prompting guidance is
140
- version-bound. `launch/check-prompting-targets.sh` fails when the launch config
141
- binds a model this guide does not list.
215
+ The shared recipe is derived from `claude-prompting-best-practices`; the Fable 5.1
216
+ section from `prompting-claude-fable-5-1`; and the Opus 5 section from
217
+ `prompting-claude-opus-5`. `source_pins` records the exact bytes used for this
218
+ derivation. Fable 5.1 has its own prompting document; model names in `targets` do
219
+ not extend the Opus-specific behavior claims to other models.
220
+
221
+ When a `targets` model changes, re-derive its advice from its own current document
222
+ and check the shared recipe for conflicts.
223
+ `launch/check-prompting-targets.sh` fails when the launch config binds a model
224
+ this guide does not list; that check is about **naming**, and a model added to
225
+ `targets:` satisfies it forever. Whether the guidance was actually re-derived is
226
+ not decidable and is gated nowhere.
@@ -23,7 +23,7 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
23
23
 
24
24
  - FRONTIER: hardest bounded design, authority-changing decisions, triage, final verdicts.
25
25
  - HELM: standing main/judgment seat; orchestration and bounded escalation.
26
- - WORKHORSE: implementation volume and per-item judgments. SWEEP: cheap wide reads, candidate finding, mechanical passes.
26
+ - WORKHORSE: implementation volume and per-item judgments. SWEEP: read-only work applying one explicit rule to each item, returning ambiguity as an exception.
27
27
  - VERIFIER-A/B: different review kinds, preferably cross-family. INDEPENDENT-PR-REVIEWER: final review from a different family than the author.
28
28
 
29
29
  - Bind concrete models in Environment Binding and allocate by **difficulty × blast radius**. The main defaults to HELM; first-of-kind/authority-changing mains use FRONTIER at a session boundary; trivial work stays direct.
@@ -35,7 +35,8 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
35
35
 
36
36
  Main-context pollution is usually costlier than spawn overhead. Apply these gates in order; the first that fires decides:
37
37
 
38
- 1. **Independence:** verification or review always spawns; isolation is the purpose.
38
+ 1. **Independence:** verification and review go outside your own reasoning, not merely outside your conversation. A child carries the standing corpus on both hosts, except Claude's built-in `Explore` and `Plan`, which omit the CLAUDE.md hierarchy. Otherwise a Claude child starts fresh, while Codex `spawn_agent` forks by default — `fork_turns` defaults to `all`, so the child also holds the parent's turn input unless the call passes `none` or a turn count. What a spawn buys is graded by the seat — see Review Independence — never by the fact that it happened.
39
+ Verify a spawn from the artifact: Claude writes the child to its own `agent-<id>.jsonl` beside the session transcript; Codex writes a rollout whose header carries `parent_thread_id`, `agent_nickname`, `agent_path`, `agent_role`. Codex's `--json` stream cannot see a spawn at all — its `collab_tool_call` object is identical whether or not one occurred.
39
40
  2. **Parallelism:** independent items spawn in parallel with per-item tracking.
40
41
  3. **Residual context:** spawn work whose working log is much larger than the conclusion the main needs, such as broad reads, searches, tests, or implementation bursts.
41
42
  4. **Specifiability:** keep work local when it needs the main's live context or unresolved round-trips, especially deep debugging. Grind alone is not a FRONTIER reason.
@@ -46,6 +47,14 @@ Main-context pollution is usually costlier than spawn overhead. Apply these gate
46
47
  - Explicit no-fan-out overrides standing authorization.
47
48
  - Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — plus the FRONTIER disposition. A launch contract's `Delegation=off` lifts the spawn obligation, not the records.
48
49
 
50
+ ### Cost-Driven Down-Spawn (bounded implementation work)
51
+
52
+ For a unit already classified as bounded implementation work, this rule takes the place of gates 4 and 5 above; gates 1–3 and Escalation still come first, and an explicit no-fan-out instruction still wins. It is the measured text — apply it verbatim, do not paraphrase it:
53
+
54
+ > This rule applies at a work-unit boundary of bounded implementation work; an explicit instruction not to fan out always wins. Spawn a WORKHORSE for the unit when it has 5 or more items and is decision-complete, has a machine-checkable done-when, and is self-contained; otherwise do it inline. An unstated count is below 5.
55
+
56
+ Measured 2026-09-08 on the dependent L2 edit family with a claude-opus-5 (xhigh) parent and a claude-sonnet-5 WORKHORSE child: delegating a five-item unit saved about $0.05 per unit and a ten-item unit $0.14–0.18, net of the rule's own cost; a one-item unit cost $0.05 more delegated, and a three-item unit was unresolved at the registered sample. Untested sizes between and above the tested ones rest on the assumption that a saving present at 5 and 10 holds at 6–9 and beyond; the ordering with the gates above, the cost of reading this guide, and the rule's firing rate were not measured. Shipped by guide placement rather than into the global (decision D-20260908-2186cd).
57
+
49
58
  ## Delegation Mechanics And Teammate Persistence
50
59
 
51
60
  Delegate execution, not decisions. A unit is delegable only when it is decision-complete, self-containedly specifiable, machine-checkable at done-when, and bounded in blast radius. Delegated output is staged until the main accepts it — workers take no external irreversible actions — and handling (brief, verify, correct, integrate) must be clearly subordinate to the work itself. A SWEEP-bound unit applies one explicit rule per item and returns ambiguity as an exception, never resolved.
@@ -54,11 +63,14 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
54
63
  - Bundle related sub-floor tasks up to the decision-complete ceiling. A scout is read-only and reports file:line evidence for named pending decisions, probing the highest kill-risk unknown first.
55
64
  - Prompt constants, thresholds, signatures, and judgment criteria are decisions even when stored in code. Discard decision-tainted worker output when review would cost more than a clean re-dispatch.
56
65
  - Worker cost grows with request count × transcript prefix. Batch independent reads, minimize edit rounds, and dispatch independent workers/messages together.
66
+ - **Pin the tier before dispatch.** Unpinned, the tier is chosen once the work is in view and tracks task size rather than task difficulty. Claim a cost advantage only from evidence on this task.
57
67
  - Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
58
68
  - After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
59
69
  - Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
60
70
  - Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
61
71
  - Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
72
+ - Codex `spawn_agent` decides how much of the parent crosses: `fork_turns` defaults to `all`, and takes `none` or a turn count. A `SubagentStart` hook there receives `agent_type` and may return `continue: false`, so a tier rule can be enforced rather than stated.
73
+ - No per-spawn corpus suppression exists on either host: the subagent definition carries model and effort, not scope. Excluding the standing instructions is a process-level act — `claude --setting-sources ''`, or `CODEX_HOME` pointed at a directory holding only `auth.json` — and it removes the tier definitions with them, so a corpus-free reader and a pinned tier cannot come from one process. An emptied `CODEX_HOME` without `auth.json` fails 401; skills still load.
62
74
  - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
63
75
 
64
76
  ## Driving Codex CLI Directly
@@ -99,6 +111,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
99
111
  - Prompt caches are per model; each mid-session switch reprocesses the loaded transcript once. Batch work by model and switch at reset boundaries.
100
112
  - Prefer a spawned FRONTIER decision. Switch the main only when context fidelity outweighs handoff cost and the judgment cannot be delegated.
101
113
  - Avoid unplanned alternation. Planned escalate/return and explicit A/B comparisons are valid when each cache miss is budgeted.
114
+ - Forking preserves conversation content on both hosts and the prompt cache on only one: a Claude `--fork-session` at the same model reuses nearly all of it and loses it across models, while a Codex `exec fork` re-sends at any model. So "fork without changing the model" is a Claude rule; on Codex a fork is priced like a fresh dispatch.
102
115
 
103
116
  ## Cross-Verification Economy
104
117
 
@@ -120,7 +133,7 @@ How much independence a review actually bought, as an ordinal grade per reviewer
120
133
  | `perspective_floor` | otherwise — still a real review |
121
134
 
122
135
  - Only upward counts. A different-but-**lower** effort earns nothing and lands on the floor: cheaper is not another perspective.
123
- - **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen.
136
+ - **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen. An in-process subagent clears the conversation and keeps the standing instructions, so it satisfies isolation and still grades only by its seat — spawning is not itself a rung.
124
137
  - The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
125
138
  - Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
126
139
  - **Achieved is not available.** What can be projected before a review runs is `projected`; a clean verdict without a receipt evidencing a fresh dispatch, the declared packet, a non-empty result and the exact seat is `PROPOSED`, never ACHIEVED. A model echo is not a receipt.
@@ -222,14 +235,14 @@ Write for the next agent and re-verification, not narrative. Required content:
222
235
 
223
236
  This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
224
237
 
225
- Binding (2026-08-10):
238
+ Binding (2026-09-08):
226
239
 
227
240
  | Slot | Binding | Notes |
228
241
  |---|---|---|
229
- | FRONTIER | Claude Fable 5 · GPT-5.6 Sol (read-only; max default, task-fit effort including Ultra) | bounded hardest decisions and verdicts |
242
+ | FRONTIER | Claude Fable 5.1 · GPT-6 Astra (read-only; max default; launcher may explicitly select Ultra) | bounded hardest decisions and verdicts |
230
243
  | HELM | Claude Opus 5 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
231
- | WORKHORSE | Claude Opus 5 (medium) · GPT-5.6 Terra (high) | implementation and per-item judgment |
232
- | SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
244
+ | WORKHORSE | Claude Sonnet 5 (xhigh) · GPT-5.6 Terra (xhigh) | implementation and per-item judgment |
245
+ | SWEEP | Claude Haiku 4.5 (effort omitted) · GPT-5.6 Luna (max) | read-only; one explicit rule per item; not a rebind candidate |
233
246
  | VERIFIER-A | plain `codex exec` deep pass — GPT-5.6 Sol at ultra effort, packet on stdin (`-c service_tier="fast"` as explicit fast opt-in) | strongest single reader; cross-family from a Claude main |
234
247
  | VERIFIER-B | Claude Code ultracode workflow (keyword-opened, many-agent) | code/execution kind; fan-out counterpart |
235
248
  | INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
@@ -241,8 +254,8 @@ Binding (2026-08-10):
241
254
  Codex direct-drive (verified 0.144.1, 2026-07-12):
242
255
 
243
256
  - `codex-helm` defaults the HELM main to `--dangerously-bypass-approvals-and-sandbox`; explicit `--sandbox` wins in any flag order. Non-Ultra defaults native multi-agent off; explicit main Ultra defaults it on.
244
- - HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-5.6-sol`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
245
- - This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` omits fixed effort for native surfaces that accept overrides.
257
+ - HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-6-astra`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
258
+ - This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` pins the direct native FRONTIER default to max; launcher projections overwrite it from the selected tier.
246
259
  - `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
247
260
  - `claude-run` is its Claude-side twin and the command a composable review contract names for a panel dispatch on that host. Same shape: prompt on stdin, final message on stdout, exit status mirrored, `--model`/`--effort` pinning the seat, everything it does not recognise forwarded to `claude`. It denies the mutating tools by default, which is not the OS-level sandbox `codex-run` gets — do not read the two defaults as equivalent guarantees. Dispatch whatever command the contract names rather than the bare CLI: only the adapter can report what the dispatch actually did, and a review with no receipt stays PROPOSED.
248
261
 
@@ -250,21 +263,23 @@ Dispatch packets:
250
263
 
251
264
  | Target | Required packet / default |
252
265
  |---|---|
253
- | GPT-5.6 Sol FRONTIER | outcome, evidence, decision boundary, stop/verification; task-fit effort; read-only |
254
- | GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; high |
255
- | GPT-5.6 Luna SWEEP | exact search space, rules, ambiguity behavior, stop, output; low; no architecture/debugging |
266
+ | GPT-6 Astra FRONTIER | outcome, evidence, decision boundary, stop/verification; max default; read-only |
267
+ | GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; xhigh |
268
+ | GPT-5.6 Luna SWEEP | exact search space, one rule per item, ambiguity behavior, stop, output; max; read-only; no architecture/debugging |
256
269
  | Claude Opus 5 HELM | xhigh for agentic work; high minimum for sensitive judgment; lower only when bounded/cost-led |
257
- | Claude Opus 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; high default |
258
- | Claude Haiku 4.5 SWEEP | closed, high-volume, latency-sensitive work with exact schema/examples |
270
+ | Claude Sonnet 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; xhigh default |
271
+ | Claude Haiku 4.5 SWEEP | one explicit rule per item, read-only; effort parameter omitted; ambiguity returned as an exception |
259
272
 
260
273
  Use only task-relevant tools; parallelize independent calls. Worker report: `status`, `files_or_items_touched`, `evidence`, `verification`, `risks_or_escalations`. Official basis: OpenAI [model](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6), [migration](https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol), [prompting](https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6), [Codex models](https://learn.chatgpt.com/docs/models); Anthropic [subagents](https://code.claude.com/docs/en/sub-agents), [model effort](https://code.claude.com/docs/en/model-config).
261
274
 
262
275
  ## Evidence Base
263
276
 
264
- Single owner of numeric defaults; one production environment, 2026-07. Recalibration updates this table and dependent inline thresholds.
277
+ Single owner of numeric defaults. Dates and workload scopes belong to each observation; recalibration updates this table and dependent inline thresholds.
265
278
 
266
279
  | Evidence | Result / rule supported |
267
280
  |---|---|
281
+ | Claude M=40 confirmation (2026-09-06), adopted by owner correction (2026-09-08) | Sonnet 5/xhigh child under Opus 5/xhigh: KEEP confirmed on five fresh paired blocks; modelled cost-to-parity saving 45.5%, lower bound 40.4%. This is scoped cost evidence, not a general quality or billing guarantee. |
282
+ | Owner tier correction (2026-09-08), Codex discovery cells incomplete | Terra/xhigh is the measured experimental effort adopted by owner instruction, not a confirmed Codex KEEP verdict. The two HELM parent seats stay unchanged; SWEEP is not a rebind candidate and remains one-rule-per-item read-only work. |
268
283
  | 15 sessions, 3,758 requests, 10 switches | switches consumed 13.9% of uncached input; avoid unplanned switching |
269
284
  | 285-call limit incident | 208 post-limit dispatches and 34/35 lost items; breaker default 3 |
270
285
  | 99 staged reviews | 15.2% halted after most compute; resume-first |
@@ -274,3 +289,6 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
274
289
  | Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |
275
290
  | 1,075 sessions of 50+ requests, both hosts (2026-08-16; the earlier 62-session top-by-size sample gave ~1,800-2,000) | context grows ~2,400 tok/request (IQR 1,850-2,950), hosts within 7%, ~1,800 in 400+-request sessions; auto-compaction fires at 84-95% of window, never earlier |
276
291
  | 2 sessions decomposed by cost component (2026-08) | input 92-94% of cost, output 6-8%, cache hit 95-97%, uncached input 0.0%; an 867K→200K budget cuts cost per request ~4x |
292
+ | 4 dispatches over 3 situations built to trigger the Independence gate, plus a positive control (2026-09-01) | 0 spawns in the 3, 1 in the control; de-minimis absorbed all three and each inline answer was correct — a spawn mandate stated as always-fire did not fire |
293
+ | 60/150-file mechanical scan, N=5 on load-bearing cells (2026-09-02) | inline $0.627→$0.919; tier-pinned delegation $0.665→$0.921; unpinned +57-73%; an N=2 first reading of the same cells reported 19% and 36% savings that N=5 erased |
294
+ | fork cache reuse, both hosts (2026-09-02) | Claude same-model 98.9%, cross-model 0-26%; Codex 14-18% at any model (N=1 per Codex cell) — fork guidance is host-qualified |