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

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

@@ -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';
@@ -21,7 +20,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,
@@ -70,6 +68,7 @@ import {
   type AgentGuideReader,
 } from '../agent-guide/agent-guide.js';
 import { removeEmptyDirs } from './empty-dirs.js';
+import { endsTheSearch, type IPatternMatcher, type IPatternSearch } from './pattern-matcher.contract.js';
 import { FIRST_RUN_SECTION_ID, firstRunNote, knowledgeFolderIsNew, type FirstRunStarterSource } from './first-run.js';
 import { planMoveLinks } from './move-links.js';
 import { MoveLockedError, MoveRacedError, type LockingFilesystem } from '../kb-fs/locking-filesystem.js';
@@ -674,7 +673,7 @@ type FileGrepOutcome =
 async function grepOneFile(
   fs: LocalFilesystem,
   path: string,
-  re: RegExp,
+  matcher: IPatternSearch,
   out: { path: string; line: number; text: string }[],
   max: number,
   docs: DocGrepState,
@@ -697,9 +696,10 @@ async function grepOneFile(
   }
   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';
 }
@@ -742,7 +742,7 @@ async function searchRootKind(
 async function grepWalk(
   fs: LocalFilesystem,
   dir: string,
-  re: RegExp,
+  matcher: IPatternSearch,
   out: { path: string; line: number; text: string }[],
   max: number,
   depth: number,
@@ -768,7 +768,7 @@ async function grepWalk(
     if (e.type !== 'directory' && isFolderPlaceholder(e.name)) continue;
     const p = dir ? `${dir}/${e.name}` : e.name;
     if (e.type === 'directory') {
-      await grepWalk(fs, p, re, out, max, depth + 1, gate, notifyRead, docs, skip);
+      await grepWalk(fs, p, matcher, out, max, depth + 1, gate, notifyRead, docs, skip);
     } else if (skip(p)) {
       continue;
     } else {
@@ -778,9 +778,12 @@ async function grepWalk(
       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);
-      } catch {
+        await grepOneFile(fs, p, matcher, out, max, docs);
+      } catch (err) {
+        if (endsTheSearch(err)) throw err;
         continue;
       }
     }
@@ -869,9 +872,10 @@ export interface WorkspaceToolsPorts {
  * 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: IToolRegistry,
@@ -935,6 +939,13 @@ export function registerWorkspaceTools(
    * file primitives; without it `start_session` answers the id alone.
    */
   disk?: ITreeWalker,
+  /**
+   * 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?: IPatternMatcher,
 ): WorkspaceToolsPorts {
   const { kbDirName } = kb;
   /**
@@ -1586,15 +1597,6 @@ export function registerWorkspaceTools(
      * read-only key may still not make (`request_file_download`).
      */
     writeScope?: boolean;
-    /**
-     * This tool resolves `branch` ITSELF and must not be pre-checked here.
-     * Only `execute_command` sets it: for an internal session that leaves the
-     * argument off, it falls back to the caller's own focused branch (from its
-     * signed token) rather than refusing. It still answers the same
-     * `branch-required` kind when there is nothing to fall back on — see its
-     * handler. Every other tool takes the check below.
-     */
-    resolvesBranchItself?: boolean;
     /** Arguments this tool refuses by name itself, with its own wording (see `ToolDefSpec.refusesItself`). */
     refusesItself?: string[];
     handler: ToolHandler;
@@ -1653,9 +1655,9 @@ export function registerWorkspaceTools(
     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,
@@ -1706,8 +1708,7 @@ export function registerWorkspaceTools(
             );
           }
         },
-        // `execute_command` resolves its own branch (see `resolvesBranchItself`).
-        { write: spec.write, writeScope: spec.writeScope, ...(spec.resolvesBranchItself ? { branch: 'own' as const } : {}) },
+        { write: spec.write, writeScope: spec.writeScope },
       ),
     );
   };
@@ -2385,171 +2386,172 @@ export function registerWorkspaceTools(
     },
   });
 
-  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: ToolContext) => {
-      let re: RegExp;
-      try {
-        re = new RegExp(a.pattern as string, a.ignore_case ? 'i' : '');
-      } catch (err) {
-        throw new ToolError(`Invalid regex: ${(err as Error).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 as string);
-      const gate = readGateFor(a.branch as string, ctx);
-      const out: { path: string; line: number; text: string }[] = [];
-      const max = typeof a.max_results === 'number' ? Math.min(a.max_results, 1000) : 200;
-      const docs: DocGrepState = { 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: string | undefined;
-      // 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 as string, searchRoot);
-      }
-      if (coversGuide) {
-        if (kind === 'directory') {
+      write: false,
+      handler: async (a, ctx: ToolContext) => {
+        // 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 as string, 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 as string);
+        const gate = readGateFor(a.branch as string, ctx);
+        const out: { path: string; line: number; text: string }[] = [];
+        const max = typeof a.max_results === 'number' ? Math.min(a.max_results, 1000) : 200;
+        const docs: DocGrepState = { 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: string | undefined;
+        // 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 as string, searchRoot);
+        }
+        if (coversGuide) {
+          if (kind === 'directory') {
+            await grepWalk(
+              fs,
+              searchRoot,
+              matcher,
+              out,
+              max,
+              0,
+              gate,
+              (p) => notifyAgentRead(agentAccessGate, ctx, a.branch as string, p),
+              docs,
+              (p) => p === guidePath,
+            );
+          }
+          const lines = (await guideAt(a.branch as string, 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,
+            matcher,
             out,
             max,
             0,
             gate,
             (p) => notifyAgentRead(agentAccessGate, ctx, a.branch as string, p),
             docs,
-            (p) => p === guidePath,
           );
+        } 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 lines = (await guideAt(a.branch as string, ctx, guidePath)).split('\n');
-        for (let i = 0; i < lines.length && out.length < max; i++) {
-          re.lastIndex = 0;
-          if (re.test(lines[i]!)) 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 as string, 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.';
-        }
-      }
-      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 } : {}),
-      };
-    },
-  });
+        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({
@@ -4065,194 +4067,6 @@ export function registerWorkspaceTools(
     });
   }
 
-  // ── 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: ToolContext) => {
-      // 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 as Error).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 as string).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 as string, { 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: unknown) => {
-          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 };
 }