@bevel-software/platform-core-backend 0.28.1 → 0.30.0

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

@@ -1,16 +1,15 @@
-import { spawn } from 'node:child_process';
 import nodeFs from 'node:fs/promises';
 import { join } from 'node:path';
 import AdmZip from 'adm-zip';
 import { hasHttpStatus, ToolError } from '../tool-helpers/tool.contract.js';
 import { BRANCH_INPUT, toolDef } from '../tool-helpers/tool-def.js';
 import { notifyAgentRead, assertAgentWriteAllowed, SESSION_ID_INPUT, } from './agent-access.gate.js';
+import { CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts } from '../tool-helpers/index.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
 // relies on) — not a workflow service, so this stays inside the module boundary.
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import { assertInsideRepo, assertRepoRootNameFree, assertRepoRootNameFreeArgs, isInsideRepo, normalizePathArgs, normalizeWorkspacePath, } from '../kb-fs/repo-path.js';
 import { GitGuardedFilesystem } from '../kb-fs/git-guarded-filesystem.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
@@ -28,6 +27,7 @@ import { folderPlaceholderPath, isFolderPlaceholder, isPlatformFile, isPlatformF
 import { AccessDeniedError } from '../access-model/access-errors.js';
 import { AGENT_GUIDE_FILE, isAgentGuidePath, isManagedGuide, withPlatformGuideAppended, } from '../agent-guide/agent-guide.js';
 import { removeEmptyDirs } from './empty-dirs.js';
+import { endsTheSearch } from './pattern-matcher.contract.js';
 import { FIRST_RUN_SECTION_ID, firstRunNote, knowledgeFolderIsNew } from './first-run.js';
 import { planMoveLinks } from './move-links.js';
 import { MoveLockedError, MoveRacedError } from '../kb-fs/locking-filesystem.js';
@@ -487,7 +487,7 @@ function modeOf(a) {
  * Throws whatever reading the file throws — the caller decides whether that is
  * a file to skip (the walk) or an error to surface (a single-file grep).
  */
-async function grepOneFile(fs, path, re, out, max, docs) {
+async function grepOneFile(fs, path, matcher, out, max, docs) {
     const reader = docs.readers.readerFor(path);
     const bytes = asBytes(await fs.readFile(path));
     let content = reader.greppableText ? await reader.greppableText(bytes, path) : null;
@@ -507,10 +507,10 @@ async function grepOneFile(fs, path, re, out, max, docs) {
     if (content === null)
         return 'no-text';
     const lines = content.split('\n');
-    for (let i = 0; i < lines.length && out.length < max; i++) {
-        re.lastIndex = 0;
-        if (re.test(lines[i]))
-            out.push({ path, line: i + 1, text: lines[i].slice(0, 300) });
+    // matchingLines posts these to the worker in bounded batches, so no one
+    // copy of a large file runs on the request thread.
+    for (const i of await matcher.matchingLines(lines, max - out.length)) {
+        out.push({ path, line: i + 1, text: lines[i].slice(0, 300) });
     }
     return 'searched';
 }
@@ -547,7 +547,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, notifyRead, docs, 
+async function grepWalk(fs, dir, matcher, out, max, depth, gate, notifyRead, docs, 
 /** A file the walk leaves to its caller: never opened, never counted against `max`. */
 skip = () => false) {
     if (out.length >= max || depth > 12)
@@ -571,7 +571,7 @@ skip = () => false) {
             continue;
         const p = dir ? `${dir}/${e.name}` : e.name;
         if (e.type === 'directory') {
-            await grepWalk(fs, p, re, out, max, depth + 1, gate, notifyRead, docs, skip);
+            await grepWalk(fs, p, matcher, out, max, depth + 1, gate, notifyRead, docs, skip);
         }
         else if (skip(p)) {
             continue;
@@ -583,10 +583,14 @@ skip = () => false) {
             await notifyRead(p);
             // A file the walk cannot read is silently skipped: one unreadable entry
             // must not fail a search over the whole tree.
+            // A pattern too expensive to finish, or no worker free to run it, is not
+            // an unreadable file: either ends the whole search.
             try {
-                await grepOneFile(fs, p, re, out, max, docs);
+                await grepOneFile(fs, p, matcher, out, max, docs);
             }
-            catch {
+            catch (err) {
+                if (endsTheSearch(err))
+                    throw err;
                 continue;
             }
         }
@@ -626,9 +630,10 @@ export function sessionIdInputOf(def) {
  * Workspace tools) + unzip. Most just re-expose the SAME `LocalFilesystem`
  * methods Mastra's tools call (via `ctx.getFilesystem(a.branch as string)`), so behaviour is
  * identical and write-side ops still flow through the lock/commit pipeline.
- * `edit_file`, `grep`, and `execute_command` are tool-level (no filesystem
- * 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).
+ * `edit_file` and `grep` are tool-level (no filesystem method), so they're
+ * implemented here. There is no shell tool: an agent never composes a command
+ * line, and every git operation it needs is a platform tool with fixed
+ * arguments.
  */
 export function registerWorkspaceTools(registry, router, toolAuth, toolHandler, spillStore, docExtract, accessControl, kb, agentAccessGate, writePolicy, sessionSink, 
 /**
@@ -680,7 +685,14 @@ starterPacks,
  * note's look at the knowledge folder. Optional for the harnesses about the
  * file primitives; without it `start_session` answers the id alone.
  */
-disk) {
+disk, 
+/**
+ * What runs a caller's `grep` pattern off the request thread, under a
+ * budget (see `pattern-matcher.contract.ts`). Owned by the composition
+ * root, which closes it with the graph. Optional for the harnesses about the
+ * other file primitives; without it `grep` is not mounted.
+ */
+patternMatcher) {
     const { kbDirName } = kb;
     /**
      * The one extension→reader registry every read-shaped decision routes
@@ -705,6 +717,23 @@ disk) {
     });
     /** A repo-relative path in the workspace-relative form every tool speaks. */
     const toWs = (rel) => (rel ? `${kbDirName}/${rel}` : kbDirName);
+    /**
+     * `canWrite` for workspace paths, as `list_files` and `read_file` report it:
+     * whether the caller may commit a change there directly on the DEFAULT
+     * branch, whichever branch the call read — one batch per call (see
+     * `defaultBranchWriteVerdicts`). The repository folder itself is judged as
+     * the repository root; a path outside the repository never lands on the
+     * default branch, so it is `false`.
+     */
+    const canWriteAt = async (ctx, wsPaths) => {
+        const relOf = (p) => {
+            const norm = p.replace(/^\/+/, '').replace(/\/+$/, '');
+            return norm === kbDirName ? '' : toKbRelative(norm, kbDirName);
+        };
+        const rels = wsPaths.map(relOf);
+        const verdicts = await defaultBranchWriteVerdicts({ accessControl, defaultWorkspaceId: () => kb.defaultWorkspaceId() }, ctx, rels.filter((r) => r !== null));
+        return new Map(wsPaths.map((p, i) => [p, rels[i] !== null && verdicts.get(rels[i]) === true]));
+    };
     const sourceToWs = (s) => (s ? { ...s, path: toWs(s.path) } : null);
     /**
      * What `file_stat` adds to its `access` verdicts when asked to explain them:
@@ -1296,9 +1325,9 @@ disk) {
         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.
+        // Internal-only tools keep their route mounted — our agent calls them over
+        // the same loopback — but gate them to internal-source callers so an
+        // external connection key can't invoke one by name.
         router.post(path.slice('/api'.length), toolAuth, ...(spec.internalOnly ? [requireInternalSource] : []), 
         // EVERY path input becomes a repository path here, once, before any
         // handler runs: the root-anchored `/<kbDirName>/…` form Copy path gives
@@ -1339,9 +1368,7 @@ disk) {
             catch (err) {
                 return rethrowAsWriteDenial(err, { tool: spec.name, branch: args.branch, userEmail: ctx.user.email, userId: ctx.user.id }, accessControl, kb, changeGate);
             }
-        }, 
-        // `execute_command` resolves its own branch (see `resolvesBranchItself`).
-        { write: spec.write, writeScope: spec.writeScope, ...(spec.resolvesBranchItself ? { branch: 'own' } : {}) }));
+        }, { write: spec.write, writeScope: spec.writeScope }));
     };
     // ── session bootstrap (external agents) ─────────────────────────────────
     // Every read/write tool below takes a `sessionId`: the conversation the
@@ -1467,7 +1494,14 @@ disk) {
      * hook, the extraction and the not-found message all have to match, and a
      * copy drifts on the first change to any of them.
      */
-    const readForTool = async (branch, p, ctx) => {
+    const readForTool = async (branch, p, ctx) => (await readServed(branch, p, ctx)).result;
+    /**
+     * {@link readForTool}, also saying, at the guide's name, whether a file of
+     * the knowledge base's own answered first on THIS branch (`guide`: `own`)
+     * or the platform's guide answered alone (`alone`); `null` for any other
+     * path. `read_file` needs it to judge `canWrite` there (see its handler).
+     */
+    const readServed = async (branch, p, ctx) => {
         // The guide's name at the repository root answers with the platform's
         // guide, which is text the code owns and every agent may read: no gate
         // and no read hook for it. A file the knowledge base keeps under that
@@ -1476,7 +1510,8 @@ disk) {
         // guide an earlier release wrote to disk (still on a draft, say) is
         // recognised by its header and not served a second time.
         if (agentGuide && isAgentGuidePath(toKbRelative(p, kbDirName) ?? '')) {
-            return { kind: 'text', text: await guideAt(branch, ctx, p) };
+            const { text, own } = await guideServed(branch, ctx, p);
+            return { result: { kind: 'text', text }, guide: own ? 'own' : 'alone' };
         }
         await notifyAgentRead(agentAccessGate, ctx, branch, p);
         await assertCanRead(readGateFor(branch, ctx), p);
@@ -1485,18 +1520,38 @@ disk) {
         // the access gate and the read hook above — a document read is still a
         // KB read. ONE registry dispatch picks the reader by extension.
         const bytes = await orNotFound(p, async () => asBytes(await fs.readFile(p)));
-        return readers.readerFor(p).read(bytes, p);
+        return { result: await readers.readerFor(p).read(bytes, p), guide: null };
+    };
+    /**
+     * Whether the DEFAULT branch has a file of the knowledge base's own at the
+     * guide's name that this caller may read — not a copy of the platform's
+     * guide an earlier release wrote. Telling the two apart reads the file, so
+     * that branch's read hook is asked first, as {@link ownGuideFile} does —
+     * after the gate, before the bytes. A refusal, like any failure, is
+     * `false`, so `canWrite` fails closed.
+     */
+    const ownGuideOnDefault = async (ctx, p) => {
+        try {
+            const fs = await ctx.getFilesystem(kb.defaultBranch);
+            if (!(await ownGuideReadable(fs, kb.defaultBranch, ctx, p)))
+                return false;
+            await notifyAgentRead(agentAccessGate, ctx, kb.defaultBranch, p);
+            return await isOwnEntryStill(fs, p);
+        }
+        catch {
+            return false;
+        }
     };
     mount({
         name: 'read_file',
         gated: true,
-        description: 'Read a workspace file as text. Returns `{ path, content }`. What comes back for a document, an email file, an image ' +
-            'or any other binary file is the content rule\'s business (see the shared rules): text files as text, documents and ' +
-            'email files as extracted text, an image as the picture itself, anything else as a one-line description. ' +
-            'Optional `offset`/`limit` slice the content (characters for a file, bytes for a `__tool_chain_spill__/…` ref; ignored ' +
-            'for an image) — use them to page through large files or a `call_tool_chain` spill rather than reading multi-MB in full. ' +
-            'It also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: such a ref belongs to no ' +
-            'workspace, so `branch` is ignored for it.',
+        description: 'Read a workspace file as text. Returns `{ path, content, canWrite }`. Per the shared content rule: text as ' +
+            'text, documents and email as extracted text, an image as the picture, anything else as a one-line ' +
+            'description. Also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: it ' +
+            'belongs to no workspace, so `branch` is ignored and no `canWrite` comes back. `offset`/`limit` slice the ' +
+            'content (characters; bytes for a spill ref; ignored for an image): page through large files and ' +
+            'spills, never read multi-MB whole. `canWrite`: may you change this file directly on the default branch. ' +
+            CAN_WRITE_CLAUSE,
         inputs: {
             type: 'object',
             properties: {
@@ -1511,7 +1566,15 @@ disk) {
         },
         outputs: {
             type: 'object',
-            properties: { path: str('The path that was read (echoes the input).'), content: str('File (or spill) content, sliced if offset/limit were given.') },
+            properties: {
+                path: str('The path that was read (echoes the input).'),
+                content: str('File (or spill) content, sliced if offset/limit were given.'),
+                canWrite: {
+                    type: 'boolean',
+                    description: 'Whether you may commit a change to this file directly on the default branch, under that branch\'s access ' +
+                        'rules — the same answer whichever branch you read. Absent for a spill ref.',
+                },
+            },
             required: ['path', 'content'],
         },
         write: false,
@@ -1528,7 +1591,18 @@ disk) {
                     ? content.slice(start, limit !== undefined ? start + limit : undefined)
                     : content;
             };
-            const result = await readForTool(a.branch, p, ctx);
+            const branch = a.branch;
+            const { result, guide } = await readServed(branch, p, ctx);
+            // Judged after the read, so a path the caller may not read is refused
+            // before anything is said about writing it. At the guide's name this
+            // answers for the knowledge base's own file there, as `file_stat` does:
+            // where the platform's guide stands alone there is nothing to change —
+            // `false`, whether nothing is there or a file the caller may not read.
+            // Like every verdict here, that is decided on the DEFAULT branch, not
+            // the one read: a draft that deleted or added the file must not move
+            // the answer about what can land directly.
+            const ownOnDefault = guide === null || (branch === kb.defaultBranch ? guide === 'own' : await ownGuideOnDefault(ctx, p));
+            const canWrite = ownOnDefault && (await canWriteAt(ctx, [p])).get(p) === true;
             // Images return the picture itself as an MCP image content block, so a
             // multimodal model SEES it. The handler returns the `McpImageResult`
             // sentinel; the MCP result shaping (`toCallToolResult` in
@@ -1540,14 +1614,17 @@ disk) {
             // content blocks before any client could try to validate it, so the
             // schema keeps describing the text path it has always described.
             // `offset`/`limit` are meaningless on a picture and are ignored.
+            // The picture's answer has no fields beside it, so its `canWrite` rides
+            // in the text note that accompanies it.
             if (result.kind === 'image') {
-                return mcpImageResult(result.data, result.mimeType, result.note);
+                const verdict = `canWrite: ${canWrite}`;
+                return mcpImageResult(result.data, result.mimeType, result.note ? `${result.note} (${verdict})` : verdict);
             }
             // Text and refusals alike land in `content` — a refusal (corrupt
             // document, unreadable binary, oversized image) IS the file's honest
             // textual answer, sliced like any other content.
             const content = result.kind === 'text' ? result.text : result.message;
-            return { path: p, content: slice(content) };
+            return { path: p, content: slice(content), canWrite };
         },
     });
     /**
@@ -1566,10 +1643,12 @@ disk) {
      * node is indistinguishable from an absent one on every other read.
      */
     /** What a read of the guide's path answers: the guide, after the knowledge base's own readable file when it has one. */
-    const guideAt = async (branch, ctx, p) => {
+    const guideAt = async (branch, ctx, p) => (await guideServed(branch, ctx, p)).text;
+    /** {@link guideAt}, also saying whether a file of the knowledge base's own came first. */
+    const guideServed = async (branch, ctx, p) => {
         const guide = await agentGuide();
         const own = await ownGuideFile(branch, ctx, p);
-        return own === null ? guide : withPlatformGuideAppended(own, guide);
+        return own === null ? { text: guide, own: false } : { text: withPlatformGuideAppended(own, guide), own: true };
     };
     const ownGuideFile = async (branch, ctx, p) => {
         const fs = await ctx.getFilesystem(branch);
@@ -1646,7 +1725,8 @@ disk) {
     mount({
         name: 'list_files',
         gated: true,
-        description: `List a directory. Returns \`{ path, entries: [{ name, type, size? }] }\`. Omit \`path\` for the workspace root, which holds the repository as the \`${kbDirName}/\` folder: every content path is under it (e.g. \`${kbDirName}/KnowledgeBase\`), and a path given without that prefix is placed under it.`,
+        description: `List a directory. Returns \`{ path, entries: [{ name, type, size?, canWrite }] }\`. 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. ` +
+            `\`canWrite\`: may you change that file, or add a file directly inside that folder, directly on the default branch. ${CAN_WRITE_CLAUSE}`,
         inputs: {
             type: 'object',
             properties: {
@@ -1666,8 +1746,18 @@ disk) {
                     description: 'Directory entries.',
                     items: {
                         type: 'object',
-                        properties: { name: str('Entry name.'), type: str('`file` or `directory`.'), size: int('Size in bytes (files only).') },
-                        required: ['name', 'type'],
+                        properties: {
+                            name: str('Entry name.'),
+                            type: str('`file` or `directory`.'),
+                            size: int('Size in bytes (files only).'),
+                            canWrite: {
+                                type: 'boolean',
+                                description: 'Whether you may commit directly on the default branch, under that branch\'s access rules: for a ' +
+                                    'file, a change to it; for a folder, a new file directly inside it, by that folder\'s own rules. ' +
+                                    'The same answer whichever branch you listed.',
+                            },
+                        },
+                        required: ['name', 'type', 'canWrite'],
                     },
                 },
             },
@@ -1680,7 +1770,12 @@ disk) {
             const fs = await ctx.getFilesystem(a.branch);
             const entries = withoutPlaceholder((await fs.readdir(dir || '.')));
             const filtered = await filterReadableEntries(readGateFor(a.branch, ctx), dir, entries);
-            return { path: a.path ?? '', entries: filtered };
+            // One batch for the listing. A folder is judged at its own path, whose
+            // rules (its `access.md` and those above it) are what a file added
+            // directly inside it would get.
+            const wsPathOf = (e) => (dir ? `${dir}/${e.name}` : e.name);
+            const verdicts = await canWriteAt(ctx, filtered.map(wsPathOf));
+            return { path: a.path ?? '', entries: filtered.map((e) => ({ ...e, canWrite: verdicts.get(wsPathOf(e)) === true })) };
         },
     });
     mount({
@@ -1919,147 +2014,146 @@ disk) {
             return { ...out, ...fileTypeOf(reader, p, bytes) };
         },
     });
-    mount({
-        name: 'grep',
-        gated: true,
-        description: 'Regex 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: {
-                branch: BRANCH_INPUT,
-                pattern: str('JavaScript regular expression.'),
-                path: str(`Subtree to search, or a single file to search on its own, with or without a leading slash — a path without the \`${kbDirName}/\` prefix is placed under \`${kbDirName}/\` (default: the whole repository, \`${kbDirName}/\`).`),
-                ignore_case: { type: 'boolean', description: 'Case-insensitive match.' },
-                max_results: { type: 'integer', minimum: 1, maximum: 1000, description: 'Cap on matches (default 200).' },
-                sessionId: SESSION_ID_INPUT,
+    // Mounted only when the composition supplied a matcher — see the
+    // `patternMatcher` parameter. Core always does.
+    if (patternMatcher) {
+        const patterns = patternMatcher;
+        mount({
+            name: 'grep',
+            gated: true,
+            description: 'Regex 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: {
+                    branch: BRANCH_INPUT,
+                    pattern: str('JavaScript regular expression.'),
+                    path: str(`Subtree to search, or a single file to search on its own, with or without a leading slash — a path without the \`${kbDirName}/\` prefix is placed under \`${kbDirName}/\` (default: the whole repository, \`${kbDirName}/\`).`),
+                    ignore_case: { type: 'boolean', description: 'Case-insensitive match.' },
+                    max_results: { type: 'integer', minimum: 1, maximum: 1000, description: 'Cap on matches (default 200).' },
+                    sessionId: SESSION_ID_INPUT,
+                },
+                required: ['branch', 'pattern'],
+                additionalProperties: false,
             },
-            required: ['branch', 'pattern'],
-            additionalProperties: false,
-        },
-        outputs: {
-            type: 'object',
-            properties: {
-                matches: {
-                    type: 'array',
-                    description: 'Matching lines (capped by `max_results`).',
-                    items: {
-                        type: 'object',
-                        properties: { path: str('Workspace-relative file path.'), line: int('1-based line number.'), text: str('The matching line (truncated to 300 chars).') },
-                        required: ['path', 'line', 'text'],
+            outputs: {
+                type: 'object',
+                properties: {
+                    matches: {
+                        type: 'array',
+                        description: 'Matching lines (capped by `max_results`).',
+                        items: {
+                            type: 'object',
+                            properties: { path: str('Workspace-relative file path.'), line: int('1-based line number.'), text: str('The matching line (truncated to 300 chars).') },
+                            required: ['path', 'line', 'text'],
+                        },
                     },
+                    truncated: { type: 'boolean', description: 'True if the match cap was hit and results may be incomplete.' },
+                    note: str('Present when the empty/partial result needs explaining: a `path` naming a file with no searchable text (image, binary, corrupt document), or documents (office/PDF/email files) left unsearched because their text was not yet extracted and the per-call extraction budget ran out — re-run grep to cover those.'),
                 },
-                truncated: { type: 'boolean', description: 'True if the match cap was hit and results may be incomplete.' },
-                note: str('Present when the empty/partial result needs explaining: a `path` naming a file with no searchable text (image, binary, corrupt document), or documents (office/PDF/email files) left unsearched because their text was not yet extracted and the per-call extraction budget ran out — re-run grep to cover those.'),
+                required: ['matches', 'truncated'],
             },
-            required: ['matches', 'truncated'],
-        },
-        write: false,
-        handler: async (a, ctx) => {
-            let re;
-            try {
-                re = new RegExp(a.pattern, a.ignore_case ? 'i' : '');
-            }
-            catch (err) {
-                throw new ToolError(`Invalid regex: ${err.message}`, 400);
-            }
-            // No path means the whole REPOSITORY, not the workspace directory above
-            // it. The workspace root also holds whatever an older build left beside
-            // the checkout, and the read gate has no rules for a path outside the
-            // repository — it answers "readable" — so a walk from there would hand
-            // any caller the contents of every stray, including documents that were
-            // uploaded to a restricted folder and landed beside it instead. The
-            // boot note names those for an operator; no tool reads them.
-            // An EMPTY string is the same absence: the normaliser leaves it alone
-            // (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;
-            const fs = await ctx.getFilesystem(a.branch);
-            const gate = readGateFor(a.branch, ctx);
-            const out = [];
-            const max = typeof a.max_results === 'number' ? Math.min(a.max_results, 1000) : 200;
-            const docs = { readers, uncachedBudget: UNCACHED_DOCS_PER_GREP, skippedUncached: 0 };
-            // The empty root is the workspace itself — always a directory, and never
-            // worth a stat.
-            // A placeholder named on its own is searched as what it is to every
-            // other tool: nothing.
-            const kind = searchRoot === ''
-                ? 'directory'
-                : isFolderPlaceholder(searchRoot)
-                    ? 'missing'
-                    : await searchRootKind(fs, searchRoot);
-            /** Why a single-file search found nothing, when "no matches" would be a lie. */
-            let fileNote;
-            // The guide is searched where it is read: a search of the repository
-            // root covers it, and a search of its own path is a search of what
-            // `read_file` answers there. The composed text is what is searched —
-            // the knowledge base's own readable file first, then the platform's
-            // guide — under the guide's path and with the line numbers a read of
-            // it gives. The walk leaves that one file to this: a match the walk
-            // made there would be the same line again, and one it COUNTED against
-            // `max_results` would be a file later in the tree never searched while
-            // the answer says nothing was cut. A file the caller may not read is
-            // absent from it, as it is from the read.
-            const guidePath = `${kbDirName}/${AGENT_GUIDE_FILE}`;
-            const rel = toKbRelative(searchRoot, kbDirName);
-            const coversGuide = agentGuide !== undefined && (kind === 'directory' ? rel === null : isAgentGuidePath(rel ?? ''));
-            // The search root goes to the read hook — once, and only when it is
-            // repository content: a folder, or a file of the knowledge base's own.
-            // The guide's own path is not told here, because `guideAt` tells the
-            // hook of the organisation's file there exactly as `read_file` does
-            // (after the gate), and the platform's guide alone is nobody's file to
-            // note. Each file the walk opens goes to the hook per file below, so a
-            // hook sees every path a grep reached rather than only its root.
-            if (!(coversGuide && kind !== 'directory')) {
-                await notifyAgentRead(agentAccessGate, ctx, a.branch, searchRoot);
-            }
-            if (coversGuide) {
-                if (kind === 'directory') {
-                    await grepWalk(fs, searchRoot, re, out, max, 0, gate, (p) => notifyAgentRead(agentAccessGate, ctx, a.branch, p), docs, (p) => p === guidePath);
+            write: false,
+            handler: async (a, ctx) => {
+                // The caller's pattern never runs on the request thread: a backtracking
+                // one would hold the event loop for everyone (see IPatternMatcher).
+                const matcher = patterns.search(a.pattern, a.ignore_case ? 'i' : '');
+                // No path means the whole REPOSITORY, not the workspace directory above
+                // it. The workspace root also holds whatever an older build left beside
+                // the checkout, and the read gate has no rules for a path outside the
+                // repository — it answers "readable" — so a walk from there would hand
+                // any caller the contents of every stray, including documents that were
+                // uploaded to a restricted folder and landed beside it instead. The
+                // boot note names those for an operator; no tool reads them.
+                // An EMPTY string is the same absence: the normaliser leaves it alone
+                // (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;
+                const fs = await ctx.getFilesystem(a.branch);
+                const gate = readGateFor(a.branch, ctx);
+                const out = [];
+                const max = typeof a.max_results === 'number' ? Math.min(a.max_results, 1000) : 200;
+                const docs = { readers, uncachedBudget: UNCACHED_DOCS_PER_GREP, skippedUncached: 0 };
+                // The empty root is the workspace itself — always a directory, and never
+                // worth a stat.
+                // A placeholder named on its own is searched as what it is to every
+                // other tool: nothing.
+                const kind = searchRoot === ''
+                    ? 'directory'
+                    : isFolderPlaceholder(searchRoot)
+                        ? 'missing'
+                        : await searchRootKind(fs, searchRoot);
+                /** Why a single-file search found nothing, when "no matches" would be a lie. */
+                let fileNote;
+                // The guide is searched where it is read: a search of the repository
+                // root covers it, and a search of its own path is a search of what
+                // `read_file` answers there. The composed text is what is searched —
+                // the knowledge base's own readable file first, then the platform's
+                // guide — under the guide's path and with the line numbers a read of
+                // it gives. The walk leaves that one file to this: a match the walk
+                // made there would be the same line again, and one it COUNTED against
+                // `max_results` would be a file later in the tree never searched while
+                // the answer says nothing was cut. A file the caller may not read is
+                // absent from it, as it is from the read.
+                const guidePath = `${kbDirName}/${AGENT_GUIDE_FILE}`;
+                const rel = toKbRelative(searchRoot, kbDirName);
+                const coversGuide = agentGuide !== undefined && (kind === 'directory' ? rel === null : isAgentGuidePath(rel ?? ''));
+                // The search root goes to the read hook — once, and only when it is
+                // repository content: a folder, or a file of the knowledge base's own.
+                // The guide's own path is not told here, because `guideAt` tells the
+                // hook of the organisation's file there exactly as `read_file` does
+                // (after the gate), and the platform's guide alone is nobody's file to
+                // note. Each file the walk opens goes to the hook per file below, so a
+                // hook sees every path a grep reached rather than only its root.
+                if (!(coversGuide && kind !== 'directory')) {
+                    await notifyAgentRead(agentAccessGate, ctx, a.branch, searchRoot);
                 }
-                const lines = (await guideAt(a.branch, ctx, guidePath)).split('\n');
-                for (let i = 0; i < lines.length && out.length < max; i++) {
-                    re.lastIndex = 0;
-                    if (re.test(lines[i]))
+                if (coversGuide) {
+                    if (kind === 'directory') {
+                        await grepWalk(fs, searchRoot, matcher, out, max, 0, gate, (p) => notifyAgentRead(agentAccessGate, ctx, a.branch, p), docs, (p) => p === guidePath);
+                    }
+                    const lines = (await guideAt(a.branch, ctx, guidePath)).split('\n');
+                    for (const i of await matcher.matchingLines(lines, max - out.length)) {
                         out.push({ path: guidePath, line: i + 1, text: lines[i].slice(0, 300) });
+                    }
                 }
-            }
-            else if (kind === 'directory') {
-                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
-                // one, and it is `read_file`'s own gate on the same path — so grep
-                // answers a path the caller may not read exactly as read_file does,
-                // and can never confirm the existence of one read_file would hide.
-                // That ordering holds even when the stat itself failed: a denied path
-                // gets the 403, never the filesystem's complaint about it.
-                await assertCanRead(gate, searchRoot);
-                if (kind === 'missing')
-                    throw notFound(searchRoot, 'Nothing to search');
-                // A named FILE is searched directly: routing it through the walk would
-                // fail its readdir and answer an empty match list, which the caller
-                // cannot tell from "the pattern is not in this file".
-                const outcome = await orNotFound(searchRoot, () => grepOneFile(fs, searchRoot, re, out, max, docs), 'Nothing to search');
-                if (outcome === 'no-text') {
-                    fileNote =
-                        `"${displayPath(searchRoot)}" has no searchable text — it is an image, binary content, or a document ` +
-                            'whose text could not be extracted. There were no matches because there was nothing to search, not ' +
-                            'because the pattern is absent.';
+                else if (kind === 'directory') {
+                    await grepWalk(fs, searchRoot, matcher, out, max, 0, gate, (p) => notifyAgentRead(agentAccessGate, ctx, a.branch, p), docs);
                 }
-            }
-            const note = fileNote ??
-                (docs.skippedUncached > 0
-                    ? `${docs.skippedUncached} document(s) (office/PDF/email files) were not searched: their text was not yet ` +
-                        `extracted and this call's extraction budget (${UNCACHED_DOCS_PER_GREP}) ran out. Re-run the ` +
-                        'same grep to extract and search the next batch.'
-                    : undefined);
-            return {
-                matches: out,
-                truncated: out.length >= max,
-                ...(note !== undefined ? { note } : {}),
-            };
-        },
-    });
+                else {
+                    // Not a directory: the permission verdict comes BEFORE every other
+                    // one, and it is `read_file`'s own gate on the same path — so grep
+                    // answers a path the caller may not read exactly as read_file does,
+                    // and can never confirm the existence of one read_file would hide.
+                    // That ordering holds even when the stat itself failed: a denied path
+                    // gets the 403, never the filesystem's complaint about it.
+                    await assertCanRead(gate, searchRoot);
+                    if (kind === 'missing')
+                        throw notFound(searchRoot, 'Nothing to search');
+                    // A named FILE is searched directly: routing it through the walk would
+                    // fail its readdir and answer an empty match list, which the caller
+                    // cannot tell from "the pattern is not in this file".
+                    const outcome = await orNotFound(searchRoot, () => grepOneFile(fs, searchRoot, matcher, out, max, docs), 'Nothing to search');
+                    if (outcome === 'no-text') {
+                        fileNote =
+                            `"${displayPath(searchRoot)}" has no searchable text — it is an image, binary content, or a document ` +
+                                'whose text could not be extracted. There were no matches because there was nothing to search, not ' +
+                                'because the pattern is absent.';
+                    }
+                }
+                const note = fileNote ??
+                    (docs.skippedUncached > 0
+                        ? `${docs.skippedUncached} document(s) (office/PDF/email files) were not searched: their text was not yet ` +
+                            `extracted and this call's extraction budget (${UNCACHED_DOCS_PER_GREP}) ran out. Re-run the ` +
+                            'same grep to extract and search the next batch.'
+                        : undefined);
+                return {
+                    matches: out,
+                    truncated: out.length >= max,
+                    ...(note !== undefined ? { note } : {}),
+                };
+            },
+        });
+    }
     // ── writes (through the lock/commit pipeline) ───────────────────────────
     mount({
         name: 'write_file',
@@ -3503,188 +3597,6 @@ disk) {
             };
         });
     }
-    // ── shell (internal-only) ───────────────────────────────────────────────
-    mount({
-        name: 'execute_command',
-        gated: true,
-        description: 'Run a shell command in the workspace directory. Returns `{ stdout, stderr, exitCode }` (output capped). Use for git status/log, grep/rg, build/test commands.',
-        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: {
-                branch: BRANCH_INPUT,
-                command: str('The shell command line to run.'),
-                timeout_ms: { type: 'integer', minimum: 1000, maximum: 120000, description: 'Timeout in ms (default 30000).' },
-                sessionId: SESSION_ID_INPUT,
-            },
-            // `branch` stays REQUIRED here on purpose, and must not be relaxed to make
-            // the handler's focused-branch fallback "reachable". This list is the
-            // contract the model is TAUGHT — declaring it required is what makes the
-            // caller always name its branch, which is the fix for the workspace this
-            // tool used to resolve as "undefined". It is not a runtime gate: nothing in
-            // the tool route validates inputs against this schema, so a branch-less call
-            // still reaches the handler and still hits the `ctx.focusedBranch` fallback
-            // (covered by "falls back to the session focused branch when branch is
-            // omitted"). The fallback is a safety net for a model that disobeys the
-            // contract — not a sanctioned calling convention to advertise.
-            required: ['branch', 'command'],
-            additionalProperties: false,
-        },
-        outputs: {
-            type: 'object',
-            properties: {
-                stdout: str('Captured standard output (truncated to 50,000 chars).'),
-                stderr: str('Captured standard error (truncated to 50,000 chars).'),
-                exitCode: int('Process exit code; -1 if it was killed (timeout/abort) or failed to spawn.'),
-            },
-            required: ['stdout', 'stderr', 'exitCode'],
-        },
-        write: true,
-        handler: async (a, ctx) => {
-            // Resolve the branch FIRST — before the policy gates below — so a malformed
-            // call always gets the 400 that names what is missing, rather than a 403
-            // from a restricted session masking it. Unlike the file tools (which route
-            // through `getOrCreateForUser` and fall back to the default branch),
-            // execute_command turns `branch` straight into a workspace — so a bad value
-            // would `encodeURIComponent(undefined)` to the string "undefined", then try
-            // to CLONE a branch literally named "undefined", 500ing and leaving an
-            // `<workspaces>/undefined/` shell behind.
-            //
-            // Two distinct cases:
-            //  - branch OMITTED (`undefined`): the in-app chat agent may leave it off a
-            //    call. For an internal session we fall back to the caller's own focused
-            //    branch (`ctx.focusedBranch`, from its signed token), so the command runs
-            //    against the workspace the session is on (e.g. `main`) end to end. An
-            //    external caller carries no focused branch, so it stays absent → 400.
-            //  - branch PRESENT but invalid (the literal "undefined"/"null", empty, or
-            //    malformed): a broken value, never a real branch — fail closed, never
-            //    silently reinterpret it as the focused branch.
-            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, 
-                // 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
-            // is the whole bug this tool is guarded for: `getOrCreateForBranch("undefined")`
-            // clones a branch literally named "undefined" into `<workspaces>/undefined/`
-            // 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, { 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
-            // miss malformed refs (`..`, `-x`, `foo/.lock`) and reserve names git
-            // considers perfectly valid. Runs on the RAW string, so a whitespace-padded
-            // `" main "` is refused rather than silently trimmed into a different
-            // branch than the caller passed.
-            try {
-                assertValidBranchName(branch);
-            }
-            catch (err) {
-                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 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 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.
-            const cwd = (await ctx.workspaceService.getOrCreateForBranch(branch)).absolutePath;
-            const timeoutMs = typeof a.timeout_ms === 'number' ? a.timeout_ms : 30_000;
-            // cwd is the workspace ROOT so shell paths match the workspace-relative
-            // paths every other file tool uses — but the git clone lives one level
-            // deeper, at <workspace>/<kbDirName>/.git. For a bare `git status` /
-            // `git diff` (what the agent prompt teaches) point git there explicitly so
-            // it resolves the KB clone instead of failing with "not a git repository".
-            //
-            // Because the command runs under `shell: true`, GIT_DIR/GIT_WORK_TREE
-            // apply to the WHOLE shell, so restrict the override to a *standalone* bare
-            // `git …` invocation. Otherwise the KB repo context would (a) leak into a
-            // chained step that spawns its own git — `git commit && npm ci` — and (b)
-            // override a caller's explicit `git -C …` / `--git-dir` / `--work-tree`.
-            const command = a.command.trim();
-            const isStandaloneGit = /^git(\s|$)/.test(command) &&
-                !/[;&|`\n]|\$\(/.test(command) &&
-                !/(?:^|\s)(?:-C|--git-dir|--work-tree)(?:[=\s]|$)/.test(command);
-            const env = isStandaloneGit
-                ? {
-                    ...process.env,
-                    GIT_DIR: join(cwd, kbDirName, '.git'),
-                    GIT_WORK_TREE: join(cwd, kbDirName),
-                }
-                : process.env;
-            return new Promise((resolve) => {
-                // Own process group on POSIX, so a timeout or abort kills the WHOLE
-                // tree. `shell: true` puts an `sh` between us and the command; killing
-                // only that shell left whatever it had started running on — orphaned,
-                // unreaped, still holding the workspace and its memory. A self-hosted
-                // deployment leaked ~4,500 tasks that way before nothing could fork.
-                const detached = process.platform !== 'win32';
-                const child = spawn(a.command, { cwd, shell: true, env, detached });
-                let stdout = '';
-                let stderr = '';
-                const killTree = () => {
-                    try {
-                        if (detached && child.pid)
-                            process.kill(-child.pid, 'SIGKILL');
-                        else
-                            child.kill('SIGKILL');
-                    }
-                    catch {
-                        try {
-                            child.kill('SIGKILL');
-                        }
-                        catch {
-                            // Already gone.
-                        }
-                    }
-                };
-                const timer = setTimeout(killTree, timeoutMs);
-                // If the caller disconnects (request aborted), kill the tree instead of
-                // letting it run to the timeout; the resulting `close`/`error` settles
-                // the promise through `finish`.
-                const onAbort = killTree;
-                ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
-                const finish = (value) => {
-                    clearTimeout(timer);
-                    ctx.abortSignal.removeEventListener('abort', onAbort);
-                    resolve(value);
-                };
-                // Cap accumulation while streaming so a verbose command can't exhaust
-                // memory before `close`; the final slice keeps the output bound.
-                const OUTPUT_CAP = 50_000;
-                child.stdout.on('data', (d) => {
-                    if (stdout.length < OUTPUT_CAP)
-                        stdout += d.toString();
-                });
-                child.stderr.on('data', (d) => {
-                    if (stderr.length < OUTPUT_CAP)
-                        stderr += d.toString();
-                });
-                child.on('close', (code) => {
-                    finish({ stdout: stdout.slice(0, 50_000), stderr: stderr.slice(0, 50_000), exitCode: code ?? -1 });
-                });
-                child.on('error', (err) => {
-                    finish({ stdout, stderr: `${stderr}\n${String(err)}`.slice(0, 50_000), exitCode: -1 });
-                });
-            });
-        },
-    });
     // The one read `open_page` borrows — see `readForTool` above.
     return { readForTool };
 }