agentgov-cli 0.1.0__py3-none-any.whl

agentgov_cli/__init__.py

@@ -0,0 +1,3 @@
+"""AgentGov CLI. Developer-laptop tool: wrap · workitem · status · doctor."""
+
+__version__ = "0.1.0"

agentgov_cli/commands/doctor.py

@@ -0,0 +1,168 @@
+"""`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()

agentgov_cli/commands/install.py

@@ -0,0 +1,122 @@
+"""`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
+
+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 = "http://localhost:8000",
+    force: bool = False,
+) -> None:
+    """Install hooks + statusline + slash commands into ~/.claude/."""
+    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)
+    console.rule("[bold]managed-settings.json[/]")
+    console.print(f"Ask your admin to save this file at:\n  {_managed_settings_path()}\n")
+    console.print(json.dumps(settings, indent=2))
+
+
+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"

agentgov_cli/commands/login.py

@@ -0,0 +1,74 @@
+"""`agentgov login` — obtain an AgentGov session token (CLAUDE.md §13.5).
+
+v1 implements a DEV-ONLY stub: the CLI accepts a bearer token you paste
+(from the dashboard) and stores it in ~/.agentgov/identity.json (0600).
+The real OAuth device-code flow lands with Auth0 in Phase 5; the file
+layout + tower endpoint are already device-code-shaped so the swap is
+transparent to `wrap`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def run(
+    tower_url: str = typer.Option(
+        None, "--tower", envvar="CONTROL_TOWER_URL", help="Control tower URL"
+    ),
+    token: str = typer.Option(
+        None,
+        "--token",
+        help="Paste your dev-admin token (development mode only). Prompts if omitted.",
+        prompt=False,
+    ),
+) -> None:
+    """Attach this machine to a user in the AgentGov control tower."""
+    tower = tower_url or os.environ.get("CONTROL_TOWER_URL") or "http://localhost:3000"
+
+    if not token:
+        console.print(
+            "[bold]Dev-mode login[/] — paste a dev-admin token from the dashboard, or "
+            "the literal string 'agentgov-dev-admin' to use the seeded ADMIN.",
+        )
+        token = typer.prompt("token", hide_input=True).strip()
+    else:
+        token = token.strip()
+
+    # Verify the token can list /api/devices (a low-risk authenticated call).
+    try:
+        r = httpx.get(
+            f"{tower.rstrip('/')}/api/devices",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+    except Exception as e:
+        console.print(f"[red]Cannot reach control tower at {tower}: {e}[/]")
+        raise typer.Exit(2) from e
+    if r.status_code == 401:
+        console.print("[red]Token rejected by control tower.[/]")
+        raise typer.Exit(2)
+    if r.status_code >= 400:
+        console.print(f"[red]Unexpected response from control tower: {r.status_code} {r.text}[/]")
+        raise typer.Exit(2)
+
+    # Persist.
+    identity_path = Path.home() / ".agentgov" / "identity.json"
+    identity_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "tower_url": tower,
+        "auth0_token": token,
+        # user_id + tenant_id populated on register-device response.
+    }
+    identity_path.write_text(json.dumps(payload, indent=2))
+    identity_path.chmod(0o600)
+    console.print(f"[green]✅ Logged in.[/] Identity saved to {identity_path}")
+    console.print("Next: [bold]agentgov register-device --name 'my-laptop'[/]")

agentgov_cli/commands/register_device.py

@@ -0,0 +1,137 @@
+"""`agentgov register-device` — first-run device registration (CLAUDE.md §14.1).
+
+Generates an X25519 keypair, sends the public key to the control tower's
+/api/devices route, receives back a device_id + gtw_ token, and persists
+them locally so the gateway can boot in device mode.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import socket
+import uuid
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def _machine_fingerprint() -> str:
+    """SHA-256 of hostname + best-effort MAC (uuid.getnode())."""
+    return hashlib.sha256(f"{socket.gethostname()}:{uuid.getnode():012x}".encode()).hexdigest()
+
+
+def _generate_x25519_keypair() -> tuple[str, str]:
+    """Return (private_b64, public_b64)."""
+    from nacl.public import PrivateKey
+
+    priv = PrivateKey.generate()
+    return (
+        base64.b64encode(bytes(priv)).decode(),
+        base64.b64encode(bytes(priv.public_key)).decode(),
+    )
+
+
+def run(
+    name: str = typer.Option(..., "--name", help="Human-readable device name, e.g. 'work-laptop'"),
+    upstream_mode: str = typer.Option(
+        "oauth_passthrough",
+        "--mode",
+        help="oauth_passthrough (default) or apikey_vault",
+    ),
+    tower_url: str = typer.Option(None, "--tower", envvar="CONTROL_TOWER_URL"),
+    gateway_runtime_dir: Path = typer.Option(
+        None,
+        "--runtime-dir",
+        envvar="AGENTGOV_GATEWAY_RUNTIME",
+        help="Where to write device_key.priv (must match gateway's POLICY_CACHE_PATH parent)",
+    ),
+) -> None:
+    if upstream_mode not in ("oauth_passthrough", "apikey_vault"):
+        console.print(f"[red]Invalid --mode {upstream_mode}[/]")
+        raise typer.Exit(2)
+
+    tower = tower_url or os.environ.get("CONTROL_TOWER_URL") or "http://localhost:3000"
+
+    identity_path = Path.home() / ".agentgov" / "identity.json"
+    if not identity_path.exists():
+        console.print("[red]No AgentGov identity found.[/] Run [bold]agentgov login[/] first.")
+        raise typer.Exit(2)
+    identity = json.loads(identity_path.read_text())
+    token = identity.get("auth0_token") or ""
+    if not token:
+        console.print("[red]Identity file is missing auth0_token.[/] Re-run `agentgov login`.")
+        raise typer.Exit(2)
+
+    # Generate keypair; write private key to the gateway runtime dir.
+    priv_b64, pub_b64 = _generate_x25519_keypair()
+    runtime_dir = gateway_runtime_dir or Path.home() / ".agentgov" / "gateway_runtime"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    priv_path = runtime_dir / "device_key.priv"
+    priv_path.write_text(priv_b64 + "\n")
+    priv_path.chmod(0o600)
+    (runtime_dir / "device_key.priv.pub").write_text(pub_b64 + "\n")
+
+    fingerprint = _machine_fingerprint()
+
+    console.print(f"[green]Generated device keypair[/] → {priv_path}")
+    console.print(f"  public: {pub_b64[:16]}...  fingerprint: {fingerprint[:16]}...")
+
+    # POST to control tower.
+    try:
+        r = httpx.post(
+            f"{tower.rstrip('/')}/api/devices",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "name": name,
+                "public_key_b64": pub_b64,
+                "machine_fingerprint": fingerprint,
+                "upstream_mode": upstream_mode,
+            },
+            timeout=15.0,
+        )
+    except Exception as e:
+        console.print(f"[red]Registration failed: {e}[/]")
+        raise typer.Exit(2) from e
+    if r.status_code >= 400:
+        console.print(f"[red]Control tower rejected registration: {r.status_code} {r.text}[/]")
+        raise typer.Exit(2)
+
+    payload = r.json()
+    device = payload.get("device", {})
+    gtw_token = payload.get("gateway_service_token") or ""
+
+    # Persist gateway creds.
+    creds_path = Path.home() / ".agentgov" / "gateway_creds.json"
+    creds_path.write_text(
+        json.dumps(
+            {
+                "tower_url": tower,
+                "device_id": device.get("id"),
+                "device_name": device.get("name"),
+                "upstream_mode": device.get("upstream_mode"),
+                "gateway_service_token": gtw_token,
+            },
+            indent=2,
+        )
+    )
+    creds_path.chmod(0o600)
+
+    console.print(
+        f"[green]✅ Device registered.[/] id={device.get('id')} mode={device.get('upstream_mode')}"
+    )
+    console.print(f"gateway_service_token saved to {creds_path}")
+    console.print()
+    console.print("Now start (or restart) the gateway with these env vars — see .env:")
+    console.print(f"  GATEWAY_SERVICE_TOKEN={gtw_token}")
+    console.print(f"  DEVICE_KEY_PATH={priv_path}")
+    console.print(f"  UPSTREAM_MODE={upstream_mode}")

agentgov_cli/commands/status.py

@@ -0,0 +1,46 @@
+"""`agentgov status` — show current binding + session totals for cwd."""
+
+from __future__ import annotations
+
+import httpx
+import typer
+from rich.console import Console
+
+from ..port_resolver import list_active_sessions, resolve_port
+
+console = Console()
+
+
+def run(
+    session: str = typer.Option(None, "--session", envvar="AGENTGOV_SESSION"),
+    port: int = typer.Option(0, "--port", help="Override port; 0 = resolve"),
+) -> None:
+    resolved_port = port if port > 0 else resolve_port(session)
+    if resolved_port is None:
+        active = list_active_sessions()
+        if not active:
+            console.print("[yellow]No active AgentGov session.[/]")
+            console.print("Start one: [bold]agentgov wrap claude[/]")
+            raise typer.Exit(1)
+        console.print("[yellow]Multiple active sessions[/] — pass --session <id>:")
+        for sid, prt in active:
+            console.print(f"  {sid}  → :{prt}")
+        raise typer.Exit(1)
+
+    try:
+        r = httpx.post(f"http://127.0.0.1:{resolved_port}/status", timeout=5.0)
+        r.raise_for_status()
+        data = r.json()
+    except Exception:
+        console.print("[yellow]No active AgentGov session.[/]")
+        console.print("Start one: [bold]agentgov wrap claude[/]")
+        raise typer.Exit(1) from None
+
+    wi = data.get("work_item")
+    if not wi:
+        console.print("[red]📌 UNBOUND[/] — run `/workitem <ref>` in Claude Code.")
+    else:
+        console.print(
+            f"📌 {wi.get('external_id')} — [bold]{wi.get('title')}[/] ({wi.get('item_status')})"
+        )
+    console.print(f"tokens: {data.get('tokens', 0):,}   cost: ${data.get('cost_usd', 0):.2f}")

agentgov_cli/commands/workitem.py

@@ -0,0 +1,72 @@
+"""`agentgov workitem <ref>` — bind current session to a work item.
+
+Posts to the loopback admin listener started by `agentgov wrap`. Port is
+resolved dynamically (gap-P0-3): env AGENTGOV_LOOPBACK_PORT set by wrap →
+per-session state file → single-session convenience.
+"""
+
+from __future__ import annotations
+
+import httpx
+import typer
+from rich.console import Console
+
+from ..port_resolver import list_active_sessions, resolve_port
+
+console = Console()
+
+
+def run(
+    ref: str = typer.Argument(..., help="JIRA key, Notion URL, or PRJ-XXX id"),
+    session: str = typer.Option(
+        None,
+        "--session",
+        envvar="AGENTGOV_SESSION",
+        help="Session id (usually inherited from `agentgov wrap`).",
+    ),
+    port: int = typer.Option(
+        0,
+        "--port",
+        help="Override port explicitly. 0 = resolve from env/state.",
+    ),
+) -> None:
+    """Bind the current Claude Code session to <ref>."""
+    resolved_port = port if port > 0 else resolve_port(session)
+    if resolved_port is None:
+        _no_listener_help()
+        raise typer.Exit(2)
+
+    try:
+        r = httpx.post(
+            f"http://127.0.0.1:{resolved_port}/workitem",
+            json={"ref": ref},
+            timeout=15.0,
+        )
+    except Exception as e:
+        console.print(f"[red]No AgentGov loopback listener on :{resolved_port}.[/]")
+        _no_listener_help()
+        raise typer.Exit(2) from e
+
+    if r.status_code >= 400:
+        console.print(f"[red]bind failed:[/] {r.text}")
+        raise typer.Exit(2)
+
+    data = r.json()
+    wi = data.get("work_item") or {}
+    console.print(
+        f"[green]✅ Bound to[/] {wi.get('external_id')} — [bold]{wi.get('title')}[/] "
+        f"({wi.get('item_status')})"
+    )
+
+
+def _no_listener_help() -> None:
+    active = list_active_sessions()
+    if not active:
+        console.print(
+            "[red]No active AgentGov session.[/] Start one: [bold]agentgov wrap claude[/]"
+        )
+        return
+    if len(active) > 1:
+        console.print("[yellow]Multiple active sessions[/] — pass --session <id>:")
+        for sid, prt in active:
+            console.print(f"  {sid}  → :{prt}")

agentgov_cli/commands/wrap.py

@@ -0,0 +1,271 @@
+"""`agentgov wrap claude` — the launcher.
+
+1. Resolve repo root + normalized `origin`. Fail if not a git repo.
+2. Generate a UUIDv7 session id.
+3. Start the loopback admin listener on 127.0.0.1:8788 in a thread.
+4. Register the session with the gateway admin endpoint.
+5. Exec `claude` with the env described in CLAUDE.md §R-CLI2.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+
+from ..loopback import LoopbackListener
+
+console = Console()
+
+
+def run(
+    cmd: list[str] = typer.Argument(None, help="Command to launch (default: claude)"),
+    gateway_url: str = typer.Option(None, "--gateway", envvar="AGENTGOV_GATEWAY_URL"),
+    # port=0 → OS-assigned free port. The listener writes the bound port to
+    # ~/.agentgov/state/<session>.port so concurrent wraps don't collide
+    # (gap-P0-3). Set AGENTGOV_LOOPBACK_PORT to a fixed port only for tests.
+    loopback_port: int = typer.Option(0, "--loopback-port", envvar="AGENTGOV_LOOPBACK_PORT"),
+    credentials_path: Path = typer.Option(
+        Path.home() / ".agentgov" / "credentials",
+        "--credentials",
+        help="Path to the file storing the agk_ governance key.",
+    ),
+    resume_session: str = typer.Option(
+        None,
+        "--resume-session",
+        help=(
+            "Resume a previous AgentGov session id instead of generating a new one. "
+            "The gateway rehydrates the previous work-item binding (§13/gap-P1-7). "
+            "Use this when Claude Code's own --resume is bringing back an old conversation."
+        ),
+    ),
+) -> None:
+    """Wrap `claude` (or another command) in a governed session.
+
+    Session-resume semantics (gap-P1-7):
+      - Default: generate a NEW session id. Fresh session, no binding, first
+        prompt triggers NO_WORK_ITEM until /workitem runs.
+      - --resume-session <id>: re-use the given id. The gateway's boot
+        rehydration (gap-P0-2) already loads open work_item_bindings from
+        Supabase; a resumed session picks up its previous binding
+        transparently. If the binding is closed (unbound), you'll hit
+        NO_WORK_ITEM as usual.
+    """
+    repo_root, remote = _resolve_repo()
+    gov_key = _read_credentials(credentials_path)
+    if resume_session:
+        # Basic sanity: UUID-shape or reject.
+        import re
+
+        if not re.fullmatch(
+            r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
+            resume_session,
+        ):
+            console.print(f"[red]--resume-session must be a UUID; got {resume_session!r}[/]")
+            raise typer.Exit(2)
+        session_id = resume_session
+        console.print(f"[cyan]Resuming session[/] {session_id}")
+    else:
+        session_id = _uuid7_hex()
+
+    target = list(cmd) if cmd else ["claude"]
+    gateway = gateway_url or "http://localhost:8000"
+
+    # Register the session with the gateway. Also send hook hashes so the
+    # gateway can compare against expected values from the signed snapshot
+    # (gap-P0-4 hook integrity check). Mismatch = warning + audit row;
+    # depending on tenant `strict_hook_verification`, may refuse the session.
+    hook_hashes = _hash_hooks_best_effort()
+    _register_session(gateway, session_id, remote, repo_root, hook_hashes)
+
+    # Start loopback listener for `/workitem`, `status`, etc.
+    listener = LoopbackListener(port=loopback_port, gateway_url=gateway, session_id=session_id)
+    t = threading.Thread(target=listener.serve_forever, daemon=True)
+    t.start()
+    # Wait briefly for the listener to bind + write its port file (usually ~ms).
+    _wait_for_port(listener)
+
+    env = os.environ.copy()
+    # Export the ACTUAL bound port so slash commands + `agentgov workitem`
+    # find this session's listener even under concurrent wraps.
+    if listener.port is not None:
+        env["AGENTGOV_LOOPBACK_PORT"] = str(listener.port)
+    # In personal (oauth_passthrough) mode gov_key is "" and we leave whatever
+    # ANTHROPIC_API_KEY (or Anthropic OAuth session) was already set intact.
+    if gov_key:
+        env["ANTHROPIC_API_KEY"] = gov_key
+    env["ANTHROPIC_BASE_URL"] = gateway
+    env["AGENTGOV_SESSION"] = session_id
+    env["AGENTGOV_REPO"] = remote
+    env["AGENTGOV_REPO_ROOT"] = str(repo_root)
+    # Claude Code forwards ANTHROPIC_CUSTOM_HEADERS as JSON.
+    env["ANTHROPIC_CUSTOM_HEADERS"] = _custom_headers_json(session_id, remote, repo_root)
+
+    console.print(f"[green]AgentGov[/] wrapping {' '.join(target)}")
+    console.print(f"  session: {session_id}")
+    console.print(f"  repo:    {remote}")
+    console.print(f"  gateway: {gateway}")
+
+    # Launch — subprocess.call to keep pipes correct + return exit code.
+    try:
+        rc = subprocess.call(target, env=env, cwd=str(repo_root))
+    finally:
+        _end_session(gateway, session_id)
+    sys.exit(rc)
+
+
+def _wait_for_port(listener: LoopbackListener, timeout_sec: float = 2.0) -> None:
+    """Block until listener.port is set (i.e. socketserver bound) or timeout."""
+    import time as _time
+
+    deadline = _time.time() + timeout_sec
+    while listener.port is None and _time.time() < deadline:
+        _time.sleep(0.01)
+
+
+def _resolve_repo() -> tuple[Path, str]:
+    try:
+        root = subprocess.check_output(["git", "rev-parse", "--show-toplevel"], text=True).strip()
+    except subprocess.CalledProcessError as e:
+        console.print(
+            "[red]Not a git repository.[/] Run inside a repo that has been granted to you."
+        )
+        raise typer.Exit(2) from e
+    try:
+        remote = subprocess.check_output(["git", "remote", "get-url", "origin"], text=True).strip()
+    except subprocess.CalledProcessError as e:
+        console.print("[red]No `origin` remote configured on this repository.[/]")
+        raise typer.Exit(2) from e
+    return Path(root), remote
+
+
+def _read_credentials(path: Path) -> str:
+    """Return the `agk_` governance key if present; empty string in personal mode.
+
+    Personal-mode devices (oauth_passthrough) don't need an agk_ key — Claude
+    Code uses its own OAuth. In that case we return "" and Claude Code sends
+    whatever `ANTHROPIC_API_KEY` was already set (or its OAuth bearer via
+    ANTHROPIC_BASE_URL). The gateway will identify the user by device.
+    """
+    if not path.exists():
+        # OK in personal mode. Warn once and continue.
+        console.print(
+            f"[yellow]No agk_ key at {path}[/]. Assuming personal (oauth_passthrough) mode."
+        )
+        return ""
+    if path.stat().st_mode & 0o077:
+        console.print(
+            f"[red]Credentials at {path} have loose permissions.[/] Run: chmod 600 {path}"
+        )
+        raise typer.Exit(2)
+    return path.read_text().strip()
+
+
+def _uuid7_hex() -> str:
+    # Standard-library uuid doesn't provide v7 pre-3.13. We use time-based prefix
+    # plus urandom suffix for monotonicity; not RFC-perfect but sufficient here.
+    import os as _os
+    import uuid as _uuid
+
+    ms = int(time.time() * 1000)
+    prefix = ms.to_bytes(6, "big")
+    rand = _os.urandom(10)
+    b = bytearray(prefix + rand)
+    # version 7 + RFC 4122 variant bits
+    b[6] = (b[6] & 0x0F) | 0x70
+    b[8] = (b[8] & 0x3F) | 0x80
+    return str(_uuid.UUID(bytes=bytes(b)))
+
+
+def _register_session(
+    gateway: str,
+    session_id: str,
+    remote: str,
+    repo_root: Path,
+    hook_hashes: dict[str, str] | None = None,
+) -> None:
+    try:
+        r = httpx.post(
+            f"{gateway.rstrip('/')}/admin/session/register",
+            headers={"content-type": "application/json"},
+            json={
+                "session_id": session_id,
+                "repo": remote,
+                "repo_root": str(repo_root),
+                "hook_hashes": hook_hashes or {},
+            },
+            timeout=5.0,
+        )
+        r.raise_for_status()
+        payload = r.json()
+        # Gateway may report hook mismatch here — surface immediately to the dev.
+        warnings = payload.get("warnings") or []
+        for w in warnings:
+            console.print(f"[yellow]⚠ {w}[/]")
+        if payload.get("state") == "REFUSED":
+            console.print(
+                f"[red]Gateway refused this session:[/] {payload.get('reason', 'unknown')}"
+            )
+            raise typer.Exit(2)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        console.print(
+            f"[yellow]Warning:[/] could not register session with gateway ({e}). Continuing."
+        )
+
+
+def _hash_hooks_best_effort() -> dict[str, str]:
+    """Return {filename: hex_sha256} for each installed AgentGov hook.
+
+    Best-effort: missing hooks return an empty dict. The gateway decides
+    whether that's a failure (`strict_hook_verification`) or just a warning.
+    """
+    import hashlib
+
+    hooks_dir = Path.home() / ".claude" / "agentgov-hooks"
+    out: dict[str, str] = {}
+    if not hooks_dir.exists():
+        return out
+    for p in hooks_dir.glob("*.py"):
+        try:
+            h = hashlib.sha256()
+            with p.open("rb") as f:
+                for chunk in iter(lambda: f.read(65536), b""):
+                    h.update(chunk)
+            out[p.name] = h.hexdigest()
+        except OSError:
+            continue
+    return out
+
+
+def _end_session(gateway: str, session_id: str) -> None:
+    import contextlib
+
+    # Best-effort: if the gateway is down we don't want to error on shutdown.
+    with contextlib.suppress(Exception):
+        httpx.post(
+            f"{gateway.rstrip('/')}/admin/session/register",
+            json={"session_id": session_id, "action": "end"},
+            timeout=3.0,
+        )
+
+
+def _custom_headers_json(session_id: str, remote: str, repo_root: Path) -> str:
+    # Claude Code forwards this JSON as request headers.
+    import json as _json
+
+    return _json.dumps(
+        {
+            "X-AgentGov-Session": session_id,
+            "X-AgentGov-Repo": remote,
+            "X-AgentGov-Repo-Root": str(repo_root),
+        }
+    )

agentgov_cli/loopback.py

@@ -0,0 +1,122 @@
+"""127.0.0.1:8788 loopback admin listener (§R-CLI2 step 2).
+
+Backing the `/workitem` slash command + a way to query current binding.
+Talks to the gateway's admin endpoints. Every request is validated as
+local by binding to 127.0.0.1 (not 0.0.0.0).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import http.server
+import json
+import logging
+import socketserver
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+
+class LoopbackListener:
+    def __init__(self, port: int, gateway_url: str, session_id: str) -> None:
+        # port=0 → OS-assigned free port. After serve_forever() binds, the real
+        # port is available on self.port. We write it to a per-session state
+        # file so `agentgov workitem` can find the right listener even when
+        # multiple wraps run concurrently (gap-P0-3).
+        self._requested_port = port
+        self._port: int | None = None
+        self._gateway_url = gateway_url.rstrip("/")
+        self._session_id = session_id
+        self._state_dir = self._prep_state_dir()
+
+    @property
+    def port(self) -> int | None:
+        """The port the listener is actually bound to. None until serve_forever()."""
+        return self._port
+
+    def serve_forever(self) -> None:
+        parent = self  # closure
+
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def log_message(self, fmt: str, *args: Any) -> None:
+                # Route through logging instead of stderr spam.
+                log.debug("loopback: " + fmt, *args)
+
+            def _read_json(self) -> dict[str, Any]:
+                length = int(self.headers.get("content-length") or 0)
+                raw = self.rfile.read(length) if length > 0 else b"{}"
+                try:
+                    parsed: dict[str, Any] = json.loads(raw.decode("utf-8"))
+                    return parsed
+                except Exception:
+                    return {}
+
+            def _send_json(self, status: int, body: dict[str, Any]) -> None:
+                data = json.dumps(body).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def do_POST(self) -> None:
+                # ALL admin routes require the request comes from a loopback address.
+                if self.client_address[0] not in ("127.0.0.1", "::1"):
+                    self._send_json(403, {"error": "loopback_only"})
+                    return
+
+                path = self.path.split("?")[0]
+                if path == "/workitem":
+                    self._handle_workitem(self._read_json())
+                elif path == "/status":
+                    self._handle_status()
+                else:
+                    self._send_json(404, {"error": "unknown_route"})
+
+            def _handle_workitem(self, payload: dict[str, Any]) -> None:
+                ref = str(payload.get("ref") or "")
+                if not ref:
+                    self._send_json(400, {"error": "missing_ref"})
+                    return
+                # Ask the gateway (which relays to control-tower) to resolve+bind.
+                try:
+                    r = httpx.post(
+                        f"{parent._gateway_url}/admin/session/bind",
+                        json={"session_id": parent._session_id, "work_item_ref": ref},
+                        timeout=15.0,
+                    )
+                    r.raise_for_status()
+                    self._send_json(200, r.json())
+                except Exception as e:
+                    self._send_json(502, {"error": "bind_failed", "detail": str(e)})
+
+            def _handle_status(self) -> None:
+                # Serve from the state file the gateway writes to via SSE-ack path,
+                # or fall back to "unknown".
+                statefile = parent._state_dir / f"{parent._session_id}.json"
+                if statefile.exists():
+                    self._send_json(200, json.loads(statefile.read_text()))
+                else:
+                    self._send_json(200, {"work_item": None, "tokens": 0, "cost_usd": 0})
+
+        with socketserver.TCPServer(("127.0.0.1", self._requested_port), Handler) as httpd:
+            # Capture the actual bound port (may differ from _requested_port
+            # when caller passed 0). Write a session-scoped state file so
+            # `agentgov workitem` can look up the port by session id.
+            self._port = httpd.server_address[1]
+            port_file = self._state_dir / f"{self._session_id}.port"
+            port_file.write_text(str(self._port))
+            try:
+                httpd.serve_forever()
+            finally:
+                # Best-effort cleanup on shutdown.
+                with contextlib.suppress(FileNotFoundError):
+                    port_file.unlink()
+
+    def _prep_state_dir(self) -> Path:
+        p = Path.home() / ".agentgov" / "state"
+        p.mkdir(parents=True, exist_ok=True)
+        return p

agentgov_cli/main.py

@@ -0,0 +1,32 @@
+"""CLI root — dispatches to commands/*."""
+
+from __future__ import annotations
+
+import typer
+
+from .commands import doctor, install, login, register_device, status, workitem, wrap
+
+app = typer.Typer(
+    name="agentgov",
+    help="AgentGov CLI. See CLAUDE.md §6.3 + §13/§14.",
+    no_args_is_help=True,
+)
+app.command("login", help="Attach this machine to a user in the control tower (§13.5).")(login.run)
+app.command(
+    "register-device",
+    help="Generate device X25519 keypair + register with control tower (§14.1).",
+)(register_device.run)
+app.command(
+    "install", help="Install client assets into ~/.claude/ and print managed-settings.json."
+)(install.run)
+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-...).")(
+    workitem.run
+)
+app.command("status", help="Show current binding + session totals for cwd.")(status.run)
+app.command(
+    "doctor", help="Diagnose gateway reachability, hooks, managed settings, and safety rules."
+)(doctor.run)
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

agentgov_cli/port_resolver.py

@@ -0,0 +1,68 @@
+"""Resolve the loopback port for a session (gap-P0-3).
+
+Two lookup paths, tried in order:
+
+  1. AGENTGOV_LOOPBACK_PORT env — set by `agentgov wrap` in the child's
+     environment. Slash commands and same-terminal invocations get this
+     automatically.
+
+  2. `~/.agentgov/state/<session>.port` file, written by the LoopbackListener
+     when it binds. Useful for a second terminal that isn't a descendant of
+     `wrap` (e.g. developer runs `agentgov status` from a separate tmux pane).
+
+If neither works but exactly ONE port file exists in the state dir, use that
+(single-session case). Multiple port files with no env hint → ambiguous, we
+return None and the caller prints "which session?" guidance.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def resolve_port(session_id: str | None = None) -> int | None:
+    # 1) env
+    p_env = os.environ.get("AGENTGOV_LOOPBACK_PORT", "").strip()
+    if p_env:
+        try:
+            n = int(p_env)
+            if n > 0:
+                return n
+        except ValueError:
+            pass
+
+    # 2) session id → port file
+    state_dir = Path.home() / ".agentgov" / "state"
+    if session_id:
+        f = state_dir / f"{session_id}.port"
+        if f.exists():
+            try:
+                return int(f.read_text().strip())
+            except (OSError, ValueError):
+                pass
+
+    # 3) single-session convenience
+    if state_dir.exists():
+        port_files = list(state_dir.glob("*.port"))
+        if len(port_files) == 1:
+            try:
+                return int(port_files[0].read_text().strip())
+            except (OSError, ValueError):
+                pass
+
+    return None
+
+
+def list_active_sessions() -> list[tuple[str, int]]:
+    """Return [(session_id, port), ...] for all active listeners."""
+    state_dir = Path.home() / ".agentgov" / "state"
+    if not state_dir.exists():
+        return []
+    out: list[tuple[str, int]] = []
+    for f in state_dir.glob("*.port"):
+        try:
+            out.append((f.stem, int(f.read_text().strip())))
+        except (OSError, ValueError):
+            continue
+    return out

agentgov_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: agentgov-cli
+Version: 0.1.0
+Summary: AgentGov CLI — wrap Claude Code, bind work items, check gateway health.
+Author: AgentGov Contributors
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.12.5
+Requires-Dist: uuid7>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentgov
+
+The developer-laptop CLI for AgentGov.
+
+Wraps Claude Code to bind sessions to work items and enforce governance from a signed policy snapshot. Runs alongside `agentgov-gateway` (the local proxy) — this CLI handles login, device registration, session wrapping, work-item binding, and diagnostics.
+
+Part of the AgentGov project — see [github.com/deepakahu/agentGov](https://github.com/deepakahu/agentGov) for the full monorepo.
+
+## Install
+
+```bash
+pip install agentgov agentgov-gateway
+```
+
+## First-time setup
+
+```bash
+# Attach this machine to your AgentGov control tower
+agentgov login --tower https://your-agentgov.vercel.app
+
+# Register this device (generates an X25519 keypair, gets a gtw_ token)
+agentgov register-device --name "$(hostname)"
+
+# Drop Claude Code hooks + statusline + slash command into ~/.claude/
+agentgov install
+
+# Start the gateway (background)
+agentgov-gateway &
+```
+
+## Every day
+
+```bash
+# Run Claude Code through the governed gateway
+agentgov wrap claude
+
+# Bind the current session to a work item
+# (or use the /workitem slash command inside Claude Code)
+agentgov workitem PROJ-1234
+```
+
+## Diagnose
+
+```bash
+agentgov status    # what's my current binding, tokens, quota
+agentgov doctor    # is everything wired correctly
+```
+
+## Commands
+
+- `agentgov login` — attach this machine to a user in the control tower
+- `agentgov register-device` — generate device keypair + register with tower
+- `agentgov install` — drop client assets into `~/.claude/`
+- `agentgov wrap <cmd>` — wrap `claude` (or another command) in a governed session
+- `agentgov workitem <ref>` — bind the current session to a work item
+- `agentgov status` — show current binding + totals
+- `agentgov doctor` — diagnose the installation
+
+## License
+
+Apache-2.0

agentgov_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+agentgov_cli/__init__.py,sha256=MhFkd8l9GX1itDFyNS9mnohokruQWpeiq5nfHfxknYc,104
+agentgov_cli/loopback.py,sha256=NP7udIRg5yDnItDo_fJ8NgCH66TPUqHk5NgtUVqzbKA,5095
+agentgov_cli/main.py,sha256=YmcBR2KMJM_btA0YABhqxUHgaeHDWrHKI7glL3tkq1k,1152
+agentgov_cli/port_resolver.py,sha256=E6aKN73ABEQjN7h0OllkAh8azWDFp6-rPOGsRM8WPU0,2132
+agentgov_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentgov_cli/commands/doctor.py,sha256=qHwb5lIzpiSiXQUKWZ2gB7iXoWvQ03M7bDovbZuFsuQ,5865
+agentgov_cli/commands/install.py,sha256=Rr4TEC8vdlOLo64S5xy9k9wm9wt_hcv_jMMJ3V4mGTM,4343
+agentgov_cli/commands/login.py,sha256=lLm7RyD7CBUWmVxhuMcF7JMq5r2p-1MAVzs_JoJE1mY,2573
+agentgov_cli/commands/register_device.py,sha256=hNYMQv7hnxL4MYWOGwrYDPrZL43ew8BGHm595xJBp2E,4794
+agentgov_cli/commands/status.py,sha256=Rhvdn1bCere7mqNvkYj85scbLZU_ehV6U-3C5VI3QGk,1665
+agentgov_cli/commands/workitem.py,sha256=tuY-ExRNoWiYQAVLP1QP-K1rZqlLroJ6K3pVGK8ewSs,2163
+agentgov_cli/commands/wrap.py,sha256=x_XvN6XtKFZ-jZA3pTEFGHqA08BapLh1aI92LdisthU,10021
+agentgov_cli-0.1.0.dist-info/METADATA,sha256=cUXrkb7-Vxhk7uK3U__BFuBUMc2E7RRVpqR2XtbYg8U,2419
+agentgov_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agentgov_cli-0.1.0.dist-info/entry_points.txt,sha256=rqHQ0f65XZ2xMhubArHj5tfIqYApSGUwKM2se52U23Q,51
+agentgov_cli-0.1.0.dist-info/RECORD,,

agentgov_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentgov_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentgov = agentgov_cli.main:app