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

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")

1. 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_