[BUG] StructuredOutput tool wraps data in 'output' field causing schema validation to fail

[AgentWrapper]

Bug Description

When using structured outputs with output_format, the StructuredOutput tool intermittently wraps user data in an {"output": {...}} field. Validation fails when the wrapper is present.

This is non-deterministic - same prompt can produce either format:

// Sometimes (works):
{"actions": [...]}

// Sometimes (fails validation):
{"output": {"actions": [...]}}

Impact

1. ResultMessage.structured_output is None when wrapper is present
2. Agent confusion - Claude sees conflicting validation errors and may simplify output (e.g., 47 items → 1 item)
3. Flaky results - identical prompts succeed or fail randomly

Tool Response Error

Output does not match required schema: root: must have required property 'actions', root: must NOT have additional properties

This error confuses Claude because:

• actions is "required" but exists inside output
• Schema has additionalProperties: false, so output is invalid

Claude tried to "debug" by reducing output from 47 items to 1 item.

Environment

• claude-agent-sdk==0.1.19
• Python 3.11+

Related

• Structured outputs seems to be flaky #374 - Structured outputs flaky (similar wrapper issues with properties/parameters)

[AgentWrapper]

Additional data point: The wrapper key can also be "response" instead of "output":

{
  "response": {
    "actions": [...]
  }
}

Same error: Output does not match required schema: root: must have required property 'actions', root: must NOT have additional properties

[AgentWrapper]

Another wrapper variant observed: {"json": {...}} in addition to {"output": {...}} and {"response": {...}}.

[Liberot2]

the same question

[yarjor]

+1

[developer239]

+1

[InsanePrototyper]

Yes, I am also facing this

[jmehnle]

This is so frustrating. We're now setting ourselves up for just asking for a natural language response from Claude and then using ChatGPT to coerce it into a proper structured response. This appears to be a much more robust strategy.

[sihil]

FWIW, the pre tool use hook strategy documented on #374 seems like a good approach as you can rewrite the JSON in that hook and unwrap (or correct as required) before running the structured output tool.