[DOCS] Workflow docs omit schema validation retry behavior for `agent({schema})` subagents

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/workflows

Section/Topic

"Behavior and limits" for dynamic workflows

Current Documentation

The Workflows page explains that workflows are scripts that orchestrate subagents:

"A dynamic workflow is a JavaScript script that orchestrates subagents at scale."

It also explains limits around parallelism, cost, and agent caps:

"The runtime's agent caps limit how many agents a single run can spawn, which bounds the cost of a runaway script."

The page does not describe schema-bearing workflow subagents or what happens when an agent({schema}) subagent repeatedly fails schema validation.

What's Wrong or Missing?

Claude Code v2.1.186 changed Workflow agent({schema}) subagents so repeated schema validation failures abort after 5 attempts instead of looping indefinitely.

The docs do not expose this retry limit or the resulting failure behavior, so workflow authors cannot design schemas and error handling around it.

Suggested Improvement

Add a short "Structured outputs from workflow agents" subsection that explains:

• Workflow agents can be given a schema when the workflow needs structured output.
• If the agent output fails schema validation repeatedly, Claude Code retries up to 5 attempts.
• After the retry limit, the workflow agent aborts with a validation failure instead of looping indefinitely.
• Authors should keep schemas focused and make fields optional when the information may not be available.

Cross-link to the structured outputs page for general schema guidance.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/workflows | Dynamic workflow behavior and limits |
| https://code.claude.com/docs/en/agent-sdk/structured-outputs | General structured output validation and retry guidance |

Total scope: 2 pages affected