init

reference/agent-session-costs.md

@@ -0,0 +1,39 @@
+# How agent session cost accumulates
+
+Established: mechanism, asserted from how the tool loop works — not measured in this repo.
+Recorded: 2026-07-28
+
+## The model
+
+An agent turn sends the entire conversation context to the model, every time. A tool call is a
+turn. So the cost of a task is roughly:
+
+```
+total ≈ (number of tool calls) × (average context size)
+```
+
+Both factors matter, but the first is the one usually left on the floor. Consequences that follow
+directly and are easy to get backwards:
+
+- **Ten small commands cost more than one large one.** Batching independent reads into a single
+  message, or chaining shell commands into one call, cuts turns without cutting information.
+- **An always-loaded file is multiplied by every turn in the session.** A 100-line constitution over
+  40 turns costs more than a 2000-line doc read once. Per-byte, the always-loaded file is the most
+  expensive in the repo; every other doc is read on demand and paid for once.
+- **Output length is paid twice** — once as generated tokens, then again as context on every
+  subsequent turn of the session.
+- **A file read mid-session stays in context.** Reading speculatively is not a one-off cost; it
+  raises the floor for the rest of the session — the mechanical reason behind `CLAUDE.md` §1's read
+  discipline.
+- **A subagent's context is separate.** Its file dumps never enter the parent context; only its
+  conclusion does. This is why delegating fan-out search is a real multiplier rather than a
+  wash.
+- **Rework is the most expensive thing available.** A wrong assumption discovered late costs the
+  whole re-derivation plus the original attempt. Clarifying gates and plan-before-code are token
+  optimisations, not just quality ones — which is why "read the owning doc first" saves more than
+  it spends.
+
+## Practical consequence for this repo
+
+Terseness in docs and reports is not a stylistic preference here; it is a budget. See
+`ideas/token-conservation.md` for the open proposal on enforcing it.