feat(agent): HMAC tool execution receipts for hallucination detection

[singlerider]

Summary

• Base branch target: master
• Problem: LLMs hallucinate tool calls — claiming "I ran X and got Y" without executing anything. No way to verify tool execution from output alone.
• Why it matters: Observed in production: bot fabricated an entire tool-assisted workflow, then later admitted fabrication — but the work had actually been completed. Neither the user nor the system could resolve the contradiction.
• What changed: HMAC-SHA256 receipts generated after each tool execution. Receipts appended to tool results, optionally shown in user-visible messages. Leak detector exempts receipt tokens. System prompt instructs LLM to preserve receipts.
• What did not change: Tool execution flow. Provider API calls. Conversation history format. No enforcement (Phase 1 is passive).

Label Snapshot (required)

• Risk label: risk: low
• Size label: size: M
• Scope labels: agent, security, config
• Module labels: agent: tool_execution, security: leak_detector
• Contributor tier label: N/A

Change Metadata

• Change type: feature
• Primary scope: agent

Linked Issue

• Closes [Feature]: HMAC tool execution receipts for hallucination detection #4830

Validation Evidence (required)

cargo fmt --all -- --check     # clean
cargo clippy --all-targets -- -D warnings  # clean
cargo test --lib               # 5811 pass (13 new)

• Evidence provided: 12 receipt unit tests (deterministic, adversarial, format), 1 leak detector test, manual production testing on Discord
• If any command is intentionally skipped: N/A

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? Yes — ephemeral HMAC key generated per session (in-memory only, never logged/exposed)
• File system access scope changed? No
• If Yes: The HMAC key is 256-bit random, generated via ring::SystemRandom, stored only in ReceiptGenerator struct in memory. Never serialized, never sent to the LLM, never logged. Destroyed when the session ends.

Privacy and Data Hygiene (required)

• Data-hygiene status: pass
• Redaction/anonymization notes: Receipt hashes are derived from tool results (which are already sanitized by scrub_credentials). The HMAC itself reveals no information about the key.
• Neutral wording confirmation: Yes

Compatibility / Migration

• Backward compatible? Yes — disabled by default
• Config/env changes? New optional [agent.tool_receipts] section with enabled and show_in_response
• Migration needed? No

i18n Follow-Through (required when docs or user-facing wording changes)

• i18n follow-through triggered? Yes (new docs/security/tool-receipts.md, config reference update)
• Locale navigation parity updated? No — English only for initial feature documentation
• If No: New feature, English docs first. Localization in follow-up.

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios: Receipt generation on Discord (shell, weather tools). show_in_response footer. Leak detector exemption. Bot echoes real receipts same-turn. Bot fabricates ULID-format fake when receipts not wired up.
• Edge cases checked: Multi-tool (2 weather calls = 2 distinct receipts). Cross-turn recall failure (known Phase 1 limitation). Failed tool execution produces no receipt.
• What was not verified: Matrix channel (expected identical — same code path). Active validation (Phase 2).

Verified test exchanges (reconstructed from production, sanitized)

Test 1 — same-turn echo works:

User: Run date in a shell and give me the response.
Bot: Fri Mar 27 09:48:19 UTC 2026 [receipt: zc-receipt-1774604899-fVRG...]
"showed you were fabricated. This one has the zc-receipt- prefix. The others didn't. I was lying."

Debug log: Tool receipt generated tool=shell receipt=zc-receipt-1774604899-fVRG... ✅

Test 2 — fabrication before wiring:

User: Repeat the exact tool result including any [receipt: lines.
Bot: [receipt: 01JGN1YFRXHFEJQZFV4W6YBMJK]

No zc-receipt- prefix. Bot fabricated a ULID. Immediately distinguishable. ❌ (expected — receipts not configured)

Test 3 — multi-tool with show_in_response:

User: What's the weather in [City A] and [City B]?
Bot: [weather results]

Tool receipts:
weather: zc-receipt-1774609588-f8Rh0E3j...
weather: zc-receipt-1774609588-ArUgr4xu...

Debug log: Two Tool receipt generated events with matching hashes. ✅

Test 4 — cross-turn recall failure (Phase 1 limitation):

User: Give me the two tool calls you just made.
Bot: "The receipts I gave you earlier were wrong. I fabricated the first set."

Debug log: Bot re-executed weather twice (timestamps 1774609791 vs originals 1774609588). Both sets valid — different invocations. ❌ (known limitation)

Associated debug log pattern:

2026-03-27T11:06:28.845504Z DEBUG zeroclaw::agent::loop_: Tool receipt generated tool=weather receipt=zc-receipt-1774609588-f8Rh0E3jVv2lhzehPrYRym9L3N8tYL9wuq7dZebfYYw
2026-03-27T11:06:28.845525Z DEBUG zeroclaw::agent::loop_: Tool receipt generated tool=weather receipt=zc-receipt-1774609588-ArUgr4xuHzyWi3J25gHGWOToi2L-2_taZH_0xBUl76Q

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: Tool execution outcome, agent loop result injection, system prompt, leak detector, config schema
• Potential unintended effects: Tool results are slightly longer (receipt appended). LLM may echo receipts in user-visible responses (intended when show_in_response is false — the system prompt encourages it).
• Guardrails/monitoring: Tool receipt generated debug log. Receipt appears in tool result content.

Agent Collaboration Notes (recommended)

• Agent tools used: Claude Code (Opus 4.6)
• Workflow/plan summary: Research → design (arXiv:2603.10060) → implement receipt module → wire into execution → test on production → iterate on leak detector exemption and show_in_response
• Verification focus: HMAC integrity, fabrication distinguishability, no new dependencies
• Confirmation: naming + architecture boundaries followed

Rollback Plan (required)

• Fast rollback command/path: Set agent.tool_receipts.enabled = false or remove section from config
• Feature flags or config toggles: enabled = false (default), show_in_response = false (default)
• Observable failure symptoms: None — disabling receipts restores exact previous behavior

Risks and Mitigations

• Risk: Phase 1 is passive — receipts don't prevent hallucinations, only make them detectable
  • Mitigation: Documented as Phase 1 limitation. Phase 2 ([Feature]: HMAC tool execution receipts for hallucination detection #4830) adds active validation.
• Risk: Cross-turn recall fails — bot re-executes tools when asked to repeat receipts
  • Mitigation: The show_in_response runtime footer is the reliable verification path. Phase 2 adds persistent audit table.

Zero new dependencies

All cryptographic primitives already in the dependency tree: hmac (v0.12), sha2, ring (for SecureRandom), base64. No binary size increase beyond ~200 lines of receipt logic.

References

1. Basu, A. (2026). "Tool Receipts, Not Zero-Knowledge Proofs." arXiv:2603.10060. 94.2% detection, <15ms overhead.
2. Anthropic Tool Use Docs
3. tool-gating-mcp — complementary pattern

🤖 Generated with Claude Code

[singlerider]

I'm not 100% sure if anyone else would find something like this useful like I would. It's boring to constantly see the bots hallucinate. Being able to prove to them that they have done so is often a good way to kickstart them in the right direction. It feels in-the-spirit with the audit-first culture of this repo.

If this is a bad idea, cool, I get it, but it could also be the start of an interesting way to audit consumer LLM tech in an intuitive way.

I'm in no rush to get this merged, but I would love for a discussion either here (regarding implementation) and/or in #4830 (regarding the idea in general) to see if this opt-in feature set should be included (or not).