agentmetry 0.10.0__tar.gz → 0.10.2__tar.gz

{agentmetry-0.10.0 → agentmetry-0.10.2}/.gitignore

@@ -16,6 +16,8 @@ build/
 # Next.js
 apps/dashboard/.next/
 apps/dashboard/out/
+# The same export copied into the package by the release build, for the wheel.
+apps/orchestrator/agentmetry/dashboard_static/
 
 # Environment
 .env

{agentmetry-0.10.0 → agentmetry-0.10.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.10.0
-Summary: Local-first endpoint sensor for AI coding agents: hash-chained audit trail, MITRE-mapped sequence detection, DLP
+Version: 0.10.2
+Summary: Open-source security for AI coding agents: record, detect and block at the tool boundary, with a verifiable audit trail and SIEM forwarding
 Project-URL: Homepage, https://agentmetry.ai
 Project-URL: Source, https://github.com/blitzcrieg1/agentmetry
 Project-URL: Issues, https://github.com/blitzcrieg1/agentmetry/issues

{agentmetry-0.10.0 → agentmetry-0.10.2}/agentmetry/api/main.py

@@ -315,23 +315,57 @@ async def websocket_endpoint(
         ws_manager.disconnect(websocket, session_id)
 
 
-_DASHBOARD_DIR = Path(__file__).resolve().parents[3] / "dashboard" / "out"
-
-
-def mount_dashboard(target: FastAPI, directory: Path = _DASHBOARD_DIR) -> bool:
-    """Serve the dashboard's static export when it has been built.
-
-    Single-process mode: `npm run build` in apps/dashboard emits `out/`, which
-    the orchestrator serves at the root. Mounted last so it only catches paths
-    not already claimed by the API or WebSocket. Dev uses the :3000 dev server
-    instead, so this is a no-op when the export is absent.
+#: A source checkout's build, which a developer rebuilds and expects to see.
+_CHECKOUT_DASHBOARD_DIR = Path(__file__).resolve().parents[3] / "dashboard" / "out"
+#: The same export, bundled inside the wheel by the release build. Until 0.10.1
+#: nothing put it there, so `pip install agentmetry`, `agentmetry dashboard`
+#: signed the browser in and landed it on a JSON 404.
+_PACKAGED_DASHBOARD_DIR = Path(__file__).resolve().parents[1] / "dashboard_static"
+
+_DASHBOARD_MISSING_PAGE = """<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Agentmetry</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>body{font:16px/1.6 system-ui,sans-serif;max-width:40rem;margin:4rem auto;padding:0 1rem}
+code{background:#f2f2f2;padding:.1em .3em;border-radius:3px}</style></head>
+<body><h1>Agentmetry is recording.</h1>
+<p>The dashboard is not part of this install. Packages from 0.10.1 include it:
+<code>pip install --upgrade agentmetry</code>, then restart the recorder.</p>
+<p>Recording, detection and the trail do not depend on it. From a shell:
+<code>agentmetry stats</code>, <code>agentmetry replay &lt;session&gt;</code>,
+<code>agentmetry verify --trail</code>.</p></body></html>"""
+
+
+def dashboard_dir() -> Path | None:
+    """Where the dashboard export is: a checkout's build first, then the package's."""
+    for candidate in (_CHECKOUT_DASHBOARD_DIR, _PACKAGED_DASHBOARD_DIR):
+        if (candidate / "index.html").is_file():
+            return candidate
+    return None
+
+
+def mount_dashboard(target: FastAPI, directory: Path | None = None) -> bool:
+    """Serve the dashboard's static export when there is one.
+
+    Single-process mode: the orchestrator serves the export at the root,
+    mounted last so it only catches paths not already claimed by the API or
+    WebSocket. Dev uses the :3000 dev server instead. With no export, the root
+    serves a page saying so, because the sign-in link redirects there and a
+    JSON 404 reads as a broken product.
     """
-    if not directory.is_dir():
+    if directory is None:
+        directory = dashboard_dir()
+    if directory is None or not directory.is_dir():
         logger.info(
-            "Dashboard export not found at %s — run 'npm run build' in "
-            "apps/dashboard for single-process serving",
-            directory,
+            "Dashboard export not found (looked in %s and %s); serving a notice at /",
+            _CHECKOUT_DASHBOARD_DIR,
+            _PACKAGED_DASHBOARD_DIR,
         )
+        from fastapi.responses import HTMLResponse
+
+        @target.get("/", include_in_schema=False, name="dashboard-missing")
+        async def dashboard_missing() -> HTMLResponse:
+            return HTMLResponse(_DASHBOARD_MISSING_PAGE, headers={"Cache-Control": "no-cache"})
+
         return False
 
     from fastapi.staticfiles import StaticFiles

{agentmetry-0.10.0 → agentmetry-0.10.2}/agentmetry/cli/__init__.py

@@ -312,16 +312,41 @@ def cmd_status(args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_stats(args: argparse.Namespace) -> int:
-    """Audit trail metrics over a window — dogfood weekly counts."""
+def _api_get_json(port: int, path: str, what: str, params: dict | None = None) -> dict | None:
+    """GET an API route with this install's token, or print why not and return None.
+
+    Every route but health has needed the per-install token since 0.9.3, and
+    `stats` and `detections` were still calling without it. The 401 body was
+    read as if it were the answer, so both printed an empty result over a trail
+    with events and a critical detection in it. A refusal is now an error.
+    """
     try:
-        data = httpx.get(
-            f"{_base_url(args.port)}/api/v1/audit/stats",
-            params={"days": args.days},
+        resp = httpx.get(
+            f"{_api_base_url(port)}{path}",
+            params=params,
+            headers=_api_headers(),
             timeout=10.0,
-        ).json()
+        )
     except Exception:
-        print("Not running - start Agentmetry first (stats reads via the API).")
+        print(f"Not running - start Agentmetry first ({what} reads via the API).")
+        return None
+    if resp.status_code in (401, 403):
+        print(
+            f"The recorder refused the request (HTTP {resp.status_code}): this shell has no "
+            "valid API token for it. Run it as the account that started the recorder, or "
+            "set AGENTMETRY_API_KEY."
+        )
+        return None
+    if resp.status_code >= 400:
+        print(f"FAILED: HTTP {resp.status_code} from {path}")
+        return None
+    return resp.json()
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    """Audit trail metrics over a window — dogfood weekly counts."""
+    data = _api_get_json(args.port, "/api/v1/audit/stats", "stats", {"days": args.days})
+    if data is None:
         return 1
 
     if not data.get("enabled", True):
@@ -349,13 +374,10 @@ def cmd_stats(args: argparse.Namespace) -> int:
 
 
 def cmd_detections(args: argparse.Namespace) -> int:
-    try:
-        data = httpx.get(
-            f"{_base_url(args.port)}/api/v1/audit/detections/{args.correlation_id}",
-            timeout=10.0,
-        ).json()
-    except Exception:
-        print("Not running - start Agentmetry first (detections reads via the API).")
+    data = _api_get_json(
+        args.port, f"/api/v1/audit/detections/{args.correlation_id}", "detections"
+    )
+    if data is None:
         return 1
     if not data.get("enabled", True):
         print("Audit export is disabled, so no sessions are recorded.")
@@ -595,6 +617,39 @@ _HOOK_INSTALLERS = ("cursor", "claude", "codex", "qwen", "kimi", "qoder", "codeb
 
 
 
+def _cloud_cursor_cache(args: argparse.Namespace) -> int:
+    """Record Cursor cloud-agent tool calls from the desktop app's local cache.
+
+    No vendor key and no network call to Cursor: the calls are read from the
+    state database the Cursor app keeps on this machine, read-only. See
+    `core/audit/cursor_cloud_cache.py` for what that cache does and does not hold.
+    """
+    from agentmetry.core.audit.cursor_cloud_cache import STATE_FILE, default_db_path, import_cache
+    from agentmetry.core.paths import data_dir
+    from agentmetry.hooks.ingest import post_ingest
+
+    db = Path(args.db).expanduser() if args.db else default_db_path()
+    if db is None or not db.is_file():
+        print(f"No Cursor state database at {db}. Is the Cursor desktop app installed here? (--db to point at one)")
+        return 2
+
+    def post(payload: dict) -> bool:
+        # No spool: a call that did not land is simply not marked as recorded,
+        # and the next run picks it up from the cache again.
+        return post_ingest(payload, quiet=True, spool=False)
+
+    result = import_cache(db, post=post, state_path=data_dir() / STATE_FILE, dry_run=args.dry_run)
+    verb = "would record" if args.dry_run else "recorded"
+    count = result.new if args.dry_run else result.posted
+    print(f"cursor-cache: {result.agents} cloud agent conversation(s), {result.calls} finished tool call(s).")
+    print(f"  {verb} {count}, already recorded {result.already_seen}, failed {result.failed}.")
+    if result.skipped:
+        print(f"  skipped: {dict(result.skipped)}")
+    if result.tools:
+        print("  by tool: " + ", ".join(f"{name} {n}" for name, n in result.tools.most_common()))
+    return 1 if result.failed else 0
+
+
 def cmd_cloud(args: argparse.Namespace) -> int:
     """Poll a vendor cloud-agent API once and record what it exposes.
 
@@ -605,6 +660,9 @@ def cmd_cloud(args: argparse.Namespace) -> int:
     """
     import os
 
+    if args.provider == "cursor-cache":
+        return _cloud_cursor_cache(args)
+
     import httpx
 
     from agentmetry.core.audit.cloud_bridge import (
@@ -1624,10 +1682,13 @@ def main(argv: list[str] | None = None) -> int:
     stats = sub.add_parser("stats", help="audit trail metrics for dogfood (events, detections)")
     stats.add_argument("--days", type=int, default=7)
     cloud = sub.add_parser("cloud", help="record what a vendor cloud-agent API exposes (Cursor, Claude)")
-    cloud.add_argument("provider", choices=("cursor", "claude"))
+    cloud.add_argument("provider", choices=("cursor", "claude", "cursor-cache"))
+    cloud.add_argument("--db", default="", help="cursor-cache: Cursor state database (default: the desktop app's)")
+    cloud.add_argument("--dry-run", action="store_true", help="cursor-cache: count what would be recorded, post nothing")
     cloud.add_argument("--url", default="", help="vendor API base override")
     cloud.add_argument("--limit", type=int, default=10, help="max sessions/agents per poll")
     cloud.add_argument("--skip-runs", action="store_true", help="cursor: agents only, skip per-run fetch")
+    cloud.add_argument("--remote", action="store_true", help="claude: the Compliance API's remote sessions instead of local ones (not Claude Code on the web, which that API excludes)")
     detections = sub.add_parser("detections", help="list detections for one session")
     detections.add_argument("correlation_id", help="correlation_id / session id")
     disposition = sub.add_parser("disposition", help="close an audit detection from the shell")
@@ -1738,7 +1799,8 @@ def main(argv: list[str] | None = None) -> int:
     scan.add_argument(
         "target", nargs="?", default=None,
         help="a file or folder (skills, rules, a saved tools/list), npm:NAME or pypi:NAME; "
-        "omit to scan the MCP servers configured on this machine",
+        "omit to scan the MCP servers configured on this machine and the agent "
+        "instruction files in Downloads, on the Desktop and in the home folder",
     )
     scan.add_argument("--project", default=None, help="project root whose MCP config to include (default: cwd)")
     scan.add_argument("--known", default=None, help="file of extra known package names, one per line (npm:/pypi: or bare)")

agentmetry-0.10.2/agentmetry/core/audit/cursor_cloud_cache.py

@@ -0,0 +1,305 @@
+"""Cursor cloud-agent tool calls, read from the Cursor desktop app's own cache.
+
+A cloud agent runs on Cursor's VM, where no hook on this machine fires. When the
+desktop app streams one of those agents, it caches the conversation in its
+local state database (`User/globalStorage/state.vscdb`), and the cache holds
+every tool call the agent made: the terminal commands, the files read and
+edited, searches, web fetches and MCP calls, each with its arguments, status
+and result. Paths in those arguments are under `/workspace`, the cloud VM's
+checkout, so these are calls that ran there, not on this machine.
+
+This module reads that cache read-only and turns each completed tool call into
+the payload Cursor's own `postToolUse` hook would have produced, then runs it
+through the hook client's mapper. The cloud events therefore get the same
+argument hashing, command traits and ATT&CK labels as local Cursor events, and
+the same rules fire on them. Nothing else leaves the cache: results are never
+forwarded, only an exit code when the result carries one.
+
+## What this sees, and what it does not
+
+* **Only agents the desktop app has streamed.** The cache is filled when an
+  agent is opened in the app (`createdFromBackgroundAgent.shouldStreamMessages`).
+  An agent nobody opened here leaves nothing to read.
+* **After the fact.** This is a record, never a gate. A call is read once it
+  has completed, errored or been cancelled, and nothing here can block one.
+* **An undocumented format.** The layout was read off a real database on
+  2026-10-21: `composerData:<id>` rows carrying `createdFromBackgroundAgent.bcId`,
+  and `bubbleId:<id>:<bubble>` rows carrying `toolFormerData`. A row that does
+  not match it is skipped and counted, never guessed at.
+* **A claim, not proof.** The cache is a file the user can edit or delete.
+  Cursor's own run stream (`cloud_bridge.py`) is the independent view to check
+  it against, keyed on the same `cursor-cloud-<bcId>` correlation id.
+
+## Reading safely
+
+The database is opened with `mode=ro`, so a running Cursor is never blocked or
+written to. Only rows that name a cloud agent are selected, which keeps a
+multi-gigabyte database cheap to poll. A call already recorded is remembered by
+a digest of its agent and tool-call id in a small state file beside the trail,
+so a second run imports nothing twice.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+import sys
+from collections import Counter
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SOURCE_APP = "cursor_cloud"
+ADAPTER = "cursor_cloud_cache"
+STATE_FILE = "cursor-cloud-cache.seen.json"
+
+#: Tool names the cloud agent uses, mapped to the names Cursor's local hooks
+#: record, so a rule keyed on `cursor.Read` or `shell.run` fires on both.
+_TOOL_NAMES = {
+    "read_file_v2": "Read",
+    "edit_file_v2": "Write",
+    "delete_file": "Delete",
+    "ripgrep_raw_search": "Grep",
+    "glob_file_search": "Glob",
+    "web_fetch": "WebFetch",
+    "web_search": "WebSearch",
+    "task_v2": "Task",
+}
+_SHELL_TOOLS = frozenset({"run_terminal_command_v2", "run_terminal_cmd"})
+_FINAL_STATUSES = frozenset({"completed", "error", "cancelled"})
+
+
+def default_db_path() -> Path | None:
+    """Where the Cursor desktop app keeps its state database on this OS."""
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA", "")
+        root = Path(base) / "Cursor" if base else None
+    elif sys.platform == "darwin":
+        root = Path.home() / "Library" / "Application Support" / "Cursor"
+    else:
+        root = Path(os.environ.get("XDG_CONFIG_HOME", "") or Path.home() / ".config") / "Cursor"
+    if root is None:
+        return None
+    return root / "User" / "globalStorage" / "state.vscdb"
+
+
+@dataclass(frozen=True)
+class CloudToolCall:
+    bc_id: str
+    tool_call_id: str
+    name: str
+    status: str
+    created_at: str
+    args: dict[str, Any]
+    exit_code: int | None = None
+
+
+@dataclass
+class ImportResult:
+    agents: int = 0
+    calls: int = 0
+    new: int = 0
+    posted: int = 0
+    already_seen: int = 0
+    failed: int = 0
+    skipped: Counter = field(default_factory=Counter)
+    tools: Counter = field(default_factory=Counter)
+
+
+def open_readonly(db_path: Path) -> sqlite3.Connection:
+    return sqlite3.connect(f"file:{Path(db_path).as_posix()}?mode=ro", uri=True, timeout=5)
+
+
+def _json(value: Any) -> Any:
+    if isinstance(value, (dict, list)):
+        return value
+    if isinstance(value, (bytes, bytearray)):
+        value = value.decode("utf-8", errors="replace")
+    if isinstance(value, str) and value.strip()[:1] in "{[":
+        try:
+            return json.loads(value)
+        except ValueError:
+            return None
+    return None
+
+
+def iter_cloud_composers(con: sqlite3.Connection) -> Iterator[tuple[str, str]]:
+    """(composer id, cloud agent id) for every conversation streamed from a cloud agent."""
+    rows = con.execute(
+        "SELECT key, value FROM cursorDiskKV"
+        " WHERE key LIKE 'composerData:%' AND value LIKE '%createdFromBackgroundAgent%'"
+    )
+    for key, value in rows:
+        data = _json(value)
+        origin = data.get("createdFromBackgroundAgent") if isinstance(data, dict) else None
+        bc_id = origin.get("bcId") if isinstance(origin, dict) else None
+        if isinstance(bc_id, str) and bc_id:
+            yield str(key).split(":", 1)[1], bc_id
+
+
+def _exit_code(result: Any) -> int | None:
+    data = _json(result)
+    code = data.get("exitCode") if isinstance(data, dict) else None
+    return code if isinstance(code, int) and not isinstance(code, bool) else None
+
+
+def iter_tool_calls(
+    con: sqlite3.Connection, composer_id: str, bc_id: str, skipped: Counter | None = None
+) -> Iterator[CloudToolCall]:
+    """Every finished tool call in one cloud agent's cached conversation."""
+    skipped = skipped if skipped is not None else Counter()
+    rows = con.execute(
+        "SELECT value FROM cursorDiskKV WHERE key LIKE ?", (f"bubbleId:{composer_id}:%",)
+    )
+    for (value,) in rows:
+        bubble = _json(value)
+        tool = bubble.get("toolFormerData") if isinstance(bubble, dict) else None
+        if not isinstance(tool, dict):
+            continue
+        name = tool.get("name")
+        call_id = tool.get("toolCallId")
+        status = str(tool.get("status") or "")
+        if not isinstance(name, str) or not name or not isinstance(call_id, str) or not call_id:
+            skipped["unrecognised_row"] += 1
+            continue
+        if status not in _FINAL_STATUSES:
+            skipped["not_finished"] += 1
+            continue
+        args = _json(tool.get("params"))
+        if not isinstance(args, dict):
+            args = _json(tool.get("rawArgs"))
+        yield CloudToolCall(
+            bc_id=bc_id,
+            tool_call_id=call_id,
+            name=name,
+            status=status,
+            created_at=str(bubble.get("createdAt") or ""),
+            args=args if isinstance(args, dict) else {},
+            exit_code=_exit_code(tool.get("result")) if name in _SHELL_TOOLS else None,
+        )
+
+
+def _mcp_tool(name: str) -> str:
+    """`mcp-<server>-<tool>` to `MCP:<tool>`, the name the local hooks record.
+
+    Server names contain dashes too, so only the last segment is taken as the
+    tool. A tool whose own name has a dash keeps only its tail.
+    """
+    tail = name.rsplit("-", 1)[-1]
+    return f"MCP:{tail or 'unknown'}"
+
+
+def hook_event(call: CloudToolCall) -> tuple[str, dict[str, Any]]:
+    """The (hook name, payload) Cursor's local hooks would have sent for this call."""
+    data: dict[str, Any] = {"conversation_id": call.bc_id}
+    if call.status == "error":
+        data["error"] = "tool_error"
+    elif call.status == "cancelled":
+        data["error"] = "cancelled"
+    if call.exit_code is not None:
+        data["exit_code"] = call.exit_code
+
+    if call.name in _SHELL_TOOLS:
+        command = call.args.get("command")
+        data["command"] = command if isinstance(command, str) else ""
+        return "afterShellExecution", data
+
+    if call.name.startswith("mcp-"):
+        tool_name = _mcp_tool(call.name)
+        tool_input = dict(call.args)
+    else:
+        tool_name = _TOOL_NAMES.get(call.name, call.name.removesuffix("_v2"))
+        tool_input = dict(call.args)
+        path = call.args.get("path") or call.args.get("targetFile") or call.args.get("relativeWorkspacePath")
+        if tool_name in ("Read", "Write", "Delete") and isinstance(path, str):
+            # Only the path, as the local hooks send it. Edit bodies stay behind.
+            tool_input = {"path": path}
+    data["tool_name"] = tool_name
+    data["tool_input"] = tool_input
+    return "postToolUse", data
+
+
+def to_payload(call: CloudToolCall) -> dict[str, Any] | None:
+    """One cached cloud tool call as an external-ingest payload, hashed in-process."""
+    from agentmetry.hooks.ingest import _hash_tool_args, map_cursor_hook
+
+    hook_name, data = hook_event(call)
+    payload = _hash_tool_args(map_cursor_hook(hook_name, data))
+    if not payload:
+        return None
+    payload["source_app"] = SOURCE_APP
+    payload["adapter"] = ADAPTER
+    payload["correlation_id"] = f"cursor-cloud-{call.bc_id}"
+    payload["session_id"] = call.bc_id
+    if call.created_at:
+        payload["timestamp_utc"] = call.created_at
+    if call.status == "cancelled":
+        payload["reason"] = "cancelled"
+    payload.setdefault("initiator", {})["actor_type"] = "agent"
+    return payload
+
+
+def _seen_key(call: CloudToolCall) -> str:
+    return hashlib.sha256(f"{call.bc_id}\n{call.tool_call_id}".encode()).hexdigest()[:32]
+
+
+def _load_seen(path: Path) -> set[str]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return set()
+    return set(data.get("seen", [])) if isinstance(data, dict) else set()
+
+
+def _save_seen(path: Path, seen: set[str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps({"v": 1, "seen": sorted(seen)}), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def import_cache(
+    db_path: Path,
+    *,
+    post: Callable[[dict[str, Any]], bool],
+    state_path: Path,
+    dry_run: bool = False,
+) -> ImportResult:
+    """Read every cached cloud tool call not yet recorded, and post it.
+
+    A call is remembered only after `post` accepted it, so a run that fails
+    half way resumes where it stopped instead of skipping the rest.
+    """
+    result = ImportResult()
+    seen = _load_seen(state_path)
+    con = open_readonly(db_path)
+    try:
+        for composer_id, bc_id in iter_cloud_composers(con):
+            result.agents += 1
+            for call in iter_tool_calls(con, composer_id, bc_id, result.skipped):
+                result.calls += 1
+                result.tools[call.name] += 1
+                key = _seen_key(call)
+                if key in seen:
+                    result.already_seen += 1
+                    continue
+                payload = to_payload(call)
+                if payload is None:
+                    result.skipped["unmapped"] += 1
+                    continue
+                result.new += 1
+                if dry_run:
+                    continue
+                if post(payload):
+                    seen.add(key)
+                    result.posted += 1
+                else:
+                    result.failed += 1
+    finally:
+        con.close()
+        if not dry_run:
+            _save_seen(state_path, seen)
+    return result

{agentmetry-0.10.0 → agentmetry-0.10.2}/agentmetry/core/audit/tool_policy/evaluator.py

@@ -98,6 +98,14 @@ def _extract_command(hook_data: dict[str, Any] | str, qualified: str = "") -> st
         val = hook_data.get("value")
         if val is not None and str(val).strip():
             return str(val)
+    # Codex's apply_patch carries its target paths inside the patch text, not
+    # under a path key, so a config-write rule needs the patch itself.
+    if q.endswith("apply_patch"):
+        for container in (hook_data, *nested):
+            for key in ("patch", "input"):
+                val = container.get(key)
+                if isinstance(val, str) and val.strip():
+                    return val
 
     # Path fallback: lets a rule deny writes to agent-execution config.
     for container in (hook_data, *nested):

{agentmetry-0.10.0 → agentmetry-0.10.2}/agentmetry/core/diagnostics/doctor.py

@@ -250,11 +250,20 @@ def _check_hooks_installed(report: DoctorReport) -> None:
         # health checks' answer, not this one's.
         report.ok("hooks", f"Hooks installed for: {', '.join(covered)}")
     if uncovered:
+        # It used to name scripts/install_<agent>_hooks.ps1, which exist only in a
+        # git checkout: a pip install was told to run files it does not have.
+        # `hooks install` writes every agent's hooks except Antigravity's.
+        fix = "Run `agentmetry hooks install`."
+        if "antigravity" in uncovered:
+            fix += (
+                " Antigravity's hooks come from scripts/install_antigravity_hooks.ps1 "
+                "in a clone of the repository."
+            )
         report.warn(
             "hooks",
             f"Installed on this machine but NOT recorded: {', '.join(uncovered)}. "
-            "Run scripts/install_<agent>_hooks.ps1 for each. Codex additionally "
-            "needs its /hooks trust prompt approved, or it skips them silently.",
+            f"{fix} Codex additionally needs its /hooks trust prompt approved, or it "
+            "skips them silently.",
         )
     if unverified:
         report.warn(