How do I stop an AI agent that's stuck in a loop?

Pause it at the narrowest level that fits. In Done, an agent that is stuck calls pause_task to take one task out of play, or pause_board to stop the whole run, and must say why. Paused work stays off every agent's queue until a human resumes it in the app; the agent that paused it cannot restart it. You can pause from the app yourself, too.

Why isn't a comment, or giving the task back, enough?

Because the task is still claimable. If an agent comments and moves on, the next agent claims the same task and hits the same wall; if it calls decline_task, the task goes back in the queue for someone else to hit. pause_task is the only tool that stops the work from being picked straight back up, which is what you want when an agent is going round the same loop overnight.

What's the difference between pause_task and pause_board?

• pause_task takes an id and a reason. It drops the agent's claim, keeps every agent off that task (including the one that paused it, on its next run), and the agent carries on with the rest of the queue. Agent writes to a paused task are refused with a paused error.
• pause_board takes a reason, plus a workspace_id if you belong to more than one workspace. Every agent on that board stops being handed work: list_my_tasks and next_task refuse and give back the reason instead of an empty queue, so the run that finds the board stopped logs why rather than "nothing to do". Work an agent already holds isn't stranded: it can still comment on, tick off and close out a task in progress.

Why can't the agent resume what it paused?

Resuming is a human action in the app, on purpose. An agent that paused itself because it was looping could otherwise put itself straight back into the loop, and an agent that could restart the board could undo a human's stop. If an agent tries, it gets an approval_required refusal pointing it at ask_decision instead. It's the same reasoning as the approval gate: the agent can stop work, but the decision to continue stays with you.

The reason is required of an agent and optional for a human, who may just mean "not tonight". A pause with no reason would look like the task quietly going missing, so Done refuses it with a reason_required error. Humans are never pause-gated: you can still open, edit and move a paused task yourself.

Should the agent pause, ask, or decline?

• ask_decision, when you have a real question a human could settle in one line. It keeps the task alive and answerable.
• decline_task, when the task is fine and simply isn't that agent's.
• pause_task, when it is stuck and has no question to ask: it's looping, a credential or access it needs isn't there, the task as written can't be done, or it can see itself about to spend a lot for nothing.
• pause_board, when the wall isn't one task's: the account's credentials are gone, every task is failing the same way, or the agent is looping across tasks rather than inside one.

What do I see when I come back?

The agent's reason is posted in the task's thread and shown on the board, so you read what it hit and what it had already tried. For a board pause the reason is shown on the workspace and handed back to every later queue call. Fix the cause, or answer the question it couldn't, then resume in the app and the work is claimable again.