Deterministic tool-call receipt contract for trace consumers

[davidahmann]

Problem observed

Tool-call tracing had rich attributes but lacked one deterministic receipt object that downstream systems can parse consistently for audit/replay linkage. Equivalent calls with reordered args needed to yield the same receipt identity signal.

Why it matters operationally

Ops pipelines and incident replay benefit from a single stable receipt contract per tool execution. Without this, correlation logic becomes brittle, especially when argument map ordering differs across runtimes or integrations.

Minimal repro

uv run python -m pytest tests/unittests/telemetry/test_spans.py -k "trace_tool_call"

Fix approach

Added gcp.vertex.agent.tool_call_receipt to tool-call tracing with deterministic serialization. The receipt includes schema version, tool name/type, function call ID, args SHA-256 digest, and outcome. Tests now verify required fields and deterministic equality for equivalent args with different key order.

Validation evidence

• Added deterministic receipt helper + trace attribute emission.
• Extended telemetry span tests for schema field presence.
• Added deterministic serialization regression test.

Open follow-up question for maintainers

Would maintainers prefer publishing this receipt as a documented public telemetry contract now, or keep it internal until additional invocation-step receipts are aligned?

This contribution was informed by patterns from Gait: https://github.com/davidahmann/gait