"Done." It's probably the most satisfying word in a coding-agent session.
It can also conceal three very different questions:
- Was the work permitted?
- Did the work actually happen?
- Did the result achieve what we needed?
All three matter. A single green checkmark can make them look like one decision.
A small scenario
Imagine asking a coding agent to update validation logic under src/**.
It edits the code, reports that its tests passed, and declares the task complete. Everything looks fine until you ask what the status actually proves.
- The task was assigned to an implementer with a declared
src/**write scope. But did the runtime enforce that scope for the tools the agent used? - The plan called for independent review. But who actually reviewed the final revision, and was that the revision ultimately merged?
- The agent says the feature works. But was that checked in the environment where users experience it?
These are separate evidence problems. Passing a test suite answers something useful about the tested code. It cannot, by itself, answer the other two questions.
One failure you can reproduce without an AI model
I maintain Agent Role Contracts (ARC), an open-source checker for declared agent roles, scope, reviews, and handoffs.
Its quickstart uses a deliberately simple setup:
| Declared rule | Requested task | Preflight result |
|---|---|---|
Implementer may write within src/** | Update src/example.mjs | PASS |
| Same declared rule | Update secrets/production.txt | TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY |
| Same declared rule | Correct the request to src/example.mjs | PASS |
You can run the published source demo with Git, Node.js 22.5+, and npm:
git clone https://github.com/suirindo/agent-role-contracts.git npm --prefix agent-role-contracts run demo --silent The repository's documented sequence is PASS → expected FAIL → PASS. It reads fictional JSON declarations; it starts no agent and writes no target file. The intentional rejection demonstrates one narrow property: a requested scope conflicts with the declared authority.
That's useful precisely because the check has a clear boundary. A declaration PASS does not authenticate the executor, enforce filesystem permissions, verify an actual review, or authorize execution. The host system must supply those controls.
A completion report with three layers
For real work, I'd like completion reports to distinguish these layers:
| Layer | A useful receipt | What remains to establish |
|---|---|---|
| Contract | Current task, scope, responsible role, review route, and the check result | Whether the declared actors and permissions are genuine |
| Execution | Exact commit or artifact, command results, and observable side-effect receipts | Whether anything unobserved or uncertain occurred |
| Acceptance | Independent review of the exact candidate, acceptance tests, and production observation where relevant | Whether the user-facing outcome meets the original request |
That produces a much more useful sentence than "Done":
Implementation completed and local tests passed. Independent review is pending. Production behavior has not yet been checked.
It is less triumphant. It is much more actionable.
The uncomfortable question
As agents become more autonomous, the word complete is becoming a product-interface decision. If the interface compresses implementation, verification, and acceptance into one status, the human operator inherits the uncertainty later.
Some teams will reasonably keep these stages separate in CI, IAM, and their runtime. Others may want a small declaration check before dispatch. ARC handles that narrower declaration problem; the broader evidence chain belongs to the surrounding system.
For teams using coding agents today: what is the minimum evidence you require before an agent is allowed to say "done"?
Is a passing test suite enough for internal tasks? Do you require an independent reviewer, an exact artifact identifier, a live check, or different thresholds depending on the side effect?
I'd be particularly interested in answers from teams that have already found a simpler solution.
Disclosure: I maintain Agent Role Contracts at Netsujo. The example above is a synthetic declaration check, not a production incident. Read the quickstart and limitations.
