Bug Report: Custom Agent Fails with "Tool names must be unique" Error

Preflight Checklist

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

What's Wrong?

Bug Report: Custom Agent Fails with "Tool names must be unique" Error

Description

When attempting to invoke a custom agent using the Task tool, Claude Code returns a 400 error with the message "tools: Tool names must be unique." even though the
agent configuration file does not define any custom tools.

Environment

• Platform: Windows (win32)
• Claude Code Version: 2.0.30
• Model: claude-sonnet-4-5-20250929
• Agent Location: C:\Users\mvmak\.claude\agents\thai-pay-assistant.md

Actual Behavior

The Task tool returns an error:
API Error: 400 {
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "tools: Tool names must be unique."
}
}

Agent Configuration File

The agent configuration does NOT define any custom tools:

---
name: thai-pay-assistant
description: Use this agent when the user needs help with their thai-pay project, including tasks such as:\n\n<example>\nContext: User is working on the thai-pay
project and needs architecture guidance.\nuser: "I need to add a new payment provider to thai-pay. What's the best approach?"\nassistant: "Let me use the Task tool to
launch the thai-pay-assistant agent to help you design the payment provider integration."\n<commentary>\nThe user is asking for help with their thai-pay project
specifically about adding functionality, so use the thai-pay-assistant agent.\n</commentary>\n</example>\n\n<example>\nContext: User mentions working on thai-pay and
needs debugging help.\nuser: "The QR code generation in thai-pay isn't working correctly"\nassistant: "I'll use the Task tool to launch the thai-pay-assistant agent to
help debug the QR code generation issue."\n<commentary>\nThis is a thai-pay specific problem, so delegate to the specialized
agent.\n</commentary>\n</example>\n\n<example>\nContext: User is reviewing code and mentions thai-pay.\nuser: "Can you review this payment validation logic I just
wrote for thai-pay?"\nassistant: "Let me use the Task tool to launch the thai-pay-assistant agent to review your payment validation
code."\n<commentary>\nProject-specific code review for thai-pay should go to the specialized agent.\n</commentary>\n</example>\n\n<example>\nContext: User proactively
mentions the project.\nuser: "I'm going to start working on the thai-pay refund feature"\nassistant: "I'll use the Task tool to launch the thai-pay-assistant agent to
help you plan and implement the refund feature."\n<commentary>\nThe user is about to work on thai-pay, so proactively engage the specialized
agent.\n</commentary>\n</example>
model: sonnet
---

You are an expert software engineer and architect specializing in Thai payment systems, mobile payment solutions, and financial technology integration. You have deep
knowledge of:

• Thai payment ecosystems (PromptPay, QR code standards, Thai banking APIs)
• Payment processing architecture and security best practices
• Mobile payment integrations and wallet systems
• PCI DSS compliance and financial regulations in Thailand
• Modern backend development patterns for payment systems
• Error handling and reconciliation in payment flows

[... rest of system prompt - no tool definitions ...]

Analysis

The error message "Tool names must be unique" suggests that Claude Code is internally duplicating tool definitions when setting up the agent context. Since the agent
configuration doesn't define any custom tools, this appears to be a bug in how Claude Code merges:

• System tools (Read, Write, Bash, Grep, etc.)
• Agent-specific tool configurations

Impact

This bug makes custom agents completely unusable. Users cannot leverage project-specific agents for specialized assistance, which is a core feature of Claude Code.

Workaround

None currently available. The agent functionality is completely broken for this use case.

Additional Context

• The agent shows up correctly in the /context command output as "Custom agents"
• The agent configuration is valid YAML/Markdown frontmatter
• The same error occurs regardless of agent complexity or prompt content
• No custom tools are defined in the agent file - only a system prompt

Request

Please investigate the tool registration/merging logic when launching custom agents via the Task tool to identify where duplicate tool names are being created.

---
Attachment: Full agent configuration file provided above

---
You can copy this directly to the GitHub issues page at https://github.com/anthropics/claude-code/issues. Just remember to fill in your Claude Code version number!

What Should Happen?

The agent should launch successfully and have access to all standard system tools (Read, Write, Bash, Grep, Glob, etc.) without conflicts.

Error Messages/Logs

The error message "Tool names must be unique" suggests that Claude Code is internally duplicating tool definitions when setting up the agent context. Since the agent      
  configuration doesn't define any custom tools, this appears to be a bug in how Claude Code merges:
  - System tools (Read, Write, Bash, Grep, etc.)
  - Agent-specific tool configurations

Steps to Reproduce

1. Create a custom agent configuration file at ~/.claude/agents/thai-pay-assistant.md with the following structure:

---
name: thai-pay-assistant
description: Use this agent when the user needs help with their thai-pay project...
model: sonnet
---

[System prompt with no custom tool definitions]

1. In a Claude Code session, attempt to invoke the agent:

User: "Use the thai-pay-assistant agent to review my thai-pay project"

1. Claude attempts to call the Task tool:

Task({
subagent_type: "thai-pay-assistant",
description: "Review thai-pay project",
prompt: "Please review the project..."
})

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.30

Platform

Other

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_