You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@casbin.apache.org by hs...@apache.org on 2026/08/22 07:58:42 UTC

(casbin-gateway) 01/01: feat: support Hermes Agent monitoring (#221)

This is an automated email from the ASF dual-hosted git repository.

hsluoyz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/casbin-gateway.git

commit 6bd57c3c7bcbe0c70d4cc441d97083d88ed49e4e
Author: Paperlz <23...@qq.com>
AuthorDate: Sat Aug 22 15:44:27 2026 +0800

    feat: support Hermes Agent monitoring (#221)
---
 agentpatch/hermes_agent.go       | 341 +++++++++++++++++++++++
 agentpatch/hermes_config.go      | 589 +++++++++++++++++++++++++++++++++++++++
 agentpatch/hermes_config_test.go |  84 ++++++
 agentpatch/hermes_observer.py    | 534 +++++++++++++++++++++++++++++++++++
 agentpatch/hermes_plugin.yaml    |  18 ++
 go.mod                           |   1 +
 6 files changed, 1567 insertions(+)

diff --git a/agentpatch/hermes_agent.go b/agentpatch/hermes_agent.go
new file mode 100644
index 0000000..167fce1
--- /dev/null
+++ b/agentpatch/hermes_agent.go
@@ -0,0 +1,341 @@
+// Copyright 2026 The casbin Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agentpatch
+
+import (
+	"bytes"
+	_ "embed"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/apache/casbin-gateway/agenthome"
+	"github.com/apache/casbin-gateway/agentmonitor"
+	"github.com/apache/casbin-gateway/internal/hermes"
+)
+
+const (
+	hermesPluginName      = gatewayEntryName
+	hermesConfigSchema    = 1
+	minHermesAgentVersion = "0.19.0"
+)
+
+//go:embed hermes_observer.py
+var hermesObserver []byte
+
+//go:embed hermes_plugin.yaml
+var hermesPluginManifest []byte
+
+// hermesPluginVersion comes from the manifest so the two never drift apart.
+var hermesPluginVersion = hermesManifestVersion()
+
+func hermesManifestVersion() string {
+	var manifest struct {
+		Version string `yaml:"version"`
+	}
+	if err := yaml.Unmarshal(hermesPluginManifest, &manifest); err != nil {
+		return ""
+	}
+	return manifest.Version
+}
+
+type hermesPatcher struct{}
+
+type hermesLayout struct {
+	home       string
+	configPath string
+	pluginDir  string
+}
+
+type hermesObserverConfig struct {
+	SchemaVersion     int    `json:"schemaVersion"`
+	Owner             string `json:"owner"`
+	PluginVersion     string `json:"pluginVersion"`
+	RecordsURL        string `json:"recordsUrl"`
+	AgentPath         string `json:"agentPath"`
+	User              string `json:"user"`
+	IngestToken       string `json:"ingestToken"`
+	IngestTokenHeader string `json:"ingestTokenHeader"`
+}
+
+func init() {
+	register(hermesPatcher{})
+}
+
+func (hermesPatcher) AgentId() string { return hermes.AgentID }
+
+func (hermesPatcher) Supported() bool { return true }
+
+func (p hermesPatcher) Patch(target Target) error {
+	layout, err := p.validateTarget(target)
+	if err != nil {
+		return err
+	}
+	applied := IsApplied(target)
+	if info, statErr := os.Stat(layout.pluginDir); statErr == nil {
+		if !info.IsDir() {
+			return fmt.Errorf("%s exists and is not a directory", layout.pluginDir)
+		}
+		if !applied {
+			return fmt.Errorf("%s already exists and is not owned by this Gateway patch state", layout.pluginDir)
+		}
+		if hermesPluginForeign(layout.pluginDir) {
+			return fmt.Errorf("%s no longer contains a Gateway-owned observer; refusing to refresh it", layout.pluginDir)
+		}
+	} else if !os.IsNotExist(statErr) {
+		return statErr
+	}
+
+	token, err := IssueIngestToken(target)
+	if err != nil {
+		return err
+	}
+	observerConfig, err := renderHermesObserverConfig(target, token)
+	if err != nil {
+		return errors.Join(err, RevokeIngestToken(target))
+	}
+	pluginFiles := []struct {
+		name string
+		data []byte
+		mode os.FileMode
+	}{
+		{"plugin.yaml", hermesPluginManifest, 0o644},
+		{"__init__.py", hermesObserver, 0o644},
+		{"gateway.json", observerConfig, 0o600},
+	}
+
+	if err := Apply(target, func(changes *ChangeSet) error {
+		if err := changes.MkdirAll(layout.pluginDir); err != nil {
+			return err
+		}
+		for _, file := range pluginFiles {
+			path := filepath.Join(layout.pluginDir, file.name)
+			if err := changes.WriteFile(path, file.data, file.mode); err != nil {
+				return err
+			}
+		}
+		return nil
+	}); err != nil {
+		return errors.Join(err, RevokeIngestToken(target))
+	}
+
+	// config.yaml stays out of the backup journal: Unpatch deletes the one
+	// entry Gateway added rather than restore a snapshot of the user's file.
+	if err := writeHermesPluginMembership(layout.configPath, true); err != nil {
+		return errors.Join(err, Revert(target), RevokeIngestToken(target))
+	}
+	return nil
+}
+
+func (p hermesPatcher) Unpatch(target Target) error {
+	// Revert works from the saved paths, so a home directory that no longer
+	// resolves still gets its plugin removed.
+	var membershipErr error
+	if layout, err := p.layoutOf(target); err == nil {
+		membershipErr = writeHermesPluginMembership(layout.configPath, false)
+	}
+	return errors.Join(membershipErr, Revert(target), RevokeIngestToken(target))
+}
+
+// PatchNotice is the copy the agents table shows before and after the button,
+// so the Web UI does not need a branch of its own for how Hermes loads plugins.
+func (hermesPatcher) PatchNotice(patched bool) (string, string) {
+	if patched {
+		return "Removes the behaviour observer from the default Hermes profile and drops its entry from plugins.enabled. Nothing else in config.yaml changes.",
+			"Restart running Hermes processes to unload it."
+	}
+	return "Installs a behaviour observer with redacted tool inputs in the default Hermes profile and adds it to plugins.enabled. Named profiles are left alone.",
+		"Restart running Hermes processes to load it."
+}
+
+func (p hermesPatcher) Status(target Target) (Status, error) {
+	layout, err := p.layoutOf(target)
+	if err != nil {
+		return Status{}, err
+	}
+	config, owned, err := readHermesObserverConfig(layout.pluginDir)
+	if err != nil {
+		return Status{}, err
+	}
+	if !owned {
+		if _, statErr := os.Stat(layout.pluginDir); statErr == nil {
+			return Status{Detail: "plugin directory exists but is not owned by Gateway"}, nil
+		}
+		return Status{Detail: "not patched"}, nil
+	}
+
+	issuedAgent, tokenValid := ValidateIngestToken(config.IngestToken)
+	if !tokenValid || !strings.EqualFold(issuedAgent, target.AgentId) {
+		return Status{Detail: "observer files are stale or incomplete; Patch again to refresh them"}, nil
+	}
+	expectedConfig, err := renderHermesObserverConfig(target, config.IngestToken)
+	if err != nil {
+		return Status{}, err
+	}
+	expectedFiles := map[string][]byte{
+		"plugin.yaml": hermesPluginManifest, "__init__.py": hermesObserver,
+		"gateway.json": expectedConfig,
+	}
+	for name, expected := range expectedFiles {
+		actual, readErr := os.ReadFile(filepath.Join(layout.pluginDir, name))
+		if readErr != nil || !bytes.Equal(actual, expected) {
+			return Status{Detail: "observer files are stale or incomplete; Patch again to refresh them"}, nil
+		}
+	}
+	enabled, disabled, err := hermesPluginMembership(layout.configPath)
+	if err != nil {
+		return Status{}, err
+	}
+	if !enabled || disabled {
+		return Status{Detail: "observer is installed but not enabled in config.yaml; Patch again to repair it"}, nil
+	}
+	if !IsApplied(target) {
+		return Status{
+			Patched: true,
+			Detail:  "observer is enabled outside this Gateway patch state; an automatic Unpatch is unsafe",
+		}, nil
+	}
+	return Status{
+		Patched: true,
+		Detail: fmt.Sprintf(
+			"behaviour observer installed in %s; start a new Hermes process or restart a running one to load it",
+			layout.home,
+		),
+	}, nil
+}
+
+func (p hermesPatcher) validateTarget(target Target) (hermesLayout, error) {
+	layout, err := p.layoutOf(target)
+	if err != nil {
+		return hermesLayout{}, err
+	}
+	roots := []string{filepath.Join(layout.home, hermes.ProjectDir)}
+	if runtime.GOOS == "linux" && filepath.Clean(target.Path) == "/usr/local/bin/hermes" {
+		roots = append(roots, "/usr/local/lib/hermes-agent", "/root/.hermes/hermes-agent")
+	}
+	project, err := hermes.InspectLauncher(target.Path, roots...)
+	if err != nil {
+		return hermesLayout{}, err
+	}
+	// A hook Hermes does not know simply never fires, so the version gate is
+	// the only compatibility check the observer needs.
+	if !hermes.VersionAtLeast(project.Version, minHermesAgentVersion) {
+		return hermesLayout{}, fmt.Errorf(
+			"Hermes Agent %s is incompatible; upgrade to %s or later",
+			project.Version, minHermesAgentVersion,
+		)
+	}
+	return layout, nil
+}
+
+func (hermesPatcher) layoutOf(target Target) (hermesLayout, error) {
+	home, err := agenthome.Resolve(target.Owner)
+	if err != nil {
+		return hermesLayout{}, err
+	}
+	hermesHome := filepath.Join(home, ".hermes")
+	if runtime.GOOS == "windows" {
+		hermesHome = filepath.Join(home, "AppData", "Local", "hermes")
+		if isProcessHome(home) {
+			if local := os.Getenv("LOCALAPPDATA"); local != "" {
+				hermesHome = filepath.Join(local, "hermes")
+			}
+		}
+	}
+	if configured := os.Getenv("HERMES_HOME"); configured != "" && isProcessHome(home) {
+		hermesHome = configured
+	}
+	return hermesLayout{
+		home:       hermesHome,
+		configPath: filepath.Join(hermesHome, "config.yaml"),
+		pluginDir:  filepath.Join(hermesHome, "plugins", hermesPluginName),
+	}, nil
+}
+
+func renderHermesObserverConfig(target Target, token string) ([]byte, error) {
+	url, err := recordsURL()
+	if err != nil {
+		return nil, err
+	}
+	data, err := json.MarshalIndent(hermesObserverConfig{
+		SchemaVersion:     hermesConfigSchema,
+		Owner:             "casbin-gateway",
+		PluginVersion:     hermesPluginVersion,
+		RecordsURL:        url,
+		AgentPath:         target.Path,
+		User:              target.Owner,
+		IngestToken:       token,
+		IngestTokenHeader: agentmonitor.IngestTokenHeader,
+	}, "", "  ")
+	if err != nil {
+		return nil, err
+	}
+	return append(data, '\n'), nil
+}
+
+// hermesPluginForeign reports a plugin directory holding somebody else's
+// gateway.json. A missing, unreadable or stale-schema file is not evidence of
+// that, so a refresh can still repair it.
+func hermesPluginForeign(pluginDir string) bool {
+	data, err := os.ReadFile(filepath.Join(pluginDir, "gateway.json"))
+	if err != nil {
+		return false
+	}
+	var config hermesObserverConfig
+	if json.Unmarshal(data, &config) != nil {
+		return false
+	}
+	return config.Owner != "casbin-gateway"
+}
+
+func readHermesObserverConfig(pluginDir string) (hermesObserverConfig, bool, error) {
+	data, err := os.ReadFile(filepath.Join(pluginDir, "gateway.json"))
+	if os.IsNotExist(err) {
+		return hermesObserverConfig{}, false, nil
+	}
+	if err != nil {
+		return hermesObserverConfig{}, false, err
+	}
+	var config hermesObserverConfig
+	if err := json.Unmarshal(data, &config); err != nil {
+		return hermesObserverConfig{}, false, nil
+	}
+	return config, config.Owner == "casbin-gateway" &&
+		config.SchemaVersion == hermesConfigSchema, nil
+}
+
+func isProcessHome(home string) bool {
+	current, err := os.UserHomeDir()
+	if err != nil {
+		return false
+	}
+	left, right := filepath.Clean(home), filepath.Clean(current)
+	if resolved, err := filepath.EvalSymlinks(left); err == nil {
+		left = resolved
+	}
+	if resolved, err := filepath.EvalSymlinks(right); err == nil {
+		right = resolved
+	}
+	if runtime.GOOS == "windows" {
+		return strings.EqualFold(left, right)
+	}
+	return left == right
+}
diff --git a/agentpatch/hermes_config.go b/agentpatch/hermes_config.go
new file mode 100644
index 0000000..693dc40
--- /dev/null
+++ b/agentpatch/hermes_config.go
@@ -0,0 +1,589 @@
+// Copyright 2026 The casbin Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agentpatch
+
+// config.yaml is the user's file, so the observer is enabled by splicing one
+// list item into the text rather than round-tripping the document through a
+// YAML marshaller, which would rewrite every line. Reads still go through the
+// real parser, and every edit is re-parsed before it is committed.
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// writeHermesPluginMembership adds the observer to plugins.enabled, or removes
+// it, editing configPath in place. An existing config keeps its current mode.
+func writeHermesPluginMembership(configPath string, enabled bool) error {
+	data, err := os.ReadFile(configPath)
+	missing := os.IsNotExist(err)
+	if err != nil && !missing {
+		return err
+	}
+	if missing && !enabled {
+		return nil
+	}
+
+	updated, changed, err := setHermesPluginMembership(data, enabled)
+	if err != nil {
+		return fmt.Errorf("update %s: %w", configPath, err)
+	}
+	if !changed {
+		return nil
+	}
+	if err := verifyHermesPluginMembership(updated, enabled); err != nil {
+		return fmt.Errorf("update %s: %w", configPath, err)
+	}
+
+	// Removing the observer can empty a config.yaml that only ever held the
+	// block Patch appended, so Unpatch takes that file away with it.
+	if !enabled && len(bytes.TrimSpace(updated)) == 0 {
+		if err := os.Remove(configPath); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+		return nil
+	}
+	return writeFileAtomic(configPath, updated, 0o600)
+}
+
+// writeFileAtomic replaces path through a temporary file in the same directory,
+// so an interrupted write can never truncate a config Gateway does not back up.
+func writeFileAtomic(path string, data []byte, perm os.FileMode) error {
+	if info, err := os.Stat(path); err == nil {
+		perm = info.Mode().Perm()
+	} else if !os.IsNotExist(err) {
+		return err
+	}
+	temp, err := os.CreateTemp(filepath.Dir(path), "."+filepath.Base(path)+".gateway-*")
+	if err != nil {
+		return err
+	}
+	name := temp.Name()
+	_, err = temp.Write(data)
+	if err == nil {
+		err = temp.Sync()
+	}
+	if closeErr := temp.Close(); err == nil {
+		err = closeErr
+	}
+	if err == nil {
+		err = os.Chmod(name, perm)
+	}
+	if err == nil {
+		err = os.Rename(name, path)
+	}
+	if err != nil {
+		_ = os.Remove(name)
+	}
+	return err
+}
+
+// verifyHermesPluginMembership re-reads an edited document with the YAML parser
+// and checks the observer ended up where the edit intended. It is the guard
+// that keeps a line edit from writing a document Hermes would read differently.
+func verifyHermesPluginMembership(data []byte, enabled bool) error {
+	listed, blocked, err := hermesPluginMembershipOf(data)
+	if err != nil {
+		return err
+	}
+	if listed != enabled || (enabled && blocked) {
+		return errors.New("the edited plugins list does not read back as expected")
+	}
+	return nil
+}
+
+// hermesPluginEdit is one list membership the observer needs in config.yaml.
+type hermesPluginEdit struct {
+	key  string
+	want bool
+}
+
+// setHermesPluginMembership returns config.yaml with the observer added to or
+// removed from plugins.enabled. Enabling also drops it from plugins.disabled,
+// which Hermes treats as a deny list that wins over plugins.enabled. Disabling
+// leaves plugins.disabled alone: an entry there is the user's, never ours.
+func setHermesPluginMembership(data []byte, enabled bool) ([]byte, bool, error) {
+	edits := []hermesPluginEdit{{key: "enabled", want: enabled}}
+	if enabled {
+		edits = append(edits, hermesPluginEdit{key: "disabled", want: false})
+	}
+
+	current, changed := data, false
+	for _, edit := range edits {
+		next, stepChanged, err := setHermesPluginListMember(current, edit.key, edit.want)
+		if err != nil {
+			return nil, false, err
+		}
+		if stepChanged {
+			current, changed = next, true
+		}
+	}
+	return current, changed, nil
+}
+
+// setHermesPluginListMember adds or removes the observer in plugins.<key>. The
+// document is re-read for each edit so one edit's line numbers never depend on
+// another's.
+func setHermesPluginListMember(data []byte, key string, want bool) ([]byte, bool, error) {
+	document := newYAMLLines(data)
+
+	plugins := document.findMappingKey("plugins", 0, 0, len(document.lines))
+	if plugins < 0 {
+		if !want {
+			return data, false, nil
+		}
+		document.appendBlock("plugins:", "  "+key+":", "    - "+hermesPluginName)
+		return document.bytes(), true, nil
+	}
+	if _, value, _ := yamlMappingKey(document.lines[plugins], 0); value != "" {
+		return nil, false, fmt.Errorf("plugins must be a block mapping, found %q", value)
+	}
+
+	pluginsEnd := document.blockEnd(0, plugins+1)
+	childIndent := document.childIndent(plugins, 0, pluginsEnd)
+	keyLine := document.findMappingKey(key, childIndent, plugins+1, pluginsEnd)
+	if keyLine < 0 {
+		if !want {
+			return data, false, nil
+		}
+		indent := strings.Repeat(" ", childIndent)
+		document.insert(document.lastContent(plugins+1, pluginsEnd)+1,
+			indent+key+":", indent+"  - "+hermesPluginName)
+		return document.bytes(), true, nil
+	}
+	if _, value, _ := yamlMappingKey(document.lines[keyLine], childIndent); value != "" {
+		return setHermesPluginFlowMember(document, keyLine, key, want)
+	}
+
+	items := document.sequenceItems(keyLine, childIndent)
+	if len(items) == 0 && document.lastContent(keyLine+1, document.blockEnd(childIndent, keyLine+1)) > keyLine {
+		return nil, false, fmt.Errorf("plugins.%s must be a list", key)
+	}
+	existing := -1
+	for _, item := range items {
+		if value, _, _ := yamlSequenceItem(document.lines[item]); value == hermesPluginName {
+			existing = item
+			break
+		}
+	}
+
+	if !want {
+		if existing < 0 {
+			return data, false, nil
+		}
+		document.remove(existing)
+		if key == "enabled" {
+			document.pruneEmptyBlock(plugins, keyLine, childIndent)
+		}
+		return document.bytes(), true, nil
+	}
+	if existing >= 0 {
+		return data, false, nil
+	}
+	itemIndent, insertAt := childIndent+2, keyLine+1
+	if len(items) > 0 {
+		last := items[len(items)-1]
+		_, itemIndent, _ = yamlSequenceItem(document.lines[last])
+		// An item may span more than its first line, so append after the last
+		// line that still belongs to it rather than after its opening dash.
+		insertAt = document.lastContent(last, document.blockEnd(itemIndent, last+1)) + 1
+	}
+	document.insert(insertAt, strings.Repeat(" ", itemIndent)+"- "+hermesPluginName)
+	return document.bytes(), true, nil
+}
+
+// setHermesPluginFlowMember edits an inline "key: [a, b]" list without parsing
+// or rewriting its existing values. Patch appends its own scalar at the end;
+// Unpatch removes only that exact trailing scalar. If an operator moves or
+// rewrites the entry, Unpatch reports the conflict instead of risking the rest
+// of the flow sequence.
+func setHermesPluginFlowMember(document *yamlLines, keyLine int, key string, want bool) ([]byte, bool, error) {
+	line := document.lines[keyLine]
+	open := strings.IndexByte(line, '[')
+	end := strings.LastIndexByte(line, ']')
+	if open < 0 || end < open {
+		return nil, false, fmt.Errorf("plugins.%s must be a list", key)
+	}
+
+	enabled, disabled, err := hermesPluginMembershipOf(document.bytes())
+	if err != nil {
+		return nil, false, err
+	}
+	found := enabled
+	if key == "disabled" {
+		found = disabled
+	}
+	if found == want {
+		return document.bytes(), false, nil
+	}
+
+	content := line[open+1 : end]
+	core := strings.TrimRight(content, " \t")
+	trailing := content[len(core):]
+	if want {
+		separator := ""
+		if strings.TrimSpace(core) != "" {
+			separator = ", "
+		}
+		document.lines[keyLine] = line[:open+1] + core + separator + hermesPluginName + trailing + line[end:]
+		return document.bytes(), true, nil
+	}
+
+	if strings.TrimSpace(core) == hermesPluginName {
+		document.lines[keyLine] = line[:open+1] + trailing + line[end:]
+		return document.bytes(), true, nil
+	}
+	separator := strings.LastIndexByte(core, ',')
+	if separator < 0 || strings.TrimSpace(core[separator+1:]) != hermesPluginName {
+		return nil, false, fmt.Errorf("plugins.%s Gateway entry is not the final flow-list item", key)
+	}
+	document.lines[keyLine] = line[:open+1] + core[:separator] + trailing + line[end:]
+	return document.bytes(), true, nil
+}
+
+// yamlLines is a line-oriented view of a YAML document. It understands just
+// enough of the syntax to find a mapping key and the block sequence under it;
+// every shape beyond that it declines to touch, leaving the caller to report a
+// config it should not be editing blind.
+type yamlLines struct {
+	lines []string
+	// carriageReturn is what a line Gateway writes ends with. Existing lines
+	// keep whichever ending they already had, so a file with mixed endings is
+	// never normalized behind the user's back.
+	carriageReturn string
+}
+
+func newYAMLLines(data []byte) *yamlLines {
+	carriageReturn := ""
+	if bytes.Contains(data, []byte("\r\n")) {
+		carriageReturn = "\r"
+	}
+	return &yamlLines{lines: strings.Split(string(data), "\n"), carriageReturn: carriageReturn}
+}
+
+func (y *yamlLines) bytes() []byte {
+	return []byte(strings.Join(y.lines, "\n"))
+}
+
+func (y *yamlLines) insert(at int, lines ...string) {
+	written := make([]string, len(lines))
+	for index, line := range lines {
+		written[index] = line + y.carriageReturn
+	}
+	y.lines = append(y.lines[:at:at], append(written, y.lines[at:]...)...)
+}
+
+func (y *yamlLines) remove(at int) {
+	y.lines = append(y.lines[:at:at], y.lines[at+1:]...)
+}
+
+// pruneEmptyBlock drops a plugins.<key> left holding nothing by the removal of
+// Gateway's entry, then plugins itself, then the blank line that separated an
+// appended block from the content above it. Comments count as content, so a
+// block the user annotated is kept.
+func (y *yamlLines) pruneEmptyBlock(pluginsLine, keyLine, childIndent int) {
+	// Items may sit at the key's own indent, where the block under it looks
+	// empty, so the sequence decides rather than the indentation.
+	if len(y.sequenceItems(keyLine, childIndent)) > 0 {
+		return
+	}
+	if y.hasText(keyLine+1, y.blockEnd(childIndent, keyLine+1)) {
+		return
+	}
+	y.remove(keyLine)
+	if y.hasText(pluginsLine+1, y.blockEnd(0, pluginsLine+1)) {
+		return
+	}
+	y.remove(pluginsLine)
+	if pluginsLine > 0 && strings.TrimSpace(y.lines[pluginsLine-1]) == "" &&
+		!y.hasText(pluginsLine, len(y.lines)) {
+		y.remove(pluginsLine - 1)
+	}
+}
+
+func (y *yamlLines) hasText(start, end int) bool {
+	for index := start; index < end && index < len(y.lines); index++ {
+		if strings.TrimSpace(y.lines[index]) != "" {
+			return true
+		}
+	}
+	return false
+}
+
+// appendBlock adds lines at the end of the document, keeping the file's final
+// newline and separating the new block from whatever content came before it.
+func (y *yamlLines) appendBlock(lines ...string) {
+	at := len(y.lines)
+	if at > 0 && y.lines[at-1] == "" {
+		// The empty last element stands for the file's final newline.
+		at--
+	} else {
+		y.lines = append(y.lines, "")
+	}
+	if at > 0 && strings.TrimSpace(y.lines[at-1]) != "" {
+		lines = append([]string{""}, lines...)
+	}
+	y.insert(at, lines...)
+}
+
+// findMappingKey returns the line index of key at indent inside [start, end),
+// or -1. The scan stops at the first content line shallower than indent, which
+// is where the surrounding block ends.
+func (y *yamlLines) findMappingKey(key string, indent, start, end int) int {
+	for index := start; index < end && index < len(y.lines); index++ {
+		current, ok := yamlContentIndent(y.lines[index])
+		if !ok || current > indent {
+			continue
+		}
+		if current < indent {
+			return -1
+		}
+		if name, _, ok := yamlMappingKey(y.lines[index], indent); ok && name == key {
+			return index
+		}
+	}
+	return -1
+}
+
+// blockEnd returns the first line index at or after start that leaves the block
+// owned by a key at indent.
+func (y *yamlLines) blockEnd(indent, start int) int {
+	for index := start; index < len(y.lines); index++ {
+		if current, ok := yamlContentIndent(y.lines[index]); ok && current <= indent {
+			return index
+		}
+	}
+	return len(y.lines)
+}
+
+// childIndent is the indentation of the first content line inside the block
+// under keyLine, or two past the key's own indent when the block is empty.
+func (y *yamlLines) childIndent(keyLine, indent, end int) int {
+	for index := keyLine + 1; index < end && index < len(y.lines); index++ {
+		if current, ok := yamlContentIndent(y.lines[index]); ok {
+			return current
+		}
+	}
+	return indent + 2
+}
+
+// lastContent is the index of the last content line in [start, end), or
+// start-1 when the range holds none, so callers can insert right after it.
+func (y *yamlLines) lastContent(start, end int) int {
+	last := start - 1
+	for index := start; index < end && index < len(y.lines); index++ {
+		if _, ok := yamlContentIndent(y.lines[index]); ok {
+			last = index
+		}
+	}
+	return last
+}
+
+// sequenceItems returns the line index of every item of the block sequence
+// under the key at keyLine. Items may be indented deeper than their key or, as
+// YAML also allows, sit at the key's own indentation.
+func (y *yamlLines) sequenceItems(keyLine, keyIndent int) []int {
+	var items []int
+	for index := keyLine + 1; index < len(y.lines); index++ {
+		current, ok := yamlContentIndent(y.lines[index])
+		if !ok {
+			continue
+		}
+		if _, itemIndent, isItem := yamlSequenceItem(y.lines[index]); isItem && itemIndent >= keyIndent {
+			items = append(items, index)
+			continue
+		}
+		// Anything deeper is a continuation of the item above it; anything at
+		// or above the key's own indent ends the sequence.
+		if current <= keyIndent {
+			break
+		}
+	}
+	return items
+}
+
+// yamlContentIndent returns the indentation of a line that carries content.
+// Blank lines and whole-line comments belong to whichever block surrounds them,
+// so they report no content and every scan above skips over them.
+func yamlContentIndent(line string) (int, bool) {
+	trimmed := strings.TrimLeft(line, " ")
+	indent := len(line) - len(trimmed)
+	trimmed = strings.TrimRight(trimmed, "\r")
+	if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+		return 0, false
+	}
+	return indent, true
+}
+
+// yamlMappingKey reports the key and the inline value of a "<key>: <value>"
+// line sitting at exactly indent. Only plain unquoted keys are recognized,
+// which covers every key Gateway looks for.
+func yamlMappingKey(line string, indent int) (string, string, bool) {
+	current, ok := yamlContentIndent(line)
+	if !ok || current != indent {
+		return "", "", false
+	}
+	key, value, ok := strings.Cut(line[indent:], ":")
+	if !ok || !isPlainYAMLKey(key) {
+		return "", "", false
+	}
+	return key, yamlInlineValue(value), true
+}
+
+func isPlainYAMLKey(key string) bool {
+	if key == "" {
+		return false
+	}
+	for _, char := range key {
+		switch {
+		case char >= 'a' && char <= 'z', char >= 'A' && char <= 'Z',
+			char >= '0' && char <= '9', char == '_', char == '-', char == '.':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+// yamlInlineValue strips the trailing comment from the value half of a mapping
+// line. A flow sequence ends at its closing bracket; anything else ends where a
+// comment starts.
+func yamlInlineValue(value string) string {
+	value = strings.TrimSpace(value)
+	if strings.HasPrefix(value, "#") {
+		return ""
+	}
+	if strings.HasPrefix(value, "[") {
+		if end := strings.LastIndex(value, "]"); end >= 0 {
+			return value[:end+1]
+		}
+		return value
+	}
+	if comment := strings.Index(value, " #"); comment >= 0 {
+		return strings.TrimSpace(value[:comment])
+	}
+	return value
+}
+
+// yamlSequenceItem reports the scalar of a "- value" line and its indent.
+// Quotes are stripped so a quoted plugin name matches the plain one Gateway
+// writes.
+func yamlSequenceItem(line string) (string, int, bool) {
+	indent, ok := yamlContentIndent(line)
+	if !ok {
+		return "", 0, false
+	}
+	rest := strings.TrimRight(line[indent:], "\r")
+	if rest != "-" && !strings.HasPrefix(rest, "- ") {
+		return "", 0, false
+	}
+	return strings.Trim(yamlInlineValue(rest[1:]), `"'`), indent, true
+}
+
+// hermesPluginMembership reports whether config.yaml lists the observer in
+// plugins.enabled and in plugins.disabled. A missing config lists neither.
+func hermesPluginMembership(configPath string) (bool, bool, error) {
+	data, err := os.ReadFile(configPath)
+	if os.IsNotExist(err) {
+		return false, false, nil
+	}
+	if err != nil {
+		return false, false, err
+	}
+	return hermesPluginMembershipOf(data)
+}
+
+func hermesPluginMembershipOf(data []byte) (bool, bool, error) {
+	root, err := parseYAMLMapping(data)
+	if err != nil {
+		return false, false, err
+	}
+	plugins, ok := mappingValue(root, "plugins")
+	if !ok {
+		return false, false, nil
+	}
+	if plugins.Kind != yaml.MappingNode {
+		return false, false, errors.New("plugins must be a mapping")
+	}
+	enabled, err := pluginSequence(plugins, "enabled")
+	if err != nil {
+		return false, false, err
+	}
+	disabled, err := pluginSequence(plugins, "disabled")
+	if err != nil {
+		return false, false, err
+	}
+	return sequenceContains(enabled, hermesPluginName),
+		sequenceContains(disabled, hermesPluginName), nil
+}
+
+// pluginSequence returns the plugins.<key> list, or nil when the key is absent
+// or empty. Removing the last entry leaves the key behind with nothing under
+// it, which Hermes reads the same way it reads a missing key, so an empty list
+// written that way is not an error here either.
+func pluginSequence(plugins *yaml.Node, key string) (*yaml.Node, error) {
+	value, ok := mappingValue(plugins, key)
+	if !ok || value.Tag == "!!null" {
+		return nil, nil
+	}
+	if value.Kind != yaml.SequenceNode {
+		return nil, fmt.Errorf("plugins.%s must be a sequence", key)
+	}
+	return value, nil
+}
+
+func parseYAMLMapping(data []byte) (*yaml.Node, error) {
+	if len(bytes.TrimSpace(data)) == 0 {
+		return &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}, nil
+	}
+	var document yaml.Node
+	if err := yaml.Unmarshal(data, &document); err != nil {
+		return nil, err
+	}
+	if len(document.Content) != 1 || document.Content[0].Kind != yaml.MappingNode {
+		return nil, errors.New("config root must be a mapping")
+	}
+	return document.Content[0], nil
+}
+
+func mappingValue(mapping *yaml.Node, key string) (*yaml.Node, bool) {
+	if mapping == nil || mapping.Kind != yaml.MappingNode {
+		return nil, false
+	}
+	for index := 0; index+1 < len(mapping.Content); index += 2 {
+		if mapping.Content[index].Value == key {
+			return mapping.Content[index+1], true
+		}
+	}
+	return nil, false
+}
+
+func sequenceContains(sequence *yaml.Node, value string) bool {
+	if sequence == nil || sequence.Kind != yaml.SequenceNode {
+		return false
+	}
+	for _, item := range sequence.Content {
+		if item.Kind == yaml.ScalarNode && item.Value == value {
+			return true
+		}
+	}
+	return false
+}
diff --git a/agentpatch/hermes_config_test.go b/agentpatch/hermes_config_test.go
new file mode 100644
index 0000000..9f68ff3
--- /dev/null
+++ b/agentpatch/hermes_config_test.go
@@ -0,0 +1,84 @@
+// Copyright 2026 The casbin Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package agentpatch
+
+import "testing"
+
+// TestHermesPluginMembershipRoundTrip checks that enabling the observer reads
+// back through the YAML parser and that disabling restores the original bytes.
+func TestHermesPluginMembershipRoundTrip(t *testing.T) {
+	cases := map[string]string{
+		"block list":       "plugins:\n  enabled:\n    - foo\n  disabled:\n    - baz\n\nother: 1\n",
+		"dash at key":      "plugins:\n  enabled:\n  - foo\n",
+		"flow list":        "plugins:\n  enabled: [foo, bar]\n",
+		"empty flow":       "plugins:\n  enabled: []\n",
+		"flow comment":     "plugins:\n  enabled: [foo]  # loaded\n",
+		"comments":         "plugins:\n  # which plugins load\n  enabled:\n    - foo   # keep\n\nother: 1\n",
+		"crlf":             "plugins:\r\n  enabled:\r\n    - foo\r\n",
+		"mixed endings":    "top: 1\nplugins:\r\n  enabled:\r\n    - foo\r\n",
+		"nested item":      "plugins:\n  enabled:\n    - name: foo\n      opt: 1\n    - bar\n",
+		"quoted entries":   "plugins:\n  enabled:\n    - \"foo\"\n    - 'bar'\n",
+		"deep indent":      "plugins:\n    enabled:\n        - foo\n",
+		"no final newline": "plugins:\n  enabled:\n    - foo",
+		"document start":   "---\nplugins:\n  enabled:\n    - foo\n",
+		"no plugins key":   "model: gpt\n\n# section\nlogging:\n  level: info\n",
+		"empty file":       "",
+	}
+
+	for name, original := range cases {
+		t.Run(name, func(t *testing.T) {
+			on, changed, err := setHermesPluginMembership([]byte(original), true)
+			if err != nil || !changed {
+				t.Fatalf("enable: changed=%v err=%v", changed, err)
+			}
+			if err := verifyHermesPluginMembership(on, true); err != nil {
+				t.Fatalf("enable does not read back: %v\n%s", err, on)
+			}
+			off, _, err := setHermesPluginMembership(on, false)
+			if err != nil {
+				t.Fatalf("disable: %v", err)
+			}
+			if err := verifyHermesPluginMembership(off, false); err != nil {
+				t.Fatalf("disable does not read back: %v\n%s", err, off)
+			}
+			if string(off) != original {
+				t.Errorf("not restored\nwant %q\ngot  %q", original, string(off))
+			}
+		})
+	}
+}
+
+// TestHermesPluginMembershipRefuses covers documents the line editor must not
+// edit blind.
+func TestHermesPluginMembershipRefuses(t *testing.T) {
+	cases := map[string]string{
+		"plugins is a scalar": "plugins: none\n",
+		"enabled is an alias": "defaults: &d\n  - foo\nplugins:\n  enabled: *d\n",
+		"enabled is a map":    "plugins:\n  enabled:\n    foo: true\n",
+		"quoted plugins key":  "\"plugins\":\n  enabled:\n    - foo\n",
+	}
+
+	for name, original := range cases {
+		t.Run(name, func(t *testing.T) {
+			updated, _, err := setHermesPluginMembership([]byte(original), true)
+			if err != nil {
+				return
+			}
+			if err := verifyHermesPluginMembership(updated, true); err == nil {
+				t.Errorf("edit was accepted:\n%s", updated)
+			}
+		})
+	}
+}
diff --git a/agentpatch/hermes_observer.py b/agentpatch/hermes_observer.py
new file mode 100644
index 0000000..b0032a0
--- /dev/null
+++ b/agentpatch/hermes_observer.py
@@ -0,0 +1,534 @@
+"""Casbin Gateway's behaviour observer for Hermes Agent.
+
+This module intentionally never serializes prompts, responses, reasoning,
+tool results, or subagent text. Tool arguments are redacted and bounded before
+hook callbacks enqueue records without waiting for the Gateway HTTP endpoint.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import queue
+import re
+import threading
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+_LOGGER = logging.getLogger(__name__)
+_CONFIG_PATH = Path(__file__).with_name("gateway.json")
+_QUEUE: queue.Queue[dict[str, Any]] = queue.Queue(maxsize=1024)
+_STOP = threading.Event()
+_SENDER: threading.Thread | None = None
+_REGISTER_LOCK = threading.Lock()
+_MAX_OBJECT_BYTES = 64 * 1024
+
+_CREDENTIAL_PATTERN = re.compile(
+    r"\b(?:sk-(?:ant-|proj-)?[a-z0-9_-]{12,}|gh[pousr]_[a-z0-9]{20,}|"
+    r"github_pat_[a-z0-9_]{20,}|AKIA[0-9A-Z]{16}|AIza[0-9a-z_-]{30,}|"
+    r"xox[baprs]-[0-9a-z-]{12,}|eyJ[a-z0-9_-]{10,}\.[a-z0-9_-]{10,}\."
+    r"[a-z0-9_-]{10,})\b",
+    re.IGNORECASE,
+)
+_BEARER_PATTERN = re.compile(r"(bearer\s+)[a-z0-9._~+/=-]{12,}", re.IGNORECASE)
+_PRIVATE_KEY_PATTERN = re.compile(
+    r"-----BEGIN [^-\n]*PRIVATE KEY-----.*?-----END [^-\n]*PRIVATE KEY-----",
+    re.DOTALL,
+)
+_SENSITIVE_KEY_MARKERS = (
+    "secret",
+    "token",
+    "password",
+    "passwd",
+    "credential",
+    "privatekey",
+    "apikey",
+    "accesskey",
+    "authorization",
+    "cookie",
+)
+
+_TOKEN_COUNT_KEYS = {
+    "maxtokens",
+    "maxcompletiontokens",
+    "maxtokenstosample",
+    "maxoutputtokens",
+    "prompttokens",
+    "completiontokens",
+    "totaltokens",
+    "reasoningtokens",
+    "inputtokens",
+    "outputtokens",
+    "tokencount",
+    "numtokens",
+    "tokens",
+    "cachecreationinputtokens",
+    "cachereadinputtokens",
+    "cachedtokens",
+}
+
+_USAGE_KEYS = {
+    "input_tokens",
+    "output_tokens",
+    "total_tokens",
+    "prompt_tokens",
+    "completion_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+    "reasoning_tokens",
+    "inputTokens",
+    "outputTokens",
+    "totalTokens",
+    "promptTokens",
+    "completionTokens",
+    "cacheReadInputTokens",
+    "cacheCreationInputTokens",
+    "reasoningTokens",
+}
+
+
+def _load_config() -> dict[str, Any]:
+    try:
+        value = json.loads(_CONFIG_PATH.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {}
+    except Exception:
+        return {}
+
+
+_CONFIG = _load_config()
+_RECORDS_URL = str(_CONFIG.get("recordsUrl") or "")
+_AGENT_PATH = str(_CONFIG.get("agentPath") or "")
+_USER = str(_CONFIG.get("user") or "")
+_INGEST_TOKEN = str(_CONFIG.get("ingestToken") or "")
+_INGEST_TOKEN_HEADER = str(_CONFIG.get("ingestTokenHeader") or "")
+
+
+def _text(value: Any, limit: int = 512) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (str, int, float, bool)):
+        return str(value)[:limit]
+    return ""
+
+
+def _integer(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return int(value)
+    return None
+
+
+def _duration_ms(value: Any, *, seconds: bool = False) -> int:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return 0
+    if seconds:
+        number *= 1000
+    return max(0, int(number))
+
+
+def _length(value: Any) -> int:
+    if value is None:
+        return 0
+    try:
+        return len(value)
+    except (TypeError, ValueError):
+        return len(str(value))
+
+
+def _count(value: Any) -> int:
+    if isinstance(value, (list, tuple, set, dict)):
+        return len(value)
+    return 0
+
+
+def _metadata(**values: Any) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value not in ("", None)}
+
+
+def _sanitize_value(key: str, value: Any) -> Any:
+    normalized_key = key.lower().replace("_", "").replace("-", "").replace(".", "")
+    if normalized_key not in _TOKEN_COUNT_KEYS and any(
+        marker in normalized_key for marker in _SENSITIVE_KEY_MARKERS
+    ):
+        return "[REDACTED]"
+    if isinstance(value, dict):
+        return {child_key: _sanitize_value(child_key, child) for child_key, child in value.items()}
+    if isinstance(value, list):
+        return [_sanitize_value("", child) for child in value]
+    if isinstance(value, str):
+        value = _PRIVATE_KEY_PATTERN.sub("[REDACTED PRIVATE KEY]", value)
+        value = _BEARER_PATTERN.sub(r"\1[REDACTED]", value)
+        return _CREDENTIAL_PATTERN.sub("[REDACTED]", value)
+    return value
+
+
+def _sensitive_path(file_path: Any) -> bool:
+    if not isinstance(file_path, str):
+        return False
+    normalized = file_path.lower().replace("\\", "/")
+    base = normalized.rsplit("/", 1)[-1]
+    if base.startswith(".env") and base not in {".env.example", ".env.sample", ".env.template"}:
+        return True
+    if normalized.startswith(".ssh/") or "/.ssh/" in normalized:
+        return True
+    if normalized == ".aws/credentials" or normalized.endswith("/.aws/credentials"):
+        return True
+    if base in {".npmrc", ".pypirc", "credentials", "id_rsa", "id_ed25519"}:
+        return True
+    return base.endswith((".pem", ".key"))
+
+
+def _sanitize_tool_arguments(tool_name: str, arguments: Any) -> Any:
+    sanitized = _sanitize_value("", arguments)
+    if not isinstance(arguments, dict):
+        return sanitized
+    normalized_tool = tool_name.lower()
+    if (normalized_tool == "patch" or normalized_tool.endswith("__patch")) and "patch" in sanitized:
+        sanitized["patch"] = "[OMITTED: patch content]"
+    sensitive_write = normalized_tool in {"write", "edit", "write_file", "edit_file", "patch"} or normalized_tool.endswith(
+        ("__write_file", "__edit_file", "__patch")
+    )
+    file_path = arguments.get("path", "") or arguments.get("file_path", "")
+    if not sensitive_write or not _sensitive_path(file_path):
+        return sanitized
+    for key in ("content", "old_string", "new_string"):
+        if key in sanitized:
+            sanitized[key] = "[REDACTED: sensitive file content]"
+    return sanitized
+
+
+def _usage(value: Any) -> dict[str, int]:
+    if not isinstance(value, dict):
+        return {}
+    result: dict[str, int] = {}
+    for key in _USAGE_KEYS:
+        number = _integer(value.get(key))
+        if number is not None:
+            result[key] = number
+    return result
+
+
+def _mcp_identity(tool_name: str) -> tuple[str, str]:
+    parts = tool_name.split("__", 2)
+    if len(parts) == 3 and parts[0].lower() == "mcp" and parts[1] and parts[2]:
+        return parts[1], parts[2]
+    return "", ""
+
+
+def _base_record(
+    event_type: str,
+    action: str,
+    outcome: str,
+    values: dict[str, Any],
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = {
+        "agent": "hermes-agent",
+        "agentPath": _AGENT_PATH,
+        "user": _USER,
+        "eventType": event_type,
+        "action": action,
+        "sessionKey": _text(
+            values.get("session_id")
+            or values.get("parent_session_id")
+            or values.get("child_session_id")
+        ),
+        "model": _text(values.get("model")),
+        "promptId": _text(
+            values.get("api_request_id")
+            or values.get("turn_id")
+            or values.get("task_id")
+        ),
+    }
+    if outcome:
+        record["outcome"] = outcome
+    if metadata:
+        encoded = json.dumps(
+            metadata, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+        )
+        encoded_bytes = encoded.encode("utf-8")
+        if len(encoded_bytes) > _MAX_OBJECT_BYTES:
+            encoded = json.dumps(
+                {
+                    "truncated": True,
+                    "originalBytes": len(encoded_bytes),
+                    "preview": encoded_bytes[: _MAX_OBJECT_BYTES // 3].decode(
+                        "utf-8", errors="ignore"
+                    ),
+                },
+                ensure_ascii=False,
+                separators=(",", ":"),
+                sort_keys=True,
+            )
+        record["object"] = encoded
+    return {key: value for key, value in record.items() if value not in ("", None)}
+
+
+def _enqueue(record: dict[str, Any]) -> None:
+    if not _RECORDS_URL:
+        return
+    try:
+        _QUEUE.put_nowait(record)
+    except queue.Full:
+        _LOGGER.debug("Gateway observer queue is full; dropping one audit record")
+
+
+def _send(record: dict[str, Any]) -> None:
+    body = json.dumps(record, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+    if _INGEST_TOKEN_HEADER and _INGEST_TOKEN:
+        headers[_INGEST_TOKEN_HEADER] = _INGEST_TOKEN
+    request = urllib.request.Request(
+        _RECORDS_URL,
+        data=body,
+        headers=headers,
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=2.0) as response:
+        response.read(1)
+
+
+def _sender_loop() -> None:
+    while not _STOP.is_set() or not _QUEUE.empty():
+        try:
+            record = _QUEUE.get(timeout=0.2)
+        except queue.Empty:
+            continue
+        try:
+            _send(record)
+        except Exception as exc:
+            _LOGGER.debug("Gateway record delivery failed: %s", type(exc).__name__)
+        finally:
+            _QUEUE.task_done()
+
+
+def _start_sender() -> None:
+    global _SENDER
+    if not _RECORDS_URL:
+        return
+    with _REGISTER_LOCK:
+        if _SENDER is not None and _SENDER.is_alive():
+            return
+        _SENDER = threading.Thread(
+            target=_sender_loop,
+            name="casbin-gateway-agent-monitor",
+            daemon=True,
+        )
+        _SENDER.start()
+
+
+def _shutdown() -> None:
+    _STOP.set()
+    sender = _SENDER
+    if sender is not None and sender.is_alive():
+        sender.join(timeout=1.0)
+
+
+atexit.register(_shutdown)
+
+
+def _on_pre_api_request(**values: Any) -> None:
+    data = _metadata(
+        provider=_text(values.get("provider")),
+        apiMode=_text(values.get("api_mode")),
+        apiCallCount=_integer(values.get("api_call_count")),
+        retryCount=_integer(values.get("retry_count")),
+        messageCount=_integer(values.get("message_count")),
+        toolCount=_integer(values.get("tool_count")),
+        approxInputTokens=_integer(values.get("approx_input_tokens")),
+        requestCharCount=_integer(values.get("request_char_count")),
+        maxTokens=_integer(values.get("max_tokens")),
+    )
+    _enqueue(_base_record("llm", "request", "attempted", values, data))
+
+
+def _on_post_api_request(**values: Any) -> None:
+    data = _metadata(
+        provider=_text(values.get("provider")),
+        apiMode=_text(values.get("api_mode")),
+        apiCallCount=_integer(values.get("api_call_count")),
+        retryCount=_integer(values.get("retry_count")),
+        finishReason=_text(values.get("finish_reason")),
+        responseModel=_text(values.get("response_model")),
+        messageCount=_integer(values.get("message_count")),
+        assistantContentChars=_integer(values.get("assistant_content_chars")),
+        assistantToolCallCount=_integer(values.get("assistant_tool_call_count")),
+        usage=_usage(values.get("usage")),
+    )
+    record = _base_record("llm", "response", "success", values, data)
+    record["durationMs"] = _duration_ms(values.get("api_duration"), seconds=True)
+    _enqueue(record)
+
+
+def _error_identity(values: dict[str, Any]) -> tuple[str, Any]:
+    """Split Hermes' error report into a type name and the message itself.
+
+    ``api_request_error`` reports a structured ``error = {"type", "message"}``;
+    the tool hooks report flat ``error_type`` / ``error_message`` instead. Only
+    the type name and the message's length ever leave this module.
+    """
+    error = values.get("error")
+    error_type = _text(values.get("error_type"))
+    message = values.get("error_message")
+    if isinstance(error, dict):
+        error_type = error_type or _text(error.get("type"))
+        if message is None:
+            message = error.get("message")
+    elif message is None and error is not None:
+        message = error
+    if not error_type and message is not None:
+        error_type = type(message).__name__
+    return error_type, message
+
+
+def _on_api_request_error(**values: Any) -> None:
+    error_type, error_message = _error_identity(values)
+    data = _metadata(
+        provider=_text(values.get("provider")),
+        apiMode=_text(values.get("api_mode")),
+        apiCallCount=_integer(values.get("api_call_count")),
+        retryCount=_integer(values.get("retry_count")),
+        maxRetries=_integer(values.get("max_retries")),
+        retryable=values.get("retryable") if isinstance(values.get("retryable"), bool) else None,
+        statusCode=_integer(values.get("status_code")),
+        reason=_text(values.get("reason")),
+        errorType=error_type,
+        errorMessageLength=_length(error_message) if error_message is not None else None,
+    )
+    record = _base_record("llm", "error", "failure", values, data)
+    if values.get("api_duration") is not None:
+        record["durationMs"] = _duration_ms(values.get("api_duration"), seconds=True)
+    _enqueue(record)
+
+
+def _tool_record(action: str, outcome: str, values: dict[str, Any]) -> dict[str, Any]:
+    tool_name = _text(values.get("tool_name"))
+    server, tool = _mcp_identity(tool_name)
+    event_type = "mcp" if server else "tool"
+    error_type, error_message = _error_identity(values)
+    data = _metadata(
+        taskId=_text(values.get("task_id")),
+        turnId=_text(values.get("turn_id")),
+        errorType=error_type,
+        errorMessageLength=_length(error_message) if error_message is not None else None,
+        middlewareStageCount=_count(values.get("middleware_trace")),
+    )
+    if action == "call" and values.get("args") is not None:
+        data["arguments"] = _sanitize_tool_arguments(tool_name, values.get("args"))
+    record = _base_record(event_type, action, outcome, values, data)
+    record["toolName"] = tool_name
+    record["toolUseId"] = _text(values.get("tool_call_id"))
+    if server:
+        record["mcpServer"] = server
+        record["mcpTool"] = tool
+    duration = _duration_ms(values.get("duration_ms"))
+    if duration:
+        record["durationMs"] = duration
+    return {key: value for key, value in record.items() if value not in ("", None)}
+
+
+def _on_pre_tool_call(**values: Any) -> None:
+    _enqueue(_tool_record("call", "attempted", values))
+
+
+def _on_post_tool_call(**values: Any) -> None:
+    status = _text(values.get("status")).lower()
+    outcome = {"ok": "success", "blocked": "denied", "error": "failure"}.get(
+        status, "failure"
+    )
+    _enqueue(_tool_record("result", outcome, values))
+
+
+def _on_session_start(**values: Any) -> None:
+    data = _metadata(taskId=_text(values.get("task_id")))
+    _enqueue(_base_record("session", "start", "", values, data))
+
+
+def _on_session_reset(**values: Any) -> None:
+    normalized = dict(values)
+    normalized["session_id"] = values.get("new_session_id") or values.get("session_id")
+    data = _metadata(
+        oldSessionId=_text(values.get("old_session_id")),
+        reason=_text(values.get("reason")),
+    )
+    _enqueue(_base_record("session", "reset", "success", normalized, data))
+
+
+def _on_session_end(**values: Any) -> None:
+    failed = bool(values.get("failed"))
+    interrupted = bool(values.get("interrupted"))
+    outcome = "failure" if failed or interrupted else "success"
+    data = _metadata(
+        taskId=_text(values.get("task_id")),
+        turnId=_text(values.get("turn_id")),
+        completed=bool(values.get("completed")),
+        failed=failed,
+        interrupted=interrupted,
+        exitReason=_text(values.get("turn_exit_reason")),
+    )
+    _enqueue(_base_record("session", "end", outcome, values, data))
+
+
+def _on_subagent_start(**values: Any) -> None:
+    normalized = dict(values)
+    normalized["session_id"] = values.get("parent_session_id") or values.get("session_id")
+    normalized["turn_id"] = values.get("parent_turn_id") or values.get("turn_id")
+    data = _metadata(
+        subagentId=_text(values.get("child_subagent_id") or values.get("subagent_id")),
+        childSessionId=_text(values.get("child_session_id")),
+        childRole=_text(values.get("child_role")),
+        goalLength=_length(values.get("child_goal")),
+    )
+    _enqueue(_base_record("subagent", "start", "attempted", normalized, data))
+
+
+def _on_subagent_stop(**values: Any) -> None:
+    normalized = dict(values)
+    normalized["session_id"] = values.get("parent_session_id") or values.get("session_id")
+    normalized["turn_id"] = values.get("parent_turn_id") or values.get("turn_id")
+    status = _text(values.get("child_status") or values.get("status")).lower()
+    outcome = "success" if status in {"ok", "success", "completed"} else "failure"
+    data = _metadata(
+        subagentId=_text(values.get("child_subagent_id") or values.get("subagent_id")),
+        childSessionId=_text(values.get("child_session_id")),
+        childRole=_text(values.get("child_role")),
+        status=status,
+        summaryLength=_length(values.get("child_summary")),
+        toolCallCount=_count(values.get("tool_call_history")),
+    )
+    # "stop", not "end": the rest of Gateway's record vocabulary already spells
+    # the end of a subagent that way (see agenthook's SubagentStop).
+    record = _base_record("subagent", "stop", outcome, normalized, data)
+    duration = values.get("duration_ms")
+    if duration is None and values.get("duration") is not None:
+        record["durationMs"] = _duration_ms(values.get("duration"), seconds=True)
+    elif duration is not None:
+        record["durationMs"] = _duration_ms(duration)
+    _enqueue(record)
+
+
+_HOOKS = {
+    "pre_api_request": _on_pre_api_request,
+    "post_api_request": _on_post_api_request,
+    "api_request_error": _on_api_request_error,
+    "pre_tool_call": _on_pre_tool_call,
+    "post_tool_call": _on_post_tool_call,
+    "on_session_start": _on_session_start,
+    "on_session_end": _on_session_end,
+    "on_session_reset": _on_session_reset,
+    "subagent_start": _on_subagent_start,
+    "subagent_stop": _on_subagent_stop,
+}
+
+
+def register(ctx: Any) -> None:
+    """Register observational hooks. Return values are deliberately ignored."""
+    _start_sender()
+    for name, callback in _HOOKS.items():
+        ctx.register_hook(name, callback)
diff --git a/agentpatch/hermes_plugin.yaml b/agentpatch/hermes_plugin.yaml
new file mode 100644
index 0000000..83951cc
--- /dev/null
+++ b/agentpatch/hermes_plugin.yaml
@@ -0,0 +1,18 @@
+name: casbin-gateway-agent-monitor
+version: "1.1.0"
+description: "Behaviour audit with redacted tool inputs for Casbin Gateway."
+author: Casbin
+kind: standalone
+# "provides_hooks" is the key Hermes' manifest parser reads; the callbacks
+# themselves are registered from register() in __init__.py.
+provides_hooks:
+  - pre_api_request
+  - post_api_request
+  - api_request_error
+  - pre_tool_call
+  - post_tool_call
+  - on_session_start
+  - on_session_end
+  - on_session_reset
+  - subagent_start
+  - subagent_stop
diff --git a/go.mod b/go.mod
index 0bc0062..b27972b 100644
--- a/go.mod
+++ b/go.mod
@@ -27,6 +27,7 @@ require (
 	golang.org/x/sys v0.17.0
 	golang.org/x/text v0.14.0
 	golang.org/x/time v0.3.0
+	gopkg.in/yaml.v3 v3.0.1
 	modernc.org/sqlite v1.18.1
 )
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@casbin.apache.org
For additional commands, e-mail: commits-help@casbin.apache.org