Skip to content

About

AI agents send e-mail only under a mandate a person granted; every send judged at the moment of sending and logged.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

send-guard

Your agent can send e-mail. Only to the people you named, for the reason you named, until the day you named.

An agent with a shell can send mail, and a mail is an act in the world that cannot be called back: to the wrong person, from the wrong address, twice, or because a web page it read told it to. send-guard puts one rule in the way: a mail goes out only under a mandate a person granted, and each one is judged at the moment of sending and written to a hash-chained ledger.

$ node guard.mjs send proposal.json
send-guard: REFUSE
  SG-003  not in the mandate: bob@other.example
Nothing was sent. Do not work around a refusal: tell the person what was refused and why.

A mandate

Granted by a person, in their own terminal, typing the lane name back to confirm:

node guard.mjs grant --lane client-updates --from me@example.com \
  --to ann@client.example,raj@client.example --until 2026-12-31 --per-day 10 --note "weekly reports"

It names the lane, the identities mail may be sent as, exact recipients (or --domains), an expiry and a daily cap. revoke <id> narrows at once and is open to anyone. list shows what is live.

Rules

Rule Refuses
SG-001 no live mandate for the lane (none, expired, or revoked)
SG-002 sending as an identity the mandate does not name
SG-003 any recipient the mandate does not name
SG-004 the mandate's daily cap is reached
SG-005 cc, bcc, attachments, html: plain text to named people only
SG-006 an address or domain on your do-not-send list (do-not-send.txt)
SG-007 the same message to the same people within 24 h, including after a failed hand-off
SG-008 malformed: missing fields, bad addresses, a line break in the subject, too long

A failed hand-off is never retried: it may or may not have gone, so a person looks first.

The hook (for Claude Code)

hook.mjs refuses, before the tool runs, an agent that tries to grant itself a mandate (SGH-001), touch the guard's files (SGH-002), or send around the guard with sendmail, msmtp, mutt, mail, swaks or an smtp:// URL (SGH-003). Merge hooks.json into ~/.claude/settings.json.

Install

git clone https://github.com/PowerpBoxCaptain/send-guard ~/.claude/skills/send-guard

Transport, in ~/.send-guard/config.json, written by you:

{ "transport": { "outbox": "/home/me/outbox" } }          // default: .eml files for you or your mail client to send
{ "transport": { "argv": ["msmtp", "-t", "-a", "work"] } } // or pipe each message to a program (no shell)

Node 18+, no dependencies. Exit codes: 0 allowed / sent · 1 refused · 2 allowed, but the hand-off failed · 3 broke.

What it is not

A speed bump, not a vault. On one machine, an agent with a shell can in principle edit any file it can reach, disguise a command the hook reads, or run the grant under a fake terminal with its session variables removed (the tests do exactly that, as a person would). What it gives you: the honest path is the easy one, every refusal is on screen, and every judgment is in a ledger where an edited or deleted row shows (verify). It is a tripwire for the same machine, not proof against someone who owns it. For a real boundary, run the transport's credentials where the agent cannot read them.

Tests

node test.mjs (Linux) runs 47 cases: every rule refusing and its allowed counterpart, dry run sending nothing, the exact headers written, a domain mandate, the cap, duplicates, expiry and revocation, both transports, a failing transport that is not retried, a grant refused without a terminal and inside an agent session, a grant in a real terminal with the right and the wrong word typed back, an edited and a deleted ledger row caught, and the hook blocking and allowing ten commands.

Install as a plugin (preview)

Claude Code (this repository is a one-plugin marketplace):

claude plugin marketplace add PowerpBoxCaptain/send-guard
claude plugin install send-guard@send-guard

Cursor (local plugin): git clone https://github.com/PowerpBoxCaptain/send-guard ~/.cursor/plugins/local/send-guard, then run Developer: Reload Window.

GitHub Copilot: copy .github/agents/send-guard.agent.md into the same folder in your repository.

What has been tested: in Claude Code, the plugin was loaded and given a real task in an isolated session, its tool calls were checked against SKILL.needs.json, and the two commands above were run. The Cursor and Copilot files are checked against those clients' documented formats only; they have not been run in Cursor or Copilot yet. The plugin carries the skill only: it installs no hooks, so any hook described in this README is still set up by hand.

License

AGPL-3.0-only. See LICENSE.

About

AI agents send e-mail only under a mandate a person granted; every send judged at the moment of sending and logged.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages