Decisions

Why file's calls are Claude Code's, why it keeps to [files] before its sandbox does, what it narrows per call, and how it works through a files bridge and in a bucket.

Why are its calls Claude Code's?

A tool is only as good as the model calling it, and current models are trained on Claude Code's file tools. So file's calls take their names and arguments: read{file_path, offset, limit} as Read, write{file_path, content} as Write, edit{file_path, old_string, new_string, replace_all} as Edit, and glob{pattern, path} and grep{pattern, path, glob} as Glob and Grep.

Glob and Grep

Finding files and finding lines are two calls, as they are there, each keeping the same limits, skipping and time. The sandbox, the grants and the receipts fit around that shape. Grep's output modes and options beyond glob are left out, since a line's path and number serve each.

Why does file keep to [files] before its sandbox does?

The sandbox decides: file's reads Home and the agent's instructions, skills and conversations, writes only [files] write, reaches no network and runs only lnk-file-tool. The tool checks the same folders first so a refused write says in words where the agent may write, rather than a system's error. It never follows a link, writes a file whole beside it and moves it in place, and reads at most 24 KB a call, whole lines, so a harness keeps the whole answer.

Why does each conversation read only its own chat?

A conversation's transcript holds what its people said. A webhook, a member of a shared chat, or a teammate given the agent's ear must not read the owner's other conversations through file. The sandbox serves a whole session, so it reads every conversation. The tool's server therefore narrows chats/ per call, from the conversation and standing the harness names, and refuses any call that names neither. Memory remains the owner's way to search across conversations.

Why does a write refuse a file changed since its read?

A person editing a file while the agent works, or two conversations writing one file, would otherwise lose a change silently. The server keeps the SHA-256 of what each file held when the session last read or wrote it, and the next write or edit names it: an edit whose text is still there would otherwise land on a file whose other lines changed unseen. The sandbox refuses the call when the file differs, as the files bridge refuses a stale version. The version never reaches the model. A file never read is written, so a new file needs no read first.

Why do glob and grep keep to .gitignore?

What a .gitignore names is usually built or fetched, like node_modules/ or target/. Walking it would spend a search's budget of files on what the agent never edits and bury what it would. Each keeps to the same rules as git, deeper files over shallower ones, and counts what it passed over, so the model knows to name a folder when it wants one that is ignored.

Why can file work through a files bridge?

So an agent whose files folder isn't on its machine (a bucket's folder, on a machine that keeps nothing of it) still reads and writes it, with the same tools and limits. The bridge (link_store_contract::files) runs outside the sandbox, holds the folder's credential and key, and takes a call only from the agent bound, proved with its key (link_sandbox_bridge); a write of a file read is made only from the version read, so two writers never lose one silently. The other way, the folder mounted into the sandbox, would put its credential where the agent is.

Why rclone's crypt format for a folder in a bucket?

Because it's published and tested, lnk storage already writes it, and a folder stays readable by standard tools given its key. Each object is encrypted on its own, its name too, so single objects are read and written with the bucket's version conditions. A format of Link's own would buy nothing and be Link's alone to get right.