permitd 0.1.0__tar.gz

permitd-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

permitd-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing (OIDC) — no PyPI token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

permitd-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+*.db
+*.db.secret
+*_audit.jsonl
+permitd.secret

permitd-0.1.0/DESIGN.md

@@ -0,0 +1,134 @@
+# permitd — design
+
+Created: 2026-07-29
+
+## Step 0 — operator decisions (settled 2026-07-29)
+
+1. **Name:** `permitd`. The daemon-suffix reads as infrastructure, which is the
+   positioning: not an agent, not a framework — the small thing that sits under
+   an agent loop and holds the line.
+2. **License:** MIT. This is an adoption/portfolio play; AGPL-by-reflex was
+   explicitly rejected for this artifact. MIT over Apache-2.0 for brevity — no
+   patent-grant machinery, one page a stranger actually reads.
+3. **Repo:** `hbar-systems/permitd`, **public from day one**.
+
+## What this is
+
+A pip-installable governance kernel for agent tool execution, extracted from
+`brainfoundry-nous` (where it runs in production as the tool-dispatch gate).
+One artifact, two vocabularies, deliberately:
+
+- **Governance vocabulary:** permits, per-call approval, fail-closed
+  verification, append-only audit.
+- **Loop-engineering vocabulary:** state that survives across agent loop turns.
+  A permit proposed in turn N is approved out-of-band and executed in turn
+  N+K — the kernel *is* durable loop state for the human-checkpoint layer.
+
+## The flow (the whole library in one line)
+
+```
+propose(tool, args) → Permit(id, signed, TTL, single-use)
+                    → approve(id)   [out-of-band: CLI, HTTP, any callable]
+                    → execute(tool, args, permit_id) — verify + burn → run
+                    → one audit line lands (JSONL, append-only)
+```
+
+Every non-execute outcome is fail-closed: missing, expired, denied, tampered,
+args-mismatched, or already-burned permits are refused, and the refusal itself
+is audited.
+
+## Core mechanics (carried over from nous, hardened where noted)
+
+- **Binding hash.** A permit is bound to `sha256(tool + "\n" + canonical_args)`
+  where `canonical_args` is sorted-key, tight-separator JSON. Approval for
+  "send X to Alice" can neither be replayed nor bent to "send Y to Eve" —
+  argument order and whitespace can't change the binding; any value change does.
+- **Signed permits (HMAC).** On approve, the kernel mints
+  `HMAC-SHA256(secret, permit_id . binding_hash . approved_at)` and stores it on
+  the record. At execute time the signature is *recomputed and compared* — a
+  store row edited behind the kernel's back (status flipped to approved, hash
+  swapped) fails verification. In nous this pattern is the intra-brain signed
+  permit (`api/identity/permits.py`); here it degrades gracefully to
+  store-tamper evidence since library and store usually share a machine.
+- **Single-use burn, atomic.** nous documented a known limit: its JSON-file
+  store + in-process lock is only atomic single-worker. permitd's default store
+  is SQLite and the burn is one statement —
+  `UPDATE permits SET status='executed' WHERE id=? AND status='approved'` —
+  so two processes racing the same permit cannot both pass, without any
+  application-level lock.
+- **TTL.** Two clocks, both bounded: a proposal is approvable for
+  `ttl_seconds` after propose; a minted approval is executable for
+  `ttl_seconds` after approve (default 300s each). Unparseable timestamps
+  count as expired (fail closed).
+- **Tiers.** GREEN (run freely, audited), YELLOW (requires standing
+  authorization — one operator toggle, audited), RED (per-call permit, the flow
+  above). Same semantics as nous's `api/tools/` registry.
+- **Egress guard.** Ported from nous `api/tools/egress.py`: before any
+  non-GREEN call runs — including at propose time, so a poisoned proposal never
+  even reaches the approval surface — arguments are scanned for
+  credential-shaped content (private-key blocks, Bearer/Basic headers,
+  AWS/GitHub/Slack/Stripe/OpenAI/Anthropic/Google key shapes, inline
+  `secret=...` assignments), for the process's own sensitive env-var *values*,
+  and by a conservative high-entropy backstop (URLs excised — signed CDN URLs
+  false-positive on entropy; named patterns still scan full text). Refusal
+  reasons name the matched *shape*, never the value.
+- **Audit.** Append-only JSONL, one line per outcome (proposed, denied,
+  expired, blocked, executed, failed), best-effort by contract: an audit write
+  failure must never break the dispatch path. Arg values are trimmed in audit
+  lines; the approval surface, by contrast, always shows full args — it is the
+  operator's informed-consent surface and must not truncate.
+
+## Storage
+
+Pluggable via a small `PermitStore` protocol. Shipped:
+
+- `SqliteStore` — default; atomic burn; safe across processes on one machine.
+- `MemoryStore` — tests and ephemeral gates.
+
+Audit is a separate append-only JSONL file (not in SQLite) so it stays
+`tail -f`-able and trivially exportable.
+
+## Deliberately OUT
+
+Brains, RAG, memory, federation, budgets/metering, any UI beyond the approve
+CLI. No framework dependencies in the core — stdlib only. The MCP server under
+`examples/` is the only place a third-party package (`mcp`) appears, as an
+optional extra (`pip install permitd[mcp]`).
+
+The core is synchronous. Tool callables are plain functions; async frameworks
+(the MCP example included) call the gate from their event loop — the gate's own
+work is milliseconds of hashing and one SQLite statement.
+
+## The MCP wedge
+
+`examples/mcp_server/` is one example that is also the positioning: an MCP
+server whose tools are gated by the kernel. Any MCP-speaking agent — Claude
+Code included — gets propose/approve/execute + audit for free: the agent calls
+a RED tool, receives "permit PRM-… proposed, waiting for approval", a human
+runs `permitd approve PRM-…` in another terminal, the agent retries and the
+call executes with the audit line landing. No agent-side changes at all.
+
+## Ancestry
+
+- `hbar-systems/hbar.brain.console` (2026-03) — the original
+  PROPOSE/CONFIRM/EXECUTE + audit-trail prototype; the interaction grammar
+  started there.
+- `brainfoundry-nous` — the kernel as lived in production:
+  `api/tools/__init__.py` (tiers + dispatch gate), `api/tools/approvals.py`
+  (single-use args-bound tokens), `api/tools/egress.py` (outbound scan),
+  `api/tools/audit.py` (JSONL trail), `api/identity/permits.py` (typed,
+  time-bound signed permits). permitd is an extraction, not a fork: nous keeps
+  its copy; divergence is expected and fine.
+
+## Positioning inputs
+
+`discussions/2026-07-12_brainfoundry-loop-state-layer-reframe.md` and
+`discussions/2026-07-12_brainfoundry-competitive-landscape-memory-governance.md`
+(hbar.world): the governance kernel and the MCP loop-state wedge are ONE
+artifact; README speaks both languages; ride the loop-engineering vocabulary
+while it is current.
+
+## Acceptance test (the only definition of done)
+
+Clean machine, `pip install`, a stranger follows the README:
+propose → approve → execute → the audit line lands. Nothing else counts.

permitd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hbar-systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

permitd-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: permitd
+Version: 0.1.0
+Summary: Governed tool execution for agent loops: propose -> permit -> approve -> execute -> audit. Fail-closed, zero dependencies.
+Project-URL: Homepage, https://github.com/hbar-systems/permitd
+Project-URL: Issues, https://github.com/hbar-systems/permitd/issues
+Author: hbar-systems
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agent-loops,approval,audit,governance,human-in-the-loop,loop-engineering,mcp,permits,tool-use
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# permitd
+
+**Governed tool execution for agent loops.**
+
+![An agent proposes a gated call, a human approves it in another terminal, the call executes, and the audit lines land](docs/demo.gif)
+
+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.
+
+## Install
+
+```
+pip install permitd
+```
+
+Python ≥ 3.10, zero dependencies.
+
+## Sixty seconds, two terminals
+
+**Terminal 1 — the agent side** (`agent.py`):
+
+```python
+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.
+
+## What the permit actually guarantees
+
+- **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 another `ttl_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.
+
+## Tiers
+
+`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:
+
+```python
+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.
+
+## The egress guard
+
+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.
+
+## MCP: gate any agent's tools, including Claude Code's
+
+[`examples/mcp_server/`](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.
+
+## Storage
+
+`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`](src/permitd/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.
+
+## What permitd is not
+
+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.
+
+## Ancestry
+
+Extracted from the tool-governance kernel of
+[brainfoundry-nous](https://github.com/hbar-systems/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](https://github.com/hbar-systems/hbar.brain.console)
+(2026-03). Design notes: [DESIGN.md](DESIGN.md).
+
+## License
+
+MIT.

permitd-0.1.0/README.md

@@ -0,0 +1,180 @@
+# permitd
+
+**Governed tool execution for agent loops.**
+
+![An agent proposes a gated call, a human approves it in another terminal, the call executes, and the audit lines land](docs/demo.gif)
+
+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.
+
+## Install
+
+```
+pip install permitd
+```
+
+Python ≥ 3.10, zero dependencies.
+
+## Sixty seconds, two terminals
+
+**Terminal 1 — the agent side** (`agent.py`):
+
+```python
+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.
+
+## What the permit actually guarantees
+
+- **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 another `ttl_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.
+
+## Tiers
+
+`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:
+
+```python
+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.
+
+## The egress guard
+
+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.
+
+## MCP: gate any agent's tools, including Claude Code's
+
+[`examples/mcp_server/`](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.
+
+## Storage
+
+`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`](src/permitd/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.
+
+## What permitd is not
+
+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.
+
+## Ancestry
+
+Extracted from the tool-governance kernel of
+[brainfoundry-nous](https://github.com/hbar-systems/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](https://github.com/hbar-systems/hbar.brain.console)
+(2026-03). Design notes: [DESIGN.md](DESIGN.md).
+
+## License
+
+MIT.

permitd-0.1.0/examples/mcp_server/README.md

@@ -0,0 +1,52 @@
+# permitd MCP example
+
+Created: 2026-07-29
+
+An MCP server whose tools go through the permitd gate. Any MCP-speaking agent
+gets propose → approve → execute + audit for free — no agent-side changes.
+
+## Setup
+
+```
+pip install "permitd[mcp]"
+```
+
+### With Claude Code
+
+```
+claude mcp add permitd-demo -- python /absolute/path/to/examples/mcp_server/server.py
+```
+
+### With any other MCP client
+
+Run `python server.py` and connect over stdio.
+
+## The demo
+
+Ask the agent to *"write a note called hello saying hi"*. It calls
+`write_note` and gets back:
+
+```
+write_note needs operator approval before it runs. Permit PRM-9a1b2c3d4e5f is
+proposed — ask the operator to run `permitd approve PRM-9a1b2c3d4e5f`, then
+retry this exact call with that permit_id. ...
+```
+
+In another terminal (the db lives next to server.py):
+
+```
+permitd --db examples/mcp_server/permitd.db pending
+permitd --db examples/mcp_server/permitd.db approve PRM-9a1b2c3d4e5f
+```
+
+The agent retries `write_note(name, text, permit_id="PRM-9a1b2c3d4e5f")` — the
+note is written. Deny instead, and the retry is refused (`denied`). Change the
+text between propose and execute, and it is refused (`args_mismatch`). Every
+outcome is one line in:
+
+```
+permitd --db examples/mcp_server/permitd.db audit
+```
+
+Tools: `read_notes` (GREEN — runs freely, audited), `write_note` (RED — the
+flow above), `pending_permits` (convenience view).