hermes-acp 0.1.0__tar.gz

hermes_acp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GatewayStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_acp-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+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

hermes_acp-0.1.0/README.md

@@ -0,0 +1,79 @@
+# 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

hermes_acp-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hermes-acp"
+version = "0.1.0"
+description = "ACP governance plugin for Hermes Agent — audit and veto every tool call via the Agentic Control Plane."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "GatewayStack" }]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://agenticcontrolplane.com"
+Documentation = "https://agenticcontrolplane.com/integrations/hermes"
+Source = "https://github.com/agentic-control-plane/hermes-acp-plugin"
+Issues = "https://github.com/agentic-control-plane/hermes-acp-plugin/issues"
+
+[project.entry-points."hermes_agent.plugins"]
+acp = "acp_hermes"
+
+[project.scripts]
+hermes-acp = "acp_hermes.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acp_hermes"]

hermes_acp-0.1.0/src/acp_hermes/__init__.py

@@ -0,0 +1,146 @@
+"""ACP governance plugin for Hermes Agent.
+
+Routes every tool call through the Agentic Control Plane for audit and policy
+enforcement. Mirrors the contract used by the Claude Code ACP plugin:
+
+  - POST /govern/tool-use   — pre-call policy check, can deny / ask / allow
+  - POST /govern/tool-output — post-call observation, fires-and-forgets
+
+Behavior:
+  - Fails OPEN on network / parse errors so ACP outages don't block work.
+  - Reads bearer token from ACP_BEARER_TOKEN or ~/.acp/credentials.
+  - Sends X-GS-Client: hermes-plugin/<version> for per-client policy routing.
+  - Hermes post_tool_call is observational (cannot block); we only log there.
+  - Hermes has no "ask" semantic, so an ACP `ask` decision is rendered as a
+    block with an approval-required message.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+PLUGIN_VERSION = "0.1.0"
+CLIENT_ID = f"hermes-plugin/{PLUGIN_VERSION}"
+
+DEFAULT_API_BASE = "https://api.agenticcontrolplane.com"
+REQUEST_TIMEOUT_SECONDS = 4.0
+POST_HOOK_PAYLOAD_CEILING = 200 * 1024  # 200 KB, matches backend scan ceiling.
+
+
+def _api_base() -> str:
+    return os.environ.get("ACP_API_BASE", DEFAULT_API_BASE).rstrip("/")
+
+
+def _resolve_token() -> str | None:
+    token = os.environ.get("ACP_BEARER_TOKEN")
+    if token:
+        return token.strip()
+    try:
+        path = Path.home() / ".acp" / "credentials"
+        return path.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def _post_json(path: str, body: dict[str, Any], token: str) -> dict[str, Any] | None:
+    url = f"{_api_base()}{path}"
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "X-GS-Client": CLIENT_ID,
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT_SECONDS) as resp:
+            raw = resp.read()
+            if not raw:
+                return {}
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                return None
+    except (urllib.error.URLError, TimeoutError, ConnectionError) as exc:
+        sys.stderr.write(f"[ACP] gateway unreachable ({exc}); failing open\n")
+        return None
+
+
+def _block(message: str) -> dict[str, str]:
+    return {"action": "block", "message": message}
+
+
+def _pre_tool_call(
+    tool_name: str,
+    args: dict[str, Any],
+    task_id: str = "",
+    **_: Any,
+) -> dict[str, str] | None:
+    token = _resolve_token()
+    if not token:
+        return None  # Not configured — pass through.
+
+    body = {
+        "tool_name": tool_name,
+        "tool_input": args,
+        "session_id": task_id,
+        "hook_event_name": "PreToolUse",
+        "agent_tier": "interactive",
+    }
+    result = _post_json("/govern/tool-use", body, token)
+    if result is None:
+        return None  # Fail-open on network / parse error.
+
+    decision = result.get("decision")
+    reason = result.get("reason") or "policy did not return a reason"
+    if decision == "deny":
+        return _block(f"[ACP] Denied by policy: {reason}")
+    if decision == "ask":
+        return _block(
+            f"[ACP] Approval required: {reason}. "
+            "Hermes has no inline approval surface; "
+            "approve in the ACP dashboard and retry."
+        )
+    return None
+
+
+def _post_tool_call(
+    tool_name: str,
+    args: dict[str, Any],
+    result: str = "",
+    task_id: str = "",
+    duration_ms: int = 0,
+    **_: Any,
+) -> None:
+    token = _resolve_token()
+    if not token:
+        return
+
+    output_str = result if isinstance(result, str) else json.dumps(result, default=str)
+    if len(output_str.encode("utf-8")) > POST_HOOK_PAYLOAD_CEILING:
+        output_str = output_str[:POST_HOOK_PAYLOAD_CEILING]
+
+    body = {
+        "tool_name": tool_name,
+        "tool_input": args,
+        "tool_output": output_str,
+        "session_id": task_id,
+        "duration_ms": duration_ms,
+        "hook_event_name": "PostToolUse",
+        "agent_tier": "interactive",
+    }
+    _post_json("/govern/tool-output", body, token)
+
+
+def register(ctx: Any) -> None:
+    ctx.register_hook("pre_tool_call", _pre_tool_call)
+    ctx.register_hook("post_tool_call", _post_tool_call)

hermes_acp-0.1.0/src/acp_hermes/cli.py

@@ -0,0 +1,187 @@
+"""hermes-acp CLI.
+
+Subcommands:
+  login    Open browser, exchange auth token for an API key, write
+           ~/.acp/credentials. Mirrors the claude-code installer wire
+           protocol so the same workspace is reachable from any harness.
+  status   Print whether ~/.acp/credentials is present and reachable.
+  logout   Remove ~/.acp/credentials.
+
+The login flow:
+  1. Open <dashboard>/plugin/authorize in browser.
+  2. User pastes the one-time auth token.
+  3. POST <api>/plugin/provision with Bearer auth → {apiKey, workspace, isNew}.
+  4. Write apiKey to ~/.acp/credentials (chmod 600).
+  5. Verify via <api>/govern/health.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+import urllib.error
+import urllib.request
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+from . import PLUGIN_VERSION
+
+DEFAULT_API_BASE = "https://api.agenticcontrolplane.com"
+DEFAULT_DASHBOARD = "https://cloud.agenticcontrolplane.com"
+REQUEST_TIMEOUT_SECONDS = 10.0
+
+
+def _api_base() -> str:
+    return os.environ.get("ACP_API_BASE", DEFAULT_API_BASE).rstrip("/")
+
+
+def _dashboard_base() -> str:
+    return os.environ.get("ACP_DASHBOARD_BASE", DEFAULT_DASHBOARD).rstrip("/")
+
+
+def _credentials_path() -> Path:
+    return Path.home() / ".acp" / "credentials"
+
+
+def _write_credentials(api_key: str) -> Path:
+    path = _credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(api_key.strip() + "\n", encoding="utf-8")
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    return path
+
+
+def _post_json(url: str, body: dict[str, Any], token: str) -> dict[str, Any]:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "X-GS-Client": f"hermes-plugin/{PLUGIN_VERSION}",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT_SECONDS) as resp:
+        return json.loads(resp.read() or b"{}")
+
+
+def _get(url: str) -> int:
+    req = urllib.request.Request(
+        url,
+        method="GET",
+        headers={"X-GS-Client": f"hermes-plugin/{PLUGIN_VERSION}"},
+    )
+    with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT_SECONDS) as resp:
+        return resp.status
+
+
+def _prompt(message: str) -> str:
+    sys.stderr.write(message)
+    sys.stderr.flush()
+    return input().strip()
+
+
+def cmd_login(args: argparse.Namespace) -> int:
+    creds = _credentials_path()
+    if creds.exists() and not args.force:
+        sys.stderr.write(
+            f"Credentials already at {creds}. Re-run with --force to reconfigure.\n"
+        )
+        return 0
+
+    auth_url = f"{_dashboard_base()}/plugin/authorize"
+    sys.stderr.write(f"Opening browser: {auth_url}\n")
+    try:
+        webbrowser.open(auth_url)
+    except webbrowser.Error:
+        sys.stderr.write("Could not open browser automatically. Open the URL above.\n")
+
+    token = _prompt("Paste your token: ")
+    if not token:
+        sys.stderr.write("No token provided. Aborting.\n")
+        return 1
+
+    sys.stderr.write("Provisioning workspace...\n")
+    try:
+        result = _post_json(f"{_api_base()}/plugin/provision", {}, token)
+    except urllib.error.HTTPError as exc:
+        sys.stderr.write(f"Provision failed: HTTP {exc.code} {exc.reason}\n")
+        return 1
+    except (urllib.error.URLError, TimeoutError) as exc:
+        sys.stderr.write(f"Provision failed: {exc}\n")
+        return 1
+
+    api_key = result.get("apiKey")
+    workspace = result.get("workspace")
+    is_new = bool(result.get("isNew"))
+    if not api_key or not workspace:
+        sys.stderr.write(f"Malformed provision response: {result!r}\n")
+        return 1
+
+    path = _write_credentials(api_key)
+    verb = "Created" if is_new else "Connected to"
+    sys.stderr.write(f"{verb} workspace: {workspace}\n")
+    sys.stderr.write(f"Credentials written to {path}\n")
+
+    try:
+        _get(f"{_api_base()}/govern/health")
+        sys.stderr.write("Governance endpoint verified.\n")
+    except Exception as exc:
+        sys.stderr.write(f"Health check failed (non-fatal): {exc}\n")
+
+    sys.stderr.write(f"\nDashboard: {_dashboard_base()}/logs\n")
+    return 0
+
+
+def cmd_status(_: argparse.Namespace) -> int:
+    creds = _credentials_path()
+    if not creds.exists():
+        sys.stderr.write("Not configured. Run `hermes-acp login`.\n")
+        return 1
+    sys.stderr.write(f"Credentials present at {creds}\n")
+    try:
+        status = _get(f"{_api_base()}/govern/health")
+        sys.stderr.write(f"Gateway reachable (HTTP {status}).\n")
+        return 0
+    except Exception as exc:
+        sys.stderr.write(f"Gateway unreachable: {exc}\n")
+        return 2
+
+
+def cmd_logout(_: argparse.Namespace) -> int:
+    creds = _credentials_path()
+    if not creds.exists():
+        sys.stderr.write("Already logged out.\n")
+        return 0
+    creds.unlink()
+    sys.stderr.write(f"Removed {creds}\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="hermes-acp", description="ACP CLI for Hermes Agent")
+    parser.add_argument("--version", action="version", version=f"hermes-acp {PLUGIN_VERSION}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_login = sub.add_parser("login", help="Authenticate and write ~/.acp/credentials")
+    p_login.add_argument("--force", action="store_true", help="Overwrite existing credentials")
+    p_login.set_defaults(func=cmd_login)
+
+    p_status = sub.add_parser("status", help="Show credential and gateway status")
+    p_status.set_defaults(func=cmd_status)
+
+    p_logout = sub.add_parser("logout", help="Remove ~/.acp/credentials")
+    p_logout.set_defaults(func=cmd_logout)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args) or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hermes_acp-0.1.0/src/acp_hermes/plugin.yaml

@@ -0,0 +1,9 @@
+name: acp
+version: 0.1.0
+description: ACP governance — audit and veto every tool call via the Agentic Control Plane.
+author: GatewayStack
+homepage: https://agenticcontrolplane.com
+provides:
+  hooks:
+    - pre_tool_call
+    - post_tool_call

hermes_acp-0.1.0/tests/test_cli.py

@@ -0,0 +1,158 @@
+"""Unit tests for the hermes-acp CLI."""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+
+from acp_hermes import cli
+
+
+class FakeResponse:
+    def __init__(self, body: bytes, status: int = 200) -> None:
+        self._body = body
+        self.status = status
+
+    def read(self) -> bytes:
+        return self._body
+
+    def __enter__(self) -> "FakeResponse":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+@pytest.fixture(autouse=True)
+def _home(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.delenv("ACP_API_BASE", raising=False)
+    monkeypatch.delenv("ACP_DASHBOARD_BASE", raising=False)
+    return tmp_path
+
+
+def _login_args(force: bool = False) -> argparse.Namespace:
+    return argparse.Namespace(cmd="login", force=force, func=cli.cmd_login)
+
+
+def test_login_success_writes_credentials(tmp_path):
+    provision_body = json.dumps(
+        {"apiKey": "acp_live_key", "workspace": "ws-1", "isNew": True}
+    ).encode()
+
+    def _urlopen(req, timeout):  # noqa: ARG001
+        if req.full_url.endswith("/plugin/provision"):
+            return FakeResponse(provision_body)
+        if req.full_url.endswith("/govern/health"):
+            return FakeResponse(b"", status=200)
+        raise AssertionError(f"unexpected url {req.full_url}")
+
+    with patch("urllib.request.urlopen", _urlopen), patch(
+        "webbrowser.open", return_value=True
+    ), patch("builtins.input", return_value="paste_token"):
+        rc = cli.cmd_login(_login_args())
+    assert rc == 0
+    creds = tmp_path / ".acp" / "credentials"
+    assert creds.exists()
+    assert creds.read_text().strip() == "acp_live_key"
+    # Mode should be 0600
+    assert oct(creds.stat().st_mode)[-3:] == "600"
+
+
+def test_login_aborts_when_token_empty(tmp_path):
+    with patch("webbrowser.open"), patch("builtins.input", return_value=""):
+        rc = cli.cmd_login(_login_args())
+    assert rc == 1
+    assert not (tmp_path / ".acp" / "credentials").exists()
+
+
+def test_login_existing_credentials_short_circuits(tmp_path):
+    (tmp_path / ".acp").mkdir()
+    (tmp_path / ".acp" / "credentials").write_text("existing")
+    rc = cli.cmd_login(_login_args(force=False))
+    assert rc == 0
+    # Existing token preserved
+    assert (tmp_path / ".acp" / "credentials").read_text() == "existing"
+
+
+def test_login_force_overwrites(tmp_path):
+    (tmp_path / ".acp").mkdir()
+    (tmp_path / ".acp" / "credentials").write_text("stale")
+    provision_body = json.dumps(
+        {"apiKey": "fresh_key", "workspace": "ws", "isNew": False}
+    ).encode()
+
+    def _urlopen(req, timeout):  # noqa: ARG001
+        return FakeResponse(provision_body if "provision" in req.full_url else b"")
+
+    with patch("urllib.request.urlopen", _urlopen), patch(
+        "webbrowser.open"
+    ), patch("builtins.input", return_value="tok"):
+        rc = cli.cmd_login(_login_args(force=True))
+    assert rc == 0
+    assert (tmp_path / ".acp" / "credentials").read_text().strip() == "fresh_key"
+
+
+def test_login_provision_http_error_returns_1(tmp_path):
+    def _urlopen(req, timeout):  # noqa: ARG001
+        raise urllib.error.HTTPError(req.full_url, 401, "Unauthorized", {}, None)
+
+    with patch("urllib.request.urlopen", _urlopen), patch("webbrowser.open"), patch(
+        "builtins.input", return_value="bad_tok"
+    ):
+        rc = cli.cmd_login(_login_args())
+    assert rc == 1
+
+
+def test_login_malformed_response_returns_1(tmp_path):
+    def _urlopen(req, timeout):  # noqa: ARG001
+        return FakeResponse(b'{"foo": "bar"}')  # missing apiKey/workspace
+
+    with patch("urllib.request.urlopen", _urlopen), patch("webbrowser.open"), patch(
+        "builtins.input", return_value="tok"
+    ):
+        rc = cli.cmd_login(_login_args())
+    assert rc == 1
+
+
+def test_logout_removes_credentials(tmp_path):
+    (tmp_path / ".acp").mkdir()
+    (tmp_path / ".acp" / "credentials").write_text("k")
+    rc = cli.cmd_logout(argparse.Namespace())
+    assert rc == 0
+    assert not (tmp_path / ".acp" / "credentials").exists()
+
+
+def test_logout_when_already_logged_out(tmp_path):
+    rc = cli.cmd_logout(argparse.Namespace())
+    assert rc == 0
+
+
+def test_status_missing_credentials(tmp_path):
+    rc = cli.cmd_status(argparse.Namespace())
+    assert rc == 1
+
+
+def test_status_credentials_present_and_healthy(tmp_path):
+    (tmp_path / ".acp").mkdir()
+    (tmp_path / ".acp" / "credentials").write_text("k")
+    with patch("urllib.request.urlopen", lambda req, timeout: FakeResponse(b"", 200)):
+        rc = cli.cmd_status(argparse.Namespace())
+    assert rc == 0
+
+
+def test_status_credentials_present_gateway_down(tmp_path):
+    (tmp_path / ".acp").mkdir()
+    (tmp_path / ".acp" / "credentials").write_text("k")
+
+    def _down(req, timeout):  # noqa: ARG001
+        raise urllib.error.URLError("down")
+
+    with patch("urllib.request.urlopen", _down):
+        rc = cli.cmd_status(argparse.Namespace())
+    assert rc == 2

hermes_acp-0.1.0/tests/test_hooks.py

@@ -0,0 +1,171 @@
+"""Unit tests for pre/post tool-call hooks.
+
+Strategy: monkeypatch urllib.request.urlopen with a fake that records the
+request and returns a canned JSON response. No real network.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import urllib.error
+from unittest.mock import patch
+
+import pytest
+
+from acp_hermes import _post_tool_call, _pre_tool_call, register
+
+
+class FakeResponse:
+    def __init__(self, body: bytes, status: int = 200) -> None:
+        self._body = body
+        self.status = status
+
+    def read(self) -> bytes:
+        return self._body
+
+    def __enter__(self) -> "FakeResponse":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+def _fake_urlopen(payload: dict, recorded: list | None = None):
+    body = json.dumps(payload).encode()
+
+    def _impl(req, timeout):  # noqa: ARG001 — match urlopen signature
+        if recorded is not None:
+            recorded.append(req)
+        return FakeResponse(body)
+
+    return _impl
+
+
+@pytest.fixture(autouse=True)
+def _isolate_credentials(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.delenv("ACP_BEARER_TOKEN", raising=False)
+    monkeypatch.delenv("ACP_API_BASE", raising=False)
+    yield
+
+
+def _write_token(tmp_path, token: str = "acp_test_token") -> None:
+    acp_dir = tmp_path / ".acp"
+    acp_dir.mkdir()
+    (acp_dir / "credentials").write_text(token)
+
+
+def test_pre_no_token_passes_through(tmp_path):
+    # No env var, no credentials file: hook must be a no-op.
+    assert _pre_tool_call("terminal", {"command": "ls"}, task_id="t1") is None
+
+
+def test_pre_allow_returns_none(tmp_path):
+    _write_token(tmp_path)
+    with patch("urllib.request.urlopen", _fake_urlopen({"decision": "allow"})):
+        assert _pre_tool_call("terminal", {"command": "ls"}, task_id="t1") is None
+
+
+def test_pre_deny_returns_block(tmp_path):
+    _write_token(tmp_path)
+    with patch(
+        "urllib.request.urlopen",
+        _fake_urlopen({"decision": "deny", "reason": "destructive command"}),
+    ):
+        result = _pre_tool_call("terminal", {"command": "rm -rf /"}, task_id="t1")
+    assert result is not None
+    assert result["action"] == "block"
+    assert "destructive command" in result["message"]
+    assert "[ACP]" in result["message"]
+
+
+def test_pre_ask_renders_as_block(tmp_path):
+    _write_token(tmp_path)
+    with patch(
+        "urllib.request.urlopen",
+        _fake_urlopen({"decision": "ask", "reason": "needs review"}),
+    ):
+        result = _pre_tool_call("terminal", {"command": "deploy"}, task_id="t1")
+    assert result is not None
+    assert result["action"] == "block"
+    assert "Approval required" in result["message"]
+    assert "dashboard" in result["message"].lower()
+
+
+def test_pre_network_error_fails_open(tmp_path):
+    _write_token(tmp_path)
+
+    def _raise(req, timeout):  # noqa: ARG001
+        raise urllib.error.URLError("connection refused")
+
+    with patch("urllib.request.urlopen", _raise):
+        assert _pre_tool_call("terminal", {"command": "ls"}, task_id="t1") is None
+
+
+def test_pre_timeout_fails_open(tmp_path):
+    _write_token(tmp_path)
+
+    def _raise(req, timeout):  # noqa: ARG001
+        raise TimeoutError("slow")
+
+    with patch("urllib.request.urlopen", _raise):
+        assert _pre_tool_call("terminal", {"command": "ls"}, task_id="t1") is None
+
+
+def test_pre_sends_correct_headers_and_body(tmp_path):
+    _write_token(tmp_path, "tok_abc")
+    recorded: list = []
+    with patch("urllib.request.urlopen", _fake_urlopen({"decision": "allow"}, recorded)):
+        _pre_tool_call("terminal", {"command": "ls"}, task_id="session-42")
+    assert len(recorded) == 1
+    req = recorded[0]
+    assert req.full_url.endswith("/govern/tool-use")
+    assert req.headers["Authorization"] == "Bearer tok_abc"
+    assert req.headers["X-gs-client"].startswith("hermes-plugin/")
+    body = json.loads(req.data)
+    assert body["tool_name"] == "terminal"
+    assert body["tool_input"] == {"command": "ls"}
+    assert body["session_id"] == "session-42"
+    assert body["hook_event_name"] == "PreToolUse"
+
+
+def test_post_observational_no_return(tmp_path):
+    _write_token(tmp_path)
+    with patch("urllib.request.urlopen", _fake_urlopen({"action": "redact"})):
+        # post hook returns None even when the server says redact —
+        # Hermes can't act on it, so we don't propagate.
+        result = _post_tool_call(
+            "terminal", {"command": "ls"}, result="output", task_id="t", duration_ms=42
+        )
+    assert result is None
+
+
+def test_post_truncates_large_payload(tmp_path):
+    _write_token(tmp_path)
+    big = "x" * (300 * 1024)  # 300 KB, over the 200 KB ceiling
+    recorded: list = []
+    with patch("urllib.request.urlopen", _fake_urlopen({}, recorded)):
+        _post_tool_call("terminal", {}, result=big, task_id="t", duration_ms=1)
+    body = json.loads(recorded[0].data)
+    assert len(body["tool_output"]) == 200 * 1024
+
+
+def test_post_no_token_skips_request(tmp_path):
+    recorded: list = []
+    with patch("urllib.request.urlopen", _fake_urlopen({}, recorded)):
+        _post_tool_call("terminal", {}, result="x", task_id="t", duration_ms=1)
+    assert recorded == []
+
+
+def test_register_wires_both_hooks():
+    calls: list = []
+
+    class FakeCtx:
+        def register_hook(self, name, fn):
+            calls.append((name, fn))
+
+    register(FakeCtx())
+    names = [c[0] for c in calls]
+    assert "pre_tool_call" in names
+    assert "post_tool_call" in names