Large Tool Outputs to Disk — runtime test
Hands-on runtime battle-test of Large Tool Outputs to Disk. Result: PASS.
Large Tool Outputs to Disk — Runtime Test
Large bash and tool outputs exceeding ~900KB are automatically persisted to disk with a preview shown in context, preserving full output that would otherwise be truncated or lost.
How It Works
When a tool output exceeds the approximate 900KB–1MB threshold, the runtime writes the complete output to disk at ~/.claude/projects/{project}/{session}/tool-results/toolu_{tool_id}.txt and returns a <persisted-output> wrapper to the agent. This wrapper contains the file path and a 2KB preview of the output, enabling the agent to access the full result without inflating context tokens. The actual file persists after session close.
The Test
The test created files of varying sizes and used cat to output them. Results showed a threshold transition: outputs below 850KB remained inline (truncated), 950KB was variable, and 1MB+ consistently persisted to disk. The threshold is not a hard byte limit and may shift based on current context size and token count.
A 1MB output persisted successfully; the runtime confirmed full preservation with the filename in the header and showed the first 2KB inline as preview. The agent could read the persisted file using standard Read tools.
Why It Matters
Before this feature, large outputs were truncated in context, losing information. Now the full output is saved to disk and accessible, while context cost drops dramatically: a 1MB output consumed only ~2KB of context (the preview) instead of 30KB of truncated content. This preserves agent access to complete tool results without token waste.
Caveats
Binary outputs were not tested; upper limits (files >10MB) were not explored; behavior under concurrent large outputs remains untested. The threshold variability means agents cannot hardclaim a fixed cutoff.
Status: PASS — Feature works as designed. Tested 2026-01-16 on Claude Code 2.1.2 features on 2.1.9 runtime.
Test Results: Large Tool Outputs to Disk
Feature: Large bash command outputs and tool outputs are now saved to disk instead of truncated
Tested: 2026-01-16 Version: 2.1.2 features on 2.1.9
Test Setup
Created files of various sizes and used cat to output them, observing behavior.
Test Results
Test 1: 1MB file
Result: PERSISTED TO DISK ✅
<persisted-output>
Output too large (1MB). Full output saved to:
/Users/ryanhunter/.claude/projects/.../tool-results/toolu_XXXX.txt
Preview (first 2KB):
Line 1: This is test content...
...
</persisted-output>
- Full output preserved in file
- Preview shown (first 2KB)
- Tool result ID in filename
Test 2: Various sizes
| Size | Behavior |
|---|---|
| 25KB | Inline, truncated |
| 50KB | Inline, truncated |
| 100KB | Inline, truncated |
| 500KB | Inline, truncated |
| 750KB | Inline, truncated |
| 850KB | Inline, truncated |
| 920KB | Inline, truncated |
| 950KB | Sometimes persisted, sometimes inline |
| 1MB+ | Consistently persisted |
Threshold Finding
The threshold appears to be approximately 900KB-1MB, but may vary based on:
- Current context size
- Token count (not just bytes)
- Session state
The threshold is NOT a hard byte limit - there's some variability.
Key Findings
- Full output preserved - The complete output is saved, not truncated
- File location -
~/.claude/projects/{project}/{session}/tool-results/toolu_{ID}.txt - Preview provided - First 2KB shown inline with pointer to full file
- Wrapper format -
<persisted-output>...</persisted-output>tags - Accessible - I can read the persisted file using Read or Bash
Output Format
<persisted-output>
Output too large ({size}). Full output saved to: {path}
Preview (first 2KB):
{first_2kb_of_content}
...
</persisted-output>
File Persistence
- Files stored in:
~/.claude/projects/{project-hash}/{session-id}/tool-results/ - Filename format:
toolu_{tool_use_id}.txt - Files persist after session (not auto-cleaned)
- Content is raw output (no wrapper)
Token Savings
Before: Large outputs truncated, information lost After: Full output saved, only preview in context
Estimated savings: For 1MB output, context only has ~2KB preview instead of 30KB truncated content.
Edge Cases
- Binary output: NOT TESTED - how does it handle non-text?
- Very large (10MB+): NOT TESTED - is there an upper limit?
- Concurrent outputs: NOT TESTED - how are multiple large outputs handled?
Status: PASS
Feature works as documented. Large outputs are saved to disk with a preview shown in context.
test_4fc18889ede9af146ab9f9f5ed255199b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6ddd6c43409a6ce8cffc5c326aa8cc3ab2cd4dcf24279b55f7a97715875e6aa7f11d7f55acc516a3576cf8b0166a4cbf1b93fb4e6479314c48d4c7adb1b114e4800Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.
- verifies Large Tool Outputs to Disk Primitive