agentgov-cli 0.1.8__tar.gz → 0.1.11__tar.gz

{agentgov_cli-0.1.8 → agentgov_cli-0.1.11}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: agentgov-cli
-Version: 0.1.8
+Version: 0.1.11
 Summary: AgentGov CLI — wrap Claude Code, bind work items, check gateway health.
 Author: AgentGov Contributors
 License: Apache-2.0
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.2
 Requires-Dist: pydantic>=2.9.0
 Requires-Dist: pynacl>=1.5.0

agentgov_cli-0.1.11/agentgov_cli/asset_manifest.py

@@ -0,0 +1,205 @@
+"""Provenance for the client assets AgentGov installs into ~/.claude/.
+
+WHY THIS EXISTS
+---------------
+Nothing in the product could tell "installed" from "current", and five separate
+layers all needed that one fact:
+
+  * `agentgov install` skipped the hooks directory whenever it already existed,
+    so the documented upgrade (`pip install -U` + `agentgov install`) refreshed
+    the CLI and left the OLD hooks in place. Every hook fix we shipped stopped
+    at the machines that already had AgentGov.
+  * The setup page's Step 0 preflight printed `READY -> nothing to do` on the
+    strength of three hook REGISTRATIONS, never asking whether the registered
+    files were current — so it actively confirmed a broken machine as healthy.
+  * `agentgov doctor` checked presence, executability and registration. Never
+    content.
+  * `smoke-package` only ever installed into a pristine HOME, so the upgrade
+    path that every existing user takes was untested.
+
+That combination shipped a `UserPromptSubmit` hook whose block message went
+only to stderr — which the VS Code extension does not surface — so a governed
+session with no work item bound erased the prompt and displayed nothing at all.
+The fix existed in the repo for a while and could not reach anyone.
+
+A recorded hash per installed file answers the question all five were asking.
+
+WHY THE HASHES AND NOT JUST A VERSION STRING
+--------------------------------------------
+A version alone cannot separate the two reasons an installed file differs from
+the shipped one:
+
+  STALE     we wrote it, and a newer version has since shipped  -> overwrite,
+            silently, because it is ours and it is out of date.
+  MODIFIED  it matches neither what we shipped nor what we last wrote  -> the
+            developer edited it. Back it up before overwriting.
+
+Getting that distinction wrong in either direction is bad: silently eating a
+local edit, or burying every upgrade in `.bak` files and scary warnings.
+
+WHERE IT LIVES
+--------------
+Inside `~/.claude/agentgov-hooks/`, alongside the assets it describes, so that
+`agentgov uninstall` (which rmtrees that directory) disposes of it without
+needing to know it exists. The leading dot keeps it out of the `*.py` globs
+that install and doctor use to chmod and enumerate hooks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+MANIFEST_NAME = ".agentgov-manifest.json"
+
+# Asset source is discovered relative to the installed package (client_assets is
+# a sibling of the CLI package). In wheel installs we ship it as package data;
+# in a source checkout we look up-tree.
+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 / "client_assets",
+    # Source checkout: client_assets/ sits at the repo root (CLAUDE.md §4).
+    Path(__file__).resolve().parent.parent.parent / "client_assets",
+    # Legacy shared-data location, kept so older installs keep working.
+    Path(sys.prefix) / "share" / "agentgov" / "client_assets",
+]
+
+# Which source subdirectory lands in which directory under ~/.claude, and the
+# glob that selects the files install is responsible for. `managed-settings.json.tmpl`
+# sits at the source root and is deliberately absent: it is rendered into
+# ~/.agentgov/ for an admin to place, never copied into ~/.claude.
+_ASSET_DIRS: tuple[tuple[str, str, str], ...] = (
+    ("hooks", "agentgov-hooks", "*.py"),
+    ("statusline", "agentgov-statusline", "*.sh"),
+    ("commands", "commands", "*.md"),
+)
+
+
+def managed_assets(src: Path) -> list[tuple[str, str]]:
+    """(source-relative path, destination dir) for everything install owns.
+
+    Enumerated from the source tree rather than hardcoded so that adding an
+    asset makes it managed automatically. A hardcoded list is precisely what
+    let the statusline drift out of date without anything noticing — it was
+    never in whatever each layer happened to believe the asset set was.
+    """
+    out: list[tuple[str, str]] = []
+    for sub, dest_dir, pattern in _ASSET_DIRS:
+        for path in sorted((src / sub).glob(pattern)):
+            out.append((f"{sub}/{path.name}", dest_dir))
+    return out
+
+
+def find_assets() -> Path:
+    for root in ASSET_ROOTS:
+        if (root / "hooks").is_dir():
+            return root
+    raise FileNotFoundError(f"client_assets/ not found in any of: {ASSET_ROOTS}")
+
+
+def cli_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("agentgov-cli")
+    except Exception:
+        return "unknown"
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def hooks_dir(home: Path | None = None) -> Path:
+    return (home or Path.home()) / ".claude" / "agentgov-hooks"
+
+
+def manifest_path(home: Path | None = None) -> Path:
+    return hooks_dir(home) / MANIFEST_NAME
+
+
+def installed_path(rel: str, dest_dir: str, home: Path | None = None) -> Path:
+    """Where a shipped asset lands on disk."""
+    return (home or Path.home()) / ".claude" / dest_dir / Path(rel).name
+
+
+def load(home: Path | None = None) -> dict[str, str]:
+    """Recorded hash per asset from the last install. Empty when absent.
+
+    Absent is the normal state for every install predating this file, so it
+    must degrade quietly rather than raise.
+    """
+    path = manifest_path(home)
+    try:
+        data = json.loads(path.read_text())
+    except Exception:
+        return {}
+    assets = data.get("assets")
+    return assets if isinstance(assets, dict) else {}
+
+
+def load_version(home: Path | None = None) -> str:
+    try:
+        data = json.loads(manifest_path(home).read_text())
+    except Exception:
+        return ""
+    return str(data.get("version") or "")
+
+
+def save(assets: dict[str, str], home: Path | None = None) -> None:
+    path = manifest_path(home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(
+            {
+                "version": cli_version(),
+                "installed_at": datetime.now(UTC).isoformat(),
+                "assets": assets,
+            },
+            indent=2,
+        )
+        + "\n"
+    )
+
+
+def classify(rel: str, dest_dir: str, src: Path, home: Path | None = None) -> str:
+    """One of MISSING | OK | STALE | MODIFIED for a single installed asset."""
+    shipped = src / rel
+    target = installed_path(rel, dest_dir, home)
+    if not target.exists():
+        return "MISSING"
+    if not shipped.exists():
+        # Nothing to compare against — treat as fine rather than invent a fault.
+        return "OK"
+    current = sha256_file(target)
+    if current == sha256_file(shipped):
+        return "OK"
+    recorded = load(home).get(rel)
+    # No manifest (pre-manifest install) means we cannot prove we wrote it, so
+    # it is reported as MODIFIED and install will back it up. That is the safe
+    # direction: it happens at most once per machine, and it never destroys an
+    # edit we cannot account for.
+    return "STALE" if recorded and recorded == current else "MODIFIED"
+
+
+def drift(home: Path | None = None) -> list[tuple[str, str]]:
+    """(relative path, state) for every managed asset that is not OK."""
+    try:
+        src = find_assets()
+    except FileNotFoundError:
+        return []
+    out: list[tuple[str, str]] = []
+    for rel, dest_dir in managed_assets(src):
+        state = classify(rel, dest_dir, src, home)
+        if state != "OK":
+            out.append((rel, state))
+    return out

agentgov_cli-0.1.11/agentgov_cli/client_assets/commands/workitem.md

@@ -0,0 +1,58 @@
+---
+description: Bind this session to a work item — ticket id, URL, or any short label
+allowed-tools: Bash(agentgov workitem:*)
+argument-hint: <PROJ-1234 | https://tracker/issue/42 | any short label>
+---
+
+!`agentgov workitem --session "${CLAUDE_SESSION_ID}" -- '$ARGUMENTS'`
+
+The command above has already run and its output is shown. Relay that output to
+the user verbatim — do not restate, reformat, or interpret it — and then stop.
+
+If it reported a successful bind, simply acknowledge it and carry on with
+whatever the user was doing. If it reported a failure, show the message as-is;
+it already contains the remediation step.
+
+<!--
+WHY THIS FILE LOOKS THE WAY IT DOES
+===================================
+
+1. WHY A `!` SHELL BLOCK AND NOT A MODEL-DRIVEN TOOL CALL
+   An unbound session is DENIED by the gateway (WorkItemMiddleware →
+   NO_WORK_ITEM), so no model turn is possible until the bind succeeds. Asking
+   the model to run the bind would deadlock: the request that would fix the
+   problem is the request the problem blocks. The bind must therefore complete
+   entirely in the shell, before anything is sent upstream.
+
+2. WHY `${CLAUDE_SESSION_ID}` IS PASSED EXPLICITLY
+   Claude Code substitutes it into slash-command shell lines, and it is the same
+   id sent as `x-claude-code-session-id` on every API request — i.e. exactly the
+   key the gateway stores sessions under. Passing it is what lets this work in
+   the VS Code extension, with no `agentgov wrap` and no loopback listener on
+   :8788. Requiring that listener is what made `/workitem` fail for every editor
+   user.
+
+3. WHY `agentgov workitem` NEVER EXITS NON-ZERO
+   Claude Code aborts the entire invocation when a `!` command exits non-zero and
+   reports `Shell command failed for pattern "..."`. That message is Claude Code
+   quoting the shell line it tried to run — it is NOT AgentGov matching the
+   user's text against a pattern, and nothing here inspects the format of what
+   the user typed. Our real error text was being swallowed by it, which is why
+   the failure was unreadable. The CLI now reports every failure as ordinary
+   output with exit code 0.
+
+4. WHY `'$ARGUMENTS'` IS SINGLE-QUOTED
+   `$ARGUMENTS` is substituted as text into a shell line, so unquoted user input
+   would let `$(...)`, backticks, `;`, `|`, `&` and `>` be interpreted by the
+   shell. Single quotes make every one of those literal.
+
+   KNOWN GAP: a literal apostrophe in the user's text (e.g. `don't`) closes the
+   quote early and breaks the line. Anthropic's documentation does not state
+   whether Claude Code escapes `$ARGUMENTS` before substitution, so this could
+   not be settled from the docs and is deliberately not guessed at. The CLI
+   defends on its side by stripping a stray surrounding quote pair and by
+   joining all argv entries into one reference. The clean fix is a
+   `UserPromptExpansion` hook, which receives the typed text as structured JSON
+   and never involves a shell — revisit once that hook's schema and exit-code
+   semantics are documented.
+-->