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

package/src/modules/tool-manuals/tool-manuals.routes.ts

@@ -19,6 +19,7 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 import '../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 import '../tool-auth/index.js'; // Express Request augmentation (req.toolAuth)
 import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { NOT_AVAILABLE_TO_CONNECTION, resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 
 /** Resolve a connection-key/internal-token user id to its email (per-caller ACL). */
 export type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
@@ -64,6 +65,11 @@ export function createToolManualsAgentRoutes(
      */
     pluginIndex?: Pick<IPluginIndexService, 'catalog'>;
   },
+  /**
+   * Resolves the scope of a connection made as an agent configuration, so
+   * `all-tools` lists only the connectors it loads (`modules/agent-scope`).
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -83,9 +89,18 @@ export function createToolManualsAgentRoutes(
       // Default remote-safe: exclude local-only manuals unless the caller (a locally
       // installed MCP server) explicitly opts in with `?remote=false`.
       const remoteOnly = req.query.remote !== 'false';
-      const userManuals = email ? await toolManualService.toManualCallTemplates(email, { remoteOnly }) : [];
+      // A connection made as an agent configuration lists only the connectors that
+      // file loads, and says which agent it is — the MCP proxy words its
+      // refusals and its handshake from that. Everything lists as it always
+      // did, with no `connection` at all.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      const within = scope.connectorFilter();
+      const userManuals = email
+        ? await toolManualService.toManualCallTemplates(email, within ? { remoteOnly, within } : { remoteOnly })
+        : [];
       const manuals: CallTemplate[] = [kbManualTemplate(), ...userManuals];
-      res.json({ manuals });
+      const connection = scope.toWire();
+      res.json(connection ? { manuals, connection } : { manuals });
     } catch (err) {
       log.error('all-tools failed:', { err });
       res.status(500).json({ error: 'Failed to list tools' });
@@ -171,6 +186,24 @@ export function createToolManualsAgentRoutes(
         email,
         rels.map((r) => `${pluginRel}/${r}`),
       );
+      // A folder with nothing the person may read is absent to them, whatever
+      // the connection — so that 404 comes first, and the connection's own
+      // refusal below never confirms a folder the person could not see.
+      if (![...verdicts.values()].some((v) => v === true)) {
+        return void res.status(404).json({ error: 'Not found' });
+      }
+      // A connection made as an agent configuration materializes only a plugin
+      // that defines a connector the file loads — the archive is how the
+      // local MCP server runs one, and nothing else asks for it. Checked
+      // before any file is opened.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      if (!scope.loadsConnectorIn(pluginRel)) {
+        const why = scope.describe();
+        return void res.status(403).json({
+          error: `The plugin "${folder}" is not available to this connection.${why ? ` ${why}` : ''}`,
+          code: NOT_AVAILABLE_TO_CONNECTION,
+        });
+      }
       const zip = new AdmZip();
       let included = 0;
       let bytes = 0;
@@ -269,7 +302,11 @@ export function createToolManualsAgentRoutes(
       const email = await callerEmail(req);
       if (!email) return void res.status(403).json({ error: 'Forbidden' });
       const slug = Array.isArray(req.params.slug) ? req.params.slug[0] : req.params.slug;
-      const manual = await toolManualService.resolveInlineManual(email, String(slug));
+      // A connection made as an agent configuration reads only the manuals of the
+      // connectors it loads; another is as absent as one the person cannot read.
+      const scope = await resolveConnectionScope(agentScope, email, req.toolAuth?.agentPath);
+      const within = scope.connectorFilter();
+      const manual = await toolManualService.resolveInlineManual(email, String(slug), within ? { within } : undefined);
       if (!manual) return void res.status(404).json({ error: 'Not found' });
       res.json(manual);
     } catch (err) {

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -43,6 +43,7 @@ import {
   EXTERNAL_KB_MANUAL_NAME,
   MAX_CAPABILITIES,
   type IToolManualService,
+  type ConnectorScope,
   type ToolManualDescriptor,
   type ToolManualDescriptorBase,
   type ToolManualSummary,
@@ -304,8 +305,8 @@ export class ToolManualService implements IToolManualService {
     return (await this.accessibleManuals(userEmail)).map(toSummary);
   }
 
-  async listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog> {
-    const { manuals, invalid } = await this.accessibleScan(userEmail);
+  async listAccessibleCatalog(userEmail: string, within?: ConnectorScope): Promise<AccessibleCatalog> {
+    const { manuals, invalid } = await this.accessibleScan(userEmail, within);
     return { tools: manuals.map(toSummary), invalid };
   }
 
@@ -313,8 +314,8 @@ export class ToolManualService implements IToolManualService {
     return (await this.scan()).manuals.map(toSummary);
   }
 
-  async catalogFingerprints(userEmail: string): Promise<string[]> {
-    return (await this.accessibleManuals(userEmail)).map(manualFingerprint);
+  async catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]> {
+    return (await this.accessibleManuals(userEmail, within)).map(manualFingerprint);
   }
 
   async getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null> {
@@ -341,14 +342,15 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  async listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]> {
-    const manuals = await this.accessibleManuals(userEmail);
+  async listLocalOnly(userEmail: string, within?: ConnectorScope): Promise<{ slug: string; name: string; path: string }[]> {
+    const manuals = await this.accessibleManuals(userEmail, within);
     return manuals.filter((m) => m.remote === false).map((m) => ({ slug: m.slug, name: m.name, path: m.path }));
   }
 
   async listDeclaredOnlyOnBranch(
     userEmail: string,
     branch: string,
+    within?: ConnectorScope,
   ): Promise<{ name: string; path: string; type: ToolManualType }[]> {
     if (!branch || branch === this.kb.defaultBranch) return [];
     // Only a draft this process already holds a clone of — the one the caller
@@ -377,7 +379,7 @@ export class ToolManualService implements IToolManualService {
       pending.map((m) => m.path),
     );
     return pending
-      .filter((m) => allowed.get(m.path) === true)
+      .filter((m) => allowed.get(m.path) === true && (within === undefined || within(m.path)))
       .map((m) => ({ name: m.name, path: m.path, type: m.type }));
   }
 
@@ -456,8 +458,11 @@ export class ToolManualService implements IToolManualService {
     return { name: m.name, type: m.type, remote: m.remote, healthCheck: m.healthCheck, callTemplate };
   }
 
-  async toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]> {
-    const manuals = await this.accessibleManuals(userEmail);
+  async toManualCallTemplates(
+    userEmail: string,
+    opts?: { remoteOnly?: boolean; within?: ConnectorScope },
+  ): Promise<CallTemplate[]> {
+    const manuals = await this.accessibleManuals(userEmail, opts?.within);
     const out: CallTemplate[] = [];
     for (const m of manuals) {
       // Remote consumers (the hosted MCP proxy) don't get local-only manuals —
@@ -474,11 +479,17 @@ export class ToolManualService implements IToolManualService {
     return out;
   }
 
-  async resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null> {
+  async resolveInlineManual(
+    userEmail: string,
+    slug: string,
+    opts?: { within?: ConnectorScope },
+  ): Promise<UtcpManualDict | null> {
     const found = (await this.scan()).manuals.find((m) => m.slug === slug);
     if (!found || found.type !== 'inline') return null;
     const wsId = this.kb.defaultWorkspaceId();
     if (!(await this.accessControl.canRead(wsId, userEmail, found.path))) return null;
+    // After the read gate, as every narrowing is: a connection's scope can only take away.
+    if (opts?.within && !opts.within(found.path)) return null;
     try {
       return manualSerializer.validateDict({
         utcp_version: '1.1.0',
@@ -590,8 +601,8 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  private async accessibleManuals(userEmail: string): Promise<ToolManualDescriptor[]> {
-    return (await this.accessibleScan(userEmail)).manuals;
+  private async accessibleManuals(userEmail: string, within?: ConnectorScope): Promise<ToolManualDescriptor[]> {
+    return (await this.accessibleScan(userEmail, within)).manuals;
   }
 
   /**
@@ -599,8 +610,12 @@ export class ToolManualService implements IToolManualService {
    * ONE `canReadBatch`. Both halves are paths in the same workspace judged by
    * the same rule, and splitting them into two calls would pay a second
    * round-trip to ask the same question.
+   *
+   * `within` narrows the answer to a connection's connectors, AFTER the read
+   * gate: it can take a manual out of what the caller may read, never put one
+   * in. Absent, the answer is the caller's whole readable catalog.
    */
-  private async accessibleScan(userEmail: string): Promise<ScanResult> {
+  private async accessibleScan(userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
     const { manuals, invalid } = await this.scan();
     if (manuals.length === 0 && invalid.length === 0) return emptyScan();
     const wsId = this.kb.defaultWorkspaceId();
@@ -612,9 +627,10 @@ export class ToolManualService implements IToolManualService {
     // A REFUSED file is gated the same way a listed one is: its path is a fact
     // about the knowledge base, and "there is a broken tool at this path" is
     // not something to tell someone who may not read that path.
+    const inScope = (p: string) => allowed.get(p) === true && (within === undefined || within(p));
     return {
-      manuals: manuals.filter((m) => allowed.get(m.path) === true),
-      invalid: invalid.filter((i) => allowed.get(i.path) === true),
+      manuals: manuals.filter((m) => inScope(m.path)),
+      invalid: invalid.filter((i) => inScope(i.path)),
     };
   }
 

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -5,7 +5,7 @@ import type { ToolContext, ToolHandlerFactory } from '../tool-helpers/index.js';
 import { toolDef, declareRouteTool } from '../tool-helpers/index.js';
 import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IToolManualService } from './tool-manuals.contract.js';
+import type { ConnectorScope, IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 
 /**
@@ -51,7 +51,9 @@ export function registerToolManualsTools(
     hiddenTools?: HiddenToolSource;
   },
 ): void {
-  registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildListLocalToolsDef(toolManualService, ctx.userEmail, ctx.connectionScope?.connectorFilter()),
+  );
   registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
   // The def above is built per catalog listing (its description names the
   // tools configured for THIS caller), so declare the arguments here as well:
@@ -59,12 +61,22 @@ export function registerToolManualsTools(
   // against them too.
   declareRouteTool('list_local_tools', LIST_LOCAL_TOOLS_INPUTS);
 
+  // The local server's discovery read (`discovery`): it asks this route at
+  // startup for the connectors it must materialize, whatever tools the
+  // connection is offered — a connection made as an agent configuration that omits
+  // the tool is answered its connectors, not refused, or the local server
+  // could not start for that agent at all.
   router.post(
     '/agent/tools/list_local_tools',
     toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => ({
-      tools: await toolManualService.listLocalOnly(ctx.user.email),
-    })),
+    toolHandler(async (_args, ctx: ToolContext) => {
+      const within = ctx.connectionScope?.connectorFilter();
+      return {
+        tools: await (within
+          ? toolManualService.listLocalOnly(ctx.user.email, within)
+          : toolManualService.listLocalOnly(ctx.user.email)),
+      };
+    }, { discovery: true }),
   );
 
   // A FUNCTION, not a constant — this factory runs at boot, and on a
@@ -243,12 +255,17 @@ export function registerToolManualsTools(
     toolHandler(async (args, ctx: ToolContext) => {
       // The in-app agent is focused on its own draft; an external caller names it.
       const branch = typeof args.branch === 'string' && args.branch ? args.branch : ctx.focusedBranch;
+      const within = ctx.connectionScope?.connectorFilter();
       // The catalog comes back whole — what parsed AND what was refused — from
       // ONE scan, so the refused files cost no second walk of the workspace and
       // the two halves cannot disagree about which files made it.
       const [{ tools: manuals, invalid }, pending] = await Promise.all([
-        toolManualService.listAccessibleCatalog(ctx.user.email),
-        branch ? toolManualService.listDeclaredOnlyOnBranch(ctx.user.email, branch) : Promise.resolve([]),
+        // Only the connectors the caller's connection loads: setup is counted
+        // for the tools this connection can call, not every one the person can.
+        within
+          ? toolManualService.listAccessibleCatalog(ctx.user.email, within)
+          : toolManualService.listAccessibleCatalog(ctx.user.email),
+        branch ? toolManualService.listDeclaredOnlyOnBranch(ctx.user.email, branch, within) : Promise.resolve([]),
       ]);
       const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
       const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
@@ -301,9 +318,9 @@ export function registerToolManualsTools(
 }
 
 /** "Local-only tools configured for you: `a`, `b`." (or a none note), filtered to what the caller may read. */
-async function localToolsLine(svc: IToolManualService, userEmail?: string): Promise<string> {
+async function localToolsLine(svc: IToolManualService, userEmail?: string, within?: ConnectorScope): Promise<string> {
   if (!userEmail) return 'No local-only tools are currently configured.';
-  const tools = await svc.listLocalOnly(userEmail);
+  const tools = await (within ? svc.listLocalOnly(userEmail, within) : svc.listLocalOnly(userEmail));
   if (tools.length === 0) return 'No local-only tools are currently configured.';
   return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
 }
@@ -311,7 +328,7 @@ async function localToolsLine(svc: IToolManualService, userEmail?: string): Prom
 /** `list_local_tools` takes nothing; a const so the route and the def share one declaration. */
 const LIST_LOCAL_TOOLS_INPUTS = { type: 'object' as const, properties: {}, additionalProperties: false };
 
-async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
+async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string, within?: ConnectorScope): Promise<UtcpTool> {
   return toolDef({
     name: 'list_local_tools',
     description:
@@ -324,7 +341,7 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
       'machine. Otherwise each entry gives the tool’s name and its `.tool` file ' +
       'path in the knowledge base — read that file with `read_file` and wire the tool into your local ' +
       'setup by hand. ' +
-      (await localToolsLine(svc, userEmail)),
+      (await localToolsLine(svc, userEmail, within)),
     path: '/api/agent/tools/list_local_tools',
     inputs: LIST_LOCAL_TOOLS_INPUTS,
     outputs: {

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

@@ -15,7 +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 { RipgrepPatternMatcher } from '../../workspace/index.js';
 import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
 import { registerPluginsTools } from '../../plugins/plugins.tools.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
@@ -115,7 +115,7 @@ async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = em
     // mounted on the same terms (it spawns no worker until a search runs).
     undefined,
     undefined,
-    new WorkerPatternMatcher(),
+    new RipgrepPatternMatcher(),
   );
   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);

package/src/modules/tool-registry/manual.routes.ts

@@ -2,6 +2,7 @@ import express, { type Request, type RequestHandler } from 'express';
 import { UtcpManualSerializer } from '@utcp/sdk';
 import { declaresWrite, type IToolRegistry, type ToolManualContext, type UtcpTool } from './tool.contract.js';
 import { requireInternalSource } from '../tool-auth/index.js';
+import { resolveConnectionScope, type IAgentScopeResolver } from '../agent-scope/index.js';
 import type { IToolReadOnlyHints } from './read-only-hints.contract.js';
 
 /** Resolve a connection-key/internal-token user id to its email (for per-caller provider defs). */
@@ -62,6 +63,12 @@ export function createManualRoutes(
    * Absent, the manual carries the tools' own tags only.
    */
   readOnlyHints?: Pick<IToolReadOnlyHints, 'apply'>,
+  /**
+   * Resolves the scope of a connection made as an agent configuration: the external
+   * manual then lists only the platform tools it loads, and the providers word
+   * their descriptions for it (`modules/agent-scope`).
+   */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>,
 ): express.Router {
   const router = express.Router();
 
@@ -71,17 +78,31 @@ export function createManualRoutes(
   async function context(req: Request): Promise<ToolManualContext> {
     const userId = req.toolAuth?.userId;
     if (!userId) return {};
-    if (!resolveUserEmail) return { userId };
+    let userEmail: string | undefined;
     try {
-      return { userId, userEmail: await resolveUserEmail(userId) };
+      userEmail = resolveUserEmail ? await resolveUserEmail(userId) : undefined;
     } catch {
-      return { userId };
+      userEmail = undefined;
     }
+    // Everything adds nothing to the context, so its providers are asked
+    // exactly what they were asked before connections could be narrowed.
+    const agentPath = req.toolAuth?.agentPath;
+    const connectionScope = agentPath ? await resolveConnectionScope(agentScope, userEmail, agentPath) : undefined;
+    return {
+      userId,
+      ...(userEmail !== undefined ? { userEmail } : {}),
+      ...(connectionScope ? { connectionScope } : {}),
+    };
   }
 
   router.get('/agent/utcp', manualAuth, async (req, res) => {
-    const tools = await registry.listExternal(await context(req));
-    res.json(toManual(readOnlyHints ? readOnlyHints.apply(tools) : tools));
+    const ctx = await context(req);
+    const tools = await registry.listExternal(ctx);
+    // A connection made as an agent configuration is offered only the platform
+    // tools that file loads; a call to another is refused at its route.
+    const scope = ctx.connectionScope;
+    const offered = scope ? tools.filter((t) => scope.allowsPlatformTool(t.name)) : tools;
+    res.json(toManual(readOnlyHints ? readOnlyHints.apply(offered) : offered));
   });
   router.get('/agent/internal/utcp', manualAuth, requireInternalSource, async (req, res) => {
     const internal = await registry.listInternal(await context(req));

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

@@ -1,4 +1,5 @@
 import type { JsonSchema, Tool as UtcpTool } from '@utcp/sdk';
+import type { ConnectionScope } from '../agent-scope/index.js';
 
 export type { JsonSchema, UtcpTool };
 
@@ -23,6 +24,12 @@ export interface ToolManualContext {
   userEmail?: string;
   /** The requesting user's id, when it could be resolved (for per-user gating). */
   userId?: string;
+  /**
+   * What the requesting connection may load, when it was made as an agent configuration
+   * file (`modules/agent-scope`): a provider that names skills or connectors
+   * in its description names only those. Absent is Everything.
+   */
+  connectionScope?: ConnectionScope;
 }
 
 /**

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -250,7 +250,7 @@ function makeReviewWorkflow(): IReviewWorkflowService {
 describe('WorkflowService — branch delegation', () => {
   it('listBranches delegates to git.listBranches', async () => {
     const git = makeGit();
-    const branches = [{ name: 'main', isCurrent: true, isProtected: true, ahead: 0, behind: 0, hasRemote: true }];
+    const branches = [{ name: 'main', isCurrent: true, isProtected: true, hasRemote: true }];
     (git.listBranches as ReturnType<typeof vi.fn>).mockResolvedValue(branches);
 
     const svc = new WorkflowService(makeDb(), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate());

package/src/modules/workflow/__tests__/workflow.service.sync.test.ts

@@ -344,7 +344,7 @@ describe('WorkflowService.retireRemoteGoneClone — what can bring the branch ba
       }),
       createBranch: vi.fn(async (_ws: string, name: string) => {
         order.push('create');
-        return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
+        return { name, isProtected: false, hasRemote: true };
       }),
     } as unknown as GitService;
     const workspaceService = {

package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts

@@ -104,6 +104,9 @@ const workspaceService = {
 const workflowService = {
   listBranches: async (ws: string) => {
     calls.push(['listBranches', ws]);
+    // A real listing fetches first; mark when that fetch has landed.
+    await new Promise((r) => setTimeout(r, 0));
+    calls.push(['listBranches:fetched', ws]);
     return [{ name: 'main', isProtected: true }];
   },
   commitChange: async (ws: string, user: { id: string }, body: unknown) => {
@@ -117,7 +120,7 @@ const workflowService = {
   },
   createBranch: async (ws: string, name: string) => {
     calls.push(['createBranch', ws, name]);
-    return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
+    return { name, isProtected: false, hasRemote: true };
   },
   acquireLock: async (ws: string, branch: string, path: string) => {
     calls.push(['acquireLock', ws, branch, path]);
@@ -206,6 +209,10 @@ const workflowService = {
     calls.push(['branchStatus', ws]);
     return { branch: ws, hasUpstream: true, unmergedFromUpstream: true };
   },
+  branchCounts: async (ws: string) => {
+    calls.push(['branchCounts', ws]);
+    return { ahead: 3, behind: 1 };
+  },
   listPendingChangePaths: async (ws: string) => {
     calls.push(['listPendingChangePaths', ws]);
     return ['knowledge-base/KnowledgeBase/Pending.md'];
@@ -518,6 +525,24 @@ describe('registerWorkflowTools', () => {
     expect(calls).toContainEqual(['listBranches', 'existing-ws']);
   });
 
+  it('list_branches declares names, protection and remote presence, and no commit counts', async () => {
+    await start();
+    for (const tools of [await registryRef!.listInternal(), await registryRef!.listExternal()]) {
+      const listBranches = tools.find((t) => t.name === 'list_branches')!;
+      const branch = (listBranches.outputs as { properties: { branches: { items: { properties: object; required: string[] } } } })
+        .properties.branches.items;
+      expect(Object.keys(branch.properties).sort()).toEqual(['hasRemote', 'isProtected', 'name']);
+      expect([...branch.required].sort()).toEqual(['hasRemote', 'isProtected', 'name']);
+      expect(listBranches.description).toContain('{ name, isProtected, hasRemote }');
+      expect(listBranches.description).not.toMatch(/\bahead\b,|\bbehind\b,/);
+      // The counts are still `branch_status`'s answer, for its one branch.
+      const branchStatus = tools.find((t) => t.name === 'branch_status')!;
+      expect((branchStatus.outputs as { required: string[] }).required).toEqual(
+        expect.arrayContaining(['ahead', 'behind', 'behindRemote']),
+      );
+    }
+  });
+
   it('open_change_request acts on the SOURCE branch\'s workspace', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/open_change_request`, writeTok(), {
@@ -1008,6 +1033,26 @@ describe('save_file and the repository folder', () => {
     expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
   });
 
+  it('refuses a tmp ref in every path input, before any lock — save_file, the history tools and update_branch\'s resolutions alike', async () => {
+    const base = await start();
+    const calls_: Array<[string, Record<string, unknown>]> = [
+      ['save_file', { path: '__tmp__/chat-uploads/plan.xlsx' }],
+      ['read_file_at', { path: '__tmp__/chat-uploads/plan.xlsx', at: 'HEAD' }],
+      ['compare_file', { path: '__tmp__/chat-uploads/plan.xlsx' }],
+      ['list_file_changes', { path: '__tmp__/chat-uploads/plan.xlsx' }],
+      ['update_branch', { resolutions: [{ path: '__tmp__/chat-uploads/plan.xlsx', choose: 'ours' }] }],
+    ];
+    for (const [tool, args] of calls_) {
+      const res = await post(`${base}/api/agent/tools/${tool}`, writeTok(), { ...args, branch: WS });
+      expect(res.status, tool).toBe(400);
+      const body = (await res.json()) as { error: string; kind: string };
+      expect(body.kind, tool).toBe('tmp-ref-read-only');
+      expect(body.error).toContain(`${tool} does not take one there`);
+      expect(body.error).toContain('copy_file');
+    }
+    expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
+  });
+
   it('answers a missing path with a 400, not a crash', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), { branch: WS });
@@ -1165,8 +1210,9 @@ describe('history and syncing tools', () => {
       // The listing double names only `main`, so the draft's own entry is unknown.
       isProtected: false,
       hasRemote: true,
-      ahead: null,
-      behind: null,
+      // Counted for the draft alone, by its own workspace — not read off a listing.
+      ahead: 3,
+      behind: 1,
       behindRemote: true,
       uncommittedPaths: ['KnowledgeBase/Pending.md'],
       forkBase: 'main',
@@ -1175,6 +1221,11 @@ describe('history and syncing tools', () => {
       withheldPaths: 0,
     });
     expect(calls).toContainEqual(['changedPathsBetweenBranches', DRAFT_WS, 'main', DRAFT]);
+    expect(calls).toContainEqual(['branchCounts', DRAFT_WS]);
+    // Counted only once the listing's fetch has refreshed the remote-tracking refs.
+    const fetched = calls.findIndex((c) => c[0] === 'listBranches:fetched' && c[1] === DRAFT_WS);
+    expect(fetched).toBeGreaterThanOrEqual(0);
+    expect(calls.findIndex((c) => c[0] === 'branchCounts')).toBeGreaterThan(fetched);
 
     calls = [];
     const named = await post(tool(base, 'branch_status'), writeTok(), { branch: DRAFT, base: 'release' });

package/src/modules/workflow/agent-tools/workflow.tools.ts

@@ -36,11 +36,9 @@ const branchSchema: JsonSchema = {
   properties: {
     name: { type: 'string' },
     isProtected: { type: 'boolean' },
-    ahead: { type: ['integer', 'null'], description: 'Commits ahead of upstream / nearest protected base; null if unresolved.' },
-    behind: { type: ['integer', 'null'], description: 'Commits behind; null if unresolved.' },
     hasRemote: { type: 'boolean', description: 'True iff `origin/<name>` exists after the last fetch.' },
   },
-  required: ['name', 'isProtected', 'ahead', 'behind', 'hasRemote'],
+  required: ['name', 'isProtected', 'hasRemote'],
 };
 
 const commitSchema: JsonSchema = {
@@ -239,7 +237,9 @@ export function registerWorkflowTools(
         // `getFilesystem` — so the branch-less call the tool handler refuses
         // before this runs would otherwise commit to, or fork from, a
         // workspace literally named "undefined".
-        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx),
+        // The normaliser also refuses a tmp ref (`__tmp__/…`) in every path
+        // input: none of these tools takes one (see `kb-fs/tmp-ref.ts`).
+        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName, { tool: spec.name }), ctx),
         { write: spec.write },
       ),
     );
@@ -258,7 +258,8 @@ export function registerWorkflowTools(
     name: 'list_branches',
     description:
       'List every draft known to the repository (protected versions + unprotected drafts, ' +
-      'local and on the shared remote). Returns `{ branches: [{ name, isProtected, ahead, behind, hasRemote }] }`. ' +
+      'local and on the shared remote). Returns `{ branches: [{ name, isProtected, hasRemote }] }`; ' +
+      'how far one branch is ahead or behind is `branch_status`\'s answer. ' +
       'Takes no arguments — branch listing is repo-global, not scoped to any one draft.',
     // Repo-global: the branch set is the same from any clone, so don't require
     // (and risk cloning) a model-named branch — resolve any existing workspace.
@@ -978,9 +979,13 @@ export function registerWorkflowTools(
       // and a save or sync landing between two of them is tolerated — the
       // next call reports it. (The one answer that must be exact, what a
       // merge is of, is taken under one reservation by `update_branch`.)
-      const [status, branches, pending, forkBase] = await Promise.all([
+      // The counts alone wait for the listing: its fetch refreshes the
+      // remote-tracking refs they are measured against.
+      const [status, [branches, counts], pending, forkBase] = await Promise.all([
         ctx.workflowService.branchStatus(workspaceId),
-        ctx.workflowService.listBranches(workspaceId),
+        ctx.workflowService
+          .listBranches(workspaceId)
+          .then(async (listed) => [listed, await ctx.workflowService.branchCounts(workspaceId)] as const),
         ctx.workflowService.listPendingChangePaths(workspaceId),
         ctx.workflowService.resolveForkBase(workspaceId, branch),
       ]);
@@ -1000,8 +1005,8 @@ export function registerWorkflowTools(
         branch,
         isProtected: info?.isProtected ?? kb.protectedBranches.has(branch),
         hasRemote: info?.hasRemote ?? status.hasUpstream,
-        ahead: info?.ahead ?? null,
-        behind: info?.behind ?? null,
+        ahead: counts.ahead,
+        behind: counts.behind,
         behindRemote: status.unmergedFromUpstream,
         uncommittedPaths,
         forkBase,