feat: send discovered servers during guard install

docs/cli-reference.md

@@ -345,7 +345,7 @@ snyk-agent-scan scan --config-file agent-scan.yaml \
 Manage [Agent Guard](https://evo.ai.snyk.io) hooks for Claude Code, Cursor, and Codex:
 
 ```bash
-snyk-agent-scan guard [install|uninstall] [OPTIONS]
+snyk-agent-scan guard [install|uninstall|discover] [OPTIONS]
 snyk-agent-scan guard
 ```
 
@@ -355,14 +355,34 @@ snyk-agent-scan guard
 snyk-agent-scan guard install {claude,cursor,codex,all} [OPTIONS]
 ```
 
+After configuring the hooks, installation sends a `hooksConfiguredServerDiscovery` event. It also configures a
+fire-and-forget session-start hook that reports discovered MCP servers with a `sessionStartServerDiscovery` event.
+
 | Flag | Type | Default | Description |
 | --- | --- | --- | --- |
 | `--url URL` | string | `https://api.snyk.io` | Remote hook base URL for the Snyk API environment. |
 | `--tenant-id ID` | string | — | Snyk tenant UUID. Required when minting a push key; unnecessary when `PUSH_KEY` is set. |
+| `--machine-id ID` | string | — | Required non-anonymous machine identifier sent in the `X-User` header's `identifier` field. May instead be set with `MACHINE_ID`. |
 | `--file PATH` | string | — | Override the client configuration path. |
 | `--managed` | boolean | `false` | Install in the admin/MDM-managed configuration rather than the user configuration. |
 | `--test` | boolean | `false` | **Deprecated/no-op.** |
 
+### `guard discover`
+
+```bash
+snyk-agent-scan guard discover [OPTIONS]
+```
+
+This internal command is invoked by the SessionStart hook configured by `guard install`. It reads the current target
+folder(s) from the selected client's hook payload, discovers MCP servers locally, and sends the resulting
+`sessionStartServerDiscovery` event directly to Agent Monitor; it is not normally run by hand.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--url URL` | string | `https://api.snyk.io` | Remote hook base URL for the Snyk API environment. |
+| `--client {claude-code,cursor,codex}` | string | required | Hook client whose target-folder payload and endpoint conventions should be used. |
+| `--scope {servers,skills,all}` | string | `all` | Discovery data to collect. The session-start hook installed by `guard install` passes `servers`, because the event it sends carries MCP servers only. |
+
 ### `guard uninstall`
 
 ```bash
@@ -381,6 +401,8 @@ snyk-agent-scan guard uninstall {claude,cursor,codex,all} [OPTIONS]
 | `PUSH_KEY` | Pre-provisioned push key; skips minting when set |
 | `TENANT_ID` | Tenant UUID alternative to `--tenant-id` |
 | `SNYK_TOKEN` | Required to mint/revoke push keys and verify that Guard is enabled for the tenant |
+| `MACHINE_ID` | Required non-anonymous machine identifier sent with hook events; alternative to `guard install --machine-id` |
+| `AGENT_SCAN_COMMAND` | Optional Agent Scan command invoked by the session-start discovery hook, with the hook arguments appended. The hook is installed only when this is set. A value that is not an existing executable file is run as a shell command. |
 
 ## Environment variables
 
@@ -502,10 +524,10 @@ snyk agent-scan --experimental ~/.claude/skills
 snyk-agent-scan guard
 
 # Install for all supported clients
-SNYK_TOKEN=... snyk-agent-scan guard install all --tenant-id "<tenant-uuid>"
+SNYK_TOKEN=... snyk-agent-scan guard install all --tenant-id "<tenant-uuid>" --machine-id "<machine-id>"
 
 # Install through an MDM-managed configuration
-PUSH_KEY=... snyk-agent-scan guard install cursor --managed
+PUSH_KEY=... snyk-agent-scan guard install cursor --managed --machine-id "<machine-id>"
 
 # Uninstall
 snyk-agent-scan guard uninstall all

src/agent_scan/agents/__init__.py

@@ -8,7 +8,7 @@
 import logging
 from pathlib import Path
 
-from agent_scan.agents.base import AgentDiscoverer
+from agent_scan.agents.base import AgentDiscoverer, DiscoveryScope
 from agent_scan.agents.claude_code import ClaudeCodeDiscoverer
 from agent_scan.agents.claude_desktop import ClaudeDesktopDiscoverer
 from agent_scan.agents.codex import CodexDiscoverer
@@ -37,18 +37,18 @@
 }
 
 
-def find_discoverers(home_directory: Path | None) -> list[AgentDiscoverer]:
-    """Construct one instance per registered discoverer with the given home, and
-    return only those whose ``client_exists()`` confirms the agent is installed.
-    Each returned instance is home-bound; the caller just runs
-    ``d.discover()`` on each.
+def find_discoverers(home_directory: Path | None, target_folders: list[Path] | None = None) -> list[AgentDiscoverer]:
+    """Construct one instance per registered discoverer with the given home and
+    explicit request targets, then return only those whose ``client_exists()``
+    confirms the agent is installed. Each returned instance is home-bound; the
+    caller just runs ``d.discover()`` on each.
 
     A discoverer whose ``client_exists()`` raises is skipped (and logged) so a
     single buggy subclass cannot abort discovery for the whole machine.
     """
     found: list[AgentDiscoverer] = []
     for cls in DISCOVERERS.values():
-        discoverer = cls(home_directory)
+        discoverer = cls(home_directory, target_folders)
         try:
             exists = discoverer.client_exists() is not None
         except Exception:
@@ -67,6 +67,7 @@ def find_discoverers(home_directory: Path | None) -> list[AgentDiscoverer]:
     "ClaudeDesktopDiscoverer",
     "CodexDiscoverer",
     "CursorDiscoverer",
+    "DiscoveryScope",
     "KiroDiscoverer",
     "OpenCodeDiscoverer",
     "VSCodeDiscoverer",

src/agent_scan/agents/base.py

@@ -13,6 +13,7 @@
 import traceback
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Iterator
+from enum import Enum
 from pathlib import Path
 
 import pyjson5
@@ -43,6 +44,13 @@
 # when the file is absent/empty/not-MCP.
 McpScanResult = list[tuple[str, StdioServer | RemoteServer]] | CouldNotParseMCPConfig | None
 
+
+class DiscoveryScope(str, Enum):
+    SERVERS = "servers"
+    SKILLS = "skills"
+    ALL = "all"
+
+
 # Cap traversal into ``~/.claude/plugins/{cache,repos}``
 _MAX_PLUGIN_RGLOB_DEPTH = 10
 
@@ -145,17 +153,19 @@ class AgentDiscoverer(ABC):
 
     name: str = ""
 
-    def __init__(self, home_directory: Path | None) -> None:
+    def __init__(self, home_directory: Path | None, target_folders: list[Path] | None = None) -> None:
         # ``None`` is the own-home sentinel; normalize to ``Path.home()`` so the
         # stored home is always concrete. ``expand_path`` treats ``None`` as
         # "unknown home — don't expand", which would leave a ``~``-prefixed literal
         # (e.g. ``~/.claude``) on an own-home scan whose relocating env var is unset.
         self.home_directory = home_directory if home_directory is not None else Path.home()
-        # Lazily-populated cache for _project_paths_with_ancestors. A discoverer
-        # serves a single scan (see find_discoverers), so the project list is
-        # stable for its lifetime and the discovery methods that consult it need
-        # not re-walk workspaceStorage / re-read ~/.claude.json each time.
-        self._project_paths_cache: list[Path] | None = None
+        self.target_folders = list(target_folders or [])
+        # Lazily-populated cache of the discovery roots (recorded project roots plus
+        # explicit target roots) with their ancestors. A discoverer serves a single
+        # scan (see find_discoverers), so the list is stable for its lifetime and
+        # discovery does not need to re-walk workspaceStorage / re-read
+        # ~/.claude.json each time.
+        self._discovery_paths_cache: list[Path] | None = None
 
     def _scans_own_home(self) -> bool:
         """True when this discoverer targets the scanning process's own user.
@@ -185,7 +195,11 @@ def _scans_own_home(self) -> bool:
         try:
             resolved_home = self.home_directory.resolve()
             return any(resolved_home == candidate.resolve() for candidate in candidates)
-        except OSError:
+        except (OSError, RuntimeError, ValueError):
+            # Fail closed: an unresolvable path is not proof of own-home, and this gate
+            # decides whether *this* process's relocating env vars apply to it. Catching
+            # more than OSError only widens what maps to that same safe answer -- letting
+            # anything else escape here would abort the whole discovery.
             return False
 
     def __init_subclass__(cls, *, abstract: bool = False, **kwargs: object) -> None:
@@ -214,13 +228,14 @@ def discover_mcp_servers(self) -> McpConfigsResult:
     def discover_skills(self) -> SkillsDirsResult:
         """List the agent's skills, keyed by absolute skills-dir path."""
 
-    def discover(self) -> ClientToInspect | None:
+    def discover(self, scope: DiscoveryScope = DiscoveryScope.ALL) -> ClientToInspect | None:
         """Assemble a ClientToInspect, or None when the agent isn't installed."""
         client_path = self.client_exists()
         if client_path is None:
             return None
-        mcp_configs = self.discover_mcp_servers()
-        skills_dirs = self.discover_skills()
+        scope = DiscoveryScope(scope)
+        mcp_configs = self.discover_mcp_servers() if scope in (DiscoveryScope.SERVERS, DiscoveryScope.ALL) else {}
+        skills_dirs = self.discover_skills() if scope in (DiscoveryScope.SKILLS, DiscoveryScope.ALL) else {}
         return ClientToInspect(
             name=self.name,
             client_path=client_path,
@@ -442,7 +457,7 @@ def _discover_plugin_mcp_files(
                     result[mcp_file.as_posix()] = parsed
         return result
 
-    # --- shared project-folder enumeration (used by both Claude Code and the VSCode family) ---
+    # --- shared project/target-folder enumeration ---
 
     def _discover_project_folders(self) -> list[Path]:
         """Return the project roots this agent has opened.
@@ -454,21 +469,45 @@ def _discover_project_folders(self) -> list[Path]:
         """
         return []
 
-    def _project_paths_with_ancestors(self) -> list[Path]:
-        """Project roots plus every ancestor up to filesystem root, deduplicated.
-
-        Walking up lets project-scope MCP and skills discovery pick up config
-        living in any parent folder of an opened project (e.g. a monorepo root
-        that contains many project subdirectories).
+    def _discover_target_folders(self) -> list[Path]:
+        """Return explicit roots targeted by the current discovery request.
 
-        The result is cached for the discoverer's lifetime.
+        Target folders come from request context (for example, a session-start
+        hook's current working directory or workspace roots). They remain
+        separate from the agent's persisted project history returned by
+        :meth:`_discover_project_folders`.
         """
-        if self._project_paths_cache is not None:
-            return self._project_paths_cache
+        return list(self.target_folders)
+
+    def _all_discovery_folders(self) -> list[Path]:
+        """Return project roots and non-alias target roots in stable literal order."""
+        projects = self._discover_project_folders()
+        resolved_projects: set[Path] = set()
+        for project in projects:
+            try:
+                resolved_projects.add(project.resolve())
+            except (OSError, RuntimeError, ValueError):
+                # Unresolvable paths stay distinct under their literal spelling.
+                resolved_projects.add(project)
+        targets: list[Path] = []
+        for target in self._discover_target_folders():
+            try:
+                key = target.resolve()
+            except (OSError, RuntimeError, ValueError):
+                key = target
+            if key not in resolved_projects:
+                targets.append(target)
+        # Deduped here because opencode's anchor list is the one consumer that does not go
+        # through _folders_with_ancestors, whose walk already absorbs duplicates.
+        return list(dict.fromkeys((*projects, *targets)))
+
+    @staticmethod
+    def _folders_with_ancestors(folders: list[Path]) -> list[Path]:
+        """Return each folder and its ancestors, preserving first-seen order."""
         seen: set[Path] = set()
         result: list[Path] = []
-        for project_path in self._discover_project_folders():
-            cur = project_path
+        for folder in folders:
+            cur = folder
             while True:
                 if cur not in seen:
                     seen.add(cur)
@@ -477,5 +516,18 @@ def _project_paths_with_ancestors(self) -> list[Path]:
                 if parent == cur:
                     break
                 cur = parent
-        self._project_paths_cache = result
         return result
+
+    def _discovery_paths_with_ancestors(self) -> list[Path]:
+        """Project and target roots plus every ancestor, deduplicated across both.
+
+        Walking up lets project-scope MCP and skills discovery pick up config living
+        in any parent folder of an opened project (e.g. a monorepo root that contains
+        many project subdirectories).
+
+        The result is cached for the discoverer's lifetime.
+        """
+        if self._discovery_paths_cache is not None:
+            return self._discovery_paths_cache
+        self._discovery_paths_cache = self._folders_with_ancestors(self._all_discovery_folders())
+        return self._discovery_paths_cache

src/agent_scan/agents/claude_code.py

@@ -176,7 +176,7 @@ def _discover_global_mcp_servers(self) -> McpConfigsResult:
         return {config_path.as_posix(): entries}
 
     def _discover_project_mcp_servers(self) -> McpConfigsResult:
-        """Per-project MCP discovery for each path in ``_project_paths_with_ancestors``.
+        """Per-project MCP discovery for each path in ``_discovery_paths_with_ancestors``.
 
         Two sources are checked at every path:
 
@@ -197,7 +197,7 @@ def _discover_project_mcp_servers(self) -> McpConfigsResult:
         # Iterate every opened project root *and* its ancestors up to filesystem
         # root, so config in a parent folder (e.g. a monorepo root) is picked up
         # for the sub-projects beneath it.
-        for path in self._project_paths_with_ancestors():
+        for path in self._discovery_paths_with_ancestors():
             key = path.as_posix()
             # Source 1: inline ``projects.<path>.mcpServers`` recorded in ``.claude.json``.
             # For an ancestor this only matches if that ancestor was itself opened
@@ -248,7 +248,7 @@ def _discover_project_skills(self) -> SkillsDirsResult:
         ``PermissionError`` tolerance as :meth:`_discover_global_skill`.
         """
         result: SkillsDirsResult = {}
-        for path in self._project_paths_with_ancestors():
+        for path in self._discovery_paths_with_ancestors():
             for rel in self._project_skills_relative:
                 skills_dir = path / rel
                 entries = self._scan_skills_dir(skills_dir)

src/agent_scan/agents/codex.py

@@ -302,7 +302,7 @@ def _discover_project_mcp_servers(self) -> McpConfigsResult:
         absolute path, so an ancestor equal to ``codex_home`` dedups in the merge.
         """
         result: McpConfigsResult = {}
-        for path in self._project_paths_with_ancestors():
+        for path in self._discovery_paths_with_ancestors():
             config_path = path / ".codex" / self._config_filename
             result.update(self._mcp_servers_from_data(self._load_toml_file(config_path), config_path))
         return result
@@ -366,7 +366,7 @@ def _discover_global_skills(self) -> SkillsDirsResult:
     def _discover_project_skills(self) -> SkillsDirsResult:
         """Scan ``<project>/.agents/skills`` for every registered project and ancestor."""
         result: SkillsDirsResult = {}
-        for path in self._project_paths_with_ancestors():
+        for path in self._discovery_paths_with_ancestors():
             skills_dir = path / ".agents" / "skills"
             entries = self._scan_skills_dir(skills_dir)
             if entries is not None:

src/agent_scan/agents/opencode.py

@@ -37,7 +37,7 @@ class OpenCodeDiscoverer(AgentDiscoverer):
       empirically). Singular ``skill/`` is opencode's documented
       backwards-compat spelling (https://opencode.ai/docs/config: "Singular
       names (e.g., ``agent/``) are also supported for backwards compatibility").
-    * Project — for every project root in ``_project_paths_with_ancestors``
+    * Project — for every project root in ``_discovery_paths_with_ancestors``
       (and its ancestors): ``<root>/opencode.{json,jsonc}`` *and*
       ``<root>/.opencode/opencode.{json,jsonc}`` (both are real opencode config
       locations — see :meth:`_project_config_bases`) plus
@@ -516,7 +516,7 @@ def _discover_global_mcp_servers(self) -> McpConfigsResult:
 
     def _discover_project_mcp_servers(self) -> McpConfigsResult:
         result: McpConfigsResult = {}
-        for project in self._project_paths_with_ancestors():
+        for project in self._discovery_paths_with_ancestors():
             for base in self._project_config_bases(project):
                 result.update(self._scan_config_dir(base))
         return result
@@ -565,7 +565,7 @@ def _discover_global_skills(self) -> SkillsDirsResult:
 
     def _discover_project_skills(self) -> SkillsDirsResult:
         result: SkillsDirsResult = {}
-        for project in self._project_paths_with_ancestors():
+        for project in self._discovery_paths_with_ancestors():
             for rel in self._project_skills_relative:
                 self._record_skills_at(result, project / rel)
         return result
@@ -593,7 +593,7 @@ def _iter_candidate_config_files(self) -> list[Path]:
         for base in self._global_config_dirs():
             for filename in _CONFIG_FILENAMES:
                 candidates.append(base / filename)
-        for project in self._project_paths_with_ancestors():
+        for project in self._discovery_paths_with_ancestors():
             for base in self._project_config_bases(project):
                 for filename in _CONFIG_FILENAMES:
                     candidates.append(base / filename)
@@ -630,7 +630,7 @@ def _discover_config_skills_paths(self) -> SkillsDirsResult:
         # opencode's instance dirs (the db ``worktree`` leaves); computed once so
         # the relative-entry resolution below doesn't re-read the SQLite db per
         # candidate config file.
-        worktrees = self._discover_project_folders()
+        worktrees = self._all_discovery_folders()
         for config_path in self._iter_candidate_config_files():
             data = self._load_json_file(config_path)
             if not isinstance(data, dict):

src/agent_scan/agents/vscode/antigravity.py

@@ -123,7 +123,7 @@ def _discover_project_folders(self) -> list[Path]:
         ``super()`` (the ``workspaceStorage`` walk) is still consulted so that if
         a future Antigravity build does populate it, those workspaces surface too;
         in practice it returns nothing today. Duplicates across the two sources are
-        collapsed downstream by :meth:`_project_paths_with_ancestors`.
+        collapsed downstream by :meth:`_discovery_paths_with_ancestors`.
         """
         folders = super()._discover_project_folders()
         folders.extend(self._gemini_project_folders())