Turn Cap Agent Prompts: Bounding Cost and Scope

Agent turn cap prompts put a hard ceiling on how many agent iterations a coding loop may spend before it must stop and report. You write the number into the same brief as the goal so cost and scope stay bounded when tests flake, secrets are missing, or the finish line was wrong. This page teaches how to size caps, place them in Claude Code /goal text, escalate when the cap fires, and pair wording with SDK ceilings such as max_turns and dollar budgets as of mid-2026. PromptMake at https://promptmake.net/loop-prompt-generator writes command text only. It does not run loops or touch your repo. Stay here for turn-cap craft: numbers, fences, and cost math you can paste today.

What an agent turn cap is and why it belongs in the prompt

A turn is one tool-use round trip: the model plans, calls tools, reads results, and decides whether to continue. An agent turn cap is the maximum count of those rounds you allow for one job. Write it in natural language inside the loop brief, for example “or stop after 12 turns,” and mirror it in host options when your runner exposes max_turns or --max-budget-usd.

Caps bound two risks. Cost: each turn re-sends growing context, so late iterations cost more than early ones. Scope: stuck agents invent new work when the real goal is blocked. Without a number, “keep going until tests pass” becomes an open invoice.

Place the cap next to the success condition so the evaluator and the worker share one contract. Anthropic’s Claude Agent SDK docs, as of mid-2026, treat max_turns as a hard stop that returns an error subtype when hit. Your written clause teaches the agent to summarize blockers instead of thrashing until that hard stop alone kills the run.

PromptMake’s loop generator returns recommended primitive, command text, success criteria, turn cap, verification steps, and stop guidance. Treat the suggested number as a draft. Soft start: https://promptmake.net/loop-prompt-generator.

Cap versus success stop

Success stop fires when proof appears: tests exit 0, build green, forbidden paths untouched. The turn cap fires when attempts run out regardless of proof. You need both. Success alone leaves impossible jobs looping. Cap alone stops work without teaching the agent what “done” meant.

Cap versus dollar budget

Turn count and dollar spend move together but are not identical. A twelve-turn refactor on a large repo can cost more than twenty turns of tiny lint fixes. As of mid-2026, Claude Agent SDK options include max_budget_usd for unattended runs, and headless Claude Code flows may expose --max-budget-usd. Put a turn clause in the prompt for behavior; set a dollar ceiling in the runner for invoice protection.

How to size agent turn cap prompts by job type

Sizing is a judgment call grounded in how many verify ladders you expect, not a lucky round number. Start low on a branch, watch how many turns clean successes need, then raise only when escalate reports show real progress before the wall. Soft drafting for those contracts: https://promptmake.net/loop-prompt-generator.

Cheap jobs with one package and one test file rarely need more than 8–12 turns. Contained refactors with a package suite and lint often land in 12–20. Migrations that touch many call sites belong in turn-based cycles with a per-batch cap of 6–10, not one mega-cap of 40. Unattended CI babysitting on a schedule uses interval language more than turn math; still cap how many identical red statuses you tolerate before cancel.

Count only tool-use turns when you map to SDK max_turns. Chat-only narration without tools may not consume that counter the same way. Align the number in your prompt with the counter your host actually enforces so humans and machines share one definition.

Log outcomes. If the same goal class hits the cap with half the verify ladder green three times in a week, raise the cap by a small step or split the goal. If the cap never fires and successes land mid-range, leave the number alone.

Small fix and docs sync ranges

Single failing unit test, path-fenced docs sync, rename inside one package: start at 8–12. Require escalate text on cap: failing command, files touched, hypothesized blocker. Raise to 15 only after you see the agent still making new progress at turn 10.

Refactor and migration ranges

API splits, call-site migrations, dependency bumps inside one workspace: start at 15–20 with abort fences on unrelated packages. Prefer turn-based “one call site per turn, stop after 8 turns” over one 40-turn blob. Cap is a budget for one batch, not a license for the whole epic.

Paste-ready turn cap skeletons

Use these skeletons as the cost-and-scope spine of a /goal brief. Fill paths and commands for your repo. Keep one measurable finish line. Anthropic notes that /goal evaluators judge from conversation evidence, so require the worker to print command output the evaluator can see.

As of mid-2026 you can embed a clause such as “or stop after N turns” in the condition. Pair it with an escalate paragraph so the agent reports cleanly when N trips. Exact CLI flags shift by version; read code.claude.com docs when field names move.

Guest free use on PromptMake: about three loop generations per day. Free registered accounts: about five per day as of mid-2026. Anthropic token spend is separate from PromptMake quotas.

Skeleton: green tests with hard turn stop

/goal all unit tests in packages/api pass (npm test --workspace packages/api exits 0), no public export signatures changed, lint clean in packages/api/src, or stop after 12 turns. On stop without success: print blocker summary, list failing tests, list files touched, make no further edits, wait for human.

Skeleton: migration batch with tight per-run cap

/goal migrate the next 5 call sites listed in docs/migration-checklist.md to the new API, targeted tests for those sites exit 0, or stop after 10 turns. Abort if any file outside the listed paths would change. On cap: output remaining call-site count and stop edits.

Skeleton: dual ceiling note for runners

Prompt text: or stop after 15 turns. Runner option (when available): max_turns=15 and max_budget_usd=2.00 for the same job. On either fire: no further edits; print which ceiling tripped if the host exposes it.

Escalation when the turn cap hits

A cap without an escalate script wastes the stop. The agent must convert failure into a ticket you can act on in one skim. Require four lines: blocker summary, checks that passed, checks that failed, recommended human next step. Forbid further file edits after escalate.

Teach early abort inside the same brief. Identical error fingerprints across three turns, missing secrets, flaky infrastructure, and out-of-scope schema churn should stop before the numeric wall. Cap is the last resort, not the only brake.

After a cap hit, inspect the transcript before you raise the number. Common root causes: verify command wrong, goal too wide, missing permission, false premise in the ticket. Raising from 15 to 40 on a vague goal buys more of the same failure.

Store winning cap ranges next to job classes in docs/agent-loops/ with last-tested Claude Code version and date. Retest after CLI upgrades because evaluator defaults and slash behavior can shift.

Escalate block you can paste

On turn-cap or abort: (1) one-paragraph blocker, (2) passed verify lines, (3) failed verify lines with last command excerpt, (4) next human action. Do not edit more files. Do not start a new goal unless the human says continue.

What to change after repeated cap hits

Split the goal, fence directories tighter, move expensive checks after cheap ones, or switch to turn-based approval between batches. Only then nudge the number up by 3–5 turns.

Cost and scope fences that make caps honest

A turn cap lies when the agent can still burn tokens inside each turn on unbounded reads and full-suite tests. Pair the number with scope fences: allowed paths, forbidden commands, and a verify ladder ordered cheap to expensive.

Narrow directory scope cuts context growth. Targeted tests cut shell time. Short command output cuts tokens. Explicit “do not bump dependencies” and “do not touch migrations” lines cut surprise diffs that waste later turns.

For unattended SDK runs, set both max_turns and max_budget_usd before the first overnight job. Interactive sessions may lack a per-run dollar flag; use account-level usage controls plus a written turn clause in the prompt. Soft drafting: https://promptmake.net/loop-prompt-generator.

Risky work needs a human gate even with perfect caps: production deploys, payment code, permission changes, data deletes. Use turn-based skeletons and require an explicit continue after each report.

Scope fence checklist

Before paste: branch clean, allowed paths listed, destructive commands named as forbidden, secrets present, human available for escalate output, dollar ceiling set if the runner supports it.

Model cost notes for mid-2026

Route mechanical edits and log summarization to cheaper tiers when your host allows model routing. Reserve Claude Opus 5 or GPT-5.6 Sol class judgment for planning and hard fixes. Caps bound waste; model choice sets the price per turn.

Common mistakes with agent turn cap prompts

Mistake 1: Omitting the number because the job “looks small.”

Mistake 2: Cap of 40 on a vague mega-goal.

Mistake 3: Cap without escalate text.

Mistake 4: Prompt says 12 turns while the SDK has no max_turns set for unattended runs.

Mistake 5: Raising the cap instead of fixing verify or splitting scope.

Mistake 6: Treating PromptMake as a runtime that enforces caps.

Mistake 7: Confusing this turn-cap page with agent-loop-prompt-templates (stop and escalate kits) or claude-code-loop-commands (full command and runaway guide).

Soft next steps

Pick one recurring ticket. Write goal, verify, and a conservative turn number on paper. Optionally polish at https://promptmake.net/loop-prompt-generator. Run on a branch. Log whether stop fired on success, early abort, or cap. Adjust the number only after three real runs of that job class.

FAQ

What are agent turn cap prompts?

Agent turn cap prompts are loop briefs that include a maximum iteration count next to the goal and verify lines. The number forces a stop when proof never arrives. You size the cap to job class, pair it with escalate text, and mirror it in host options when available. PromptMake drafts the text; your agent host enforces runtime limits.

How do I choose a starting turn number?

Start from job class: about 8–12 for single-package test fixes, 12–20 for contained refactors, and 6–10 per batch for migrations. Watch clean successes and raise only when escalate reports show progress near the wall. Prefer splitting goals over jumping to 40.

Do turn caps replace verify criteria?

No. Verify criteria define success. Turn caps define when to stop without success. Complementary articles on this blog cover verify patterns in depth. You need both lines in every serious loop brief.

How do SDK max_turns and prompt caps work together?

As of mid-2026, Claude Agent SDK max_turns hard-stops the loop and returns an error subtype. A written “stop after N turns” clause teaches the agent to summarize before or when that wall hits. Set both for unattended runs. Soft drafts: https://promptmake.net/loop-prompt-generator.

Can I use dollar budgets instead of turn caps?

Use both when the runner supports dollar ceilings. Turns control behavior and reporting. Dollars protect the invoice when late turns grow expensive. Interactive sessions may lack per-run dollar flags; still write a turn clause in the prompt.

Does PromptMake enforce turn caps?

No. https://promptmake.net/loop-prompt-generator generates recommended turn-cap language and command text. You paste into Claude Code or Codex. PromptMake does not access your repository, schedule jobs, or pay Anthropic tokens. Guests get about three generations per day; free registered accounts about five.

How is this different from agent-loop-prompt-templates?

That page ships stop-condition and escalation template kits. This page focuses on sizing and placing turn caps for cost and scope. Read both when you assemble a full loop contract.