Built-in /resume silently shadows user custom command (~/.claude/commands/resume.md) — undocumented precedence, no disambiguation

Summary

A user-level custom command at ~/.claude/commands/resume.md is silently shadowed by the built-in /resume (conversation picker). Typing /resume opens the built-in picker; the custom command is unreachable. There is no error, no disambiguation UI, and no documented precedence rule for built-in-vs-custom name collisions.

Environment

• Claude Code v2.1.172 (Windows 11, native install; also reproduced via the desktop app surface)
• Custom command: ~/.claude/commands/resume.md (a personal session-checkpoint restore command, paired with a working /pause custom command)

Repro

1. Create ~/.claude/commands/resume.md with any instructions.
2. Type /resume in the composer.
3. The built-in conversation picker opens ("No sessions match your search" when empty). The custom command markdown is never dispatched.

Control: a custom command with a non-colliding name (e.g. /pause) in the same directory dispatches normally, confirming custom-command dispatch works and the failure is specific to the name collision.

Version bracket (local forensics)

Grepping cached release bundles for the built-in picker's empty-state string "No sessions match":

| Version | Bundle date | String present |
|---|---|---|
| 2.1.25 | 2026-01-29 | no |
| 2.1.97 | 2026-04-08 | yes |
| 2.1.172 (running) | 2026-06-10 | yes |

So the built-in picker (and the shadowing) arrived between 2.1.25 and 2.1.97. No changelog entry documents the precedence behavior.

Docs gap

• commands.md lists /resume as built-in but says nothing about collisions with custom commands.
• skills.md ("When skills share the same name") documents skill-vs-skill and skill-vs-custom-command precedence, but not built-in-command-vs-custom precedence.
• No namespacing (/user:resume), no "(user)"-labeled menu entry, and no setting appears to exist to reach the shadowed custom command.

Expected

One of:

1. Custom commands take precedence over built-ins (matching the spirit of the v2.1.228 change "Hardened skills synced from claude.ai: they no longer shadow local commands"), or
2. A documented disambiguation path (namespaced invocation or a labeled second entry in the slash menu), or
3. At minimum: documented precedence in commands.md/skills.md, and a warning at startup or in /doctor when a user/project command is shadowed by a built-in.

Actual

The built-in wins silently. The user's workflow broke with no signal; diagnosing required grepping release bundles to establish when the built-in appeared.

Workaround used

Renamed the custom command to a non-colliding name (/unpause).

🤖 Generated with Claude Code