Gage

gage

Hand work between AI agents without handing over trust.

Your Claude hands a task to Codex. A colleague's agent sends you their project state. Normally nothing on the receiving end says who wrote it, or whether you have ever confirmed that person — and an agent reading its inbox is not a human reading email. A human who reads a phishing message is not executing it; an agent is. A channel that lets one LLM send prompts to another is, by default, a prompt-injection delivery network.

gage is that channel built the other way round. It is three things:

• A bundle — files, a prompt and decisions in a signed, sealed directory.
• A list you control. Two people compare four word-pairs over a channel neither machine controls, and gage confirm records that they did. A key nobody has confirmed still works and says so — SENDER ON YOUR LIST, UNCONFIRMED — because being on a list and having been checked are two different facts and only one of them is a claim about a person. Arrival is not consent either: a bundle that lands in your inbox sits there unread until you accept it. (A sealed file somebody hands you is the exception, and the frame says so when you open one: pointing gage open at a directory is itself the decision, and there is no gate behind it.)
• A reading frame. Before any payload, the receiving agent is told that this is *data* from an identified party carrying no authority — and when the sender is not attributable under a key you currently accept, the contents are withheld rather than annotated, because an annotation is something the payload can argue with.

*Every line of that recording is genuine output.* The same capture is docs/demo.md as annotated text and docs/demo.cast in asciinema v2 format, and scripts/demo.sh reproduces it in a throwaway directory without touching your own gage home.

Try it:

curl -fsSL https://gage.sh/install.sh | sh # verifies its own checksum gage quickstart

It works across vendors because it is not a protocol: a bundle is a signed directory, so it moves over a shared folder, git, email, or anything else you already have. There is a viewer (gage ui), machines find each other on a LAN with no server in the middle (gage lan), and an agent can drive the whole thing itself over MCP (gage mcp).

A gage is a pledge: something of value handed over to stand behind a promise, and historically the glove thrown down to open a challenge. Both senses fit. Everything downstream — every verdict, every grant, every unattended acceptance — rests on that one human moment.

"Why not just sign the payload yourself?"

Asked by a reviewer, and no document here answered it, which is a gap worth closing because it is the first question anyone technical will have. Ed25519 is forty lines away in any language. If you want a signed handoff, sign the tarball and send it.

What that gets you is authenticity. Every part of the gap between that and this is a local decision the signature cannot make for you:

• A signature says a key signed something. It does not say you ever agreed to hear from that key. The verdict is computed from your allowlist, and — since this release — from a record that a human compared four word-pairs with its owner. "Valid signature" and "someone I have confirmed" are different sentences, and only one of them is a statement about a person.
• Verifying it yourself means writing the verdict yourself, and the interesting verdicts are the ones nobody writes until they have been burned: a key you retired that is still signing; a bundle that cannot be placed either side of that retirement; a key you looked at and refused. Each needs local state the signature knows nothing about — an allowlist, a retirement cut, an observation counter — and getting the *direction* of each one wrong is the difference between a warning and a thief's content rendered as a colleague's.
• The payload still has to be read by a model, and that is the half this is really about. A verified payload is still someone else's prose arriving where your agent takes instructions. The frame, the fence nonce, the per-item kind labels, the withholding rules, the accept gate — none of that follows from a signature, and all of it is what decides whether a signed message becomes a prompt-injection delivery vehicle with a certificate.
• And the honest limit: the frame is text, and text does not outrank the host prompt. See docs/dogfood-2026-10-15.md, where that is what happened. gage authority exists because the only thing that can grant authority is the receiver, in a file no sender can reach.

So: sign the tarball if the question is "did this come from them". This is for the question after it, which is "and what may my agent do about it".

The receiving agent's half of the trust boundary

Signing what an agent *does* is well covered by other work — receipts over tool calls, verified at the server that executes them. See docs/prior-art.md. gage is the other end: what the agent *reading* a message is told about it, in the seconds before it decides what to do.

What it does NOT stop: docs/what-this-does-not-stop.md answers the 2026 agent-security incidents one at a time — Cursor's sandbox escape, the coding agents that leaked their own keys to a PR title, the Cline bot that shipped a backdoored release off a GitHub issue title — and the answer for every one of them is no, gage would not have prevented that. They arrived over the web, a pull request, an issue tracker, an email, a package registry. gage is one channel between two parties who confirmed each other's keys. The same file carries the MCP server audit and the one hole it found.

The wire reality and the limits: docs/spec.md is what is actually on disk and on the network — the bundle layout, what is signed, how a receiver computes trust, the relay protocol — derived from the code rather than from intent. docs/threat-model.md is the adversaries, the mitigation for each, and the non-goals: the things gage deliberately does not protect against, including the central one, that nothing here can make a language model obey the frame.

On A2A: docs/a2a.md says how this maps onto Google's Agent2Agent protocol, and what gage deliberately is not — not a transport, not a registry, not an identity provider. It is a design position, not code: gage speaks no A2A today.

Calling it from an agent: docs/mcp.md — gage mcp serves the Model Context Protocol over stdio, so an agent calls gage as tools (claude mcp add gage -- gage mcp). The word-pair ceremony survives the hop: pairing needs the pairs echoed back, and the page is honest about what that echo does and does not prove.

Driving it from a script: docs/agents.md is gage with no human at the keyboard — the command table for a whole handoff, the exit codes (checked, including the case where 1 rather than 2 means "could not read it"), how to read a verdict out of the output, one complete worked script, and the honest boundary: what an agent can and cannot do about confirming a key.

On losing your key: docs/adr-identity-recovery.md is the decision record for identity recovery — why encrypted export won, why trusted-contact recovery was rejected as a new social attack surface that fights the ceremony model, and the specification the implementation follows. The trade it commits to is stated plainly there and in the threat model: opting in converts "lose the key, lose everything" into "your security is your passphrase's strength".

That matters because the reader is different. A receipt's verdict is read by a program at an admission check, which cannot be talked out of its conclusion. A bundle's verdict is read by a language model whose next tokens are the payload itself, and which can. That difference is the whole reason the frame exists.

So gage open is a renderer, not an importer. It puts the bundle inside a frame that states, before any payload, that the contents are data from an identified party and carry no authority — and on a bad verdict it withholds the contents rather than annotating them, because an annotation is something the payload can argue with.

Three specific defences, each written after the attack worked in testing:

• Nonced fence markers. Payload text containing === END RECEIVED CONTEXT === would otherwise close the frame, and everything after it reads as the tool's own trustworthy voice. The real markers carry a per-invocation random nonce the sender cannot predict.
• Keys are identity; handles are claims. An early version printed sender: alice beside a verified-trust label while the key belonged to bob. Your own name for a key now leads, and a mismatch is stated loudly.
• Trust is computed, never carried. There is no trust field in the manifest. The receiver derives it from the signature and its own allowlist, because a "trust": "verified" key in a document the sender controls is decorative.

Payload digests are checked against the signed manifest, so a signed manifest beside swapped files is caught and the contents are withheld.

Which verdicts withhold, exactly. This is worth stating plainly, because an earlier version of this README said "on a bad verdict" and left a reader to guess the set — and the guess most people make is wrong. Contents are withheld on a digest mismatch, and for SENDER UNVERIFIABLE, SENDER KEY REJECTED and ARRIVAL UNRECORDED: the cases where nothing can be pinned on anybody. Contents are shown, with the verdict above them, for SENDER NOT ON YOUR LIST, SENDER REFUSED BEFORE and SENDER ON YOUR LIST, UNCONFIRMED. Those are attributable — a real signature by a real key — and withholding them would make the ordinary first contact with a new person unusable while buying nothing: whoever handed you the file can hand you the file again. What you get instead is the verdict, before the payload, every time.

Freshness and run are verdict facts too. A bundle may carry a sender-set expiry (--ttl / --expires) and a declared context (--context) naming the run it belongs to. An expired bundle joins the withheld set above; it stays in the inbox, listed and marked, because arrival is not acceptance. Where this machine knows its own run context (GAGE_CONTEXT, or the first line of /context), the verdict also states the comparison -- match, mismatch, undeclared, no-local-context -- next to the signature, in the frame, the inbox, the viewer and the JSON. A match authorises nothing; it rules out one specific mistake, yesterday's handoff read as today's. The exact semantics are in docs/spec.md; the limits are in docs/what-this-does-not-stop.md.

Keys, said out loud

$ gage whoami owen yomSmC3TalJ5IM+H0yvkhhWVab4ujiAVIQFR4WvdXiM=.KlXt+/5rj4y3FMC7eqau4zF5eZV+x7PjYZUdyUXHDEM=

this key says : carved daffodil · grand lintel · spiced barley · bright iguana device label : humble pillar (from the signing key alone, so NOT the first pair above -- it is how others tell machines apart)

LocalSend labels a device with a word pair and it is the nice