Metadata-Version: 2.5
Name: ory-hermes
Version: 1.10.1
Summary: Ory Agent Security for Hermes Agent — a Hermes plugin for per-tool authorization, activity logging, and identity propagation through the pre_tool_call hook. Built on ory-argus.
Author: Ory
License-Expression: Apache-2.0
Keywords: agent,ai,authorization,hermes,hermes-agent,nous,ory,permissions
Requires-Python: >=3.10
Requires-Dist: ory-argus<2,>=1
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# ory-hermes

Ory Agent Security for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

`ory-hermes` is a Hermes plugin. Hermes calls it before and after every tool call, so each
call is authorized against Ory Permissions, audited, and tied to the user → agent identity.
It is built on [`ory-argus`](https://pypi.org/project/ory-argus/).

## Install

Install the package into the Python environment Hermes runs in, then enable the plugin:

```bash
pip install ory-hermes
hermes plugins enable ory-hermes
```

Hermes discovers the package through the `hermes_agent.plugins` entry point. Plugins are
opt-in in Hermes: nothing is checked until `ory-hermes` is in `plugins.enabled`
(`hermes plugins enable` adds it). Restart Hermes after enabling, and confirm with
`hermes plugins list`.

If you cannot install packages into that environment, install it as a directory plugin
instead. Create `~/.hermes/plugins/ory-hermes/` with two files and enable it the same way:

```yaml
# plugin.yaml
name: ory-hermes
provides_hooks: [on_session_start, pre_tool_call, post_tool_call, subagent_start, on_session_end]
python_dependencies: ["ory-hermes>=1,<2"]
```

```python
# __init__.py
from ory_hermes import register
```

The installed `ory_hermes` package directory also carries a `plugin.yaml`, so a copy of it
works as a directory plugin when `ory-argus` is importable.

## What it does

| Hermes hook | Ory behavior |
|---|---|
| `on_session_start` | Starts user sign-in and agent identity in the background. It never waits and never blocks the session. |
| `pre_tool_call` | Authorizes the call. Runs for built-in, plugin, and MCP tools, and for `delegate_task`. |
| `post_tool_call` | Records `tool.complete`, or `tool.fail` when Hermes reports an error, a timeout, or a cancellation. |
| `subagent_start` | Records the delegation to the child agent. Its tool calls are then checked in the delegating session. |
| `on_session_end` | Flushes queued activity after each turn. |

In **enforce** mode a denied tool is vetoed with Hermes' block directive,
`{"action": "block", "message": "..."}`. The tool does not run and the model receives the
reason. In **observe** mode the denial is recorded and the tool runs.

When the check itself fails, enforce mode denies on authorization, TLS, network,
rate-limit, and server failures, and allows on not-found and other unknown failures.
Observe mode never blocks.

Hermes blocks a tool when a `pre_tool_call` plugin raises or runs longer than
`plugins.hook_callback_timeout` (30 seconds by default). The plugin therefore decides within
25 seconds and treats a check that takes longer as a network failure. The first tool call of
a session waits up to 10 seconds for sign-in to finish and is then checked without it. To
change either limit, or to pass your own client, register the plugin from a directory
plugin:

```python
# ~/.hermes/plugins/ory-hermes/__init__.py
from ory_hermes import OryHermesPlugin


def register(ctx):
    OryHermesPlugin(decision_timeout=50, session_start_wait=20).register(ctx)
```

Keep `decision_timeout` below Hermes' `plugins.hook_callback_timeout`.

## MCP tools

Hermes registers MCP tools as `mcp__<server>__<tool>`. Those calls are checked as
`McpServer:<server>` and `McpTool:<server>:<tool>` instead of plain tools.

The server is read from the tool's `mcp-<server>` toolset in Hermes' registry, which keeps
the unsanitized server name. If that is unavailable, it comes from the `mcp_servers` entry
whose sanitized name prefixes the tool, and otherwise from the tool name itself. For a name
Hermes shortened to 64 characters with a hash suffix, only the `McpServer` check applies.
The server's URL host or launched package from `mcp_servers` is sent as a hashed
fingerprint, so Agent Security matches the server to its catalog whatever it is named. URLs
and arguments are not sent.

## Wrapping your own callables

`guard_callable`, `guard_function_map`, and `guard_tools` wrap tool callables that your own
code dispatches, for example in a custom embedding. A denied call raises `OryDenialError`
before the tool body runs.

```python
from ory_hermes import guard_function_map

tools = guard_function_map({"search": search, "fetch": fetch})
```

These wrappers do not protect Hermes Agent. Hermes dispatches tools through its registry
and never reads a wrapped copy, so use the plugin for Hermes.

## Limits

- Hermes is not published as an installable Python package, so this package has no Hermes
  dependency and no real-SDK compatibility test. Its tests drive the hooks with the payloads
  Hermes sends, taken from the Hermes source.
- Hermes tools are checked by tool name. Commands run through Hermes' `terminal` tool are
  not split into per-command shell checks.

Credentials come from the shared `~/.config/ory-agent-plugins/config.json`, so a login
performed by any other Ory harness plugin or SDK integration is reused here.
