Governed tool execution for agent loops.
Your agent loop wants to send the email, write the file, hit the API. You want a human decision in between — one that an agent cannot fake, replay, or bend to different arguments — and a line in an audit log either way.
propose(tool, args) ──> permit (signed, TTL, single-use)
──> approve (a human, out-of-band: CLI, or any callable)
──> execute (verify + burn, atomically)
──> one audit line lands (append-only JSONL)
permitd is that flow as a small, stdlib-only Python library. It is also loop state: the permit lives in SQLite, so a call proposed in turn N of your agent loop is approved from another terminal and executed in turn N+K — across restarts, across processes.
Every non-execute outcome is fail-closed. A missing, expired, denied, tampered, argument-mismatched, or already-used permit is refused, and the refusal is audited too.
pip install permitd
Python ≥ 3.10, zero dependencies.
Terminal 1 — the agent side (agent.py):
import time
from permitd import Gate, RED
gate = Gate(db="permitd.db")
@gate.tool(tier=RED, description="send a message to someone")
def send_message(to, body):
return f"delivered to {to}: {body!r}"
args = {"to": "alice", "body": "hello from the loop"}
r = gate.call("send_message", args)
print(r.error) # "... permit PRM-xxxx is proposed ..."
pid = r.permit["id"]
while gate.get(pid).status == "proposed": # this state survives restarts
time.sleep(1)
r = gate.call("send_message", args, permit_id=pid)
print(r.result if r.ok else r.error)python agent.py
Terminal 2 — the human side:
$ permitd pending
1 pending permit(s):
PRM-3f9c21ab44de [proposed] send_message
args: {"to": "alice", "body": "hello from the loop"}
proposed: 2026-07-29T18:12:03+00:00 ttl: 300s
$ permitd approve PRM-3f9c21ab44de
approved — PRM-3f9c21ab44de is executable for 300s, single use, bound to exactly these arguments
Terminal 1 wakes up and prints delivered to alice: 'hello from the loop'.
The trail:
$ permitd audit
{"ts": "...", "event": "proposed", "permit_id": "PRM-3f9c21ab44de", "tool": "send_message", ...}
{"ts": "...", "event": "approved", "permit_id": "PRM-3f9c21ab44de", ...}
{"ts": "...", "event": "executed", "permit_id": "PRM-3f9c21ab44de", "ok": true}
That is the whole product: propose, approve, execute, audit line.
- Bound to exact arguments. A permit is scoped to
sha256(tool + canonical_json(args)). Approval for "send X to Alice" cannot be replayed as "send Y to Eve" — key order and whitespace don't change the binding; any value change does (args_mismatch). - Single-use, atomically. The burn is one SQLite compare-and-swap
(
UPDATE ... WHERE status='approved'), so two processes racing the same permit cannot both pass (already_used). - Time-boxed twice. A proposal is approvable for
ttl_seconds(default 300); a minted approval is executable for anotherttl_seconds. Unparseable timestamps count as expired. - HMAC-signed. Approval mints
HMAC-SHA256(secret, id.binding_hash.approved_at), re-verified at execute time — a store row edited behind the kernel's back fails (bad_signature). - Fail-closed everywhere. Anything the kernel cannot positively verify — including "the arguments could not even be inspected" — is a refusal, not a pass. Refusals are audited with their reason.
Gate is a small registry with three tiers over the kernel:
| tier | meaning | gate |
|---|---|---|
GREEN |
read-only over your own state | runs freely, audited |
YELLOW |
external read (search, fetch) | one standing toggle: gate.standing_authorization = True |
RED |
write / exec / send | per-call permit: the flow above |
If you don't want the registry, use the kernel directly:
from permitd import PermitKernel, SqliteStore, AuditLog
kernel = PermitKernel(SqliteStore("permitd.db"),
secret_path="permitd.db.secret",
audit=AuditLog("permitd_audit.jsonl"))
p = kernel.propose("deploy", {"target": "prod"})
kernel.approve(p.id) # or from the CLI / your own UI
kernel.execute("deploy", {"target": "prod"}, p.id, runner=do_deploy)approve is just a method on a store-backed kernel — call it from a CLI, a
Slack handler, an HTTP endpoint, wherever your human is.
Before any non-GREEN call runs — including at propose time — its arguments
are scanned for credential-shaped content: private-key blocks, Bearer/Basic
headers, AWS/GitHub/Slack/Stripe/OpenAI/Anthropic/Google key shapes, inline
api_key=... assignments, the values of this process's own sensitive
environment variables, and a conservative high-entropy backstop. A poisoned
context that steers a secret into a tool argument is refused before anything
leaves, before any approval card is shown, and the refusal reason names the
matched shape, never the value.
examples/mcp_server/ is an MCP server whose tools go
through the gate. Point any MCP-speaking agent at it and that agent gets
propose → approve → execute + audit with zero agent-side changes: the
agent calls a RED tool, is told "permit PRM-… proposed, waiting for approval",
you run permitd approve PRM-… in another terminal, the agent retries and the
call executes. The audit line lands either way.
SqliteStore (default, durable, atomic burn) and MemoryStore (tests,
ephemeral) ship in the box. Anything else needs five methods — see the
PermitStore protocol in store.py; keep burn
compare-and-swap or you lose the one-shot guarantee. The audit trail is a
separate append-only JSONL file so it stays tail -f-able.
Not an agent, not a framework, not memory, not RAG. It has no opinion about your loop, your model, or your prompts. It is the layer that holds the state of "may this run?" across turns — and the receipt after it did.
Extracted from the tool-governance kernel of brainfoundry-nous, where it runs in production gating a personal AI node's tools. The propose/confirm/execute + audit grammar goes back to hbar.brain.console (2026-03). Design notes: DESIGN.md.
MIT.