co-mono/packages/coding-agent/docs/truncation.md

Tool Output Truncation

Limits

• Line limit: 2000 lines
• Byte limit: 30KB
• Grep line limit: 500 chars per match line

Whichever limit is hit first wins. Never return partial lines (except bash edge case).

---

read

Head truncation (first N lines). Has offset/limit params for continuation.

Scenarios

First line > 30KB:

LLM sees:
[Line 1 is 50KB, exceeds 30KB limit. Use bash to read: head -c 30000 path/to/file]

Details:
{ truncation: { truncated: true, truncatedBy: "bytes", outputLines: 0, ... } }

Hit line limit (2000 lines, < 30KB):

LLM sees:
[lines 1-2000 content]

[Showing lines 1-2000 of 5000. Use offset=2001 to continue]

Details:
{ truncation: { truncated: true, truncatedBy: "lines", outputLines: 2000, totalLines: 5000 } }

Hit byte limit (< 2000 lines, 30KB):

LLM sees:
[lines 1-500 content]

[Showing lines 1-500 of 5000 (30KB limit). Use offset=501 to continue]

Details:
{ truncation: { truncated: true, truncatedBy: "bytes", outputLines: 500, totalLines: 5000 } }

With offset, hit line limit (e.g., offset=1000):

LLM sees:
[lines 1000-2999 content]

[Showing lines 1000-2999 of 5000. Use offset=3000 to continue]

Details:
{ truncation: { truncatedBy: "lines", ... } }

With offset, hit byte limit (e.g., offset=1000, 30KB after 500 lines):

LLM sees:
[lines 1000-1499 content]

[Showing lines 1000-1499 of 5000 (30KB limit). Use offset=1500 to continue]

Details:
{ truncation: { truncatedBy: "bytes", outputLines: 500, ... } }

With offset, first line at offset > 30KB (e.g., offset=1000, line 1000 is 50KB):

LLM sees:
[Line 1000 is 50KB, exceeds 30KB limit. Use bash: sed -n '1000p' file | head -c 30000]

Details:
{ truncation: { truncated: true, truncatedBy: "bytes", outputLines: 0 } }

---

bash

Tail truncation (last N lines). Writes full output to temp file if truncated.

Scenarios

Hit line limit (2000 lines):

LLM sees:
[lines 48001-50000 content]

[Showing lines 48001-50000 of 50000. Full output: /tmp/pi-bash-xxx.log]

Details:
{ truncation: { truncated: true, truncatedBy: "lines", outputLines: 2000, totalLines: 50000 }, fullOutputPath: "/tmp/..." }

Hit byte limit (< 2000 lines, 30KB):

LLM sees:
[lines 49501-50000 content]

[Showing lines 49501-50000 of 50000 (30KB limit). Full output: /tmp/pi-bash-xxx.log]

Details:
{ truncation: { truncatedBy: "bytes", ... }, fullOutputPath: "/tmp/..." }

Last line alone > 30KB (edge case, partial OK here):

LLM sees:
[last 30KB of final line]

[Showing last 30KB of line 50000 (line is 100KB). Full output: /tmp/pi-bash-xxx.log]

Details:
{ truncation: { truncatedBy: "bytes", lastLinePartial: true }, fullOutputPath: "/tmp/..." }

---

grep

Head truncation. Primary limit: 100 matches. Each match line truncated to 500 chars.

Scenarios

Hit match limit (100 matches):

LLM sees:
file.ts:10: matching content here...
file.ts:25: another match...
...

[100 matches limit reached. Use limit=200 for more, or refine pattern]

Details:
{ matchLimitReached: 100 }

Hit byte limit (< 100 matches, 30KB):

LLM sees:
[matches that fit in 30KB]

[30KB limit reached (50 of 100+ matches shown)]

Details:
{ truncation: { truncatedBy: "bytes", ... } }

Match lines truncated (any line > 500 chars):

LLM sees:
file.ts:10: very long matching content that exceeds 500 chars gets cut off here... [truncated]
file.ts:25: normal match

[Some lines truncated to 500 chars. Use read tool to see full lines]

Details:
{ linesTruncated: true }

---

find

Head truncation. Primary limit: 1000 results. File paths only (never > 30KB each).

Scenarios

Hit result limit (1000 results):

LLM sees:
src/file1.ts
src/file2.ts
[998 more paths]

[1000 results limit reached. Use limit=2000 for more, or refine pattern]

Details:
{ resultLimitReached: 1000 }

Hit byte limit (unlikely, < 1000 results, 30KB):

LLM sees:
[paths that fit]

[30KB limit reached]

Details:
{ truncation: { truncatedBy: "bytes", ... } }

---

ls

Head truncation. Primary limit: 500 entries. Entry names only (never > 30KB each).

Scenarios

Hit entry limit (500 entries):

LLM sees:
.gitignore
README.md
src/
[497 more entries]

[500 entries limit reached. Use limit=1000 for more]

Details:
{ entryLimitReached: 500 }

Hit byte limit (unlikely):

LLM sees:
[entries that fit]

[30KB limit reached]

Details:
{ truncation: { truncatedBy: "bytes", ... } }

---

TUI Display

tool-execution.ts reads details.truncation and related fields to display truncation notices in warning color. The LLM text content and TUI display show the same information.