# Trust fabric
Source: https://docs.treeship.dev/concepts/trust-fabric

> Treeship is a trust fabric for AI agents — the universal layer that gives every agent both a verifiable identity and a verifiable work record. This page is the whole architecture in one read.

> **Treeship is the trust fabric, not another agent.**

Once Treeship is installed, attaching any serious agent — Claude Code, Cursor, Codex, OpenClaw, Hermes, or any future MCP-compatible agent — should be a one-config-block change. The output is always the same: a verifiable agent identity plus a verifiable work receipt, regardless of vendor. Two surfaces, one trust story.

## The two surfaces

Treeship's trust fabric has two public artifacts. They bind into a single verifiable record but they answer different questions.

|                  | Identity layer                                                                            | Activity layer                                                        |
| ---------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **URL**          | `treeship.dev/agent/<slug>`                                                               | `treeship.dev/receipt/<id>`                                           |
| **Answers**      | Who this agent represents and what it's allowed to do                                     | What this agent actually did                                          |
| **Built from**   | `treeship agent register` (CLI) → signed `.agent` package                                 | Session events from hooks + MCP + git, sealed in a Merkle tree        |
| **Signed under** | The ship's ed25519 key                                                                    | The same key, plus per-artifact ed25519 signatures inside the session |
| **Binding**      | Cross-verification: every receipt must stay inside its agent's declared `bounded_actions` |                                                                       |

See [Agent Identity](/docs/concepts/agent-identity) for the identity layer, [Session Receipts](/docs/concepts/session-receipts) for the activity layer, and [Cross-verification](/docs/concepts/cross-verification) for the binding.

## Three axes the trust fabric separates cleanly

A clean trust story for agents has to keep three different concerns from collapsing into each other. Treeship treats them as orthogonal:

| Axis                 | Examples                                                                                      | Where it shows up in the receipt                  |
| -------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Agent surface**    | Claude Code, Cursor, Codex, Cline, OpenClaw, Hermes                                           | `agent_name` per event, `agent_graph` per session |
| **Model + provider** | claude-opus-4-7 / anthropic, gpt-5 / openai, kimi-k2 / moonshot, llama / meta, local / ollama | Provider-colored model pill on each agent card    |
| **Tool channel**     | Native hook, MCP gateway, shell wrap, git reconciliation                                      | `source` field on every file row and process row  |

Any agent that speaks MCP attaches via the same gateway. Any model behind that agent gets attributed. Any tool channel that touches the working tree gets witnessed.

## The bar

> **If an agent changes code during a Treeship session and the receipt does not show it, Treeship failed.**

Hooks and MCP cover most paths but not all. An agent that runs `sed -i` inside a Bash command, a build tool that modifies generated files, a developer who manually edits during the session — none of those reach a captured tool channel directly. The trust fabric closes that gap with three complementary layers, ranked by attribution strength:

| Layer | Source                                       | What it sees                                                                          | Trust signal                                                     |
| ----- | -------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| 1     | Specialized event types (`agent.wrote_file`) | Native hook saw the tool fire with full input                                         | `source: "hook"` — highest direct attribution                    |
| 2     | Promoted from `agent.called_tool`            | MCP bridge captured the call; the aggregator inferred direction from tool name + meta | `source: "mcp"` — medium, direction inferred                     |
| 3     | `git diff` at session close                  | Backstop; catches anything missed                                                     | `source: "git-reconcile"` — completeness over direct attribution |

Every file row on a receipt carries one of these `source` labels so a reviewer can see how each change was witnessed, not just that it happened.

## Determinism is a property, not a marketing word

Every artifact Treeship produces is reproducible bit-for-bit from its inputs. This isn't aesthetic — it's the foundation of independent verification.

* **Signatures are deterministic.** Ed25519 signing the same message with the same key always produces the same signature. (RFC 8032 — see the [DSSE explainer](/blog/dsse-dead-simple-signing-explained) for why this matters as a safety property.)
* **Pre-Authentication Encoding is deterministic.** The PAE format used for signing prepends every payload's type and length so the bytes signed cannot be reinterpreted.
* **Receipts are deterministic.** The session receipt is a pure aggregation over the event log. Same events in, same `receipt.json` out, same merkle root, same package digest. See [`treeship package inspect`](/docs/cli/package).
* **Verification is deterministic.** The verifier runs offline on your machine. No network call, no clock skew tolerance applied silently — the caller passes `now` explicitly.
* **Reconciliation is deterministic.** Git reconciliation at session close uses a `BTreeMap` ordering so two close runs against the same working tree produce byte-identical receipts.

The result: anyone can take a `.treeship` package and an `.agent` certificate, run them through a verifier on a clean machine, and get the same answer Treeship's own renderer got. No server and no account needed.

## How identity gets bound to activity

When you run a Treeship session under a registered agent, three independent records are created and bound together:

1. **The Agent Identity Certificate** (issued at registration) declares `bounded_actions`, `forbidden`, `escalation_required`, and a validity window — all signed under the ship's ed25519 key.
2. **Session events** are emitted in real time as the agent works. Each event records actor, tool, timestamp, and (when present) the file path or command. The event log is sealed in a Merkle tree at session close.
3. **The Session Receipt** is composed from those events plus an optional git-reconciliation pass. It carries the same `ship_id` as the certificate.

[Cross-verification](/docs/concepts/cross-verification) (`cross_verify_receipt_and_certificate` in core, `treeship verify --certificate` from the CLI) takes both artifacts and answers a single question: **did this session stay inside the certificate's authorized envelope?**

The result has four orthogonal checks:

* `ship_id_match` — the receipt is signed by the same ship the cert was issued to
* `within_validity_window` — the session ran while the cert was still valid
* `unauthorized_calls` — count of tool calls outside `bounded_actions` (must be zero)
* `never_called` — declared tools the agent didn't end up using (informational; useful for tightening the next cert)

The agent card surfaces this binding visually as a "✓ no unauthorized calls" badge alongside each recent receipt.

## Capture → normalize → reconcile → receipt → verify

The end-to-end pipeline:

```
   Native hooks    ┐
   (Claude Code)   │
                    │
   MCP bridge      ├─▶  events.jsonl  ──▶  ReceiptComposer  ──▶  receipt.json
   (Cursor/Codex/  │    (signed in     │    (deterministic       │   (canonical
    Cline/...)     │     real time)    │     aggregation;        │    JSON,
                    │                   │     git-reconcile       │    sealed in
   treeship wrap   │                   │     adds backstop)      │    merkle root)
   (shell)         ┘                   │                          │
                                        │                          ▼
                                        │              treeship package verify
                                        │              cross_verify_receipt_and_certificate
                                        │              (offline, deterministic)
                                        ▼
                              Sealed in merkle root
                              alongside the per-artifact
                              ed25519 signatures
```

Each stage has its own concept doc:

* **Capture**: [Session Receipts](/docs/concepts/session-receipts) covers the event model. The integration READMEs (`integrations/claude-code-plugin/`, `integrations/cursor/`, `integrations/codex/`, etc) cover per-vendor instrumentation. The MCP gateway is documented in [`bridges/mcp/ATTACHING.md`](https://github.com/zerkerlabs/treeship/blob/main/bridges/mcp/ATTACHING.md).
* **Normalize**: handled inside `SideEffects::from_events` in `packages/core/src/session/side_effects.rs`. Generic `agent.called_tool` events with file-path metadata get promoted into `files_read` / `files_written` / `processes` so the receipt's headline sections actually reflect the work.
* **Reconcile**: `packages/core/src/session/git.rs` runs `git diff` at session close and synthesizes events for changes no captured channel saw.
* **Receipt**: [Session Receipts](/docs/concepts/session-receipts) covers the on-disk format and the package layout.
* **Verify**: [Trust model](/docs/concepts/trust-model), [Cross-verification](/docs/concepts/cross-verification), and [`treeship package verify`](/docs/cli/package) cover the offline check.

## What this is not

* **Not a hosted runtime.** Treeship doesn't execute agents. It records what they do.
* **Not a single-vendor stack.** The MCP gateway makes any MCP-compatible agent an equal citizen. Skill-based agents (Hermes, OpenClaw) attach via skill files rather than MCP.
* **Not a payment layer by itself.** x402 / lobster.cash payment flows can be wrapped via `treeship wrap` and recorded into the same receipt, but identity-of-payment is a separate concern from identity-of-agent.
* **Not a moderation tool.** The certificate declares what an agent is *allowed* to do. Whether that envelope is appropriate is a policy question, not a Treeship one.

## Where to go next

* New to Treeship? [Quickstart](/docs/guides/quickstart) gets you a verified receipt in 90 seconds.
* Want to understand the activity layer? [Session Receipts](/docs/concepts/session-receipts).
* Want to understand the identity layer? [Agent Identity](/docs/concepts/agent-identity).
* Want to understand the binding? [Cross-verification](/docs/concepts/cross-verification).
* Want to attach a new agent? [`bridges/mcp/ATTACHING.md`](https://github.com/zerkerlabs/treeship/blob/main/bridges/mcp/ATTACHING.md).