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

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

@@ -1,4 +1,3 @@
-import { spawn } from 'node:child_process';
 import nodeFs from 'node:fs/promises';
 import { join } from 'node:path';
 import AdmZip from 'adm-zip';
@@ -11,7 +10,6 @@ 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';
@@ -29,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';
@@ -488,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;
@@ -508,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';
 }
@@ -548,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)
@@ -572,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;
@@ -584,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;
             }
         }
@@ -627,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, 
 /**
@@ -681,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
@@ -1314,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
@@ -1357,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
@@ -2005,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',
@@ -3589,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 };
 }