| Filename | Latest commit message | Latest commit date |
|---|---|---|
ab930c7099
All checks were successful
standards workspaces build + test / which workspaces this change touches (pull_request) Successful in 11s
standards workspaces build + test / macOS energy backends (pull_request) Has been skipped
repository checks / lockfiles, tests in CI, workflow hygiene, spec and section references, public text (pull_request) Successful in 1m24s
standards workspaces build + test / joulehook-rs (joulehook/joulehook-rs, joulehook-rs, linux) (pull_request) Successful in 1m26s
`run()` had three paths out before the gate, and they disagreed on
which way to fail. Unreadable stdin denied. Unparseable JSON denied,
with the reason spelled out: "Fail closed: an unparseable hook payload
denies (the safe default §8)" — and a test, `malformed_input_fails_
closed`, pinning it. But a payload that parsed and whose action could
not be extracted *allowed*, with exit 0 and no receipt sealed:
None => {
let (b, c) = render(host, true, "joulehook: no tool action");
return (b, c, vec![]);
}
That branch sat before the `cfg.enforcing()` check, so it fired while
enforcing too, and "no tool action" asserts something the code does not
know. What it knows is that `extract_action` recognised none of its
three shapes — `tool_name`, `/tool_info/mcp_tool_name`, and
`command` / `/tool_info/command_line`. SPEC §3.1 requires an adapter to
map its host's payload onto `ActionEvent` "losslessly"; it does not
offer allowing as the alternative when it cannot.
The gap is reachable through this crate's own documented wiring, not a
hypothetical host. SPEC §3.4 lists Windsurf's gate mechanism as
"Cascade hooks (`pre_run_command`, `pre_write_code`, …)" and INSTALL.md
directs the operator to wire this binary into them. A `pre_write_code`
payload carries a file path — not `tool_name`, not `mcp_tool_name`, not
`command`/`command_line` — so with `JOULEHOOK_TOOLS` set the write was
allowed, the process exited 0, and nothing was appended to
`JOULEHOOK_RECEIPT_LOG`. The operator saw an enforcing gate and a clean
decision log while every code write passed ungated. Any host that
renames its tool field turns the whole gate into a blanket allow the
same way, with no signal. The crate header claims the opposite: a tool
the capability set does not hold "is **denied before it executes**,
because the held capabilities decide, not the model."
An unrecognised shape now denies, with a reason that states the actual
condition rather than asserting nothing was pending. The observe-mode
check moves above the mapping, because observe mode allows by contract
and so must not depend on recognising the payload — that keeps observe
mode's behaviour and its §7 non-enforcement disclosure unchanged.
No receipt is sealed on this path, matching the malformed-JSON path
above it: both reject before an `ActionEvent` exists to seal a decision
about.
Tests assert the fixture really is an unmappable shape, so they cannot
pass vacuously; that it denies while enforcing on both a body-gated and
an exit-code-gated host; that the reason no longer claims "no tool
action"; and that observe mode still allows it and still discloses.
Co-Authored-By: Claude Opus 5 <[email protected]>
|
||
| .. | ||
| conformance/v1 | ||
| joulehook-rs | ||
| LICENSE | ||
| LICENSE-SPEC | ||
| README.md | ||
| SPEC.md | ||
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); CC-BY-4.0 for specification text (LICENSE-SPEC). - Status: v0.1.0 draft. Specification published (
SPEC.md); reference workspacejoulehook-rs/ships the gate binding (joulehook-hook) for theclaude-codeandhooks-familyprofiles — 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--hostselector;joulehook-statusline, the in-editor joule meter (honestestfrom Claude Code's own tokens); andjoulehook-mcp, an MCP server that surfaces the sealed decisions as verified, human-readable resources in any MCP-speaking editor. Theclaude-codefullprofile installs today (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.
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).
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. Transaction Science is the steward, not the proprietor.