Tool Result Size Management

PROJECT CONTEXT:
One verbose command or giant file read can blow half my agent's context. Harness source analyses show mature agents budget every tool's output and use head+tail truncation, pagination, and result references to stay bounded.

GOAL:
Enforce output budgets across all tools with signal-preserving truncation, pagination for big result sets, and references for oversized artifacts.

REQUIREMENTS:
- A per-tool output token budget with a global default
- Head+tail truncation preserving both ends with an honest elision marker
- Pagination for list-like results (search hits, directory listings)
- Reference-based results for oversized artifacts: store, summarize, fetch-on-demand
- Truncation events logged and visible to the model

CONSTRAINTS:
- Truncation must state exactly what was omitted and how to get more
- Error-bearing regions of output (tails of failed commands) must survive truncation

DEFINITION OF DONE:
- No tool can return more than its budget regardless of input
- A failed build's error message survives truncation of the megabyte before it
- Search with thousands of hits returns page one plus retrieval instructions
- An oversized file result becomes a summary plus a working fetch reference

COMMON FAILURES TO AVOID:
- Naive head-only truncation cutting off the error at the tail
- Silent truncation the model does not know happened, breeding hallucinated completions
- No pagination, so 'list files' becomes a context bomb
- Dumping artifacts into context that should have been stored and referenced