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

Agent metadata IS used: The agent's name, description, and color from the YAML frontmatter are recognized and used for agent discovery/matching.
Agent body is NOT used: The markdown content after the --- frontmatter delimiter is completely ignored when the agent is spawned as a subagent.
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:

Put all instructions in CLAUDE.md
Disable the Task tool via --allowedTools or --disallowedTools "Task" to prevent subagent spawning
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 "[email protected]"
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

[Feature Request] Subagents should inherit parent agent context to avoid redundant codebase scanning #12790 - "Subagents should inherit parent agent context" (different issue - about conversation context, not agent instructions)
[BUG] Agents packaged inside a plugin cannot access plugin skills. #11955 - "Agents packaged inside a plugin cannot access plugin skills" (related pattern - subagent missing expected configuration)

Found 3 possible duplicate issues:

[BUG] Custom Sub-Agent Instructions Overridden by Undocumented Name-Based Inference System #4554
[BUG] Subagent ignores system_prompt when generating execution prompts #7515
[BUG] multiline descriptions in subagent files are silently ignored #9068

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

I just tested this, and confirm this is still occurring.

I just tested this, and confirm this is still occurring.

Thank you!!

Investigation Findings

I spent some time investigating this issue and wanted to share my findings. I've also submitted a plugin-based workaround as a draft PR (#20654).

Confirmed Behavior

I reproduced this issue on Claude Code 2.1.19 using the exact reproduction steps provided. The bug is confirmed:

✅ Agent metadata (name, description, color, tools) IS parsed and used
❌ Agent body content (markdown after frontmatter) is NOT passed to spawned subagents

Source Code Analysis

I analyzed the minified CLI source to understand the root cause. Key findings:

1. Agent body IS extracted correctly for plugin agents:

// The body content is assigned to P:
P = X.trim();  // X is the body content after frontmatter

return {
  agentType: _,
  whenToUse: Z,
  tools: G,
  // ...
  getSystemPrompt: () => P,  // Body SHOULD be returned here
  source: "plugin",
}

2. There's conditional logic for built-in vs custom agents:

if (BA.source === "built-in") {
  h(`[teammate] Built-in agent ${BA.agentType} - skipping custom prompt`);
} else {
  v8 = M6.getSystemPrompt();  // Custom agents SHOULD get their prompt here
}

3. The spawn function receives user prompt, not system prompt:

// In the FWA spawn function:
let M = await FWA({
  name: Z,
  teamName: $,
  prompt: w,      // <-- This is the USER'S task prompt, not the agent's system prompt
  color: W,
  model: X
}, K);

The getSystemPrompt() function exists and returns the correct body content, but it appears the result isn't being passed through to the spawned subagent's context.

SubagentStart Hook Discovery

I discovered that Claude Code v2.0.43 added a SubagentStart hook event that can inject additionalContext into spawned subagents:

case "SubagentStart":
  O.additionalContext = A.hookSpecificOutput.additionalContext;
  break;

The hook receives:

{
  "hook_event_name": "SubagentStart",
  "agent_type": "my-custom-agent",
  "agent_id": "agent-abc123",
  "cwd": "/path/to/project"
}

And can output:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Your custom instructions here..."
  }
}

This provides a workaround mechanism.

Related Issues Pattern

I found several related issues that seem to point to the same underlying problem:

Issue	Title	Status
#4554	Custom Sub-Agent Instructions Overridden by Name-Based Inference	Closed
#7515	Subagent ignores system_prompt when generating execution prompts	Closed
#9068	Multiline descriptions in subagent files are silently ignored	Open

These suggest this may be a broader issue with how subagent configuration is passed through the spawn pipeline.

Workaround Plugin

I've submitted PR #20654 (draft) with a plugin called agent-instructions-loader that uses the SubagentStart hook to:

Intercept subagent spawn events
Look up the agent's .md file by agent_type
Extract the body content
Return it as additionalContext

Note: This is a workaround, not a proper fix. The additionalContext is added to the conversation context, which is different from the intended behavior where the body becomes the actual system prompt. A proper fix would need to happen in the core spawn logic.

Suggested Fix Location

Based on the analysis, the fix likely needs to happen where FWA (or equivalent spawn function) is called. The agent's getSystemPrompt() result should be passed as the systemPrompt parameter for the spawned subagent, not just the user's task prompt.

Happy to provide more details if helpful!

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Navigation Menu

Repository navigation

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

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

Summary

Environment

Steps to Reproduce

1. Create test directory with agent configuration

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

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

4. Commit the files

5. Verify the agent is discovered

6. Spawn the agent via Task tool

Expected Behavior

Actual Behavior

Additional Observations

Workaround

Impact

Reproduction Script

Related Issues

Investigation Findings

Confirmed Behavior

Workaround Plugin

Suggested Fix Location

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

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

Summary

Environment

Steps to Reproduce

1. Create test directory with agent configuration

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

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

4. Commit the files

5. Verify the agent is discovered

6. Spawn the agent via Task tool

Expected Behavior

Actual Behavior

Additional Observations

Workaround

Impact

Reproduction Script

Related Issues

Activity

github-actions commented on Dec 11, 2025

github-actions commented on Jan 13, 2026

fast-90 commented on Jan 15, 2026

CameronImmesoete commented on Jan 16, 2026

CameronImmesoete commented on Jan 24, 2026

Investigation Findings

Confirmed Behavior

Workaround Plugin

Suggested Fix Location

github-actions commented on Feb 28, 2026

github-actions commented on Mar 12, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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