@bevel-software/platform-core-backend 0.12.1 → 0.13.1

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

@@ -3,6 +3,9 @@ import fs from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
 import '@utcp/http'; // side effect: register the 'http' call-template type (http + inline sub-manuals)
 import '@utcp/mcp'; // side effect: register the 'mcp' call-template type (mcp `.tool` sources)
+// side effect: register the 'cli' call-template type for PARSING ONLY — the
+// executor is removed again, so this process cannot dispatch a shell command.
+import { containsCliCallTemplate } from './utcp-cli-parse-only.js';
 import {
   UtcpManualSerializer,
   CallTemplateSerializer,
@@ -103,19 +106,32 @@ const variableSubstitutor = new DefaultVariableSubstitutor();
  * the vault applies in the other direction with `VariableScopeResolver`.
  */
 export interface McpAuthDiscoveryPort {
-  statusFor(
-    manualName: string,
-    mcpUrl: string,
-  ): Promise<
-    | { status: 'open' }
-    | {
-        status: 'oauth';
-        provider: { authorizationUrl: string; tokenUrl: string; clientId: string; scopes?: string[] };
-      }
-    | { status: 'unsupported'; reason: string }
-  >;
+  statusFor(manualName: string, mcpUrl: string): Promise<McpAuthDiscoveryResult>;
+  /**
+   * The sign-in endpoints for an OWNER-REGISTERED client: the same metadata
+   * walk as `statusFor`, stopping short of dynamic registration — the manual
+   * already names its `clientId`. Nothing is persisted; the owner's
+   * client-secret save pins the completed provider. Optional so a port that
+   * only knows the zero-config path still satisfies the interface.
+   */
+  providerForDeclaredClient?(manualName: string, mcpUrl: string, clientId: string): Promise<McpAuthDiscoveryResult>;
 }
 
+export type McpAuthDiscoveryResult =
+  | { status: 'open' }
+  | {
+      status: 'oauth';
+      provider: {
+        authorizationUrl: string;
+        tokenUrl: string;
+        clientId: string;
+        scopes?: string[];
+        resource?: string;
+        pkce?: boolean;
+      };
+    }
+  | { status: 'unsupported'; reason: string };
+
 /**
  * Reads `*.tool` manuals from the DEFAULT-branch workspace (never the caller's
  * branch), so the catalog is one global, released set — same discipline as
@@ -172,9 +188,9 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  async listLocalOnly(userEmail: string): Promise<{ name: string; path: string }[]> {
+  async listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]> {
     const manuals = await this.accessibleManuals(userEmail);
-    return manuals.filter((m) => m.remote === false).map((m) => ({ name: m.name, path: m.path }));
+    return manuals.filter((m) => m.remote === false).map((m) => ({ slug: m.slug, name: m.name, path: m.path }));
   }
 
   async userScopedKeysForManual(
@@ -426,21 +442,31 @@ export class ToolManualService implements IToolManualService {
   private async decorateMcpOAuth(manuals: ToolManualDescriptor[]): Promise<void> {
     const discovery = this.mcpAuthDiscovery;
     if (!discovery) return;
-    const eligible = manuals.filter((m) => {
-      if (m.type !== 'mcp' || !m.url) return false;
-      // Local-only servers aren't probeable from here; templated URLs aren't
-      // resolvable without a caller. Both keep their file-declared behavior.
-      if (m.remote === false || m.url.includes('${')) return false;
+    const bare: ToolManualDescriptor[] = [];
+    const declared: { m: ToolManualDescriptor; v: ToolVariable }[] = [];
+    for (const m of manuals) {
+      if (m.type !== 'mcp') continue;
+      const oauthVar = (m.variables ?? []).find((v) => v.oauth != null);
+      if (oauthVar) {
+        // An owner-registered client is `oauth-manual` by definition — whether
+        // the declaration is complete or still needs its endpoints discovered.
+        // Explicit wins over discovery: never registered over, never probed
+        // for anything but the endpoints the declaration left out.
+        m.setup = { kind: 'oauth-manual' };
+        const o = oauthVar.oauth!;
+        if (!o.authorizationUrl || !o.tokenUrl) declared.push({ m, v: oauthVar });
+        continue;
+      }
       // The file configures auth itself — explicit wins over discovery.
       const hasAuthHeader = Object.keys(m.headers ?? {}).some((h) => h.toLowerCase() === 'authorization');
-      const hasOAuthVar = (m.variables ?? []).some((v) => v.oauth != null);
-      return !hasAuthHeader && !hasOAuthVar;
-    });
+      if (!hasAuthHeader && isProbeableMcpServer(m)) bare.push(m);
+    }
     // Probe every eligible server CONCURRENTLY — a cold scan with several bare
     // mcp tools shouldn't pay one network round-trip per tool in series. The
     // mutation still happens per-manual after its own probe settles.
-    await Promise.all(
-      eligible.map(async (m) => {
+    await Promise.all([
+      ...declared.map(({ m, v }) => this.completeDeclaredOAuth(discovery, m, v)),
+      ...bare.map(async (m) => {
         try {
           const found = await discovery.statusFor(m.name, m.url!);
           // Record the setup requirement so the secrets UI can tell an admin
@@ -485,7 +511,62 @@ export class ToolManualService implements IToolManualService {
           );
         }
       }),
-    );
+    ]);
+  }
+
+  /**
+   * "Bring your own client": a declared sign-in that names only its `clientId`
+   * (the owner registered an app with a provider that offers no dynamic
+   * registration — HubSpot, Google) gets its endpoints, PKCE and resource
+   * indicator from the server's own OAuth metadata, exactly as the zero-config
+   * path would. The descriptor is completed IN MEMORY: the client-secret route
+   * reads the completed declaration and pins it with the secret, so nothing
+   * here persists. When the metadata can't be had, the declaration stays
+   * incomplete and `setup.reason` says so — the secret route then refuses
+   * with the same reason instead of pinning a provider with no endpoints.
+   */
+  private async completeDeclaredOAuth(
+    discovery: McpAuthDiscoveryPort,
+    m: ToolManualDescriptor,
+    v: ToolVariable,
+  ): Promise<void> {
+    const declaredByHand = 'declare `authorizationUrl` and `tokenUrl` on the sign-in variable';
+    if (!isProbeableMcpServer(m)) {
+      m.setup = {
+        kind: 'oauth-manual',
+        reason: `the sign-in endpoints can't be discovered for a local-only or templated server URL — ${declaredByHand}`,
+      };
+      return;
+    }
+    if (!discovery.providerForDeclaredClient) {
+      m.setup = { kind: 'oauth-manual', reason: `sign-in endpoint discovery is unavailable — ${declaredByHand}` };
+      return;
+    }
+    try {
+      const found = await discovery.providerForDeclaredClient(m.name, m.url!, v.oauth!.clientId);
+      if (found.status !== 'oauth') {
+        m.setup = {
+          kind: 'oauth-manual',
+          reason:
+            found.status === 'unsupported'
+              ? found.reason
+              : `the server did not ask for a sign-in and publishes no OAuth metadata — ${declaredByHand} if it needs one`,
+        };
+        return;
+      }
+      v.oauth = {
+        ...v.oauth!,
+        authorizationUrl: found.provider.authorizationUrl,
+        tokenUrl: found.provider.tokenUrl,
+        // A hand-declared resource wins; otherwise the server's own canonical URL.
+        ...(!v.oauth!.resource && found.provider.resource ? { resource: found.provider.resource } : {}),
+      };
+    } catch (err) {
+      // Never break the catalog — the sign-in just isn't ready yet.
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[tool-manuals] sign-in endpoint discovery failed for "${m.path}": ${msg}`);
+      m.setup = { kind: 'oauth-manual', reason: `sign-in endpoint discovery failed: ${msg}` };
+    }
   }
 
   private async scanDisk(): Promise<ToolManualDescriptor[]> {
@@ -556,10 +637,19 @@ export class ToolManualService implements IToolManualService {
     // silently rebind a configured secret to a different file. The winner is
     // deterministic (files scanned in sorted path order); the shared `dedupeById`
     // is the one dedup rule across tools and skills.
-    return dedupeById(parsed, (m) => m.name, (m, id) =>
+    // Deduped by NAMESPACE, not by name. The comment below has always said the
+    // id is the secret-variable namespace and must be unique — but the check
+    // compared raw names, and the two are not the same function. Namespacing
+    // maps every non-word character to `_` and then doubles it, so `a-b` and
+    // `a_b` are different names with the SAME namespace `a__b_`. A `.tool` id
+    // cannot contain a hyphen, but an mcp.json server name can, so the pair is
+    // reachable — and the consequence is that two manuals share one set of
+    // vault keys, with either able to resolve the other's secrets.
+    return dedupeById(parsed, (m) => utcpNamespacePrefix(m.name), (m, ns) =>
       console.warn(
-        `[tool-manuals] skipping "${m.path}": manual id "${id}" is already used by another ` +
-          '`.tool` — give it a unique `id` (the id is the secret-variable namespace and must be unique).',
+        `[tool-manuals] skipping "${m.path}": manual "${m.name}" resolves to the secret-variable ` +
+          `namespace "${ns}", which another manual already uses. Names differing only in \`-\` vs \`_\` ` +
+          'share one namespace — rename one of them.',
       ),
     );
   }
@@ -714,6 +804,23 @@ export function normalizeToolManual(
 
   descriptor.remote = normalizeRemote(obj.remote);
 
+  // A `.tool` that shells out is LOCAL, always. The hosted platform parses and
+  // lists these so the local MCP server can find them, but it must never be the
+  // thing that runs them — a `.tool` is knowledge-base content, and agents write
+  // to the knowledge base. A declared `remote: true` beside a shell command is
+  // therefore a refusal rather than a warning: silently correcting it would let
+  // an author believe they had published a remote tool, and would leave the
+  // catalog disagreeing with the file about what the platform will do.
+  if (containsCliCallTemplate(obj)) {
+    if (obj.remote === true) {
+      throw new Error(
+        `\`.tool\` "${name}" declares \`remote: true\` but contains a \`cli\` call template — ` +
+          'shell tools execute only in a local runtime (drop `remote: true`, or the `cli` template).',
+      );
+    }
+    descriptor.remote = false;
+  }
+
   if (type === 'inline') {
     const tools = Array.isArray(obj.tools) ? obj.tools : undefined;
     if (!tools) throw new Error('inline `.tool` must have a `tools` array');
@@ -812,11 +919,23 @@ function normalizeVariables(raw: unknown): ToolVariable[] {
   });
 }
 
+/**
+ * Whether the platform can reach an MCP server's URL for OAuth discovery.
+ * Local-only servers aren't probeable from here; templated URLs aren't
+ * resolvable without a caller. Both keep their file-declared behavior — the
+ * one rule for the zero-config probe and for completing a declared client.
+ */
+function isProbeableMcpServer(m: ToolManualDescriptor): boolean {
+  return !!m.url && m.remote !== false && !m.url.includes('${');
+}
+
 /**
  * Parse a variable's optional OAuth provider config. Carries PUBLIC config only —
  * never a client secret. Both URLs are validated with the SAME SSRF-safe check the
  * vault uses for OAuth endpoints (`assertSafeFetchUrl` with https required), so a
- * `.tool` author can't aim a sign-in/token exchange at an internal host.
+ * `.tool` author can't aim a sign-in/token exchange at an internal host. Both
+ * URLs are REQUIRED here: a `.tool` (http/inline) has no server whose OAuth
+ * metadata could fill them in — that convenience belongs to mcp.json servers.
  */
 function normalizeVariableOAuth(name: string, raw: unknown): ToolVariableOAuth | undefined {
   if (raw === undefined || raw === null) return undefined;
@@ -862,12 +981,21 @@ function normalizeVariableOAuth(name: string, raw: unknown): ToolVariableOAuth |
     }
     authParams = Object.fromEntries(entries) as Record<string, string>;
   }
+  // PKCE is on unless the file says `false`; only the opt-out is ever stored.
+  if (o.pkce !== undefined && typeof o.pkce !== 'boolean') {
+    throw new Error(`variable "${name}" oauth.pkce must be a boolean`);
+  }
+  // Never fetched (it rides as a request param), but it names the remote
+  // server — same https/SSRF bar as the endpoints.
+  const resource = o.resource !== undefined ? safeUrl(o.resource, 'resource') : undefined;
   return {
     authorizationUrl,
     tokenUrl,
     clientId,
     ...(scopes ? { scopes } : {}),
     ...(authParams ? { authParams } : {}),
+    ...(o.pkce === false ? { pkce: false } : {}),
+    ...(resource ? { resource } : {}),
   };
 }
 

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

@@ -69,9 +69,12 @@ export function registerToolManualsTools(
       'what is already configured. Results are scoped to the caller — a `.tool` the caller cannot READ is ' +
       'absent entirely, and all status flags reflect the caller\'s own state. Per tool: `setup` describes ' +
       'an MCP server\'s sign-in requirement (`open` = none; `oauth-auto` = sign-in was configured ' +
-      'automatically; `oauth-manual` = the provider does not support automatic registration, so a writer ' +
-      'must declare the OAuth provider in the `.tool` file and paste its client secret into the tool ' +
-      'editor). Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
+      'automatically; `oauth-manual` = the sign-in needs an OAuth app the owner registers with the provider: ' +
+      'a writer declares its client id on a `user`-scoped variable with an `oauth` block — in the plugin.json ' +
+      'extensions entry for an mcp.json server (endpoints are discovered from the server; PKCE is on by ' +
+      'default), or in the `.tool` file with explicit URLs — and pastes the client secret on the tool\'s page. ' +
+      '`setup.reason` is present only while something still blocks the sign-in and says what). ' +
+      'Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
       'set/authorized their own, and whether it is an OAuth sign-in (users authorize those on the /connect ' +
       'page, never by typing a value). `canWrite` = the caller may write THAT `.tool` FILE (per-file access ' +
       'from its frontmatter `write:`/`owner:` verbs and the access.md chain — NOT a platform role), which ' +
@@ -181,8 +184,9 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
       '(e.g. a self-hosted MCP server on localhost) and therefore cannot be called through this ' +
       'remote endpoint. To CALL them, run the workspace as a local MCP server instead of this one: ' +
       '`npx @bevel-software/hexis-mcp --url <workspace-url> --key <connection-key>` serves every tool ' +
-      'you have here plus these, because it runs where they exist (their own credentials come from ' +
-      'that process\'s environment). Otherwise each entry gives the tool’s name and its `.tool` file ' +
+      'you have here plus these, because it runs where they exist — and it resolves each tool\'s ' +
+      'declared variables from this workspace\'s secrets, so nothing has to be hand-placed on that ' +
+      '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)),
@@ -197,6 +201,7 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
           items: {
             type: 'object',
             properties: {
+              slug: { type: 'string', description: 'How the tool is addressed on this API.' },
               name: { type: 'string' },
               path: { type: 'string', description: 'KB path of the `.tool` file (read it with read_file).' },
             },

package/src/modules/tool-manuals/utcp-cli-parse-only.ts

@@ -0,0 +1,76 @@
+/**
+ * Registers the UTCP `cli` call-template type for PARSING ONLY, and takes the
+ * executor away again.
+ *
+ * A `.tool` whose tools shell out (`git status`, `git push`) is how the local
+ * MCP server gets a git surface without handing an agent a token. The hosted
+ * platform still has to UNDERSTAND those files — it scans them, validates them,
+ * lists them through `list_local_tools`, and serves the inline manual body to
+ * the local server that will run it — so the `cli` serializer must be
+ * registered here or every such file fails validation and drops out of the
+ * catalog.
+ *
+ * What it must never do is RUN one. Agents write to the knowledge base, so
+ * anyone who can land a `.tool` would otherwise have a shell on production.
+ * `@utcp/cli`'s module-level `register()` installs two things — the call
+ * template serializer and a `CliCommunicationProtocol` — and only the first is
+ * wanted here, so the protocol is removed from the SDK's registry immediately
+ * after the import that added it.
+ *
+ * That makes decision 8 of the AEL plan structural instead of procedural. The
+ * `remote: false` forcing in `normalizeToolManual` keeps cli manuals out of the
+ * hosted proxy's registration set, but this is the backstop underneath it: with
+ * no `cli` protocol in the process, a cli template that reached a hosted client
+ * by any route at all fails to dispatch rather than executing. Two independent
+ * mechanisms, because one of them being wrong is a remote shell.
+ *
+ * Import this module for its side effect wherever `.tool` files are parsed;
+ * import order does not matter, since the removal runs at module evaluation and
+ * nothing dispatches during a scan.
+ */
+import '@utcp/cli';
+import { CommunicationProtocol } from '@utcp/sdk';
+
+/** The UTCP call-template type this module registers the serializer for. */
+export const CLI_CALL_TEMPLATE_TYPE = 'cli';
+
+delete (CommunicationProtocol.communicationProtocols as Record<string, unknown>)[CLI_CALL_TEMPLATE_TYPE];
+
+/**
+ * Whether this process could dispatch a `cli` call template. Always false in the
+ * hosted platform — exported so the guarantee is assertable in a test rather
+ * than only described in a comment.
+ */
+export function canExecuteCliTemplates(): boolean {
+  return CommunicationProtocol.communicationProtocols[CLI_CALL_TEMPLATE_TYPE] !== undefined;
+}
+
+/**
+ * True when any part of `doc` is a `cli` call template.
+ *
+ * Deep walk rather than a lookup at `tool_call_template.call_template_type`:
+ * the field is nested differently across UTCP tool shapes, sub-manuals nest
+ * templates inside templates, and the consequence of missing one is a shell
+ * template in a manual marked remote-capable. Cheap, and a `.tool` is small.
+ *
+ * Cycle-safe. A YAML anchor aliased inside itself (`a: &x { self: *x }`)
+ * parses to a genuinely cyclic object, and an unguarded walk overflows the
+ * stack — which the callers catch, so the file would be dropped from the
+ * catalog silently instead of being examined. A node already seen contributes
+ * nothing new, so it is simply not re-entered.
+ */
+export function containsCliCallTemplate(doc: unknown): boolean {
+  const seen = new WeakSet<object>();
+  const walk = (node: unknown): boolean => {
+    if (!node || typeof node !== 'object') return false;
+    if (seen.has(node)) return false;
+    seen.add(node);
+    if (Array.isArray(node)) return node.some(walk);
+    const obj = node as Record<string, unknown>;
+    if (typeof obj.call_template_type === 'string' && obj.call_template_type.toLowerCase().trim() === CLI_CALL_TEMPLATE_TYPE) {
+      return true;
+    }
+    return Object.values(obj).some(walk);
+  };
+  return walk(doc);
+}

package/src/modules/workflow/__tests__/pending-commits.worker.test.ts

@@ -13,6 +13,7 @@ import type {
   PendingCommit,
   PendingCommitsService,
 } from '../pending-commits.service.js';
+import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 
 /**
  * Unit tests for the queue-draining worker. The service + workflow layers
@@ -20,6 +21,8 @@ import type {
  * applies per claimed row:
  *
  *   - Success → markSucceeded, nothing else.
+ *   - Failure because the path is outside the repository → needs_attention +
+ *     feedback notice at once, whatever the budgets say.
  *   - Failure inside transient budget → markTransientFailure, no recovery agent.
  *   - Failure outside transient budget but inside recovery budget → spawn agent.
  *   - Failure outside recovery budget → mark needs_attention + send feedback notice.
@@ -69,6 +72,16 @@ function makeWorkspaces(): WorkspaceProvider {
   };
 }
 
+/** The error `commitFile` throws for a path beside the clone, as the real producer builds it. */
+function captureRefusal(wsPath: string): unknown {
+  try {
+    assertInsideRepo(wsPath, 'knowledge-base');
+  } catch (err) {
+    return err;
+  }
+  throw new Error(`expected assertInsideRepo to refuse "${wsPath}"`);
+}
+
 function makeFeedback(): ISystemNoticeSink {
   return { send: vi.fn().mockResolvedValue(undefined) } as unknown as ISystemNoticeSink;
 }
@@ -215,6 +228,39 @@ describe('PendingCommitsWorker.drainOnce', () => {
     expect(call.message).toContain('alice@example.com');
   });
 
+  it('a path-outside-repo refusal escalates at once: no retry, no recovery agent, the notice names the corrected path', async () => {
+    // A fresh row with both budgets untouched: any other failure would be
+    // retried. This one cannot change on retry (the bytes are beside the
+    // clone, where git never looks) and gives a recovery agent nothing to
+    // repair, so the ladder is skipped and the row is flagged immediately.
+    const row = makeRow({ path: 'KnowledgeBase/Reviews/PR-12.html', attempts: 0, recoveryAgentRuns: 0 });
+    (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);
+    // The commit layer's own refusal, built by its producer so the shape the
+    // worker switches on cannot drift from what is actually thrown.
+    workflow.runPendingCommit.mockRejectedValueOnce(captureRefusal('KnowledgeBase/Reviews/PR-12.html'));
+
+    await worker.drainOnce();
+
+    expect(service.markTransientFailure).not.toHaveBeenCalled();
+    expect(service.markRecoveryStarted).not.toHaveBeenCalled();
+    expect(recoveryAgent.run).not.toHaveBeenCalled();
+    // `last_error` gets the sanitized message (truncated to fit the column).
+    expect(service.markNeedsAttention).toHaveBeenCalledWith(
+      'row-1',
+      expect.stringContaining('"KnowledgeBase/Reviews/PR-12.html" is outside the knowledge base repository'),
+    );
+    expect(feedback.send).toHaveBeenCalledTimes(1);
+    const call = (feedback.send as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(call.source).toBe('system');
+    expect(call.user).toEqual(RECOVERY_BOT);
+    expect(call.message).toContain('outside the repository');
+    expect(call.message).toContain('Path:      KnowledgeBase/Reviews/PR-12.html');
+    // The correction survives the truncation: it rides on the error payload,
+    // not on the message.
+    expect(call.message).toContain('Use instead: knowledge-base/KnowledgeBase/Reviews/PR-12.html');
+    expect(call.message).toContain('alice@example.com');
+  });
+
   it('a feedback-sink failure does not throw — the row stays needs_attention regardless', async () => {
     const row = makeRow({ attempts: N_TRANSIENT - 1, recoveryAgentRuns: N_RECOVERY });
     (service.claimNext as ReturnType<typeof vi.fn>).mockResolvedValueOnce(row);

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

@@ -42,6 +42,13 @@ const workflowService = {
     calls.push(['createBranch', ws, name]);
     return { name, isProtected: false, ahead: 0, behind: 0, hasRemote: true };
   },
+  acquireLock: async (ws: string, branch: string, path: string) => {
+    calls.push(['acquireLock', ws, branch, path]);
+    return { acquired: true, lock: { branch, path, holderUserId: 'user-A', holderName: 'N' } };
+  },
+  releaseLock: async (ws: string, branch: string, path: string) => {
+    calls.push(['releaseLock', ws, branch, path]);
+  },
 } as never;
 const events = {
   emit: (p: unknown) => {
@@ -52,15 +59,18 @@ const events = {
 
 const internalToken = new InternalTokenService({ secret: 's' });
 let httpServer: HttpServer | undefined;
+/** The registry the tools were mounted into, so a test can inspect their definitions. */
+let registryRef: ToolRegistry | undefined;
 
 async function start(): Promise<string> {
   const registry = new ToolRegistry();
+  registryRef = registry;
   const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
   const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
   const toolHandler = createToolHandlerFactory(resolve);
 
   const router = express.Router();
-  registerWorkflowTools(registry, router, toolAuth, toolHandler);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, 'knowledge-base');
   router.use(createManualRoutes(registry, toolAuth));
 
   const app = express();
@@ -190,3 +200,52 @@ describe('registerWorkflowTools', () => {
     expect(external).not.toContain('switch_branch'); // internal-only
   });
 });
+
+describe('save_file and the repository folder', () => {
+  // `save_file` commits whatever is on disk at `path` through the lock
+  // protocol, bypassing the locking filesystem's own guard. A path without the
+  // clone-folder prefix names a file git can never see, so it is refused here,
+  // before a lock is taken, with the same corrected-path message the write
+  // tools give.
+  it('refuses a repo-relative path before taking any lock', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: 'KnowledgeBase/Reviews/PR-12.html',
+      branch: WS,
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('"knowledge-base/KnowledgeBase/Reviews/PR-12.html"');
+    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 });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toMatch(/path/i);
+    expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
+  });
+
+  it('schedules a prefixed path as before', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: 'knowledge-base/KnowledgeBase/Reviews/PR-12.html',
+      branch: WS,
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ saved: true, queued: true });
+    expect(calls).toContainEqual(['acquireLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
+    expect(calls).toContainEqual(['releaseLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
+  });
+
+  it('describes the prefix on its path input', async () => {
+    await start();
+    const tools = await registryRef!.listInternal();
+    const def = tools.find((t) => t.name === 'save_file');
+    // `toolDef` wraps a tool's inputs under a single `body` property.
+    const body = (def!.inputs as { properties: { body: { properties: Record<string, { description?: string }> } } }).properties.body;
+    expect(body.properties.path.description).toContain('`knowledge-base/`');
+  });
+});

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

@@ -6,6 +6,7 @@ import { toolDef, withBranchInput } from '../../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 
 // A function, not a constant: the branch model is applied during boot, and a
 // module-scope capture would freeze this at the empty set that exists before it.
@@ -118,6 +119,8 @@ export function registerWorkflowTools(
   router: Router,
   toolAuth: RequestHandler,
   toolHandler: ToolHandlerFactory,
+  /** The clone folder at the workspace root; `save_file` refuses a path outside it. */
+  kbDirName: string,
 ): void {
   const mount = (spec: {
     name: string;
@@ -221,7 +224,13 @@ export function registerWorkflowTools(
       '`{ saved: false, reason }` rather than throwing. The commit lands asynchronously.',
     inputs: {
       type: 'object',
-      properties: { path: { type: 'string', minLength: 1, description: 'Workspace-relative path (as write_file expects).' } },
+      properties: {
+        path: {
+          type: 'string',
+          minLength: 1,
+          description: `Workspace-relative path, as write_file expects: starts with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`).`,
+        },
+      },
       required: ['path'],
       additionalProperties: false,
     },
@@ -238,6 +247,14 @@ export function registerWorkflowTools(
     handler: async (args, ctx: ToolContext) => {
       const path = args.path as string;
       const branch = args.branch as string;
+      // This tool commits whatever is on disk at `path` through the lock
+      // protocol, bypassing the locking filesystem's own guard. A path without
+      // the clone-folder prefix names a file git can never see: refuse it
+      // before a lock is taken, with the same corrected-path message.
+      if (typeof path !== 'string' || path.length === 0) {
+        throw new ToolError('`path` is required and must be a non-empty string.', 400);
+      }
+      assertInsideRepo(path, kbDirName);
       const workspaceId = workspaceIdForBranch(branch);
       const acquired = await ctx.workflowService.acquireLock(workspaceId, branch, path, ctx.user);
       if (!acquired.acquired) {

package/src/modules/workflow/git/__tests__/git.service.changedFilesForPr.test.ts

@@ -130,6 +130,62 @@ describe('GitService.changedFilesForPr / resolvePrShas', () => {
     expect(baseSha).not.toBe(headSha);
   });
 
+  /**
+   * A change-request detail resolves the SHAs (which fetches both refs) and
+   * then lists the files. `at` pins that listing to the commits just
+   * resolved: no second fetch, and the file list describes exactly the head
+   * the approvals pin against even when a newer push has landed on origin in
+   * between. The default keeps refreshing first.
+   */
+  it('`at` pins the diff to the resolved commits; the default refreshes origin/* first', async () => {
+    const { upstream, repo } = await seedWorkspace(root, workspaceId);
+    // The branch is authored in ANOTHER clone, so this workspace only ever
+    // knows it as origin/alice/feature — the production shape, where the
+    // base-branch workspace answers for every request without a local copy.
+    const other = path.join(root, 'other');
+    await runGit(root, ['clone', upstream, other]);
+    await runGit(other, ['checkout', '-b', 'alice/feature']);
+    await fs.writeFile(path.join(other, 'added.md'), 'hello\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'feature work']);
+    await runGit(other, ['push', '-u', 'origin', 'alice/feature']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+    // What the detail does first: resolve (and fetch) the two SHAs.
+    const pinned = await git.resolvePrShas(workspaceId, 'current-company-state', 'alice/feature');
+
+    // A second push lands on origin after the resolution.
+    await fs.writeFile(path.join(other, 'second.md'), 'more\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'more work']);
+    await runGit(other, ['push', 'origin', 'alice/feature']);
+
+    const atPinned = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'alice/feature',
+      { at: pinned },
+    );
+    expect(atPinned.map((f) => f.path)).toEqual(['added.md']);
+
+    const refreshed = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'alice/feature',
+    );
+    expect(refreshed.map((f) => f.path).sort()).toEqual(['added.md', 'second.md']);
+
+    await expect(
+      git.changedFilesForPr(workspaceId, 'current-company-state', 'alice/feature', {
+        at: { baseSha: pinned.baseSha, headSha: 'origin/alice/feature' },
+      }),
+    ).rejects.toThrow(/invalid commit sha/);
+  });
+
   /**
    * roles.yaml can never change through a merge — `preserveBaseRolesYaml`
    * restores the base copy onto the source before every merge — so the review