Consider a simple request: add CSV export to a reporting screen.
The coding agent adds an export button, connects it to the data already displayed, writes a test that checks a download starts, and runs the build. Everything passes. Its final message lists the changed files and says the task is complete.
The first person to use the feature exports a full quarter of data.
The file contains only the fifty rows that happened to be loaded in the browser. Dates use the viewer's local time instead of the reporting timezone. A larger export locks the page for several seconds.
The agent did not lie. It reached the end of its execution path.
The engineering work was still open.
That distinction matters because coding agents are becoming good at ending a task convincingly. They can change the code, run checks, and produce a clear account of what they did. None of those actions decides whether the result deserves to be accepted.
The difficult question is no longer whether the agent stopped.
It is whether the evidence is strong enough for an engineer to accept responsibility for the change.
Execution has an end. Acceptance needs a case.
An agent can stop for several legitimate reasons.
It may have completed the actions in its plan. The tests it knows about may pass. It may have reached a turn, time, or cost limit. It may be blocked by missing access. It may believe the requested outcome exists.
These are useful execution states. They are not interchangeable with engineering acceptance.
The export example makes the gap visible. The agent had enough information to produce a plausible implementation. It did not have a complete definition of the product outcome, realistic operating conditions, or the evidence needed to prove both.
A completion summary cannot repair that omission after the fact.
The team needs a clearer agreement before the work begins.
The Completion Contract
A Completion Contract is a short agreement that defines what must be true before agent-generated work can be accepted.
It has five clauses:
1. Outcome What must the user, system, or team be able to do when the work is complete?
2. Evidence Which checks and observations will demonstrate that outcome?
3. Reality conditions Under which realistic data, load, integration, permission, and failure conditions must the result be tried?
4. Stopping rule What causes the loop to accept, revise, escalate, or stop without accepting?
5. Acceptance owner Who has the authority and responsibility to decide that the evidence is sufficient?
This does not replace acceptance criteria or a Definition of Done. It makes them more explicit for a workflow where the same agent may implement the change, run some checks, and explain its own work.
The point is not more paperwork. The point is preventing an execution state from silently becoming a product decision.
For the export feature, the contract might look like this:
Outcome
Users can export every record matching the active filters.
Evidence
Tests cover filtering, pagination, timezone handling, empty results,
permission failures, and large exports.
Reality conditions
Use the feature with a small account, a large account, different timezones,
slow network conditions, and restricted permissions.
Stopping rule
Accept when required evidence passes and product behaviour is clear.
Revise when evidence fails.
Escalate when limits, retention rules, or security expectations are unclear.
Stop without accepting when the environment or budget blocks verification.
Acceptance owner
The engineer responsible for the change, with product or security review
where the unresolved decision requires it.That contract changes the agent's job.
It no longer needs to decide whether the work is complete. It needs to produce the change and the evidence required for a separate acceptance decision.
Tests are evidence, not the whole case
Tests remain essential. They are often the fastest and most reliable way to check behaviour that can be specified mechanically.
The problem begins when a passing suite is treated as a complete account of the product.
A test only proves the assertion it contains. If the export test checks that a file downloads, it may say nothing about whether the file contains all records, preserves timezone semantics, remains responsive, or handles realistic volume.
Agent-generated code can therefore satisfy an incomplete suite perfectly.
This is not a criticism of testing. It is a reason to make the evidence portfolio broader.
For product-facing work, the Completion Contract should usually cover four kinds of evidence:
- Static evidence: the code builds, type-checks, follows required policies, and introduces no known static failures.
- Behavioural evidence: unit and integration tests cover the specified behaviour and important failure paths.
- Runtime evidence: the application starts, real integrations connect, and the feature operates outside the test harness.
- Product evidence: someone uses the feature under realistic conditions and judges whether the outcome is clear, useful, truthful, and acceptable.
A fifth question belongs in review even when it cannot be reduced to a single check:
What kind of system did this change leave behind?
The feature may work while duplicating responsibility, hiding complexity, or making the next related change harder. That is still relevant evidence.
Stopped is a valid state. It is not the same as done.
Coding-agent workflows often need firm limits. Maximum turns, elapsed time, model cost, permissions, and tool budgets prevent the agent from continuing indefinitely.
Those limits should remain.
The mistake is labelling every clean stop as success.
A useful controller distinguishes at least four outcomes:
- Accepted: the required evidence exists and the acceptance owner approves.
- Revise: the evidence contradicts the intended outcome or exposes a correctable problem.
- Escalate: the next decision is ambiguous, consequential, or outside the agent's authority.
- Stopped without acceptance: a budget, permission, environment, or dependency prevented the required verification.
This distinction is small in code and significant in practice.
It prevents a blocked agent from sounding successful. It also prevents a team from interpreting "tests pass" as the only terminal state that matters.
The completion summary still matters
The agent's final message is useful when it is treated as an index into the evidence rather than the evidence itself.
A strong completion record should state:
- what changed
- which commands ran
- which checks passed or failed
- which realistic scenarios were tried
- what was not verified
- which risks or assumptions remain
- why the workflow stopped
- what decision is now required from the reviewer
That is a better summary because it makes uncertainty visible.
It also makes review faster. The engineer can follow each claim to a test result, runtime observation, screenshot, log, or unresolved question.
The summary supports judgement. It does not replace it.
A practical test for your next agent task
Before starting the work, write the Completion Contract in a few lines.
Do not ask the agent only to implement the feature. Give it the outcome, the evidence it must collect, the realistic conditions it should try, and the situations that require escalation.
When the agent stops, hide its completion summary.
Then review what remains:
- Can you show the intended outcome?
- Can you reproduce the evidence?
- Has the feature been used under conditions that matter?
- Are unresolved risks named?
- Is the stopping state accurate?
- Is there a clear acceptance owner?
If the answer is yes, the change may be ready.
If the answer is no, the agent may have finished executing. The engineering work has not yet crossed the Completion Contract.
The most useful question for teams adopting coding agents is therefore not:
How do we make the agent more confident that it is done?
It is:
What evidence would make us willing to accept responsibility for this change?
That is a question the engineering system can answer, even when the agent cannot.
---