[BUG] Custom agent fails with "Tool names must be unique" API error after upgrade to 2.x.x

[marc0der]

Bug Description

After upgrading to Claude Code 2.x.x, a previously working custom agent now fails with API error: {"type":"error","error":{"type":"invalid_request_error","message":"tools: Tool names must be unique."}

This is a regression - the same agent worked perfectly in Claude Code 1.x.x and broke after the upgrade to 2.x.x with no changes to the agent definition.

Custom Agent Definition

The custom agent is defined in ~/.claude/agents/git-guy.md:

---
name: Git Guy
description: Use this agent when you need to commit code changes with properly formatted commit messages that follow conventional commit standards. Examples: <example>Context: User has just implemented a new feature and wants to commit their changes. user: 'I just added a new user registration endpoint to the API. Can you commit these changes?' assistant: 'I'll use Git Guy to create a properly formatted commit for your new user registration endpoint.' <commentary>Since the user wants to commit code changes, use Git Guy to handle the commit with proper formatting and conventional commit standards.</commentary></example> <example>Context: User has fixed a bug and wants to commit the fix. user: 'Fixed the null pointer exception in the payment processing module' assistant: 'Let me use Git Guy to commit this bug fix with the proper commit message format.' <commentary>The user has made a bug fix and needs it committed, so use Git Guy to ensure proper commit message formatting.</commentary></example>
color: red
---

[Agent instructions omitted for brevity - full template follows standard agent format with git commit workflow]

Steps to Reproduce

1. Create a custom agent in `claude/agents/git-guy.md` with the name "Git Guy"
2. Make changes to a file and stage them with git
3. Attempt to invoke the agent using the Task tool:

Task(subagent_type="Git Guy", description="Commit changes", prompt="Commit the staged changes...")

4. Receive API error about duplicate tool names

Expected Behavior

The custom "Git Guy" agent should launch and execute its defined workflow, as it did in Claude Code 1.x.x

Actual Behavior

API returns error: `tools: Tool names must be unique.` with request_id similar to `req_011CUrZkdGPQXjoby6DWd2S9`

Environment

• Platform: Linux (NixOS)
• Claude Code version: 2.x.x (regression from 1.x.x where it worked)
• Repository: Local git repository with custom agent defined
• Date: 2025-11-06

Additional Context

• Worked in 1.x.x, broke in 2.x.x - no changes were made to the agent definition
• The agent name contains a space: "Git Guy"
• No other custom agents are defined
• The agent is properly formatted with frontmatter and description
• Agent appears in Claude's available agents list during conversation
• Error occurs consistently across multiple invocation attempts
• ~/.claude/settings.local.json only contains permission allowlists, no other configuration

Possible Causes

The error message "Tool names must be unique" suggests the 2.x.x upgrade may have introduced:

1. Changes to how agent names with spaces are handled
2. A new internal tool name collision with custom agents
3. Changes to the custom agent registration system
4. Stricter tool name validation

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.