[FEATURE] Tools should accept ~/ and relative paths, resolve via $HOME/$PWD instead of requiring absolute paths

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

Claude Code's file tools (Read, Edit, Write, Glob) require absolute paths in their parameters. This forces the LLM to hard-code the user's home directory path (e.g. /Users/mike.schmitt/...), which is a frequent source of silent failures because LLMs hallucinate usernames.

A user named "mike.schmitt" will routinely see Claude generate:

• /Users/mike.schmidt/Work/project/file.rb (schmidt — is a more common spelling, hallucinated)
• /home/mike.schmitt/Work/project/file.rb (wrong OS prefix)

LLMs default to the more common spelling of ambiguous names. This fails silently or produces "file not found" errors, wasting tokens and user time. Users can add CLAUDE.md instructions like "never hard-code my home directory" but the tool contract requires absolute paths, so the instruction fights the tool API.

Claude Code needs to be aware if a file location is under $PWD or not.

• For files under $PWD, the LLM should use relative paths (./src/file.rb).
• For files under $HOME but outside $PWD (e.g. ~/.claude/CLAUDE.md), the LLM should use $HOME directly!

In neither case should the LLM attempt to spell out the username.

Proposed Solution

1. Under $PWD: tools should accept and prefer relative paths (e.g. ./src/file.rb), resolved server-side against the working directory
2. Under $HOME but outside $PWD: accept ~/, resolved server-side via $HOME
3. Reject path traversal (../) that escapes $PWD — this addresses the security concern raised in issue #38270
4. The LLM should never attempt to spell out the user's home directory path. Tools should resolve $HOME internally, not require the LLM to guess it.

Alternative Solutions

Current workarounds:

• CLAUDE.md instructions telling the model to use ~/ (is ignored by tools that reject it)
• Expanding $HOME via a Bash call first, then passing the result to file tools (extra round-trip, still requires the LLM to copy the path correctly)
• Users with simple usernames don't notice, but anyone with a non-ASCII or multi-syllable name hits this regularly

Priority

High - Significant impact on productivity

Feature Category

File operations

Use Case Example

1. User "mike.schmitt" asks Claude to edit ~/.claude/CLAUDE.md
2. Claude must expand ~/ to /Users/mike.schmitt/ for the Edit tool
3. Claude hallucinates /Users/mike.schmidt/ (more common spelling)
4. Edit tool returns "file not found"
5. Claude retries with another variation, wasting another round-trip
6. User has to manually correct the path

With ~/ support: Claude passes ~/.claude/CLAUDE.md directly, tool resolves it server-side via $HOME, no hallucination possible.

For files under $PWD: Claude passes ./foo/bar/baz.rb, tool resolves against the working directory. No home directory path involved at all.

Additional Context

Security note: requiring absolute paths is actually less safe than relative paths scoped to $PWD.

• Absolute paths can reference any location on the filesystem, easily escaping the project sandbox.
• Relative paths scoped to $PWD and ~/ scoped to $HOME are naturally bounded.

Related:
issue #38270 raises the complementary concern — relative paths are silently accepted when they should be validated.

Both issues stem from the same root cause: path handling is underdesigned.

The fix for both: tools should resolve paths against $PWD and $HOME server-side, and reject anything that escapes those boundaries.

This replaces the current model where the LLM constructs absolute paths (hallucination-prone) and tools silently accept whatever they get (no boundary enforcement).