How do I tell an AI agent what "done" means?

Write what "done" means on the task itself, as a markdown checklist, before the agent starts. In Done that is the task's acceptance_criteria field: one line per condition someone could verify, written as "- [ ] tests pass on the branch tip". The agent reads it first, ticks each line with check_criterion as it actually satisfies it, and then asks for completion. Ticking every box does not close the task; a human still approves.

Why isn't a good task description enough?

A description tells an agent what to do. It doesn't say what a finished result looks like, so the agent decides that for itself, and an agent left to decide will often stop at the first plausible output. Acceptance criteria are the other half: the checkable bar the result is judged against, not more instructions. Done's own tool descriptions draw that line, and ask the agent to check its work against the bar before it proposes completion.

What does a criterion that an agent can use look like?

• Make it checkable by someone else: "tests pass on the branch tip", "the page loads under 200ms", "the summary lists every overdue invoice". "Looks good" is not a condition.
• One line per condition, so each can be ticked on its own and a half-done task reads as 2/4 rather than as nothing.
• Write it as a markdown checklist, lines starting "- [ ] ". A plain bullet list or a paragraph is stored fine, but it's prose to Done: the task reports no criteria, and there is nothing for the agent to tick.
• Put the how in notes_for_agent or the description, and keep the criteria to the what. Mixing them makes the bar move with the instructions.

How does an agent report progress against the criteria?

It calls get_task, which returns criteria with met, total and each item's zero-based index, then check_criterion with the task id and that index as it satisfies each line. Passing done:false unticks one, and ticking an already-ticked box changes nothing. Each real change leaves a line in the task's history such as "met 'tests pass' (2/4 criteria met)", so you can see how the work moved without a running commentary in the thread. Ticking is limited to tasks in the agent's own lane.

Does ticking every criterion finish the task?

No, and that is deliberate. check_criterion is a progress report; the response only tells the agent that all criteria are met and that it can propose completion. Closing is a separate act. A task that isn't marked agent_ok goes to pending_approval through propose_completion and waits for you, and only on an agent_ok task can the agent call complete_task itself. So a checklist makes the agent's claim easier to check, and the approval gate is what stops the claim being final.

Can the agent rewrite its own criteria?

It can edit the field with update_task, which is exactly why you shouldn't take a full checklist at face value. For a human's task it can instead use propose_edit, which shows you the change as a current-versus-proposed diff that you accept or dismiss field by field. When you review, get_evidence returns the criteria progress along with every receipt, deliverable and run trace, plus the task's edit history and agent_edits_since_human, the count of agent edits since a person last touched it. If that number isn't zero, read the criteria before you trust the ticks, because criteria rewritten after the work started are not the bar you agreed to.