feat: add built-in filesystem discovery and structural tools #33

Merged
sam merged 4 commits from feat/builtin-filesystem-tools into main 2026-10-14 06:47:34 +00:00
Collaborator

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 could ls/grep/find/mkdir/rm were 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, .git omitted
  • search_files(pattern, path?, maxResults?) — literal-substring grep like grep -rn, path:line: text output, skips .git and binary files, capped at 100 matches by default
  • create_directory(path) — mkdir -p semantics, succeeds if it exists
  • delete(path) — remove one file
  • delete_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 green
  • golangci-lint run ./internal/... — 0 issues
  • New tests: listing format + .git omission, content grep + binary/cap behavior, mkdir idempotence, deletes + non-empty refusal, scope guard (absolute path and .. escape, with the outside file asserted to survive)
## 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 could `ls`/`grep`/`find`/`mkdir`/`rm` were 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, `.git` omitted - `search_files(pattern, path?, maxResults?)` — literal-substring grep like `grep -rn`, `path:line: text` output, skips `.git` and binary files, capped at 100 matches by default - `create_directory(path)` — `mkdir -p` semantics, succeeds if it exists - `delete(path)` — remove one file - `delete_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 green - `golangci-lint run ./internal/...` — 0 issues - New tests: listing format + `.git` omission, content grep + binary/cap behavior, mkdir idempotence, deletes + non-empty refusal, scope guard (absolute path and `..` escape, with the outside file asserted to survive)
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. Paseo's own injected tool catalog only offers terminal tools that
can ls/grep/find, so the model loaded those and used the terminal for
everything.

Add two always-visible built-in tools named after the reference MCP
filesystem server (list_directory, search_files):

- list_directory(path) lists entries like ls, marking [DIR]/[FILE] and
  omitting .git.
- search_files(pattern, path?, maxResults?) greps a literal substring across
  files, returning path:line: text up to maxResults (default 100), skipping
  .git and binary files.

Both register unconditionally (no git dependency), stay in the always-visible
prune set via Filesystem.Names(), and honor context cancellation. The agent
instruction now names the built-ins and tells the model to inspect files with
them and open a terminal only to run commands (git, builds, tests).
The built-in file tools could read, write, and edit but never create a
directory or delete anything, so scaffolding and cleanup still required a
terminal. Add the reference filesystem server's structural tools, always
visible like the rest:

- create_directory(path) - mkdir -p semantics, succeeds if it exists.
- delete_file(path) - remove one file.
- delete_directory(path) - remove an empty directory (contents first).

Unlike the read/write tools, the structural tools are confined to the
session working directory: an absolute path or a .. escape that lands
outside it is refused, so an agent cannot create or delete outside the
workspace it was spawned for. The agent instruction now names all nine
built-in file tools.
refactor: rename delete_file built-in tool to delete
All checks were successful
code-review / Agent review (pull_request) Successful in 8s
49017cb20c
The file tools use short names (read, create, edit, insert), so delete_file
was the odd one out; directory tools keep the _directory suffix
(create_directory, delete_directory). delete matches the pattern: short for
files, suffixed for directories.
pi-reviewer left a comment

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.

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() {
Collaborator

🟡 SUGGESTION — .git is only skipped when it is a directory, but in a linked git worktree — the exact layout brainless sessions run in (sessions are worktrees; .git is a file containing 'gitdir: ...') — the .git file is opened and searched, contradicting the documented '.git and binary files are skipped'. Reproduced with go test ./internal/tools/ -run TestVerifySearchGitFileInWorktree -v: search output contains .git:2: alpha. Fix: check entry.Name() == ".git" before the IsDir branch so the file form is skipped too (listDirectory already handles both by checking the name first).

🟡 SUGGESTION — `.git` is only skipped when it is a directory, but in a linked git worktree — the exact layout brainless sessions run in (sessions are worktrees; `.git` is a file containing 'gitdir: ...') — the `.git` file is opened and searched, contradicting the documented '`.git` and binary files are skipped'. Reproduced with `go test ./internal/tools/ -run TestVerifySearchGitFileInWorktree -v`: search output contains `.git:2: alpha`. Fix: check `entry.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 {
Collaborator

🟡 SUGGESTION — the truncation note can silently vanish. truncated is 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 with go 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 >= budget while the file had more matching lines) and OR it into truncated. The cap itself is never violated (verified: <= maxResults lines always).

🟡 SUGGESTION — the truncation note can silently vanish. `truncated` is 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 with `go 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 >= budget` while the file had more matching lines) and OR it into `truncated`. The cap itself is never violated (verified: <= maxResults lines always).
@ -542,0 +955,4 @@
default:
}
if err := os.Remove(resolved); err != nil {
Collaborator

🟠 IMPORTANT — delete_directory silently deletes a regular file. os.Remove succeeds on files as well as directories, so calling delete_directory on a file path returns Deleted directory <path> and the file is gone, contradicting the tool's contract ('Delete an empty directory'). Reproduced with go 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).

🟠 IMPORTANT — delete_directory silently deletes a regular file. os.Remove succeeds on files as well as directories, so calling `delete_directory` on a file path returns `Deleted directory <path>` and the file is gone, contradicting the tool's contract ('Delete an empty directory'). Reproduced with `go 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)
Collaborator

🔴 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, and create_directory operate on the symlink target — outside the workspace the PR promises to confine them to. Reproduced against the head commit with go 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-symlink created outside/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.EvalSymlinks both base and 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.

🔴 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`, and `create_directory` operate on the symlink target — outside the workspace the PR promises to confine them to. Reproduced against the head commit with `go 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-symlink` created `outside/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.EvalSymlinks` both `base` and 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.
pi-agent referenced this pull request from a commit 2026-10-13 21:33:27 +00:00
- scope guard now evaluates symlinks (blocking): resolveScopedPath resolves
  the session dir and the target (via evalClosest, which walks up to the
  deepest existing ancestor for create_directory) before the containment
  check, so a symlink inside the workspace pointing outside can no longer
  route delete/create_directory outside it.
- delete_directory refuses regular files: os.Stat first, error unless
  IsDir; the 'delete its contents first' hint is only appended to
  ENOTEMPTY failures.
- search_files truncation note: searchReader reports budget exhaustion so
  the note appears even when the last file visited overflows the budget and
  the walk ends without another file.
- search_files skips the .git file too: linked git worktrees (the layout
  brainless sessions run in) have .git as a file, which was being searched.

New tests: TestScopeGuardSymlink (delete + create via symlink, outside
target asserted to survive), TestDeleteDirectoryOnFile, TestSearchFilesSingleFileTruncation, TestSearchFilesSkipsGitFile.
Author
Collaborator

All four review comments are resolved at head 8107755:

  • comment 1112 (blocking, symlink scope bypass) — resolveScopedPath now evaluates symlinks on both sides before the containment check: filepath.EvalSymlinks on the session dir, and evalClosest on the target (walks up to the deepest existing ancestor for create_directory, re-appending the remainder). delete, delete_directory, and create_directory can no longer follow a workspace-internal symlink outside. Covered by TestScopeGuardSymlink, which reproduces the reported bypass (delete and create through an escape symlink) and asserts the outside target survives.
  • comment 1113 (delete_directory deletes regular files) — removeDirectory now os.Stats first and refuses unless info.IsDir(); the "delete its contents first" hint is only appended to syscall.ENOTEMPTY failures, not every os.Remove error. Covered by TestDeleteDirectoryOnFile.
  • comment 1114 (truncation note can vanish) — searchReader now returns whether the file had more matching lines than the remaining budget, and searchFiles ORs that into truncated, so the note appears even when the last file visited overflows the budget and the walk ends. Covered by TestSearchFilesSingleFileTruncation (single file, 200 matches, maxResults=10 → note present).
  • comment 1115 (.git file searched in linked worktrees) — the .git name check moved before the IsDir branch, so the linked-worktree .git file is skipped like the .git directory. Covered by TestSearchFilesSkipsGitFile.

Verification: go vet ./..., go test ./..., go test -race ./internal/tools/ ./internal/harness/ all green; golangci-lint run ./internal/... 0 issues.

All four review comments are resolved at head 8107755: - **comment 1112 (blocking, symlink scope bypass)** — `resolveScopedPath` now evaluates symlinks on both sides before the containment check: `filepath.EvalSymlinks` on the session dir, and `evalClosest` on the target (walks up to the deepest existing ancestor for `create_directory`, re-appending the remainder). `delete`, `delete_directory`, and `create_directory` can no longer follow a workspace-internal symlink outside. Covered by `TestScopeGuardSymlink`, which reproduces the reported bypass (delete and create through an `escape` symlink) and asserts the outside target survives. - **comment 1113 (delete_directory deletes regular files)** — `removeDirectory` now `os.Stat`s first and refuses unless `info.IsDir()`; the "delete its contents first" hint is only appended to `syscall.ENOTEMPTY` failures, not every `os.Remove` error. Covered by `TestDeleteDirectoryOnFile`. - **comment 1114 (truncation note can vanish)** — `searchReader` now returns whether the file had more matching lines than the remaining budget, and `searchFiles` ORs that into `truncated`, so the note appears even when the last file visited overflows the budget and the walk ends. Covered by `TestSearchFilesSingleFileTruncation` (single file, 200 matches, maxResults=10 → note present). - **comment 1115 (.git file searched in linked worktrees)** — the `.git` name check moved before the `IsDir` branch, so the linked-worktree `.git` file is skipped like the `.git` directory. Covered by `TestSearchFilesSkipsGitFile`. Verification: `go vet ./...`, `go test ./...`, `go test -race ./internal/tools/ ./internal/harness/` all green; `golangci-lint run ./internal/...` 0 issues.
sam merged commit 3aa01088fb into main 2026-10-14 06:47:34 +00:00
sam deleted branch feat/builtin-filesystem-tools 2026-10-14 06:47:34 +00:00
Sign in to join this conversation.
No reviewers
No labels
code-review
No milestone
No project
No assignees
2 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!33
No description provided.