agent-bios 0.11.0 → 0.12.0

package/README.md

@@ -24,7 +24,7 @@ Two layers:
 - **Every span we write into a file we do not own has a remover** — the Codex config block, the settings hook registrations, the `AGENTS.md` central region and the zsh hook line each sit in a span identifiable as ours (a marker pair, a tagged line, or a manifest name), and `uninstall` removes exactly those and nothing around them. The entry `CLAUDE.md`/`AGENTS.md` are seeded once and then yours: the corpus is assembled under `central/` and the entry file only imports it, so your own additions are never mixed with ours and never removed with them. `uninstall` is a security operation — everything of ours goes, and what it took leaves as one archive you can hand off or delete.
 - **Metadata selects, observation authorizes** — a record of what was promoted can propose an irreversible act but never authorize one; it has never seen the machine it will run on. Clearing a user's personal copy of a promoted learning asks the deployed corpus whether the replacement is really there, excludes the copy being deleted from that evidence, and keeps the copy on any uncertainty: a kept duplicate is redundant, a wrong removal is data loss.
 - **The deployment outlives the act that made it** — a command's success says nothing about which version landed; a cached package can serve the previous one at exit 0. So the deployed state carries its own version marker and `status` reads that marker rather than the source it was launched from. With no marker the answer is `unknown`, never a guess.
-- **`Evidence Base` (per guide) is the single owner of numbers.** Measure with `session-cost.py`.
+- **`Evidence Base` (per guide) is the single owner of numbers.** Measure with `session-cost.py` (`agent-bios cost` on an installed package).
 - **English is canonical and installed; Korean (`ko/`) is reference only.** The harness loads only fixed-name English files; the installer deploys English only.
 
 ## Layout
@@ -42,7 +42,7 @@ Two layers:
 | `wrappers/` | internal Codex wrappers, deployed to `$CODEX_HOME/bin/` |
 | `gates/` | author-side verification (mirror generation, parity, lexicon, payload, assembler scenarios) — reachable only from a repo checkout, and `check-package.sh` fails if any of it enters the npm payload |
 | `ontology/` | what a change obliges elsewhere — entities, obligation edges, and the service's routes, held against real source by `check-ontology.py`. `instances/graph.json` is canonical; `LEXICON.md`, the RDF views, the HTML map, and the competency/extension docs are generated from it |
-| `install.sh`, `session-cost.py` | the CLI and the cost meter — the two things you run directly |
+| `install.sh`, `session-cost.py` | the CLI and the cost meter — the two things you run directly (`agent-bios` and `agent-bios cost` once installed) |
 | `decisions/` | the decision record for developing this repo — what was decided and which alternative it closed; author-side, never shipped |
 | `packages/` | authored corpus packages, organized by package identity rather than by concept home |
 | `.githooks/` | the pre-commit hook that runs the gates against the index, enabled per clone with `core.hooksPath` |
@@ -95,11 +95,11 @@ agent-bios uninstall   # remove deployed files and the zsh hook
 
 From a git clone, run `./install.sh install` directly (the same CLI). `install` respects `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `AGENT_LAUNCH_VENV`, and `ZDOTDIR`; `--dry-run` prints actions without changing anything. Deploy to **every active environment in one sitting** — a partial deploy leaves a shared global pointing at a guide some environment lacks; globals are English only. Replaced files are backed up under `~/.local/share/agent-bios/backups/<timestamp>/`, and the installed set is recorded in a manifest that `uninstall` consumes. Those copies are **a manual escape hatch, not a restore mechanism**: nothing reads them back, so recovering from one means copying files yourself. The supported paths are the ones `agent-bios help` prints — a clone rolls corpus content back to a registered version, an npm install rolls the whole package back by version — and `uninstall` emits one archive of everything it removed. The backups exist for the case those three do not cover: the exact bytes that were on disk before a particular install. The published npm package ships only the deploy set (never `settings.json`, `config.toml`, `ko/`, or `benchmarks/`).
 
-In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`launch/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native and the deep route — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, deep via plain `codex exec -m <frontier model> -c model_reasoning_effort="ultra"` with a self-contained packet on stdin — `-c service_tier="fast"` is the explicit faster, shallower opt-in); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, deep via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
+In a TTY, zero-argument `codex` or `claude` opens the launch preflight. Every arrow-key TUI selection screen keeps the complete current setup in a fixed top panel, followed by the highlighted option's description and then the option list. Move with Up/Down, select with Enter, use Esc to return to the previous menu, and use `q` to cancel; Esc at the mode root also cancels. Each tier's model is chosen from the host's configured catalog, or via **Other** to type any model id the backend accepts; that text input preserves values that start with `q`, so Esc or Ctrl-C cancels immediately there, while submitting `q` cancels after Enter. The Textual preflight reflows to the terminal size, so there is no fixed minimum geometry. The root menu picks a mode — **Software Engineer** (repo-scoped work that defers to the project's own AGENTS.md/CLAUDE.md: **Vanilla**, the bare CLI with no launch contract, tier bindings, or applied permissions, plus **Custom**; SE-specific review defaults arrive later), **Builder** (the tier presets: Balanced, Deep review, Fast batch, Solo with delegation off, plus Custom), **Session distill** — then a preset within it. Two entries below the modes act on the installation rather than the launch: **Corpus packages** opens a checklist of the optional domain packages (core + infra always install) and, on Apply, hands the exact checked set to `agent-bios onboard --domains` — the installer alone deploys, runs the activation canary, and records the outcome, which the status panel then reports, loudly when an apply failed. **Language** switches the interface text between English, 한국어, and 日本語 and persists the choice in your own `launcher.local.toml`; it changes the launcher's own screens only, since the corpus the models consume is English-unified. Select **Custom** (in Software Engineer or Builder) to open a persistent settings hub for the main tier, review setup, host policy, and each tier binding. Every edit returns to that hub; **Start with these settings** is the final launch confirmation, **Save these settings globally and start** additionally persists the setup as a named preset (with host-scoped tier overrides) in your user config for reuse elsewhere, and **Exit without launching** cancels the launch. The rich preflight runs from a managed virtualenv (`launch/provision-venv.sh`, at `~/.local/share/agent-launch/venv`) that the launcher re-execs into on the interactive path; when that venv is unavailable, or the call is non-interactive, or `TERM` is `dumb`/unset, the launcher falls back to numbered prompts, where `b` is the back command. Backend command names are resolved from the calling environment's `PATH`; shell functions are not re-entered. Codex child bindings are materialized as session-selected agent configs under the user cache, while Claude receives model and effort in `--agents` JSON when delegation is enabled. Review runs cross-family by default (`review_family`, default `cross`; `same` restores today's same-family projection): because the main's tiers are one model family, every dispatchable review route — native and the deep route — runs on the opposite family. The exception is `slash-review`, the host's own built-in review command (`/code-review` on Claude, with `ultra` for its deep multi-agent pass; `/review` on Codex): it needs no dependency and always resolves, but being the main's own command it cannot be dispatched cross-family, so under `cross` it runs as the same-family floor and its verdicts are labeled PROPOSED. A Claude main dispatches gpt/codex review (native via the `codex-run` reviewer wrapper resolved under `$CODEX_HOME/bin`, deep via plain `codex exec -m <frontier model> -c model_reasoning_effort="ultra"` with a self-contained packet on stdin — `-c service_tier="fast"` is the explicit faster, shallower opt-in); a Codex main dispatches Anthropic/Claude review (native via `claude -p --permission-mode plan`, deep via the `claude` CLI headless with the keyword `ultracode` in the prompt, which is what opens Claude Code's dynamic workflow for that turn). The concrete reviewer command, resolved absolute path, and opposite-family tier bindings are named in the injected session-start contract; cross-family reviewers are dispatched as read-only subprocesses, not CLI-native subagents, since neither CLI hosts the other family as a native subagent. When a cross-family route is unavailable at launch or unauthenticated at use time it degrades to same-family native subagent review labeled PROPOSED (family collapse) rather than blocking; a requested non-none review with no cross-family route and no same-family fallback (delegation off) stays fail-closed. A reviewer this launcher has never seen is yours to add: **Register another reviewer…** in the review editor asks for the descriptor a method needs, proves the candidate by running it through the real config reader before a byte is written, and appends it to `review-methods.local.toml` beside your config — a file the installer never deploys, verifies, or overwrites, whose entries face exactly the validation a shipped one does and whose name may not shadow a shipped method. A refusal shows the reader's own message and leaves that file byte-identical. Review setup means configured/requested; this launcher does not claim that review completed, and unavailable runtimes such as Ultrawork are not offered until integrated.
 
 At the shell-wrapper boundary, every argument-bearing command (`codex exec ...`, `claude -p ...`) and every non-TTY invocation skips launch-profile projection and preserves caller arguments. The Claude direct path intentionally retains its wrapper default, `--dangerously-skip-permissions`. `codex --no-tui ...` / `claude --no-tui ...` explicitly take that direct path, and `AGENT_LAUNCH_TUI=0` disables zero-argument TUI interception for a process tree.
 
-Direct `agent-launch` calls still require a valid profile to resolve the backend command and its default arguments. `--preset`, `--custom`, or `--dry-run` select the configured-launch path even when non-TTY or combined with `--no-tui`; a non-TTY bare `--dry-run` deterministically uses Balanced, and a custom profile without that preset must pass `--preset NAME`. Forwarded backend arguments are expert overrides appended after projected defaults and may supersede them; the summary discloses this when arguments are present. For scripted configured launches, call `$HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ...` or add `$HOME/.local/bin` to `PATH`. The summary goes to stderr so backend stdout stays machine-consumable.
+Direct `agent-launch` calls still require a valid profile to resolve the backend command and its default arguments. `--preset`, `--custom`, or `--dry-run` select the configured-launch path even when non-TTY or combined with `--no-tui`; a non-TTY bare `--dry-run` deterministically uses Balanced, and a custom profile without that preset must pass `--preset NAME`. Forwarded backend arguments are appended verbatim after the projected defaults; one that would override a projected option (the seat, the contract, delegation, policy) is refused at launch so the contract keeps describing the run, and the summary discloses forwarded arguments when present. For scripted configured launches, call `$HOME/.local/bin/agent-launch --preset NAME --yes HOST -- ...` or add `$HOME/.local/bin` to `PATH`. The summary goes to stderr so backend stdout stays machine-consumable.
 
 Add `$CODEX_DIR/bin` to `PATH` or invoke the wrappers by absolute path. `codex-helm` follows the local CLI default and launches the HELM main with `--dangerously-bypass-approvals-and-sandbox`; an explicit `--sandbox MODE` disables bypass for that run regardless of flag order. `AGENTS.md` gives root/main local Codex sessions standing ordinary-subagent authorization when the delegation gates fire. A non-Ultra HELM main sets native multi-agent off by default and instructs HELM to send tiered dispatch through the internal `codex-run` adapter, where the selected model, effort, and sandbox are pinned; native multi-agent defaults on only when the HELM main itself is explicitly Ultra. FRONTIER is instructed to run as a separate `gpt-5.6-sol` root that is always read-only, at max by default, Ultra for genuinely divisible complex work, or a lower supported effort when cost or latency dominates. Because the HELM main has bypass authority and arbitrary expert `-c` by design, this dispatch route is an instruction-backed, live-E2E-verified default rather than a security boundary. Keep `codex-run` as the low-level internal adapter, not as a user-facing policy boundary. Both wrappers accept `-c key=value` as an expert override, and that override may intentionally change wrapper defaults for a single run.
 

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

@@ -154,6 +154,50 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 - After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
 - Attribute a parallel session's action (commit, branch, resource) by execution evidence in that session's own transcript, never by token mentions — shared handoff/memory files inject the same tokens into every session's context.
 
+## Context Budget And Reset
+
+Context growth is a property of the work, not of the host: over 1,075 sessions of 50+
+requests across both CLIs it runs ~2,400 tokens per request (IQR 1,850-2,950), the two
+hosts within 7% of each other (2,280 Claude, 2,450 Codex); the longest sessions (400+
+requests) run lower, ~1,800. One budget therefore serves both, and what differs per host
+is the price of ignoring it. The figure is a prior; the live session is measured below.
+
+- **Automatic compaction fires only when the window is nearly full** — Claude at 84-87%
+  (windows cluster at 200K and 1M), Codex at ~95% of the window its transcript records as
+  `model_context_window` (258,400 on the sessions measured; a later Codex/model pair
+  records 353,400 — read the value, never assume it). Cache read is charged per
+  request against the whole loaded context, so leaving the reset to the host pays the
+  maximum on every request before it. Measured: input is 92-94% of session cost and
+  output 6-8%, at a 95-97% cache hit rate — the context is the bill, and uncached input
+  is 0.0% of it.
+- Reset deliberately instead. Cost per request falls ~4x from an 867K auto-compact point
+  to 200K. The cost-theoretic optimum is ~65K, but it buys a compaction every ~32
+  requests at 2-3 minutes each, so 150-250K is the working range and the tail below it is
+  not worth chasing.
+- **What bounds the budget is what survives the reset, not the token count.** A compaction
+  keeps a ~14K summary plus 3-4 recent messages and discards the rest — unguided when it
+  fires on its own. Anything already written to a file survives every reset, so the
+  earliest safe threshold is the one where durable state is already on disk. That is what
+  decouples cost from loss: without it, resetting more often loses proportionally more.
+- Choose the mechanism by what is known, not by how large the context grew:
+
+| Situation | Mechanism |
+|---|---|
+| Stage finished, what to keep is known | clear + dated handoff file — cheapest, and the loss is not a loss |
+| Mid-stage, what to keep is known | write the handoff first, then compact with explicit instructions |
+| Mid-stage, the needed detail is not yet identifiable | compact with instructions; a summary spans what a file cannot yet name |
+| Original detail likely wanted later | clear, and record the transcript path in the handoff — transcripts persist on disk |
+| The next question is unknown | new session plus messaging; only this keeps a round trip available |
+| Growth is tool output | offload to subagents instead — measured ~20x cheaper (tier ~5x, context isolation ~4x) |
+| The judgement trail itself is load-bearing | keep the session and pay the 2-5x resume |
+
+- Measure rather than estimate: `agent-bios cost --context <transcript>` (the installed
+  entry to `session-cost.py`) reads either
+  host's transcript and reports current context, growth rate, compactions, and requests
+  remaining against a budget. Codex records `model_context_window` directly; Claude does
+  not, so the tool reports its observed auto-compaction point instead of assuming a
+  window.
+
 ## Handoff Contract
 
 Write for the next agent and re-verification, not narrative. Required content:
@@ -223,3 +267,5 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
 | two live delegation sessions | tiering saved ~3.3×; discarded prefixes made fresh respawn cheaper; unpinned reviewers inherited FRONTIER |
 | Codex reach contrast | inherit ~16.5K vs hermetic ~8.7K tokens; schema and stdout/stderr contract verified |
 | 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 |

package/claude/hooks/tooling-gotchas-hook.py

@@ -172,9 +172,19 @@ def main() -> int:
         payload = json.load(sys.stdin)
     except Exception:
         return 0  # never block on malformed input
-    if payload.get("tool_name") != "Bash":
+    # Malformed is a SHAPE, not just a parse failure. The guard above only covered bytes
+    # that are not JSON; a well-formed payload of the wrong shape — a top-level array, a
+    # list-valued tool_input, a non-string command — walked straight into `.get` or into
+    # `re.search` and left this hook exiting 1 with a traceback. That is the one thing
+    # the charter says it never does, and it would do it before EVERY Bash call in every
+    # deployed session, on a payload shape decided by a host this repo does not own.
+    # Advisory means silent on anything it cannot read, so each check returns 0.
+    if not isinstance(payload, dict) or payload.get("tool_name") != "Bash":
+        return 0
+    tool_input = payload.get("tool_input")
+    command = tool_input.get("command") if isinstance(tool_input, dict) else None
+    if not isinstance(command, str) or not command:
         return 0
-    command = (payload.get("tool_input") or {}).get("command") or ""
     hits = matches(command)
     if not hits:
         return 0
@@ -219,6 +229,31 @@ def self_test() -> int:
     if r2.stdout.strip():
         problems.append(f"hook injected on a command that matches nothing: {r2.stdout.strip()[:80]!r}")
 
+    # Never-blocks is a claim about EVERY payload, so the shapes that are valid JSON and
+    # not the expected object are the ones worth naming. Each of these exited 1 with a
+    # traceback before the shape guard existed, and each stands for a different way the
+    # host's payload could move: a different top-level type, a different tool_input type,
+    # a command that is not a string. The two controls above are the other half — a guard
+    # that returns 0 on everything would satisfy this block and nothing else.
+    for label, raw in (
+        ("top-level array", "[1, 2, 3]"),
+        ("top-level null", "null"),
+        ("top-level string", '"hello"'),
+        ("tool_input as a list", '{"tool_name": "Bash", "tool_input": [1, 2]}'),
+        ("tool_input as null", '{"tool_name": "Bash", "tool_input": null}'),
+        ("command as a number", '{"tool_name": "Bash", "tool_input": {"command": 123}}'),
+        ("command as a list", '{"tool_name": "Bash", "tool_input": {"command": ["git", "pull"]}}'),
+        ("command absent", '{"tool_name": "Bash", "tool_input": {}}'),
+        ("empty stdin", ""),
+    ):
+        r3 = subprocess.run([sys.executable, str(here)], input=raw, capture_output=True, text=True)
+        if r3.returncode != 0:
+            problems.append(
+                f"hook exited {r3.returncode} on {label} instead of staying silent: "
+                f"{r3.stderr.strip()[-120:]}")
+        elif r3.stdout.strip():
+            problems.append(f"hook injected context for {label}: {r3.stdout.strip()[:80]!r}")
+
     # Every rule needs a command that must reach it. A nonempty pattern is not evidence: a
     # trigger of `(?!)` can never match, and a rule suppressed by the special-case logic in
     # matches() never reaches the caller either — both leave the rule inert while this file

package/claude/skills/repo-charter/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: repo-charter
+description: Write or overhaul a repository's AGENTS.md (with CLAUDE.md as a one-line shim) for the agents that will work in it. Use when a repo has no agent instructions, when its AGENTS.md is a preamble that names nothing, or when the user asks to set a repo up for coding agents. Reads invariants and traps out of the code rather than pasting a template.
+---
+
+# Repo charter
+
+A repository's AGENTS.md is the repo's own layer of agent instruction — what a global
+corpus cannot know because it is true only here. This skill produces that layer for a real
+repository, and it produces it *from the repository*: the substantive half is reading the
+invariants, the gates and the traps out of the code, and no template can do that part.
+
+The output belongs to the repository — its team, its contributors, its git history. Nothing
+this skill writes carries a marker, a version stamp, or copyable boilerplate, because nothing
+outside that repo will ever update it.
+
+## 0. First decide whether the file is warranted
+
+Many repositories correctly have no instruction file. Content and documentation repos need
+at most a few lines of orientation; a personal repo rarely needs governance; and a one-line
+fix in someone else's project is not the moment to charter it — the file is theirs to create.
+Write one when agents will do repeated, non-trivial work here and the repo carries rules a
+newcomer would otherwise learn by breaking something. If the answer is no, say so and stop;
+an empty file with a heading is worse than none.
+
+Read enough to answer honestly before deciding: the top-level tree, the package or build
+manifest, hook and CI configuration, and the last fifty commit subjects. Steps 0 and 1 are
+provisional; step 3 may revise them. **Draft from the code first** — if the repo already has
+an instruction file, open it only at step 8, because reading it earlier anchors your
+structure to it and the comparison stops being evidence.
+
+## 1. Purpose type, then category mix
+
+Decide what the repo is *for* before writing a line. The type fixes which categories must be
+thick; everything else stays thin or absent.
+
+| Purpose type | Categories that must be thick |
+| --- | --- |
+| Library / framework that accepts outside contribution | contribution protocol, completion gates, hard boundaries |
+| Application / product | project invariants, pitfall warnings, co-change duties |
+| CLI / single-author tool | repo orientation, project invariants, task procedure |
+| Monorepo / platform | context routing, task procedure |
+| Corpus / payload the repo publishes elsewhere (the code is delivery, the content is the product) | hard boundaries, co-change duties, completion gates |
+| Content / docs | repo orientation only, minimal |
+
+A repo may take two rows; take the union and note which row explains each thick category.
+
+The category vocabulary, in one line each: **repo orientation** (what lives where, so nobody
+has to search), **command recipes** (the exact commands), **house form** (the shape of
+outputs), **project invariants** (semantic contracts the code must keep), **context routing**
+(when to open which document, skill or tool), **task procedure** (the order for a kind of
+work), **pitfall warnings** (traps and environment quirks that cause misdiagnosis),
+**contribution protocol** (how a change gets accepted), **completion gates** (what must pass
+before "done"), **co-change duties** (change X, then also Y), **hard boundaries** (never),
+**human authority** (where to stop and hand over), **agent conduct** (how the agent itself
+operates). Across thousands of real files, human authority is the rarest of these — people
+write prohibitions but not escalation paths — so it is asked for explicitly in step 5.
+
+## 2. AGENTS.md is the body; CLAUDE.md is a shim
+
+Write one file: `AGENTS.md`, which Codex reads natively. Where Claude Code is used, add a
+`CLAUDE.md` whose only content is an import of `AGENTS.md` (`@AGENTS.md`), plus at most a
+sentence saying why the shim exists — and if that sentence claims something about a tool's
+behaviour, date it or drop it, because such claims rot into lies. Two bodies drift; one body
+and one pointer cannot. A file's name does not tell an agent which tool it is for — content
+that opens "guidance for tool X" is copied between tools verbatim, so leave the tool's name
+out of the body; the shim sentence is the one exception.
+
+## 3. Read the invariants and traps out of the code
+
+This is the work, and it is done by reading, not by asking the repo's owner to dictate.
+For an existing repo, collect at least these before drafting:
+
+- **What runs before a commit and what it enforces.** Hooks, CI configuration, gate scripts,
+  lint and test entrypoints. For each rule you state, name the file that enforces it, and
+  mark the rules nothing enforces as convention — a reader must be able to tell a gate from
+  a wish.
+- **What a green check does and does not prove.** A test suite that skips a leg, a check that
+  runs against a fixture rather than the real path, a scan whose subject set can be empty.
+  These belong in the file because they are exactly what a newcomer misreads.
+- **Generated paths.** Anything produced from another file must be named as such, with the
+  generator and the command that regenerates it; hand-editing a projection is the most
+  common silent defect.
+- **Where authority lives.** For each value that appears in more than one place, which copy
+  is the source and how the others follow it.
+- **What the history paid for.** Read the recent log and any postmortems or dated design
+  notes for mistakes that cost a real attempt — the deploy that took the wrong tree, the
+  command whose exit status lied, the flag that was rejected rather than implemented. Each
+  becomes a present-tense warning that names the symptom.
+- **Runtime shape that a reader cannot infer.** Which entrypoint is real, which directory
+  is payload versus tooling, which environment the tests assume.
+
+State each finding as a rule about the present, in one or two sentences, and cite the code
+by **file and identifier** — function, constant, leg name — never by line number: a symbol
+survives an edit and is greppable, a line number is wrong within a day. A rule that cannot
+cite its enforcer or its evidence is a candidate for deletion. Stop collecting when a new
+source stops producing rules you would keep — usually after the hooks, the gate entrypoints,
+the packaging manifest, the installer, and the recent commit subjects.
+
+## 4. Choose the sections from the findings, not from a template
+
+Group what step 3 produced under headings that match the repo's thick categories from
+step 1. Order by what an agent hits first: orientation and the pre-commit contract before
+style; traps near the commands that trigger them. The file is re-sent to every session, so it
+is a token budget: if the draft exceeds roughly 2,000 words, the excess is a guide — move the
+longest section behind a pointer and keep the one rule that says when to read it.
+
+## 5. Ask for human authority explicitly
+
+Ask the user, in outcome terms, which decisions an agent must bring to a person rather than
+settle: releases and publishes, schema or data migrations, anything touching credentials or
+production, deleting or rewriting history, spending money, changing a public contract.
+Write the answer as a short list of *stop points* with what to bring (evidence, options),
+not as a prohibition. If the user has no answer yet, record the question as open in the
+file rather than inventing a policy; if the run is unattended, draft the stop points as a
+proposal marked as requiring confirmation, and never infer one the code does not evidence
+as irreversible or outward-facing.
+
+## 6. Refuse the zero-content preamble
+
+Delete any sentence that could open any repository's file: "this file provides guidance to
+agents working in this repository", "follow best practices", "write clean code", restated
+general engineering rules the agent already carries. Read the draft once more asking of each
+line, "what would an agent do differently after reading this?" — a line with no answer goes.
+
+## 7. Directory-scoped files only for the monorepo or platform type
+
+A `CLAUDE.md` or `AGENTS.md` placed inside a subdirectory is loaded when a file beside it is
+touched, which makes it survive the loss of early session context. That is valuable when
+subtrees have genuinely different rules — the monorepo case — and noise everywhere else,
+where it splits one file's authority in two. Default to one root file.
+
+## 8. Before handing it over
+
+Self-review against three constraints, and fix rather than annotate:
+
+- Nothing in the output is boilerplate meant to be pasted elsewhere, and nothing points back
+  to this skill, to a version, or to any tool that would "update it later" — no such
+  mechanism exists, and a stamp that promises one is a lie the repo will carry.
+- Every rule names the code that enforces it, or is marked as convention.
+- The file states current behaviour only. Change narratives, rejected alternatives and
+  handoff logs are pointed to where they live (design notes, the log), not repeated here. A
+  live process that is followed but not enforced is current, not history — it belongs in the
+  file or behind a pointer, and length decides which.
+
+Now read the repo's existing instruction file, if any, and verify each of its claims against
+the code — a stale sentence beside current code reads as fact. Show the user your skeleton
+beside it and name the divergences: a large gap means either the draft or the existing file
+is wrong, and finding out which is the point of the exercise.

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

@@ -154,6 +154,50 @@ How much independence a review actually bought, as an ordinal grade per reviewer
 - After resume/clear/relocation, verify pwd, branch, and HEAD against the pinned handoff before acting.
 - Attribute a parallel session's action (commit, branch, resource) by execution evidence in that session's own transcript, never by token mentions — shared handoff/memory files inject the same tokens into every session's context.
 
+## Context Budget And Reset
+
+Context growth is a property of the work, not of the host: over 1,075 sessions of 50+
+requests across both CLIs it runs ~2,400 tokens per request (IQR 1,850-2,950), the two
+hosts within 7% of each other (2,280 Claude, 2,450 Codex); the longest sessions (400+
+requests) run lower, ~1,800. One budget therefore serves both, and what differs per host
+is the price of ignoring it. The figure is a prior; the live session is measured below.
+
+- **Automatic compaction fires only when the window is nearly full** — Claude at 84-87%
+  (windows cluster at 200K and 1M), Codex at ~95% of the window its transcript records as
+  `model_context_window` (258,400 on the sessions measured; a later Codex/model pair
+  records 353,400 — read the value, never assume it). Cache read is charged per
+  request against the whole loaded context, so leaving the reset to the host pays the
+  maximum on every request before it. Measured: input is 92-94% of session cost and
+  output 6-8%, at a 95-97% cache hit rate — the context is the bill, and uncached input
+  is 0.0% of it.
+- Reset deliberately instead. Cost per request falls ~4x from an 867K auto-compact point
+  to 200K. The cost-theoretic optimum is ~65K, but it buys a compaction every ~32
+  requests at 2-3 minutes each, so 150-250K is the working range and the tail below it is
+  not worth chasing.
+- **What bounds the budget is what survives the reset, not the token count.** A compaction
+  keeps a ~14K summary plus 3-4 recent messages and discards the rest — unguided when it
+  fires on its own. Anything already written to a file survives every reset, so the
+  earliest safe threshold is the one where durable state is already on disk. That is what
+  decouples cost from loss: without it, resetting more often loses proportionally more.
+- Choose the mechanism by what is known, not by how large the context grew:
+
+| Situation | Mechanism |
+|---|---|
+| Stage finished, what to keep is known | clear + dated handoff file — cheapest, and the loss is not a loss |
+| Mid-stage, what to keep is known | write the handoff first, then compact with explicit instructions |
+| Mid-stage, the needed detail is not yet identifiable | compact with instructions; a summary spans what a file cannot yet name |
+| Original detail likely wanted later | clear, and record the transcript path in the handoff — transcripts persist on disk |
+| The next question is unknown | new session plus messaging; only this keeps a round trip available |
+| Growth is tool output | offload to subagents instead — measured ~20x cheaper (tier ~5x, context isolation ~4x) |
+| The judgement trail itself is load-bearing | keep the session and pay the 2-5x resume |
+
+- Measure rather than estimate: `agent-bios cost --context <transcript>` (the installed
+  entry to `session-cost.py`) reads either
+  host's transcript and reports current context, growth rate, compactions, and requests
+  remaining against a budget. Codex records `model_context_window` directly; Claude does
+  not, so the tool reports its observed auto-compaction point instead of assuming a
+  window.
+
 ## Handoff Contract
 
 Write for the next agent and re-verification, not narrative. Required content:
@@ -223,3 +267,5 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
 | two live delegation sessions | tiering saved ~3.3×; discarded prefixes made fresh respawn cheaper; unpinned reviewers inherited FRONTIER |
 | Codex reach contrast | inherit ~16.5K vs hermetic ~8.7K tokens; schema and stdout/stderr contract verified |
 | 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 |