Chapter 36: Tool Result Budget and Spill

The filesystem can extend working context only when the prompt keeps a trustworthy, retrievable pointer.

Public-source snapshot: implementation details are examples from public Kocoro origin/main at commit 4ec6772, reviewed 2026-07-27. Treat the invariant as the lesson and re-check constants against current source.

36.1 The problem

One large file read can dominate the next prompt; many medium parallel results can do the same in aggregate. Blind truncation prevents later inspection, while keeping everything makes the filesystem tool act like an accidental context-window denial of service.

36.2 The design rule

Spill the full payload to a runtime-owned file, replace the in-prompt result with a preview plus a pointer, and preserve that replacement across later turns. Enforce a per-result limit, and treat the per-turn aggregate as a best-effort target: after parallel execution, spill the largest eligible results until the batch fits under it. A turn can still end above target when a tool is exempt from spilling or when the spill itself fails — so treat exceeding it as a signal to investigate, not an impossible state.

36.3 Snapshot evidence

Source snapshot	Observation
`4ec6772`	per-result snapshot threshold: 50,000 characters
`4ec6772`	in-context preview: 2,000 runes
`4ec6772`	aggregate tool-result target per turn: 200,000 characters — not a hard ceiling: a spill-exempt or unlimited-size tool, or a failed spill, can still exit above it

The values above describe one dated implementation, not a universal contract.

36.4 Implementation checklist

Use rune-safe previews for multilingual text.
Make spill files session-scoped and access-controlled.
Test aggregate overflow with several medium results.

36.5 Takeaway

The filesystem can extend working context only when the prompt keeps a trustworthy, retrievable pointer.

Read these chapters as one system: context, tool schemas, persistence, steering, time discipline, loop detection, and concurrency affect one another.

@incollection{zhang2026aiagent_en_chapter-36-tool-result-budget-and-spill, author = {Zhang, Wayland}, title = {Chapter 36: Tool Result Budget and Spill}, booktitle = {AI Agent Architecture: From Single Agent to Enterprise Multi-Agent Systems}, year = {2026}, url = {https://waylandz.com/ai-agent-book-en/chapter-36-tool-result-budget-and-spill/} }