Bug Report: Task Tool Error - Unique Tool Names Required

by Admin 57 views
Bug Report: Task Tool Error - Unique Tool Names Required

Hey guys,

We've got a critical bug report on our hands that's completely blocking agent system functionality. It's all about the Task tool throwing an error because it's not handling unique tool names properly when spawning subagents. Let's dive into the details and figure out what's going on.

What's the Issue?

The core problem is that the Task tool is failing to spawn subagents, and it's throwing this error: "tools: Tool names must be unique". This happens because the logic for merging tools isn't deduplicating them when a subagent is created. Basically, all the tools inherited from the parent agent are getting registered twice. Not cool!

Error Message

Here's the exact error message we're seeing:

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

Attempted Workarounds (Spoiler: None Worked)

Our intrepid reporter, Stasi Vladimirov, tried a bunch of different things to get around this, but no dice:

  1. Removing Task from subagent tools: The idea was to prevent recursion, but it still failed with the same duplicate error.
  2. Removing non-existent tools: There were some tools listed that didn't even exist (LS, MultiEdit, mcp__ide__*), but removing them didn't fix the issue.
  3. Adding missing MCP tools: Stasi tried adding mcp__ide__getDiagnostics and mcp__ide__executeCode, but still no luck.
  4. Removing ALL tool definitions: As a last resort, all tools: lines were removed from the agent configs to rely on inheritance, but it still failed. Ouch!

Root Cause Analysis: The Code Detective Work

Okay, so what's actually causing this? It looks like the Task tool implementation is merging the parent and subagent tools without checking for duplicates. Here's a snippet of what the broken code might look like:

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

When this function merges the tools:

  • The parent agent has tools like [Bash, Glob, Grep, Read, Edit, ...]
  • The subagent needs the same tools: [Bash, Glob, Grep, Read, Edit, ...]
  • The result? Every tool is duplicated, leading to the dreaded error.

This is where our SEO keywords come in handy. We can see that issues like "duplicate tools", "subagent creation error", and "Task tool bug" are central to this problem. By addressing these issues directly, we improve both the user experience and the article's visibility.

Impact: This is a Big Deal!

This bug is classified as critical because it's completely blocking the agent system. This means:

  • ❌ We can't use any specialized agents.
  • ❌ Multiverse agent workflows are a no-go.
  • ❌ We have to bypass the agent policy for all development work.
  • ❌ It violates the project's mandatory agent usage guidelines.

Basically, it's a mess. And it's affecting all 17 agents in the .claude/agents/ directory, including agents with colorful names like:

  • Pep Guardiola - form-schema-implementer
  • Pierluigi Collina - frontend-unit-test-writer
  • Diego Maradona - frontend-staff-engineer
  • Cristiano Ronaldo - cosmos-ui-engineer
  • ...and many more!

Environment Details

Here's the environment where this bug was found:

- 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

No Workaround? Seriously?

Yep, you read that right. There's currently no workaround. We're stuck with manual implementation, which totally goes against the project's agent usage policy. This highlights the importance of robust error handling and the need for thorough testing of agent interactions.

Files Modified During the Investigation

Stasi made some changes while trying to fix this, including:

  • .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 a final test

The Requested Fix: Deduplication, Please!

The solution here is pretty clear: we need to implement tool deduplication in the Task tool's subagent creation logic. Stasi suggests Option 1 (inheritance) as the cleanest approach, since subagents don't really need different tools than their parents. This is a key SEO consideration because search engines value solutions that are simple and effective.

Expected Behavior: How Subagents Should Handle Tools

Ideally, subagents should handle tools in one of these ways:

Option 1: Inherit Parent Tools (Recommended)

This is the simplest and most efficient solution. The subagent just inherits all the tools from its parent.

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

If we need to merge tools, we should deduplicate them first to avoid conflicts.

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

This approach only adds tools that are explicitly needed by the subagent and not already present in the parent.

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
 });
}

These code snippets demonstrate potential solutions and are great for SEO as they show the technical depth of the analysis and proposed fixes. Using code examples makes the content more valuable and helps other developers facing similar issues.

Error Messages and Logs

Here's the error we're seeing in the 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: Let's Break It Again!

Want to see this bug in action? Here's how to reproduce it:

  1. Start with a parent agent that has a bunch of tools: Bash, Glob, Grep, Read, Edit, Write, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, AskUserQuestion, Task, ...
  2. Try to invoke a subagent using the Task tool.
  3. Configure the subagent in one of these ways:
    • Give it an explicit tools: list with the same tools as the parent.
    • Don't give it a tools: list at all (so it inherits