@bevel-software/platform-core-backend 0.32.0 → 0.33.0

package/src/modules/plugins/__tests__/bundle-dialect.e2e.test.ts

@@ -8,6 +8,7 @@ import { testKbContext } from '../../../__tests__/kb-context.js';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
+import { AccessMutationService } from '../../access/access-mutation.service.js';
 import { SkillService } from '../../skills/skills.service.js';
 import { ToolManualService } from '../../tool-manuals/tool-manuals.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
@@ -103,7 +104,7 @@ describe('bundle dialect, end to end', () => {
     links = new PluginLinkIndex(workspaceService, skills, access, kb, source);
     index = new PluginIndexService(workspaceService, access, skills, tools, kb, source, Date.now, links);
     compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, kb, { name: 'acme', owner: 'Acme' }, source, disk, new NodeGitRunner());
-    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, skills, links, kb);
+    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, new AccessMutationService(workspaceService, access, kb.kbDirName), skills, links, kb);
   });
   afterEach(async () => {
     await fs.rm(root, { recursive: true, force: true });

package/src/modules/plugins/__tests__/plugin-links.service.test.ts

@@ -8,6 +8,7 @@ import { DEFAULT_BRANCH, withLinkedSkillRoots, type AuthUser } from '@bevel-soft
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
+import { AccessMutationService } from '../../access/access-mutation.service.js';
 import { SkillService } from '../../skills/skills.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { PluginLinkIndex } from '../plugin-links.js';
@@ -98,7 +99,7 @@ describe('PluginLinksService', () => {
     const kb = testKbContext({ kbDirName: KB_DIR });
     skills = new SkillService(workspaceService, access, kb, disk);
     index = new PluginLinkIndex(workspaceService, skills, access, kb, new KbPluginSource(disk, kb));
-    svc = new PluginLinksService(workspaceService, driver, access, skills, index, kb);
+    svc = new PluginLinksService(workspaceService, driver, access, new AccessMutationService(workspaceService, access, kb.kbDirName), skills, index, kb);
   });
   afterEach(() => fs.rm(root, { recursive: true, force: true }));
 

package/src/modules/plugins/compile/compile-marketplace.ts

@@ -11,8 +11,8 @@ import {
 import { BUNDLE_FILE as BUNDLE_MANIFEST_FILE } from '../discovery/bundle-dialect/bundle.source.js';
 import type { ITreeWalker } from '../../../shared/fs.contract.js';
 import { containsVariableReference } from '../../../shared/variable-refs.js';
-import { judgeMcpServerEntry } from '../../tool-manuals/mcp-json-discovery.js';
-import type { SkillSummary } from '../../skills/skills.contract.js';
+import { judgeMcpServerEntry } from '../../tool-manuals/index.js';
+import type { SkillSummary } from '../../skills/index.js';
 import type { LinkMembership } from '../plugin-links.js';
 import type { DiscoveredPlugin } from '../discovery/plugin-source.js';
 

package/src/modules/plugins/compile/marketplace-compiler.service.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { ISkillService } from '../../skills/skills.contract.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { IAccessControl } from '../../access/index.js';
+import type { ISkillService } from '../../skills/index.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import type { PluginLinkIndex } from '../plugin-links.js';
 import type { PluginSource } from '../discovery/plugin-source.js';

package/src/modules/plugins/discovery/bundle-dialect/registry.ts

@@ -18,7 +18,7 @@ import {
   judgeMcpServerEntry,
   type PortableHttpEntry,
   type PortableStdioEntry,
-} from '../../../tool-manuals/mcp-json-discovery.js';
+} from '../../../tool-manuals/index.js';
 
 export interface RegistryServer {
   /** The registry's own key: what a profile lists, unique across the file. */

package/src/modules/plugins/index.ts

@@ -39,3 +39,5 @@ export type {
   ResolvedPrincipals,
   ResolvedReaders,
 } from './plugins.contract.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { BUNDLE_FILE } from './discovery/bundle-dialect/bundle.source.js';

package/src/modules/plugins/join-proposals.ts

@@ -5,8 +5,8 @@ import {
   parseOwnAccessEntries,
   type ParsedEntry,
   type Verb,
-} from '../access-model/access-grammar.js';
-import type { TargetKind } from '../access/access-mutation.service.js';
+} from '../access-model/index.js';
+import type { TargetKind } from '../access/index.js';
 
 /**
  * What a join branch is PROPOSING, relative to the default branch.

package/src/modules/plugins/join-request-jobs.service.ts

@@ -5,12 +5,12 @@ import {
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
 import { DrizzleQueryError } from 'drizzle-orm';
-import { spliceGrant } from '../access-model/access-splice.js';
-import { sanitizeError } from '../workflow/sanitize-error.js';
+import { spliceGrant } from '../access-model/index.js';
+import { sanitizeError } from '../workflow/index.js';
 import { logger } from '../../shared/logging.js';
 import { printable } from '../../shared/printable.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type {
   ClaimedJoinRequest,
   JoinRequestRecord,

package/src/modules/plugins/join-request-records.store.ts

@@ -1,7 +1,7 @@
 import { and, eq, inArray, isNotNull, sql } from 'drizzle-orm';
 import type { ChangeRequestState } from '@bevel-software/platform-shared';
-import type { Database } from '../database/connection.js';
-import { changeRequests, pluginJoinRequests } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { changeRequests, pluginJoinRequests } from '../database/index.js';
 
 /**
  * A join request as the platform recorded it — the durable "this person

package/src/modules/plugins/join-requests.service.ts

@@ -4,18 +4,18 @@ import {
   type ChangeRequest,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
-import { type WorkspaceService } from '../workspace/workspace.service.js';
+import { type WorkspaceService } from '../workspace/index.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import {
   rulesFileFor,
   type AccessRequestTarget,
   type IAccessRequestLifecycle,
-} from '../access/access-requests.contract.js';
-import type { Verb } from '../access-model/access-grammar.js';
+} from '../access/index.js';
+import type { Verb } from '../access-model/index.js';
 import { pendingProposals, type JoinProposal } from './join-proposals.js';
 
 /** One open join change request, with what it still proposes. */

package/src/modules/plugins/plugin-links.service.ts

@@ -10,14 +10,14 @@ import {
   withLinkedSkillRoots,
   type AuthUser,
 } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { AccessMutationService, accessMdPathForFolder } from '../access/access-mutation.service.js';
-import { pluginPrincipalKey } from '../access-model/access-grammar.js';
-import type { Principal } from '../access-model/access-splice.js';
-import { WorkspaceMutex } from '../kb-fs/mutex.js';
-import type { ISkillService } from '../skills/skills.contract.js';
+import type { IAccessControl, IAccessMutation } from '../access/index.js';
+import { accessMdPathForFolder } from '../access/index.js';
+import { pluginPrincipalKey } from '../access-model/index.js';
+import type { Principal } from '../access-model/index.js';
+import { WorkspaceMutex } from '../kb-fs/index.js';
+import type { ISkillService } from '../skills/index.js';
 import { logger } from '../../shared/logging.js';
 import type { ProvisionCommitDriver } from './plugin-provision.service.js';
 import type { PluginLinkIndex } from './plugin-links.js';
@@ -119,12 +119,13 @@ export class PluginLinkError extends Error {
  */
 export class PluginLinksService {
   private readonly locks = new WorkspaceMutex();
-  private readonly mutation: AccessMutationService;
 
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly commits: ProvisionCommitDriver,
     private readonly accessControl: IAccessControl,
+    /** Grants and revokes the links' tokens; the composition root owns the implementation. */
+    private readonly mutation: IAccessMutation,
     private readonly skillService: ISkillService,
     private readonly links: PluginLinkIndex,
     private readonly kb: KbContext,
@@ -132,9 +133,7 @@ export class PluginLinksService {
       emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void;
     },
     private readonly onChanged?: () => void,
-  ) {
-    this.mutation = new AccessMutationService(workspaceService, accessControl, kb.kbDirName);
-  }
+  ) {}
 
   private get kbDirName(): string {
     return this.kb.kbDirName;

package/src/modules/plugins/plugin-links.ts

@@ -3,12 +3,12 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
 import { pluginManifestName, skillUnderRoot } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { ISkillService } from '../skills/skills.contract.js';
+import type { IAccessControl } from '../access/index.js';
+import type { ISkillService } from '../skills/index.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
-import { canonicalRoleName, pluginPrincipalKey } from '../access-model/access-grammar.js';
+import { canonicalRoleName, pluginPrincipalKey } from '../access-model/index.js';
 import type { PluginMembership } from './plugins.contract.js';
 import type { PluginSource } from './discovery/plugin-source.js';
 

package/src/modules/plugins/plugin-provision.service.ts

@@ -51,11 +51,10 @@ import {
   type AuthUser,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { creatorPrincipal } from '../access-model/creator.js';
-import { spliceGrant } from '../access-model/access-splice.js';
-import { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { WorkspaceService } from '../workspace/index.js';
+import type { IAccessControl } from '../access/index.js';
+import { creatorPrincipal, spliceGrant } from '../access-model/index.js';
+import { WorkspaceMutex } from '../kb-fs/index.js';
 
 /** Commit machinery the provision rides — the pending-commit pipeline, run inline. */
 export interface ProvisionCommitDriver {

package/src/modules/plugins/plugin-rename.service.ts

@@ -10,14 +10,14 @@ import {
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import type { ITreeWalker, WalkListener } from '../../shared/fs.contract.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import {
   PLUGIN_TOKEN_PREFIX,
   canonicalPluginToken,
   hasAccessFrontmatterExtension,
   parsePluginPrincipalKey,
-} from '../access-model/access-grammar.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+} from '../access-model/index.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { PluginSource } from './discovery/plugin-source.js';
 

package/src/modules/plugins/plugins.contract.ts

@@ -33,7 +33,7 @@
  * change requests; only the UI dresses them up.
  */
 
-export type { PluginMembership } from '../skills/skills.contract.js';
+export type { PluginMembership } from '../skills/index.js';
 
 /** Access-rule principals as the resolver hands them back. */
 export interface ResolvedPrincipals {

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

@@ -2,7 +2,7 @@ import express from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
-import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../auth/index.js'; // Express Request.userId / userEmail augmentation
 import {
   joinBranchFor,
   type AuthUser,
@@ -10,17 +10,17 @@ import {
   type ChangeRequestState,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { pluginFolderBelowRoot } from './plugins.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
-import { argumentsRefusal } from '../tool-helpers/route-argument-check.js';
+import { argumentsRefusal } from '../tool-helpers/index.js';
 import { PluginLinkError, type PluginLinksService } from './plugin-links.service.js';
 import { PluginRenameError, type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
-import { folderTarget } from '../access/access-requests.contract.js';
+import { folderTarget } from '../access/index.js';
 import type { PluginJoinRequestJobs } from './join-request-jobs.service.js';
 import type { JoinRequestRecord } from './join-request-records.store.js';
 import type {

package/src/modules/plugins/plugins.service.ts

@@ -3,13 +3,13 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
 import path from 'node:path';
-import { isPrivateAccessMd } from '../access-model/access-grammar.js';
+import { isPrivateAccessMd } from '../access-model/index.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { ISkillService } from '../skills/skills.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { IAccessControl } from '../access/index.js';
+import type { ISkillService } from '../skills/index.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
 import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
 import type { PluginLinkIndex } from './plugin-links.js';

package/src/modules/plugins/plugins.tools.ts

@@ -1,7 +1,7 @@
 import { resolveKbLayout, type KbLayout } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
+import { toolDef } from '../tool-helpers/index.js';
 
 /**
  * The two plugin tools an agent has, both surfaces — DESCRIPTIONS of the
@@ -112,7 +112,7 @@ export function myPluginDef(layout: KbLayout): UtcpTool {
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: PROVISIONED_OUTPUT,
     // `write`: both make folders and commit — a read-scoped caller's manual
-    // must not advertise them (see `isWriteTool` in the manual routes).
+    // must not advertise them (see `declaresWrite` in `tool.contract.ts`).
     tags: ['plugins', 'skills', 'write'],
   });
 }
@@ -143,6 +143,6 @@ export const CREATE_PLUGIN: UtcpTool = toolDef({
   },
   outputs: PROVISIONED_OUTPUT,
   // `write`: both make folders and commit — a read-scoped caller's manual
-  // must not advertise them (see `isWriteTool` in the manual routes).
+  // must not advertise them (see `declaresWrite` in `tool.contract.ts`).
   tags: ['plugins', 'skills', 'write'],
 });

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

@@ -8,10 +8,10 @@ import {
   pluginOfPath,
   type KbLayout,
 } from '@bevel-software/platform-shared';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { ISkillService } from '../skills/skills.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { ISkillService } from '../skills/index.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
 import type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract.js';
 
 /**

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -3,8 +3,8 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('vault');
 import { and, desc, eq, inArray, isNull, like, or } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { secrets } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { secrets } from '../database/index.js';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import {

package/src/modules/secrets-vault/index.ts

@@ -26,3 +26,5 @@ export {
   BEVEL_SECRETS_LOADER_TYPE,
   DEFAULT_SECRETS_SCOPE,
 } from './secrets-variable-loader.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { scopesCovered } from './secrets-vault.contract.js';

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -12,12 +12,12 @@ import {
   configuredAs,
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
-import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/tool-manuals.contract.js';
-import type { IConnectionProbeService } from '../connection-probe/connection-probe.contract.js';
+import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/index.js';
+import type { IConnectionProbeService } from '../connection-probe/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
+import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface SecretsVaultRoutesDeps {
   secretsVault: ISecretsVaultService;

package/src/modules/settings/__tests__/deployment-settings.service.test.ts

@@ -8,8 +8,11 @@ import {
   CORE_SETTINGS,
   LEGACY_LAYOUT_ENV_VARS,
   retireMergedBranchesOn,
+  parseToolReadOnlyOverrides,
 } from '../deployment-settings.service.js';
 import type { Database } from '../../database/connection.js';
+import { ToolReadOnlyHints, ToolRegistry } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
 
 const ENC_KEY = randomBytes(32).toString('base64');
 
@@ -22,7 +25,16 @@ const ENC_KEY = randomBytes(32).toString('base64');
 function makeDb() {
   const rows: { key: string; value: string; encrypted: boolean }[] = [];
   const db = {
-    select: () => ({ from: () => Promise.resolve(rows.map((r) => ({ ...r }))) }),
+    // `select … from` is every row; `… where key = ?` (a `reload`) is that key's.
+    select: () => ({
+      from: () =>
+        Object.assign(Promise.resolve(rows.map((r) => ({ ...r }))), {
+          where: (predicate: unknown) => {
+            const [key] = boundParams(predicate);
+            return Promise.resolve(rows.filter((r) => r.key === key).map((r) => ({ ...r })));
+          },
+        }),
+    }),
     insert: () => ({
       values: (v: { key: string; value: string; encrypted: boolean }) => ({
         onConflictDoUpdate: () => {
@@ -677,3 +689,78 @@ describe('DeploymentSettingsService — recordIfAbsent', () => {
     expect(settings.resolve('starterPackClaim')).toBe('');
   });
 });
+
+describe('DeploymentSettingsService — the read-only overrides', () => {
+  /** A registry with one reader and one writer, as the Tools page would show them. */
+  function registry(): ToolRegistry {
+    const r = new ToolRegistry();
+    const inputs = { type: 'object', properties: {} } as const;
+    r.registerExternalTool(toolDef({ name: 'read_file', description: 'r', path: '/api/agent/tools/read_file', inputs }));
+    r.registerExternalTool(
+      toolDef({ name: 'write_file', description: 'w', path: '/api/agent/tools/write_file', inputs, tags: ['write'] }),
+    );
+    return r;
+  }
+
+  it('survives a restart: a new process over the same table reads the override back', async () => {
+    const { db, rows } = makeDb();
+    const before = new DeploymentSettingsService(db, ENC_KEY);
+    await before.load();
+    await new ToolReadOnlyHints(registry(), before).set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    expect(rows.find((r) => r.key === 'toolReadOnlyOverrides')?.value).toBe('{"write_file":true}');
+
+    const after = new DeploymentSettingsService(db, ENC_KEY);
+    await after.load();
+    const hints = new ToolReadOnlyHints(registry(), after);
+    expect((await hints.describe()).find((e) => e.name === 'write_file')).toMatchObject({ override: true, readOnly: true });
+
+    // And the reset removes the row, every tool back on its built-in value.
+    await hints.set('write_file', null, '00000000-0000-4000-8000-00000000000a');
+    expect(rows.find((r) => r.key === 'toolReadOnlyOverrides')).toBeUndefined();
+  });
+
+  it('is read per use, so a change written by another replica is in the next answer', async () => {
+    const { db } = makeDb();
+    const one = new DeploymentSettingsService(db, ENC_KEY);
+    const two = new DeploymentSettingsService(db, ENC_KEY);
+    await one.load();
+    await two.load();
+    await new ToolReadOnlyHints(registry(), one).set('read_file', false, null);
+    expect(await new ToolReadOnlyHints(registry(), two).overrides()).toEqual({ read_file: false });
+  });
+
+  it('is not a field of the setup screen: a save naming it is refused, and the screen is not told of it', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.load();
+    await expect(settings.save({ toolReadOnlyOverrides: '{"write_file":true}' }, null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+    expect(rows).toEqual([]);
+    expect(settings.describe().some((s) => s.key === 'toolReadOnlyOverrides')).toBe(false);
+  });
+
+  it('refuses a stored value that is not a map of tool names to booleans', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.load();
+    await expect(settings.recordIfAbsent('toolReadOnlyOverrides', '{"write_file":"yes"}', null)).rejects.toBeInstanceOf(
+      SettingsValidationError,
+    );
+  });
+});
+
+describe('the read-only overrides setting holds only a map of tool names to booleans', () => {
+  it('accepts a map, and blank as no override', () => {
+    expect(parseToolReadOnlyOverrides('{"read_file":false,"call_tool_chain":true}')).toEqual({
+      read_file: false,
+      call_tool_chain: true,
+    });
+    expect(parseToolReadOnlyOverrides('')).toEqual({});
+    expect(Object.hasOwn(parseToolReadOnlyOverrides('{"__proto__":true}')!, '__proto__')).toBe(true);
+  });
+
+  it.each(['[]', 'true', '{"read_file":"false"}', '{"bad name":true}', 'not json'])('refuses %s', (raw) => {
+    expect(parseToolReadOnlyOverrides(raw)).toBeNull();
+  });
+});

package/src/modules/settings/connection-check.ts

@@ -6,7 +6,7 @@ import { validateHttpsRemote } from './deployment-settings.service.js';
 import { classifyGitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 
 /** The repository connection a deployment reads and writes its knowledge base with. */
 export interface RepositoryConnection {

package/src/modules/settings/deployment-settings.service.ts

@@ -2,8 +2,8 @@ import { and, eq, inArray } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('settings');
-import type { Database } from '../database/connection.js';
-import { deploymentSettings } from '../database/core-schema.js';
+import type { Database } from '../database/index.js';
+import { deploymentSettings } from '../database/index.js';
 import {
   DEFAULT_KB_LAYOUT,
   type KbLayout,
@@ -13,8 +13,8 @@ import {
 } from '@bevel-software/platform-shared';
 import { createHmac } from 'node:crypto';
 import { TokenCrypto } from '../../shared/token-crypto.js';
-import { assertKbDirNameFree, hasControlCharacter } from '../kb-fs/repo-path.js';
-import { parseRetentionWindow } from '../audit/audit.contract.js';
+import { assertKbDirNameFree, hasControlCharacter } from '../kb-fs/index.js';
+import { parseRetentionWindow } from '../audit/index.js';
 import { normalizeIssuerUrl } from './oidc-check.js';
 import { GIT_MODES, isGitMode } from './repository-source.js';
 
@@ -119,6 +119,29 @@ export function retireMergedBranchesOn(raw: string): boolean {
   return !/^(false|0|off|no)$/i.test(raw.trim());
 }
 
+/**
+ * The `toolReadOnlyOverrides` setting read as a map, or null when it is not
+ * one: a JSON object whose keys are tool names (MCP's name grammar) and whose
+ * values are booleans. Blank is no override at all.
+ */
+export function parseToolReadOnlyOverrides(raw: string): Record<string, boolean> | null {
+  if (!raw.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const entries = Object.entries(parsed as Record<string, unknown>);
+  for (const [name, value] of entries) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(name) || typeof value !== 'boolean') return null;
+  }
+  // Built with `fromEntries`, which defines own properties: assigning into a
+  // plain object would send a valid name like `__proto__` to its prototype.
+  return Object.fromEntries(entries) as Record<string, boolean>;
+}
+
 export const CORE_SETTINGS: SettingDef[] = [
   {
     /**
@@ -400,6 +423,23 @@ export const CORE_SETTINGS: SettingDef[] = [
       parseRetentionWindow(v) === null ? 'Enter a whole number of days, or 0 to keep events forever.' : null,
   },
 
+  {
+    /**
+     * The read-only hints an admin set on the Tools page, overriding a
+     * platform tool's or a code-mode meta-tool's built-in one: a JSON map from
+     * tool name to `true`/`false`. Written by the Tools page's admin route
+     * alone (see `modules/tool-registry/read-only-hints.ts`), which also judges
+     * the NAMES against the catalog; here only the shape is. Internal: not a
+     * field of the setup screen. A blank clears it, which is every tool back
+     * on its built-in value.
+     */
+    key: 'toolReadOnlyOverrides',
+    section: 'knowledge-base',
+    internal: true,
+    blankMeansDefault: true,
+    validate: (v) => (parseToolReadOnlyOverrides(v) === null ? 'A map from tool name to true or false.' : null),
+  },
+
   {
     /**
      * Which starter pack the first admin chose for a new knowledge base — a

package/src/modules/settings/git-root-folders.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { IGitRunner } from '../../shared/git.contract.js';
 import { printable } from '../../shared/printable.js';
 import { logger } from '../../shared/logging.js';
-import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../workflow/index.js';
 import { probeCredentialArgs, probeGitEnv } from './connection-check.js';
 
 const log = logger('setup');

package/src/modules/settings/index.ts

@@ -0,0 +1,12 @@
+/**
+ * What the settings module offers the other modules: the deployment settings
+ * service as a contract for a route that reads or writes a setting, the
+ * parsers of the settings whose stored text another module interprets (the
+ * tool read-only overrides), and the shapes of the repository source a git
+ * integration configures itself from. The service is wired by the
+ * composition root.
+ */
+export type { DeploymentSettingsService, ResolvedSetting, SettingSource } from './deployment-settings.service.js';
+export { parseToolReadOnlyOverrides } from './deployment-settings.service.js';
+export { normalizeIssuerUrl } from './oidc-check.js';
+export type { GitHubAppRepository, SettingReader } from './repository-source.js';