@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/skills/skills.tools.ts

@@ -1,11 +1,25 @@
 import type { Router, RequestHandler } from 'express';
 import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import { ToolError, type ToolContext } from '../tool-helpers/tool.contract.js';
 import { toolDef } from '../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { ISkillService } from './skills.contract.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
 
+/**
+ * The optional `branch` both skill tools declare. Optional on purpose, unlike
+ * the required `branch` of the KB file tools: a skill read is answered by the
+ * released catalog by default, and naming a branch is the caller asking for
+ * something nobody has approved yet.
+ */
+const BRANCH_SKILLS_INPUT = {
+  type: 'string' as const,
+  description:
+    'Optional: a draft branch to read the skills from instead of the released (default) branch — ' +
+    'the branch you are working on. You must be able to read the branch and the skill on it; ' +
+    'a branch that does not exist answers 404 naming it. Omit it for the approved skills.',
+};
+
 /**
  * Registers the two skill tools (both surfaces) and hosts their endpoints.
  *
@@ -14,6 +28,13 @@ import type { IAllowedToolsChecker } from './allowed-tools-check.js';
  * what exists right in the tool catalog, no `list_skills` round-trip needed, and
  * it auto-updates as the default-branch catalog changes. The hosted routes are
  * static; only the description text is dynamic.
+ *
+ * Both tools take an optional `branch`. Without it they answer from the
+ * released (default-branch) catalog — what the descriptions name, what the
+ * browser menu lists and what the MCP prompt surface serves. With it they read
+ * the skills as they are on that draft and say which of them nobody has
+ * approved, so an agent can try the skill it just wrote without waiting for a
+ * merge.
  */
 export function registerSkillsTools(
   registry: IToolRegistry,
@@ -32,8 +53,8 @@ export function registerSkillsTools(
   router.post(
     '/agent/tools/list_skills',
     toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => ({
-      skills: await skillService.listSkills(ctx.user.email),
+    toolHandler(async (args, ctx: ToolContext) => ({
+      skills: await skillService.listSkills(ctx.user.email, { branch: branchArg(args) }),
     })),
   );
 
@@ -44,14 +65,38 @@ export function registerSkillsTools(
       const name = typeof args.name === 'string' ? args.name : '';
       const file = typeof args.file === 'string' ? args.file : undefined;
       const version = typeof args.version === 'string' ? args.version : undefined;
+      const branch = branchArg(args);
       if (!name) return { error: 'missing_name' };
-      const result = await skillService.getSkill(ctx.user.email, name, file, { version });
+      // Refused rather than ranked: a `version` is a point in the released
+      // skill's history, a `branch` is a draft nobody has released — asked for
+      // together, neither answer is the one the caller meant, and guessing
+      // would serve instructions under a label that does not describe them.
+      if (branch !== undefined && version !== undefined && version.trim().length > 0) {
+        throw new ToolError(
+          'get_skill takes `branch` or `version`, not both: `branch` loads the skill as that draft has it ' +
+            'now, `version` loads a version the released skill declared. Pass one of them.',
+          400,
+        );
+      }
+      const result = await skillService.getSkill(ctx.user.email, name, file, { version, branch });
       if (!allowedTools || !result.ok || result.kind !== 'skill') return result;
       return { ...result, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
     }),
   );
 }
 
+/**
+ * The `branch` a tool call named, or undefined when it named none (the
+ * released catalog). A non-string or blank value is NOT a branch: it is taken
+ * as absent, which answers from the default branch — the approved one. The
+ * resolution of a real name, and the 404 for one the platform never heard of,
+ * belong to the workspace layer, exactly as on the file tools.
+ */
+function branchArg(args: Record<string, unknown>): string | undefined {
+  const branch = args.branch;
+  return typeof branch === 'string' && branch.trim().length > 0 ? branch : undefined;
+}
+
 /** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
 async function availableSkillsLine(skillService: ISkillService, userEmail?: string): Promise<string> {
   const skills = await skillService.listSkills(userEmail);
@@ -67,9 +112,16 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
       'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
       'top-level `version`, else `lifecycle.version`). ' +
       'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
+      'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
+      'what you need to try a skill you just wrote there; each skill that differs from the released ' +
+      'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ' +
       (await availableSkillsLine(skillService, userEmail)),
     path: '/api/agent/tools/list_skills',
-    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    inputs: {
+      type: 'object',
+      properties: { branch: BRANCH_SKILLS_INPUT },
+      additionalProperties: false,
+    },
     outputs: {
       type: 'object',
       properties: {
@@ -88,6 +140,13 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
                   'else `lifecycle.version` in its SKILL.md); absent when it declares none.',
               },
               path: { type: 'string' },
+              unmerged: {
+                type: 'boolean',
+                description:
+                  'Only when `branch` was passed, and only on a skill that differs from the released one ' +
+                  '(it exists only on that branch, or was changed there): nobody has approved what it says.',
+              },
+              branch: { type: 'string', description: 'With `unmerged`: the branch the skill was read from.' },
             },
           },
         },
@@ -104,7 +163,7 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
       'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
       'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
       '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
-      'one the skill declared. ' +
+      'one the skill declared, or `branch` names a draft to load it from. ' +
       (await availableSkillsLine(skillService, userEmail)),
     path: '/api/agent/tools/get_skill',
     inputs: {
@@ -126,6 +185,7 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
             'recent commit that declared that version; a version the skill never declared answers ' +
             '`version_not_found` with the versions it did declare.',
         },
+        branch: BRANCH_SKILLS_INPUT,
       },
       required: ['name'],
       additionalProperties: false,
@@ -134,8 +194,20 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
       type: 'object',
       description: 'On success carries `skill` (or `file` when `file` was passed); on failure carries `error`.',
       properties: {
-        skill: { type: 'object', description: 'The loaded skill: name, description, body, files, ….' },
-        file: { type: 'object', description: 'A bundled file: name, file, path, content.' },
+        skill: {
+          type: 'object',
+          description:
+            'The loaded skill: name, description, body, files, …. Read from a `branch` that changed it, ' +
+            'it also carries `unmerged: true` and that branch, and its `body` BEGINS with one line ' +
+            'saying the skill comes from that unmerged branch and is not approved — treat it as a ' +
+            'proposal you are testing, not as approved instructions.',
+        },
+        file: {
+          type: 'object',
+          description:
+            'A bundled file: name, file, path, content — plus `unmerged` and `branch` when it came off ' +
+            'a branch that changed the skill (the note stays beside the content, never inside it).',
+        },
         warnings: {
           type: 'array',
           description:

package/src/modules/tool-auth/__tests__/manual-auth.middleware.test.ts

@@ -8,6 +8,7 @@ import { InternalTokenService } from '../internal-token.service.js';
 import { createManualAuthMiddleware } from '../tool-auth.middleware.js';
 import type { IExternalApiKeyService } from '../external-api-key.interface.js';
 import type { AuthService } from '../../auth/auth.service.js';
+import { AuthBackendError } from '../../auth/account-admission.js';
 
 /**
  * The manual endpoints (`/agent/utcp`, `/agent/internal/utcp`) accept a browser
@@ -17,6 +18,8 @@ import type { AuthService } from '../../auth/auth.service.js';
  */
 const KEY = 'bevel_validkey';
 const JWT = 'browser-jwt';
+/** A valid session, presented while its account cannot be looked up. */
+const JWT_DURING_OUTAGE = 'browser-jwt-during-outage';
 
 const fakeExternalApiKeys = {
   looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
@@ -25,10 +28,12 @@ const fakeExternalApiKeys = {
 } as unknown as IExternalApiKeyService;
 
 const fakeAuth = {
-  verifyToken: (t: string) => {
+  resolveSession: async (t: string) => {
     if (t === JWT) return { userId: 'u-jwt', email: 'jwt@x' };
+    if (t === JWT_DURING_OUTAGE) throw new AuthBackendError(new Error('the database is down'));
     throw new Error('bad jwt');
   },
+  isActive: async () => true,
 } as unknown as AuthService;
 
 let server: HttpServer | undefined;
@@ -75,6 +80,14 @@ describe('createManualAuthMiddleware (read-only manual endpoints)', () => {
     expect((await get(base, '/api/agent/utcp', 'garbage')).status).toBe(401);
   });
 
+  it('answers 500, not 401, when the session’s account cannot be looked up', async () => {
+    const { base } = await start();
+    const r = await get(base, '/api/agent/utcp', JWT_DURING_OUTAGE);
+    // A 401 would sign a valid caller out over an outage.
+    expect(r.status).toBe(500);
+    expect(r.headers.get('www-authenticate')).toBeNull();
+  });
+
   it('refuses the INTERNAL manual to a browser JWT (403) but allows an internal token', async () => {
     const { base, intToken } = await start();
     expect((await get(base, '/api/agent/internal/utcp', JWT)).status).toBe(403);

package/src/modules/tool-auth/external-api-key.service.ts

@@ -108,7 +108,9 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // Join users so a single round-trip resolves both "token is valid" and
     // "load the user it belongs to". The unique index on token_hash makes
     // this a point-lookup. `isNull(revokedAt)` is what enforces revocation
-    // — the row remains for audit.
+    // — the row remains for audit — and `isNull(deactivatedAt)` is what
+    // stops a switched-off account's keys without revoking them, so
+    // switching it back on restores them.
     const [row] = await this.db
       .select({
         tokenId: externalApiKeys.id,
@@ -119,7 +121,7 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       })
       .from(externalApiKeys)
       .innerJoin(users, eq(externalApiKeys.userId, users.id))
-      .where(and(eq(externalApiKeys.tokenHash, tokenHash), isNull(externalApiKeys.revokedAt)))
+      .where(and(eq(externalApiKeys.tokenHash, tokenHash), isNull(externalApiKeys.revokedAt), isNull(users.deactivatedAt)))
       .limit(1);
 
     if (!row) return null;

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

@@ -12,9 +12,9 @@ export interface InternalTokenClaim {
   /**
    * The agent run / conversation id (the Mastra thread id) this token is scoped
    * to, when minted per-run. Surfaced as `ToolContext.sessionId` so the
-   * ontology-session boundary can scope to one run for the in-process agent
-   * (the external/MCP path carries `sessionId` on the tool body instead).
-   * Absent for identity-only tokens.
+   * agent-access hooks can tell the in-process agent's run apart (the
+   * external/MCP path carries `sessionId` on the tool body instead). Absent
+   * for identity-only tokens.
    */
   sessionId?: string;
   /**

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

@@ -4,6 +4,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('tools');
 import type { IExternalApiKeyService } from './external-api-key.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AuthBackendError } from '../auth/account-admission.js';
 import { InternalTokenService } from './internal-token.service.js';
 import { INVALID_CONNECTION_KEY_CHALLENGE, INVALID_CONNECTION_KEY_MESSAGE } from './connection-key-rejection.js';
 
@@ -79,10 +80,10 @@ export const requireInternalSource: RequestHandler = (req, res, next) => {
 
 /**
  * Mirror of `requireInternalSource` for surfaces that must admit ONLY external
- * callers. `start_session` mints a fresh chat thread as the caller's
- * ontology-session id; an internal (in-process agent) token already carries
- * its run's `sessionId`, so letting it mint a new thread mid-run would
- * silently reset the one-ontology-per-conversation boundary.
+ * callers. `start_session` mints a fresh chat thread as the caller's session
+ * id; an internal (in-process agent) token already carries its run's
+ * `sessionId`, so letting it mint a new thread mid-run would silently split
+ * one conversation in two.
  *
  * "External" is decided by the VERIFIER, not by which credential shape
  * authenticated: a `bevel_…` connection key resolves external, and so does an
@@ -122,6 +123,15 @@ export type VerifyResult =
 export function createTokenVerifier(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
+  /**
+   * Whether the account an internal token was minted for is still on. An
+   * internal token carries only a user id and lives up to an hour (longer
+   * for the MCP loopback), so without this a switched-off account's running
+   * agent would keep working until it expired. Connection keys need no
+   * second look: their lookup reads the account. Every deployment passes
+   * it; absent, internal tokens are judged on their signature alone.
+   */
+  accounts?: Pick<AuthService, 'isActive'>,
 ): (token: string | undefined) => Promise<VerifyResult> {
   const missing = { ok: false as const, status: 401, message: 'A connection key or internal token is required' };
   return async (token) => {
@@ -136,6 +146,9 @@ export function createTokenVerifier(
     if (internalTokenService.looksLikeInternalToken(token)) {
       const claim = internalTokenService.verify(token);
       if (!claim) return { ok: false, status: 401, message: 'Invalid or expired internal token' };
+      if (accounts && !(await accounts.isActive(claim.userId))) {
+        return { ok: false, status: 401, message: ACCOUNT_DEACTIVATED_MESSAGE };
+      }
       return claim.externalProxy
         ? {
             ok: true,
@@ -170,8 +183,9 @@ export function createTokenVerifier(
 export function createToolAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
+  accounts?: Pick<AuthService, 'isActive'>,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, accounts);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -210,9 +224,9 @@ export function createToolAuthMiddleware(
 export function createManualAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   internalTokenService: InternalTokenService,
-  authService: AuthService,
+  authService: Pick<AuthService, 'isActive' | 'resolveSession'>,
 ): RequestHandler {
-  const verify = createTokenVerifier(externalApiKeyService, internalTokenService);
+  const verify = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
   return async (req: Request, res: Response, next: NextFunction) => {
     const header = req.headers.authorization;
     if (!header || !header.toLowerCase().startsWith('bearer ')) {
@@ -241,13 +255,22 @@ export function createManualAuthMiddleware(
     }
 
     // Otherwise treat the bearer as a browser session JWT.
+    let userId: string;
     try {
-      const { userId } = authService.verifyToken(token);
-      req.toolAuth = { source: 'session', userId, scope: 'write' };
-      next();
-    } catch {
+      ({ userId } = await authService.resolveSession(token));
+    } catch (err) {
+      // The account could not be looked up: an outage, not a verdict on the
+      // session, and a 401 would sign a valid caller out over it.
+      if (err instanceof AuthBackendError) {
+        log.error('session account lookup failed:', { err: err.cause });
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
       res.setHeader('WWW-Authenticate', WWW_AUTH);
       res.status(401).json({ error: 'Invalid or expired token' });
+      return;
     }
+    req.toolAuth = { source: 'session', userId, scope: 'write' };
+    next();
   };
 }

package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts

@@ -12,6 +12,7 @@ import { createToolHandlerFactory } from '../tool-handler.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
@@ -68,13 +69,14 @@ async function start(): Promise<string> {
     canOwner: async () => true,
     canWriteBatchAtRef: async () => null,
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+    // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
+    previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
   } as never;
   registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache), allowAll, testKbContext({ kbDirName: KB }), {
-    service: {} as never,
-    enabled: false, // ontology boundary not under test here
-    kb: testKbContext({ kbDirName: KB }),
+    // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
+    notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never);
   const app = express();
   app.use(express.json());

package/src/modules/tool-helpers/__tests__/phase4-tools.test.ts

@@ -10,6 +10,7 @@ import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -65,11 +66,10 @@ async function start(): Promise<string> {
   // and their web_search / submit_feedback / cite_kb_node cases — moved to
   // the enterprise repo with their modules; core registers only core tools.
   registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), new DocExtractService('/tmp/bevel-test-doc-extract'), accessControl, testKbContext(), {
-    service: {} as never,
-    enabled: false, // ontology boundary not under test here
-    kb: testKbContext(),
+    // No hook registered: the agent-access gate refuses nothing here.
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
+    notes: new ToolDescriptionNotes(),
   }, new RoutineWritePolicyService(), {} as never /* sessionSink — start_session not exercised here */);
   router.use(createManualRoutes(registry, toolAuth));
 

package/src/modules/tool-helpers/__tests__/validate-token.test.ts

@@ -18,7 +18,11 @@ const externalApiKeyService = {
   verifyAndLoadToken: async (t: string) =>
     t === 'bevel_ok' ? { user: { id: 'u-ext', email: 'e@x', name: 'Ext' }, tokenId: 'tk-1' } : null,
 } as never;
-const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+// Every account is on except `u-off`, which an admin switched off.
+const authService = {
+  getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }),
+  isActive: async (id: string) => id !== 'u-off',
+} as never;
 
 let tempDir = '';
 const workspaceService = {
@@ -66,6 +70,12 @@ describe('validateToken (tool-author SDK entry)', () => {
     expect((await fs.readFile('a.md')).toString()).toBe('hi');
   });
 
+  it('throws a 401 ToolError for a valid internal token whose account was switched off', async () => {
+    const err = await validateToken(internalToken.mint({ userId: 'u-off' })).catch((e) => e);
+    expect(hasHttpStatus(err) && err.status).toBe(401);
+    expect((err as Error).message).toContain('switched off');
+  });
+
   it('throws a 401 ToolError on a bad token and an empty token', async () => {
     for (const bad of ['garbage', 'bevel_nope', '', undefined]) {
       const err = await validateToken(bad as string).catch((e) => e);

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

@@ -12,6 +12,7 @@ import type { ICreatorAccess } from '../access-model/creator.js';
 import type { GroupsIndex } from '../access-model/group-files.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { isAbsence } from '../../shared/fs.contract.js';
+import { assertBranchProvided } from '../../shared/domain-errors.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import type { AuthService } from '../auth/auth.service.js';
@@ -77,6 +78,20 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
     const { loadActiveGroups } = deps;
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
+      // THE choke point: every knowledge-base tool resolves its workspace
+      // through here, and a `call_tool_chain` call reaches the very same route
+      // over loopback — so refusing a branch-less call here refuses it on both
+      // paths at once, with no per-tool guard to keep in step.
+      //
+      // Before ANY workspace work, because both things downstream do with this
+      // value are wrong when it is absent: `getOrCreateForUser` defaults a
+      // missing branch to the deployment's default (protected) branch, so an
+      // omitted argument would silently act on `main`; and a present-but-absent
+      // value like the string "undefined" goes to `workspaceIdForBranch`, which
+      // makes it a workspace directory of that name and then tries to clone a
+      // branch nobody ever pushed. Failing closed here means no workspace is
+      // created and no clone is attempted.
+      assertBranchProvided(branch);
       const cached = fsCache.get(branch);
       if (cached) return cached;
       const ws = await deps.workspaceService.getOrCreateForUser(user, branch);

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

@@ -6,6 +6,7 @@ import { hasHttpStatus, ToolError, type ToolHandler } from './tool.contract.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
+import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool, type IWriteAccess } from '../write-access/write-access.js';
 import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
 
 function isAsyncIterable(v: unknown): v is AsyncIterable<unknown> {
@@ -29,7 +30,7 @@ export interface ToolHandlerOptions {
  * The handler receives `req.body` as the flat args (UTCP's `body_field` already
  * delivered the inner body as the request body).
  */
-export function createToolHandlerFactory(resolve: ResolveToolContext) {
+export function createToolHandlerFactory(resolve: ResolveToolContext, writeAccess: IWriteAccess = alwaysWritable) {
   return function toolHandler(handler: ToolHandler, opts: ToolHandlerOptions = {}) {
     return async (req: Request, res: Response): Promise<void> => {
       const auth = req.toolAuth;
@@ -41,10 +42,29 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
         res.status(403).json({ error: 'This tool requires write access.' });
         return;
       }
+      // Before anything is awaited: a client that goes away during the
+      // write-access check below must still abort the call.
+      //
+      // Asked of the RESPONSE. The request closes as soon as its body has
+      // been read, with the client still there and waiting, so its `close`
+      // says nothing about the client; the response closes when it has been
+      // sent or the connection is gone, and `writableEnded` tells the two
+      // apart.
       const abort = new AbortController();
-      req.on('close', () => {
+      res.on('close', () => {
         if (!res.writableEnded) abort.abort();
       });
+      // The tool layer's half of the read-only gate: the HTTP gate lets every
+      // tool call through, since only here is a write tool told from a read.
+      if (opts.write) {
+        const refusal = await refuseWriteTool(writeAccess);
+        if (refusal !== null) {
+          res.status(403).json({ error: refusal, code: READ_ONLY_CODE });
+          return;
+        }
+        // The client left while the verdict was awaited: nobody to answer.
+        if (abort.signal.aborted) return;
+      }
       const body: unknown = req.body;
       if (body !== undefined && body !== null && (typeof body !== 'object' || Array.isArray(body))) {
         res.status(400).json({ error: 'Request body must be a JSON object.' });
@@ -53,8 +73,8 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
       const args = (body ?? {}) as Record<string, unknown>;
       // `sessionId` rides the tool body like `branch` does: the external MCP
       // proxy injects it (ask-tool continuity convention) and the in-process
-      // agent passes its thread id. Surfaced on the context so the ontology
-      // gate can scope to one run without each handler re-reading args.
+      // agent passes its thread id. Surfaced on the context so the
+      // agent-access gate can name the run without each handler re-reading args.
       const sessionId = typeof args.sessionId === 'string' && args.sessionId.length > 0
         ? args.sessionId
         : undefined;

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

@@ -34,8 +34,9 @@ export interface ToolContext {
    * The agent run / conversation id this call belongs to (the agent thread id).
    * Supplied as a `sessionId` field on the tool's input body — the external MCP
    * proxy injects it via the `ask`-tool continuity convention, and the
-   * in-process agent passes its thread id. Used to scope the ontology-session
-   * boundary to one run. Absent for non-agent or unthreaded calls.
+   * in-process agent passes its thread id. Handed to the agent-access hooks,
+   * which is how a deployment scopes a rule to one conversation. Absent for
+   * non-agent or unthreaded calls.
    */
   sessionId?: string;
   /**

package/src/modules/tool-helpers/validate-token.ts

@@ -35,7 +35,7 @@ export type ValidateToken = (
 ) => Promise<ToolContext>;
 
 export function createToolValidator(deps: ToolValidatorDeps): ValidateToken {
-  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService);
+  const verify = createTokenVerifier(deps.externalApiKeyService, deps.internalTokenService, deps.authService);
   const resolve = createToolContextResolver(deps);
   return async (token, signal) => {
     let result;

package/src/modules/workflow/__tests__/apply-failure.test.ts

@@ -582,7 +582,7 @@ describe('WorkflowService — a refusal clears when a change makes it obsolete',
     const { svc } = service(
       store.db,
       (e) => emitted.push(e as { kind: string }),
-      {},
+      { carryApprovalsForward: vi.fn(async () => 0) },
       {
         git: {
           pull: vi.fn(async () => ({ treeChanged: false })),
@@ -591,6 +591,14 @@ describe('WorkflowService — a refusal clears when a change makes it obsolete',
             return { kind: 'merged', alreadyUpToDate: false };
           }),
           push: vi.fn(async () => undefined),
+          hasUnpushedCommits: vi.fn(async () => true),
+          pathsChangedBetween: vi.fn(async () => []),
+          // The head this test is named for: one sha before the merge,
+          // another after it.
+          resolvePrShas: vi
+            .fn()
+            .mockResolvedValueOnce({ baseSha: 'b'.repeat(40), headSha: 'a'.repeat(40) })
+            .mockResolvedValue({ baseSha: 'b'.repeat(40), headSha: 'd'.repeat(40) }),
         } as unknown as Partial<GitService>,
         prs: {
           getPrDetail: vi.fn(async () => ({ state: 'open', branch: 'bo/suggestions', base: 'main', viewerCanUpdate: true })),