Custom agents in ~/.claude/agents/ not detected — multiple discovery and UI bugs (v2.1.89)

Summary

Custom agents placed in ~/.claude/agents/ are not discovered by Claude Code. Multiple related bugs make the agent creation/editing workflow unreliable.

Environment

• Claude Code v2.1.89
• macOS (Darwin), Apple Silicon
• Installed via npm global

Bug 1: Manually created agent files are not detected

Steps to reproduce:

1. Create ~/.claude/agents/my-agent.md with valid frontmatter (name, description, model, etc.)
2. Start a new Claude Code session
3. Run claude agents or check /agents UI

Expected: Agent appears in the list
Actual: Agent is not found. Error when invoking: Agent type 'my-agent' not found

Workaround: Create the agent through the /agents → "Create new agent" → "Personal" UI flow. Only this path registers the agent correctly.

Bug 2: claude agents CLI never shows user agents

Steps to reproduce:

1. Create an agent via the /agents UI (it appears in the interactive list as "User agents")
2. Run claude agents from a terminal

Expected: User agents appear alongside plugin and built-in agents
Actual: Only shows plugin and built-in agents (always shows N agents, never includes user agents). The agent still works inside sessions — this is a display-only bug.

Bug 3: Overwriting agent file with Write tool breaks detection

Steps to reproduce:

1. Create agent via /agents UI (works correctly)
2. Use the Write tool (full file rewrite) to replace the file contents
3. Agent disappears from /agents list and stops being invocable

Expected: Modified file is still detected
Actual: Agent silently disappears. Must delete and recreate via UI.

Workaround: Use the Edit tool (diff-based edits) instead of Write. Diff edits preserve detection; full rewrites break it. Likely related to inode or file metadata changes.

Bug 4: /agents UI terminal corruption when pasting multiline text

Steps to reproduce:

1. /agents → Create new agent → Manual configuration
2. At the "System prompt" step, paste multiline text (Cmd+V) or return from the external editor (ctrl+g)
3. Terminal becomes unresponsive — escape sequences are printed (^[[O^[[I), arrow keys and Enter stop working

Expected: Text is accepted or editor content is loaded
Actual: Terminal is corrupted. Only Ctrl+C recovers. Happens consistently, both inside and outside wrapper scripts.

What I tried that didn't help

• Reinstalling Claude Code via npm
• Moving file from subdirectory (agents/my-agent/AGENT.md) to flat (agents/my-agent.md)
• Different YAML formatting (quoted vs unquoted values, with/without special characters)
• Creating file via Bash (cat heredoc) vs Write tool
• Running claude agents from different working directories