hermes-agent/website/docs/developer-guide
Teknium b088535c78 feat(plugins): capability declarations + install/update consent flow (#64228)
Unify the scattered per-plugin trust gates into one declared, diffable
capability model with an install/update-time consent flow. Consent +
audit over host API surfaces — explicitly NOT a sandbox.

New module hermes_cli/plugin_capabilities.py:
- Canonical CAPABILITY_REGISTRY mapping each capability id 1:1 to an
  EXISTING enforcing gate (no capability minted without a surface):
    tools.override          -> allow_tool_override
    llm.provider_override   -> llm.allow_provider_override
    llm.model_override      -> llm.allow_model_override
    llm.agent_id_override   -> llm.allow_agent_id_override
    llm.profile_override    -> llm.allow_profile_override
    llm.task_override       -> llm.allow_task_override
- plugin_capability_granted(plugin_id, capability): canonical check —
  granted set OR deprecated legacy allow_* key; fail closed on unknown
  ids and any unreadable/corrupt consent state; emits checked_by audit
  log lines on every decision.
- record_consent() persists plugins.entries.<id>.granted_capabilities +
  capabilities_consent {hash, granted_at} and mirrors grants into the
  legacy keys so existing enforcement sites keep working unchanged.
- capability_set_hash / pending_capabilities / declared_set_changed
  power the update-time re-consent diff.

Wiring:
- plugin.yaml manifest field `capabilities:` parsed into
  PluginManifest.capabilities (unknown ids dropped with a warning).
- hermes plugins install: consent screen (one Y/n) when the manifest
  declares capabilities; non-interactive installs proceed with
  capabilities ungranted (fail closed).
- hermes plugins update: when the new version declares capabilities the
  granted set lacks (hash diff), the additions are surfaced and require
  re-consent — an update can never silently widen access.
- hermes plugins enable: consent screen replaces the standalone
  tool-override prompt for capability-declaring plugins.
- hermes plugins capabilities [<id>]: declared vs granted per plugin,
  flags grants held via deprecated legacy keys.
- PluginContext.has_capability() probing API so plugins degrade
  gracefully; _tool_override_allowed migrated to the canonical
  plugin_capability_granted path (reference migration; legacy
  allow_tool_override still honored).

Tests: tests/hermes_cli/test_plugin_capabilities.py (38 tests) —
declaration parsing, consent grant/persist, update re-consent on added
capability, fail-closed on missing/corrupt state, legacy-gate backward
compat, consent CLI flow (grant / decline / non-interactive).

Docs: user-guide plugins.md consent section (with explicit not-a-sandbox
warning) + developer-guide plugin authoring capability note.

Salvages the intent of PR #37976 (@coygeek — require renewed review
before plugin updates), scoped to capability diffs.

Part of #64182.
2026-08-12 18:05:21 -07:00
..
plugins feat(plugins): capability declarations + install/update consent flow (#64228) 2026-08-12 18:05:21 -07:00
_category_.json
…
acp-internals.md rip out brew + pip/PyPI wheel support (#68217) 2026-07-22 16:51:01 -04:00
adding-platform-adapters.md feat(platforms): add typed plugin send paths 2026-08-12 16:27:19 -07:00
adding-providers.md docs: DX sweep — 7 verified-absent documentation items 2026-08-07 08:58:08 -07:00
adding-tools.md
…
agent-loop.md Revert "feat: add DCP context engine" 2026-08-08 23:09:43 +05:30
architecture.md Revert "feat: add DCP context engine" 2026-08-08 23:09:43 +05:30
browser-provider-plugin.md
…
browser-supervisor.md
…
codebase-ownership.md docs: DX sweep — 7 verified-absent documentation items 2026-08-07 08:58:08 -07:00
context-compression-and-caching.md feat(compression): native OpenAI Responses server-side compaction for gpt-5.6 2026-08-08 11:24:45 -07:00
context-engine-plugin.md fix(agent): isolate the pooled compression worker from the live transcript (review F3) 2026-08-02 16:16:36 -07:00
contributing.md cleanup: remove references to simple-term-menu 2026-08-10 15:13:29 -04:00
creating-skills.md
…
cron-internals.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
desktop-plugin-sdk.md feat(desktop): ctx.os — the curated OS door for plugins 2026-08-04 11:33:25 -06:00
egress-internals.md Reapply "Merge pull request #30179 from NousResearch/feat/iron-proxy" 2026-07-24 09:49:00 -07:00
extending-the-cli.md
…
gateway-internals.md docs: sync overnight sweep with registry, gateway, curator, cron 2026-07-29 09:45:11 -07:00
image-gen-provider-plugin.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
memory-provider-plugin.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
model-provider-plugin.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
plugin-llm-access.md fix(plugins): complete task-routed LLM integration 2026-08-12 16:25:20 -07:00
programmatic-integration.md fix: close sibling display_kind drops and ui-tui parity for #82756 2026-08-10 11:01:15 +05:30
prompt-assembly.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
provider-runtime.md Revert "remove Vercel AI Gateway and Vercel Sandbox (#33067)" 2026-07-29 19:48:37 -07:00
secret-source-plugin.md fix: track secret source registration origin 2026-08-12 16:25:10 -07:00
session-storage.md perf(state): add messages(session_id, id) index for window/ordering queries 2026-08-02 21:16:17 +05:30
subagent-lifecycle-api.md fix subagent lifecycle ownership invariants 2026-07-26 23:27:30 -07:00
tools-runtime.md docs(plugins): clarify tool description sources 2026-08-09 00:52:07 -07:00
trajectory-format.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
video-gen-provider-plugin.md docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
web-search-provider-plugin.md
…
worktree-ui-dev.md docs(developer-guide): document htui/hgui worktree UI dev helpers (#64783) 2026-07-16 22:51:23 -04:00