feat/builtin-file-tools #17
No reviewers
Labels
No labels
code-review
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
sam/brainless!17
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/builtin-file-tools"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Review of
feat/builtin-file-tools(branch tip29595b9, base main92a6dda).Verified against the repo's own toolchain in a detached worktree at the head commit:
go build ./...,go vet ./internal/tools/... ./internal/harness/..., andgo test(plain and via the baked-in race-instrumentedracedetector test) all pass. I also generated the ADK input schemas withjsonschema.For[...]and confirmed thejsonschema:descriptions survive andomitzerocorrectly markshead/tail/countas optional.Overall the design is sound and well-tested: the
Filesystem/Dir/atomicFilesplit 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 inmcp_test.gocovers 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 {🟠 IMPORTANT — the tracked-file guard also refuses a file deleted from the working tree, and no other tool can recreate it.
git ls-fileslists a deleted-but-unstaged tracked file: afterrm tracked.txt,git ls-files -z --full-namestill printstracked.txt. Socreatereturns 'file is tracked by git; use edit for tracked files', butedit/insertthen fail becauseos.Opencannot 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.Statthe 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 whatcreateshould do.@ -0,0 +468,4 @@lastEndedNewline = strings.HasSuffix(raw, "\n")if lineNo == line {if _, werr := io.WriteString(dst, text+"\n"); werr != nil {🟡 SUGGESTION — the inserted text always gets a newline appended (
io.WriteString(dst, text+"\n")), but thetextjsonschema explicitly allows 'one or more lines'. A model passing text ending in a newline gets a stray blank line: insertingline\nbefore line 2 ofl1\n l2\nyieldsl1\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")🟡 SUGGESTION —
git ls-filesis run with no pathspec on everycreate, 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.Resolved all three findings in
cf72f31(pushed; branch tip is nowcf72f31on top of29595b9).go build,go vet,go test(plain andracedetector test), andgolangci-lint run --fix=falseare all clean.🟠 IMPORTANT — deleted tracked file (comment 624): fixed.
createFilenow checks whether the resolved path is on disk first, via a newfileExistshelper, 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 whatcreateshould re-create. New testTestCreateRecreatesDeletedTrackedFile: it assertseditstill fails on the deleted file (the reviewer's second half), then thatcreaterestores it.🟡 SUGGESTION — insert trailing newline (comment 625): fixed.
insertFiletrims one trailing newline fromtextbefore inserting, since the insertion adds the separator itself."line\n"before line 2 ofl1\nl2\nnow yieldsl1\nline\nl2\n. Covered inTestInsertFileRanges, 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-pathspecsis a global git option; afterls-filesgit 2.39 answerserror: unknown option, exit 129 (verified). The working form isgit --literal-pathspecs ls-files ....gosecG204 (Subprocess launched with variable), which is enabled in the shared lint config and cannot be suppressed under this repo's no-//nolintrule. G204's rule flags any subprocess argument that is not a constant literal, so a pathspec — literal or not — is not available here.So
trackednow runs the constant command linegit ls-files -zwithcmd.Dirset to the target's own directory, and compares againstfilepath.Base(path).git ls-filesonly lists entries under the directory it runs in (verified: fromsub/it printsinner.txt, and--full-nameonly 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 addingG204to the gosec exclusions (orgoogle.golang.org/adk/v2/tool.Tooltoireturn.allow) in the shared go-linters config. New testTestCreateRefusesNestedTrackedFilecovers the nested case, since the prefix-free comparison is what makes directory scoping work.Also updated the README's
createbullet to say the guard refuses an existing tracked file, and why a deleted one is re-creatable.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:
exec.CommandContextpasses an argv, so nothing is word-split and no metacharacter is expanded.--ends the options, so a file named--helpis looked up as a path rather than parsed as a flag (checked).--literal-pathspecsdisables globbing and pathspec magic. A name like:(exclude)other.txtbecomes a file name: with the flag,git ls-files -z --full-name -- :(exclude)tracked.txtprints 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 afterls-files).resolvePathjoins and cleans, thenfilepath.Rel+filepath.Cleanproduce 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>withcmd.Dirat the repository root, plus a//nolint:gosecwhose 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:
resolvePathnow rejects aNULbyte 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 inTestResolvePath.go build,go vet,go test(plain andracedetector test) andgolangci-lint run --fix=falseare clean atec6cfd9.