failproofai 1.0.12-beta.0 → 1.0.12-beta.2

package/hermes-plugin/README.md

@@ -165,23 +165,25 @@ decision, because otherwise corrupted retry state could block a turn forever.
 ## Local protocol
 
 Requests and responses use the existing length-prefixed failproofaid Unix
-socket protocol, version 1.
+socket protocol, version 2. A v1 daemon must be upgraded before it can safely
+evaluate agent/profile-scoped policies.
 
 ```json
 {
   "type": "policyEvaluation",
-  "protocolVersion": 1,
+  "protocolVersion": 2,
   "integration": "hermes",
   "event": "pre_tool_call",
   "payload": {},
-  "cwd": "/workspace/project"
+  "cwd": "/workspace/project",
+  "agentSettingsPath": "/path/to/the/hermes/profile"
 }
 ```
 
 ```json
 {
   "type": "policyResult",
-  "protocolVersion": 1,
+  "protocolVersion": 2,
   "decision": "instruct",
   "policyNames": ["custom/approved-write-route"],
   "reason": "Use the approved write route.",

package/hermes-plugin/__init__.py

@@ -102,6 +102,32 @@ def _profile_name() -> str:
     return "default"
 
 
+def _profile_settings_path(profile: str) -> str | None:
+    """Evidence of the profile running this plugin, not a transcript guess."""
+    try:
+        # The host's own resolver first: it honours a per-task profile
+        # override as well as HERMES_HOME, so each profile of a multi-profile
+        # gateway reports its own config (and roster identity), not the
+        # process-wide one.
+        from hermes_constants import get_hermes_home
+
+        hosted = Path(get_hermes_home()).expanduser() / "config.yaml"
+        return str(hosted.absolute()) if hosted.is_file() else None
+    except Exception:
+        pass
+    configured = os.environ.get("HERMES_HOME", "").strip()
+    if configured:
+        selected = Path(configured).expanduser() / "config.yaml"
+    elif profile == "default":
+        selected = Path.home() / ".hermes" / "config.yaml"
+    elif re.fullmatch(r"[A-Za-z0-9._-]{1,80}", profile):
+        selected = Path.home() / ".hermes" / "profiles" / profile / "config.yaml"
+    else:
+        return None
+    # An unresolvable profile does not acquire some other profile's ID.
+    return str(selected.absolute()) if selected.is_file() else None
+
+
 def _string(value: object) -> str:
     return value if isinstance(value, str) else ""
 
@@ -660,6 +686,7 @@ class FailproofAIPlugin:
             event=event,
             payload=payload,
             cwd=cwd,
+            agent_settings_path=_profile_settings_path(self.profile),
             connect_timeout_ms=self.connect_timeout_ms,
             evaluation_timeout_ms=timeout_ms or self.evaluation_timeout_ms,
         )

package/hermes-plugin/client.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
-PROTOCOL_VERSION = 1
+PROTOCOL_VERSION = 2
 MAX_FRAME_BYTES = 16 * 1024 * 1024
 MAX_REQUEST_BYTES = 1024 * 1024
 
@@ -75,6 +75,7 @@ def evaluate_policy(
     event: str,
     payload: Mapping[str, Any],
     cwd: str | None,
+    agent_settings_path: str | None = None,
     connect_timeout_ms: int = 250,
     evaluation_timeout_ms: int = 12_000,
 ) -> PolicyVerdict:
@@ -85,6 +86,9 @@ def evaluate_policy(
         "event": event,
         "payload": dict(payload),
         "cwd": cwd,
+        # An unknown profile is explicit. Omitting this field would let a new
+        # daemon's warm worker attribute the call to its own Hermes home.
+        "agentSettingsPath": agent_settings_path or "",
     }
     try:
         body = json.dumps(

package/hermes-plugin/plugin.yaml

@@ -1,5 +1,5 @@
 name: failproofai
-version: 1.0.12-beta.0
+version: 1.0.12-beta.2
 description: Real-time FailproofAI policy enforcement for Hermes
 manifest_version: 2
 api_version: 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "1.0.12-beta.0",
+  "version": "1.0.12-beta.2",
   "description": "Observability and enforcement for AI agent harnesses. 40 built-in policies hooked into 12 of them — Claude Code, Codex, Cursor, Hermes, OpenClaw and more — blocking the tool call before it runs. Local dashboard included, no account needed.",
   "bin": {
     "failproofai": "./dist/cli.mjs",
@@ -118,22 +118,23 @@
     "postcss": "8.5.26",
     "eslint-plugin-react-hooks": "7.0.1",
     "vite": "8.1.6",
-    "undici": "7.29.1",
+    "undici": "7.30.1",
+    "zod": "4.6.6",
     "brace-expansion": "5.0.12",
     "sharp": "0.35.5",
     "source-map-js": "1.2.2",
     "browserslist": "4.28.8"
   },
   "optionalDependencies": {
-    "@failproofai/failproofaid-linux-x64": "1.0.12-beta.0",
-    "@failproofai/failproofaid-linux-arm64": "1.0.12-beta.0",
-    "@failproofai/failproofaid-darwin-x64": "1.0.12-beta.0",
-    "@failproofai/failproofaid-darwin-arm64": "1.0.12-beta.0"
+    "@failproofai/failproofaid-linux-x64": "1.0.12-beta.2",
+    "@failproofai/failproofaid-linux-arm64": "1.0.12-beta.2",
+    "@failproofai/failproofaid-darwin-x64": "1.0.12-beta.2",
+    "@failproofai/failproofaid-darwin-arm64": "1.0.12-beta.2"
   },
   "failproofaidBinaries": {
-    "linux-x64": "61710dd6261ff0deb1116e390c366c26809bf04bb2e2c16f279b7d79e1819049",
-    "linux-arm64": "5e9501522d35b32790664b4f3b1b90aa1728629f5013df94e72c2e2a11842bd2",
-    "darwin-x64": "e9d195cf30b6bc2427b7cbe89e354cc8dab7ae02e7c45a7e44a941eda84c2674",
-    "darwin-arm64": "d70ae3a3b8073ace0852a20671dba3d32f380b97ed4a01f5791a13d2fa12e63b"
+    "linux-x64": "4c09117fdb80d87792d1d2b77d9359cdbd0c522b5a6222ab7b927659130ddf54",
+    "linux-arm64": "dd390d76561267fc519ceb96fb90be340044e2f564bef36a44e284f227d93f29",
+    "darwin-x64": "62381f7ffe21d02289c36c4b205166b2867dbde986444d1ea185241b94fd04ef",
+    "darwin-arm64": "9ad798817d3048a5126e80dc71883538d37c1b6b6443e9c19389dc2583c8f675"
   }
 }

package/src/audit/open-browser.ts

@@ -32,17 +32,16 @@ export function canOpenBrowser(
 }
 
 /** Open a URL with the platform's default handler. Never throws. */
-export function openUrl(url: string): void {
+export function openUrl(url: string, platform: NodeJS.Platform = process.platform): void {
   let cmd: string;
   let args: string[];
-  if (process.platform === "darwin") {
+  if (platform === "darwin") {
     cmd = "open";
     args = [url];
-  } else if (process.platform === "win32") {
-    // `start` is a cmd builtin; the empty "" is the (required) window-title arg
-    // so a URL containing `&` or spaces isn't mis-parsed as the title.
-    cmd = "cmd";
-    args = ["/c", "start", "", url];
+  } else if (platform === "win32") {
+    // ShellExecute via rundll32 avoids interpreting URL characters as cmd.exe syntax.
+    cmd = "rundll32.exe";
+    args = ["url.dll,FileProtocolHandler", url];
   } else {
     cmd = "xdg-open";
     args = [url];

package/src/hooks/agent-roster.ts

@@ -0,0 +1,180 @@
+/**
+ * Read the daemon-owned profile roster. The telemetry agent_id and transcript
+ * path are not profile evidence. A scoped Cloud assignment is withheld unless
+ * this invocation resolves to one of the daemon's recorded config paths.
+ */
+import { lstatSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { agentRosterFile } from "./fp-home";
+import { validAgentIdentity, type AgentIdentity } from "./agent-targets";
+import type { HookScope, IntegrationType } from "./types";
+
+/** `MAX_AGENTS` / `MAX_ROSTER_BYTES` in the daemon's `agent_roster.rs`. */
+export const MAX_ROSTER_AGENTS = 256;
+export const MAX_ROSTER_BYTES = 4_000_000;
+
+const USER_SETTINGS: Partial<Record<IntegrationType, string>> = {
+  claude: ".claude/settings.json",
+  codex: ".codex/hooks.json",
+  copilot: ".copilot/hooks/failproofai.json",
+  cursor: ".cursor/hooks.json",
+  opencode: ".config/opencode/opencode.json",
+  pi: ".pi/agent/settings.json",
+  factory: ".factory/hooks.json",
+  devin: ".config/devin/config.json",
+  antigravity: ".gemini/config/hooks.json",
+  goose: ".agents/plugins/failproofai/hooks/hooks.json",
+};
+
+const PROJECT_SETTINGS: Partial<Record<IntegrationType, string[]>> = {
+  claude: [".claude/settings.local.json", ".claude/settings.json"],
+  codex: [".codex/hooks.json"],
+  copilot: [".github/hooks/failproofai.json"],
+  cursor: [".cursor/hooks.json"],
+  opencode: [".opencode/opencode.json"],
+  pi: [".pi/settings.json"],
+  factory: [".factory/hooks.json"],
+  devin: [".devin/config.json"],
+  antigravity: [".agents/hooks.json"],
+  goose: [".agents/plugins/failproofai/hooks/hooks.json"],
+};
+
+function installedHookAt(path: string, cli: IntegrationType): boolean {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile() || stat.size > 131_072) return false;
+    const text = readFileSync(path, "utf8");
+    if (text.includes("failproofai")) return true;
+    // Pi's project entry is portable and relative to `.pi/settings.json`:
+    // `../pi-extension` contains no product name. Missing it here let a
+    // simultaneously installed user hook masquerade as this project's Pi.
+    if (cli !== "pi") return false;
+    const config: unknown = JSON.parse(text);
+    if (!config || typeof config !== "object" || Array.isArray(config)) return false;
+    const packages = (config as { packages?: unknown }).packages;
+    return Array.isArray(packages) && packages.some(
+      (entry) => typeof entry === "string" && /(?:^|\/)pi-extension\/?$/.test(entry),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Called in the originating hook process; the worker's env may be different. */
+export function runtimeAgentSettingsPath(
+  cli: IntegrationType,
+  cwd?: string,
+  userHome = homedir(),
+  hookScope?: HookScope,
+): string | null {
+  if (cli === "hermes") {
+    if (hookScope && hookScope !== "user") return null;
+    const home = process.env.HERMES_HOME;
+    return resolve(home?.trim() ? home : resolve(userHome, ".hermes"), "config.yaml");
+  }
+  if (cli === "openclaw") {
+    if (hookScope && hookScope !== "user") return null;
+    const config = process.env.OPENCLAW_CONFIG_PATH;
+    if (config?.trim()) return resolve(config);
+    const state = process.env.OPENCLAW_STATE_DIR || process.env.OPENCLAW_HOME;
+    if (state?.trim()) return resolve(state, "openclaw.json");
+    // `openclaw --profile <name>` runs from `~/.openclaw-<name>`; a gateway
+    // that exports only the profile name must still resolve to that profile's
+    // config, not the default one (each profile has its own roster identity).
+    const profile = process.env.OPENCLAW_PROFILE?.trim();
+    if (profile && profile !== "default" && /^[A-Za-z0-9._-]{1,80}$/.test(profile) && !profile.startsWith(".")) {
+      return resolve(userHome, `.openclaw-${profile}`, "openclaw.json");
+    }
+    return resolve(userHome, ".openclaw", "openclaw.json");
+  }
+  const relative = USER_SETTINGS[cli];
+  if (!relative) return null;
+  const override = cli === "codex" ? process.env.CODEX_HOME
+    : cli === "claude" ? process.env.CLAUDE_CONFIG_DIR : undefined;
+  const user = resolve(override?.trim() ? override : userHome, override?.trim()
+    ? cli === "codex" ? "hooks.json" : "settings.json"
+    : relative);
+  if (hookScope === "user") return user;
+
+  const scopeFiles = hookScope === "local"
+    ? cli === "claude" ? [".claude/settings.local.json"] : []
+    : hookScope === "project"
+      ? (PROJECT_SETTINGS[cli] ?? []).filter((name) => name !== ".claude/settings.local.json")
+      : PROJECT_SETTINGS[cli] ?? [];
+  const matches = new Set<string>();
+  if (hookScope === undefined && installedHookAt(user, cli)) matches.add(user);
+  let dir = resolve(cwd ?? process.cwd());
+  const userRoot = resolve(userHome);
+  for (let depth = 0; depth < 16 && dir !== userRoot; depth++) {
+    for (const candidate of scopeFiles) {
+      const path = resolve(dir, candidate);
+      if (installedHookAt(path, cli)) matches.add(path);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // No source hint can tell WHICH installed hook fired if both user and
+  // project/local scopes contain us. A guessed profile would let an exact
+  // assignment match another installation: withhold it instead.
+  if (matches.size > 1) return null;
+  if (hookScope === "project" || hookScope === "local") return matches.values().next().value ?? null;
+  return matches.values().next().value ?? user;
+}
+
+export function readRuntimeAgentIdentity(cli: IntegrationType, settingsPath: string | null): AgentIdentity | null {
+  if (!settingsPath) return null;
+  try {
+    const path = agentRosterFile();
+    const stat = lstatSync(path);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size > MAX_ROSTER_BYTES) return null;
+    const roster: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!roster || typeof roster !== "object" || Array.isArray(roster)) return null;
+    const data = roster as Record<string, unknown>;
+    if (data.schemaVersion !== 1 || !Array.isArray(data.agents) || data.agents.length > MAX_ROSTER_AGENTS) return null;
+    const absolute = resolve(settingsPath);
+    const agent = data.agents.find((entry: unknown) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+      const record = entry as Record<string, unknown>;
+      return record.integration === cli && record.settingsPath === absolute &&
+        validAgentIdentity({ integration: record.integration, instanceId: record.instanceId });
+    });
+    const instanceId = (agent as Record<string, unknown> | undefined)?.instanceId;
+    return validAgentIdentity({ integration: cli, instanceId })
+      ? { integration: cli, instanceId: instanceId as string }
+      : null;
+  } catch {
+    // Unavailable, malformed or old roster: never infer a profile from cwd,
+    // transcript, or the display name and widen a scoped deployment.
+    return null;
+  }
+}
+
+/**
+ * Display labels from the daemon's roster, by `agt_` id (`claude / .claude-work`
+ * style: integration, then the profile label). For listings only; never an
+ * identity — `readRuntimeAgentIdentity` is the only thing that decides which
+ * profile a hook is. Empty when the roster cannot be read.
+ */
+export function readRosterLabels(): Map<string, string> {
+  const out = new Map<string, string>();
+  try {
+    const path = agentRosterFile();
+    const stat = lstatSync(path);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size > MAX_ROSTER_BYTES) return out;
+    const roster: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!roster || typeof roster !== "object" || Array.isArray(roster)) return out;
+    const data = roster as Record<string, unknown>;
+    if (data.schemaVersion !== 1 || !Array.isArray(data.agents) || data.agents.length > MAX_ROSTER_AGENTS) return out;
+    for (const entry of data.agents) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      const record = entry as Record<string, unknown>;
+      if (typeof record.instanceId !== "string" || typeof record.profileLabel !== "string" || record.profileLabel === "") continue;
+      out.set(record.instanceId, record.profileLabel.slice(0, 80));
+    }
+  } catch {
+    // No roster: the bare ids are shown.
+  }
+  return out;
+}

package/src/hooks/agent-skill.ts

@@ -0,0 +1,203 @@
+/**
+ * The `failproofai` skill: one small SKILL.md that `failproofai config` puts in
+ * every agent this machine has, in that agent's own user-scope skills folder.
+ *
+ * It carries no instructions of its own. It points the agent at the umbrella
+ * skill in the public FailproofAI/skills repository, which the agent reads when
+ * a FailproofAI task comes up, along with whichever focused sibling skill and
+ * `references/*.md` file the task needs. So the content is never stale on
+ * disk: changing that repository changes what every machine reads next, with
+ * no release and no re-run of setup.
+ *
+ * Every folder below was verified on 2026-10-23 against the real CLI (versions
+ * in each comment), by planting a probe skill in each candidate folder and
+ * reading what the CLI listed, or what it sent to a mock model server.
+ *
+ * Never `~/.agents/skills`, although many agents read it: Claude Code does not
+ * read it at all, Codex lists a skill found there and in `~/.codex/skills`
+ * twice, Copilot stops reading it once `COPILOT_HOME` is set, and in OpenClaw it
+ * outranks OpenClaw's own folder. Each agent's own folder works on its own.
+ *
+ * The frontmatter is shaped by the strictest of them: `name` equals the folder
+ * name (Claude Code, Cursor and Devin go by the folder, the rest by `name`, and
+ * Antigravity shows a skill without one as "SKILL"); Copilot drops a skill whose
+ * description is over 1024 characters, droid shows the model the first 200, and
+ * Hermes the first 57 — so the description is short and leads with what it is
+ * for.
+ */
+import { existsSync, mkdirSync, rmdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { listHermesProfiles } from "../../lib/hermes-profiles";
+import { listOpenClawProfiles } from "../../lib/openclaw-profiles";
+import { hookLogWarn } from "./hook-logger";
+import { writeConfigFileAtomic } from "./safe-config-write";
+import { INTEGRATION_TYPES, type IntegrationType } from "./types";
+
+export const AGENT_SKILL_NAME = "failproofai";
+
+/**
+ * Sits beside SKILL.md in a folder failproofai wrote. A `failproofai` folder
+ * without it belongs to someone else — most often the full skill installed with
+ * `npx skills add FailproofAI/skills` — and is never overwritten or removed.
+ */
+export const AGENT_SKILL_MARKER = ".failproofai-managed";
+
+const SKILLS_RAW = "https://raw.githubusercontent.com/FailproofAI/skills/main/skills";
+
+export const AGENT_SKILL_MD = `---
+name: ${AGENT_SKILL_NAME}
+description: FailproofAI hooks, policies, daemon, Cloud, the fp CLI and the SDK. Use for any question about setting up, running or fixing FailproofAI.
+---
+
+# FailproofAI
+
+This skill is a pointer. Before acting on anything FailproofAI, read the full skill, which is kept current online (use your web fetch tool, or \`curl -fsSL <url>\`):
+
+${SKILLS_RAW}/${AGENT_SKILL_NAME}/SKILL.md
+
+Files it names by a relative path, such as \`references/cli.md\`, are in that same folder: ${SKILLS_RAW}/${AGENT_SKILL_NAME}/<path>
+
+For focused work, read the matching skill too. Each has the same layout, with its own \`references/\` beside it.
+
+- Writing or testing a policy: ${SKILLS_RAW}/failproofai-policy-author/SKILL.md
+- Publishing a policy pack: ${SKILLS_RAW}/failproofai-policy-publish/SKILL.md
+- FailproofAI Cloud and the \`fp\` CLI: ${SKILLS_RAW}/fp-cloud-cli/SKILL.md
+- Adding the SDK to an agent, or running an evaluator: ${SKILLS_RAW}/failproofai-sdk/SKILL.md
+- Planning evaluations: ${SKILLS_RAW}/failproofai-eval-brainstorm/SKILL.md
+`;
+
+/** An agent's own override for where it keeps its files, else the default. */
+function envDir(name: string, fallback: string): string {
+  const value = (process.env[name] ?? "").trim();
+  return value ? resolve(value) : fallback;
+}
+
+/**
+ * The skills folders `id` reads at user scope — one, except for Hermes and
+ * OpenClaw, where every profile reads only its own.
+ */
+export function agentSkillRoots(id: IntegrationType): string[] {
+  const home = homedir();
+  const config = envDir("XDG_CONFIG_HOME", join(home, ".config"));
+  switch (id) {
+    // 2.1.309. CLAUDE_CONFIG_DIR replaces ~/.claude rather than adding to it.
+    case "claude":
+      return [join(envDir("CLAUDE_CONFIG_DIR", join(home, ".claude")), "skills")];
+    // 0.164.0. Its own skill installer writes here too.
+    case "codex":
+      return [join(envDir("CODEX_HOME", join(home, ".codex")), "skills")];
+    // 1.0.103.
+    case "copilot":
+      return [join(envDir("COPILOT_HOME", join(home, ".copilot")), "skills")];
+    // 2026.10.22. Always under HOME: CURSOR_CONFIG_DIR does not move it.
+    case "cursor":
+      return [join(home, ".cursor", "skills")];
+    // 1.19.4.
+    case "opencode":
+      return [join(config, "opencode", "skills")];
+    // 1.4.0 and 0.73.1. Not the pi-extension package: a `skills/` folder there
+    // makes Pi stop loading the package's index.ts, and with it enforcement.
+    case "pi":
+      return [join(envDir("PI_CODING_AGENT_DIR", join(home, ".pi", "agent")), "skills")];
+    // 0.21.3. A profile reads its own skills/ and no other profile's.
+    case "hermes":
+      return listHermesProfiles().map((p) => join(p.home, "skills"));
+    // 2026.9.2. The same profile homes its hooks are installed into.
+    case "openclaw":
+      return listOpenClawProfiles().map((p) => join(p.home, "skills"));
+    // 0.248.0. FACTORY_HOME_OVERRIDE stands in for HOME.
+    case "factory":
+      return [join(envDir("FACTORY_HOME_OVERRIDE", home), ".factory", "skills")];
+    // 3000.11.205.
+    case "devin":
+      return [join(config, "devin", "skills")];
+    // 1.4.6. The documented user folder, beside the hooks.json we write; not
+    // ~/.gemini/antigravity/skills, which it does not read.
+    case "antigravity":
+      return [join(home, ".gemini", "config", "skills")];
+    // 1.55.0. GOOSE_PATH_ROOT moves Goose's whole config tree.
+    case "goose": {
+      const root = (process.env.GOOSE_PATH_ROOT ?? "").trim();
+      return [root ? join(resolve(root), "config", "skills") : join(config, "goose", "skills")];
+    }
+  }
+}
+
+/**
+ * Whether `id` already has a `failproofai` skill from a folder it also reads,
+ * and would list ours beside it rather than pick one. Only Codex: it reads
+ * `~/.agents/skills` (always under HOME, whatever CODEX_HOME says) as well as
+ * its own folder and lists a name found in both twice (0.164.0) — and that is
+ * where `npx skills add FailproofAI/skills -g` puts the full skill for it.
+ */
+function listedTwice(id: IntegrationType): boolean {
+  return id === "codex" && existsSync(join(homedir(), ".agents", "skills", AGENT_SKILL_NAME, "SKILL.md"));
+}
+
+/**
+ * Write the skill for each agent in `ids`. Never fails setup: an agent whose
+ * folder cannot be written is logged and skipped. Returns the agents it was
+ * written for.
+ */
+export function installAgentSkill(ids: readonly IntegrationType[]): IntegrationType[] {
+  const installed: IntegrationType[] = [];
+  for (const id of ids) {
+    let wrote = false;
+    const covered = listedTwice(id);
+    for (const root of agentSkillRoots(id)) {
+      const dir = join(root, AGENT_SKILL_NAME);
+      const ours = existsSync(join(dir, AGENT_SKILL_MARKER));
+      // Covered already: a copy of ours from an earlier run is now the duplicate.
+      if (covered) {
+        if (ours) removeSkillDir(dir);
+        continue;
+      }
+      if (existsSync(dir) && !ours) continue;
+      let created = false;
+      let marked = false;
+      try {
+        // Marker first: a run interrupted before it would leave a folder every
+        // later run takes for someone else's and skips.
+        mkdirSync(root, { recursive: true });
+        if (!existsSync(dir)) {
+          mkdirSync(dir);
+          created = true;
+        }
+        writeConfigFileAtomic(join(dir, AGENT_SKILL_MARKER), "", { backup: false, symlinks: "replace" });
+        marked = true;
+        writeConfigFileAtomic(join(dir, "SKILL.md"), AGENT_SKILL_MD, { backup: false, symlinks: "replace" });
+        wrote = true;
+      } catch (err) {
+        if (created && !marked) {
+          try { rmdirSync(dir); } catch { /* Preserve a directory that is no longer empty. */ }
+        }
+        hookLogWarn(`the failproofai skill was not written to ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    if (wrote) installed.push(id);
+  }
+  return installed;
+}
+
+/** Every skill folder failproofai wrote, for any agent. */
+export function installedAgentSkillDirs(): string[] {
+  const dirs = INTEGRATION_TYPES.flatMap((id) => agentSkillRoots(id).map((root) => join(root, AGENT_SKILL_NAME)));
+  return [...new Set(dirs)].filter((dir) => existsSync(join(dir, AGENT_SKILL_MARKER)));
+}
+
+/** Remove one skill folder; never throws, so neither setup nor uninstall stops on it. */
+function removeSkillDir(dir: string): boolean {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch (err) {
+    hookLogWarn(`the failproofai skill was not removed from ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+
+/** Remove every skill folder failproofai wrote. Returns the folders removed. */
+export function removeAgentSkill(): string[] {
+  return installedAgentSkillDirs().filter(removeSkillDir);
+}

package/src/hooks/agent-targets.ts

@@ -0,0 +1,60 @@
+/** Agent identity for enforcement, separate from the project-derived telemetry agent_id. */
+import { INTEGRATION_TYPES, type IntegrationType } from "./types";
+
+export interface AgentIdentity {
+  integration: IntegrationType;
+  instanceId: string;
+}
+
+export interface AgentTarget {
+  integration: IntegrationType;
+  instanceId?: string;
+}
+
+const INSTANCE_ID_RE = /^agt_[0-9a-f]{16,32}$/;
+const integrations = new Set<string>(INTEGRATION_TYPES);
+
+export function validAgentIdentity(value: unknown): value is AgentIdentity {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const agent = value as Record<string, unknown>;
+  return Object.keys(agent).every((key) => key === "integration" || key === "instanceId") &&
+    typeof agent.integration === "string" && integrations.has(agent.integration) &&
+    typeof agent.instanceId === "string" && INSTANCE_ID_RE.test(agent.instanceId);
+}
+
+/** Null/absent means all; a malformed selector is never silently treated as all. */
+export function parseAgentTargets(value: unknown, schemaVersion: number): AgentTarget[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (schemaVersion < 3 || !Array.isArray(value) || value.length < 1 || value.length > 32) {
+    throw new Error("invalid agentTargets in cloud-managed active manifest");
+  }
+  const seen = new Set<string>();
+  return value.map((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error("invalid agentTargets in cloud-managed active manifest");
+    }
+    const entry = raw as Record<string, unknown>;
+    if (Object.keys(entry).some((key) => key !== "integration" && key !== "instanceId") ||
+        typeof entry.integration !== "string" || !integrations.has(entry.integration) ||
+        (entry.instanceId !== undefined &&
+          (typeof entry.instanceId !== "string" || !INSTANCE_ID_RE.test(entry.instanceId)))) {
+      throw new Error("invalid agentTargets in cloud-managed active manifest");
+    }
+    const key = `${entry.integration}\0${entry.instanceId ?? ""}`;
+    if (seen.has(key)) throw new Error("duplicate agentTargets in cloud-managed active manifest");
+    seen.add(key);
+    return {
+      integration: entry.integration as IntegrationType,
+      ...(entry.instanceId !== undefined ? { instanceId: entry.instanceId as string } : {}),
+    };
+  });
+}
+
+/** An unknown runtime identity cannot widen any scoped assignment. */
+export function agentTargetsMatch(targets: readonly AgentTarget[] | undefined, agent: AgentIdentity | null): boolean {
+  if (targets === undefined) return true;
+  if (!validAgentIdentity(agent)) return false;
+  return targets.some((target) =>
+    target.integration === agent.integration &&
+    (target.instanceId === undefined || target.instanceId === agent.instanceId));
+}