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

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

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

agentgov_cli-0.1.9/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.
+-->

{agentgov_cli-0.1.8 → agentgov_cli-0.1.9}/agentgov_cli/client_assets/hooks/userpromptsubmit_workitem.py

@@ -39,6 +39,12 @@ 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.
+#
+# NOTE: per Anthropic's hook reference, `UserPromptSubmit` does NOT fire for
+# slash commands at all — those raise `UserPromptExpansion` instead. So this
+# list is belt-and-braces, not the thing that lets `/workitem` through, and it
+# must not be relied on. Keep it: it costs nothing, and it still covers a
+# developer who types the command as plain text.
 ESCAPE_PREFIXES = ("/workitem", "/agentgov", "/help", "/status", "/doctor")
 
 
@@ -186,10 +192,11 @@ def main() -> None:
         "📌 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"
+        "   Run /workitem with anything that identifies the work — a ticket id,\n"
+        "   a URL, or a short label. There is no required format:\n"
+        "     /workitem PROJ-1234\n"
+        "     /workitem https://your-tracker/issue/42\n"
+        "     /workitem payment retry loop spike\n"
         "\n"
         "   Your prompt was not sent and no tokens were used.\n"
     )

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

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# AgentGov statusline (§R-CC3).
+#
+# Renders one of:
+#   🛡 <repo> │ 📌 <work item> │ 41% weekly · resets 08-18 09:00
+#   🛡 <repo> │ 📌 <work item> │ 8% context
+#   🛡 <repo> │ 📌 UNBOUND — /workitem required
+#
+# WHY THIS WAS REWRITTEN
+# ----------------------
+# It read $AGENTGOV_SESSION and a state file at ~/.agentgov/state/<session>.json.
+# Both only ever existed under `agentgov wrap`: the variable was exported by the
+# launcher, and the file was written by the loopback listener the launcher
+# started. In the VS Code extension neither exists, so the statusline printed
+#
+#     📌 UNGOVERNED — run agentgov wrap claude
+#
+# permanently — for sessions that were registered, bound and governed. It was the
+# main surface a developer would look at to confirm a bind had worked, and it was
+# reporting the opposite of the truth.
+#
+# Claude Code hands the statusline a JSON document on stdin containing
+# `session_id`, `workspace.repo`, `cost`, `context_window` and `rate_limits`
+# (documented at https://code.claude.com/docs/en/statusline.md). That is the same
+# session id the gateway keys sessions under, so the binding can be read straight
+# from the gateway with no wrapper, no exported variable and no state file.
+#
+# The body is Python rather than jq + `read`, because the previous word-splitting
+# approach corrupted any value containing a space — which now includes work-item
+# labels, since those are free text. It is held in a quoted heredoc so the shell
+# performs no substitution on it, and passed via -c so that stdin stays the JSON
+# Claude Code sent.
+
+set -u
+
+read -r -d '' AGENTGOV_STATUSLINE_PY <<'PYEOF'
+import json
+import os
+import sys
+import urllib.request
+from datetime import datetime, timezone
+
+GATEWAY = os.environ.get("AGENTGOV_GATEWAY_URL", "http://127.0.0.1:8000").rstrip("/")
+# Runs on every assistant message, so keep it tight. This is a loopback call to
+# an in-memory lookup; if it is slow, something is wrong and we show less rather
+# than stall the status bar.
+TIMEOUT = 1.0
+
+RED = "\033[31m"
+YELLOW = "\033[33m"
+GREEN = "\033[32m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+
+def payload():
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return {}
+
+
+def binding(session_id):
+    """Ask the gateway about this session. None means 'could not tell'."""
+    if not session_id:
+        return None
+    try:
+        url = GATEWAY + "/admin/session/" + str(session_id) + "/binding"
+        with urllib.request.urlopen(url, timeout=TIMEOUT) as r:
+            data = json.loads(r.read() or b"{}")
+        return data if isinstance(data, dict) else None
+    except Exception:
+        return None
+
+
+def repo_label(data, state):
+    """Prefer the repo the gateway registered, then Claude Code's, then the folder."""
+    if state and state.get("repo"):
+        return str(state["repo"])
+    repo = (data.get("workspace") or {}).get("repo") or {}
+    owner = repo.get("owner")
+    name = repo.get("name")
+    if owner and name:
+        return "{}/{}".format(owner, name)
+    cwd = (data.get("workspace") or {}).get("current_dir") or data.get("cwd") or ""
+    return os.path.basename(cwd.rstrip("/")) or "unknown"
+
+
+def shorten(text, limit=42):
+    """Work items are free text now, so a long label must not crowd out the rest."""
+    text = " ".join(str(text).split())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"
+
+
+def usage_segment(data):
+    """Weekly quota if Claude Code reported it, else context use, else cost.
+
+    These come from Claude Code itself, which is strictly more accurate than
+    anything AgentGov could accumulate locally between ingest acknowledgements.
+    """
+    week = (data.get("rate_limits") or {}).get("seven_day") or {}
+    pct = week.get("used_percentage")
+    if isinstance(pct, (int, float)):
+        color = RED if pct >= 85 else YELLOW if pct >= 60 else GREEN
+        seg = "{}{:.0f}% weekly{}".format(color, pct, RESET)
+        resets = week.get("resets_at")
+        if isinstance(resets, (int, float)):
+            when = datetime.fromtimestamp(resets, tz=timezone.utc).astimezone()
+            seg += when.strftime(" · resets %m-%d %H:%M")
+        return seg
+
+    ctx = (data.get("context_window") or {}).get("used_percentage")
+    if isinstance(ctx, (int, float)):
+        return "{}{:.0f}% context{}".format(DIM, ctx, RESET)
+
+    cost = (data.get("cost") or {}).get("total_cost_usd")
+    if isinstance(cost, (int, float)):
+        return "{}${:.2f}{}".format(DIM, cost, RESET)
+    return ""
+
+
+def main():
+    data = payload()
+    state = binding(data.get("session_id"))
+
+    parts = ["\U0001f6e1 " + repo_label(data, state)]
+
+    if state is None:
+        # Gateway unreachable. Say so plainly — "not bound" and "cannot tell"
+        # are different answers, and conflating them is what made the old
+        # statusline misleading.
+        parts.append("{}\U0001f4cc gateway offline{}".format(YELLOW, RESET))
+    elif state.get("bound"):
+        label = shorten(state.get("work_item_ref") or "bound")
+        parts.append("\U0001f4cc " + label)
+    else:
+        parts.append("{}\U0001f4cc UNBOUND — /workitem required{}".format(RED, RESET))
+
+    usage = usage_segment(data)
+    if usage:
+        parts.append(usage)
+
+    sys.stdout.write(" │ ".join(parts))
+
+
+main()
+PYEOF
+
+exec python3 -c "$AGENTGOV_STATUSLINE_PY"

{agentgov_cli-0.1.8 → agentgov_cli-0.1.9}/agentgov_cli/commands/install.py

@@ -140,6 +140,58 @@ def run(
     console.print("\n[dim]Contents (for reference):[/]")
     console.print(settings_json)
 
+    _print_next_steps(target_path)
+
+
+def _print_next_steps(managed_target: str) -> None:
+    """Say plainly what happens next, and what will NOT happen.
+
+    Installing hooks is not the last step, and on its own it changes nothing a
+    developer can see. Without this, `install` finishes on a wall of JSON and
+    the obvious conclusion is "it's set up" — then the work-item prompt never
+    appears and the install looks broken when it is behaving correctly.
+    """
+    governed_everywhere = Path(managed_target).exists()
+
+    console.rule("[bold]Next steps[/]")
+    console.print("[bold]1.[/] Fully quit and reopen Claude Code / VS Code.")
+    console.print(
+        "   [dim]Hooks are read when a session starts. A window that is already "
+        "open will not pick them up.[/]\n"
+    )
+
+    if governed_everywhere:
+        console.print(
+            "[bold]2.[/] Machine-wide settings are installed, so [green]every[/] Claude Code "
+            "session is governed."
+        )
+        console.print("   Open a granted repo and send a prompt — you will be asked to bind a "
+                      "work item.\n")
+    else:
+        console.print(
+            "[bold]2.[/] Choose how you want to be governed — "
+            "[yellow]until you do, nothing changes[/]:\n"
+        )
+        console.print("   [cyan]agentgov wrap claude[/]   (per session, no sudo)")
+        console.print(
+            "     Governs just that session. Plain `claude` and the VS Code extension "
+            "keep talking to Anthropic directly.\n"
+        )
+        console.print(
+            f"   [cyan]sudo cp ~/.agentgov/managed-settings.json {managed_target}[/]   "
+            "(whole machine)"
+        )
+        console.print(
+            "     The only way to govern the VS Code / Cursor extension. Requires sudo, and "
+            "means a stopped gateway blocks all Claude Code.\n"
+        )
+
+    console.print("[bold]3.[/] Check it took:  [cyan]agentgov doctor[/]")
+    console.print(
+        "   [dim]Step 1 CLIENT tells you whether anything is actually routed through the "
+        "gateway.[/]"
+    )
+
 
 def _agentgov_hook_entries(hooks_dest: Path) -> dict[str, list[dict[str, object]]]:
     """The hook registrations AgentGov owns, keyed by Claude Code event name."""
@@ -224,9 +276,16 @@ def _merge_user_settings(gateway_url: str, hooks_dest: Path, statusline_dest: Pa
     # 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}")
+    # Be precise about what this does and does not do. The earlier wording
+    # ("these run in every Claude Code session, including the VS Code
+    # extension") was wrong twice over: hooks load only at session start, and
+    # since 0.1.7 they intentionally do nothing in sessions that are not routed
+    # through the gateway. Overstating it makes the next step look broken when
+    # it is working exactly as designed.
     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.[/]"
+        "  [dim]Loaded when a Claude Code session STARTS — restart Claude Code.\n"
+        "  They act only on sessions routed through the gateway; other sessions are "
+        "left alone.[/]"
     )
 
 

agentgov_cli-0.1.9/agentgov_cli/commands/status.py

@@ -0,0 +1,72 @@
+"""`agentgov status` — show the current work-item binding for this session.
+
+Rewritten for the same reason as `agentgov workitem`: this asked the loopback
+listener on :8788 that only `agentgov wrap` starts, so in the VS Code extension
+it always answered "No active AgentGov session. Start one: agentgov wrap claude"
+about a session that was registered and working. The one command a developer
+runs to check whether their bind took effect was reporting the opposite of the
+truth.
+
+It now asks the gateway directly, keyed on Claude Code's own session id — the
+same identifier the gateway stores sessions under.
+"""
+
+from __future__ import annotations
+
+import httpx
+import typer
+from rich.console import Console
+
+from .workitem import DEFAULT_GATEWAY, _body, _resolve_session
+
+console = Console()
+
+
+def run(
+    session: str = typer.Option(
+        None,
+        "--session",
+        help="Claude Code session id. Defaults to $CLAUDE_SESSION_ID / $AGENTGOV_SESSION.",
+    ),
+    gateway: str = typer.Option(
+        None,
+        "--gateway",
+        envvar="AGENTGOV_GATEWAY_URL",
+        help=f"Gateway base URL (default {DEFAULT_GATEWAY}).",
+    ),
+) -> None:
+    """Report whether this session is bound, and to what."""
+    base = (gateway or DEFAULT_GATEWAY).rstrip("/")
+    session_id = _resolve_session(session)
+
+    if not session_id:
+        console.print(
+            "[yellow]No Claude Code session id in this shell.[/]\n"
+            "  Run `agentgov status` from inside Claude Code, or pass --session <id>.\n"
+            "  Session ids are listed by: [bold]agentgov doctor[/]"
+        )
+        raise typer.Exit(0)
+
+    try:
+        r = httpx.get(f"{base}/admin/session/{session_id}/binding", timeout=10.0)
+        data = _body(r)
+    except Exception:
+        console.print(
+            f"[red]Gateway at {base} is not reachable.[/]\n"
+            "  Start it with: [bold]agentgov gateway install[/]"
+        )
+        raise typer.Exit(0) from None
+
+    if not data.get("known"):
+        console.print(
+            "[yellow]This session is not registered with the gateway.[/]\n"
+            "  It will re-register on your next prompt, or when you run `/workitem`."
+        )
+        raise typer.Exit(0)
+
+    console.print(f"🛡 repo: [bold]{data.get('repo') or 'unknown'}[/]")
+    if data.get("bound"):
+        console.print(f"📌 work item: [bold]{data.get('work_item_ref')}[/]")
+    else:
+        console.print("[red]📌 UNBOUND[/] — run `/workitem <anything>` in Claude Code.")
+    raise typer.Exit(0)

{agentgov_cli-0.1.8 → agentgov_cli-0.1.9}/agentgov_cli/commands/uninstall.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 import json
 import shutil
 import subprocess
+import sys
 from pathlib import Path
 
 import typer
@@ -34,6 +35,33 @@ SETTINGS = CLAUDE_DIR / "settings.json"
 AGENTGOV_DIR = Path.home() / ".agentgov"
 
 
+def _running_from(directory: Path) -> Path | None:
+    """Is this process's interpreter installed underneath `directory`?
+
+    The documented install puts the CLI in a venv at ~/.agentgov/venv — INSIDE
+    the directory `uninstall` deletes. So `shutil.rmtree(~/.agentgov)` was
+    deleting the interpreter and site-packages out from under the running
+    process. It did not fail immediately, because Python had already imported
+    what it needed; it failed on the NEXT lazy import. In practice that was
+    rich's on-demand unicode table, from the very next console.print():
+
+        ModuleNotFoundError: No module named 'rich._unicode_data.unicode17-0-0'
+
+    followed by typer's excepthook failing too, because typer's own modules were
+    gone as well. It read like a rich/typer version conflict. It was not — it was
+    self-deletion, and it left the user with no `agentgov` command at all and no
+    obvious way back.
+
+    Returns the venv root when this process runs from inside `directory`.
+    """
+    try:
+        prefix = Path(sys.prefix).resolve()
+        target = directory.resolve()
+    except OSError:
+        return None
+    return prefix if prefix == target or target in prefix.parents else None
+
+
 def run(
     keep_credentials: bool = typer.Option(
         False,
@@ -70,12 +98,38 @@ def run(
         workitem.unlink()
         console.print(f"[green]Removed[/] {workitem}")
 
+    self_venv: Path | None = None
     if not keep_credentials and AGENTGOV_DIR.exists():
-        shutil.rmtree(AGENTGOV_DIR, ignore_errors=True)
-        console.print(f"[green]Removed[/] {AGENTGOV_DIR}")
+        self_venv = _running_from(AGENTGOV_DIR)
+        if self_venv is None:
+            shutil.rmtree(AGENTGOV_DIR, ignore_errors=True)
+            console.print(f"[green]Removed[/] {AGENTGOV_DIR}")
+        else:
+            # Delete everything EXCEPT the venv we are executing from. Removing
+            # it here crashes this process mid-teardown (see _running_from) and
+            # destroys the only copy of the CLI, so the user cannot even re-run
+            # uninstall to finish the job. Leave it and hand them one command.
+            for child in AGENTGOV_DIR.iterdir():
+                if child == self_venv:
+                    continue
+                if child.is_dir() and not child.is_symlink():
+                    shutil.rmtree(child, ignore_errors=True)
+                else:
+                    child.unlink(missing_ok=True)
+            console.print(f"[green]Removed[/] {AGENTGOV_DIR} [dim](except the venv below)[/]")
 
     console.print("\n[bold green]AgentGov removed.[/]")
     console.print("Claude Code is unaffected — restart it to clear the old session.")
+
+    if self_venv is not None:
+        console.print(
+            f"\n[yellow]Left in place:[/] {self_venv}\n"
+            "  That is the virtualenv running this command — deleting it mid-run would "
+            "crash before the teardown finished.\n"
+            "  Remove it once this command has exited:\n"
+            f"    rm -rf {self_venv}"
+        )
+
     console.print(
         "\n[dim]Machine-wide managed-settings.json (if you installed it) needs sudo:[/]\n"
         "  sudo rm -f /etc/claude-code/managed-settings.json"

agentgov_cli-0.1.9/agentgov_cli/commands/workitem.py

@@ -0,0 +1,291 @@
+"""`agentgov workitem [ref...]` — bind the current Claude Code session to a work item.
+
+WHY THIS WAS REWRITTEN
+----------------------
+This command used to POST to the loopback admin listener on :8788 that
+`agentgov wrap` starts. That made it unusable for almost everyone: the rest of
+the system had already moved to governing whatever Claude Code the developer
+actually runs — the VS Code / Cursor / JetBrains extension — via hooks that talk
+straight to the gateway using Claude Code's own `session_id` (see
+gateway/agentgov_gateway/session_identity.py). But `workitem` stayed on the old
+wrapper-only path, so in an editor session there was no listener and every
+attempt died with:
+
+    No AgentGov loopback listener on :8788.
+    No active AgentGov session. Start one: agentgov wrap claude
+
+...for a session that was perfectly healthy and already registered. The loopback
+listener never did anything except relay to `POST /admin/session/bind`, so this
+now calls that endpoint directly and works identically under `wrap` and under the
+editor extension.
+
+THREE RULES THIS COMMAND OBEYS
+------------------------------
+1. **Never exit non-zero.** The `/workitem` slash command runs this inside a
+   `` !`...` `` block, and Claude Code aborts the whole invocation on any
+   non-zero exit, reporting `Shell command failed for pattern "..."` — which is
+   what the developer saw instead of our actual error text. Failures are
+   reported as readable output with exit code 0.
+2. **Accept any text.** A reference is whatever the developer typed: a JIRA key,
+   a URL, an id from some other tracker, or a plain label. Nothing is validated
+   client-side; the only limit is MAX_REF_LEN characters, and over-long input is
+   truncated with a notice rather than refused.
+3. **Self-heal a forgotten session.** The gateway holds sessions in memory, so a
+   restart drops every editor window that is already open. Rather than telling
+   the developer to start a new session, re-register and retry the bind once.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any
+
+import httpx
+import typer
+from rich.console import Console
+
+console = Console()
+
+# Mirrors MAX_REF_LEN in control-tower/lib/work-items.ts and the CHECK
+# constraint in supabase/migrations/016_freeform_work_items.sql.
+MAX_REF_LEN = 200
+
+DEFAULT_GATEWAY = "http://127.0.0.1:8000"
+
+
+def run(
+    ref: list[str] = typer.Argument(
+        None,
+        help=(
+            "Anything that identifies the work: a ticket id, a URL, or a short "
+            f"description. Free text is fine. Truncated to {MAX_REF_LEN} characters."
+        ),
+    ),
+    session: str = typer.Option(
+        None,
+        "--session",
+        help="Claude Code session id. Defaults to $CLAUDE_SESSION_ID / $AGENTGOV_SESSION.",
+    ),
+    gateway: str = typer.Option(
+        None,
+        "--gateway",
+        envvar="AGENTGOV_GATEWAY_URL",
+        help=f"Gateway base URL (default {DEFAULT_GATEWAY}).",
+    ),
+) -> None:
+    """Bind this Claude Code session to a work item, so its tokens are attributed to it."""
+    base = (gateway or DEFAULT_GATEWAY).rstrip("/")
+    session_id = _resolve_session(session)
+
+    if not session_id:
+        console.print(
+            "[red]AgentGov: no Claude Code session id.[/]\n"
+            "  Run /workitem from inside Claude Code, or pass --session <id> explicitly."
+        )
+        raise typer.Exit(0)
+
+    raw = _join(ref)
+    if not raw:
+        _show_current(base, session_id)
+        raise typer.Exit(0)
+
+    work_ref, truncated = _clamp(raw)
+
+    result = _bind(base, session_id, work_ref)
+    if result is None:
+        console.print(
+            f"[red]AgentGov: the gateway at {base} is not reachable,[/] so the work item "
+            "could not be bound.\n"
+            "  Start it with: [bold]agentgov gateway install[/]  (then: agentgov doctor)"
+        )
+        raise typer.Exit(0)
+
+    status, payload = result
+
+    # A session the gateway has forgotten (restart, reinstall) is transient, not
+    # an error the developer should have to act on. Re-register and retry once.
+    forgotten = status == 409 or _error_code(payload) == "session_not_registered"
+    if forgotten and _register(base, session_id):
+        retried = _bind(base, session_id, work_ref)
+        if retried is not None:
+            status, payload = retried
+
+    if status >= 400:
+        console.print(f"[red]AgentGov: could not bind to[/] {work_ref!r}")
+        console.print(f"  {_error_text(payload)}")
+        raise typer.Exit(0)
+
+    wi = payload.get("work_item") or {}
+    bound = str(wi.get("external_id") or work_ref)
+    console.print(f"[green]✅ Bound to[/] [bold]{bound}[/]")
+    if truncated:
+        console.print(
+            f"  [yellow]Note:[/] your text was longer than {MAX_REF_LEN} characters "
+            "and was shortened to the above."
+        )
+    console.print("  Tokens from here on are attributed to this work item.")
+    raise typer.Exit(0)
+
+
+# -----------------------------------------------------------------------------
+# Reference handling
+# -----------------------------------------------------------------------------
+
+
+def _join(ref: list[str] | None) -> str:
+    """Join argv into one reference string.
+
+    The slash command substitutes the developer's text into a shell line, so the
+    text may arrive as many argv entries ("fix", "the", "retry", "loop") and may
+    carry the quote characters the slash command wrapped it in. Rejoin, collapse
+    whitespace, and drop one matching pair of surrounding quotes if present —
+    a developer who types `PROJ-1 fix retry` means one work item, not four, and
+    should never see stray quotes in their dashboard.
+    """
+    if not ref:
+        return ""
+    joined = " ".join(ref).strip()
+    joined = " ".join(joined.split())
+    for q in ("'", '"'):
+        if len(joined) >= 2 and joined.startswith(q) and joined.endswith(q):
+            joined = joined[1:-1].strip()
+            break
+    return joined
+
+
+def _clamp(raw: str) -> tuple[str, bool]:
+    """Enforce MAX_REF_LEN. Returns (ref, was_truncated).
+
+    Truncate rather than refuse. Refusing would block the developer over a
+    pasted URL, and the whole point of binding is attribution — a shortened
+    label attributes just as well as a long one.
+    """
+    if len(raw) <= MAX_REF_LEN:
+        return raw, False
+    return raw[:MAX_REF_LEN].rstrip(), True
+
+
+def _resolve_session(explicit: str | None) -> str:
+    """Claude Code's session id, preferring the one Claude Code itself provides.
+
+    CLAUDE_SESSION_ID is substituted by Claude Code into slash-command shell
+    lines and is the id the gateway keys sessions by (it is the same value sent
+    as `x-claude-code-session-id` on every API request). AGENTGOV_SESSION is the
+    wrapper's own UUIDv7 and is only a fallback for legacy `agentgov wrap` use.
+    """
+    candidates = (
+        explicit,
+        os.environ.get("CLAUDE_SESSION_ID"),
+        os.environ.get("AGENTGOV_SESSION"),
+    )
+    for candidate in candidates:
+        value = (candidate or "").strip()
+        # Guard against an unsubstituted placeholder reaching us as literal text.
+        if value and not value.startswith("$"):
+            return value
+    return ""
+
+
+# -----------------------------------------------------------------------------
+# Gateway calls. None = transport failure; otherwise (status_code, json_body).
+# -----------------------------------------------------------------------------
+
+
+def _bind(base: str, session_id: str, work_ref: str) -> tuple[int, dict[str, Any]] | None:
+    try:
+        r = httpx.post(
+            f"{base}/admin/session/bind",
+            json={"session_id": session_id, "work_item_ref": work_ref},
+            timeout=20.0,
+        )
+    except Exception:
+        return None
+    return r.status_code, _body(r)
+
+
+def _register(base: str, session_id: str) -> bool:
+    """Re-register this session from the current working directory."""
+    cwd = os.getcwd()
+    root = _git(cwd, "rev-parse", "--show-toplevel")
+    if not root:
+        return False
+    try:
+        httpx.post(
+            f"{base}/admin/session/register",
+            json={
+                "session_id": session_id,
+                "repo": _git(cwd, "remote", "get-url", "origin"),
+                "repo_root": root,
+            },
+            timeout=15.0,
+        )
+    except Exception:
+        return False
+    return True
+
+
+def _show_current(base: str, session_id: str) -> None:
+    """`/workitem` with no arguments: report the binding instead of erroring.
+
+    This previously fell through to Typer's `Missing argument 'ref'` usage error
+    and a non-zero exit, which Claude Code surfaced as a failed shell command.
+    Asking "what am I bound to?" is a reasonable thing to do.
+    """
+    try:
+        r = httpx.get(f"{base}/admin/session/{session_id}/binding", timeout=10.0)
+        data = _body(r)
+    except Exception:
+        data = {}
+
+    if data.get("bound"):
+        console.print(f"[green]📌 Bound to[/] [bold]{data.get('work_item_ref')}[/]")
+    else:
+        console.print("[yellow]📌 This session is not bound to a work item.[/]")
+
+    console.print(
+        "\n  Bind it with anything that identifies the work — there is no required format:\n"
+        "    /workitem PROJ-1234\n"
+        "    /workitem https://your-tracker/issue/42\n"
+        "    /workitem payment retry loop spike\n"
+        f"\n  [dim]Up to {MAX_REF_LEN} characters; longer text is shortened.[/]"
+    )
+
+
+# -----------------------------------------------------------------------------
+# Small helpers
+# -----------------------------------------------------------------------------
+
+
+def _body(r: httpx.Response) -> dict[str, Any]:
+    try:
+        parsed = r.json()
+    except Exception:
+        return {"error": {"detail": r.text[:400]}}
+    return parsed if isinstance(parsed, dict) else {"error": {"detail": str(parsed)[:400]}}
+
+
+def _error_code(payload: dict[str, Any]) -> str:
+    err = payload.get("error")
+    return str(err.get("code") or "") if isinstance(err, dict) else ""
+
+
+def _error_text(payload: dict[str, Any]) -> str:
+    err = payload.get("error")
+    if isinstance(err, dict):
+        detail = err.get("detail") or err.get("message") or err.get("code") or ""
+        return str(detail)
+    if isinstance(err, str):
+        return err
+    return json.dumps(payload)[:400] if payload else "no detail returned by the gateway"
+
+
+def _git(cwd: str, *args: str) -> str:
+    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 ""

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

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

@@ -1,18 +0,0 @@
----
-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.8/agentgov_cli/client_assets/statusline/agentgov_statusline.sh

@@ -1,74 +0,0 @@
-#!/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.8/agentgov_cli/commands/status.py

@@ -1,46 +0,0 @@
-"""`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-0.1.8/agentgov_cli/commands/workitem.py

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