From 4a96311503e98947df92d7e91e077af2fe02cb67 Mon Sep 17 00:00:00 2001 From: joaomarcos Date: Sun, 6 Sep 2026 19:37:39 -0300 Subject: [PATCH] fix(agent): hold the tools pin through a surface switch, name what it carried MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The announcing turn used to skip the tools freeze and re-persist the array the new surface had just built. That is the one mutation this fix cannot afford: tools[] is serialized ahead of the system prompt, so rebuilding it moves the request at token 0 and re-prefills everything behind it — the exact cost #104414 measured (1% cache hit on a 220K session), spent on the very turn the fix exists to make cheap. On a `desktop -> tui` switch with a configured toolset selection (`_gui_surface_toolsets` gives desktop `desktop_ui`, the TUI nothing), skipping the pin dropped ~a dozen tools and bought back the whole miss. The pin now holds. `_merge_preserving_prefix` still appends what the new surface brought, so a `tui -> desktop` switch pays a break no freeze could have avoided, and the tools it carries FORWARD are named at the end of the surface note instead of being silently advertised: a `focus_pane` a terminal turn can only answer with `tool_error("desktop only")` now reads as unavailable rather than as live capability. The toolset converges at the next real rebuild boundary, where the break is already paid. Credit to @StanleyStetson, who caught that the tool array is evaluated ahead of the system prompt and that the bypass reintroduced the miss this PR is about. --- agent/conversation_loop.py | 55 ++++++++++++++++++----- tests/agent/test_system_prompt_restore.py | 53 +++++++++++++++++----- 2 files changed, 88 insertions(+), 20 deletions(-) diff --git a/agent/conversation_loop.py b/agent/conversation_loop.py index 98fd42a798..23b309cb02 100644 --- a/agent/conversation_loop.py +++ b/agent/conversation_loop.py @@ -693,20 +693,21 @@ def _restore_or_build_system_prompt(agent, system_message, conversation_history) announced_switch = _stage_surface_switch_note(agent, stored_prompt, conversation_history) # Same contract for tools[]: pin the array to the order this session already # sent (tools freeze) instead of re-probing every check_fn on a fresh AIAgent. - # NOT on the turn that announces a surface switch: the saved names are the PREVIOUS - # surface's toolset (``coding_context: focus`` gives desktop a desktop_ui toolset the - # TUI has no use for) and the tool registry is process-global, so the merge would - # re-advertise tools this surface cannot run. The fresh, toolset-correct array wins, - # and is persisted so the very next turn pins THAT one — the freeze is skipped once, - # not disabled for the rest of the session. + # The pin holds ON the announcing turn too. tools[] is serialized AHEAD of the system + # prompt this branch just preserved, so dropping the previous surface's toolset would + # change the request at token 0 and re-prefill everything behind it — the exact cost + # #104414 is about, paid on the exact turn we are here to make cheap. The merge still + # ADDS what the new surface brought (a tui -> desktop switch pays a break no freeze can + # avoid), and what it carries FORWARD is named in the note instead, so a tool that can + # only answer ``tool_error("desktop only")`` here does not read as a live capability. try: saved_tools = session_row.get("tool_names") if session_row else None - if announced_switch: - from tools.mcp_tool_agent import persist_agent_tool_names - persist_agent_tool_names(agent) - elif saved_tools: + if saved_tools: from tools.mcp_tool_agent import restore_agent_tool_prefix + built_for_this_surface = _agent_tool_names(agent) restore_agent_tool_prefix(agent, json.loads(saved_tools)) + if announced_switch: + _note_inert_pinned_tools(agent, built_for_this_surface) except Exception: logger.debug("tool prefix restore skipped", exc_info=True) # Prompt-section callbacks are new-session-only; recover their frozen bytes @@ -827,6 +828,40 @@ def _last_announced_surface(conversation_history) -> str: return "" +def _agent_tool_names(agent) -> list: + """The names in ``agent.tools``, in wire order ([] when the attribute is unreadable).""" + names = [] + try: + for entry in getattr(agent, "tools", None) or []: + name = (entry.get("function") or {}).get("name", "") if isinstance(entry, dict) else "" + if name: + names.append(name) + except Exception: + return [] + return names + + +def _note_inert_pinned_tools(agent, built_for_this_surface: list) -> None: + """Name the pinned tools THIS surface did not build, at the end of the switch note. + + The freeze keeps a previous surface's tools on the wire deliberately — removing them is the + one thing that would still re-prefill the request behind the preserved prompt — so the model + has to be TOLD they are inert here, or it plans around a ``focus_pane`` that a terminal turn + can only answer with ``tool_error("desktop only")``. Rides the note, so it is one-shot and + lands behind the cached prefix like the rest of the correction. + """ + surface_names = set(built_for_this_surface) + inert = [name for name in _agent_tool_names(agent) if name not in surface_names] + note = getattr(agent, "_surface_switch_note", "") or "" + if not inert or not note: + return + agent._surface_switch_note = note + ( + "\n[System: These tools stay listed for this conversation (dropping them would discard " + "the cached request prefix) but were not loaded for this interface — expect a call to " + f"one of them to fail: {', '.join(inert)}.]" + ) + + def _stage_surface_switch_note(agent, prompt: str, conversation_history) -> bool: """Stage a correction when the request would otherwise misdescribe the current surface. diff --git a/tests/agent/test_system_prompt_restore.py b/tests/agent/test_system_prompt_restore.py index db856b7698..b110d93f9b 100644 --- a/tests/agent/test_system_prompt_restore.py +++ b/tests/agent/test_system_prompt_restore.py @@ -70,7 +70,11 @@ class TestSurfaceSwitch: {"role": "assistant", "content": "hello"}, ] - def _restore(self, *, stored: str, current: str, history=None, tool_names=None): + @staticmethod + def _tool(name: str) -> dict: + return {"type": "function", "function": {"name": name, "parameters": {}}} + + def _restore(self, *, stored: str, current: str, history=None, tool_names=None, tools=None): db = MagicMock() row = {"system_prompt": self._stored(stored)} if tool_names is not None: @@ -78,6 +82,8 @@ class TestSurfaceSwitch: db.get_session.return_value = row agent = _make_agent(session_db=db) agent.platform = current + if tools is not None: + agent.tools = tools agent._platform_hint_overrides = None agent._surface_switch_note = "" agent._gateway_turn_context_notes = "" @@ -144,12 +150,11 @@ class TestSurfaceSwitch: agent._build_system_prompt.assert_called_once() assert agent._surface_switch_note.startswith(f"{_SURFACE_SWITCH_NOTE_PREFIX}desktop.") - def test_tool_prefix_is_replaced_on_the_turn_that_announces_a_switch(self): - """The saved names are the PREVIOUS surface's toolset. + def test_tool_prefix_stays_pinned_on_the_turn_that_announces_a_switch(self): + """tools[] is serialized ahead of the prompt this branch went out of its way to keep. - The tool registry is process-global, so ``_merge_preserving_prefix`` would keep a - saved-but-not-loaded tool (e.g. the desktop_ui toolset a `coding_context: focus` - desktop session gets) and re-advertise it on a TUI session that cannot run it. + Rebuilding the array for the new surface would move token 0 and re-prefill the whole + request — the cost #104414 is about — on the very turn the fix exists to make cheap. """ from unittest.mock import patch @@ -158,12 +163,40 @@ class TestSurfaceSwitch: patch("tools.mcp_tool_agent.persist_agent_tool_names") as persist, ): self._restore(stored="desktop", current="tui", tool_names='["desktop_ui_tool"]') - pin.assert_not_called() - persist.assert_called_once() + pin.assert_called_once() + persist.assert_not_called() + + def test_the_note_names_the_tools_the_pin_carried_forward(self): + """A pinned tool this surface did not build is inert here — say so. + + Keeping it on the wire is what preserves the prefix, so the model has to learn from the + note that calling it only returns ``tool_error("desktop only")``. + """ + from unittest.mock import patch + + def _carry_desktop_tool(agent, saved_names): + agent.tools = [self._tool("read_file"), self._tool("focus_pane")] + return True + + with patch("tools.mcp_tool_agent.restore_agent_tool_prefix", _carry_desktop_tool): + agent = self._restore(stored="desktop", current="tui", tool_names='["focus_pane"]', + tools=[self._tool("read_file")]) + assert "focus_pane" in agent._surface_switch_note + assert "were not loaded for this interface" in agent._surface_switch_note + # Only the carried-over name: a tool this surface built is not inert. + assert "read_file" not in agent._surface_switch_note.split("were not loaded for this interface")[1] + + def test_the_note_says_nothing_about_tools_when_the_pin_carries_none(self): + from unittest.mock import patch + + with patch("tools.mcp_tool_agent.restore_agent_tool_prefix", lambda agent, names: False): + agent = self._restore(stored="desktop", current="tui", tool_names='["read_file"]', + tools=[self._tool("read_file")]) + assert agent._surface_switch_note.startswith(f"{_SURFACE_SWITCH_NOTE_PREFIX}tui.") + assert "were not loaded for this interface" not in agent._surface_switch_note def test_tool_prefix_is_pinned_again_on_the_next_turn(self): - # The freeze is skipped once, not disabled for the rest of the session: the announcing - # turn persisted this surface's tools, so the next turn pins those. + # The pin is never skipped, on the announcing turn or after it. from unittest.mock import patch with patch("tools.mcp_tool_agent.restore_agent_tool_prefix") as pin: