[FEATURE] Support structured output schemas for Claude Code subagents that directly use the structured output API

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I’d love support for enforcing structured outputs on Claude Code subagents configured via Markdown (.claude/agents/*.md) and settings.json.

Problem

Right now:

• The CLI can enforce structured output only at the top level via flags (e.g., JSON schema and output formatting).
• Subagents defined in Markdown or settings.json can customize prompts, tools, and model, but they cannot declare a structured-output contract.
• This makes it hard to build reliable multi-agent workflows where each subagent is responsible for a specific, typed payload (e.g., planner, critic, code-analyzer, test-generator) without adding another orchestration layer around the CLI.

Why this would be nice:

• Enables strongly typed, composable workflows directly in Claude Code, without having to reimplement a separate coordinator using the low-level SDK or make separate API calls utilizing skills and script wrappers.
• Reduces brittle string parsing and makes it much easier to integrate Claude Code into existing dev tooling (shell scripts, CI, editor plugins).
• Aligns the Claude Code experience with the structured-output capabilities already available in the Agent SDK.

Proposed Solution

Add first-class structured output support for subagents, for example:

1. YAML frontmatter in agent Markdown

---
name: test-writer
description: Writes tests for code
model: claude-3.7-sonnet
structured_output:
  type: json_schema
  schema:
    type: object
    properties:
      files:
        type: array
        items:
          type: object
          properties:
            path:
              type: string
            contents:
              type: string
          required: [path, contents]
    required: [files]
---

1. Support in settings.json

Allow defining subagents with a structured_output (or similar) field that maps to the same JSON Schema / typed output functionality as the Agent SDK.

1. CLI interop

• When a subagent is invoked from Claude Code, its response should be validated against the declared schema.
• If validation fails, provide a clear error or automatic retry with the same schema.

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

Any situation where an enforced structured response gives more confidence in the model's output.

Additional Context

_No response_