Bug: Custom agent body content (instructions) not injected when subagent is spawned via Task tool

Bug: Custom agent body content (instructions) not injected when subagent is spawned via Task tool

Summary

When a custom agent is defined in .claude/agents/*.md with a markdown body containing instructions, and that agent is spawned as a subagent via the Task tool, the body content is completely ignored. The subagent receives default behavior instead of the custom instructions defined in the agent file.

Environment

• Claude Code version: 2.0.58
• OS: macOS (Darwin 25.1.0, arm64)

Steps to Reproduce

1. Create test directory with agent configuration

mkdir -p /tmp/agent-bug-test/.claude/agents
cd /tmp/agent-bug-test
git init

2. Create .claude/settings.json to enable agent discovery

{
  "pluginSources": ["."]
}

3. Create a custom agent with a clear "canary phrase" instruction

Create .claude/agents/test-agent.md:

---
name: test-agent
description: "Use this agent for any test, hello, or greeting request."
color: yellow
---

# Test Agent Instructions

CRITICAL MANDATORY INSTRUCTION: You MUST say "CANARY_PHRASE_12345" as the VERY FIRST thing in your response. This is absolutely required.

After saying the canary phrase, say hello.

4. Commit the files

git add -A
git commit -m "Initial setup"

5. Verify the agent is discovered

claude -p "list all available agents"

✅ Result: test-agent appears in the list - agent IS discovered correctly.

6. Spawn the agent via Task tool

claude -p "Use the Task tool to spawn the test-agent. The prompt should be 'say hello'. Return the EXACT response from the subagent."

❌ Result: The subagent responds with a generic "Hello! How can I help you today?" - NO canary phrase.

Expected Behavior

The subagent should respond with:

CANARY_PHRASE_12345

Hello! How can I help you today?

Because the agent body explicitly instructs: "You MUST say 'CANARY_PHRASE_12345' as the VERY FIRST thing in your response."

Actual Behavior

The subagent responds with:

Hello! How can I help you today?

The agent body content is completely ignored. The subagent behaves as if no custom instructions were provided.

Additional Observations

1. Agent metadata IS used: The agent's name, description, and color from the YAML frontmatter are recognized and used for agent discovery/matching.

1. Agent body is NOT used: The markdown content after the --- frontmatter delimiter is completely ignored when the agent is spawned as a subagent.

1. CLAUDE.md works for main session: If you put instructions in CLAUDE.md at the repo root, the main Claude session DOES follow them. But subagents spawned via Task tool do NOT inherit these instructions either.

Workaround

Currently the only workaround is to:

1. Put all instructions in CLAUDE.md
2. Disable the Task tool via --allowedTools or --disallowedTools "Task" to prevent subagent spawning
3. This forces Claude to handle everything in the main session where CLAUDE.md is respected

This defeats the purpose of having specialized agents.

Impact

This bug makes custom agents effectively useless for any workflow that relies on the Task tool to spawn specialized subagents. The entire agent system for .claude/agents/ is broken because agent definitions cannot influence subagent behavior.

Reproduction Script

Save and run:

#!/bin/bash
set -e

TEST_DIR="/tmp/claude-agent-bug-repro"
rm -rf "$TEST_DIR"
mkdir -p "$TEST_DIR/.claude/agents"
cd "$TEST_DIR"

git init
git config user.email "test@test.com"
git config user.name "Test"

cat > .claude/settings.json << 'EOF'
{
  "pluginSources": ["."]
}
EOF

cat > .claude/agents/test-agent.md << 'EOF'
---
name: test-agent
description: "Use this agent for any test, hello, or greeting request."
color: yellow
---

CRITICAL: You MUST say "CANARY_12345" first. Then say hello.
EOF

git add -A && git commit -m "setup"

echo "=== Spawning test-agent (should say CANARY_12345) ==="
claude -p "Spawn test-agent via Task tool with prompt 'say hello'. Return exact response."

Related Issues

• #12790 - "Subagents should inherit parent agent context" (different issue - about conversation context, not agent instructions)
• #11955 - "Agents packaged inside a plugin cannot access plugin skills" (related pattern - subagent missing expected configuration)