agent experience - tool calls have different directory requriements

[acoliver]

x Shell {"command":"npm run format","description":"Run the project's formatting script to ensure code style compliance after README edits.","directory":"/Users/acoliver/projects/llxprt/branch-1/llxprt-code"}

Directory cannot be absolute. Please refer to workspace directories by their name.

• but other tools require an absolute path.

For nemotron 3 it took forever to see that the issue was the directory and then

Directory '.' is not a registered workspace directory.

I feel like one of two things needs to happen:

1. Standardize on absolute or not absolute
2. Autotranslate any absoulute to workspace directories without error for tools that take workspace directories.

I feel like the absolute thing in the editor was a workaround for models (like gemini) that tend to create turducken code like used to happen in Cursor (where there is a src/mysrc/mything.ts and then src/src/mysrc/mything.ts)

It may or may not still be a good practice. I feel like having some other commands then reject it seems a bit off...

[acoliver]

@CodeRabbit look into this and research it.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for the error messages mentioned in the issue
echo "=== Searching for directory validation error messages ==="
rg -n "Directory cannot be absolute" -C 3

echo -e "\n=== Searching for workspace directory error ==="
rg -n "is not a registered workspace directory" -C 3

echo -e "\n=== Finding Shell tool implementation ==="
rg -n "class Shell|Shell.*Tool" --type ts --type tsx -C 3

echo -e "\n=== Searching for workspace directory handling ==="
rg -n "workspace.*director" -i --type ts --type tsx -C 2 | head -50

Length of output: 2700

---

🏁 Script executed:

#!/bin/bash
# Find tool definitions and directory parameter handling
echo "=== Finding tool-related files ==="
fd -e ts -e tsx "tool" -i | grep -v node_modules | head -20

echo -e "\n=== Searching for directory parameter validation ==="
rg -n "directory.*absolute|absolute.*directory" -i --type ts --type tsx -C 3

Length of output: 1265

---

🏁 Script executed:

#!/bin/bash
# Search for tool base classes and interfaces
echo "=== Finding tool base classes/interfaces ==="
ast-grep --pattern 'interface $_ {
  $$$
  directory: $_
  $$$
}'

echo -e "\n=== Searching for tool parameter definitions ==="
rg -n "ToolParameter|ToolInput|directory.*param" --type ts --type tsx -C 2 | head -50

Length of output: 122

---

🏁 Script executed:

#!/bin/bash
# Look at the shell.ts file in detail
echo "=== Examining shell.ts tool implementation ==="
cat packages/core/src/tools/shell.ts | head -100

echo -e "\n=== Looking at directory validation section ==="
sed -n '690,720p' packages/core/src/tools/shell.ts

Length of output: 4276

---

🏁 Script executed:

#!/bin/bash
# Find other tools that might have different directory handling
echo "=== Finding all tool implementations ==="
fd -e ts "tool" packages/core/src/tools/ -x basename {}

echo -e "\n=== Searching for other tools with directory parameters ==="
rg -n "directory.*:" packages/core/src/tools/*.ts -A 2 -B 2 | head -80

Length of output: 6172

---

🏁 Script executed:

#!/bin/bash
# Look for file system tools and editor tools that might use absolute paths
echo "=== Examining file-related tools ==="
ls -la packages/core/src/tools/

echo -e "\n=== Checking for editor or file system tools ==="
rg -n "class.*Tool" packages/core/src/tools/ -A 10 | grep -E "(class|directory|path)" | head -50

Length of output: 11646

---

🏁 Script executed:

#!/bin/bash
# Look at the workspace context implementation
echo "=== Finding workspace context ==="
fd -e ts "workspace" packages/core/src/ | grep -v test | head -10

echo -e "\n=== Looking at getDirectories implementation ==="
rg -n "getDirectories" packages/core/src/ --type ts -A 5 -B 2

Length of output: 29893

---

🏁 Script executed:

#!/bin/bash
# Look at file tools that require absolute paths
echo "=== Examining read-file.ts for path handling ==="
sed -n '280,380p' packages/core/src/tools/read-file.ts

echo -e "\n=== Examining write-file.ts for path handling ==="
sed -n '500,600p' packages/core/src/tools/write-file.ts

echo -e "\n=== Examining edit.ts for path handling ==="
sed -n '750,800p' packages/core/src/tools/edit.ts

Length of output: 10040

---

🏁 Script executed:

#!/bin/bash
# Look at how Shell tool resolves directory names to absolute paths
echo "=== Examining how shell.ts resolves workspace directory names ==="
sed -n '695,750p' packages/core/src/tools/shell.ts

echo -e "\n=== Looking at shell execution with directory ==="
sed -n '130,200p' packages/core/src/tools/shell.ts

Length of output: 3465

---

🏁 Script executed:

#!/bin/bash
# Look at tool schema definitions to understand parameter types
echo "=== Looking at read-file tool schema ==="
rg -n "absolute_path.*:" packages/core/src/tools/read-file.ts -A 2 -B 2 | head -20

echo -e "\n=== Looking at edit tool schema ==="
rg -n "file_path.*:" packages/core/src/tools/edit.ts -A 2 -B 2 | head -20

echo -e "\n=== Looking at ls tool schema ==="
rg -n "path.*:" packages/core/src/tools/ls.ts -A 2 -B 2 | head -20

Length of output: 1146

---

🏁 Script executed:

#!/bin/bash
# Get the actual parameter definitions from the tools
echo "=== Read file tool parameters definition ==="
rg -n "interface.*ReadFile.*Params|absolute_path.*{" packages/core/src/tools/read-file.ts -A 5 -B 2

echo -e "\n=== Edit tool parameters definition ==="
rg -n "interface.*EditTool.*Params|file_path.*{" packages/core/src/tools/edit.ts -A 5 -B 2

echo -e "\n=== Shell tool parameters definition ==="
rg -n "interface.*Shell.*Params|directory.*{" packages/core/src/tools/shell.ts -A 5 -B 2

Length of output: 561

---

🏁 Script executed:

#!/bin/bash
# Get the actual parameter definitions from the tools (fixed regex)
echo "=== Read file tool parameters interface ==="
rg -n "^export interface ReadFileToolParams" packages/core/src/tools/read-file.ts -A 20

echo -e "\n=== Edit tool parameters interface ==="
rg -n "^export interface EditToolParams" packages/core/src/tools/edit.ts -A 15

echo -e "\n=== Shell tool parameters interface ==="
rg -n "^export interface ShellToolParams" packages/core/src/tools/shell.ts -A 15

Length of output: 1319

---

🏁 Script executed:

#!/bin/bash
# Look at how shell tool actually uses the directory parameter during execution
echo "=== Shell tool execution with directory resolution ==="
sed -n '200,280p' packages/core/src/tools/shell.ts

Length of output: 3210

---

🏁 Script executed:

#!/bin/bash
# Check if there are any other tools with similar directory parameter patterns
echo "=== Finding all tools with directory parameters ==="
rg -n "directory\?:" packages/core/src/tools/*.ts | grep -v test | head -20

echo -e "\n=== Tools requiring absolute paths ==="
rg -n "must be absolute" packages/core/src/tools/*.ts | grep -v test

Length of output: 1060

---

🏁 Script executed:

#!/bin/bash
# Look at workspace context to understand how directories are stored
echo "=== Workspace context implementation ==="
cat packages/core/src/utils/workspaceContext.ts | head -120

Length of output: 3875

---

@acoliver I've thoroughly researched this issue and can confirm the inconsistency. Here's what I found:

The Problem

Shell Tool (packages/core/src/tools/shell.ts):

• The directory parameter expects a workspace directory NAME (basename only)
• Explicitly rejects absolute paths with: "Directory cannot be absolute. Please refer to workspace directories by their name."
• Matches by comparing the basename of registered workspace directories
• Example: For workspace /Users/acoliver/projects/llxprt/branch-1/llxprt-code, you'd pass just "llxprt-code"

All File Tools (read-file, write-file, edit, ls, insert_at_line, delete_line_range, read_line_range):

• Require absolute paths for file/directory parameters
• Validate with: "File path must be absolute"
• Then check if the absolute path is within the workspace
• Example: Must pass /Users/acoliver/projects/llxprt/branch-1/llxprt-code/src/file.ts

Root Cause

The Shell tool was designed to be "simpler" for agents by accepting just directory names, while file tools use absolute paths for precise validation and security. This creates cognitive overhead for AI agents who must remember which parameter format each tool expects.

Recommendation

I strongly recommend Option 2: Auto-translate absolute paths to workspace directory names in the Shell tool. Here's why:

Benefits:

1. Backward compatible - existing agents using basename continue to work
2. Forward compatible - agents can now use absolute paths consistently across all tools
3. Better UX - eliminates confusing error messages
4. Simpler mental model - "use absolute paths everywhere"
5. Minimal code change - only Shell tool validation needs updating

Implementation Strategy:

Modify shell.ts validation (around line 695-710) to:

1. If params.directory is absolute, resolve it to a workspace directory basename automatically
2. If it's already a basename, use existing logic
3. Validate the resulting directory exists in workspace

Pseudocode:

if (params.directory) {
  let directoryToMatch = params.directory;
  
  // Auto-translate absolute path to basename
  if (path.isAbsolute(params.directory)) {
    const workspaceDirs = this.config.getWorkspaceContext().getDirectories();
    const matchingDir = workspaceDirs.find(dir => 
      params.directory === dir || params.directory.startsWith(dir + path.sep)
    );
    
    if (matchingDir) {
      directoryToMatch = path.basename(matchingDir);
    } else {
      return `Directory '${params.directory}' is not within any registered workspace directory.`;
    }
  }
  
  // Existing validation logic using directoryToMatch...
}

This approach eliminates the inconsistency without breaking existing functionality and makes the tool interface more intuitive for AI agents.

Would you like me to create a detailed implementation plan or open an issue with this analysis?