Two ways I tried and failed to manage context across multiple AI agents, and what I built instead

I keep seeing this question in the community. Here's what I actually tried, why it broke, and what I ended up shipping.

The problem

When you're running multiple agents across a session (one that writes, one that reviews, one that deploys) you need them to share state. Not just conversation history. Actual verified state: what changed, what's blocked, what evidence exists that a task is done.

What I tried first (and why it failed)

Attempt 1: I maintained the handoff notes myself

After every session, I updated a Markdown file. This worked until I finished tired and skipped the update. The next agent read stale context as if it were current. Worse: even when the file was accurate, I was still the router, a human bottleneck between every agent transition.

Attempt 2: I let agents maintain the notes

The agent finished its work, updated the handoff, and the next continued from there. Then I noticed the real problem: an agent could write "tests pass" just as easily as it could actually run the tests.

Agent A would write: "Refactored auth. Tests pass."

Agent B had no idea which tests ran, against which version, or whether the slow integration suite was skipped. It didn't inherit verified work. It inherited a story about the work.

What I built

Three principles became the foundation:

State in fields, not paragraphs. What changed, what's blocked, what's unresolved as explicit fields, not embedded in a summary. An agent can't make unresolved work disappear by writing a nicer paragraph.

The agent that does the work can't approve it. A separate reviewer starts from the original goal and inspects the result directly, not from the implementing agent's explanation of why it's probably done.

Machine-checkable claims need evidence attached to a specific version. "Tests pass" is a claim. A test result attached to the exact commit hash is evidence. If the code changes after the evidence was produced, the evidence doesn't automatically transfer.

This became an open-source project (link in comments).

Results over 30 days of dogfooding

4,172 PRs merged across 16 repositories, one maintainer

Coordination overhead stayed roughly flat from 3 agents to 10; adding agents stopped adding to my mental load linearly

Stale-context bugs dropped to near zero because agents can't declare victory without attached evidence

The number I actually care about: my day looks the same with 3 agents as with 10. That wasn't true before.

What didn't work

The reviewer agent still occasionally fails to distinguish "the goal changed mid-task" from "the implementation is wrong." We handle this with an explicit goal-hash that both agents reference, but it adds friction. Still working on the right UX for that.

Has anyone else hit the "agent self-reports done but the work isn't clean" problem? Curious what enforcement patterns people are using, if any.