Repository navigation
Approval decision record: bind a verifiable receipt to in-chat approvals #5
Description
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_idamount,currencyrecipient_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_idamount,currency,recipient_wallet,recipient_urlactor/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 owntimeout_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.
revisesemantics: a real counter-offer flow, or out of scope for v1?- Where does
actor/principalcome 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.
Activity
rpelevin commentedon May 29, 2026
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:
I would treat
params_hash,expires_at, andactor/principalas 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 commentedon May 29, 2026
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_refsgoing 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/principalin 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.rejectanddenymean the same thing here, and the rest of the codebase + policy DSL already usesreject. Reservingreviseas 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 commentedon May 30, 2026
Partial update:
expires_at(one of the load-bearing bullets above) shipped in v0.1.3 / mcp 0.1.2.StagedIntent.expires_atis now a public field driven bydecision.timeout_seconds, andpay.complete(staged, "approve")throwsApprovalTimeoutErrorpast the window. MCP usesstaged.expires_atfor 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.draft: ApprovalRecord schema type (closes #5)
feat(schema): ApprovalRecord type for in-chat approval receipts (#6)