@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -1,4 +1,5 @@
 import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -8,6 +9,12 @@ import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { readFile as fsReadFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { GitService } from '../../workflow/git/git.service.js';
+
+const execFileAsync = promisify(execFile);
 
 const KB_DIR = 'knowledge-base';
 const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
@@ -46,7 +53,7 @@ describe('SkillService', () => {
   } as unknown as IAccessControl;
 
   const svc = (access: IAccessControl = allowAll) =>
-    new SkillService(workspaceService, access, KB_DIR);
+    new SkillService(workspaceService, access, KB_DIR, new NodeFs());
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
@@ -65,7 +72,9 @@ describe('SkillService', () => {
     );
     await writeFile(join(skills, 'Development', 'access.md'), '---\nwrite:\n  - Developer\n---\n');
   });
-  afterEach(() => rm(root, { recursive: true, force: true }));
+  // Retried: the version tests put a real git repository under `root`, and a
+  // git child may still hold a `.git` handle for a moment on Windows.
+  afterEach(() => rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }));
 
   test('lists shared skills under the Skills root alongside plugin skills', async () => {
     const shared = join(root, wsId, KB_DIR, 'Skills', 'Engineering', 'deploy');
@@ -258,4 +267,216 @@ describe('SkillService', () => {
     } as unknown as IAccessControl;
     expect(await svc(denyRfi).getSkill('user@x.eu', 'rfi')).toEqual({ ok: false, error: 'forbidden' });
   });
+
+  /**
+   * The listing and the loader must never disagree about the same skill at the
+   * same instant.
+   *
+   * The regression: `getSkill` gated on `canRead`, which reads a file's own
+   * frontmatter rules off disk per call, while `listSkills` gated on
+   * `canReadBatch`, which resolves them through a per-workspace memo with its
+   * own lifetime. So a freshly written SKILL.md could be loadable by name and
+   * absent from the listing — an author who writes a skill and then lists them
+   * not seeing their own work, and an agent discovering by listing unable to
+   * find a skill it could load. Both now resolve through the one batch gate.
+   */
+  describe('listSkills and getSkill never disagree', () => {
+    /** Records which gate each surface consulted, and answers only on the batch one. */
+    function splitBrain(batchVerdict: boolean) {
+      const consulted: string[] = [];
+      const access = {
+        canRead: async () => {
+          consulted.push('canRead');
+          return !batchVerdict; // the OPPOSITE answer, so any use of it shows up
+        },
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => {
+          consulted.push('canReadBatch');
+          return new Map(paths.map((p) => [p, batchVerdict]));
+        },
+      } as unknown as IAccessControl;
+      return { access, consulted };
+    }
+
+    test('a skill the batch gate allows is both listed and loadable', async () => {
+      const { access, consulted } = splitBrain(true);
+      const service = svc(access);
+      const listed = (await service.listSkills('user@x.eu')).map((s) => s.name);
+      const loaded = await service.getSkill('user@x.eu', 'rfi');
+
+      expect(listed).toContain('rfi');
+      expect(loaded.ok).toBe(true);
+      // The single-file gate — whose answer here is the opposite — was never
+      // asked. One resolver decides both.
+      expect(consulted).not.toContain('canRead');
+    });
+
+    test('a skill the batch gate denies is neither listed nor loadable', async () => {
+      const { access, consulted } = splitBrain(false);
+      const service = svc(access);
+      const listed = (await service.listSkills('user@x.eu')).map((s) => s.name);
+      const loaded = await service.getSkill('user@x.eu', 'rfi');
+
+      expect(listed).not.toContain('rfi');
+      expect(loaded).toEqual({ ok: false, error: 'forbidden' });
+      expect(consulted).not.toContain('canRead');
+    });
+
+    test('a bundled file is served on the same verdict as the listing', async () => {
+      const { access } = splitBrain(false);
+      // Not `not_found`: the skill exists and the caller may not read it.
+      expect(await svc(access).getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py')).toEqual({
+        ok: false,
+        error: 'forbidden',
+      });
+    });
+  });
+
+  test('the version is `metadata.version` first, then `version`, then `lifecycle.version`', async () => {
+    const skills = join(root, wsId, KB_DIR, 'Plugins');
+    const put = async (name: string, frontmatter: string) => {
+      await mkdir(join(skills, name), { recursive: true });
+      await writeFile(join(skills, name, 'SKILL.md'), `---\n${frontmatter}\n---\n\n# ${name}\n`);
+    };
+    await put('meta-wins', 'version: 0.9.0\nmetadata:\n  version: "2.0.0"');
+    await put('lifecycle-only', 'lifecycle:\n  version: 3.1');
+    await put('bare-metadata', 'metadata: notes');
+    const list = await svc().listSkills();
+    const version = (name: string) => list.find((s) => s.name === name)?.version;
+    expect(version('meta-wins')).toBe('2.0.0');
+    expect(version('rfi')).toBe('1.4.0'); // top-level `version`, no metadata
+    expect(version('lifecycle-only')).toBe('3.1');
+    expect(version('bare-metadata')).toBeUndefined();
+  });
+
+  /**
+   * `getSkill` with a `version` reads the skill out of the default branch's
+   * git history — a real repository here, driven through the real GitService,
+   * because the walk (newest first, first declaring commit wins, files from
+   * that commit's tree) is exactly what these assert.
+   */
+  describe('getSkill with a version', () => {
+    let repo: string;
+
+    const runGit = (args: string[]) =>
+      execFileAsync('git', args, {
+        cwd: repo,
+        env: {
+          ...process.env,
+          GIT_AUTHOR_NAME: 'Test',
+          GIT_AUTHOR_EMAIL: 't@x.com',
+          GIT_COMMITTER_NAME: 'Test',
+          GIT_COMMITTER_EMAIL: 't@x.com',
+        },
+      });
+    const commit = async (message: string) => {
+      await runGit(['add', '-A']);
+      await runGit(['commit', '-q', '-m', message]);
+    };
+    const skillMd = (version: string, body: string, description = 'RFI.') =>
+      `---\nname: rfi\ndescription: ${description}\nmetadata:\n  version: "${version}"\n---\n\n${body}\n`;
+
+    const versioned = (access: IAccessControl = allowAll) => {
+      const service = svc(access);
+      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), KB_DIR));
+      return service;
+    };
+
+    beforeEach(async () => {
+      repo = join(root, wsId, KB_DIR);
+      const rfi = join(repo, 'Plugins', 'rfi');
+      await runGit(['init', '-q', '-b', DEFAULT_BRANCH]);
+      await runGit(['config', 'core.autocrlf', 'false']);
+      // 1.0.0 — the body and one script; no build_xlsx.py yet.
+      await rm(join(rfi, 'scripts', 'build_xlsx.py'));
+      await writeFile(join(rfi, 'scripts', 'draft.py'), 'print("v1")\n');
+      // A non-ASCII name: git would C-quote it on a line-based listing.
+      await writeFile(join(rfi, 'scripts', 'übersicht.md'), 'v1\n');
+      await writeFile(join(rfi, 'SKILL.md'), skillMd('1.0.0', '# RFI v1', 'First cut.'));
+      await commit('rfi 1.0.0');
+      // 1.1.0 — the script changes, draft.py stays.
+      await writeFile(join(rfi, 'scripts', 'draft.py'), 'print("v1.1")\n');
+      await writeFile(join(rfi, 'SKILL.md'), skillMd('1.1.0', '# RFI v1.1'));
+      await commit('rfi 1.1.0');
+      // An edit that keeps 1.1.0: the version's latest copy is this one.
+      await writeFile(join(rfi, 'SKILL.md'), skillMd('1.1.0', '# RFI v1.1 (typo fixed)'));
+      await commit('rfi 1.1.0 typo');
+      // 1.4.0 — what is on disk now: the fixture body, build_xlsx.py, draft.py gone.
+      await rm(join(rfi, 'scripts', 'draft.py'));
+      await rm(join(rfi, 'scripts', 'übersicht.md'));
+      await writeFile(join(rfi, 'scripts', 'build_xlsx.py'), 'print("xlsx")\n');
+      await writeFile(join(rfi, 'SKILL.md'), RFI_SKILL);
+      await commit('rfi 1.4.0');
+    });
+
+    test('serves the body, description and bundled files as they were at that version', async () => {
+      const res = await versioned().getSkill('user@x.eu', 'rfi', undefined, { version: '1.0.0' });
+      expect(res.ok && res.kind === 'skill').toBe(true);
+      if (!res.ok || res.kind !== 'skill') return;
+      expect(res.skill.version).toBe('1.0.0');
+      expect(res.skill.description).toBe('First cut.');
+      expect(res.skill.body).toBe('# RFI v1\n');
+      expect(res.skill.files).toEqual(['Plugins/rfi/scripts/draft.py', 'Plugins/rfi/scripts/übersicht.md']);
+      expect(res.skill.path).toBe('Plugins/rfi');
+      const file = await versioned().getSkill('user@x.eu', 'rfi', 'scripts/übersicht.md', { version: '1.0.0' });
+      expect(file.ok && file.kind === 'file' && file.file.content).toBe('v1\n');
+    });
+
+    test('a version declared by several commits answers with its most recent copy', async () => {
+      const res = await versioned().getSkill('user@x.eu', 'rfi', undefined, { version: '1.1.0' });
+      expect(res.ok && res.kind === 'skill' && res.skill.body).toBe('# RFI v1.1 (typo fixed)\n');
+    });
+
+    test('the current version, or no version, is served from disk', async () => {
+      const now = await svc().getSkill('user@x.eu', 'rfi');
+      // No history attached: were 1.4.0 looked up in git, this could not answer.
+      expect(await svc().getSkill('user@x.eu', 'rfi', undefined, { version: '1.4.0' })).toEqual(now);
+      expect(await svc().getSkill('user@x.eu', 'rfi', undefined, { version: '  ' })).toEqual(now);
+    });
+
+    test('a bundled file is read at that version, and one not there then is not found', async () => {
+      const service = versioned();
+      const file = await service.getSkill('user@x.eu', 'rfi', 'scripts/draft.py', { version: '1.0.0' });
+      expect(file).toEqual({
+        ok: true,
+        kind: 'file',
+        file: { name: 'rfi', file: 'scripts/draft.py', path: 'Plugins/rfi/scripts/draft.py', content: 'print("v1")\n' },
+      });
+      expect(await service.getSkill('user@x.eu', 'rfi', 'scripts/build_xlsx.py', { version: '1.0.0' })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      expect(await service.getSkill('user@x.eu', 'rfi', '../etc/passwd', { version: '1.0.0' })).toEqual({
+        ok: false,
+        error: 'invalid_file',
+      });
+    });
+
+    test('a version never declared lists the ones that were, newest first', async () => {
+      expect(await versioned().getSkill('user@x.eu', 'rfi', undefined, { version: '9.9.9' })).toEqual({
+        ok: false,
+        error: 'version_not_found',
+        versions: ['1.4.0', '1.1.0', '1.0.0'],
+      });
+    });
+
+    test('without a history source a version cannot be answered and lists nothing', async () => {
+      expect(await svc().getSkill('user@x.eu', 'rfi', undefined, { version: '1.0.0' })).toEqual({
+        ok: false,
+        error: 'version_not_found',
+        versions: [],
+      });
+    });
+
+    test('history is gated on the caller reading the skill now', async () => {
+      const denyRfi: IAccessControl = {
+        canRead: async () => true,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) =>
+          new Map(paths.map((p) => [p, !p.includes('/rfi/')])),
+      } as unknown as IAccessControl;
+      expect(await versioned(denyRfi).getSkill('user@x.eu', 'rfi', undefined, { version: '1.0.0' })).toEqual({
+        ok: false,
+        error: 'forbidden',
+      });
+    });
+  });
 });

package/src/modules/skills/allowed-tools-check.ts

@@ -0,0 +1,352 @@
+import { PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import type { IToolRegistry } from '../tool-registry/tool.contract.js';
+import {
+  EXTERNAL_KB_MANUAL_NAME,
+  MAX_CAPABILITIES,
+  type IToolManualService,
+} from '../tool-manuals/tool-manuals.contract.js';
+import { parseSkillFrontmatter } from './skills.service.js';
+
+const log = logger('skills');
+
+/**
+ * Checks a skill's `allowed-tools` against the tools the platform actually
+ * serves, and says so when an entry names one that does not exist.
+ *
+ * A WARNING, never a refusal. The list is shared with the client: a skill
+ * names the agent's own tools there too (`Bash`, `Read`, `Bash(git:*)`), and
+ * the platform cannot know those. So an entry is only checked when it LOOKS
+ * like a platform tool:
+ *
+ *  - a manual-qualified name, `hubspot.search` (the UTCP namespace);
+ *  - an MCP-style name for this server, `mcp__hexis__<tool>` — `<tool>` being
+ *    a core tool (`read_file`) or a manual's tool as the proxy names it
+ *    (`hubspot_search`);
+ *  - a bare lowercase name: a manual (`hubspot`), a core tool, or `<manual>_<tool>`.
+ *
+ * Everything else is the client's: names starting with a capital (Claude
+ * Code's `Bash`, `WebFetch`, …), permission-rule syntax (`Bash(git:*)`),
+ * wildcards, another MCP server's `mcp__<server>__…`, and the lowercase
+ * client tools listed in {@link CLIENT_TOOL_NAMES}.
+ */
+
+/** One entry the platform could not resolve. */
+export interface AllowedToolWarning {
+  /**
+   * The `allowed-tools` entry as written, with surrounding whitespace
+   * removed — the only normalization applied. A YAML list may quote an entry
+   * with padding (`- " hubspot.search "`); the padding is not part of the
+   * name, and echoing it back would name an entry the author cannot find.
+   */
+  entry: string;
+  /** A sentence naming the entry, and the suggestion when there is one. */
+  message: string;
+  /** The closest tool name the caller can see, in the entry's own spelling. */
+  suggestion?: string;
+}
+
+/**
+ * The tools a caller can see. `tools: null` for a manual whose tools are only
+ * discovered at call time (`http`/`mcp`) — any tool under it is accepted,
+ * because nothing here can prove it absent without a network round-trip.
+ */
+export interface VisibleTools {
+  core: string[];
+  manuals: { name: string; tools: string[] | null }[];
+}
+
+/** The MCP server prefix this platform's tools carry in a client's tool list. */
+export const MCP_PREFIX = 'mcp__hexis__';
+
+/**
+ * Lowercase tool names that belong to agent CLIENTS, not the platform —
+ * capitalised ones (every Claude Code tool) are exempt by shape already.
+ * Explicit rather than clever: a name added here is never flagged.
+ */
+export const CLIENT_TOOL_NAMES: ReadonlySet<string> = new Set([
+  // Codex / OpenAI agents
+  'shell',
+  'apply_patch',
+  'update_plan',
+  'view_image',
+  'web_search',
+  'local_shell',
+  // Gemini CLI
+  'run_shell_command',
+  'read_many_files',
+  'google_web_search',
+  'web_fetch',
+  'save_memory',
+  'glob',
+  'replace',
+]);
+
+/**
+ * Whether an entry has one of the shapes the platform checks — decided from
+ * the entry alone, before any catalog is read. A list of nothing but client
+ * tools (`Bash Read Edit`) therefore costs no catalog reads, which matters
+ * because `get_skill` runs on every skill use, and the catalog behind a check
+ * is a skill listing, a manual listing and one detail read per inline manual.
+ */
+export function looksLikePlatformTool(raw: string): boolean {
+  const entry = raw.trim();
+  if (!entry || /[()*\s]/.test(entry)) return false; // permission-rule syntax or a wildcard
+  const lower = entry.toLowerCase();
+  if (lower.startsWith('mcp__')) return lower.startsWith(MCP_PREFIX); // else another MCP server's tool
+  const dot = entry.indexOf('.');
+  if (dot > 0) return /^\w+$/.test(lower.slice(0, dot)); // else not a manual name — a file, a URL, …
+  // Bare names: a capital first letter is a client tool's shape.
+  return /^[a-z][\w-]*$/.test(entry) && !CLIENT_TOOL_NAMES.has(entry);
+}
+
+/** Classify and resolve every entry; only unresolved platform-looking ones come back. */
+export function checkAllowedTools(entries: readonly string[], visible: VisibleTools): AllowedToolWarning[] {
+  const core = new Set(visible.core.map((n) => n.toLowerCase()));
+  const manuals = new Map(
+    visible.manuals.map((m) => [m.name.toLowerCase(), m.tools?.map((t) => t.toLowerCase()) ?? null]),
+  );
+  const warnings: AllowedToolWarning[] = [];
+  const seen = new Set<string>();
+  for (const raw of entries) {
+    const entry = raw.trim();
+    if (!entry || seen.has(entry)) continue;
+    seen.add(entry);
+    const warning = checkEntry(entry, core, manuals, visible);
+    if (warning) warnings.push(warning);
+  }
+  return warnings;
+}
+
+function checkEntry(
+  entry: string,
+  core: Set<string>,
+  manuals: Map<string, string[] | null>,
+  visible: VisibleTools,
+): AllowedToolWarning | null {
+  if (!looksLikePlatformTool(entry)) return null;
+  const lower = entry.toLowerCase();
+
+  if (lower.startsWith(MCP_PREFIX)) {
+    const name = lower.slice(MCP_PREFIX.length);
+    if (core.has(name) || resolvesUnderscored(name, manuals)) return null;
+    return warn(
+      entry,
+      lower,
+      [...visible.core.map((c) => MCP_PREFIX + c), ...underscoredCandidates(visible).map((c) => MCP_PREFIX + c)],
+      MCP_PREFIX.length,
+    );
+  }
+
+  const dot = entry.indexOf('.');
+  if (dot > 0) {
+    const manual = lower.slice(0, dot);
+    const tool = lower.slice(dot + 1);
+    // The core toolset's own namespace, as `call_tool_chain` spells it.
+    if (manual === EXTERNAL_KB_MANUAL_NAME.toLowerCase()) {
+      if (core.has(tool)) return null;
+      return warn(entry, lower, visible.core.map((c) => `${EXTERNAL_KB_MANUAL_NAME}.${c}`), dot + 1);
+    }
+    const tools = manuals.get(manual);
+    if (tools === null) return null;
+    if (tools === undefined) {
+      // The manual itself is unknown, so the typo may be anywhere in the name.
+      return warn(
+        entry,
+        lower,
+        visible.manuals.flatMap((m) => (m.tools ? m.tools.map((t) => `${m.name}.${t}`) : [`${m.name}.${entry.slice(dot + 1)}`])),
+      );
+    }
+    if (tools.includes(tool)) return null;
+    // The manual is known: only its own tools are candidates, and only the
+    // tool part is scored.
+    const known = visible.manuals.find((m) => m.name.toLowerCase() === manual);
+    return warn(entry, lower, (known?.tools ?? []).map((t) => `${known!.name}.${t}`), dot + 1);
+  }
+
+  if (core.has(lower) || manuals.has(lower) || resolvesUnderscored(lower, manuals)) return null;
+  return warn(entry, lower, [...visible.core, ...visible.manuals.map((m) => m.name), ...underscoredCandidates(visible)]);
+}
+
+/** `<manual>_<tool>` — how the MCP proxy names a manual's tool. */
+function resolvesUnderscored(name: string, manuals: Map<string, string[] | null>): boolean {
+  for (const [manual, tools] of manuals) {
+    if (!name.startsWith(`${manual}_`)) continue;
+    const tool = name.slice(manual.length + 1);
+    // Manual names may hold underscores themselves, so keep looking on a miss.
+    if (tools === null || tools.includes(tool)) return true;
+  }
+  return false;
+}
+
+function underscoredCandidates(visible: VisibleTools): string[] {
+  return visible.manuals.flatMap((m) => (m.tools ?? []).map((t) => `${m.name}_${t}`));
+}
+
+/**
+ * @param shared How many leading characters the entry and every candidate
+ *   share (`mcp__hexis__`, `<manual>.`). They are left out of the typo
+ *   scoring: the budget is a third of the scored name, and a prefix pads it
+ *   with characters that can never be misspelt — scored whole,
+ *   `mcp__hexis__weather_forecast` was "corrected" to `mcp__hexis__write_files`.
+ *   The suggestion keeps the entry's own prefix in front of the candidate's tail.
+ */
+function warn(entry: string, normalized: string, candidates: string[], shared = 0): AllowedToolWarning {
+  const tail = closest(normalized.slice(shared), candidates.map((c) => c.slice(shared)));
+  const suggestion = tail === undefined ? undefined : entry.slice(0, shared) + tail;
+  return {
+    entry,
+    message: suggestion
+      ? `"${entry}" in allowed-tools is not a tool you can use here. Did you mean "${suggestion}"?`
+      : `"${entry}" in allowed-tools is not a tool you can use here.`,
+    ...(suggestion ? { suggestion } : {}),
+  };
+}
+
+/** The nearest candidate by edit distance, when it is near enough to be a typo. */
+export function closest(name: string, candidates: readonly string[]): string | undefined {
+  const limit = Math.max(1, Math.floor(name.length / 3));
+  let best: string | undefined;
+  let bestDistance = limit + 1;
+  for (const candidate of candidates) {
+    const d = editDistance(name, candidate.toLowerCase());
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  return best;
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j]! + 1, cur[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length]!;
+}
+
+/**
+ * The repo-relative path of a skill file (`Plugins/…/SKILL.md` or
+ * `Skills/…/SKILL.md`) when `workspacePath` names one, else `null`.
+ * Accepts the workspace spelling (`<kbDirName>/Plugins/…`) the save
+ * surfaces receive.
+ */
+export function skillFileRepoPath(kbDirName: string, workspacePath: string): string | null {
+  const parts = workspacePath.split('/').filter((p) => p && p !== '.');
+  if (parts[0] === kbDirName) parts.shift();
+  if (parts.length < 3 || parts[parts.length - 1] !== 'SKILL.md') return null;
+  return parts[0] === PLUGINS_DIR || parts[0] === SKILLS_DIR ? parts.join('/') : null;
+}
+
+/** What the save surfaces and `get_skill` depend on. */
+export interface IAllowedToolsChecker {
+  /** Warnings for a declared list, resolved against what `userEmail` can see. Never throws. */
+  check(userEmail: string, allowedTools: readonly string[] | undefined): Promise<AllowedToolWarning[]>;
+  /**
+   * Warnings for a file being saved: `[]` unless `workspacePath` is a skill
+   * file. Never throws — a save must not fail because a check could not run.
+   */
+  checkSave(userEmail: string, workspacePath: string, content: string): Promise<AllowedToolWarning[]>;
+  /**
+   * `checkSave` for a whole batch, reading the caller's catalog ONCE:
+   * `result[i]` is the warnings for `files[i]`. Never throws.
+   */
+  checkSaves(
+    userEmail: string,
+    files: readonly { path: string; content: string }[],
+  ): Promise<AllowedToolWarning[][]>;
+}
+
+/** Resolves "the tools a user can see" from the tool catalog and the manuals they may read. */
+export class AllowedToolsChecker implements IAllowedToolsChecker {
+  constructor(
+    private readonly registry: Pick<IToolRegistry, 'listExternal'>,
+    private readonly manuals: Pick<IToolManualService, 'listAccessible' | 'getDetail'>,
+    private readonly kbDirName: string,
+    /**
+     * The cap `getDetail` applies to a manual's capabilities. Taken from the
+     * projection itself: a copy of the number here would silently start
+     * reporting real tools missing the day the projection's cap grew.
+     */
+    private readonly maxCapabilities = MAX_CAPABILITIES,
+  ) {}
+
+  async check(userEmail: string, allowedTools: readonly string[] | undefined): Promise<AllowedToolWarning[]> {
+    return (await this.checkLists(userEmail, [allowedTools]))[0]!;
+  }
+
+  async checkSave(userEmail: string, workspacePath: string, content: string): Promise<AllowedToolWarning[]> {
+    return (await this.checkSaves(userEmail, [{ path: workspacePath, content }]))[0]!;
+  }
+
+  async checkSaves(
+    userEmail: string,
+    files: readonly { path: string; content: string }[],
+  ): Promise<AllowedToolWarning[][]> {
+    return this.checkLists(
+      userEmail,
+      files.map((f) => this.declaredTools(f.path, f.content)),
+    );
+  }
+
+  /**
+   * The `allowed-tools` a file being saved declares — `undefined` for a file
+   * that is not a skill, or whose frontmatter will not parse (a save must not
+   * fail because a check could not run).
+   */
+  private declaredTools(workspacePath: string, content: string): readonly string[] | undefined {
+    if (skillFileRepoPath(this.kbDirName, workspacePath) === null) return undefined;
+    try {
+      return parseSkillFrontmatter(content).allowedTools;
+    } catch (err) {
+      log.warn('allowed-tools check skipped', { err });
+      return undefined;
+    }
+  }
+
+  /**
+   * One catalog read for however many lists. A list with nothing the platform
+   * could have an opinion on costs nothing — and when no list has, the catalog
+   * is not read at all.
+   */
+  private async checkLists(
+    userEmail: string,
+    lists: readonly (readonly string[] | undefined)[],
+  ): Promise<AllowedToolWarning[][]> {
+    const worth = lists.map((l) => l?.some(looksLikePlatformTool) === true);
+    if (!worth.some(Boolean)) return lists.map(() => []);
+    try {
+      const visible = await this.visibleTools(userEmail);
+      return lists.map((l, i) => (worth[i] ? checkAllowedTools(l!, visible) : []));
+    } catch (err) {
+      log.warn('allowed-tools check skipped', { err });
+      return lists.map(() => []);
+    }
+  }
+
+  private async visibleTools(userEmail: string): Promise<VisibleTools> {
+    const [coreTools, summaries] = await Promise.all([
+      this.registry.listExternal({ userEmail }),
+      this.manuals.listAccessible(userEmail),
+    ]);
+    const manuals = await Promise.all(
+      summaries.map(async (m) => {
+        if (m.type !== 'inline') return { name: m.name, tools: null };
+        const detail = await this.manuals.getDetail(userEmail, m.slug);
+        const caps = detail?.capabilities ?? [];
+        // A capped list may be missing the very tool asked about.
+        if (!detail || caps.length >= this.maxCapabilities) return { name: m.name, tools: null };
+        return {
+          name: m.name,
+          tools: caps.map((c) => (c.name.startsWith(`${m.name}.`) ? c.name.slice(m.name.length + 1) : c.name)),
+        };
+      }),
+    );
+    return { core: coreTools.map((t) => t.name), manuals };
+  }
+}

package/src/modules/skills/index.ts

@@ -2,6 +2,8 @@ export { SkillService } from './skills.service.js';
 export { PendingSkillsService } from './pending-skills.service.js';
 export { registerSkillsTools } from './skills.tools.js';
 export { createSkillsRoutes } from './skills.routes.js';
+export { AllowedToolsChecker } from './allowed-tools-check.js';
+export type { IAllowedToolsChecker, AllowedToolWarning } from './allowed-tools-check.js';
 export { createSkillAccessRequestRoutes } from './skill-access-requests.routes.js';
 export type {
   ISkillService,
@@ -11,4 +13,6 @@ export type {
   SkillFileContent,
   PendingSkill,
   GetSkillResult,
+  GetSkillOptions,
+  SkillHistorySource,
 } from './skills.contract.js';