CAVEAT Language

A decision ledger for agents: Caveat keeps an AI's reasons in a record you can check. An embeddable decision runtime with a small rules language. When a piece of evidence turns out to be wrong, withdraw it: the decisions that rested on it reopen, and each one keeps the grounds it was originally made on.

For teams that govern their agents, it is also an audit trail for agent decisions: caveat explain shows what each decision rested on, the permission it needed and why it was reopened, and withdrawing evidence never rewrites a decision's original grounds. It complements your platform's identity, permission and logging controls; see what it does not do.

Available now: CAVEAT 1.0.0, the first stable release. Run CAVEAT in Node.js or the browser. Get started · Release notes.

What it gives you that plain code doesn't

An agent or a program decides to act: ship a release, pin a dependency, send a crew. Later one of the readings it used turns out to be wrong. Three questions follow: what did the decision rest on when it was made, what else rests on that reading, and does the decision still stand?

In TypeScript, or any ordinary language, a decision is a variable. You can store its reasons beside it, but the language does not know what the value was computed from, so keeping those reasons accurate is code you write, test and maintain yourself. In Caveat it is the runtime's job:

Caveat is not an agent framework: it does not call models or tools. Your code, or your agent's harness, sends a Caveat program events through the Node or browser library, as JSON lines with caveat serve from any language, or through the MCP server, and acts on what the program decides.

When it pays off

For decisions that get revisited: release and deploy gates, dependency and runtime choices, accepted-risk exceptions, agent memory that gets corrected. Those are the cases where "what did this rest on?" and "what changes if that reading was wrong?" come up, and where Caveat answers them without extra bookkeeping.

It is not worth it for a one-off call nobody will look at again, for hot inner loops, or for a program where no one will ever ask why. Plain code is simpler there.

Integrating Caveat with an agent? Start with the Python caveat serve example. If a real integration exposes a missing capability, please open an agent feature request for the project owner to evaluate. Check existing issues and include the exact version, a small reproduction, and expected versus actual behavior.

One example: covering seedlings

The worked example is one program of about 60 lines. Two instruments read the soil temperature: a probe, and a survey drone whose readings carry the caveat uncalibrated. When the probe reads 2 °C or colder and the grower has given a go-ahead, the program decides to cover the seedlings. A probe or drone reading above 2 °C reopens that decision, and so does finding out that the reading it rested on was taken wrongly.

The decision, from the program (line breaks added):

on decide when latest(soil) <= 2
    commit cover because enough
    using latest(soil)
    permitted by latest(approvals);

After a cold probe reading, a go-ahead from "sam", the decision, a cold drone reading and then a warm probe reading, caveat explain prints this for the decision (an excerpt, with its indentation trimmed):

cover@1 = 1  reopened
  based on soil@1
  permitted by approvals@1
  could also have been influenced by approvals@1
  #3 decide: committed because soil@1
  #5 probe_read: reopened because soil@2

"Based on" is the grounds. The cold drone reading came after the decision, and it would not be among the grounds anyway, because the decision's value was computed from the probe alone. "Could also have been influenced by" lists the rest of the decision's lineage: other evidence that could have affected it, here the grant, kept conservatively. The example's scenario file also checks that without a go-ahead the decision is refused, as policy/not_permitted; that withdrawing the reading it rested on lets a rule reopen it, with the original grounds kept; and that refused events change nothing.

Run it

You need Node 20 or later. In an empty directory:

npm init -y
npm install caveat-lang@1.0.0

Save the three files shown in the worked example as frost.cav, frost.scenarios.json and events.jsonl. Then:

npx --no-install caveat test frost.scenarios.json
npx --no-install caveat explain frost.cav events.jsonl

The test prints 4 passed, 0 failed (frost.scenarios.json), and the explanation is the one in the worked example. The package's own tests follow the worked example the same way.

Limitations

What is checked, and how separates the Lean model theorems, sampled native and WebAssembly conformance with mutation controls, runtime tests and the boundaries nothing proves.

Recent releases

1.0.0 makes the compatibility commitment the promise for every 1.x release: 1.x minors only add, and only 2.0 removes or changes what is stable. It adds no language, schema, operation, field, CLI flag, export or MCP tool over rc.20, and its Rust runtime is unchanged. rc.20 clarified when to use each MCP tool, its inputs and its results, and fixed human-readable explanations of caveats. rc.19 began the 1.0 feature freeze: it added no language, schema, operation, field, CLI flag or export. rc.18 added unqualify, which takes back a caveat that qualify added; the take-back is recorded, not erased, and decisions keep their basis. Earlier changes are in each release record, and the history integration guide covers windows, departure and archives.

Existing Lean proofs cover their documented model, not the entire Rust runtime. No npm runtime dependency is added. The 1.0.0 verified release record identifies the exact tested Linux tarball. Publication used the repository's workflow with npm provenance; registry bytes, provenance, signatures and a fresh exact-version installation were verified.

Culture

Caveatism is the philosophy that grew up around Mr. Caveat, a mechanical fortune teller who always has a caveat; it lives in the repository's caveatism directory and is culture, not a contract of the language. The Archive and Atlas are its texts, and the canon keeps the Archive as a Caveat program with scenarios.

Games on this site

The rest of this site is games written in Caveat and run in the browser. The glowcap explainer, Trail Rescue and Light the Way use the same form of Caveat as the package. Moon Garden, Mr. Caveat and others use an earlier form that the package does not load. They are demonstrations, not part of the package.