# Agent guidance

## Tool selection

Use `read_full` when the calling agent must consume a complete text file in its
own context. Pass only `path`, absolute or relative to the session directory.
Call it directly rather than first paging through `read`. A summary, index, or
subagent read does not satisfy an instruction to load the complete file.

Use `read` for images, focused excerpts, and hashline edit prerequisites. Use
search or sandboxed processing when only selected facts from a large file are
needed. `read_full` has no fixed size cap. It refuses content that cannot fit
the active model's safe remaining context budget.

The installed extension supplies these rules through its tool description,
`promptSnippet`, and `promptGuidelines` in `index.ts`. This file documents the
rules for repository work; do not rely on Pi loading it from an installed
package. Keep every example and instruction generic, without user-specific
project paths.

## Implementation contract

- Register `read_full`, never override `read`.
- When the context-fit safeguard accepts the file, return one text block with
  the complete UTF-8 text, including its BOM and original newlines. An empty
  file returns an empty text block.
- Do not add headers, hashes, line numbers, summaries, or clipping.
- Keep terminal rendering separate from model content. Never duplicate file text
  in result details or load it automatically at startup.
- Refuse a file whose estimated `characters / 4` token cost exceeds the active
  model's remaining context after Pi's default response reserve. If current
  usage is unknown, compare against the model's window minus that reserve. If
  model context metadata is unavailable, preserve the full-read behavior.
- Before reading file contents, use file size only for a conservative
  impossibility check. Valid UTF-8 can need as few as one estimated token per 12
  bytes; do not reject a file early with a less conservative conversion.
- Accept regular UTF-8 files without NUL bytes. Throw on read errors or
  cancellation; never report partial content as success.
- Keep permission hooks and tool allowlists in force. A new tool name is not
  authorization to bypass them.
- Use Node's file API and Pi's peer packages. Do not add subprocess reads,
  indexing, hash calculations, caches, or settings without a concrete need.

## Verification

```sh
npm ci --ignore-scripts
npm run check
npm run verify:tarball
```

Tests use disposable fixtures, not personal files. Preserve coverage for long
lines, many lines, multi-megabyte input, Unicode, newlines, cancellation,
errors, and compact rendering. Update tool metadata and documentation together
when behavior changes.

Use a conventional commit with a body explaining the change and verification.
Stage only intended files. Do not publish or push without the user's request.
See [RELEASING.md](RELEASING.md) for release setup.