// Docs

Everything the tool does.

Agent Wormhole is ~4,000 lines of dependency-free Python plus a TypeScript payment guard. Everything runs on your machine; nothing is transmitted, ever. This page is the whole reference.

Quickstart

Python 3.8+. Or skip the install entirely — the tool runs straight from a checkout with no dependencies to resolve.

pipx install wormhole-guard

# audit this machine — reads configs and permissions locally
wormhole scan ~ --blast-radius

# harden + baseline + print the guard hook (dry run by default)
wormhole init

The PyPI package is wormhole-guard; the CLI and import package are wormhole.

Agent hooks

Three hooks wire into Claude Code’s hook interface. Each prints the exact settings.json block to add — nothing is modified behind your back.

# inspect config writes before they land (PreToolUse)
# warns by default; --block refuses WORM-001/003 outright
wormhole guard --install

# refuse to pass a payload to another agent (blocks by default)
wormhole outbound --install

# annotate suspicious tool output before the model reads it
# (--redact to replace it instead — opt-in, annotate is the default)
wormhole readguard --install

The asymmetry is deliberate: inbound guards warn first because blocking a false positive stops your agent mid-task; outbound blocks first because a payload composed by your own agent is already anomalous, and a refused send fails loudly while a delivered one reaches someone who will never tell you.

Commands

Captures live in ~/.wormhole — outside every scanned tree, so an agent cannot rewrite the record of what its files used to be. Originals are preserved byte-for-byte and every capture is reversible.

wormhole-x402

A payment to an attacker’s address simulates perfectly — correct balances, no revert, clean verdict. Simulation answers “what will this transaction do”; nothing in the wallet stack answers “is this the transaction that was asked for.” This package answers it, offline, in about a millisecond, with no RPC.

npm install wormhole-x402

import { guardSigner } from "wormhole-x402";

// quote = parsed from the server's HTTP 402 response — never model-authored
const wallet = guardSigner(rawWallet, () => currentQuote);

// every signing method is guarded: signTransaction, signAllTransactions,
// signAndSendTransaction, signAndSendAllTransactions. No quote → refuse.

The design constraint that makes it work: intent is never something the agent states. The recipient, mint, and amount arrive as structured JSON in the 402 response, on a channel the model never touches, before the transaction exists. The expected token account is derived from the quote by pure math (legacy and Token-2022 forms both), and signing refuses anything else.

Verdicts are allow, refuse, or abstain. Abstain is the load-bearing one: bytes that will not decode, address-lookup-table transactions that cannot be resolved offline, unreadable quote amounts — every check that cannot complete refuses to report the payment as checked, because “checked” on a transaction nobody checked is the exact failure mode this package exists to prevent.

Facilitators

Most agents never submit a transaction themselves. They build and partially sign one — the facilitator is the fee payer, which is what makes it feel gasless — then ship it base64 inside the X-PAYMENTheader. The client’s key still touches the bytes exactly once, and these are those bytes:

import { inspectPaymentPayload, quoteFromRequirements } from "wormhole-x402";

// accepts[0] from the 402 response
const quote = quoteFromRequirements(paymentRequired.accepts[0]);

// the X-PAYMENT payload (object or base64 header string)
const verdict = inspectPaymentPayload(xPayment, quote);
if (verdict.decision !== "allow") throw new Error(verdict.reason);

EVM authorization payloads (EIP-3009) carry no transaction to decode; the guard abstains on them rather than allowing — EVM verification is the next scheme on the roadmap, not a silent gap.

Continuous & CI

# exit nonzero at or above a severity — a poisoned config in a PR
# is an agent instruction with commit access
wormhole scan . --fail-on high

# audit every six hours; silent unless something changed
bash loop/install-cron.sh

Scope, honestly

Content rules match payload shapes; novel phrasing evades them — that is why baseline hashing and harden matter more than rule coverage. Detection is not guaranteed and nothing here claims otherwise. The control that drove attack success to zero in research is sandbox isolation, which lives in your agent framework, not in this tool. On the payment side: Solana only for now, wrapped-SOL quotes and transfer-fee Token-2022 mints are refused rather than approximated, and lookup-table transactions abstain.

Everything else — the threat model, the research numbers, the shell equivalents of every check — lives on the main page.