Your Agent's Permission Logic Lives in 2,267 Files

A paper crossed my desk this week that put a number on something I'd only ever felt as a vague unease. I want to tell you about the number, and about the two very different conclusions you can draw from it.

The paper is the Harness Handbook (Wang et al., arXiv:2607.13285) — a serious piece of engineering research on making agent infrastructure understandable. The authors traced a single safety behavior, “confirm before file deletion,” through a production coding-agent harness. One rule. The logic implementing it touched 2,267 files in a codebase of 34,000 functions.

Sit with that. Not an exotic behavior — the single most obvious guardrail any agent should have. And in a well-engineered production system, its implementation is smeared across the entire harness: the tool wrapper checks something, the permission module checks something else, the sandbox has its own rules, the headless mode has an auto-approve path someone added for CI, and the fallback handler quietly does its own thing. Every one of those sites is a place the rule can drift, fork, or silently stop applying after a refactor.

Two honest answers

The paper's answer is better maps: a behavior-level handbook that links every rule to every place it lives, so humans (and coding agents — their evals on this are genuinely clever) can navigate the scatter. It works, and if you maintain a big harness you should read it.

But there's a second answer, and it's the one I've bet this company on: move the behavior somewhere the scatter can't reach. However complicated a harness gets on the inside, it touches the world through a small number of narrow waists — the plane where tool calls exit, the boundary where work is delegated to another agent, and the moments where money moves or something irreversible happens. A rule enforced at a waist is one rule, in one place, with one audit log. The 2,267 files can churn all they like behind it.

Documentation for the inside, architecture for the boundary

I want to be fair to the handbook people, because the two approaches compose. Inside the harness — where behavior is genuinely yours to own — their behavior maps are the right tool. At the boundary — where authority crosses to code you don't control — maps aren't enough, because the other side doesn't read your documentation. That's where the rule itself has to travel with the request: signed, verifiable, and only ever narrowing. That's the mandate model, and it's why a chain of delegations can cross five agents from four vendors and still be one auditable object at the end.

The paper also shamed me into something. If our whole pitch is auditability, our docs should be as auditable as our protocol — so we published a guarantee-evidence table: every claim we make, mapped to the exact function that enforces it and the published test that proves it. Everything resolves inside our MIT npm tarballs — you don't need access to any repo to check us. That discipline is a straight lift from their “behavior → code evidence” idea, credited gladly.

The uncomfortable takeaway from 2,267 files isn't that harness engineers are sloppy — that harness was well engineered. It's that safety-by-scatter is what implementing rules inside a moving codebase naturally produces. Maps help you live with it. Chokepoints let you stop producing it.