khosra/reference/agent-session-costs.md

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.