Files

T

retoor afc88b8087 ask_user tool, prompt-JSON CLI repair loop, tool-loop research archive

- New ask_user core tool: mid-turn user question with option picking,
  refusing cleanly in autonomous mode, for background workers, and
  without a tty; system prompt points at it instead of prose questions.
- Structural loop control for prompt-JSON CLI backends (opencode,
  grok, claude, codex, gemini): shared cli_json_turn repairs a
  missing JSON envelope exactly once, then accepts prose; prompt
  contract hardened against narrate-without-calling.
- research/agentic-tool-loop-design: 74 sources plus 2 conclusions
  backing the loop-control decisions; INDEX updated to 6 subjects.

2026-10-11 02:54:17 +02:00

3.0 KiB

Raw Blame History

Stop Reasons and Fallback

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	agentic-tool-loop-design
Document type	Source Dossier
Tier	1
Source title	Stop reasons and fallback
Source URL	https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
Source publisher / author	Anthropic (platform documentation)
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-11
Researched by	tai (agent), model: Muse Spark, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

The official Claude API reference for the stop_reason field. Every Messages API response carries a machine-readable reason generation stopped; the documented handler table maps each value to an action: end_turn means use the response, tool_use means run the tool and return the result, pause_turn means re-send content to continue a server-tool loop, and the rest (max_tokens, stop_sequence, refusal, model_context_window_exceeded) cover truncation and fallback paths.

Key findings

stop_reason is part of every successful response and tells the caller why generation stopped, distinct from errors.
tool_use: the model is calling a tool; the runtime must run it and return the result (a server tool call still missing its result block completes in a later response).
end_turn: the model finished naturally; the runtime should use the response as-is.
pause_turn: a server-tool loop hit its iteration limit; the runtime continues by sending the assistant content back.
max_tokens and model_context_window_exceeded both mean truncation and need explicit continuation handling, not silent acceptance.

Pros / strengths

Authoritative vendor contract: this is the deterministic loop-control signal the whole ecosystem keys on.
The quick-reference table is unambiguous about which values continue the loop and which end it.

Cons / limitations / caveats

Claude-specific wire format; OpenAI uses finish_reason: tool_calls and other vendors differ again, so a multi-backend harness must normalize per backend.
Documents the signal, not what to do when a weak model emits the wrong signal (e.g. ending the turn when it should have called a tool).

Relevance to tai

Load-bearing for the conclusion that loop control must stay structural: tai's normalized tool_calls presence/absence across its heterogeneous backends is exactly the stop_reason equivalent, and assistant text must never drive loop decisions.
Tai's CLI backends (opencode, grok, claude, codex, gemini) synthesize this signal by parsing model prose into {content, tool_calls}, which is where the narration-instead-of-call failure enters; the docs confirm the signal layer is the right place to harden.

Changelog

Date	Change
2026-10-11	Initial dossier created.

3.0 KiB Raw Blame History