Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
f3d4e40
feat: add list_files and grep_file skills tools
brandonkeung Jul 15, 2026
27fb17c
fix: address Copilot review findings on grep_file/list_files
brandonkeung Jul 15, 2026
8927e93
docs: document list_files/grep_file in the ADK skills tools README
brandonkeung Jul 15, 2026
69b5d5f
fix: correct err-shadowing bug and add timeout to grep_file
brandonkeung Jul 16, 2026
041e747
fix: harden grep_file against hangs, unbounded output, and silent rea…
brandonkeung Jul 16, 2026
a56d813
feat: gate list_files/grep_file behind KAGENT_ENABLE_FILE_SEARCH_TOOLS
brandonkeung Jul 23, 2026
e3f9c76
fix: close symlink-listing, TOCTOU, and skip-count gaps in grep_file/…
brandonkeung Jul 24, 2026
bd346e9
Merge branch 'kagent-dev:main' into feat/grep-list-files-tools
brandonkeung Aug 13, 2026
c94bf09
Merge upstream/main into feat/grep-list-files-tools
brandonkeung Aug 24, 2026
07e4d62
fix: correct symlink sizing, FIFO hang, UTF-8 truncation, and skip ac…
brandonkeung Aug 26, 2026
d5fb009
fix: share one bounded reader between read_file and grep_file
brandonkeung Aug 26, 2026
8064ed8
refactor: split the grep subsystem out of shell.go
brandonkeung Aug 26, 2026
abb3889
test: cover long line and symlink fixes through ADK tool path
brandonkeung Aug 26, 2026
9652ae1
style: satisfy ruff format on the file-search tool additions
brandonkeung Aug 26, 2026
97a23d8
perf: stop pre-allocating 64KB of scan buffer per file
brandonkeung Aug 27, 2026
0e303ee
refactor: give the Python walk classifier the shape Go already has
brandonkeung Aug 27, 2026
c565a30
test: pin Go's walk classifier directly, mirroring the Python table
brandonkeung Aug 27, 2026
b4f76af
Merge remote-tracking branch 'upstream/main' into feat/grep-list-file…
brandonkeung Aug 31, 2026
0b0bfe8
fix: keep grepping when an entry cannot be statted
brandonkeung Sep 22, 2026
028a5fa
fix: enforce the grep_file timeout, and stop stripping the pattern
brandonkeung Sep 22, 2026
e31c8aa
fix: drop a redundant debug log that used the default slog logger
brandonkeung Sep 23, 2026
ca084de
Merge remote-tracking branch 'upstream/main' into feat/grep-list-file…
brandonkeung Sep 23, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix: close symlink-listing, TOCTOU, and skip-count gaps in grep_file/…
…list_files

Addresses 4 issues mesutoezdil found in review on PR #2267:
- ListDirContent listed a directory symlink (e.g. every session's "skills"
  entry) as a file instead of a directory, since entry.IsDir() doesn't
  follow symlinks. Now stats symlink entries to classify them correctly,
  matching Python's existing symlink-following behavior.
- classifyWalkEntry verified a walked entry's resolved, in-bounds target,
  but grepFile then reopened the original unresolved path -- a
  verify-then-use gap where the symlink's target could differ between the
  check and the read. grepFile now reads the resolved path that was
  actually verified. This narrows the race but doesn't fully eliminate it
  (documented in a comment on classifyWalkEntry); closing it completely
  would need platform-specific work disproportionate to this file's
  existing security bar.
- Go and Python both silently dropped the "N entries could not be read"
  note whenever there were also real matches, only surfacing it when the
  result was otherwise empty -- masking partial failures. Both now append
  it alongside real matches too.

Verified end-to-end on a live kind cluster via A2A against redeployed
Go- and Python-runtime test agents, extracting raw tool function_response
payloads (not model-summarized text) to confirm each fix's actual
behavior, plus a targeted regression check confirming symlink-escape
protection still holds after the refactor.

Signed-off-by: brandonkeung <[email protected]>
  • Loading branch information
brandonkeung committed Jul 24, 2026
commit e3f9c76d181ce4571a01d16d07ca693a869529e0
61 changes: 45 additions & 16 deletions go/adk/pkg/skills/shell.go
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,18 @@ func ListDirContent(path string) (string, error) {
continue
}

// entry.IsDir() reflects the entry's own type (Lstat-like) and is
// false for a symlink even when its target is a directory -- e.g.
// the "skills" symlink present in every session dir. Stat (which
// follows symlinks) to classify those correctly, matching Python's
// pathlib Path.is_dir(), which follows symlinks by default.
if entry.Type()&fs.ModeSymlink != 0 {
if target, statErr := os.Stat(filepath.Join(path, entry.Name())); statErr == nil && target.IsDir() {
fmt.Fprintf(&result, "%s/\n", entry.Name())
continue
}
}

info, err := entry.Info()
if err != nil {
fmt.Fprintf(&result, "%s\n", entry.Name())
Expand Down Expand Up @@ -164,38 +176,51 @@ const (

// classifyWalkEntry decides how GrepContent's WalkDir callback should treat
// p, given the resolved search root. It never opens p for reading -- the
// caller is responsible for that once this returns walkEntryGrep.
func classifyWalkEntry(root, p string, d fs.DirEntry) walkEntryAction {
// caller is responsible for that once this returns walkEntryGrep, and must
// read the returned resolved path rather than p itself: p is the symlink
// as walked, and re-resolving or reopening it separately from this check
// would reintroduce a TOCTOU window where the symlink's target could change
// between the check and the read.
//
// This narrows that window but doesn't eliminate it: resolved is still a
// path string, so the later os.Open on it is a fresh lookup, not an
// operation on a captured file handle. A path component of resolved could
// still be swapped out between this check and that open. Closing that
// residual race fully would need platform-specific work (e.g. Linux's
// openat2 with RESOLVE_NO_SYMLINKS), which isn't done anywhere else in this
// file either -- this function only guarantees "reads what was just
// verified", not "reads atomically with no concurrent tampering".
func classifyWalkEntry(root, p string, d fs.DirEntry) (walkEntryAction, string) {
if d.IsDir() {
return walkEntrySkip
return walkEntrySkip, ""
}
resolved, err := filepath.EvalSymlinks(p)
if err != nil {
return walkEntryUnreadable
return walkEntryUnreadable, ""
}
fi, statErr := os.Stat(resolved)
if statErr != nil {
return walkEntryUnreadable
return walkEntryUnreadable, ""
}
if fi.IsDir() {
// p is a symlink to a directory: WalkDir doesn't recurse into
// symlinked directories, and grepFile would fail trying to read
// one as a file, so skip it rather than treating it as an error.
return walkEntrySkip
return walkEntrySkip, ""
}
if !fi.Mode().IsRegular() {
// Skip non-regular files (FIFOs, sockets, devices): opening one
// for reading can block indefinitely (e.g. a FIFO with no writer
// connected), and grep has no business reading them.
return walkEntrySkip
return walkEntrySkip, ""
}
if !WithinRoot(resolved, root) {
// The symlink-resolved target escapes the root being searched, so
// a symlink can't be used to read files outside the requested
// directory.
return walkEntrySkip
return walkEntrySkip, ""
}
return walkEntryGrep
return walkEntryGrep, resolved
}

// GrepContent searches path for lines matching a regular expression pattern.
Expand All @@ -216,6 +241,7 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
}

var result strings.Builder
var skipped int
grepFile := func(filePath string) error {
file, err := os.Open(filePath)
if err != nil {
Expand Down Expand Up @@ -254,7 +280,6 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
// its root argument, so if path itself were an unresolved directory
// symlink, WalkDir would see a non-directory at the root and never
// descend into it at all.
var skipped int
err = filepath.WalkDir(root, func(p string, d fs.DirEntry, walkErr error) error {
if walkErr != nil {
if p == root {
Expand All @@ -272,22 +297,19 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
skipped++
return nil
}
switch classifyWalkEntry(root, p, d) {
switch action, resolved := classifyWalkEntry(root, p, d); action {
case walkEntryUnreadable:
skipped++
case walkEntryGrep:
// A read error on one file (permission denied, a line
// exceeding the scan buffer, etc.) shouldn't abort matches
// already found elsewhere in the tree.
if grepErr := grepFile(p); grepErr != nil {
if grepErr := grepFile(resolved); grepErr != nil {
skipped++
}
}
return nil
})
if err == nil && skipped > 0 && result.Len() == 0 {
return fmt.Sprintf("no matches found (%d entries could not be read)", skipped), nil
}
} else {
if !info.Mode().IsRegular() {
return "", fmt.Errorf("%q is not a regular file", path)
Expand All @@ -299,10 +321,17 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
}

if result.Len() == 0 {
if skipped > 0 {
return fmt.Sprintf("no matches found (%d entries could not be read)", skipped), nil
}
return "no matches found", nil
}

return strings.TrimSuffix(result.String(), "\n"), nil
matches := strings.TrimSuffix(result.String(), "\n")
if skipped > 0 {
matches += fmt.Sprintf("\n\n(%d entries could not be read)", skipped)
}
return matches, nil
}

func resolveSRTSettingsArgs() ([]string, error) {
Expand Down
89 changes: 89 additions & 0 deletions go/adk/pkg/skills/shell_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -345,6 +345,26 @@ func TestListDirContent(t *testing.T) {
t.Fatal("expected error for nonexistent path")
}
})

t.Run("symlink to a directory is listed as a directory", func(t *testing.T) {
realDir := filepath.Join(tmpDir, "a-subdir")
linkPath := filepath.Join(tmpDir, "dir-link")
if err := os.Symlink(realDir, linkPath); err != nil {
t.Skipf("symlinks not supported: %v", err)
}
defer os.Remove(linkPath)

result, err := ListDirContent(tmpDir)
if err != nil {
t.Fatalf("ListDirContent() error = %v", err)
}
if !strings.Contains(result, "dir-link/") {
t.Errorf("expected symlinked directory to be listed with a trailing slash, got %q", result)
}
if strings.Contains(result, "dir-link\t") {
t.Errorf("expected symlinked directory not to be listed as a file, got %q", result)
}
})
}

func TestGrepContent(t *testing.T) {
Expand Down Expand Up @@ -437,6 +457,35 @@ func TestGrepContent(t *testing.T) {
}
})

t.Run("recursive search greps the resolved target of an in-bounds file symlink", func(t *testing.T) {
realFile := filepath.Join(subDir, "real_target.txt")
if err := os.WriteFile(realFile, []byte("foo via symlink\n"), 0644); err != nil {
t.Fatalf("Failed to write test file: %v", err)
}
linkPath := filepath.Join(subDir, "file_link.txt")
if err := os.Symlink(realFile, linkPath); err != nil {
t.Skipf("symlinks not supported: %v", err)
}
defer os.Remove(linkPath)

result, err := GrepContent(subDir, "foo via symlink", true, false)
if err != nil {
t.Fatalf("GrepContent() error = %v", err)
}
// The match must be reported against the resolved target path
// (real_target.txt), not the walked symlink path (file_link.txt):
// classifyWalkEntry verifies the resolved target is in-bounds, and
// the actual read must use that same resolved value rather than
// re-deriving/reopening the raw symlink path, or the verified-safe
// check and the actual read could diverge (TOCTOU).
if !strings.Contains(result, "real_target.txt:1:foo via symlink") {
t.Errorf("expected match to be reported against the resolved target path, got %q", result)
}
if strings.Contains(result, "file_link.txt:") {
t.Errorf("expected match not to be reported against the unresolved symlink path, got %q", result)
}
})

t.Run("recursive search does not abort on an in-bounds directory symlink", func(t *testing.T) {
walkDir := createTempDir(t)
defer os.RemoveAll(walkDir)
Expand Down Expand Up @@ -635,6 +684,46 @@ func TestGrepContent(t *testing.T) {
}
})

t.Run("matches are annotated with the skip count when some entries could not be read", func(t *testing.T) {
if os.Geteuid() == 0 {
t.Skip("root bypasses directory permissions; cannot exercise this case")
}

walkDir := createTempDir(t)
defer os.RemoveAll(walkDir)

okSub := filepath.Join(walkDir, "aaa_ok")
if err := os.Mkdir(okSub, 0755); err != nil {
t.Fatalf("Failed to create subdir: %v", err)
}
if err := os.WriteFile(filepath.Join(okSub, "match.txt"), []byte("foo readable\n"), 0644); err != nil {
t.Fatalf("Failed to write test file: %v", err)
}

noPermSub := filepath.Join(walkDir, "mmm_noperm")
if err := os.Mkdir(noPermSub, 0755); err != nil {
t.Fatalf("Failed to create subdir: %v", err)
}
if err := os.WriteFile(filepath.Join(noPermSub, "hidden.txt"), []byte("foo hidden\n"), 0644); err != nil {
t.Fatalf("Failed to write test file: %v", err)
}
if err := os.Chmod(noPermSub, 0000); err != nil {
t.Fatalf("Failed to chmod subdir: %v", err)
}
defer os.Chmod(noPermSub, 0755)

result, err := GrepContent(walkDir, "foo", true, false)
if err != nil {
t.Fatalf("GrepContent() error = %v", err)
}
if !strings.Contains(result, "match.txt:1:foo readable") {
t.Errorf("expected the real match to still be reported, got %q", result)
}
if !strings.Contains(result, "could not be read") {
t.Errorf("expected the skip count to be reported alongside real matches, not silently dropped, got %q", result)
}
})

t.Run("recursive search on a fully unreadable root returns an error, not a confident empty result", func(t *testing.T) {
if os.Geteuid() == 0 {
t.Skip("root bypasses directory permissions; cannot exercise this case")
Expand Down
5 changes: 4 additions & 1 deletion python/packages/kagent-skills/src/kagent/skills/shell.py
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,10 @@ def grep_file(file_path: Path) -> list[str]:
return f"no matches found ({skipped} entries could not be read)"
return "no matches found"

return "\n".join(results)
output = "\n".join(results)
if skipped:
output += f"\n\n({skipped} entries could not be read)"
return output


# --- Shell Operation Tools ---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -519,6 +519,29 @@ def test_grep_content_recursive_does_not_abort_or_discard_matches_on_an_unreadab
assert "match.txt:1:foo readable" in result


def test_grep_content_annotates_skip_count_alongside_real_matches(tmp_path):
"""A skip count found alongside real matches must not be silently dropped."""
if os.geteuid() == 0:
pytest.skip("root bypasses directory permissions; cannot exercise this case")

ok_sub = tmp_path / "aaa_ok"
ok_sub.mkdir()
(ok_sub / "match.txt").write_text("foo readable\n")

noperm_sub = tmp_path / "mmm_noperm"
noperm_sub.mkdir()
(noperm_sub / "hidden.txt").write_text("foo hidden\n")
noperm_sub.chmod(0o000)

try:
result = grep_content(tmp_path, "foo", recursive=True, allowed_root=tmp_path)
finally:
noperm_sub.chmod(0o755)

assert "match.txt:1:foo readable" in result
assert "could not be read" in result


def test_grep_content_no_matches_found_is_annotated_when_a_subdirectory_could_not_be_read(tmp_path):
if os.geteuid() == 0:
pytest.skip("root bypasses directory permissions; cannot exercise this case")
Expand Down