Skip to content
Python

Persist finish_reason on assistant messages (OPE-173)

Devika Vermaa6677e00caf9
diff --git a/coworker/engine.py b/coworker/engine.py
index e492443c..f181c7fc 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -559,6 +559,9 @@ class TurnEngine:
payload["reasoning"] = turn.reasoning
if turn.usage is not None:
payload["usage"] = {"model": self.model, **turn.usage.as_dict()}
+ if turn.finish_reason:
+ # How the reply ended (OPE-173): `stop` / `tool_calls` / `length`.
+ payload["finish_reason"] = turn.finish_reason
yield Event(EventType.ASSISTANT_MESSAGE, payload)
if not turn.tool_calls:
@@ -1982,10 +1985,10 @@ class TurnEngine:
"""
# Strip the display-only sidecars — `source` (connector cards), `_display`
# (e.g. filter-hidden counts), `ts` (append-time timestamps), `reasoning`
- # (thinking text), and `usage` (token counts) — copying only messages that carry
- # one. Whole `notice` messages (error/interrupted/model-switch markers) are
- # display-only too: dropped entirely.
- _SIDECARS = ("source", "_display", "ts", "reasoning", "usage")
+ # (thinking text), `usage` (token counts), and `finish_reason` (how the reply
+ # ended) — copying only messages that carry one. Whole `notice` messages
+ # (error/interrupted/model-switch markers) are display-only too: dropped entirely.
+ _SIDECARS = ("source", "_display", "ts", "reasoning", "usage", "finish_reason")
# Auto-compaction (OPE-27): everything before the boundary is represented by the
# compacted block. Outbound-only — the canonical history stays intact — and the
# block+tail are byte-stable between turns, so prompt caching keeps working.
@@ -2095,6 +2098,15 @@ def _assistant_message(turn: AssistantTurn, model: Optional[str] = None) -> dict
# stripped before provider calls. Tagged with the model that produced it so
# per-model rollups survive mid-session model switches.
message["usage"] = {"model": model, **turn.usage.as_dict()}
+ if turn.finish_reason:
+ # How the reply ended, in the engine's normalised vocabulary (`stop` /
+ # `tool_calls` / `length`; unknown provider values pass through). Persisted
+ # so a saved session can tell "chose to stop" from "hit the output limit"
+ # without re-deriving it from token counts (OPE-173). Omitted — never null —
+ # for partial turns and providers that report no stop reason. Stripped before
+ # every provider call (`_outbound_messages`). The provider's raw value, where
+ # it differs, lives in that provider's sidecar (e.g. `_anthropic.stop_reason`).
+ message["finish_reason"] = turn.finish_reason
if turn.reasoning:
# Display-only thinking text — rendered by the GUI, stripped for every provider
# (`_outbound_messages`); provider-private replay blocks go via `extras` instead.
diff --git a/coworker/providers/anthropic_provider.py b/coworker/providers/anthropic_provider.py
index 0cf0e08e..0e4d59c4 100644
--- a/coworker/providers/anthropic_provider.py
+++ b/coworker/providers/anthropic_provider.py
@@ -376,9 +376,20 @@ def _reasoning_text(thinking_blocks: list[dict[str, Any]]) -> Optional[str]:
return text or None
-def _thinking_extras(thinking_blocks: list[dict[str, Any]]) -> dict[str, Any]:
- """Raw blocks → the `_anthropic` sidecar convert_messages replays (empty when none)."""
- return {"_anthropic": {"blocks": thinking_blocks}} if thinking_blocks else {}
+def _anthropic_extras(
+ thinking_blocks: list[dict[str, Any]], stop_reason: Any = None
+) -> dict[str, Any]:
+ """The `_anthropic` sidecar persisted on the assistant message (empty when nothing
+ to keep): raw thinking blocks, which convert_messages replays verbatim, and the raw
+ `stop_reason` (OPE-173) so values the engine's finish_reason map collapses —
+ `pause_turn`, `stop_sequence` → "stop" — stay recoverable from a saved session.
+ convert_messages only reads `blocks`; other providers strip the whole key."""
+ sidecar: dict[str, Any] = {}
+ if thinking_blocks:
+ sidecar["blocks"] = thinking_blocks
+ if stop_reason:
+ sidecar["stop_reason"] = stop_reason
+ return {"_anthropic": sidecar} if sidecar else {}
class AnthropicProvider(ProviderClient):
@@ -526,7 +537,7 @@ class AnthropicProvider(ProviderClient):
finish_reason=_STOP_REASON_MAP.get(stop_reason, stop_reason),
raw=response,
reasoning=_reasoning_text(thinking_blocks),
- extras=_thinking_extras(thinking_blocks),
+ extras=_anthropic_extras(thinking_blocks, stop_reason),
usage=_usage_from(getattr(response, "usage", None)),
)
@@ -647,7 +658,7 @@ class AnthropicProvider(ProviderClient):
tool_calls=tool_calls,
finish_reason=_STOP_REASON_MAP.get(stop_reason, stop_reason),
reasoning=_reasoning_text(thinking_blocks),
- extras=_thinking_extras(thinking_blocks),
+ extras=_anthropic_extras(thinking_blocks, stop_reason),
usage=usage,
)
)
diff --git a/tests/test_finish_reason.py b/tests/test_finish_reason.py
new file mode 100644
index 00000000..c1b877dd
--- /dev/null
+++ b/tests/test_finish_reason.py
@@ -0,0 +1,189 @@
+"""OPE-173: the provider's stop reason is persisted on the assistant message.
+
+The engine already receives `AssistantTurn.finish_reason` (`stop` / `tool_calls` /
+`length`, normalised per provider) and uses it transiently (`_turn_truncated`). These
+tests pin down that it is also (a) written to the saved message as a sidecar, (b) carried
+on the ASSISTANT_MESSAGE event, (c) stripped before any provider call, and (d) that the
+Anthropic provider keeps its raw `stop_reason` in the `_anthropic` sidecar so values the
+normalisation collapses (`pause_turn`, `stop_sequence` → `stop`) are not lost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from types import SimpleNamespace
+
+import aisuite as ai
+import pytest
+from coworker.engine import TurnEngine, _assistant_message
+from coworker.events import EventType
+from coworker.permissions import PermissionEngine
+from coworker.providers import (
+ AnthropicProvider,
+ AssistantTurn,
+ ModelCapabilities,
+ ProviderClient,
+ ToolCall,
+)
+from coworker.tools import ToolRegistry
+
+
+# -- engine plumbing ----------------------------------------------------------------
+
+
+class _OneTurnProvider(ProviderClient):
+ def __init__(self, turn: AssistantTurn):
+ self._turn = turn
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ return self._turn
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _run_engine(tmp_path, turn: AssistantTurn):
+ registry = ToolRegistry()
+ registry.register_all(ai.toolkits.files(root=str(tmp_path), allow_write=True))
+ engine = TurnEngine(
+ provider=_OneTurnProvider(turn),
+ registry=registry,
+ permissions=PermissionEngine(workspace_root=tmp_path),
+ model="gpt-5.5",
+ )
+
+ async def _collect():
+ return [ev async for ev in engine.run("hello")]
+
+ return engine, asyncio.run(_collect())
+
+
[email protected]("finish_reason", ["stop", "length"])
+def test_engine_persists_finish_reason_on_message_and_event(tmp_path, finish_reason):
+ turn = AssistantTurn(text="partial answer", finish_reason=finish_reason)
+ engine, events = _run_engine(tmp_path, turn)
+
+ assistant = next(ev for ev in events if ev.type == EventType.ASSISTANT_MESSAGE)
+ assert assistant.data["finish_reason"] == finish_reason
+
+ persisted = next(m for m in engine.messages if m.get("role") == "assistant")
+ assert persisted["finish_reason"] == finish_reason
+
+
+def test_outbound_messages_strip_finish_reason_sidecar(tmp_path):
+ engine, _ = _run_engine(tmp_path, AssistantTurn(text="done", finish_reason="stop"))
+ assert any("finish_reason" in m for m in engine.messages)
+ assert all("finish_reason" not in m for m in engine._outbound_messages())
+
+
+def test_assistant_message_omits_finish_reason_when_unknown():
+ """Partial turns (interrupt / provider error mid-stream) and providers that never
+ report a stop reason must not write a `finish_reason: null` key."""
+ message = _assistant_message(AssistantTurn(text="half a reply"))
+ assert "finish_reason" not in message
+
+
+def test_assistant_message_keeps_finish_reason_with_tool_calls():
+ turn = AssistantTurn(
+ tool_calls=[ToolCall(id="c1", name="read_file", arguments={"path": "x"})],
+ finish_reason="tool_calls",
+ )
+ message = _assistant_message(turn, model="m")
+ assert message["finish_reason"] == "tool_calls"
+ assert message["tool_calls"][0]["function"]["name"] == "read_file"
+
+
+# -- Anthropic raw stop reason ------------------------------------------------------
+
+
+class _FakeClient:
+ def __init__(self, response=None, events=None):
+ self.kwargs: dict = {}
+
+ def create(**kwargs):
+ self.kwargs = kwargs
+ if kwargs.get("stream"):
+ return iter(events or [])
+ return response
+
+ @contextmanager
+ def stream(**kwargs):
+ self.kwargs = kwargs
+ yield SimpleNamespace(get_final_message=lambda: response)
+
+ self.messages = SimpleNamespace(create=create, stream=stream)
+ self.beta = SimpleNamespace(messages=SimpleNamespace(create=create, stream=stream))
+
+
+def _text_response(text="hello", stop_reason="end_turn"):
+ return SimpleNamespace(
+ content=[SimpleNamespace(type="text", text=text)],
+ stop_reason=stop_reason,
+ )
+
+
+ "stop_reason,expected",
+ [
+ ("end_turn", "stop"),
+ ("max_tokens", "length"),
+ ("pause_turn", "stop"), # collapsed by the map — only the sidecar keeps it
+ ("stop_sequence", "stop"),
+ ],
+)
+def test_anthropic_complete_keeps_raw_stop_reason_in_sidecar(stop_reason, expected):
+ provider = AnthropicProvider(
+ client=_FakeClient(response=_text_response(stop_reason=stop_reason))
+ )
+ turn = provider.complete(model="m", messages=[{"role": "user", "content": "x"}])
+ assert turn.finish_reason == expected
+ assert turn.extras["_anthropic"]["stop_reason"] == stop_reason
+
+
+def test_anthropic_stream_keeps_raw_stop_reason_in_sidecar():
+ events = [
+ SimpleNamespace(
+ type="content_block_start",
+ index=0,
+ content_block=SimpleNamespace(type="text", text=""),
+ ),
+ SimpleNamespace(
+ type="content_block_delta",
+ index=0,
+ delta=SimpleNamespace(type="text_delta", text="cut off mid"),
+ ),
+ SimpleNamespace(
+ type="message_delta", delta=SimpleNamespace(stop_reason="max_tokens")
+ ),
+ ]
+ provider = AnthropicProvider(client=_FakeClient(events=events))
+ chunks = list(
+ provider.stream(model="m", messages=[{"role": "user", "content": "x"}])
+ )
+ turn = chunks[-1].turn
+ assert turn.finish_reason == "length"
+ assert turn.extras["_anthropic"]["stop_reason"] == "max_tokens"
+
+
+def test_anthropic_sidecar_with_stop_reason_replays_cleanly():
+ """A persisted assistant message carrying `_anthropic.stop_reason` but no thinking
+ blocks must convert back to the wire shape without error or extra blocks."""
+ fake = _FakeClient(response=_text_response())
+ provider = AnthropicProvider(client=fake)
+ history = [
+ {"role": "user", "content": "x"},
+ {
+ "role": "assistant",
+ "content": "earlier reply",
+ "_anthropic": {"stop_reason": "end_turn"},
+ "finish_reason": "stop", # would be stripped by the engine; belt and braces
+ },
+ {"role": "user", "content": "y"},
+ ]
+ provider.complete(model="m", messages=history)
+ sent = fake.kwargs["messages"]
+ assistant = next(m for m in sent if m["role"] == "assistant")
+ assert assistant["content"] == [{"type": "text", "text": "earlier reply"}]
+ assert "finish_reason" not in assistant
+ assert "_anthropic" not in assistant