chore: bump version to 1.2.2

* fix: universal tool_call/tool_result orphan detection for OpenAI-compat providers

The Anthropic provider had orphan detection for mismatched tool_call ↔
tool_result pairs, but OpenAI-compatible providers (Chat Completions,
Google, Responses API) had none. When an Anthropic model runs behind
an OpenAI-compat API (e.g. Azure) or cancellation creates orphans,
the API rejects the malformed request.

- Rewrite sanitize_messages() with orphan detection: synthesize error
  tool results for unmatched tool_calls, drop tool results with no
  matching tool_call, fill empty tool_call IDs with positional remap
- Call sanitize_messages() from Responses API _convert_messages()

* fix: address review feedback on orphan detection

- Track answered IDs per-turn (local_answered) instead of scanning
  all of out, preventing false matches from reused IDs across turns
- Drop empty-ID tool results that have no remap entry instead of
  passing them through with invalid empty tool_call_id
- Increment empty_result_idx for every empty result, not just remapped
- Remove dead result_ids peek-ahead code
- Add test for repeated tool_call IDs across turns

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "turnstone"
-version = "1.2.1"
+version = "1.2.2"
 description = "Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."
 readme = "README.md"
 license = "BUSL-1.1"

tests/test_providers.py

@@ -128,6 +128,8 @@ def _anthropic_event(
         if "usage_input_tokens" in kwargs:
             msg_usage = MagicMock()
             msg_usage.input_tokens = kwargs.get("usage_input_tokens", 0)
+            msg_usage.cache_creation_input_tokens = 0
+            msg_usage.cache_read_input_tokens = 0
             msg.usage = msg_usage
         else:
             msg.usage = None
@@ -176,6 +178,217 @@ class TestOpenAIProvider:
         sanitize_messages([original])
         assert original["content"] is None
 
+    # -- sanitize_messages: orphan detection -----------------------------------
+
+    def test_sanitize_orphaned_tool_call_synthesized(self) -> None:
+        """Tool_call with no matching tool result gets a synthetic error result."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "bash", "arguments": "{}"},
+                    },
+                ],
+            },
+            {"role": "user", "content": "next"},
+        ]
+        result = sanitize_messages(msgs)
+        assert len(result) == 3
+        assert result[1]["role"] == "tool"
+        assert result[1]["tool_call_id"] == "call_1"
+        assert "cancelled" in result[1]["content"]
+        assert result[2]["role"] == "user"
+
+    def test_sanitize_partial_results(self) -> None:
+        """Only the missing tool_call gets a synthetic result."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "a", "arguments": "{}"},
+                    },
+                    {
+                        "id": "call_2",
+                        "type": "function",
+                        "function": {"name": "b", "arguments": "{}"},
+                    },
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": "ok"},
+        ]
+        result = sanitize_messages(msgs)
+        assert len(result) == 3
+        assert result[1]["tool_call_id"] == "call_1"
+        assert result[1]["content"] == "ok"
+        assert result[2]["role"] == "tool"
+        assert result[2]["tool_call_id"] == "call_2"
+        assert "cancelled" in result[2]["content"]
+
+    def test_sanitize_complete_results_unchanged(self) -> None:
+        """All tool_calls paired → no changes."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "a", "arguments": "{}"},
+                    },
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": "ok"},
+            {"role": "user", "content": "thanks"},
+        ]
+        result = sanitize_messages(msgs)
+        assert len(result) == 3
+        assert result[0]["tool_calls"][0]["id"] == "call_1"
+        assert result[1]["content"] == "ok"
+        assert result[2]["role"] == "user"
+
+    def test_sanitize_trailing_orphan(self) -> None:
+        """Orphaned tool_call at end of conversation (no following messages)."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "a", "arguments": "{}"},
+                    },
+                ],
+            },
+        ]
+        result = sanitize_messages(msgs)
+        assert len(result) == 2
+        assert result[1]["role"] == "tool"
+        assert result[1]["tool_call_id"] == "call_1"
+
+    def test_sanitize_orphaned_tool_result_dropped(self) -> None:
+        """Tool result with no matching tool_call in preceding assistant → dropped."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "a", "arguments": "{}"},
+                    },
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": "ok"},
+            {"role": "tool", "tool_call_id": "call_ORPHAN", "content": "stale"},
+        ]
+        result = sanitize_messages(msgs)
+        assert len(result) == 2
+        assert result[1]["tool_call_id"] == "call_1"
+
+    def test_sanitize_empty_tool_call_id_filled(self) -> None:
+        """Empty tool_call IDs get synthetic values; tool results are remapped to match."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {"id": "", "type": "function", "function": {"name": "a", "arguments": "{}"}},
+                ],
+            },
+            {"role": "tool", "tool_call_id": "", "content": "ok"},
+        ]
+        result = sanitize_messages(msgs)
+        new_id = result[0]["tool_calls"][0]["id"]
+        assert new_id.startswith("call_")
+        assert len(new_id) > 10
+        # Tool result must have been remapped to match
+        assert result[1]["tool_call_id"] == new_id
+        # No synthetic result needed — the pairing is complete
+        assert len(result) == 2
+
+    def test_sanitize_stale_result_with_orphan(self) -> None:
+        """Stale tool results are dropped even when orphaned calls are present."""
+        msgs = [
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "a", "arguments": "{}"},
+                    },
+                    {
+                        "id": "call_2",
+                        "type": "function",
+                        "function": {"name": "b", "arguments": "{}"},
+                    },
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": "ok"},
+            {"role": "tool", "tool_call_id": "call_STALE", "content": "stale"},
+        ]
+        result = sanitize_messages(msgs)
+        result_tc_ids = [m["tool_call_id"] for m in result if m.get("role") == "tool"]
+        assert "call_STALE" not in result_tc_ids
+        assert "call_1" in result_tc_ids
+        assert "call_2" in result_tc_ids  # synthesized
+
+    def test_sanitize_orphan_no_mutation(self) -> None:
+        """Original messages and dicts are not mutated by orphan detection."""
+        tc = {"id": "", "type": "function", "function": {"name": "a", "arguments": "{}"}}
+        msg = {"role": "assistant", "content": None, "tool_calls": [tc]}
+        sanitize_messages([msg])
+        assert tc["id"] == ""  # original dict untouched
+        assert msg["tool_calls"][0]["id"] == ""
+
+    def test_sanitize_repeated_ids_across_turns(self) -> None:
+        """Reused tool_call IDs across turns are handled per-turn, not globally."""
+        msgs = [
+            # Turn 1: call_1 fully paired
+            {"role": "user", "content": "do A"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "a", "arguments": "{}"},
+                    },
+                ],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": "ok"},
+            # Turn 2: reuses call_1 but has no result → must be synthesized
+            {"role": "user", "content": "do B"},
+            {
+                "role": "assistant",
+                "content": None,
+                "tool_calls": [
+                    {
+                        "id": "call_1",
+                        "type": "function",
+                        "function": {"name": "b", "arguments": "{}"},
+                    },
+                ],
+            },
+        ]
+        result = sanitize_messages(msgs)
+        # Turn 2's orphaned call_1 should get a synthetic result
+        tool_msgs = [m for m in result if m.get("role") == "tool"]
+        assert len(tool_msgs) == 2  # one real from turn 1, one synthetic from turn 2
+
     # -- convert_tools --------------------------------------------------------
 
     def test_convert_tools_passthrough(self) -> None:
@@ -637,6 +850,8 @@ class TestAnthropicProvider:
         response.usage = MagicMock()
         response.usage.input_tokens = 10
         response.usage.output_tokens = 5
+        response.usage.cache_creation_input_tokens = 0
+        response.usage.cache_read_input_tokens = 0
 
         client = MagicMock()
         stream_ctx = MagicMock()
@@ -673,6 +888,8 @@ class TestAnthropicProvider:
         response.usage = MagicMock()
         response.usage.input_tokens = 15
         response.usage.output_tokens = 20
+        response.usage.cache_creation_input_tokens = 0
+        response.usage.cache_read_input_tokens = 0
 
         client = MagicMock()
         stream_ctx = MagicMock()
@@ -708,6 +925,8 @@ class TestAnthropicProvider:
         response.usage = MagicMock()
         response.usage.input_tokens = 100
         response.usage.output_tokens = 50
+        response.usage.cache_creation_input_tokens = 0
+        response.usage.cache_read_input_tokens = 0
 
         client = MagicMock()
         stream_ctx = MagicMock()
@@ -1910,6 +2129,8 @@ class TestAnthropicWebSearch:
         response.stop_reason = "end_turn"
         response.usage.input_tokens = 100
         response.usage.output_tokens = 50
+        response.usage.cache_creation_input_tokens = 0
+        response.usage.cache_read_input_tokens = 0
 
         client = MagicMock()
         stream_ctx = MagicMock()
@@ -2876,7 +3097,8 @@ class TestAnthropicPromptCaching:
                 messages=[{"role": "user", "content": "hi"}],
             )
         )
-        start_chunks = [r for r in results if r.usage is not None and r.usage.prompt_tokens == 100]
+        # prompt_tokens = input_tokens (100) + cache_creation (80) + cache_read (0) = 180
+        start_chunks = [r for r in results if r.usage is not None and r.usage.prompt_tokens == 180]
         assert len(start_chunks) == 1
         assert start_chunks[0].usage is not None
         assert start_chunks[0].usage.cache_creation_tokens == 80
@@ -3224,11 +3446,14 @@ class TestResponsesMessageConversion:
             },
         ]
         _, items = self.provider._convert_messages(messages)
-        assert len(items) == 1
+        # sanitize_messages synthesizes a missing tool result for the orphaned call
+        assert len(items) == 2
         assert items[0]["type"] == "function_call"
         assert items[0]["call_id"] == "call_1"
         assert items[0]["name"] == "read_file"
         assert items[0]["arguments"] == '{"path": "/tmp"}'
+        assert items[1]["type"] == "function_call_output"
+        assert items[1]["call_id"] == "call_1"
 
     def test_tool_result(self) -> None:
         messages = [
@@ -3279,11 +3504,14 @@ class TestResponsesMessageConversion:
             },
         ]
         _, items = self.provider._convert_messages(messages)
-        assert len(items) == 2
+        # sanitize_messages synthesizes a missing tool result for the orphaned call
+        assert len(items) == 3
         assert items[0]["type"] == "message"
         assert items[0]["content"] == "I'll read that file"
         assert items[1]["type"] == "function_call"
         assert items[1]["name"] == "read_file"
+        assert items[2]["type"] == "function_call_output"
+        assert items[2]["call_id"] == "call_1"
 
 
 class TestResponsesToolConversion:

tests/test_session.py

@@ -105,7 +105,8 @@ class TestChatSessionConstruction:
     def test_msg_char_count_content_only(self, tmp_db):
         session = _make_session()
         msg = {"role": "assistant", "content": "hello world"}
-        assert session._msg_char_count(msg) == 11
+        # "hello world" (11) + "assistant" (9) = 20
+        assert session._msg_char_count(msg) == 20
 
     def test_msg_char_count_with_tool_calls(self, tmp_db):
         session = _make_session()
@@ -122,13 +123,14 @@ class TestChatSessionConstruction:
                 }
             ],
         }
-        # "hi" (2) + "bash" (4) + '{"command": "ls"}' (17) = 23
-        assert session._msg_char_count(msg) == 23
+        # "hi" (2) + "tc_1" (4) + "bash" (4) + '{"command": "ls"}' (17) + "assistant" (9) = 36
+        assert session._msg_char_count(msg) == 36
 
     def test_msg_char_count_none_content(self, tmp_db):
         session = _make_session()
         msg = {"role": "assistant", "content": None}
-        assert session._msg_char_count(msg) == 0
+        # len("assistant") = 9
+        assert session._msg_char_count(msg) == 9
 
     def test_reasoning_effort_stored(self, tmp_db):
         session = _make_session(reasoning_effort="high")

turnstone/__init__.py

@@ -1,3 +1,3 @@
 """turnstone - Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation."""
 
-__version__ = "1.2.1"
+__version__ = "1.2.2"

turnstone/core/providers/_anthropic.py

@@ -714,14 +714,19 @@ class AnthropicProvider:
             elif event_type == "message_delta":
                 if hasattr(event, "usage") and event.usage:
                     u = event.usage
+                    inp = getattr(u, "input_tokens", 0) or 0
+                    out = getattr(u, "output_tokens", 0) or 0
+                    cc = getattr(u, "cache_creation_input_tokens", 0) or 0
+                    cr = getattr(u, "cache_read_input_tokens", 0) or 0
+                    # prompt_tokens = total input (non-cached + cached) so
+                    # context-window tracking matches OpenAI semantics.
+                    total_input = inp + cc + cr
                     sc.usage = UsageInfo(
-                        prompt_tokens=getattr(u, "input_tokens", 0),
-                        completion_tokens=getattr(u, "output_tokens", 0),
-                        total_tokens=(
-                            getattr(u, "input_tokens", 0) + getattr(u, "output_tokens", 0)
-                        ),
-                        cache_creation_tokens=getattr(u, "cache_creation_input_tokens", 0) or 0,
-                        cache_read_tokens=getattr(u, "cache_read_input_tokens", 0) or 0,
+                        prompt_tokens=total_input,
+                        completion_tokens=out,
+                        total_tokens=total_input + out,
+                        cache_creation_tokens=cc,
+                        cache_read_tokens=cr,
                     )
                 if hasattr(event.delta, "stop_reason") and event.delta.stop_reason:
                     sc.finish_reason = _normalize_finish_reason(event.delta.stop_reason)
@@ -732,12 +737,16 @@ class AnthropicProvider:
             elif event_type == "message_start":
                 if hasattr(event.message, "usage") and event.message.usage:
                     u = event.message.usage
+                    inp = getattr(u, "input_tokens", 0) or 0
+                    cc = getattr(u, "cache_creation_input_tokens", 0) or 0
+                    cr = getattr(u, "cache_read_input_tokens", 0) or 0
+                    total_input = inp + cc + cr
                     sc.usage = UsageInfo(
-                        prompt_tokens=getattr(u, "input_tokens", 0),
+                        prompt_tokens=total_input,
                         completion_tokens=0,
-                        total_tokens=getattr(u, "input_tokens", 0),
-                        cache_creation_tokens=getattr(u, "cache_creation_input_tokens", 0) or 0,
-                        cache_read_tokens=getattr(u, "cache_read_input_tokens", 0) or 0,
+                        total_tokens=total_input,
+                        cache_creation_tokens=cc,
+                        cache_read_tokens=cr,
                     )
 
             has_content = sc.content_delta or sc.reasoning_delta or sc.tool_call_deltas
@@ -826,12 +835,17 @@ class AnthropicProvider:
         usage = None
         if hasattr(response, "usage") and response.usage:
             u = response.usage
+            inp = getattr(u, "input_tokens", 0) or 0
+            out = getattr(u, "output_tokens", 0) or 0
+            cc = getattr(u, "cache_creation_input_tokens", 0) or 0
+            cr = getattr(u, "cache_read_input_tokens", 0) or 0
+            total_input = inp + cc + cr
             usage = UsageInfo(
-                prompt_tokens=u.input_tokens,
-                completion_tokens=u.output_tokens,
-                total_tokens=u.input_tokens + u.output_tokens,
-                cache_creation_tokens=getattr(u, "cache_creation_input_tokens", 0) or 0,
-                cache_read_tokens=getattr(u, "cache_read_input_tokens", 0) or 0,
+                prompt_tokens=total_input,
+                completion_tokens=out,
+                total_tokens=total_input + out,
+                cache_creation_tokens=cc,
+                cache_read_tokens=cr,
             )
 
         return CompletionResult(

turnstone/core/providers/_openai_common.py

@@ -7,14 +7,19 @@ formatting, and message sanitisation live here so both
 
 from __future__ import annotations
 
+import uuid
 from typing import Any
 
+import structlog
+
 from turnstone.core.providers._protocol import (
     ModelCapabilities,
     UsageInfo,
     _lookup_capabilities,
 )
 
+log = structlog.get_logger(__name__)
+
 # ---------------------------------------------------------------------------
 # Model capability table
 # ---------------------------------------------------------------------------
@@ -304,21 +309,132 @@ def format_citations(content: str, annotations: list[Any]) -> str:
 def sanitize_messages(
     messages: list[dict[str, Any]],
 ) -> list[dict[str, Any]]:
-    """Ensure assistant messages always have ``content`` or ``tool_calls``.
+    """Sanitize messages for OpenAI-compatible APIs.
 
-    OpenAI-compatible APIs reject assistant messages that have neither.
-    This is a defensive catch-all; the upstream layers should already
-    guarantee well-formed messages.
+    Performs three repairs:
+
+    1. Ensures assistant messages always have ``content`` or ``tool_calls``
+       (APIs reject messages with neither).
+    2. Fills empty tool_call IDs with synthetic ``call_{uuid}`` values
+       (local servers sometimes omit them).
+    3. Detects and repairs orphaned tool_call / tool_result pairs:
+
+       - Synthesizes error tool messages for tool_calls with no matching
+         tool result.
+       - Drops tool messages whose ``tool_call_id`` has no matching
+         tool_call in the preceding assistant message.
+
+    Returns a new list; the original messages are not mutated.
     """
     out: list[dict[str, Any]] = []
-    for msg in messages:
-        if (
-            msg.get("role") == "assistant"
-            and msg.get("content") is None
-            and not msg.get("tool_calls")
-        ):
+    i = 0
+    while i < len(messages):
+        msg = messages[i]
+        role = msg.get("role", "")
+
+        # (1) Fix empty-content assistant messages
+        if role == "assistant" and msg.get("content") is None and not msg.get("tool_calls"):
             msg = {**msg, "content": ""}
+            out.append(msg)
+            i += 1
+            continue
+
+        # (2+3) Assistant with tool_calls: fix IDs and detect orphans
+        if role == "assistant" and msg.get("tool_calls"):
+            tool_calls = msg["tool_calls"]
+
+            # Back-fill empty IDs and build positional remap for tool results.
+            # Local servers (vLLM, llama.cpp) sometimes omit IDs entirely;
+            # positional pairing is the best heuristic in that case.
+            needs_id_fix = any(not tc.get("id") for tc in tool_calls)
+            id_remap: dict[int, str] = {}  # positional index → new ID
+            if needs_id_fix:
+                new_tcs = []
+                empty_idx = 0
+                for tc in tool_calls:
+                    if not tc.get("id"):
+                        new_id = f"call_{uuid.uuid4().hex}"
+                        id_remap[empty_idx] = new_id
+                        empty_idx += 1
+                        new_tcs.append({**tc, "id": new_id})
+                    else:
+                        new_tcs.append(tc)
+                msg = {**msg, "tool_calls": new_tcs}
+                tool_calls = msg["tool_calls"]
+
+            # Collect IDs from this assistant message
+            tc_ids = [tc["id"] for tc in tool_calls if tc.get("id")]
+            tc_id_set = set(tc_ids)
+
+            out.append(msg)
+            i += 1
+
+            # Copy through existing tool messages, applying ID remap and
+            # filtering out stale results that don't match any tool_call.
+            local_answered: set[str] = set()
+            empty_result_idx = 0
+            while i < len(messages) and messages[i].get("role") == "tool":
+                tool_msg = messages[i]
+                result_tc_id = tool_msg.get("tool_call_id", "")
+                if not result_tc_id and empty_result_idx in id_remap:
+                    # Positional remap: empty result → matching new ID
+                    new_id = id_remap[empty_result_idx]
+                    tool_msg = {**tool_msg, "tool_call_id": new_id}
+                    local_answered.add(new_id)
+                    empty_result_idx += 1
+                    out.append(tool_msg)
+                elif not result_tc_id:
+                    # Empty ID with no remap available — drop it
+                    log.debug("sanitize_messages: dropping tool result with empty ID")
+                    empty_result_idx += 1
+                elif result_tc_id in tc_id_set:
+                    local_answered.add(result_tc_id)
+                    out.append(tool_msg)
+                else:
+                    log.debug(
+                        "sanitize_messages: dropping stale tool result: %s",
+                        result_tc_id,
+                    )
+                i += 1
+
+            # Synthesize error results for tool_calls not answered in
+            # THIS turn (not all of `out`, to avoid false matches from
+            # reused IDs across turns).
+            still_orphaned = [uid for uid in tc_ids if uid not in local_answered]
+            if still_orphaned:
+                log.debug(
+                    "sanitize_messages: synthesizing %d tool result(s) for orphaned tool_calls",
+                    len(still_orphaned),
+                )
+                for uid in still_orphaned:
+                    out.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": uid,
+                            "content": "Tool execution was cancelled.",
+                        }
+                    )
+            continue
+
+        # (3d) Drop orphaned tool results
+        if role == "tool":
+            tc_id = msg.get("tool_call_id", "")
+            # Find the preceding assistant message's tool_call IDs
+            prev_tc_ids: set[str] = set()
+            for k in range(len(out) - 1, -1, -1):
+                if out[k].get("role") == "assistant" and out[k].get("tool_calls"):
+                    prev_tc_ids = {tc.get("id", "") for tc in out[k]["tool_calls"] if tc.get("id")}
+                    break
+            if prev_tc_ids and tc_id and tc_id not in prev_tc_ids:
+                log.debug(
+                    "sanitize_messages: dropping orphaned tool result (no matching tool_call): %s",
+                    tc_id,
+                )
+                i += 1
+                continue
+
         out.append(msg)
+        i += 1
     return out
 
 

turnstone/core/providers/_openai_responses.py

@@ -24,6 +24,7 @@ from turnstone.core.providers._openai_common import (
     format_citations,
     lookup_openai_capabilities,
     resolve_reasoning_effort,
+    sanitize_messages,
 )
 from turnstone.core.providers._protocol import (
     CompletionResult,
@@ -83,6 +84,7 @@ class OpenAIResponsesProvider:
         concatenated system/developer messages (or ``None``) and *input_items*
         is the Responses API ``input`` array.
         """
+        messages = sanitize_messages(messages)
         instructions_parts: list[str] = []
         items: list[dict[str, Any]] = []
 

turnstone/core/session.py

@@ -372,6 +372,7 @@ class ChatSession:
         self._applied_skill_version: int = 0
         self._applied_skill_content: str = ""  # inline prompt from applied skill
         self._assistant_pending_tokens = 0
+        self._calibrated_msg_count = 0  # len(messages) at last _update_token_table
         self.creative_mode = False
         self._notify_count = 0
         # Watch support: server-level runner injected via set_watch_runner()
@@ -918,11 +919,25 @@ class ChatSession:
     def _remaining_token_budget(self) -> int:
         """Estimate how many tokens are available for new content.
 
+        When provider-reported usage is available, uses the last API
+        call's ``prompt_tokens`` as ground truth and only estimates the
+        delta (messages added since that call).  Falls back to pure
+        local estimates otherwise.
+
         Reserves a response budget (capped at 25% of context window, since
         ``max_tokens`` is an upper bound, not guaranteed consumption) plus
         a 5% safety margin.  Returns at least 0.
         """
         used = self._system_tokens + sum(self._msg_tokens)
+        if self._last_usage:
+            # Provider-reported tokens from the last API call
+            base = self._last_usage["prompt_tokens"]
+            # Only estimate tokens for messages added AFTER calibration.
+            # Clamp index to prevent stale _calibrated_msg_count from
+            # over-slicing after compaction or message list mutations.
+            start = min(self._calibrated_msg_count, len(self._msg_tokens))
+            new_msg_tokens = sum(self._msg_tokens[start:])
+            used = base + new_msg_tokens
         response_reserve = min(self.max_tokens, self.context_window // 4)
         safety_margin = int(self.context_window * 0.05)
         return max(0, self.context_window - used - response_reserve - safety_margin)
@@ -1090,6 +1105,7 @@ class ChatSession:
         self._read_files.clear()
         self._recent_tool_sigs.clear()
         self._last_usage = None
+        self._calibrated_msg_count = 0
         self._title_generated = True  # don't re-title resumed workstreams
         self._msg_tokens = [
             max(1, int(self._msg_char_count(m) / self._chars_per_token)) for m in self.messages
@@ -1836,6 +1852,7 @@ class ChatSession:
                     return
 
                 self._update_token_table(assistant_msg)
+                self._print_status_line()  # Report usage for EVERY API call
                 self.messages.append(assistant_msg)
                 self._msg_tokens.append(
                     self._assistant_pending_tokens
@@ -1875,7 +1892,6 @@ class ChatSession:
 
                 tool_calls = assistant_msg.get("tool_calls")
                 if not tool_calls:
-                    self._print_status_line()
                     # Auto-compact when prompt exceeds threshold
                     if (
                         self._last_usage
@@ -2093,6 +2109,18 @@ class ChatSession:
                 if user_feedback:
                     self.messages.append({"role": "user", "content": user_feedback})
                     self._msg_tokens.append(max(1, int(len(user_feedback) / self._chars_per_token)))
+
+                # Mid-turn compaction: prevent context overflow during long
+                # tool chains.  Uses local estimates since _last_usage reflects
+                # the previous API call, not the tool results just appended.
+                estimated_prompt = self._system_tokens + sum(self._msg_tokens)
+                if estimated_prompt > self.context_window * self.auto_compact_pct:
+                    pct_display = int(self.auto_compact_pct * 100)
+                    self.ui.on_info(
+                        f"\n[Auto-compacting mid-turn: estimated prompt "
+                        f"exceeds {pct_display}% of context window]"
+                    )
+                    self._compact_messages(auto=True)
         except GenerationCancelled:
             # If a newer send() has started (force cancel), this thread is
             # orphaned — skip all message mutations and state changes.
@@ -2259,6 +2287,11 @@ class ChatSession:
         Returns the complete assistant message as a dict suitable for
         appending to self.messages.
         """
+        # Reset so this API call captures fresh usage — prevents stale
+        # completion_tokens from a prior tool-chain iteration leaking
+        # through the max() accumulator.
+        self._last_usage = None
+
         content_parts: list[str] = []
         reasoning_parts: list[str] = []
         tool_calls_acc: dict[int, dict[str, Any]] = {}
@@ -2598,17 +2631,44 @@ class ChatSession:
 
     # -- Token tracking & status ----------------------------------------------
 
-    def _msg_char_count(self, msg: dict[str, Any]) -> int:
-        """Count characters in a message, including tool call arguments."""
+    # Fixed token count per image (provider-agnostic average).
+    _IMAGE_TOKENS = 1000
+
+    @staticmethod
+    def _msg_text_chars(msg: dict[str, Any]) -> tuple[int, int]:
+        """Return (text_chars, image_count) for a message.
+
+        Counts all textual content plus structural overhead (role,
+        tool_call IDs, tool call names/arguments).  Images are counted
+        separately so the calibration can subtract their fixed token
+        cost from prompt_tokens.
+        """
         content = msg.get("content")
+        n = 0
+        images = 0
         if isinstance(content, list):
-            n = sum(len(p.get("text", "")) for p in content if p.get("type") == "text")
+            n += sum(len(p.get("text", "")) for p in content if p.get("type") == "text")
+            images += sum(1 for p in content if p.get("type") == "image_url")
         else:
-            n = len(content or "")
+            n += len(content or "")
         for tc in msg.get("tool_calls", []):
+            n += len(tc.get("id", ""))
             n += len(tc.get("function", {}).get("name", ""))
             n += len(tc.get("function", {}).get("arguments", ""))
-        return n
+        # Structural overhead: role, tool_call_id
+        n += len(msg.get("role", ""))
+        n += len(msg.get("tool_call_id", ""))
+        return n, images
+
+    def _msg_char_count(self, msg: dict[str, Any]) -> int:
+        """Count characters in a message, including structural overhead.
+
+        Includes role markers, tool_call IDs, and image placeholders so
+        that the chars_per_token calibration matches what providers
+        actually bill.
+        """
+        text_chars, images = self._msg_text_chars(msg)
+        return text_chars + int(images * self._IMAGE_TOKENS * self._chars_per_token)
 
     def _update_token_table(self, assistant_msg: dict[str, Any]) -> None:
         """Update per-message token estimates using API usage data."""
@@ -2619,12 +2679,28 @@ class ChatSession:
         compl_tok = self._last_usage["completion_tokens"]
 
         # Calibrate chars_per_token ratio from actual usage.
+        # Images get a fixed token budget, so we subtract those from the
+        # provider-reported prompt_tokens and calibrate only the text portion.
         all_msgs = self._full_messages()  # system + self.messages (before append)
         active_tools = self._get_active_tools() or []
         tool_def_chars = sum(len(json.dumps(t)) for t in active_tools)
-        total_chars = sum(self._msg_char_count(m) for m in all_msgs) + tool_def_chars
-        if total_chars > 0 and prompt_tok > 0:
-            self._chars_per_token = total_chars / prompt_tok
+        text_chars = 0
+        image_count = 0
+        for m in all_msgs:
+            tc, ic = self._msg_text_chars(m)
+            text_chars += tc
+            image_count += ic
+        text_chars += tool_def_chars
+        image_tokens = image_count * self._IMAGE_TOKENS
+        text_prompt_tok = prompt_tok - image_tokens
+        if text_prompt_tok <= 0:
+            log.debug(
+                "Image token estimate (%d) >= prompt_tokens (%d), skipping calibration",
+                image_tokens,
+                prompt_tok,
+            )
+        elif text_chars > 0:
+            self._chars_per_token = text_chars / text_prompt_tok
 
         # Compute system_tokens (stable after first call)
         sys_chars = sum(self._msg_char_count(m) for m in self.system_messages)
@@ -2638,6 +2714,10 @@ class ChatSession:
         # Stash completion_tokens for the assistant message about to be appended
         self._assistant_pending_tokens = compl_tok
 
+        # Record how many messages were in context at calibration time so
+        # _remaining_token_budget() can estimate only the delta.
+        self._calibrated_msg_count = len(self.messages)
+
         # Token budget tracking
         if self._token_budget > 0:
             total = prompt_tok + compl_tok
@@ -2849,6 +2929,7 @@ class ChatSession:
         su_tok = max(1, int(self._msg_char_count(summary_user) / self._chars_per_token))
         sa_tok = max(1, int(self._msg_char_count(summary_asst) / self._chars_per_token))
         self._msg_tokens = [su_tok, sa_tok]
+        self._calibrated_msg_count = len(self.messages)  # anchored to compacted state
         after_tokens = self._system_tokens + sum(self._msg_tokens)
 
         # Update usage estimate so the status bar reflects post-compaction state
@@ -6713,6 +6794,7 @@ class ChatSession:
             self._read_files.clear()
             self._recent_tool_sigs.clear()
             self._last_usage = None
+            self._calibrated_msg_count = 0
             self._msg_tokens = []
             self.ui.on_info("Context cleared (messages preserved in database).")
 
@@ -6723,6 +6805,7 @@ class ChatSession:
             self._read_files.clear()
             self._recent_tool_sigs.clear()
             self._last_usage = None
+            self._calibrated_msg_count = 0
             self._msg_tokens = []
             self._ws_id = uuid.uuid4().hex
             self._title_generated = False

uv.lock

@@ -2501,7 +2501,7 @@ wheels = [
 
 [[package]]
 name = "turnstone"
-version = "1.2.1"
+version = "1.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },