[BUG] Task Tool Error: Tool names must be unique - Cannot spawn subagents

[Cmacu]

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: Task Tool - Duplicate Tool Names Error

Date: 2025-11-04 Reporter: Stasi Vladimirov Claude Code Version: 2.0.30 Severity: Critical - Blocks all agent invocations

Summary

The Task tool fails to spawn subagents with error: "tools: Tool names must be unique". This occurs because the tool merging logic doesn't deduplicate tools when creating subagents, causing all inherited tools to be registered twice.

Error Message

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "tools: Tool names must be unique."
  }
}

Attempted Workarounds (All Failed)

Test 1: Remove Task from subagent tools

Action: Removed Task tool from agent configurations to prevent recursion Result: Still failed with duplicate error Files Modified: .claude/agents/frontend-unit-test-writer.md

Test 2: Remove non-existent tools

Action: Removed LS, MultiEdit, mcp__ide__* tools that don't exist Result: Still failed with duplicate error Files Modified: 3 agent configuration files

Test 3: Add missing MCP tools

Action: Added mcp__ide__getDiagnostics, mcp__ide__executeCode to system Result: Still failed with duplicate error

Test 4: Remove ALL tool definitions

Action: Removed all tools: lines from agent configs to rely on inheritance Result: Still failed with duplicate error Files Modified: All 4 agents with explicit tool lists

Root Cause Analysis

The Task tool implementation appears to merge parent and subagent tools without deduplication:

// Suspected current implementation (broken)
function createSubagent(parentTools, agentConfig) {
  const agentTools = agentConfig.tools || getAllTools();
  const mergedTools = [...parentTools, ...agentTools]; // ❌ Creates duplicates!
  return createAgent(mergedTools);
}

When merging:

• Parent has: [Bash, Glob, Grep, Read, Edit, ...]
• Subagent needs: [Bash, Glob, Grep, Read, Edit, ...]
• Result: Every tool is duplicated → Error

Impact

Critical: Completely blocks agent system functionality:

• ❌ Cannot use any specialized agents
• ❌ Cannot follow multiverse agent workflows
• ❌ Must bypass agent policy for all development work
• ❌ Violates project's mandatory agent usage guidelines

Affected Agents (All 17 agents in .claude/agents/):

• Pep Guardiola - form-schema-implementer
• Pierluigi Collina - frontend-unit-test-writer
• Diego Maradona - frontend-staff-engineer
• Cristiano Ronaldo - cosmos-ui-engineer
• Roberto Carlos - api-controller-architect
• Diego Forlan - mobx-state-optimizer
• Chuky Lozano - typescript-resolver
• Gianluigi Buffon - accessibility-auditor
• Zinedine Zidane - Architecture Guardian
• David Beckham - performance-optimizer
• Lionel Messi - git-workflow-manager
• And 6 more...

Environment

- OS: macOS (Darwin 24.6.0)
- Claude Code Version: 2.0.30
- Installation: Homebrew Cask
- Path: /opt/homebrew/Caskroom/claude-code/2.0.30/claude
- Node.js: v22.13.1

Workaround

Currently no workaround exists. Must proceed with manual implementation, violating project's agent usage policy.

Files Modified During Investigation

• .claude/agents/frontend-unit-test-writer.md - Removed problematic tools
• .claude/agents/frontend-requirements-planner.md - Removed problematic tools
• .claude/agents/architecture-guardian.md - Removed problematic tools
• .claude/agents/form-schema-implementer.md - Removed problematic tools
• All 4 files: Removed ALL tool definitions as final test

Requested Fix

Please implement tool deduplication in the Task tool's subagent creation logic. Recommended approach is Option 1 (inheritance) as it's cleanest and subagents don't need different tools than their parent.

What Should Happen?

Expected Behavior

Subagents should either:

Option 1: Inherit parent tools (Recommended)

function createSubagent(parentTools, agentConfig) {
  // Subagents simply inherit all parent tools
  return createAgent({
    tools: parentTools,
    prompt: agentConfig.prompt,
    model: agentConfig.model
  });
}

Option 2: Deduplicate before merging

function createSubagent(parentTools, agentConfig) {
  const parentToolNames = new Set(parentTools.map(t => t.name));
  const agentTools = agentConfig.tools || [];

  // Filter out tools that parent already has
  const uniqueAgentTools = agentTools.filter(
    toolName => !parentToolNames.has(toolName)
  );

  return createAgent({
    tools: [...parentTools, ...uniqueAgentTools],
    prompt: agentConfig.prompt,
    model: agentConfig.model
  });
}

Option 3: Subagent-specific tools only

function createSubagent(parentTools, agentConfig) {
  // Only add tools explicitly needed by subagent
  const parentToolNames = new Set(parentTools.map(t => t.name));
  const subagentOnlyTools = (agentConfig.tools || [])
    .filter(toolName => !parentToolNames.has(toolName));

  return createAgent({
    tools: [...parentTools, ...subagentOnlyTools],
    prompt: agentConfig.prompt,
    model: agentConfig.model
  });
}

Error Messages/Logs

## Logs


API Error: 400
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "tools: Tool names must be unique."
  },
  "request_id": "req_011CUomUf7SzKkUtQ1f9ATK3"
}

Steps to Reproduce

Steps to Reproduce

1. Have a parent agent with tools: Bash, Glob, Grep, Read, Edit, Write, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, AskUserQuestion, Task, ...
2. Attempt to invoke a subagent using Task tool
3. Subagent configuration either:
   • Has explicit tools: list with same tools as parent
   • Has no tools: list (inherits "All tools")
4. Error occurs regardless of configuration

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.0.30 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

No response

[dhofheinz]

Confirmed Reproduction - Base Task Tool Failure (No MCP)

Reproducing this issue without any MCP servers configured - this affects core Task tool functionality.

Environment

• Claude Code Version: Latest (2.0.30+)
• Platform: Linux/WSL2 (6.6.87.2-microsoft-standard-WSL2)
• MCP Servers: None configured

All Subagents Fail

✗ general-purpose → API Error 400 "tools: Tool names must be unique"
✗ Explore         → API Error 400 "tools: Tool names must be unique"
✗ Plan            → API Error 400 "tools: Tool names must be unique"

Regression of #10668

This appears to be a regression. Issue #10668 was closed as fixed with:

"Fixed MCP tools not being available to sub-agents" (v2.0.30)

The fix may have introduced tool duplication during subagent initialization, breaking Task tool even for users without MCP.

[pragmatic-ai-expert]

Seeing the same issue on latest version of claude code

[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.