# Local Tool and File-Edit Procedure

## File read contract

File reads are source observations. They must return a truthful description of
what the model receives:

```text
path
current content identity
line/range coverage
delivery mode: full body | range | extract | truncated
whether the exact requested text is visible now
```

### Full reads

For a bounded explicit full read, deliver the full selected source body. Do not
replace it with a branch wrapper, evidence pointer, controller directive, or
structural preview.

For an overwhelming source, use an isolated extraction frame when needed. The
extract must be anchored to lines and distinguish:

```text
complete: every declared requirement is grounded
partial: each unresolved requirement has a source-based reason and deterministic
         recovery query
```

A partial extract is advisory. It cannot deny a later parent read, edit, or
verification action.

### Cache/reuse

Reuse a read only when all are true:

1. the source version is current;
2. the request range is covered;
3. the relevant exact body is model-visible; and
4. the cached representation is complete for the requested use.

Otherwise execute the requested read or deliver actual canonical source. Never
return an error/rejection merely because an identity cache was hit.

## File edit contract

Use `file_edit` for a unique exact replacement. Use `batch_edit` for an atomic
set of replacements. Use a range patch when the edit is naturally line/range
based. Use whole-file write only for a deliberate full replacement/new file.

### Exact edit behavior

Required edit evidence is the actual target text. A current hash is valuable
and should be attached automatically when available, but it should not be a
ceremonial prerequisite that prevents a model from reaching the real edit tool.

The tool should report natural outcomes:

| Tool result | Meaning |
| --- | --- |
| Unique old text matched | Edit can apply |
| Old text absent | Source/premise changed; inspect target |
| Old text ambiguous | Narrow target or use explicit replace-all/range patch |
| Hash mismatch | File changed; obtain current identity/text |
| Batch validation failed | No mutation occurred; inspect exact failing member |

Do not transform these into a branch-admission, todo-topology, stale-loop, or
verifier-lock error before the tool gets a chance to return its real result.

## Shell contract

Use shell for commands, build/test verification, project tooling, and
diagnostics when it is the right mechanism. Do not force shell merely because
the normal read path hid source body. Do not prohibit shell generically when it
is the valid verifier or diagnostic.

Classify capped/truncated output as partial success with provenance. Narrow the
next command deterministically: a target file, symbol, error range, command
tail, or known discriminating pattern.

## Tool failure contract

Every tool failure must preserve:

```text
tool
arguments/target
real error/result
whether mutation occurred
current relevant source identity
```

Failure evidence is not permission to repeat indefinitely. It is input to a
changed hypothesis, changed arguments, changed filesystem state, or an honest
blocked/incomplete report.