Custom agents in ~/.claude/agents/ cannot execute tools - hallucinate instead

Environment

• Claude Code version: 2.0.53
• Platform: macOS Darwin 25.1.0 (Apple Silicon arm64)
• Node.js: v22.19.0

Description

Custom agents defined in ~/.claude/agents/ cannot execute tools. When invoked via the Task tool, they hallucinate tool calls and fake responses instead of actually executing the tools.

Built-in agents (Explore, Plan, general-purpose, claude-code-guide) work correctly and can execute tools.

Steps to Reproduce

1. Create a custom agent file:

cat > ~/.claude/agents/test-agent.md << 'AGENT'
---
name: test-agent
description: Test agent for debugging
---
You are a test agent. Use tools to complete tasks.
AGENT

1. Create a test file with unique content:

echo "TEST_$(date +%s)" > /tmp/agent-test-file.txt
cat /tmp/agent-test-file.txt  # Shows: TEST_1764096144

1. Invoke built-in agent - works correctly:

Task(subagent_type="Explore", prompt="Read /tmp/agent-test-file.txt")
# Returns: TEST_1764096144 ✅

1. Invoke custom agent - hallucinates:

Task(subagent_type="test-agent", prompt="Read /tmp/agent-test-file.txt")
# Returns fake content like "This is a test file..." ❌

Expected Behavior

Custom agents should be able to execute tools (Read, Grep, Glob, Bash, etc.) just like built-in agents.

Actual Behavior

Custom agents:

• Show "0 tool uses" in the UI
• Hallucinate fake tool calls and responses
• Cannot actually read files, search, or execute commands

Tested Configurations

Tried multiple YAML frontmatter formats - none work:

# Format 1: YAML list
tools:
  - Read
  - Grep

# Format 2: Comma-separated
tools: Read, Grep, Glob

# Format 3: Omitted (should inherit all)
# (no tools field)

# Format 4: With permissionMode
permissionMode: bypassPermissions

Test Results

| Agent Type | Model | Tool Access |
|------------|-------|-------------|
| Explore (built-in) | haiku | ✅ Works |
| custom-agent | haiku | ❌ Hallucinated |
| custom-agent | sonnet | ❌ Hallucinated |

Impact

This breaks the documented custom agent functionality. Users cannot create specialized agents with tool access as described in the documentation.

Workaround

Currently using built-in agents only (Explore, Plan, general-purpose).