feat: add built-in filesystem discovery and structural tools #33
No reviewers
Labels
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
sam/brainless!33
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/builtin-filesystem-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?
Problem
Agents kept opening Paseo terminals (
create_terminal+send_terminal_keys) to inspect the repo because the built-in file tools (read/create/edit/insert) all need a known path: there was no way to list a directory or search file contents, and no way to create a directory or delete anything. The only Paseo-injected tools that couldls/grep/find/mkdir/rmwere the terminal tools, so the model loaded those and used the terminal for everything.Change
Nine always-visible built-in file tools (named after the reference MCP filesystem server, https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem):
list_directory(path)—ls-style listing,[FILE]/[DIR]prefixes,.gitomittedsearch_files(pattern, path?, maxResults?)— literal-substring grep likegrep -rn,path:line: textoutput, skips.gitand binary files, capped at 100 matches by defaultcreate_directory(path)—mkdir -psemantics, succeeds if it existsdelete(path)— remove one filedelete_directory(path)— remove an empty directory (contents first)The three structural tools are confined to the session working directory: an absolute path or a
..escape landing outside it is refused, so an agent cannot create or delete outside the workspace it was spawned for (the read/write tools keep the documented trusted-client posture).The agent instruction now names the built-ins and says: inspect and edit files with them, open a terminal only to run commands that need execution (git, builds, tests).
Verification
go vet ./...,go test ./...,go test -race ./internal/tools/ ./internal/harness/all greengolangci-lint run ./internal/...— 0 issues.gitomission, content grep + binary/cap behavior, mkdir idempotence, deletes + non-empty refusal, scope guard (absolute path and..escape, with the outside file asserted to survive)Review of PR #33 (feat/builtin-filesystem-tools, head
49017cb) — verified against a worktree checked out at the head commit with go1.27.1 (go build ./... , go vet, and the PR's own tests all green). No existing reviews on this PR.Summary of passes (samber/cc-skills-golang): code style/naming/docs are consistent with the existing built-in tools (exported constructors with doc comments, //nolint:ireturn explained, tool name constants in tools.go, README and agent instruction updated coherently); error wrapping uses %w with context throughout and close errors are handled; no new dependencies (only stdlib bytes/io/fs added; go.mod untouched); no goroutines or shared state introduced (ctx checks in the walk and line loops); tests are well-structured (t.Parallel, helper, t.Context).
Four verified findings, one blocking: the structural-tool scope guard (the PR's headline security property: "an agent cannot create or delete outside the workspace it was spawned for") is bypassable through symlinks; delete_directory silently deletes regular files; and two smaller correctness gaps in search_files (missing truncation note in one case, .git-as-file searched in the linked-worktree layout the harness itself runs in). Each was reproduced with the actual PR code via targeted tests in the internal/tools package; the command and its failing output are quoted inline.
@ -542,0 +789,4 @@default:}if entry.IsDir() {🟡 SUGGESTION —
.gitis only skipped when it is a directory, but in a linked git worktree — the exact layout brainless sessions run in (sessions are worktrees;.gitis a file containing 'gitdir: ...') — the.gitfile is opened and searched, contradicting the documented '.gitand binary files are skipped'. Reproduced withgo test ./internal/tools/ -run TestVerifySearchGitFileInWorktree -v: search output contains.git:2: alpha. Fix: checkentry.Name() == ".git"before the IsDir branch so the file form is skipped too (listDirectory already handles both by checking the name first).@ -542,0 +797,4 @@return nil}if matches >= maxResults {🟡 SUGGESTION — the truncation note can silently vanish.
truncatedis only set when a NEW file is reached with matches >= maxResults; when the last file visited overflows the remaining budget, searchReader stops appending at budget lines but the walk ends without ever setting truncated, so the '... (truncated at N matches)' note is missing even though the result is capped. Reproduced withgo test ./internal/tools/ -run TestVerifySilentTruncation -v: a single file with 200 matching lines and maxResults=10 yields exactly 10 lines but no 'truncated at 10 matches'. The PR's own TestSearchFiles misses this only because many.txt sorts alphabetically before one.txt/two.txt. Fix: have searchReader report budget exhaustion (e.g. return a bool when it stops because*matches >= budgetwhile the file had more matching lines) and OR it intotruncated. The cap itself is never violated (verified: <= maxResults lines always).@ -542,0 +955,4 @@default:}if err := os.Remove(resolved); err != nil {🟠 IMPORTANT — delete_directory silently deletes a regular file. os.Remove succeeds on files as well as directories, so calling
delete_directoryon a file path returnsDeleted directory <path>and the file is gone, contradicting the tool's contract ('Delete an empty directory'). Reproduced withgo test ./internal/tools/ -run TestVerifyDeleteDirectoryOnFile -v:removeDirectory plain.txt -> output="Deleted directory .../plain.txt" err=<nil>. Since the model drives these tools, a single misclassification destroys the file with directory semantics. Fix: os.Stat first and refuse unless info.IsDir() (or check errors.Is(err, syscall.ENOTEMPTY) to keep the 'not empty' message for the real case — currently the '(only empty directories can be deleted)' suffix is appended to every os.Remove failure, including permission errors).@ -542,0 +982,4 @@base = wd}rel, err := filepath.Rel(base, resolved)🔴 BLOCKING — the scope guard is purely lexical and is bypassed by symlinks. resolveScopedPath compares filepath.Rel(base, resolved) without evaluating symlinks, while os.Remove/os.MkdirAll follow them. If the session directory contains a symlink pointing outside (node_modules/.bin, .venv, dotfiles-style repos, or anything the model creates via a terminal command),
delete,delete_directory, andcreate_directoryoperate on the symlink target — outside the workspace the PR promises to confine them to. Reproduced against the head commit withgo test ./internal/tools/ -run TestVerifySymlinkScopeBypass -v:removeFile escape/secret.txt -> output="Deleted .../escape/secret.txt" err=<nil>and the outside file is gone (stat .../secret.txt: no such file or directory);makeDirectory escape/created-via-symlinkcreatedoutside/created-via-symlink. The PR's own TestDeleteFileAndDirectory only exercises absolute and..escapes, so it misses this. Fix: evaluate symlinks before the containment check —filepath.EvalSymlinksbothbaseand the resolved path (for create_directory, where the target may not exist yet, evaluate the deepest existing ancestor and re-append the remainder), then verify the evaluated path is still within the evaluated base.All four review comments are resolved at head
8107755:resolveScopedPathnow evaluates symlinks on both sides before the containment check:filepath.EvalSymlinkson the session dir, andevalCloseston the target (walks up to the deepest existing ancestor forcreate_directory, re-appending the remainder).delete,delete_directory, andcreate_directorycan no longer follow a workspace-internal symlink outside. Covered byTestScopeGuardSymlink, which reproduces the reported bypass (delete and create through anescapesymlink) and asserts the outside target survives.removeDirectorynowos.Stats first and refuses unlessinfo.IsDir(); the "delete its contents first" hint is only appended tosyscall.ENOTEMPTYfailures, not everyos.Removeerror. Covered byTestDeleteDirectoryOnFile.searchReadernow returns whether the file had more matching lines than the remaining budget, andsearchFilesORs that intotruncated, so the note appears even when the last file visited overflows the budget and the walk ends. Covered byTestSearchFilesSingleFileTruncation(single file, 200 matches, maxResults=10 → note present)..gitname check moved before theIsDirbranch, so the linked-worktree.gitfile is skipped like the.gitdirectory. Covered byTestSearchFilesSkipsGitFile.Verification:
go vet ./...,go test ./...,go test -race ./internal/tools/ ./internal/harness/all green;golangci-lint run ./internal/...0 issues.