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:
+45
-10
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user