retoor
afc88b8087
- 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.
54 lines
3.0 KiB
Markdown
54 lines
3.0 KiB
Markdown
# 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. |
|