[BUG] Claude-code does not call subagents anymore

[rezaalavi]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

After upgrading to version 2 I can't no longer call @agent-[agent-name] to call subagents.
CLI doesn't show my subagents when I type @agent- and when I manually type it claude doesn't call it and instead make a generic TASK

What Should Happen?

Like before it should call the subagent as instructed.

Error Messages/Logs

Steps to Reproduce

1. Create a markdown subagent inside .claude/agents/myagent.md
2. prompt "using @agent-myagent implement the function'

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

v2.0.1

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

No response

[Notum]

I can confirm this bug.
Agent won't start even after direct command to do so:

 As ruby on rails developer proceed with the complex task bellow.
 Use internal memory and you should complete ALL TASKS bellow.
 Do not stop until all phases are completed, ignore any time terms.

[wdelhagen]

I am also experiencing this.

After recent update either to v2 or to a minor update that got pushed subagents in ~/.claude/agents/ are no longer recognized and slash commands are intermittently recognized and absent.

/agents command shows no currently active agents but no change has been made to filesystem or agent definition files and subagents have been working as documented for months.

Some claude sessions are recognizing and auto-completing custom slash commands in ~/.claude/commands and some sessions are not, all on the same machine.

Environment Info

• Platform: darwin
• Terminal: iTerm.app
• Version: 2.0.5
• Feedback ID: 0b9ac650-71c5-47a6-96f7-cbd24cb085cd

 Diagnostics
 └ Currently running: native (2.0.5)
 └ Path: /Users/willd/.local/bin/claude
 └ Invoked: /Users/willd/.local/share/claude/versions/2.0.5
 └ Config install method: native
 └ Auto-updates enabled: default (true)
 └ Search: OK (bundled)

[wdelhagen]

More observations:

1. start claude session
2. /agents command shows no custom agents
3. claude reports no custom agents available to delegate to
4. /agents command > "Create new agent" and follow workflow for "Personal" until completion
5. .md file created in ~/.claude/agents/ alongside many other existing subagent files. Format appears consistent with same yaml frontmatter and subagent prompt
6. /agents now shows the new agent created in [step 4]
7. claude now recognizes and can delegate to new agent created in [step 4]
8. exit claude session
9. start new claude session in same cwd
10. /agents command shows no custom agents
11. claude reports no custom agents available to delegate to

Same behavior when reproducing with "Project"-level subagent.

[wdelhagen]

Claude agrees

> /agents
  ⎿  Agents dialog dismissed

> what subagents are available to delegate to?

⏺ Three subagent types are available via the Task tool:

  1. general-purpose - Researches complex questions, searches for code, executes multi-step tasks (has
   access to all tools)
  2. statusline-setup - Configures Claude Code status line settings (Read, Edit tools)
  3. output-style-setup - Creates Claude Code output styles (Read, Write, Edit, Glob, Grep tools)

  You launch them by specifying the subagent_type parameter when using the Task tool.

> list the contents of .claude/agents/

⏺ Bash(ls -la .claude/agents/)
  ⎿  total 16
     drwx------  3 willd  staff    96 Oct  3 17:20 .
     drwx------  4 willd  staff   128 Oct  3 17:20 ..
     -rw-r--r--  1 willd  staff  7516 Oct  3 17:20 architecture-designer.md

⏺ One file: architecture-designer.md

> list the contents of ~/.claude/agents/

⏺ Bash(ls -la ~/.claude/agents/)
  ⎿  total 288
     drwxr-xr-x  17 willd  staff    544 Oct  3 16:58 .
     drwxr-xr-x  23 willd  staff    736 Oct  3 17:24 ..
     … +15 lines (ctrl+o to expand)

⏺ 15 agent files in ~/.claude/agents/:

  - acceptance-criteria-reviewer.md
  - api-reference-drafter.md
  - code-reviewer.md
  - design-reviewer.md
  - developer.md
  - development-auditor.md
  - document-editor.md
  - milestone-manager.md
  - prompt-reviewer.md
  - requirements-reviewer.md
  - test-debt-remediator.md
  - test-quality-auditor.md
  - test-reviewer.md
  - valet-organizer.md

> are all of these files valid subagent definition files?

⏺ Fetch(https://docs.claude.com/en/docs/claude-code/claude_code_docs_map.md)
  ⎿  Received 27.5KB (200 OK)

⏺ Fetch(https://docs.claude.com/en/docs/claude-code/sub-agents.md)
  ⎿  Received 14.1KB (200 OK)

⏺ Read(~/.claude/agents/code-reviewer.md)
  ⎿  Read 190 lines (ctrl+o to expand)

⏺ Read(~/.claude/agents/developer.md)
  ⎿  Read 152 lines (ctrl+o to expand)

⏺ Bash(head -10 ~/.claude/agents/*.md | grep -E "(^==>|^---$|^name:|^description:)" | head -40)
  ⎿  ==> /Users/willd/.claude/agents/acceptance-criteria-reviewer.md <==
     ---
     name: acceptance-criteria-reviewer
     … +89 lines (ctrl+o to expand)

⏺ Bash(for file in ~/.claude/agents/*.md; do echo "==> $(basename "$file") <=="; head -10 "$file" | grep
      -E "^(name:|description:)" || echo "MISSING REQUIRED FIELDS";…)
  ⎿ ==> acceptance-criteria-reviewer.md <==
    name: acceptance-criteria-reviewer
    description: Use this agent when you need to verify project completion against acceptance criteri
    … +169 lines (ctrl+o to expand)


⏺ Yes, all 15 files in ~/.claude/agents/ are valid subagent definition files. They all contain:

  Required fields:
  - name: Unique identifier (lowercase with hyphens)
  - description: Purpose description

  Common optional fields:
  - tools: Comma-separated list of allowed tools
  - model: Model to use (e.g., 'sonnet')
  - color: Display color (not in official docs but supported)

  All files follow the proper format: YAML frontmatter delimited by ---, followed by a detailed system
   prompt defining the agent's behavior.

[wdelhagen]

@rezaalavi I want to confirm this is the same issue. Are the subagents also not registered when you use the /agents slash command? If this is just about the @-mention function but the subagents are otherwise available then it's not the same bug.

[wdelhagen]

The issue has resolved on my system. I didn't make any changes, but I am no longer able to reproduce the behavior.

[Notum]

I still have this issue, even re-creating an agent and trying to call him in direct way - it doesn't "Turn On".

[ChrisSc]

Parent agent won't call a subagent, even if included in instruction. All I've done is burn output tokens. This is fundamentally broken on MacOs.

[rezaalavi]

For me the original issue that I reported is now fixed.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.