@halofy/agent-connect 0.12.1 → 0.13.0

package/src/instructions.mjs

@@ -136,7 +136,11 @@ async function targetFor(connection, owner) {
 function render(bundle, owner, cursor) {
   const begin = `${MARKER}${owner}:BEGIN -->`;
   const end = `${MARKER}${owner}:END -->`;
-  const content = bundle.documents.map((doc) => `## ${doc.title}\n\n${doc.content}`).join("\n\n");
+  const content = bundle.documents.map((doc) => {
+    // Preserve the authored bytes; omit only our redundant display heading.
+    const heading = doc.content.trimStart().split(/\r?\n/, 1)[0].match(/^#{1,6}\s+(.+?)(?:\s+#+)?\s*$/);
+    return heading?.[1] === doc.title ? doc.content : `## ${doc.title}\n\n${doc.content}`;
+  }).join("\n\n");
   const text = `${cursor ? "---\nalwaysApply: true\n---\n" : ""}${begin}\n# Organization agent instructions\n\n${content}\n${end}\n`;
   return { begin: Buffer.from(begin), end: Buffer.from(end), bytes: Buffer.from(text) };
 }

package/src/skill-guard.mjs

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { safeDirectory, writePrivateFile } from "./storage.mjs";
+import { readPrivateJson, withContextLock } from "./context-sync.mjs";
+import { loadSkillsManifest, managedSkillsDirectory, readManagedSkillTuples } from "./skills-sync.mjs";
+import { SignedRuntimeTransport } from "./transport.mjs";
+
+const PREFIX = "halofy-managed-";
+const ID = /^[A-Za-z0-9_-]{1,160}$/;
+const KEY = /^[a-z0-9][a-z0-9._-]{0,199}$/i;
+const SHA = /^[a-f0-9]{64}$/;
+const hash = value => createHash("sha256").update(value).digest("hex");
+const enabled = connection => connection.clientKind === "claude-code" && connection.skillGuardVersion === 1;
+const stateRoot = root => join(root, "claude-skill-guard");
+const validEntry = entry => entry && ID.test(entry.installationId) && ID.test(entry.skillId)
+  && KEY.test(entry.skillKey) && !entry.skillKey.includes("..") && SHA.test(entry.sha)
+  && entry.nativeSkillKey === guardedSkillName({ installationId: entry.installationId }, entry);
+
+/** Native identity is immutable across updates, restores and reconnects. */
+export function guardedSkillName(connection, skill) {
+  return `${PREFIX}${hash(JSON.stringify([connection.installationId, skill.skillId, skill.sha])).slice(0, 40)}`;
+}
+export function managedNativeSkillKey(connection, skill) {
+  return enabled(connection) ? guardedSkillName(connection, skill) : skill.skillKey;
+}
+
+async function readHistory(root) {
+  const dir = stateRoot(root);
+  await safeDirectory(dir);
+  for (const name of ["initialized.json", "history.json"]) {
+    const entry = await lstat(join(dir, name));
+    if (!entry.isFile() || entry.isSymbolicLink() || entry.size > 4 * 1024 * 1024) throw new Error("invalid skill guard evidence");
+  }
+  const anchor = await readPrivateJson(join(dir, "initialized.json"));
+  const history = await readPrivateJson(join(dir, "history.json"));
+  if (anchor?.version !== 1 || history?.version !== 1 || !Array.isArray(history.entries)
+    || !Array.isArray(history.legacyKeys) || history.entries.length > 10000 || history.legacyKeys.length > 10000
+    || history.entries.some(entry => !validEntry(entry))
+    || history.legacyKeys.some(key => typeof key !== "string" || !KEY.test(key) || key.includes(".."))
+    || new Set(history.entries.map(entry => entry.nativeSkillKey)).size !== history.entries.length) {
+    throw new Error("invalid skill guard evidence");
+  }
+  return history;
+}
+
+/** Explicit installer bootstrap only. Hook/sync reads never reset missing history. */
+export async function initializeSkillGuard(root) {
+  const dir = stateRoot(root);
+  await safeDirectory(dir, true);
+  return withContextLock(dir, async () => {
+    const names = await readdir(dir);
+    if (names.includes("initialized.json") || names.includes("history.json")) return readHistory(root);
+    const connections = await readdir(join(root, "connections")).catch(error => {
+      if (error.code === "ENOENT") return []; throw error;
+    });
+    if (connections.length > 1000) throw new Error("skill guard connection limit");
+    const legacyKeys = new Set();
+    for (const name of connections) {
+      if (!/^[A-Za-z0-9_-]{1,160}\.json$/.test(name)) continue;
+      const connection = await readPrivateJson(join(root, "connections", name));
+      if (connection?.clientKind !== "claude-code") continue;
+      if (connection.skillGuardVersion === 1) throw new Error("missing initialized skill history");
+      const manifest = await loadSkillsManifest(root, connection.installationId);
+      for (const entry of manifest.installs) legacyKeys.add(entry.skillKey);
+      // Pre-guard runtimes removed manifest entries after withdrawal, but kept
+      // owned directories in quarantine. Preserve those legacy cache identities.
+      const quarantine = join(root, "skills-quarantine", connection.installationId);
+      let withdrawn = [];
+      try { await safeDirectory(quarantine); withdrawn = await readdir(quarantine); }
+      catch (error) { if (error.code !== "ENOENT" && error.code !== "directory_missing") throw error; }
+      if (withdrawn.length > 10000) throw new Error("legacy skill history limit");
+      for (const name of withdrawn) {
+        const match = /^(.+)-[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{3}Z$/.exec(name);
+        if (!match || !KEY.test(match[1]) || match[1].includes("..")) throw new Error("unrecognized legacy quarantine");
+        await safeDirectory(join(quarantine, name));
+        legacyKeys.add(match[1]);
+      }
+    }
+    if (legacyKeys.size > 10000) throw new Error("legacy skill history limit");
+    const history = { version: 1, entries: [], legacyKeys: [...legacyKeys] };
+    await writePrivateFile(join(dir, "history.json"), JSON.stringify(history));
+    await writePrivateFile(join(dir, "initialized.json"), JSON.stringify({ version: 1 }));
+    return history;
+  });
+}
+
+/** Record ownership before activation/withdrawal; records are never removed. */
+export async function recordSkillOwnership(connection, root, entries) {
+  if (!enabled(connection)) return;
+  const dir = stateRoot(root);
+  await safeDirectory(dir);
+  await withContextLock(dir, async () => {
+    const history = await readHistory(root);
+    for (const entry of entries) {
+      if (!entry.nativeSkillKey) {
+        if (!history.legacyKeys.includes(entry.skillKey)) history.legacyKeys.push(entry.skillKey);
+      } else {
+        const record = { installationId: connection.installationId, skillId: entry.skillId,
+          skillKey: entry.skillKey, sha: entry.sha, nativeSkillKey: entry.nativeSkillKey };
+        if (!validEntry(record)) throw new Error("invalid owned skill");
+        if (!history.entries.some(item => item.nativeSkillKey === record.nativeSkillKey)) history.entries.push(record);
+      }
+    }
+    if (history.entries.length > 10000 || history.legacyKeys.length > 10000) throw new Error("skill guard history limit");
+    await writePrivateFile(join(dir, "history.json"), JSON.stringify(history));
+  });
+}
+
+export function skillInvocationDenial(reason = "This Halofy managed skill is withdrawn, changed, or could not be verified. Refresh Halofy and start a new conversation before using it.") {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny",
+    permissionDecisionReason: reason } };
+}
+
+/** No allow decision: host permissions retain their normal authority. */
+async function checkClaudeSkillInvocation({ connection, root, input, home, env, transport, signal }) {
+  if (typeof input?.tool_name === "string" && input.tool_name !== "Skill") return null;
+  try {
+    if (typeof input.tool_input?.skill !== "string") throw new Error("missing skill identity");
+    // Claude trims native names before resolving cached plain-name skills.
+    const name = input.tool_input.skill.trim().replace(/^\//, "").trim().toLowerCase();
+    let history;
+    try { history = await readHistory(root); }
+    catch { return skillInvocationDenial("Halofy skill ownership evidence is unavailable; managed and employee skills cannot be safely distinguished. Skill calls are paused. Ask your administrator to restore verified ownership history or review the reconnect migration; do not recreate an empty history."); }
+    if (history.legacyKeys.some(key => key.toLowerCase() === name)) return skillInvocationDenial();
+    const owned = history.entries.find(entry => entry.nativeSkillKey === name);
+    if (!owned && !name.startsWith(PREFIX)) return null;
+    if (!owned || !enabled(connection) || owned.installationId !== connection.installationId) throw new Error("unknown managed skill");
+    const active = async () => {
+      await safeDirectory(root);
+      const marker = await readPrivateJson(join(root, "active-claude-code.json"));
+      return marker?.installationId === connection.installationId && marker?.protocolVersion === "1";
+    };
+    if (!(await active())) throw new Error("inactive installation");
+    const manifest = await loadSkillsManifest(root, connection.installationId);
+    const local = manifest.installs.find(entry => entry.nativeSkillKey === name && entry.skillId === owned.skillId && entry.sha === owned.sha);
+    if (!local) throw new Error("withdrawn managed copy");
+    // Verify all recorded bytes, then verify the exact local alias again after the network read.
+    await readManagedSkillTuples({ connection, root, home, env });
+    const current = await (transport ?? new SignedRuntimeTransport(connection, { timeoutMs: 3000, signal }))
+      .skillsCheckin([{ skillId: owned.skillId, sha: owned.sha }]);
+    if (!Array.isArray(current?.items) || current.items.length !== 1
+      || current.items[0].skillId !== owned.skillId || current.items[0].status !== "approved"
+      || !Array.isArray(current.skills) || !current.skills.some(entry => entry.skillId === owned.skillId
+        && entry.skillKey === owned.skillKey && entry.sha === owned.sha)) throw new Error("skill no longer eligible");
+    const path = join(managedSkillsDirectory("claude-code", { home, env }), name, "SKILL.md");
+    const bytes = await readFile(path);
+    if (hash(bytes) !== local.fileSha256 || !(await active())) throw new Error("changed managed copy");
+    await readManagedSkillTuples({ connection, root, home, env });
+    const latest = await loadSkillsManifest(root, connection.installationId);
+    if (!latest.installs.some(entry => entry.nativeSkillKey === name && entry.skillId === owned.skillId && entry.sha === owned.sha)) throw new Error("withdrawn during check");
+    await readHistory(root);
+    return null;
+  } catch { return skillInvocationDenial(); }
+}
+
+/** Bound the entire guard, including local reads, below the native hook timeout.
+ * The CLI flushes and exits after this decision so stuck filesystem work cannot
+ * turn a host timeout into a fail-open native invocation. */
+export async function guardClaudeSkillInvocation(options) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    return await Promise.race([
+      checkClaudeSkillInvocation({ ...options, signal: controller.signal }),
+      new Promise(resolve => { timer = setTimeout(() => {
+        controller.abort(); resolve(skillInvocationDenial());
+      }, 4500); }),
+    ]);
+  } finally { clearTimeout(timer); controller.abort(); }
+}

package/src/skills-sync.mjs

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
+import { managedNativeSkillKey, recordSkillOwnership } from "./skill-guard.mjs";
 import { isActiveInstallation } from "./active.mjs";
 import { ensurePrivateDirectory, readJson, safeDirectory, writePrivateFile } from "./storage.mjs";
 
@@ -11,11 +12,12 @@ import { ensurePrivateDirectory, readJson, safeDirectory, writePrivateFile } fro
  * skill on its team + org chain; this module mirrors that set into the host's
  * own skills folder and keeps it there.
  *
- * Every managed copy is written as `<skillsRoot>/<skillKey>/SKILL.md`, the
+ * Every managed copy is written as `<skillsRoot>/<nativeSkillKey>/SKILL.md`, the
  * layout Claude Code and Codex both read. A manifest under the runtime home
  * records what was written (id, sha, file digest) so the next check-in can
  * report it, drift can be repaired, and a withdrawn skill can be quarantined
  * — moved, never deleted (D7 on the client mirror).
+ * Guarded Claude installs use immutable aliases; other hosts use skillKey.
  *
  * A folder this runtime did not create is never touched: an employee's own
  * skill with a colliding name is reported as a conflict and left alone.
@@ -111,15 +113,16 @@ export async function loadSkillsManifest(root, installationId) {
   if (!manifestFile) return { version: 1, installationId, installs: [], lastCheckinAt: null };
   if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.installs)) throw new Error("invalid skill manifest");
   if (manifest.installationId !== installationId || manifest.installs.some((entry) =>
-    !safeKey(entry?.skillKey) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha))) throw new Error("invalid skill manifest");
+    !safeKey(entry?.skillKey) || (entry.nativeSkillKey !== undefined && !safeKey(entry.nativeSkillKey)) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha))) throw new Error("invalid skill manifest");
   return manifest;
 }
 
 /**
  * One sync pass. Never throws for server or filesystem trouble on a single
  * skill; the summary names what happened so callers (installer, SessionStart
- * hooks) can report it. A failed check-in leaves installed copies usable
- * until the 7-day staleness allowance runs out, then quarantines them (D37).
+ * hooks) can report it. A failed check-in retains installed copies until the
+ * 7-day staleness allowance runs out, then quarantines them (D37). Retention
+ * is not invocation permission: guarded Claude calls require a fresh check.
  */
 export async function syncManagedSkills({
   connection,
@@ -150,6 +153,7 @@ export async function syncManagedSkills({
   const quarantineRoot = join(root, "skills-quarantine", connection.installationId);
   const manifest = await loadSkillsManifest(root, connection.installationId);
   const current = now();
+  await recordSkillOwnership(connection, root, manifest.installs);
 
   const active = () => isActiveInstallation(connection, root);
   if (!(await active())) {
@@ -176,7 +180,7 @@ export async function syncManagedSkills({
       const failedWithdrawals = [];
       for (const entry of manifest.installs) {
         try {
-          const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
+          const moved = await quarantine(skillsRoot, quarantineRoot, entry.nativeSkillKey || entry.skillKey, current);
           if (moved) summary.quarantined.push({ skillKey: entry.skillKey, reason: "stale_checkin", to: moved });
         } catch (fsError) {
           failedWithdrawals.push(entry);
@@ -202,10 +206,12 @@ export async function syncManagedSkills({
   for (const entry of manifest.installs) {
     const verdict = verdicts.get(entry.skillId);
     const status = verdict?.status;
-    const withdrawn = status === "revoked" || status === "unknown" || (!wanted.has(entry.skillId) && status !== "stale");
+    const desired = wanted.get(entry.skillId) ?? wanted.get(verdict?.currentSkillId);
+    const renamed = desired && (entry.nativeSkillKey || entry.skillKey) !== managedNativeSkillKey(connection, desired);
+    const withdrawn = renamed || status === "revoked" || status === "unknown" || (!wanted.has(entry.skillId) && status !== "stale");
     if (!withdrawn) { survivors.push(entry); continue; }
     try {
-      const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
+      const moved = await quarantine(skillsRoot, quarantineRoot, entry.nativeSkillKey || entry.skillKey, current);
       summary.quarantined.push({ skillKey: entry.skillKey, reason: status || "not_resolved", to: moved });
     } catch (error) {
       summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: error?.code || "fs_error" });
@@ -220,14 +226,15 @@ export async function syncManagedSkills({
   //    to the row that replaced it.
   for (const entry of manifest.installs) {
     const verdict = verdicts.get(entry.skillId);
-    if (verdict?.status === "stale" && verdict.currentSkillId && !wanted.has(entry.skillId)) {
+    if (connection.skillGuardVersion !== 1 && verdict?.status === "stale" && verdict.currentSkillId && !wanted.has(entry.skillId)) {
       entry.skillId = verdict.currentSkillId;
     }
   }
   const next = [...failedWithdrawals];
   for (const skill of wanted.values()) {
-    const entry = manifest.installs.find((candidate) => candidate.skillId === skill.skillId);
-    const dir = join(skillsRoot, skill.skillKey);
+    const entry = manifest.installs.find((candidate) => candidate.skillId === skill.skillId && (candidate.nativeSkillKey || candidate.skillKey) === managedNativeSkillKey(connection, skill));
+    const nativeSkillKey = managedNativeSkillKey(connection, skill);
+    const dir = join(skillsRoot, nativeSkillKey);
     const file = join(dir, "SKILL.md");
     if (!(await active())) {
       summary.errors.push({ stage: "download", code: "inactive_installation" });
@@ -246,17 +253,24 @@ export async function syncManagedSkills({
       next.push({ ...entry, lastCheckinAt: current.toISOString() });
       continue;
     }
-    if (!(await isManaged(skillsRoot, skill.skillKey, entry)) && (await pathState(dir))) {
+    if (!(await isManaged(skillsRoot, nativeSkillKey, entry)) && (await pathState(dir))) {
       summary.conflicts.push({ skillKey: skill.skillKey, reason: "unmanaged_folder" });
       continue;
     }
     try {
       const exported = await transport.skillDownload(skill.skillId);
-      const content = typeof exported?.content === "string" ? exported.content : null;
+      let content = typeof exported?.content === "string" ? exported.content : null;
       if (!content) throw Object.assign(new Error("skill export was empty"), { code: "empty_export" });
       if (!content.startsWith("---\n") || !content.split("\n---\n")[0].split("\n").includes(`content_sha256: ${skill.sha}`)) {
         throw Object.assign(new Error("skill digest mismatch"), { code: "skill_digest_mismatch" });
       }
+      if (connection.clientKind === "claude-code" && connection.skillGuardVersion === 1) {
+        const boundary = content.indexOf("\n---\n");
+        const frontmatter = content.slice(0, boundary);
+        if ((frontmatter.match(/^name:.*$/gm) || []).length !== 1) throw new Error("missing native skill name");
+        content = frontmatter.replace(/^name:.*$/m, `name: ${nativeSkillKey}`) + content.slice(boundary);
+        await recordSkillOwnership(connection, root, [{ ...skill, nativeSkillKey }]);
+      }
       if (!(await active())) throw Object.assign(new Error("inactive installation"), { code: "inactive_installation" });
       await safeDirectory(dir, true);
       if ((await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill file");
@@ -264,6 +278,7 @@ export async function syncManagedSkills({
       const record = {
         skillId: skill.skillId,
         skillKey: skill.skillKey,
+        ...(nativeSkillKey !== skill.skillKey ? { nativeSkillKey } : {}),
         sha: skill.sha,
         fileSha256: digest(content),
         namespace: skill.namespace,
@@ -325,8 +340,8 @@ export async function readManagedSkillTuples({ connection, root, home = homedir(
   if (manifest.installationId !== connection.installationId || !manifest.lastCheckinAt) throw new Error("incomplete skill evidence");
   for (const entry of manifest.installs) {
     if (!safeKey(entry.skillKey) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha)) throw new Error("invalid skill evidence");
-    const dir = join(skillsRoot, entry.skillKey), file = join(dir, "SKILL.md");
-    if ((await pathState(dir))?.isSymbolicLink() || (await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill evidence");
+    const dir = join(skillsRoot, entry.nativeSkillKey || entry.skillKey), file = join(dir, "SKILL.md");
+    if (!(await pathState(dir))?.isDirectory() || !(await pathState(file))?.isFile() || (await pathState(dir))?.isSymbolicLink() || (await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill evidence");
     const content = await readText(file);
     const separator = content?.indexOf("\n---\n\n");
     // The export wrapper adds exactly one blank line and one terminal newline.
@@ -343,14 +358,15 @@ export async function retireManagedSkills({ connection, root, home = homedir(),
   const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
   if (!skillsRoot) return;
   const manifest = await loadSkillsManifest(root, connection.installationId);
+  await recordSkillOwnership(connection, root, manifest.installs);
   if (!manifest.installs.length) return;
   await safeDirectory(skillsRoot);
   for (const entry of manifest.installs) {
-    const dir = join(skillsRoot, entry.skillKey);
+    const dir = join(skillsRoot, entry.nativeSkillKey || entry.skillKey);
     const disk = await pathState(dir);
     if (!disk) continue;
     if (disk.isSymbolicLink() || !disk.isDirectory()) throw new Error("unsafe predecessor skill");
-    await quarantine(skillsRoot, join(root, "skills-quarantine", connection.installationId), entry.skillKey, now());
+    await quarantine(skillsRoot, join(root, "skills-quarantine", connection.installationId), entry.nativeSkillKey || entry.skillKey, now());
   }
   manifest.installs = [];
   await writePrivateFile(skillsManifestPath(root, connection.installationId), `${JSON.stringify(manifest, null, 2)}\n`);

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.12.1";
-export const RUNTIME_VERSION = "0.12.1";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-10.1";
+export const INSTALLER_VERSION = "0.13.0";
+export const RUNTIME_VERSION = "0.13.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-17.1";