feat/builtin-file-tools #17

Merged
sam merged 4 commits from feat/builtin-file-tools into main 2026-09-30 17:42:51 +00:00
Owner
No description provided.
brainless is an MCP-only harness: every callable tool comes from a
connected MCP server, and the deploy connects none that offer file
tools (Paseo's injected workspace MCP exposes workspace management
only), so agents had no way to read, write, or edit a file.

Add an internal/tools package whose tools are registered directly on
the agent and always visible (kept by pruneTools without a load step),
not routed through the lazy MCP catalog.

The package is a single Filesystem type, named after the reference MCP
filesystem server and built by NewFilesystem. Each tool is a public
method returning a tool.Tool and defining its own description, and it
calls the private method that does the work:

- Read(path, head?, tail?) - 1-indexed line bounds; reading stops at
  tail, so a bounded read never loads the whole file.
- Create(path, content) - create or overwrite; refuses git-tracked
  files, and is registered only when git is present on the host. New
  files are 0600.
- Edit(path, oldText, newText, count?) - count mirrors strings.Replace
  (negative replaces all, 0 or 1 requires a unique match); applied
  line by line as the file streams past.
- Insert(path, line, text) - 1-indexed insert-before-line.

Tools() assembles the registered set. Dir is the session working
directory, shared rather than abstracted: the harness holds one and
records it in NewSession, and hands the same value to NewFilesystem, so
the harness (listing sessions) and the tools (resolving relative paths)
read one source.

The caller's context is threaded from the ADK handler through every
operation down to the loops, which select on Done; the git check runs
under exec.CommandContext. The file operations stream instead of
loading whole files, and create, edit, and insert write through a
temporary file that is renamed over the original.

Handlers are methods rather than closures so the ADK function-tool
signature stays explicit and the context is not smuggled through an
injected callback. The four tool constructors carry an ireturn
suppression with a comment, like the harness's existing ones: ADK keeps
its concrete function-tool type unexported, so only the interface is
available to return. No other //nolint is used: filepath.Clean at the
file operations keeps gosec quiet, and the git subprocess carries the
repository in its working directory with a constant command line.
refactor(tools): resolve review comments on the built-in file tools
All checks were successful
code-review / Agent review (pull_request) Successful in 9s
29595b9504
Ten local review comments, one per item:

1. Dir moved out of filesystem.go into dir.go: it is the session
   working directory shared with the harness, not part of the file
   tools' implementation.
2. The ADK handlers stay, now one-line adapters with a comment saying
   why they cannot be inlined: ADK requires a handler whose first
   parameter is exactly agent.Context, the operations take a
   context.Context so tests can call them, and Go does not widen
   function parameters, so one function cannot be both. Replacing the
   adapter with a closure instead of a bound method trips
   contextcheck, which skips only bound method values.
3. toolNames removed from internal/harness; the names now come from
   Filesystem.Names(), which applies the same rule as Tools.
4. The multi-line oldText rejection is gone; the edit simply matches
   within a line, and a multi-line oldText reports "not found" like any
   other text that is not there.
5. The count switch is gone: one strings.Replace per line, with the
   per-line budget spent from the count that is left, so replace-all,
   replace-once, and replace-up-to-N all fall out of the same call.
   count 0 is normalised to 1 once, keeping the "unique match" default.
6. editFile did commit - the asymmetry was create hiding its commit in
   a writeFile helper; that helper is inlined into createFile, so all
   three operations now end in the same Commit call.
7. The atomic write moved to atomic_file.go.
8. Commit now syncs the temporary file before the rename: the rename is
   the single visible step, and syncing first means a crash just after
   it cannot leave an empty file in place of the old one.
9. Each type's methods now live in that type's file, and resolve is
   renamed resolvePath.
10. The git support moved to git.go.

Git availability is now recorded once in NewFilesystem instead of being
re-checked per call, which also keeps Tools and Names consistent.

Tests updated for the fileResult results and resolvePath; a test caught
two real regressions during the rewrite: count=-1 was rejected by the
uniqueness check, and multi-line oldText no longer reported a specific
error.
pi-reviewer left a comment

Review of feat/builtin-file-tools (branch tip 29595b9, base main 92a6dda).

Verified against the repo's own toolchain in a detached worktree at the head commit: go build ./..., go vet ./internal/tools/... ./internal/harness/..., and go test (plain and via the baked-in race-instrumented racedetector test) all pass. I also generated the ADK input schemas with jsonschema.For[...] and confirmed the jsonschema: descriptions survive and omitzero correctly marks head/tail/count as optional.

Overall the design is sound and well-tested: the Filesystem/Dir/atomicFile split is clean, the streaming edit/insert logic is correct (count normalization, per-line matching, atomic rename, mode preservation, context cancellation), Names()/Tools() can't disagree, and the pruning test in mcp_test.go covers the always-visible contract. No security, data-race, or build-blocking defects found.

One IMPORTANT functional gap and two minor suggestions below. The IMPORTANT one (create's tracked guard blocks re-creating a deleted tracked file, with no working alternative) is a real trap in the new feature, so I'm requesting changes.

Review of `feat/builtin-file-tools` (branch tip 29595b9, base main 92a6dda). Verified against the repo's own toolchain in a detached worktree at the head commit: `go build ./...`, `go vet ./internal/tools/... ./internal/harness/...`, and `go test` (plain and via the baked-in race-instrumented `racedetector test`) all pass. I also generated the ADK input schemas with `jsonschema.For[...]` and confirmed the `jsonschema:` descriptions survive and `omitzero` correctly marks `head`/`tail`/`count` as optional. Overall the design is sound and well-tested: the `Filesystem`/`Dir`/`atomicFile` split is clean, the streaming edit/insert logic is correct (count normalization, per-line matching, atomic rename, mode preservation, context cancellation), `Names()`/`Tools()` can't disagree, and the pruning test in `mcp_test.go` covers the always-visible contract. No security, data-race, or build-blocking defects found. One IMPORTANT functional gap and two minor suggestions below. The IMPORTANT one (create's tracked guard blocks re-creating a deleted tracked file, with no working alternative) is a real trap in the new feature, so I'm requesting changes.
@ -0,0 +265,4 @@
return fileResult{}, fmt.Errorf("create %s: %w", resolved, err)
}
if tracked {
Collaborator

🟠 IMPORTANT — the tracked-file guard also refuses a file deleted from the working tree, and no other tool can recreate it. git ls-files lists a deleted-but-unstaged tracked file: after rm tracked.txt, git ls-files -z --full-name still prints tracked.txt. So create returns 'file is tracked by git; use edit for tracked files', but edit/insert then fail because os.Open cannot find the missing file (reproduced: create→tracked error, edit→'no such file or directory'). A deleted tracked file is unrecoverable via the built-in tools, and the create message points the agent at an operation that also errors. Fix: os.Stat the resolved path first and skip the guard when it does not exist — a path that isn't on disk cannot be overwritten, so re-creating it is exactly what create should do.

🟠 IMPORTANT — the tracked-file guard also refuses a file deleted from the working tree, and no other tool can recreate it. `git ls-files` lists a deleted-but-unstaged tracked file: after `rm tracked.txt`, `git ls-files -z --full-name` still prints `tracked.txt`. So `create` returns 'file is tracked by git; use edit for tracked files', but `edit`/`insert` then fail because `os.Open` cannot find the missing file (reproduced: create→tracked error, edit→'no such file or directory'). A deleted tracked file is unrecoverable via the built-in tools, and the create message points the agent at an operation that also errors. Fix: `os.Stat` the resolved path first and skip the guard when it does not exist — a path that isn't on disk cannot be overwritten, so re-creating it is exactly what `create` should do.
@ -0,0 +468,4 @@
lastEndedNewline = strings.HasSuffix(raw, "\n")
if lineNo == line {
if _, werr := io.WriteString(dst, text+"\n"); werr != nil {
Collaborator

🟡 SUGGESTION — the inserted text always gets a newline appended (io.WriteString(dst, text+"\n")), but the text jsonschema explicitly allows 'one or more lines'. A model passing text ending in a newline gets a stray blank line: inserting line\n before line 2 of l1\n l2\n yields l1\n line\n\n l2\n (verified by a scratch test). Fix: trim one trailing newline first, e.g. text = strings.TrimSuffix(text, "\n").

🟡 SUGGESTION — the inserted text always gets a newline appended (`io.WriteString(dst, text+"\n")`), but the `text` jsonschema explicitly allows 'one or more lines'. A model passing text ending in a newline gets a stray blank line: inserting `line\n` before line 2 of `l1\n l2\n` yields `l1\n line\n\n l2\n` (verified by a scratch test). Fix: trim one trailing newline first, e.g. `text = strings.TrimSuffix(text, "\n")`.
@ -0,0 +37,4 @@
return false, fmt.Errorf("git root: %w", err)
}
cmd := exec.CommandContext(ctx, "git", "ls-files", "-z", "--full-name")
Collaborator

🟡 SUGGESTION — git ls-files is run with no pathspec on every create, so it lists the entire index and matches the path in-process (verified: it emits every tracked file). On a large repository each write is O(index size). Scope the scan to the target by passing it as a pathspec with --literal-pathspecs (so a caller-supplied path is never treated as a glob): git ls-files -z --full-name --literal-pathspecs -- <rel>. Git exits as soon as the entry is matched/absent.

🟡 SUGGESTION — `git ls-files` is run with no pathspec on every `create`, so it lists the entire index and matches the path in-process (verified: it emits every tracked file). On a large repository each write is O(index size). Scope the scan to the target by passing it as a pathspec with `--literal-pathspecs` (so a caller-supplied path is never treated as a glob): `git ls-files -z --full-name --literal-pathspecs -- <rel>`. Git exits as soon as the entry is matched/absent.
Three findings from the pull request review (review id 30):

- create refused a tracked file that is deleted from the working tree,
  and nothing could recreate it: git still lists it in the index, so the
  guard fired, while edit and insert both fail because they need the file
  to read. create now checks whether anything is on disk first and only
  consults git for a path that exists, since a path that is not there
  cannot be overwritten. TestCreateRecreatesDeletedTrackedFile covers it.
- insert appended a line separator to text that already ended in one, so
  passing "line\n" inserted a blank line as well. The trailing newline is
  now trimmed before the insertion, which keeps the documented "one or
  more lines" contract. Covered in TestInsertFileRanges.
- the git lookup listed the whole index on every create. git ls-files
  lists the entries under the directory it runs in, so it now runs in the
  target's own directory, which scopes the scan without putting a
  caller-supplied name on the command line. The pathspec form cannot be
  used: passing the name as an argument trips gosec G204, and git 2.39
  rejects --literal-pathspecs after the subcommand. Covered by
  TestCreateRefusesNestedTrackedFile.

README updated for the create guard's new wording.
Collaborator

Resolved all three findings in cf72f31 (pushed; branch tip is now cf72f31 on top of 29595b9). go build, go vet, go test (plain and racedetector test), and golangci-lint run --fix=false are all clean.

🟠 IMPORTANT — deleted tracked file (comment 624): fixed. createFile now checks whether the resolved path is on disk first, via a new fileExists helper, and only consults git when it is. A path that is not there cannot be overwritten, so a tracked file deleted from the working tree is exactly what create should re-create. New test TestCreateRecreatesDeletedTrackedFile: it asserts edit still fails on the deleted file (the reviewer's second half), then that create restores it.

🟡 SUGGESTION — insert trailing newline (comment 625): fixed. insertFile trims one trailing newline from text before inserting, since the insertion adds the separator itself. "line\n" before line 2 of l1\nl2\n now yields l1\nline\nl2\n. Covered in TestInsertFileRanges, deliberately placed outside the parallel subtests because it shares one fixture.

🟡 SUGGESTION — whole-index git scan (comment 626): fixed, but not via the pathspec. The scan is now directory-scoped. Two obstacles to the pathspec form as proposed:

  • --literal-pathspecs is a global git option; after ls-files git 2.39 answers error: unknown option, exit 129 (verified). The working form is git --literal-pathspecs ls-files ....
  • Passing the name as an argument trips gosec G204 (Subprocess launched with variable), which is enabled in the shared lint config and cannot be suppressed under this repo's no-//nolint rule. G204's rule flags any subprocess argument that is not a constant literal, so a pathspec — literal or not — is not available here.

So tracked now runs the constant command line git ls-files -z with cmd.Dir set to the target's own directory, and compares against filepath.Base(path). git ls-files only lists entries under the directory it runs in (verified: from sub/ it prints inner.txt, and --full-name only changes the prefix, not the set), so the scan is scoped to that directory instead of the whole index. It does not exit as early as a pathspec would: for a target sitting at the repository root the listing is the repository's root subtree, not one entry. If you would rather have the exact pathspec, the unblocking change is adding G204 to the gosec exclusions (or google.golang.org/adk/v2/tool.Tool to ireturn.allow) in the shared go-linters config. New test TestCreateRefusesNestedTrackedFile covers the nested case, since the prefix-free comparison is what makes directory scoping work.

Also updated the README's create bullet to say the guard refuses an existing tracked file, and why a deleted one is re-creatable.

Resolved all three findings in `cf72f31` (pushed; branch tip is now `cf72f31` on top of `29595b9`). `go build`, `go vet`, `go test` (plain and `racedetector test`), and `golangci-lint run --fix=false` are all clean. **🟠 IMPORTANT — deleted tracked file (comment 624): fixed.** `createFile` now checks whether the resolved path is on disk first, via a new `fileExists` helper, and only consults git when it is. A path that is not there cannot be overwritten, so a tracked file deleted from the working tree is exactly what `create` should re-create. New test `TestCreateRecreatesDeletedTrackedFile`: it asserts `edit` still fails on the deleted file (the reviewer's second half), then that `create` restores it. **🟡 SUGGESTION — insert trailing newline (comment 625): fixed.** `insertFile` trims one trailing newline from `text` before inserting, since the insertion adds the separator itself. `"line\n"` before line 2 of `l1\nl2\n` now yields `l1\nline\nl2\n`. Covered in `TestInsertFileRanges`, deliberately placed outside the parallel subtests because it shares one fixture. **🟡 SUGGESTION — whole-index git scan (comment 626): fixed, but not via the pathspec.** The scan is now directory-scoped. Two obstacles to the pathspec form as proposed: - `--literal-pathspecs` is a *global* git option; after `ls-files` git 2.39 answers `error: unknown option`, exit 129 (verified). The working form is `git --literal-pathspecs ls-files ...`. - Passing the name as an argument trips `gosec` G204 (`Subprocess launched with variable`), which is enabled in the shared lint config and cannot be suppressed under this repo's no-`//nolint` rule. G204's rule flags any subprocess argument that is not a constant literal, so a pathspec — literal or not — is not available here. So `tracked` now runs the constant command line `git ls-files -z` with `cmd.Dir` set to the target's own directory, and compares against `filepath.Base(path)`. `git ls-files` only lists entries under the directory it runs in (verified: from `sub/` it prints `inner.txt`, and `--full-name` only changes the prefix, not the set), so the scan is scoped to that directory instead of the whole index. It does not exit as early as a pathspec would: for a target sitting at the repository root the listing is the repository's root subtree, not one entry. If you would rather have the exact pathspec, the unblocking change is adding `G204` to the gosec exclusions (or `google.golang.org/adk/v2/tool.Tool` to `ireturn.allow`) in the shared go-linters config. New test `TestCreateRefusesNestedTrackedFile` covers the nested case, since the prefix-free comparison is what makes directory scoping work. Also updated the README's `create` bullet to say the guard refuses an *existing* tracked file, and why a deleted one is re-creatable.
Follow-up to the PR #17 review: with the argument's safety established,
git can be handed the path instead of listing the whole index and
matching in process.

The path reaches the subprocess in a form that cannot change what the
call does: exec passes an argv with no shell, so nothing is word-split or
expanded; the name follows --, so a file named --help is looked up as a
path; and --literal-pathspecs (which must precede the subcommand)
switches off globbing and pathspec magic, so a name like
:(exclude)other.txt is a file name rather than an instruction - without
it that argument lists every tracked file except one, which is exactly
the injection the flag prevents. The value itself comes from the path
stdlib only: resolvePath joins and cleans, and filepath.Rel plus
filepath.Clean produce the pathspec, so the caller's string never reaches
the command line as given. A caller can choose which path is looked up,
and nothing else.

resolvePath now also rejects a NUL byte in a path instead of passing it
on: the path would be cut short at the syscall boundary, so the file the
guard inspects and the file the write opens could stop agreeing.

git exits as soon as the pathspec is matched or ruled out, so a create no
longer walks the index. The existing nested and root-level tests cover
both shapes, and the NUL rejection is covered in TestResolvePath.
Collaborator

Follow-up to finding 3 (whole-index scan), now in ec6cfd9 — the pathspec form is in after all.

My earlier reply said the pathspec was unavailable because gosec G204 rejects a non-constant argument. That is true of the linter, not of the risk: the suppression is acceptable here because the value cannot change what the call does, only which path is looked up. Verified, concretely:

  • No shell. exec.CommandContext passes an argv, so nothing is word-split and no metacharacter is expanded.
  • -- ends the options, so a file named --help is looked up as a path rather than parsed as a flag (checked).
  • --literal-pathspecs disables globbing and pathspec magic. A name like :(exclude)other.txt becomes a file name: with the flag, git ls-files -z --full-name -- :(exclude)tracked.txt prints exactly that path; without it the same argument prints every tracked file except one. That is the injection the flag closes, and it has to precede the subcommand (git 2.39: error: unknown option, exit 129 after ls-files).
  • The value is stdlib-built. resolvePath joins and cleans, then filepath.Rel + filepath.Clean produce the pathspec, so the caller's string never reaches the command line as given.

So the call is now git --literal-pathspecs ls-files -z --full-name -- <clean rel path> with cmd.Dir at the repository root, plus a //nolint:gosec whose comment states the reason. git exits as soon as the pathspec is matched or ruled out, which is the O(index) walk gone.

One related hardening came out of the same reasoning: resolvePath now rejects a NUL byte in a path instead of passing it on. A NUL truncates the path at the syscall boundary, so the file the tracked guard inspects and the file the write opens could otherwise stop agreeing — a path bypass with the guard on the wrong file. Covered in TestResolvePath.

go build, go vet, go test (plain and racedetector test) and golangci-lint run --fix=false are clean at ec6cfd9.

Follow-up to finding 3 (whole-index scan), now in `ec6cfd9` — the pathspec form is in after all. My earlier reply said the pathspec was unavailable because gosec G204 rejects a non-constant argument. That is true of the linter, not of the risk: the suppression is acceptable here because the value cannot change *what the call does*, only *which path* is looked up. Verified, concretely: - **No shell.** `exec.CommandContext` passes an argv, so nothing is word-split and no metacharacter is expanded. - **`--` ends the options**, so a file named `--help` is looked up as a path rather than parsed as a flag (checked). - **`--literal-pathspecs` disables globbing *and* pathspec magic.** A name like `:(exclude)other.txt` becomes a file name: with the flag, `git ls-files -z --full-name -- :(exclude)tracked.txt` prints exactly that path; without it the same argument prints every tracked file *except* one. That is the injection the flag closes, and it has to precede the subcommand (git 2.39: `error: unknown option`, exit 129 after `ls-files`). - **The value is stdlib-built.** `resolvePath` joins and cleans, then `filepath.Rel` + `filepath.Clean` produce the pathspec, so the caller's string never reaches the command line as given. So the call is now `git --literal-pathspecs ls-files -z --full-name -- <clean rel path>` with `cmd.Dir` at the repository root, plus a `//nolint:gosec` whose comment states the reason. git exits as soon as the pathspec is matched or ruled out, which is the O(index) walk gone. One related hardening came out of the same reasoning: `resolvePath` now rejects a `NUL` byte in a path instead of passing it on. A NUL truncates the path at the syscall boundary, so the file the tracked guard inspects and the file the write opens could otherwise stop agreeing — a path bypass with the guard on the wrong file. Covered in `TestResolvePath`. `go build`, `go vet`, `go test` (plain and `racedetector test`) and `golangci-lint run --fix=false` are clean at `ec6cfd9`.
sam merged commit 127032d9c1 into main 2026-09-30 17:42:51 +00:00
sam deleted branch feat/builtin-file-tools 2026-09-30 17:42:51 +00:00
Sign in to join this conversation.
No reviewers
No labels
code-review
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
sam/brainless!17
No description provided.