[DOCS] Headless mode docs omit total_cost_usd field from JSON output description

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Get structured output" section

Current Documentation

The documentation describes JSON output as:

json: structured JSON with result, session ID, and metadata

And later:

The response includes metadata about the request (session ID, usage, etc.) with the structured output in the structured_output field.

What's Wrong or Missing?

The headless documentation does not explicitly document the total_cost_usd field that is available in the JSON output. This field is critical for CI/CD pipelines and automated workflows that need to track API costs.

The SDK type definitions (source of truth) show this field exists:

// From SDKResultMessage in typescript.md
{
total_cost_usd: number;
// ... other fields
}

Developers building cost-tracking integrations for CI/CD pipelines (a primary use case for headless mode) cannot discover this field from the headless documentation alone.

Suggested Improvement

Update the "Get structured output" section to explicitly list available fields in JSON output:

Before:

json: structured JSON with result, session ID, and metadata

After:

json: structured JSON including: - result: The text response - session_id: Session identifier for resuming conversations - total_cost_usd: Total cost in USD for the request - usage: Token usage breakdown - is_error: Whether the request failed

Or add an example showing the JSON structure:

claude -p "Summarize this project" --output-format json | jq '{result, session_id, total_cost_usd}'

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Section | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/headless | Get structured output | Missing field documentation |

Cross-references:

| Page | Evidence |
|------|----------|
| https://platform.claude.com/docs/en/agent-sdk/typescript | SDKResultMessage type includes total_cost_usd: number |
| https://platform.claude.com/docs/en/agent-sdk/python | SDKResultMessage includes cost field |

Total scope: 1 page affected