agent-skillboard 0.2.18 → 0.3.0

package/src/compatibility.mjs

@@ -0,0 +1,24 @@
+export const V1_COMPATIBILITY_REMOVAL_VERSION = "v0.4.0";
+export const V1_MIGRATION_COMMAND = "skillboard migrate v2";
+export const V1_COMPATIBILITY_NOTICE =
+  `Version 1 policy is deprecated and read-only; run \`${V1_MIGRATION_COMMAND}\`. Support ends in package release ${V1_COMPATIBILITY_REMOVAL_VERSION}.`;
+export const V1_MUTATION_ERROR = `Version 1 policy is read-only. Run \`${V1_MIGRATION_COMMAND}\`.`;
+export const STALE_V1_PROJECTION_ERROR = "This pre-v2 policy projection is stale; regenerate it from version 2 policy.";
+
+export function compatibilityForVersion(version) {
+  return version === 1 ? { notice: V1_COMPATIBILITY_NOTICE, removalVersion: V1_COMPATIBILITY_REMOVAL_VERSION } : null;
+}
+
+export function assertV2MutationVersion(version) {
+  if (version === 1 || version === undefined) throw new Error(V1_MUTATION_ERROR);
+}
+
+export function isPreV2ActionId(actionId) {
+  return /^(?:review-install-unit|trust-install-unit|activate-skill|block-install-unit):/.test(actionId);
+}
+
+export function assertCurrentProjectionVersion(projectionVersion, policyVersion) {
+  if (projectionVersion !== undefined && Number(projectionVersion) !== policyVersion) {
+    throw new Error(`${STALE_V1_PROJECTION_ERROR} Expected policy projection version ${policyVersion}, got ${projectionVersion}.`);
+  }
+}

package/src/control/can-use-guard.mjs

@@ -6,8 +6,12 @@ import {
 import { workflowConflictEntriesForSkill } from "../conflicts.mjs";
 import { isModelSelectableInvocation, isUserControlledSource } from "../domain/source-classes.mjs";
 import { classifySkillTrust, workflowSkillRole } from "./source-trust.mjs";
+import { authorizeV2Skill } from "./v2-guard.mjs";
 
-export function canUseSkill(workspace, skillId, workflowName) {
+export function canUseSkill(workspace, skillId, workflowName, agentName) {
+  if (workspace.version === 2) {
+    return canUseV2Skill(workspace, skillId, agentName);
+  }
   const policy = checkPolicy(workspace);
   const skill = workspace.skills.find((candidate) => candidate.id === skillId);
   const workflow = workspace.workflows.find((candidate) => candidate.name === workflowName);
@@ -51,6 +55,22 @@ export function canUseSkill(workspace, skillId, workflowName) {
   return canUseResult(reasons.length === 0, skillId, workflowName, skill, workflow, reasons, role, classifySkillTrust(workspace, skill));
 }
 
+function canUseV2Skill(workspace, skillId, agentName) {
+  const skill = workspace.skills.find((candidate) => candidate.id === skillId);
+  const authorization = authorizeV2Skill(skillId, skill, workspace.inventory, agentName);
+  return {
+    allowed: authorization.allowed,
+    automaticAllowed: authorization.allowed,
+    allowedUse: authorization.allowed ? allowedUse(skillId) : null,
+    skill: skillId,
+    workflow: null,
+    agent: agentName ?? null,
+    workflowKnown: true,
+    integrityError: authorization.integrityError,
+    reasons: authorization.reasons
+  };
+}
+
 function trustUseReasons(workspace, skill) {
   const unit = skill.ownerInstallUnit === undefined
     ? undefined

package/src/control/config-write.mjs

@@ -1,4 +1,4 @@
-import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { open, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, join } from "node:path";
 import YAML from "yaml";
@@ -6,6 +6,7 @@ import { loadWorkspace } from "../workspace.mjs";
 import { checkPolicy } from "../policy.mjs";
 import { textChangePlan } from "../change-plan.mjs";
 import { canUseSkill } from "./can-use-guard.mjs";
+import { assertV2MutationVersion } from "../compatibility.mjs";
 
 export async function loadConfig(path) {
   const text = await readFile(path, "utf8");
@@ -21,10 +22,12 @@ export async function loadConfig(path) {
 }
 
 export async function writeCheckedConfig(document, originalText, options, message) {
+  assertV2MutationVersion(document.get("version") ?? 1);
   const nextText = preserveLineEndings(String(document), originalText);
   const plan = textChangePlan(originalText, nextText);
   const tempPath = tempConfigPath(options.configPath);
-  await writeFile(tempPath, nextText, { encoding: "utf8", flag: "wx" });
+  const originalMode = (await stat(options.configPath)).mode & 0o777;
+  await writeFile(tempPath, nextText, { encoding: "utf8", flag: "wx", mode: originalMode });
   try {
     const workspace = await loadWorkspace({ configPath: tempPath, skillsRoot: options.skillsRoot });
     const policy = checkPolicy(workspace);
@@ -50,6 +53,33 @@ export async function writeCheckedConfig(document, originalText, options, messag
   }
 }
 
+export async function withPolicyMutationLock(configPath, operation) {
+  const canonicalPath = await realpath(configPath);
+  const lockPath = `${canonicalPath}.migrate.lock`;
+  const deadline = Date.now() + 5_000;
+  let handle;
+  while (handle === undefined) {
+    try {
+      handle = await open(lockPath, "wx", 0o600);
+    } catch (error) {
+      if (error?.code !== "EEXIST" || Date.now() >= deadline) {
+        throw error?.code === "EEXIST"
+          ? new Error("Another policy update is already using this config.")
+          : error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    await handle.sync();
+    return await operation(canonicalPath);
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
 function tempConfigPath(configPath) {
   return join(dirname(configPath), `.${basename(configPath)}.${randomUUID()}.tmp`);
 }

package/src/control/skill-crud.mjs

@@ -26,12 +26,14 @@ import {
   writeCheckedConfig
 } from "./config-write.mjs";
 import { canUseSkill } from "./can-use-guard.mjs";
+import { assertV2MutationVersion } from "../compatibility.mjs";
 
 const WRITABLE_INVOCATIONS = new Set(["manual-only", "router-only", "workflow-auto", "global-auto"]);
 const NON_ACTIVATABLE_STATUSES = new Set(["blocked", "deprecated", "archived", "removed"]);
 
 export async function activateSkill(options) {
   const { document, originalText } = await loadConfig(options.configPath);
+  assertV2MutationVersion(document.get("version") ?? 1);
   const skill = requireConfigSkill(document, options.skillId);
   const workflow = requireConfigWorkflow(document, options.workflow);
   const mode = options.mode ?? readMapString(skill, "invocation", "manual-only");
@@ -55,6 +57,7 @@ export async function activateSkill(options) {
 
 export async function addSkill(options) {
   const { document, originalText } = await loadConfig(options.configPath);
+  assertV2MutationVersion(document.get("version") ?? 1);
   const skills = ensureMapAt(document, ["skills"], "skills");
   if (skills.get(options.skillId, true) !== undefined) {
     throw new Error(`Skill already exists: ${options.skillId}`);
@@ -147,6 +150,7 @@ export async function addSkillVariant(options) {
 
 export async function blockSkill(options) {
   const { document, originalText } = await loadConfig(options.configPath);
+  assertV2MutationVersion(document.get("version") ?? 1);
   requireConfigSkill(document, options.skillId);
   const workflow = requireConfigWorkflow(document, options.workflow);
 
@@ -188,6 +192,7 @@ export async function removeSkill(options) {
 
 export async function preferSkill(options) {
   const { document, originalText } = await loadConfig(options.configPath);
+  assertV2MutationVersion(document.get("version") ?? 1);
   const skill = requireConfigSkill(document, options.skillId);
   const workflow = requireConfigWorkflow(document, options.workflow);
   const capabilities = requireMapAt(document, ["capabilities"], "capabilities");

package/src/control/v2-guard.mjs

@@ -0,0 +1,175 @@
+import { readFile } from "node:fs/promises";
+import { supportedAgentNames } from "../agent-skill-roots.mjs";
+
+export async function loadV2InventoryIndex(path) {
+  const text = await readFile(path, "utf8").catch((error) => {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  });
+  if (text === null) {
+    return { path, integrityErrors: [`generated inventory is missing: ${path}`], skillIds: [], skills: [], installUnits: [] };
+  }
+  try {
+    const value = JSON.parse(text);
+    const errors = validateInventory(value);
+    const skillIds = errors.length === 0
+      ? value.skills.map((skill) => skill.id).sort((left, right) => left.localeCompare(right))
+      : [];
+    const installUnits = errors.length === 0
+      ? (value.install_units ?? []).map(projectInstallUnitObservation)
+      : [];
+    return { path, integrityErrors: errors, skillIds, skills: errors.length === 0 ? value.skills : [], installUnits };
+  } catch (error) {
+    return { path, integrityErrors: [`generated inventory is invalid JSON: ${errorMessage(error)}`], skillIds: [], skills: [], installUnits: [] };
+  }
+}
+
+export function authorizeV2Skill(skillId, policy, inventory, agentName) {
+  if (typeof agentName !== "string" || agentName.length === 0) {
+    return {
+      allowed: false,
+      integrityError: false,
+      reasons: ["Current agent is required for version 2 availability checks."]
+    };
+  }
+  if (!supportedAgentNames().includes(agentName)) {
+    return {
+      allowed: false,
+      integrityError: false,
+      reasons: [`Unsupported agent: ${agentName}.`]
+    };
+  }
+  const integrityReasons = inventoryIntegrityReasons(inventory, skillId);
+  if (integrityReasons.length > 0) {
+    return { allowed: false, integrityError: true, reasons: integrityReasons };
+  }
+  if (policy === undefined) {
+    return { allowed: false, integrityError: false, reasons: ["Skill has no version 2 policy entry."] };
+  }
+  if (!policy.enabled) {
+    return { allowed: false, integrityError: false, reasons: [`Skill ${policy.id} is disabled.`] };
+  }
+  const observation = inventory.skills?.find((skill) => skill.id === skillId);
+  const installedOn = Array.isArray(observation?.installed_on) ? observation.installed_on : [];
+  if (!installedOn.includes(agentName)) {
+    return {
+      allowed: false,
+      integrityError: false,
+      reasons: [`Skill ${policy.id} is not installed for agent ${agentName}.`]
+    };
+  }
+  return { allowed: true, integrityError: false, reasons: [] };
+}
+
+function validateInventory(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return ["generated inventory root must be an object"];
+  }
+  const errors = [];
+  if (value.format_version !== 1) errors.push("generated inventory format_version must be 1");
+  if (value.generated !== true) errors.push("generated inventory must declare generated: true");
+  if (value.authoritative_for_availability !== false) {
+    errors.push("generated inventory must declare authoritative_for_availability: false");
+  }
+  if (!Array.isArray(value.skills)) {
+    errors.push("generated inventory skills must be an array");
+    return errors;
+  }
+  const ids = new Set();
+  for (const [index, skill] of value.skills.entries()) {
+    if (skill === null || typeof skill !== "object" || Array.isArray(skill)) {
+      errors.push(`generated inventory skill ${index} must be an object`);
+      continue;
+    }
+    for (const field of ["id", "path", "owner_install_unit"]) {
+      if (typeof skill[field] !== "string" || skill[field].trim() === "") {
+        errors.push(`generated inventory skill ${index}.${field} must be a non-empty string`);
+      }
+    }
+    if (skill.installed_on !== undefined && (!Array.isArray(skill.installed_on)
+      || skill.installed_on.some((agent) => typeof agent !== "string" || agent.trim() === ""))) {
+      errors.push(`generated inventory skill ${index}.installed_on must be a list of agent names`);
+    }
+    if (typeof skill.id === "string") {
+      if (ids.has(skill.id)) errors.push(`generated inventory contains duplicate skill id: ${skill.id}`);
+      ids.add(skill.id);
+    }
+  }
+  if (value.install_units !== undefined && !Array.isArray(value.install_units)) {
+    errors.push("generated inventory install_units must be an array");
+    return errors;
+  }
+  const unitIds = new Set();
+  for (const [index, unit] of (value.install_units ?? []).entries()) {
+    if (unit === null || typeof unit !== "object" || Array.isArray(unit)) {
+      errors.push(`generated inventory install unit ${index} must be an object`);
+      continue;
+    }
+    if (typeof unit.id !== "string" || unit.id.trim() === "") {
+      errors.push(`generated inventory install unit ${index}.id must be a non-empty string`);
+    } else if (unitIds.has(unit.id)) {
+      errors.push(`generated inventory contains duplicate install unit id: ${unit.id}`);
+    } else {
+      unitIds.add(unit.id);
+    }
+  }
+  return errors;
+}
+
+function projectInstallUnitObservation(unit) {
+  const runtime = unit.runtime_components ?? {};
+  return {
+    id: unit.id,
+    kind: unit.kind ?? "skill",
+    sourceClass: unit.source_class,
+    priority: undefined,
+    trustLevel: unit.trust_observation ?? "unreviewed",
+    sourceDigest: unit.source_digest,
+    signature: unit.signature_observed === true ? "observed" : undefined,
+    publicKey: undefined,
+    verifiedAt: unit.verified_at,
+    source: unit.source ?? "",
+    scope: "inventory-observation",
+    manifestPath: unit.manifest_path ?? "",
+    cachePath: unit.cache_path ?? "",
+    providedComponents: [],
+    components: {
+      skills: stringList(unit.skills),
+      commands: stringList(runtime.commands),
+      hooks: stringList(runtime.hooks),
+      mcpServers: stringList(runtime.mcp_servers)
+    },
+    modifiedConfigFiles: [],
+    autoUpdate: false,
+    enabled: true,
+    workflowDependencies: [],
+    permissionRisk: unit.permission_risk ?? "unknown",
+    rollback: "observation-only"
+  };
+}
+
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function inventoryIntegrityReasons(inventory, skillId) {
+  if (inventory === null || typeof inventory !== "object") {
+    return ["Inventory integrity error: generated inventory is unavailable."];
+  }
+  if (Array.isArray(inventory.integrityErrors) && inventory.integrityErrors.length > 0) {
+    return inventory.integrityErrors.map((reason) => `Inventory integrity error: ${reason}`);
+  }
+  const ids = inventory.skillIds instanceof Set
+    ? inventory.skillIds
+    : new Set(Array.isArray(inventory.skillIds) ? inventory.skillIds : []);
+  if (!ids.has(skillId)) {
+    return [`Inventory integrity error: skill ${skillId ?? "<unknown>"} is missing from generated inventory.`];
+  }
+  return [];
+}

package/src/control/v2-skill-crud.mjs

@@ -0,0 +1,32 @@
+import { ensureMapAt, loadConfig, requireYamlMap, withPolicyMutationLock, writeCheckedConfig } from "./config-write.mjs";
+
+export async function setV2SkillEnabled(options) {
+  return mutate(options, (skill) => skill.set("enabled", options.enabled), `${options.enabled ? "Enabled" : "Disabled"} ${options.skillId}`);
+}
+
+export async function setV2SkillShared(options) {
+  return mutate(options, (skill) => skill.set("shared", options.shared), `${options.shared ? "Shared" : "Unshared"} ${options.skillId}`);
+}
+
+export async function setV2SkillPreference(options) {
+  const intents = names(options.intents, "--intent");
+  if (!Number.isInteger(options.priority)) throw new Error("--priority must be an integer");
+  return mutate(options, (skill, document) => skill.set("preference", document.createNode({ intents, priority: options.priority })), `Updated preference for ${options.skillId}`);
+}
+
+async function mutate(options, update, message) {
+  return await withPolicyMutationLock(options.configPath, async (configPath) => {
+    const { document, originalText } = await loadConfig(configPath);
+    const skills = ensureMapAt(document, ["skills"], "skills");
+    const raw = skills.get(options.skillId, true);
+    if (raw === undefined) throw new Error(`Unknown skill: ${options.skillId}`);
+    update(requireYamlMap(raw, `skills.${options.skillId}`), document);
+    return await writeCheckedConfig(document, originalText, { ...options, configPath }, message);
+  });
+}
+
+function names(values, option) {
+  const result = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))].sort();
+  if (result.length === 0) throw new Error(`${option} requires at least one value`);
+  return result;
+}

package/src/control/v2-skill-forget.mjs

@@ -0,0 +1,38 @@
+import { loadWorkspace } from "../workspace.mjs";
+import {
+  loadConfig,
+  requireYamlMap,
+  withPolicyMutationLock,
+  writeCheckedConfig
+} from "./config-write.mjs";
+
+export async function forgetV2Skill(options) {
+  return await withPolicyMutationLock(options.configPath, async (configPath) => {
+    const workspace = await loadWorkspace({
+      configPath,
+      inventoryPath: options.inventoryPath,
+      skillsRoot: options.skillsRoot
+    });
+    const policy = workspace.skills.find((skill) => skill.id === options.skillId);
+    if (policy === undefined) throw new Error(`Unknown skill: ${options.skillId}`);
+    if (workspace.inventory.integrityErrors.length > 0) {
+      throw new Error(`Cannot forget a skill while generated inventory is unhealthy: ${workspace.inventory.integrityErrors.join("; ")}`);
+    }
+    if (policy.shared) {
+      throw new Error(`Skill ${options.skillId} is shared. Run skillboard skill unshare ${options.skillId} before forgetting it.`);
+    }
+    if (workspace.inventory.skills.some((skill) => skill.id === options.skillId)) {
+      throw new Error(`Skill ${options.skillId} is still installed. Remove it from its owning agent before forgetting its policy.`);
+    }
+
+    const { document, originalText } = await loadConfig(configPath);
+    const skills = requireYamlMap(document.get("skills", true), "skills");
+    skills.delete(options.skillId);
+    return await writeCheckedConfig(
+      document,
+      originalText,
+      { ...options, configPath },
+      `Forgot ${options.skillId}`
+    );
+  });
+}

package/src/control/variant-status.mjs

@@ -7,7 +7,10 @@ import {
 
 export async function variantLifecycleStatus(options) {
   const workspace = await loadWorkspace({ configPath: options.configPath, skillsRoot: options.skillsRoot });
-  const skill = workspace.skills.find((candidate) => candidate.id === options.variantId);
+  const policySkill = workspace.skills.find((candidate) => candidate.id === options.variantId);
+  const skill = workspace.version === 2
+    ? historicalVariantSkill(workspace, policySkill)
+    : policySkill;
   if (skill === undefined) {
     throw new Error(`Unknown skill: ${options.variantId}`);
   }
@@ -39,6 +42,49 @@ export async function variantLifecycleStatus(options) {
   };
 }
 
+function historicalVariantSkill(workspace, policySkill) {
+  if (policySkill === undefined) return undefined;
+  const observed = workspace.inventory?.skills?.find((candidate) => candidate.id === policySkill.id);
+  const rawVariant = observed?.observations?.variant;
+  if (observed === undefined || rawVariant === undefined) return policySkill;
+  return {
+    ...policySkill,
+    path: observed.path,
+    variant: parseHistoricalVariant(rawVariant, policySkill.id)
+  };
+}
+
+function parseHistoricalVariant(raw, skillId) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Inventory variant observation for ${skillId} must be an object`);
+  }
+  const approved = raw.approved === undefined ? undefined : historicalCheckpoint(raw.approved, `${skillId}.approved`);
+  return {
+    of: requiredString(raw.of, `${skillId}.variant.of`),
+    adaptedFor: typeof raw.adapted_for === "string" ? raw.adapted_for : null,
+    capability: requiredString(raw.capability, `${skillId}.variant.capability`),
+    workflow: requiredString(raw.workflow, `${skillId}.variant.workflow`),
+    status: requiredString(raw.status, `${skillId}.variant.status`),
+    base: historicalCheckpoint(raw.base, `${skillId}.variant.base`),
+    ...(approved === undefined ? {} : { approved })
+  };
+}
+
+function historicalCheckpoint(raw, label) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Inventory variant checkpoint ${label} must be an object`);
+  }
+  return {
+    contentDigest: requiredString(raw.content_digest, `${label}.content_digest`),
+    snapshot: requiredString(raw.snapshot, `${label}.snapshot`)
+  };
+}
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
+  return value;
+}
+
 function computeStatus(lifecycleStatus, liveDigest, baseDigest, approvedDigest) {
   if (liveDigest === null) {
     return "missing-live-file";

package/src/control.mjs

@@ -29,14 +29,22 @@ import { variantLifecycleStatus } from "./control/variant-status.mjs";
 import { addHarness, addWorkflow } from "./control/workflow-crud.mjs";
 import {
   GUARD_HOOK_MODE,
+  assertHookTargetContained,
   assertGuardHookPlanIsInstallable,
   buildGuardHookInstallPlan,
   planGuardHookInstall
 } from "./hook-plan.mjs";
 
 export { planGuardHookInstall } from "./hook-plan.mjs";
+export { setV2SkillEnabled, setV2SkillPreference, setV2SkillShared } from "./control/v2-skill-crud.mjs";
+export { forgetV2Skill } from "./control/v2-skill-forget.mjs";
 
 export function listSkills(workspace, options = {}) {
+  if (workspace.version === 2) {
+    return workspace.skills
+      .map((skill) => v2SkillSummary(workspace, skill))
+      .sort((left, right) => left.id.localeCompare(right.id));
+  }
   const workflow = options.workflow === undefined ? undefined : workflowByName(workspace, options.workflow);
   const skillIds = workflow === undefined
     ? new Set(workspace.skills.map((skill) => skill.id))
@@ -57,6 +65,9 @@ export function listSkills(workspace, options = {}) {
 }
 
 export function listWorkflows(workspace) {
+  if (workspace.version === 2) {
+    return [];
+  }
   return workspace.workflows.map((workflow) => ({
     name: workflow.name,
     harness: workflow.harness,
@@ -96,6 +107,12 @@ export function listInstallUnits(workspace) {
 
 export function explainSkill(workspace, skillId) {
   const skill = skillById(workspace, skillId);
+  if (workspace.version === 2) {
+    return {
+      ...v2SkillSummary(workspace, skill),
+      agents: v2InventoryObservation(workspace, skill.id).installed_on
+    };
+  }
   const source = classifySkillSource(workspace, skill);
   const workflows = workspace.workflows
     .map((workflow) => workflowSkillRole(workspace, workflow, skillId))
@@ -119,6 +136,43 @@ export function explainSkill(workspace, skillId) {
   };
 }
 
+function v2SkillSummary(workspace, skill) {
+  const inventory = v2InventoryObservation(workspace, skill.id);
+  return {
+    id: skill.id,
+    enabled: skill.enabled,
+    shared: skill.shared,
+    preference: skill.preference,
+    path: inventory.path,
+    inventory,
+    variant: inventory.observations.variant ?? null
+  };
+}
+
+function v2InventoryObservation(workspace, skillId) {
+  const observed = workspace.inventory?.skills?.find((candidate) => candidate.id === skillId);
+  if (observed === undefined) {
+    return {
+      present: false, path: null, owner_install_unit: null, source: null,
+      category: null, description: null, content_digest: null, installed_on: [], aliases: [], observations: {}
+    };
+  }
+  return {
+    present: true,
+    path: observed.path,
+    owner_install_unit: observed.owner_install_unit,
+    source: observed.source ?? null,
+    category: observed.category ?? null,
+    description: observed.description ?? null,
+    content_digest: observed.content_digest ?? null,
+    installed_on: Array.isArray(observed.installed_on) ? observed.installed_on : [],
+    aliases: Array.isArray(observed.aliases) ? observed.aliases : [],
+    observations: observed.observations !== null && typeof observed.observations === "object" && !Array.isArray(observed.observations)
+      ? observed.observations
+      : {}
+  };
+}
+
 export {
   activateSkill,
   addHarness,
@@ -143,6 +197,7 @@ export async function installGuardHook(options) {
   const { plan, script } = await buildGuardHookInstallPlan(options);
   assertGuardHookPlanIsInstallable(plan);
 
+  await assertHookTargetContained(options.configPath, plan.path);
   await mkdir(dirname(plan.path), { recursive: true });
   await assertNewNonSymlinkPath(plan.path);
   await writeFile(plan.path, script, { encoding: "utf8", flag: "wx", mode: GUARD_HOOK_MODE });