Metadata-Version: 2.4
Name: custodian-hermes-guard
Version: 0.1.0
Summary: Fail-closed Custodian policy guard for Hermes Agent, managed by Talaria
Author-email: InovinLabs <hello@inovinlabs.com>
License-Expression: MIT
Project-URL: Homepage, https://getcustodian.xyz
Project-URL: Repository, https://github.com/KeyArgo/custodian-hermes-guard
Project-URL: Documentation, https://getcustodian.xyz/docs
Project-URL: Issues, https://github.com/KeyArgo/custodian-hermes-guard/issues
Project-URL: Security, https://github.com/KeyArgo/custodian-hermes-guard/blob/main/SECURITY.md
Project-URL: Changelog, https://github.com/KeyArgo/custodian-hermes-guard/blob/main/CHANGELOG.md
Keywords: hermes,guard,policy,agent,custodian
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: custodian-kernel<0.5,>=0.4.2
Dynamic: license-file

# Custodian Hermes Guard

### The enforcement adapter under Talaria.

Hermes Guard sits in the Hermes Agent tool loop. Before a tool runs, it checks
the proposed action through Custodian's policy pipeline. After the tool
returns, it inspects the result before Hermes sees it.

It follows the same kernel policy and operator contract as
[Custodian Codex Guard](https://github.com/KeyArgo/custodian-codex-guard);
only host-specific integration features differ.

That gives Hermes a mechanical boundary for forbidden files, tools, prompt
injection, secret leakage, personal data, spending patterns, and
operator-approved actions. These checks live below the model. Remembering the
rule is not part of the security design.

## Hermes Guard or Talaria?

Use Hermes Guard when you want the smallest standalone enforcement adapter.
Use [Talaria](https://github.com/KeyArgo/custodian-talaria) when you want the complete
Hermes experience: policy authoring, dashboard, denial history, credential
broker, session capsules, and governed skill execution.

Talaria depends on Hermes Guard. Hermes Guard does not depend on Talaria.
There is one canonical enforcement runtime, not two implementations that can
drift apart.

## Install

Version 0.1.0 is available as a GitHub release.

Install from PyPI:

```bash
pipx install custodian-hermes-guard
custodian-hermes setup
custodian-hermes doctor
custodian-hermes status
```

`custodian-hermes-guard` is an equivalent long-form command. On PEP 668 Linux
systems, use `pipx` or a virtual environment rather than modifying the system
Python.

## The two hooks

`pre_tool_call` evaluates the tool name and arguments. A denial becomes a hard
Hermes block.

`transform_tool_result` inspects returned text. It can redact sensitive
content or suppress an unsafe result before the model receives it.

If the kernel, policy, or plugin cannot initialize, the pre-tool hook blocks
the call. An installation failure must not become unrestricted execution.

## Exact approvals

Protected mode creates an authenticated approval for the exact action.
Approvals are:

- single-use;
- time-bounded;
- tied to the arguments, workspace, requester, and policy version;
- consumed only by the matching follow-up action.

Hermes Guard waits for the operator decision and resumes the original call
when approved. Repeated identical attempts reuse the same live request instead
of filling the dashboard with duplicates.

## Policy

Hermes Guard reads `~/.talaria/policy.yaml`:

```yaml
version: "1"

operator:
  mode: protected
  approval_wait_seconds: 300

tools:
  forbid: [stripe-payout]

paths:
  forbid: ["~/.ssh", "~/.aws", "~/.gnupg"]
  forbid_globs: ["*.env", "*.pem", "id_rsa"]

privacy:
  redact: [email, phone, ssn, card]
```

Kernel self-protection, prompt-injection detection, and secret-leak protection
remain mandatory. Policy can narrow authority but cannot switch off those
boundaries.

## Release status

The 0.1.0 release has passed source, filtered-package, clean-wheel, Linux,
and Windows qualification. macOS qualification remains pending. No PyPI
publication has occurred.

Custodian is alpha software and has not received a third-party security audit.
Read [SECURITY.md](SECURITY.md) before relying on it for consequential work.

## Links

- [Source](https://github.com/KeyArgo/custodian-hermes-guard)
- [Talaria](https://github.com/KeyArgo/custodian-talaria)
- [Custodian Kernel](https://github.com/KeyArgo/custodian-kernel)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
