`file_read` always read from position 0; `max_chars` (ADR-2030 D-3) only
bounded where the returned content stopped, so once a large file was
truncated there was no way to retrieve the next chunk short of falling
back to the `shell` tool (`tail -c +N`, `sed -n`, `dd skip=...`) — the
same class of awkward, error-prone detour ADR-2030 D-4 already eliminated
for file paths mistaken for shell commands.
Adds an optional `offset` character-position argument (default 0,
byte-for-byte identical output when omitted) to both the tool schema
(`llm_tools._BUILTIN_TOOL_SCHEMAS["file_read"]`) and the implementation
(`ToolAgent._file_read_tool`). Combined with `max_chars` it returns the
window `[offset, offset + max_chars)`, and the `[FILE_READ_SUCCESS]`
header now signals continuation: `MORE_CONTENT_AT_OFFSET: N` when more
content remains (N is the exact next offset, so callers never compute
`offset + max_chars` themselves), or `NO_MORE_CONTENT_AT_OFFSET: N` when
the requested offset is at or beyond end-of-file — a success response
with empty content, not an error, since that is the expected terminal
state of a correctly-paginating caller. Negative or non-integer offsets
raise `ExecutionError`, mirroring the existing `max_chars` validation
pattern.
See docs/adr/ADR-2033-file-read-offset-pagination.md for the full set of
design decisions, including why directory-listing pagination and
byte-level seeking are deferred to a future issue.
ISSUES CLOSED: #83
CoreRasurae