KBCodeKB
Claude CodeModel Context ProtocolUnverified

Fix Claude Code Task Agent 'tools: Tool names must be unique' API Error (400) When Spawning Subprocess with MCP Tools

Claude Code v2.0.30 introduced a regression in subprocess tool inheritance that causes Task agent spawns to fail with API Error 400: 'tools: Tool names must be unique'. Core tools, MCP tools from multiple servers, and custom agent tools are incorrectly deduplicated during subprocess initialization, producing duplicate tool names that the Anthropic API rejects. Affects all built-in subagents (Explore, Plan, general-purpose), custom agents defined in .claude/agents/, and the /sidequest command. The main Claude Code session functions normally — only subprocess launches fail. Anthropic staff confirmed and shipped the fix in v2.0.31 within 6 hours of the report. Multiple community-confirmed workarounds available: downgrade to v2.0.29, temporarily disable MCP servers before agent launch, or pin npx to v2.0.29 in shell aliases.

Symptoms

  • Task agent subprocess immediately fails with API Error 400: 'tools: Tool names must be unique'
  • All built-in subagents (Explore, Plan, general-purpose) return 'Done (0 tool uses · 0 tokens · 1s)' without executing
  • Custom agents defined in .claude/agents/ fail to launch
  • /sidequest command non-functional — background agents cannot start
  • Main Claude Code session works perfectly with all MCP tools; only subprocess spawns fail
  • Error persists across session restarts and new chats on v2.0.30

Error signatures

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools: Tool names must be unique."}}
Done (0 tool uses · 0 tokens · 1s)

Possible causes

  • Claude Code v2.0.30 changelog states 'Fixed MCP tools not being available to sub-agents' — the attempted fix introduced a regression where tool deduplication fails during subprocess serialization/deserialization
  • During Task agent subprocess initialization, tools from core toolset, MCP server tool lists, and custom agent definitions are combined incorrectly, producing duplicate tool names even when all parent-process tools are properly namespaced
  • Tool inheritance serialization between parent and child Claude Code process does not guarantee uniqueness across merged tool sources
  • Edge case: even a single MCP server or zero MCP servers can trigger the bug if custom agents are defined — the deduplication bug is in the general subprocess tool merging path, not MCP-specific

Solutions

Solution 3 (Permanent): Upgrade to Claude Code v2.0.31 or Later

risk: lowofficialpending_review

Anthropic staff (@ashwin-ant) shipped the fix in v2.0.31 on the same day the bug was reported (Oct 31, 2025). The fix corrects tool deduplication in the subprocess initialization path. All versions ≥ 2.0.31 include the fix. This is the recommended permanent resolution.

  1. Check current version: claude --version
  2. Upgrade to latest: npm install -g @anthropic-ai/claude-code@latest
  3. Verify version ≥ 2.0.31: claude --version
  4. Launch Claude Code and test Task agent with all MCP servers enabled
  5. Confirm /sidequest and custom agents work with full MCP tool access

Commands

npm install -g @anthropic-ai/claude-code@latest
npm install -g @anthropic-ai/claude-code@2.0.31
claude --version
npx @anthropic-ai/claude-code@2.0.31

Config examples

{
  "// shell-alias-for-temporary-pin": "Add to .zshrc or .bashrc for temporary pin",
  "alias": "alias claude='npx @anthropic-ai/claude-code@2.0.31'"
}

Risks

  • Later versions (2.1.x) introduce breaking changes — review changelog before upgrading past 2.0.x if stability is critical
  • If using claude-agent-sdk, ensure SDK version parity: v0.1.31+ corresponds to CLI v2.0.31+

Verification

  • Run claude --version → expect version ≥ '2.0.31' (e.g., '2.0.37' or '2.1.170')
  • Launch Claude Code with 10+ MCP servers configured and run /sidequest 'summarize this project' → expect agent spawns, uses tools from both core and MCP sets, and returns summary (tool uses ≥ 3, no 400 API error)
  • Run custom agent from .claude/agents/ with MCP servers enabled → expect normal execution with MCP tool access
  • Verify no 'Tool names must be unique' error appears in any output
✓ 0 verified✕ 0 failed

Solution 2 (Workflow): Temporarily Disable MCP Servers Before Task Agent Invocation

risk: lowgithubpending_review

Use the /mcp command in Claude Code to disable MCP servers before spawning Task agents or running /sidequest, then re-enable them afterward. This avoids the tool merging bug by reducing the tool count during subprocess initialization. Confirmed working on v2.0.30 without downgrading.

  1. In active Claude Code session, run /mcp to open the MCP server manager
  2. Disable all MCP servers (toggle each off)
  3. Relaunch Claude Code (Ctrl+C then claude to restart session)
  4. Resume the previous session using the resume prompt
  5. Execute Task agent or /sidequest — should work now with core tools only
  6. After Task agent completes, re-enable MCP servers via /mcp

Risks

  • Task agents run without MCP tool access — tasks requiring MCP tools must be executed in main process
  • Session resume may not preserve full context for all workflows
  • Frequent MCP toggle is disruptive for MCP-heavy workflows

Verification

  • After disabling MCP servers and relaunching, run /sidequest 'read README.md' → expect agent uses Read tool and returns file contents (tool uses ≥ 1)
  • Re-enable MCP servers and verify they appear in /mcp list
  • Main process continues to function with MCP tools after re-enabling
✓ 0 verified✕ 0 failed

Solution 1 (Immediate): Downgrade to Claude Code v2.0.29

risk: lowgithubpending_review

Revert to v2.0.29 which does not have the subprocess tool deduplication regression. All Task agents, custom agents, and /sidequest work correctly on v2.0.29 with any number of MCP servers. Multiple community members confirmed this restores full functionality immediately.

  1. Check current Claude Code version: claude --version
  2. Uninstall v2.0.30 if globally installed: npm uninstall -g @anthropic-ai/claude-code
  3. Install v2.0.29: npm install -g @anthropic-ai/claude-code@2.0.29
  4. Verify version: claude --version → expect 2.0.29
  5. Launch Claude Code and test Task agent or /sidequest — expect normal subprocess execution with tool usage > 0

Commands

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@2.0.29
claude --version

Risks

  • Missing features or fixes introduced in v2.0.30 (consult changelog)
  • npm cache may serve stale version — use npx for guaranteed version pinning

Verification

  • Run claude --version → expect '2.0.29'
  • Launch Claude Code and type /sidequest 'list files in current directory' → expect agent spawns and executes file listing tools (tool uses > 0, not '0 tool uses · 0 tokens · 1s')
  • With MCP servers configured, run any custom agent from .claude/agents/ → expect agent launches and uses both core and MCP tools normally
  • Check no 400 API errors appear in Claude Code output
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "cc0e03f9-bcc0-4dea-ac15-8dc14acedde5",
  "slug": "fix-claude-code-task-agent-tools-tool-names-must-be-unique-api-error-400-when-spawning-subprocess-with-mcp-tools-vahtdz",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-code-task-agent-tools-tool-names-must-be-unique-api-error-400-when-spawning-subprocess-with-mcp-tools-vahtdz"
}
← Back to all issuesPowered by CodeKB
Fix Claude Code Task Agent 'tools: Tool names must be unique' API Error (400) When Spawning Subprocess with MCP Tools · CodeKB