Context & Cost Economy

Principle order: quality → speed → cost. Never trade correctness for cost. This doc shows how to stay correct and cheaper.

The platform already keeps per-session context lean at the artifact layer (lazy-loaded skills/agents, ~50 KB/session). This doc covers the agent-runtime I/O layer — where tool output, snapshots, and accumulated context balloon the bill.

The Cost-Lever Tier Ladder

Choose the lowest tier that solves the problem. Never trade up a tier for cost on reasoning-critical context.

Tier	Lever	Lossy?	Stance
0	Source-side deterministic pruning — return only the needed fields/rows/lines	No	Lead here. Pure "code before model" (INS-1). Fixes the cause.
1	Lossless first-party levers: prompt caching, context-editing, memory tool, Batch API, model tiering, subagent-as-context-firewall	No	Adopt. Zero quality trade-off.
2	Deterministic selective stripping of uncontrolled tool output (RTK-style) — preserve errors/diffs/exit codes	Yes (bounded)	Gated pilot only; off correctness-critical paths; local build, telemetry off, validated against /cost.
3	Lossy model-based compression (Headroom ML path, LLMLingua) / semantic caching	Yes	Last resort; never on reasoning-critical live context; requires preserved source-of-truth + task validation.

Cross-cutting rules:

• Choose the lowest tier. Never move up a tier for cost if it touches reasoning-critical context.
• Cache-defeat warning: a prompt-rewriting proxy changes the prefix and turns cache reads back into full-price tokens — potentially raising net cost.

Tier 0 — Code Before Model

Return only what is needed. Three patterns:

Extract, don't dump. grep or Read with offset+limit instead of the full file. Project only needed DB fields; no full-collection scans.

Query the API, not the DOM. For web automation, intercept the network request (browser_network_requests) or run a targeted JS expression (browser_evaluate) to get the specific datum. Reserve browser_snapshot (full accessibility-tree dump, 10–40 K tokens) for cases where the rendered page structure is genuinely needed.

Parameterize once, invoke cheaply. A deterministic script you invoke is far cheaper than re-reasoning through the same flow each time. Write the JS, save it, reuse it.

Tier 1 — Lossless First-Party Levers

Subagent as context firewall

Token-heavy I/O that stays in a subagent's context costs nothing in the main thread. Only the conclusion returns:

// 20 K-token Playwright session → subagent
Agent(
  "Verify the withdrawal CSV download on localhost:3000/events. Log in as admin. " +
  "Click Export. Check columns: event_name, amount, date. Return: pass|fail + first mismatch.",
  { subagent_type: "bewith:qa-engineer" }
)
// main thread receives: "pass — 42 rows, correct columns." (~10 tokens)

Use the firewall when an operation will produce 5 K+ tokens of output and the main thread only needs a verdict, a count, or an extracted value.

Model tiering

• Mechanical work (transcription, grep, doc draft, lint, format conversion): Sonnet / Haiku.
• Hard reasoning (design decisions, root cause analysis, multi-step debugging): Opus.
• The 1 M-context window is a cost multiplier — do not default to it for tasks that fit in 200 K.

Prompt caching

The claude-api skill mandates cache_control on the system prompt and the first large user block. Do not rewrite the system prompt dynamically — that defeats the cache and turns cache reads into full-price tokens.

Context editing / finished tool results

After a long tool call (DB import, test run, log search) whose output is no longer needed for future reasoning, clear the finished tool results from the context. This is the memory-tool + context-editing pattern.

File-based handoff over pasting

Pasted context stays resident in the conversation and re-costs every turn. Move large briefs, diffs, and intermediate data to files. Read them on demand; never paste up-front.

Playwright — cost rules

browser_snapshot emits the full accessibility tree: 10–40 K tokens per call. These rules reduce that to near-zero for most tasks.

Situation	Prefer	Instead of
Extract a specific value	browser_evaluate("document.querySelector('#total').textContent")	browser_snapshot
Check API response data	browser_network_requests + filter by URL	browser_snapshot
Fill and submit a form	browser_fill_form or a JS sequence via browser_evaluate	snapshot → click → snapshot loop
Verify an element exists	browser_evaluate("!!document.querySelector('.success-toast')")	screenshot
Navigate to an unvisited page	browser_navigate + targeted extraction	browser_snapshot
Human needs to see pixels	browser_take_screenshot	(correct — use it)

Behavioral rules:

1. Ask before acting. When the goal is underspecified, ask what to verify or extract before opening the browser.
2. State model in text. After each browser action write a one-line state ("navigated to /events, filter = July 2026") instead of re-snapshotting to "remember" current position.
3. Write JS scripts. For repeated automations (login, table extract, CSV trigger), write a reusable browser_evaluate script rather than re-discovering the path each session.
4. Screenshots on demand only. Take a screenshot only when the user asks or when visual verification (layout, color, animation) is the explicit goal.
5. One snapshot per flow, not per step. If a snapshot is unavoidable, take it once at the key decision point.
6. Wrap Playwright sessions in a subagent. When a browser session is the bulk of the work, run it in an Agent subagent so snapshots and logs stay out of the main thread context.

Progress ledger

For multi-session tasks, maintain a short ledger file (.bewith/ledger.md) listing completed steps with verdicts. This prevents re-running finished work after context compaction — the compaction loses conversation history, but the file survives.

Evaluated tools — not adopted as defaults

Tool	Verdict
Headroom (chopratejas/headroom)	Rejected as default. Apache-2.0 beta, vendor-self-reported savings, lossy ML compression. A pre-registered RCT found aggressive compression raised cost ~1.8% (model expanded output to compensate). Tier 3 only.
RTK (rtk-ai/rtk)	Rejected as default. Same as Headroom, plus: security issue #640 (shell-injection, telemetry default-on, exit codes not propagated — agent misreads failed commands as success, secrets retained in tracking.db for 90 days).

Both can be used as a gated Tier-2 pilot for uncontrolled output that is not correctness-critical. Measure against Claude Code /cost on a real session (not vendor numbers); local build, telemetry off; never where command lines carry secrets.

---

Promotes INS-1 (docs/insights/index.md). Cross-linked from deterministic-ai.md (principle 2) and the delegate-heavy-context skill.