From e364636dad4bf27a7694b9ac6eb9d41c69df33a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Thu, 6 Aug 2026 04:02:24 +0000 Subject: [PATCH 1/2] docs: update for PR #3912 - list_directory empty detection Reflects changes from docker/docker-agent#3912. Source PR: https://github.com/docker/docker-agent/pull/3912 Added documentation for the new empty directory detection behavior: - list_directory now explicitly reports when a directory is empty - Distinguishes between truly empty directories and directories with all entries hidden by ignore patterns - Helps models avoid unnecessary shell command retries --- docs/tools/filesystem/index.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/tools/filesystem/index.md b/docs/tools/filesystem/index.md index 921d25273..42a547161 100644 --- a/docs/tools/filesystem/index.md +++ b/docs/tools/filesystem/index.md @@ -28,6 +28,15 @@ When a file is not found, error messages include the resolved absolute path to h > [!IMPORTANT] > Agents must use paths appropriate for the host OS. A Windows absolute path like `C:\file.txt` on a Unix system (or vice versa) is rejected with a clear error message. +### Empty directory detection + +When `list_directory` encounters an empty directory or a directory where all entries are hidden by ignore patterns (e.g., only a `.git` folder when `ignore_vcs: true`), it explicitly reports the state: + +- **Empty directory**: "Directory is empty: /path/to/dir" +- **All entries ignored**: "Directory has no visible entries (N hidden by ignore patterns): /path/to/dir" + +This helps agents distinguish between an empty directory and a tool failure, avoiding unnecessary retries with shell commands. + ## Available Tools | Tool | Description | @@ -36,7 +45,7 @@ When a file is not found, error messages include the resolved absolute path to h | `read_multiple_files` | Read several files in one call (more efficient than multiple `read_file`) | | `write_file` | Create or overwrite a file with new content | | `edit_file` | Make line-based edits (find-and-replace) in an existing file | -| `list_directory` | List files and directories at a given path | +| `list_directory` | List files and directories at a given path (explicitly reports empty directories) | | `directory_tree` | Recursive tree view of a directory | | `create_directory` | Create a new directory (creates parent directories as needed) | | `remove_directory` | Remove an empty directory | From 871bc5e98c6f39093d9239943bea7e145d4e04ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Thu, 6 Aug 2026 04:02:49 +0000 Subject: [PATCH 2/2] docs: update for PR #3911 - shell interpreter detection Reflects changes from docker/docker-agent#3911. Source PR: https://github.com/docker/docker-agent/pull/3911 Added documentation for the new shell interpreter detection feature: - The shell tool now names the resolved interpreter in its description - Includes OS information (Linux, macOS, Windows) to help models - Provides shell-specific syntax hints (e.g., PowerShell vs POSIX) - Reduces wasted turns from incorrect shell syntax assumptions --- docs/tools/shell/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/tools/shell/index.md b/docs/tools/shell/index.md index 297c457ef..4649dff3a 100644 --- a/docs/tools/shell/index.md +++ b/docs/tools/shell/index.md @@ -15,6 +15,17 @@ The shell tool allows agents to execute arbitrary shell commands synchronously. Commands have a default 30-second timeout and require user confirmation unless `--yolo` is used. For servers, watchers, and other long-running commands, add the [`background_jobs`](../background-jobs/index.md) toolset alongside `shell`. +### Shell interpreter detection + +The shell tool automatically detects and names the resolved shell interpreter (e.g., `bash`, `zsh`, `powershell`, `pwsh`, `cmd`) in its description to the model, along with the operating system (Linux, macOS, Windows). This helps models use the correct shell syntax for the host environment. + +For example: + +- On Linux with bash: "Executes the given shell command with bash on Linux." +- On Windows with PowerShell: "Executes the given shell command with powershell on Windows. Use Windows PowerShell 5.1 syntax: chain commands with ";" (not "&&"), and avoid POSIX commands/flags like "ls -la"." + +This reduces wasted turns where models assume POSIX syntax on Windows or vice versa. + ## Configuration ```yaml