onbuzz 4.9.13 → 4.10.0

package/src/tools/__tests__/toolShapeForgiveness.test.js

@@ -1,260 +1,259 @@
-/**
- * Tests for the forgiving param-shape normalizers added across
- * filesystem / terminal / seek / file-content-replace / code-map.
- *
- * Production observation (Kimi-K2.6 + gpt-5.4 multi-turn live trace,
- * scripts/memory-bench/live-v2-directive-*.json): production agents
- * routinely call these tools with natural-feeling singular shapes
- * (`{action, path}`, `{command}`, `{query, filePattern}`) that the
- * canonical implementations rejected. Cascading rejections caused
- * "actions is not iterable", "Cannot read 'length' of undefined",
- * and eventual task-discipline collapse.
- *
- * These tests pin the forgiving behavior — any future change that
- * tightens the canonical shape MUST update both the implementation
- * AND these tests in the same commit.
- */
-import { describe, test, expect } from '@jest/globals';
-import FileSystemTool from '../fileSystemTool.js';
-import SeekTool from '../seekTool.js';
-import TerminalTool from '../terminalTool.js';
-import FileContentReplaceTool from '../fileContentReplaceTool.js';
-
-const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
-
-describe('filesystem — accepts singular {action, path} shape', () => {
-  test('promotes {action: "read", path: "X"} to {actions: [{type, filePath}]}', async () => {
-    const tool = new FileSystemTool({}, SILENT_LOGGER);
-    // Throw early from the read path to capture the action shape after
-    // normalization without actually doing disk I/O.
-    const orig = tool.customValidateParameters?.bind(tool);
-    let captured = null;
-    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
-    try {
-      await tool.execute({ action: 'read', path: 'src/foo.js' }, { projectDir: process.cwd() });
-    } catch { /* downstream errors fine */ }
-    expect(captured).not.toBeNull();
-    expect(Array.isArray(captured.actions)).toBe(true);
-    expect(captured.actions[0].type).toBe('read');
-    expect(captured.actions[0].filePath).toBe('src/foo.js');
-  });
-
-  test('still rejects when neither {action} nor {actions} is provided', async () => {
-    const tool = new FileSystemTool({}, SILENT_LOGGER);
-    await expect(tool.execute({}, { projectDir: process.cwd() }))
-      .rejects.toThrow(/actions is required/);
-  });
-
-  test('canonical {actions: [...]} still works (normalization is a no-op)', async () => {
-    const tool = new FileSystemTool({}, SILENT_LOGGER);
-    let captured = null;
-    const orig = tool.customValidateParameters?.bind(tool);
-    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
-    try {
-      await tool.execute(
-        { actions: [{ type: 'read', filePath: 'src/foo.js' }] },
-        { projectDir: process.cwd() }
-      );
-    } catch { /* downstream errors fine */ }
-    expect(captured).not.toBeNull();
-    expect(captured.actions[0].type).toBe('read');
-    expect(captured.actions[0].filePath).toBe('src/foo.js');
-  });
-});
-
-describe('terminal — accepts singular {command} shape', () => {
-  test('promotes {command: "ls"} to {actions: [{type: "run-command", command}]}', async () => {
-    const tool = new TerminalTool({ allowedCommands: ['echo'] }, SILENT_LOGGER);
-    let recordedAction = null;
-    tool._runCommandAction = async (a) => { recordedAction = a; return { success: true, output: 'ok' }; };
-    // Intercept the execute loop by mocking the action dispatcher path
-    // — terminal's execute iterates params.actions; with our normalization
-    // the array exists and we can verify the inner shape via tool internals.
-    // Easier: just call execute and verify it doesn't throw "is not iterable".
-    let threw = null;
-    try {
-      await tool.execute({ command: 'echo hi' }, { projectDir: process.cwd(), agentId: 'a' });
-    } catch (e) { threw = e; }
-    // The promotion happened iff we no longer get the "actions is not
-    // iterable" / "actions is required" error. The actual command may
-    // still fail downstream (sandbox, allowlist, etc.) and that's fine.
-    if (threw) {
-      expect(threw.message).not.toMatch(/actions is not iterable/);
-      expect(threw.message).not.toMatch(/At least one action is required/);
-    }
-  });
-});
-
-describe('seek — accepts {query, filePattern} singular shape', () => {
-  test('returns clear error when both are missing (no null-deref)', async () => {
-    const tool = new SeekTool({}, SILENT_LOGGER);
-    const r = await tool.execute({}, { projectDir: process.cwd() });
-    expect(r.success).toBe(false);
-    expect(r.error).toMatch(/filePaths/);
-  });
-
-  test('accepts {query: "X", filePattern: "*.js"} singular shape (no crash)', async () => {
-    const tool = new SeekTool({}, SILENT_LOGGER);
-    // Mock resolveFilePaths to return the canonical {found, notFound} shape.
-    tool.resolveFilePaths = async () => ({ found: [], notFound: ['*.js'] });
-    const r = await tool.execute(
-      { query: 'tok-', filePattern: '*.js' },
-      { projectDir: process.cwd() }
-    );
-    // No "Cannot read 'length' of undefined" — we either get a clean
-    // success (no matches in empty file list) or a clean error string.
-    expect(typeof r).toBe('object');
-    expect(r).not.toBeNull();
-  });
-
-  test('returns clean error when only filePaths is missing', async () => {
-    const tool = new SeekTool({}, SILENT_LOGGER);
-    const r = await tool.execute({ searchTerms: ['foo'] }, { projectDir: process.cwd() });
-    expect(r.success).toBe(false);
-    expect(r.error).toMatch(/filePaths/);
-  });
-
-  test('returns clean error when only searchTerms is missing', async () => {
-    const tool = new SeekTool({}, SILENT_LOGGER);
-    const r = await tool.execute({ filePaths: ['*.js'] }, { projectDir: process.cwd() });
-    expect(r.success).toBe(false);
-    expect(r.error).toMatch(/searchTerms/);
-  });
-});
-
-describe('file-content-replace — accepts flat {actions: [{type, filePath, search, replace}]} shape', () => {
-  test('promotes flat actions shape to canonical {files: [{path, replacements}]}', async () => {
-    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
-    // Capture the post-normalization params shape via _isNormalizedParams.
-    let captured = null;
-    const orig = tool._isNormalizedParams.bind(tool);
-    tool._isNormalizedParams = (p) => { captured = p; return orig(p); };
-    try {
-      await tool.execute(
-        { actions: [{ type: 'replace', filePath: 'a.js', search: 'foo', replace: 'bar' }] },
-        { projectDir: process.cwd() }
-      );
-    } catch { /* downstream errors fine */ }
-    expect(captured).not.toBeNull();
-    expect(Array.isArray(captured.files)).toBe(true);
-    expect(captured.files[0].path).toBe('a.js');
-    expect(captured.files[0].replacements[0].oldContent).toBe('foo');
-    expect(captured.files[0].replacements[0].newContent).toBe('bar');
-  });
-
-  test('returns clean error when neither {files} nor {actions} provided', async () => {
-    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
-    const r = await tool.execute({}, { projectDir: process.cwd() });
-    expect(r.success).toBe(false);
-    expect(r.error).toMatch(/files/);
-  });
-
-  test('groups multiple actions by filePath', async () => {
-    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
-    // Spy on _isNormalizedParams to capture the normalized params shape.
-    let capturedParams = null;
-    const orig = tool._isNormalizedParams.bind(tool);
-    tool._isNormalizedParams = (p) => { capturedParams = p; return orig(p); };
-    try {
-      await tool.execute({
-        actions: [
-          { type: 'replace', filePath: 'a.js', search: '1', replace: 'A' },
-          { type: 'replace', filePath: 'a.js', search: '2', replace: 'B' },
-          { type: 'replace', filePath: 'b.js', search: '3', replace: 'C' },
-        ],
-      }, { projectDir: process.cwd() });
-    } catch { /* downstream errors fine */ }
-    expect(capturedParams).not.toBeNull();
-    expect(Array.isArray(capturedParams.files)).toBe(true);
-    expect(capturedParams.files.length).toBe(2);
-    const a = capturedParams.files.find(f => f.path === 'a.js');
-    expect(a.replacements.length).toBe(2);
-    expect(a.replacements[0].oldContent).toBe('1');
-    expect(a.replacements[0].newContent).toBe('A');
-  });
-});
-
-describe('item discriminator cross-acceptance (type / action)', () => {
-  // Some tools use `type` as item discriminator inside actions[]
-  // (filesystem, terminal, taskmanager, code-map, memory), others use
-  // `action` (jobdone, docx, excel, pdf). To prevent cross-tool drift,
-  // every plural-envelope tool accepts BOTH names.
-  test('filesystem accepts {actions: [{action: "read", filePath}]} (action-named item)', async () => {
-    const tool = new FileSystemTool({}, SILENT_LOGGER);
-    let captured = null;
-    const orig = tool.customValidateParameters?.bind(tool);
-    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
-    try {
-      await tool.execute(
-        { actions: [{ action: 'read', filePath: 'src/foo.js' }] },
-        { projectDir: process.cwd() }
-      );
-    } catch { /* downstream errors fine */ }
-    expect(captured).not.toBeNull();
-    // After normalization, the item should have `type` set.
-    expect(captured.actions[0].type).toBe('read');
-  });
-
-  test('terminal accepts {actions: [{action: "run-command", command}]} (action-named item)', async () => {
-    const tool = new TerminalTool({ allowedCommands: ['echo'] }, SILENT_LOGGER);
-    // Validate path: customValidateParameters mutates the input items
-    // in place, setting .type from .action. Verify by inspecting the
-    // input object after validation runs.
-    const input = { actions: [{ action: 'run-command', command: 'echo hi' }] };
-    const v = tool.customValidateParameters(input);
-    expect(v.valid).toBe(true);
-    expect(input.actions[0].type).toBe('run-command');
-  });
-
-  test('filesystem validateParameters accepts {action} item discriminator and normalizes to type', () => {
-    const tool = new FileSystemTool({}, SILENT_LOGGER);
-    const input = { actions: [{ action: 'read', filePath: 'src/foo.js' }] };
-    const v = tool.customValidateParameters(input);
-    expect(v.valid).toBe(true);
-    expect(input.actions[0].type).toBe('read');
-  });
-
-  test('taskmanager accepts {actions: [{action: "list"}]} item discriminator', () => {
-    // taskmanager has its own non-customValidateParameters path —
-    // verify by going through execute and seeing that params.action
-    // gets set from firstAction.action.
-    // (Tests against taskmanager's full execute lifecycle live in
-    // src/tools/__tests__/taskManagerTool.test.js.)
-    expect(true).toBe(true);
-  });
-});
-
-describe('code-map — explanatory errors on invalid action', () => {
-  test('action="search" → hint points at seek', async () => {
-    const { default: CodeMapTool } = await import('../codeMapTool.js');
-    const tool = new CodeMapTool({}, SILENT_LOGGER);
-    const v = tool.customValidateParameters({ action: 'search', filePath: 'x' });
-    expect(v.valid).toBe(false);
-    expect(v.errors.join(' ').toLowerCase()).toContain('seek');
-  });
-
-  test('action="list" → hint points at file-tree', async () => {
-    const { default: CodeMapTool } = await import('../codeMapTool.js');
-    const tool = new CodeMapTool({}, SILENT_LOGGER);
-    const v = tool.customValidateParameters({ action: 'list' });
-    expect(v.valid).toBe(false);
-    expect(v.errors.join(' ').toLowerCase()).toContain('file-tree');
-  });
-
-  test('action="read" (without -range) → hint points at filesystem read or code-map read-range', async () => {
-    const { default: CodeMapTool } = await import('../codeMapTool.js');
-    const tool = new CodeMapTool({}, SILENT_LOGGER);
-    const v = tool.customValidateParameters({ action: 'read' });
-    expect(v.valid).toBe(false);
-    expect(v.errors.join(' ').toLowerCase()).toMatch(/filesystem|read-range/);
-  });
-
-  test('valid actions still pass', async () => {
-    const { default: CodeMapTool } = await import('../codeMapTool.js');
-    const tool = new CodeMapTool({}, SILENT_LOGGER);
-    expect(tool.customValidateParameters({ action: 'skeleton', path: 'src/' }).valid).toBe(true);
-    expect(tool.customValidateParameters({
-      action: 'read-range', filePath: 'src/foo.js', startLine: 1, endLine: 50,
-    }).valid).toBe(true);
-  });
-});
+/**
+ * Tests for the forgiving param-shape normalizers added across
+ * filesystem / terminal / seek / file-content-replace / code-map.
+ *
+ * Production observation (Kimi-K2.6 + gpt-5.4 multi-turn live trace,
+ * scripts/memory-bench/live-v2-directive-*.json): production agents
+ * routinely call these tools with natural-feeling singular shapes
+ * (`{action, path}`, `{command}`, `{query, filePattern}`) that the
+ * canonical implementations rejected. Cascading rejections caused
+ * "actions is not iterable", "Cannot read 'length' of undefined",
+ * and eventual task-discipline collapse.
+ *
+ * These tests pin the forgiving behavior — any future change that
+ * tightens the canonical shape MUST update both the implementation
+ * AND these tests in the same commit.
+ */
+import { describe, test, expect } from '@jest/globals';
+import FileSystemTool from '../fileSystemTool.js';
+import SeekTool from '../seekTool.js';
+import TerminalTool from '../terminalTool.js';
+import FileContentReplaceTool from '../fileContentReplaceTool.js';
+
+const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+describe('filesystem — accepts singular {action, path} shape', () => {
+  test('promotes {action: "read", path: "X"} to {actions: [{type, filePath}]}', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    // Throw early from the read path to capture the action shape after
+    // normalization without actually doing disk I/O.
+    const orig = tool.customValidateParameters?.bind(tool);
+    let captured = null;
+    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
+    try {
+      await tool.execute({ action: 'read', path: 'src/foo.js' }, { projectDir: process.cwd() });
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    expect(Array.isArray(captured.actions)).toBe(true);
+    expect(captured.actions[0].type).toBe('read');
+    expect(captured.actions[0].filePath).toBe('src/foo.js');
+  });
+
+  test('still rejects when neither {action} nor {actions} is provided', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    await expect(tool.execute({}, { projectDir: process.cwd() }))
+      .rejects.toThrow(/actions is required/);
+  });
+
+  test('canonical {actions: [...]} still works (normalization is a no-op)', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    let captured = null;
+    const orig = tool.customValidateParameters?.bind(tool);
+    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
+    try {
+      await tool.execute(
+        { actions: [{ type: 'read', filePath: 'src/foo.js' }] },
+        { projectDir: process.cwd() }
+      );
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    expect(captured.actions[0].type).toBe('read');
+    expect(captured.actions[0].filePath).toBe('src/foo.js');
+  });
+});
+
+describe('terminal — accepts singular {command} shape', () => {
+  test('promotes {command: "ls"} to {actions: [{type: "run-command", command}]}', async () => {
+    const tool = new TerminalTool({ allowedCommands: ['echo'] }, SILENT_LOGGER);
+    tool._runCommandAction = async () => ({ success: true, output: 'ok' });
+    // Intercept the execute loop by mocking the action dispatcher path
+    // — terminal's execute iterates params.actions; with our normalization
+    // the array exists and we can verify the inner shape via tool internals.
+    // Easier: just call execute and verify it doesn't throw "is not iterable".
+    let threw = null;
+    try {
+      await tool.execute({ command: 'echo hi' }, { projectDir: process.cwd(), agentId: 'a' });
+    } catch (e) { threw = e; }
+    // The promotion happened iff we no longer get the "actions is not
+    // iterable" / "actions is required" error. The actual command may
+    // still fail downstream (sandbox, allowlist, etc.) and that's fine.
+    if (threw) {
+      expect(threw.message).not.toMatch(/actions is not iterable/);
+      expect(threw.message).not.toMatch(/At least one action is required/);
+    }
+  });
+});
+
+describe('seek — accepts {query, filePattern} singular shape', () => {
+  test('returns clear error when both are missing (no null-deref)', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    const r = await tool.execute({}, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/filePaths/);
+  });
+
+  test('accepts {query: "X", filePattern: "*.js"} singular shape (no crash)', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    // Mock resolveFilePaths to return the canonical {found, notFound} shape.
+    tool.resolveFilePaths = async () => ({ found: [], notFound: ['*.js'] });
+    const r = await tool.execute(
+      { query: 'tok-', filePattern: '*.js' },
+      { projectDir: process.cwd() }
+    );
+    // No "Cannot read 'length' of undefined" — we either get a clean
+    // success (no matches in empty file list) or a clean error string.
+    expect(typeof r).toBe('object');
+    expect(r).not.toBeNull();
+  });
+
+  test('returns clean error when only filePaths is missing', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    const r = await tool.execute({ searchTerms: ['foo'] }, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/filePaths/);
+  });
+
+  test('returns clean error when only searchTerms is missing', async () => {
+    const tool = new SeekTool({}, SILENT_LOGGER);
+    const r = await tool.execute({ filePaths: ['*.js'] }, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/searchTerms/);
+  });
+});
+
+describe('file-content-replace — accepts flat {actions: [{type, filePath, search, replace}]} shape', () => {
+  test('promotes flat actions shape to canonical {files: [{path, replacements}]}', async () => {
+    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
+    // Capture the post-normalization params shape via _isNormalizedParams.
+    let captured = null;
+    const orig = tool._isNormalizedParams.bind(tool);
+    tool._isNormalizedParams = (p) => { captured = p; return orig(p); };
+    try {
+      await tool.execute(
+        { actions: [{ type: 'replace', filePath: 'a.js', search: 'foo', replace: 'bar' }] },
+        { projectDir: process.cwd() }
+      );
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    expect(Array.isArray(captured.files)).toBe(true);
+    expect(captured.files[0].path).toBe('a.js');
+    expect(captured.files[0].replacements[0].oldContent).toBe('foo');
+    expect(captured.files[0].replacements[0].newContent).toBe('bar');
+  });
+
+  test('returns clean error when neither {files} nor {actions} provided', async () => {
+    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
+    const r = await tool.execute({}, { projectDir: process.cwd() });
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/files/);
+  });
+
+  test('groups multiple actions by filePath', async () => {
+    const tool = new FileContentReplaceTool({}, SILENT_LOGGER);
+    // Spy on _isNormalizedParams to capture the normalized params shape.
+    let capturedParams = null;
+    const orig = tool._isNormalizedParams.bind(tool);
+    tool._isNormalizedParams = (p) => { capturedParams = p; return orig(p); };
+    try {
+      await tool.execute({
+        actions: [
+          { type: 'replace', filePath: 'a.js', search: '1', replace: 'A' },
+          { type: 'replace', filePath: 'a.js', search: '2', replace: 'B' },
+          { type: 'replace', filePath: 'b.js', search: '3', replace: 'C' },
+        ],
+      }, { projectDir: process.cwd() });
+    } catch { /* downstream errors fine */ }
+    expect(capturedParams).not.toBeNull();
+    expect(Array.isArray(capturedParams.files)).toBe(true);
+    expect(capturedParams.files.length).toBe(2);
+    const a = capturedParams.files.find(f => f.path === 'a.js');
+    expect(a.replacements.length).toBe(2);
+    expect(a.replacements[0].oldContent).toBe('1');
+    expect(a.replacements[0].newContent).toBe('A');
+  });
+});
+
+describe('item discriminator cross-acceptance (type / action)', () => {
+  // Some tools use `type` as item discriminator inside actions[]
+  // (filesystem, terminal, taskmanager, code-map, memory), others use
+  // `action` (jobdone, docx, excel, pdf). To prevent cross-tool drift,
+  // every plural-envelope tool accepts BOTH names.
+  test('filesystem accepts {actions: [{action: "read", filePath}]} (action-named item)', async () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    let captured = null;
+    const orig = tool.customValidateParameters?.bind(tool);
+    tool.customValidateParameters = (p) => { captured = p; return orig ? orig(p) : { valid: true }; };
+    try {
+      await tool.execute(
+        { actions: [{ action: 'read', filePath: 'src/foo.js' }] },
+        { projectDir: process.cwd() }
+      );
+    } catch { /* downstream errors fine */ }
+    expect(captured).not.toBeNull();
+    // After normalization, the item should have `type` set.
+    expect(captured.actions[0].type).toBe('read');
+  });
+
+  test('terminal accepts {actions: [{action: "run-command", command}]} (action-named item)', async () => {
+    const tool = new TerminalTool({ allowedCommands: ['echo'] }, SILENT_LOGGER);
+    // Validate path: customValidateParameters mutates the input items
+    // in place, setting .type from .action. Verify by inspecting the
+    // input object after validation runs.
+    const input = { actions: [{ action: 'run-command', command: 'echo hi' }] };
+    const v = tool.customValidateParameters(input);
+    expect(v.valid).toBe(true);
+    expect(input.actions[0].type).toBe('run-command');
+  });
+
+  test('filesystem validateParameters accepts {action} item discriminator and normalizes to type', () => {
+    const tool = new FileSystemTool({}, SILENT_LOGGER);
+    const input = { actions: [{ action: 'read', filePath: 'src/foo.js' }] };
+    const v = tool.customValidateParameters(input);
+    expect(v.valid).toBe(true);
+    expect(input.actions[0].type).toBe('read');
+  });
+
+  test('taskmanager accepts {actions: [{action: "list"}]} item discriminator', () => {
+    // taskmanager has its own non-customValidateParameters path —
+    // verify by going through execute and seeing that params.action
+    // gets set from firstAction.action.
+    // (Tests against taskmanager's full execute lifecycle live in
+    // src/tools/__tests__/taskManagerTool.test.js.)
+    expect(true).toBe(true);
+  });
+});
+
+describe('code-map — explanatory errors on invalid action', () => {
+  test('action="search" → hint points at seek', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'search', filePath: 'x' });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toContain('seek');
+  });
+
+  test('action="list" → hint points at file-tree', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'list' });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toContain('file-tree');
+  });
+
+  test('action="read" (without -range) → hint points at filesystem read or code-map read-range', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    const v = tool.customValidateParameters({ action: 'read' });
+    expect(v.valid).toBe(false);
+    expect(v.errors.join(' ').toLowerCase()).toMatch(/filesystem|read-range/);
+  });
+
+  test('valid actions still pass', async () => {
+    const { default: CodeMapTool } = await import('../codeMapTool.js');
+    const tool = new CodeMapTool({}, SILENT_LOGGER);
+    expect(tool.customValidateParameters({ action: 'skeleton', path: 'src/' }).valid).toBe(true);
+    expect(tool.customValidateParameters({
+      action: 'read-range', filePath: 'src/foo.js', startLine: 1, endLine: 50,
+    }).valid).toBe(true);
+  });
+});