What is your agent's instruction budget?
Ten runtimes, ten different ceilings, no shared unit — and most of them fail silently.
A while back I wrote about the small agent I run on a server in my house — it reads my accounts, files my documents, and drafts the twice-daily briefing that lands on my phone. This is the story of the day — it quietly broke.
The rules file that agent loads at the start of every session had grown past the runtime’s injection ceiling. It injected what fit and dropped the rest — and what got dropped was the rule I’d appended most recently, because appending to the end is how a governing file grows.
Nothing failed. No warning, no error, no change in the agent’s confidence. It simply operated for weeks under a rule set it had never fully received, and one morning it handed me a financial briefing with account balances it had never fetched — fabricated numbers — surprise, surprise! It’s hallucination! Your agent runtime ships you a component with an unknown (may be undocumented as well) tolerance.
The runtime doesn’t matter, and I’m not going to make this about one vendor — by the end of this you’ll see there are at least ten.
The vendors know
OpenAI’s Codex caps the AGENTS.md it injects at 32,768 bytes. That number isn’t a community discovery — it’s DEFAULT_PROJECT_DOC_MAX_BYTES in codex-rs/config/src/config_toml.rs, and the comment beside the loader describes the behavior in the vendor’s own words: “Larger files are silently truncated to this size so we do not take up too much of the context window.”
The bug report asking for a startup warning — openai/codex#7138, titled “AGENTS.md is silently truncated without any warning within the TUI” — was closed not planned in March 2026. The stated reason: “This feature request hasn’t received any upvotes in three months, so I’m going to close.” It was filed as an enhancement, not a bug. Someone refiled it the next day; #13386 is still open. A user commented there in July that he’d “only accidentally discovered today that my 40KB AGENTS.md was being truncated to 32KB and silently omitting 20% of my instructions.”
That’s the shape of it. The number is sometimes published. The behavior almost never is.
Nobody agrees on the ceiling — or the units
The good guides to AGENTS.md cover the four major coding agents and tell you the size limits. What none of them cover is what happens when you cross one — which is the only part that decides whether your rules are in the model’s context. Here is what the sources actually say:
Sources: Claude Code; OpenClaw; Nous Hermes; Moltis
Two things about this table are worse than any individual row.
The units aren’t comparable. Codex counts bytes. OpenClaw, Hermes and moltis count characters. Anthropic counts lines-or-kilobytes, whichever comes first. That divergence isn’t theoretical: Hermes’ own shipped AGENTS.md measures 75,142 bytes but 74,506 characters. Six hundred and thirty-six units of difference, in one file, on the number that decides what survives. I’ve found no test of how any of these implementations actually counts.
The config keys don’t even share a name — project_doc_max_bytes, bootstrapMaxChars, context_file_max_chars. There is no convention here to be non-compliant with.
And if you want a sense of how well the ecosystem tracks its own constraint, I measured the reference implementations. OpenClaw’s own shipped AGENTS.md is 56,458 bytes against its own 20,000-character cap — roughly 2.8× over. Hermes’ is 75,142 bytes; the issue documenting that 74% of it never reaches the model was closed not planned and labeled cosmetic. (Both measured 20 July 2026 — OpenClaw at e2e394e1, Hermes at 0144743b. They move.) The reference implementations exceed their own limits.
Rule drift
The closest named thing I’ve found is governance decay — safety constraints silently removed by context compaction (arXiv:2606.22528). This is a different mechanism with the same signature, and mine happens before the session even starts.
A governing instruction file grows by accretion, and it accretes at the bottom. You append a rule because something went wrong. You append another because a customer asked. Each edit is individually correct and individually small. Meanwhile the ceiling stays fixed and — in harnesses (the software that runs the agent, the runtime by another name) that truncate silently from the tail, which is not all of them, as the table shows — truncation eats from the end. The file degrades through ordinary, competent maintenance, and no single commit ever looks like the mistake.
This isn’t hypothetical. A survey of AGENTS.md files across 100 popular repositories (arXiv:2606.15828) found measurable context bloat in 42% of them, and “skill leakage” — execution detail sitting in the always-loaded file — in 35%.
The rules that die are the newest ones. Which is to say: the rules you added because something already went wrong once.
The fix isn’t shortening the file. It’s deciding which prefix survives amputation — smaller, blunter, ordered by consequence, with the non-negotiables at the top not because top is more persuasive but because top is what remains. (Order does demonstrably affect adherence — Zeng et al., ACL 2025, arXiv:2502.17204 — though that paper finds hard-to-easy ordering wins, which is not the same as importance ordering. The optimal arrangement is still open.)
One thing that doesn’t help: splitting the file up. Anthropic’s docs are explicit that imports “help organization but don’t reduce context, since imported files load at launch.”
And the reason placement matters at all: a behavior placed in the wrong layer silently never happens. Put “always fetch before answering” in a skill body — which loads only after that skill is chosen — and it cannot help you. The agent decided to fabricate before it ever opened that file.
What the always-on layer costs
This is where it gets commercially interesting, and where I think the discussion is thin.
A rule that must hold on every turn is a fixed per-turn prefill tax. Twelve thousand characters is roughly three thousand tokens. At $5 per million input tokens (roughly a frontier model’s rate) — that’s about 1.5 cents a turn uncached, about 0.15 cents cached.
That tiny number is the problem. I’ve argued before that inference is usually the cheapest line item in an AI product — and here that cheapness turns dangerous: a bloated instruction file shows up as degraded adherence and silent rule loss long before it ever shows up on an invoice. There is no cost signal to catch this.
Two research groups have now measured what the file actually buys, and they don’t agree.
A team from Singapore Management University, Heidelberg, Bamberg and King’s College London (arXiv:2601.20404, ICSE JAWs 2026) ran Codex across ten repositories and 124 merged pull requests, twice each — with the repo’s AGENTS.md and without. Median wall-clock time fell 28.6% and median output tokens fell 16.6%, both statistically significant. Median total tokens went slightly up, about 1.3%, and that result wasn’t significant. So the file bought speed and cheaper generation, not less context. The authors speculate the gain comes from less exploratory navigation; they flag testing that as future work, and they did not measure task success at all. Caveats worth stating: PRs under 100 lines and five files, one harness, one model.
An independent team at ETH Zurich and LogicStar (arXiv:2602.11988) measured something close to the opposite. Across SWE-bench and a purpose-built benchmark, every kind of context file raised cost and step count — machine-generated ones by up to 23%, human-written ones by up to 19%. Success moved −2% for generated files and +2.4% for developer-written ones, and neither result was statistically significant. Their mechanism is the part worth keeping: cost rises because agents actually follow the instructions — more testing, wider exploration — not because the file is padding. What they found genuinely useless was repository overviews, which the agent can read for itself.
These two results point in different directions, and I’d rather say that than average them. One measures wall-clock and tokens on paired reruns of real merged PRs; the other measures dollars and agent steps on benchmarks. What survives both is narrower and more useful than either headline: instruction context is not free and it is not linear. It buys you less exploration, and it buys you more obedience — and obedience costs money too. What it does not reliably buy is a higher success rate. Past the ceiling, it also costs you the lines underneath.
One correction to the obvious conclusion: a file written blind is the failure mode, not machines writing files. Shepard and Albrecht (arXiv:2606.20512) got 33% resolution against 25.5% unguided by probing the agent and iterating the guidance against what actually failed. Generated-then-never-tested is the bad case.
The instruction file is also a cache key. Caching is exact-prefix; edit the file mid-session and you re-price everything downstream. Practitioners are already engineering around it — claude-code#77355, opened 14 July 2026 and still open, is someone maintaining a CLAUDE.staging.md and copying it in at session start “specifically to avoid busting the cache mid-session.” Google prices the same resource on a third axis: Gemini bills cached context by the hour — $1.00 per million tokens per hour of storage on 3.5 Flash, on top of a cached-input rate of $0.15 against $1.50 standard (pricing, read 20 July 2026). You pay rent on an always-loaded block whether or not anything reads it.
So one resource now has three incompatible meters: per-token consumption, per-hour rent, and free-if-the-prefix-matches. Nobody prices against all three.
Does progressive disclosure actually save money? On tokens and accuracy, measurably yes. Anthropic reports a five-server MCP setup — 58 tools across GitHub, Slack, Sentry, Grafana and Splunk — consuming “approximately 55K tokens before the conversation even starts,” cut to ~8.7K with deferred loading, and MCP eval accuracy on Opus 4.5 rising 79.5% → 88.1% (Anthropic engineering, 24 Nov 2025). Internally they’ve seen tool definitions hit 134K tokens before optimization. On net cost, nobody has published a number — and the honest tell is that Anthropic had to build a special mechanism to keep deferred loading from destroying the cache. Naive on-demand loading would cost you cache reuse. That’s why the mechanism exists.
Which produces a question I’d want answered before I signed anything: if the injection budget determines whether my agent’s safety rules hold, and the platform owns that budget — what is it, how is it counted, and what happens when I exceed it, in writing?
It is the same question a buyer asks about any supplied component whose failure is invisible in the finished good: what is the tolerance, how is it measured, and does the supplier tell me when I’m outside it. In every mature supply chain that answer lives in a datasheet and a change-notification clause. Here it lives in a source comment.
Nothing I can find answers it. I’m talking about what a buyer can read before entering a negotiation: Anthropic’s Commercial Terms, effective 17 June 2025, contain no service levels, no context-size language and no truncation language — only that “ANTHROPIC DOES NOT WARRANT… THAT THE SERVICES OR OUTPUTS ARE ACCURATE, COMPLETE OR ERROR-FREE.” Meanwhile the same vendor publishes a twelve-row table specifying its own injected overhead to the single token — 290 tokens of tool-use system prompt on Opus 4.8 under tool_choice: auto, 410 under any, 675 on Opus 4.7, 264 on Haiku 3.5 — broken out by model and by setting (tool use pricing, read 20 July 2026). The platform meters its side of the boundary to the token. Yours it will not name.
The fix
Here is what to actually do — four steps.
1. Measure your file. Run wc -c on your rules file (AGENTS.md, CLAUDE.md, whatever your tool uses) and compare the number to your tool’s limit — Codex cuts off at 32,768 bytes; others differ, and some publish no number at all. If you are over the limit, part of your file is being thrown away every session, and nothing tells you.
2. Put the most important rules first. When a file is cut, it is cut from the bottom. So move your non-negotiable rules to the top, where they survive. Order by what matters most, not by topic.
3. Add a tripwire at the bottom. Make the last line of the file something distinctive — say, RULES-END-DO-NOT-DELETE — and have your startup check confirm that exact line came through. If it is missing, the file was cut, and now you know, instead of finding out from a wrong answer. (That is all a “canary” is: a marker whose absence is the alarm.)
4. For anything that must never be wrong, do not trust the file at all. A rules file is a suggestion — the model usually follows it, and “usually” is fine for judgment calls. It is not fine for a rule about money, which has to hold every time. Put those rules in code instead of text: make the step that reports a balance refuse to run until the balance has actually been fetched. Text can be ignored. Code cannot.
That is the whole fix.