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

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

@@ -0,0 +1,224 @@
+import { describe, test, expect, vi } from 'vitest';
+import {
+  AllowedToolsChecker,
+  checkAllowedTools,
+  skillFileRepoPath,
+  type VisibleTools,
+} from '../allowed-tools-check.js';
+import type { UtcpTool } from '../../tool-registry/tool.contract.js';
+import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+
+const visible: VisibleTools = {
+  core: ['read_file', 'get_skill', 'list_skills'],
+  manuals: [
+    // inline: its tools are known, so a tool under it can be proven absent
+    { name: 'hubspot', tools: ['search', 'create_contact'] },
+    // mcp: tools discovered at call time, so anything under it is accepted
+    { name: 'gmail', tools: null },
+  ],
+};
+
+const entries = (w: ReturnType<typeof checkAllowedTools>) => w.map((x) => x.entry);
+
+describe('checkAllowedTools', () => {
+  test('a known platform tool, in every spelling, is not flagged', () => {
+    expect(
+      checkAllowedTools(
+        [
+          'hubspot',
+          'hubspot.search',
+          'mcp__hexis__hubspot_search',
+          'mcp__hexis__read_file',
+          'read_file',
+          'hubspot_create_contact',
+          'gmail.send_message',
+          'mcp__hexis__gmail_send_message',
+          'KNOWLEDGE_BASE.read_file',
+        ],
+        visible,
+      ),
+    ).toEqual([]);
+  });
+
+  test('an unknown platform-looking name is flagged with the closest tool', () => {
+    const warnings = checkAllowedTools(['hubspot.serch'], visible);
+    expect(warnings).toEqual([
+      {
+        entry: 'hubspot.serch',
+        suggestion: 'hubspot.search',
+        message: expect.stringContaining('"hubspot.serch"'),
+      },
+    ]);
+    expect(warnings[0]!.message).toContain('hubspot.search');
+  });
+
+  test('suggestions keep the spelling of the entry', () => {
+    expect(checkAllowedTools(['mcp__hexis__read_fil'], visible)[0]?.suggestion).toBe('mcp__hexis__read_file');
+    expect(checkAllowedTools(['hubspto'], visible)[0]?.suggestion).toBe('hubspot');
+    // A manual whose tools are unknown suggests the manual, keeping the tool part.
+    expect(checkAllowedTools(['gmial.send_message'], visible)[0]?.suggestion).toBe('gmail.send_message');
+  });
+
+  test('a shared prefix does not pad the typo budget', () => {
+    // Scored whole, `mcp__hexis__weather_forecast` is within a third of its
+    // length of `mcp__hexis__write_files` — the twelve prefix characters can
+    // never be misspelt, yet they bought nine edits of slack.
+    const withWriteFiles: VisibleTools = { ...visible, core: [...visible.core, 'write_files'] };
+    const [retired] = checkAllowedTools(['mcp__hexis__weather_forecast'], withWriteFiles);
+    expect(retired?.entry).toBe('mcp__hexis__weather_forecast');
+    expect(retired?.suggestion).toBeUndefined();
+    // A real typo behind the prefix is still found, in the entry's own namespace spelling.
+    expect(checkAllowedTools(['KNOWLEDGE_BASE.read_fil'], visible)[0]?.suggestion).toBe('KNOWLEDGE_BASE.read_file');
+    // Under a known manual only that manual's tools are candidates.
+    expect(checkAllowedTools(['hubspot.create_contct'], visible)[0]?.suggestion).toBe('hubspot.create_contact');
+  });
+
+  test('an unknown name with nothing close carries no suggestion', () => {
+    const [w] = checkAllowedTools(['mcp__hexis__totally_unrelated_thing'], visible);
+    expect(w?.entry).toBe('mcp__hexis__totally_unrelated_thing');
+    expect(w?.suggestion).toBeUndefined();
+    expect(w?.message).not.toContain('Did you mean');
+  });
+
+  test('client tool names are never flagged', () => {
+    expect(
+      checkAllowedTools(
+        [
+          'Bash',
+          'Read',
+          'Edit',
+          'Write',
+          'Glob',
+          'Grep',
+          'WebFetch',
+          'Bash(git:*)',
+          'mcp__github__create_issue',
+          'mcp__hexis__*',
+          'apply_patch',
+          'shell',
+        ],
+        visible,
+      ),
+    ).toEqual([]);
+  });
+
+  test('a retired manual — no longer in the catalog — is flagged in every spelling', () => {
+    const warnings = checkAllowedTools(['legacy_crm', 'legacy_crm.search', 'mcp__hexis__legacy_crm_search'], visible);
+    expect(entries(warnings)).toEqual(['legacy_crm', 'legacy_crm.search', 'mcp__hexis__legacy_crm_search']);
+  });
+});
+
+describe('skillFileRepoPath', () => {
+  test('recognises skill files under the plugin and skills roots only', () => {
+    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
+    expect(skillFileRepoPath('knowledge-base', './knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
+    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
+    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Data/SKILL.md')).toBeNull();
+  });
+});
+
+describe('AllowedToolsChecker', () => {
+  const summary = (name: string, type: ToolManualSummary['type']): ToolManualSummary => ({
+    slug: name,
+    name,
+    path: `Plugins/Sales/${name}.tool`,
+    type,
+  });
+  const registry = {
+    listExternal: async () => [{ name: 'read_file' }, { name: 'get_skill' }] as UtcpTool[],
+  };
+  const manuals = {
+    listAccessible: async () => [summary('hubspot', 'inline'), summary('gmail', 'mcp')],
+    getDetail: async (_email: string, slug: string): Promise<ToolManualDetail | null> =>
+      slug === 'hubspot'
+        ? {
+            ...summary('hubspot', 'inline'),
+            description: null,
+            capabilities: [{ name: 'search', description: null }],
+          }
+        : null,
+  };
+  const checker = new AllowedToolsChecker(registry, manuals, 'knowledge-base');
+
+  const skill = (tools: string) => `---\nname: rfi\ndescription: RFI.\nallowed-tools: ${tools}\n---\n\n# RFI\n`;
+
+  test('checkSave resolves against the tools the user can see', async () => {
+    const warnings = await checker.checkSave(
+      'a@x.com',
+      'knowledge-base/Plugins/Sales/rfi/SKILL.md',
+      skill('Bash Read hubspot.search hubspot.serch gmail.send retired_crm'),
+    );
+    expect(entries(warnings)).toEqual(['hubspot.serch', 'retired_crm']);
+    expect(warnings[0]?.suggestion).toBe('hubspot.search');
+  });
+
+  test('checkSave ignores files that are not skills', async () => {
+    expect(await checker.checkSave('a@x.com', 'knowledge-base/Data/notes.md', skill('nope.nothing'))).toEqual([]);
+  });
+
+  test('a failing catalog yields no warnings rather than an error — the save is never blocked', async () => {
+    const broken = new AllowedToolsChecker(
+      { listExternal: async () => { throw new Error('down'); } },
+      manuals,
+      'knowledge-base',
+    );
+    await expect(
+      broken.checkSave('a@x.com', 'knowledge-base/Plugins/Sales/rfi/SKILL.md', skill('hubspot.serch')),
+    ).resolves.toEqual([]);
+  });
+
+  test('a capped capability list is treated as unknown, never as proof of absence', async () => {
+    const capped = new AllowedToolsChecker(registry, manuals, 'knowledge-base', 1);
+    expect(await capped.check('a@x.com', ['hubspot.whatever'])).toEqual([]);
+  });
+
+  test('the catalog is read AS THE CALLER, so the answer is about tools they can see', async () => {
+    // Spies, not plain stubs: the mocks above ignore their arguments, so a
+    // regression that built the catalog for the wrong user — or for nobody —
+    // would still return the same tools and pass every test above it.
+    const listExternal = vi.fn(registry.listExternal);
+    const listAccessible = vi.fn(manuals.listAccessible);
+    const getDetail = vi.fn(manuals.getDetail);
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+
+    expect(entries(await spying.check('alice@example.com', ['hubspot.serch']))).toEqual(['hubspot.serch']);
+    expect(listExternal).toHaveBeenCalledWith({ userEmail: 'alice@example.com' });
+    expect(listAccessible).toHaveBeenCalledWith('alice@example.com');
+    // The per-manual detail decides which tools exist, so it is the caller's
+    // view of that manual that must be read, not an ambient one.
+    expect(getDetail).toHaveBeenCalledWith('alice@example.com', 'hubspot');
+  });
+
+  test('a batch of saves reads the catalog once, and answers per file in order', async () => {
+    const listExternal = vi.fn(registry.listExternal);
+    const listAccessible = vi.fn(manuals.listAccessible);
+    const getDetail = vi.fn(manuals.getDetail);
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+
+    const results = await spying.checkSaves('a@x.com', [
+      { path: 'knowledge-base/Plugins/Sales/rfi/SKILL.md', content: skill('hubspot.serch') },
+      { path: 'knowledge-base/Data/notes.md', content: skill('nope.nothing') },
+      { path: 'knowledge-base/Skills/quote/SKILL.md', content: skill('Bash Read') },
+      { path: 'knowledge-base/Skills/triage/SKILL.md', content: skill('retired_crm') },
+    ]);
+
+    expect(results.map(entries)).toEqual([['hubspot.serch'], [], [], ['retired_crm']]);
+    expect(listExternal).toHaveBeenCalledTimes(1);
+    expect(listAccessible).toHaveBeenCalledTimes(1);
+    expect(getDetail).toHaveBeenCalledTimes(1);
+  });
+
+  test('a list of nothing but client tools reads no catalog at all', async () => {
+    // `get_skill` runs on every skill use; a skill that names only the
+    // client's tools must not cost a skill listing and a manual listing each time.
+    const listExternal = vi.fn(registry.listExternal);
+    const listAccessible = vi.fn(manuals.listAccessible);
+    const getDetail = vi.fn(manuals.getDetail);
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+
+    expect(await spying.check('a@x.com', ['Bash', 'Read', 'Bash(git:*)', 'mcp__github__create_issue', 'shell'])).toEqual([]);
+    expect(listExternal).not.toHaveBeenCalled();
+    expect(listAccessible).not.toHaveBeenCalled();
+    expect(getDetail).not.toHaveBeenCalled();
+  });
+});

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -0,0 +1,210 @@
+import type { Server as HttpServer } from 'node:http';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { LocalFilesystem } from '@mastra/core/workspace';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolContext } from '../../tool-helpers/tool.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { SpillStore } from '../../workspace/spill-store.js';
+import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import { registerSkillsTools } from '../skills.tools.js';
+import type { ISkillService } from '../skills.contract.js';
+import { AllowedToolsChecker } from '../allowed-tools-check.js';
+
+/**
+ * The agent surfaces end to end: a SKILL.md written through the file tools
+ * comes back with `warnings` (and is still written), and `get_skill` carries
+ * the same list — both resolved through the real tool handler machinery.
+ */
+
+const KB_DIR = 'knowledge-base';
+const SKILL_PATH = `${KB_DIR}/Plugins/Sales/rfi/SKILL.md`;
+const SKILL = '---\nname: rfi\ndescription: RFI.\nallowed-tools: Bash Read hubspot.search hubspot.serch legacy_crm\n---\n\n# RFI\n';
+
+const hubspot: ToolManualSummary = { slug: 'hubspot', name: 'hubspot', path: 'Plugins/Sales/hubspot.tool', type: 'inline' };
+const checker = new AllowedToolsChecker(
+  { listExternal: async () => [] },
+  {
+    listAccessible: async () => [hubspot],
+    getDetail: async (): Promise<ToolManualDetail> => ({
+      ...hubspot,
+      description: null,
+      capabilities: [{ name: 'search', description: null }],
+    }),
+  },
+  KB_DIR,
+);
+
+/** What the tool handed the service on its last `getSkill` — the tool's one job is to pass it on. */
+let lastGetSkillArgs: unknown[] = [];
+
+const skillService: ISkillService = {
+  listSkills: async () => [],
+  getSkill: async (...args: unknown[]) => {
+    lastGetSkillArgs = args;
+    return {
+      ok: true,
+      kind: 'skill',
+      skill: {
+        name: 'rfi',
+        description: 'RFI.',
+        path: 'Plugins/Sales/rfi',
+        body: '# RFI',
+        files: [],
+        allowedTools: ['Bash', 'hubspot.search', 'hubspot.serch', 'legacy_crm'],
+      },
+    };
+  },
+  invalidate: () => {},
+};
+
+let httpServer: HttpServer | undefined;
+let tempDir = '';
+
+async function start(): Promise<string> {
+  tempDir = await mkdtemp(join(tmpdir(), 'allowed-tools-'));
+  const fs = new LocalFilesystem({ basePath: tempDir, contained: true });
+  // `write_files` lands its batch through the locking filesystem's `writeFiles`
+  // (re-judge every path under the lock, then write what is kept). This plain
+  // filesystem has none, so the same contract is honoured by hand.
+  Object.assign(fs, {
+    writeFiles: async (
+      writes: { path: string; content: string }[],
+      _summary: string,
+      _deletes: string[],
+      check: (pending: readonly { path: string; content: string }[]) => Promise<{ path: string; content: string }[]>,
+    ) => {
+      for (const w of await check(writes)) await fs.writeFile(w.path, w.content);
+    },
+  });
+  const registry = new ToolRegistry();
+  const resolve = async (auth: ToolAuth, signal: AbortSignal, sessionId?: string): Promise<ToolContext> => ({
+    user: { id: 'u', email: 'e@x', name: 'N' },
+    scope: auth.scope,
+    source: auth.source,
+    sessionId,
+    abortSignal: signal,
+    workspaceService: {} as never,
+    workflowService: {} as never,
+    events: {} as never,
+    getFilesystem: async () => fs,
+  });
+  const toolHandler = createToolHandlerFactory(resolve);
+  const fakeAuth = (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    req.toolAuth = { source: 'internal', userId: 'u', scope: 'write' };
+    next();
+  };
+  const allowAll = { canRead: async () => true } as unknown as IAccessControl;
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  registerWorkspaceTools(
+    registry, router, fakeAuth, toolHandler,
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
+    { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+    new RoutineWritePolicyService(),
+    {} as never,
+    checker,
+  );
+  registerSkillsTools(registry, router, fakeAuth, toolHandler, skillService, checker);
+  app.use('/api', router);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+const post = (url: string, body: unknown) =>
+  fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer x' }, body: JSON.stringify(body) });
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  if (tempDir) await rm(tempDir, { recursive: true, force: true });
+});
+
+type Warning = { entry: string; suggestion?: string };
+
+describe('allowed-tools warnings on the agent surfaces', () => {
+  it('write_file saves the skill AND returns warnings for the unknown platform tools only', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/write_file`, { branch: 'main', path: SKILL_PATH, content: SKILL });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { warnings?: Warning[] };
+    expect(body.warnings?.map((w) => w.entry)).toEqual(['hubspot.serch', 'legacy_crm']);
+    expect(body.warnings?.[0]?.suggestion).toBe('hubspot.search');
+    // Never blocked: the file is on disk as written.
+    const read = (await (await post(`${base}/api/agent/tools/read_file`, { branch: 'main', path: SKILL_PATH })).json()) as {
+      content: string;
+    };
+    expect(read.content).toBe(SKILL);
+  });
+
+  it('edit_file checks the file as edited, and a clean skill carries no warnings key', async () => {
+    const base = await start();
+    await post(`${base}/api/agent/tools/write_file`, { branch: 'main', path: SKILL_PATH, content: SKILL });
+    const res = await post(`${base}/api/agent/tools/edit_file`, {
+      branch: 'main',
+      path: SKILL_PATH,
+      old_string: ' hubspot.serch legacy_crm',
+      new_string: '',
+    });
+    expect(await res.json()).toEqual({ path: SKILL_PATH, replaced: 1 });
+  });
+
+  it('write_files judges each landed skill once, by the content that is in the branch', async () => {
+    const base = await start();
+    const quote = `${KB_DIR}/Plugins/Sales/quote/SKILL.md`;
+    const res = await post(`${base}/api/agent/tools/write_files`, {
+      branch: 'main',
+      mode: 'overwrite',
+      files: [
+        // Named twice: this first content is replaced below and must not be judged.
+        { path: SKILL_PATH, content: SKILL },
+        { path: SKILL_PATH, content: SKILL.replace(' hubspot.serch legacy_crm', '') },
+        { path: quote, content: SKILL.replace('name: rfi', 'name: quote').replace(' hubspot.serch', '') },
+        { path: `${KB_DIR}/Data/notes.md`, content: '---\nallowed-tools: nope.nothing\n---\n' },
+      ],
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { count: number; warnings?: (Warning & { path: string })[] };
+    expect(body.count).toBe(4);
+    expect(body.warnings).toEqual([{ path: quote, entry: 'legacy_crm', message: expect.any(String) }]);
+  });
+
+  it('a non-skill file is never checked', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/write_file`, {
+      branch: 'main',
+      path: `${KB_DIR}/Data/notes.md`,
+      content: '---\nallowed-tools: nope.nothing\n---\n',
+    });
+    expect(await res.json()).not.toHaveProperty('warnings');
+  });
+
+  it('get_skill includes the same warnings under `warnings`', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi' });
+    const body = (await res.json()) as { ok: boolean; skill: { name: string }; warnings: Warning[] };
+    expect(body.ok).toBe(true);
+    expect(body.skill.name).toBe('rfi');
+    expect(body.warnings.map((w) => w.entry)).toEqual(['hubspot.serch', 'legacy_crm']);
+  });
+
+  it('get_skill passes `version` (and `file`) through to the service', async () => {
+    const base = await start();
+    await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi', version: '1.2.0' });
+    expect(lastGetSkillArgs.slice(1)).toEqual(['rfi', undefined, { version: '1.2.0' }]);
+    await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi', file: 'scripts/x.py' });
+    expect(lastGetSkillArgs.slice(1)).toEqual(['rfi', 'scripts/x.py', { version: undefined }]);
+  });
+});

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

@@ -1,7 +1,7 @@
 import { describe, test, expect } from 'vitest';
-import type { ChangeRequest, IWorkflowService } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
 import { PendingSkillsService } from '../pending-skills.service.js';
-import { hashEmail } from '../../../shared/hash-email.js';
+import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ISkillService, SkillSummary } from '../skills.contract.js';
@@ -37,7 +37,7 @@ function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
     author: { login: 'user-abc', name: 'service' },
     appAuthor: { name: 'Ali Raza' },
     branch: 'agent/weekly-newsletter',
-    base: 'main',
+    base: DEFAULT_BRANCH,
     state: 'open',
     createdAt: '2026-08-06T09:00:00.000Z',
     touchedNodePaths: ['Plugins/Engineering/weekly-newsletter/SKILL.md'],

package/src/modules/skills/__tests__/skills.routes.warnings.test.ts

@@ -0,0 +1,91 @@
+import type { Server } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import '../../auth/auth.middleware.js'; // Express Request.userEmail augmentation
+import { createSkillsRoutes } from '../skills.routes.js';
+import type { ISkillService } from '../skills.contract.js';
+import type { IAllowedToolsChecker } from '../allowed-tools-check.js';
+
+/**
+ * The browser's skill read carries the same `allowed-tools` warnings as
+ * `get_skill`, resolved for the CALLER — that is what lets the skill page say
+ * so when it opens, not only after a save.
+ */
+
+const EMAIL = 'alice@example.com';
+const SKILL = {
+  name: 'rfi',
+  description: 'RFI.',
+  path: 'Plugins/Sales/rfi',
+  body: '# RFI',
+  files: [] as string[],
+  allowedTools: ['Bash', 'hubspot.serch'],
+};
+const WARNING = { entry: 'hubspot.serch', message: 'not a tool', suggestion: 'hubspot.search' };
+
+const skillService = {
+  listSkills: async () => [],
+  getSkill: async (_email: string, name: string, file?: string) => {
+    if (name === 'secret') return { ok: false, error: 'forbidden' };
+    return file
+      ? { ok: true, kind: 'file', file: { name: 'rfi', file, path: `Plugins/Sales/rfi/${file}`, content: 'notes' } }
+      : { ok: true, kind: 'skill', skill: SKILL };
+  },
+  invalidate: () => {},
+} as unknown as ISkillService;
+
+let server: Server | undefined;
+
+async function start(checker?: IAllowedToolsChecker): Promise<string> {
+  const app = express();
+  app.use((req, _res, next) => {
+    req.userEmail = EMAIL;
+    next();
+  });
+  app.use('/api', createSkillsRoutes(skillService, undefined, undefined, undefined, checker));
+  server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+}
+
+afterEach(async () => {
+  if (server) await new Promise<void>((r) => server!.close(() => r()));
+  server = undefined;
+});
+
+describe('GET /api/skills/:name — allowed-tools warnings', () => {
+  it('answers with the warnings for the requesting user beside the skill', async () => {
+    const check = vi.fn(async () => [WARNING]);
+    const base = await start({ check, checkSave: async () => [], checkSaves: async () => [] });
+
+    const body = await (await fetch(`${base}/api/skills/rfi`)).json();
+
+    expect(body).toEqual({ ok: true, kind: 'skill', skill: SKILL, warnings: [WARNING] });
+    expect(check).toHaveBeenCalledWith(EMAIL, SKILL.allowedTools);
+  });
+
+  it('leaves a bundled-file answer alone: nothing there to check', async () => {
+    const check = vi.fn(async () => [WARNING]);
+    const base = await start({ check, checkSave: async () => [], checkSaves: async () => [] });
+
+    const body = (await (await fetch(`${base}/api/skills/rfi?file=notes.md`)).json()) as { kind: string };
+
+    expect(body.kind).toBe('file');
+    expect(body).not.toHaveProperty('warnings');
+    expect(check).not.toHaveBeenCalled();
+  });
+
+  it('passes a refusal through untouched, without asking the checker', async () => {
+    const check = vi.fn(async () => [WARNING]);
+    const base = await start({ check, checkSave: async () => [], checkSaves: async () => [] });
+
+    expect(await (await fetch(`${base}/api/skills/secret`)).json()).toEqual({ ok: false, error: 'forbidden' });
+    expect(check).not.toHaveBeenCalled();
+  });
+
+  it('without a checker the answer keeps its previous shape', async () => {
+    const base = await start();
+    expect(await (await fetch(`${base}/api/skills/rfi`)).json()).toEqual({ ok: true, kind: 'skill', skill: SKILL });
+  });
+});