40 lines
2.0 KiB
Markdown
40 lines
2.0 KiB
Markdown
# 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.
|