Metadata-Version: 2.4
Name: hermes-acp
Version: 0.1.0
Summary: ACP governance plugin for Hermes Agent — audit and veto every tool call via the Agentic Control Plane.
Project-URL: Homepage, https://agenticcontrolplane.com
Project-URL: Documentation, https://agenticcontrolplane.com/integrations/hermes
Project-URL: Source, https://github.com/agentic-control-plane/hermes-acp-plugin
Project-URL: Issues, https://github.com/agentic-control-plane/hermes-acp-plugin/issues
Author: GatewayStack
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# hermes-acp

ACP governance plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

Routes every tool call through the [Agentic Control Plane](https://agenticcontrolplane.com) so you get:

- **Audit** — every tool call (terminal, file, web, browser, custom skills) is logged with tenant + session attribution.
- **Veto** — server-side policy can deny or require approval on individual tool calls before they execute.

Companion to the [Claude Code ACP plugin](https://github.com/davidcrowe/claude-code-acp-plugin). Same backend contract, same dashboard, same policies — just wired into Hermes's Python plugin system instead of Claude Code's shell hooks.

## Install

```bash
pip install hermes-acp
hermes plugins enable acp
hermes-acp login
```

`hermes-acp login` opens the dashboard, exchanges your one-time auth token for a workspace API key, and writes it to `~/.acp/credentials`.

## Configure

For non-interactive setups (CI, devcontainers), skip the `login` step and provide the key directly:

```bash
export ACP_BEARER_TOKEN="gsk_yourslug_..."
# or
mkdir -p ~/.acp && echo "gsk_yourslug_..." > ~/.acp/credentials
```

The env var wins over the file.

## CLI

```bash
hermes-acp login       # browser-based authentication + workspace provisioning
hermes-acp status      # check creds + gateway reachability
hermes-acp logout      # remove ~/.acp/credentials
```

Optional — point at a non-default backend:

```bash
export ACP_API_BASE="https://api.agenticcontrolplane.com"  # default
```

## How it works

The plugin registers two Hermes hooks:

| Hook            | Behavior                                                      |
|-----------------|---------------------------------------------------------------|
| `pre_tool_call` | POSTs to `/govern/tool-use`. Server returns `allow` / `deny` / `ask`. `deny` and `ask` block the tool call with a system message; `allow` passes through. |
| `post_tool_call`| POSTs to `/govern/tool-output` for observation. Cannot block (Hermes limitation), but server-side audit, redaction logging, and DLP scanning all apply. |

### Fail-open

Network errors, timeouts (>4s), or malformed responses **fail open** — the tool call proceeds and a warning is written to stderr. ACP outages should never block your work. Server-side per-tenant `failMode: closed` can flip this in a future release.

### "Ask" semantic

Hermes doesn't support inline approval prompts the way Claude Code does, so an ACP `ask` decision is rendered as a `block` with a message instructing the user to approve in the ACP dashboard and retry. If you want a richer approval UX in Hermes, this is the spot to extend.

### Client identity

Sends `X-GS-Client: hermes-plugin/<version>` so the dashboard, policy router, and audit log can distinguish Hermes traffic from Claude Code / Cursor / Codex / etc.

## Troubleshooting

**No audit events appearing.** Check that `ACP_BEARER_TOKEN` is set in the shell that launched `hermes`, not just your `.zshrc` after the fact. Hermes inherits the env at process start.

**Every tool call blocked.** Look at stderr. A `[ACP] gateway unreachable` warning means network failure (fail-open kicked in but something else blocked you — maybe a policy from another hook). A `[ACP] Denied by policy: …` means the server returned `deny`; check the policy in the ACP dashboard.

**Hooks not firing at all.** Confirm the plugin is enabled: `hermes plugins list`. If `acp` isn't in the enabled list, run `hermes plugins enable acp`.

## License

MIT
