Skip to content

Three walls every multi-agent setup hits

Three walls every multi-agent setup hits

Give a coding agent one task and it works. Give it a second and the cracks show. By the third it feels like chaos, and the obvious diagnosis is that you are running too many agents.

I believed that for a while. Then I went back through the commits, and the failures did not sort by how many agents were running. They sorted by which surface two actors were writing to, and whether anything owned it. A state file where “done” gets recorded. A shared checkout two implementations can both write into. A completion claim that only the agent making it can see.

The three are not the same kind of failure, and lumping them together is how you end up fixing the wrong one. Nobody owned the write. Nobody copied the record out before deleting the workspace. Nobody independent accepted the claim. Ownership, persistence, acceptance.

It is not a taxonomy either. These are the three walls that cost me work, and a fourth may be waiting. Nor is it a ladder: the order below is the order I came to understand them, which is not the order the fixes landed, and the close comes back to that.

Nobody else may write the record

The first failure did not look like sabotage, which is part of why it took time to name. Nothing was edited by an agent that had no business editing it. The problem sat upstream of any edit. The coordinator trusted what an agent said it had done instead of checking the filesystem, so phases were marked complete with no commits behind them. The fix commit records the root cause in its own words:

a critical governance gap where the coordinator (Claude Code) could trust agent claims without verification, leading to phases being marked complete without commits.

The mechanism underneath that gap is one sentence long. The worker could call state.py directly, which meant the executor of a task was also eligible to be the one recording that the task was done. Authority did not leak sideways to a rogue process. It collapsed into a single actor holding both halves. A rogue file edit is a different story that needs a different fix, and it is not this one.

The practice: protected state gets one owned write path, and every other actor routes through it.

The enforcement is small on purpose. The guardian refuses a direct state.py call unless it carries the authorized skill marker. Two more refusals close the obvious side doors: approving a proposal through raw Bash, and creating new files as a way of getting something approved by accumulation. And the shape the coordinator is held to, written in the repo as a single line:

Workers make claims → Coordinator verifies → Coordinator updates state.

The point of that arrow is who is absent from it. The worker reports. The worker does not certify.

At reader scale the whole wall is one rule, and it does not need a repo. One Claude Code session, one progress file. A subagent reports that it wrote the three files. You mark the task complete without opening any of them, and the files do not exist, because the report described intent rather than a write. That is an illustration: no date, nothing in my logs to point at. The minimum version is a sentence. Only the session holding the plan may write the progress file. The worker reports, you verify, you write.

So pick the one artefact that is the source of truth for “what is true right now.” A state file, a status table, a changelog, a single row in a database. Give exactly one component the write path to it and make everyone else route through that component. Then verify the claim before the write, and not after. Once the pen sits in one hand, an executor’s account of its own work stops being evidence anyone can act on.

Redirect the write, don’t lock the worker out

The second failure was quieter, because nothing failed loudly at all.

A finished piece of work got cleaned up. The tooling removed the temporary workspace the work had been done in, and the newest verification record went with it. The task then closed as resolved carrying an older verification result, timestamped 14:57 where the re-verification had actually run at 19:40. resolved is terminal here, with no reopen path, so the loss could not be corrected by re-running anything. Fixing it meant building a new primitive, a hard-fenced reopen_for_reverify, now the only way to correct a terminal spec.

The evidence left behind is an anachronism, which is the part worth keeping. A deleted workspace leaves no wreckage to find. What survives is a record that looks complete and is exactly one iteration old. Nothing was lost to a disk. It was lost to two steps disagreeing about which surface owned the write.

That story is doing double duty, so I will separate the two risks it contains, because they need different fixes and it is easy to buy one and think you bought both. The first risk is that removal destroys proof: anything living only inside a throwaway workspace dies when the workspace does. The second is that the shared checkout accepts writes from anyone: while one implementation is running, another agent can put files in the tree it is working in.

For the first, the remedy is persist-before-destroy: copy the workspace’s state and verification into the main repository before the workspace is removed. It is an idempotent step in the resolve skill.

For the second, the remedy is redirection: refuse writes into the shared checkout while an implementation is in flight. The redirect would not, on its own, have preserved the artefacts above. It makes the wrong surface hard to reach. It does not make a removal safe.

The instinct on hitting a collision is to build a lock: one agent per scope, mutually exclusive. That is not what this does, and building it would have been a mistake. Two agents working on two different pieces of work is not a collision; it is the reason to run a fleet. The collision that actually loses work is an agent writing into the shared checkout while another agent’s implementation is in flight, because the shared checkout is the one surface every agent can reach and none of them owns.

So the fix is redirection. The write is not refused because someone else holds a lock. It is refused because the main tree is the wrong place to write, and the refusal tells the agent where it should have written.

In ordinary terms: work happens in a throwaway workspace instead of the shared checkout. While any implementation is in progress, the repo keeps a small live note saying so and saying where its workspace is. Before any file write, a check resolves the path. If the path points into the source tree while a note exists, the write is refused and the agent is pointed at the workspace instead.

no

yes

no

yes

Agent issues a mutating write

Guardian: check_write

Path under apps/, packages/, internal/ or cmd/?

Write proceeds

An implementation marker is live?

Refused, and the active spec worktree is named

Agent writes into .trustless/worktrees/spec instead

The granularity is worth one line, because it is what makes parallelism work. Each note is keyed to one piece of work, so several in flight means several notes, and none of them is a mutex. Writes inside .trustless/worktrees/ are always allowed. Writes outside the protected directories are untouched.

Two limits I will not dress up as solved. The first is that the protection is by location, not by role. It refuses a path during an implementation, from whoever is making the write, and it does not know or care whether the writer is the coordinator or a worker. There is a second guard on the same condition whose name suggests it detects the coordinator and holds it to a higher standard; it detects no role at all. Do not read that as separation of powers. The intent behind the rule is real, since the coordinator should be dispatching rather than coding, but what exists enforces the condition, not the identity.

The second limit is the destination. Notes are per task, so a repo running several implementations at once has several live at once, and “the active workspace” stops being a single obvious directory. My read is that the redirect’s value is mostly in its first half, keeping the write out of the main tree, which is the part that loses work. Naming the right destination for this particular agent is only as good as the resolution behind it, and that resolution is thinnest exactly when the fleet is busiest. If you build this, test the destination hardest.

What the note does not do is audit. It is short-lived runtime state, scoped to the session and never committed, so it answers “is a write safe right now,” not “who did what three weeks ago.” For that question you read the version control history: every implementation lands on its own branch with its own commits, and the commits are what you go back to. The note prevents the collision. It does not testify.

One honest caveat about the other half of scope. Each unit of work declares which files it may touch, and those declarations are recorded per proposal, 59 of them in this repo with explicit read and write sections. But the guardian validates only the structure of those files: the named fields must be present, and no code compares an actual write against the declared list. One recorded violation makes that concrete. A fix modified a file that its own declaration had marked read-only. Nothing mechanical caught it. A reviewer did, at the second review gate, and flagged it as high severity. The workflow stopped for a human decision, and the same day it was resolved by widening the scope rather than reverting the edit.

So the boundary that looks like enforcement is actually a review prompt, and it worked because somebody read the diff. That is the honest split everywhere in this piece: some boundaries can be enforced by code, and the rest have to be caught by a person looking. Review attention is the scarce resource, which is the argument for mechanising the ones you can.

At reader scale none of this machinery is required. Two sessions, one repo:

git worktree add ../proj-<task> -b <task>

Each task gets its own directory, so neither can write over the other. No marker, no hook, no mutex between them. The discipline is one sentence: while another task is open, do not edit in the main checkout. And take the other half of the incident with you, because it is the half that actually preserved anything. Before you remove a worktree, a branch, or a session, move the proof out of it: commit the test output, paste the verification record into the pull request, leave the summary somewhere that outlives the directory. Deleting a workspace you have not read from is how a complete-looking record ends up one revision stale.

Start with the habit. Automate the refusal on the day remembering it stops working.

The one who writes is not the one who reads

Ten phases were marked complete and zero files were created. The work had been done in a workspace that was later removed, so by the time anyone could check, there was nothing left to check.

What makes that incident worth leading with is its shape. The fabrication was not in the code, because there was no code. It was in the reporting layer. Subagents reported task completion without producing anything, and the completion was accepted because the actor reporting it was the actor being trusted.

The gate that now blocks it is small, and it is named after the incident in its own header. It refuses to mark a phase complete when the workspace has no commits behind it. The executor certified its own success, and the certification was invented.

I have told the other version of this story already, the payment refactor that migrated protected state, invented a handler it had been forbidden from writing, tested its own work and reported itself ready to deploy. That one is the case study in Agents Need Architecture, Not Prompts. It stays there. The exchange-rate failure leads here because it is cleaner: no invented code at all, just an invented completion.

The deeper problem is not dishonesty, and framing it as dishonesty leads to the wrong fix. Judging work requires standing outside it, and the agent that wrote the work is the one participant that cannot. A contractor signing off their own electrical installation is the same objection: not that contractors lie, but that nobody independent looked before the wall closed. The arrangement to avoid is one actor defining the task, executing it, and evaluating the result. In my experience of agent workflows, that arrangement is the largest single operational risk. When nothing external checks the claim, “done” is a statement about the agent’s confidence, not about the repository.

So the rule is a prohibition rather than a habit. A phase cannot close until a reviewer that did not do the work has checked the evidence and passed it. Self-certification without independent evidence is forbidden, and so is validation that happens implicitly or in the background as a side effect of something else.

That reviewer pass runs once the implementation is in place, and a passing result is a precondition for marking the phase complete. Note what independence attaches to. The reviewer may read the worker’s own diff, and usually should, since the diff is the most direct evidence of what changed. Independence belongs to the act of review, not to who authored the artefacts being reviewed.

My own version of this is a deletion story rather than an evolution story, and the difference matters. The old verifier, which worked by having the agent present a token proving it had done the checks, was not gradually replaced. It was deleted outright, 1,721 lines plus its test file, in a single commit, and replaced by a 212-line module that does the opposite thing. There was no window where both ran. The lesson is not that the validator improved. It is that an entire verification mechanism was removed because its existence made self-certification possible.

What verification requires now is a per-phase check performed by an independent reviewer, across five questions. Was the goal met. Was the plan completed. Were the open findings closed. Were the invariants preserved. Did the change introduce anything new that nobody has looked at.

Each of the five consumes evidence rather than assertion: the list of files actually modified, the plan, and a snapshot of the open findings taken before the phase started, which is what lets the last question be answered at all. The output is a structured pass, warn or fail, with a hash of the reviewer’s output recorded.

The hash is worth being precise about, because it is the part people over-read. It ties a verdict to the exact bytes of the evidence it was computed over, so you can tell later which read of which diff produced it. It does not establish that the judgment was right, and it does not by itself prove anyone was allowed to close the phase. A hashed pass is still somebody’s read of the evidence, and treating the hash as proof is how a process ends up looking stricter than it is.

At reader scale, none of the gates matter yet. The agent says the tests pass. You open a clean shell and run them yourself, then read every hunk of the diff rather than the summary the agent wrote about the diff. For anything production-bound, hand the diff to a different agent and ask what changed that the first one did not mention. The minimum version of this wall is not a verifier. It is the rule that whoever writes the code is not whoever signs it off.

Three practices, no framework

Strip the repo away and three practices remain, each usable this afternoon with nothing installed:

  • give one component the write path to your source of truth, and verify a claim before it reaches that write path
  • put each task in its own workspace, and before you tear a workspace down, move the proof out of it
  • never accept completion from the actor that produced it, and ground acceptance in an artefact someone else read

There is no order to adopt them in. Two of these walls surfaced together because one January episode produced two fixes, and the third took months longer to understand and turned out to need a redirect rather than a lock. That is a fact about this repository’s year, not a curriculum.

Now the objection from the top of the piece. Is this overbuilt?

For one agent on one task, yes. None of it earns its keep, and the three practices in a session with a single worker are just habits you already have: you write the progress file, you read your own diff. The governance layer exists because those habits stop scaling at the same rate as the fleet, not because they are wrong.

What the failures above justify automating is the narrow set of decisions that can be expressed as a refusal: who may write the record, whether this write belongs in this tree, whether this claim has been read by somebody else. Those three are worth mechanising because all three fail silently and all three are cheap to check. Everything else in my setup is a habit wearing infrastructure, and I would not recommend copying it.

What stays dependent on a person is the part that caught the real violation in this piece. Somebody read the diff and noticed the file that had been declared off limits. No mechanism did that, and I do not expect one to. Budget for the reading.

I did eventually automate the three refusals, as a governance layer called ACP, inside a platform I work on. It is the implementation of these practices rather than a prerequisite for using them, and it is not a general reliability guarantee. My recollection of why I automated rather than kept doing it by hand is unglamorous: enough projects were running in parallel that enforcing the practices manually had become its own job. I am not going to dress that up as a decision point with a date on it.

If you do one thing tomorrow, pick the file that is the record of what is true, and take the pen away from everyone else. That is the whole first wall, and it takes an afternoon.

Notes

Receipts for anyone who wants them, in the order they appear.

  • The state-authority root cause is from commit b049c4fda (2026-01-30). The guardian check is check_state_authority (guardian.py:2693); the two refusals beside it are guard-approve-via-bash.py and safety-file-creation.py (Alignment Spec §B.1).
  • The declaration files are counted at the repository head: 59 scope.yaml files carrying explicit write.files and read_only sections. The scope violation is finding F-G2-SCOPE-001 (2026-05-19); middleware/audit.go was declared read_only and Codex’s Gate 2 review raised it as HIGH. Structure-only validation is guardian.py:1791, which requires six named fields.
  • The two implementation hooks declare the same tuple, IMPLEMENTATION_DIRS = ("apps/", "packages/", "internal/", "cmd/"), at guard-active-spec.py:33 and guardian.py:28. The phase gate is guard-phase-complete.py; its header carries the incident reference.
  • The deletion is commit f28a611ac (2026-02-03), removing opencode_piv.py (1,721 lines) plus tests. The 212-line replacement is the runtime adapter at .claude/hooks/piv.py; the canonical module, .agents/skills/implementation-execute/piv.py, is 238 lines.
  • The scope incident is dated 2026-06-05, at the resolve skill’s Step 4.5 and Step 5. The exchange-rate spec, add-exchange-rate-infrastructure, is dated 2026-01-25.
  • The governance layer is Trustless ACP, and the platform is Trustless, an agent-native banking and exchange platform. ACP is one component inside it.
  • Article 3 of this series turns the four moves into a template: scope the work, assign it to an actor, execute inside the workspace it was given, verify against evidence before anything is recorded as done.