Lockfile specification

agentgate.lock pins the tool surface an agent sees from its MCP servers: for each tool, SHA-256 hashes of its name, description, and input schema — the three fields an upstream rug-pull would mutate. If any of them changes, agentgate diff and agentgate ci fail.

Canonical JSON Schema: docs/spec/agentgate.lock.schema.json (a cross-route contract per docs/ROUTES.md; changes are coordinated in PRs).

Format

{
  "lockfileVersion": 1,
  "generatedBy": "[email protected]",
  "generatedAt": "2026-08-03T12:00:00.000Z",
  "servers": {
    "filesystem": {
      "surfaceHash": "9f2c…64 hex chars…",
      "tools": [
        {
          "name": "read_file",
          "nameHash": "77d0…",
          "descriptionHash": "c56a…",
          "inputSchemaHash": "0e19…"
        }
      ]
    }
  }
}

Fields

Field	Description
lockfileVersion	Format version; this page documents version 1 (the only accepted value).
generatedBy	Tool and version that wrote the file, e.g. [email protected].
generatedAt	ISO-8601 timestamp. Informational only — not part of drift comparison.
servers.<name>	Locked surface per server, keyed by the server name from the client config.
servers.<name>.surfaceHash	SHA-256 over the canonical JSON array of [nameHash, descriptionHash, inputSchemaHash] triples of all tools, sorted by tool name — a fast whole-server comparison.
servers.<name>.tools[]	Locked tools, sorted by name. name is kept in plaintext for readable diffs.

Hashing rules

All hashes are lowercase hex SHA-256:

• nameHash — SHA-256 of the UTF-8 tool name.
• descriptionHash — SHA-256 of the UTF-8 tool description (empty string if absent).
• inputSchemaHash — SHA-256 of the canonical JSON of the tool input schema ({} if absent). Canonical JSON = object keys sorted recursively, no whitespace.

Design goals

1. Reviewable — deterministic output (sorted tools, stable field order) so lockfile diffs in PRs are minimal and meaningful.
2. Tamper-evident — a reworded description (the classic rug-pull payload) flips descriptionHash even though the code is unchanged.
3. Self-describing — lockfileVersion gates format evolution; the CLI refuses to gate against a version it does not understand.