Repository avatar
AI Tools
v0.5.16
active

rh-preflight

io.github.quotumorg/rh-preflight

read-only Robinhood Chain builder and transaction checks by quotum with HEY Research Lab

Documentation

rh-preflight

rh-preflight by quotum with HEY Research Lab.

rh-preflight

no keys required · never signs or pays · read-only RPC and API reads · runs without a wallet

tests

rh-preflight reads public project records and applies your approval rules before Hermes Agent acts on Robinhood Chain.

HEY Research Lab, co-author, supplies the builder record with links to what HEY read; rh-preflight makes the go / ask / stop decision under your rules; ten other Robinhood Chain projects each add a line where they apply. Applicable reads run concurrently under one deadline; the coverage line shows who answered, did not apply or stayed silent. OffRouter joins for its own project; RPC, DexScreener and GeckoTerminal are separate infrastructure reads. The source table and bundled captures document that scope.

The plugin runs at the pre-tool hook, requests a human answer when your rules require it, and records each check in a local ledger. A prompt or skill alone cannot enforce that gate. Source records describe what each project published; you decide what to do.

Not this: rh-preflight is not a safety oracle and does not call a token good or bad. It never signs, pays, revokes or sends a transaction, and holds no wallet keys.

Security and footprint

  • Sends: the addresses, agent ids, project names or repository names you act on, to the source hosts in Sources, plus read-only RPC, DexScreener and GeckoTerminal reads. Detected unsigned transactions or wallet signing requests also go to Toll when transaction simulation is on.
  • Stores: one local SQLite ledger of checks in the active profile's plugin-data/rh-preflight/ directory. No credentials.
  • Runs: bounded HTTP reads inside the hook's deadline. No subprocess, background service, signature, payment or external write.
  • Installs: the Python core uses the standard library; nothing extra is downloaded.
  • After hermes plugins remove rh-preflight: the plugin directory is deleted; the ledger stays in plugin-data/rh-preflight/ until you delete it.

Reproducible PRIORS output from python3 demo/offline.py, using the bundled 2026-11-09 captures:

if Hermes Agent swapped this now: go · no rule of yours fired
11 sources · 8 answered · 1 not for this target: Borro · off: Sherwood, OffRouter
HEY Research Lab: Priors Agents · 0xedbf91223639800bcd5756815caf908df3b890be · https://heyresearch.xyz/project/priors-agents
priors-agents: SHIPPING under HEY's activity rule (hbm-v35). SHIPPING by the activity rule: 6 counted ships in the last 30 days, the newest 2026-11-09. This is a record of development, not a view on the token.
Verified Builder: not in HEY's answer
Latest meaningful ship: title not in HEY's answer · 2026-11-09T09:53:07.000Z · https://heyresearch.xyz/api/evidence/ship%3A759f85a9-93ce-4666-8d19-8a9b73035be1
Freshness: live at 2026-11-09T10:45:07.534Z; recent at 2026-11-09T10:11:36.953Z · asOf: 2026-11-09T10:46:45.421Z
Priors: agent #7622 Minimum Viable Agent: 4 loans repaid, 40 USDG repaid, defaulted: no, frozen: no · https://priors.trade/agent?id=7622
Sentinelhood: ERC-20 PRIORS, launched on pons by 0x9f05…ac0f, 6 launches by that deployer, block 110264821 · https://sentinelhood.com/?ca=0xedbf91223639800bcd5756815caf908df3b890be
HoodLock holds no token lock or vesting for this token (token locks and vesting only; LP locks in HoodLock's Liquidity Locker and other lockers not read) · https://hoodlock.tech/lock-checker
Trnch: no rug, no dump on record · first seen 2026-10-14T11:50:25.981Z · https://trnch.fun/token/0xedbf91223639800bcd5756815caf908df3b890be
Agent Wormhole has not observed this token; that is not a verdict · https://dashboard.agentwormhole.com/t/4663/0xedbf91223639800bcd5756815caf908df3b890be
Hookr's page no longer lists hooks in a readable form · https://hookr.fun/hooks
Toll: card loads; MCP did not answer; x402 answered HTTP 402. payTo matches registered agentWallet · https://t0ll.xyz/agents/census?agent=7622
DexScreener: uniswap v4 pair, liquidity $1,076,142.88, 24h volume $90,340.22, pair since 2026-09-19 · https://dexscreener.com/robinhood/0xff7b3bd2db34d9ed8160e6dedf1d448777abaa1fa6fc8a31144930a1a656fd92
GeckoTerminal: FDV $9,817,064.86, CoinGecko listing priors-agent · https://www.geckoterminal.com/robinhood/tokens/0xedbf91223639800bcd5756815caf908df3b890be
Source: HEY Research Lab, builder research for Robinhood Chain, https://heyresearch.xyz/project/priors-agents, as of 2026-11-09, rules hbm-v35

Reproducible NVDA output from the same command:

if Hermes Agent swapped this now: ask · your rule: HEY record could not be read
11 sources · 2 answered · 1 not for this target: HEY · off: Priors, Sentinelhood, HoodLock, Trnch, Agent Wormhole, Hookr, Sherwood, OffRouter
NVDA · 0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec
HEY response for NVDA was not captured; no builder reading shown
Toll: official Robinhood Stock Token NVDA, ISIN US67066G1040, status ASSET_STATUS_ACTIVE, registry as of 2026-11-09T17:54:06.940Z; chain price $176.80 read 2026-11-09T18:08:17.266Z; Chainlink reference $177.56 updated 2026-11-09T17:06:17.000Z · https://t0ll.xyz/markets/NVDA
Borro: NVDA lending market present, lending fees 0.000300%/year before BORRO drip, short borrow fees 0.026200%/year, Borro short desk price $176.77 vs feed $176.59 at 2026-11-09T18:22:24Z · https://borro.markets

mcp over stdio

runs from any mcp client, without hermes. python 3.11 or later. no runtime dependencies.

from this checkout:

python -m rh_preflight.mcp

or install the checkout with python -m pip install . and run rh-preflight-mcp. from a release tag:

uvx --from git+https://github.com/quotumorg/rh-preflight@v0.5.12 rh-preflight-mcp

the mcp entry point ships from v0.5.12. nothing here publishes a package or starts a hosted endpoint.

claude desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "rh-preflight": {
      "command": "python3",
      "args": ["-m", "rh_preflight.mcp"],
      "env": {"PYTHONPATH": "/absolute/path/to/rh-preflight"}
    }
  }
}

claude code, from the checkout, with that python environment available to the client:

claude mcp add --transport stdio --env "PYTHONPATH=$PWD" rh-preflight -- python3 -m rh_preflight.mcp

cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "rh-preflight": {
      "command": "python3",
      "args": ["-m", "rh_preflight.mcp"],
      "env": {"PYTHONPATH": "/absolute/path/to/rh-preflight"}
    }
  }
}

replace the checkout path and, if needed, python3 with the absolute path to python 3.11 or later. after installing the package, the command can be rh-preflight-mcp with empty args and no PYTHONPATH.

  • builder_card: string fields address, project and repo_url; provide at least one. address and repo_url cannot be combined. returns the same public card as the plugin tool.
  • tx_check: unsigned to plus data or value, optional from, and optional chainId fixed to 4663. value is wei, as a uint256 integer, decimal string or hex quantity. data is even-length hex prefixed with 0x, at most 262144 characters. alternatively pass tx_hash. if both are present, the supplied fields must match. no signed bytes, wallet keys or arbitrary rpc methods.
{"to":"0x000000000000000000000000000000000000dead","data":"0x","value":"0","chainId":4663}

tx_check uses the same intent extraction, transaction cards, source reads and decision code as a hypothetical transfer hook call. calldata determines approvals and swaps. it returns action (pass, ask, block or note), advisory: true, the unchanged decision text, cards and rules. the card labels remain go, ask, stop and note. no human approval loop or local ledger is created. the client decides whether to continue; calling this tool does not enforce a gate around other tools.

hash lookup verifies chain 4663 and reads only eth_getTransactionByHash. signatures in the rpc response are discarded. the resulting intent is checked against current state, not replayed at its historical block. missing, conflicting or unreadable transactions return a tool error with action: block. hash resolution has one builder timeout before the shared check budgets start. contract-creation transactions without to are not supported.

settings use the plugin defaults and validation. set RH_PREFLIGHT_<SETTING_NAME> in the launching environment, or repeat --setting name=value; arguments take precedence. strings are plain text; booleans, numbers, lists and maps use json. no config, dotenv, hermes profile or secret store is read.

the complete setting and environment names are below. pass each setting as --setting name=value. defaults are the plugin defaults; sources and ask_when are empty maps. the default action regex list is shown in the settings table below.

setting nameenvironment variabledefault
modeRH_PREFLIGHT_MODE"ask_when"
quiet_daysRH_PREFLIGHT_QUIET_DAYS30
ask_quietRH_PREFLIGHT_ASK_QUIETtrue
ask_unmeasuredRH_PREFLIGHT_ASK_UNMEASUREDtrue
ask_no_recordRH_PREFLIGHT_ASK_NO_RECORDtrue
ask_not_verifiedRH_PREFLIGHT_ASK_NOT_VERIFIEDfalse
allow_unattendedRH_PREFLIGHT_ALLOW_UNATTENDEDfalse
assume_chainRH_PREFLIGHT_ASSUME_CHAINnull
tool_patternsRH_PREFLIGHT_TOOL_PATTERNSaction regex list
tx_checkRH_PREFLIGHT_TX_CHECK"on"
toll_key_headerRH_PREFLIGHT_TOLL_KEY_HEADER"x-toll-pass"
toll_wait_max_secondsRH_PREFLIGHT_TOLL_WAIT_MAX_SECONDS30.0
ask_payout_otherRH_PREFLIGHT_ASK_PAYOUT_OTHERtrue
ask_hookr_refusedRH_PREFLIGHT_ASK_HOOKR_REFUSEDtrue
toll_coin_findingsRH_PREFLIGHT_TOLL_COIN_FINDINGS"silent"
on_uncheckedRH_PREFLIGHT_ON_UNCHECKED"ask"
tx_timeoutRH_PREFLIGHT_TX_TIMEOUT15.0
timeoutRH_PREFLIGHT_TIMEOUT4.0
hey_cache_secondsRH_PREFLIGHT_HEY_CACHE_SECONDS600
sourcesRH_PREFLIGHT_SOURCES{}
ask_whenRH_PREFLIGHT_ASK_WHEN{}

the additional environment variable TOLL_API_KEY is optional and has no default key.

python -m rh_preflight.mcp --setting timeout=4 --setting tx_timeout=15 --setting toll_wait_max_seconds=0 --setting 'sources={"offrouter":"off"}'

builder reads default to 4 seconds, transaction reads to 15, and toll before-buy retries may add up to 30 by default, with a configurable maximum of 120 seconds; inside a Hermes Agent hook the wait for network results, retries included, ends within 20 seconds of hook entry, and settings, history and the pending-message lock have deadlines below 25 seconds. transaction budgets cap at 25 seconds; the builder setting accepts up to 30 and the shared hook caps its deadline at 20. these are the plugin's existing limits. RH_PREFLIGHT_ON_UNCHECKED defaults to ask.

set your own TOLL_API_KEY in the server environment only if you have toll partner access. when unset, toll transaction simulation makes no request and the card retains the plugin's Toll: not simulated gap. public toll reads and other sources still run. RH_PREFLIGHT_TOLL_KEY_HEADER uses Authorization case-insensitively for a bearer header; all other values fall back to x-toll-pass. the key is never a tool argument, command-line option or response field, and is sent only to toll's existing allowed host and routes.

stdio uses one utf-8 json-rpc message per line. logs and help use stderr. initialize, send notifications/initialized, then call tools/list or tools/call; ping also works before initialization. supported revisions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. tools are read-only. revisions 2025-06-18 and 2025-11-25 get structuredContent as well as the same serialized json in text content; older revisions get text content. unsupported revisions negotiate to 2025-11-25. tool failures set isError; malformed protocol requests use json-rpc errors. requests run serially, no background tasks or batch messages. each frame is limited to 1 mib. closing stdin ends the process after any active bounded check.

server.json is the official mcp registry entry io.github.quotumorg/rh-preflight; its version matches the release. the publish workflow, run by hand for a release tag, uploads the pypi package rh-preflight-mcp and then this registry entry, both through github oidc with no stored tokens. streamable http is deferred; there is no hosted endpoint.

Quickstart

Requires Hermes Agent 0.23.0 or later, with 0.23.0 checked locally.

on Hermes Agent 0.23.0/0.23.1 with Tool Search on, a deferred plugin action tool invoked through the tool_call bridge skips pre_tool_call, so the rh-preflight gate does not see the real tool; run hermes config set tools.tool_search.enabled off or use a newer Hermes Agent with the fix (canary >= 20261115, PR #155527).

Allow roughly 3-5 minutes with Hermes Agent already configured, plus 2-3 minutes for the approval walkthrough. These are setup estimates.

hermes plugins install quotumorg/rh-preflight --no-enable
hermes plugins enable rh-preflight
hermes plugins list

For a local checkout, run hermes plugins install "file://$(pwd)" --no-enable from the clone root; only committed files are cloned. Then enable and list the plugin as above.

To upgrade an existing unpinned Git install from 0.5.3, run in the same active profile:

hermes plugins update rh-preflight
hermes plugins list

Pinned installs keep their revision; follow Hermes Agent's pin-update instructions with the reviewed commit you intend to install. Restart Hermes Agent after the update. Existing settings and ledger rows need no migration. New settings use their defaults when absent: transaction checks are on, Toll and Hookr transaction reads share a separate 15-second budget, incomplete checks ask, and fixed Toll coin figures stay silent unless enabled; before-buy words print when applicable. An existing sources.toll: "off" still disables Toll; with transaction checks on, the missing simulation uses on_unchecked. Existing mode: note keeps its documented exception. allow_unattended: true now covers only cron identified by the public plugin context; non-cron asks use Hermes Agent's approval gate, including its YOLO bypass.

Confirm rh-preflight is enabled in the active profile. Exit Hermes Agent and start it again:

hermes

In that session:

/rh-preflight 0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec

This reads a card only. It evaluates a hypothetical attended swap, does not open an approval prompt, and does not add a check to history. The bundled NVDA replay shows ask · your rule: HEY record could not be read: its HEY response was not captured. Official Stock Tokens confirmed by Toll are exempt from the no-HEY-record rule by default, but an unread builder record still requests approval. Both opening cards replay bundled captures; they do not establish today's source responses.

Card labelMeaning
goThe plugin permits the detected call under your settings. Other Hermes Agent checks still apply.
askYour rules require a human answer before the detected call. A read-only card only previews this.
stopAn explicit stop rule fired, a person cannot answer, or the local check failed.
noteThe card is appended without an approval gate, even if rules fire.

Coverage partitions 11 sources: HEY Research Lab plus ten Robinhood Chain projects. answered includes no-record replies; not for this target means unmatched or inapplicable; silent shows each additional source's structured reason (unreachable, refused, rate limited or payment required) with seconds waited, for example silent: Toll (payment required; 0.1 s). HEY keeps its seconds-only label because its structured failure reason is not retained. off means disabled. A go card can contain silent sources when no enabled rule depends on them. Coverage details explain the count.

See an approval prompt

In your terminal, set the plugin to ask on every detected action:

hermes config set plugins.entries.rh-preflight.settings.mode ask

Start an interactive hermes session with approvals enabled and yolo disabled. Ask Hermes Agent to run this literal read-only command through its terminal tool:

cast call 0xd0601ce157db5bdc3162bbac2a2c8af5320d9eec 'symbol()(string)' --rpc-url https://rpc.mainnet.chain.robinhood.com

The plugin detects literal cast call commands as well as writes. Its card should begin ask · your rule: ask before every detected action; Hermes Agent presents the human approval choices. Choose deny. The command is blocked before execution, so this walkthrough does not require a wallet or an installed cast. If the agent only explains the command, request a terminal tool call. A slash-card read cannot demonstrate this prompt.

Then run hermes rh-preflight log in your terminal to see the recorded check and human response, and restore the default mode:

hermes config set plugins.entries.rh-preflight.settings.mode ask_when

If you see stop, use an attended session with approvals enabled; leave allow_unattended false. If /rh-preflight is missing, check the enabled plugin in the same profile and restart. This walkthrough uses public reads. For a provider-free offline demonstration of the directive, denial and ledger, run python3 demo/gate_replay.py from the clone; it simulates host events and does not show a host prompt.

Desktop keeps the answer, coverage and complete target: identifier visible and puts source details in a native disclosure. The answer is colored by outcome (go, ask, stop, note), an eleven-segment bar under the coverage line shows each source's bucket, and a source list names every project with its bucket, silent reason and a link to the source page it answered with. Colors come from the stored answer and coverage line; links come from each source's own answer as recorded in the local ledger. Desktop loads no logos or other remote assets. hermes rh-preflight card colors the outcome word on a terminal and prints plain text when output is redirected or NO_COLOR is set. Multi-target rows show the count, for example swap · 2 checked targets. Repository URLs, agent ids and pool ids use the same target label without guessing a role or chain. Human responses distinguish checks that did not request approval, unanswered requests, denials, timeouts, cancellations and the three recorded approval choices. Approvals say that execution is not recorded. Legacy rows still render.

Enable the optional Desktop half for the active profile to see checks in the sidebar and the status chip. The Python core uses the standard library. The dashboard uses the host's FastAPI adapter and Desktop uses the host's React runtime. The MIT license covers this plugin.

See the gate without a model

From the cloned repository directory, run the explicit deny-retry-unattended scenario with no sockets, model or provider. The unattended scenario simulates detected cron. The host events are simulated, source lines use bundled captures, and the ledger is temporary. Uncaptured sources are off. Clocks use fixture time; real approval keys remain unique and are shown as display aliases. The default python3 demo/offline.py demo is unchanged.

python3 demo/gate_replay.py
simulated · offline gate replay · deny-retry-unattended · clock: 2026-11-09T10:46:47.178Z
simulated · rh-preflight by quotum with HEY Research Lab · https://heyresearch.xyz
simulated · bundled captures; uncaptured sources off; temporary ledger; no Hermes Agent prompt
simulated · swap · chain 4663 · 0x000000000000000000000000000000000000dead
simulated · ask · your rule: no HEY record
simulated · 11 sources · 2 answered · off: Priors, HoodLock, Trnch, Agent Wormhole, Hookr, Toll, Borro, Sherwood, OffRouter
simulated · HEY Research Lab: no published project for this contract (HEY's index, not a statement about the token) · asOf: 2026-11-09T10:46:47.178Z · https://heyresearch.xyz
simulated · Sentinelhood: no contract at this address, block 110264826 · https://sentinelhood.com/?ca=0x000000000000000000000000000000000000dead
simulated · hook directive: approve (ask) · approval key: request-1 (display alias)
simulated · host event via post_approval_response · human response: deny
simulated · ledger request-1 · disposition: ask · human response: denied
simulated · retry: fresh approval required · approval key: request-2 (display alias)
simulated · ledger request-2 · disposition: ask · human response: not recorded
simulated · unattended · hook directive: block · stop · human approval required, unattended
simulated · action executions: 0

For a labelled simulated swap combining the bundled PRIORS HEY projection and missing-target capture, run python3 demo/gate_replay.py --scenario two-target-deny-retry-unattended. It names only the missing target behind the rule, denies the whole call through the observer, retries with a fresh key and stops in simulated detected cron. No uncaptured badge follow-up is made.

Transactions and signatures

The detector contract below applies to argument content, including nested objects, JSON strings and literal command-line JSON. Tool names use the same camel-case and underscore normalization for read classification and example exclusions. Builder and install rules remain independent of transaction checks.

Input or boundaryTransaction detection and requirement before go
Chain contextOnly chain 4663: explicit fields, recognized Robinhood RPC URLs or assume_chain. Conflicting or unreadable explicit chain fields prevent the assumption. A signing domain is signature evidence, not the call network; without explicit call context, a 4663 domain supplies signature scope.
Unsigned transactionA valid to plus data, input, calldata or value; aliases normalize to data, and native value transfers may omit calldata. Toll must complete, the sender must be known and no enabled local rule may ask or stop. Supported HookrRouter trade checks must also complete.
Wallet RPC send/signDirect method/params or an rpc wrapper: eth_sendTransaction, eth_signTypedData_v4, personal_sign. Explicit sends/signatures override read names and simulated parameters, including independent nested requests. Sends may omit data and value. Completed applicable checks and a known sending/signing wallet are required; malformed or missing parameters use on_unchecked.
Literal cast sendRaw calldata, native value, and common approve/increaseAllowance/transfer/transferFrom/setApprovalForAll signatures can supply an unsigned transaction. Unsupported or unreadable sends use on_unchecked. No shell expansion is performed.
Raw broadcastExplicit eth_sendRawTransaction uses on_unchecked; signed bytes are not decoded, sent to Toll or retained.
Standalone EIP-712A domain/types/primaryType/message object stays local and uses on_unchecked because the signer is unknown. Permit and domain rules still apply.
Unencoded actionsWith a quantity in amount, amountIn, amountOut, value or allowance: tokenIn/tokenOut keys identify swaps, a spender address identifies approvals, and a recipient/payTo/payee/to address identifies payments. These shapes use on_unchecked and retain local approval and payout facts. A tool name or address alone supplies builder research only.
Declared reads and installsget/read/search/research/fetch/quote/price/estimate/browse prefixes, web_search/web_fetch, plugins_install, plugin_install, install_plugin and mcp_add leave ordinary quote, allowance, payment lookup and example arguments out of transaction checks. Content reads (read_file, web_search, web_fetch, research, browse prefixes) also exclude unsigned examples. Quote and other non-content read tools still check concrete unsigned transactions.
Execution evidence on a read toolExplicit send/sign RPC or literal cast send, execution tool names, execute/send/sign/submit/broadcast true, quoteOnly/readOnly/dryRun/simulateOnly false, or mode/action/operation execute/send/sign/submit/broadcast/swap/approve/transfer/pay override read exclusions. Ordinary quote-only flags retain read behavior.
Read RPC and terminal readseth_call, eth_estimateGas, eth_createAccessList, debug_traceCall, wallet_simulateCalls exclude hypothetical params while preserving independent nested send/sign requests. Literal cast call and hermes plugins install/hermes mcp add retain builder/install checks.
Incomplete checks or parsingFailed, refused, late or partial required checks, missing wallets and unreadable detection use on_unchecked (ask by default; detected cron stops unless allow_unattended is enabled, other asks use Hermes Agent's gate). Parsing is bounded to 24 nesting levels, 20,000 input nodes, 2,000,000 string-value characters per input/decoded JSON value, 64 JSON candidates per string and 1,024 intent rows. Exceeding a bound or a detector exception yields an unchecked card without sending partial arguments to providers, even when chain/read classification could not be completed. Other internal failures stop.
Explicit settings and Hookr limitstx_check: off, on_unchecked: note, mode: note and cron-only allow_unattended retain their documented exceptions; hard stops remain. Hookr exact-output and unread token-input amounts are skipped as described below.
Outside scopeOther-chain calls with readable context, wallet research, shell variables/expansion, opaque scripts, signed bytes without an explicit broadcast method and unsupported wallet methods without otherwise recognized transaction content. A tool declaring only a read name and ordinary quote arguments with no observable execution evidence cannot be distinguished from a read.

Local EIP-712 decoding runs before any Toll request. It prints the domain, signing type, spender, amount, deadline and nonce. Permit2 is recognized by address, including each token in PermitBatch. DAI-style allowed: true grants unlimited approval; expiry zero and maximum deadlines print as no expiry. Other zero deadlines print the epoch date. Any Permit or Permit2 asks; a signing domain on another chain asks when the call is on 4663. Unlimited approval or permit to a spender with no code stops. Approval for all to a spender with no code also stops and describes all items in the collection. An unlimited approval to an unknown contract, EIP-7702 delegation, payout to another wallet, reverted simulation, expired transaction deadline or insufficient ETH asks. A successful swap adds facts without another approval rule. A missing sending or signing wallet uses on_unchecked even if Toll reports simulation success. These checks do not authenticate the signer or prove domain ownership.

Signature cards also print one Toll line for each x-toll.take.takes[] row: who can take tokens, how much is takeable now, the signed limit and the recorded block. Amounts are converted from base units with exact Decimal math. For example, the bundled unlimited Permit capture prints Toll: this signature lets 0x1111…1111 take up to 8,324.467654 USDG (~$8,324.47) now, signed unlimited, block 115484554. A zero balance warns that an unlimited signature can take more later if the wallet is funded. Expired signatures and already-used nonces are named explicitly. Missing USD omits the dollar value; missing token metadata uses a short token address and base units, never a guessed symbol or scale. The real zero-balance capture has no symbol or decimals.

Toll's take.status: not-read prints its own sanitized, length-capped line. Each malformed row prints Toll: what this signature lets someone take is not read and uses on_unchecked, while valid sibling rows still print. When every validated take row has simulated.status: moved, a typed signature card prints Toll: pull simulated at block N, using the latest recorded simulation block. If any simulation block is missing, it labels the latest take-read block separately instead. The missing transaction simulation then adds no unchecked reason. Other incomplete reads still use on_unchecked; personal_sign and not-read take results keep their existing lines and handling. Permit approval rules and hard stops remain. Validated take fields, including the simulated movement when supplied, are retained in the ledger and dashboard card data; no signature or remote report is stored.

By default, a signature with a positive takeable amount asks with this signature lets someone take funds, recorded as signature_take. Expired signatures, already-used nonces and zero takeable amounts do not fire this rule. Configuring ask_when.take_above_usd replaces this default ask with the USD threshold described below; the take facts stay visible below it.

Saved Toll and Hookr responses, rendered by our parser. Hookr captures are a later read, so quote amounts do not replace simulated balances. The first is a fresh unsigned swap, never sent. The second is a constructed payout case, never sent. Simulation blocks describe the replay, not an executed transaction:

go · no rule of yours fired
unsigned transaction to 0xc2bc9a3fe6c4ce8c2f7eb4655b0869b01d8c93c9 on chain 4663
Toll: ALLOW
Hookr: this pool's rules allow this wallet
transaction uses third-party router 0xc2bc9a3fe6c4ce8c2f7eb4655b0869b01d8c93c9
Toll: simulated at block 111933448
simulated sender balance change: -0.000480569378599765 ETH
simulated sender balance change: +45704.730444476128839330 $CLEAR
Toll · https://t0ll.xyz
Hookr: hook kind shared root
Hookr scan: 79/100, automated screening · 5 findings: Inline assembly needs manual review, Unchecked arithmetic block, Delegated execution to code fixed at construction, +2 more · https://hookr.fun/scan?hook=0x89c9FB50d1f03192230FFB1c279BB6E7d3Fe6aCc&chain=4663
ask · your rule: Hookr pool rules refuse this wallet +5 more
your rule: payout to another wallet
your rule: simulation reverted
your rule: transaction deadline passed
your rule: sender short of ETH
your rule: transaction could not be checked
unsigned transaction to 0xc2bc9a3fe6c4ce8c2f7eb4655b0869b01d8c93c9 on chain 4663
pays out to 0xdc36d51963d08862c525045ccfd39fae6a0c7f40, not the sending wallet
Toll: WARN
Hookr: this pool's rules refuse this wallet: This wallet holds no ERC-8004 agent identity and is not linked as one's agent wallet.
Toll could not read all findings for $CLEAR
transaction uses third-party router 0xc2bc9a3fe6c4ce8c2f7eb4655b0869b01d8c93c9
sender short of ETH for this transaction
simulation reverted
transaction deadline passed
Toll · https://t0ll.xyz
Hookr: hook kind shared root
Hookr scan: 79/100, automated screening · 5 findings: Inline assembly needs manual review, Unchecked arithmetic block, Delegated execution to code fixed at construction, +2 more · https://hookr.fun/scan?hook=0x89c9FB50d1f03192230FFB1c279BB6E7d3Fe6aCc&chain=4663
Our outcomeHermes Agent directiveEffect
go or notenoneContinue; append the card to the result.
ask{"action": "approve", "message": …, "rule_key": …}Request a fresh human decision.
stop{"action": "block", "message": …}Veto the call before execution.
Could not checkon_unchecked: ask by defaultAsk in ask modes; stop vetoes; note adds the incomplete reading without that prompt. mode: note suppresses asks. Internal errors always stop.

The plugin detects cron only through ctx.current_cron_execution(). In detected cron, calls in ask modes stop by default, even when no optional rule fires. allow_unattended: true permits those cron calls without an approval request; hard stops still apply. mode: note keeps its documented exception.

Outside detected cron, every ask returns Hermes Agent's approve directive. Hermes Agent decides how to obtain approval and fails closed when no interactive user, gateway or approval bridge is present, subject to its configured unattended and single-query policies. A missing or raising plugin context does not establish cron and follows this same host gate. If a cron request reaches that gate, Hermes Agent applies approvals.cron_mode.

YOLO and approvals.mode: off bypass Hermes Agent's approval gate. A user who runs YOLO accepts Hermes Agent's bypass; rh-preflight no longer imposes a stricter presence or bypass check. Plugin hard stops, including unlimited approval to a spender with no code and internal check failures, still return block regardless of presence or bypass.

Builder and independent-source reads use timeout (4 seconds by default, capped at 25); Toll and Hookr transaction checks use tx_timeout (15 seconds by default, maximum 25). They start in parallel and keep separate deadlines, with card assembly and local ledger writes afterward. Only Toll before-buy WAIT retries can add time, bounded by toll_wait_max_seconds (30 seconds by default, maximum 120); other reads keep their original budgets. The tx card can add up to about 15 seconds before a transaction because a first coin read can take about 14 seconds. Healthy tx requests receive the full budget before any retry. Each Toll tx request states the time left before its deadline as budgetMs (less a 0.4 second round trip), so Toll answers inside it: a coin it has not read by then is the Toll has not read ... yet line beside the completed simulation. A transport or HTTP 5xx failure may retry once within the same deadline; no retry follows 429. Retry-After applies as a per-process cooldown without sleeping; only a validated before-buy WAIT can sleep. An unavailable, refused or rate-limited simulation says Toll: not simulated and uses on_unchecked. Partial coin or signature reads use on_unchecked alongside any simulation facts that did complete. Existing approval and payout facts still apply. With tx_check: off, only local facts and rules remain; sources.toll: off prevents a Toll request and leaves simulation unchecked when tx_check is on. The detector contract above defines action shapes and read exclusions.

Source waits without before-buy WAIT retries, measured from the start of the check; inside pre_tool_call the start is hook entry. Local assembly and ledger work follow. B=min(timeout,25), T=tx_timeout<=25; inside pre_tool_call both are further capped at 20. When Toll starts a before-buy retry, its deadline alone extends by at most toll_wait_max_seconds, shared across all retries, rather than per call. In pre_tool_call that extension is further capped so the retry ends within 20 seconds of hook entry; builder_card and the MCP server keep the full ceiling. The same limits apply to unattended runs.

PathBuilder readsTx readsSource wait bound
Defaults, exhausted<=4 sToll + Hookr <=15 s together<=15 s
Optional free coin readStock membership then check_coin share B; no coin retry loopIndependent of check_tx<=max(B,T), never B+T
Maximum settings with transport retry<=25 s total (20 s in the hook)<=25 s total including retry (20 s in the hook)<=25 s (20 s in the hook)
Stock TokenMembership only; no check_coinIndependent tx check<=max(B,T)
HTTP 429 or quota exhaustedNo cooldown sleep or paid follow-upNo 429 retry<=max(B,T)

Inside pre_tool_call, the wait for network results and any before-buy WAIT ends within 20 seconds of hook entry. Settings, checking and rendering have an outer deadline at 21 seconds. The ledger write waits at most 2 seconds in total across its SQLite statements, and the final pending-message lock has a deadline at 24 seconds. These limits keep the hook below Hermes Agent's 30-second fail-closed cutoff. A wait that does not fit keeps the WAIT line. A busy or timed-out ledger skips that history row, keeps the completed decision, adds check history unavailable to the message and gives an approval request a fresh key. Other check failures stop the call with rh-preflight could not complete this check. A running DNS or socket read may finish later in a background worker. Prolonged process scheduling can still delay any hook.

Only Toll's 14 stable warning codes are projected; unknown codes add no fact or rule. A coin not yet read adds a fact without a rule. Partial coin reads and undecoded signatures use on_unchecked. Coin classifications add no rule. toll_coin_findings: silent is the default; line prints Toll lists findings for <symbol> and the public coin link when supplied on tx cards. Builder cards may read free check_coin for non-stock addresses and print only fixed, Toll-attributed launch and wallet figures; the default silent setting skips that request. This setting does not hide incomplete-read facts from check_tx: those explain transaction coverage and on_unchecked. Amounts use structured symbols and decimals when provided; missing decimals retain base units, and missing symbols use a short token address. A nonzero v4 hook address in hook, hooks or hookAddress arguments, or Toll's decoded[].hook, triggers Hookr MCP hookr_hook and hookr_scan. The card prints shared root, own hook from Hookr's factory or unknown, then the numeric screen with automated screening, at most three fixed finding labels from recognized ids and +N more. Upstream titles, classifications, headlines, bands and cap prose are discarded. The numeric result is a screen, not an audit; it fires no policy rule. Each hook's read is cached in process for ten minutes. At most six fresh scans run per minute per client; rate limits leave only the public scan link and never sleep.

For swaps to HookrRouter 0xc2bc9a3fe6c4ce8c2f7eb4655b0869b01d8c93c9, hookr_check_trade runs beside Toll within tx_timeout. The captured 0x19b36adf ABI yields PoolKey, poolId (Ethereum Keccak-256), direction and exact input locally. Native buys need no pool lookup; token-funded inputs use matching pool metadata for decimals and side. With an unsupported selector, Toll's bought token selects the first hookr_pools result; only a native-funded buy with a known paying amount is quoted. Exact-output amounts and unread token input amounts are skipped. The wallet is always the sender, including a payout to someone else. refused adds the first reason sentence and asks by default under ask_hookr_refused; ok adds a pool-rule fact and symbol/decimals for the actual Toll balance changes. Hookr price-impact advice is discarded. A started trade read that fails, times out or returns an unknown status says Hookr: wallet pool rules could not be checked and uses on_unchecked; the default asks, without blocking solely because Hookr is down. The Toll card still prints. Unsupported exact-output trades are skipped. sources.hookr: off disables these reads; tx_check: off disables transaction enrichment.

Transaction simulation is supplied by Toll. The optional TOLL_API_KEY is read through the Hermes Agent profile secret scope (agent.secret_scope.get_secret), never from the process environment directly, and only for this route; it never enters the card or ledger. Keyless access is confirmed; the optional partner key uses x-toll-pass. The plugin stores projected facts, not raw calldata, typed messages, remote reports or signatures. No returned API or payment link is followed.

Settings

Settings live under plugins.entries.rh-preflight.settings. Policy and source toggles are read for every check. Restart Hermes Agent after changing either timeout or hey_cache_seconds. sources is a mapping from priors, sherwood, hookr, wormhole, toll, dexscreener, geckoterminal, chain, offrouter, sentinelhood, hoodlock, trnch and borro to on or off. All entries default to on. The core builder source stays enabled.

For example, merge these keys into the active profile's config.yaml. Keep ask_no_record at the settings level and stock_no_hey_record inside ask_when. Quote source values so YAML preserves strings:

plugins:
  entries:
    rh-preflight:
      settings:
        mode: ask_when
        ask_no_record: true
        ask_when:
          stock_no_hey_record: true
          stock_swap_above_usd: 250
          take_above_usd: 250
        sources:
          borro: "off"
SettingDefaultMeaning
modeask_whenask requests approval for every detected action; ask_when uses your enabled rules; note appends the card and proceeds except for explicit stops and internal errors.
quiet_days30Measured interval without a meaningful ship.
ask_quiettrueEnable the quiet interval rule.
ask_unmeasuredtrueAsk when builder activity is not measured.
ask_no_recordtrueAsk when the builder source has no record.
ask_when.stock_no_hey_recordfalseAsk for no HEY record even when Toll confirms an official Robinhood Stock Token. Without confirmation in time, the no-record rule still applies; unresolved HEY replies still print, while confirmed shared-contract project claims are omitted.
ask_when.stock_swap_above_usdunsetAsk when either side of a swap is an official Stock Token and its value is strictly above this positive finite USD threshold; null disables it. If both sides are Stock Tokens, use the larger value.
ask_when.take_above_usdunsetReplace the default signature_take ask with an ask only when the sum of available Toll take-row USD across signatures in the call is strictly above this positive finite threshold; unset or null keeps the default ask. Expired rows, used nonces, zero takeable amounts and missing USD do not contribute.
ask_not_verifiedfalseAsk when the builder badge is not established.
ask_when.payee_no_priors_recordtrueAsk when a checked payment recipient has no repayment record or that source cannot be reached.
ask_when.vault_strategy_inactivefalseAsk when a listed vault has an inactive strategy or the registry or bundle cannot be reached.
allow_unattendedfalseOnly for cron identified by the public context: permit detected actions in ask modes without a human request. Does not change non-cron asks or hard stops.
assume_chainunsetSet to 4663 for tools without an explicit chain field.
tool_patternsaction regex listConfigurable native and MCP tool classes, including swap, buy, sell, trade, approve, permit, transfer, pay, mint, bridge, deposit, stake and deploy.
tx_checkonToll simulation and Hookr transaction enrichment; off leaves local signature and calldata checks enabled.
toll_key_headerx-toll-passSends the optional profile secret as x-toll-pass: <key>, or Authorization: Bearer <key> for Authorization in any case. Other values fall back to x-toll-pass; doctor reports the fallback without the key. Applies to tx checks and before-buy MCP reads.
toll_wait_max_seconds30.0Extra time for Toll before-buy WAIT retries, from 0 to 120 seconds; 0 keeps the previous single-call WAIT line. At most three calls in all, with total sleeps and the extended deadline bounded by this limit. In pre_tool_call the retry also ends within 20 seconds of hook entry. Other sources keep their budgets, including in unattended runs.
ask_payout_othertrueAsk when transaction proceeds go to another wallet.
ask_hookr_refusedtrueAsk when Hookr says this pool's rules refuse the sender.
toll_coin_findingssilentline permits neutral coin attribution and fixed Toll figures; silent omits coin findings and skips free check_coin. Tx incomplete-read facts remain visible.
on_uncheckedaskAn incomplete transaction, builder read or enabled dependent source rule asks, stops or adds a note. Internal errors always stop.
timeout4.0Builder and independent-source budget in seconds, capped at 25 below Hermes Agent's 30-second hook limit.
hey_cache_seconds600HEY record cache in seconds, maximum 86400; 0 disables reads and writes to this cache. Negative, non-numeric and non-finite values use 600.
tx_timeout15.0Toll and Hookr tx-check budget in seconds, maximum 25; runs in parallel with builder reads.

The Stock Token swap threshold uses explicit base-unit amounts (raw on a token side, amountInRaw / amountOutRaw in swap arguments, or locally decoded exact-input calldata) and decimals already available for this call multiplied by Toll's prices.chain.usd, not the Chainlink reference. Prices and metadata match by token address, never symbol or underlying asset; the card prints the price's original as_of, including for cached prices, with no additional freshness cutoff. Generic amount / amountIn / amountOut fields do not establish units; simulation balance changes and independent Hookr quote amounts do not establish swap amounts. It makes no new reads; missing or ambiguous amount, decimals, chain price or price read time prints swap value not read: <what was missing> without firing this rule. Multiple decoded swaps or conflicting side identities are ambiguous. Incomplete Toll prices retain the existing source state and HEY rules. Triggered thresholds are recorded as stock_swap_above_usd with your triggered rules in the ledger.

The rule reads only a top-level action or direct objects in its calls list. An RPC, signing or shell command envelope does not make its calls entries executable. Supported action arguments have both tokenIn and tokenOut, no calldata, RPC method or shell command, and consistent identities for both sides. Amounts use amountInRaw / amountOutRaw or raw on the corresponding token object, with matching decimals on that side. Raw-only arguments also work beside another transaction or with a leading null generic amount. Arbitrary nesting, nested calls lists and serialized examples never establish valuation scope. An unsupported detected Stock Token swap reports swap value not read and leaves the existing ask/stop rules in control; the rule does not traverse examples to recover an amount. Quote/simulation flags must be absent or explicitly false; boolean execute, send, sign, submit and broadcast flags must be absent or explicitly true; any mode, action or operation hint must request execution (execute, send, sign, submit, broadcast, swap, approve or transfer or pay). Read-only tools require explicit execution on the action or its enclosing root, never an independent sibling. Simulated RPC params and signature message fields do not trigger the threshold. Metadata checks include nested token objects and every decoded row before using decimals. Local calldata amount decoding supports only the captured HookrRouter 0x19b36adf exact-input sell side, not Uniswap exactInputSingle or a bought-side minimum. The same root/direct-calls scope and execution hints apply to unsigned transactions, wallet eth_sendTransaction objects (directly or under rpc) and a single literal cast send starting command (no help/version flags, echo or prose prefix, compound shell commands, pipelines or shell substitutions). Those transaction shapes can use an explicit raw on a Toll-decoded swap side. No other transaction envelope supplies a value for this rule. These paths require the Stock Token address among the call's existing lookup targets and matching decimals already read; calldata bytes alone do not discover Stock Token membership. amountInBaseUnits / amountOutBaseUnits are not supported aliases. The constructed offline NVDA buy fixture in tests/fixtures/stock-swap/nvda-buy-film.json demonstrates the agent argument path with the saved chain price and an explicit 1.7-token bought amount; it is not a captured trade.

The signature take threshold uses only validated takeable USD already supplied by Toll, summed with Decimal math. It replaces the default signature_take ask: amounts at or below the threshold stay as card facts without this ask. Missing USD fires no threshold rule; incomplete take reads still use on_unchecked. Triggered threshold rules are recorded as take_above_usd. Hermes Agent receives the same approval directive as for the Stock Token swap threshold; note mode, detected cron, allow_unattended and explicit stops keep their existing behavior.

Only declared top-level settings are read. Unknown source names are ignored for existing configurations; unknown ask_when rules and invalid values are rejected, except hey_cache_seconds, which falls back as described above. The existing builder rules remain flat settings for compatibility. Payment, vault and Stock Token rules live in the ask_when mapping. An additional source's failure uses on_unchecked when its dependent rule is enabled, except the swap threshold's not-read case described above. note mode suppresses approval prompts; explicit stops for unlimited approval to a spender with no code, on_unchecked: stop and internal errors still apply. A failed local check or ledger write always stops.

The plugin never answers an approval prompt. Interactive checks return the host's approve directive to request human approval. Each check has a fresh approval key. Human answers are recorded only when the host emits an approval response event.

Sources

Each source publishes its own records. Additional lines carry public source links when available; HoodLock LP lines omit invalid or missing proof links, say how many positions are in range and their share of active pool liquidity, and name an unreviewed v4 hook. The answer is first, coverage second, then the full list when two or more rules fire, followed by the source readings in the order below. A single rule already shown in the answer is not repeated. The fixed detected-cron stop keeps its reason below coverage. The catalog covers HEY Research Lab plus ten Robinhood Chain projects; OffRouter is scoped to its own project and infrastructure is listed separately.

SourceKeyless URL or readWhat its line answers
HEY Research Labhttps://heyresearch.xyz/api/agent/builder_status?address={address} or /api/agent/research_project?q={name} or ?project={slug}; legacy /api/v1/builder, /api/contracts/4663/{address}, /api/projects, /api/projects/{slug} and /snapshotBuilder identity, activity, badge, ships, evidence, unknowns and citation. Snapshots retain token-lock fields for comparison.
Priorshttps://priors.trade/api/check?address={address} or ?agent={id}Agent repayment counts and amounts, default and freeze fields. Called for payments, agent ids and full read cards.
Sentinelhoodhttps://sentinelhood.com/api/service?action=token&value={address}, then action=deployer&value={token} for Pons tokensERC-20 identity, Pons deployer, launch count and observed block. Non-contract results are explicit.
HoodLockRead-only JSON-RPC at https://rpc.mainnet.chain.robinhood.com, Locker 0xd0f7d8c6e9f6d80c297bebe4f7fd1b9c8125c32f, Vesting 0x910e19bcC4bce46999994Ed7297E0Fc4431ec72E; GET https://hoodlock.tech/api/v1/lp-locksPercent of total supply in future token locks, earliest unlock, withdrawn locks and vesting schedule count. Separate informational future, locked v2/v3/v4 LP positions from the keyless API, grouped by pool with position proof links. Other lockers are not read.
Trnchhttps://trnch.fun/api/bot/v1/check?token={address}; POST /api/bot/v1/check/batch for multiple tokensTrnch's keyless token check relays verified, summary and a validated token-page link per Trnch's licence; multiple tokens use batches of twenty under the same deadline. Unknown stays an answered no-record reply, even when verified.
Agent Wormholehttps://dashboard.agentwormhole.com/api/v1/token/4663/{address}Its metadata rule field, mutation count, first observation and current/expired attestation. Unobserved is explicit.
HookrPOST https://hookr.fun/api/mcp: hookr_hook, hookr_scan, hookr_pools, hookr_check_trade; catalog /api/hooks/catalog, /api/hooks/integrations, /api/discover/pools with public /hooks fallbackHook kind, automated screen and finding titles; wallet-specific pool refusal or quote metadata beside Toll. Sends hook address, or token address then poolId, side, amount and sender wallet. Catalog reads still cover pool lookup, integrations and full cards.
Tollhttps://t0ll.xyz/api/tx/check for unsigned transactions and wallet requests; /mcp free check_agent(id) and check_hook(address) and check_coin(address) and pre_buy_check(address, budget_ms); /api/markets/stock/{id} for stock membership/pricesSimulated sender changes, approval, recipient, delegation and incomplete-read facts under our local rules. Agent card/payTo and hook facts, or official Stock Token ticker, ISIN, active status and registry timestamp, plus price versus timestamped Chainlink reference. A token address that is not a Stock Token gets Toll's free check_coin, enabled only by toll_coin_findings: line and projected to fixed Figures lines only (where and when it launched, the maker's launch count, wallets on Toll's flag list and what they bought, what the maker holds now); a coin Toll is still reading, an answer naming another token, a timeout, 429, 5xx or a used-up daily quota prints nothing, and a whole answer is kept ten minutes per address (maximum 512 addresses), independently of tx checks, so repeats do not spend the free quota. Stock Tokens never call check_coin. Known ids/hooks come from Priors/Hookr or arguments. Toll's own pre_buy_check word (BLOCK, WARN, ALLOW or WAIT) is printed for the bought non-Stock-Token address in a detected swap and on builder/direct-address token cards, under sources.toll. the line includes the first validated reason and remaining reason count, or ALLOW's limited meaning or WAIT's seconds, any supplied read age and a validated same-token report link. each attempt uses its remaining deadline less 0.4 seconds, clamped to 300-25000 milliseconds. a validated WAIT with N seconds sleeps N seconds before calling again, at most three calls total. total sleeps cannot exceed toll_wait_max_seconds, and all retries end by the original deadline plus that ceiling. a wait that does not fit leaves the WAIT line and requested seconds unchanged; a card that retried adds, for example, after one wait of 12 s. 0 disables the loop. one reader per address owns the loop; concurrent callers get its whole answer within their original deadline, or no line. parsed non-WAIT answers have a separate ten-minute cache per address (maximum 512); Stock Tokens never call it. tx cards also print validated check_tx.action as Toll: ALLOW, Toll: WARN or Toll: BLOCK. all words are informational and leave our approval rules unchanged.
Borrohttps://borro.markets/markets.json and /prices.jsonOfficial Stock Token lending market, annual stock lending fees before BORRO drip (lend.apr), annual short borrow fees (short.yearly) and short desk mid price versus feed at the recorded time. Membership must first come from Toll with a response address matching the requested address, ignoring letter case. A missing or mismatched response address prints Toll: response address differs from requested address; official Stock Token status not established, keeps the no-HEY-record rule and skips Borro for that target. No market is explicit.
Sherwoodhttps://app.sherwood.sh/api/v1/vaults, /api/v1/vault/{address}Listed vault strategy, proposals, assets and agents. Unlisted vaults add no line.
OffRouterhttps://docs.offrouter.org/.well-known/x402 and /modelsIts own x402 mode, chain-specific payTo and model count, only for HEY's exact OffRouter identity.
Robinhood Chain RPC (plumbing)https://rpc.mainnet.chain.robinhood.com: eth_chainId, eth_getCode, eth_blockNumber, metadata eth_callContract presence, readable name/symbol and read block. Quiet fallback: its line prints only if Sentinelhood fails or is disabled.
DexScreener (plumbing)https://api.dexscreener.com/latest/dex/tokens/{address}Highest-liquidity chain pair, liquidity, volume and creation date. Empty pairs are explicit only with positive RPC code presence.
GeckoTerminal (plumbing)https://api.geckoterminal.com/api/v2/networks/robinhood/tokens/{address}FDV and CoinGecko id without repeating pair price.

The method, chosen integrations and not-taken list are in docs/SOURCES.md. Reserves amlil, HoodRugCheck, Marlowe and HookKit overlap existing questions or exceed the time budget. Key-only, paid-only, other-chain and own-product-only interfaces were excluded. The explorer is a citation only.

HoodLock keeps the released token-lock paging: batches of twenty, at most ten pages and 200 details at the returned block, under one deadline. capped totals cover shown locks only; vesting counts use the full index.

the LP API uses the same sources.hoodlock switch, deadline and sixty-second cache. exact token0/token1 addresses in future locked v2/v3/v4 rows match. v2/v3 pools use addresses; v4 pools use 32-byte ids. hooks, hookStatus, positionManager and inRange do not exclude positions. each pool gets its position count, API symbols, summed valueUsd only when every value is available, and earliest unlock. complete: false is labelled incomplete API result. no USD value is inferred. a successful complete or partial LP read removes the LP-not-read caveat, including empty or unmatched results. skipped, failed or timed-out reads retain it and preserve independent token facts.

each LP line links only to the API proof value of the position that unlocks first; on an unlock tie, the larger one by valueUsd when all values are known, otherwise pool-local liquidity. remaining ties keep API order. only https://hoodlock.tech/proof/position/<digits> is accepted; missing or invalid links are omitted, without an API URL fallback. malformed identities, excessive nesting and unrenderable dates cannot erase independent token facts. LP lines add no approval rule or locked-supply percentage.

replay the supplied 2026-11-19 Trnch checks without sockets with python3 -m demo.r6_replay --trnch HISS, --trnch USDG or --trnch PULLED. HISS and USDG retain other sources' older capture dates; the token whose liquidity was pulled has only a Trnch capture. summaries retain first-seen dates and kept-out categories where the legacy line included them. verified and summary are informational, with no approval rule.

replay the supplied 2026-11-18 HISS and LOCK cards without sockets with python3 -m demo.r6_replay --lp HISS or --lp LOCK. non-HoodLock facts come from captured card text; only LP projection and its scope sentence are updated, at the LP capture timestamp. HISS uses the released answer wording. raw token RPC responses were not supplied for these two cards.

Hookr income attribution defaults to an offline check. python -m rh_preflight.income --token <address> reads caller-supplied JSON; an API total or swap sender does not prove an economic payer. Opt into live collection with python3 -m rh_preflight.hookr_live --token <address> --days 7 --public, using the existing ETHERSCAN_API_KEY; add --card for a token card. Only verified direct creator payments can warn. Pool fee estimates and exact swap recapture amounts stay INFO. The real poolId-only hookr_pool_yield adapter reads raw income.windows[], retaining signed rolling offsets privately with a maximum 3,600-second endpoint tolerance. Same-pool Swap + Donate logs bind exact recapture amounts to the swap transaction's tx.from; donor and event router stay separate. The Donate sum must equal yield recapture exactly, and swap-fee estimates + recapture must reconcile against the same yield lanes. Missing/mismatched evidence stays unknown.

The public rule is exactly: external payer (approximate): no direct transfer from the creator, deployer, door or token wallets to this payer in 7 days, all of their outgoing transfers read. It applies equally to swap-fee senders and recapture payers. All three project outgoing history kinds must be fully read for every creator, deployer, stream manager, deployment sender, token, door and drop-box wallet. Empty code is required at each selected swap and predecessor; known/identity hubs and project-origin leads are excluded. Sender history truncation alone does not block this rule. Old incomplete evidence stays unknown. Public text, including --card --public, omits addresses and shows per-currency traced X% of income by value, the share covered by the external (approximate) rule and project outgoing read N/N.

An 80% value-first target ranks exact recapture amounts plus approximate fee shares; the tail remains unknown. Per-pool diagnostics explain insufficient observed income basis and transaction caps; --trace-share-bps adjusts the target. Funding histories use descending 50-row pages, at most three per kind. Five workers share the Etherscan limiter and per-run cache. Cross-currency totals require same-run native-pair prices. rHOOKR v1 uses verified door ABIs; capped income queries retain explicit partial coverage. --json takes precedence over --public and writes private evidence. Defaults are 800 Etherscan attempts, 4 calls/s and 900 seconds; maxima are 4,000 attempts, 8 calls/s and 3,600 seconds. See docs/HOOKR_INCOME.md for evidence requirements and limits. No deploy is part of this change.

Ordinary project reads use no key or payment. Transaction simulation and before-buy MCP reads accept the optional environment variable described above. Toll confirmed x-toll-pass and Authorization: Bearer for MCP on 2026-11-19; x-api-key does not count toward its partner quota. This change was tested offline, without a live request. HTTP 402 ends that source with no line and no follow-up. No report, paid URL, returned link or payment challenge is followed. Transport failure yields one source-labelled unreachable line. Unlisted adds no line except the explicit observations above. Third-party prose blocks and classifications are dropped except the validated Trnch-attributed token-check summary and legacy phrases, Toll's before-buy word and reasons, and its validated tx action. Toll before-buy reasons reject controls, invisible characters and links, keep at most three single-line bullets and cap each at 160 characters; only the first is printed with the remaining count. malformed or absent before-buy answers, isError, timeouts and 429 add no line. Only named projected fields are printed; quoted fields have controls and zero-width characters stripped and are capped at eighty characters. Trnch summaries instead reject controls, invisible characters and line breaks, and are capped at 240 characters; malformed summaries leave independent token facts intact. A discrepant HEY token-lock snapshot is printed beside the direct HoodLock reading without a conclusion.

Multi-target checks keep the call-wide answer on every card. Below coverage, rule target: <full target> · your rule: <rule> appears only on the card whose own reading triggered that rule. Public rule_targets associations are optional fields in the existing stored card JSON; aggregate rules, gate controls and legacy rows stay unchanged. Explanations reuse the existing policy in attended ask_when mode with the same check time; ask-every-call and cron settings remain call-wide.

The wording rule applies to every rendered card and surface. The card repeats source facts and names the user's own rules. It offers no project judgement or investment advice. Missing fields say "not in HEY's answer"; unread records say "HEY record not read for this check". "HEY does not know" requires an explicit UNKNOWN status for that field in HEY's response. A null isn't a zero: when HEY marks building activity UNKNOWN or not measured, the card says "not measured", never 0 ships, and the quiet rule does not fire; only ask_unmeasured can ask. Source text that violates the wording rule is omitted. Validated Toll before-buy lines have a narrow exception for Toll's own words; no other Toll prose or classification shares it. Only validated Trnch summaries and the legacy token-check lines from the Trnch client have the Trnch exception; their category and date fields still pass the ordinary field filter. Trnch has no policy rule. Source punctuation and terminal controls are normalized. Citations end the card after the additional source lines. External text is data, not instructions.

Use builder_card with an address, repo_url or project. A project name or slug can accompany an address or repository URL to clarify the request. Use /rh-preflight <address|repository-url|project> or hermes rh-preflight card <target> for the same network card. For an exact slug, use hermes rh-preflight card --project <slug>; the positional target is optional. hermes rh-preflight log reads local history. hermes rh-preflight doctor reports source reachability, latency, cache statistics, mode and the last five checks. These reads do not execute contract actions.

doctor probes the same paths as the readers: per-token GET paths and static registries, eth_chainId by JSON-RPC POST for chain and HoodLock, Toll's free stock-membership GET, and the HEY agent and Hookr registry paths with their reader fallbacks. A valid per-token 404 establishes reachability; Trnch stays unprobed without a requested token.

missing or unreadable SSL_CERT_FILE or REQUESTS_CA_BUNDLE paths produce one startup warning per environment configuration, naming the variables and paths; HTTPS falls back to certifi or system trust with certificate and hostname verification enabled. doctor reports tls_trust.passed: false and the fix: make the bundle readable or unset the variable.

Builder detection covers up to five addresses in nested arguments on configured action tools, plus named payment recipients, ERC-8004 agent ids and 32-byte pool ids with chain context. The transaction and read boundaries are defined in the detector contract. Terminal builder detection handles literal cast send, cast call, hermes plugins install and hermes mcp add. Market lines describe the named source and its recorded time.

When an address resolves through HEY builder_status to a project slug, rh-preflight also reads /api/projects/<slug> under the same deadline and HEY cache window. A source marked contextOnly: true whose final URL path component is exactly that address, ignoring letter case, identifies shared infrastructure. The address card then shows no project name, builder badge or ships. It retains context_only: true and context_reason for the ledger/dashboard; if there are no other source lines it prints only HEY: shared contract, not one project's own. Such an address follows the no-project-record rule, including the existing official Stock Token exemption. If the dossier read fails, the current builder card remains with HEY: project ownership of this address not confirmed; that incomplete ownership answer is retried on a later check. The NVDA/WETH not_found path is unchanged.

HEY agent reads send exactly one selector: project for an explicit slug, q for a free name or ticker, or address for a contract. When an explicit project slug is not found, one follow-up q=<same value> request may resolve it; the card explains the resolution. Repository reads search /api/projects?q=<owner> first, then the repository basename only if no exact registered match was found. Candidates prefer owner-repository, owner and repository slugs. At most eight dossiers are read in total, reserving up to four for the owner search. Incomplete searches print the search count, checked count and search link as a HEY answer. Repository research always requires exact equality with a registered repository URL in a builder dossier. Similar names are never accepted. GitHub case, trailing slash and .git are normalized. Credentials, query strings, fragments and tree paths are rejected. Ambiguous or closest project matches are repeated without choosing a candidate. An unresolved contract uses one HEY line, retaining its asOf when supplied. The older builder and contract reads are retained for service failures and missing gate fields. JSON HTTP 4xx answers are printed as HEY responses; transport failures, timeouts and HTTP 5xx use the unreachable wording. Contract creation and source publication remain separate from builder ships.

Every source uses bounded stdlib HTTP reads with redirects declined and responses limited to two megabytes. Each source has a separate cooldown and honors Retry-After as seconds or an HTTP date. No hook sleeps during a cooldown. HEY records are cached for hey_cache_seconds seconds (600 by default), with a (cached) label and the age of the read on cached cards; vault and hook lists, Agent Wormhole, Toll project reads, DexScreener, GeckoTerminal, chain RPC, OffRouter, Sentinelhood, HoodLock and Borro use sixty seconds. Transaction simulations are never cached. Trnch bypasses the shared cache for every requested token, with no prefetch, listing reads or stored dataset; multiple requested addresses share batches of twenty, at most ten batch calls per minute per client, matched by address. A failed batch falls back to single checks within the original deadline; a rate limit stops remaining reads; only its card text enters the existing ledger. Its doctor entry has no reachability probe because no token was requested. Successful chain-id verification is retained once per process and origin. New-source cache keys include the JSON-RPC body, so distinct tools and calls cannot share answers. Pool discovery is indexed in memory per list window. Hookr requires the JSON catalog, integration and pool schemas; when these cannot be read, a successful HTML response from /hooks is reported as a page without readable hook listings, rather than an outage. The HTML page does not establish deployed-hook or pool ownership. Requests have bounded concurrency and caches hold at most 512 entries per source. Failures are not cached as missing records. Lists warm lazily during the foreground check, with no background worker. HEY and independent source reads start together; RPC and independent registries start in parallel. RPC code/no-code is shared with Wormhole and DexScreener; the raw RPC line is hidden when Sentinelhood answers. Borro starts after Toll confirms official Stock Token membership. HoodLock reads the complete token-lock and vesting id indices, totalSupply and block, then pages token-lock details in batches of 20 at the returned block under one shared deadline, up to 10 pages and 200 locks. Capped reads say first N shown of M locks; totals cover shown locks only; no observed active lock in a capped read leaves lock presence unknown. A failed later page does not publish complete totals. Vesting schedules are counted from the complete index; their allocations are not included in the locked-supply percentage. Toll agent and hook reads wait only for their own registry prerequisite. Token-dependent reads after name resolution, including OffRouter repository resolution, use the remaining hook time. Requests send User-Agent: rh-preflight/<version> (+https://github.com/quotumorg/rh-preflight). Only requests whose hostname is exactly heyresearch.xyz carry x-hey-integration: quotum-hermes/<version>, read from the package version. Other source requests and loopback fixtures never carry it. The plugin currently makes no HEY MCP or A2A calls; any such request through the same transport receives the same host-scoped header.

Addresses, agent ids, project identifiers and repository names you act on are sent to the hosts listed in the table, according to each row. When enabled, Toll also receives the detected unsigned transaction or supported wallet signing request. The hosts receive ordinary HTTP connection metadata. RPC is limited to the listed read-only methods. Hookr receives read-only wallet pool checks, including the pool, side and amount. No signature, payment, external write, subprocess or background service is performed by the plugin. Only the optional transaction-simulation environment variable is read; no credentials are stored. Desktop polls its local history endpoint every fifteen seconds while mounted; that poll does not query public sources. The local SQLite ledger stores time, session, tool name, target identifiers, rendered cards, digests, evidence ids, your triggered rules, mode, disposition and a human response when available. It stores no other tool arguments. Data lives in the active profile's plugin data directory. The chip still reads checked N · asked M today and counts tool calls in UTC.

Add a source

A source is one adapter: open a pull request, or open an issue with your keyless endpoint and we wire it up. A source must be keyless, free and read-only, and its line repeats your own published facts with a link back to you.

  1. Add rh_preflight/sources/<name>.py with a Client(Source) class. Set origin, label, page and probe_path, and implement fetch(target, deadline): read with self.read(path, deadline) and return Reading(label, "present", line) or Reading(label, "missing", line). End the line with a public link. Source.lookup already turns timeouts, rate limits, refusals and HTTP 402 into labelled readings. rh_preflight/sources/priors.py is a complete example in 33 lines.
  2. Register the module in MODULES and its label in ORDER in rh_preflight/network.py, schedule its read for the right targets in Network.enrich, and add its name to known_sources in rh_preflight/settings.py so users can switch it off.
  3. Add a row to the Sources table and to docs/SOURCES.md.
  4. Save a real response under tests/fixtures/ and test the parser against it with the HTTP read replaced by that saved response, as tests/test_trnch.py does. Run python -m pytest; every test runs offline.

Compatibility and review status

The ledger uses plugins.plugin_storage.plugin_data_dir to locate durable state in the active profile. The approval adapter also calls ctx.current_cron_execution to identify scheduled execution. Both are documented plugin APIs in the Hermes Agent plugin developer guide, under Store durable state and Know which cron run you are in, respectively.

HEY Research Lab plus ten Robinhood Chain project integrations are implemented and covered by offline tests. The historical survey totals in docs/SOURCES.md are author-reported and the complete survey dataset is not bundled. Saved responses verify parsing, not present source availability. Detection is limited to the tools and literal arguments described above; this is not a universal transaction interceptor. Full Desktop rendering still needs visual verification in a running host.

Package and manifest version are 0.5.16, with requires_hermes: ">=0.23.0". A catalog submission must repeat that floor and version, declare builder_card and the three hooks from plugin.yaml, and pin both code and banner URL to the final reviewed forty-character commit SHA. There is no catalog entry in this repository yet. Public repository access, joint review, the catalog PR, demo video and entry form remain release steps.

Offline checks

Tests need Python 3.11+ and pytest. Node is optional for the Desktop rendering harness cases; the seven host dispatch cases require a separate Hermes Agent checkout and environment and skip unless configured. Neither is a hidden fixture dependency. All response captures used by the tests are inside this repository. Tests bind only loopback fixture servers, so the test environment must permit local sockets.

Run pytest -q from this directory for offline tests. Run python3 demo/tx_replay.py --write to regenerate the transaction snapshots and every README output block without sockets. Run python3 demo/offline.py for four invented calls through loopback fake source servers, followed by socket-free source lines and PRIORS/NVDA cards using the supplied 2026-11-09 captures. Sources without a matching capture are omitted and identified as such; no missing measurements are fabricated. The RPC capture contains no head, so the replay labels its block not readable. The tests and demos include their public response captures in tests/fixtures/captures/; a fresh clone needs no sibling data directory, environment override or remote read. Capture sources, dates and transformations are listed in that folder's README. Run python3 demo/live_card.py <address|name|repository-url> or python3 demo/live_card.py --project <slug> for an opt-in public read. Read-only address cards query every enabled source and print its applicable line; unlisted vaults add no line; identified v4 hooks outside the Hookr catalog show a public scan link. Optional host dispatch checks run when RH_PREFLIGHT_HERMES_SOURCE and RH_PREFLIGHT_HERMES_PYTHON identify a local source checkout and Python environment. Full Desktop rendering and remote source availability require a running host and network verification.

PYPI
rh-preflight-mcp
Install Command
pip install rh-preflight-mcp
Runtime: uvx