feat(plugins): references_dir + plugin_reference_tool for agent-visible skill references

[offendingcommit]

Plugin skills declared via plugin_skill() can only ever expose their bare SKILL.md — there's no way to ship a companion references/ directory alongside it, so a plugin that wants to give the agent a deeper lookup doc has nowhere to put it through this SDK's own registration path. This adds that declaration surface, and a working way to actually reach it today rather than waiting on a host change.

What's here

1. references_dir on plugin_skill()/PluginSkill/register_plugin() — forward-compatible groundwork. The actual host-side capability to serve companion files lives in hermes-agent, not here, and hasn't shipped in any released host. This is the kit half of that contract: plugins that declare references_dir today start working automatically the moment a host adds support, no second kit-side change required.
2. plugin_reference_tool(skill, *, toolset) — makes the directory agent-visible today, without waiting on that host change. It builds an ordinary @tool function (the same mechanism every other plugin capability already uses) that lists or reads files under references_dir directly, sidestepping register_skill/skill_view entirely.

Design decisions

• Groundwork says it's groundwork. Every doc surface (README, this repo's own skills/hermes-plugins authoring reference, docstrings) states plainly that no released host reads references_dir via register_skill yet, rather than implying a capability that doesn't exist. plugin_reference_tool exists precisely because that gap has no timeline.
• The signature probe alone isn't trustworthy, so the call site doesn't rely on it alone. A bare Mock(spec=...) test double or a decorator applied without functools.wraps both present a (*args, **kwargs) shape that reads as "the host accepts this" even when it doesn't — confirmed by reproducing both live. register_plugin() retries once without references_dir if the host rejects it with a TypeError naming it; Python raises that error at argument binding, before the callee's body executes, so retrying is safe even against a host with side effects.
• references_dir must actually be scoped to the skill. Review reproduced, end-to-end, that an unscoped references_dir (e.g. pointing it at /etc) turns plugin_reference_tool into an arbitrary-file-read tool using only the documented public API. Fixed by requiring references_dir to resolve as a descendant of the skill's own directory — enforced in plugin_skill() at declaration time, and re-checked defensively in plugin_reference_tool() in case PluginSkill is constructed directly, bypassing that factory.
• A real correctness bug surfaced in review, not just a hardening gap. plugin_skill() was resolving an optional skill's missing references_dir to None before register_plugin() ever ran its own check, so the "dropped with a warning" behavior the README promised never actually logged anything for the ordinary case. Fixed by having plugin_skill() only validate existence for required skills, exactly mirroring how SKILL.md itself is already handled.
• Default tool-name derivation now handles every name plugin_skill() itself accepts. The first cut only swapped hyphens for underscores; any skill name with an uppercase letter or leading digit (both legal per plugin_skill()'s own name pattern) produced an invalid tool name and crashed. Fixed with a proper normalize-and-guard helper, reproduced and locked in with a test.

Test plan

• just test — 181 unit tests pass: 13 for references_dir plumbing (declaration-time/registration-time validation, the capability probe and its retry-on-rejection safety net, an explicit-named-parameter host, a **kwargs-only host, uninspectable signatures, unrelated TypeError passthrough) and 15 for plugin_reference_tool (listing, reading, custom name/description, the containment fix from both enforcement points, the tool-name fix for uppercase/leading-digit skill names, absolute-path/relative-traversal/symlink rejection, non-string file_path, empty directories, and a directory passed as file_path).
• just test-contract against the real hermes-agent checkout could not be run in this environment — fails on main too, before this change, on an unrelated pre-existing import gap. Confirmed via direct source reading (not just the failing import) that the real host's register_skill(self, name, path, description="") has no references_dir parameter and no **kwargs, so this change's fallback path — register without it, log a warning — is exactly what fires against production today.
• uv run python -m compileall -q hermes_plugin_kit tests — clean.

Known Residuals

Reviewed and accepted, not applied, each for a stated reason:

• plugin_reference_tool reads are not TOCTOU-safe against a references_dir writable by an untrusted process at runtime (the containment check and the eventual read are separate syscalls, not a held file descriptor). Fine for the intended case — a static directory shipped with the plugin — insufficient if that assumption doesn't hold for a given deployment; documented in the README and the docstring rather than solved with fd-pinning, which is disproportionate for a directory authored by the plugin's own build pipeline.
• register_plugin() is not transactional. A failure partway through registers some surfaces and not others — true of every registration surface in this function already, not specific to this change.
• tests/test_hermes_contract.py (just test-contract) was not extended with a case exercising references_dir against the real host signature — the local hermes-agent checkout can't currently be imported in this environment for unrelated reasons (see Test plan).

Post-Deploy Monitoring & Validation

No additional operational monitoring required for the references_dir plumbing — it ships no runtime behavior change for any consumer (no plugin in this ecosystem currently passes it). plugin_reference_tool is opt-in per plugin (a plugin must explicitly call it and register the result), so it also has no default-on behavior to monitor; once a plugin adopts it, watch that plugin's own tool-call logs for the new <skill>_read_reference tool name.

---