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

{agentgov_cli-0.1.3 → agentgov_cli-0.1.5}/.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.3 → agentgov_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgov-cli
-Version: 0.1.3
+Version: 0.1.5
 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/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.5/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.5/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.5/agentgov_cli/client_assets/hooks/userpromptsubmit_workitem.py

@@ -0,0 +1,106 @@
+#!/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/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.5/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.3 → agentgov_cli-0.1.5}/agentgov_cli/commands/gateway.py

@@ -39,12 +39,17 @@ def install(gateway_url: str = _GATEWAY_OPT) -> None:
         return
 
     console.print(f"[green]{detail}[/]")
-    if gp.is_healthy(url, timeout_sec=10.0):
+    # Wait for boot rather than probing once. The service manager returns as
+    # soon as it has spawned the process, but the gateway only binds its port
+    # after rehydrating sessions and fetching the first policy snapshot — two
+    # round-trips to the control tower. A single probe here reports a false
+    # failure on a gateway that is simply still starting.
+    console.print(f"Waiting for {url}/health ...")
+    if gp.wait_until_healthy(url):
         console.print(f"[green]Gateway healthy[/] at {url}")
     else:
-        # The service manager accepted the unit but the process is not
-        # answering — surface the log rather than claiming success.
-        console.print(f"[yellow]Service installed but {url}/health did not answer yet.[/]")
+        # Genuinely not answering — surface the log rather than claiming success.
+        console.print(f"[yellow]Service installed but {url}/health did not answer in time.[/]")
         console.print(gp.log_tail())
         raise typer.Exit(1)
 

agentgov_cli-0.1.5/agentgov_cli/commands/install.py

@@ -0,0 +1,269 @@
+"""`agentgov install` — copies client assets to ~/.claude/, prints managed-settings.json.
+
+The managed-settings.json is printed to stdout (with the admin-visible path per OS)
+so an administrator can drop it into the OS-managed path. That path is ROOT-owned;
+we do NOT try to write it — the CLI runs as the developer.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+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",
+]
+
+
+def run(
+    gateway_url: str = typer.Option(
+        "http://localhost:8000",
+        "--gateway-url",
+        "--gateway",  # alias — earlier docs called it --gateway
+        envvar="AGENTGOV_GATEWAY_URL",
+        help="URL of the local AgentGov gateway (usually http://localhost:8000).",
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing hooks/statusline."),
+    user_settings: bool = typer.Option(
+        True,
+        "--user-settings/--no-user-settings",
+        help=(
+            "Register the hooks + statusline in ~/.claude/settings.json so they take "
+            "effect immediately, with no sudo. Disable for admin-managed installs."
+        ),
+    ),
+) -> None:
+    """Install hooks + statusline + slash commands into ~/.claude/.
+
+    By default this also REGISTERS them in ~/.claude/settings.json, so the
+    governance hooks run in every Claude Code session on this machine — the VS
+    Code / Cursor extension included — without sudo and without launching
+    anything through a wrapper.
+
+    Also writes a ready-to-copy managed-settings.json to
+    ~/.agentgov/managed-settings.json. Installing THAT (needs sudo/admin) is
+    what makes governance non-overridable, for team/enterprise deployments.
+    """
+    src = _find_assets()
+    dest = Path.home() / ".claude"
+    dest.mkdir(exist_ok=True)
+
+    hooks_src = src / "hooks"
+    hooks_dest = dest / "agentgov-hooks"
+    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, ignore=_IGNORE_BUILD_JUNK
+        )
+        for h in hooks_dest.glob("*.py"):
+            h.chmod(0o755)
+        console.print(f"[green]Copied[/] hooks → {hooks_dest}")
+
+    statusline_src = src / "statusline"
+    statusline_dest = dest / "agentgov-statusline"
+    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, ignore=_IGNORE_BUILD_JUNK
+        )
+        for h in statusline_dest.glob("*.sh"):
+            h.chmod(0o755)
+        console.print(f"[green]Copied[/] statusline → {statusline_dest}")
+
+    commands_dest = dest / "commands"
+    commands_dest.mkdir(exist_ok=True)
+    shutil.copy2(src / "commands" / "workitem.md", commands_dest / "workitem.md")
+    console.print(f"[green]Copied[/] /workitem slash command → {commands_dest / 'workitem.md'}")
+
+    settings = _build_managed_settings(gateway_url, hooks_dest, statusline_dest)
+    settings_json = json.dumps(settings, indent=2)
+
+    # Activate the hooks for THIS user, right now, without sudo.
+    #
+    # Copying the files is not enough — Claude Code only runs hooks that a
+    # settings file registers. Previously the only place that happened was
+    # managed-settings.json, which needs root, so a developer who followed setup
+    # to the letter ended up with hook files on disk and nothing running them:
+    # no statusline, no path guard, and no work-item prompt.
+    if user_settings:
+        _merge_user_settings(gateway_url, hooks_dest, statusline_dest)
+
+    # Write to a stable local path so the admin can `sudo cp` it into place
+    # without having to redirect stdout carefully.
+    local_settings_path = Path.home() / ".agentgov" / "managed-settings.json"
+    local_settings_path.parent.mkdir(parents=True, exist_ok=True)
+    local_settings_path.write_text(settings_json + "\n")
+    local_settings_path.chmod(0o644)
+
+    target_path = _managed_settings_path()
+    console.rule("[bold]managed-settings.json[/]")
+    console.print(f"Written locally to: [cyan]{local_settings_path}[/]")
+    console.print(f"Target install path: [cyan]{target_path}[/]\n")
+    console.print("[bold]To govern the VS Code extension too, run:[/]")
+    if platform.system() == "Windows":
+        console.print(
+            f'  Copy-Item "{local_settings_path}" "{target_path}" -Force'
+        )
+    else:
+        parent = str(Path(target_path).parent)
+        console.print(
+            f"  sudo mkdir -p {parent} && sudo cp {local_settings_path} {target_path}"
+        )
+    console.print(
+        "\nThen fully quit VS Code and reopen — the extension now routes through the gateway."
+    )
+    console.print("\n[dim]Contents (for reference):[/]")
+    console.print(settings_json)
+
+
+def _agentgov_hook_entries(hooks_dest: Path) -> dict[str, list[dict[str, object]]]:
+    """The hook registrations AgentGov owns, keyed by Claude Code event name."""
+    def cmd(script: str) -> dict[str, object]:
+        return {"type": "command", "command": str(hooks_dest / script)}
+
+    return {
+        "SessionStart": [{"hooks": [cmd("sessionstart_register.py")]}],
+        "UserPromptSubmit": [{"hooks": [cmd("userpromptsubmit_workitem.py")]}],
+        "PreToolUse": [
+            {
+                "matcher": "Read|Write|Edit|Glob|Grep|Bash|NotebookEdit",
+                "hooks": [cmd("pretooluse_pathguard.py")],
+            }
+        ],
+    }
+
+
+def _is_agentgov_entry(entry: object) -> bool:
+    """True if a hook registration belongs to AgentGov.
+
+    Matched on the command path so re-running `install` replaces our own entries
+    instead of stacking duplicates, while leaving the user's other hooks alone.
+    """
+    if not isinstance(entry, dict):
+        return False
+    for h in entry.get("hooks") or []:
+        if isinstance(h, dict) and "agentgov-hooks" in str(h.get("command", "")):
+            return True
+    return False
+
+
+def _merge_user_settings(gateway_url: str, hooks_dest: Path, statusline_dest: Path) -> None:
+    """Register AgentGov's hooks + statusline in ~/.claude/settings.json.
+
+    MERGES. The file usually already holds the developer's own preferences and
+    hooks; clobbering it would be a hostile way to install a governance tool.
+    We replace only entries we previously wrote (identified by their path) and
+    leave everything else untouched. A corrupt file is left alone entirely —
+    reporting it beats silently overwriting whatever was in there.
+    """
+    path = Path.home() / ".claude" / "settings.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict[str, object] = {}
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text() or "{}")
+            if isinstance(loaded, dict):
+                data = loaded
+            else:
+                console.print(f"[yellow]Skipping[/] {path} — not a JSON object.")
+                return
+        except json.JSONDecodeError as e:
+            console.print(
+                f"[red]Skipping[/] {path} — it is not valid JSON ({e}).\n"
+                "Fix or remove it, then re-run `agentgov install`."
+            )
+            return
+        # Back the file up once before the first modification.
+        backup = path.with_suffix(".json.agentgov-backup")
+        if not backup.exists():
+            backup.write_text(path.read_text())
+
+    hooks_raw = data.get("hooks")
+    hooks: dict[str, object] = hooks_raw if isinstance(hooks_raw, dict) else {}
+    for event, entries in _agentgov_hook_entries(hooks_dest).items():
+        existing_raw = hooks.get(event)
+        existing = existing_raw if isinstance(existing_raw, list) else []
+        kept = [e for e in existing if not _is_agentgov_entry(e)]
+        hooks[event] = kept + entries
+    data["hooks"] = hooks
+
+    data["statusLine"] = {
+        "type": "command",
+        "command": str(statusline_dest / "agentgov_statusline.sh"),
+    }
+
+    # NOTE: deliberately NOT setting env.ANTHROPIC_BASE_URL here. User settings
+    # are the lowest-precedence scope and the developer can edit them, so
+    # pinning the base URL here would look like enforcement while being trivial
+    # to undo. Routing is the job of managed-settings.json (highest precedence).
+    path.write_text(json.dumps(data, indent=2) + "\n")
+    console.print(f"[green]Registered[/] hooks + statusline → {path}")
+    console.print(
+        "  [dim]These run in every Claude Code session on this machine, including the "
+        "VS Code extension. Restart Claude Code to pick them up.[/]"
+    )
+
+
+def _find_assets() -> Path:
+    for root in ASSET_ROOTS:
+        if root.exists():
+            return root
+    raise FileNotFoundError(f"client_assets/ not found in any of: {ASSET_ROOTS}")
+
+
+def _build_managed_settings(
+    gateway_url: str, hooks_dest: Path, statusline_dest: Path
+) -> dict[str, object]:
+    return {
+        "env": {
+            "ANTHROPIC_BASE_URL": gateway_url,
+            "AGENTGOV_LOOPBACK_PORT": os.environ.get("AGENTGOV_LOOPBACK_PORT", "8788"),
+        },
+        # apiKeyHelper disabled — Claude Code must use the agk_ key from the wrapper env.
+        "apiKeyHelper": "",
+        "hooks": _agentgov_hook_entries(hooks_dest),
+        "statusLine": {
+            "type": "command",
+            "command": str(statusline_dest / "agentgov_statusline.sh"),
+        },
+        # Permissions baseline: developers may NOT override the base URL or hooks.
+        "permissions": {
+            "allow": [],
+            "deny": [],
+        },
+    }
+
+
+def _managed_settings_path() -> str:
+    sysname = platform.system()
+    if sysname == "Darwin":
+        return "/Library/Application Support/ClaudeCode/managed-settings.json"
+    if sysname == "Windows":
+        return r"C:\ProgramData\ClaudeCode\managed-settings.json"
+    return "/etc/claude-code/managed-settings.json"

{agentgov_cli-0.1.3 → agentgov_cli-0.1.5}/agentgov_cli/gateway_process.py

@@ -42,7 +42,12 @@ _POLL_INTERVAL_SEC = 0.25
 
 
 def is_healthy(gateway_url: str, timeout_sec: float = 2.0) -> bool:
-    """True if a gateway answers /health at `gateway_url`."""
+    """True if a gateway answers /health at `gateway_url` RIGHT NOW.
+
+    Single probe, no retry. `timeout_sec` bounds a slow *response*; it does
+    NOT wait for a port to appear — a closed port refuses the connection
+    immediately. To wait for a booting gateway, use `wait_until_healthy`.
+    """
     try:
         r = httpx.get(f"{gateway_url.rstrip('/')}/health", timeout=timeout_sec)
     except httpx.HTTPError:
@@ -50,6 +55,28 @@ def is_healthy(gateway_url: str, timeout_sec: float = 2.0) -> bool:
     return r.status_code == 200
 
 
+def wait_until_healthy(gateway_url: str, timeout_sec: float | None = None) -> bool:
+    """Poll /health until it answers or `timeout_sec` elapses.
+
+    Startup is not instant: the gateway's lifespan awaits session rehydration
+    and the first policy-snapshot fetch, both round-trips to the control tower,
+    before uvicorn binds. Probing once right after launching it reports a false
+    "NOT RUNNING" on a gateway that is merely still booting.
+
+    `timeout_sec=None` resolves `_BOOT_TIMEOUT_SEC` at CALL time, not at import
+    time — a default argument would freeze the module constant into the
+    signature and ignore any later override.
+    """
+    if timeout_sec is None:
+        timeout_sec = _BOOT_TIMEOUT_SEC
+    deadline = time.time() + timeout_sec
+    while time.time() < deadline:
+        if is_healthy(gateway_url, timeout_sec=1.0):
+            return True
+        time.sleep(_POLL_INTERVAL_SEC)
+    return False
+
+
 def find_executable() -> str | None:
     """Locate the `agentgov-gateway` entry point.
 
@@ -109,11 +136,8 @@ def start_detached(gateway_url: str) -> tuple[bool, str]:
     finally:
         log_fh.close()
 
-    deadline = time.time() + _BOOT_TIMEOUT_SEC
-    while time.time() < deadline:
-        if is_healthy(gateway_url, timeout_sec=1.0):
-            return True, f"started; logging to {GATEWAY_LOG}"
-        time.sleep(_POLL_INTERVAL_SEC)
+    if wait_until_healthy(gateway_url):
+        return True, f"started; logging to {GATEWAY_LOG}"
 
     return False, (
         f"started but did not answer /health within {int(_BOOT_TIMEOUT_SEC)}s.\n"
@@ -141,6 +165,8 @@ def log_tail(lines: int = 15) -> str:
     except OSError as e:
         return f"(could not read {GATEWAY_LOG}: {e})"
     tail = content[-lines:]
+    if not tail:
+        return f"({GATEWAY_LOG} is empty — the gateway has not logged anything yet)"
     body = "\n".join(f"  {ln}" for ln in tail)
     return f"Last {len(tail)} line(s) of {GATEWAY_LOG}:\n{body}"
 

agentgov_cli-0.1.5/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.3 → agentgov_cli-0.1.5}/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.3"
+version = "0.1.5"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -37,18 +37,28 @@ 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",
 ]

agentgov_cli-0.1.3/agentgov_cli/commands/install.py

@@ -1,160 +0,0 @@
-"""`agentgov install` — copies client assets to ~/.claude/, prints managed-settings.json.
-
-The managed-settings.json is printed to stdout (with the admin-visible path per OS)
-so an administrator can drop it into the OS-managed path. That path is ROOT-owned;
-we do NOT try to write it — the CLI runs as the developer.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import platform
-import shutil
-import sys
-from pathlib import Path
-
-import typer
-from rich.console import Console
-
-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.
-ASSET_ROOTS = [
-    Path(__file__).resolve().parent.parent.parent.parent / "client_assets",
-    Path(sys.prefix) / "share" / "agentgov" / "client_assets",
-]
-
-
-def run(
-    gateway_url: str = typer.Option(
-        "http://localhost:8000",
-        "--gateway-url",
-        "--gateway",  # alias — earlier docs called it --gateway
-        envvar="AGENTGOV_GATEWAY_URL",
-        help="URL of the local AgentGov gateway (usually http://localhost:8000).",
-    ),
-    force: bool = typer.Option(False, "--force", help="Overwrite existing hooks/statusline."),
-) -> None:
-    """Install hooks + statusline + slash commands into ~/.claude/.
-
-    Also writes a ready-to-copy managed-settings.json to
-    ~/.agentgov/managed-settings.json — save that file at the OS-managed path
-    (needs sudo/admin) to force ALL Claude Code processes on this machine —
-    terminal AND VS Code extension — through the gateway.
-    """
-    src = _find_assets()
-    dest = Path.home() / ".claude"
-    dest.mkdir(exist_ok=True)
-
-    hooks_src = src / "hooks"
-    hooks_dest = dest / "agentgov-hooks"
-    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)
-        for h in hooks_dest.glob("*.py"):
-            h.chmod(0o755)
-        console.print(f"[green]Copied[/] hooks → {hooks_dest}")
-
-    statusline_src = src / "statusline"
-    statusline_dest = dest / "agentgov-statusline"
-    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)
-        for h in statusline_dest.glob("*.sh"):
-            h.chmod(0o755)
-        console.print(f"[green]Copied[/] statusline → {statusline_dest}")
-
-    commands_dest = dest / "commands"
-    commands_dest.mkdir(exist_ok=True)
-    shutil.copy2(src / "commands" / "workitem.md", commands_dest / "workitem.md")
-    console.print(f"[green]Copied[/] /workitem slash command → {commands_dest / 'workitem.md'}")
-
-    settings = _build_managed_settings(gateway_url, hooks_dest, statusline_dest)
-    settings_json = json.dumps(settings, indent=2)
-
-    # Write to a stable local path so the admin can `sudo cp` it into place
-    # without having to redirect stdout carefully.
-    local_settings_path = Path.home() / ".agentgov" / "managed-settings.json"
-    local_settings_path.parent.mkdir(parents=True, exist_ok=True)
-    local_settings_path.write_text(settings_json + "\n")
-    local_settings_path.chmod(0o644)
-
-    target_path = _managed_settings_path()
-    console.rule("[bold]managed-settings.json[/]")
-    console.print(f"Written locally to: [cyan]{local_settings_path}[/]")
-    console.print(f"Target install path: [cyan]{target_path}[/]\n")
-    console.print("[bold]To govern the VS Code extension too, run:[/]")
-    if platform.system() == "Windows":
-        console.print(
-            f'  Copy-Item "{local_settings_path}" "{target_path}" -Force'
-        )
-    else:
-        parent = str(Path(target_path).parent)
-        console.print(
-            f"  sudo mkdir -p {parent} && sudo cp {local_settings_path} {target_path}"
-        )
-    console.print(
-        "\nThen fully quit VS Code and reopen — the extension now routes through the gateway."
-    )
-    console.print("\n[dim]Contents (for reference):[/]")
-    console.print(settings_json)
-
-
-def _find_assets() -> Path:
-    for root in ASSET_ROOTS:
-        if root.exists():
-            return root
-    raise FileNotFoundError(f"client_assets/ not found in any of: {ASSET_ROOTS}")
-
-
-def _build_managed_settings(
-    gateway_url: str, hooks_dest: Path, statusline_dest: Path
-) -> dict[str, object]:
-    return {
-        "env": {
-            "ANTHROPIC_BASE_URL": gateway_url,
-            "AGENTGOV_LOOPBACK_PORT": os.environ.get("AGENTGOV_LOOPBACK_PORT", "8788"),
-        },
-        # apiKeyHelper disabled — Claude Code must use the agk_ key from the wrapper env.
-        "apiKeyHelper": "",
-        "hooks": {
-            "PreToolUse": [
-                {
-                    "matcher": "Read|Write|Edit|Glob|Grep|Bash|NotebookEdit",
-                    "hooks": [
-                        {"type": "command", "command": str(hooks_dest / "pretooluse_pathguard.py")}
-                    ],
-                }
-            ],
-            "SessionStart": [
-                {
-                    "hooks": [
-                        {"type": "command", "command": str(hooks_dest / "sessionstart_register.py")}
-                    ]
-                }
-            ],
-        },
-        "statusLine": {
-            "type": "command",
-            "command": str(statusline_dest / "agentgov_statusline.sh"),
-        },
-        # Permissions baseline: developers may NOT override the base URL or hooks.
-        "permissions": {
-            "allow": [],
-            "deny": [],
-        },
-    }
-
-
-def _managed_settings_path() -> str:
-    sysname = platform.system()
-    if sysname == "Darwin":
-        return "/Library/Application Support/ClaudeCode/managed-settings.json"
-    if sysname == "Windows":
-        return r"C:\ProgramData\ClaudeCode\managed-settings.json"
-    return "/etc/claude-code/managed-settings.json"