@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/src/modules/mcp/shared-definitions.ts

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import type { CallTemplate, Tool as UtcpTool } from '@utcp/sdk';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import type { ProxiedTool } from '@bevel-software/platform-mcp-core';
+
+/**
+ * Tool definitions held once for every cached client that discovered the same
+ * ones.
+ *
+ * Two hundred people whose catalogs are identical would otherwise hold two
+ * hundred copies of the same descriptions and schemas: a client's repository
+ * keeps what discovery parsed, and every build parses its own. After a build,
+ * each manual's discovered tools are swapped for the first copy of identical
+ * tools this process has seen, so the descriptions, schemas and call templates
+ * are one object graph no matter how many clients point at it. A client keeps
+ * only what is its own: the repository's per-tool shells, its variables and
+ * its secrets loader.
+ *
+ * Identity is the CONTENT of the definitions, not the manual's name or its
+ * template: the knowledge base's manual is filtered per caller, so two people
+ * can get different tools from the same template, and only identical content
+ * may be shared. Definitions are tool schemas and call TEMPLATES — `${VAR}`
+ * placeholders, never a resolved value — so sharing them shares no secret.
+ *
+ * Nothing here is read back for correctness: a definition dropped from these
+ * maps (they are bounded) only stops the NEXT build from sharing it.
+ */
+export class SharedDefinitions {
+  private readonly byContent = new Map<string, unknown>();
+  private readonly interfaceCaches = new Map<string, Map<string, string>>();
+
+  /** `maxEntries` bounds each map; 0 shares nothing. */
+  constructor(private readonly maxEntries = 1000) {}
+
+  /**
+   * The first-seen copy of `value` (by its JSON), or `value` itself when it is
+   * the first. Kinds share no key space: a tool list and a listing could
+   * otherwise serialise alike.
+   */
+  intern<T>(kind: string, value: T): T {
+    const key = `${kind}\u0000${fingerprint(value)}`;
+    const held = this.byContent.get(key);
+    if (held !== undefined) {
+      // Recently used goes last, so the first entry is the one to drop.
+      this.byContent.delete(key);
+      this.byContent.set(key, held);
+      return held as T;
+    }
+    if (this.maxEntries <= 0) return value;
+    bound(this.byContent, this.maxEntries);
+    this.byContent.set(key, value);
+    return value;
+  }
+
+  /**
+   * Point `client`'s repository at shared definitions: every manual's tools,
+   * and the client's cache of generated TypeScript interfaces.
+   *
+   * `rawTemplates` are the manuals as fetched, by the name they are registered
+   * under. Registration stores the template AFTER variable substitution — for
+   * a platform-hosted manual, with the bearer of the request that built the
+   * client in its headers. Nothing calls through a stored template (each
+   * tool's own template is substituted at call time), but a cached client
+   * must hold no request's credential, so the stored template is put back to
+   * its placeholders.
+   */
+  async share(client: CodeModeUtcpClient, rawTemplates: ReadonlyMap<string, CallTemplate>): Promise<void> {
+    const repo = client.config.tool_repository;
+    const templates = await repo.getManualCallTemplates();
+    const everyTool: UtcpTool[] = [];
+    for (const stored of templates) {
+      const name = String(stored.name ?? '');
+      const manual = await repo.getManual(name);
+      if (!manual) continue;
+      const tools = this.intern('tools', manual.tools);
+      everyTool.push(...tools);
+      const raw = rawTemplates.get(name);
+      const template = raw ? ({ ...raw, name } as CallTemplate) : stored;
+      await repo.saveManual(template, { ...manual, tools });
+    }
+    // `toolFunctionCache` is filled lazily by `tools_info` and every chain,
+    // keyed by tool name and derived from the definitions alone. Shared by
+    // every client holding the very same tool set, it is generated once for
+    // all of them instead of once per person.
+    (client as unknown as { toolFunctionCache: Map<string, string> }).toolFunctionCache = this.interfaceCache(
+      fingerprint(everyTool),
+    );
+  }
+
+  /** The flattened catalog a surface lists, shared the same way. */
+  listing(tools: ProxiedTool[]): ProxiedTool[] {
+    return this.intern('listing', tools);
+  }
+
+  /** The generated-interface cache of one exact tool set. */
+  private interfaceCache(toolSet: string): Map<string, string> {
+    let cache = this.interfaceCaches.get(toolSet);
+    if (cache) {
+      this.interfaceCaches.delete(toolSet);
+    } else {
+      cache = new Map();
+      if (this.maxEntries <= 0) return cache;
+      bound(this.interfaceCaches, this.maxEntries);
+    }
+    this.interfaceCaches.set(toolSet, cache);
+    return cache;
+  }
+}
+
+/** Make room for one more entry, dropping the least recently used. */
+function bound(map: Map<string, unknown>, maxEntries: number): void {
+  while (map.size >= maxEntries) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
+function fingerprint(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}

package/src/modules/mcp/surface-cache.ts

@@ -0,0 +1,154 @@
+/**
+ * The hosted MCP server's memory of built tool surfaces: one per caller and
+ * catalog revision, built once and reused until something it was built from
+ * changes.
+ *
+ * Keyed by whatever the service says identifies a surface — the person, the
+ * kind of caller, the key's scope and the catalog revision. A catalog change
+ * needs no listener: it is a new revision, so a new key, and the old entry
+ * ages out unused. What the revision cannot see (a secret) is evicted
+ * explicitly through {@link evictWhere} / {@link clear}.
+ *
+ * Bounded twice: an entry unused for `idleTtlMs` is dropped, and at most
+ * `maxEntries` are held, the least recently used going first. `maxEntries: 0`
+ * keeps nothing, which is the per-request build this replaced: the escape
+ * hatch if the cache ever has to be switched off.
+ *
+ * Single-flight: concurrent misses on one key share one build. A build that
+ * fails is not remembered, so the next request tries again. A build that was
+ * in flight when its key was evicted answers the requests waiting on it but is
+ * not kept: it was built from what the eviction said is stale. A build still
+ * running after `buildTimeoutMs` is let go the same way, so a discovery that
+ * hangs holds up the requests already waiting on it, not every later one.
+ *
+ * Holds references only. A surface owns no connection (its `mcp` manuals route
+ * to the downstream pool, which owns and closes those), so dropping an entry
+ * is the whole teardown.
+ */
+export interface SurfaceCacheOptions {
+  /** Drop an entry unused for this long. Default one hour. */
+  idleTtlMs?: number;
+  /** Hold at most this many entries. Default 500; 0 keeps nothing. */
+  maxEntries?: number;
+  /** Let go of a build still running after this long; the next request starts another. Default two minutes. */
+  buildTimeoutMs?: number;
+  /** Clock, for tests. */
+  now?: () => number;
+}
+
+export const SURFACE_IDLE_TTL_MS = 60 * 60 * 1000;
+export const SURFACE_BUILD_TIMEOUT_MS = 2 * 60 * 1000;
+export const SURFACE_MAX_ENTRIES = 500;
+
+interface Entry<V> {
+  value: Promise<V>;
+  startedAt: number;
+  lastUsed: number;
+  /** An absolute end, for a value that must not live its full idle time (see `maxAgeMs`). */
+  expiresAt: number;
+  /** False once the entry was evicted while its build was still running. */
+  live: boolean;
+  settled: boolean;
+}
+
+export class SurfaceCache<V> {
+  private readonly entries = new Map<string, Entry<V>>();
+  private readonly idleTtlMs: number;
+  private readonly maxEntries: number;
+  private readonly buildTimeoutMs: number;
+  private readonly now: () => number;
+
+  constructor(opts: SurfaceCacheOptions = {}) {
+    this.idleTtlMs = opts.idleTtlMs ?? SURFACE_IDLE_TTL_MS;
+    this.maxEntries = opts.maxEntries ?? SURFACE_MAX_ENTRIES;
+    this.buildTimeoutMs = opts.buildTimeoutMs ?? SURFACE_BUILD_TIMEOUT_MS;
+    this.now = opts.now ?? Date.now;
+  }
+
+  /**
+   * The value for `key`, built by `build` when none is held. `hit` says
+   * whether this call found one (or joined a build already running).
+   *
+   * `maxAgeMs`, read off a built value, ends that entry early whatever its
+   * use: a surface built while one of its manuals was failing is kept only
+   * as long as that failure would be remembered anyway.
+   */
+  async get(
+    key: string,
+    build: () => Promise<V>,
+    maxAgeMs?: (value: V) => number | undefined,
+  ): Promise<{ value: V; hit: boolean }> {
+    this.sweep();
+    const now = this.now();
+    const held = this.entries.get(key);
+    if (held) {
+      held.lastUsed = now;
+      // Most recently used goes last, so the first entry is always the one to drop.
+      this.entries.delete(key);
+      this.entries.set(key, held);
+      return { value: await held.value, hit: true };
+    }
+    if (this.maxEntries <= 0) return { value: await build(), hit: false };
+    while (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.drop(oldest);
+    }
+    const entry: Entry<V> = {
+      value: build(),
+      startedAt: now,
+      lastUsed: now,
+      expiresAt: Number.POSITIVE_INFINITY,
+      live: true,
+      settled: false,
+    };
+    this.entries.set(key, entry);
+    try {
+      const value = await entry.value;
+      entry.settled = true;
+      const maxAge = maxAgeMs?.(value);
+      if (maxAge !== undefined) entry.expiresAt = this.now() + maxAge;
+      if (!entry.live) this.forget(key, entry);
+      return { value, hit: false };
+    } catch (err) {
+      this.forget(key, entry);
+      throw err;
+    }
+  }
+
+  /** Drop every entry whose key matches. A build in flight still answers its waiters, and is not kept. */
+  evictWhere(predicate: (key: string) => boolean): void {
+    for (const key of [...this.entries.keys()]) {
+      if (predicate(key)) this.drop(key);
+    }
+  }
+
+  /** Drop everything. */
+  clear(): void {
+    this.evictWhere(() => true);
+  }
+
+  private drop(key: string): void {
+    const entry = this.entries.get(key);
+    if (!entry) return;
+    entry.live = false;
+    this.entries.delete(key);
+  }
+
+  /** Remove `entry` only if it is still the one under `key` (a newer build may have taken its place). */
+  private forget(key: string, entry: Entry<V>): void {
+    if (this.entries.get(key) === entry) this.entries.delete(key);
+  }
+
+  /** Drop what has been idle too long, or outlived its own end, and let go of a build that has run too long. */
+  private sweep(): void {
+    const now = this.now();
+    for (const [key, entry] of this.entries) {
+      if (!entry.settled) {
+        if (now - entry.startedAt >= this.buildTimeoutMs) this.drop(key);
+        continue;
+      }
+      if (now - entry.lastUsed >= this.idleTtlMs || now >= entry.expiresAt) this.drop(key);
+    }
+  }
+}

package/src/modules/plugins/__tests__/teams.routes.test.ts

@@ -4,6 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { AccessControlService } from '../../access/access-control.service.js';
 import type { ISkillService, SkillSummary } from '../../skills/skills.contract.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { IPluginIndexService, PluginCatalogEntry } from '../plugins.contract.js';
@@ -62,6 +63,10 @@ interface HarnessOpts {
   /** What the org-wide `everyone` principal reads. */
   everyone?: string[];
   email?: string | null;
+  /** Whether the caller is an admin, who is shown every group. Defaults to true. */
+  admin?: boolean;
+  /** The groups the caller is a member of, which is all a non-admin is shown. */
+  memberOf?: string[];
 }
 
 /** The org-wide entry every answer opens with — empty unless `everyone` says otherwise. */
@@ -82,6 +87,12 @@ async function harness(opts: HarnessOpts = {}) {
       opts.team && group in opts.team ? tableVerdict(opts.team[group], paths) : null,
     ),
     canReadAsEveryoneBatch: vi.fn(async (_w: string, paths: string[]) => tableVerdict(opts.everyone, paths)),
+    holdsAdminRootWrite: vi.fn(async () => opts.admin ?? true),
+    groupsOfUser: vi.fn(async () => opts.memberOf ?? []),
+    // The real policy over the two stubs above: who sees which group is the
+    // resolver's one answer, not something a route (or this double) decides.
+    visibleGroups: (wsId: string, email: string, groups: readonly string[]) =>
+      AccessControlService.prototype.visibleGroups.call(accessControl, wsId, email, groups),
   } as unknown as IAccessControl;
   const index = { catalog: async () => CATALOG, invalidate: () => undefined } as IPluginIndexService;
   const skills = { listSkills: async () => SKILLS } as unknown as ISkillService;
@@ -242,6 +253,50 @@ describe('GET /api/teams', () => {
     );
   });
 
+  it("shows someone who is not an admin only the groups they are in, never another group's name", async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: {
+        'Sales Team': ['Plugins/GTM', 'Skills/Sales/outreach/SKILL.md', 'Plugins/GTM/mcp.json'],
+        'Finance Team': ['Plugins/Finance', 'Skills/Finance/ledger/SKILL.md', 'Plugins/Finance/books.tool'],
+      },
+      admin: false,
+      memberOf: ['Sales Team'],
+    });
+    const res = await h.get();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      teams: [
+        NOTHING_ORG_WIDE,
+        { name: 'Sales Team', plugins: ['gtm'], skills: ['outreach'], tools: ['hubspot'] },
+      ],
+    });
+    // A group that is not listed is not asked about either.
+    expect(h.accessControl.canReadAsGroupBatch).not.toHaveBeenCalledWith(
+      expect.anything(),
+      'Finance Team',
+      expect.anything(),
+    );
+  });
+
+  it('shows someone in no group, who is not an admin, Everyone alone', async () => {
+    const h = await harness({ groups: ['Sales Team'], caller: EVERYTHING, team: { 'Sales Team': [] }, admin: false });
+    expect(await (await h.get()).json()).toEqual({ teams: [NOTHING_ORG_WIDE] });
+  });
+
+  it('shows an admin every group, including ones they are not in', async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: { 'Sales Team': [], 'Finance Team': [] },
+      admin: true,
+      memberOf: [],
+    });
+    const body = (await (await h.get()).json()) as { teams: { name: string }[] };
+    expect(body.teams.map((t) => t.name)).toEqual(['Everyone', 'Sales Team', 'Finance Team']);
+  });
+
   it('is 401 without a caller', async () => {
     const h = await harness({ email: null });
     expect((await h.get()).status).toBe(401);

package/src/modules/plugins/teams.routes.ts

@@ -37,6 +37,10 @@ import type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract
  * what `read: everyone` (or a public plugin) reaches. Same slice, same
  * caller gate, asked of the resolver as `canReadAsEveryoneBatch`. The name
  * cannot collide with a group's: `everyone` is reserved by the grammar.
+ *
+ * The groups listed after it are every group for an admin, and only the
+ * caller's own groups for anyone else (`groupsOfUser`), so the lens never
+ * names a group the caller has no part in.
  */
 export interface TeamAccess {
   name: string;
@@ -110,10 +114,19 @@ export function createTeamsRoutes(
         };
       };
 
+      // Which groups to list: the resolver's one answer to who sees which
+      // group (every group for an admin, only their own for anyone else), the
+      // same the share dialog offers and a grant may name. A group's NAME is
+      // information too: a deployment that gives each client, author or
+      // customer a group of their own would otherwise show every member the
+      // whole roster, even though the slices of groups they are not in come
+      // back empty.
+      const listed = await accessControl.visibleGroups(wsId, email, groups);
+
       const teams: TeamAccess[] = [
         slice(EVERYONE_TEAM, await accessControl.canReadAsEveryoneBatch(wsId, probes)),
       ];
-      for (const name of groups) {
+      for (const name of listed) {
         const team = await accessControl.canReadAsGroupBatch(wsId, name, probes);
         if (team === null) continue; // gone between the two reads — nothing to say
         teams.push(slice(name, team));

package/src/modules/settings/__tests__/setup.routes.layout-phase.test.ts

@@ -10,13 +10,13 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
-import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
 import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import { newKbStartupRunner } from '../../../__tests__/workspace-service.js';
 
 /**
  * The completing save and the REAL initialization phase, wired the way the
@@ -105,7 +105,7 @@ function boot() {
   // it: the completing save applies the admin's names to it, and the step
   // reads them from it when the phase runs.
   const kb = testKbContext();
-  const runner = new KbStartupRunner({
+  const runner = newKbStartupRunner({
     gitRunner: new NodeGitRunner(),
     kbRepoUrl: () => upstream,
     workspacesRoot: path.join(root, 'workspaces'),

package/src/modules/settings/__tests__/setup.routes.managed-phase.test.ts

@@ -12,7 +12,6 @@ import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import { ManagedRepository } from '../managed-repository.js';
 import { RepositorySource } from '../repository-source.js';
-import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
 import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
@@ -20,6 +19,7 @@ import { defaultKbTemplateDir } from '../../../assets.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { KbContext } from '../../../shared/kb-context.js';
+import { newKbStartupRunner } from '../../../__tests__/workspace-service.js';
 
 /**
  * A repository the deployment keeps, and the REAL startup phase, wired the
@@ -89,7 +89,7 @@ function boot(kb: KbContext) {
   const gitRunner = new NodeGitRunner(60_000, source.credentials);
   const workspacesRoot = path.join(root, 'workspaces');
   const setAsideRoot = path.join(root, 'backups', 'replaced-working-copies');
-  const runner = new KbStartupRunner({
+  const runner = newKbStartupRunner({
     gitRunner,
     kbRepoUrl: () => source.url(),
     workspacesRoot,

package/src/modules/tool-auth/internal-token.service.ts

@@ -33,7 +33,7 @@ export interface InternalTokenClaim {
    * connection key to pass through). The verifier resolves such tokens to
    * `source: 'external'`: the caller IS an external agent, and must be treated
    * like one everywhere — admitted to external-only surfaces (`start_session`,
-   * `ask`), refused from internal-only ones (`execute_command`, …), and
+   * `ask`), refused from internal-only ones (`switch_branch`, …), and
    * expected to carry `sessionId` on the tool body, not in the token.
    */
   externalProxy?: boolean;

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -66,8 +66,7 @@ const WWW_AUTH = 'Bearer realm="bevel-tools"';
  * Gate that admits ONLY in-process callers (those bearing an internal HMAC
  * token). Mount it AFTER `toolAuth` on every internal-only surface — the
  * internal tool catalog and the routes of tools registered with
- * `registerInternalTool` but NOT `registerExternalTool` (e.g. `execute_command`,
- * `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
+ * `registerInternalTool` but NOT `registerExternalTool` (e.g. `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
  * an external connection key authenticates successfully, so without this gate it
  * could invoke an internal-only route directly by guessing its name. The route
  * MUST stay mounted (our own agent reaches it over the same loopback HTTP), so

package/src/modules/tool-helpers/__tests__/branch-declaration.test.ts

@@ -8,7 +8,6 @@ import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
@@ -24,6 +23,7 @@ import {
   type BranchDeclaration,
   type ToolDefSpec,
 } from '../index.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 const execFileAsync = promisify(execFile);
 const KB_DIR = 'knowledge-base';
@@ -116,7 +116,7 @@ describe('a tool declares how it treats its branch', () => {
     await runGit(seed, ['push', 'origin', 'HEAD:refs/heads/refs/heads/ghost']);
 
     kb = testKbContext({ kbDirName: KB_DIR });
-    const workspaces = new WorkspaceService(workspacesRoot, upstream, kb, new NodeFs());
+    const workspaces = newWorkspaceService(workspacesRoot, upstream, kb, new NodeFs());
     const resolve = createToolContextResolver({
       authService: {
         getUserById: async () => ({ id: 'u', email: 'alice@example.com', name: 'Alice' }),

package/src/modules/tool-helpers/tool-context.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 import { ReadOnlyFilesystem } from '../kb-fs/read-only-filesystem.js';
 import {
   makeAgentRolesYamlWriteValidator,
@@ -76,6 +77,36 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
     if (!user) throw new ToolError('Your account is no longer available.', 401);
 
     const { loadActiveGroups } = deps;
+    const validatorCache = new Map<string, WriteValidator>();
+    /**
+     * The agent's pre-disk `roles.yaml` gate for `branch`'s workspace
+     * (cached): refuses a write that would leave the file unparseable (an
+     * app-wide admin lockout), that creates a role, or that adds a
+     * `- group:` entry naming no group — agents manage membership; roles are
+     * pre-set. ONE gate for every agent write to the workspace: the file
+     * tools take it before a byte lands, and `update_branch` takes it for a
+     * resolution's content before the merge.
+     */
+    const getWriteValidator = async (branch: string): Promise<WriteValidator> => {
+      assertBranchProvided(branch);
+      const cached = validatorCache.get(branch);
+      if (cached) return cached;
+      const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
+      const basePath = await deps.workspaceService.getWorkspacePath(ws.id);
+      const validator = makeAgentRolesYamlWriteValidator(
+        deps.kbDirName,
+        () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
+        loadActiveGroups &&
+          (async () => {
+            // A source that exists but cannot be read leaves group entries
+            // unchecked rather than refusing every one.
+            const active = await loadActiveGroups((file) => readTextIfExists(path.join(basePath, deps.kbDirName, file)));
+            return active.health.ok ? active : null;
+          }),
+      );
+      validatorCache.set(branch, validator);
+      return validator;
+    };
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
       // THE choke point: every knowledge-base tool resolves its workspace
@@ -94,6 +125,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       assertBranchProvided(branch);
       const cached = fsCache.get(branch);
       if (cached) return cached;
+      // (The write validator below is built through `getWriteValidator`.)
       const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
       const workspaceId = ws.id;
       const basePath = await deps.workspaceService.getWorkspacePath(workspaceId);
@@ -107,24 +139,10 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
                 branch: branchForWorkspaceId(workspaceId),
                 user,
                 kbDirName: deps.kbDirName,
-                // Reject an agent write that would leave roles.yaml unparseable
-                // (app-wide admin lockout) or that creates a role before it
-                // reaches disk, or that adds a `- group:` entry naming no group
-                // — the agent gets a tool error and the file is untouched.
-                // Agents manage membership; roles are pre-set.
-                validateWrite: makeAgentRolesYamlWriteValidator(
-                  deps.kbDirName,
-                  () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
-                  loadActiveGroups &&
-                    (async () => {
-                      // A source that exists but cannot be read leaves group
-                      // entries unchecked rather than refusing every one.
-                      const active = await loadActiveGroups((file) =>
-                        readTextIfExists(path.join(basePath, deps.kbDirName, file)),
-                      );
-                      return active.health.ok ? active : null;
-                    }),
-                ),
+                // The agent's pre-disk roles.yaml gate (`getWriteValidator`):
+                // the file tools and `update_branch`'s resolutions take the
+                // same one.
+                validateWrite: await getWriteValidator(branch),
                 creatorAccess: deps.creatorAccess,
               },
             )
@@ -155,6 +173,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       workflowService: deps.workflowService,
       events: deps.events,
       getFilesystem,
+      getWriteValidator,
     };
   };
 }

package/src/modules/tool-helpers/tool-handler.ts

@@ -36,8 +36,8 @@ export interface ToolHandlerOptions {
   writeScope?: boolean;
   /**
    * How this route treats `branch`, when it must differ from what its
-   * `toolDef` recorded. Only `execute_command` sets it (`own`): it falls back
-   * to an internal caller's focused branch rather than being refused.
+   * `toolDef` recorded (`own`: the handler resolves it itself rather than
+   * being refused).
    */
   branch?: BranchHandling;
 }

package/src/modules/tool-helpers/tool.contract.ts

@@ -2,6 +2,7 @@ import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared
 import type { LocalFilesystem } from '@mastra/core/workspace';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 
 /**
  * The hosting/execution contract a module works against when it lets `toolHelpers`
@@ -41,8 +42,8 @@ export interface ToolContext {
   sessionId?: string;
   /**
    * The branch the in-process agent's workspace is focused on, from its internal
-   * token. An internal-only workspace tool (e.g. `execute_command`) falls back to
-   * it when the model omits `branch`, so the in-app chat agent acts on its own
+   * token. A tool may fall back to it when the model omits `branch` (`list_tool_setup`
+   * reads the focused branch's setup), so the in-app chat agent acts on its own
    * workspace even on a branch-less call. Only set for `source: 'internal'`;
    * external callers must name the branch explicitly (a present-but-invalid value
    * still fails closed regardless of this).
@@ -63,6 +64,13 @@ export interface ToolContext {
   events: WorkflowEventBus;
   /** Build the lock-aware filesystem for `branch`'s workspace (cached). The tool supplies `branch` from its own input. */
   getFilesystem(branch: string): Promise<LocalFilesystem>;
+  /**
+   * The agent's pre-disk write gate for `branch`'s workspace (cached) — the
+   * one the filesystem above runs before a byte lands (`roles.yaml`: must
+   * parse, no new role, no unknown group). A tool that writes content by
+   * another road than that filesystem (a merge resolution) takes it too.
+   */
+  getWriteValidator(branch: string): Promise<WriteValidator>;
 }
 
 /**

package/src/modules/tool-registry/__tests__/own-tool-schemas.test.ts

@@ -59,7 +59,7 @@ const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import
 const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
   {
     name: 'registerWorkflowTools',
-    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true),
+    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
   },
   {
     name: 'registerChangeRequestReadTools',

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -15,6 +15,7 @@ import type { UtcpTool } from '../tool.contract.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { WorkerPatternMatcher } from '../../workspace/bounded-matcher.js';
 import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
 import { registerPluginsTools } from '../../plugins/plugins.tools.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
@@ -110,8 +111,13 @@ async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = em
     // mounted on the same terms as the upload one.
     undefined,
     unused(),
+    // Starter packs and the tree walk, not needed; then the grep matcher,
+    // mounted on the same terms (it spawns no worker until a search runs).
+    undefined,
+    undefined,
+    new WorkerPatternMatcher(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
   registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
@@ -257,7 +263,6 @@ describe('every file tool opens with the guide-first sentence and carries no sha
     'move_file',
     'copy_file',
     'unzip',
-    'execute_command',
     'apply_file_upload',
   ];