File and search tools

Keep paths inside the workspace

The agent works in one folder, the workspace, like a workshop with a fence around it. Every tool must refuse paths outside it, whatever the model writes: ../../etc/passwd, /home/me/.ssh/id_rsa, or a symlink that points out. A symlink is a file that's really a shortcut to somewhere else, so it can lead outside the fence while looking like it's inside.

The reliable check:

1. Join the path to the workspace root.
2. Resolve it: Path.resolve() turns .. and symlinks into the real absolute path.
3. Check the result is still inside the root, with is_relative_to(root).

Checking the raw string for .. isn't enough: there are too many ways to spell the same escape.

In plain words: work out where a path really leads, and only then decide whether to allow it.

from pathlib import Path

root = Path("/work/project").resolve()

def safe(path):
    full = (root / path).resolve()
    return full.is_relative_to(root), str(full)

for p in ["src/app.py", "src/../notes.txt", "../../etc/passwd", "/etc/passwd", "src/../../secrets.txt"]:
    print(p, "->", safe(p))

Read before you write

A painter looks at a wall before painting over it. Two rules stop the agent clobbering work:

• Read before overwrite. The harness remembers which files the agent has read. Writing or editing an existing file that wasn't read is refused. That stops the agent replacing a file it has never seen.
• No stale edits. The harness also remembers the content it read. If the file has changed since, say because the user edited it, the edit is refused with "read it again". The agent then works from the current text.

import hashlib

files = {"app.py": "print('v1')"}
seen = {}

def fingerprint(text):
    return hashlib.sha256(text.encode()).hexdigest()[:8]

def read(path):
    seen[path] = fingerprint(files[path])
    return files[path]

def write(path, text):
    if path in files and seen.get(path) != fingerprint(files[path]):
        return "refused: read the file first, it has changed"
    files[path] = text
    seen[path] = fingerprint(text)
    return "written"

print(write("app.py", "print('v2')"))      # never read it
read("app.py")
files["app.py"] = "print('edited by a person')"
print(write("app.py", "print('v2')"))      # changed since it was read
read("app.py")
print(write("app.py", "print('v2')"))

Output a model can use

Read shows line numbers, like page numbers in a book, so the model and the user can talk about "line 42". Grep shows path:line: text. Both cap their output and say when they've cut it, as you built in the registry lesson.

Checks that look right and aren't

Searching for .. doesn't protect a path. It blocks notes/../plan.md, which is harmless, and it misses /etc/passwd, which contains no dots at all. It misses a symlink as well, which looks like an ordinary file name and points anywhere. Only resolving the path, and then comparing the result with your root, gives a reliable answer.

Replacing the first match isn't a safe guess. Say the model asks to replace total = 0, and the file has that line in three functions. If your tool quietly edits the first, the change lands in the wrong place, and the tests may not notice. So fail when there's more than one match, and tell the model how many there were. It can then include more surrounding lines to pin down the right one.

Blind overwrites lose work. A model that never read a file doesn't know what's in it, and it can overwrite someone's changes with its guess. Requiring a read first costs one tool call, and it prevents a whole class of accidents.

Line numbers and caps matter too. A file returned with no line numbers makes it hard for the model to refer to any spot. A file returned with no cap can fill the context in one call. Number the lines, cap the size, and say what you cut.