# JouleHook — Metered, Gated, Attested Agent Work in Any Host

*Provisional name — the steward may rename; the profile string `joulehook/1` and the
seam names are the stable surface.*

The energy-accounting and methodology-gating you build for one coding agent is worth
little if it's trapped in that one agent. JouleHook carries it into the editors
developers already use — **Claude Code, Cursor, Windsurf, Antigravity, Zed, JetBrains,
OpenCode** — without forking any of them.

It rests on one finding: **no host lets an extension observe its agent's tokens or
intercept its native tools** — but every host exposes the same three seams, and
JouleHook is the normative contract over them:

> **A per-action *gate*, a model-call *meter*, and a *receipt* surface. Bind those
> three to a decide-outside-the-model grant check, an honest energy meter, and a
> sealed receipt, and any agent's work becomes a metered, gated transaction — from
> one core.**

JouleHook does not replace the host's agent. It is the **host-binding layer** for the
sibling standards: **JCP** decides and grants, **Mesh** meters at the model front
door, **`jcp-efficiency`** is the receipt. JouleHook adds the seam contract and the
per-host conformance profiles that make them portable.

- **Licence:** Apache-2.0 for reference code ([`LICENSE`](LICENSE)); CC-BY-4.0 for
  specification text ([`LICENSE-SPEC`](LICENSE-SPEC)).
- **Status:** v0.1.0 draft. Specification published ([`SPEC.md`](SPEC.md)); reference
  workspace `joulehook-rs/` ships the **gate binding** (`joulehook-hook`) for the
  `claude-code` **and** `hooks-family` profiles — one PreToolUse hook that gates by
  JCP capability (decided outside the model, every decision sealed) and speaks the
  native decision format of Claude Code, Cursor, Windsurf, and Antigravity behind a
  `--host` selector; `joulehook-statusline`, the in-editor joule meter (honest `est`
  from Claude Code's own tokens); and `joulehook-mcp`, an MCP server that surfaces
  the sealed decisions as **verified, human-readable** resources in any MCP-speaking
  editor. The `claude-code` `full` profile installs today
  ([`joulehook-rs/INSTALL.md`](joulehook-rs/INSTALL.md)); the enforcing Mesh-proxy
  meter + a site land next.

## The three seams

| Seam | Host mechanisms | What rides it |
|---|---|---|
| **Gate** | `PreToolUse`-hook family; ACP `request_permission` | allow / deny / rewrite, decided outside the model, sealed |
| **Meter** | `base_url` proxy; OTel `gen_ai.*` | tokens→joules, honest provenance, enforceable joule ceiling |
| **Receipt** | MCP resources; status line; panel | hash-chained, verifiable `efficiency/1` + decision receipts |

## Conformance profiles

`claude-code` (reference) · `hooks-family` (Cursor / Windsurf / Antigravity) · `acp`
(Zed / JetBrains / Neovim) · `opencode` · `cline` · `vscode` (Open-VSX) · `meter-only`
(Continue, any OTel host). See [`SPEC.md §6`](SPEC.md).

## The honest limit

A host-side adapter alone cannot meter the host agent's own tokens; a complete energy
figure requires the Meter seam (proxy or OTel). An adapter that claims whole-session
energy without a bound meter is non-conformant ([`SPEC.md §7`](SPEC.md)).

## What's here

```
joulehook/
├── SPEC.md          — the normative standard (§1–§9)
├── README.md        — this file
├── joulehook-rs/    — reference implementation
│   └── crates/
│       ├── joulehook-hook      — ✅ the PreToolUse gate CLI for the hook family
│       │                          (Claude Code / Cursor / Windsurf / Antigravity via --host;
│       │                          wraps jcp-bridge::LocalToolGate for the JCP check + seal)
│       │                          + joulehook-statusline — ✅ the in-editor joule meter
│       ├── joulehook-mcp       — ✅ the receipt-surface MCP server (sealed decisions →
│       │                          verified MCP resources, any MCP-speaking editor)
│       ├── joulehook-meter     — ✅ the meter-seam binding: inject a grant's budget as
│       │                          the Mesh joule ceiling (enforce) + bridge Mesh's
│       │                          usage.energy into an efficiency/1 receipt
│       └── joulehook-proxy     — ✅ the deployable meter: an OpenAI-shaped base_url
│                                  proxy that caps + seals every model call
└── conformance/v1/  — ✅ reproducible vectors: per-host decision encodings
                        (decisions.json) + a byte-deterministic sealed deny receipt
                        (deny-receipt.hex + receipt.json, verified-decode)
```

JouleHook is one of the [Transaction Science open standards](../README.md).
Transaction Science is the steward, not the proprietor.