Internal orchestrator-to-subagent communication leaks into final AssistantMessage

[erdem-b]

Description

When using multi-agent orchestration with ClaudeSDKClient, internal communication between the orchestrator and sub-agents (via the Task tool) is included in the final AssistantMessage content, even when include_partial_messages=False (the default).

Expected Behavior

Only the final user-facing response from the orchestrator should be included in AssistantMessage objects yielded by receive_response(). Internal delegation prompts and sub-agent responses should not be visible.

Actual Behavior

The AssistantMessage.content includes internal text like:

• Orchestrator delegation prompts: "Search for marbles matching this profile: elegant white marble with gold veins. This describes a prestigious, luxurious aesthetic..."
• Sub-agent task instructions: "Return the marble IDs found"
• Other internal workflow text

This internal content is concatenated with the actual user-facing response.

Reproduction

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

options = ClaudeAgentOptions(
    agents={
        "ProfileSearcher": {
            "description": "Searches for marbles by profile",
            "prompt": "You search for marbles. Return marble IDs.",
            "tools": ["mcp__tools__search"]
        }
    },
    allowed_tools=["Task", "mcp__tools__search"],
    # include_partial_messages=False  # Default
)

async with ClaudeSDKClient(options) as client:
    await client.query("Find white marbles with gold veins")
    
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)  # Contains internal delegation text!

Environment

• claude-agent-sdk version: 0.1.10
• Python version: 3.11
• OS: Linux (Docker container)

Workaround Attempted

We tried using include_partial_messages=True with content filtering patterns, but this is fragile and not a proper solution.

Suggested Fix

The SDK should either:

1. Filter out Task tool delegation content from final messages automatically
2. Provide a message type or flag to distinguish internal vs user-facing content
3. Document the expected behavior for multi-agent message handling