@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/src/modules/workspace/workspace.tools.ts

@@ -1,28 +1,33 @@
 import { spawn } from 'node:child_process';
 import nodeFs from 'node:fs/promises';
 import { join } from 'node:path';
+import AdmZip from 'adm-zip';
 import type { Router, RequestHandler } from 'express';
 import type { LocalFilesystem } from '@mastra/core/workspace';
 import type { IToolRegistry, JsonSchema } from '../tool-registry/tool.contract.js';
 import { ToolError, type ToolContext, type ToolHandler } from '../tool-helpers/tool.contract.js';
 import { BRANCH_INPUT, toolDef } from '../tool-helpers/tool-def.js';
 import {
-  recordOntologyRead,
-  assertOntologyWriteAllowed,
-  assertShellAllowedWithinOntology,
-  ONTOLOGY_BOUNDARY_NOTE,
+  notifyAgentRead,
+  assertAgentWriteAllowed,
   SESSION_ID_INPUT,
-  type SessionOntologyGate,
-} from './session-ontology.gate.js';
+  type AgentAccessGate,
+} from './agent-access.gate.js';
 import type { IRoutineWritePolicy } from './routine-write-policy.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import { assertBranchProvided } from '../../shared/domain-errors.js';
+import { assertBranchProvided, GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
 // relies on) — not a workflow service, so this stays inside the module boundary.
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
-import { assertInsideRepo, assertRepoRootNameFreeArgs, normalizePathArgs } from '../kb-fs/repo-path.js';
+import {
+  assertInsideRepo,
+  assertRepoRootNameFree,
+  assertRepoRootNameFreeArgs,
+  isInsideRepo,
+  normalizePathArgs,
+} from '../kb-fs/repo-path.js';
 import { GitGuardedFilesystem } from '../kb-fs/git-guarded-filesystem.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { isRolesYamlPath } from '../access-model/roles-yaml-guard.js';
@@ -40,28 +45,36 @@ import { createFileReaderRegistry } from './file-readers/file-reader.registry.js
 import { DocumentReader } from './file-readers/document-reader.js';
 import { mcpImageResult } from '@bevel-software/platform-mcp-core';
 import {
-  LEGACY_AGENTS_FILE,
   folderPlaceholderPath,
   isFolderPlaceholder,
   isPlatformFile,
   isPlatformFolder,
   platformFileCreationRefusal,
-  platformFileNames,
   platformFileRefusal,
+  platformFileUploadRefusal,
   platformFolderRefusal,
   entryExistsMessage,
   type ExistingEntryKind,
-  type KbLayout,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
 import { AccessDeniedError } from '../access-model/access-errors.js';
 import { removeEmptyDirs } from './empty-dirs.js';
-import { PROPOSAL_ROUTE_NOTE, rethrowAsWriteDenial } from './write-denial.js';
+import { rethrowAsWriteDenial } from './write-denial.js';
+import { sharedRulesPointer } from '../agent-instructions/shared-file-rules.js';
 import type { IChangeReadGate } from '../access-model/change-gate.js';
 import { notFound, orDeclaredNotFound, orNotFound } from './not-found.js';
 import { logger } from '../../shared/logging.js';
 import { printable } from '../../shared/printable.js';
 import { DestinationTakenError, inspectDestination } from '../../shared/rename-no-replace.js';
+import { AgentUploadStore, type ClaimedUpload } from './agent-upload.store.js';
+import {
+  isSymlinkZipEntry,
+  isZipNoiseEntry,
+  readZipEntry,
+  zipEntryName,
+  zipEntryNameRefusal,
+  zipEntrySegments,
+} from './zip-entry-rules.js';
 
 const log = logger('workspace-tools');
 
@@ -195,60 +208,26 @@ async function keepFolderOf(
   }
 }
 
-/**
- * Appended (centrally, in `mount`) to EVERY workspace tool description. The
- * platform's managed agent guide sits at the workspace root and documents the
- * conventions of that knowledge base; agents (ours and external) should consult
- * it before touching files. It rides on every entrypoint — reads (grep/
- * list_files/file_stat) included — because any of them can be a session's first
- * touch.
- *
- * `CLAUDE.md` is named as a fallback because knowledge bases seeded before the
- * rename still carry one, and the seeder never deletes a file it did not
- * expect. Naming both means an agent finds the conventions either way, instead
- * of reading none because it looked for the newer name and stopped.
- *
- * WHEN THE GUIDE HAS BEEN RENAMED the sentence names two files, ours first. The
- * second is the organisation's OWN `AGENTS.md`, which on such a deployment is
- * ordinary content the platform never touches — and which no harness reads for a
- * remote agent, because a remote agent has no checkout. Telling it to read both
- * is the only way the conventions the customer actually wrote reach the agent
- * working in their knowledge base. Under the default name the wording collapses
- * to the one file it has always named.
- *
- * A FUNCTION of the layout, called when a description is built: the name is a
- * deployment setting, and a module-scope string would snapshot the default.
- */
-function kbConventionsNote(layout: KbLayout): string {
-  const agentsFile = layout.agentsFile ?? LEGACY_AGENTS_FILE;
-  if (agentsFile === LEGACY_AGENTS_FILE) {
-    return ' Before your first read or change in a workspace, read `AGENTS.md` at the KB root — or `CLAUDE.md` on a knowledge base seeded before it was renamed — if either exists: it holds the author\'s conventions for this knowledge base, and you should follow them.';
-  }
-  return (
-    ` Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
-    '`AGENTS.md` if it also exists (the organisation\'s own conventions) — or `CLAUDE.md` on a knowledge base seeded before it was renamed: together they hold the conventions for this knowledge base, and you should follow them.'
-  );
-}
-
-/** The platform files as a tool description lists them — the guide under its own name. */
-function platformFileList(layout: KbLayout): string {
-  return platformFileNames(layout)
-    .map((name) => `\`${name}\``)
-    .join(', ');
-}
-
 const int = (description: string): JsonSchema => ({ type: 'integer', description });
 
 const str = (description: string): JsonSchema => ({ type: 'string', description });
 
 /**
- * Where pictures go, on the two tools that write pages. An agent in core cannot
- * upload bytes yet (TODOS.md), but it can write the page with the link a person
- * will satisfy, and this sentence is what keeps every page it writes on the
- * README's convention: images beside the page, linked relatively.
+ * The upload route, named on every tool that takes content as a JSON string.
+ *
+ * ONE sentence, and the tools' own: it is what stops the three failures the
+ * route was built for. An agent landing 27 files read each one and typed it
+ * out again as a tool argument: a 37 KB write was truncated mid-answer, a page
+ * of regex backslashes failed to parse as a JSON parameter, and a PNG could not
+ * be sent at all. None of that is discoverable from a refusal — a truncated
+ * write reports success — so the tools that invite it name where the bytes
+ * should go instead, in the description itself, for a client that reads
+ * nothing else. WHY, and how the route is used, is one of the shared rules
+ * (`agent-instructions/shared-file-rules.ts`): said in full on three
+ * descriptions it took each of them past the length a client cuts at.
  */
-const IMAGE_CONVENTION_NOTE =
-  ' Images: keep them in an `assets/` folder next to the page that uses them and link them with a relative path, e.g. `![Approval screen](./assets/approval-screen.png)`; the page renders them inline.';
+const UPLOAD_ROUTE_NOTE =
+  ' Large, escape-heavy or binary content does not go through here: use `request_file_upload` + `apply_file_upload`.';
 
 /**
  * A path input that names the clone folder, and says what happens when it does
@@ -287,6 +266,9 @@ const RESERVED_ROOT_NAME_TARGETS: Readonly<Record<string, readonly string[]>> =
   copy_file: ['dest'],
   move_file: ['dest'],
   unzip: ['destination'],
+  // The folder the upload lands in. Each of its own paths is checked again
+  // inside the handler — an archive chooses its entry names, not the caller.
+  apply_file_upload: ['destination'],
 };
 
 function asText(content: string | Buffer): string {
@@ -315,16 +297,6 @@ interface DocGrepState {
   skippedUncached: number;
 }
 
-/**
- * THE binary capability contract, stated once and appended (in `mount`) to
- * every file tool's description — which is also what `tools_info` returns.
- * The split it states is enforced by the reader registry: the text tools
- * refuse what their reader marks not `textEditable` (and binary content under
- * any name) with a `binary_not_writable` refusal; the byte tools never look.
- */
-export const CONTENT_RULE =
-  ' Content rule (the same on every file tool): read_file returns text for text files and extracted text for documents (.docx/.pptx/.xlsx/.odt/.odp/.ods/.pdf, .eml/.msg); write_file, write_files and edit_file accept TEXT only — they refuse documents, images, archives and other binary files (legacy .doc/.ppt/.xls included) with kind `binary_not_writable`, naming the file\'s kind and the tool to use instead; copy_file, move_file, delete_file and unzip act on bytes of any kind; new binary content arrives through upload (`request_upload_token` + `apply_upload` where offered, otherwise Upload in the app). file_stat reports `contentMode` (`text` | `document` | `binary`) so you can decide before acting.';
-
 /** What a `binary_not_writable` refusal points to, in the order to try them. */
 const BINARY_USE_INSTEAD = ['upload', 'copy_file', 'move_file'] as const;
 
@@ -337,7 +309,7 @@ const BINARY_USE_INSTEAD = ['upload', 'copy_file', 'move_file'] as const;
 function binaryNotWritable(fileKind: FileKind, explanation: string): ToolError {
   return new ToolError(
     `${explanation} [binary_not_writable: this file's kind is ${fileKind}; write_file, write_files and edit_file accept text only. ` +
-      'Use upload for new bytes (`request_upload_token` + `apply_upload` where offered, otherwise Upload in the app), ' +
+      'Use upload for new bytes (`request_file_upload` + `apply_file_upload`, or Upload in the app), ' +
       'or copy_file / move_file to place bytes that are already in the workspace.]',
     415,
     { kind: 'binary_not_writable', fileKind, useInstead: [...BINARY_USE_INSTEAD] },
@@ -429,13 +401,6 @@ const WRITE_MODE_INPUT: JsonSchema = {
     'EXISTING file and refuses (`missing`) a path that holds nothing.',
 };
 
-/** The same three modes, said once, for both tool descriptions. */
-const WRITE_MODE_NOTE =
-  ' `mode` decides what may happen at a path and DEFAULTS TO `create`: `create` writes a new file and refuses a path that ' +
-  'already exists (`exists`, with the path — pass `mode: overwrite` to replace it), `overwrite` replaces what is there ' +
-  '(creating it if there is nothing), `update` replaces an existing file and refuses a path that does not exist (`missing`). ' +
-  'A refused path is left exactly as it was.';
-
 /** The refusal `create` gives on a path that already holds something. */
 function pathExists(path: string): ToolError {
   return new ToolError(
@@ -467,6 +432,169 @@ function decideWrite(mode: WriteMode, path: string, exists: boolean): WriteOutco
   return exists ? 'replaced' : 'created';
 }
 
+/**
+ * How many of an upload's paths the answer NAMES before it stops and says how
+ * many there were. A 300-file zip's full outcome list is pages of text an agent
+ * pays for on every call; 25 is enough to see the shape of what happened, and
+ * `total` plus `truncated` say that there is more. `all: true` asks for the
+ * rest, for a caller that really does have to read each one.
+ */
+const APPLY_ANSWER_CAP = 25;
+
+/**
+ * How many entries of one uploaded archive are landed, and how many bytes of
+ * uncompressed content in total.
+ *
+ * Tighter than `unzip`'s own caps on purpose. An apply lands its whole set as
+ * ONE commit, which means every entry's bytes are held in memory at once —
+ * the property that makes the commit atomic is the one that makes a zip bomb
+ * expensive. The upload itself is already bounded by the deployment's upload
+ * limit; these bound what that upload is allowed to expand into.
+ */
+const APPLY_MAX_ENTRIES = 5_000;
+const APPLY_MAX_TOTAL_BYTES = 128 * 1024 * 1024; // 128 MB uncompressed
+
+/**
+ * One path of an upload, as `apply_file_upload` plans it: the bytes to write,
+ * or the reason this path is refused before any gate is asked. A refused path
+ * carries the name the archive held rather than a workspace path, because for
+ * those the whole problem is that no workspace path can be built from it.
+ */
+interface PlannedUploadPath {
+  path: string;
+  content?: Buffer;
+  error?: string;
+  message?: string;
+}
+
+/**
+ * Turn a stored upload into one planned path per file.
+ *
+ * A single file is one path: the destination plus the name it was sent with.
+ * A zip is one path per member, with the member's folder structure kept under
+ * the destination — judged by the same entry rules `unzip` applies
+ * (`zip-entry-rules.ts`), plus one `unzip` does not have: an entry that is a
+ * symbolic LINK is refused outright. A zip stores a link as a member whose
+ * bytes are its target text, so a reader that ignored the mode bits would
+ * write that text out as a file — content nobody sent, under a name that was
+ * meant to point elsewhere.
+ */
+/** The refusal an entry gets when the archive would expand past what one commit lands. */
+function tooLargeToApply(): string {
+  return `This archive expands past the ${APPLY_MAX_TOTAL_BYTES} byte total the apply lands in one commit; this entry was not applied.`;
+}
+
+async function planUpload(
+  upload: ClaimedUpload,
+  destination: string,
+  kbDirName: string,
+): Promise<PlannedUploadPath[]> {
+  const bytes = await nodeFs.readFile(upload.absolutePath);
+  if (upload.kind !== 'zip') {
+    return [{ path: `${destination}/${upload.filename}`, content: bytes }];
+  }
+  let zip: AdmZip;
+  try {
+    zip = new AdmZip(bytes);
+  } catch (err) {
+    throw new ToolError(
+      `"${upload.filename}" could not be opened as a .zip archive: ${err instanceof Error ? err.message : String(err)}`,
+      422,
+      { code: 'unreadable_archive' },
+    );
+  }
+  const planned: PlannedUploadPath[] = [];
+  let seen = 0;
+  let totalBytes = 0;
+  for (const entry of zip.getEntries()) {
+    const rawName = zipEntryName(entry.entryName);
+    if (isZipNoiseEntry(rawName)) continue;
+    if (seen >= APPLY_MAX_ENTRIES) {
+      planned.push({
+        path: rawName || '(empty)',
+        error: 'too_many_entries',
+        message: `This archive holds more than ${APPLY_MAX_ENTRIES} entries; the rest were not applied.`,
+      });
+      continue;
+    }
+    seen++;
+    const nameRefusal = zipEntryNameRefusal(rawName);
+    if (nameRefusal !== null) {
+      planned.push({ path: rawName || '(empty)', error: 'invalid_entry', message: nameRefusal });
+      continue;
+    }
+    if (isSymlinkZipEntry(entry)) {
+      planned.push({
+        path: rawName,
+        error: 'link',
+        message: `"${rawName}" is a symbolic link, not a file; an upload lands files, never links.`,
+      });
+      continue;
+    }
+    // A folder comes into being with the files under it (the write path mkdirs
+    // each parent), so a directory member has nothing of its own to land.
+    if (entry.isDirectory) continue;
+    const segments = zipEntrySegments(rawName);
+    const target = [destination, ...segments].join('/');
+    // Belt and braces: `zipEntryNameRefusal` already refuses a `..` segment
+    // and a root-anchored name, so nothing should reach here that climbs out.
+    // The check stays because the cost of being wrong about that is bytes
+    // landing outside the folder the caller named.
+    if (!target.startsWith(`${destination}/`) || !isInsideRepo(target, kbDirName)) {
+      planned.push({ path: rawName, error: 'invalid_entry', message: 'Path escapes destination' });
+      continue;
+    }
+    // Through the one bounded reader `unzip` uses too, capped at what is left
+    // of the budget: a deflate stream can expand a thousandfold, and the
+    // header's declared size is the archive's claim, not a fact — an entry
+    // declaring ZERO would otherwise be inflated with no cap at all (see
+    // `readZipEntry`). A read that fails is this entry's outcome and no more.
+    const read = readZipEntry(entry, APPLY_MAX_TOTAL_BYTES - totalBytes);
+    if (!read.ok) {
+      planned.push(
+        read.reason === 'too_large'
+          ? { path: rawName, error: 'too_large', message: tooLargeToApply() }
+          : { path: rawName, error: 'unreadable_entry', message: `"${rawName}" could not be read: ${read.detail}.` },
+      );
+      continue;
+    }
+    totalBytes += read.data.byteLength;
+    planned.push({ path: target, content: read.data });
+  }
+  return planned;
+}
+
+/**
+ * Record on `entry` that this path was refused, saying what the gate that
+ * refused it said. Four kinds of refusal count as one path's outcome: a
+ * typed tool refusal (`exists`, `platform_file`, the mode gate), a permission
+ * refusal (the caller may not write this path, where the DESTINATION was
+ * writable), the git folder in any spelling, and a path-shape refusal from the
+ * repository rules. Anything else
+ * is not a verdict about this path — it is a gate failing — so it travels on
+ * and the whole apply fails loudly, exactly as it does in `write_files`.
+ */
+function refuseEntry(entry: Record<string, unknown>, err: unknown): void {
+  entry.outcome = 'refused';
+  if (err instanceof ToolError) {
+    const details = (err.details ?? {}) as { code?: string; kind?: string };
+    entry.error = details.code ?? details.kind ?? 'refused';
+    entry.message = err.message;
+    return;
+  }
+  if (err instanceof AccessDeniedError) {
+    entry.error = 'write-denied';
+    entry.message = err.message;
+    return;
+  }
+  if (err instanceof GitInternalsError || err instanceof WorkflowValidationError) {
+    entry.error = (err.payload as { kind?: string } | undefined)?.kind ?? 'refused';
+    entry.message = err.message;
+    return;
+  }
+  throw err;
+}
+
 /** The three modes, as a set the handler can check a raw argument against. */
 const WRITE_MODES: readonly WriteMode[] = ['create', 'overwrite', 'update'];
 
@@ -591,7 +719,7 @@ async function grepWalk(
   max: number,
   depth: number,
   gate: ReadGate,
-  recordOntologyRead: (path: string) => Promise<void>,
+  notifyRead: (path: string) => Promise<void>,
   docs: DocGrepState,
 ): Promise<void> {
   if (out.length >= max || depth > 12) return;
@@ -610,12 +738,12 @@ async function grepWalk(
     if (e.type !== 'directory' && isFolderPlaceholder(e.name)) continue;
     const p = dir ? `${dir}/${e.name}` : e.name;
     if (e.type === 'directory') {
-      await grepWalk(fs, p, re, out, max, depth + 1, gate, recordOntologyRead, docs);
+      await grepWalk(fs, p, re, out, max, depth + 1, gate, notifyRead, docs);
     } else {
-      // Opening a file under a named ontology is a read of that ontology — even
-      // for a root-level grep that resolves to a neutral root. Record it so a
-      // cross-ontology grep poisons later writes (closes the read-leak).
-      await recordOntologyRead(p);
+      // Opening a file is a read of it, even when the walk started at a root
+      // the read hook was already told about — so every file the walk opens
+      // reaches the hook by name (closes the read-leak).
+      await notifyRead(p);
       // A file the walk cannot read is silently skipped: one unreadable entry
       // must not fail a search over the whole tree.
       try {
@@ -663,6 +791,20 @@ const BATCH_SAVE_WARNINGS_OUTPUT: JsonSchema = {
   items: { type: 'object' },
 };
 
+/**
+ * The `sessionId` property inside a BUILT tool def's input schema, or
+ * `undefined` for a tool that declares none. `toolDef` wraps the flat inputs
+ * under `body` and copies the schema it is given, so a note registered after
+ * the tools were built has to be written here rather than onto the shared
+ * `SESSION_ID_INPUT` constant.
+ */
+function sessionIdInputOf(def: { inputs?: unknown }): { description?: string } | undefined {
+  const inputs = def.inputs as
+    | { properties?: { body?: { properties?: Record<string, { description?: string }> } } }
+    | undefined;
+  return inputs?.properties?.body?.properties?.sessionId;
+}
+
 /**
  * Workspace domain tools: the file primitives (replacing Mastra's auto-injected
  * Workspace tools) + unzip. Most just re-expose the SAME `LocalFilesystem`
@@ -681,7 +823,7 @@ export function registerWorkspaceTools(
   docExtract: DocExtractService,
   accessControl: IAccessControl,
   kb: KbContext,
-  sessionOntologyGate: SessionOntologyGate,
+  agentAccessGate: AgentAccessGate,
   writePolicy: IRoutineWritePolicy,
   sessionSink: ISessionSink,
   /**
@@ -697,6 +839,15 @@ export function registerWorkspaceTools(
    * verdict alone then decides, which differs only at a root.
    */
   changeGate?: IChangeReadGate,
+  /**
+   * The upload-token store behind `request_file_upload` / `apply_file_upload`
+   * — the route an agent lands bytes by, without their content passing
+   * through the model. Optional for the same reason the two above are: a tool
+   * harness that is about the file primitives need not stand one up. Every
+   * real composition wires it (`create-core-server.ts`), and without it the
+   * two tools are not mounted at all rather than mounted and broken.
+   */
+  uploads?: AgentUploadStore,
 ): void {
   const { kbDirName } = kb;
   /**
@@ -780,7 +931,7 @@ export function registerWorkspaceTools(
    * Every spelling first, then the resolved form against the branch's
    * workspace, so a link into the folder is refused the same way. The resolved
    * check only runs on a branch that is already cloned: bootstrapping a clone
-   * here would happen before the handler's access and ontology gates. A branch
+   * here would happen before the handler's access and agent-access gates. A branch
    * not cloned yet (or that does not resolve) is left to the handler; the
    * filesystem refuses again underneath regardless.
    */
@@ -802,7 +953,7 @@ export function registerWorkspaceTools(
    * The branch's workspace root, to judge a spelling against what is on disk
    * — or null when there is nothing to judge it against yet. Only a branch
    * ALREADY cloned is used: bootstrapping one here would clone before the
-   * handler's access and ontology gates have had their say.
+   * handler's access and agent-access gates have had their say.
    */
   const gitCheckRootFor = async (args: Record<string, unknown>, ctx: ToolContext): Promise<string | null> => {
     if (typeof args.branch !== 'string' || args.branch === '') return null;
@@ -865,6 +1016,128 @@ export function registerWorkspaceTools(
     return { read, write, download, owner };
   };
 
+  /** Whether any one of the caller's four verdicts differs between the two sides of a preview. */
+  const verbsDiffer = (before: AccessVerbs, after: AccessVerbs): boolean =>
+    (Object.keys(before) as (keyof AccessVerbs)[]).some((v) => before[v] !== after[v]);
+
+  /**
+   * Why `copy_file` will not take a folder. One sentence, said by the dry
+   * run and by the call itself, so the preflight and the execution never
+   * disagree — the rule this whole section is built on.
+   */
+  const folderCopyRefusal = (src: string): string =>
+    `"${src}" is a folder; copy_file copies one file. Copy its files one by one, or move the folder with move_file.`;
+
+  /**
+   * The caller's verdicts at `dest` as they will be once `src` has been
+   * moved (or, with `sourceRemains`, copied) there — the `after` half of a
+   * move's or copy's preview.
+   *
+   * `accessAt(dest)` is the wrong answer to that question for a folder: the
+   * destination on disk has neither the folder nor the `access.md` files it
+   * carries, so it describes the destination's PARENT. A rename of a folder
+   * that names the caller owner in its own `access.md` therefore warned
+   * about losing owner access the move was about to hand straight back, and
+   * a warning that is wrong is a warning people learn to click through.
+   *
+   * Preview only, like everything else in this section: it answers what the
+   * caller WILL have, never whether they may do it. The write verdicts that
+   * gate the move are `writeBlocked` and the lock gate, both of which read
+   * the tree as it is.
+   */
+  const accessAfter = async (
+    branch: string,
+    ctx: ToolContext,
+    src: string,
+    dest: string,
+    opts?: { sourceRemains?: boolean },
+  ): Promise<AccessVerbs> => {
+    const from = toKbRelative(src, kbDirName);
+    const to = toKbRelative(dest, kbDirName);
+    // Outside the repository there are no rules to carry, and none to land
+    // among — the same answer `accessAt` gives for such a path.
+    if (from === null || to === null) return accessAt(branch, ctx, dest);
+    return accessControl.previewAccessAfterRelocation(
+      workspaceIdForBranch(branch),
+      ctx.user.email,
+      from,
+      to,
+      opts,
+    );
+  };
+
+  /**
+   * What `copy_file`'s dry run answers: the same impact shape `move_file`
+   * previews, over a copy's own rules.
+   *
+   * A copy LEAVES the source where it is, so the rules it carries are
+   * duplicated rather than relocated (`sourceRemains`) — otherwise the two
+   * previews ask the same question. The order of the refusals is `copy_file`'s
+   * own and is load-bearing: the write verdict on the destination outranks
+   * "that name is taken", because a caller who may not write a folder must
+   * not learn what is in it from a refusal.
+   *
+   * A folder source is reported as the refusal it is. `copy_file` copies one
+   * file; the preview says so rather than promising a copy that would fail,
+   * and still answers `access.after` for the folder it was asked about.
+   *
+   * NOTHING is probed on disk until the write verdict on the destination has
+   * been taken — not the destination, and not the source either, which is the
+   * order the call itself keeps at length: a caller who may not write there
+   * gets the same refusal whether the source is a file, a folder, or missing
+   * altogether. Probing the source first put a 404 in front of that 403 and
+   * handed a denied caller the source's kind and its file count. So a refused
+   * preview answers `allowed: false` with the sentence and no `kind` or
+   * `descendants`: those are the half of the impact the caller has to have
+   * earned. The two `access` sides are the caller's own four verbs and tell
+   * them nothing they could not ask `file_stat` for.
+   */
+  const copyImpact = async (branch: string, ctx: ToolContext, src: string, dest: string) => {
+    const [before, after, blocked] = await Promise.all([
+      accessAt(branch, ctx, src),
+      accessAfter(branch, ctx, src, dest, { sourceRemains: true }),
+      writeBlocked(branch, ctx, [dest]),
+    ]);
+    const access = { before, after };
+    const accessChanges = verbsDiffer(before, after);
+    if (blocked.length > 0) {
+      return {
+        src,
+        dest,
+        access,
+        accessChanges,
+        allowed: false,
+        reason: `You may not write "${dest}", so the copy cannot run.`,
+        dryRun: true,
+        copied: false,
+      };
+    }
+    const fs = await ctx.getFilesystem(branch);
+    const kind = await kindOf(fs, src);
+    if (kind === null) throw notFound(src, 'Nothing to copy');
+    const srcFiles = kind === 'folder' ? (await filesUnder(fs, src)).files : [src];
+    const occupiedBy = await existingAt(await workspaceRoot(branch, ctx), dest);
+    const reason = occupiedBy !== null
+      ? entryExistsMessage(occupiedBy, dest)
+      : kind === 'folder'
+        ? folderCopyRefusal(src)
+        : undefined;
+    return {
+      src,
+      dest,
+      kind,
+      // The placeholder travels with its folder, but it is never content —
+      // counted as `move_file` counts it.
+      descendants: srcFiles.filter((f) => !isFolderPlaceholder(f)).length,
+      access,
+      accessChanges,
+      allowed: reason === undefined,
+      ...(reason !== undefined ? { reason } : {}),
+      dryRun: true,
+      copied: false,
+    };
+  };
+
   /**
    * The paths among `paths` the caller may NOT write, judged exactly as the
    * lock gate judges them (`WorkflowService.acquireLock`): on a protected
@@ -1172,6 +1445,14 @@ export function registerWorkspaceTools(
     proposable?: boolean;
     /** False for a tool that is not a file tool (the shell), which the content rule does not describe. */
     fileTool?: boolean;
+    /**
+     * This tool runs through the agent-access gate, so a call to it reaches
+     * the deployment's read or write hook. Such a tool carries the note the
+     * deployment registered ({@link ToolDescriptionNotes}) at the end of its
+     * description — core registers none, so on a core-only deployment the
+     * flag adds nothing to what the agent reads.
+     */
+    gated?: boolean;
     /**
      * This tool resolves `branch` ITSELF and must not be pre-checked here.
      * Only `execute_command` sets it: for an internal session that leaves the
@@ -1184,10 +1465,14 @@ export function registerWorkspaceTools(
     handler: ToolHandler;
   }): void => {
     const path = `/api/agent/tools/${spec.name}`;
-    // Every workspace entrypoint carries the agent-guide reminder, every file
-    // tool the one content rule, and every tool a permission can refuse the
-    // proposal route — appended once here so no tool (especially the
-    // read-only ones a session hits first) can miss them.
+    // Every description ends with ONE sentence pointing at the rules these
+    // tools share — the content rule, the agent guide, the write modes, the
+    // dry-run protocol, the proposal route. They used to be appended here in
+    // FULL, which made a description several thousand characters of text the
+    // agent had already read on the tool above, and clients cut a long
+    // description from the END, where what is specific to the tool sits. The
+    // rules themselves are in the handshake instructions and in the managed
+    // guide (see `shared-file-rules.ts`), stated once and from one text.
     // Whether a call to this tool MUST name a branch, read off the tool's own
     // declaration rather than assumed of the family. Every tool mounted here
     // requires `branch` today; keying on the schema means a tool that declares
@@ -1196,9 +1481,8 @@ export function registerWorkspaceTools(
     const requiresBranch = ((spec.inputs as { required?: string[] }).required ?? []).includes('branch');
     const describe = (): string =>
       (typeof spec.description === 'function' ? spec.description() : spec.description) +
-      (spec.proposable ? PROPOSAL_ROUTE_NOTE : '') +
-      (spec.fileTool === false ? '' : CONTENT_RULE) +
-      kbConventionsNote(kb.layout);
+      (spec.gated ? agentAccessGate.notes.gatedToolNote() : '') +
+      sharedRulesPointer(kb.layout);
     const def = toolDef({
       name: spec.name,
       description: describe(),
@@ -1209,16 +1493,32 @@ export function registerWorkspaceTools(
     });
     registry.registerInternalTool(def);
     if (!spec.internalOnly) registry.registerExternalTool(def);
-    // The catalog FOLLOWS the layout. The conventions reminder above names the
-    // guide, and several descriptions name it again as a platform file, so the
-    // save that completes first-run setup — which applies the names the admin
-    // just chose, in that same request, without a restart — must be able to
-    // move the text with them. Rewritten in place: the registry holds this
-    // object, both surfaces hold the same one, and re-registering would be a
-    // duplicate name.
-    kb.onLayoutApplied(() => {
+    /**
+     * What the agent reads about this tool, rebuilt from whatever is in effect
+     * NOW: the layout's names and the notes the deployment registered.
+     *
+     * The catalog FOLLOWS the layout. The conventions reminder above names the
+     * guide, and several descriptions name it again as a platform file, so the
+     * save that completes first-run setup — which applies the names the admin
+     * just chose, in that same request, without a restart — must be able to
+     * move the text with them. Rewritten in place: the registry holds this
+     * object, both surfaces hold the same one, and re-registering would be a
+     * duplicate name. The `sessionId` input is rewritten on the DEF rather
+     * than on `SESSION_ID_INPUT`, because `toolDef` copies the schema it is
+     * given.
+     */
+    const redescribe = (): void => {
       def.description = describe();
-    });
+      const sessionId = sessionIdInputOf(def);
+      if (sessionId) sessionId.description = agentAccessGate.notes.sessionIdDescription();
+    };
+    // Once for a note registered BEFORE the tools were mounted (the `sessionId`
+    // input is copied by `toolDef`, so it carries the bare default until this
+    // runs), and then on every later change: a note may be registered AFTER
+    // the mount, from the tool-surface hook an overlay registers on.
+    redescribe();
+    kb.onLayoutApplied(redescribe);
+    agentAccessGate.notes.onChange(redescribe);
     // Internal-only tools (e.g. `execute_command`) keep their route mounted —
     // our agent calls it over the same loopback — but gate it to internal-source
     // callers so an external connection key can't invoke it by name.
@@ -1288,22 +1588,20 @@ export function registerWorkspaceTools(
   };
 
   // ── session bootstrap (external agents) ─────────────────────────────────
-  // Every read/write tool below scopes the ontology-session boundary off a
-  // `sessionId`. The in-process agent carries its thread id, but an external
-  // agent has no ambient run id and so cannot satisfy the gate until it has
-  // one. This mints that id up front (called ONCE); the MCP proxy then threads
-  // it onto every later gated call via its sessionId-output continuity
+  // Every read/write tool below takes a `sessionId`: the conversation the
+  // call belongs to, which is what a deployment's hooks scope their rule to.
+  // The in-process agent carries its thread id, but an external agent has no
+  // ambient run id, so this mints one up front (called ONCE); the MCP proxy
+  // then threads it onto every later call via its sessionId-output continuity
   // convention. EXTERNAL-ONLY (not registered internal): the in-process agent
   // already supplies its session id and ignores any body value.
   //
   // WHAT the minted id is backed by is the `ISessionSink` port's business
   // (session-sink.ts). In the enterprise app it is a REAL chat-thread id, so
-  // the SAME id works end to end: KB reads scope the ontology boundary under
-  // it, AND `ask` accepts it (its sessionId IS a chat thread, resolved via
-  // getThread) — that unification is what stops a caller reading from one
-  // ontology and then having `ask` write into another. In a core-only
-  // deployment (no chat/ask) the default sink mints a bare id, which is all
-  // the ontology gate needs.
+  // the SAME id works end to end: the file tools take it AND `ask` accepts it
+  // (its sessionId IS a chat thread, resolved via getThread), so a run's reads
+  // and its questions are one conversation rather than two. In a core-only
+  // deployment (no chat/ask) the default sink mints a bare id.
   //
   // The description tells the caller that retrying is safe, and that is a
   // property of the sink rather than a promise this route makes on its own:
@@ -1316,7 +1614,7 @@ export function registerWorkspaceTools(
   const startSessionDef = toolDef({
     name: 'start_session',
     description:
-      'Mint the KnowledgeBase session id this run needs to read or write the knowledge ontologies. Call this ONCE, before any other KnowledgeBase tool, and only once per run — every gated tool needs the `sessionId` it returns to enforce the one-ontology-per-conversation boundary, and minting a new id mid-run resets that boundary. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: reads and ask then share one ontology boundary. Pass the returned id explicitly as `sessionId` on every subsequent KnowledgeBase tool call (direct MCP calls and inside `call_tool_chain` alike). RETRYING IS SAFE: a call that fails created nothing, so retry it — there is no half-made session to clean up. If a retry lands after a success you simply hold two independent ids, which is harmless: keep passing the one id you have already used for the rest of the run and ignore the other. Returns `{ sessionId }`.',
+      'Mint the id of this conversation, which the KnowledgeBase tools take as `sessionId`. Call this ONCE, at the start of your work and only once per run — minting a new id mid-run starts a second conversation as far as the server is concerned. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: your reads and your questions are then one conversation. Pass the returned id explicitly as `sessionId` on every subsequent KnowledgeBase tool call (direct MCP calls and inside `call_tool_chain` alike). RETRYING IS SAFE: a call that fails created nothing, so retry it — there is no half-made session to clean up. If a retry lands after a success you simply hold two independent ids, which is harmless: keep passing the one id you have already used for the rest of the run and ignore the other. Returns `{ sessionId }`.',
     path: '/api/agent/tools/start_session',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
@@ -1328,12 +1626,12 @@ export function registerWorkspaceTools(
   });
   registry.registerExternalTool(startSessionDef);
   // Mint the session id via the sink and return it (see comment above: one id
-  // spans start_session -> reads -> ask, closing the ontology-pollution gap).
+  // spans start_session -> reads -> ask).
   router.post(
     '/agent/tools/start_session',
     toolAuth,
     // External-only: an internal token already carries its run's sessionId, so
-    // minting a new thread mid-run would reset the ontology boundary. Note
+    // minting a new thread mid-run would split one run in two. Note
     // "external" includes the MCP proxy's `externalProxy` loopback tokens
     // (OAuth/JWT MCP sessions) — the verifier resolves those to
     // `source: 'external'`, and one such session may legitimately mint several
@@ -1348,9 +1646,15 @@ export function registerWorkspaceTools(
   // ── reads ──────────────────────────────────────────────────────────────
   mount({
     name: 'read_file',
+    gated: true,
     description:
-      'Read a workspace file as text. Returns `{ path, content }`. Images (.png/.jpg/.jpeg/.gif/.webp) return the IMAGE ITSELF as native MCP image content (plus a one-line text note naming the file), so you can look at the picture — up to 3.5 MB of raw image data; a larger image gets an honest refusal asking for a locally downscaled copy or a smaller export (`.svg` is text and reads as text). Images come back only on a DIRECT call: inside `call_tool_chain` an image read yields an `{ image_omitted, note }` stub instead. Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods) and PDFs return their EXTRACTED text under an honest `[extracted text of …]` header, with `[slide N]`/`[sheet: Name]`/`[page N]` markers — the extraction is READ-ONLY (layout/images omitted; such files cannot be edited as text, only replaced by uploading a new version). Email files (.eml/.msg) return their EXTRACTED text the same way: a `[from]`/`[to]`/`[subject]`/`[date]` header block, the body (plain-text part preferred; an HTML-only body is stripped to text), and an `[attachments]` name list — attachments are listed, never extracted. Other binary files return a one-line description instead of raw bytes. Optional `offset`/`limit` slice the content (characters for a file, bytes for a `__tool_chain_spill__/…` ref; ignored for an image) — use them to page through large files or a `call_tool_chain` spill rather than reading multi-MB in full. A spill ref is workspace-independent: `branch` is ignored for it.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      'Read a workspace file as text. Returns `{ path, content }`. What comes back for a document, an email file, an image ' +
+      'or any other binary file is the content rule\'s business (see the shared rules): text files as text, documents and ' +
+      'email files as extracted text, an image as the picture itself, anything else as a one-line description. ' +
+      'Optional `offset`/`limit` slice the content (characters for a file, bytes for a `__tool_chain_spill__/…` ref; ignored ' +
+      'for an image) — use them to page through large files or a `call_tool_chain` spill rather than reading multi-MB in full. ' +
+      'It also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: such a ref belongs to no ' +
+      'workspace, so `branch` is ignored for it.',
     inputs: {
       type: 'object',
       properties: {
@@ -1376,12 +1680,12 @@ export function registerWorkspaceTools(
       if (spillStore.isSpillRef(p)) {
         return { path: p, content: await spillStore.read(p, offset, limit) };
       }
-      await recordOntologyRead(sessionOntologyGate, ctx, p);
+      await notifyAgentRead(agentAccessGate, ctx, a.branch as string, p);
       await assertCanRead(readGateFor(a.branch as string, ctx), p);
       const fs = await ctx.getFilesystem(a.branch as string);
       // Reading (extraction, image and binary handling included) happens AFTER
-      // the access gate and the ontology-read recording above — a document
-      // read is still a KB read. ONE registry dispatch picks the reader by
+      // the access gate and the read hook above — a document read is still a
+      // KB read. ONE registry dispatch picks the reader by
       // extension; everything below just maps its ReadResult onto the tool's
       // result shape.
       const bytes = await orNotFound(p, async () => asBytes(await fs.readFile(p)));
@@ -1414,9 +1718,9 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'list_files',
+    gated: true,
     description:
-      `List a directory. Returns \`{ path, entries: [{ name, type, size? }] }\`. Omit \`path\` for the workspace root, which holds the repository as the \`${kbDirName}/\` folder: every content path is under it (e.g. \`${kbDirName}/KnowledgeBase\`), and a path given without that prefix is placed under it.` +
-      ONTOLOGY_BOUNDARY_NOTE,
+      `List a directory. Returns \`{ path, entries: [{ name, type, size? }] }\`. Omit \`path\` for the workspace root, which holds the repository as the \`${kbDirName}/\` folder: every content path is under it (e.g. \`${kbDirName}/KnowledgeBase\`), and a path given without that prefix is placed under it.`,
     inputs: {
       type: 'object',
       properties: {
@@ -1446,7 +1750,7 @@ export function registerWorkspaceTools(
     write: false,
     handler: async (a, ctx: ToolContext) => {
       const dir = (a.path as string) || '';
-      await recordOntologyRead(sessionOntologyGate, ctx, dir);
+      await notifyAgentRead(agentAccessGate, ctx, a.branch as string, dir);
       const fs = await ctx.getFilesystem(a.branch as string);
       const entries = withoutPlaceholder((await fs.readdir(dir || '.')) as DirEntry[]);
       const filtered = await filterReadableEntries(readGateFor(a.branch as string, ctx), dir, entries);
@@ -1456,14 +1760,19 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'file_stat',
-    description: () =>
-      'Get a file/directory\'s metadata (name, type, size, …) without returning content. A file also reports `contentMode`: `text` (read, write and edit it as text), `document` (read returns an extraction; replace it by upload) or `binary` (bytes: copy, move, delete, or replace by upload), plus `kind` (`text` | `document` | `image` | `binary`), `mime`, `mimeSource` and `textEditable` — decided by the same file readers read_file, grep and the write tools use, so an extensionless text file is `text/plain`.' +
-      ' Every entry also reports what you may DO with it. ' +
-      `\`managed\` is true for a platform item — a platform file (${platformFileList(kb.layout)}) or a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`); managed items are never movable or deletable through these tools. ` +
-      '`access: { read, write, download, owner }` is your own verdict under the access rules; pass `explainAccess: true` to learn why, and who else holds each verb. `movable` and `deletable` say whether `move_file` / `delete_file` / `delete_folder` would be allowed for you, judged like their dry runs: not managed, no symbolic link, and on a protected branch you hold write on the item AND on every file under a folder (on a draft branch writes are not gated). `movable` judges the source side only; the destination is judged by a `move_file` dry run. ' +
-      'For a folder, `descendants` is the number of files under it at any depth; counting stops at 10000 and `descendantsTruncated` says so, and past that point `movable` and `deletable` are false because a folder that large was not judged in full — run the `move_file` or `delete_folder` dry run for the real verdict. ' +
-      'Call this before a move or delete to see what it would touch.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+    gated: true,
+    description:
+      'Get a file/directory\'s metadata (name, type, size, …) without returning content, and what you may DO with it. ' +
+      'A file also reports `contentMode`, `kind`, `mime`, `mimeSource` and `textEditable` — decided by the same readers ' +
+      'read_file, grep and the write tools use, so an extensionless text file is `text/plain`. ' +
+      '`access: { read, write, download, owner }` is your own verdict under the access rules; pass `explainAccess: true` to ' +
+      'learn why, and who else holds each verb. ' +
+      'Call this before a move or delete: `managed`, `movable` and `deletable` answer the shared rules on what these tools ' +
+      'never move or delete, judged like the dry runs (on a draft branch writes are not gated); `movable` judges the SOURCE ' +
+      'side only, so the destination still wants a `move_file` dry run. ' +
+      'For a folder, `descendants` counts the files under it at any depth; counting stops at 10000 and ' +
+      '`descendantsTruncated` says so, past which `movable` and `deletable` are false — a folder that large was not judged ' +
+      'in full, so run the `move_file` or `delete_folder` dry run for the real verdict.',
     inputs: {
       type: 'object',
       properties: {
@@ -1539,7 +1848,7 @@ export function registerWorkspaceTools(
     handler: async (a, ctx: ToolContext) => {
       const p = a.path as string;
       const branch = a.branch as string;
-      await recordOntologyRead(sessionOntologyGate, ctx, p);
+      await notifyAgentRead(agentAccessGate, ctx, branch, p);
       await assertCanRead(readGateFor(branch, ctx), p);
       // Nothing there is a 404, and the placeholder — never content — gets
       // exactly that answer: the one every file tool gives (see not-found.ts).
@@ -1640,9 +1949,9 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'grep',
+    gated: true,
     description:
-      'Regex content search across the workspace. Returns `{ matches: [{ path, line, text }] }` (capped). Use to find where something is defined/referenced. `path` may name a DIRECTORY (searches the subtree) or a single FILE (searches just that file); a path with nothing at it is an error, never an empty result. Searches INSIDE Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods), PDFs and email files (.eml/.msg) via their extracted text — matches there carry the extraction\'s line numbers, and the `[slide N]`/`[sheet: Name]`/`[page N]`/`[from]`/`[subject]` marker lines locate them; a bounded number of not-yet-extracted documents is extracted per call, and the result notes how many were skipped (re-run to cover them).' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      'Regex content search across the workspace. Returns `{ matches: [{ path, line, text }] }` (capped). Use to find where something is defined/referenced. `path` may name a DIRECTORY (searches the subtree) or a single FILE (searches just that file); a path with nothing at it is an error, never an empty result. Searches INSIDE Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods), PDFs and email files (.eml/.msg) via their extracted text — matches there carry the extraction\'s line numbers, and the `[slide N]`/`[sheet: Name]`/`[page N]`/`[from]`/`[subject]` marker lines locate them; a bounded number of not-yet-extracted documents is extracted per call, and the result notes how many were skipped (re-run to cover them).',
     inputs: {
       type: 'object',
       properties: {
@@ -1692,11 +2001,10 @@ export function registerWorkspaceTools(
       // (an empty path is the handler's to explain), and here it would
       // otherwise name the workspace directory by another spelling.
       const searchRoot = typeof a.path === 'string' && a.path.length > 0 ? a.path : kbDirName;
-      // The search root itself is checked here (fail-closed for an agent grep on
-      // a named subtree with no sessionId); each file the walk actually opens is
-      // recorded per-file below, so a root-level grep that reaches into multiple
-      // ontologies still records each one (and can poison later writes).
-      await recordOntologyRead(sessionOntologyGate, ctx, searchRoot);
+      // The search root itself goes to the read hook here; each file the walk
+      // actually opens goes to it per-file below, so a hook sees every path a
+      // grep reached rather than only the root it started from.
+      await notifyAgentRead(agentAccessGate, ctx, a.branch as string, searchRoot);
       const fs = await ctx.getFilesystem(a.branch as string);
       const gate = readGateFor(a.branch as string, ctx);
       const out: { path: string; line: number; text: string }[] = [];
@@ -1723,7 +2031,7 @@ export function registerWorkspaceTools(
           max,
           0,
           gate,
-          (p) => recordOntologyRead(sessionOntologyGate, ctx, p),
+          (p) => notifyAgentRead(agentAccessGate, ctx, a.branch as string, p),
           docs,
         );
       } else {
@@ -1768,12 +2076,11 @@ export function registerWorkspaceTools(
   // ── writes (through the lock/commit pipeline) ───────────────────────────
   mount({
     name: 'write_file',
+    gated: true,
     description:
       'Write a workspace TEXT file. The change is committed + pushed as you. Returns `{ path, bytes, outcome }`, where `outcome` is ' +
       '`created`, `replaced` or `updated`.' +
-      WRITE_MODE_NOTE +
-      IMAGE_CONVENTION_NOTE +
-      ONTOLOGY_BOUNDARY_NOTE,
+      UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
       properties: {
@@ -1809,7 +2116,7 @@ export function registerWorkspaceTools(
       // (today only `watchlist_check`, to `.html`). Unrestricted sessions pass straight
       // through (see `assertPathWritable`), so it does not limit other agents.
       writePolicy.assertPathWritable(ctx.sessionId, a.path as string);
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path as string);
+      await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch as string, a.path as string);
       const mode = modeOf(a);
       const fs = await ctx.getFilesystem(a.branch as string);
       await assertNotBinaryOverwrite(readers,a.path as string, fs);
@@ -1851,18 +2158,17 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'write_files',
+    gated: true,
     description:
       'Batch-write many files in ONE commit — far faster than calling write_file once per file when ' +
       'creating many files at once (e.g. seeding a knowledge base). Each entry is `{ path, content }`, and the files it ' +
       'writes are committed + pushed together as you. Prefer this over many write_file ' +
-      'calls. All files must be in the SAME ontology (the boundary below applies to the batch). Text files only. ' +
+      'calls. Text files only. ' +
       'Returns `{ count, files }`: one entry per REQUESTED path, in the order you gave them, each `{ path, outcome }` — ' +
       '`created` / `replaced` / `updated` for a path it wrote, or `refused` with `error` (the code) and `message` (why) for a ' +
       'path it could not. `count` is how many were written. A path it refuses — the mode said no, or the file is not text — ' +
       'does not stop the others; read `files` to see what landed.' +
-      WRITE_MODE_NOTE +
-      IMAGE_CONVENTION_NOTE +
-      ONTOLOGY_BOUNDARY_NOTE,
+      UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
       properties: {
@@ -1915,13 +2221,13 @@ export function registerWorkspaceTools(
       const files = (a.files as Array<{ path: string; content: string }>) ?? [];
       if (files.length === 0) return { count: 0, files: [] };
       const mode = modeOf(a);
-      // The POLICY gates still judge the whole batch: a restricted run or a
-      // cross-ontology batch is a call that should not have been made at all,
-      // not a per-path outcome, and the ontology gate must see every path
-      // before anything lands. What a single FILE is (not text) or what its
-      // path already holds (the mode) is decided per path, below.
+      // The POLICY gate still judges the whole batch: a restricted run is a
+      // call that should not have been made at all, not a per-path outcome.
+      // The write hook is asked PER PATH, below, so a path it refuses is that
+      // path's outcome and the rest of the batch still lands. What a single
+      // FILE is (not text) or what its path already holds (the mode) is
+      // decided per path too.
       for (const f of files) writePolicy.assertPathWritable(ctx.sessionId, f.path);
-      for (const f of files) await assertOntologyWriteAllowed(sessionOntologyGate, ctx, f.path);
       const fs = await ctx.getFilesystem(a.branch as string);
       // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands the
       // batch as one commit. Structural cast avoids a workflow-internal import.
@@ -1950,6 +2256,18 @@ export function registerWorkspaceTools(
       for (const f of files) {
         const entry: Record<string, unknown> = { path: f.path };
         outcomes.push(entry);
+        try {
+          await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch as string, f.path);
+        } catch (err) {
+          // A DELIBERATE refusal by the deployment's write hook is this path's
+          // outcome and no more: its message is what the caller is meant to
+          // read, and one refused path must not take the others down. Anything
+          // else the hook throws is not a verdict — it is the gate itself
+          // failing — so `refuse` rethrows it and the whole batch fails loudly,
+          // exactly as it does in `write_file`.
+          refuse(entry, err);
+          continue;
+        }
         try {
           assertNotDocumentEdit(readers, f.path);
           await assertNotBinaryOverwrite(readers, f.path, fs);
@@ -2017,9 +2335,10 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'edit_file',
+    gated: true,
     description:
       'Replace an exact string in a workspace TEXT file. `old_string` must appear exactly once unless `replace_all`. Committed + pushed as you.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      UPLOAD_ROUTE_NOTE,
     inputs: {
       type: 'object',
       properties: {
@@ -2043,7 +2362,7 @@ export function registerWorkspaceTools(
     handler: async (a, ctx: ToolContext) => {
       assertNotDocumentEdit(readers, a.path as string);
       writePolicy.assertPathWritable(ctx.sessionId, a.path as string);
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path as string);
+      await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch as string, a.path as string);
       const fs = await ctx.getFilesystem(a.branch as string);
       const path = a.path as string;
       const oldStr = a.old_string as string;
@@ -2067,10 +2386,9 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'delete_file',
-    description: () =>
-      'Delete ONE workspace file (a symbolic link is refused: links are never followed or removed). Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`. ' +
-      `A platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${kb.layout.agentsFile}\` at the repository root) and git metadata are refused.` +
-      ONTOLOGY_BOUNDARY_NOTE,
+    gated: true,
+    description:
+      'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.',
     inputs: {
       type: 'object',
       properties: {
@@ -2089,14 +2407,14 @@ export function registerWorkspaceTools(
     write: true,
     proposable: true,
     handler: async (a, ctx: ToolContext) => {
-      // A delete propagates no cross-ontology information (it removes a node, it
-      // doesn't carry bytes from elsewhere), so it is NOT ontology-write-gated — it
-      // only records the ontology it touched, like a read. The extension policy
-      // DOES apply though: a dashboard-only run must not delete graph `.md` nodes.
+      // A delete carries no bytes from anywhere else — it removes a node — so
+      // it goes to the READ hook, like a read, not the write hook. The
+      // extension policy DOES apply though: a dashboard-only run must not
+      // delete graph `.md` nodes.
       const path = a.path as string;
       const branch = a.branch as string;
       writePolicy.assertPathWritable(ctx.sessionId, path);
-      await recordOntologyRead(sessionOntologyGate, ctx, path);
+      await notifyAgentRead(agentAccessGate, ctx, branch, path);
       const fs = await ctx.getFilesystem(branch);
       assertPlainPath(path);
       const root = await workspaceRoot(branch, ctx);
@@ -2120,13 +2438,15 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'delete_folder',
+    gated: true,
     description:
       'Delete a workspace FOLDER and every file under it, at any depth; the whole folder lands as ONE committed + pushed change as you — all of it or none of it — then the empty folder is removed. This is the one way a folder goes away: the folder that held it stays, even if this was all it had, and a folder holding nothing but its empty-folder placeholder counts as empty. ' +
-      'Preflight first: `dryRun: true` changes nothing and answers `{ path, kind: "folder", descendants, files, filesTruncated, allowed, reason? }` — `descendants` is the file count, `files` names up to 100 of them. ' +
-      'A non-empty folder is deleted only with `confirm: true`; without it the call deletes nothing and returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — dry-run, check the impact, then confirm. ' +
-      'Refused (in a dry run as `allowed: false` with the `reason`): a platform folder (the repository root or a reserved root folder such as `KnowledgeBase/`), git metadata, a folder holding a symbolic link (links are never removed), and a folder holding any file you may not write. A path that is a file is refused with a pointer to `delete_file`, and a path through a symbolic link is refused (links are never followed). ' +
-      'The folder\'s own platform files (`access.md`, `.bevelignore`) go with it in that same one change, so its files are never left ungoverned part-way; you must be able to write those platform files too.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      'The dry run answers `{ path, kind: "folder", descendants, files, filesTruncated, allowed, reason? }` — `descendants` is ' +
+      'the file count, `files` names up to 100 of them — and a non-empty folder wants `confirm: true`. ' +
+      'Beyond what the shared rules refuse, a folder HOLDING a symbolic link, or any file you may not write, is refused ' +
+      '(the link itself is never removed), and a path that is a FILE ' +
+      'is refused with a pointer to `delete_file`. You must be able to write the folder\'s own platform files too: they go ' +
+      'with it in that same one change, so its files are never left ungoverned part-way.',
     inputs: {
       type: 'object',
       properties: {
@@ -2164,7 +2484,7 @@ export function registerWorkspaceTools(
       // The normaliser has already placed the path inside the repository; this
       // is the check that it really is in there before a folder is walked.
       assertInsideRepo(path, kbDirName);
-      await recordOntologyRead(sessionOntologyGate, ctx, path);
+      await notifyAgentRead(agentAccessGate, ctx, branch, path);
       const fs = await ctx.getFilesystem(branch);
       const kind = await kindOf(fs, path);
       if (kind === null) throw new ToolError(`"${path}" does not exist.`, 404);
@@ -2259,7 +2579,8 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'mkdir',
-    description: 'Create a directory (recursive). It lists as an empty folder and persists in git until it is deleted explicitly.' + ONTOLOGY_BOUNDARY_NOTE,
+    gated: true,
+    description: 'Create a directory (recursive). It lists as an empty folder and persists in git until it is deleted explicitly.',
     inputs: {
       type: 'object',
       properties: {
@@ -2279,7 +2600,7 @@ export function registerWorkspaceTools(
     proposable: true,
     handler: async (a, ctx: ToolContext) => {
       writePolicy.assertPathWritable(ctx.sessionId, a.path as string);
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path as string);
+      await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch as string, a.path as string);
       await (await ctx.getFilesystem(a.branch as string)).mkdir(a.path as string, { recursive: true });
       return { path: a.path, created: true };
     },
@@ -2287,12 +2608,16 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'move_file',
-    description: () =>
+    gated: true,
+    // A plain string again: what refuses a move names the guide, and that is in
+    // the shared rules now, which are rebuilt from the layout where they live.
+    description:
       'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Lands as a delete + create, committed + pushed as you. ' +
-      `Rules: the destination must not exist — a move never overwrites a file or merges into a folder; a platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${kb.layout.agentsFile}\` at the repository root) is refused with "<name> is a platform file and stays in its folder." — a folder that moves takes its own platform files along, still in their folder; a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`) and git metadata are refused; a move cannot create a platform file or folder at \`dest\` either (renaming a note to \`access.md\` is refused); a path through a symbolic link is refused, since links are never followed; on a protected branch you must be able to write both ends — for a folder, every file under it at its old and its new path. ` +
-      'Access follows the destination folder. Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination. ' +
-      'A move whose `accessChanges` is true runs only with `confirm: true`; without it the call moves nothing and returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — dry-run, check the impact, then confirm.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      'The destination must not exist — a move never overwrites a file or merges into a folder. Access follows the ' +
+      'DESTINATION folder, so a move can change what you (and others) may do with the file: the dry run answers ' +
+      '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }`, where `access` is your ' +
+      'own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the move has landed, ' +
+      'with every `access.md` inside a moved folder counted at its new place, and a move whose `accessChanges` is true wants `confirm: true`.',
     inputs: {
       type: 'object',
       properties: {
@@ -2313,8 +2638,8 @@ export function registerWorkspaceTools(
         dest: str('Destination path (echoes the input).'),
         kind: str('`file` or `folder`.'),
         descendants: int('Files that move: 1 for a file, the file count under a folder.'),
-        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and destination (`after`).' },
-        accessChanges: { type: 'boolean', description: 'True when any of your verdicts differs between source and destination.' },
+        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the move has landed (`after`).' },
+        accessChanges: { type: 'boolean', description: 'True when any of your verdicts differs between `before` and `after`.' },
         allowed: { type: 'boolean', description: 'Whether the move may run.' },
         reason: str('Why it may not, when `allowed` is false.'),
         dryRun: { type: 'boolean', description: 'True on a dry run.' },
@@ -2332,12 +2657,12 @@ export function registerWorkspaceTools(
       const src = (a.src as string).replace(/\/+$/, '');
       const dest = (a.dest as string).replace(/\/+$/, '');
       const branch = a.branch as string;
-      // A move CARRIES the source content into the destination — a genuine
-      // cross-ontology flow if the two differ — so BOTH endpoints are write-gated
-      // (unlike a plain delete, which moves no content). Check both BEFORE
-      // touching disk so a blocked endpoint can't leave the source already deleted.
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, src);
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, dest);
+      // A move CARRIES the source content into the destination, so BOTH ends
+      // go to the write hook (unlike a plain delete, which moves no content).
+      // Ask about both BEFORE touching disk, so a refused end can't leave the
+      // source already deleted.
+      await assertAgentWriteAllowed(agentAccessGate, ctx, branch, src);
+      await assertAgentWriteAllowed(agentAccessGate, ctx, branch, dest);
       const fs = await ctx.getFilesystem(branch);
       const root = await workspaceRoot(branch, ctx);
       // Before the kind check, which stats THROUGH a link: a dangling link at
@@ -2354,8 +2679,13 @@ export function registerWorkspaceTools(
         writePolicy.assertPathWritable(ctx.sessionId, dest + f.slice(src.length));
       }
 
-      const [before, after] = await Promise.all([accessAt(branch, ctx, src), accessAt(branch, ctx, dest)]);
-      const accessChanges = (Object.keys(before) as (keyof AccessVerbs)[]).some((v) => before[v] !== after[v]);
+      // `after` is the destination as it WILL be — with the `access.md` files
+      // under `src` counted where they land. See `accessAfter`.
+      const [before, after] = await Promise.all([
+        accessAt(branch, ctx, src),
+        accessAfter(branch, ctx, src, dest),
+      ]);
+      const accessChanges = verbsDiffer(before, after);
       // The placeholder moves with its folder, but it is never content.
       const descendants = srcFiles.filter((f) => !isFolderPlaceholder(f)).length;
       // Neither end may be the platform's own: a move neither takes a platform
@@ -2448,15 +2778,18 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'copy_file',
+    gated: true,
     description:
-      'Copy a workspace file to a new path. The destination must not exist — like a move, a copy never overwrites a file or a folder; to change what is in a file that already exists, write it. Committed + pushed as you.'
-      + ONTOLOGY_BOUNDARY_NOTE,
+      'Copy a workspace FILE to a new path. The destination must not exist — like a move, a copy never overwrites a file or a folder; to change what is in a file that already exists, write it. Committed + pushed as you. ' +
+      'Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the copy has landed, with every `access.md` inside a copied folder counted at its new place. ' +
+      'One exception to that shape: when the destination is one you may not write, the answer is the refusal alone — `allowed: false` with `reason`, and no `kind` and no `descendants`, because nothing about the source is read before that verdict.',
     inputs: {
       type: 'object',
       properties: {
         branch: BRANCH_INPUT,
         src: wsPath(kbDirName, 'Source path'),
         dest: wsPath(kbDirName, 'Destination path — must not exist yet'),
+        dryRun: { type: 'boolean', description: 'Answer with the impact and change nothing.' },
         sessionId: SESSION_ID_INPUT,
       },
       required: ['branch', 'src', 'dest'],
@@ -2464,20 +2797,30 @@ export function registerWorkspaceTools(
     },
     outputs: {
       type: 'object',
-      properties: { src: str('Source path (echoes the input).'), dest: str('Destination path (echoes the input).'), copied: { type: 'boolean', description: 'Always true on success.' } },
+      properties: {
+        src: str('Source path (echoes the input).'),
+        dest: str('Destination path (echoes the input).'),
+        kind: str('`file` or `folder` (dry run only; absent when `allowed` is false because you may not write the destination).'),
+        descendants: int('Files the copy would carry: 1 for a file, the file count under a folder (dry run only; absent when `allowed` is false because you may not write the destination).'),
+        access: { type: 'object', description: 'Your `{ read, write, download, owner }` at the source (`before`) and at the destination once the copy has landed (`after`) — dry run only.' },
+        accessChanges: { type: 'boolean', description: 'True when any of your verdicts differs between `before` and `after` (dry run only).' },
+        allowed: { type: 'boolean', description: 'Whether the copy may run (dry run only).' },
+        reason: str('Why it may not, when `allowed` is false.'),
+        dryRun: { type: 'boolean', description: 'True on a dry run.' },
+        copied: { type: 'boolean', description: 'True once the copy landed; false on a dry run.' },
+      },
       required: ['src', 'dest', 'copied'],
     },
     write: true,
     proposable: true,
     handler: async (a, ctx: ToolContext) => {
-      // A copy CARRIES the source content into the destination — a genuine
-      // cross-ontology flow if the two differ — so BOTH endpoints are write-gated.
-      // Check both before touching disk.
+      // A copy CARRIES the source content into the destination, so BOTH ends
+      // go to the write hook. Ask about both before touching disk.
       writePolicy.assertPathWritable(ctx.sessionId, a.src as string);
       writePolicy.assertPathWritable(ctx.sessionId, a.dest as string);
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.src as string);
-      await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.dest as string);
       const branch = a.branch as string;
+      await assertAgentWriteAllowed(agentAccessGate, ctx, branch, a.src as string);
+      await assertAgentWriteAllowed(agentAccessGate, ctx, branch, a.dest as string);
       const src = a.src as string;
       const dest = a.dest as string;
       // A copy lands bytes at a name of its own, so it is refused by the same
@@ -2489,6 +2832,7 @@ export function registerWorkspaceTools(
       // own containment check: a path with a `..` segment must not reach
       // `lstat` outside the workspace, even to be told a name is taken.
       assertPlainPath(dest);
+      if (a.dryRun === true) return copyImpact(branch, ctx, src, dest);
       // The write verdict comes FIRST, for the reason `move_file` gives at
       // length: "already exists" is a fact about the destination folder, and a
       // caller who may not write there must not be told it. The lock gate
@@ -2525,6 +2869,12 @@ export function registerWorkspaceTools(
       try {
         await asEntryExists(() => fs.copyFile(src, dest));
       } catch (err) {
+        // The filesystem's own "that is a directory" becomes the sentence the
+        // dry run predicts, instead of escaping as a 500 carrying the
+        // server's absolute path.
+        if ((err as { name?: string } | null)?.name === 'IsDirectoryError') {
+          throw new ToolError(folderCopyRefusal(src), 400);
+        }
         const missing = isAbsence(err) || (err as { name?: string }).name === 'FileNotFoundError';
         if (missing) {
           throw (await kindOf(fs, src)) === null
@@ -2539,9 +2889,9 @@ export function registerWorkspaceTools(
 
   mount({
     name: 'unzip',
+    gated: true,
     description:
-      'Extract a .zip already in the workspace (defaults to the zip\'s parent). Returns extracted files + skipped entries. Existing files are overwritten.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      'Extract a .zip already in the workspace (defaults to the zip\'s parent). Returns extracted files + skipped entries. Existing files are overwritten.',
     inputs: {
       type: 'object',
       properties: {
@@ -2573,9 +2923,9 @@ export function registerWorkspaceTools(
     write: true,
     handler: async (a, ctx: ToolContext) => {
       const zipPath = a.path as string;
-      // Reading the source archive pins/records the source ontology, so a session
-      // can't unzip from ontology A into ontology B without the A read counting.
-      await recordOntologyRead(sessionOntologyGate, ctx, zipPath);
+      // Opening the archive is a read of the archive, so the read hook hears
+      // about it before a single entry is extracted out of it.
+      await notifyAgentRead(agentAccessGate, ctx, a.branch as string, zipPath);
       // A .zip that is not there is a missing PATH, not an unreadable archive:
       // the service now says so (PathNotFoundError) and the helper turns it
       // into the same 404 every other file tool answers. Only that declared
@@ -2587,10 +2937,10 @@ export function registerWorkspaceTools(
             workspaceIdForBranch(a.branch as string),
             zipPath,
             typeof a.destination === 'string' ? a.destination : undefined,
-            // Each extracted file is a write: a cross-ontology or write-blocked entry
-            // is skipped (not extracted), so an archive can't bypass the boundary — the
-            // extension policy applies per entry too, so a restricted run can't unzip a
-            // `.md` into the graph.
+            // Each extracted file is a write of its own: an entry the write
+            // hook refuses is skipped (not extracted), so an archive can't be
+            // a way around it — the extension policy applies per entry too, so
+            // a restricted run can't unzip a `.md` into the graph.
             (wsRelPath) => {
               // An entry that would land beside the repository is skipped with the
               // corrected-path reason, like any other refused entry.
@@ -2604,7 +2954,7 @@ export function registerWorkspaceTools(
                 );
               }
               writePolicy.assertPathWritable(ctx.sessionId, wsRelPath);
-              return assertOntologyWriteAllowed(sessionOntologyGate, ctx, wsRelPath);
+              return assertAgentWriteAllowed(agentAccessGate, ctx, a.branch as string, wsRelPath);
             },
           ),
         'Nothing to extract',
@@ -2612,12 +2962,341 @@ export function registerWorkspaceTools(
     },
   });
 
+  // ── uploads (bytes that never pass through the model) ───────────────────
+  //
+  // The pair exists because MCP tool arguments are JSON. Every byte an agent
+  // sends through `write_file` is first typed out by the model, which
+  // truncates long files, mangles backslash and `\u` escapes, and cannot carry
+  // a PNG at all. `request_file_upload` answers an address; the agent POSTs
+  // the file (or one zip holding many) there with any HTTP client;
+  // `apply_file_upload` lands it on a branch in one commit. The bytes go from
+  // the agent's disk to the server's and never enter a prompt.
+  //
+  /**
+   * Why one of an upload's paths may not be landed, judged on the path ALONE —
+   * or undefined when nothing about the name itself refuses it.
+   *
+   * The platform files are the whole of it. `access.md` governs who may read
+   * and write the folder it sits in, `roles.yaml` says which roles exist, and
+   * the agent guide is read as instructions: each is configuration the platform
+   * obeys, and each has a write path that CHECKS the change (the roles gate
+   * refuses an edit that would lock every admin out; a folder's access rules
+   * are judged against who is asking). Bytes arriving by upload meet none of
+   * those gates — they are a buffer the sender chose — so an upload never
+   * lands one, whatever else the caller may write. `unzip` has refused
+   * `roles.yaml` from an archive for the same reason; this is that rule, over
+   * all four names.
+   */
+  const platformFileReason = (wsPath: string): string | undefined => {
+    const rel = toKbRelative(wsPath, kbDirName);
+    return rel !== null && isPlatformFile(rel, kb.layout) ? platformFileUploadRefusal(rel) : undefined;
+  };
+
+  /**
+   * `apply_file_upload`'s handler: resolve the stored bytes into one path per
+   * file, judge each path the way `write_files` judges its own, and land the
+   * survivors as ONE commit.
+   *
+   * The judging is deliberately the same shape as `write_files`, down to the
+   * second verdict under the lock, because the promise the ticket makes is
+   * that an upload is judged "exactly as `write_file` would judge it". Three
+   * gates run per path and a path that fails one is that path's outcome and no
+   * more: the deployment's write hook, the platform-file rule above, and the
+   * `mode`. What is judged ONCE for the whole call is the destination — a
+   * caller who may not write the folder at all gets one refusal naming the
+   * change-request route, rather than the same refusal repeated per entry.
+   */
+  const applyFileUpload = async (
+    a: Record<string, unknown>,
+    ctx: ToolContext,
+    uploads: AgentUploadStore,
+  ): Promise<unknown> => {
+    const branch = a.branch as string;
+    const token = a.token;
+    if (typeof token !== 'string' || token === '') {
+      throw new ToolError(
+        'Name the `token` `request_file_upload` answered with, after POSTing the file to its `uploadUrl`.',
+        400,
+        { code: 'token-required' },
+      );
+    }
+    const mode = modeOf(a);
+    const destination = (a.destination as string).replace(/\/+$/, '');
+    assertInsideRepo(destination, kbDirName);
+    // CLAIMED, not consumed: an apply refused whole (a protected destination,
+    // an archive that will not open) leaves the token alive so the caller can
+    // retry somewhere else rather than send the bytes again. The claim is what
+    // keeps it single-use meanwhile — a second apply finds the token in use.
+    const upload = uploads.claim(token, ctx.user.id);
+    let spent = false;
+    try {
+      const fs = await ctx.getFilesystem(branch);
+      const root = await workspaceRoot(branch, ctx);
+      // The destination, once, for the whole call. On a protected branch a
+      // caller who may not write the folder gets the lock gate's own refusal —
+      // which `rethrowAsWriteDenial` turns into `write-denied` with the
+      // change-request steps — and nothing lands.
+      const blockedDest = await writeBlocked(branch, ctx, [destination]);
+      if (blockedDest.length > 0) throw await writeRefusal(branch, blockedDest[0], 'dir');
+      if ((await kindOf(fs, destination)) === 'file') {
+        throw new ToolError(
+          `"${displayPath(destination)}" is a file, not a folder — \`destination\` names the folder the upload lands in.`,
+          409,
+          { code: 'not_a_folder' },
+        );
+      }
+
+      const planned = await planUpload(upload, destination, kbDirName);
+      const paths = planned.filter((p) => p.content !== undefined).map((p) => p.path as string);
+      // One batched access read for every path, like `write_files` — empty on
+      // a draft branch, where changes reach a protected branch only through a
+      // change request.
+      const blocked = new Set(await writeBlocked(branch, ctx, paths));
+
+      const writes: { path: string; content: Buffer }[] = [];
+      const outcomes: Record<string, unknown>[] = [];
+      /** The `files` entry for `writes[i]`, so the under-lock verdict can revise it. */
+      const entryOf: Record<string, unknown>[] = [];
+      for (const item of planned) {
+        const entry: Record<string, unknown> = { path: item.path };
+        outcomes.push(entry);
+        if (item.content === undefined) {
+          entry.outcome = 'refused';
+          entry.error = item.error;
+          entry.message = item.message;
+          continue;
+        }
+        const wsPathOf = item.path;
+        try {
+          if (blocked.has(wsPathOf)) throw await writeRefusal(branch, wsPathOf);
+          const platform = platformFileReason(wsPathOf);
+          if (platform !== undefined) throw new ToolError(platform, 422, { code: 'platform_file' });
+          // The git folder is never a workspace path, in any spelling. A ZIP
+          // entry's name has already met this rule in `zipEntryNameRefusal`; a
+          // SINGLE uploaded file's has not — `.git` is a name the upload
+          // route's `validateFilename` accepts — and the preflight that reads
+          // the caller's own arguments never sees it either, because the name
+          // came from the upload, not from the call. Asked here so that path
+          // is REFUSED like any other, with the rest of the upload landing,
+          // rather than failing the whole apply from inside `writeFiles`.
+          assertNoGitInternalsSegment(wsPathOf);
+          assertRepoRootNameFree(wsPathOf, kbDirName);
+          // A link already on disk under the destination must not redirect
+          // these bytes — the rule `unzip` applies per entry, applied here on
+          // the path the write will take.
+          const link = await symlinkOnPath(root, wsPathOf);
+          if (link !== undefined) {
+            throw new ToolError(
+              `"${wsPathOf}" goes through the symbolic link "${link}"; an upload never follows links.`,
+              400,
+              { code: 'symlink' },
+            );
+          }
+          writePolicy.assertPathWritable(ctx.sessionId, wsPathOf);
+          await assertAgentWriteAllowed(agentAccessGate, ctx, branch, wsPathOf);
+          // An earlier entry of this same upload counts as existing, as it
+          // does in `write_files`: two `create` entries for one path are a
+          // mistake the commit would otherwise hide.
+          const exists =
+            writes.some((w) => w.path === wsPathOf) || (await kindOf(fs, wsPathOf)) !== null;
+          entry.outcome = decideWrite(mode, wsPathOf, exists);
+          writes.push({ path: wsPathOf, content: item.content });
+          entryOf.push(entry);
+        } catch (err) {
+          refuseEntry(entry, err);
+        }
+      }
+
+      // The mode gate again, with every path's lock held — the verdict the
+      // answer carries, for the reason `write_file` states at length. A path
+      // whose verdict changed under the lock is dropped from the batch and
+      // reported refused, leaving the rest to land.
+      const recheck = async (
+        pending: readonly { path: string; content: Buffer }[],
+      ): Promise<{ path: string; content: Buffer }[]> => {
+        const kept: { path: string; content: Buffer }[] = [];
+        for (let i = 0; i < pending.length; i++) {
+          const entry = entryOf[i];
+          try {
+            const exists =
+              kept.some((k) => k.path === pending[i].path) || (await kindOf(fs, pending[i].path)) !== null;
+            entry.outcome = decideWrite(mode, pending[i].path, exists);
+            kept.push(pending[i]);
+          } catch (err) {
+            refuseEntry(entry, err);
+          }
+        }
+        return kept;
+      };
+      if (writes.length > 0) {
+        // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands
+        // the whole set as ONE commit and takes a Buffer as content, so bytes
+        // reach disk exactly as they were sent — no text decode anywhere on
+        // the way, which is what makes a PNG and a backslash-heavy page land
+        // with the checksum they were uploaded with.
+        const batching = fs as unknown as {
+          writeFiles(
+            writes: { path: string; content: Buffer }[],
+            summary: string,
+            deletes: string[],
+            check: (
+              pending: readonly { path: string; content: Buffer }[],
+            ) => Promise<{ path: string; content: Buffer }[]>,
+          ): Promise<void>;
+        };
+        // In the DESTINATION folder's TURN, which `delete_folder` takes over the
+        // same subtree (and `keepFolderOf` with it). `writeFiles` creates the
+        // destination, and any folder above a zip entry on the way to it, as
+        // part of landing the batch — and a folder delete running between that
+        // creation and the commit enumerates the folder's files BEFORE these
+        // exist and then removes the folder they are landing in, which is an
+        // answer saying `created` for bytes that are already gone. The turn is
+        // taken OUTSIDE `writeFiles`, so it is held across the under-lock
+        // recheck and the commit both, and in the same order the delete takes
+        // its own (the folder's turn first, then each path's lock), which is
+        // what keeps two callers from waiting on each other's half.
+        await ctx.workspaceService.withFolderTurn(workspaceIdForBranch(branch), destination, async () => {
+          await batching.writeFiles(writes, `Apply upload of ${writes.length} file(s)`, [], recheck);
+        });
+      }
+      // The token is spent once an ANSWER exists, even an answer in which
+      // every path was refused: the apply ran and said what happened at each
+      // path, and re-running it would say the same. Only a refusal that landed
+      // nothing AND answered nothing (thrown above) gives the token back.
+      spent = true;
+      await uploads.consume(token);
+      const listed = a.all === true ? outcomes : outcomes.slice(0, APPLY_ANSWER_CAP);
+      return {
+        destination,
+        count: outcomes.filter((o) => o.outcome !== 'refused').length,
+        total: outcomes.length,
+        files: listed,
+        ...(listed.length < outcomes.length ? { truncated: true } : {}),
+      };
+    } finally {
+      if (!spent) uploads.release(token);
+    }
+  };
+
+  // Mounted only when the composition supplied a store — see the `uploads`
+  // parameter. Core always does.
+  if (uploads) {
+    mount({
+      name: 'request_file_upload',
+      fileTool: false,
+      description:
+        // Within the description cap (`tool-registry/description-length.ts`):
+        // why a file goes this way is one of the shared rules, and the header
+        // spelling of the token is on the `uploadUrl` output, where the
+        // address it changes is.
+        'Ask for a one-time address to send FILE BYTES to, so their content never passes through this conversation. ' +
+        'Use it for anything `write_file` cannot carry faithfully: a large file, a file full of backslashes or `\\u` ' +
+        'escapes, a binary file (a PNG, a PDF, a zip), or many files at once (zip them). ' +
+        'Returns `{ uploadUrl, token, expiresAt, expiresInSeconds, maxBytes }`. THEN: ' +
+        '(1) POST the file as the raw request body to `uploadUrl` with `?filename=<name>` — ' +
+        '`curl -X POST --data-binary @skill.zip "<uploadUrl>?filename=skill.zip"` — which answers what it received; ' +
+        '(2) call `apply_file_upload` with the same `token`, a `branch` and a destination folder. ' +
+        'One token carries one file or one zip, is bound to you and expires at `expiresAt`: an upload nobody applies ' +
+        'by then is deleted, and one over `maxBytes` is refused when you send it, naming the limit.',
+      inputs: { type: 'object', properties: {}, additionalProperties: false },
+      outputs: {
+        type: 'object',
+        properties: {
+          uploadUrl: str(
+            'The absolute URL to POST the bytes to. Carries the token; add `?filename=<name>`. To keep the token out ' +
+              'of a URL — when the command line you send from is logged or shared — POST to this address without its ' +
+              'last (token) segment and send the token in an `x-upload-token` header instead.',
+          ),
+          token: str(
+            'The token itself — what `apply_file_upload` takes, and what an `x-upload-token` header carries when you ' +
+              'would rather it not sit in a URL. Treat it as a credential.',
+          ),
+          expiresAt: str('ISO-8601 instant after which the token, and any bytes sent with it, are gone.'),
+          expiresInSeconds: int('Seconds from now until `expiresAt`.'),
+          maxBytes: int('The largest upload this deployment accepts, in bytes.'),
+        },
+        required: ['uploadUrl', 'token', 'expiresAt', 'expiresInSeconds', 'maxBytes'],
+      },
+      // A read-scoped caller has nothing to do with an upload token: the only
+      // thing it unlocks is a write. Refused at the handler factory, by scope,
+      // before the token is minted.
+      write: true,
+      handler: async (_a, ctx: ToolContext) => uploads.issue(ctx.user),
+    });
+
+    mount({
+      name: 'apply_file_upload',
+      gated: true,
+      description:
+        'Land a file you have already uploaded (see `request_file_upload`) in a folder on a branch, in ONE commit, as you. ' +
+        'A single file lands under the name it was sent with; a zip lands as its entries, keeping their folder structure. ' +
+        'Returns `{ destination, count, total, files }`: one entry per path, each `{ path, outcome }` — `created` / ' +
+        '`replaced` / `updated`, or `refused` with `error` (the code) and `message` (why). `count` is how many landed and ' +
+        '`total` how many paths there were; `files` is cut to the first 25 unless you pass `all: true`. ' +
+        'Every path is judged one by one — by your write access, the platform-file rules and what is already there — ' +
+        'exactly as `write_file` judges it, and a refused path does not stop the others. ' +
+        'The token is single-use: it is spent by the apply that lands it, and refused if you use it twice, let it ' +
+        'expire, or present one issued to somebody else. `mode` means what it means on `write_file`.',
+      inputs: {
+        type: 'object',
+        properties: {
+          branch: BRANCH_INPUT,
+          token: str('The `token` from `request_file_upload`, after you have POSTed the file to its `uploadUrl`.'),
+          destination: wsPath(kbDirName, 'Folder the upload lands in (created if it is not there yet)'),
+          mode: WRITE_MODE_INPUT,
+          all: {
+            type: 'boolean',
+            description:
+              'List EVERY path in `files` instead of the first 25. `total` always says how many there were, so ask for ' +
+              'all only when you need to read each outcome.',
+          },
+          sessionId: SESSION_ID_INPUT,
+        },
+        required: ['branch', 'token', 'destination'],
+        additionalProperties: false,
+      },
+      outputs: {
+        type: 'object',
+        properties: {
+          destination: str('The folder the upload was applied to (echoes the input).'),
+          count: int('How many paths landed — the entries in `files` whose `outcome` is not `refused`.'),
+          total: int('How many paths the upload held, whether or not `files` lists them all.'),
+          files: {
+            type: 'array',
+            description: 'One entry per path, in the order the upload held them. Cut to 25 unless `all` was true.',
+            items: {
+              type: 'object',
+              properties: {
+                path: str('The workspace path this entry was judged at.'),
+                outcome: {
+                  type: 'string',
+                  enum: ['created', 'replaced', 'updated', 'refused'],
+                  description: 'What happened at this path. `refused` means nothing was written there.',
+                },
+                error: str('Present when `outcome` is `refused`: the refusal code — e.g. `exists`, `missing`, `invalid_entry`, `platform_file`, `write-denied`.'),
+                message: str('Present when `outcome` is `refused`: the full refusal, the same one `write_file` would have given.'),
+              },
+              required: ['path', 'outcome'],
+            },
+          },
+          truncated: { type: 'boolean', description: 'True when `files` was cut: `total` is larger than what it lists. Pass `all: true` for the rest.' },
+        },
+        required: ['destination', 'count', 'total', 'files'],
+      },
+      write: true,
+      // So a protected-branch refusal arrives as `write-denied`, with the
+      // change-request steps, exactly as it does from write_file.
+      proposable: true,
+      handler: async (a, ctx: ToolContext) => applyFileUpload(a, ctx, uploads),
+    });
+  }
+
   // ── shell (internal-only) ───────────────────────────────────────────────
   mount({
     name: 'execute_command',
+    gated: true,
     description:
-      'Run a shell command in the workspace directory. Returns `{ stdout, stderr, exitCode }` (output capped). Use for git status/log, grep/rg, build/test commands.' +
-      ONTOLOGY_BOUNDARY_NOTE,
+      'Run a shell command in the workspace directory. Returns `{ stdout, stderr, exitCode }` (output capped). Use for git status/log, grep/rg, build/test commands.',
     internalOnly: true,
     fileTool: false,
     // The one tool the mount's branch check skips: the handler below resolves an
@@ -2714,11 +3393,12 @@ export function registerWorkspaceTools(
           400,
         );
       }
-      // Shell is a write path with no single target path to check, so enforce the
-      // boundary at the session level: refuse once the run is already write-blocked,
-      // or when the run is restricted to a file type (shell could write anything).
+      // Shell is a write path with no single target path to check, so the
+      // write hook is asked once for the call itself, with no path — and the
+      // run must not be restricted to a file type either, since shell could
+      // write anything.
       writePolicy.assertUnrestricted(ctx.sessionId);
-      await assertShellAllowedWithinOntology(sessionOntologyGate, ctx);
+      await assertAgentWriteAllowed(agentAccessGate, ctx, branch);
       // Canonical per-branch bootstrap entry point — it owns the workspace-id
       // encoding and the single-flight clone, so the shell never derives a
       // workspace path by hand.