Follow up Hermes Agent upstream updates: MCP ssl_verify/skip_preflight/sampling dropped and clobbered, stale delegate_task toolsets argument

[dyoshikawa]

Summary

No Hermes Agent release newer than the one rulesync is validated against has shipped (v2026.7.20 / v0.19.0 is still Latest), but three drifts exist: three MCP per-server keys are dropped and destroyed on regenerate, and the generated subagent/command plugins still pass a toolsets argument that delegate_task no longer accepts.

This does not overlap with open issue #2389 (honor HERMES_HOME for all global configuration), whose scope is global config root resolution rather than the per-feature schemas below.

Recent Releases

gh release list -R NousResearch/hermes-agent confirms v2026.7.20 (Hermes Agent v0.19.0, 2026-07-20) is still Latest as of 2026-07-26 — i.e. rulesync's documented compatibility baseline is current.

Version	Tag	Date	Notes
v0.19.0 "Quicksilver"	v2026.7.20	2026-07-20	release — smart approvals default + approvals.deny user deny rules, mcp__server__tool naming, hosted MCP OAuth + redirect_uri/redirect_host, live subagent transcripts + durable background delegation, stacked slash-skill invocations, pre_tool_call approve escalation re-landed. Rolls up the v0.18.1/v0.18.2 windows.
v0.18.2	v2026.7.7.2	2026-07-07	release — WhatsApp Baileys dependency patch only. No config surface.
v0.18.1	v2026.7.7	2026-07-07	release — infrastructure patch tag, uncurated; contents documented in v0.19.0.
v0.18.0 "Judgment"	v2026.7.1	2026-07-01	release
v0.17.0	v2026.6.19	2026-06-19	release
v0.16.0 "Surface"	v2026.6.5	2026-06-06	release
v0.15.x	v2026.5.28…v2026.5.29.2	2026-05-28/29	mTLS + ssl_verify MCP keys land in this window (PR #33721, doc commit 2026-05-28)

Unreleased main changes since v0.19.0 were also inspected and none require a rulesync change: fnmatch glob support in tools.include/exclude filters (2026-07-22), approvals.smart_policy / approvals.denial_breaker_threshold (2026-07-26), and Slack reaction:added / reaction:removed gateway hook events (2026-07-23).

Dry-runs used for validation (from /workspace):

--targets hermesagent --features "*" --dry-run
  → .hermes.md, .hermes/plugins/rulesync-ignore/*, .hermes/rulesync/subagents/*.json,
    .hermes/plugins/rulesync-subagents/*, .hermes/config.yaml (activation);
    mcp/hooks/permissions skipped with "global scope only"
--targets hermesagent --features "*" --global --dry-run
  → ~/.hermes/config.yaml (mcp + hooks + permissions), ~/.hermes/skills/**, ~/.hermes/rulesync/subagents/*

Gaps

1. mcp — ssl_verify, skip_preflight and sampling are dropped, and destroyed on regenerate

• Upstream: the MCP config reference documents these per-server keys under mcp_servers.<name>:

  • ssl_verify (bool or PEM CA-bundle path) — landed with the mTLS work, doc commit 87e5b2f (2026-05-28, PR #33721), the same PR as client_cert / client_key.
  • skip_preflight (bool, HTTP) — bypasses the fail-fast content-type probe; doc commit 81becec4 (2026-07-06), shipped in v0.19.0.
  • sampling (mapping: enabled, model, max_tokens_cap, timeout, max_rpm, max_tool_rounds, allowed_models, log_level) — MCP sampling support (PR chore: remove AmazonQ Developer CLI support #753).

• rulesync (global): copyHermesAdvancedFields (src/features/mcp/hermesagent-mcp.ts) whitelists only auth, client_cert, client_key, connect_timeout, supports_parallel_tool_calls, oauth.{redirect_uri,redirect_host,client_id,client_secret,redirect_port,scopes}, idle_timeout_seconds, max_lifetime_seconds. ssl_verify, skip_preflight and sampling are in neither the export path (convertServerToHermes) nor the import path (convertFromHermesFormat).

  Two user-visible consequences:

  1. Those keys cannot be authored from .rulesync/mcp.json at all — not even through the hermesagent override, which is populated exclusively from copyHermesAdvancedFields.
  2. They are destroyed on regenerate: mergeHermesMcpServers merges at the server-name level ({...existingMcpServers, ...mcpServers}), so a hand-written ssl_verify: "~/ca.pem" on a server rulesync also manages is replaced wholesale by the converted entry. This is the same class of bug Follow up Hermes Agent upstream updates: MCP advanced per-server fields (auth/oauth, mTLS, connect_timeout) dropped on export #2236 fixed for auth/mTLS; ssl_verify was part of that same upstream PR but was missed.

2. subagents / commands — generated plugins still pass a removed delegate_task argument

• Upstream: delegate_task no longer accepts a model-facing toolsets argument. Confirmed in tools/delegate_tool.py:

  # NOTE: nested delegation is granted by role='orchestrator' (which re-adds the
  # "delegation" toolset in _build_child_agent), NOT by the model naming toolsets
  # — the model has no toolsets argument. Subagents inherit the parent's toolsets.

  The signature is delegate_task(goal, context, tasks, max_iterations, role, background, parent_agent), and the registry handler explicitly picks only those keys out of args. Documented in commit 35c5781 "docs(delegation): align guidance with current contract" (2026-07-17), which rewrote the delegation docs to state: "delegate_task does not accept a model-facing toolsets parameter. Each subagent inherits the parent's enabled toolsets so the model cannot grant a child capabilities that the parent does not have." Shipped in v0.19.0.

• rulesync (project + global for subagents, global for commands): both generated Python plugins still send toolsets in the dispatch_tool payload — src/features/subagents/hermesagent-subagent.ts (toolsets = subagent.get("toolsets") or ["terminal", "file", "web"], "toolsets": toolsets), so every emitted .hermes/rulesync/subagents/<slug>.json carries a hardcoded toolsets: ["terminal", "file", "web"]; and src/features/commands/hermesagent-command.ts ("toolsets": ["terminal", "file", "web"]).

• Because the registry handler ignores unknown keys, this fails silently rather than erroring — but the emitted spec advertises a per-subagent tool restriction Hermes no longer honors, and the toolsets field in the generated JSON is dead schema that an importer, or a user editing the file, would reasonably trust.

3. skills — skills.external_dirs unused, so project-scope skills stay unsupported (minor)

• Upstream: skills.external_dirs in ~/.hermes/config.yaml adds extra skill roots that are fully integrated (system-prompt index, skills_list, skill_view, /skill-name slash commands), with ~ and ${VAR} expansion — external skill directories (introduced 2026-03-29, PR #3678 — not a recent change; listed only because rulesync has never claimed it).
• rulesync (global only): HermesagentSkill.getSettablePaths() (src/features/skills/hermesagent-skill.ts) hardcodes HERMESAGENT_SKILLS_DIR_PATH = .hermes/skills, and the matrix marks skills 🌏 global-only. rulesync already writes to the global config.yaml from a project generate run (the project-plugin activation path in src/features/shared/hermes-project-plugin-activation.ts), so the mechanism for registering a project path exists.

Proposed Follow-up

1. Extend copyHermesAdvancedFields to carry ssl_verify (boolean | string), skip_preflight (boolean) and sampling (plain object, deep-copied with prototype-pollution key stripping) verbatim in both directions, and cover them in hermesagent-mcp.test.ts.
2. Drop toolsets from the generated delegate_task payload and from the emitted .hermes/rulesync/{subagents,commands}/*.json spec in both adapters (and from the round-trip readers). If a per-subagent knob is still wanted, role (leaf | orchestrator) and max_iterations are the parameters the current schema actually accepts.
3. Optional, and a design decision rather than a regression: emit project skills to <project>/.hermes/skills/ and append that absolute path to skills.external_dirs in the resolved HERMES_HOME config, mirroring the project-plugin activation flow, to earn a ✅ in the skills column.

Per-feature verification (non-gaps)

Feature	Upstream surface	rulesync today	Verdict
rules	.hermes.md / HERMES.md root context file (walks to git root); nested AGENTS.md/CLAUDE.md/.cursorrules progressive discovery; ~/.hermes/SOUL.md is identity, not user rules	project — root .hermes.md, non-root bodies folded in (decision recorded in #2214)	no gap
ignore	no native ignore file; enforced via a project plugin on pre_tool_call + transform_tool_result	project — guards read_file/write_file/patch and filters search_files; the Hermes file toolset still contains exactly these four tools	no gap
hooks	shell hooks under hooks: in ~/.hermes/config.yaml; VALID_HOOKS event keys	global — rulesync's native list is a superset of the documented VALID_HOOKS table (incl. pre_verify, subagent_start/stop, pre_gateway_dispatch, pre/post_approval_response, the three transform_*, and kanban_task_*). Gateway hooks (HOOK.yaml + handler.py, incl. the new reaction:* events) are Python-only and out of the canonical command-hook model	no gap
permissions	command_allowlist, approvals.{mode,deny,denial_breaker_threshold,smart_policy}, security.{redact_secrets,tirith_*,website_blocklist}	global — bash deny → approvals.deny, webfetch deny → security.website_blocklist, allow → command_allowlist, and every other approvals.*/security.*/skills.*/memory.* key passes through buildHermesOverride; the new smart_policy / denial_breaker_threshold keys are already expressible	no gap
checks	pre_verify hook (added 2026-06-30)	project, simulated via a rulesync-checks plugin registering pre_verify	no gap

Open questions / unconfirmed

• mcp__server__tool naming convention (v0.19.0 highlight, PR #52750) vs. mcp_<server>_<tool> still documented in mcp-config-reference.md#tool-naming. The two primary sources disagree and this could not be resolved from docs alone. It does not affect rulesync either way: tools.include/exclude filters use the original (unsanitized) MCP tool names, which is exactly what rulesync passes through from enabledTools/disabledTools.
• fnmatch globs in tools.include/exclude (main, 2026-07-22, unreleased) — purely a widening of pattern semantics; rulesync passes the strings through verbatim, so no adapter change is implied.
• The hooks.md shell-hook section says hooks are declared in cli-config.yaml in its prose intro but ~/.hermes/config.yaml in its comparison table and every example. cli-config.yaml.example is the in-repo template that installs as ~/.hermes/config.yaml, so rulesync's target file is correct; the prose is an upstream doc slip.

References

• https://github.com/NousResearch/hermes-agent/releases/tag/v2026.7.20 — the current latest release, confirming rulesync's compatibility baseline is still accurate.
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/mcp-config-reference.md — the per-server key list including ssl_verify and skip_preflight (gap 1).
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/mcp.md#mcp-sampling-support — the sampling mapping (gap 1).
• https://github.com/NousResearch/hermes-agent/blob/main/tools/delegate_tool.py — the current delegate_task signature and the explicit note that the model has no toolsets argument (gap 2).
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/delegation.md — the documented contract change shipped in v0.19.0 (gap 2).
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/skills.md#external-skill-directories — skills.external_dirs (gap 3).
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/tools-reference.md — the file toolset contents, used to confirm the ignore plugin still guards the right tools.

[dyoshikawa]

Gaps 1 and 2 are fixed by #2451 (merged). Gap 3 stays open here.

Fixed

• Gap 1. copyHermesAdvancedFields now carries ssl_verify (true/false or a PEM CA-bundle path), skip_preflight, and the sampling mapping (cloned as an opaque object with prototype-pollution keys stripped, so new upstream sub-keys keep working) in both directions — authorable from the canonical config, and no longer destroyed on regenerate on a rulesync-managed server. Covered by a new test plus the extended Follow up Hermes Agent upstream updates: MCP advanced per-server fields (auth/oauth, mTLS, connect_timeout) dropped on export #2236 round-trip test.
• Gap 2. The generated subagent and command plugins no longer pass toolsets to delegate_task, and the emitted .hermes/rulesync/subagents/*.json spec no longer advertises one. Verified against upstream tools/delegate_tool.py (the model has no toolsets argument; a subagent inherits the parent's toolsets). Both generated plugins were compiled with py_compile during review.

Still open — gap 3 (project-scope skills via skills.external_dirs). A design decision rather than a regression: emitting <project>/.hermes/skills/ and appending its absolute path to skills.external_dirs in the resolved HERMES_HOME config would mirror the project-plugin activation flow and earn skills a project-scope ✅. Writing a project-dependent absolute path into the shared global config has retraction/staleness implications (a moved or deleted project leaves a dangling entry), so it deserves its own decision.

Review notes (accepted as-is): the sampling sanitize is top-level only — verified inert end-to-end (values are only ever serialized, never key-merged); ssl_verify: false passes through without a warning, consistent with the adapter carrying user config faithfully.

[nx107]

RuleSync #2414 — Project-Scoped Hermes Skills Design Proposal

Status: Draft only — not posted

Author account if approved: nx107

I investigated the remaining Gap 3 in #2414 locally and built a proof of concept around skills.external_dirs. The initial design confirmed that project-scoped Hermes skills are feasible, but an independent review exposed two ownership/concurrency requirements that should be agreed before a production PR.

Proposed layout

Instead of generating into the user's native project skill namespace:

<project>/.hermes/skills

I propose a RuleSync-owned project directory:

<project>/.hermes/rulesync/skills

RuleSync would register that absolute directory in the resolved Hermes profile's skills.external_dirs.

This avoids overwriting or deleting manually authored skills under .hermes/skills, while keeping generated artifacts local to the project.

Registration ownership

RuleSync would maintain a versioned sidecar under the resolved HERMES_HOME:

<HERMES_HOME>/rulesync/project-skills.yaml

The sidecar would record only external-dir entries added by RuleSync.

Proposed rules:

1. Preserve unrelated config.yaml keys and user-managed skills settings.
2. Never claim an exact external_dirs entry that already existed without RuleSync ownership evidence.
3. Retract only entries recorded as RuleSync-owned.
4. Preserve multiple projects simultaneously.
5. Opportunistically prune a missing RuleSync-owned project path.
6. Treat manual removal from config.yaml as ownership relinquishment rather than silently restoring it.
7. Store and accept only normalized absolute paths in the ownership sidecar.
8. Preserve the user's string/list representation when the semantic value is unchanged.
9. Make --delete retract only the current project's registration and RuleSync-owned generated skill directories.

Shared config concurrency

A local concurrent reproduction showed that two project activations using an unlocked read-modify-write can lose one registration. Atomic replacement of one file alone is insufficient because the transaction covers both config.yaml and the ownership sidecar, and other Hermes feature writers also update the same config.yaml.

My proposed fix is a reusable transaction lock keyed by the resolved Hermes config.yaml, shared by:

• the shared-config gateway;
• project-plugin activation;
• project-skill activation.

The lock would cover re-read → validate → reconcile → write, with atomic temp-file replacement for each file. The conservative write order would remain config first, ownership sidecar second, so interruption may leak a stale registration but cannot accidentally grant deletion ownership.

Suggested implementation split

To keep review scope manageable, I suggest two PRs if you agree with the direction:

1. Add the reusable Hermes shared-config transaction/locking foundation and concurrency regressions.
2. Add project-scoped Hermes skills using the RuleSync-owned project directory, ownership sidecar, documentation, and deletion tests.

Planned regressions include:

• two simultaneous projects preserve both registrations and unrelated config keys;
• manually authored .hermes/skills/* survive normal generation and --delete;
• a same-name user skill is never overwritten or claimed;
• only RuleSync-owned project registrations retract;
• sequential activation is idempotent;
• string-form external_dirs remains byte-stable on semantic no-op;
• invalid/relative ownership records fail closed;
• custom HERMES_HOME, dry-run, multiple output roots, moved projects, and deletion are covered.

Would the RuleSync-owned project directory plus shared transaction-lock approach fit the intended design for Gap 3? If so, I can refine the local prototype into the split above and submit the locking foundation first.

[dyoshikawa]

Upstream update (re-check on 2026-08-06)

Newly found releases / changes

The premise "no release newer than v0.19.0" no longer holds — two releases have shipped:

• v2026.7.30 — Hermes Agent v0.19.1 (2026-07-30) — infrastructure patch tag; release notes defer curation to v0.20.0. No schema changes. https://github.com/NousResearch/hermes-agent/releases/tag/v2026.7.30
• v2026.8.3 — Hermes Agent v0.20.0 "The Herald Release" (2026-08-03). https://github.com/NousResearch/hermes-agent/releases/tag/v2026.8.3

Method note: schema changes below were isolated by diffing the upstream docs tree between tags v2026.7.20..v2026.8.3 and then verified empirically against a temp HERMES_HOME profile.

Additional or changed gaps

1. hooks (highest severity) — the new v0.20.0 hooks.outbound: webhook registry is silently destroyed on every generate. Outbound webhooks (PR #69406; hooks docs, "Outbound Webhooks" section) are configured as an outbound: list nested inside the same hooks: mapping rulesync owns: entries carry name, url, events, secret_env, matcher, timeout. shared-config-gateway.ts declares hooks: { kind: "replace-owned-keys", ownedKeys: ["hooks"] }, replacing the entire mapping. Verified: a profile with a hooks.outbound target plus a shell hook came back as nothing but the generated hook — outbound gone, no warning. Unlike native event keys (re-declarable via the hermesagent.hooks override), outbound is not a hook event and has no migration path — pure silent config loss. Urgent fix: narrow the hermesagent hooks ownership to the native VALID_HOOKS event keys so sibling keys survive; modelling outbound webhooks as a first-class surface can follow separately.
2. mcp — three new v0.20.0 per-server keys unmodelled, same data-loss shape as this issue's (fixed) gap 1: transport: sse (now a real upstream key — hermesagent-mcp.ts still strips transport as a "canonical-only alias", so a canonical type: "sse" server is emitted as a bare url: entry and Hermes connects over Streamable HTTP), keepalive_interval (default 180, floor 5), and elicitation: { enabled, timeout }. All three are wiped from rulesync-managed servers on regenerate. Fix: extend copyHermesAdvancedFields and map canonical SSE onto transport: sse. Source: https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference
3. compat metadata — docs/reference/supported-tools.md and the hermesagent-hooks.ts runtime warning still pin validation to v0.19.0; re-pin to v0.20.0 alongside the fixes.

Checked and clean at v0.20.0

Rules chain unchanged (byte-identical between tags); still no .hermesignore (an earlier fetch summary claiming one was a summarization artifact — zero occurrences in the docs tree); the mcp_<server>_<tool> → mcp__server__tool rename does not leak into the permissions adapter; the new managed scope (/etc/hermes, HERMES_MANAGED_DIR) is enforced via filesystem permissions and judged out of rulesync's scope; HERMES_HOME semantics unchanged.

References

• https://github.com/NousResearch/hermes-agent/releases/tag/v2026.8.3 — v0.20.0 release
• https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks — outbound webhooks section
• https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference — new per-server keys

[dyoshikawa]

PR #2610 landed the two v0.20.0 gaps from the 2026-08-06 re-check comment.

hooks.outbound is no longer destroyed. The hooks writer recomputes the hooks: mapping instead of replacing it: a key is treated as rulesync's only when it is a documented native event, or when its value looks like a hook list (a non-empty array of entries carrying a string command). Everything rulesync writes matches that; an outbound entry carries url/events and no command, so it survives. Both directions use that one predicate, so import cannot read the registry as a hook and write it back in the wrong shape. Event keys are still replaced wholesale, including the undocumented event names rulesync emits from the hermesagent.hooks override for forward compatibility — review caught that an earlier cut of the fix had made those unretractable.

The shared-file no-data-loss contract now seeds hooks.outbound in the Hermes config and tracks it across the whole write order. A top-level sentinel alone is what let this class of bug ship, so that is the part that actually protects the fix against a future writer.

The three new per-server MCP keys round-trip. keepalive_interval and elicitation go through copyHermesAdvancedFields, and a canonical sse server is now written as Hermes's own transport: sse and imported back as type: "sse" — without it Hermes connected to the server over Streamable HTTP. Streamable HTTP stays implicit, since sse is the only value upstream reads.

Compat metadata re-pinned from v0.19.0 to v0.20.0 in docs/reference/supported-tools.md and the hooks runtime warning.

Modelling outbound webhooks as a first-class authoring surface remains out of scope — this only stops rulesync from deleting them. The issue's other design items, including the shared-config transaction lock and the project-scoped skills discussion, are untouched, so this stays open.

[dyoshikawa]

Upstream update (re-check on 2026-08-08)

Newly found releases / changes

• No release newer than v0.20.0 (v2026.8.3, 2026-08-03) exists — the compatibility pin needs no change. All three gaps below are unreleased upstream main, committed 2026-08-07 (after the last re-check), found by diffing the website/docs tree at v2026.8.3...main:
  • Commit 1dee7340 — "Inspired by Cursor: fail-closed hook semantics + exit-code-2 blocking".
  • Commit c8369e37 — "feat(mcp): trust-tier gating for write-capable MCP tools via readOnlyHint".
  • Commit 9fad45fc — per-server MCP identity header.

Additional or changed gaps

1. hooks — fail_closed unauthorable, and rulesync's canonical model already carries the exact matching field (highest severity). Upstream shell-hook entries now take fail_closed: <bool> (default false, pre_tool_call only; camelCase failClosed accepted explicitly for Cursor/Claude Code compat) — a failing hook (crash, timeout, non-executable, non-JSON) blocks the tool call; same commit adds exit-code-2 blocking. Docs: hooks.md ("Exit code 2 = block", "Fail-open vs fail-closed"). rulesync (global): src/features/hooks/hermesagent-hooks.ts builds entries from exactly command/matcher/timeout, so a canonical failClosed: true (already in HookDefinition, src/types/hooks.ts) is silently dropped — a security gate the author believes fails closed is emitted fail-open, with no warning. Follow-up: map failClosed → fail_closed on export, accept both spellings on import, and optionally warn when set on an event other than pre_tool_call (mirroring the existing matcher-on-wrong-event warning).
2. mcp — per-server trust tier dropped and clobbered. mcp_servers.<name>.trust: full (default) or untrusted (every write-capable tool call — no readOnlyHint: true — requires approval; unrecognized values treated as untrusted). Docs: mcp-config-reference.md. Absent from copyHermesAdvancedFields in src/features/mcp/hermesagent-mcp.ts, so it is unauthorable and destroyed on regenerate — and losing trust: untrusted silently re-grants unapproved writes, a security downgrade.
3. mcp — per-server identity_header mapping dropped and clobbered. {name, value_from: static|profile, value} sends a per-user identity header to remote HTTP/SSE servers (value_from: profile resolves the active profile at connect time; ignored with a warning on stdio). Docs: mcp.md ("Per-user identity header"). Same copyHermesAdvancedFields omission. Follow-up: carry it as a deep-cloned object with prototype-pollution keys stripped, exactly the treatment sampling/elicitation already get. Gaps 2 and 3 are one small change to one function — naturally a single PR.

Verified non-gaps

• The new "Directory Chain" context-file merging (commit 2e2fcc09) does not apply to .hermes.md — one project context type per session, first match wins; the Follow up Hermes Agent upstream updates: nested subdirectory context files (progressive discovery) #2214 folding decision still holds.
• "Portable Agent Plugins v1" support in the plugin docs is a purely additive compatibility adapter; native plugin.yaml + register(ctx) (what rulesync emits) is unchanged — no re-validation needed.
• MCP context variables (${userHome}, ${workspaceFolder}, …) interpolate at runtime; rulesync passes args/env through verbatim, so they already work.
• delegate_task structured-output schema (d6ee58b5) has no doc coverage yet — nothing stable to model.

References

• https://github.com/NousResearch/hermes-agent/releases/tag/v2026.8.3 — still the latest release; everything above is main-only.
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/hooks.md — fail-closed semantics (gap 1).
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/mcp-config-reference.md — trust and identity_header per-server keys (gaps 2–3).
• https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/mcp.md — identity-header behavior (gap 3).