[FEATURE] Better error messages for tools (some existing ones are generic and or misleading)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

File tools return generic or misleading error messages for multiple different failure scenarios, making troubleshooting extremely difficult. Users cannot distinguish between different root causes that require completely different solutions.

The inconsistency problem: Some errors like permission denied show detailed EPERM messages, proving the infrastructure exists for useful error messages. However, other operations show generic or misleading errors that hide diagnostic information.

Validated findings:

• ❌ Missing file → Generic Error reading file
• ❌ File locked → Misleading Error: File has been unexpectedly modified. Read it again...
• ✅ Permission denied → Detailed EPERM: operation not permitted, open '[path]'

Impact:

• Users waste significant time debugging the wrong things
• No way to distinguish between different failure types that require completely different solutions
• Frustration from inability to self-diagnose issues
• Misleading errors compound the problem:
• File lock errors say "file was modified" and suggest "read it again" when file is locked by another process

Proposed Solution

Implement detailed error messages for file operations that match the quality of existing permission errors.

Requirements:

1. Specific failure type - What actually went wrong (file not found, file locked, etc.)
2. Path information - The exact path that was attempted
3. Contextual details - Relevant information for the specific failure type
4. Actionable suggestions - What to try next (when applicable)

Examples of improved errors:

File Not Found

Current: Error reading file (generic)

Improved:

Error reading file: File not found
Path: C:/Users/[user]/test/nonexistent.txt
Parent directory exists: Yes
Suggestion: Check filename spelling or verify the path

File Locked

Current: Error: File has been unexpectedly modified. Read it again before attempting to write it. (misleading!)

Improved:

Error writing file: File is locked by another process
Path: C:/Users/[user]/test-locked-file.txt
Locked by: python.exe (PID: 12345) [if detectable]
Suggestion: Close the file in the other application and try again

Reference: Permission Denied (Already Works Well!)

Current behavior:

Error: EPERM: operation not permitted, open 'C:\Windows\System32\protected.txt'

This error already provides good diagnostic information and should be the standard for all errors.

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

File operations

Use Case Example

❌ Bad/Generic Error Messages

Example 1: Missing File ✅ Validated

Tested scenario: Attempted to read C:\Users\Ben\this-file-does-not-exist-12345.txt

What user sees:

Error reading file

What Claude sees internally:

File does not exist.

What's hidden from user:

• That the file doesn't exist (the actual issue)
• Whether the parent directory exists
• Whether it's a typo in the filename

Impact: User cannot distinguish this from other failures and wastes time checking permissions, path formats, etc.

Example 2: File Locked (Misleading!) ✅ Validated

Tested scenario:

• Created C:\Users\Ben\test-locked-file.txt
• Opened file with exclusive lock using Python script (simulating file open in Word/Excel/etc)
• Attempted to Write/Edit the locked file

What user sees:

Error: File has been unexpectedly modified. Read it again before attempting to write it.

What Claude sees internally:

File has been unexpectedly modified. Read it again before attempting to write it.

What's hidden from user:

• The file was NOT modified
• The file is LOCKED by another process
• Which process has the lock
• That the suggested solution ("Read it again") won't help
• That the locking process needs to be closed

Impact: This is extremely misleading - the error says the file was "modified" when it's actually locked. The suggested fix ("read it again") won't solve the problem. Users have no idea a lock is involved.

✅ Good Error Messages (What Works!)

Permission Denied ✅ Validated

Tested scenario: Attempted to write to C:\Windows\System32\claude-test-file.txt

Error message (same for user and Claude):

Error: EPERM: operation not permitted, open 'C:\Windows\System32\claude-test-file.txt'

Why this works well:

• Clear error type (EPERM - permission denied)
• Exact path that failed
• Operation attempted (open for write)
• User can immediately understand the problem and know to check permissions or run as admin

This is the standard all errors should meet!

Additional Context

• Platform: Windows 11 with Git Bash
• Claude Code Version: Latest (as of 2025-10-23)
• Tools Tested: Read (generic errors), Write (permission errors work well, file lock errors misleading), Edit (file lock errors misleading)
• Likely Affected: Glob, Grep may have similar issues but not yet tested

Related Issues

This issue is separate from but related to the path format bug where Read/Edit tools don't support bash-style paths (/c/Users/...) that Glob/Grep accept. That issue results in generic "Error reading file" messages that are particularly misleading since the file exists but at a different path format.