✓ declared tools — matches registrations
⚠ provides_tools declares probe_tool but register() did not register them
Validation passed.
Those three lines are one run of hermes plugins validate on 20 November 2026. The process exited 0. The JSON report set ok to true. The check named declared tools was itself ok, and its detail was matches registrations. The warning was not a second command and not a later retry. It was the next line of the same report.
The directory held two files. plugin.yaml named the plugin probe-declared, set version 0.0.1, set a one-sentence description, and listed probe_tool under provides_tools. __init__.py defined register and returned None. Nothing in that function called ctx.register_tool. The name in the manifest was not a name the function registered. The checkmark still said the list matched.
A catalog job that reads the exit code, the final sentence, or the ok field will accept that directory. A job that reads only the declared tools detail will accept it too. The disagreement is in the warning, and the warning does not change the exit.
The command and the host
hermes --version printed Hermes Agent v0.22.5+471.g5894e75 (2026.9.24), then stable, then a local revision, then Python 3.14.9. The same output said an update was available. This run did not apply it. The host was Linux x86_64. Each command used a new HERMES_HOME under the lab, not the operator home. The operator configuration file’s modification time was the same before and after. No plugin was installed. No gateway was started. No model call was made.
The trees were synthetic. Each one is a manifest plus a register function, enough for this binary’s admission check and nothing else. Paths below are the names of those trees, not a layout you should copy onto a host.
Missing name, extra name
The developer guide, fetched the same morning, says to list every tool register() registers in provides_tools. It then says the declared tools check fails when the registered tools do not match the list, and that the failure blocks catalog admission. On this binary the two directions of “do not match” are not the same exit.
The missing-name tree is the one above. Text mode printed the checkmark, then the warning, then Validation passed. JSON mode put the same warning in warnings and left the check successful:
{
"name": "declared tools",
"ok": true,
"detail": "matches registrations"
}
The warning string was provides_tools declares probe_tool but register() did not register them.
A second tree, extra-tool, had no provides_tools list. Its register called ctx.register_tool with the name extra_tool and a no-op handler. Text mode marked declared tools failed, named extra_tool as an undeclared tool registered and not in provides_tools, and ended with Validation failed. The exit was 1. The warnings array was empty. There was no checkmark for that check, and there was no warning to miss. This is the direction the guide sentence describes.
A third tree, both-ways, declared named_tool and registered extra_tool. The exit was 1. The failed check named only extra_tool. The warning named only named_tool. A log scraper that keeps the failed line and drops warnings will record the name that appeared and lose the name that disappeared. The rename is two edits. This command fails the command for one of them.
Hooks follow the tool rule. A tree that listed post_tool_call under provides_hooks and did not call ctx.register_hook exited 0. The declared hooks line said matches registrations. The warning said provides_hooks declares post_tool_call but register() did not register them. A tree that called ctx.register_hook for post_tool_call and did not list it exited 1. The failed check named that hook. There was no warning.
Middleware follows the validate rule and not the doctor rule, which is the next section. A tree that listed llm_request under provides_middleware and did not call ctx.register_middleware exited 0, with a checkmark on declared middleware and a warning that provides_middleware declares llm_request. A tree that called ctx.register_middleware("llm_request", ...) and did not list it exited 1. The failed check named llm_request. llm_request is a kind this project’s own plugin tests pass to register_middleware. It was not an invented event name.
The plain tree, with a manifest and a register that returns None and no capability lists, exited 0 with an empty warnings array. The checkmarks on that tree mean there was nothing to disagree about. The checkmarks on the missing-name trees do not mean that.
What the guide is using the list for
The same guide page says provides_tools does not decide whether a user-installed plugin’s tools load. Once the plugin is enabled, everything register() registers is available, declared or not. That sentence was not retested here by enabling a plugin in a gateway. It is the reason the two exits are different problems.
An extra registration is capability the manifest did not advertise. Validate refuses it. That is the catalog gate the guide is pointing at, and on this binary it works for tools, hooks, and middleware.
A name that is only in the manifest is the other problem. Validate accepts it. The same page says the list drives the catalog’s tool-count chips and tool-name search, and that dashboard auth hints use availability checks for declared tools only. Those surfaces were not opened in this run. If that page is right, a missing register_tool call can still leave a name on a listing and on an auth hint, and this binary will not stop the commit that does it.
The page was fetched from the developer guide on 20 November 2026. Hermes 0.23.3 was tagged the day before. This host is not running that tag. Do not read the measured exits as a result for 0.23.3. Read them as the result for the binary hermes --version named, which is the binary a job on this host will call until someone updates it. After an update, run both trees again before you trust the guide sentence. The sentence is wider than this exit code: it says the check fails when the registered tools do not match the list. This binary fails the check when register() adds a name the list does not have. It does not fail the check when the list has a name register() never adds.
Plugin Doctor does not close it
hermes plugins doctor --help says --ci exits non-zero when validation reports an error. It does not say a warning is an error.
On the missing-tool tree, doctor printed a warning that the manifest declares probe_tool but registration did not add it, then printed OK: runtime discovery, manifest parsing, import, and registration passed, and exited 0. On the extra-tool tree it printed a warning that registration adds extra_tool and that the name is not listed in provides_tools, then the same OK line, and exited 0. The hook trees did the same: a warning for each direction, then OK, then exit 0. --ci did not change those exits. A warning is not the error --ci is waiting for.
The middleware trees are quieter. Doctor printed no warning for the missing llm_request declaration and no warning for the extra llm_request registration. Both exited 0. Both ended with registrations: 0 tool(s), 0 hook(s). There is no middleware count in that summary. Doctor is not silent because the trees were empty. Validate had already distinguished them. Doctor’s summary does not mention the kind validate failed.
The guide says doctor runs the same discovery, manifest parser, register(ctx), and registries Hermes uses, under a temporary HERMES_HOME, and blocks direct Python socket connections during that check. It also says this is not a sandbox: plugin code still runs as the current user and can start subprocesses. Run it only on a tree you are willing to import. This run did that, against the synthetic functions above, with HERMES_HOME pointed at the lab. It is a useful import check. It is not the admission exit. A job that calls doctor because validate is noisy will accept the extra registration validate refuses, and it will also accept the missing name validate only warns about. For middleware it will not even print the warning.
What to require before you merge
Point validate at the plugin root, the directory that contains plugin.yaml, not at a parent that holds several plugins. Ask for JSON when a script will decide.
hermes plugins validate --json PLUGIN_DIR
On this binary, exit 0 is necessary and not sufficient. Read warnings. Fail the job if any warning starts with provides_tools, provides_hooks, or provides_middleware. Those are the lines that carry a declared name register() did not add. The matching check can still be ok with detail matches registrations while that warning is present. Treating the detail as a comparison result is how the missing name gets through.
Also fail the job on exit 1. That is the extra-registration case. The failed check names the extra tool, hook, or middleware. Keep the warnings from that run as well. The both-ways tree shows why: exit 1 can be the new name, and the old name can be only in warnings.
Text mode is the form to read at a terminal. The checkmarks are printed before the warnings. Validation passed. is printed after them. If you stop at the last line, you will miss the only line that names probe_tool.
hermes plugins validate PLUGIN_DIR
echo "exit=$?"
Do not substitute hermes plugins doctor --ci for that pair. Use doctor when you want the runtime import, the manifest parse, and the registration warnings it does print for tools and hooks. Do not use its exit code as the catalog gate on this build. Do not use it as the middleware comparison. Validate is the command whose exit changes when an undeclared name is registered.
A tree with no capability lists and a register that returns None is a weak control, not a proof that the plugin is empty in a gateway. It shows that a clean report is possible. The missing-name report is also a clean exit. The difference is the warning line. Require the warning list to be empty if the list in the manifest is supposed to be the list register() adds.
What was not run
These trees were not installed with hermes plugins install, not enabled, and not loaded by a gateway session. The guide’s statement that an enabled plugin exposes every tool register() registers, declared or not, is the documented load rule. It is not a second measurement from this host. Catalog chips, dashboard auth hints, and a real catalog admission workflow were not opened. The security scan on these particular trees reported safe. That scan is a different check. Do not treat a safe scan on an empty register as a review of a plugin that reads credentials or starts a network client.
Hermes 0.23.3 was not installed beside this binary. The guide page fetched today still uses the broad sentence about a failed match. If a newer CLI fails the missing-name tree, the procedure above still works: a non-empty warning fails the job, and so does exit 1. If a newer CLI moves the missing name into the failed check and clears the warning, the same read still works. The read that does not work is an exit-code-only gate, or a gate that trusts matches registrations without reading warnings.
Verification
Rebuild the two tool trees in a scratch directory. The missing-name manifest lists one tool. Its register returns None. The extra-name manifest lists no tools. Its register calls ctx.register_tool once. Run hermes plugins validate on each. On 0.22.5+471.g5894e75 the first exits 0, prints matches registrations, prints the warning that names the declared tool, and prints Validation passed. The second exits 1, names the extra tool on the failed check, and prints Validation failed.
Repeat with provides_hooks and post_tool_call, and with provides_middleware and llm_request. The validate exits match the tool case. Then run hermes plugins doctor --ci on the extra-tool tree and require yourself to notice exit 0. If that exit is the only thing your job stores, the extra registration is already in.
The operator home was not the HERMES_HOME for these commands, and its configuration timestamp did not move. Keep that split when you reproduce the check. Doctor imports the tree. Point it at a copy.
Sources
hermes --versionon 20 November 2026: Hermes Agent v0.22.5+471.g5894e75 (2026.9.24), Python 3.14.9, Linux x86_64. The same output said an update was available. It was not applied.hermes plugins validateandhermes plugins validate --json, plushermes plugins doctor --ci, against the synthetic trees described above. No install and no model call.- Build a Hermes plugin, step 2, fetched 20 November 2026. The page says the declared-tools check fails when the registered tools do not match the list, and that
provides_toolsdoes not by itself decide what an enabled plugin loads. hermes plugins doctor --helpon the same binary:--ciexits non-zero when validation reports an error.