Agent Trust Kit

README

<p align="center">
  <img src="docs/assets/social-preview.jpg" alt="Agent Trust Kit — bounded AI-agent handoffs with controller-side verification" width="100%">
</p>

# Agent Trust Kit

**Make every AI-agent handoff explicit: select what leaves, record what returns,
and recheck evidence before you trust or merge it.**

[![CI](https://github.com/mauricemohr88-debug/agent-trust-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/mauricemohr88-debug/agent-trust-kit/actions/workflows/ci.yml)
[![CodeQL](https://github.com/mauricemohr88-debug/agent-trust-kit/actions/workflows/codeql.yml/badge.svg)](https://github.com/mauricemohr88-debug/agent-trust-kit/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-55e6a5.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-36d9ff.svg)](pyproject.toml)
[![agent-packet on PyPI](https://img.shields.io/pypi/v/agent-packet.svg?label=agent-packet)](https://pypi.org/project/agent-packet/)
[![agent-receipt on PyPI](https://img.shields.io/pypi/v/agent-receipt.svg?label=agent-receipt)](https://pypi.org/project/agent-receipt/)

Delegating code is easy. Keeping the handoff narrow—and deciding whether the
returned result deserves trust—is the hard part. Agent Trust Kit gives the
controller an inspectable packet, an explicit evidence record, and an
independent verification step.

| Tool | Boundary it adds |
|---|---|
| [`agent-packet`](packages/agent-packet/) | Builds an allowlist-based handoff archive and rejects known private paths, links, unsafe archive structures, and secret-like text. |
| [`agent-receipt`](packages/agent-receipt/) | Records claims and evidence, then lets a controller repeat explicitly selected checks inside a controller-chosen workspace. |
| [Native Hermes plugin](docs/HERMES_PLUGIN.md) | Adds project registration, operator approval, a fixed return quarantine, and controller-owned verification. |

The intended flow is:

```text
trusted controller -> inspectable packet -> remote worker
trusted controller <- changes + receipt <- remote worker
trusted controller -> independent checks -> accept or reject
```

## Start here

- [Try one local handoff, including a rejected tampered return](#try-one-local-handoff)
- [Follow the complete Hermes/OpenClaw handoff](docs/HERMES_OPENCLAW_FLOW.md)
- [Install and use the native Hermes plugin](docs/HERMES_PLUGIN.md)
- [Understand the security boundary](THREAT_MODEL.md)
- [Review the local validation record](docs/LOCAL_VALIDATION.md)
- [Read the first native Hermes dogfood record](docs/DOGFOOD_2026-08-03.md)
- [Review the isolated Hermes v0.20.0 compatibility check](docs/COMPATIBILITY_2026-08-05.md)

## Try one local handoff

Start with generated example files, not a private repository. With Python 3.10+,
Git, Bash, and [uv](https://docs.astral.sh/uv/) installed:

```bash
git clone https://github.com/mauricemohr88-debug/agent-trust-kit.git
cd agent-trust-kit
uv sync --all-packages --group dev
bash scripts/smoke_e2e.sh
```

The script builds a packet from a tiny example, checks that the fixture's
`.env` and private file are omitted, materializes the packet into a separate
temporary directory, records a `RESULT.md` claim, and rechecks it. It then
changes the result and requires verification to reject it. The expected final
line is `end-to-end smoke passed`; temporary example files are removed on exit.

This demonstrates the local packet → receipt → recheck flow. It does not run
Hermes, contact a worker, test the latest Hermes release, or prove that every
secret would be detected. Dependency installation may use the network. For the
operator-controlled workflow, continue with the
[complete handoff guide](docs/HERMES_OPENCLAW_FLOW.md).

## Install the Python tools

```bash
uv tool install agent-packet
uv tool install agent-receipt
```

The tools are separate commands so a controller or worker can install only the
boundary it needs. `pipx install agent-packet` and `pipx install agent-receipt`
are equivalent alternatives.

The source repository is public. The tools
reduce common handoff mistakes; they do not send packets, sandbox workers,
control every Hermes tool, guarantee that sensitive data is absent, prove that
a worker was honest, or merge returned changes automatically.

## Development

Requirements: Python 3.10+ and [uv](https://docs.astral.sh/uv/). The Python
version matrix is not an operating-system support claim: the native Hermes
plugin currently supports macOS and Linux only.

```bash
uv sync --all-packages --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
```

Package-specific instructions and examples live in each package README. The
[Hermes/OpenClaw walkthrough](docs/HERMES_OPENCLAW_FLOW.md) shows the complete
handoff and independent verification boundary.

## Native Hermes integration

<p align="center">
  <img src="docs/assets/hermes-native-flow.png" alt="The native Hermes flow: prepare, approve, and verify" width="100%">
</p>

The repository root is also a Hermes plugin. It exposes `handoff_prepare`,
`handoff_status`, and `handoff_verify_return`, while keeping approval and local
paths on the operator-facing `hermes agent-trust` CLI. Prepare accepts only a
registered Git project, explicit include paths, and a clean input commit.
Verification uses a fixed private quarantine, requires
`OUTPUT_MANIFEST.json` plus `receipt.json`, performs a full recheck without
executing worker commands, and never merges automatically.

The native plugin supports macOS and Linux. It imports on native Windows so
Hermes can report a deterministic support error, but it does not activate
there. Secure descriptor-relative, no-follow traversal and private-state
semantics need a dedicated Windows backend before native Windows can be
supported; the manifest intentionally remains limited to macOS and Linux.

Install the public repository with:

```bash
hermes plugins install mauricemohr88-debug/agent-trust-kit --enable
hermes agent-trust project add my-project /path/to/git/project
hermes agent-trust doctor
```

The plugin is not a global egress gate or OS sandbox. Other Hermes tools, manual
transfers, unrestricted same-user terminal access, and a compromised host remain
outside its boundary. Read [the plugin guide](docs/HERMES_PLUGIN.md) and the
[threat model](THREAT_MODEL.md) before using it with private work.

Packet, receipt, and output-manifest hashes are byte-exact. If a separately
selected Windows worker or transfer path rewrites LF line endings to CRLF, the
changed bytes will not match the recorded digest. Preserve file bytes across
checkouts and transfers.

## Try it and tell us where you got stuck

We are looking for two independent testers to follow one non-sensitive
handoff. Start with the local example above, then try the native Hermes flow
only if it fits your setup. Share a short, sanitized report in
[issue #3](https://github.com/mauricemohr88-debug/agent-trust-kit/issues/3):

- OS, Python version, tool version or Git commit, and Hermes version if used;
- what you wanted to hand off and which guide you followed;
- the last completed step and the first confusing or failed step;
- whether you needed help and whether you would use it again.

The test is free, asynchronous, and needs no sales call. Do not post private
source, credentials, raw packets, or real receipts. A local smoke run is not
independent two-machine or real-workflow validation.

The full local core stays MIT-licensed. The former
[149 € review pilot](docs/FOUNDING_PILOT_DE.md) and its
[intake](docs/PILOT_INTAKE_DE.md) are **paused**, retained only as historical
scope records; they are not an active booking or 48-hour delivery offer.

## Relationship to Hermes Plugin Guard

[Hermes Plugin Guard](https://github.com/mauricemohr88-debug/hermes-plugin-guard)
remains a separate project: it examines a plugin before activation. These tools
cover the later handoff boundary. They may be used together but have independent
release and support cycles.

## Status

- `v0.1.0` is the first public beta for the native Hermes plugin,
  `agent-packet`, and `agent-receipt`. Tagged releases publish the two Python
  tools through PyPI Trusted Publishing without a stored upload token.
- The dated [local validation record](docs/LOCAL_VALIDATION.md) documents lint,
  the Python 3.10–3.14 test matrix, package builds, wheel-install smoke, and an
  end-to-end handoff. It is not a current CI or latest-Hermes compatibility
  report; the badges link to the live workflows.
- One non-sensitive native Hermes workflow was maintainer-dogfooded; see the
  [2026-08-03 record](docs/DOGFOOD_2026-08-03.md). Feedback from two outside
  testers remains an open beta-validation goal tracked in
  [issue #3](https://github.com/mauricemohr88-debug/agent-trust-kit/issues/3);
  it is not presented as completed evidence.
- An isolated compatibility check against Hermes v0.20.0 (official tag
  `v2026.8.3`) passed the plugin-load and focused smoke coverage; it is not a
  claim that this repository has been live-upgraded. See the
  [compatibility record](docs/COMPATIBILITY_2026-08-05.md).

MIT licensed. See [SECURITY.md](SECURITY.md) for responsible reporting.