Approval decision record: bind a verifiable receipt to in-chat approvals

[nmrtn]

Problem

In-conversation approval shipped in #4 (v0.1.0/0.1.1): when a payment needs
human approval, pay.stage() returns a staged intent and the MCP server
exposes approve_payment / reject_payment keyed by intent_id. Today the
approval is recorded as a stream of audit events (approval_staged →
approval_received → payment_completed|payment_denied), not as a single
structured, queryable decision record.

@rpelevin raised this in #4:
"the human said yes in chat" should be a verifiable decision boundary, not a
vague transcript claim. The approval should mint a record that binds exactly
what was approved.

What's bound today

The staged intent + audit chain already carry:

• intent_id
• amount, currency
• recipient_wallet, recipient_url (the target endpoint)
• intent (the agent's own stated reason for the spend)
• rule_fired (the policy threshold that was crossed)
• audit events keyed by intent_id

Proposed: a single ApprovalRecord

Bind, in one structured object returned at approval time and persisted:

• mcp_server + tool (provenance)
• intent_id
• amount, currency, recipient_wallet, recipient_url
• actor / principal — who initiated; matters once more than one agent or human shares a wallet. New.
• reason + policy threshold crossed (rule_fired)
• expires_at — driven by the policy's own timeout_seconds, not a fixed TTL. Overlaps the approval-timeout gap (today the MCP server uses a fixed 1h TTL).
• params_hash — hash of the exact request (url + method + body + amount) so the approved request == the settled request, closing the approve→settle TOCTOU. New, and worth it.
• route: allow | revise | human_review | stop — revise (counter-offer a lower cap instead of a binary yes/no) is new.

Open questions

• Append-only audit JSONL with these fields added, or a separate signed/structured record? blacktea keeps the audit log narrow on purpose; this is the natural place to widen it.
• revise semantics: a real counter-offer flow, or out of scope for v1?
• Where does actor/principal come from across the SDK / CLI / MCP surfaces?

Related

• MCP server: in-conversation approval (surface 'ask the human' through the chat) #4 — in-conversation approval (shipped); this issue is the receipt boundary on top.
• Out-of-band approval CLI mode: blacktea approve <intent-id> #3 — out-of-band approval (separate trust model).
• Prior art shared by @rpelevin: https://github.com/neurarelay/relay-action-card/blob/main/docs/mcp-risk-gate.md

Design push credit: @rpelevin.

[rpelevin]

Thanks Nicolas — this is exactly the right place to separate the shipped in-chat approval flow from the durable decision boundary.

For v1, I would keep the ApprovalRecord small but strict:

• intent_id
• mcp_server + tool
• actor/principal
• amount, currency, recipient_wallet, recipient_url
• reason + rule_fired
• params_hash over the exact settlement-relevant request
• route: allow | deny | revise | human_review
• expires_at
• created_at
• final_state: staged | approved | denied | expired | settled | failed
• audit_event_refs

I would treat params_hash, expires_at, and actor/principal as the non-negotiable fields. Those are what prevent “human said yes” from collapsing back into a transcript claim.

For revise, I would keep it in the enum now but make the first implementation allowed to return it as unsupported. That preserves the future counter-offer path without blocking the approval-record v1.

I would start as an append-only structured record in the existing audit path, then add signing later if the object shape proves stable.

[nmrtn]

This is solid, taking most of it.

Shipping with your three non-negotiables: params_hash, expires_at, and the lifecycle (staged → approved → denied → expired → settled → failed). audit_event_refs going in too, it's the right way to keep the record tight and let the audit stream stay the full trail.

Two small tweaks:

actor/principal in the schema but nullable for v1. blacktea today is mostly one human, one agent, one wallet. Forcing a value means people invent one. The field is there for the day someone runs multiple agents against a shared wallet, and that's the right time to make it required.

Keeping blacktea's existing names for the route: allow / reject / human_review. reject and deny mean the same thing here, and the rest of the codebase + policy DSL already uses reject. Reserving revise as you suggested, returns unsupported if anyone tries it.

Putting up a draft PR now with the type so we can argue field names in code rather than comments. I'll tag you on it.

[nmrtn]

Partial update: expires_at (one of the load-bearing bullets above) shipped in v0.1.3 / mcp 0.1.2. StagedIntent.expires_at is now a public field driven by decision.timeout_seconds, and pay.complete(staged, "approve") throws ApprovalTimeoutError past the window. MCP uses staged.expires_at for its in-memory map instead of a fixed 1h TTL.

The full ApprovalRecord object (params_hash, actor, provenance, lifecycle, audit_event_refs) is still pending. Draft schema for those lives in #6.