[DOCS] Versioned schema for Claude Code 2.1.260 print-mode JSON result envelope

Status Open

Reported on v2.1.260

Maintainer reply None cached

Activity 0 comments · opened Sep 29, 2026

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/headless#get-structured-output

Section/Topic

Version-pinned print-mode JSON result envelope, Claude Code 2.1.260

Current Documentation

_No response_

What's Wrong or Missing?

Is there an authoritative, version-pinned schema or source reference for the complete outer JSON object emitted by Claude Code 2.1.260 when invoked directly with -p --output-format json?

We are building a strict, fail-closed reader for a public dummy-text check. We distinguish the outer CLI envelope from the text in result and from structured_output produced with --json-schema. The invocation uses --safe-mode, --tools '', --disallowedTools '*', --strict-mcp-config, an empty MCP configuration, settings with disableAllHooks: true, --disable-slash-commands, --no-chrome, --no-session-persistence, and --max-turns 1. It does not add --bare or --json-schema. No reproduction command or additional model request is being requested here.

Our bounded diagnostic retained only an anonymous shape: 24 outer keys, one key unclassified by our current reader whose value is an object with 9–64 immediate members, and no missing reader-required keys. The field name and its values were not retained. This is not a complete reproduction or a claim that the CLI output is defective. We cannot identify that field or conclude it is harmless from this shape.

We compared the published @anthropic-ai/claude-agent-sdk@0.3.260 result type declarations with our reader. We have not found a guarantee that those SDK declarations exhaustively describe direct CLI print-mode JSON. The published @anthropic-ai/claude-code@2.1.260 npm wrapper forwards arguments and inherits native stdout; its tool-schema declarations do not define the final result envelope.

Could you point us to documentation for:

The complete success and error outer envelopes for CLI 2.1.260: field names, types, required/optional/null rules, and extension-field policy.
Whether direct --output-format json, the final stream-json result event, and SDK 0.3.260's result types have exactly the same fields and meanings. If not, the documented CLI-only additions or transformations.
How a downstream reader can distinguish diagnostic metadata from fields that affect completion, tool execution, permissions, pending work, or output truncation without silently discarding unknown fields.
A version-pinned reference and compatibility policy that downstream validators can test against without relying on rolling documentation or reverse engineering the native executable.

We are keeping unknown fields rejected while this contract is unconfirmed. We are not seeking broader permissions, removal of safety flags, or an automatic retry strategy. An authoritative reference or clarification would let us prepare synthetic compatibility tests before considering another separately authorized runtime check.

Public references consulted:

Suggested Improvement

Please provide the version-pinned references and field contracts requested in items 1-4 above.

Impact

Medium - Makes feature difficult to understand

Additional Context