[DOCS] JSON output format description varies between Headless and Common Workflows guides

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/headless - https://code.claude.com/docs/en/common-workflows

Section/Topic

• Headless Guide: The "Get structured output" section. - Common Workflows: The "Control output format" section under "Use Claude as a unix-style utility".

Current Documentation

In Headless Mode (docs/en/headless):

"This example returns a project summary as JSON with session metadata, with the text result in the result field" It provides this code snippet: claude -p "Summarize this project" --output-format json | jq -r '.result'

In Common Workflows (docs/en/common-workflows):

"This outputs a JSON array of messages with metadata including cost and duration."

What's Wrong or Missing?

There is a critical contradiction regarding the structure of the JSON output when using the --output-format json flag.

1. headless.md implies the output is a JSON Object containing a top-level key named .result.
2. common-workflows.md states the output is a JSON Array of messages.

If a developer follows the headless.md guide but the CLI actually outputs an Array (as suggested by common-workflows.md), the jq -r '.result' command will fail or return null, causing scripts to break. Conversely, if it outputs an Object, the description in common-workflows is factually incorrect.

Suggested Improvement

Verify the actual output of claude -p "query" --output-format json in the current version of the CLI.

If the output is an Object with a result field:
Update docs/en/common-workflows to read:

"This outputs a JSON object containing the result string and metadata including cost and duration."

If the output is an Array of messages:
Update docs/en/headless to remove the reference to the .result field and update the jq example to correctly parse the array (e.g., extracting the text from the last message).

Impact

High - Prevents users from using a feature

Additional Context

This inconsistency creates friction for developers attempting to integrate Claude Code into CI/CD pipelines or bash scripts, as the documentation provides two different "sources of truth" for the expected data structure.