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

{agentgov_cli-0.1.4 → agentgov_cli-0.1.6}/.gitignore

@@ -79,3 +79,6 @@ Thumbs.db
 # ---- Local overrides ----
 *.local
 CLAUDE.local.md
+
+# Build artifact: vendored by cli/hatch_build.py from the repo-root copy.
+cli/agentgov_cli/client_assets/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgov-cli
-Version: 0.1.4
+Version: 0.1.6
 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/client_assets/commands/workitem.md

@@ -0,0 +1,18 @@
+---
+description: Bind this session to a work item (JIRA / Notion / PRJ-XXXX)
+allowed-tools: Bash(agentgov workitem:*)
+argument-hint: <PROJ-1234 | https://notion.so/... | PRJ-0042>
+---
+
+Bind the current session to a validated work item so token spend is
+attributed to the right story.
+
+Run:
+
+!`agentgov workitem $ARGUMENTS`
+
+If the CLI prints an error (JIRA not reachable, item DONE, etc.), relay it
+verbatim to the user and stop — do not attempt to run other tools until they
+provide a valid work item. If the CLI prints a success line
+(`✅ Bound to PROJ-1234 …`), acknowledge the binding and continue with whatever
+the user was doing.

agentgov_cli-0.1.6/agentgov_cli/client_assets/hooks/pretooluse_pathguard.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""AgentGov PreToolUse path-guard hook (§R-CC1).
+
+Registered for Read | Write | Edit | Glob | Grep | Bash | NotebookEdit.
+
+Reads Claude Code's hook JSON on stdin; extracts candidate paths from
+tool_input; resolves realpath (symlink-safe); exits 2 with a stderr
+explanation if any path escapes $AGENTGOV_REPO_ROOT.
+
+Fail-closed: unparsable input → exit 2 (block).
+Allow: paths inside $AGENTGOV_REPO_ROOT, or under /tmp/claude-* scratch.
+
+Every block is appended to ~/.agentgov/toolguard.log for post-hoc audit.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# The authorized repository root. Resolved in main() from the hook payload's
+# `cwd`, because this hook now runs in ANY Claude Code session — including the
+# VS Code extension, where no `agentgov wrap` process exists to export
+# AGENTGOV_REPO_ROOT. The env var is still honoured first so wrapper-launched
+# sessions and the test-suite behave exactly as before.
+REPO_ROOT = os.environ.get("AGENTGOV_REPO_ROOT", "")
+LOG_PATH = Path.home() / ".agentgov" / "toolguard.log"
+
+
+def _resolve_repo_root(cwd: str) -> str:
+    """Repository root for this session: env first, else `git rev-parse` in cwd.
+
+    Returning "" makes _allowed() fail closed, which is the correct outcome for
+    a directory that is not a git repository — there is no authorized root, so
+    nothing is authorized.
+    """
+    if REPO_ROOT:
+        return REPO_ROOT
+    if not cwd:
+        return ""
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return out.stdout.strip() if out.returncode == 0 else ""
+
+
+def _log_block(reason: str, detail: str) -> None:
+    try:
+        LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with LOG_PATH.open("a", encoding="utf-8") as f:
+            f.write(
+                json.dumps(
+                    {
+                        "at": datetime.now(timezone.utc).isoformat(),
+                        "reason": reason,
+                        "detail": detail,
+                        "repo_root": REPO_ROOT,
+                    }
+                )
+                + "\n"
+            )
+    except Exception:
+        pass  # never let logging break enforcement
+
+
+def _bail(reason: str, detail: str) -> None:
+    _log_block(reason, detail)
+    sys.stderr.write(f"AgentGov: blocked — {detail}\n")
+    sys.exit(2)
+
+
+def _is_inside(candidate: Path, root: Path) -> bool:
+    try:
+        candidate.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def _allowed(candidate: str) -> bool:
+    if not REPO_ROOT:
+        return False  # fail-closed if the env wasn't set
+    # /tmp/claude-* scratch is explicitly allowed.
+    if candidate.startswith("/tmp/claude-") or candidate.startswith("/tmp/agentgov-"):
+        return True
+    p = Path(candidate)
+    if not p.is_absolute():
+        # Relative path — treat as inside cwd (which the wrapper set to repo root).
+        p = Path.cwd() / p
+    try:
+        resolved = p.resolve(strict=False)
+    except Exception:
+        return False
+    root = Path(REPO_ROOT).resolve(strict=False)
+    return _is_inside(resolved, root)
+
+
+def _extract_paths(tool_name: str, tool_input: dict) -> list[str]:
+    if tool_name == "Bash":
+        # For Bash, scan the command string for absolute paths and `cd` targets.
+        cmd = str(tool_input.get("command", ""))
+        paths: list[str] = []
+        # `cd <path>`
+        for m in re.finditer(r"\bcd\s+([^\s;&|<>]+)", cmd):
+            paths.append(m.group(1))
+        # Absolute paths appearing as tokens.
+        try:
+            for tok in shlex.split(cmd):
+                if tok.startswith("/") or tok.startswith("~/"):
+                    paths.append(tok)
+        except ValueError:
+            paths.append(cmd)  # unparsable → be conservative
+        return paths
+    # Standard file-touching tools.
+    for k in ("file_path", "path", "pattern"):
+        v = tool_input.get(k)
+        if v:
+            return [str(v)]
+    return []
+
+
+def main() -> None:
+    try:
+        payload = json.loads(sys.stdin.read())
+    except Exception:
+        _bail("bad_input", "unparsable hook JSON")
+
+    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):
+        _bail("bad_input", "tool_input is not an object")
+
+    # Resolve the root for THIS session before checking anything against it.
+    global REPO_ROOT
+    REPO_ROOT = _resolve_repo_root(str(payload.get("cwd") or ""))
+
+    candidates = _extract_paths(tool_name, tool_input)
+    for c in candidates:
+        if not _allowed(c):
+            _bail("outside_repo_root", f"'{c}' is outside the authorized repository root")
+
+    # No offending path; allow.
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

agentgov_cli-0.1.6/agentgov_cli/client_assets/hooks/sessionstart_register.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""AgentGov SessionStart hook — registers this Claude Code session (§R-CC2).
+
+Runs inside WHATEVER Claude Code the developer actually uses: the VS Code /
+Cursor / JetBrains extension, or the terminal CLI. That is the point. The old
+version of this hook required `agentgov wrap` to have exported AGENTGOV_SESSION,
+which meant only a wrapper-launched terminal agent could ever be governed — the
+editor extension the developer really works in was left out.
+
+It needs nothing from a wrapper. Claude Code hands the hook everything on stdin:
+
+    {"hook_event_name": "SessionStart",
+     "session_id": "40a9b75f-55f6-42bb-b839-a4d668a47b45",
+     "cwd": "/home/dev/payment-api"}
+
+and sends that SAME session id to the API on every request as
+`x-claude-code-session-id`. So registering `session_id -> repo` here is what lets
+the gateway authorize every later request. See readme/ARCHITECTURE_v1.md §4.
+
+Exit code is always 0: a governance hook must never stop a developer from
+opening their editor. If registration fails, the API plane still denies —
+enforcement does not depend on this hook succeeding.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+
+GATEWAY_URL = os.environ.get("AGENTGOV_GATEWAY_URL", "http://127.0.0.1:8000")
+TIMEOUT_SEC = 5.0
+
+
+def _git(cwd: str, *args: str) -> str:
+    """Run a git command in `cwd`, returning stripped stdout ('' on failure)."""
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return out.stdout.strip() if out.returncode == 0 else ""
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)  # Never block the session on a parse problem.
+
+    session_id = str(payload.get("session_id") or "")
+    cwd = str(payload.get("cwd") or os.getcwd())
+    if not session_id:
+        sys.exit(0)
+
+    repo_root = _git(cwd, "rev-parse", "--show-toplevel")
+    remote = _git(cwd, "remote", "get-url", "origin") if repo_root else ""
+
+    if not repo_root:
+        # Outside a git repo there is nothing to authorize against. Say so now,
+        # in the session banner, rather than letting the first prompt fail.
+        sys.stdout.write(
+            "AgentGov: this directory is not a git repository, so it cannot be "
+            "authorized. Open a granted repository to use Claude Code here.\n"
+        )
+        sys.exit(0)
+
+    body = json.dumps(
+        {
+            "session_id": session_id,
+            "repo": remote,
+            "repo_root": repo_root,
+            "client_version": os.environ.get("CLAUDE_CODE_VERSION", ""),
+        }
+    ).encode()
+
+    try:
+        req = urllib.request.Request(
+            f"{GATEWAY_URL.rstrip('/')}/admin/session/register",
+            data=body,
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=TIMEOUT_SEC) as resp:  # noqa: S310 — loopback only
+            data = json.loads(resp.read() or b"{}")
+    except Exception:
+        sys.stdout.write(
+            "AgentGov: could not reach the governance gateway at "
+            f"{GATEWAY_URL}. Claude Code will not be able to send requests until it is "
+            "running. Start it with: agentgov gateway install\n"
+        )
+        sys.exit(0)
+
+    # Surface anything the developer needs to act on, in the session banner.
+    for warning in data.get("warnings") or []:
+        sys.stdout.write(f"AgentGov: {warning}\n")
+    if not remote:
+        sys.stdout.write(
+            "AgentGov: this repository has no `origin` remote, so it cannot be "
+            "matched to a grant.\n"
+        )
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,171 @@
+#!/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 _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()
+
+    # 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.6/agentgov_cli/client_assets/managed-settings.json.tmpl

@@ -0,0 +1,41 @@
+{
+  "$comment": "AgentGov managed-settings.json template. Rendered by `agentgov install`. The final file MUST live in the OS-managed path (see docs/DEPLOYMENT.md §4) and be root/Administrator-owned. Developers cannot override.",
+  "env": {
+    "ANTHROPIC_BASE_URL": "{{GATEWAY_URL}}",
+    "AGENTGOV_LOOPBACK_PORT": "8788"
+  },
+  "apiKeyHelper": "",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Write|Edit|Glob|Grep|Bash|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "{{HOME}}/.claude/agentgov-hooks/pretooluse_pathguard.py" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "{{HOME}}/.claude/agentgov-hooks/sessionstart_register.py" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "$comment": "Work-item gate. Blocks the prompt (exit 2) in the developer's own window when the session has no work item bound, so they are told before anything is sent rather than after.",
+        "hooks": [
+          { "type": "command", "command": "{{HOME}}/.claude/agentgov-hooks/userpromptsubmit_workitem.py" }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "{{HOME}}/.claude/agentgov-statusline/agentgov_statusline.sh"
+  },
+  "permissions": {
+    "allow": [],
+    "deny": []
+  }
+}

agentgov_cli-0.1.6/agentgov_cli/client_assets/statusline/agentgov_statusline.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# AgentGov statusline (§R-CC3, §13.6).
+# Renders one of:
+#   🛡 <repo> │ 📌 <work-item> │ N% weekly · resets <when>            (personal mode w/ rate-limit)
+#   🛡 <repo> │ 📌 <work-item> │ N.NNk tok / $C.CC                    (vault mode w/ cost)
+#   🛡 <repo> │ 📌 UNBOUND — /workitem required                       (no binding)
+
+set -u
+
+session="${AGENTGOV_SESSION:-}"
+state_file="${HOME}/.agentgov/state/${session}.json"
+
+if [[ -z "${session}" ]]; then
+  printf "\033[31m📌 UNGOVERNED — run agentgov wrap claude\033[0m"
+  exit 0
+fi
+
+if [[ ! -f "${state_file}" ]]; then
+  printf "\033[33m🛡 %s\033[0m │ \033[31m📌 UNBOUND — /workitem required\033[0m" "${AGENTGOV_REPO:-unknown}"
+  exit 0
+fi
+
+# Parse fields — jq preferred; python fallback.
+if command -v jq >/dev/null 2>&1; then
+  repo=$(jq -r '.repo // env.AGENTGOV_REPO // "unknown"' "${state_file}")
+  wi=$(jq -r '.work_item.external_id // "UNBOUND"' "${state_file}")
+  tokens=$(jq -r '.tokens // 0' "${state_file}")
+  cost=$(jq -r '.cost_usd // 0' "${state_file}")
+  percent=$(jq -r '.rate_limit_percent // ""' "${state_file}")
+  reset=$(jq -r '.rate_limit_reset // ""' "${state_file}")
+else
+  read -r repo wi tokens cost percent reset < <(python3 - "${state_file}" <<'PY'
+import json, os, sys
+d = json.load(open(sys.argv[1]))
+print(
+    d.get("repo") or os.environ.get("AGENTGOV_REPO", "unknown"),
+    (d.get("work_item") or {}).get("external_id") or "UNBOUND",
+    d.get("tokens") or 0,
+    d.get("cost_usd") or 0,
+    d.get("rate_limit_percent") or "",
+    d.get("rate_limit_reset") or "",
+)
+PY
+)
+fi
+
+# Format tokens as N.Nk if >= 1000.
+if [[ "$tokens" -ge 1000 ]] 2>/dev/null; then
+  tokens_h=$(awk "BEGIN {printf \"%.1fk\", $tokens/1000}")
+else
+  tokens_h="${tokens}"
+fi
+
+if [[ "$wi" == "UNBOUND" ]]; then
+  wi_display="\033[31m📌 UNBOUND — /workitem required\033[0m"
+else
+  wi_display="📌 ${wi}"
+fi
+
+# Prefer rate-limit view (personal mode) when we have it; fall back to cost.
+if [[ -n "${percent}" && "${percent}" != "null" && "${percent}" != "None" ]]; then
+  # Color the % red under 15%, yellow under 40%, green otherwise.
+  if awk "BEGIN {exit !($percent < 15)}"; then color=31
+  elif awk "BEGIN {exit !($percent < 40)}"; then color=33
+  else color=32; fi
+  if [[ -n "${reset}" && "${reset}" != "null" ]]; then
+    reset_short=$(printf "%s" "$reset" | cut -c 6-16 | tr T " ")
+    printf "🛡 %s │ %b │ \033[%sm%s%% weekly\033[0m · resets %s" "$repo" "$wi_display" "$color" "$percent" "$reset_short"
+  else
+    printf "🛡 %s │ %b │ \033[%sm%s%% weekly\033[0m" "$repo" "$wi_display" "$color" "$percent"
+  fi
+else
+  printf "🛡 %s │ %b │ %s tok / \$%.2f" "$repo" "$wi_display" "$tokens_h" "$cost"
+fi

{agentgov_cli-0.1.4 → agentgov_cli-0.1.6}/agentgov_cli/commands/install.py

@@ -22,8 +22,18 @@ console = Console()
 # Asset source is discovered relative to the installed package (client_assets is
 # a sibling directory of the cli/). In wheel installs we ship it via
 # package data; in local dev we look up-tree.
+# pip byte-compiles the vendored hooks inside site-packages, so the source
+# tree carries __pycache__. Never copy that into the developer's ~/.claude.
+_IGNORE_BUILD_JUNK = shutil.ignore_patterns("__pycache__", "*.pyc")
+
 ASSET_ROOTS = [
+    # Vendored into the package at build time by cli/hatch_build.py. This is the
+    # path that works for pip/pipx installs: it is relative to __file__, so it
+    # survives relocated venvs and `pip install --user`, unlike sys.prefix.
+    Path(__file__).resolve().parent.parent / "client_assets",
+    # Source checkout: client_assets/ sits at the repo root (CLAUDE.md §4).
     Path(__file__).resolve().parent.parent.parent.parent / "client_assets",
+    # Legacy shared-data location, kept so older installs keep working.
     Path(sys.prefix) / "share" / "agentgov" / "client_assets",
 ]
 
@@ -66,7 +76,9 @@ def run(
     if hooks_dest.exists() and not force:
         console.print(f"[yellow]Skipping[/] hooks — {hooks_dest} exists (use --force)")
     else:
-        shutil.copytree(hooks_src, hooks_dest, dirs_exist_ok=True)
+        shutil.copytree(
+            hooks_src, hooks_dest, dirs_exist_ok=True, ignore=_IGNORE_BUILD_JUNK
+        )
         for h in hooks_dest.glob("*.py"):
             h.chmod(0o755)
         console.print(f"[green]Copied[/] hooks → {hooks_dest}")
@@ -76,7 +88,9 @@ def run(
     if statusline_dest.exists() and not force:
         console.print(f"[yellow]Skipping[/] statusline — {statusline_dest} exists")
     else:
-        shutil.copytree(statusline_src, statusline_dest, dirs_exist_ok=True)
+        shutil.copytree(
+            statusline_src, statusline_dest, dirs_exist_ok=True, ignore=_IGNORE_BUILD_JUNK
+        )
         for h in statusline_dest.glob("*.sh"):
             h.chmod(0o755)
         console.print(f"[green]Copied[/] statusline → {statusline_dest}")

agentgov_cli-0.1.6/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.4 → agentgov_cli-0.1.6}/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.6/hatch_build.py

@@ -0,0 +1,72 @@
+"""Vendor client_assets/ into the wheel at build time.
+
+WHY THIS FILE EXISTS
+--------------------
+`agentgov install` copies hooks, the statusline and the /workitem command out of
+`client_assets/`, which CLAUDE.md §4 places at the REPO ROOT — a sibling of
+`cli/`, i.e. outside this package's build root.
+
+Two earlier attempts failed:
+
+  * `[tool.hatch.build.targets.wheel.shared-data]` with "../client_assets"
+    produced NOTHING, silently. The wheel shipped without any assets, so
+    `agentgov install` worked only from a source checkout and raised
+    FileNotFoundError for every pip-installed user.
+  * `force-include` with "../client_assets" builds fine in the repo but breaks
+    `uv build`, which builds the wheel FROM the sdist — and inside the unpacked
+    sdist there is no parent directory to reach into.
+
+So the assets are copied INTO the package during `initialize()`, which runs for
+both the sdist and the wheel:
+
+  * building in the repo   -> found at <root>/../client_assets
+  * building from an sdist -> already vendored at agentgov_cli/client_assets
+
+Being inside the package also means `agentgov install` resolves them relative to
+__file__ instead of sys.prefix, which is what makes it work under pipx, `pip
+install --user`, and relocated virtualenvs.
+
+The vendored copy is a build artifact and is git-ignored; the repo-root copy
+stays the single source of truth.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+VENDORED_SUBPATH = "agentgov_cli/client_assets"
+
+
+class CustomBuildHook(BuildHookInterface):
+    """Copies <repo>/client_assets into agentgov_cli/client_assets before build."""
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        root = Path(self.root)
+        vendored = root / VENDORED_SUBPATH
+        source = root.parent / "client_assets"
+
+        if source.is_dir():
+            # Building from the repo: refresh the vendored copy so a stale one
+            # can never ship instead of the real assets. __pycache__ is excluded
+            # because running a hook in the repo leaves .pyc files behind, and a
+            # stale one shipped next to an edited hook is a nasty way to debug.
+            if vendored.exists():
+                shutil.rmtree(vendored)
+            shutil.copytree(source, vendored, ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))
+        elif not vendored.is_dir():
+            raise FileNotFoundError(
+                f"client_assets not found at {source} and not vendored at {vendored}. "
+                "The CLI cannot ship without the hooks and statusline it installs."
+            )
+
+        # Be explicit rather than relying on default file collection: these are
+        # untracked build artifacts, and a wheel that silently omits them is the
+        # exact failure this hook exists to prevent.
+        force_include = build_data.setdefault("force_include", {})
+        for path in sorted(vendored.rglob("*")):
+            if path.is_file() and "__pycache__" not in path.parts and path.suffix != ".pyc":
+                force_include[str(path)] = str(path.relative_to(root))

{agentgov_cli-0.1.4 → agentgov_cli-0.1.6}/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.4"
+version = "0.1.6"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -37,24 +37,35 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["agentgov_cli"]
 
-# Ship client_assets/ (sibling dir of cli/) as shared data. Installs to
-# <venv>/share/agentgov/client_assets/, which is exactly where
-# commands/install.py:ASSET_ROOTS[1] looks. Without this, a pip-installed CLI
-# can't find hooks/statusline/slash-command and `agentgov install` fails with
-# FileNotFoundError.
-[tool.hatch.build.targets.wheel.shared-data]
-"../client_assets" = "share/agentgov/client_assets"
+# Ship client_assets/ (a SIBLING of cli/) inside the package itself.
+#
+# `shared-data` was tried here first and silently produced nothing: the build
+# root is cli/, and hatchling will not collect a `../` path for shared-data. The
+# wheel therefore contained no assets at all, so `agentgov install` worked only
+# from a source checkout (where ASSET_ROOTS[0] resolves) and died with
+# FileNotFoundError for every pip-installed user — the exact opposite of who
+# needs it.
+#
+# `force-include` DOES accept paths outside the project root, and placing the
+# assets inside the package means they are found relative to __file__ — no
+# dependence on sys.prefix, which breaks under pipx, --user, and relocated venvs.
+# hatch_build.py vendors <repo>/client_assets into agentgov_cli/client_assets
+# for BOTH targets. See that file for why shared-data and a bare force-include
+# of "../client_assets" both fail.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
 
 [tool.hatch.build.targets.sdist]
 include = [
     "agentgov_cli/**",
-    "../client_assets/**",
+    "hatch_build.py",
     "README.md",
     "pyproject.toml",
 ]
 
 [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"]
@@ -63,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