@semalt-ai/code 1.8.5 → 1.20.0

package/test/grep-glob-serialize.test.js

@@ -0,0 +1,242 @@
+'use strict';
+
+// Task W.5 — grep/glob result serialization + output modes + head_limit.
+//
+// THE BUG these tests pin: formatFileResult had no `grep`/`glob` case, so both
+// fell through to the default and the model received "grep: done" / "glob: done"
+// — the engine computed the matches (and the UI even printed a count) but the
+// STRUCTURED RESULT WAS DROPPED before it entered context. These tests assert
+// what the MODEL receives (the audit's empirical method), not just what the
+// engine returns: the pure serializers AND the real agent loop feeding the tool
+// result back to the model.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ui = require('../lib/ui');
+const { createApiClient } = require('../lib/api');
+const { createToolExecutor, extractToolCalls } = require('../lib/tools');
+const { createPermissionManager } = require('../lib/permissions');
+const { createAgentRunner, formatGrepResult, formatGlobResult } = require('../lib/agent');
+const { startMockLLM } = require('./harness/mock-llm');
+
+// ---------------------------------------------------------------------------
+// Part A — pure model-facing serialization (formatGrepResult / formatGlobResult)
+// ---------------------------------------------------------------------------
+
+function grepResult(matches, extra = {}) {
+  return { matches, pattern: 'TODO', count: matches.length, output_mode: 'content', ...extra };
+}
+
+test('content mode (default): serializes file:line:text per match — NOT "grep: done"', () => {
+  const out = formatGrepResult(grepResult([
+    { file: 'a.js', line: 3, text: '  // TODO fix' },
+    { file: 'b.js', line: 9, text: 'x = 1 // TODO' },
+  ]));
+  assert.match(out, /a\.js:3:  \/\/ TODO fix/);
+  assert.match(out, /b\.js:9:x = 1 \/\/ TODO/);
+  assert.doesNotMatch(out, /grep: done/);
+  assert.match(out, /2 match\(es\)/);
+});
+
+test('count mode: per-file + total counts, NO line text', () => {
+  const out = formatGrepResult(grepResult([
+    { file: 'a.js', line: 3, text: 'TODO one' },
+    { file: 'a.js', line: 7, text: 'TODO two' },
+    { file: 'b.js', line: 1, text: 'TODO three' },
+  ], { output_mode: 'count' }));
+  assert.match(out, /3 match\(es\) in 2 file\(s\)/);
+  assert.match(out, /a\.js: 2/);
+  assert.match(out, /b\.js: 1/);
+  // count mode must not leak the line content
+  assert.doesNotMatch(out, /TODO one/);
+});
+
+test('files_with_matches mode: unique paths only, no line content', () => {
+  const out = formatGrepResult(grepResult([
+    { file: 'a.js', line: 3, text: 'TODO one' },
+    { file: 'a.js', line: 7, text: 'TODO two' },
+    { file: 'b.js', line: 1, text: 'TODO three' },
+  ], { output_mode: 'files_with_matches' }));
+  assert.match(out, /2 file\(s\) with matches/);
+  assert.match(out, /^a\.js$/m);
+  assert.match(out, /^b\.js$/m);
+  // no per-line text and no file:line:text references (header echoes the pattern,
+  // so we check for line-content shape, not the literal pattern string)
+  assert.doesNotMatch(out, /:\d+:/);
+  assert.doesNotMatch(out, /TODO (one|two|three)/);
+});
+
+test('head_limit BOUNDS context (content): over-limit shows only N + truncation notice', () => {
+  const matches = [];
+  for (let i = 1; i <= 50; i++) matches.push({ file: 'f.js', line: i, text: `TODO ${i}` });
+  const out = formatGrepResult(grepResult(matches, { head_limit: 10 }));
+  // exactly 10 file:line:text lines serialized
+  const shownLines = out.split('\n').filter((l) => /^f\.js:\d+:/.test(l));
+  assert.strictEqual(shownLines.length, 10, 'serialized lines bounded to head_limit');
+  assert.match(out, /40 more match\(es\) not shown/);
+  assert.match(out, /head_limit/);
+  // the full count is still reported honestly
+  assert.match(out, /50 match\(es\)/);
+});
+
+test('head_limit PAIRED POSITIVE: under-limit shows all with NO truncation notice', () => {
+  const matches = [];
+  for (let i = 1; i <= 5; i++) matches.push({ file: 'f.js', line: i, text: `TODO ${i}` });
+  const out = formatGrepResult(grepResult(matches, { head_limit: 10 }));
+  const shownLines = out.split('\n').filter((l) => /^f\.js:\d+:/.test(l));
+  assert.strictEqual(shownLines.length, 5, 'all matches shown');
+  assert.doesNotMatch(out, /more match\(es\) not shown/);
+  assert.doesNotMatch(out, /not shown/);
+});
+
+test('grep no-match → clear no-matches line, not "done"', () => {
+  const out = formatGrepResult(grepResult([]));
+  assert.match(out, /no matches/);
+  assert.doesNotMatch(out, /grep: done/);
+});
+
+test('glob: serializes the file list — NOT "glob: done"', () => {
+  const out = formatGlobResult({ files: [{ path: 'a.ts' }, { path: 'src/b.ts' }], pattern: '*.ts', count: 2, head_limit: 100 });
+  assert.match(out, /^a\.ts$/m);
+  assert.match(out, /^src\/b\.ts$/m);
+  assert.doesNotMatch(out, /glob: done/);
+  assert.match(out, /2 file\(s\)/);
+});
+
+test('glob head_limit bounds + paired under-limit no notice', () => {
+  const many = [];
+  for (let i = 0; i < 40; i++) many.push({ path: `f${i}.ts` });
+  const bounded = formatGlobResult({ files: many, pattern: '*.ts', count: 40, head_limit: 10 });
+  const shown = bounded.split('\n').filter((l) => /^f\d+\.ts$/.test(l));
+  assert.strictEqual(shown.length, 10);
+  assert.match(bounded, /30 more file\(s\) not shown/);
+
+  const few = [{ path: 'a.ts' }, { path: 'b.ts' }];
+  const full = formatGlobResult({ files: few, pattern: '*.ts', count: 2, head_limit: 10 });
+  assert.doesNotMatch(full, /not shown/);
+});
+
+test('spec + prompt accurately describe the modes and what is returned', () => {
+  const { TOOL_SPECS } = require('../lib/tool_specs');
+  const { TOOL_TAG_SPECS: TAG_DOCS } = require('../lib/prompts');
+  // tool_specs grep: documents all three modes + head_limit, and the modes are
+  // model-selectable (enum present).
+  const grepDesc = TOOL_SPECS.grep.description;
+  for (const m of ['content', 'files_with_matches', 'count']) assert.ok(grepDesc.includes(m), `grep desc mentions ${m}`);
+  assert.ok(grepDesc.includes('head_limit'), 'grep desc mentions head_limit');
+  assert.deepStrictEqual(TOOL_SPECS.grep.parameters.properties.output_mode.enum, ['content', 'files_with_matches', 'count']);
+  assert.ok(TOOL_SPECS.grep.parameters.properties.head_limit, 'grep spec exposes head_limit');
+  assert.ok(TOOL_SPECS.glob.parameters.properties.head_limit, 'glob spec exposes head_limit');
+  // prompts.js no longer lies: grep purpose advertises the real serialized shape.
+  if (TAG_DOCS && TAG_DOCS.grep) {
+    assert.ok(/file:line:text/.test(TAG_DOCS.grep.purpose), 'prompt grep purpose names the real return shape');
+    assert.ok(/output_mode/.test(TAG_DOCS.grep.purpose));
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Part B — end-to-end through the REAL agent loop (the regression):
+// a <grep>/<glob> tag must feed the actual matches back to the model.
+// ---------------------------------------------------------------------------
+
+let prevKey;
+let prevCwd;
+let tmpDir;
+
+before(() => {
+  prevKey = process.env.SEMALT_API_KEY;
+  process.env.SEMALT_API_KEY = 'test-key';
+  prevCwd = process.cwd();
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-w5-'));
+  fs.writeFileSync(path.join(tmpDir, 'alpha.js'), 'line one\nconst NEEDLE = 1; // here\nplain\n');
+  fs.writeFileSync(path.join(tmpDir, 'beta.js'), 'no match here\nanother NEEDLE token\n');
+  fs.writeFileSync(path.join(tmpDir, 'gamma.ts'), 'irrelevant\n');
+  process.chdir(tmpDir);
+});
+
+after(() => {
+  process.chdir(prevCwd);
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY;
+  else process.env.SEMALT_API_KEY = prevKey;
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+});
+
+function buildRunner(base) {
+  const config = {
+    api_base: base, api_key: 'test-key', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+    sandbox: { mode: 'off' },
+  };
+  const getConfig = () => config;
+  const saveConfig = (c) => Object.assign(config, c);
+  const api = createApiClient({ getConfig, saveConfig, ui });
+  const pm = createPermissionManager(ui, { skipPermissions: true });
+  pm.setUICallbacks({ onAddMessage: () => {}, onShowModal: () => {}, onCloseModal: () => {}, onCaptureNavigation: () => () => {} });
+  const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(pm, ui, getConfig);
+  const runner = createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig,
+  });
+  return runner;
+}
+
+async function runOneToolTurn(toolTag) {
+  const mock = await startMockLLM();
+  mock.replyWith(toolTag);
+  mock.replyWith('Done.');
+  try {
+    const runner = buildRunner(mock.base);
+    const tools = [];
+    const cb = {
+      onToken: () => {}, onToolStart: () => {},
+      onToolEnd: (tag, result) => tools.push({ tag, result }),
+      onError: () => {}, onRetry: () => {}, onAssistantMessage: () => {},
+    };
+    const messages = [{ role: 'user', content: 'go' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, { callbacks: cb });
+    const fedBack = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    return { tools, fedBack };
+  } finally {
+    await mock.close?.();
+  }
+}
+
+test('REGRESSION: real loop — grep feeds actual matches (file:line:text) to the model, not "grep: done"', async () => {
+  const { tools, fedBack } = await runOneToolTurn('<grep pattern="NEEDLE"/>');
+  assert.strictEqual(tools.length, 1);
+  const result = tools[0].result;
+  assert.doesNotMatch(result, /grep: done/, 'the W.5 bug (undelivered result) must be closed');
+  assert.match(result, /alpha\.js:2:.*NEEDLE/);
+  assert.match(result, /beta\.js:2:.*NEEDLE/);
+  // and it actually reached the messages array the model sees next turn
+  assert.ok(fedBack && /NEEDLE/.test(fedBack.content), 'matches present in the fed-back tool message');
+});
+
+test('REGRESSION: real loop — glob feeds the file list to the model, not "glob: done"', async () => {
+  const { tools } = await runOneToolTurn('<glob pattern="*.js"/>');
+  const result = tools[0].result;
+  assert.doesNotMatch(result, /glob: done/);
+  assert.match(result, /alpha\.js/);
+  assert.match(result, /beta\.js/);
+  assert.doesNotMatch(result, /gamma\.ts/); // *.js glob excludes the .ts file
+});
+
+test('real loop — grep output_mode="count" yields counts, no line text', async () => {
+  const { tools } = await runOneToolTurn('<grep pattern="NEEDLE" output_mode="count"/>');
+  const result = tools[0].result;
+  assert.match(result, /2 match\(es\) in 2 file\(s\)/);
+  assert.match(result, /alpha\.js: 1/);
+  assert.doesNotMatch(result, /const NEEDLE/); // no source line text in count mode
+});
+
+test('real loop — head_limit threads end-to-end and bounds the model-facing result', async () => {
+  const { tools } = await runOneToolTurn('<grep pattern="NEEDLE" head_limit="1"/>');
+  const result = tools[0].result;
+  const shown = result.split('\n').filter((l) => /\.js:\d+:/.test(l));
+  assert.strictEqual(shown.length, 1, 'bounded to head_limit=1');
+  assert.match(result, /1 more match\(es\) not shown/);
+});

package/test/grep-glob.test.js

@@ -0,0 +1,268 @@
+'use strict';
+
+// Characterization tests for the first-class `grep` and `glob` tools (Task 2.1).
+// Written tests-first. All fs work is isolated under a temp $HOME (so the audit
+// log resolves there) and a temp working directory (so isPathSafe permits the
+// search root and grep/glob confine to it).
+//
+// The central guarantee proven here: grep produces BYTE-IDENTICAL output whether
+// it runs through ripgrep (`rg`) or the pure-Node fallback. The two engines are
+// exercised explicitly via the exported `_grepSearch({ engine })` seam and their
+// results are deep-compared. The rg branch is skipped (visibly, not silently)
+// when ripgrep is not on PATH.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Redirect home-based paths (audit log) into a temp dir BEFORE any lib module is
+// required — those paths are computed at module load.
+const TMP_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-home-'));
+const PREV_HOME = process.env.HOME;
+const PREV_USERPROFILE = process.env.USERPROFILE;
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+
+const ui = require('../lib/ui');
+const { createPermissionManager } = require('../lib/permissions');
+const { createToolExecutor } = require('../lib/tools');
+const {
+  fromInvoke,
+  registryToolNames,
+  _grepSearch,
+  _globSearch,
+  _detectRipgrep,
+} = require('../lib/tool_registry');
+const { extractToolCalls } = require('../lib/tools');
+
+const HAVE_RG = !!_detectRipgrep();
+
+let exec;
+let CWD;
+let PREV_CWD;
+
+// ---------------------------------------------------------------------------
+// Fixture tree (mirrors the rg empirical probe used to pin canonical semantics)
+// ---------------------------------------------------------------------------
+
+function writeFixture(root) {
+  const w = (rel, data) => {
+    const p = path.join(root, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, data);
+  };
+  w('a.txt', 'hello TODO world\nsecond line\nTODO again\n');
+  w('b.txt', 'nothing here\n');
+  w('sub/c.txt', 'deep TODO\n');
+  w('f.md', 'TODO md\n');
+  w('bin.dat', Buffer.from('TODO\x00binary\n', 'binary')); // NUL → binary, must be skipped
+  w('node_modules/d.txt', 'TODO in node_modules\n');       // large dir → skipped
+  w('.gitignore', 'ignored.txt\n*.log\nskip/\n');
+  w('ignored.txt', 'TODO ignored\n');                      // gitignore name → skipped
+  w('x.log', 'TODO log\n');                                // gitignore *.log → skipped
+  w('skip/e.txt', 'TODO skipdir\n');                       // gitignore skip/ → skipped
+}
+
+before(() => {
+  PREV_CWD = process.cwd();
+  CWD = fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-cwd-'));
+  fs.realpathSync(CWD); // touch
+  CWD = fs.realpathSync(CWD);
+  process.chdir(CWD);
+  writeFixture(CWD);
+  const pm = createPermissionManager(ui, {});
+  exec = createToolExecutor(pm, ui, () => ({ max_file_size_kb: 512, command_timeout_ms: 30000 }));
+});
+
+after(() => {
+  process.chdir(PREV_CWD);
+  if (PREV_HOME === undefined) delete process.env.HOME; else process.env.HOME = PREV_HOME;
+  if (PREV_USERPROFILE === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = PREV_USERPROFILE;
+});
+
+const EXPECTED_TODO = [
+  { file: 'a.txt', line: 1, text: 'hello TODO world' },
+  { file: 'a.txt', line: 3, text: 'TODO again' },
+  { file: 'f.md', line: 1, text: 'TODO md' },
+  { file: 'sub/c.txt', line: 1, text: 'deep TODO' },
+];
+
+// ---------------------------------------------------------------------------
+// grep — Node engine (always runs, the reference behavior)
+// ---------------------------------------------------------------------------
+
+test('grep (node): regex match across the tree returns file/line/text', () => {
+  const r = _grepSearch({ pattern: 'TODO', baseDir: CWD, engine: 'node' });
+  assert.deepStrictEqual(r.matches, EXPECTED_TODO);
+  assert.strictEqual(r.pattern, 'TODO');
+  assert.strictEqual(r.count, 4);
+});
+
+test('grep (node): gitignored, binary, hidden, and node_modules files are skipped', () => {
+  const r = _grepSearch({ pattern: 'TODO', baseDir: CWD, engine: 'node' });
+  const files = r.matches.map((m) => m.file);
+  for (const skipped of ['ignored.txt', 'x.log', 'skip/e.txt', 'bin.dat', 'node_modules/d.txt']) {
+    assert.ok(!files.includes(skipped), `${skipped} must be skipped`);
+  }
+});
+
+test('grep (node): zero matches returns an empty list, not an error', () => {
+  const r = _grepSearch({ pattern: 'ZZZ_NO_SUCH_TOKEN', baseDir: CWD, engine: 'node' });
+  assert.deepStrictEqual(r.matches, []);
+  assert.strictEqual(r.count, 0);
+  assert.strictEqual(r.error, undefined);
+});
+
+test('grep (node): case-insensitive flag widens the match', () => {
+  const sensitive = _grepSearch({ pattern: 'todo', baseDir: CWD, engine: 'node' });
+  assert.deepStrictEqual(sensitive.matches, []);
+  const insensitive = _grepSearch({ pattern: 'todo', baseDir: CWD, engine: 'node', ignoreCase: true });
+  assert.deepStrictEqual(insensitive.matches, EXPECTED_TODO);
+});
+
+test('grep (node): regex metacharacters work', () => {
+  const r = _grepSearch({ pattern: 'TODO\\s\\w+', baseDir: CWD, engine: 'node' });
+  assert.deepStrictEqual(r.matches, [
+    { file: 'a.txt', line: 1, text: 'hello TODO world' },
+    { file: 'a.txt', line: 3, text: 'TODO again' },
+    { file: 'f.md', line: 1, text: 'TODO md' },
+  ]);
+});
+
+test('grep (node): path glob filter restricts which files are searched', () => {
+  const r = _grepSearch({ pattern: 'TODO', baseDir: CWD, engine: 'node', pathGlob: '*.md' });
+  assert.deepStrictEqual(r.matches, [{ file: 'f.md', line: 1, text: 'TODO md' }]);
+});
+
+test('grep (node): an invalid regex is reported as an error (not a throw)', () => {
+  const r = _grepSearch({ pattern: '(', baseDir: CWD, engine: 'node' });
+  assert.ok(r.error && /regex|pattern/i.test(r.error));
+});
+
+// ---------------------------------------------------------------------------
+// grep — rg vs Node parity (the headline guarantee). Skipped without ripgrep.
+// ---------------------------------------------------------------------------
+
+const rgOpts = HAVE_RG ? {} : { skip: 'ripgrep (rg) not on PATH' };
+
+for (const c of [
+  { label: 'plain literal', params: { pattern: 'TODO' } },
+  { label: 'regex metachars', params: { pattern: 'TODO\\s\\w+' } },
+  { label: 'case-insensitive', params: { pattern: 'todo', ignoreCase: true } },
+  { label: 'path glob filter', params: { pattern: 'TODO', pathGlob: '*.md' } },
+  { label: 'zero matches', params: { pattern: 'ZZZ_NO_SUCH_TOKEN' } },
+]) {
+  test(`grep parity (rg === node): ${c.label}`, rgOpts, () => {
+    const viaRg = _grepSearch({ ...c.params, baseDir: CWD, engine: 'rg' });
+    const viaNode = _grepSearch({ ...c.params, baseDir: CWD, engine: 'node' });
+    assert.strictEqual(viaRg.error, undefined, 'rg path produced no error');
+    assert.deepStrictEqual(viaRg, viaNode, 'rg and node outputs are byte-identical');
+  });
+}
+
+test('grep auto-engine resolves to rg when present and matches node', rgOpts, () => {
+  const auto = _grepSearch({ pattern: 'TODO', baseDir: CWD, engine: 'auto' });
+  const node = _grepSearch({ pattern: 'TODO', baseDir: CWD, engine: 'node' });
+  assert.deepStrictEqual(auto, node);
+});
+
+// ---------------------------------------------------------------------------
+// glob
+// ---------------------------------------------------------------------------
+
+test('glob: basename pattern matches at any depth with metadata', () => {
+  const r = _globSearch({ pattern: '*.txt', baseDir: CWD });
+  const paths = r.files.map((f) => f.path).sort();
+  assert.deepStrictEqual(paths, ['a.txt', 'b.txt', 'ignored.txt', 'skip/e.txt', 'sub/c.txt']);
+  const a = r.files.find((f) => f.path === 'a.txt');
+  assert.strictEqual(a.size, fs.statSync(path.join(CWD, 'a.txt')).size);
+  assert.ok(!Number.isNaN(Date.parse(a.mtime)));
+});
+
+test('glob: node_modules and .git are skipped', () => {
+  const r = _globSearch({ pattern: '*.txt', baseDir: CWD });
+  assert.ok(!r.files.some((f) => f.path.includes('node_modules')));
+});
+
+test('glob: a slashed pattern is anchored to the base', () => {
+  const r = _globSearch({ pattern: 'sub/*.txt', baseDir: CWD });
+  assert.deepStrictEqual(r.files.map((f) => f.path), ['sub/c.txt']);
+});
+
+test('glob: zero matches returns an empty list', () => {
+  const r = _globSearch({ pattern: '*.nonexistent', baseDir: CWD });
+  assert.deepStrictEqual(r.files, []);
+  assert.strictEqual(r.count, 0);
+});
+
+// ---------------------------------------------------------------------------
+// Registry wiring: both tools register and dispatch via XML and native paths
+// ---------------------------------------------------------------------------
+
+test('grep and glob register as callable tools', () => {
+  const names = registryToolNames();
+  assert.ok(names.includes('grep'));
+  assert.ok(names.includes('glob'));
+});
+
+test('constants parity guard still passes with grep/glob added', () => {
+  assert.doesNotThrow(() => require('../lib/constants'));
+});
+
+test('grep dispatches identically via XML and native', () => {
+  // Tuple now carries output_mode/head_limit/offset (Task W.5); absent → null in both rails.
+  assert.deepStrictEqual(
+    extractToolCalls('<grep pattern="TODO" path="*.js" ignore_case="true"/>'),
+    [['grep', 'TODO', '*.js', true, null, null, null]],
+  );
+  assert.deepStrictEqual(
+    fromInvoke('grep', { pattern: 'TODO', path: '*.js', ignore_case: true }),
+    ['grep', 'TODO', '*.js', true, null, null, null],
+  );
+  // inline-content form: body is the pattern
+  assert.deepStrictEqual(extractToolCalls('<grep>TODO</grep>'), [['grep', 'TODO', null, false, null, null, null]]);
+  // W.5 params parse through both rails identically.
+  assert.deepStrictEqual(
+    extractToolCalls('<grep pattern="TODO" output_mode="count" head_limit="5" offset="2"/>'),
+    [['grep', 'TODO', null, false, 'count', '5', '2']],
+  );
+  assert.deepStrictEqual(
+    fromInvoke('grep', { pattern: 'TODO', output_mode: 'count', head_limit: 5, offset: 2 }),
+    ['grep', 'TODO', null, false, 'count', 5, 2],
+  );
+});
+
+test('glob dispatches identically via XML and native', () => {
+  assert.deepStrictEqual(extractToolCalls('<glob pattern="*.ts"/>'), [['glob', '*.ts', '.', null, null]]);
+  assert.deepStrictEqual(extractToolCalls('<glob pattern="*.ts" path="src"/>'), [['glob', '*.ts', 'src', null, null]]);
+  assert.deepStrictEqual(fromInvoke('glob', { pattern: '*.ts' }), ['glob', '*.ts', '.', null, null]);
+  assert.deepStrictEqual(extractToolCalls('<glob pattern="*.ts" head_limit="3"/>'), [['glob', '*.ts', '.', '3', null]]);
+});
+
+test('grep/glob are read-only (no permission gate)', async () => {
+  assert.strictEqual(await exec.describePermission(['grep', 'TODO', null, false]), null);
+  assert.strictEqual(await exec.describePermission(['glob', '*.ts', '.']), null);
+});
+
+// ---------------------------------------------------------------------------
+// Integration through the executor (auto engine)
+// ---------------------------------------------------------------------------
+
+test('agentExecFile grep returns matches', async () => {
+  const r = await exec.agentExecFile('grep', 'TODO');
+  assert.deepStrictEqual(r.matches, EXPECTED_TODO);
+});
+
+test('agentExecFile glob returns files', async () => {
+  const r = await exec.agentExecFile('glob', '*.md');
+  assert.deepStrictEqual(r.files.map((f) => f.path), ['f.md']);
+});
+
+test('grep confines a path-escaping glob to the working tree (no escape)', () => {
+  const r = _grepSearch({ pattern: 'TODO', baseDir: CWD, engine: 'node', pathGlob: '../**' });
+  // nothing outside the base is reachable; the worst case is an empty result
+  for (const m of r.matches) assert.ok(!m.file.startsWith('..'));
+});