agentgov-cli 0.1.5__tar.gz → 0.1.8__tar.gz

{agentgov_cli-0.1.5 → agentgov_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgov-cli
-Version: 0.1.5
+Version: 0.1.8
 Summary: AgentGov CLI — wrap Claude Code, bind work items, check gateway health.
 Author: AgentGov Contributors
 License: Apache-2.0

{agentgov_cli-0.1.5 → agentgov_cli-0.1.8}/agentgov_cli/client_assets/hooks/pretooluse_pathguard.py

@@ -138,6 +138,26 @@ def main() -> None:
     except Exception:
         _bail("bad_input", "unparsable hook JSON")
 
+    # Only confine sessions that are actually governed.
+    #
+    # This hook is registered in ~/.claude/settings.json, so it runs in EVERY
+    # Claude Code session on the machine. Enforcing repo confinement on a session
+    # whose traffic never touches the gateway is not governance, it is just
+    # breaking someone's editor — and because this guard fails closed outside a
+    # git repo, it would block every tool call in any non-repo directory.
+    #
+    # ANTHROPIC_BASE_URL is set by `agentgov wrap` or managed-settings.json,
+    # i.e. exactly when governance is on. See the same check in
+    # userpromptsubmit_workitem.py.
+    # Either signal means governance is deliberately on for this session:
+    #   ANTHROPIC_BASE_URL  — traffic is routed through the gateway
+    #   AGENTGOV_REPO_ROOT  — `agentgov wrap` scoped this session to a repo
+    governed = bool((os.environ.get("ANTHROPIC_BASE_URL") or "").strip()) or bool(
+        (os.environ.get("AGENTGOV_REPO_ROOT") or "").strip()
+    )
+    if not governed:
+        sys.exit(0)
+
     tool_name = payload.get("tool_name") or payload.get("toolName") or ""
     tool_input = payload.get("tool_input") or payload.get("toolInput") or {}
     if not isinstance(tool_input, dict):

agentgov_cli-0.1.8/agentgov_cli/client_assets/hooks/userpromptsubmit_workitem.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""AgentGov UserPromptSubmit hook — the work-item gate.
+
+WHY THIS EXISTS
+---------------
+Work-item binding used to be enforced only at the gateway, which replied with a
+synthetic "bind a work item" assistant message. That has two problems:
+
+  1. The developer only discovers the requirement AFTER sending a prompt, and
+     it arrives looking like a strange answer from the model.
+  2. It cannot prompt at all until something is sent — so a developer who opens
+     their editor and starts typing gets no guidance.
+
+`UserPromptSubmit` fires before Claude Code sends anything, and exit code 2
+blocks the prompt and shows stderr to the developer. So the ask happens in the
+window they are already working in, before any network call, and costs nothing.
+
+The gateway still enforces the same rule independently (§3.1, two-plane model).
+This hook is the good experience; the gateway is the actual control. A developer
+who deletes this hook does not gain ungoverned access — they just go back to
+being told by the gateway instead.
+
+Exit codes:
+  0 -> allow the prompt
+  2 -> block it, and show stderr to the developer
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+from typing import NoReturn
+
+GATEWAY_URL = os.environ.get("AGENTGOV_GATEWAY_URL", "http://127.0.0.1:8000")
+TIMEOUT_SEC = 4.0
+
+# Prompts that exist to FIX an unbound session must not be blocked by the
+# unbound session — otherwise the developer is deadlocked with no way out.
+ESCAPE_PREFIXES = ("/workitem", "/agentgov", "/help", "/status", "/doctor")
+
+
+def _allow() -> NoReturn:
+    sys.exit(0)
+
+
+def _block(message: str) -> NoReturn:
+    sys.stderr.write(message)
+    sys.exit(2)
+
+
+def _is_governed() -> bool:
+    """Is THIS Claude Code session actually routed through the gateway?
+
+    Hooks are registered in ~/.claude/settings.json, which applies to EVERY
+    Claude Code session on the machine — including repositories nobody governs,
+    scratch directories, and support sessions. But a session only means anything
+    to AgentGov if its API traffic goes through the gateway.
+
+    Blocking an ungoverned session is pure harm: no tokens are attributed, no
+    policy applies, and the developer sees their prompt silently vanish (exit 2
+    erases it). That happened for real — the work-item gate froze a session that
+    was talking to Anthropic directly and had nothing to do with governance.
+
+    So: gate only when ANTHROPIC_BASE_URL points at our gateway. That is set by
+    `agentgov wrap` or by managed-settings.json, i.e. exactly when governance is
+    switched on. When it is not set, Claude Code talks to Anthropic directly and
+    we stay out of the way.
+    """
+    base = (os.environ.get("ANTHROPIC_BASE_URL") or "").strip().rstrip("/")
+    if not base:
+        return False
+    return base == GATEWAY_URL.strip().rstrip("/") or "localhost" in base or "127.0.0.1" in base
+
+
+def _binding(session_id: str) -> dict | None:
+    """Ask the gateway about this session. None = gateway unreachable."""
+    try:
+        with urllib.request.urlopen(  # noqa: S310 — loopback only
+            f"{GATEWAY_URL.rstrip('/')}/admin/session/{session_id}/binding",
+            timeout=TIMEOUT_SEC,
+        ) as resp:
+            result = json.loads(resp.read() or b"{}")
+            return result if isinstance(result, dict) else {}
+    except Exception:
+        return None
+
+
+def _register(session_id: str, cwd: str) -> bool:
+    """Re-register a session the gateway has forgotten (e.g. after a restart).
+
+    The gateway holds sessions in memory, so any restart drops every editor
+    window that is already open. Re-registering here means the developer never
+    has to know that happened.
+    """
+    if not cwd:
+        return False
+    try:
+        repo_root = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        if repo_root.returncode != 0:
+            return False
+        root = repo_root.stdout.strip()
+        remote = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        body = json.dumps(
+            {
+                "session_id": session_id,
+                "repo": remote.stdout.strip() if remote.returncode == 0 else "",
+                "repo_root": root,
+            }
+        ).encode()
+        req = urllib.request.Request(
+            f"{GATEWAY_URL.rstrip('/')}/admin/session/register",
+            data=body,
+            headers={"Content-Type": "application/json"},
+        )
+        urllib.request.urlopen(req, timeout=TIMEOUT_SEC).read()  # noqa: S310 — loopback only
+        return True
+    except Exception:
+        return False
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        _allow()  # Fail open: the gateway is the real control.
+
+    session_id = str(payload.get("session_id") or "")
+    user_input = str(payload.get("user_input") or "").strip()
+    cwd = str(payload.get("cwd") or "")
+
+    if not session_id:
+        _allow()
+
+    # Not routed through the gateway -> not governed -> not ours to block.
+    if not _is_governed():
+        _allow()
+
+    # Let the developer run the command that fixes the problem.
+    if user_input.startswith(ESCAPE_PREFIXES):
+        _allow()
+
+    data = _binding(session_id)
+    if data is None:
+        # Gateway down or unreachable. Do NOT block here: Claude Code cannot
+        # reach the model either way, and blocking would bury the real error
+        # ("connection refused") under a confusing governance message.
+        _allow()
+
+    if data.get("bound"):
+        _allow()
+
+    if not data.get("known"):
+        # The gateway does not recognise this session. This is almost always
+        # TRANSIENT, not an attack: the gateway keeps sessions in memory, so a
+        # restart or reinstall forgets every editor window that is already open.
+        #
+        # Blocking here was a serious mistake. It bricked every open Claude Code
+        # window after a gateway restart, with a message telling the developer to
+        # start a new session — while the API plane would have enforced anyway.
+        # Self-heal instead: re-register, then re-check.
+        if not _register(session_id, cwd):
+            _allow()  # Could not re-register — let the gateway be the judge.
+        data = _binding(session_id)
+        if data is None or data.get("bound"):
+            _allow()
+
+    repo = data.get("repo") or "this repository"
+    _block(
+        "📌 AgentGov: bind this session to a work item before continuing.\n"
+        f"   Repository: {repo}\n"
+        "\n"
+        "   Run one of:\n"
+        "     /workitem PROJ-1234              (JIRA issue)\n"
+        "     /workitem PRJ-0042               (internal project)\n"
+        "     /workitem https://notion.so/...  (Notion page)\n"
+        "\n"
+        "   Your prompt was not sent and no tokens were used.\n"
+    )
+
+
+if __name__ == "__main__":
+    main()

agentgov_cli-0.1.8/agentgov_cli/commands/doctor.py

@@ -0,0 +1,363 @@
+"""`agentgov doctor` — diagnose the request path, hop by hop.
+
+The verified path a governed request takes:
+
+    Editor host (VS Code / Cursor / Windsurf / plain terminal)
+      └─ Claude Code            ← the ONLY thing AgentGov governs
+           ├─ hooks ─────────────→ gateway /admin/*        (tool plane)
+           └─ HTTPS to ANTHROPIC_BASE_URL
+                └─ AgentGov Gateway :8000                  (API plane)
+                     ├─ policy snapshot ← control tower
+                     ├─ token events    → control tower
+                     └─ forwards ───────→ api.anthropic.com
+
+Cursor and Windsurf are editor HOSTS, not Claude Code clients. Their own
+assistants (Composer, Cascade) never route through Claude Code, so AgentGov
+cannot see or govern them. Only Claude Code — CLI or extension — is governed.
+
+Checks are grouped by which hop they belong to, so a failure points at one link
+in that chain instead of a flat list of unrelated red rows. Every non-OK row
+carries the exact command to run next; the matching Troubleshooting entry on
+/setup uses the same step names.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import platform
+import socket
+import uuid
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+# The hops, in the order a request travels them.
+STEP_CLIENT = "1 CLIENT"
+STEP_HOOKS = "2 HOOKS"
+STEP_GATEWAY = "3 GATEWAY"
+STEP_IDENTITY = "4 IDENTITY"
+STEP_TOWER = "5 TOWER"
+STEP_UPSTREAM = "6 UPSTREAM"
+
+
+def run(
+    gateway_url: str = typer.Option(None, "--gateway", envvar="AGENTGOV_GATEWAY_URL"),
+    fix: bool = typer.Option(
+        False, "--fix", help="Repair the problems that are safe to repair automatically."
+    ),
+) -> None:
+    url = (gateway_url or "http://localhost:8000").rstrip("/")
+    rows: list[tuple[str, str, str, str]] = []  # step, check, result, what to do
+    ok = warn = fail = 0
+
+    def add(step: str, check: str, level: str, detail: str) -> None:
+        nonlocal ok, warn, fail
+        colour = {"OK": "green", "WARN": "yellow", "FAIL": "red"}[level]
+        rows.append((step, check, f"[{colour}]{level}[/]", detail))
+        if level == "OK":
+            ok += 1
+        elif level == "WARN":
+            warn += 1
+        else:
+            fail += 1
+
+    # ---- 1. CLIENT: is Claude Code actually pointed at the gateway? --------
+    # Nothing below matters if traffic never reaches us. This is also the check
+    # that explains "AgentGov seems installed but does nothing".
+    managed = _managed_settings_path()
+    base_url = (os.environ.get("ANTHROPIC_BASE_URL") or "").strip()
+    if managed.exists():
+        add(STEP_CLIENT, "routing (managed-settings)", "OK", f"all sessions → {url}")
+    elif base_url:
+        add(STEP_CLIENT, "routing (this shell)", "OK", f"ANTHROPIC_BASE_URL={base_url}")
+    else:
+        add(
+            STEP_CLIENT,
+            "routing",
+            "WARN",
+            "Claude Code talks to Anthropic DIRECTLY — nothing is governed. "
+            "Use `agentgov wrap claude`, or install managed-settings (see /setup step 7).",
+        )
+
+    # ---- 2. HOOKS: the tool plane -----------------------------------------
+    hooks_dir = Path.home() / ".claude" / "agentgov-hooks"
+    expected = {
+        "sessionstart_register.py",
+        "userpromptsubmit_workitem.py",
+        "pretooluse_pathguard.py",
+    }
+    if not hooks_dir.exists():
+        add(STEP_HOOKS, "hook files", "FAIL", f"missing {hooks_dir} — run `agentgov install`")
+    else:
+        present = {h.name for h in hooks_dir.glob("*.py")}
+        missing = expected - present
+        if missing:
+            add(
+                STEP_HOOKS,
+                "hook files",
+                "FAIL",
+                f"missing {', '.join(sorted(missing))} — run `agentgov install --force`",
+            )
+        else:
+            not_exec = [h.name for h in hooks_dir.glob("*.py") if not h.stat().st_mode & 0o111]
+            if not_exec:
+                add(
+                    STEP_HOOKS,
+                    "hook files",
+                    "FAIL",
+                    f"not executable: {', '.join(not_exec)} — run `agentgov doctor --fix`",
+                )
+            else:
+                add(STEP_HOOKS, "hook files", "OK", str(hooks_dir))
+
+    registered, dangling = _registered_hooks()
+    if dangling:
+        add(
+            STEP_HOOKS,
+            "hook registration",
+            "FAIL",
+            f"{len(dangling)} registration(s) point at MISSING files — Claude Code runs a "
+            "missing command every prompt. Run `agentgov doctor --fix`.",
+        )
+    elif registered == 0:
+        add(
+            STEP_HOOKS,
+            "hook registration",
+            "WARN",
+            "not registered in ~/.claude/settings.json — no work-item prompt, no path guard. "
+            "Run `agentgov install`.",
+        )
+    elif registered < 3:
+        add(
+            STEP_HOOKS,
+            "hook registration",
+            "WARN",
+            f"only {registered}/3 registered — run `agentgov install --force`",
+        )
+    else:
+        add(STEP_HOOKS, "hook registration", "OK", "3/3 in ~/.claude/settings.json")
+
+    sl = Path.home() / ".claude" / "agentgov-statusline" / "agentgov_statusline.sh"
+    add(
+        STEP_HOOKS,
+        "statusline",
+        "OK" if sl.exists() else "WARN",
+        str(sl) if sl.exists() else "missing — run `agentgov install` (cosmetic only)",
+    )
+
+    # ---- 3. GATEWAY: the API plane ----------------------------------------
+    gateway_up = False
+    try:
+        r = httpx.get(f"{url}/health", timeout=3.0)
+        if r.status_code == 200:
+            gateway_up = True
+            add(STEP_GATEWAY, "reachable", "OK", url)
+        else:
+            add(STEP_GATEWAY, "reachable", "FAIL", f"{url} → HTTP {r.status_code}")
+    except Exception:
+        add(
+            STEP_GATEWAY,
+            "reachable",
+            "FAIL",
+            f"nothing answering at {url} — run `agentgov gateway install`, "
+            "then `agentgov gateway logs`",
+        )
+
+    # ---- 4. IDENTITY -------------------------------------------------------
+    identity = Path.home() / ".agentgov" / "identity.json"
+    add(
+        STEP_IDENTITY,
+        "logged in",
+        "OK" if identity.exists() else "FAIL",
+        str(identity) if identity.exists() else "run `agentgov login --tower <url> --token <tok>`",
+    )
+    creds = Path.home() / ".agentgov" / "gateway_creds.json"
+    add(
+        STEP_IDENTITY,
+        "device registered",
+        "OK" if creds.exists() else "FAIL",
+        str(creds) if creds.exists() else 'run `agentgov register-device --name "$(hostname)"`',
+    )
+
+    # ---- 5. CONTROL TOWER --------------------------------------------------
+    # A gateway that cannot sync policy keeps working until the staleness
+    # ceiling, then denies everything. Surface it before that happens.
+    tower = _creds_field("control_tower_url")
+    if not gateway_up:
+        add(STEP_TOWER, "policy sync", "WARN", "cannot check — gateway is not running")
+    elif not tower:
+        add(STEP_TOWER, "policy sync", "WARN", "no control_tower_url in gateway_creds.json")
+    else:
+        log = Path.home() / ".agentgov" / "gateway.log"
+        tail = ""
+        with contextlib.suppress(OSError):
+            tail = "\n".join(log.read_text(errors="replace").splitlines()[-80:])
+        # A healthy gateway reports EITHER:
+        #   200 -> "snapshot applied"        (policy changed, cache replaced)
+        #   304 -> "Not Modified"            (nothing changed — the steady state)
+        # Only checking for "snapshot applied" flagged a perfectly synced gateway
+        # as WARN, because 304 is what it returns almost all of the time.
+        synced = "snapshot applied" in tail or (
+            "policy/snapshot" in tail and "304" in tail
+        )
+        if synced:
+            add(STEP_TOWER, "policy sync", "OK", tower)
+        elif "401" in tail:
+            add(
+                STEP_TOWER,
+                "policy sync",
+                "FAIL",
+                "control tower rejected the gateway token (401) — re-run "
+                '`agentgov register-device --name "$(hostname)"`',
+            )
+        else:
+            add(STEP_TOWER, "policy sync", "WARN", f"no snapshot seen yet in {log}")
+
+    # ---- 6. UPSTREAM -------------------------------------------------------
+    try:
+        httpx.get("https://api.anthropic.com/v1/models", timeout=5.0)
+        add(STEP_UPSTREAM, "api.anthropic.com", "OK", "reachable from this machine")
+    except Exception as e:
+        add(STEP_UPSTREAM, "api.anthropic.com", "FAIL", f"unreachable: {type(e).__name__}")
+
+    # ---- render ------------------------------------------------------------
+    table = Table("step", "check", "result", "what to do", show_lines=False)
+    for row in rows:
+        table.add_row(*row)
+    console.print(table)
+    console.print(f"\n[bold]{ok} OK  ·  {warn} WARN  ·  {fail} FAIL[/]")
+
+    first_bad = next((r for r in rows if "OK" not in r[2]), None)
+    if first_bad:
+        console.print(
+            f"\n[bold]Start with step {first_bad[0]}[/] — {first_bad[1]}.\n"
+            "  Requests travel the steps in order, so the earliest failure is usually the cause "
+            "of everything after it."
+        )
+    else:
+        console.print("\n[green]Whole path is healthy.[/]")
+
+    repaired = _repair(fix)
+    if repaired and not fix:
+        console.print(
+            "\n[yellow]Repairable automatically:[/] "
+            + "; ".join(repaired)
+            + "\n  Run: [cyan]agentgov doctor --fix[/]"
+        )
+
+    if fail:
+        raise typer.Exit(2)
+    if warn:
+        raise typer.Exit(1)
+
+
+def _registered_hooks() -> tuple[int, list[str]]:
+    """(count of AgentGov registrations, those pointing at files that don't exist)."""
+    settings = Path.home() / ".claude" / "settings.json"
+    if not settings.exists():
+        return 0, []
+    try:
+        data = json.loads(settings.read_text() or "{}")
+    except json.JSONDecodeError:
+        return 0, []
+    if not isinstance(data, dict):
+        return 0, []
+    count = 0
+    dangling: list[str] = []
+    for entries in (data.get("hooks") or {}).values():
+        if not isinstance(entries, list):
+            continue
+        for e in entries:
+            for h in (e or {}).get("hooks", []) if isinstance(e, dict) else []:
+                cmd = str(h.get("command", ""))
+                if "agentgov-hooks" in cmd:
+                    count += 1
+                    if not Path(cmd).exists():
+                        dangling.append(cmd)
+    return count, dangling
+
+
+def _creds_field(key: str) -> str:
+    try:
+        data = json.loads((Path.home() / ".agentgov" / "gateway_creds.json").read_text())
+        return str(data.get(key) or "")
+    except (OSError, ValueError):
+        return ""
+
+
+def _repair(apply: bool) -> list[str]:
+    """Fix only what is UNAMBIGUOUSLY safe to fix.
+
+    Deliberately narrow: the current state must be broken, the correct state must
+    not be a judgement call, and the repair must not destroy anything the
+    developer chose. That excludes logging in, registering a device, and anything
+    needing sudo — those stay manual.
+    """
+    found: list[str] = []
+    settings = Path.home() / ".claude" / "settings.json"
+    hooks_dir = Path.home() / ".claude" / "agentgov-hooks"
+
+    _, dangling = _registered_hooks()
+    if dangling:
+        found.append(f"{len(dangling)} hook registration(s) pointing at missing files")
+        if apply:
+            data = json.loads(settings.read_text() or "{}")
+            hooks = data.get("hooks") or {}
+            for ev in list(hooks):
+                kept = [
+                    e
+                    for e in hooks[ev]
+                    if not any(
+                        "agentgov-hooks" in str(h.get("command", ""))
+                        and not Path(str(h.get("command", ""))).exists()
+                        for h in (e or {}).get("hooks", [])
+                    )
+                ]
+                if kept:
+                    hooks[ev] = kept
+                else:
+                    del hooks[ev]
+            if hooks:
+                data["hooks"] = hooks
+            else:
+                data.pop("hooks", None)
+            settings.write_text(json.dumps(data, indent=2) + "\n")
+            console.print(
+                f"[green]Fixed:[/] removed {len(dangling)} dangling hook registration(s). "
+                "Restart Claude Code."
+            )
+
+    if hooks_dir.is_dir():
+        not_exec = [h for h in hooks_dir.glob("*.py") if not h.stat().st_mode & 0o111]
+        if not_exec:
+            found.append(f"{len(not_exec)} hook(s) not executable")
+            if apply:
+                for h in not_exec:
+                    h.chmod(0o755)
+                console.print(f"[green]Fixed:[/] made {len(not_exec)} hook(s) executable.")
+
+    if apply and not found:
+        console.print("\n[green]Nothing to repair.[/]")
+    return found
+
+
+def _managed_settings_path() -> Path:
+    sysname = platform.system()
+    if sysname == "Darwin":
+        return Path("/Library/Application Support/ClaudeCode/managed-settings.json")
+    if sysname == "Windows":
+        return Path(r"C:\ProgramData\ClaudeCode\managed-settings.json")
+    return Path("/etc/claude-code/managed-settings.json")
+
+
+def _machine_fingerprint() -> str:
+    """SHA-256 of hostname + a stable MAC — same recipe as the gateway."""
+    return hashlib.sha256(f"{socket.gethostname()}:{uuid.getnode():012x}".encode()).hexdigest()

agentgov_cli-0.1.8/agentgov_cli/commands/uninstall.py

@@ -0,0 +1,149 @@
+"""`agentgov uninstall` — remove AgentGov from this machine, safely.
+
+WHY THIS EXISTS
+---------------
+`agentgov install` writes hook registrations into ~/.claude/settings.json that
+point at ~/.claude/agentgov-hooks/*.py. Nothing removed them, so the documented
+teardown —
+
+    rm -rf ~/.agentgov ~/.claude/agentgov-hooks
+
+— left Claude Code registering three hooks whose files no longer existed. Every
+session and every prompt then tried to execute a missing command. Deleting the
+files made Claude Code WORSE, not neutral, and no amount of reinstalling fixed
+it because the stale registrations were never the thing being reinstalled.
+
+Order matters and is the whole point of this command: **deregister first, delete
+second**. A half-removed install must never be able to break the editor.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+CLAUDE_DIR = Path.home() / ".claude"
+SETTINGS = CLAUDE_DIR / "settings.json"
+AGENTGOV_DIR = Path.home() / ".agentgov"
+
+
+def run(
+    keep_credentials: bool = typer.Option(
+        False,
+        "--keep-credentials",
+        help="Keep ~/.agentgov (device key, identity, logs). Only remove Claude Code wiring.",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Do not prompt for confirmation."),
+) -> None:
+    """Remove AgentGov's Claude Code hooks, statusline, and local state."""
+    if not yes:
+        console.print("This will remove AgentGov's hooks and statusline from Claude Code.")
+        if not keep_credentials:
+            console.print(
+                f"It will also delete [cyan]{AGENTGOV_DIR}[/] "
+                "(device key, identity, gateway logs)."
+            )
+        if not typer.confirm("Continue?", default=False):
+            raise typer.Abort()
+
+    # 1. STOP the gateway service first, so nothing restarts mid-teardown.
+    _stop_service()
+
+    # 2. DEREGISTER before deleting. This is the step whose absence broke
+    #    Claude Code: settings.json outlives the files it points at.
+    _deregister()
+
+    # 3. Now the files are safe to delete — nothing references them.
+    for path in (CLAUDE_DIR / "agentgov-hooks", CLAUDE_DIR / "agentgov-statusline"):
+        if path.exists():
+            shutil.rmtree(path, ignore_errors=True)
+            console.print(f"[green]Removed[/] {path}")
+    workitem = CLAUDE_DIR / "commands" / "workitem.md"
+    if workitem.exists():
+        workitem.unlink()
+        console.print(f"[green]Removed[/] {workitem}")
+
+    if not keep_credentials and AGENTGOV_DIR.exists():
+        shutil.rmtree(AGENTGOV_DIR, ignore_errors=True)
+        console.print(f"[green]Removed[/] {AGENTGOV_DIR}")
+
+    console.print("\n[bold green]AgentGov removed.[/]")
+    console.print("Claude Code is unaffected — restart it to clear the old session.")
+    console.print(
+        "\n[dim]Machine-wide managed-settings.json (if you installed it) needs sudo:[/]\n"
+        "  sudo rm -f /etc/claude-code/managed-settings.json"
+    )
+
+
+def _stop_service() -> None:
+    """Stop + disable the gateway service, ignoring 'not installed'."""
+    unit = Path.home() / ".config" / "systemd" / "user" / "agentgov-gateway.service"
+    if not unit.exists():
+        return
+    for args in (["stop", "agentgov-gateway"], ["disable", "agentgov-gateway"]):
+        subprocess.run(
+            ["systemctl", "--user", *args], capture_output=True, check=False, timeout=30
+        )
+    unit.unlink(missing_ok=True)
+    subprocess.run(
+        ["systemctl", "--user", "daemon-reload"], capture_output=True, check=False, timeout=30
+    )
+    console.print(f"[green]Stopped[/] gateway service ({unit.name})")
+
+
+def _deregister() -> None:
+    """Strip AgentGov's entries from ~/.claude/settings.json, leaving the rest."""
+    if not SETTINGS.exists():
+        return
+    try:
+        data = json.loads(SETTINGS.read_text() or "{}")
+    except json.JSONDecodeError:
+        console.print(
+            f"[yellow]Could not parse {SETTINGS}[/] — leaving it alone. "
+            "Remove any 'agentgov-hooks' entries by hand."
+        )
+        return
+    if not isinstance(data, dict):
+        return
+
+    removed = 0
+    hooks = data.get("hooks")
+    if isinstance(hooks, dict):
+        for event in list(hooks):
+            entries = hooks[event]
+            if not isinstance(entries, list):
+                continue
+            kept = [e for e in entries if not _is_agentgov(e)]
+            removed += len(entries) - len(kept)
+            if kept:
+                hooks[event] = kept
+            else:
+                del hooks[event]
+        if hooks:
+            data["hooks"] = hooks
+        else:
+            data.pop("hooks", None)
+
+    if "agentgov" in str(data.get("statusLine", "")):
+        data.pop("statusLine", None)
+        removed += 1
+
+    if removed:
+        SETTINGS.write_text(json.dumps(data, indent=2) + "\n")
+        console.print(f"[green]Deregistered[/] {removed} entr(ies) from {SETTINGS}")
+
+
+def _is_agentgov(entry: object) -> bool:
+    if not isinstance(entry, dict):
+        return False
+    return any(
+        isinstance(h, dict) and "agentgov-hooks" in str(h.get("command", ""))
+        for h in (entry.get("hooks") or [])
+    )

{agentgov_cli-0.1.5 → agentgov_cli-0.1.8}/agentgov_cli/main.py

@@ -4,7 +4,17 @@ from __future__ import annotations
 
 import typer
 
-from .commands import doctor, gateway, install, login, register_device, status, workitem, wrap
+from .commands import (
+    doctor,
+    gateway,
+    install,
+    login,
+    register_device,
+    status,
+    uninstall,
+    workitem,
+    wrap,
+)
 
 app = typer.Typer(
     name="agentgov",
@@ -19,6 +29,10 @@ app.command(
 app.command(
     "install", help="Install client assets into ~/.claude/ and print managed-settings.json."
 )(install.run)
+app.command(
+    "uninstall",
+    help="Remove AgentGov hooks, statusline and local state (deregisters before deleting).",
+)(uninstall.run)
 app.add_typer(gateway.app, name="gateway")
 app.command("wrap", help="Wrap `claude` — start a governed Claude Code session.")(wrap.run)
 app.command("workitem", help="Bind the current session to a work item (JIRA/Notion/PRJ-...).")(

{agentgov_cli-0.1.5 → agentgov_cli-0.1.8}/pyproject.toml

@@ -2,7 +2,7 @@
 # PyPI: `agentgov` was rejected as too similar to existing `agent-gov`.
 # Package name is agentgov-cli; the console command it installs is still `agentgov`.
 name = "agentgov-cli"
-version = "0.1.5"
+version = "0.1.8"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -65,6 +65,7 @@ include = [
 
 [tool.ruff]
 line-length = 100
+extend-exclude = ["agentgov_cli/client_assets"]
 target-version = "py310"
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
@@ -73,6 +74,9 @@ select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF"]
 ignore = ["B008"]
 
 [tool.mypy]
+# agentgov_cli/client_assets is a build artifact vendored by hatch_build.py;
+# the real source lives at the repo root and is checked there.
+exclude = ['agentgov_cli/client_assets/']
 python_version = "3.10"
 strict = true
 disallow_untyped_defs = true

agentgov_cli-0.1.5/agentgov_cli/client_assets/hooks/userpromptsubmit_workitem.py

@@ -1,106 +0,0 @@
-#!/usr/bin/env python3
-"""AgentGov UserPromptSubmit hook — the work-item gate.
-
-WHY THIS EXISTS
----------------
-Work-item binding used to be enforced only at the gateway, which replied with a
-synthetic "bind a work item" assistant message. That has two problems:
-
-  1. The developer only discovers the requirement AFTER sending a prompt, and
-     it arrives looking like a strange answer from the model.
-  2. It cannot prompt at all until something is sent — so a developer who opens
-     their editor and starts typing gets no guidance.
-
-`UserPromptSubmit` fires before Claude Code sends anything, and exit code 2
-blocks the prompt and shows stderr to the developer. So the ask happens in the
-window they are already working in, before any network call, and costs nothing.
-
-The gateway still enforces the same rule independently (§3.1, two-plane model).
-This hook is the good experience; the gateway is the actual control. A developer
-who deletes this hook does not gain ungoverned access — they just go back to
-being told by the gateway instead.
-
-Exit codes:
-  0 -> allow the prompt
-  2 -> block it, and show stderr to the developer
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import sys
-import urllib.request
-
-GATEWAY_URL = os.environ.get("AGENTGOV_GATEWAY_URL", "http://127.0.0.1:8000")
-TIMEOUT_SEC = 4.0
-
-# Prompts that exist to FIX an unbound session must not be blocked by the
-# unbound session — otherwise the developer is deadlocked with no way out.
-ESCAPE_PREFIXES = ("/workitem", "/agentgov", "/help", "/status", "/doctor")
-
-
-def _allow() -> None:
-    sys.exit(0)
-
-
-def _block(message: str) -> None:
-    sys.stderr.write(message)
-    sys.exit(2)
-
-
-def main() -> None:
-    try:
-        payload = json.load(sys.stdin)
-    except Exception:
-        _allow()  # Fail open: the gateway is the real control.
-
-    session_id = str(payload.get("session_id") or "")
-    user_input = str(payload.get("user_input") or "").strip()
-
-    if not session_id:
-        _allow()
-
-    # Let the developer run the command that fixes the problem.
-    if user_input.startswith(ESCAPE_PREFIXES):
-        _allow()
-
-    try:
-        with urllib.request.urlopen(  # noqa: S310 — loopback only
-            f"{GATEWAY_URL.rstrip('/')}/admin/session/{session_id}/binding",
-            timeout=TIMEOUT_SEC,
-        ) as resp:
-            data = json.loads(resp.read() or b"{}")
-    except Exception:
-        # Gateway down or unreachable. Do NOT block here: Claude Code cannot
-        # reach the model either way, and blocking would bury the real error
-        # ("connection refused") under a confusing governance message.
-        _allow()
-
-    if data.get("bound"):
-        _allow()
-
-    if not data.get("known"):
-        _block(
-            "AgentGov: this session is not registered with the gateway, so it cannot "
-            "be governed.\n"
-            "Start a new Claude Code session so the SessionStart hook can run. If this "
-            "persists, run: agentgov doctor\n"
-        )
-
-    repo = data.get("repo") or "this repository"
-    _block(
-        "📌 AgentGov: bind this session to a work item before continuing.\n"
-        f"   Repository: {repo}\n"
-        "\n"
-        "   Run one of:\n"
-        "     /workitem PROJ-1234              (JIRA issue)\n"
-        "     /workitem PRJ-0042               (internal project)\n"
-        "     /workitem https://notion.so/...  (Notion page)\n"
-        "\n"
-        "   Your prompt was not sent and no tokens were used.\n"
-    )
-
-
-if __name__ == "__main__":
-    main()

agentgov_cli-0.1.5/agentgov_cli/commands/doctor.py

@@ -1,168 +0,0 @@
-"""`agentgov doctor` — diagnose the installation (CLAUDE.md §13, §14).
-
-The old §12.1 blanket rule ("gateway must NEVER run on a governed developer's
-machine") has been REPLACED by the §14.4 CONDITIONAL rule:
-
-  The gateway MAY run locally provided
-    (a) upstream_mode = oauth_passthrough  (no vault to steal)
-    OR
-    (b) every credential is user-scoped + spending-capped + device-encrypted.
-
-So this doctor:
-  - Confirms local gateway is reachable (green: it IS local).
-  - Reports the machine fingerprint + the upstream_mode the gateway is
-    running in.
-  - Flags a WARNING (not an error) only if apikey_vault is on AND we couldn't
-    confirm device-encrypted delivery (i.e. an env-provided key overrides the
-    sealed cred — legacy §12 path on a dev machine, which we discourage).
-"""
-
-from __future__ import annotations
-
-import hashlib
-import platform
-import socket
-import uuid
-from pathlib import Path
-
-import httpx
-import typer
-from rich.console import Console
-from rich.table import Table
-
-console = Console()
-
-
-def run(
-    gateway_url: str = typer.Option(None, "--gateway", envvar="AGENTGOV_GATEWAY_URL"),
-) -> None:
-    ok = 0
-    warn = 0
-    fail = 0
-    table = Table("check", "result", "detail", show_lines=False)
-
-    # 1. Managed settings present (Linux only; on macOS/Windows we just show the path)
-    settings_path = _managed_settings_path()
-    if settings_path.exists():
-        table.add_row("managed-settings.json", "[green]OK[/]", str(settings_path))
-        ok += 1
-    else:
-        table.add_row("managed-settings.json", "[yellow]MISSING[/]", str(settings_path))
-        warn += 1
-
-    # 2. Hooks executable
-    hooks_dir = Path.home() / ".claude" / "agentgov-hooks"
-    if not hooks_dir.exists():
-        table.add_row("hooks installed", "[red]MISSING[/]", str(hooks_dir))
-        fail += 1
-    else:
-        problems = [str(h) for h in hooks_dir.glob("*.py") if not h.stat().st_mode & 0o100]
-        if problems:
-            table.add_row("hooks executable", "[red]FAIL[/]", ", ".join(problems))
-            fail += 1
-        else:
-            table.add_row("hooks executable", "[green]OK[/]", str(hooks_dir))
-            ok += 1
-
-    # 3. Statusline installed
-    sl = Path.home() / ".claude" / "agentgov-statusline" / "agentgov_statusline.sh"
-    if sl.exists():
-        table.add_row("statusline installed", "[green]OK[/]", str(sl))
-        ok += 1
-    else:
-        table.add_row("statusline installed", "[yellow]MISSING[/]", str(sl))
-        warn += 1
-
-    # 4. Identity + device registration (§13/§14)
-    identity = Path.home() / ".agentgov" / "identity.json"
-    creds = Path.home() / ".agentgov" / "gateway_creds.json"
-    if identity.exists():
-        table.add_row("identity", "[green]OK[/]", str(identity))
-        ok += 1
-    else:
-        table.add_row("identity", "[yellow]MISSING[/]", "run `agentgov login`")
-        warn += 1
-    if creds.exists():
-        table.add_row("device registered", "[green]OK[/]", str(creds))
-        ok += 1
-    else:
-        table.add_row(
-            "device registered", "[yellow]MISSING[/]", "run `agentgov register-device --name ...`"
-        )
-        warn += 1
-
-    # 5. Gateway reachable
-    url = gateway_url or "http://localhost:8000"
-    upstream_mode = None
-    try:
-        r = httpx.get(f"{url}/health", timeout=3.0)
-        if r.status_code == 200:
-            table.add_row("gateway reachable", "[green]OK[/]", url)
-            ok += 1
-            # Try to read the mode from the /admin endpoint or fall back to
-            # env — for now we just show what env says.
-            import os as _os
-
-            upstream_mode = _os.environ.get("UPSTREAM_MODE", "oauth_passthrough")
-        else:
-            table.add_row("gateway reachable", "[red]FAIL[/]", f"{url} → HTTP {r.status_code}")
-            fail += 1
-    except Exception as e:
-        table.add_row("gateway reachable", "[red]FAIL[/]", f"{url}: {e}")
-        fail += 1
-
-    # 6. §14.4 CONDITIONAL rule check
-    fp = _machine_fingerprint()
-    if upstream_mode == "oauth_passthrough":
-        table.add_row(
-            "§14.4 rule",
-            "[green]OK[/]",
-            f"oauth_passthrough — no vault  ·  fingerprint={fp[:16]}…",
-        )
-        ok += 1
-    elif upstream_mode == "apikey_vault":
-        # We can't introspect the running gateway's config remotely (yet).
-        # This is a soft warning until we add /admin/mode endpoint.
-        import os as _os
-
-        legacy_env_key = bool(_os.environ.get("ANTHROPIC_API_KEY", ""))
-        if legacy_env_key:
-            table.add_row(
-                "§14.4 rule",
-                "[yellow]WARN[/]",
-                (
-                    "apikey_vault WITH env-provided ANTHROPIC_API_KEY — legacy §12 path. "
-                    "Prefer per-device sealed credentials."
-                ),
-            )
-            warn += 1
-        else:
-            table.add_row(
-                "§14.4 rule",
-                "[green]OK[/]",
-                "apikey_vault via per-device sealed credential (recommended)",
-            )
-            ok += 1
-
-    console.print(table)
-    console.print(f"\n[bold]{ok} OK  ·  {warn} WARN  ·  {fail} FAIL[/]")
-    if fail:
-        raise typer.Exit(2)
-    if warn:
-        raise typer.Exit(1)
-
-
-def _managed_settings_path() -> Path:
-    sysname = platform.system()
-    if sysname == "Darwin":
-        return Path("/Library/Application Support/ClaudeCode/managed-settings.json")
-    if sysname == "Windows":
-        return Path(r"C:\ProgramData\ClaudeCode\managed-settings.json")
-    return Path("/etc/claude-code/managed-settings.json")
-
-
-def _machine_fingerprint() -> str:
-    """SHA-256 of hostname + a stable MAC — same recipe as the gateway."""
-    hostname = socket.gethostname()
-    mac = uuid.getnode()
-    return hashlib.sha256(f"{hostname}:{mac:012x}".encode()).hexdigest()