fix(agent): hold the tools pin through a surface switch, name what it carried

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.
This commit is contained in:
joaomarcos
2026-09-06 19:37:39 -03:00
committed by kshitij
parent a020050c8c
commit 4a96311503
2 changed files with 88 additions and 20 deletions
+45 -10
View File
@@ -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.
+43 -10
View File
@@ -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: