agentgov-cli 0.1.16__tar.gz → 0.1.18__tar.gz

{agentgov_cli-0.1.16 → agentgov_cli-0.1.18}/PKG-INFO

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

{agentgov_cli-0.1.16 → agentgov_cli-0.1.18}/agentgov_cli/client_assets/hooks/pretooluse_pathguard.py

@@ -38,12 +38,65 @@ from collections.abc import Iterator
 from datetime import datetime, timezone
 from pathlib import Path
 
+def _sane_repo_root(value: str) -> str:
+    """Accept an AGENTGOV_REPO_ROOT only if it could really be a repository.
+
+    THE HOLE THIS CLOSES. The env var was trusted absolutely, so
+    `AGENTGOV_REPO_ROOT=/` made every path on the machine "inside the authorized
+    root" and the tool plane allowed everything — including /etc/shadow — while
+    every other check still reported the machine governed. One exported variable,
+    no error, no log line, governance gone. That inverts the prime directive in
+    CLAUDE.md §1 exactly as a deleted hook did (§13 gap #31): bypassing produced
+    UNGOVERNED access rather than none.
+
+    THE RULE: a root may not be your home directory, nor anything containing it.
+
+    That is deliberately narrow. It rejects every value that actually disables
+    the guard — `/`, `/home`, `/Users`, `$HOME` itself — because authorising any
+    of those puts ~/.ssh, ~/.claude and every other repository inside the
+    "authorized" tree at once. It does NOT require the root to be a git work
+    tree, which was the first attempt and was wrong: the hook is also used
+    against scratch directories and test fixtures that are legitimately not
+    repositories, and a check that strict turns a governance control into a
+    reason to stop using it.
+
+    An unusable value is DISCARDED, not fatal. Returning "" falls through to the
+    normal resolution — CLAUDE_PROJECT_DIR, then cwd — which still fails closed
+    when nothing is found. Refusing outright would let anyone disable a
+    developer's editor by exporting one bad variable, trading a permissive bug
+    for a denial-of-service one.
+    """
+    root = (value or "").strip()
+    if not root:
+        return ""
+    try:
+        p = Path(root).expanduser().resolve()
+    except (OSError, RuntimeError):
+        return ""
+    if not p.is_dir():
+        return ""
+    # True only at a filesystem root, on POSIX and Windows alike, without
+    # hardcoding "/" or a drive-letter pattern.
+    if p.parent == p:
+        return ""
+    try:
+        home = Path.home().resolve()
+    except (OSError, RuntimeError):
+        return str(p)
+    # `p == home` or `home` beneath `p`: both authorise the whole home
+    # directory, and with it every credential and every other checkout.
+    if p == home or p in home.parents:
+        return ""
+    return str(p)
+
+
 # The authorized repository root. Resolved in main() from the hook payload,
 # 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", "")
+# sessions and the test-suite behave exactly as before — but only after
+# `_sane_repo_root` has confirmed it names something that could be a repository.
+REPO_ROOT = _sane_repo_root(os.environ.get("AGENTGOV_REPO_ROOT", ""))
 
 # The directory Claude is working in, from the payload's `cwd`. Used as the
 # base for relative paths. Previously this was the HOOK process's own cwd,

{agentgov_cli-0.1.16 → agentgov_cli-0.1.18}/agentgov_cli/client_assets/hooks/userpromptsubmit_workitem.py

@@ -209,6 +209,78 @@ def parse_marked_ref(prompt: str) -> tuple[str, str]:
     return ref, remainder
 
 
+# Public, no sign-in required. Deliberately NOT the dashboard's /setup page: a
+# developer who cannot bind often cannot sign in either — their account may not
+# exist yet, or the blocker IS the account — so troubleshooting behind a login is
+# unreachable exactly when it is needed. Overridable for self-hosted deployments.
+HELP_URL = (os.environ.get("AGENTGOV_HELP_URL") or "https://www.aicodekeyshare.com/help").rstrip("/")
+
+# What each failure code means to a PERSON, and the single next action that
+# resolves it. Written as an instruction, not a diagnosis: "ask your admin to
+# grant this repository" is actionable, "REPO_NOT_REGISTERED" is not.
+_BIND_FAILURE_HELP: dict[str, tuple[str, str]] = {
+    "repo_not_registered": (
+        "This repository has not been granted to you.",
+        "Ask an admin to add it on the Grants page. Until then Claude Code cannot "
+        "run here — this is the repo lock working, not a fault.",
+    ),
+    "grant_expired": (
+        "Your access to this repository has expired.",
+        "Ask an admin to renew the grant on the Grants page.",
+    ),
+    "user_inactive": (
+        "Your account is not active.",
+        "Ask an admin to reactivate it on the Team page.",
+    ),
+    "session_not_registered": (
+        "The control tower has no record of this editor session.",
+        "Usually a dropped connection. Send the prompt once more — the hook "
+        "re-registers automatically. If it repeats, the tower is unreachable from "
+        "this machine.",
+    ),
+    "work_item_invalid": (
+        "That work item could not be validated with your tracker.",
+        "Check the id, or use a short label instead — any text in brackets works.",
+    ),
+}
+
+
+def bind_failure_message(ref: str, repo: str, code: str) -> str:
+    """Explain why a work item that WAS supplied could not be bound.
+
+    The message this replaces rendered the generic marker guidance, which asks
+    the reader to supply a work item — the thing they had just supplied. It named
+    no cause, so there was nothing to act on, and offered no exit, so retyping the
+    same marker was the only move. A customer reported it as "a settings checking
+    screen which is not taking to right settings to fix", which is an accurate
+    description of a loop.
+
+    Every branch here ends with something the developer can DO, and a link to a
+    page they can open without signing in.
+    """
+    what, action = _BIND_FAILURE_HELP.get(
+        code.lower(),
+        (
+            "The work item could not be bound.",
+            "Send the prompt once more. If it repeats, run `agentgov doctor` — it "
+            "checks each step in order and names the first one that is failing.",
+        ),
+    )
+    anchor = code.lower().replace("_", "-") if code.lower() in _BIND_FAILURE_HELP else "binding"
+    return (
+        "\U0001f4cc AgentGov: could not bind to '" + ref + "'.\n"
+        "   Repository: " + repo + "\n"
+        "\n"
+        "   " + what + "\n"
+        "   " + action + "\n"
+        "\n"
+        "   Full troubleshooting (no sign-in needed):\n"
+        "   " + HELP_URL + "#" + anchor + "\n"
+        "\n"
+        "   Your prompt was not sent and no tokens were used.\n"
+    )
+
+
 def marker_guidance(repo: str = "", reason: str = "") -> str:
     """The one message that teaches the marker form.
 
@@ -439,7 +511,7 @@ def _bind_attempt(session_id: str, ref: str) -> tuple[int, dict]:
         return 0, {}
 
 
-def _bind_root(session_id: str, ref: str, cwd: str) -> bool:
+def _bind_root(session_id: str, ref: str, cwd: str) -> tuple[bool, str]:
     """Bind the session to `ref` as its ROOT work item.
 
     A bind with NO parent is the developer naming their work, so the gateway
@@ -459,10 +531,18 @@ def _bind_root(session_id: str, ref: str, cwd: str) -> bool:
     whatever state it was already in: still bound to the previous item, or still
     unbound and therefore answered with the guidance message. Neither loses the
     prompt.
+
+    RETURNS (ok, reason). The reason used to be computed here and thrown away on
+    every failure path, so a developer who DID name a work item was answered with
+    "start your prompt with a work item in square brackets" — the one thing they
+    had just done. That message is a dead end: it asks for what was already
+    supplied, names no cause, and offers no way out, so the only remaining move is
+    to type the same thing again. Carrying the reason out is what lets the caller
+    say which of the several possible failures actually happened.
     """
     status, payload = _bind_attempt(session_id, ref)
     if 200 <= status < 300:
-        return True
+        return True, ""
 
     code = ""
     err = payload.get("error")
@@ -477,11 +557,19 @@ def _bind_root(session_id: str, ref: str, cwd: str) -> bool:
         # key needs. Only retry when that actually succeeded — a second bind
         # against a still-missing session would fail identically.
         if not _register(session_id, cwd):
-            return False
-        status, _ = _bind_attempt(session_id, ref)
-        return 200 <= status < 300
+            return False, "session_not_registered"
+        status, retry_payload = _bind_attempt(session_id, ref)
+        if 200 <= status < 300:
+            return True, ""
+        retry_err = retry_payload.get("error")
+        retry_code = ""
+        if isinstance(retry_err, dict):
+            retry_code = str(retry_err.get("code") or "")
+        elif isinstance(retry_err, str):
+            retry_code = retry_err
+        return False, retry_code or f"http_{status}"
 
-    return False
+    return False, code or f"http_{status}"
 
 
 def _auto_child(
@@ -1451,6 +1539,11 @@ def main() -> None:
     # below sees the session the developer just named rather than the one they
     # happened to be on. This is what removes the second round trip: naming the
     # work and doing the work are one message.
+    # Why a bind that was attempted did not land. Empty means either no
+    # marker was given or the bind succeeded — the final gate tells those two
+    # apart by whether `ref` is set.
+    bind_failure = ""
+
     if ref:
         # Bind would 409 on a session with no upstream row — `work_item_bindings`
         # has a foreign key onto it. Registering first turns a gateway restart
@@ -1468,13 +1561,18 @@ def main() -> None:
         # drift counters, so re-binding the same ref on every prompt would zero
         # `prompts_since_bind` every turn and no drift signal could accumulate.
         current_root = str(data.get("root_work_item_ref") or data.get("work_item_ref") or "")
-        if (
-            repaired
-            and current_root.strip().casefold() != ref.casefold()
-            and _bind_root(session_id, ref, cwd)
-            and (refreshed := _binding(session_id)) is not None
-        ):
-            data = refreshed
+        if not repaired:
+            # The session could not be registered upstream, so a bind cannot
+            # land. Named rather than folded into the generic guidance, because
+            # "we could not reach the control tower" and "you did not name a work
+            # item" call for completely different actions from the developer.
+            bind_failure = "session_not_registered"
+        elif current_root.strip().casefold() != ref.casefold():
+            ok, bind_failure = _bind_root(session_id, ref, cwd)
+            if ok and (refreshed := _binding(session_id)) is not None:
+                data = refreshed
+        # An unchanged marker is not a failure — the session is already bound to
+        # it, and re-binding would reset the drift counters for nothing.
 
     if data.get("bound"):
         # The ROOT is the item the developer named with `/workitem`. Once
@@ -1568,6 +1666,12 @@ def main() -> None:
     # No gateway downstream: this hook is the only gate, so it blocks and says
     # so on every channel at once.
     repo = data.get("repo") or "this repository"
+    if ref and bind_failure:
+        # THE FIX. Reaching here with a marker in hand used to render the generic
+        # "start your prompt with a work item" text — telling a developer to do
+        # the thing they had just done, with no cause and no exit. Repeating it
+        # was the only move left, which is exactly the loop a customer reported.
+        _block(bind_failure_message(ref, repo, bind_failure))
     _block(
         marker_guidance(repo=repo)
         + "\n   Your prompt was not sent and no tokens were used.\n"

{agentgov_cli-0.1.16 → agentgov_cli-0.1.18}/agentgov_cli/main.py

@@ -21,6 +21,45 @@ app = typer.Typer(
     help="AgentGov CLI. See CLAUDE.md §6.3 + §13/§14.",
     no_args_is_help=True,
 )
+
+
+def _print_version(value: bool) -> None:
+    """`agentgov --version`.
+
+    The Setup page has told every developer to run this since it was written, and
+    until now it errored with "No such option: --version" — so the FIRST command
+    in the documented install path failed, for every client, on every machine.
+
+    It matters beyond tidiness. Half the diagnoses in this product turn on which
+    version is installed: `doctor`'s hook-version check compares assets against
+    `cli_version()`, and a stale CLI is the usual reason hooks are out of date.
+    Asking someone to report their version and handing them a command that does
+    not exist is the worst possible first impression of a governance tool.
+
+    Reads the installed distribution metadata rather than a hardcoded string, so
+    it cannot drift from what pip actually installed — the same source `doctor`
+    already compares against, which is what makes the two agree.
+    """
+    if not value:
+        return
+    from .asset_manifest import cli_version
+
+    typer.echo(f"agentgov {cli_version()}")
+    raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_print_version,
+        is_eager=True,
+        help="Show the installed CLI version and exit.",
+    ),
+) -> None:
+    """Root options. Commands are registered below."""
 app.command("login", help="Attach this machine to a user in the control tower (§13.5).")(login.run)
 app.command(
     "register-device",

{agentgov_cli-0.1.16 → agentgov_cli-0.1.18}/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.16"
+version = "0.1.18"
 description = "AgentGov CLI — wrap Claude Code, bind work items, check gateway health."
 readme = "README.md"
 license = { text = "Apache-2.0" }