Raise a clear error for list-form system_prompt

[PranavMishra28]

What was broken

ClaudeAgentOptions(system_prompt=[...]) (a list of Anthropic content blocks) was accepted at construction but then crashed later, at command-build time, with a cryptic AttributeError: 'list' object has no attribute 'get' in SubprocessCLITransport._build_command. The failure was delayed and noisy — per the issue it surfaced only after a paid model call was already in flight.

Why it matters

The Messages API system parameter accepts string | content_block[], and Anthropic's prompt-caching guidance recommends the list form so cache_control can sit on a trailing block and give layer-independent caching (a stable role prompt vs. per-call injected content).

Why this is a fast-fail, not full list-form support

The bundled claude CLI has no channel that carries a structured system array. Checking the bundled CLI (2.1.201): content passed via --system-prompt / --system-prompt-file is forwarded as a single plain-text block, so a JSON array written to the file is sent verbatim as the literal system-prompt text and per-block cache_control is never honored. Real list-form support therefore needs a new CLI-side flag (one that forwards a JSON system array to the API) and is out of scope for an SDK-only change.

What the fix does

Validates the shape early, in ClaudeAgentOptions.__post_init__: a list system_prompt now raises a clear, actionable ValueError at construction — naming the concatenate-to-string workaround and its prompt-caching cost, and pointing to the preset/file forms — instead of the delayed AttributeError.

What it deliberately does not change

• No transport/CLI behavior changes; str, None, SystemPromptPreset, and SystemPromptFile are untouched.
• No new flags, dependencies, or wire-format changes.
• No lossy client-side concatenation — that stays the caller's explicit choice.

Testing

• New test asserting the list form raises ValueError at construction.
• Existing system_prompt tests (str / None / preset / preset+append / preset+exclude_dynamic / file) still pass.
• Full suite green: 1057 passed, 5 skipped; ruff check, ruff format --check, and mypy --strict src/ all clean.

Addresses #899.

Developed with Claude Code; reviewed and tested by Pranav before marking ready for review.

[PranavMishra28]

simple fix for our sdk to immediately raise clear errors if a list is incorrectly passed in the system prompt

[tapheret2]

Review: Raise a clear error for list-form system_prompt

Files: src/claude_agent_sdk/types.py, tests/test_types.py
Size: +30 / -0

Notes

• Tests/fixtures included — good for merge confidence.

Nits

• Any user-facing change that should be mentioned in the PR description?
• Need a changelog/release note for the next tag?

Thanks @PranavMishra28 — independent review pass on the diff.

[PranavMishra28]

@tapheret2 I've added the release note entry. Lemme know if you need any other fixes so we can get this merged in.