signature

Overview ¶

Claude thinking signature validation.

Spec reference: SIGNATURE-CHANNEL-SPEC.md

Encoding detection (Spec section 3)

Claude signatures use base64 encoding in one or two layers. The raw string's first character determines the encoding depth. This is mathematically equivalent to the spec's "decode first, check byte" approach:

• E prefix: single-layer, payload[0] == 0x12, first 6 bits = 000100, base64 index 4 = E.
• R prefix: double-layer, inner[0] == E (0x45), first 6 bits = 010001, base64 index 17 = R.

Valid signatures can be normalized to R-form (double-layer base64) before sending to the Antigravity backend.

Protobuf structure (Spec sections 4.1 and 4.2) in strict mode only ¶

After base64 decoding to raw bytes, the first byte must be 0x12:

Top-level protobuf
|- Field 2 (bytes): container                    -> extractClaudeBytesField(payload, 2)
|  |- Field 1 (bytes): channel block             -> extractClaudeBytesField(container, 1)
|  |  |- Field 1 (varint): channel_id [required] -> routing_class (11 | 12)
|  |  |- Field 2 (varint): infra [optional]      -> infrastructure_class (aws=1 | google=2)
|  |  |- Field 3 (varint): version=2             -> skipped
|  |  |- Field 5 (bytes): ECDSA sig              -> skipped, per Spec section 11
|  |  |- Field 6 (bytes): model_text [optional]  -> schema_features
|  |  `- Field 7 (varint): unknown [optional]    -> schema_features
|  |- Field 2 (bytes): nonce 12B                 -> skipped
|  |- Field 3 (bytes): session 12B               -> skipped
|  |- Field 4 (bytes): SHA-384 48B               -> skipped
|  `- Field 5 (bytes): metadata                  -> skipped, per Spec section 11
`- Field 3 (varint): =1                          -> skipped

Output dimensions (Spec section 8)

routing_class:        routing_class_11 | routing_class_12 | unknown
infrastructure_class: infra_default (absent) | infra_aws (1) | infra_google (2) | infra_unknown
schema_features:      compact_schema (len 70-72, no f6/f7) | extended_model_tagged_schema (f6 exists) | unknown
legacy_route_hint:    only for ch=11, legacy_default_group | legacy_aws_group | legacy_vertex_direct/proxy

Compatibility ¶

Verified against all confirmed spec samples (Anthropic Max 20x, Azure, Vertex, Bedrock) and legacy ch=11 signatures. Both single-layer (E) and double-layer (R) encodings are supported. Historical cache-mode modelGroup# prefixes are stripped.

Gemini thought signature validation notes.

The Antigravity Gemini request translator can preserve provider-compatible Gemini thought signatures and uses the skip sentinel only for synthetic or incompatible model parts.

Gemini 3 and later models can return thoughtSignature on model content parts. Function-call parts are the strict case: when a model functionCall is replayed with a following functionResponse, Gemini validates that the original functionCall part still carries its provider-issued thoughtSignature. Text or other non-functionCall parts may also carry a signature; those should be preserved when replaying native Gemini history, but they are not the primary validation gate.

Synthetic history and migration from other model families are different. If a functionCall part was not produced by Gemini API, there is no real signature to preserve. Gemini documents two bypass sentinels for that case:

• "skip_thought_signature_validator"
• "context_engineering_is_the_way_to_go"

This repo currently emits "skip_thought_signature_validator" for non-Claude Antigravity Gemini model parts that contain functionCall, thought, or an existing thoughtSignature. That is a request-shape compatibility policy, not a proof that the replaced signature was malformed.

This validator is intentionally more conservative than a decrypting verifier. Claude has a known E/R base64 envelope and a protobuf tree in this package. Gemini thought signatures are opaque provider state here, so local validation checks only the transport-level protobuf envelope and leaves the wrapped provider payload uninterpreted.

Validation tiers:

• Sentinel tier: accept the documented bypass sentinels only when the model functionCall is synthetic, migrated, or otherwise not traceable to a prior Gemini model response in the same conversation.
• Opaque-shape tier: for real Gemini signatures, require a non-empty string, bounded length, successful standard base64 decoding, and a known protobuf envelope when the caller needs provider compatibility. Observed samples currently include Gemini 3.x field-2 -> field-1 payloads and Gemini 2.5 repeated field-1 payloads. Base64 UUID payloads are classified separately and should be replaced with the bypass sentinel rather than replayed.
• Replay tier: real validation means preserving the exact model part that came from Gemini, including its thoughtSignature, id/name/function args, part index, and ordering relative to sibling parallel function calls.
• Tool pairing tier: functionResponse parts must match the preceding functionCall id/name and must not be interleaved between parallel calls. The valid shape is all model functionCalls first, then their responses.
• Compatibility tier: GPT-compatible Gemini traffic stores the same state under tool_calls[].extra_content.google.thought_signature. If that path is translated back to native Gemini, the value must stay attached to the same assistant tool call.

Important non-goals:

• Do not treat a Gemini thoughtSignature as a Claude signature. Similar base64 prefixes are not provenance.
• Do not attach a signature to user functionResponse/tool-result parts.
• Do not log complete signatures during validation failures; log only field paths, lengths, and redacted prefixes.
• Do not preserve client-provided signatures across model/provider/session boundaries unless the request pipeline can prove they came from the same Gemini conversation state.