agentlane/ docs
On this page

read

read_tool() exposes a read tool for UTF-8 text files.

Parameters:

  1. path: str
  2. offset: int | None = None
  3. limit: int | None = None

At construction, pass reader= to read from application storage. The native schema, text limits, and result format stay the same. The reader receives paths in its logical namespace; cwd defaults to the storage root. Mounted readers accept rooted virtual paths and resolve relative paths from cwd. Plain injected readers retain relative POSIX paths. Omit reader for local files and the process cwd captured at construction. See File I/O adapters for the stream contract and example.

Permissions

For local files, read resolves path through ToolPathResolver. An injected reader uses its normalized logical paths. Both modes check ToolOperation.READ_FILE before opening the file. A denied request returns:

permission denied: read is not allowed for `/workspace/private.txt`

The bundled side-effect approval policy does not request approval for reads. A custom policy may still return require_approval, in which case the tool uses the configured approval_callback=.

approval required: read requires application approval for `/workspace/notes.txt` before execution

Example tool result:

alpha
bravo
charlie

When more lines remain after a caller limit or global line cap, the result adds a continuation note:

alpha
bravo

[Showing lines 1-2. Use offset=3 to continue.]

When the byte cap is reached, the result reports:

[Showing lines 1-128 (51200 byte limit). Use offset=129 to continue.]

If the first requested line exceeds the byte cap by itself, the result reports:

[Line 1 is 51201 bytes, exceeds 51200 byte limit. Use bash to inspect it.]

The tool returns clear text errors for directories, missing files, likely binary files, invalid offsets, invalid limits, and unreadable paths. A file is flagged as binary when a NUL byte appears in its first 4096 bytes (not a full-file scan). Invalid UTF-8 byte sequences are decoded with replacement characters so the model can still use the surrounding text.