agent-bios 0.14.0 → 0.16.0

package/codex/guides/claude-prompting.md

@@ -9,13 +9,26 @@ use_when:
   - porting a prompt written for an older claude model
   - deciding a reasoning-effort level for claude work
 core_rules:
+  - choose guidance by the actual target model — Fable 5.1 and Opus 5 need different progress, delegation, and verification tuning
   - state the goal, the constraints, and the reason behind the request; let the model choose the route
-  - de-prescribe ported prompts — step-by-step scaffolding written for older models reduces output quality on this tier
+  - compare inherited process scaffolding on the target model before keeping or removing it
   - put the full task specification in the first turn for long-horizon work rather than revealing it across turns
   - make tool descriptions prescriptive about when to call, not only what the tool does
   - require progress claims to be audited against a tool result from the same session
   - name the boundary explicitly — what to do without asking, and what to stop and ask about
+derived_at: 2026-09-07
+source_pins:
+  - doc: prompting-claude-opus-5
+    sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
+    pinned_at: 2026-09-07
+  - doc: claude-prompting-best-practices
+    sha256: f98aa130a7974b2edf98f8c3babe806ab140d5cdd3933a506f5211335b431c5f
+    pinned_at: 2026-09-07
+  - doc: prompting-claude-fable-5-1
+    sha256: 4aa645dd26fe9efebdaaff7462563bfac1f27782ce2d71dd5afffeaf02a80c62
+    pinned_at: 2026-09-07
 targets:
+  - claude-fable-5-1
   - claude-fable-5
   - claude-opus-5
   - claude-sonnet-5
@@ -24,6 +37,7 @@ verification_focus:
   - prompt changes are A/B'd against the prior scaffolding rather than assumed
   - effort changes are swept across levels on a real eval set, not chosen by reputation
   - per-model constraints are confirmed against the live surface before use
+  - model-specific advice stays within its named section, including after assembly
 ---
 
 # Claude Prompting Guide
@@ -33,26 +47,56 @@ composing a prompt for a claude-tier model — a review packet dispatched
 cross-family, a subagent brief, or the main's own instructions when the main is
 Claude.
 
-The central shift: this tier is more autonomous and more literal than its
-predecessors, and prompts written for older models are often too prescriptive —
-they measurably reduce output quality. Porting a prompt means removing
-scaffolding, not adding to it. State the goal and the constraints; let the model
-pick the path.
+Use the shared recipe and checklist together with the section for the model being
+prompted, even when a subagent uses a different model from the main. Model-specific
+tuning preserves the corpus's permission boundaries and required verification.
+
+| Target | Apply |
+| --- | --- |
+| `claude-fable-5-1` | Shared recipe and Claude Fable 5.1 |
+| `claude-opus-5` | Shared recipe and Claude Opus 5 |
+| `claude-fable-5`, `claude-sonnet-5`, `claude-haiku-4-5` | Shared recipe; consult the target's own guidance before borrowing another model's tuning |
 
 ## Default prompt recipe
 
-- `Goal` and the **reason behind it** — this tier connects a task to relevant
-  context when it knows the intent, instead of inferring intent on its own.
-  "I'm doing X for Y, who needs Z; with that in mind: …" outperforms the bare
-  request, most of all for long-running agents holding several workstreams.
+- `Goal` and the **reason behind it** — provide the audience, purpose, and relevant
+  context so the model does not have to infer the intent.
 - `Success criteria` — what done means and how it is checked.
-- `Constraints and boundaries` — say what not to do. This tier sometimes takes
-  unrequested-but-adjacent actions; naming the boundary is the fix.
+- `Constraints and boundaries` — state the permitted scope and approval conditions.
 - `Tools` — each description states **when to call it**, not only what it does.
-  Prescriptive trigger conditions give measurable lift here.
+  Name prerequisite retrieval and validation when correctness depends on them.
 - `Output` — the artifact shape and the register.
 
-## When to add blocks
+## Claude Fable 5.1
+
+- Begin effort experiments at `high`; compare supported levels afresh. Identical
+  effort names need not have identical costs across models.
+- Request brief start, progress, and final updates; first verify the client renders
+  updates and remove conflicting silence instructions.
+- Batch independent tool calls. Let the lead do independent work while subagents run.
+- Complete authorized requests, including promised next steps. State genuine approval
+  boundaries and whether a person is available; avoid unnecessary pauses.
+- Ask for literal prose and useful formatting. Demonstrate how retrieved quotations
+  should be marked and attributed.
+- Keep edits targeted and tests proportional to the requested behavior; report
+  unrelated issues separately.
+- At `low`, explicitly trigger retrieval for current facts instead of trusting name
+  recognition. Compare higher effort when retrieval still fails.
+- Preserve decisions, constraints, open work, and exact details in compaction summaries.
+- Append API history unchanged; use supported compaction instead of replaying thinking
+  against an edited prefix.
+- At `xhigh`/`max`, budget tokens for thinking and the deliverable; compare `high` for
+  long outputs.
+- Give dense-image work crop and zoom tools.
+
+These are prompt and harness tuning choices, not changes to the configured seat's
+effort or permissions. The Opus-specific advice below does not apply to this model.
+
+## Claude Opus 5
+
+The following behavior claims and tuning recommendations apply to `claude-opus-5`.
+
+### When to add blocks
 
 - Long-horizon or autonomous work: give the full spec up front in one
   well-specified turn and run at a high effort. Do **not** add a self-check
@@ -68,7 +112,12 @@ pick the path.
 - Delegation: say when *not* to delegate, and cap the spawn count. The helm
   binding reaches for subagents readily — the reverse of the binding it replaced
   — and every spawn rebuilds context, reports back, and is then re-read, so
-  unbounded delegation multiplies cost and latency. File-based memory and custom
+  unbounded delegation multiplies cost and latency. Where the harness offers
+  deterministic caps, prefer them to prose: under Claude Code and the Agent SDK
+  these are `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`,
+  `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and the SDK's `max_budget_usd` — a
+  limit the model cannot talk itself past. Confirm the harness version supports
+  them before relying on it. File-based memory and custom
   tools are the opposite case: they still need an explicit when-to-use trigger.
 - Autonomous runs with no human watching: say so. Otherwise it asks permission
   it does not need and blocks. Grant autonomy on minor choices (naming,
@@ -77,21 +126,18 @@ pick the path.
 - Progress reporting: require each claim to be traceable to a tool result from
   the session, and unverified work to be labeled as such.
 
-## How to choose prompt shape
+### How to choose prompt shape
 
 - One bounded question with a self-contained packet → a single run. Default for
   review.
 - Independent workstreams → delegate, and prefer asynchronous subagents over
   spawn-and-block: long-lived agents keep their context instead of rebuilding it
   per subtask, and the orchestrator is not pinned to the slowest one.
-- Effort ladder — `low`, `medium`, `high`, `xhigh`, `max` on the frontier, helm,
-  and workhorse bindings; `xhigh` is the best setting for most coding and
-  agentic work, `high` a sound default, `low` for cheap subagent scans. Start
-  there and sweep *down* on a real eval set rather than reaching for the top: the
-  lower rungs are unusually strong on the helm binding, higher effort up front
-  often *reduces* turn count and total cost on agentic work, and some tasks land
-  equally well a level down. Effort does not control response length — see
-  Working rules.
+- Start effort experiments at `high`; compare lower settings on representative
+  tasks and step up to `xhigh` for demanding coding or agentic work when quality
+  improves. Re-test inherited defaults. The configured seat's effort remains an
+  explicit workload choice. Effort does not control response length — see Working
+  rules.
 - Per-model constraints differ across the `targets` bindings — thinking
   configuration, sampling parameters, and effort support are not uniform, and
   the sweep binding is the most restricted. On the helm binding, for instance,
@@ -100,14 +146,16 @@ pick the path.
   live surface before relying on it in a dispatch; do not assume the frontier
   binding's rules apply to the sweep one.
 
-## Working rules
+### Working rules
 
 - Expect long turns. A single request on a hard task at high effort can run for
   minutes; plan timeouts, streaming, and progress UX around that rather than
   treating a quiet call as a hang.
 - Do not add "summarize every N tool calls" scaffolding — this tier narrates on
   its own. If it narrates too much for a coding agent, set a silence default
-  instead: text only on a finding, a direction change, or a blocker.
+  instead: text only on a finding, a direction change, or a blocker. Describe the
+  cadence you want by example; a positive description of the style outperforms a
+  list of what not to do.
 - Length is a prompting lever, not an effort lever. This tier writes longer
   answers and longer files than its predecessors, and lowering `effort` does not
   reliably shorten visible output — only an explicit instruction does. Calibrate
@@ -121,6 +169,36 @@ pick the path.
   work they did not watch. Lead with the outcome; drop the working shorthand.
 - Do not show a remaining-context countdown. This tier can start conserving and
   suggest a fresh session instead of finishing.
+- Re-validate prompt-side vision workarounds carried from older bindings; this
+  tier is strong on charts, documents, diagrams, and UI replication, and the
+  workaround may now be the thing costing quality. Tools that let it crop and
+  visually verify beat thinking alone here.
+- Instruction following stays consistent across the full context window, so a
+  rule does not need restating near the end to survive a long session.
+
+### Running with thinking disabled
+
+Disabling thinking is accepted only at `high` effort or below, and it is usually
+the wrong lever: thinking on at `low` effort generally beats thinking off at
+comparable cost. Reach for lower effort before reaching for the switch.
+
+Two artifacts appear when it is off, and both are prompt-fixable:
+
+- A tool call written as **user-facing text** instead of a structured call. The
+  turn completes, the call never runs, and in an agentic loop the leaked text
+  stays in history and contaminates later turns. Most common on tool-heavy work.
+- Internal XML tags leaking into the visible response.
+
+One instruction mitigates both — permission to speak before a call, an out when
+no tool fits, and a general ban on internal tags:
+
+> When you use a tool, you may say a brief sentence first. If no tool can express
+> what the user asked for, say so instead of guessing. Do not include internal or
+> system XML tags in your response.
+
+Two traps. Naming the tags specifically is **less** effective than the general
+form. And if a prompt anywhere tells this tier not to think or not to reason,
+delete it: that instruction increases tag leakage rather than suppressing it.
 
 ## Prompt assembly checklist
 
@@ -128,14 +206,21 @@ pick the path.
 2. Name the boundaries — what to do freely, what to stop and ask about.
 3. Give each tool a when-to-call description.
 4. Say how progress claims must be grounded, and how the deliverable should read.
-5. Delete the step-by-step scaffolding inherited from older models — including
-   any verify-your-work step and any encouragement to delegate — then A/B the
-   prompt with it removed before keeping either version.
+5. Apply the target model's section and check for contradictions. Compare changes
+   on the same tasks; remove inherited scaffolding only when the target benefits,
+   keeping required repository checks and permission boundaries intact.
 
 ## Sources
 
-Derived from the vendor's published guidance for the `targets` models above.
-When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound. `launch/check-prompting-targets.sh` fails when the launch config
-binds a model this guide does not list.
+The shared recipe is derived from `claude-prompting-best-practices`; the Fable 5.1
+section from `prompting-claude-fable-5-1`; and the Opus 5 section from
+`prompting-claude-opus-5`. `source_pins` records the exact bytes used for this
+derivation. Fable 5.1 has its own prompting document; model names in `targets` do
+not extend the Opus-specific behavior claims to other models.
+
+When a `targets` model changes, re-derive its advice from its own current document
+and check the shared recipe for conflicts.
+`launch/check-prompting-targets.sh` fails when the launch config binds a model
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.

package/codex/guides/cli-multi-model-workflow.md

@@ -23,7 +23,7 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
 
 - FRONTIER: hardest bounded design, authority-changing decisions, triage, final verdicts.
 - HELM: standing main/judgment seat; orchestration and bounded escalation.
-- WORKHORSE: implementation volume and per-item judgments. SWEEP: cheap wide reads, candidate finding, mechanical passes.
+- WORKHORSE: implementation volume and per-item judgments. SWEEP: read-only work applying one explicit rule to each item, returning ambiguity as an exception.
 - VERIFIER-A/B: different review kinds, preferably cross-family. INDEPENDENT-PR-REVIEWER: final review from a different family than the author.
 
 - 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
 
 Main-context pollution is usually costlier than spawn overhead. Apply these gates in order; the first that fires decides:
 
-1. **Independence:** verification or review always spawns; isolation is the purpose.
+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.
+   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.
 2. **Parallelism:** independent items spawn in parallel with per-item tracking.
 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.
 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
 - Explicit no-fan-out overrides standing authorization.
 - 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.
 
+### Cost-Driven Down-Spawn (bounded implementation work)
+
+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:
+
+> 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.
+
+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).
+
 ## Delegation Mechanics And Teammate Persistence
 
 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-
 - 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.
 - 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.
 - Worker cost grows with request count × transcript prefix. Batch independent reads, minimize edit rounds, and dispatch independent workers/messages together.
+- **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.
 - 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.
 - 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.
 - 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.
 - 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.
 - 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.
+- 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.
+- 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.
 - Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
 
 ## Driving Codex CLI Directly
@@ -99,6 +111,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
 - Prompt caches are per model; each mid-session switch reprocesses the loaded transcript once. Batch work by model and switch at reset boundaries.
 - Prefer a spawned FRONTIER decision. Switch the main only when context fidelity outweighs handoff cost and the judgment cannot be delegated.
 - Avoid unplanned alternation. Planned escalate/return and explicit A/B comparisons are valid when each cache miss is budgeted.
+- 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.
 
 ## Cross-Verification Economy
 
@@ -120,7 +133,7 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 | `perspective_floor` | otherwise — still a real review |
 
 - Only upward counts. A different-but-**lower** effort earns nothing and lands on the floor: cheaper is not another perspective.
-- **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.
+- **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.
 - The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
 - Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
 - **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:
 
 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.
 
-Binding (2026-08-10):
+Binding (2026-09-08):
 
 | Slot | Binding | Notes |
 |---|---|---|
-| FRONTIER | Claude Fable 5 · GPT-5.6 Sol (read-only; max default, task-fit effort including Ultra) | bounded hardest decisions and verdicts |
+| FRONTIER | Claude Fable 5.1 · GPT-6 Astra (read-only; max default; launcher may explicitly select Ultra) | bounded hardest decisions and verdicts |
 | 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 |
-| WORKHORSE | Claude Opus 5 (medium) · GPT-5.6 Terra (high) | implementation and per-item judgment |
-| SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (low) | clear repeatable scans and mechanical work |
+| WORKHORSE | Claude Sonnet 5 (xhigh) · GPT-5.6 Terra (xhigh) | implementation and per-item judgment |
+| SWEEP | Claude Haiku 4.5 (effort omitted) · GPT-5.6 Luna (max) | read-only; one explicit rule per item; not a rebind candidate |
 | 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 |
 | VERIFIER-B | Claude Code ultracode workflow (keyword-opened, many-agent) | code/execution kind; fan-out counterpart |
 | INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
@@ -241,8 +254,8 @@ Binding (2026-08-10):
 Codex direct-drive (verified 0.144.1, 2026-07-12):
 
 - `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.
-- 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.
-- 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.
+- 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.
+- 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.
 - `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
 - `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.
 
@@ -250,21 +263,23 @@ Dispatch packets:
 
 | Target | Required packet / default |
 |---|---|
-| GPT-5.6 Sol FRONTIER | outcome, evidence, decision boundary, stop/verification; task-fit effort; read-only |
-| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; high |
-| GPT-5.6 Luna SWEEP | exact search space, rules, ambiguity behavior, stop, output; low; no architecture/debugging |
+| GPT-6 Astra FRONTIER | outcome, evidence, decision boundary, stop/verification; max default; read-only |
+| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; xhigh |
+| GPT-5.6 Luna SWEEP | exact search space, one rule per item, ambiguity behavior, stop, output; max; read-only; no architecture/debugging |
 | Claude Opus 5 HELM | xhigh for agentic work; high minimum for sensitive judgment; lower only when bounded/cost-led |
-| Claude Opus 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; high default |
-| Claude Haiku 4.5 SWEEP | closed, high-volume, latency-sensitive work with exact schema/examples |
+| Claude Sonnet 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; xhigh default |
+| Claude Haiku 4.5 SWEEP | one explicit rule per item, read-only; effort parameter omitted; ambiguity returned as an exception |
 
 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).
 
 ## Evidence Base
 
-Single owner of numeric defaults; one production environment, 2026-07. Recalibration updates this table and dependent inline thresholds.
+Single owner of numeric defaults. Dates and workload scopes belong to each observation; recalibration updates this table and dependent inline thresholds.
 
 | Evidence | Result / rule supported |
 |---|---|
+| 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. |
+| 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. |
 | 15 sessions, 3,758 requests, 10 switches | switches consumed 13.9% of uncached input; avoid unplanned switching |
 | 285-call limit incident | 208 post-limit dispatches and 34/35 lost items; breaker default 3 |
 | 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
 | Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |
 | 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 |
 | 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 |
+| 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 |
+| 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 |
+| 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 |

package/codex/guides/gpt-prompting.md

@@ -9,20 +9,30 @@ use_when:
   - porting a prompt written for an older gpt model
   - deciding a reasoning-effort level for gpt work
 core_rules:
+  - apply the shared recipe and only the section for the actual target model — GPT-5.6 and GPT-6 Astra have different prompting needs
   - describe the destination, not the route — state outcome, success bar, real constraints, and available evidence
-  - simplify before adding; remove one group of instructions, examples, or tools at a time and re-run the same evals
   - keep only what changes behavior; cut repeated statements, style rules, and examples that do not
   - replace blanket ALWAYS/NEVER with decision rules naming the condition each choice applies under
   - fix the prompt before raising effort — weak output usually means a missing success criterion, dependency rule, tool-routing rule, or verification loop
   - prompting habits carried from older gpt models cost tokens and can cost accuracy
+derived_at: 2026-09-07
+source_pins:
+  - doc: prompt-guidance-gpt-5p6
+    sha256: 46181efec9fd1160ef537b0379282a14c1ba32380f2f8149a805128253c1115a
+    pinned_at: 2026-09-07
+  - doc: model-guidance-gpt-6-astra
+    sha256: 2a59b26078e001a4e4e3da10693e80ad5ee1c02cbe472afa6b682308f27b8b22
+    pinned_at: 2026-09-07
 targets:
+  - gpt-6-astra
   - gpt-5.6-sol
   - gpt-5.6-terra
   - gpt-5.6-luna
 verification_focus:
   - prompt changes are validated by re-running the same evals, not by inspection
   - removals are tested one group at a time so the cause of a delta is known
-  - effort changes are compared against the baseline and one level lower
+  - effort changes use settings the target model supports and are compared against the baseline
+  - model-specific advice is checked against its own pinned source, including autonomy, writing style, delegation, and verification
 ---
 
 # GPT Prompting Guide
@@ -32,14 +42,79 @@ composing a prompt for a gpt-tier model — a review packet dispatched
 cross-family, a subagent brief, or the main's own instructions when the main is
 Codex.
 
-The current gpt tier is more concise and more self-directing than its
-predecessors, so the failure mode has inverted: the usual defect is now an
-over-specified prompt, not an under-specified one. Leaner system prompts
-measured roughly +10–15% eval score at 41–66% fewer tokens and 33–67% lower
-cost in the vendor's own coding-agent sample — directional, and worth
-validating on your own workload rather than taking on faith.
-
-## Default prompt recipe
+Use the shared recipe below together with the section for the actual target model.
+The model being prompted decides the section, including when it is a subagent on a
+different model from the main. These sections tune prompts within the existing
+permission policy; they do not change tool permissions or approval requirements.
+
+| Target | Apply | Pinned source |
+| --- | --- | --- |
+| `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` | GPT-5.6 | `prompt-guidance-gpt-5p6` |
+| `gpt-6-astra` | GPT-6 Astra | `model-guidance-gpt-6-astra` |
+
+## GPT-5.6
+
+- **Simplify first.** State the outcome, constraints, evidence, and completion bar,
+  then leave the model room to choose its path. Start from a working prompt; remove
+  one group of repeated instructions, examples, or irrelevant tools at a time and
+  re-run the same evals. Keep a process instruction when it changes behavior.
+- **Calibrate brevity.** GPT-5.6 tends to be more concise than GPT-5.5. Re-test broad
+  brevity instructions before carrying them over; they can make answers too thin.
+  Keep them when they produce the required result. Where the API exposes
+  `text.verbosity`, use it for the default detail level and the prompt for the
+  task's length, structure, and required content. Shorten repetition before evidence,
+  decisions, caveats, or next actions.
+- **Define collaboration separately from tone.** Briefly name when to ask, assume,
+  take initiative, and explain uncertainty. Distinguish inspection or planning
+  requests from requests to implement. Name safe local actions and approval
+  boundaries once so ordinary in-scope work does not pause unnecessarily.
+- **Tune effort after the prompt.** Preserve the current effective effort as the
+  baseline, then compare it and one supported level lower on representative tasks.
+  Use `low` when latency matters and quality holds; `medium` is a balanced starting
+  point. Use `high`/`xhigh` when evals show a gain, and reserve `max` for the hardest
+  quality-first work. Verify availability against the active model and host.
+
+## GPT-6 Astra
+
+- **Initiative and follow-through.** Astra is more likely to ask a question when
+  input could materially change the result. For action requests, prompt it to infer
+  routine details from context and complete authorized work, including validation,
+  before answering. A plan or an offer to continue does not complete an action
+  request. Ask when missing information changes the outcome; continue independent
+  authorized work while waiting. If approval is required for a later step, prepare
+  the concrete, reviewable result first. Keep existing permission boundaries and
+  avoid adding approval steps based only on hypothetical risk.
+- **Instruction and skill sensitivity.** Audit the loaded skills and instruction
+  files for unclear or conflicting guidance. Make explicit user instructions take
+  precedence over skill workflow preferences within higher-priority instructions
+  and permission constraints. When a skill causes a pause, an approval request, or
+  unfinished work, identify and link the exact skill file, quote the relevant rule,
+  and explain whether it is explicit or an interpretation. Do not turn an optional
+  guideline into a new requirement.
+- **Writing style.** Astra tends toward detailed responses, lists, tables, and
+  recurring phrases. Specify the desired length and structure for the audience.
+  For plain prose, request concise paragraphs, familiar words, active verbs, and
+  the main point first. Use lists when comparison or sequence benefits; retain
+  technical detail needed to assess the result. Name unwanted stock phrases or
+  formulaic contrasts when they recur rather than assuming GPT-5.6's brevity bias.
+- **Subagent delegation.** Astra may delegate less often than a workflow needs.
+  State when independent work should be delegated, the intended amount of
+  parallelism, each subagent's scope, and when to keep work local. Use the existing
+  spawn gates, available seats, and budget; a generic instruction to be proactive
+  does not specify delegation. Require readable inter-agent messages with correct
+  spacing.
+- **Testing and verification.** Astra can over-test small coding changes. Name the
+  relevant checks and completion bar. Avoid tests that only mirror a reversible,
+  low-impact implementation. Complete required checks; broaden or repeat them only
+  when a new edit, a failure, or an unresolved concern warrants it. This calibration
+  preserves required repository gates and validation of the actual changed behavior.
+- **Reasoning effort.** Astra does not support `none`. When migrating a prompt from
+  `none` or `minimal`, begin with `low` and compare results; otherwise preserve the
+  current effective effort. Check the active model and host for supported settings
+  instead of reusing a family-wide effort ladder. Fix a missing success criterion,
+  dependency rule, or verification loop before increasing effort.
+
+## Shared prompt recipe
 
 Compose in this order; omit any block that would not change the artifact.
 
@@ -59,8 +134,7 @@ Compose in this order; omit any block that would not change the artifact.
 - Coding and debugging: name the validation to run after changes — targeted
   tests for the changed behavior, type/lint checks, build, a minimal smoke test.
   Require prerequisite lookups before edits.
-- Review: no vendor task guidance exists for review specifically. Carry the
-  general rules and be explicit about the evidence bar and the verdict shape; a
+- Review: carry the general rules and be explicit about the evidence bar and the verdict shape; a
   reviewer with no stated bar defaults to plausible-sounding findings.
 - Research and grounded work: cite only retrieved sources, attach citations to
   the claims they support, and label inference separately from supported fact.
@@ -77,23 +151,55 @@ Compose in this order; omit any block that would not change the artifact.
   This is the default for review.
 - Work that divides into independent workstreams → fan-out. Parallelize
   independent reads; keep dependent steps sequential.
-- Effort ladder — `none`, `low`, `medium`, `high`, `xhigh`, `max` are all valid.
-  Hold the current binding as the baseline, then test it and one level lower on
-  representative tasks: `low` for latency-sensitive work, `medium` as the
-  balanced default, `high`/`xhigh` only where evals show real gain, `max`
-  reserved for the hardest quality-first work and compared against `xhigh`.
+- Choose reasoning effort using the target model's section above and the settings
+  the active model and host actually support.
 - Prefer a self-contained packet over resuming a long history: it is cheaper to
   reason about and cheaper to cache.
 
+## Programmatic tool calling
+
+A bounded stage where code processes several tool results and returns a much smaller
+structured result. The qualifier is **reduction**, not parallelism: multiple, parallel,
+or dependent calls alone do not justify it.
+
+- Use it for filtering, joining, sorting, ranking, deduplication and aggregation;
+  batching across many similar records; repeated deterministic validation; and large
+  structured results reducible to a compact schema.
+- Prefer direct calls when one call suffices, when intermediate outputs are already
+  small, when each result may change the next decision, when an action needs approval,
+  when the answer must preserve citations or native artifacts, or when semantic
+  judgment sits between calls.
+- A generic "use programmatic tool calling efficiently" does nothing. State the bounded
+  stage, the eligible tools, the output schema, the retry limit, the stop condition, and
+  the handoff back to direct judgment. If both routes are needed, define one handoff and
+  say not to switch routes or repeat completed work.
+- **Test both outputs.** The program's result and the final assistant message are
+  separate; a program can return the right records while the message drops a required
+  field, citation, or caveat.
+- Compare the two routes on the same tasks, and count lower token/latency/cost as an
+  improvement only when the response still passes the existing evals.
+
 ## Working rules
 
 - One clear task per run, with an explicit output contract.
+- **Read the assembled prompt for contradictions.** This tier follows a prompt contract
+  closely, so two rules that disagree destabilize it more than a missing rule does —
+  the opposite of the intuition that more instruction is safer.
+- State each authority rule once. Repeating "ask first", "do not mutate", or "wait for
+  approval" produces approval requests for safe, expected actions.
+- Name the current layer of work — research, design, implementation, review, external
+  coordination — on long-running tasks, so the model does not move between layers
+  silently.
+- Persisted reasoning is not a free optimization. It helps while the objective and
+  priorities hold; once they move, stale reasoning adds tokens and anchors the model to
+  a superseded approach. Compact at milestones, not every turn, and treat compacted
+  items as opaque.
+- Preserve explicit user values. Where the right value is implicit, give decision
+  criteria and let the model reason from context or schema rather than installing
+  universal defaults or keyword maps.
 - Keep reusable prefixes stable and avoid churn in large system prompts. Add
   explicit cache breakpoints only where they measurably improve cache behavior —
-  a cache write costs 1.25× the uncached input rate, so read the cached-token
-  and cache-write counters before adding one.
-- Do not say "be concise" reflexively. This tier is concise by default, and the
-  instruction can push responses past useful into thin.
+  inspect the active model's cache usage and cost before adding one.
 - After each tool result, ask whether the core request can now be answered with
   useful evidence. If yes, answer.
 - Render any visual artifact before finalizing; inspect layout, clipping,
@@ -105,14 +211,28 @@ Compose in this order; omit any block that would not change the artifact.
 2. Add role, goal, real constraints, and the output shape.
 3. Add only the tools the task needs, each with when-to-use and error behavior.
 4. Add stop rules and the verification the task must pass.
-5. Delete every line that would not change the artifact if removed, then re-read
-   for instructions inherited from older-model habits.
+5. Apply the matching model section. Re-read for contradictions and rules inherited
+   from a different model; validate targeted changes with the same representative cases.
+
+## Evidence base
+
+The vendor's GPT-5.6 coding-agent sample reported roughly +10–15% eval score,
+41–66% fewer total tokens, and 33–67% lower cost with leaner system prompts
+(`prompt-guidance-gpt-5p6`, pinned 2026-09-07). These are directional results for
+that sample, not Astra measurements or promised gains on another workload.
 
 ## Sources
 
-Derived from the vendor's published prompting guidance for the `targets` models
-above. When a `targets` model changes, re-derive this guide from current vendor
-guidance rather than editing around the old rules — prompting guidance is
-version-bound, and the previous generation's advice inverted on this one.
+The GPT-5.6 section is derived from `prompt-guidance-gpt-5p6`; the GPT-6 Astra
+section from `model-guidance-gpt-6-astra`. The shared recipe retains task, evidence,
+tool, and validation practices from the GPT-5.6 guidance and the corpus; model
+behavior claims belong only to their matching section. `source_pins` records the
+exact bytes used for this derivation so later vendor edits can be detected.
+
+When a `targets` model changes, re-derive its section from the matching current
+document, check the shared rules for contradictions, and re-run representative
+evals rather than extending another model's behavior claims to it.
 `launch/check-prompting-targets.sh` fails when the launch config binds a model
-this guide does not list.
+this guide does not list; that check is about **naming**, and a model added to
+`targets:` satisfies it forever. Whether the guidance was actually re-derived is
+not decidable and is gated nowhere.