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

[Wingrammer]

Deterministic receipts become foundational once traces feed audit, replay, or external policy systems.
One subtle extension to consider: are you treating receipt determinism as purely structural (args hash + call metadata), or as part of a broader execution-state contract?
We’ve seen cases where equivalent args still produced materially different side effects due to execution-state deltas (model config, retrieval assembly, dependency revisions). Structural determinism held, behavioral determinism didn’t.
Publishing the receipt as a formal telemetry contract would likely stabilize downstream tooling early.
This is exactly the sort of surface that benefits from being explicit rather than implied.