Repository navigation
command @ includes go through the Read tool's 50 KB, 2000-line and 2000-character caps, with no config key #54007
Description
- Found: 2026-10-07, Cowright Plan 01-06 smoke; limits read from the 1.18.35 binary in Plan 01-09
- Environment: OpenCode 1.18.35, Linux
Summary
A command template (or skill) can reference files with @path. OpenCode turns each reference
into one synthetic Read call with no offset, before the model's first turn. The Read tool's normal
caps then apply to content that the command author meant to be delivered in full:
- output stops when the summed UTF-8 bytes of the delivered lines exceed 51,200, followed by
"(Output capped at 50 KB. Showing lines A-B. Use offset=C to continue.)"; - at most 2000 lines are returned;
- each line over 2000 characters is cut and suffixed "... (line truncated to 2000 chars)".
No config key changes these limits for @ includes. The truncation is visible only inside the
session, so the command author never sees it.
Minimal repro
- Create
~/.config/opencode/commands/big.mdwhose body is@/path/to/big.mdon its own line,
wherebig.mdis about 100 KB of markdown, and one line in it is 2500 characters long. opencode run --command big "go"- Inspect the session (for example in the TUI): the synthetic Read part for
big.mdends at
about 50 KB with the "Output capped" note, and the long line is cut.
Expected
Content a command explicitly includes is delivered in full, or at least up to a limit the user
can configure. If it must be truncated, the command author is warned when the command loads, not
the model mid-session.
Actual
The include is silently truncated. The model gets only an "offset" hint, which models routinely
ignore. Two of two attempts with mistral-large ignored it in Cowright's smoke.
Suggested fix
Deliver @ includes from command templates and skills in full (they are author-controlled
context, not a model-initiated Read). Alternatively, make the Read caps configurable for synthetic
include reads, and log a warning when an include is truncated.
Cowright workaround
The read-window patch (see U-02) splits and wraps the GSD files so that each part fits the window,
and lists every part as its own @ include. The constants are pinned to OpenCode 1.18.35 and must
be re-checked on every OpenCode upgrade.
Evidence
docs/smoke/runs/2026-10-07/headless.json(plan-phase root_cause quoting the "Output capped"
note)scripts/patches/read-window.cjsheader (constants and the@-reference regex, as read from
the 1.18.35 binary)
Activity
opencode-agent commentedon Oct 8, 2026
Thanks for the detailed write-up and the repro, @stiefenm.
This was reported on OpenCode 1.18.35, which is v1 (the
opencode-aipackage). v1 now only gets fixes for critical bugs, such as data loss, security problems, or crashes and breakage with no workaround. Truncated@includes are a real limitation, but you already have a workaround (splitting files into parts that fit the read window), so this is unlikely to be changed in v1.We recommend moving to v2 (
@opencode/cli, theopencodecommand), where active development happens. v2's Read tool also has 50 KB and 2000-character-per-line limits, but its command and include handling is a separate implementation. If you can reproduce the truncation on v2, please reply here with the v2 version and the same minimal repro, and we'll look at it there. Please also reply if you think this counts as critical on v1.opencode-agent commentedon Oct 9, 2026
We haven't heard back, so I'm closing this as not planned. The report is about OpenCode 1.18.35 (v1), which only gets fixes for critical bugs. Command
@includes being cut off by the Read limits (50 KB, 2000 lines, 2000 characters per line) is a real limitation, but splitting the files still works around it.If you see the same truncation on v2 (
@opencode/cli), please open a new issue with the v2 version and your minimal repro, and we'll look at it there. Thanks again for the detailed report, @stiefenm.AlexSilverLight commentedon Oct 25, 2026
Hi, this is a real problem for those who stay on v1: read truncates large files at 50 KB, and the continuation hint is routinely ignored by models — the agent silently loses up to 90% of the file.
Environment: opencode v1 (1.19.4), Windows, file ~200 KB / 880 lines.
What is confirmed as fixed after the update: offset/limit pagination in 1.19.4 now works correctly (thanks for fixing the behavior from #33650/#53230): a call with offset=640, limit=30 returns lines 640–669 with an honest "of 880" total and a working Use offset=670 to continue hint. The 2000-char per-line truncation also works as documented.
What remains broken in v1:
The 50 KB byte cap is hardcoded (MAX_BYTES = 50 * 1024), is not configurable via tool_output (#29604), and is not mentioned in the tool description the model sees before calling (#30773) — the model believes it received the entire file and reasons from the truncated head.
The only continuation signal is a text line (Output capped at 50 KB. Use offset=136 to continue.) at the end of the output. As noted in this issue, models routinely ignore it: in our session the agent repeatedly called Read without parameters, received the same lines 1–135 each time, and never noticed it was re-reading the same head (a dozen wasted calls on a single file, useless waste of tokens).
After context compaction, earlier Read results are replaced with [Old tool result content cleared] (#22407), and the agent may edit files based on stale memory it can no longer see — the exact "Bug 5" scenario from #30376: read → placeholder → edit from memory.
Why I believe this is critical for v1: the combination of "the model is unaware of the cap + ignores the hint + compaction erases what was read" leads to editing files from incomplete/stale content — that is data-loss territory, not a convenience issue. Minimal non-invasive mitigations that remove most of the risk: (a) mention the 50 KB cap in the read.txt tool description so the model reads large files in ranges up front; (b) expose the truncation flag and continuation offset as a structured field of the result (like v2's TextPage { truncated, next }) instead of a text hint at the tail of the output.
Our workaround is AGENTS.md rules: never read files >50 KB in full, build a structure map via Grep first, fetch ranges via the shell.