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

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

@@ -279,9 +279,10 @@ export function registerWorkflowTools(
   mount({
     name: 'commit_change',
     description:
-      'Save the currently-pending file edits as a new change on the current branch. Each change ' +
-      'must affect exactly one file — if multiple files are dirty, returns a structured error ' +
-      'listing them; commit them one at a time. Refused on protected branches without write permission.',
+      'Commit, as you, the one file left uncommitted on `branch`, without sharing it. Writes commit and share ' +
+      'on their own moments later (`branch_status` lists those still landing); `unzip` leaves its files uncommitted. ' +
+      'If several files are uncommitted, returns a structured error listing them; commit them one at a time. ' +
+      'Refused on protected branches without write permission.',
     inputs: {
       type: 'object',
       properties: {
@@ -309,7 +310,7 @@ export function registerWorkflowTools(
     name: 'save_file',
     description:
       'Schedule the file at <path> for commit + push using whatever bytes are on disk (no content ' +
-      'rewrite) — for binary uploads or files left uncommitted. On lock contention returns ' +
+      'rewrite) — for files left uncommitted, such as those `unzip` extracts. On lock contention returns ' +
       '`{ saved: false, reason }` rather than throwing. The commit lands asynchronously.',
     inputs: {
       type: 'object',
@@ -357,8 +358,9 @@ export function registerWorkflowTools(
   mount({
     name: 'share_current_branch',
     description:
-      'Publish the current branch to the shared remote so teammates and any change request pick up ' +
-      'your commits. No arguments. Refused on protected branches without write permission.',
+      'Publish `branch` to the shared remote so teammates and any change request pick up its commits. ' +
+      'Writes already share on their own: this is for sharing again after a refused push (`branch_status` shows ' +
+      'the branch ahead). Refused on protected branches without write permission.',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
       type: 'object',
@@ -377,10 +379,11 @@ export function registerWorkflowTools(
     description:
       'Create a new unprotected draft named `name`, forked from the existing branch `branch`. The ' +
       `backend rejects protected names (${protectedInline(kb)}) and filesystem-invalid names — surface ` +
-      'those errors verbatim. Convention: `<email-localpart>/<kebab-slug>`. Does NOT switch the ' +
-      'agent onto the new draft.',
+      'those errors verbatim. Name it `<you>/<kebab-slug>`: `<you>` is the person\'s email before the @, in lower case, ' +
+      'with each run of characters other than letters and digits as one `-` (`paul.brandt@` gives `paul-brandt/`). ' +
+      'Only that prefix makes the draft theirs, to delete later. Does NOT switch the agent onto the new draft.',
     // `branch` here is the fork BASE — its own meaning — so skip the generic
-    // workspace-`branch` injection ("the branch you are currently working on"),
+    // workspace-`branch` injection ("the branch to work on: ... or your draft"),
     // whose wording invites filling in the draft being created instead.
     skipBranch: true,
     // The handler refuses a missing `name` with a message that says what the
@@ -389,7 +392,7 @@ export function registerWorkflowTools(
     inputs: {
       type: 'object',
       properties: {
-        name: { type: 'string', minLength: 1, description: 'Name of the draft to create (`<email-localpart>/<kebab-slug>` for user drafts). Must not exist yet.' },
+        name: { type: 'string', minLength: 1, description: 'Name of the draft to create (`<you>/<kebab-slug>` for user drafts, as the description says). Must not exist yet.' },
         branch: { type: 'string', minLength: 1, description: 'Existing branch to fork the new draft from — usually the branch you are currently on.' },
       },
       required: ['name', 'branch'],
@@ -437,7 +440,7 @@ export function registerWorkflowTools(
     description:
       'Open a change request from a draft branch into a target branch. Auto-merges the latest target ' +
       'into the source first, pushes, then creates the CR. On conflicts returns a ' +
-      '`change-request-conflicts` error with affected paths. The author marker is injected server-side. ' +
+      '`change-request-conflicts` error with affected paths. ' +
       'Answers a SUMMARY, not the request\'s content: `url` first (hand it to the user), then `number`, ' +
       '`title`, `state`, `sourceBranch`, `targetBranch`, `approvals` (who must approve each file), ' +
       '`mergeBlockedReasons` (what blocks the merge), and `files` — the changed paths with their kind of ' +
@@ -549,12 +552,13 @@ export function registerWorkflowTools(
     name: 'merge_branch',
     description:
       'Merge branch `source` into branch `target` as you, and publish `target`. An agent proposes and syncs; ' +
-      'a person merges: this tool never lands a change request. It refuses while a change request from `source` ' +
+      'a person merges: this never lands a change request. It refuses while a change request from `source` ' +
       'into `target` is open (naming it): ask the user to review it in the app. It refuses ' +
-      'when `target` is a protected branch unless you could commit every changed file directly to it. ' +
+      'when `target` is a protected branch unless you could commit every changed file directly to it (never ' +
+      'for a change to `roles.yaml`). ' +
       'SYNC: merging the target into your draft (`source` = the change request\'s target, `target` = your draft) ' +
       'is always allowed, even with the draft\'s request open. ' +
-      'Writes are committed asynchronously; the merge first waits up to 20s for those on `source`. ' +
+      'Writes are committed asynchronously; it waits up to 20s for those on `source`. ' +
       'Returns `merged` with the merge commit; `nothing-to-merge` with `target`\'s tip when it already holds ' +
       'all of `source`; `pending-commits` (nothing merged) when writes are still committing — retry shortly — ' +
       'or one failed (`needsAttention`: tell the user); or `conflicts-need-resolution` with the conflicting ' +
@@ -618,7 +622,7 @@ export function registerWorkflowTools(
     name: 'delete_branch',
     description:
       'Delete branch `name` from the shared repository and the server. Allowed for the ' +
-      'branch\'s author (`<email-localpart>/…`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
+      'branch\'s author (`<you>/…` per `create_branch`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
       'protected branch, a name that is not a branch, a branch with saves still landing or a file held ' +
       '(retry once they land). An open change request from or into it that proposes nothing is closed and the ' +
       'delete goes ahead; one that still proposes something refuses it, naming and linking it: its author ' +
@@ -836,13 +840,13 @@ export function registerWorkflowTools(
       'One file as it was at a point in history: `at` is a commit (from `list_file_changes`, on `branch`\'s ' +
       'own history) or the name of another branch (its published tip). Answers `content` (null when the ' +
       'file was not there) and `sha`, the commit it was read at; for a commit, also `before`, the file ' +
-      'just before that commit. To put an earlier version back, write it with `write_file`. Takes the read ' +
-      'the file takes at that point.',
+      'just before that commit. To put an earlier version back, write it with `write_file`. Takes your ' +
+      'read of the file on `branch` now and, for a branch, also at its tip.',
     inputs: {
       type: 'object',
       properties: {
         path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
-        at: { type: 'string', minLength: 1, description: 'A commit sha, or a branch name.' },
+        at: { type: 'string', minLength: 1, description: 'A full commit sha (40 or 64 hex characters), or a branch name.' },
         sessionId: SESSION_ID_INPUT,
       },
       required: ['path', 'at'],

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -4,19 +4,17 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import { GUIDE_FIRST_SENTENCE, ToolRegistry } from '../../tool-registry/index.js';
+import { WorkflowHooks, createToolHandlerFactory } from '../../../__tests__/tool-wiring.js';
+import type { ToolAuth } from '../../tool-auth/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
 import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { SpillStore } from '../spill-store.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
-import { sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
+import { sharedFileRulesSection } from '../../agent-instructions/index.js';
 import { RipgrepPatternMatcher } from '../index.js';
 
 /** The grep matcher this file's harness wires, closed once the file is done. */
@@ -80,10 +78,10 @@ async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
 afterEach(() => kb.applyLayout({ ...DEFAULT_KB_LAYOUT }));
 
 describe('what tells an agent to read the guide first', () => {
-  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with the same guide after the organisation\'s own', () => {
+  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with that start after the organisation\'s own', () => {
     const rules = sharedFileRulesSection(kb.layout);
-    expect(rules).toContain("call `get_agent_guide` and read the platform's guide");
-    expect(rules).toContain('read_file on `AGENTS.md` at the KB root answers with the same guide');
+    expect(rules).toContain("call `get_agent_guide`: it answers the guide's start");
+    expect(rules).toContain('read_file on `AGENTS.md` at the KB root answers with that start');
     expect(rules).toContain("after the organisation's own conventions file of that name");
     expect(rules).toContain('`CLAUDE.md`');
     // One name on every deployment: the rule names no other.

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

@@ -10,40 +10,38 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { slowRipgrep } from '../../../__tests__/slow-ripgrep.js';
 import { LocalFilesystem } from '@mastra/core/workspace';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { GUIDE_FIRST_SENTENCE, ToolRegistry } from '../../tool-registry/index.js';
+import { AccessControlService, WorkflowHooks, createToolHandlerFactory, type AgentOperationContext } from '../../../__tests__/tool-wiring.js';
+import { ToolError, type ToolContext } from '../../tool-helpers/index.js';
+import type { ToolAuth } from '../../tool-auth/index.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
 import { RipgrepPatternMatcher, type RipgrepPatternMatcherOptions } from '../index.js';
-import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
-import { composeAgentGuide } from '../../agent-guide/agent-guide.js';
-import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/index.js';
+import { composeAgentGuide } from '../../agent-guide/index.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { UuidSessionSink, type ISessionSink } from '../session-sink.js';
 import { FIRST_RUN_SECTION_ID, STARTER_GUIDE_FILE, firstRunNote, type FirstRunStarterSource } from '../first-run.js';
-import { WorkflowHooks, type AgentOperationContext } from '../../workflow/workflow-hooks.js';
 import { SESSION_ID_DESCRIPTION, ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
 import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { OCTET_STREAM_FALLBACK_NOTE } from '../file-readers/content-mode.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
-import { AccessControlService } from '../../access/access-control.service.js';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { IAccessControl } from '../../access/index.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 import type { WorkspaceService } from '../workspace.service.js';
 import { DEFAULT_KB_LAYOUT, isBranchAuthoredBy, isOwnSuggestionsBranch } from '@bevel-software/platform-shared';
-import { normalizeWorkspacePath } from '../../kb-fs/repo-path.js';
+import { normalizeWorkspacePath } from '../../kb-fs/index.js';
 import { GIT_INTERNALS_MESSAGE, PathNotFoundError } from '../../../shared/domain-errors.js';
-import { AccessDeniedError } from '../../access-model/access-errors.js';
+import { AccessDeniedError } from '../../access-model/index.js';
 import { proposalTitleFor } from '../write-denial.js';
 import { NOT_FOUND_NEXT_STEP } from '../not-found.js';
 import { compileCheck, exampleArguments } from '@bevel-software/platform-mcp-core';
-import { routeToolSchemas } from '../../tool-helpers/route-tool-schemas.js';
-import { TOOL_DESCRIPTION_CAP, clientVisibleLength } from '../../tool-registry/description-length.js';
 
 const KB_DIR = 'knowledge-base';
 
+/** A move that changes nobody's access: what a stand-in without rules answers. */
+const NO_CHANGES = { lose: [], gain: [] };
+
 /** Allow-all access control — the default for tests not exercising read gating. */
 const allowAll = {
   canRead: async () => true,
@@ -67,6 +65,8 @@ const allowAll = {
   // a folder's `access.md` files actually does to it is exercised against
   // REAL rules in "a move preview judges the destination as it will be".
   previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+  // Who else loses or gains access in a move: nobody, here.
+  prospectiveHolderChanges: async () => NO_CHANGES,
 } as unknown as IAccessControl;
 
 /** Access control that denies `canRead` for an explicit set of repo-relative paths. */
@@ -2124,30 +2124,12 @@ describe('office documents and PDFs', () => {
       // Narrowed by hand: the assertion above already failed the test if not.
       if (!compiled.checkable) throw new Error(compiled.reason);
       expect(compiled.check(exampleArguments(def.inputs)), def.name).toEqual([]);
-      // And the FLAT schema, which is what the tool's own route checks the
-      // call against: the two must agree, or a call the example produced would
-      // be refused one layer in.
-      const flat = routeToolSchemas(def.name)?.flat;
-      expect(flat, def.name).toBeDefined();
-      const flatCheck = compileCheck(flat);
-      expect(flatCheck.checkable, `${def.name} (flat): ${flatCheck.checkable ? '' : flatCheck.reason}`).toBe(true);
-      if (!flatCheck.checkable) throw new Error(flatCheck.reason);
-      expect(flatCheck.check(exampleArguments(flat)), `${def.name} (flat)`).toEqual([]);
-    }
-  });
-
-  it('every description, call example and purpose prefix included, stays inside the cap a client shows', async () => {
-    await start();
-    const tools = await toolRegistry.listInternal();
-    for (const def of tools) {
-      // Measured as a CLIENT receives it: the call line, the purpose prefix at
-      // its own cap (the four knowledge-base tools carry one), and the
-      // description — the three things that ride one tool's entry.
-      const received = clientVisibleLength(def);
-      expect(received, `${def.name} is ${received} characters (cap ${TOOL_DESCRIPTION_CAP})`).toBeLessThanOrEqual(
-        TOOL_DESCRIPTION_CAP,
-      );
     }
+    // That the FLAT schema each route checks a call against agrees with the
+    // example is the route layer's own property: tool-helpers'
+    // `route-tool-schemas.catalog.test.ts` holds it over the whole catalog.
+    // And that every description stays inside the cap a client shows is the
+    // registry's: `tool-description-length.test.ts`, over the same catalog.
   });
 
   describe('binary capability contract: a text file, a document, an image and a zip', () => {
@@ -2475,7 +2457,7 @@ describe('start_session', () => {
       undefined,
       undefined /* downloads */,
       starterPacks,
-      new NodeFs(),
+      realDisk(),
     );
     app.use('/api', router);
     server = await new Promise<HttpServer>((r) => {
@@ -3256,7 +3238,8 @@ describe('preflight for moves and deletes', () => {
     if (rel === 'sealed.md' || rel.endsWith('/sealed.md')) return { read: true, write: false, download: false, owner: false };
     if (rel.startsWith('HR/')) return { read: true, write: true, download: false, owner: false };
     if (rel.startsWith('Locked/')) return { read: true, write: false, download: false, owner: false };
-    if (rel.startsWith('Secret/')) return { read: false, write: false, download: false, owner: false };
+    // The folder itself answers as its contents do, as the resolver's scopes do.
+    if (rel === 'Secret' || rel.startsWith('Secret/')) return { read: false, write: false, download: false, owner: false };
     return { read: true, write: true, download: true, owner: true };
   };
   const rules = {
@@ -3273,6 +3256,7 @@ describe('preflight for moves and deletes', () => {
     // preview learned to relocate them, which keeps every ordering and
     // oracle test below about what it is about.
     previewAccessAfterRelocation: async (_w: string, _u: string, _from: string, to: string) => verbsFor(to),
+    prospectiveHolderChanges: async () => NO_CHANGES,
   } as unknown as IAccessControl;
 
   const call = async (base: string, tool: string, body: Record<string, unknown>) => {
@@ -3401,10 +3385,12 @@ describe('preflight for moves and deletes', () => {
           writes.push(op.wsPath ?? '');
         });
         expect((await call(base, 'move_file', args)).body).toMatchObject({ moved: true });
-        // `Locked/refs.md` is named (left for want of write access, its links
-        // listed), so the read hook hears of it; the unreadable page and the
-        // transcript are never named, so it never hears of them.
-        expect(reads.sort()).toEqual([KB('Locked/refs.md'), KB('Sales/deal.md'), KB('Sales/index.md')]);
+        // The move's two ends first, as read_file tells it (what moves, and
+        // the folder it lands in); then `Locked/refs.md` is named (left for
+        // want of write access, its links listed), so the read hook hears of
+        // it; the unreadable page and the transcript are never named, so it
+        // never hears of them.
+        expect(reads.sort()).toEqual([KB('Locked/refs.md'), KB('Sales/2026'), KB('Sales/deal.md'), KB('Sales/deal.md'), KB('Sales/index.md')]);
         expect([...new Set(writes)].sort()).toEqual([KB('Sales/2026/deal.md'), KB('Sales/deal.md'), KB('Sales/index.md')]);
       });
 
@@ -3450,6 +3436,32 @@ describe('preflight for moves and deletes', () => {
       expect(await exists(args.src)).toBe(false);
     });
 
+    it('a caller who cannot read what moves is refused as read_file refuses them, on a draft too, and nothing is looked at', async () => {
+      const resolved: string[] = [];
+      const base = await start('write', {
+        ...rules,
+        prospectiveHolderChanges: async (_w: string, from: string) => {
+          resolved.push(from);
+          return { lose: [{ kind: 'group', name: 'Board', verb: 'read' }], gain: [] };
+        },
+      } as unknown as IAccessControl);
+      await fs.writeFile(KB('Secret/plan.md'), 'plan');
+      // A draft is not write-gated, so only the read gate stands between a
+      // caller and a move of a file they may not open — and it does: the dry
+      // run, the unconfirmed move and the confirmed one are all read_file's
+      // own refusal, with nobody resolved and nothing moved.
+      const args = { branch: 'someone/draft', src: KB('Secret/plan.md'), dest: KB('Secret/old/plan.md') };
+      const read = await call(base, 'read_file', { branch: args.branch, path: args.src });
+      expect(read.status).toBe(403);
+      for (const body of [{ ...args, dryRun: true }, args, { ...args, confirm: true }]) {
+        const res = await call(base, 'move_file', body);
+        expect(res.status).toBe(403);
+        expect(res.body).toEqual(read.body);
+      }
+      expect(resolved).toEqual([]);
+      expect(await exists(args.src)).toBe(true);
+    });
+
     it('an access-changing move shows before/after and runs only with confirm: true', async () => {
       const base = await seeded();
       const args = { src: KB('Sales/deal.md'), dest: KB('HR/deal.md') };
@@ -3648,13 +3660,18 @@ describe('preflight for moves and deletes', () => {
       expect(await exists(KB('Sales/moved'))).toBe(false);
     });
 
-    it('a denied move into a path the caller cannot read cannot be proposed, and says why', async () => {
+    it('a move into a folder the caller cannot read is refused as read_file refuses the folder, before the write verdict', async () => {
       const base = await seeded();
+      // The folder's rules are what a move preview would read back (the
+      // caller's verdicts there, who else is affected), so the read refusal
+      // comes first — not the write denial, which would say whether the path
+      // can be proposed and name the folder's contents on a collision.
       const run = await call(base, 'move_file', { src: KB('Sales/deal.md'), dest: KB('Secret/deal.md'), confirm: true });
       expect(run.status).toBe(403);
-      expect(run.body).toMatchObject({ kind: 'write-denied', canPropose: false });
+      expect(run.body.error).toContain(`permission to read "${KB('Secret')}"`);
+      expect(run.body.kind).toBeUndefined();
       expect(run.body.proposal).toBeUndefined();
-      expect(run.body.cannotProposeReason).toContain('you cannot read this path');
+      expect(await exists(KB('Sales/deal.md'))).toBe(true);
     });
 
     it('a draft branch is not write-gated, so the same move is allowed there', async () => {
@@ -4225,7 +4242,8 @@ describe('preflight for moves and deletes', () => {
       // The protocol itself, and what a platform folder does to it, are shared.
       const rules = sharedFileRulesSection(testKbContext().layout);
       expect(rules).toContain('`dryRun: true`');
-      expect(rules).toContain('A non-empty folder is deleted, and a move that changes your access runs, only with `confirm: true`');
+      // Anyone's: a move asks when it changes who else may open or edit the file too (`holderChanges`).
+      expect(rules).toContain("A non-empty folder is deleted, and a move that changes anyone's access runs, only with `confirm: true`");
       expect(rules).toContain('platform folder');
       const dry = await call(base, 'delete_folder', { path: KB('Sales/archive'), dryRun: true });
       const unconfirmed = await call(base, 'delete_folder', { path: KB('Sales/archive') });
@@ -4291,6 +4309,7 @@ describe('a write refused for permissions says whether and how to propose it', (
       canOwner: async () => true,
       canWriteBatchAtRef: async () => null,
       previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+      prospectiveHolderChanges: async () => NO_CHANGES,
       eligibleWritersAtRef: async () => ({ roles: ['Sales Lead'], users: [{ name: 'Owner', email: 'owner@x' }] }),
     } as unknown as IAccessControl;
     return { ac, calls };
@@ -5134,7 +5153,7 @@ describe('a move preview judges the destination as it will be', () => {
           ensureRemotesFetched: async () => undefined,
         } as unknown as WorkspaceService,
         KB_DIR,
-        new NodeFs(),
+        realDisk(),
       );
     return {
       canRead: (w: string, u: string, r: string) => fresh().canRead(w, u, r),
@@ -5146,6 +5165,7 @@ describe('a move preview judges the destination as it will be', () => {
       previewAccessAfterRelocation: (
         w: string, u: string, from: string, to: string, opts?: { sourceRemains?: boolean },
       ) => fresh().previewAccessAfterRelocation(w, u, from, to, opts),
+      prospectiveHolderChanges: (w: string, from: string, to: string) => fresh().prospectiveHolderChanges(w, from, to),
     } as unknown as IAccessControl;
   };
 
@@ -5189,6 +5209,8 @@ describe('a move preview judges the destination as it will be', () => {
     expect(dry.body).toMatchObject({ kind: 'folder', accessChanges: false, allowed: true, moved: false });
     expect(dry.body.access.after).toEqual(dry.body.access.before);
     expect(dry.body.access.after.owner).toBe(true);
+    // A rename carries its own rules along: nobody else gains or loses either.
+    expect(dry.body.holderChanges).toBeUndefined();
     // Nothing moved and nothing was written to answer the question.
     expect(await fs.exists(args.dest)).toBe(false);
     expect(await fs.exists(KB('Sales/access.md'))).toBe(true);
@@ -5213,6 +5235,91 @@ describe('a move preview judges the destination as it will be', () => {
     expect(await verbsAt(base, args.dest)).toEqual(dry.body.access.after);
   });
 
+  it('a move that changes only who ELSE may edit it names them, and asks before it moves', async () => {
+    const base = await seeded();
+    // `Ops/` gives the caller what `Sales/` gives, and Ops Lead write as well.
+    await fs.writeFile(
+      KB('Ops/access.md'),
+      rules(`write:\n  - Mover <${MOVER}>\n  - Ops Lead <ops@x.io>\nowner:\n  - Mover <${MOVER}>\n`),
+    );
+    const args = { src: KB('Sales/deal.md'), dest: KB('Ops/deal.md') };
+
+    const dry = await call(base, 'move_file', { ...args, dryRun: true });
+    expect(dry.body).toMatchObject({ accessChanges: false, allowed: true });
+    // Everyone may read on both sides, so the only change is who may edit.
+    expect(dry.body.holderChanges).toEqual({
+      lose: [],
+      gain: [{ kind: 'person', name: 'ops@x.io', email: 'ops@x.io', verb: 'write' }],
+    });
+
+    const unconfirmed = await call(base, 'move_file', args);
+    expect(unconfirmed.body).toMatchObject({ confirmationRequired: true, moved: false });
+    expect(unconfirmed.body.message).toContain('`holderChanges`');
+    expect(await fs.exists(args.src)).toBe(true);
+    expect((await call(base, 'move_file', { ...args, confirm: true })).body).toMatchObject({ moved: true });
+  });
+
+  it('a source the read hook refuses is refused as read_file refuses it: no preview, not even that the move would ask', async () => {
+    const base = await seeded();
+    await fs.writeFile(
+      KB('Ops/access.md'),
+      rules(`write:\n  - Mover <${MOVER}>\n  - Ops Lead <ops@x.io>\nowner:\n  - Mover <${MOVER}>\n`),
+    );
+    const args = { src: KB('Sales/deal.md'), dest: KB('Ops/deal.md'), rewriteLinks: false };
+    // The rules let the caller read it; a deployment's read hook does not. The
+    // hook's refusal is the whole answer: a "this move asks for confirm" would
+    // already say what the comparison found behind the hook.
+    hooks.onAgentRead(async (op) => {
+      if (op.wsPath === args.src) throw new Error('not for agents');
+    });
+    const read = await call(base, 'read_file', { path: args.src });
+    expect(read.status).toBeGreaterThanOrEqual(400);
+    for (const body of [{ ...args, dryRun: true }, args, { ...args, confirm: true }]) {
+      const res = await call(base, 'move_file', body);
+      expect(res.status).toBe(read.status);
+      expect(res.body).toEqual(read.body);
+      expect(JSON.stringify(res.body)).not.toContain('ops@x.io');
+    }
+    expect(await fs.exists(args.src)).toBe(true);
+  });
+
+  it('a caller who reads what moves but not the folder it lands in is refused, on a draft too, and told nothing of the folder', async () => {
+    const base = await seeded();
+    // `Closed/` is somebody else's: its rules are what a move preview would
+    // read back (who it lets in, whom it denies). On a draft no write gate
+    // stands, so the read gate is what refuses — before anything is looked at.
+    await fs.writeFile(
+      KB('Closed/access.md'),
+      rules('read:\n  - Other <other@x.io>\n  - deny everyone\nwrite:\n  - Other <other@x.io>\n'),
+    );
+    await fs.writeFile(KB('Closed/deal.md'), 'taken');
+    const args = { branch: 'someone/draft', src: KB('Sales/deal.md'), dest: KB('Closed/deal.md'), rewriteLinks: false };
+
+    for (const body of [{ ...args, dryRun: true }, args, { ...args, confirm: true }]) {
+      const res = await call(base, 'move_file', body);
+      expect(res.status).toBe(403);
+      expect(res.body.error).toContain(`permission to read "${KB('Closed')}"`);
+      // Neither the folder's rules nor what sits in it: the name clash at
+      // `Closed/deal.md` is never reached.
+      const text = JSON.stringify(res.body);
+      expect(text).not.toContain('other@x.io');
+      expect(text).not.toContain('already exists');
+    }
+    expect(await fs.exists(args.src)).toBe(true);
+    expect(await fs.readFile(KB('Closed/deal.md'), { encoding: 'utf8' })).toBe('taken');
+  });
+
+  it('a move out of a folder names everyone it leaves behind', async () => {
+    const base = await seeded();
+    const args = { src: KB('Work/Notes'), dest: KB('Legal/Notes') };
+    const dry = await call(base, 'move_file', { ...args, dryRun: true });
+    // Everyone may still read it in Legal/: the caller loses editing, not opening.
+    expect(dry.body.holderChanges).toEqual({
+      lose: [{ kind: 'person', name: MOVER, email: MOVER, verb: 'write' }],
+      gain: [],
+    });
+  });
+
   it('what the folder inherited is left behind; what its own access.md gives comes along', async () => {
     const base = await seeded();
     const args = { src: KB('Work/Team'), dest: KB('Legal/Team') };

package/src/modules/workspace/agent-access.gate.ts

@@ -32,7 +32,7 @@ import type { WorkflowHooks } from '../workflow/index.js';
  * takes, so a run's reads and its questions share one conversation.
  */
 export const SESSION_ID_DESCRIPTION =
-  "This conversation's id, so the server can tell one run's calls apart. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here — the same id `ask` takes. The in-process agent runtime supplies this automatically (do not set it yourself).";
+  "This conversation's id: call `start_session` once, at the start of your work, and pass its id here, inside `call_tool_chain` too (and to `ask`, where the deployment offers it). The in-process agent runtime sets it itself.";
 
 /**
  * The `sessionId` input every gated tool declares. The description a MOUNTED