agent says done after 3 of 9 steps, is silent early stopping normal multi-step

Also look at how much tool output you are stuffing back in. Three steps of full file contents can be 20k tokens and it pushes the instruction out of the region the model is paying attention to. Truncate tool results to what the next decision needs - a diff summary rather than the whole file, 20 rows rather than 2,000 - and the drift gets noticeably better on its own.

Known, extremely common, and mostly an architecture problem rather than a prompting one. Your nine steps live in a message that is now thirty turns back, competing with a pile of tool output. The plan needs to be state your loop owns, not a paragraph in the transcript.

What this looks like in practice:

• the loop holds a checklist as real data, and after every step you re-render it into the prompt: [x] fetch [x] validate [x] transform [ ] write file 1 ...
• the model does not get to declare completion in prose. It calls mark_step_done(id, evidence) and your code checks the evidence - the file exists, the row count matches.
• finish is a tool that your loop rejects if unchecked items remain, with a message saying which ones.

Once completion is something your code decides rather than something the model asserts, this failure stops being possible. Prompting harder gets you from 3 steps to maybe 5.

Nine steps in one run is a lot to ask of any loop. Consider splitting it into three runs with hard handoffs: fetch+validate produces a file, transform reads that file, writing reads the transform output. Each run is short, each one is independently retryable, and a failure tells you exactly where it happened. Agents are much better at four steps than at nine, and pipelines are allowed.

Not naive at all - this is the first thing everybody hits and it is why so much agent tooling ends up looking like a workflow engine with a model inside rather than a model with tools bolted on. You are rediscovering the reason in the right order.

The apologising-then-doing-it behaviour when you push back is the interesting part. It knows, in some useful sense, what it skipped. A cheap version of what the top answer describes: after the model says it is done, run one more turn with a fixed prompt that says "list which of the nine steps have verifiable output and which do not". Catches most of these with about six lines of code, and you can do it this afternoon while you build the proper checklist.

One small thing that helped us: number the steps in the tool names or arguments so the trace is greppable. When a run stops early you want to see step=4 missing from the log rather than reading a summary paragraph and inferring what happened.