How to Write a Stop Message an Agent Can Act On at the Cap

Treat the cap as a boundary event with three phases, executed in order, each with its own allowance.

Phase 1: finish the step in flight. An agent partway through writing a file, applying a migration or sending a request is in a dangerous state. Cutting power mid-step is how you get half-written artifacts and orphaned side effects. Give the boundary a small overshoot allowance, expressed in the same unit as the cap, and spend it only to reach a safe point. A step-limit cap might grant one extra model call. A budget cap might grant a fixed reserve held back from the main loop precisely for this purpose.

Phase 2: persist partial work. When the agent reaches a safe point, it writes what it has to a named location: a file path, a branch, a draft record, a comment on the ticket. Phase 2 is where most implementations fail, because the model is asked to "summarize progress" in prose and the summary never reaches durable storage. The unit economics literature is clear that retrieval, orchestration, evaluation and labor all sit outside the token line and all cost real money per this allocation guide. A partial artifact that a human can pick up is the only part of the run that survives the cap with value intact.

Phase 3: tell a person what it needs. The final message names the one blocking input. Not five. One, plus a list of what is already done and where the partial work lives.

The ordering matters because each phase depends on the previous one. You cannot write a truthful handoff about partial work if the work was never persisted, and you cannot persist cleanly if you are interrupted mid-write.

A practical rule of thumb: reserve the boundary allowance before the loop starts, not after. If the cap is 100 units, run the main loop to 95 and hold 5 for the boundary. An agent that discovers it has zero left cannot finish a write or compose a handoff, so it does the worst thing available: it emits a long apology, which is itself a paid generation.

The stop message should be machine-checkable, because a human reviewer under time pressure will read the first line and then look for a file. Keep the schema small and fixed. Four fields do most of the work: what finished, what is partial with its exact path, what the agent was trying to do next, and the single input a person must supply.

{
  "status": "capped",
  "cap": {"type": "budget", "limit": 15.00, "spent": 14.92, "unit": "usd"},
  "finished": ["migrations/004_add_index.sql applied to staging"],
  "partial": [{"path": "reports/q3-draft.md", "state": "sections 1-4 complete, 5-7 missing"}],
  "next_intended_step": "fetch Q3 revenue from warehouse view finance.q3_rev",
  "blocking_input": "warehouse access for the reporting service account",
  "owner": "data-platform-oncall"
}

Three properties make this usable.

It is actionable without the transcript. A reviewer reads the blocking input, grants or denies it, and re-runs with a larger cap. They never need to scroll through 40 tool calls to reconstruct intent. The handoff-protocol literature makes the same point about agent-to-agent work: pass conclusions and unresolved items, not raw exploration logs, because the receiver cannot parse your noise efficiently per this handoff pattern reference.

It states the cap honestly. Recording the type, the limit and the spend at the moment of stopping turns the message into an audit record. That matters for the same reason signed receipts matter in budget enforcement systems, where a refusal over budget is itself an event worth proving as described in this cost control overview.

It separates finished from partial. Ambiguity here is expensive, because the next person will either redo completed work or trust incomplete work. A structured handoff format with explicit fields for what was done, what was found, what needs attention and what is unresolved is more reliable than prose notes, since field extraction is deterministic per this handoff protocol guide.

One caveat worth designing around: structured fields imply certainty. An agent that fills a partial array with tidy JSON can hide that its conclusions were tentative. Where the work is genuinely uncertain, put the hedge inside the field value rather than dropping it for the sake of a clean schema.

Step, time and budget caps fail differently, and the stop message should reflect that. A step cap is predictable but blind to cost. A time cap protects latency for interactive users but can fire mid-tool-call. A budget cap protects margin but is the hardest to enforce because it needs a pre-execution decision.

If you run more than one cap, decide precedence up front. A common and defensible order is: budget first, because it is the only one that can stop the next call; then time, because users and pipelines have deadlines; then steps, which mostly catch loops the other two would eventually catch anyway.

Budget caps also need a scope decision. A single monthly ceiling will not stop a runaway loop inside one agent, or a single tenant consuming a shared pool per this token budget guide. Set per-run limits for the loop, per-user or per-tenant limits for fairness, and per-feature limits so a single expensive workflow cannot eat the allowance for everything else. That layering is also what lets you attribute spend to the team that caused it rather than to the platform that happened to host it per this FinOps treatment of AI unit economics.

A worked example makes the arithmetic concrete. Suppose a summarization task averages 23 calls at about 2.63 dollars when it behaves using the cost profile in this budget control article, and you set a 5 dollar run cap. A well-behaved run finishes with 2.37 dollars of headroom. A looping run hits the cap and stops. The difference between a good and bad stop path is whether that 5 dollar run returns four section summaries on disk plus one blocked question, or returns a paragraph saying it ran out of money.

The boundary allowance should be derived from measured behaviour, not intuition. Instrument first, enforce second, optimize third, and log input tokens, output tokens, model, feature, user or tenant, environment, request status, retry count and estimated cost per request per this guide to setting token budgets.

Three measurements set the numbers.

The distribution of steps per successful task gives you the step cap: take a high percentile of successful runs, not the mean, so ordinary variation does not trip the boundary. Retry behaviour is the reason to aim high, because retries are a large and under-budgeted cost driver; in one simulation, a five times retry multiplier pushed cost per successful task from 5.73 dollars to 28.65 dollars per this retry cost analysis. A cap that fires on ordinary retries will be tuned away by the first engineer who gets paged.

The cost of a single step at the tail of a run gives you the phase 1 allowance. Because context grows with each turn, a late step can cost several times an early one. Measured per-call consumption in a documented five-step run grew from 888 tokens to 18,900 per this agent cost analysis. Size the overshoot for the step you will actually be on, not the average.

The size of your handoff schema gives you the phase 2 and 3 allowance. Keep it to a few hundred tokens and it will never be the reason a run overshoots.

Two levers reduce the allowance you need. Prompt caching cuts the cost of repeated context, with published savings on cacheable content of up to 90 percent per this token efficiency survey. And explicit terminal states in tool responses stop the model retrying an ambiguous outcome; one team cut per-task tool calls from 14 to 2 by adding clear success and failure signals per the same multi-turn cost analysis. Fewer ambiguous outcomes means fewer runs that reach the cap at all, and the ones that do are genuinely out of road.

Everything above assumes the agent is producing text and files. When the agent can send email, change infrastructure or call paid third-party APIs, the boundary carries a different risk: side effects that cannot be undone by cutting the budget afterwards per this enforcement discussion.

For these agents, add two fields to the schema: side_effects_committed and side_effects_uncertain. The second field is the important one. It lists actions the agent started but could not confirm, such as a request sent without a response or a job submitted without a status check. A person then knows exactly what to verify before re-running, which is the difference between a recovery that takes minutes and one that takes an incident review.

Autonomy level should also be encoded at the boundary rather than decided ad hoc. Governance frameworks that distinguish fully supervised, checkpointed, monitored and post-hoc reviewed work give you a vocabulary for this, and the checkpointed level, where routine cases proceed and exceptions escalate to a human, maps naturally onto the cap as set out in this handoff and autonomy guide. At the cap, the agent is always in the escalate branch.

Treat the boundary as a trust boundary too. Limit what context and credentials cross it, and revalidate before the next run acts on inherited state, because a compromised or malfunctioning upstream step can otherwise steer later actions through context it should never have passed along per this handoff governance guidance.

There is an older, useful analogy. When a contract is terminated for convenience, the supplier does not stop dead and vanish: it stops incurring new obligations, protects the work already done, and submits a settlement proposal describing what was completed and what remains under the termination rules in the Federal Acquisition Regulation. Your agent's stop message is that settlement proposal. Short, factual, and sufficient for someone else to close the file.

If the boundary work is where your team keeps getting stuck, a free 30-minute discovery call is a reasonable place to sketch the protocol against your actual stack: book a Quanta consulting call.