Custom agents lose file tools when spawned with team_name

Summary

Custom agents defined in ~/.claude/agents/ lose all file manipulation tools (Read, Glob, Grep, Edit, Write, Bash) when spawned as teammates using the team_name parameter in the Task tool. They retain only team communication tools (SendMessage, TaskCreate, TaskGet, TaskList, TaskUpdate). The same agents work correctly when spawned standalone (without team_name).

Environment

• Platform: Claude Code CLI
• OS: WSL2 (Ubuntu on Windows)
• Custom Agents Location: ~/.claude/agents/*.md
• Affected Agent Types: All custom agents registered at session start

Reproduction Steps

Minimal Reproduction

1. Create a custom agent file at ~/.claude/agents/my-agent.md:

```markdown
---
name: my-agent
description: Test agent
tools:

• Read
• Glob
• Grep
• Bash
• Edit
• Write

---

You are a helpful agent.
```

1. Start a new Claude Code session (important - agent must be in registry at session start)

1. Create a team and spawn the agent:

```python
# Create team
TeamCreate(team_name="test-team")

# Spawn custom agent in team mode
Task(
subagent_type="my-agent",
team_name="test-team",
name="worker",
instruction="List your available tools"
)
```

1. Observe: Agent only has 5 tools (SendMessage + Task management), missing all file tools

1. Control test: Spawn the same agent standalone:

``python
Task(
subagent_type="my-agent",
instruction="List your available tools"
)
``

1. Observe: Agent has all 16+ tools including Read, Glob, Grep, Bash, Edit, Write

Expected Behavior

Custom agents spawned with team_name should have:

• All tools specified in their tools: whitelist (if defined)
• OR all file tools by default (if no whitelist)
• PLUS team communication tools (SendMessage, Task management)

Actual Behavior

Custom agents spawned with team_name only receive:

• SendMessage
• TaskCreate
• TaskGet
• TaskList
• TaskUpdate

All file manipulation tools are missing, making them unable to read code, search files, or perform any file operations.

Root Cause Analysis

The bug occurs when ALL of these conditions are met:

1. Agent is a custom agent (defined in ~/.claude/agents/)
2. Agent's name: field matches an entry in the Task tool's agent type registry (populated at session start from discovered custom agents)
3. Agent is spawned with team_name parameter

Why it happens: When Claude Code starts a session, it discovers custom agents and registers them in the Task tool's available agent types. When these pre-registered agents are spawned in team mode, there appears to be a tool resolution conflict between the custom agent's definition and team-mode tool injection, resulting in only team-communication tools being granted.

Evidence supporting this theory:

• Built-in agent types (general-purpose, Explore) work correctly in team mode
• Custom agents created DURING a session (not in original registry) work correctly in team mode
• Custom agents spawned standalone (no team_name) work correctly
• The bug is deterministic and reproducible 100% of the time for registered custom agents

Test Matrix Summary

| Agent Type | Pre-registered? | Team Mode? | Tools Available | Result |
|-----------|----------------|-----------|----------------|--------|
| my-agent (custom) | Yes | Yes | 5 (team only) | FAIL |
| my-agent (custom) | Yes | No | All 16+ | PASS |
| my-agent-clone (custom) | No (created this session) | Yes | All 18 | PASS |
| general-purpose (built-in) | N/A | Yes | All 16+ | PASS |

Workarounds

Workaround 1: Spawn Standalone

Spawn custom agents without team_name. Agents cannot use SendMessage but have all file tools.

Workaround 2: Use general-purpose with Inline Instructions

Task(
    subagent_type="general-purpose",
    team_name="test-team",
    name="worker",
    instruction="[Paste custom agent instructions here]..."
)

Workaround 3: Rename Custom Agents

Rename custom agents to different names before starting sessions (theory - not fully tested across sessions).

Impact

• Blocks team-based workflows that require custom agents with specialized roles
• Forces workarounds that lose benefits of reusable agent definition files
• Affects all custom agents in ~/.claude/agents/ when used in team mode

Expected Fix

Custom agents should receive their defined tools (or default file tools) PLUS team communication tools when spawned in team mode, matching the behavior of built-in agent types.