docs: prefer relative paths in tool documentation and system prompt

docs/tools/file-system.md

@@ -14,7 +14,8 @@ Lists the names of files and subdirectories directly within a specified path.
 
 - **Tool name:** `list_directory`
 - **Arguments:**
-  - `dir_path` (string, required): Absolute or relative path to the directory.
+  - `dir_path` (string, required): Path to the directory (relative to workspace
+    root preferred).
   - `ignore` (array, optional): Glob patterns to exclude.
   - `file_filtering_options` (object, optional): Configuration for `.gitignore`
     and `.geminiignore` compliance.
@@ -26,7 +27,8 @@ and PDF.
 
 - **Tool name:** `read_file`
 - **Arguments:**
-  - `file_path` (string, required): Path to the file.
+  - `file_path` (string, required): Path to the file (relative to workspace root
+    preferred).
   - `offset` (number, optional): Start line for text files (0-based).
   - `limit` (number, optional): Maximum lines to read.
 
@@ -37,7 +39,8 @@ if not.
 
 - **Tool name:** `write_file`
 - **Arguments:**
-  - `file_path` (string, required): Path to the file.
+  - `file_path` (string, required): Path to the file (relative to workspace root
+    preferred).
   - `content` (string, required): Data to write.
 - **Confirmation:** Requires manual user approval.
 
@@ -51,16 +54,16 @@ Finds files matching specific glob patterns across the workspace.
 - **Parameters:**
   - `pattern` (string, required): The glob pattern to match against (e.g.,
     `"*.py"`, `"src/**/*.js"`).
-  - `path` (string, optional): The absolute path to the directory to search
-    within. If omitted, searches the tool's root directory.
+  - `dir_path` (string, optional): The path to the directory to search within
+    (relative to workspace root preferred). If omitted, searches the tool's root
+    directory.
   - `case_sensitive` (boolean, optional): Whether the search should be
     case-sensitive. Defaults to `false`.
   - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore
     patterns when finding files. Defaults to `true`.
 - **Behavior:**
   - Searches for files matching the glob pattern within the specified directory.
-  - Returns a list of absolute paths, sorted with the most recently modified
-    files first.
+  - Returns a list of paths, sorted with the most recently modified files first.
   - Ignores common nuisance directories like `node_modules` and `.git` by
     default.
 - **Output (`llmContent`):** A message like:
@@ -79,8 +82,9 @@ lines containing matches, along with their file paths and line numbers.
 - **Parameters:**
   - `pattern` (string, required): The regular expression (regex) to search for
     (e.g., `"function\s+myFunction"`).
-  - `path` (string, optional): The absolute path to the directory to search
-    within. Defaults to the current working directory.
+  - `dir_path` (string, optional): The path to the directory to search within
+    (relative to workspace root preferred). Defaults to the current working
+    directory.
   - `include` (string, optional): A glob pattern to filter which files are
     searched (e.g., `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted, searches most
     files (respecting common ignores).
@@ -113,7 +117,8 @@ around the `old_string` to ensure it modifies the correct location.
 
 - **Tool name:** `replace`
 - **Arguments:**
-  - `file_path` (string, required): Path to the file.
+  - `file_path` (string, required): Path to the file (relative to workspace root
+    preferred).
   - `instruction` (string, required): Semantic description of the change.
   - `old_string` (string, required): Exact literal text to find.
   - `new_string` (string, required): Exact literal text to replace with.

docs/tools/shell.md

@@ -14,8 +14,10 @@ platforms, they execute with `bash -c`.
 - `command` (string, required): The exact shell command to execute.
 - `description` (string, optional): A brief description shown to the user for
   confirmation.
-- `dir_path` (string, optional): The absolute path or relative path from
-  workspace root where the command runs.
+- `dir_path` (string, optional): The path of the directory to run the command in
+  (relative to workspace root preferred). If not provided, the project root
+  directory is used. Must be a directory within the workspace and must already
+  exist.
 - `is_background` (boolean, optional): Whether to move the process to the
   background immediately after starting.
 

packages/core/src/agents/local-executor.ts

@@ -1199,7 +1199,7 @@ export class LocalAgentExecutor<TOutput extends z.ZodTypeAny> {
 Important Rules:
 * You are running in a non-interactive mode. You CANNOT ask the user for input or clarification.
 * Work systematically using available tools to complete your task.
-* Always use absolute paths for file operations. Construct them using the provided "Environment Context".`;
+* Prefer relative paths (relative to workspace root) for file operations. Construct them using the provided "Environment Context".`;
 
     if (this.definition.outputConfig) {
       finalPrompt += `