feat: add file persistence for large tool outputs by ben-vargas · Pull Request #6234 · anomalyco/opencode

ben-vargas · 2025-12-27T04:23:08Z

Edited 2026-01-07: Refactored to align to centralized truncation changes upstream; retain file persistence.

Summary

Enhances the centralized truncation system with file persistence for large tool outputs.

Background: Upstream recently added centralized truncation (Truncate.output() in tool.ts and registry.ts) which addresses "prompt is too long" errors by capping outputs at 50KB/2000 lines. However, this truncation permanently loses data - the model has no way to access content beyond the cutoff.

This PR retains the benefits of file persistence from the original approach: when outputs exceed the threshold, the full output is saved to disk and the model receives a preview with instructions for exploring the data using Read, Grep, or jq tools. The model can then make targeted requests to examine specific portions of large outputs.

Closes#4560
Related: #4826, #4845, #5360

Changes

truncation.ts - Extends the centralized truncation namespace with:

outputWithPersistence() - saves large outputs to ~/.local/share/opencode/storage/tool_results/{sessionID}/
Head (67%) + tail (33%) preview respecting caller's maxLines/maxBytes
JSON detection (.json extension + jq hint for structured queries)
10MB hard cap on persisted files with proper multibyte handling
Path traversal protection (sessionID validation + resolve containment check)
cleanupSessionFiles() for session deletion lifecycle

tool.ts - Updates Tool.define() wrapper to use outputWithPersistence

registry.ts - Updates fromPlugin() to use outputWithPersistence

session/index.ts - Calls cleanup on session delete

Benefits over pure truncation

Aspect	Upstream Truncation	This PR
Prompt size	✅ Controlled	✅ Controlled
Data access	❌ Lost permanently	✅ Preserved on disk
Model exploration	❌ Cannot access	✅ Via Read/Grep/jq

Coverage

All tools automatically get file persistence:

✅ Built-in tools via Tool.define() wrapper
✅ Plugin tools via fromPlugin()
✅ MCP tools (via registry)

mgunnin · 2025-12-29T19:45:12Z

I'm constantly having the prompt is too long error so this PR would be greatly appreciated.

mgunnin · 2025-12-29T19:46:39Z

Can we get this prioritized @fwang

taxilian · 2025-12-29T20:39:34Z

This seems likely to fix the single biggest usability issue with opencode that I keep hitting over and over and over... literally daily, multiple times per day with normal use of opencode.

codyw912 · 2025-12-29T20:48:54Z

This seems likely to fix the single biggest usability issue with opencode that I keep hitting over and over and over... literally daily, multiple times per day with normal use of opencode.

It's worked for me over the past few days. Haven't hit the "prompt too long" issue once.

Cherry-picked from PR anomalyco#6234 (ben-vargas/ai-opencode) When tool outputs exceed 30,000 characters, save to disk instead of passing to model context. This prevents 'prompt is too long' errors caused by large WebFetch, Bash, or MCP tool outputs. Changes: - Add tool-results.ts: Storage helper for large outputs - Update bash.ts, webfetch.ts, websearch.ts, codesearch.ts: File persistence - Update prompt.ts: MCP tools save large outputs to file - Update session/index.ts: Cleanup tool_results on session delete - Add OPENCODE_EXPERIMENTAL_MCP_MAX_OUTPUT_LENGTH flag for configurability

codyw912 · 2025-12-31T21:31:47Z

This seems likely to fix the single biggest usability issue with opencode that I keep hitting over and over and over... literally daily, multiple times per day with normal use of opencode.
It's worked for me over the past few days. Haven't hit the "prompt too long" issue once.

Just wanted to note, this actually hasn't completely fixed the bug for me. It has significantly lowered the frequency that I run into it, but it still happens a few times a day now. Seems like the team is working on a fix though.

ben-vargas · 2025-12-31T23:04:35Z

@codyw912 - yeah, this is just addressing one possible cause (tool use and specifically mcp tools) which often caused it for me. But i'm certain there are other edge cases to be addressed, hopefully their team gets all of them if not wanting to merge this PR.

I do hope they retain or implement a feature similar to writing to a file rather than just returning truncated data, the models are much more effective when they can be warned of the truncation and take a couple attempts at reading/exploring the large data, especially useful when using tools in enterprise (think reading data from salesforce or servicenow APIs). Flat out truncation of what the model gets back from tools alone isn't great.

@thdxr - Any thoughts on having this kind of file write rather than pure truncation of tools?

anntnzrb · 2026-01-07T14:10:02Z

+1

Refactors the file persistence feature to work with the new centralized truncation architecture in upstream. Instead of modifying each tool individually, this integrates file persistence directly into the Truncate namespace. When tool output exceeds 50KB/2000 lines, the full output is saved to disk and the model receives a head+tail preview with instructions for exploring the data using Read/Grep/jq tools. Changes: - truncation.ts: Add outputWithPersistence() function with: - Head (67%) + tail (33%) preview respecting caller's maxLines - Preview byte cap respecting min(caller's maxBytes, 20KB) - JSON detection (.json extension + jq hint) - 10MB hard cap on persisted files (using Buffer for both detection AND truncation to handle multibyte chars correctly) - Tool name sanitization (64 char limit, safe chars only) - Path traversal protection (sessionID validation + resolve check) - cleanupSessionFiles() for session deletion - tool.ts: Update Tool.define() wrapper to use outputWithPersistence - registry.ts: Update fromPlugin() to use outputWithPersistence - session/index.ts: Call Truncate.cleanupSessionFiles on session delete Benefits over previous per-tool approach: - Single point of change - all tools automatically get file persistence - Aligns with upstream's centralized truncation architecture - No duplicate truncation logic across multiple files - Cleaner integration with existing session lifecycle

MCP tools have a separate execution path in prompt.ts that wasn't covered by the centralized truncation changes. This adds Truncate.outputWithPersistence() to the MCP tool wrapper so that large outputs from MCP tools (like firecrawl) are also saved to disk instead of overflowing the context window. Also improves the truncation notice to be more explicit that the preview is INCOMPLETE and the model MUST read the file for accurate results - prevents models from answering based on partial data.

When a tool output is truncated and saved to file, the TUI now shows a [truncated] indicator in the tool call line so users can see at a glance that the output was truncated. Shows in warning color on both InlineTool and BlockTool displays.

ben-vargas · 2026-01-08T00:32:52Z

@rekram1-node one thing I found really helpful on the tool truncation persistence was the small little indicator to the user I added in the refactor which was done after your PR merging concepts.

You might consider adding something similar to 5e0aca1 in this branch so the user knows when a tool was truncated... helpful because sometimes I have to know truncation happened and prompt it to look a little deeper at the persisted tool output, and user doesn't know unless there is an indicator of some kind.

ben-vargas · 2026-01-08T00:33:30Z

Also, thanks for considering and landing the persistence!!

ben-vargas · 2026-02-04T21:24:42Z

mostly addressed by other commits referenced above

ben-vargas mentioned this pull request Dec 27, 2025
prompt is too long #5360
Closed

codyw912 mentioned this pull request Dec 29, 2025
Prompt is too long recovery compaction is not working code-yeongyu/oh-my-openagent#96
Closed

ben-vargas force-pushed the mcp-output-file-persistence branch from 496ae0e to 0339c06Compare January 5, 2026 03:04

ben-vargas force-pushed the mcp-output-file-persistence branch from 2e5a12e to ce28fd3Compare January 7, 2026 21:20

ben-vargas added 2 commits January 7, 2026 14:55

rekram1-node mentioned this pull request Jan 7, 2026
feat: write truncated tool outputs to files #7239
Merged

davidbernat mentioned this pull request Jan 8, 2026
[Feature] Add Fetch tool that saves to file (like Claude Code) #7168
Closed

github-actionsBot mentioned this pull request Jan 20, 2026
feat(opencode): switch tool truncation to token-based limits #9648
Closed

thdxr force-pushed the dev branch from cbab81f to 2d3c7a0Compare January 30, 2026 04:50

opencode-agentBotforce-pushed the dev branch from 00637c0 to 71e0ba2Compare January 30, 2026 14:32

thdxr force-pushed the dev branch 3 times, most recently from f1ae801 to 08fa7f7Compare January 30, 2026 14:37

ben-vargas closed this Feb 4, 2026

ben-vargas deleted the mcp-output-file-persistence branch February 4, 2026 23:29

Navigation Menu

Uh oh!

feat: add file persistence for large tool outputs - #6234

feat: add file persistence for large tool outputs#6234
ben-vargas wants to merge 3 commits into
anomalyco:devfrom
ben-vargas:mcp-output-file-persistence

ben-vargas commented Dec 27, 2025•
edited
Loading

Uh oh!

mgunnin commented Dec 29, 2025

Uh oh!

mgunnin commented Dec 29, 2025

Uh oh!

taxilian commented Dec 29, 2025

Uh oh!

codyw912 commented Dec 29, 2025

Uh oh!

codyw912 commented Dec 31, 2025

Uh oh!

ben-vargas commented Dec 31, 2025

Uh oh!

anntnzrb commented Jan 7, 2026

Uh oh!

ben-vargas commented Jan 8, 2026

Uh oh!

ben-vargas commented Jan 8, 2026

Uh oh!

ben-vargas commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

ben-vargas commented Dec 27, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Benefits over pure truncation

Coverage

Uh oh!

mgunnin commented Dec 29, 2025

Uh oh!

mgunnin commented Dec 29, 2025

Uh oh!

taxilian commented Dec 29, 2025

Uh oh!

codyw912 commented Dec 29, 2025

Uh oh!

codyw912 commented Dec 31, 2025

Uh oh!

ben-vargas commented Dec 31, 2025

Uh oh!

anntnzrb commented Jan 7, 2026

Uh oh!

ben-vargas commented Jan 8, 2026

Uh oh!

ben-vargas commented Jan 8, 2026

Uh oh!

ben-vargas commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ben-vargas commented Dec 27, 2025•
edited
Loading