[P1] Tool result auto-truncation at framework level

[JackChen-me]

Problem

Currently tool output size is entirely the user's responsibility. If a tool returns 50k lines of build logs, the full output gets injected into the agent's context, often causing context blowup. Users must manually truncate in their tool's execute function.

Industry comparison: Anthropic's context editing strips consumed tool results automatically. Most production agent systems have framework-level output management.

Proposal

Add a framework-level mechanism to control tool output size. Options to explore:

1. maxToolOutputTokens on AgentConfig or ToolExecutor — auto-truncate any tool result exceeding the limit (keep head + tail, or just tail for logs)
2. Per-tool maxOutputTokens on ToolDefinition — different tools have different expected output sizes
3. Post-consumption compression — after the agent has seen and acted on a tool result, replace it with a short summary in subsequent turns (similar to Anthropic's clear_tool_uses)

These are not mutually exclusive. Option 1 is the simplest starting point.

Source

• Competitive analysis: Anthropic context editing (clear_tool_uses_20250919), Manus context engineering blog post
• Triggered by [Feature] Provide Custom Tools. #108 discussion — user's ESP32 build logs blowing up agent context