Importing a Hermes internal? There is now a published list of what plugins may import


Your plugin has been in use for three months without a complaint. Then a new Hermes release ships, a user upgrades, and the plugin fails to load with an ImportError. You go through the changelog: nothing mentions your plugin. You go through your code, and the culprit is one line you wrote half a year ago — from hermes_cli.cli_config_load import _parse_service_tier_config — pointing at an internal function that has since moved.

What makes this class of accident so unpleasant is that nothing goes wrong at the moment you write it. The plugin installs, runs and passes its tests. This is a delayed charge, and the change below is about exposing it early.

Why a private import is always a future break

Hermes already has a runtime check, the core-override rule: a plugin may not rebind a function inside a core module at runtime. But that check governs replacing, not referencing. Importing an internal passes it — and then you are attached to somebody’s private implementation, which carries no compatibility promise: it can be renamed, moved, or removed in a refactor you never hear about.

For a plugin author the cost arrives late; for a reviewer it is nearly invisible in a few hundred lines of code. What the problem actually needs is a static, mechanically decidable boundary: is the thing you imported on the published list?

The list moved out of the code

It used to be a frozenset hardcoded in hermes_cli/plugin_validate_private_imports.py. Workable, but invisible to plugin authors — you found out what was on it when CI pointed at your line.

The change on November 5 moved the list, unchanged, into hermes_cli/data/plugin_api.json (already shipped as package data), and the validator reads it from there. A generator script renders the docs page developer-guide/plugins/public-api.md from the same file, and — the important part — a test fails when the page is stale. The list cannot drift quietly: changing it forces the docs to change with it.

A day later the list gained its first entry that is squarely “what a plugin should call”: agent.redact.redact_sensitive_text, covered below.

Three verdicts

The rule is short:

  • A whole-module row (say agent.memory_provider) allows that module and every name in it that does not start with an underscore.
  • A single-name row (say hermes_cli.auth_model_picker:prompt_model_selection) allows that one name only.
  • A Hermes module outside the list: a warning, never a block.

Not blocking is deliberate. This is the admission gate’s hint (catalog rule 9, public surfaces only), not a compiler: the plugin still installs and still runs, and both the author and the reviewer can see “this will probably break one day”.

Four categories are never flagged: the standard library, third-party packages, the plugin’s own modules, and imports under if TYPE_CHECKING:. That last one is genuinely useful — when a type annotation needs an internal type, wrapping the import in TYPE_CHECKING is the clean move. String imports through importlib.import_module("hermes_cli.…") are resolved too, so a different spelling is not an escape.

What the warning looks like

Findings are printed as relative/path.py:line module[.name]:

myplugin/tools.py:41 hermes_cli.cli_config_load._parse_service_tier_config

One detail is worth knowing: the report lists the first site of every distinct module before the remaining sites. When the list is truncated you still see the breadth — how many internal modules you touch — rather than ten lines of the same one. In CI, --json gives you a machine-readable report; --install-deps installs declared dependencies before the capability probe, which is how the catalog gate runs it.

The new entry: redact_sensitive_text

This one deserves its own section, because it answers a question plugin authors hit constantly: I want to send user text to a model. How do I mask the secrets first?

The old answer was from agent.redact import redact_sensitive_text — it worked, but the validator warned you, because it was private. It is public API now:

from agent.redact import redact_sensitive_text

text = redact_sensitive_text(user_text, force=True)

Why a function rather than a redact= parameter on ctx.llm? Because a plugin may handle the same text several times — slice it, concatenate it, paste it into a prompt — and redacting only at the final call is not enough. With the function in hand, you can clean it wherever it needs cleaning.

The force=True semantics are the part to remember: it is the switch that leaves you no way out. By default redaction follows the operator’s security.redact_secrets setting, so with that turned off the function returns text unchanged. Text bound for a model is a security boundary, and there the setting should not decide — hence force=True. The official wording is that you use it where secrets must never leave the machine.

Two more parameters matter. code_file=True skips the ENV/JSON assignment passes for known source code, so a fixture like MAX_TOKENS=*** survives. file_read=True is for file content returned to the agent: prefix-matched credentials such as ghp_… become a non-reusable sentinel instead of a head/tail mask, because a head/tail mask looks like a real but truncated key — and an agent may well write that back into config.yaml.

Checking your own plugin

hermes plugins validate ./my-plugin
hermes plugins validate ./my-plugin --json

Look for imports starting with the core packages — hermes_cli., agent., gateway., tools.. If you find one, there are three exits: switch to a public entry on the list; if it exists only for a type annotation, put it under TYPE_CHECKING; or accept that you need an internal and plan to move with core — at least now you know where you are standing.

For the wider picture of how plugins are admitted, installed and laid out, the plugin catalog guide covers it. If your interest is how secrets are handled along the way, the three redaction lanes looks at the same machinery from the other end.

Can you use it today

The list move and the new entry are on main (November 5–6) and not in the v0.23.0 tag. On a stable build, hermes plugins validate still reads the list hardcoded in the source, and redact_sensitive_text is still a private import.

Update (2026-11-10): these changes shipped in v0.23.1 (November 9) — hermes update is enough. The “not in v0.23.0” statements above are still accurate; v0.23.1 closes the gap.

The value of this does not depend on the version, though: write against the published page now. What is on the list is stable; what is off it is borrowed. That rule does not change with a release.

The takeaway

No feature was added here. Visibility was. A rule that had always existed, and that only reviewers held in their heads, is now a file you can read, a page you can search, and a check your CI can run — with a test that keeps the page honest. It will not make a plugin faster, but it is the kind of groundwork that keeps it installable ten releases from now.