Changelog

Added

• An agent set to observe on the guard gets one console.warn naming the decision enforce mode would have given, with its reasons.
• DecisionRecord carries the agent's dashboard name as optional agentName on listed decisions.

Changed

• reportSettlement finds a payment's decision through x402's onPaymentResponse hook, which guard() now registers. It no longer reads the signed PAYMENT-SIGNATURE header.
• Breaking Pass reportSettlement the response wrapFetchWithPayment returned, and call guard() before you register any onPaymentResponse hook of your own.
• Breaking For a paid request sent without wrapFetchWithPayment, pass its response to processPaymentResult on new x402HTTPClient(client) before reportSettlement.
• An x402 client with no onPaymentResponse gets a warning and cannot report a settlement.
• Breaking guard() also registers a payment policy, so Hookable requires registerPolicy. An x402Client from @x402/core 2.24 or later has it. A structural wrapper must expose it.
• Breaking A second guard() on the same x402 client throws. Give each session its own x402 client.
• Breaking observe mode lets a payment through only when the guard did not answer in time. That means it was unreachable, sent a 408 or a 5xx other than 503 payment_screening_unavailable, or ran past its time budget.
• A rate limit, and a page sent for checking that the guard refused, now abort the payment in both modes.
• A page whose read failed or was still arriving after 5 s now aborts the payment in both modes.
• A 402 or decision the SDK cannot read, and a held payment whose review poll failed, now abort in both modes.
• Breaking guard() throws when session is not 1 to 200 characters with no NUL character.
• Breaking guard() and new GuardClient() throw when apiKey is missing or blank. 0.6.0 built and failed on each call.
• Breaking X402Proposal and X402Payment refuse an unknown field, so a caller of vulsight.api.decide must drop fields the API does not take.
• Breaking X402Proposal and X402Payment refuse a scheme that is not lowercase letters, digits, and hyphens. Send exact as the 402 writes it.
• X402Proposal and X402Payment accept x402Version (2 only), assetTransferMethod, paymentFlow, and the 402's extra.
• Breaking TypeScript change RuleId includes payment_method_supported; handle it in exhaustive maps and switches.
• When a seller offers several options, the x402 client pays with one the guard supports instead of aborting on an unsupported first one.
• When a seller offers no supported option, the payment hook refuses before signing, in both modes, and lists up to five of the options offered.
• The payment hook refuses before signing, in both modes, a 402 that is not x402 version 2.
• On Solana, the payment hook refuses before signing a transfer method other than the default.
• The payment carries the 402's declared assetTransferMethod and paymentFlow to the guard.
• X402_SUPPORT and paymentSupport(payment) from @vulsight/guard/types are the supported payments and their check. The API, the advisory MCP tool, and the proxy use the same.
• A refusal of an unsupported payment names the payment's own network.
• reportSettlement reads the older X-PAYMENT-RESPONSE header too, and reports each receipt once. A repeat returns the recorded settlement.
• reportSettlement keeps up to 1000 receipts. It refuses a receipt two payments name, a response from the unsigned vulsight.fetch, and a payment the guard did not decide.
• On a second 402, or a receipt whose success is false, reportSettlement names the seller's reason only for known x402 refusal codes. Anything else is an unknown outcome.
• A reportSettlement error for a short-funded wallet says to wait until the signed payment expires: on EVM when the 402 offer's time limit passes, on Solana when its recent blockhash is no longer valid.
• reportSettlement reports a used or expired authorization, a failed simulation, and settlement_pending as possibly settled.
• A possibly settled error says to check the wallet's transfers to the payee on chain before paying again, and that an allowed or approved amount still counts toward the daily cap for the UTC day the guard checked it.
• In observe mode, a payment's amount counts toward the cap only if enforce mode would have allowed it, or held it and the review timeout has not passed.
• reportSettlement errors that name the paid URL drop its query.
• A payment waits only for pages from its own site, and for text sent for checking under a label that names no site. Another site's unchecked page blocks only payments to that site.
• The review wait tries again after a poll the guard did not answer or rate limited. A refused or unreadable poll aborts at once and names the held decision to check before a retry.
• A held payment prints one console.warn when the wait starts. It names the decision, the Review page at <baseUrl>/review, and how long the SDK waits.
• A payment still held when the wait ends says to deny the open review on the Review page first, then run the payment again. The open review counts toward today's cap until it expires.
• An expired review says to run the payment again and approve it before it expires, or to raise the Review timeout and waitForReviewSeconds with it.
• A refused or failed last review poll links the decision at <baseUrl>/decisions/<id>.
• Breaking The held payment sentences changed, so code that matched the old "Ask your user to review it in the VulSight Guard dashboard." sentence must update.
• file() given undefined or null sends nothing for checking and answers pass.
• file() given any other value that is not a string sends nothing, answers unavailable, and logs a warning.
• A text sent for checking that the guard refused or still rate limits aborts the next payment it concerns, in both modes.
• Breaking Every guard call refuses a base URL that redirects and names the address to set.
• Every guard call sends an x-vulsight-client header with the SDK version, and a 408 counts as an outage.
• An error for an answer that is not the guard's names the host and status, and an answer this SDK cannot read says to update it.
• README and Policy docs: the daily cap is one USDC budget per key across every network and lane.
• README: how long the proxy holds an EVM payment for review, and what its review_pending and resign_required answers mean.
• README: where to answer a held payment's review, and to give the HTTP client a read timeout of at least 60 seconds.
• README: the proxy's Solana receipt statuses, and the 16 MiB daily ceiling on text sent for checking.
• README: the vs_test_ prefix as only a key format, and the MCP tool as advisory, not enforced.
• README: the sample reads its keys from the environment, pays the demo seller, and says how to run it.

Fixed

• When a seller answers the signed retry with a redirect, the wrapped fetch returns it unfollowed with a warning that the payment may have been made, where it used to throw. A browser hides redirects, so there it throws that warning.
• A page the guard passed is sent for checking again when it is read a minute or more later. That replaces a pass the guard no longer honors.
• A cited excerpt is cut between characters, so a page with an emoji at its 2000th unit no longer fails the decision.
• A payment still held when the wait ends mentions Approve and always allow this payee only when a first payment is the only reason for the hold.

Security

• Breaking TxHash refuses the all-zero hash and SolanaSignature the all-zero signature, the unsigned placeholders.
• The payment hook refuses, before signing, terms that are not one of the 402's offers.
• The hook that runs after signing blocks, in every mode, a payment whose x402 version, offer, or resource URL changed after the check, or whose 402 was replaced so no decision matches it.
• reportSettlement refuses, as the proxy does, a receipt whose transaction is the payment's own EIP-3009 nonce, the buyer's own Solana signature, or an unsigned placeholder. The error never repeats the value.
• On Base, reportSettlement records the signing wallet as the payer of a receipt that names none, and refuses one naming another payer, as the proxy does. A paid 402 can be reported too.
• vulsight.fetch throws on a URL under the guard's own /p/ proxy path, and on a read redirected onto one, so a proxied payment is not decided twice and its proxy token stays out of decision records.

Added

• A file_context text or hook result that could not be sent for checking because the guard was out (a 408, a 429, a 5xx, or no answer) is kept.
• The next check_payment a kept text concerns sends it first, and fails closed while the guard is still out.
• The Claude Code hook keeps unsent results, at most 200 a session, in a file under the system temp directory that only the server's operating system user can read, so a restarted server still sends them.
• A reused idempotency_key answers with a sentence that names the causes and asks for a new key.
• list_recent_decisions names each agent and takes a before cursor.

Changed

• check_payment forwards an x402 payment's x402Version, the requirement's extra, assetTransferMethod, and paymentFlow.
• check_payment refuses locally what the guard cannot judge: any scheme but exact, an upfront or escrow flow, and a transfer method other than EIP-3009 on Base or the default on Solana.
• Breaking check_payment refuses a payment with a field it does not take, where 0.3.0 dropped it. Pass only the listed fields, not the whole 402 accepts entry.
• Breaking check_payment refuses a scheme that is not lowercase letters, digits, and hyphens. Pass it as the 402 writes it.
• The printed skill (--skill, --skill codex) says the tool is advisory, not enforced.
• The printed skill adds a step that lists the payment methods the guard supports.
• The printed skill says when to skip the tool for a payment sent through the proxy URL.
• The printed skill says which terms and receipts to report.
• The printed skill says the vs_test_ prefix is only a key format, not test money.
• The printed skill asks for the proxy URL shown with the user's API key when it needs one. It does not pay until it has it.
• The printed skill tells the user to install the server with --scope user.
• The printed skill says a 409 resign_required after a content wait means nothing was sent, and to request the URL through the proxy again and sign the fresh 402.
• A flagged page sent for checking under its URL origin holds that seller in every lane, the proxy included.
• check_payment sends kept texts for checking one at a time, within its own time budget, and stops on a cancel between them.
• A check_payment that runs out of time fails closed, and the next one sends the rest.
• A refused kept text is reported as one kept from earlier, not one sent with this payment.
• A page's kept text tells the agent to send it again with file_context before a payment through the proxy URL.
• check_payment's held and expired answers name the Review page at <baseUrl>/review.
• A held answer says to repeat check_payment with the same payment, context, seller_402, and idempotency_key when nothing new was read. Otherwise, or with no key, have the review denied, send any new content with file_context, and check again.
• An expired answer says to check again with a new idempotency_key and approve it before it expires, or to raise the Review timeout and wait_seconds.
• A hold whose answer could not be read links <baseUrl>/decisions/<id>.
• report_settlement and the printed skill say a receipt whose success is false may still have settled. file_context says so too.
• report_settlement and the printed skill say the seller can use the signed payment until it expires: the 402 offer's time limit on EVM, the recent blockhash on Solana.
• report_settlement and the printed skill say to check the wallet's transfers to the payee on chain before paying again.
• report_settlement and the printed skill say an allowed or approved amount still counts toward the daily cap for the UTC day the guard checked it.
• In observe mode, a payment's amount counts toward the cap only if enforce mode would have allowed it, or held it and the review timeout has not passed.
• get_policy prints limits and thresholds in USDC instead of the asset's smallest unit.
• get_policy says an allowed payee skips the wallet blocklist and the guard's issuer freeze check, while the token contract still refuses a transfer to a frozen account.
• A failed, rate-limited, or unreadable review poll is tried again until wait_seconds runs out, and a wait whose every poll failed says the answer could not be read.
• Breaking Guard calls refuse a missing key and a base URL that redirects; set the key and the final base URL.
• Guard calls send x-vulsight-client and treat a 408 as an outage.
• The daily cap is one budget per key across networks, and get_policy says so.
• README: install with --scope user, the guard's tools do not pay (the agent brings its own x402 payment tool and wallet), and how to get a lost proxy URL.
• Breaking Node 20.3 or later.

Fixed

• A cancelled check_payment stops before it decides, and a response the guard refuses is told to the report_settlement call that sent it, not sent again in another client's check.
• The Claude Code hook reports a missing key or a failed send for checking to the agent, and a bare unknown command prints usage and exits 1.
• An excerpt cut inside a character is sent whole, and text with nothing to read counts as a pass.

Security

• report_settlement refuses an all-zero txHash or Solana signature, the unsigned placeholders, before it asks the guard, as the proxy does.