[DOCS] Headless stream-json init event missing `plugin_errors` documentation

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Stream responses" (--output-format stream-json) and the init event payload used to report plugin startup state

Current Documentation

The headless docs currently say:

Use --output-format stream-json with --verbose and --include-partial-messages to receive tokens as they're generated. Each line is a JSON object representing an event:

The same page only gives a text-delta filtering example:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

The SDK TypeScript reference currently defines the init system message as:

type SDKSystemMessage = { type: "system"; subtype: "init"; ... mcp_servers: { name: string; status: string; }[]; ... slash_commands: string[]; output_style: string; skills: string[]; plugins: { name: string; path: string }[]; };

And the plugin SDK guide tells readers to inspect the init message only for loaded plugins and commands:

When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available:

What's Wrong or Missing?

Changelog v2.1.111 adds a new startup behavior: headless --output-format stream-json now includes plugin_errors on the init event when plugins are demoted for unsatisfied dependencies.

The current docs do not describe that init-event field or the demotion behavior:

A. Headless stream-json docs omit the init payload details

The headless page explains that stream-json emits events, but it does not document the startup/init event shape or mention that plugin dependency failures surface through plugin_errors.

B. SDK init-message references are now incomplete

The TypeScript init-message field list omits plugin_errors, and the Python reference only describes SystemMessage generically. Readers who inspect init messages to verify plugin state are not told how dependency-related plugin demotions are reported.

C. Plugin troubleshooting guidance does not connect dependency demotion to init output

The plugin docs discuss successful plugin loading and general loading errors, but they do not explain that unsatisfied dependencies can demote a plugin and that headless/SDK consumers should check plugin_errors on the init event.

Suggested Improvement

Update the headless and Agent SDK docs to document the init event as part of the --output-format stream-json contract.

Recommended minimum changes:

1. In https://code.claude.com/docs/en/headless, add a short init-event example for --output-format stream-json and mention that plugin_errors is included when plugins are demoted for unsatisfied dependencies.
2. In the TypeScript and Python Agent SDK message references, add plugin_errors to the documented init-message payload and describe when it appears.
3. In the plugin/SDK plugin docs, add a troubleshooting note telling users to inspect init output for demoted plugins caused by missing or unsatisfied dependencies.

It would also help to document the shape of each plugin_errors entry and clarify whether a demoted plugin is omitted from plugins, marked separately, or otherwise represented in startup metadata.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | Documents --output-format stream-json, but not the init event schema or plugin_errors |
| https://code.claude.com/docs/en/cli-reference | Documents the CLI flags that enable stream-json output |
| https://code.claude.com/docs/en/agent-sdk/typescript | SDKSystemMessage lists init fields such as mcp_servers, slash_commands, skills, and plugins, but not plugin_errors |
| https://code.claude.com/docs/en/agent-sdk/python | SystemMessage is described only generically, with no documented init payload fields for plugin demotion/errors |
| https://code.claude.com/docs/en/agent-sdk/plugins | Tells users to inspect the init message for loaded plugins, but not for dependency-driven demotion via plugin_errors |

Total scope: 5 pages affected

Source: Changelog v2.1.111

Changelog entry: Headless --output-format stream-json now includes plugin_errors on the init event when plugins are demoted for unsatisfied dependencies