What you will be able to do
- Read a misbehaving agent's trace and name the pattern that is missing or misapplied
- Choose stop_reason-based termination over text matching and treat turn caps as a backstop
- Fix tool-call thrash by returning instructive is_error results instead of bare error strings
- Match context bloat, lost state and forgotten instructions to subagent isolation, memory, compaction or deterministic controls
Key concept
Structural signals over textual guesses — An agent loop is fixed by acting on the structured signals the runtime already gives you, such as stop_reason, is_error and the result subtype, and by choosing where information lives (subagent, memory file, re-injected config). Guessing from what the model wrote is not a fix. Most misbehaving agents ignore one of these signals or put information somewhere it gets lost.
1.From symptom to missing pattern
An agent is usually simple at its core, so most misbehaviour traces back to one missing pattern. An agent is a model calling tools in a loop and reading what comes back. Each pass adds tool results to the conversation, the model decides what to do next, and the loop ends when the model answers without calling a tool. When a run goes wrong, the trace shows you which part of that cycle failed: the exit, the feedback from a tool, the growth of context, or what the agent remembers.
Diagnosis means mapping the symptom to the cycle. A run that ends halfway was stopped by the wrong exit test. A run that repeats one call until it hits its cap was getting tool feedback it could not act on. A run that slows down and loses focus over a long task is carrying too much context. An agent that forgets yesterday's decisions, or an instruction from an hour ago, kept that information somewhere that does not survive. Each symptom has its own corrective pattern, and the wrong pattern can make the trace look better while leaving the cause in place.
| Symptom in the trace | Missing or misapplied pattern | Corrective pattern |
|---|---|---|
| Run ends mid-task after the model writes a word like "complete" | Termination keyed on text | Loop while stop_reason is tool_use; finish on end_turn |
| Identical tool call repeated until the turn cap | Tool feedback the model cannot act on | tool_result with is_error and an instructive message |
| Main conversation swollen with file contents from research | No context isolation | Delegate the reads to a subagent; only its final message returns |
| Agent forgets earlier work in a new conversation | No persistent memory | Memory tool files read back at task start |
| Instruction from an early message ignored after summarization | Instruction stored only in conversation history | Put it in re-injected config, or enforce it with a hook |
Statelessness is the most basic missing pattern. Each model call sees only what you send. In the agent loop, Claude receives the system prompt, the tool definitions and the conversation history along with the prompt. A chat feature that sends each user message as a one-element messages array has dropped the history, so the assistant cannot recall anything said a minute earlier. The fix is to send back the accumulated conversation on every request.
Checkpoint 1 of 9· Match them up
Match each symptom seen in an agent trace to the pattern that corrects it
Tap a term, then the definition that fits it.
Each symptom points to the part of the loop that failed: the exit test, the tool feedback, context growth, or where information is stored. A higher turn cap or a bigger context hides the symptom but leaves the cause in place. For example, a subagent keeps research reads out of the parent because only its final message comes back.
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”Source: code.claude.com
2.Loop termination: exit on stop_reason, not on text
On the Messages API, a client-side tool loop is keyed on stop_reason. When Claude wants a tool run, the response comes back with stop_reason: "tool_use" and one or more tool_use blocks. Your code runs each tool, sends the results back as tool_result blocks, and repeats. Any other stop reason (end_turn, max_tokens, stop_sequence, refusal) exits the loop. Only end_turn means Claude produced its final answer. The others mean it stopped for a reason your application has to handle. max_tokens, for example, means the response was cut off, not that the task is done.
Every text-based exit has the same flaw. A rarer marker such as <<TASK_FINISHED>> makes false matches less likely, but the exit still depends on what the model chose to write, not on whether it asked for a tool. A second model call that judges whether the text "reads like a final answer" adds cost, plus a new guess, on top of a signal the API already provides. A fixed five-iteration limit is worse: a task that needs seven tool rounds always ends with two of them undone.
A turn or budget cap is still useful, as a backstop rather than as the exit. Anthropic's guidance on agents notes that tasks usually end on completion, but that it is common to add stopping conditions such as a maximum number of iterations to keep control. In the Agent SDK, a run that hits the cap ends with a result whose subtype says so. error_max_turns means the run hit the maxTurns limit before finishing, and error_max_budget_usd is the cost equivalent. Neither of these results has a result field, so read the subtype before you treat the output as an answer.
if (message.type === "result") {
if (message.subtype === "success") {
console.log(message.result);
} else {
console.log(`Stopped: ${message.subtype}`);
}
}One more stop reason looks like an ending but is not. Server-executed tools such as web search run their own loop on Anthropic's infrastructure, and that loop has an iteration limit. If the model is still working when it reaches the limit, the response arrives with stop_reason: "pause_turn". The work is unfinished: send the conversation back, including the paused response, so the model can carry on.
Checkpoint 2 of 9· Check yourself
A request with web search enabled comes back with stop_reason "pause_turn" and a partly written reply. What should the application do next?
pause_turn means the server-side tool loop hit its iteration limit while the model was still working. Only end_turn marks a final answer. To continue, send the conversation back with the paused response included.
“A paused turn means the work isn’t complete; re-send the conversation (including the paused response) to let the model continue where it left off.”Source: platform.claude.com
Checkpoint 3 of 9· Check yourself
An Agent SDK run with maxTurns set ends with a result message whose subtype is error_max_turns. How should your code handle it?
error_max_turns means the cap stopped the run before the task was done, and the result has no result field. Check the subtype before you treat any output as an answer. The cost limit has its own subtype, error_max_budget_usd.
“Check the subtype field to determine whether the task succeeded or hit a limit.”Source: code.claude.com
Checkpoint 4 of 9· Exam question
Which stop_reason on a Messages API response tells an agent loop that the model wants a tool executed and the loop should continue?
Correct answer: C — tool_use
- A. Incorrect. This value means the model finished its turn naturally, which is the signal to exit the loop rather than continue it.
- B. Incorrect. This means the response was cut off at the token limit; it is a truncation case and does not carry a tool request.
- C. Correct. It indicates the response contains a tool call that the application must run, after which the result is sent back and the loop continues.
- D. Incorrect. This means generation halted at a custom stop string, which says nothing about a pending tool call.
Checkpoint 5 of 9· Exam question
A loop built on the Messages API stops whenever the assistant's text contains the word "complete". In production the model sometimes writes "Step one is complete, now checking the tests", and the run ends with half the work undone. What is the correct termination pattern?
Correct answer: D — Run tools and return results while stop_reason is tool_use, and end the loop only once stop_reason is end_turn
- A. Incorrect. A custom marker is still free text in the model's output. The model can print it in a progress note before the work is done, or omit it at the end. This keeps the same fragility with a different string.
- B. Incorrect. An iteration count has no link to whether the work is finished. A task needing more than five tool calls is cut off half done, and a shorter task spends turns it does not need. It works as a safety ceiling, not as the stop condition.
- C. Incorrect. A judging call only guesses from prose, and a note like 'Step one is complete, now checking the tests' can still be read as final. It adds cost and latency on every turn while ignoring the structured field that already says whether tool calls are pending.
- D. Correct. The Messages API reports in
stop_reasonwhether the model wants a tool run (tool_use) or has ended its turn (end_turn). Driving the loop from that field means words in the assistant's text cannot end the run early.
3.Tool-call thrash: give the agent an error it can act on
An agent that repeats the same failing call is usually getting feedback it cannot use. Suppose a lookup_order tool returns the bare string "error" whenever an order ID is malformed. The model learns that something failed, but not what to change. With nothing to adjust, it sends the same ID again and keeps doing so until the turn cap stops it. The loop is behaving correctly: it runs tools while the model asks for them. The broken part is the content going back into the loop.
The fix is a tool_result that marks the failure and explains it. Set is_error: true and use the content to say what went wrong. For the order lookup, that means stating the ID format and giving a valid example. When a tool result reports an error, Claude will try the tool again with the missing or corrected information. If the call failed because the model lacked information, such as a missing parameter, a longer-term fix is to write more detailed descriptions in the tool definition. Error messages are covered in more depth under tool response shaping.
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}The tempting fixes all leave the uninformative feedback in place. Raising the cap from 25 to 100, or adding a delay between retries, just pays for more identical calls. A system-prompt rule allowing two calls per tool stops the thrash sooner, but the agent still never learns the correct ID format, so the task fails anyway. Splitting the tool into three tools by order type, each with its own short error string, multiplies the problem by three.
Checkpoint 6 of 9· Check yourself
In a trace, the agent calls lookup_order with the same malformed order ID on every turn. Each time, the tool returns the bare string "error". This repeats until the run reaches its turn cap. Which change fixes the cause rather than the symptom?
The loop is working correctly. The problem is the feedback: a bare "error" tells the model nothing it can change, so it sends the same call again. An is_error result that explains the expected format lets Claude correct the ID on its next call. A higher cap or a per-tool limit only changes how many failed calls you pay for.
“Each set of tool results feeds back to Claude for the next decision.”Source: code.claude.com
Checkpoint 7 of 9· Exam question
A support agent calls lookup_order, and the tool returns the bare string "error" whenever the order ID is malformed. The trace shows the agent retrying the identical call with the same ID 25 times until it hits its turn cap. Which change best corrects this behavior?
Correct answer: B — Return the result with is_error set, naming the ID format rule and a valid example, so the agent can adjust the argument on its next call
- A. Incorrect. A higher cap and a delay only stretch out the same loop. The tool still returns a bare string with no cause, so the agent has nothing that would lead it to change the ID it sends.
- B. Correct. The agent repeats the call because the failure result tells it nothing about what was wrong. An error result flagged with
is_errorthat names the format rule and shows a valid example gives it what it needs to fix the argument. - C. Incorrect. A prompt rule is not an enforced limit, and the model cannot reliably count its own calls across a long trace. It would also block legitimate repeat lookups for different orders. The agent would still never learn why the ID was rejected.
- D. Incorrect. Separate tools that each return a short error string only show which tool failed. They still give no reason for the failure, so the agent has no basis for correcting a badly formatted ID and would repeat the call.
Sources4
4.Context growth: isolate work in subagents
Context grows with every turn of a loop. Each file read, search result and command output stays in the conversation and is sent again on every later request. A research step that reads dozens of files leaves all of that text in the main agent's context long after the research is finished. The result is slower, more expensive turns and an agent that struggles to find the details that still matter.
A subagent. It runs in its own conversation, its tool calls and results stay inside it, and only its final message, a concise summary, comes back to the parent.
Subagent isolation is the corrective pattern. Each subagent runs in its own conversation. Its intermediate tool calls and results stay inside it, and only its final message comes back to the parent. A research subagent can explore many files while the parent receives a short summary instead of every file it read. Isolation also helps in two other ways. Independent subagents can run in parallel, and each one can be limited to specific tools, so a reviewer given only Read and Grep cannot change the files it analyses.
Isolation only works if the result that comes back is small. A subagent definition that has no tools list inherits every tool available to subagents, and one with no maxTurns has no limit of its own on agentic turns. When a delegated task returns too much or runs away, look at what the subagent definition is missing. Writing the definitions themselves is the subject of Agent SDK construction.
Checkpoint 8 of 9· Match them up
A team's subagent setup shows each of the problems below. Pair each problem with the change that addresses it.
Tap a term, then the definition that fits it.
Each subagent runs in its own conversation and only its final message returns, which keeps large reads out of the parent. A definition with no tools list inherits every tool, and one with no maxTurns has no turn limit of its own. Independent subagents can run at the same time.
“A doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files.”Source: code.claude.com
5.Lost state: memory, compaction and instructions that survive
State lost between conversations points to a missing memory pattern. The memory tool lets Claude create, read, update and delete files in a memory directory that persists between sessions. When the tool is enabled, Claude checks that directory before it starts a task. It writes down what it learns as it works and reads those files back in later conversations. Information is loaded only when it is needed, which also keeps the active context focused on the current task. An agent that starts every session with no idea what it decided yesterday is missing exactly this.
State lost within one long session is a context-management problem. Compaction replaces older turns with a summary so a long agent task fits in the context window. It also keeps the active context small, because response quality degrades as the conversation grows. In Claude Code, running /clear between unrelated tasks stops old conversation from crowding out the files needed next. The strategies are taught in full in context management for long-running sessions. The diagnostic point is what does and does not survive a summary.
| Where the information lives | After compaction |
|---|---|
| System prompt and output style | Both still apply |
| Project-root CLAUDE.md and unscoped rules | Re-injected from disk |
| Auto memory | Re-injected from disk |
| Context that hooks added earlier | Summarized with the rest of the conversation |
| Instructions given in conversation messages | Summarized with the rest of the conversation |
This table explains a common trace. An agent was told in its first user message never to modify files under /legacy. After automatic summarization it edits one anyway, because that instruction lived only in conversation history and the summary dropped it. Moving the rule into the project-root CLAUDE.md fixes this, because that file is re-injected from disk after compaction. If a rule must hold no matter what the model remembers, such as never running rm -rf on production paths, a prompt is the wrong mechanism. Hooks can intercept and block tool calls before they run, which is the deterministic guardrail pattern.
Checkpoint 9 of 9· Match them up
An agent's rules and notes can live in different places. Pair each place with what happens to its contents when the conversation is compacted or a new session starts.
Tap a term, then the definition that fits it.
Compaction summarizes conversation messages, so an instruction kept only there can be lost. Project-root CLAUDE.md is reloaded from disk, and the system prompt still applies. Memory tool files carry knowledge into new sessions. A hook enforces a rule deterministically instead of relying on the model's memory.
“Project-root CLAUDE.md and unscoped rules | Re-injected from disk”Source: code.claude.com
Sources
(9)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agent-sdk/agent-loopOfficial docs
“Claude receives your prompt, along with the system prompt, tool definitions, and conversation history.”
↩︎ From symptom to missing pattern“Hit the maxTurns limit before finishing”
↩︎ Loop termination: exit on stop_reason, not on text“You can use hooks to intercept, modify, or block tool calls before they run.”
↩︎ Lost state: memory, compaction and instructions that survive“Claude continues calling tools and processing results until it produces a response with no tool calls.”
↩︎ Key concept“Check the subtype field to determine whether the task succeeded or hit a limit.”
↩︎ Exam trap 3“Check the subtype field to determine whether the task succeeded or hit a limit.”
↩︎ Checkpoint“Each set of tool results feeds back to Claude for the next decision.”
↩︎ Checkpoint - 2.https://www.anthropic.com/engineering/building-effective-agentsSecondary source
“They are typically just LLMs using tools based on environmental feedback in a loop.”
↩︎ From symptom to missing pattern“include stopping conditions (such as a maximum number of iterations) to maintain control.”
↩︎ Loop termination: exit on stop_reason, not on text - 3.
“Claude responds with stop_reason: "tool_use" and one or more tool_use blocks.”
↩︎ Loop termination: exit on stop_reason, not on text“or stopped for another reason that your application should handle”
↩︎ Loop termination: exit on stop_reason, not on text“If the model is still iterating when it hits the cap, the response comes back with stop_reason: "pause_turn" instead of "end_turn".”
↩︎ Exam trap 1“In practice this reads as: while stop_reason == "tool_use", run the tools and continue the conversation.”
↩︎ Prediction“A paused turn means the work isn’t complete; re-send the conversation (including the paused response) to let the model continue where it left off.”
↩︎ Checkpoint - 4.
“you can return the error message in the content along with "is_error": true”
↩︎ Tool-call thrash: give the agent an error it can act on“The best approach during development is to try the request again with more-detailed description values in your tool definitions.”
↩︎ Tool-call thrash: give the agent an error it can act on“and Claude will attempt to use the tool again with the missing information filled in”
↩︎ Exam trap 2 - 5.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ Context growth: isolate work in subagents“The parent receives a concise summary, not every file the subagent read.”
↩︎ Context growth: isolate work in subagents“If omitted, inherits every tool available to subagents”
↩︎ Context growth: isolate work in subagents“intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
↩︎ Checkpoint“A doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files.”
↩︎ Checkpoint - 6.
“An agent running in a loop generates more and more data that could be relevant for the next turn of inference”
↩︎ Context growth: isolate work in subagents - 7.
“When the memory tool is enabled, Claude automatically checks its memory directory before starting a task.”
↩︎ Lost state: memory, compaction and instructions that survive - 8.
“it keeps the active context small, because response quality degrades as a conversation grows.”
↩︎ Lost state: memory, compaction and instructions that survive - 9.https://code.claude.com/docs/en/context-windowOfficial docs
“Old conversation crowds out the files you need next and costs tokens on every message.”
↩︎ Lost state: memory, compaction and instructions that survive“Summarized with the rest of the conversation”
↩︎ Exam trap 4“Project-root CLAUDE.md and unscoped rules | Re-injected from disk”
↩︎ Checkpoint