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

package/dist/modules/workspace/workspace.tools.js

@@ -3,9 +3,10 @@ import nodeFs from 'node:fs/promises';
 import { join } from 'node:path';
 import { ToolError } from '../tool-helpers/tool.contract.js';
 import { BRANCH_INPUT, toolDef } from '../tool-helpers/tool-def.js';
-import { recordOntologyRead, assertOntologyWriteAllowed, assertShellAllowedWithinOntology, ONTOLOGY_BOUNDARY_NOTE, SESSION_ID_INPUT, } from './session-ontology.gate.js';
+import { notifyAgentRead, assertAgentWriteAllowed, SESSION_ID_INPUT, } from './agent-access.gate.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';
 // 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';
@@ -318,6 +319,25 @@ const WRITE_MODE_NOTE = ' `mode` decides what may happen at a path and DEFAULTS
     '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.';
+/**
+ * What an agent needs to know about escape sequences in the content it sends,
+ * on the three tools that take content as a JSON string.
+ *
+ * The three write routes — the MCP endpoint, the `/api/agent/tools/<name>`
+ * route and `call_tool_chain` — were measured end to end against raw requests
+ * and a byte-level read of the stored file (see
+ * `__tests__/escape-sequences.routes.test.ts`): each stores content exactly as
+ * the JSON string value decodes ONCE. So when an escape arrives already
+ * decoded, the decoding happened in the client that built the request, and no
+ * tool here can tell that content from content that was meant to be decoded.
+ * Hence a warning rather than a fix, and the pointer to the one route whose
+ * payload is bytes rather than a JSON string.
+ */
+const ESCAPE_SEQUENCE_NOTE = ' Escape sequences: some clients decode them in arguments before sending, so content meant to CONTAIN an escape rather ' +
+    'than what it stands for (the six characters backslash, `u`, `0`, `0`, `4`, `1`, say, rather than the letter `A`) can ' +
+    'reach this tool already decoded — what arrives is stored byte for byte, so when that distinction matters, verify what ' +
+    'landed (`read_file`, or a hash) and send such content through the upload route (`request_upload_token` + `apply_upload` ' +
+    'where offered, otherwise Upload in the app), which lands it unchanged.';
 /** The refusal `create` gives on a path that already holds something. */
 function pathExists(path) {
     return new ToolError(`"${displayPath(path)}" already exists — pass mode: overwrite to replace it, or write to a different path.`, 409, { code: 'exists', path });
@@ -430,7 +450,7 @@ async function searchRootKind(fs, path) {
     }
 }
 /** JS grep over the workspace tree (read methods only) — bounded by match + depth caps. */
-async function grepWalk(fs, dir, re, out, max, depth, gate, recordOntologyRead, docs) {
+async function grepWalk(fs, dir, re, out, max, depth, gate, notifyRead, docs) {
     if (out.length >= max || depth > 12)
         return;
     let entries;
@@ -452,13 +472,13 @@ async function grepWalk(fs, dir, re, out, max, depth, gate, recordOntologyRead,
             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 {
@@ -488,6 +508,17 @@ const BATCH_SAVE_WARNINGS_OUTPUT = {
         'The writes still happened.',
     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) {
+    const inputs = def.inputs;
+    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`
@@ -497,7 +528,7 @@ const BATCH_SAVE_WARNINGS_OUTPUT = {
  * method), so they're implemented here. File ops are `both`; `execute_command`
  * is INTERNAL-only (arbitrary shell as the caller is too dangerous to expose).
  */
-export function registerWorkspaceTools(registry, router, toolAuth, toolHandler, spillStore, docExtract, accessControl, kb, sessionOntologyGate, writePolicy, sessionSink, 
+export function registerWorkspaceTools(registry, router, toolAuth, toolHandler, spillStore, docExtract, accessControl, kb, agentAccessGate, writePolicy, sessionSink, 
 /**
  * Save-time skill check (see `AllowedToolsChecker`): a write to a SKILL.md
  * returns `warnings` for `allowed-tools` entries naming no visible tool.
@@ -581,7 +612,7 @@ changeGate) {
      * 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.
      */
@@ -604,7 +635,7 @@ changeGate) {
      * 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, ctx) => {
         if (typeof args.branch !== 'string' || args.branch === '')
@@ -671,6 +702,112 @@ changeGate) {
         ]);
         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, after) => Object.keys(before).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) => `"${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, ctx, src, dest, opts) => {
+        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, ctx, src, dest) => {
+        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
@@ -950,10 +1087,17 @@ changeGate) {
         // 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.
+        // 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
+        // it optional (and resolves absence itself, as `list_tool_setup` does on its
+        // own route) is not handed a refusal it never asked for.
+        const requiresBranch = (spec.inputs.required ?? []).includes('branch');
         const describe = () => (typeof spec.description === 'function' ? spec.description() : spec.description) +
             (spec.proposable ? PROPOSAL_ROUTE_NOTE : '') +
             (spec.fileTool === false ? '' : CONTENT_RULE) +
-            kbConventionsNote(kb.layout);
+            kbConventionsNote(kb.layout) +
+            (spec.gated ? agentAccessGate.notes.gatedToolNote() : '');
         const def = toolDef({
             name: spec.name,
             description: describe(),
@@ -965,16 +1109,33 @@ changeGate) {
         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 = () => {
             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.
@@ -991,6 +1152,17 @@ changeGate) {
         // path, and exempting it there would be a workspace-relative path that
         // never reached the repository — the whole bug, spelled with a prefix.
         toolHandler(async (args, ctx) => {
+            // FIRST, before the path work and before any handler: every tool
+            // mounted here declares `branch` as a required, non-empty string, and
+            // nothing enforced that, so a call that named none was carried down
+            // until `workspaceIdForBranch` made a workspace directory out of the
+            // missing value. Most of these tools would meet the same refusal one
+            // layer down at `getFilesystem`, but not all of them do — `unzip`
+            // hands `branch` straight to the workspace service by id — so the
+            // check belongs on the mount every one of them shares rather than on
+            // the resolver only some of them reach.
+            if (requiresBranch && !spec.resolvesBranchItself)
+                assertBranchProvided(args.branch);
             // BEFORE the normaliser: see `assertToolPathsNotGitInternals`.
             if (spec.fileTool !== false)
                 await assertToolPathsNotGitInternals(args, ctx);
@@ -1021,22 +1193,20 @@ changeGate) {
         }, { write: spec.write }));
     };
     // ── 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:
@@ -1048,7 +1218,7 @@ changeGate) {
     // transport hiccup on its first call as an unrecoverable start.
     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 }`.',
+        description: '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: {
@@ -1060,10 +1230,10 @@ changeGate) {
     });
     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
@@ -1075,8 +1245,8 @@ changeGate) {
     // ── reads ──────────────────────────────────────────────────────────────
     mount({
         name: 'read_file',
-        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,
+        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.',
         inputs: {
             type: 'object',
             properties: {
@@ -1102,12 +1272,12 @@ changeGate) {
             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, p);
             await assertCanRead(readGateFor(a.branch, ctx), p);
             const fs = await ctx.getFilesystem(a.branch);
             // 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)));
@@ -1139,8 +1309,8 @@ changeGate) {
     });
     mount({
         name: 'list_files',
-        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,
+        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.`,
         inputs: {
             type: 'object',
             properties: {
@@ -1170,7 +1340,7 @@ changeGate) {
         write: false,
         handler: async (a, ctx) => {
             const dir = a.path || '';
-            await recordOntologyRead(sessionOntologyGate, ctx, dir);
+            await notifyAgentRead(agentAccessGate, ctx, a.branch, dir);
             const fs = await ctx.getFilesystem(a.branch);
             const entries = withoutPlaceholder((await fs.readdir(dir || '.')));
             const filtered = await filterReadableEntries(readGateFor(a.branch, ctx), dir, entries);
@@ -1179,13 +1349,13 @@ changeGate) {
     });
     mount({
         name: 'file_stat',
+        gated: true,
         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,
+            'Call this before a move or delete to see what it would touch.',
         inputs: {
             type: 'object',
             properties: {
@@ -1258,7 +1428,7 @@ changeGate) {
         handler: async (a, ctx) => {
             const p = a.path;
             const branch = a.branch;
-            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).
@@ -1360,8 +1530,8 @@ changeGate) {
     });
     mount({
         name: 'grep',
-        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,
+        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).',
         inputs: {
             type: 'object',
             properties: {
@@ -1412,11 +1582,10 @@ changeGate) {
             // (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, searchRoot);
             const fs = await ctx.getFilesystem(a.branch);
             const gate = readGateFor(a.branch, ctx);
             const out = [];
@@ -1434,7 +1603,7 @@ changeGate) {
             /** Why a single-file search found nothing, when "no matches" would be a lie. */
             let fileNote;
             if (kind === 'directory') {
-                await grepWalk(fs, searchRoot, re, out, max, 0, gate, (p) => recordOntologyRead(sessionOntologyGate, ctx, p), docs);
+                await grepWalk(fs, searchRoot, re, out, max, 0, gate, (p) => notifyAgentRead(agentAccessGate, ctx, a.branch, p), docs);
             }
             else {
                 // Not a directory: the permission verdict comes BEFORE every other
@@ -1473,11 +1642,12 @@ changeGate) {
     // ── 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,
+            ESCAPE_SEQUENCE_NOTE,
         inputs: {
             type: 'object',
             properties: {
@@ -1513,7 +1683,7 @@ changeGate) {
             // (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);
-            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path);
+            await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch, a.path);
             const mode = modeOf(a);
             const fs = await ctx.getFilesystem(a.branch);
             await assertNotBinaryOverwrite(readers, a.path, fs);
@@ -1546,17 +1716,18 @@ changeGate) {
     });
     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,
+            ESCAPE_SEQUENCE_NOTE,
         inputs: {
             type: 'object',
             properties: {
@@ -1610,15 +1781,14 @@ changeGate) {
             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);
             // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands the
             // batch as one commit. Structural cast avoids a workflow-internal import.
@@ -1639,6 +1809,19 @@ changeGate) {
             for (const f of files) {
                 const entry = { path: f.path };
                 outcomes.push(entry);
+                try {
+                    await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch, 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);
@@ -1706,8 +1889,9 @@ changeGate) {
     });
     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,
+            ESCAPE_SEQUENCE_NOTE,
         inputs: {
             type: 'object',
             properties: {
@@ -1731,7 +1915,7 @@ changeGate) {
         handler: async (a, ctx) => {
             assertNotDocumentEdit(readers, a.path);
             writePolicy.assertPathWritable(ctx.sessionId, a.path);
-            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path);
+            await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch, a.path);
             const fs = await ctx.getFilesystem(a.branch);
             const path = a.path;
             const oldStr = a.old_string;
@@ -1755,9 +1939,9 @@ changeGate) {
     });
     mount({
         name: 'delete_file',
+        gated: true,
         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,
+            `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.`,
         inputs: {
             type: 'object',
             properties: {
@@ -1776,14 +1960,14 @@ changeGate) {
         write: true,
         proposable: true,
         handler: async (a, ctx) => {
-            // 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;
             const branch = a.branch;
             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);
@@ -1809,12 +1993,12 @@ changeGate) {
     });
     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 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.',
         inputs: {
             type: 'object',
             properties: {
@@ -1852,7 +2036,7 @@ changeGate) {
             // 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)
@@ -1946,7 +2130,8 @@ changeGate) {
     });
     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: {
@@ -1966,18 +2151,18 @@ changeGate) {
         proposable: true,
         handler: async (a, ctx) => {
             writePolicy.assertPathWritable(ctx.sessionId, a.path);
-            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.path);
+            await assertAgentWriteAllowed(agentAccessGate, ctx, a.branch, a.path);
             await (await ctx.getFilesystem(a.branch)).mkdir(a.path, { recursive: true });
             return { path: a.path, created: true };
         },
     });
     mount({
         name: 'move_file',
+        gated: true,
         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,
+            '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 AS IT WILL BE once the move has landed, with every `access.md` inside a moved folder counted at its new place. ' +
+            '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.',
         inputs: {
             type: 'object',
             properties: {
@@ -1998,8 +2183,8 @@ changeGate) {
                 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.' },
@@ -2017,12 +2202,12 @@ changeGate) {
             const src = a.src.replace(/\/+$/, '');
             const dest = a.dest.replace(/\/+$/, '');
             const branch = a.branch;
-            // 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
@@ -2039,8 +2224,13 @@ changeGate) {
                 writePolicy.assertPathWritable(ctx.sessionId, f);
                 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).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
@@ -2135,14 +2325,17 @@ changeGate) {
     });
     mount({
         name: 'copy_file',
-        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,
+        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. ' +
+            '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'],
@@ -2150,20 +2343,30 @@ changeGate) {
         },
         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) => {
-            // 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);
             writePolicy.assertPathWritable(ctx.sessionId, a.dest);
-            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.src);
-            await assertOntologyWriteAllowed(sessionOntologyGate, ctx, a.dest);
             const branch = a.branch;
+            await assertAgentWriteAllowed(agentAccessGate, ctx, branch, a.src);
+            await assertAgentWriteAllowed(agentAccessGate, ctx, branch, a.dest);
             const src = a.src;
             const dest = a.dest;
             // A copy lands bytes at a name of its own, so it is refused by the same
@@ -2175,6 +2378,8 @@ changeGate) {
             // 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
@@ -2214,6 +2419,12 @@ changeGate) {
                 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?.name === 'IsDirectoryError') {
+                    throw new ToolError(folderCopyRefusal(src), 400);
+                }
                 const missing = isAbsence(err) || err.name === 'FileNotFoundError';
                 if (missing) {
                     throw (await kindOf(fs, src)) === null
@@ -2227,8 +2438,8 @@ changeGate) {
     });
     mount({
         name: 'unzip',
-        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,
+        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.',
         inputs: {
             type: 'object',
             properties: {
@@ -2260,19 +2471,19 @@ changeGate) {
         write: true,
         handler: async (a, ctx) => {
             const zipPath = a.path;
-            // 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, 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
             // answer maps — a failure part-way through an extraction is not the
             // archive going missing.
             return orDeclaredNotFound(() => ctx.workspaceService.unzipFile(workspaceIdForBranch(a.branch), 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.
@@ -2283,17 +2494,20 @@ changeGate) {
                     throw new ToolError('roles.yaml is never extracted from an archive — change it with edit_file or write_file, where the change is checked.', 422);
                 }
                 writePolicy.assertPathWritable(ctx.sessionId, wsRelPath);
-                return assertOntologyWriteAllowed(sessionOntologyGate, ctx, wsRelPath);
+                return assertAgentWriteAllowed(agentAccessGate, ctx, a.branch, wsRelPath);
             }), 'Nothing to extract');
         },
     });
     // ── shell (internal-only) ───────────────────────────────────────────────
     mount({
         name: 'execute_command',
-        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,
+        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.',
         internalOnly: true,
         fileTool: false,
+        // The one tool the mount's branch check skips: the handler below resolves an
+        // omitted `branch` to the internal caller's focused branch before refusing.
+        resolvesBranchItself: true,
         inputs: {
             type: 'object',
             properties: {
@@ -2347,7 +2561,12 @@ changeGate) {
             const raw = a.branch;
             const branch = raw === undefined ? ctx.focusedBranch : raw;
             if (typeof branch !== 'string' || branch.length === 0) {
-                throw new ToolError('execute_command requires a `branch`: pass the branch (draft) whose workspace to run the command in — the one you are currently working on.', 400);
+                throw new ToolError('execute_command requires a `branch`: pass the branch (draft) whose workspace to run the command in — the one you are currently working on.', 400, 
+                // The same discriminator every other KB tool answers a branch-less
+                // call with, so a client switches on one kind across the surface.
+                // The MESSAGE stays this tool's own: it can name the focused-branch
+                // fallback that only applies here.
+                { kind: 'branch-required' });
             }
             // A stringified absent value. Both are syntactically valid git branch names,
             // so `assertValidBranchName` below happily accepts them — and accepting one
@@ -2356,7 +2575,7 @@ changeGate) {
             // and 500s. Reject them by name, ahead of the shape check.
             if (branch === 'undefined' || branch === 'null') {
                 throw new ToolError(`execute_command got the literal string "${branch}" as \`branch\` — that is a stringified absent value, not a branch. ` +
-                    'Pass the real branch (draft) whose workspace to run the command in.', 400);
+                    'Pass the real branch (draft) whose workspace to run the command in.', 400, { kind: 'branch-required' });
             }
             // Then the SHAPE, via the one canonical validator every other branch path
             // uses — no hand-maintained list of suspicious literals, which would both
@@ -2371,11 +2590,12 @@ changeGate) {
                 throw new ToolError(`execute_command got an invalid \`branch\`: ${err.message} — ` +
                     'pass the exact branch (draft) whose workspace to run the command in.', 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.