The Claude Code cost brake turned out not to be the turn limit
I thought --max-turns was keeping my delegation costs down. It only counts rounds; the flag that actually holds dollars is --max-budget-usd.
TL;DR
A test revealed Claude Code's --max-turns flag doesn't limit spending; a single-turn task cost $0.045 without ever touching its cap of two. By contrast, --max-budget-usd actually halted a run mid-turn once spending passed $0.01. The takeaway: use budget caps to control costs, keeping turn limits only for stopping endless loops.
At seven in the evening I opened the acceptance doc in our repo, the section holding the delegation cap test results. The line we had been waiting for came down to two numbers: a trivial task handed to Claude Code with --max-turns 2 finished successfully in a single turn, cost about 0.045 dollars, and raised no error at all. Which means the brake I thought I had installed was never connected to anything.
In the months before that, our project's working doc carried one firm rule: every Claude Code call must travel with --max-turns. In my head the logic held up. Cap the rounds and you cap the damage. I more or less assumed every turn bills roughly the same. That assumption of a flat per-turn price turned out to be the exact weak point.
The numbers from that night's test
The test was deliberately trivial. Print mode, the task only had to reply briefly, cap set at two turns. The result: num_turns one, success, and the cap of two never got touched because the task finished first. The bill still went out: about 0.045 dollars for that one turn.
Then came the control run. No turn limit this time, but --max-budget-usd 0.01 instead. That is where the brake finally grabbed. The process was stopped hard with an error_max_budget_usd subtype, exit code 1, spending halted at 0.0403 dollars, still inside the first turn. The cap number got overshot a little before the check caught up, but the stop was real, and money triggered it, not a round counter.
Two flags, two different measures
Claude Code's official CLI docs describe --max-turns as a limit on agentic turns in print mode, and the error only shows up once that limit is actually reached [1]. So this flag measures progress, not money. As long as the task finishes under the cap, the flag just rides along in the command line.
Compare that with --max-budget-usd: defined as the maximum dollar amount to spend on API calls before stopping, print mode only as well [1]. The costs page adds the detail that makes this one credible: the number compared against the cap is the same figure shown as the session cost in the status line [2]. One source of truth, one cut-off point.
The history is readable in the official changelog too. The flag arrived through the SDK path [3], and its enforcement kept getting tightened; the fix list carries a line about background subagents that used to slip past the cap and now get stopped as well [3]. For that subagent-stopping behavior specifically, the CLI page says Claude Code 2.1.217 or newer is required [1]. On my machine, running 2.1.269, the flag is right there in --help, with the note that it only works in print mode.
One detail the docs still don't spell out: how often the budget check actually runs, once per API call or more often than that. What I can confirm from my own test is that the check is granular enough to kill a process in the middle of a turn that was already running. For a brake, that much precision is plenty.
Every delegation carries a dollar figure
The consequence went straight into our working doc: delegation calls now have to carry --max-budget-usd. Turn limits can stay, but their job is stopping a confused loop that spins without finishing, not holding down the bill. And the cost context here isn't small change either: the official Claude Code page puts the enterprise average at 13 dollars per developer per active day, with a range of 150 to 250 dollars per month [2].
Meanwhile --max-turns keeps a real job. In an unattended loop, a turn cap is what cuts off a session that keeps circling without ever finishing; the official docs say the error fires the moment the limit is reached [1]. Think of it as an emergency switch for behavior, not for bills. And a session that dies with error_max_turns never gets rerun blind in my setup: first check what it managed to write to disk, then decide whether to continue or tear it down.
The same pattern applies to anyone running agents unattended overnight. Turn counts never were a unit of money; one turn can be cheap because the context is short, or expensive because the model does a lot of work in a single round. If cost is what you want bounded, set the cap in dollars. One honest dollar figure beats a round counter that never gets touched.