agentgov-cli 0.1.6__tar.gz → 0.1.7__tar.gz

{agentgov_cli-0.1.6 → agentgov_cli-0.1.7}/PKG-INFO

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

{agentgov_cli-0.1.6 → agentgov_cli-0.1.7}/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.6 → agentgov_cli-0.1.7}/agentgov_cli/client_assets/hooks/userpromptsubmit_workitem.py

@@ -51,6 +51,30 @@ def _block(message: str) -> NoReturn:
     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:
@@ -124,6 +148,10 @@ def main() -> None:
     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()

agentgov_cli-0.1.7/agentgov_cli/commands/doctor.py

@@ -0,0 +1,355 @@
+"""`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:])
+        if "snapshot applied" in tail:
+            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.6 → agentgov_cli-0.1.7}/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.6"
+version = "0.1.7"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }

agentgov_cli-0.1.6/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()