prompture 1.13.6.dev1__tar.gz → 1.13.7.dev1__tar.gz

{prompture-1.13.6.dev1 → prompture-1.13.7.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.13.6.dev1
+Version: 1.13.7.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -42,8 +42,10 @@ Requires-Dist: youtube-transcript-api>=1.0; extra == "web"
 Requires-Dist: trafilatura>=1.8; extra == "web"
 Provides-Extra: media
 Requires-Dist: yt-dlp>=2024.8.6; extra == "media"
+Provides-Extra: chess
+Requires-Dist: chess>=1.10; extra == "chess"
 Provides-Extra: all
-Requires-Dist: prompture[anthropic,google,groq,mcp,media,openai,pandas,sandbox,toon,web]; extra == "all"
+Requires-Dist: prompture[anthropic,chess,google,groq,mcp,media,openai,pandas,sandbox,toon,web]; extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
@@ -1417,6 +1419,28 @@ conv = Conversation("openai/gpt-4", tools=registry, simulated_tools=False)
 
 The simulation loop describes tools in the system prompt, asks the model to respond with JSON (`tool_call` or `final_answer`), executes tools, and feeds results back — all transparent to the caller.
 
+#### Keeping tools from filling the context window
+
+Two defaults keep large tool setups cheap, in both `Conversation` and `Agent`:
+
+- **Large results are stored, not cut.** A result over ~4k tokens, or a round of parallel results over ~12k tokens together (largest first), is stored and replaced by a short preview and an `artifact://` handle. The model reads what it needs with the built-in `read_tool_result(handle, query=..., offset=...)` tool, which is only offered once something has been stored. Error results are never stored.
+- **Tool schemas load on demand.** When the full schemas would cost more than ~8k tokens, the model gets `search_tools` and `load_tools` instead; loaded tools stay available for the rest of the conversation.
+
+```python
+from prompture import Conversation
+from prompture.agents.tool_context import ToolResultPolicy
+
+conv = Conversation(
+    "openai/gpt-4o",
+    tools=registry,
+    tool_result_policy=ToolResultPolicy(per_call_tokens=4000, batch_tokens=8000),
+    defer_tools="auto",            # True / False to force
+    preload_tools=["get_weather"], # always sent, even when deferring
+)
+```
+
+`max_tool_result_length=None` keeps results whole, and `ToolResultPolicy(offload=False)` restores plain truncation. Stored results live in memory and do not survive `save()` / `load()`. A tool call left without a result (for example a live stream closed mid-round) gets a placeholder result on the next call, so the provider does not reject the history.
+
 ### Live Streaming Tool Calls (any model, including local Ollama)
 
 `Conversation.ask_live` / `Agent.run_live` yields an interleaved event stream — text deltas, tool calls, tool results — *as the model produces them*. This is the "Claude Code feel" where the model narrates between actions instead of buffering everything into one chunk per turn.
@@ -1592,7 +1616,7 @@ agent = create_deep_agent(
     model="openai/gpt-4o",
     tools=[...],
     enable_summarization=True,          # default
-    summarize_at_tokens=80_000,         # default
+    summarize_at_tokens="auto",         # default: min(80k, 75% of window, window - max output)
     summarize_keep_last_n=6,            # default
     summarizer_model="openai/gpt-4o-mini",  # optional, falls back to main model
 )
@@ -2036,6 +2060,31 @@ prompture code-agent codex  --auto-approve "Add tests for the pricing cache"
 prompture code-agent aider  --auto-approve --model gpt-4o "Rename foo to bar across the package"
 ```
 
+#### Delegating a task
+
+`prompture delegate` hands a task to the companion's automation queue instead
+of running the agent in your terminal: the companion (`prompture companion`,
+started for you if it's not running) drives Claude Code or Codex unattended —
+permission prompts skipped, model access from this machine's Prompture setup,
+so the caller needs no provider key. The agent's work streams to stdout, and
+the queue keeps going in the background if you stop watching. This is the
+entry point to give other agents: a delegating LLM can run
+`prompture delegate "…"` and read the result, instead of reaching for its own
+API keys.
+
+```bash
+prompture delegate "Translate docs/guide.md to Spanish"
+prompture delegate --agent codex --cost-cap 2 "Add tests for the pricing cache"
+prompture delegate-status                  # what's the queue doing now
+prompture delegate-answer "Use SQLite"     # reply when a run ends on a question
+prompture delegate-resume                  # carry on after a failure or cost cap
+```
+
+Exit codes: `0` finished, `1` failed, `3` waiting for an answer, `4` stopped
+or still running in the background. `--json` prints the final run as JSON,
+`--no-wait` returns at once, and companion apps (like Prompture Desk) show the
+same queue live.
+
 #### From the server
 
 `prompture serve` exposes coding-agent discovery and execution as HTTP

{prompture-1.13.6.dev1 → prompture-1.13.7.dev1}/README.md

@@ -1300,6 +1300,28 @@ conv = Conversation("openai/gpt-4", tools=registry, simulated_tools=False)
 
 The simulation loop describes tools in the system prompt, asks the model to respond with JSON (`tool_call` or `final_answer`), executes tools, and feeds results back — all transparent to the caller.
 
+#### Keeping tools from filling the context window
+
+Two defaults keep large tool setups cheap, in both `Conversation` and `Agent`:
+
+- **Large results are stored, not cut.** A result over ~4k tokens, or a round of parallel results over ~12k tokens together (largest first), is stored and replaced by a short preview and an `artifact://` handle. The model reads what it needs with the built-in `read_tool_result(handle, query=..., offset=...)` tool, which is only offered once something has been stored. Error results are never stored.
+- **Tool schemas load on demand.** When the full schemas would cost more than ~8k tokens, the model gets `search_tools` and `load_tools` instead; loaded tools stay available for the rest of the conversation.
+
+```python
+from prompture import Conversation
+from prompture.agents.tool_context import ToolResultPolicy
+
+conv = Conversation(
+    "openai/gpt-4o",
+    tools=registry,
+    tool_result_policy=ToolResultPolicy(per_call_tokens=4000, batch_tokens=8000),
+    defer_tools="auto",            # True / False to force
+    preload_tools=["get_weather"], # always sent, even when deferring
+)
+```
+
+`max_tool_result_length=None` keeps results whole, and `ToolResultPolicy(offload=False)` restores plain truncation. Stored results live in memory and do not survive `save()` / `load()`. A tool call left without a result (for example a live stream closed mid-round) gets a placeholder result on the next call, so the provider does not reject the history.
+
 ### Live Streaming Tool Calls (any model, including local Ollama)
 
 `Conversation.ask_live` / `Agent.run_live` yields an interleaved event stream — text deltas, tool calls, tool results — *as the model produces them*. This is the "Claude Code feel" where the model narrates between actions instead of buffering everything into one chunk per turn.
@@ -1475,7 +1497,7 @@ agent = create_deep_agent(
     model="openai/gpt-4o",
     tools=[...],
     enable_summarization=True,          # default
-    summarize_at_tokens=80_000,         # default
+    summarize_at_tokens="auto",         # default: min(80k, 75% of window, window - max output)
     summarize_keep_last_n=6,            # default
     summarizer_model="openai/gpt-4o-mini",  # optional, falls back to main model
 )
@@ -1919,6 +1941,31 @@ prompture code-agent codex  --auto-approve "Add tests for the pricing cache"
 prompture code-agent aider  --auto-approve --model gpt-4o "Rename foo to bar across the package"
 ```
 
+#### Delegating a task
+
+`prompture delegate` hands a task to the companion's automation queue instead
+of running the agent in your terminal: the companion (`prompture companion`,
+started for you if it's not running) drives Claude Code or Codex unattended —
+permission prompts skipped, model access from this machine's Prompture setup,
+so the caller needs no provider key. The agent's work streams to stdout, and
+the queue keeps going in the background if you stop watching. This is the
+entry point to give other agents: a delegating LLM can run
+`prompture delegate "…"` and read the result, instead of reaching for its own
+API keys.
+
+```bash
+prompture delegate "Translate docs/guide.md to Spanish"
+prompture delegate --agent codex --cost-cap 2 "Add tests for the pricing cache"
+prompture delegate-status                  # what's the queue doing now
+prompture delegate-answer "Use SQLite"     # reply when a run ends on a question
+prompture delegate-resume                  # carry on after a failure or cost cap
+```
+
+Exit codes: `0` finished, `1` failed, `3` waiting for an answer, `4` stopped
+or still running in the background. `--json` prints the final run as JSON,
+`--no-wait` returns at once, and companion apps (like Prompture Desk) show the
+same queue live.
+
 #### From the server
 
 `prompture serve` exposes coding-agent discovery and execution as HTTP

{prompture-1.13.6.dev1 → prompture-1.13.7.dev1}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.13.6.dev1'
-__version_tuple__ = version_tuple = (1, 13, 6, 'dev1')
+__version__ = version = '1.13.7.dev1'
+__version_tuple__ = version_tuple = (1, 13, 7, 'dev1')
 
 __commit_id__ = commit_id = None

{prompture-1.13.6.dev1 → prompture-1.13.7.dev1}/prompture/agents/agent.py

@@ -35,7 +35,7 @@ import logging
 import time
 import typing
 from collections.abc import Callable, Generator
-from typing import Any, Generic
+from typing import Any, Generic, Literal
 
 from pydantic import BaseModel
 
@@ -47,6 +47,7 @@ from ..infra.provider_env import ProviderEnvironment
 from ..infra.session import UsageSession
 from .conversation import Conversation
 from .persona import Persona
+from .tool_context import ToolResultPolicy
 from .tools_schema import ToolDefinition, ToolRegistry
 from .types import (
     AgentCallbacks,
@@ -256,6 +257,14 @@ class Agent(Generic[DepsType]):
             instead of wedging the run forever.  ``None`` (default) means
             no timeout.  Can be overridden per call via
             ``options={"tool_timeout": ...}``.
+        tool_result_policy: When a tool result is moved out of context
+            instead of inlined (see :class:`ToolResultPolicy`).  Defaults
+            to offloading results over ~4k tokens, or ~12k per round.
+        defer_tools: Send tool schemas on demand via ``search_tools`` /
+            ``load_tools``.  ``"auto"`` (default) defers once the full
+            schemas would cost more than ~8k tokens.
+        preload_tools: Tools whose schemas are always sent, even when
+            deferring.
     """
 
     def __init__(
@@ -286,6 +295,9 @@ class Agent(Generic[DepsType]):
         skill_config: dict[str, Any] | None = None,
         max_tool_result_length: int | None = None,
         tool_timeout: float | None = None,
+        tool_result_policy: ToolResultPolicy | None = None,
+        defer_tools: bool | Literal["auto"] = "auto",
+        preload_tools: list[str] | None = None,
         max_depth: int = _DEFAULT_MAX_AGENT_DEPTH,
         env: ProviderEnvironment | None = None,
     ) -> None:
@@ -317,6 +329,9 @@ class Agent(Generic[DepsType]):
         self._auto_approve_safe_only = auto_approve_safe_only
         self._skill_config = skill_config
         self._max_tool_result_length = max_tool_result_length
+        self._tool_result_policy = tool_result_policy
+        self._defer_tools = defer_tools
+        self._preload_tools = list(preload_tools) if preload_tools else None
         self._tool_timeout = tool_timeout
         self._conversation: Conversation | None = None
         # The conversation driving the current run.  Tracked separately from
@@ -965,6 +980,11 @@ class Agent(Generic[DepsType]):
             kwargs["before_turn"] = hook
         if self._max_tool_result_length is not None:
             kwargs["max_tool_result_length"] = self._max_tool_result_length
+        if self._tool_result_policy is not None:
+            kwargs["tool_result_policy"] = self._tool_result_policy
+        kwargs["defer_tools"] = self._defer_tools
+        if self._preload_tools:
+            kwargs["preload_tools"] = self._preload_tools
         if self._tool_timeout is not None:
             kwargs["tool_timeout"] = self._tool_timeout
         if self._options:

{prompture-1.13.6.dev1 → prompture-1.13.7.dev1}/prompture/agents/async_agent.py

@@ -23,7 +23,7 @@ import logging
 import time
 import typing
 from collections.abc import AsyncGenerator, Callable
-from typing import Any, Generic
+from typing import Any, Generic, Literal
 
 from pydantic import BaseModel
 
@@ -33,6 +33,7 @@ from ..infra.callbacks import DriverCallbacks
 from ..infra.provider_env import ProviderEnvironment
 from ..infra.session import UsageSession
 from .persona import Persona
+from .tool_context import ToolResultPolicy
 from .tools_schema import ToolDefinition, ToolRegistry
 from .types import (
     AgentCallbacks,
@@ -193,6 +194,14 @@ class AsyncAgent(Generic[DepsType]):
             instead of wedging the run forever.  ``None`` (default) means
             no timeout.  Can be overridden per call via
             ``options={"tool_timeout": ...}``.
+        tool_result_policy: When a tool result is moved out of context
+            instead of inlined (see :class:`ToolResultPolicy`).  Defaults
+            to offloading results over ~4k tokens, or ~12k per round.
+        defer_tools: Send tool schemas on demand via ``search_tools`` /
+            ``load_tools``.  ``"auto"`` (default) defers once the full
+            schemas would cost more than ~8k tokens.
+        preload_tools: Tools whose schemas are always sent, even when
+            deferring.
     """
 
     def __init__(
@@ -223,6 +232,9 @@ class AsyncAgent(Generic[DepsType]):
         skill_config: dict[str, Any] | None = None,
         max_tool_result_length: int | None = None,
         tool_timeout: float | None = None,
+        tool_result_policy: ToolResultPolicy | None = None,
+        defer_tools: bool | Literal["auto"] = "auto",
+        preload_tools: list[str] | None = None,
         max_depth: int = _DEFAULT_MAX_AGENT_DEPTH,
         env: ProviderEnvironment | None = None,
     ) -> None:
@@ -254,6 +266,9 @@ class AsyncAgent(Generic[DepsType]):
         self._auto_approve_safe_only = auto_approve_safe_only
         self._skill_config = skill_config
         self._max_tool_result_length = max_tool_result_length
+        self._tool_result_policy = tool_result_policy
+        self._defer_tools = defer_tools
+        self._preload_tools = list(preload_tools) if preload_tools else None
         self._tool_timeout = tool_timeout
         self._conversation: Any = None
         # The conversation driving the current run.  Tracked separately from
@@ -993,6 +1008,11 @@ class AsyncAgent(Generic[DepsType]):
             kwargs["before_turn"] = hook
         if self._max_tool_result_length is not None:
             kwargs["max_tool_result_length"] = self._max_tool_result_length
+        if self._tool_result_policy is not None:
+            kwargs["tool_result_policy"] = self._tool_result_policy
+        kwargs["defer_tools"] = self._defer_tools
+        if self._preload_tools:
+            kwargs["preload_tools"] = self._preload_tools
         if self._tool_timeout is not None:
             kwargs["tool_timeout"] = self._tool_timeout
         if self._options:

{prompture-1.13.6.dev1 → prompture-1.13.7.dev1}/prompture/agents/async_conversation.py

@@ -32,12 +32,13 @@ from ..media.image import ImageInput, make_image
 from ..persistence.serialization import export_conversation, import_conversation
 from ..persistence.store import load_from_file, save_to_file
 from .persona import Persona, get_persona
+from .tool_context import ToolContextMixin, ToolResultPolicy, repair_tool_pairs
 from .tools_schema import ToolRegistry
 
 logger = logging.getLogger("prompture.async_conversation")
 
 
-class AsyncConversation:
+class AsyncConversation(ToolContextMixin):
     """Async stateful multi-turn conversation with an LLM.
 
     Mirrors :class:`Conversation` but all methods are ``async``.
@@ -75,6 +76,9 @@ class AsyncConversation:
         on_model_fallback: Callable[[str, str, Any], None] | None = None,
         env: ProviderEnvironment | None = None,
         before_turn: Callable[[AsyncConversation, int], Any] | None = None,
+        tool_result_policy: ToolResultPolicy | None = None,
+        defer_tools: bool | Literal["auto"] = "auto",
+        preload_tools: list[str] | None = None,
     ) -> None:
         if system_prompt is not None and persona is not None:
             raise ValueError("Cannot provide both 'system_prompt' and 'persona'. Use one or the other.")
@@ -127,6 +131,12 @@ class AsyncConversation:
         self._tools = tools or ToolRegistry()
         self._max_tool_rounds = max_tool_rounds
         self._max_tool_result_length = max_tool_result_length
+        self._init_tool_context(
+            max_tool_result_length=max_tool_result_length,
+            tool_result_policy=tool_result_policy,
+            defer_tools=defer_tools,
+            preload_tools=preload_tools,
+        )
         self._simulated_tools = simulated_tools
         self._max_history_messages = max_history_messages
         self._tool_timeout = tool_timeout
@@ -214,6 +224,7 @@ class AsyncConversation:
         """Reset message history (keeps system_prompt and driver)."""
         self._messages.clear()
         self._full_tool_results.clear()
+        self._reset_tool_context()
 
     def request_stop(self) -> None:
         """Request a cooperative stop of the tool loop.
@@ -442,26 +453,6 @@ class AsyncConversation:
             blocks.append({"type": "image", "source": ic})
         return blocks
 
-    def _truncate_tool_result(self, result_str: str) -> str:
-        """Truncate a tool result string if it exceeds the configured limit.
-
-        Returns the original string when no limit is set or the string is
-        within bounds.  Otherwise returns a truncated version with a note
-        indicating the original length.
-        """
-        if self._max_tool_result_length is None:
-            return result_str
-        if len(result_str) <= self._max_tool_result_length:
-            return result_str
-        logger.debug(
-            "Truncating tool result from %d to %d chars",
-            len(result_str),
-            self._max_tool_result_length,
-        )
-        return (
-            result_str[: self._max_tool_result_length] + f"\n\n[... result truncated ({len(result_str):,} chars total)]"
-        )
-
     def _trim_history(self) -> None:
         """Trim history to the sliding window without orphaning tool pairs.
 
@@ -507,11 +498,12 @@ class AsyncConversation:
         from ..extraction.tukuy_bridge import current_tool_call_id
 
         token = current_tool_call_id.set(tc["id"])
+        registry = self._dispatch_registry(tc["name"])
         try:
             if timeout is not None:
-                result = await asyncio.wait_for(self._tools.aexecute(tc["name"], tc["arguments"]), timeout)
+                result = await asyncio.wait_for(registry.aexecute(tc["name"], tc["arguments"]), timeout)
             else:
-                result = await self._tools.aexecute(tc["name"], tc["arguments"])
+                result = await registry.aexecute(tc["name"], tc["arguments"])
             return (json.dumps(result) if not isinstance(result, str) else result), False
         except (TimeoutError, asyncio.TimeoutError):
             return f"Error: tool '{tc['name']}' timed out after {timeout}s", True
@@ -588,6 +580,7 @@ class AsyncConversation:
 
     def _build_messages(self, user_content: str, images: list[ImageInput] | None = None) -> list[dict[str, Any]]:
         """Build the full messages array for an API call."""
+        repair_tool_pairs(self._messages)
         msgs: list[dict[str, Any]] = []
         if self._system_prompt:
             msgs.append({"role": "system", "content": self._system_prompt})
@@ -673,7 +666,6 @@ class AsyncConversation:
         self._stop_requested = False
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
-        tool_defs = self._tools.to_openai_format()
 
         user_content = self._build_content_with_images(content, images)
         self._messages.append({"role": "user", "content": user_content})
@@ -686,6 +678,7 @@ class AsyncConversation:
             self._check_budget()
             if await self._run_before_turn():
                 msgs = self._build_messages_raw()
+            tool_defs = self._active_tools().to_openai_format()
             resp = await self._driver.generate_messages_with_tools_with_hooks(msgs, tool_defs, merged)
 
             meta = resp.get("meta", {})
@@ -723,15 +716,14 @@ class AsyncConversation:
             msgs.append(assistant_msg)
 
             results = await self._run_tool_calls(tool_calls, merged)
-            for tc, (result_str, _is_error) in zip(tool_calls, results, strict=True):
-                # Preserve full result for step extraction before truncating
+            batch: list[tuple[str, str, bool]] = []
+            for tc, (result_str, is_error) in zip(tool_calls, results, strict=True):
+                # Preserve full result for step extraction before shaping
                 self._full_tool_results[tc["id"]] = result_str
+                batch.append((tc["name"], result_str, is_error))
 
-                tool_result_msg: dict[str, Any] = {
-                    "role": "tool",
-                    "tool_call_id": tc["id"],
-                    "content": self._truncate_tool_result(result_str),
-                }
+            for tc, content in zip(tool_calls, self._shape_tool_results(batch), strict=True):
+                tool_result_msg: dict[str, Any] = {"role": "tool", "tool_call_id": tc["id"], "content": content}
                 self._messages.append(tool_result_msg)
                 msgs.append(tool_result_msg)
 
@@ -773,7 +765,6 @@ class AsyncConversation:
         self._stop_requested = False
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
-        tool_defs = self._tools.to_openai_format()
 
         user_content = self._build_content_with_images(content, images)
         self._messages.append({"role": "user", "content": user_content})
@@ -788,6 +779,7 @@ class AsyncConversation:
             self._check_budget()
             if await self._run_before_turn():
                 msgs = self._build_messages_raw()
+            tool_defs = self._active_tools().to_openai_format()
             resp = await self._driver.generate_messages_with_tools_with_hooks(msgs, tool_defs, merged)
 
             meta = resp.get("meta", {})
@@ -834,9 +826,11 @@ class AsyncConversation:
             # Independent calls run concurrently; results stay in call order
             # so tool_call_id <-> result matching holds.
             results = await self._run_tool_calls(tool_calls, merged)
-            for tc, (result_str, _is_error) in zip(tool_calls, results, strict=True):
-                # Preserve full result for step extraction before truncating
+            batch: list[tuple[str, str, bool]] = []
+            for tc, (result_str, is_error) in zip(tool_calls, results, strict=True):
+                # Preserve full result for step extraction before shaping
                 self._full_tool_results[tc["id"]] = result_str
+                batch.append((tc["name"], result_str, is_error))
 
                 # Yield the FULL result for UI consumers
                 yield {
@@ -846,12 +840,9 @@ class AsyncConversation:
                     "id": tc["id"],
                 }
 
-                # Truncate before adding to conversation to avoid token overflow
-                tool_result_msg: dict[str, Any] = {
-                    "role": "tool",
-                    "tool_call_id": tc["id"],
-                    "content": self._truncate_tool_result(result_str),
-                }
+            # Shape the round as a whole before it enters history
+            for tc, content in zip(tool_calls, self._shape_tool_results(batch), strict=True):
+                tool_result_msg: dict[str, Any] = {"role": "tool", "tool_call_id": tc["id"], "content": content}
                 self._messages.append(tool_result_msg)
                 msgs.append(tool_result_msg)
 
@@ -920,7 +911,6 @@ class AsyncConversation:
         self._stop_requested = False
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
-        tool_defs = self._tools.to_openai_format()
 
         user_content = self._build_content_with_images(content, images)
         self._messages.append({"role": "user", "content": user_content})
@@ -945,6 +935,7 @@ class AsyncConversation:
             pending_tools: list[dict[str, Any]] = []
             turn_usage: dict[str, Any] = {}
 
+            tool_defs = self._active_tools().to_openai_format()
             stream = self._driver.generate_messages_with_tools_stream(msgs, tool_defs, merged)
             stream_started = time.perf_counter()
             recorded = False
@@ -1034,16 +1025,14 @@ class AsyncConversation:
             # Independent calls run concurrently; results stay in call order
             # so tool_call_id <-> result matching holds.
             results = await self._run_tool_calls(pending_tools, merged)
+            batch: list[tuple[str, str, bool]] = []
             for tc, (result_str, is_error) in zip(pending_tools, results, strict=True):
                 self._full_tool_results[tc["id"]] = result_str
+                batch.append((tc["name"], result_str, is_error))
                 yield ToolResult(id=tc["id"], name=tc["name"], output=result_str, is_error=is_error)
 
-                truncated_result = self._truncate_tool_result(result_str)
-                tool_result_msg: dict[str, Any] = {
-                    "role": "tool",
-                    "tool_call_id": tc["id"],
-                    "content": truncated_result,
-                }
+            for tc, content in zip(pending_tools, self._shape_tool_results(batch), strict=True):
+                tool_result_msg: dict[str, Any] = {"role": "tool", "tool_call_id": tc["id"], "content": content}
                 self._messages.append(tool_result_msg)
                 msgs.append(tool_result_msg)
 
@@ -1064,16 +1053,12 @@ class AsyncConversation:
         images: list[ImageInput] | None = None,
     ) -> AsyncIterator[dict[str, Any]]:
         """Async simulated tool calling with event emission."""
-        from .simulated_tools import build_tool_prompt, format_tool_result, parse_simulated_response
+        from .simulated_tools import format_tool_result, parse_simulated_response
 
         self._stop_requested = False
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
-        tool_prompt = build_tool_prompt(self._tools)
-
-        augmented_system = tool_prompt
-        if self._system_prompt:
-            augmented_system = f"{self._system_prompt}\n\n{tool_prompt}"
+        augmented_system = self._simulated_system_prompt()
 
         user_content = self._build_content_with_images(content, images)
         self._messages.append({"role": "user", "content": user_content})
@@ -1086,6 +1071,7 @@ class AsyncConversation:
                 return
             self._check_budget()
             await self._run_before_turn()
+            augmented_system = self._simulated_system_prompt()
             msgs: list[dict[str, Any]] = []
             msgs.append({"role": "system", "content": augmented_system})
             msgs.extend(self._messages)
@@ -1095,7 +1081,7 @@ class AsyncConversation:
             meta = resp.get("meta", {})
             self._accumulate_usage(meta)
 
-            parsed = parse_simulated_response(text, self._tools)
+            parsed = parse_simulated_response(text, self._all_callable_tools())
 
             if parsed["type"] == "final_answer":
                 answer = parsed["content"]
@@ -1115,10 +1101,11 @@ class AsyncConversation:
 
             _sim_token = _sim_tc_id.set("")
             try:
+                registry = self._dispatch_registry(tool_name)
                 if timeout is not None:
-                    result = await asyncio.wait_for(self._tools.aexecute(tool_name, tool_args), timeout)
+                    result = await asyncio.wait_for(registry.aexecute(tool_name, tool_args), timeout)
                 else:
-                    result = await self._tools.aexecute(tool_name, tool_args)
+                    result = await registry.aexecute(tool_name, tool_args)
                 result_msg = format_tool_result(tool_name, result)
             except (TimeoutError, asyncio.TimeoutError):
                 result_msg = format_tool_result(tool_name, f"Error: tool '{tool_name}' timed out after {timeout}s")
@@ -1129,7 +1116,8 @@ class AsyncConversation:
 
             yield {"type": "tool_result", "name": tool_name, "result": result_msg, "id": ""}
 
-            self._messages.append({"role": "user", "content": self._truncate_tool_result(result_msg)})
+            (shaped,) = self._shape_tool_results([(tool_name, result_msg, False)])
+            self._messages.append({"role": "user", "content": shaped})
 
         # Max rounds exhausted — graceful final answer without tools (C4).
         logger.warning(
@@ -1147,17 +1135,12 @@ class AsyncConversation:
         images: list[ImageInput] | None = None,
     ) -> str:
         """Async prompt-based tool calling for drivers without native tool use."""
-        from .simulated_tools import build_tool_prompt, format_tool_result, parse_simulated_response
+        from .simulated_tools import format_tool_result, parse_simulated_response
 
         self._stop_requested = False
         self._max_rounds_reached = False
         merged = {**self._options, **(options or {})}
-        tool_prompt = build_tool_prompt(self._tools)
-
-        # Augment system prompt with tool descriptions
-        augmented_system = tool_prompt
-        if self._system_prompt:
-            augmented_system = f"{self._system_prompt}\n\n{tool_prompt}"
+        augmented_system = self._simulated_system_prompt()
 
         # Record user message in history
         user_content = self._build_content_with_images(content, images)
@@ -1169,7 +1152,7 @@ class AsyncConversation:
                 return await self._final_answer_simulated(augmented_system, merged)
             self._check_budget()
             await self._run_before_turn()
-            # Build messages with the augmented system prompt
+            augmented_system = self._simulated_system_prompt()
             msgs: list[dict[str, Any]] = []
             msgs.append({"role": "system", "content": augmented_system})
             msgs.extend(self._messages)
@@ -1179,7 +1162,7 @@ class AsyncConversation:
             meta = resp.get("meta", {})
             self._accumulate_usage(meta)
 
-            parsed = parse_simulated_response(text, self._tools)
+            parsed = parse_simulated_response(text, self._all_callable_tools())
 
             if parsed["type"] == "final_answer":
                 answer: str = parsed["content"]
@@ -1195,18 +1178,20 @@ class AsyncConversation:
 
             timeout = merged.get("tool_timeout", self._tool_timeout)
             try:
+                registry = self._dispatch_registry(tool_name)
                 if timeout is not None:
-                    result = await asyncio.wait_for(self._tools.aexecute(tool_name, tool_args), timeout)
+                    result = await asyncio.wait_for(registry.aexecute(tool_name, tool_args), timeout)
                 else:
-                    result = await self._tools.aexecute(tool_name, tool_args)
+                    result = await registry.aexecute(tool_name, tool_args)
                 result_msg = format_tool_result(tool_name, result)
             except (TimeoutError, asyncio.TimeoutError):
                 result_msg = format_tool_result(tool_name, f"Error: tool '{tool_name}' timed out after {timeout}s")
             except Exception as exc:
                 result_msg = format_tool_result(tool_name, f"Error: {exc}")
 
-            # Record tool result as a user message (truncated for the LLM)
-            self._messages.append({"role": "user", "content": self._truncate_tool_result(result_msg)})
+            # Record tool result as a user message (shaped for the LLM)
+            (shaped,) = self._shape_tool_results([(tool_name, result_msg, False)])
+            self._messages.append({"role": "user", "content": shaped})
 
         # Max rounds exhausted — graceful final answer without tools (C4).
         logger.warning(
@@ -1218,6 +1203,7 @@ class AsyncConversation:
 
     def _build_messages_raw(self) -> list[dict[str, Any]]:
         """Build messages array from system prompt + full history (including tool messages)."""
+        repair_tool_pairs(self._messages)
         msgs: list[dict[str, Any]] = []
         if self._system_prompt:
             msgs.append({"role": "system", "content": self._system_prompt})