Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

feat(middleware): cap tool-result text in after_tool_call

xf gong005c75ab8483
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf6bc7f..1d28645 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- **`ToolResultLimitMiddleware` caps tool-result text in `after_tool_call`.**
+ Oversized text is truncated to `max_chars` (default 20,000) with a notice
+ telling the model to narrow the call. The rewrite happens before
+ `ToolExecutionEndEvent`, so the model, checkpointer, and host consumers
+ all see the truncated result. Image blocks are kept; tools in
+ `exclude_tool_names` pass through.
+
## [0.15.0] - 2026-09-16
### Added
diff --git a/cubeloop/middleware/__init__.py b/cubeloop/middleware/__init__.py
index a9feea5..a3e8378 100644
--- a/cubeloop/middleware/__init__.py
+++ b/cubeloop/middleware/__init__.py
@@ -9,6 +9,7 @@ __all__ = [
"CompactionState",
"GoalMiddleware",
"ToolResultCompressor",
+ "ToolResultLimitMiddleware",
"Middleware",
"SubagentMiddleware",
"SubagentRequest",
@@ -29,6 +30,10 @@ _LAZY = {
"CompactionMiddleware": ("cubeloop.middleware.compaction", "CompactionMiddleware"),
"CompactionState": ("cubeloop.middleware.compaction", "CompactionState"),
"ToolResultCompressor": ("cubeloop.middleware.compaction", "ToolResultCompressor"),
+ "ToolResultLimitMiddleware": (
+ "cubeloop.middleware.tool_result_limit",
+ "ToolResultLimitMiddleware",
+ ),
"GoalMiddleware": ("cubeloop.middleware.goal", "GoalMiddleware"),
"SubagentMiddleware": ("cubeloop.middleware.subagents", "SubagentMiddleware"),
"SubagentRequest": ("cubeloop.middleware.subagents", "SubagentRequest"),
diff --git a/cubeloop/middleware/tool_result_limit.py b/cubeloop/middleware/tool_result_limit.py
new file mode 100644
index 0000000..f231a65
--- /dev/null
+++ b/cubeloop/middleware/tool_result_limit.py
@@ -0,0 +1,103 @@
+"""Cap tool-result text before CubeLoop emits ``ToolExecutionEndEvent``.
+
+``after_tool_call`` runs after the tool returns and before the end event is
+published, so a truncated result is what the model, the checkpointer, and
+host event consumers all see. Hosts whose event bus has a byte budget
+(CubePlex projects at 1 MiB) stay inside that budget without failing the
+required consumer.
+
+Non-text blocks (images) are preserved. Tools listed in
+``exclude_tool_names`` pass through unchanged.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Collection
+
+from cubeloop.agent.types import AfterToolCallContext, AfterToolCallResult
+from cubeloop.middleware.base import Middleware
+from cubeloop.providers.base import Content, TextContent
+
+DEFAULT_MAX_TOOL_RESULT_CHARS = 20_000
+
+_TRUNCATION_NOTICE = (
+ "\n\n[truncated: tool result was {total} characters; "
+ "showing first {kept}. Narrow the tool call and retry.]"
+)
+
+
+def _text_char_count(content: list[Content]) -> int:
+ return sum(len(block.text) for block in content if isinstance(block, TextContent))
+
+
+def truncate_tool_result_content(
+ content: list[Content],
+ *,
+ max_chars: int,
+) -> list[Content] | None:
+ """Return truncated content, or ``None`` when no truncation is needed."""
+ total = _text_char_count(content)
+ if total <= max_chars:
+ return None
+
+ remaining = max_chars
+ truncated: list[Content] = []
+ for block in content:
+ if not isinstance(block, TextContent):
+ truncated.append(block)
+ continue
+ if remaining <= 0:
+ continue
+ if len(block.text) <= remaining:
+ truncated.append(block)
+ remaining -= len(block.text)
+ continue
+ truncated.append(TextContent(text=block.text[:remaining]))
+ remaining = 0
+
+ notice = _TRUNCATION_NOTICE.format(total=total, kept=max_chars)
+ if truncated and isinstance(truncated[-1], TextContent):
+ truncated[-1] = TextContent(text=truncated[-1].text + notice)
+ else:
+ truncated.append(TextContent(text=notice.lstrip()))
+ return truncated
+
+
+class ToolResultLimitMiddleware(Middleware):
+ """Rewrite oversized tool results in ``after_tool_call``.
+
+ Place this after other ``after_tool_call`` middleware so the truncated
+ content is what later composition and ``ToolExecutionEndEvent`` see.
+ Under the default last-non-None composer, a later middleware that
+ returns a result without ``content`` will drop this rewrite — put this
+ last, or use a merging composer.
+ """
+
+ def __init__(
+ self,
+ *,
+ max_chars: int = DEFAULT_MAX_TOOL_RESULT_CHARS,
+ exclude_tool_names: Collection[str] = (),
+ ) -> None:
+ if max_chars < 1:
+ raise ValueError("max_chars must be >= 1")
+ self.max_chars = max_chars
+ self.exclude_tool_names = frozenset(exclude_tool_names)
+
+ async def after_tool_call(
+ self,
+ ctx: AfterToolCallContext,
+ *,
+ signal: asyncio.Event | None = None,
+ ) -> AfterToolCallResult | None:
+ del signal
+ if ctx.tool_call.name in self.exclude_tool_names:
+ return None
+ truncated = truncate_tool_result_content(
+ ctx.result.content,
+ max_chars=self.max_chars,
+ )
+ if truncated is None:
+ return None
+ return AfterToolCallResult(content=truncated)
diff --git a/tests/middleware/test_init_exports.py b/tests/middleware/test_init_exports.py
index fd719ca..eba9034 100644
--- a/tests/middleware/test_init_exports.py
+++ b/tests/middleware/test_init_exports.py
@@ -10,6 +10,7 @@ def test_lazy_exports_resolve_builtin_middleware() -> None:
assert middleware.CompactionState.__name__ == "CompactionState"
assert middleware.SubagentMiddleware.__name__ == "SubagentMiddleware"
assert middleware.SubagentSpec.__name__ == "SubagentSpec"
+ assert middleware.ToolResultLimitMiddleware.__name__ == "ToolResultLimitMiddleware"
def test_unknown_lazy_export_raises_attribute_error() -> None:
diff --git a/tests/middleware/test_tool_result_limit.py b/tests/middleware/test_tool_result_limit.py
new file mode 100644
index 0000000..a973a40
--- /dev/null
+++ b/tests/middleware/test_tool_result_limit.py
@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import pytest
+
+from cubeloop.agent.types import (
+ AfterToolCallContext,
+ AgentContext,
+ AgentToolResult,
+)
+from cubeloop.middleware import ToolResultLimitMiddleware
+from cubeloop.middleware.tool_result_limit import (
+ DEFAULT_MAX_TOOL_RESULT_CHARS,
+ truncate_tool_result_content,
+)
+from cubeloop.providers.base import (
+ AssistantMessage,
+ Content,
+ ImageContent,
+ TextContent,
+ ToolCall,
+)
+
+
+def _ctx(
+ text: str | list[Content],
+ *,
+ name: str = "execute",
+) -> AfterToolCallContext:
+ content: list[Content] = (
+ [TextContent(text=text)] if isinstance(text, str) else list(text)
+ )
+ return AfterToolCallContext(
+ assistant_message=AssistantMessage(content=[]),
+ tool_call=ToolCall(id="t1", name=name, arguments={}),
+ args={},
+ result=AgentToolResult(content=content),
+ is_error=False,
+ context=AgentContext(system_prompt="", messages=[]),
+ )
+
+
+class TestTruncateToolResultContent:
+ def test_under_limit_returns_none(self) -> None:
+ content = [TextContent(text="hello")]
+ assert truncate_tool_result_content(content, max_chars=10) is None
+
+ def test_exact_limit_returns_none(self) -> None:
+ content = [TextContent(text="a" * 20)]
+ assert truncate_tool_result_content(content, max_chars=20) is None
+
+ def test_over_limit_keeps_prefix_and_appends_notice(self) -> None:
+ content = [TextContent(text="abcdefghij")]
+ out = truncate_tool_result_content(content, max_chars=4)
+ assert out is not None
+ assert len(out) == 1
+ assert isinstance(out[0], TextContent)
+ assert out[0].text.startswith("abcd")
+ assert "[truncated:" in out[0].text
+ assert "10 characters" in out[0].text
+ assert "showing first 4" in out[0].text
+
+ def test_truncates_across_text_blocks(self) -> None:
+ content = [
+ TextContent(text="aaa"),
+ TextContent(text="bbbbbb"),
+ ]
+ out = truncate_tool_result_content(content, max_chars=5)
+ assert out is not None
+ texts = [b.text for b in out if isinstance(b, TextContent)]
+ assert texts[0] == "aaa"
+ assert texts[1].startswith("bb")
+ assert "[truncated:" in texts[-1]
+
+ def test_preserves_image_blocks(self) -> None:
+ content = [
+ ImageContent(source="data:image/png;base64,xx", media_type="image/png"),
+ TextContent(text="x" * 50),
+ ]
+ out = truncate_tool_result_content(content, max_chars=4)
+ assert out is not None
+ assert isinstance(out[0], ImageContent)
+ assert isinstance(out[1], TextContent)
+ assert out[1].text.startswith("xxxx")
+ assert "[truncated:" in out[1].text
+
+
+class TestToolResultLimitMiddleware:
+ def test_rejects_non_positive_max_chars(self) -> None:
+ with pytest.raises(ValueError, match="max_chars"):
+ ToolResultLimitMiddleware(max_chars=0)
+
+ async def test_under_limit_is_noop(self) -> None:
+ mw = ToolResultLimitMiddleware(max_chars=20)
+ assert await mw.after_tool_call(_ctx("short")) is None
+
+ async def test_over_limit_rewrites_content(self) -> None:
+ mw = ToolResultLimitMiddleware(max_chars=8)
+ result = await mw.after_tool_call(_ctx("0123456789abcdef"))
+ assert result is not None
+ assert result.content is not None
+ assert isinstance(result.content[0], TextContent)
+ assert result.content[0].text.startswith("01234567")
+ assert "[truncated:" in result.content[0].text
+ assert result.details is None
+
+ async def test_excluded_tool_passes_through(self) -> None:
+ mw = ToolResultLimitMiddleware(
+ max_chars=4,
+ exclude_tool_names={"load_skill"},
+ )
+ huge = "x" * 100
+ assert await mw.after_tool_call(_ctx(huge, name="load_skill")) is None
+ rewritten = await mw.after_tool_call(_ctx(huge, name="execute"))
+ assert rewritten is not None
+
+ async def test_default_cap_matches_exported_constant(self) -> None:
+ mw = ToolResultLimitMiddleware()
+ assert mw.max_chars == DEFAULT_MAX_TOOL_RESULT_CHARS
+ body = "y" * (DEFAULT_MAX_TOOL_RESULT_CHARS + 50)
+ result = await mw.after_tool_call(_ctx(body))
+ assert result is not None
+ assert result.content is not None
+ text = result.content[0].text
+ assert text.startswith("y" * DEFAULT_MAX_TOOL_RESULT_CHARS)
+ assert "[truncated:" in text
diff --git a/website/docs/guides/middleware/examples.md b/website/docs/guides/middleware/examples.md
index 0b0b674..6ca00ba 100644
--- a/website/docs/guides/middleware/examples.md
+++ b/website/docs/guides/middleware/examples.md
@@ -171,6 +171,26 @@ class SummaryInjector(Middleware):
return f"{system_prompt}\n\nContext: {summary}".strip()
```
+## Built-in tool-result cap
+
+`ToolResultLimitMiddleware` truncates oversized tool-result text in
+`after_tool_call` so a runaway `execute` / fetch / MCP payload cannot
+blow the next model call (or a host event-size budget).
+
+```python
+from cubeloop.middleware import ToolResultLimitMiddleware
+
+agent = Agent(
+ model=…,
+ middleware=[
+ ToolResultLimitMiddleware(max_chars=20_000),
+ ],
+)
+```
+
+See [Tool Result Limit](./tool-result-limit.md) for options, exclusions,
+and placement.
+
## Built-in compaction
`CompactionMiddleware` summarizes older turns into `ctx.extra` and
diff --git a/website/docs/guides/middleware/tool-result-limit.md b/website/docs/guides/middleware/tool-result-limit.md
new file mode 100644
index 0000000..41095f7
--- /dev/null
+++ b/website/docs/guides/middleware/tool-result-limit.md
@@ -0,0 +1,70 @@
+---
+title: Tool Result Limit
+description: "Use ToolResultLimitMiddleware to cap tool-result text before it is emitted to the model and host event consumers."
+---
+
+# Tool Result Limit
+
+`ToolResultLimitMiddleware` truncates oversized tool-result text in
+`after_tool_call`, before CubeLoop publishes `ToolExecutionEndEvent`.
+The model, the checkpointer, and any host event consumer all see the
+truncated result.
+
+Use it when a tool can return unbounded output — shell commands,
+web fetches, MCP tools — and a huge result would blow the context
+window or a host event-size budget.
+
+## Basic setup
+
+```python
+from cubeloop import Agent
+from cubeloop.middleware import ToolResultLimitMiddleware
+
+agent = Agent(
+ model=provider.model("claude-sonnet-4-6"),
+ middleware=[
+ ToolResultLimitMiddleware(),
+ ],
+)
+```
+
+The default cap is 20,000 characters of text content. Results at or
+under the cap pass through unchanged (`after_tool_call` returns
+`None`). Over the cap, text is cut to the first `max_chars` characters
+and a notice is appended:
+
+```text
+[truncated: tool result was 1082017 characters; showing first 20000. Narrow the tool call and retry.]
+```
+
+Image blocks are kept. Only `TextContent` counts toward the cap.
+
+## Options
+
+```python
+ToolResultLimitMiddleware(
+ max_chars=20_000,
+ exclude_tool_names={"load_skill"},
+)
+```
+
+- `max_chars` — maximum characters of text kept from the original
+ result. Must be `>= 1`.
+- `exclude_tool_names` — tool names that skip truncation. Use this for
+ tools whose full payload is load-bearing (for example a skill body
+ returned by `load_skill`).
+
+## Placement
+
+Put this **after** other `after_tool_call` middleware so they rewrite
+the full result first, and the truncated text is what
+`ToolExecutionEndEvent` carries.
+
+CubeLoop's default composer is last-non-`None` wins. A later
+middleware that returns an `AfterToolCallResult` without `content`
+would drop this rewrite. Keep `ToolResultLimitMiddleware` last, or
+use a composer that merges `content` and `details`.
+
+Subagent child agents do not inherit parent middleware. Pass the same
+instance (or a second one) via `SubagentMiddleware(inherited_middleware=...)`
+if child tool results should be capped too.
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 6343f77..1baf8f4 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -45,6 +45,7 @@ const sidebars: SidebarsConfig = {
'guides/middleware/compaction',
'guides/middleware/subagents',
'guides/middleware/todo',
+ 'guides/middleware/tool-result-limit',
'guides/middleware/deferred-tools',
'guides/middleware/goal',
'guides/middleware/examples',