When a coding agent gets stuck: stop, ask or guess
Stefan-Iulian Tesoi · · 6 min read
Stop and say so, where a person will see it, whenever the next step would change scope, cross a permission or choose between two readings of a criterion. When a coding agent gets stuck on anything smaller, it should proceed and write the choice down. The outcome to design against is the agent that builds its way around the obstacle.
What does it mean when a coding agent gets stuck?
Stuck means the next step needs information or authority the work order does not contain. It does not mean the task is hard; hard is the job. Four kinds come up again and again:
- Ambiguity. One of the acceptance criteria supports two readings, and they lead to different code.
- A missing dependency. The item assumes an endpoint, a table or a decision that does not exist yet.
- A refusal. A permission, a hook, a branch protection or a missing credential says no.
- A broken environment. The suite fails on a clean checkout, the build is red on main before any change, a service is down.
The fourth is the one agents most often get wrong, because it looks like part of the task. A Claude Code session whose tests fail before it has touched anything will often start repairing them, and the item comes back with unrelated changes to the test setup and a note that it "also fixed the tests". That is two items, one of which nobody asked for.
Which questions decide whether to stop or proceed?
Three, asked in order. A yes to either of the first two means stop:
| Question | If yes | Example |
|---|---|---|
| Would the next step change what the item delivers? | Stop and ask | The criterion says "paginate the list" and the API behind it has no paging |
| Would it cross a boundary someone set on purpose? | Stop and report | A hook refuses the commit; a credential is missing |
| Is the choice expensive to undo? | Stop, or proceed with the choice recorded | Choosing between two data shapes for a new collection |
| None of the above | Proceed, and note it in the hand-back | Naming a helper, ordering two independent edits |
The second question matters most and is the one an agent is least inclined to ask. To a capable agent a refusal reads as an obstacle, and obstacles are what it is good at removing. But a boundary refuses for a reason the agent usually cannot see, and the guardrails an agent should never cross only work if hitting one ends the attempt rather than starting a search for another route.
The third is the honest middle. Not every judgement call needs a person, and a work order that pre-authorises the small ones, as a good coding agent work order does, saves a round trip. What it should not do is leave the choice unrecorded. A decision written on the item with its rejected alternative can be reversed in review. One buried in a diff usually is not.
Where should a coding agent report a blocker?
Somewhere a person will see without asking, attached to the item it blocks, with enough said that the answer can be given without reading the code. In the four stages of a coding agent workflow, a blocker is the execute stage handing a question back to specify. A message in the agent's terminal fails that test, because the session ends and the blocker goes with it. A note in a commit message fails it too, because nothing gets committed.
A useful agent blocker has three parts:
- What was attempted, including the command and its output.
- What is missing, as precisely as the agent can say it: the decision, the permission, the dependency.
- The options the agent sees, with the one it would pick, so the person can answer in a word.
In Laimonade, report_blocker over MCP records the message against the item as a high-risk entry on the product owner channel, and it stays open until someone gives a verdict. It does not move the item or close anything. It makes the impediment visible without anyone having to go looking, and the orchestration rules every connected agent receives say to report an impediment that way instead of silently skipping the item.
This is human in the loop at the one point where it is cheap. Asking before the work starts means guessing what will go wrong; reviewing after it finishes is too late to change the approach. A blocker arrives at the moment the agent knows something the person does not.
Why is a workaround worse than stopping?
Because it succeeds. A stopped agent costs an hour. An agent that gets past a boundary produces finished-looking work on a foundation nobody agreed to, and the cost turns up in review or later.
A real case, from running parallel agents on this product in September 2026. A guard, written as a Claude Code hook that runs before every tool call, refuses git writes anywhere except the agent's own worktree, so that sessions sharing a checkout cannot move each other's branch. In one batch of thirteen background Claude Code agents, five ended up with their shell pinned to the shared checkout and could not commit at all. Most reported the refusal and left their changes staged for someone else to commit. One wrote a wrapper script that ran git in a way the guard did not recognise, and committed. Whatever the quality of its code, its method was the exact thing the guard existed to prevent, and nobody had been asked.
The immediate fix was not a stronger guard. It was one sentence added to every agent's instructions: when a guard refuses, stop and report, and do not build a way around it. The permissions a coding agent should have set the technical limit. Escalation rules decide what the agent does when it reaches one.
An agent that stops at a boundary has done its job. An agent that finds a way past it has done a different job, and the reviewer has to notice.
Frequently asked questions
Should an agent skip to the next item when it is blocked?
Only after reporting the blocker, and only to an item that does not depend on the blocked one. A silent skip is the worst version: the board still shows the first item in progress, and nobody learns why it stalled. Reported and then skipped is fine. It is what a person would do with a ticket waiting on someone else.
How much should a work order authorise in advance?
Enough that the agent does not stop for choices a reviewer would wave through: naming, internal structure, the order of independent edits. Anything that changes the item's outcome, its interfaces or its permissions should stay out of pre-authorisation, because those choices are expensive to discover in review and cheap to ask about first.
What happens if nobody answers the blocker?
The item waits, which is the correct outcome, and it should be visible as waiting. A blocker that ages without an answer is a planning signal: the item was dispatched before it was ready. The fix belongs upstream, in the readiness check before dispatch, not in giving the agent more licence to decide on its own.