Enhancement: Detect bash hash conflicts and suggest `hash -r` on version check failure
Summary
When Claude Code blocks execution due to outdated version, detect if bash's hash table is pointing to a different binary than PATH resolution, and suggest hash -r before asking to update.
Problem
Users with long-running bash sessions may have cached paths to old installations. After updating, which claude shows the new location, but bash still executes the cached old binary.
Symptom:
$ which claude
/home/user/.local/bin/claude
$ type claude
claude is hashed (/usr/local/bin/claude) # Different location!
$ claude
# Shows "needs update" error despite having latest version
Fix: hash -r && claude
Why Add Detection?
- Low cost: Simple check comparing executing binary with PATH resolution
- High value: Catches issue at exact failure point
- No harm: Only triggers when mismatch exists
Proposed Error Message
Your version needs an update to continue.
⚠️ Shell hash mismatch detected:
Running: /usr/local/bin/claude
PATH finds: /home/user/.local/bin/claude
Try clearing your shell's command cache first:
hash -r && claude
If issue persists, update:
claude update # Will detect installation method and update appropriately
Real-World Error Output (for searchability)
<details>
<summary>Actual error users encounter</summary>
$ claude
╭────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code │
╰────────────────────────────────────────────────╯
It looks like your version of Claude Code needs an update.
A newer version is required to continue.
To update, please run:
claude update
Diagnosis that would have helped:
$ type claude
claude is hashed (/old/path/claude)
$ which claude
/new/path/claude
# Solution:
$ hash -r
</details>
---
Common triggers: Multiple package managers, system + user installs, tmux/screen sessions created pre-update
Why not just document it? Users at the error state won't read docs first. Auto-detection at failure point = better UX.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗