When an Agent Should Stop and Ask a Person

There are eight recurring situations where more edits make things worse. Put this table in your prompt review checklist.

The last row matters more than it looks. A good verification prompt says explicitly: if a command fails for an unrelated reason, stop and report the failure instead of editing unrelated files, as Steve Kinney's TDD prompt example puts it. Without that line, agents drift into fixing the environment rather than the task.

A threshold turns a vague instruction into a decision rule. Three numbers do most of the work.

Fix attempts per failing test: two or three. After the second identical failure, the agent is usually repeating a theory, not learning. After the third, the patch is more likely to be a workaround. Choose two for data migrations, payment code, and anything touching customer records; choose three for UI and test-only changes. Whatever you pick, write the number into the prompt.

Total edits before handoff: a soft cap on the whole task. A cap between ten and twenty edits stops the slow-burn runaway where each change looks small. If the agent crosses the cap, the handoff message must list every file touched.

Time or token budget: one budget per task. When the budget runs out, stop and report. Guidance on agent instructions makes the same point plainly: avoid unlimited retries and open-ended loops, and define completion and stop conditions so the agent knows when work is actually finished rather than merely quiet.

Worked example. A ticket says "invoice totals are off by a cent." The agent writes a regression test, sees it fail, fixes rounding, and reruns the suite. The suite is still red, but in three unrelated billing tests. Under the rules above, that is one unrelated test failure plus a possible regression, not a signal to keep editing. The agent stops, lists the three failing tests, shows the rounding diff, and asks whether the rounding change is in scope. A human decides in about a minute; the agent, left alone, might have rewritten three test files and hidden the real regression.

The system prompt is the right home for behavior that must not change mid-conversation. It sets role, scope, constraints, and tools before the model sees any user message, and most providers treat it with higher priority than later turns, as Decagon's explanation of system prompts describes. Stop rules are exactly that kind of constraint.

A handoff block that works in practice has four parts per rule: a condition, a threshold, the evidence to collect, and the message format. Here is a compact version you can adapt.

STOP AND ASK A PERSON when any of the following is true.

1. Failing test.
   Condition: the same test fails after 2 fix attempts.
   Collect: test name, attempt count, last error output, files changed.
   Do not: delete, skip, or edit the test.

2. Missing or contradictory requirement.
   Condition: acceptance criteria are absent, or two requirements conflict.
   Collect: the exact conflicting text, quoted, with where it came from.
   Do not: pick an interpretation silently.

3. Missing secret or credential.
   Condition: a tool returns 401, 403, or a permission error.
   Collect: the tool, the environment, the error code.
   Do not: try other credentials, read env files, or guess headers.

4. Irreversible or production action.
   Condition: the next step deletes data, rewrites history, runs a
   migration, deploys, or changes a shared environment.
   Collect: the exact command and what it affects.
   Do not: run it.

5. Out of scope.
   Condition: the request needs files or systems outside the declared scope.
   Collect: the path requested and the allowed paths.
   Do not: widen scope on your own.

HANDOFF FORMAT
STOP REASON: <one of 1-5>
EVIDENCE: <bulleted facts, no opinions>
WHAT I TRIED: <numbered list, max 5>
QUESTION: <one question a person can answer in one reply>

Two refinements matter. First, never let the agent put the question and the evidence out of order; reviewers read the reason line first and decide whether to engage at all. Second, keep the "do not" clause explicit. Prompts do not enforce anything, so the real guardrails (blocking destructive commands, restricting secrets) belong in application code and runtime permissions, a point the promptessor guide stresses: instructions are not a security boundary.

Test-driven development makes stop rules sharper because it gives the agent an executable definition of done. The red-green-refactor loop is simple: write a failing test, make it pass with the minimum code, then clean up, as Martin Fowler describes TDD. A failing test after the retry budget is thus a clean stop signal, not a judgment call.

Agents need this explained explicitly. Without instruction, Claude tends to write the implementation first and then tests that match it, which defeats the purpose, as a community guide to TDD with Claude Code observes. The fix is a prompt that demands the failing assertion be shown before any production code changes, and a rule that the test itself is read-only to the agent. If the agent believes the test is wrong, that is stop condition 2, not an invitation to edit the test.

The Builder.io walkthrough makes the same argument from the other direction: a prompt like "make a login button" is a gamble, while a test suite that defines disabled, loading, and error states gives the agent a concrete target it can iterate against (Builder.io on TDD with AI). The test is the finish line. Everything past it is scope creep.

There is a nuance worth knowing. TDAD's authors found that telling a smaller model how to do TDD was less useful than telling it which tests to check: generic TDD prompting increased regressions to 9.94% while a graph-based test map cut them by 70%, from 6.08% to 1.82% (TDAD). In practice, wire your stop rule to a specific verification command, not a slogan. "Run npm test -- src/billing and stop if it is not green after two attempts" beats "follow TDD strictly."

The three "I need a human" conditions are easiest to encode because the evidence is short.

Requirement gaps show up as an empty field in the ticket or a sentence that contradicts another. Ask the agent to quote the conflict verbatim. Quoting prevents the agent from paraphrasing a requirement into something it can satisfy. It also saves the reviewer from re-reading the whole ticket.

Secrets are the classic escalation. When a tool call returns an auth error, the agent should hand off with the tool name, environment, and status code, and should not attempt to find credentials elsewhere. A prompt line like "do not read .env files or search for tokens" is worth more than a dozen policies nobody reads.

Scope is the quiet one. Agents classify requests as related to the goal even when they touch adjacent systems. Define allowed paths and allowed repositories explicitly, and add a rule that any path outside them triggers a stop. Speakeasy's layering of agent prompts is a useful mental model here: project rules files tell the agent what it owns, and user rules files cover how you want it to behave while it works.

If your agents run across many models and vendors, keeping stop rules identical across all of them matters more than model choice. Routing the same prompt through a single gateway, such as Quanta Inference, avoids the situation where your escalation policy drifts because one provider's prompt format differs.

A stop rule you never test is a wish. Three checks catch most failures.

The impossible task. Give the agent a ticket whose test contradicts its specification, then verify that it stops and reports the conflict instead of making the test pass. This is the ImpossibleBench idea applied as a smoke test (ImpossibleBench). A correct run produces a handoff, not a green suite.

The flaky test. Add a test that fails intermittently. The agent should stop after the retry budget and say so, never disable the test. If it comments out assertions, you have found the behavior NIST documented (CAISI blog).

The scope request. Ask for a change in a file the agent does not own. It should decline and name the allowed paths.

Log every handoff with the reason code and the question asked, then track two numbers per week: handoffs per task and the share that a person resolved without further agent work. If handoffs are frequent but never answered, your stop threshold is set too tight. If almost no tasks hand off and reviewers keep catching regressions, it is too loose. Retry budgets of two or three attempts are defensible defaults for teams starting out, but the logged numbers, not the defaults, should drive changes.

Teams that need a curated set of behaviors rather than a hand-written prompt can install one, which is the pitch of the skill library: a reviewed behavior pack that a coding agent can pick up without every team rewriting its own stop rules.