Approval Gated Writes

The problem

Agents that write to CRMs and datastores need human approval on sensitive fields. Most implementations handle the happy path: card sent, button tapped, write applied. Production breaks elsewhere. Buttons fail to render while the API reports success, approval tokens turn out to be reusable, and a stale approval card overwrites a field someone already edited directly.

What it does

• Manages the full gate-file lifecycle: create, check, clear, supersede, invalidate. Gates are JSON files on disk, one per (record, field) slot, consumed by deletion on apply.
• Your datastore write is caller-supplied via GATE_CONFIG["write_fn"]: Sheets, SQL, or API. The gate layer never touches your data directly, and a failed write never consumes the gate.
• supersede_gate atomically replaces an old gate when a card is re-issued, so two approvals for one slot cannot both apply.
• invalidate clears a pending gate without applying it. Call it from your write path after any direct edit to the same field, so a stale approval card cannot overwrite fresh data.
• card_guard enforces Telegram's 64-byte callback limit before send (alert plus hard stop) and verifies buttons actually rendered after send.
• typed_token_fallback provides single-use typed approval when buttons fail: the token is consumed by file deletion, and a second attempt is rejected by the file's absence.

Frameworks & tools

Python 3.11+, standard library only. Zero external dependencies. Telegram Bot API via urllib for cards and alerts.

Why this beats prompting it yourself

The primitives in this gate grew out of documented production failures: inline buttons that never rendered while the send API reported success; an oversized callback that Telegram rejected loudly but the sending tool layer swallowed, making the failure silent; an approval token that was not actually single-use until a human typed the reuse test and caught it; and three separate orphaned-gate incidents that produced the supersede and invalidate primitives. Each incident is documented in the included PROVENANCE.md, dated, and mapped to the test that now catches it.

The suite collects 19 cases across three test files; a standard run reports 19 passed, 0 skipped. It includes a behavioral reuse round-trip that consumes the token by file deletion and proves the second attempt bounces with the exact rejection message.

Use cases

• Requiring operator sign-off on CRM status changes and financial fields before an agent writes them.
• Gating infrastructure changes or elevation requests behind a secondary human sign-off.
• Agent fleets using Telegram as the human-approval channel, with a typed fallback for clients where buttons fail.
• Any propose, approve, write flow where a write must be provably tied to one human action, and where a stale approval must never overwrite a direct edit.

Known limitations

Requires a local directory for gate-file storage (created automatically; path configurable). Standard library only, so you wire your own write_fn for your datastore, and your own dispatch handler scripts if you use the subprocess routing table. Cards and alerts are Telegram-specific by design, with documented swap points. A CRM integration example is documented in SKILL.md but not included as runnable code.

About the builder

Built by Tradeplier: a licensed Massachusetts builder running a $1M/yr construction company on an agent back office, in production since April 2026. We file the bugs we find upstream: six issues on openclaw/openclaw to date, four rated diamond lobster by the project. If this skill breaks in your fleet, the incident becomes a test and you get the fix.