How do I know whether an AI agent actually finished a task?

You know an AI agent actually finished a task when a check you trust, run independently of the agent, passes against the current code and the changes match what the task asked for. Anything less is one of two weaker states that look the same at a glance: the process exited, or the agent said it was done. A process exits when it crashes, hits a limit or simply stops. An agent says done when it believes it is done, and that belief is shaped by what it ran, what it skipped and what it misread. Neither tells you the work is correct. This page is a checklist for the moment you see a finished session and need to decide which of the three states you are really in. It works with any agent and takes a few minutes per task. The reasoning behind treating the agent's word as a claim is in self-reported versus independent checks.

Three states that look alike

Start by naming the state honestly, because each one calls for a different next step.

Process exited. The terminal is quiet or the job reports an exit code. That says the program stopped. A zero exit code from an agent CLI usually means the session ended normally, not that the task's goal was met. If this is all you have, the task's status is unknown.

Agent says done. The final message lists changes and often says tests pass. Treat it as a report to check, not a result. Agents summarize from their own transcript, and the summary can include steps they planned but did not run, or a test run that happened before their last edit.

Verified. Someone, or something you control, ran the agreed check after the last change, it passed, and the diff stayed inside the task. Only this state should move work to done.

An example from BRAIN FLUID's own development testing: on an early workflow route, a completion report asserting a pass was accepted while the app still failed a test. The response was to make the system run the checks itself instead of reading the agent's report.

The checklist, in order

Step 1: Find the criteria. What did the task say finished looks like? If there is no written criterion, you cannot verify anything, only form an impression. Write one now, before reading the diff, so the diff does not shape it.

Step 2: Run the check yourself. Use the command the task names, on the current working tree, in a fresh shell. Do not reuse output pasted into the agent's message.

Step 3: Compare changed paths with the task. git status and git diff --stat show every file touched. Anything outside the expected area needs a reason, and untracked files count too.

Step 4: Read the test diff separately. If tests changed, ask whether they changed to match a new requirement or to match the new code. A deleted assertion, a widened tolerance or a newly skipped test can turn red to green without fixing anything; test tampering covers the patterns.

Step 5: Pin the revision. Note the commit or tree the check ran against. If anything changes after that, the result describes old code, and the check has to run again.

How to tell the failure modes apart

When the checklist fails, the step where it fails points to the cause.

No criteria. The task was 'improve the export' and the agent improved something. That is a task-writing problem, not an agent problem; see writing tasks agents can finish.

Your run fails where the agent's passed. The agent ran a narrower set of tests, ran them before its final edit, or ran them in a different environment. Look for the exact command in its transcript. Tests that pass for the agent but fail later goes through each case.

The check passes but the paths are wrong. The work can be correct and out of scope at the same time. Split the extra changes off and review them as their own change.

The check passes only because the tests changed. Treat the task as unfinished until a person agrees with the test change and the reason for it.

Everything passes and you still doubt it. That usually means the check is too narrow for the risk. Add the missing case to the criteria instead of relying on a closer reading of the code.

Making finished mean the same thing every time

The checklist is slow if you rebuild it for every task. Build it into the workflow instead.

Write the acceptance check into the task before the agent starts, as a command anyone can run: 'pytest tests/export passes, and no files outside src/export change.' The agent then aims at the same target you will check.

Keep a separate state between the agent saying done and done. Many teams call it verify or review. Work sits there until the independent check runs and a person accepts it. A board with that column makes the three states visible instead of collapsing them into one; board states for agent work explains the layout.

Record the evidence with the task: the command, the revision and the result. A week later, when someone asks whether this was really done, the answer is a record rather than a recollection.

Finally, decide what done means for your project and write it down. For some teams it means merged and checked; for others it also means a person tried the feature. Either works if it is applied every time.

QUESTIONS

Does a zero exit code mean the agent completed the task?

No. An exit code reports how the program stopped, not whether the task's goal was met. An agent CLI can end normally after giving up, after hitting a limit or after doing the wrong thing well. Treat exit status as the start of verification: run the task's check yourself against the current code before calling it finished.

Should I trust the test output an agent pastes into its summary?

Use it as a pointer, not as evidence. Pasted output may come from an earlier run, a narrower selection or a different environment, and it may be summarized rather than copied. Rerun the named command yourself on the current tree. If your result matches, good; if not, the difference tells you where to look.

What should a definition of done include for an AI agent task?

A runnable check, the area of code expected to change, and anything that must not change, such as public interfaces or existing tests. Write it before the agent starts so it is a target, not a description of whatever happened. Name who accepts the work, since an agent marking its own task done is still only a claim.

RELATED GUIDES

• How to read BRAIN FLUID reports and provenance
• How to read project progress in BRAIN FLUID Build

RELATED HARNESS PAGES

• Self-reported vs independently run checks for AI agent work Self-reported vs independently run checks for AI agent work: why an agent's own "tests pass" is weaker than a check the system runs itself.
• human review of agent output Human review of agent output: what to inspect before accepting AI changes, and how recorded outcomes make the review honest.
• evidence gates for AI work Evidence gates for AI work: separate proposed from approved execution, run checks, and record outcomes so acceptance rests on evidence.
• When an AI agent edits the tests to make them pass When an AI agent edits the tests to make them pass: the signs, why it happens, and how to keep test files out of an implementation task's scope.
• kanban for AI agents Kanban for AI agents: the board states that matter when software does the work, including review, blocked and decision owed.