onbuzz 4.8.3 → 4.9.0

package/src/tools/__tests__/taskManagerTool.discipline.test.js

@@ -0,0 +1,137 @@
+/**
+ * Tests for the TASK DISCIPLINE signal — `currentFocus` returned on
+ * every taskmanager response — and the OPERATING POSTURE guideline
+ * that pairs with it.
+ *
+ * Production observation (scripts/memory-bench/live-v2-*,
+ * agent-agent-v2-v2-s2-multi-topic-1779570320941): Kimi-K2.6 and gpt-5.4
+ * lost task focus after cascading tool errors and silently reverted
+ * to a prior task instead of completing the current one. The fix is
+ * two-pronged:
+ *   1. Surface `currentFocus` on every taskmanager response so the
+ *      anchor stays visible across error cascades.
+ *   2. OPERATING POSTURE explicitly tells the agent: only one task
+ *      in_progress at a time, transition before working, finish or
+ *      release before switching.
+ */
+import { describe, test, expect } from '@jest/globals';
+import TaskManagerTool from '../taskManagerTool.js';
+import { BaseTool, ToolsRegistry } from '../baseTool.js';
+
+const SILENT_LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+function makeTool() {
+  const tool = new TaskManagerTool({ description: 'test' });
+  tool.logger = SILENT_LOGGER;
+  return tool;
+}
+
+describe('_buildCurrentFocus — task-discipline signal', () => {
+  test('ok=true when exactly one task is in_progress', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'Polish README', description: 'Rewrite intro', status: 'in_progress' },
+      { id: 'task-2', title: 'Other thing',   description: '...',           status: 'pending' },
+    ]);
+    expect(focus.ok).toBe(true);
+    expect(focus.inProgressCount).toBe(1);
+    expect(focus.current).toMatchObject({
+      taskId: 'task-1', title: 'Polish README', description: 'Rewrite intro',
+    });
+    expect(focus.warning).toBeUndefined();
+  });
+
+  test('ok=false with warning when 0 tasks are in_progress', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'X', description: '...', status: 'pending' },
+      { id: 'task-2', title: 'Y', description: '...', status: 'completed' },
+    ]);
+    expect(focus.ok).toBe(false);
+    expect(focus.inProgressCount).toBe(0);
+    expect(focus.current).toBeNull();
+    expect(focus.warning).toMatch(/in_progress/);
+    expect(focus.warning).toMatch(/BEFORE/);
+  });
+
+  test('ok=false with warning when 2+ tasks are in_progress', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'A', description: '...', status: 'in_progress' },
+      { id: 'task-2', title: 'B', description: '...', status: 'in_progress' },
+      { id: 'task-3', title: 'C', description: '...', status: 'pending' },
+    ]);
+    expect(focus.ok).toBe(false);
+    expect(focus.inProgressCount).toBe(2);
+    expect(Array.isArray(focus.current)).toBe(true);
+    expect(focus.current).toHaveLength(2);
+    expect(focus.warning).toMatch(/Multiple tasks/);
+  });
+
+  test('empty task list reports 0 in_progress with warning', () => {
+    const focus = makeTool()._buildCurrentFocus([]);
+    expect(focus.ok).toBe(false);
+    expect(focus.inProgressCount).toBe(0);
+    expect(focus.current).toBeNull();
+  });
+
+  test('null/undefined input handled gracefully (no crash)', () => {
+    expect(() => makeTool()._buildCurrentFocus(null)).not.toThrow();
+    expect(() => makeTool()._buildCurrentFocus(undefined)).not.toThrow();
+    const f = makeTool()._buildCurrentFocus(null);
+    expect(f.inProgressCount).toBe(0);
+  });
+
+  test('long descriptions are truncated to 140 chars', () => {
+    const long = 'x'.repeat(500);
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'T', description: long, status: 'in_progress' },
+    ]);
+    expect(focus.current.description.length).toBeLessThanOrEqual(141);
+    expect(focus.current.description.endsWith('…')).toBe(true);
+  });
+
+  test('non-string description is coerced to empty (no crash)', () => {
+    const focus = makeTool()._buildCurrentFocus([
+      { id: 'task-1', title: 'T', description: null, status: 'in_progress' },
+    ]);
+    expect(focus.current.description).toBe('');
+  });
+});
+
+describe('OPERATING POSTURE — TASK DISCIPLINE section', () => {
+  // The OPERATING POSTURE block lives in baseTool.js and is built per
+  // agent based on its capabilities. We construct a BaseTool-derived
+  // tool registry stub and verify the block content directly.
+  function buildOperatingPosture(capabilities) {
+    // Use the real ToolsRegistry — it's the class that owns
+    // generateToolDescriptionsForPrompt. Register fake tools matching
+    // the capability list so the block emits its sections.
+    const reg = new ToolsRegistry(SILENT_LOGGER);
+    for (const id of capabilities) {
+      reg.tools.set(id, { id, getDescription: () => `# ${id}` });
+    }
+    return reg.generateToolDescriptionsForPrompt(capabilities);
+  }
+
+  test('section appears when taskmanager capability is present', () => {
+    const block = buildOperatingPosture(['memory', 'taskmanager']);
+    expect(block).toMatch(/TASK DISCIPLINE/);
+    expect(block).toMatch(/ONE.*task.*in_progress/);
+    expect(block).toMatch(/Transition first, then work/);
+    expect(block).toMatch(/Finish or release/);
+    expect(block).toMatch(/Anchor on tool failures/);
+    expect(block).toMatch(/currentFocus/);
+  });
+
+  test('section does NOT appear without taskmanager capability', () => {
+    const block = buildOperatingPosture(['memory']);
+    expect(block).not.toMatch(/TASK DISCIPLINE/);
+  });
+
+  test('section guidance is descriptive of cognitive effort, not bureaucratic checklist', () => {
+    // The aim is "task list reflects actual work", not "fill in fields".
+    const block = buildOperatingPosture(['memory', 'taskmanager']);
+    expect(block).toMatch(/cognitive effort/);
+    // Should describe what to do on tool failures — that's the main
+    // failure mode we observed.
+    expect(block).toMatch(/tool.*fail/i);
+  });
+});

package/src/tools/__tests__/taskManagerTool.transition.test.js

@@ -0,0 +1,236 @@
+/**
+ * Tests for updateTask's status-transition handler.
+ *
+ * Covers the in_progress entry handler that:
+ *   - Auto-loads `[memory:mem-...]` referenced memory into result.attachedMemory
+ *   - Emits result.memoryNudge when no memory is attached
+ *   - Surfaces a not-found error when the referenced memory was deleted
+ *   - Does nothing on non-transitioning updates (already in_progress)
+ *   - Does nothing for transitions to other statuses (e.g. blocked)
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+const mockLoadMemories = jest.fn();
+const mockInitialize = jest.fn().mockResolvedValue(undefined);
+const mockAddMemory = jest.fn();
+jest.unstable_mockModule('../../services/memoryService.js', () => ({
+  getMemoryService: jest.fn(() => ({
+    initialize: mockInitialize,
+    addMemory: mockAddMemory,
+    loadMemories: mockLoadMemories,
+  })),
+}));
+
+let uuidCounter = 0;
+jest.unstable_mockModule('uuid', () => ({
+  v4: jest.fn(() => `mock-uuid-${++uuidCounter}`),
+}));
+
+const { default: TaskManagerTool } = await import('../taskManagerTool.js');
+
+function makeTool() {
+  const tool = new TaskManagerTool({ description: 'test' });
+  tool.logger = createMockLogger();
+  return tool;
+}
+
+function makeContext({ taskList } = {}) {
+  const agent = {
+    id: 'agent-1',
+    name: 'Trans Test',
+    capabilities: ['memory', 'tools'],
+    taskList: taskList || { tasks: [], lastUpdated: new Date().toISOString() },
+  };
+  return {
+    agent,
+    context: {
+      agentId: 'agent-1',
+      agentName: 'Trans Test',
+      agent,
+      agentPool: {
+        getAgent: jest.fn().mockResolvedValue(agent),
+        persistAgentState: jest.fn().mockResolvedValue(undefined),
+      },
+      projectDir: '/tmp/test',
+    },
+  };
+}
+
+function makeTask(overrides = {}) {
+  return {
+    id: 'task-1',
+    title: 'Demo task',
+    description: 'No reference here',
+    status: 'pending',
+    priority: 'medium',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  uuidCounter = 0;
+  mockLoadMemories.mockReset();
+  mockInitialize.mockReset();
+  mockInitialize.mockResolvedValue(undefined);
+  mockAddMemory.mockReset();
+});
+
+describe('TaskManagerTool — updateTask in_progress transition handler', () => {
+  test('auto-loads attached memory when task description has [memory:mem-...] marker', async () => {
+    mockLoadMemories.mockResolvedValueOnce([
+      { id: 'mem-abc', title: 'Task plan', content: 'step 1: ...' },
+    ]);
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: '[memory:mem-abc] short summary' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeDefined();
+    expect(res.result.attachedMemory.id).toBe('mem-abc');
+    expect(res.result.attachedMemory.content).toBe('step 1: ...');
+    expect(res.result.attachedMemory._hint).toMatch(/memory append/);
+    expect(res.result.memoryNudge).toBeUndefined();
+  });
+
+  test('LOXIA_MEMORY_NUDGE_VARIANT=descriptive falls back to the older wording (for A/B validation)', async () => {
+    const prev = process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+    process.env.LOXIA_MEMORY_NUDGE_VARIANT = 'descriptive';
+    try {
+      const tool = makeTool();
+      const { agent, context } = makeContext();
+      agent.taskList.tasks = [makeTask({ description: 'Plain task with no marker' })];
+
+      const res = await tool.execute(
+        { action: 'update', taskId: 'task-1', status: 'in_progress' },
+        context
+      );
+
+      expect(res.success).toBe(true);
+      // Descriptive wording, NOT the imperative "VERY NEXT" phrasing.
+      expect(res.result.memoryNudge).toMatch(/Scan the.*AGENT MEMORY/);
+      expect(res.result.memoryNudge).not.toMatch(/VERY NEXT/);
+    } finally {
+      if (prev === undefined) delete process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+      else process.env.LOXIA_MEMORY_NUDGE_VARIANT = prev;
+    }
+  });
+
+  test('LOXIA_MEMORY_NUDGE_VARIANT unset OR =directive emits the directive wording', async () => {
+    const prev = process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+    delete process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+    try {
+      const tool = makeTool();
+      const { agent, context } = makeContext();
+      agent.taskList.tasks = [makeTask({ description: 'Plain task with no marker' })];
+
+      const res = await tool.execute(
+        { action: 'update', taskId: 'task-1', status: 'in_progress' },
+        context
+      );
+
+      expect(res.result.memoryNudge).toMatch(/VERY NEXT tool call/);
+      expect(res.result.memoryNudge).toMatch(/memory list/);
+    } finally {
+      if (prev === undefined) delete process.env.LOXIA_MEMORY_NUDGE_VARIANT;
+      else process.env.LOXIA_MEMORY_NUDGE_VARIANT = prev;
+    }
+  });
+
+  test('emits memoryNudge when transitioning to in_progress without any [memory:] marker', async () => {
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: 'Plain task with no marker' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    // Directive wording (post-optimization, 2026-05-19): the
+    // descriptive earlier nudge ("Scan the catalog...") scored 22% in
+    // the live multi-turn memory bench. Switching to "Your VERY NEXT
+    // tool call MUST be `memory list`" doubled it to 44%. See
+    // scripts/memory-bench/.
+    expect(res.result.memoryNudge).toMatch(/memory list/);
+    expect(res.result.memoryNudge).toMatch(/VERY NEXT tool call/);
+    expect(res.result.memoryNudge).toMatch(/memory add/);
+    expect(mockLoadMemories).not.toHaveBeenCalled();
+  });
+
+  test('surfaces error when [memory:] marker points at a deleted memory', async () => {
+    mockLoadMemories.mockResolvedValueOnce([]); // memory not found
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: '[memory:mem-ghost] gone' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeDefined();
+    expect(res.result.attachedMemory.id).toBe('mem-ghost');
+    expect(res.result.attachedMemory.error).toMatch(/not found/i);
+    expect(res.result.attachedMemory.content).toBeUndefined();
+  });
+
+  test('does NOT trigger handler when task was already in_progress (no transition)', async () => {
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ status: 'in_progress', description: '[memory:mem-xyz] x' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    expect(res.result.memoryNudge).toBeUndefined();
+    expect(mockLoadMemories).not.toHaveBeenCalled();
+  });
+
+  test('does NOT trigger handler for transitions to non-in_progress statuses', async () => {
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ status: 'pending', description: '[memory:mem-xyz] x' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'blocked' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    expect(res.result.memoryNudge).toBeUndefined();
+    expect(mockLoadMemories).not.toHaveBeenCalled();
+  });
+
+  test('handler errors are swallowed (does not break update)', async () => {
+    mockLoadMemories.mockRejectedValueOnce(new Error('disk on fire'));
+    const tool = makeTool();
+    const { agent, context } = makeContext();
+    agent.taskList.tasks = [makeTask({ description: '[memory:mem-abc] x' })];
+
+    const res = await tool.execute(
+      { action: 'update', taskId: 'task-1', status: 'in_progress' },
+      context
+    );
+
+    expect(res.success).toBe(true);
+    expect(res.result.attachedMemory).toBeUndefined();
+    expect(res.result.memoryNudge).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,260 @@
+/**
+ * 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);
+  });
+});

package/src/tools/baseTool.js

@@ -868,6 +868,21 @@ class ToolsRegistry {
         description += '**`plan/*` memories auto-inject into your system prompt every turn under `## AGENT WORKING PLAN` — that\'s how they survive compaction. Update or delete them as the situation evolves; a stale plan is worse than no plan.**\n\n';
       }
 
+      // ── TASK DISCIPLINE ─────────────────────────────────────────
+      // Address the production-observed pattern where agents (especially
+      // Kimi-K2.6) lose task focus after cascading tool errors and
+      // silently revert to a prior task instead of completing the current
+      // one. The fix: make the task list a faithful representation of
+      // cognitive effort. Gated on `taskmanager` capability only.
+      if (toolIds.includes('taskmanager')) {
+        description += '**TASK DISCIPLINE — keep your task list aligned with your actual cognitive effort:**\n';
+        description += '- Only **ONE** task may be `in_progress` at a time. Two or more in-progress tasks means the list no longer reflects what you are actually doing.\n';
+        description += '- **Transition first, then work.** Before you do work on a task, call `taskmanager` → `update` to move it `pending → in_progress`. The transition IS the signal you have started — do not start mentally then transition later.\n';
+        description += '- **Finish or release.** When done, move `in_progress → completed` BEFORE starting the next task. If the user pivots and you must drop the current task, transition it to `blocked` or `cancelled` (with a one-line note in `description` saying why) — never silently abandon it.\n';
+        description += '- **Anchor on tool failures.** If a tool call fails or you get stuck, re-read your task list. Resume the `in_progress` task. Do NOT switch topics until the current task is explicitly transitioned. This is how multi-task sessions stay coherent across error recovery.\n';
+        description += '- The `currentFocus` field returned by every `taskmanager` action tells you which task you are on. If it warns about 0 or 2+ in-progress tasks, fix that before doing anything else.\n\n';
+      }
+
       description += '**Distinction:**\n';
       description += '- `memory` = persistent knowledge that survives sessions (why, constraints, durable facts, working plans).\n';
       if (toolIds.includes('taskmanager')) {
@@ -887,7 +902,19 @@ class ToolsRegistry {
       description += '2. **Understand code** — Use `code-map` skeleton to extract signatures, classes, and functions with line numbers\n';
       description += '3. **Zoom in** — Use `code-map` read-range to read only the specific lines you need\n';
       description += '4. **Search** — Use `seek` to find specific terms, then `code-map` read-range to view context around matches\n\n';
-      description += 'This avoids wasting context on entire file reads. Reserve `filesystem` read for small files or when you need the complete content.\n';
+      description += 'This avoids wasting context on entire file reads. Reserve `filesystem` read for small files or when you need the complete content.\n\n';
+
+      // Code-map cache discipline — addresses production-observed
+      // re-skeleton pattern (Monopoly mission: 22 skeleton calls on
+      // the same file, 80% while the original result was still in
+      // active context). The runtime maintains a per-session cache
+      // surfaced via the `## CODEBASE KNOWLEDGE` block injected by
+      // the scheduler. Agent must consult that block before re-issuing
+      // identical reads. See services/codebaseKnowledgeService.js.
+      description += '**Cache awareness — before re-issuing a code-map call:**\n';
+      description += '- Scan the `## CODEBASE KNOWLEDGE` section of this prompt (appears below the task list when populated). It lists files you have ALREADY mapped this session and what was mapped (skeleton, line ranges).\n';
+      description += '- If the file is listed and marked `current` (not STALE), the tool will serve from cache automatically on an identical re-read. You do not need to issue the call again unless you need DIFFERENT information (a different range) or the entry is marked STALE.\n';
+      description += '- The cache invalidates automatically when you write to a file (via filesystem write/append or file-content-replace). After a write, the file\'s entry will appear STALE — re-skeleton is correct in that case.\n';
     }
 
     return description;