read_file tool can't authorize edits when file is larger than tool's default limit cap

[btipling]

Problem

The read_file tool has a read-before-write gate: before str_replace or write_file (overwrite) can modify a file, the agent must have performed a "successful full read" — offset 1 covering every line of the returned content, not clipped by limit or maxBytes.

But the tool's docs say the default limit is 1000 lines. For files larger than 1000 lines, this creates a catch-22:

1. Read with default limit (1000): The read is truncated — tool says you read 1000 of 1085 lines → can't edit.
2. Read with a high explicit limit, e.g. limit: 2000: The tool caps at 1000 anyway (server-capped) → still can't edit.
3. Read in chunks with offset: Each chunk is a separate read_file call. Each is a truncated view of the file. The tool says "read is not enough" because no single call covered every line.

The agent is stuck in a loop:

• It knows it needs to read the full file to edit it.
• It tries offset=1, reads 1000 lines (truncated).
• It tries offset=1001, reads 85 lines (not covering line 1).
• Neither call authorizes the edit — the gate requires a single call that covers the whole file.
• It tries limit=2000, server caps at 1000 → truncated again.
• It tries exec with sed to avoid the read gate entirely (workaround).

Affected files

Any source file >1000 lines in the repo. Example: lib/agent/tools.ts is 1085 lines.

Proposed solutions

1. Allow chunked reads to collectively satisfy the gate. If the agent reads offset=1,limit=1000 then offset=1001,limit=1000 and together they cover every line, that should authorize the edit.
2. Raise or remove the server-side limit cap. Let limit actually go higher when explicitly requested.
3. Add a block-size parameter to read_file that lets the agent paginate and the tool tracks coverage across calls.
4. Document the escape hatch: When the file is too large, the tool should tell the agent what to do instead of looping.

Observed behavior

read_file offset=1, limit=1000 → "truncated: 1000 of 1085 lines read" → can't edit
read_file offset=1001, limit=1000 → "85 lines read (starting at line 1001)" → can't edit
read_file limit=2000 → server-capped to 1000 → "truncated" → can't edit

The agent eventually falls back to exec with sed as a workaround, which defeats the purpose of the read gate.

[btipling]

Fixed by #730 (#729).

[btipling]

#730 is not the fix. It merged without a re-review after a BLOCK, then was reverted on main (d876e8d).

The last BLOCK (grant on a clipped 1000/1400 window → write_file can drop the unread tail) is not on main. The catch-22 here is: default limit=1000 still denies, and the tool still does not say use limit>=N. Explicit limit>=totalLines already grants (never server-capped).

Do not re-land plan #729’s “grant when the daemon has the bytes.” Remaining work is #733 — keep the EOF grant, add the hint.

[btipling]

Closed: shipped in PR #745 (merge SHA d963c6e). The limit>=N escape has a clipped read at offset 1 reach the EOF grant.