@semalt-ai/code 1.8.5 → 1.19.0

package/test/memory.test.js

@@ -0,0 +1,198 @@
+'use strict';
+
+// Characterization tests for project memory (Task 2.3): the AGENTS.md/CLAUDE.md
+// hierarchy loader and its injection into the system prompt. Filesystem work is
+// isolated under temp dirs; HOME is redirected before requiring lib modules so
+// the global-memory level resolves under the temp home.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TMP_HOME = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-memhome-')));
+const PREV_HOME = process.env.HOME;
+const PREV_USERPROFILE = process.env.USERPROFILE;
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const { test, after } = require('node:test');
+const assert = require('node:assert');
+
+const {
+  loadProjectMemory,
+  discoverMemoryFiles,
+  findRepoRoot,
+  memoryStatusLines,
+} = require('../lib/memory');
+const { getSystemPrompt } = require('../lib/prompts');
+
+const PREV_CWD = process.cwd();
+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;
+});
+
+function mkRepo(prefix) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+  return root;
+}
+function write(p, data) { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, data); }
+
+// ---------------------------------------------------------------------------
+// Absent files → no memory, base prompt unchanged
+// ---------------------------------------------------------------------------
+
+test('no memory files present → empty block and no files', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-emptyhome-')));
+  const root = mkRepo('semalt-mem-none-');
+  const r = loadProjectMemory({ cwd: root, home: emptyHome });
+  assert.strictEqual(r.block, '');
+  assert.deepStrictEqual(r.files, []);
+  assert.strictEqual(r.truncated, false);
+});
+
+test('getSystemPrompt is byte-for-byte the base prompt when memory is empty', () => {
+  const base = getSystemPrompt(false, '');
+  assert.ok(!base.includes('PROJECT_MEMORY'), 'no memory section in the base prompt');
+  // Memory is appended verbatim to the end — proves append-only + empty == base.
+  assert.strictEqual(getSystemPrompt(false, '\n\nMEMBLOCK'), base + '\n\nMEMBLOCK');
+  // Same for the native template.
+  const nbase = getSystemPrompt(true, '');
+  assert.strictEqual(getSystemPrompt(true, '\n\nX'), nbase + '\n\nX');
+});
+
+test('getSystemPrompt with no project memory in CWD/home equals the explicit-empty base', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-eh2-')));
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-nomem-cwd-')));
+  const prevHome = process.env.HOME;
+  process.env.HOME = emptyHome; process.env.USERPROFILE = emptyHome;
+  process.chdir(dir);
+  try {
+    assert.strictEqual(getSystemPrompt(false), getSystemPrompt(false, ''));
+  } finally {
+    process.env.HOME = prevHome; process.env.USERPROFILE = prevHome;
+    process.chdir(PREV_CWD);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Hierarchy: global → project root → nested CWD, in order
+// ---------------------------------------------------------------------------
+
+test('hierarchy loads global, repo root, and nested CWD in order', () => {
+  write(path.join(TMP_HOME, '.semalt-ai', 'AGENTS.md'), 'GLOBAL_MEM');
+  const root = mkRepo('semalt-mem-hier-');
+  write(path.join(root, 'AGENTS.md'), 'ROOT_MEM');
+  const nested = path.join(root, 'pkg', 'sub');
+  write(path.join(nested, 'AGENTS.md'), 'CWD_MEM');
+
+  const r = loadProjectMemory({ cwd: nested, home: TMP_HOME });
+  assert.deepStrictEqual(r.files.map((f) => f.source), ['global', 'project-root', 'cwd']);
+  const gi = r.block.indexOf('GLOBAL_MEM');
+  const ri = r.block.indexOf('ROOT_MEM');
+  const ci = r.block.indexOf('CWD_MEM');
+  assert.ok(gi !== -1 && ri !== -1 && ci !== -1, 'all three present');
+  assert.ok(gi < ri && ri < ci, 'concatenated in hierarchy order');
+  assert.ok(r.block.includes('<<<PROJECT_MEMORY>>>') && r.block.includes('<<<END_PROJECT_MEMORY>>>'));
+
+  // cleanup global so it does not leak into other tests
+  fs.rmSync(path.join(TMP_HOME, '.semalt-ai'), { recursive: true, force: true });
+});
+
+test('CWD at the repo root is not double-loaded', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-eh3-')));
+  const root = mkRepo('semalt-mem-rootcwd-');
+  write(path.join(root, 'AGENTS.md'), 'ONLY_ROOT');
+  const r = loadProjectMemory({ cwd: root, home: emptyHome });
+  assert.deepStrictEqual(r.files.map((f) => f.source), ['project-root']);
+});
+
+// ---------------------------------------------------------------------------
+// AGENTS.md vs CLAUDE.md alias
+// ---------------------------------------------------------------------------
+
+test('AGENTS.md is preferred over CLAUDE.md and the choice is reported', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-eh4-')));
+  const root = mkRepo('semalt-mem-alias-');
+  write(path.join(root, 'AGENTS.md'), 'A_WINS');
+  write(path.join(root, 'CLAUDE.md'), 'C_IGNORED');
+  const r = loadProjectMemory({ cwd: root, home: emptyHome });
+  assert.strictEqual(r.files.length, 1);
+  assert.strictEqual(r.files[0].name, 'AGENTS.md');
+  assert.strictEqual(r.files[0].alsoPresent, true);
+  assert.ok(r.block.includes('A_WINS'));
+  assert.ok(!r.block.includes('C_IGNORED'), 'CLAUDE.md content is not loaded when AGENTS.md exists');
+});
+
+test('CLAUDE.md is used as the alias when AGENTS.md is absent', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-eh5-')));
+  const root = mkRepo('semalt-mem-claude-');
+  write(path.join(root, 'CLAUDE.md'), 'CLAUDE_ONLY');
+  const r = loadProjectMemory({ cwd: root, home: emptyHome });
+  assert.strictEqual(r.files[0].name, 'CLAUDE.md');
+  assert.strictEqual(r.files[0].alsoPresent, false);
+  assert.ok(r.block.includes('CLAUDE_ONLY'));
+});
+
+// ---------------------------------------------------------------------------
+// Truncation
+// ---------------------------------------------------------------------------
+
+test('oversized memory is truncated with a visible notice', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-eh6-')));
+  const root = mkRepo('semalt-mem-big-');
+  write(path.join(root, 'AGENTS.md'), 'X'.repeat(5000));
+  const r = loadProjectMemory({ cwd: root, home: emptyHome, maxBytes: 200 });
+  assert.strictEqual(r.truncated, true);
+  assert.ok(/truncated/i.test(r.block), 'block carries a truncation notice');
+});
+
+// ---------------------------------------------------------------------------
+// findRepoRoot + status lines
+// ---------------------------------------------------------------------------
+
+test('findRepoRoot locates the nearest .git ancestor and returns null without one', () => {
+  const root = mkRepo('semalt-mem-root-');
+  const nested = path.join(root, 'a', 'b');
+  fs.mkdirSync(nested, { recursive: true });
+  assert.strictEqual(findRepoRoot(nested), root);
+  const bare = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-bare-')));
+  // a temp dir under the OS tmpdir is not inside a git repo
+  assert.strictEqual(findRepoRoot(bare), null);
+});
+
+test('memoryStatusLines reports loaded files, alias note, and edit target', () => {
+  const result = {
+    files: [
+      { path: '/home/u/.semalt-ai/AGENTS.md', source: 'global', name: 'AGENTS.md', alsoPresent: false },
+      { path: '/repo/AGENTS.md', source: 'project-root', name: 'AGENTS.md', alsoPresent: true },
+    ],
+    truncated: false,
+  };
+  const lines = memoryStatusLines(result).join('\n');
+  assert.ok(lines.includes('/home/u/.semalt-ai/AGENTS.md'));
+  assert.ok(lines.includes('[global]') && lines.includes('[project-root]'));
+  assert.ok(/CLAUDE\.md also present/.test(lines), 'alias note shown');
+  assert.ok(lines.includes('Edit project memory: /repo/AGENTS.md'), 'points at the nearest project file');
+});
+
+test('memoryStatusLines handles the no-memory case', () => {
+  const lines = memoryStatusLines({ files: [], truncated: false }).join('\n');
+  assert.ok(/No project memory files found/.test(lines));
+});
+
+// ---------------------------------------------------------------------------
+// discoverMemoryFiles direct
+// ---------------------------------------------------------------------------
+
+test('discoverMemoryFiles returns ordered entries with resolved paths', () => {
+  const emptyHome = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-eh7-')));
+  const root = mkRepo('semalt-disc-');
+  write(path.join(root, 'CLAUDE.md'), 'x');
+  const found = discoverMemoryFiles(root, emptyHome);
+  assert.strictEqual(found.length, 1);
+  assert.strictEqual(found[0].source, 'project-root');
+  assert.strictEqual(path.isAbsolute(found[0].path), true);
+});

package/test/native-dispatch.test.js

@@ -0,0 +1,356 @@
+'use strict';
+
+// Native-path dispatch tests (Pre-Task 4.0c). Closes the coverage-shape blind
+// spot the re-audit found: end-to-end dispatch through the REAL runAgentLoop was
+// proven for read-only tools on BOTH rails (Task 3.3b), but EFFECTFUL tools were
+// only ever exercised through the XML path. The native function-calling path has
+// distinct glue — mapInvokeToCall → descriptor gate → role:'tool' result rooting
+// (lib/agent.js ~1378) — and Phase 4's per-pattern permissions + checkpoints both
+// hook the MUTATING dispatch path. Layering that onto unverified native glue would
+// repeat the 3.3b mistake, so these tests lock the native path end-to-end for:
+//   * file-mutating tools (write, edit, delete, move),
+//   * shell/exec,
+//   * plan-mode withhold + approve,
+// each asserting the mutation actually happens, the permission gate fires (with
+// the right descriptor), and the result is rooted as a role:'tool' message on the
+// originating tool_call_id. Where useful each native case is paired with its XML
+// equivalent IN THE SAME TEST so the two rails are proven equivalent at the loop
+// level for effectful tools (extending the 3.3b read-only equivalence proof).
+//
+// Driven via mock.replyWithToolCall(name, args) — a native tool_calls response
+// with EMPTY text content — against a temp $cwd so isPathSafe (CWD-confined)
+// permits the writes. skipPermissions auto-approves so the loop runs unattended;
+// pm.askPermission is wrapped to RECORD each gate consultation so we can assert
+// the descriptor fired for mutating tools and did NOT for read-only ones.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ui = require('../lib/ui');
+const { createApiClient } = require('../lib/api');
+const { createToolExecutor, extractToolCalls } = require('../lib/tools');
+const { createPermissionManager } = require('../lib/permissions');
+const { createAgentRunner } = require('../lib/agent');
+const { startMockLLM } = require('./harness/mock-llm');
+
+let prevKey;
+let CWD;
+let PREV_CWD;
+before(() => {
+  prevKey = process.env.SEMALT_API_KEY; process.env.SEMALT_API_KEY = 'test-key';
+  PREV_CWD = process.cwd();
+  CWD = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-native-')));
+  process.chdir(CWD);
+});
+after(() => {
+  process.chdir(PREV_CWD);
+  try { fs.rmSync(CWD, { recursive: true, force: true }); } catch {}
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY; else process.env.SEMALT_API_KEY = prevKey;
+});
+
+// A real runner whose chatStream points at `base`. skipPermissions auto-approves
+// so the loop runs unattended; `asks` records every permission-gate consultation
+// (actionType + tag) so a test can prove the descriptor fired (mutating) or did
+// not (read-only). Returns `getSaved` for the rare persistence assertion.
+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: [],
+    // Dispatch test, not a sandbox test — run real `echo` unsandboxed regardless
+    // of the runner's bwrap/sandbox-exec availability (Task 4.4).
+    sandbox: { mode: 'off' },
+  };
+  let saved = null;
+  const getConfig = () => config;
+  const saveConfig = (c) => { saved = { ...c }; Object.assign(config, c); };
+
+  const api = createApiClient({ getConfig, saveConfig, ui });
+  const pm = createPermissionManager(ui, { skipPermissions: true });
+  pm.setUICallbacks({ onAddMessage: () => {}, onShowModal: () => {}, onCloseModal: () => {}, onCaptureNavigation: () => () => {} });
+
+  const asks = [];
+  const realAsk = pm.askPermission;
+  pm.askPermission = async (actionType, description, tag) => {
+    asks.push({ actionType, tag });
+    return realAsk(actionType, description, tag);
+  };
+
+  const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(pm, ui, getConfig);
+  const runner = createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig,
+  });
+  return { runner, asks, getSaved: () => saved };
+}
+
+function collector(extra = {}) {
+  const ev = { tokens: [], tools: [], errors: [], retries: [], assistants: [], withheld: [] };
+  const cb = {
+    onToken: (t) => ev.tokens.push(t),
+    onToolStart: () => {},
+    onToolEnd: (tag, result) => ev.tools.push({ tag, result }),
+    onError: (e) => ev.errors.push(e),
+    onRetry: (next, max) => ev.retries.push({ next, max }),
+    onAssistantMessage: (m) => ev.assistants.push(m),
+    onPlanWithhold: (tag, arg, desc) => ev.withheld.push({ tag, arg, desc }),
+    ...extra,
+  };
+  return { ev, cb };
+}
+
+// The assistant turn that carried structured tool_calls (native shape), plus its
+// rooted role:'tool' result. Shared assertion: a native tool turn records an
+// assistant message with EMPTY text + tool_calls, and the result comes back on a
+// role:'tool' message keyed to the originating tool_call id (lib/agent.js ~1378).
+function assertNativeRooting(messages, fnName) {
+  const assistantWithCall = messages.find((m) => m.role === 'assistant' && Array.isArray(m.tool_calls));
+  assert.ok(assistantWithCall, 'assistant message recorded the native tool_calls');
+  assert.strictEqual(assistantWithCall.content, '', 'native tool-call turn has empty text content');
+  assert.strictEqual(assistantWithCall.tool_calls[0].function.name, fnName, `tool_calls names ${fnName}`);
+  const toolMsg = messages.find((m) => m.role === 'tool');
+  assert.ok(toolMsg, 'native path appends a role:"tool" result message');
+  assert.strictEqual(toolMsg.tool_call_id, assistantWithCall.tool_calls[0].id, 'result rooted to its tool_call id');
+  assert.ok(!messages.some((m) => m.role === 'user' && /Tool execution results/.test(m.content)),
+    'native path does NOT use the XML "Tool execution results" user message');
+  return toolMsg;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Native file-mutating: write — mutation + gate + role:'tool' rooting,
+//    paired with the XML equivalent for loop-level equivalence.
+// ---------------------------------------------------------------------------
+
+test('native write_file: mutates, gate fires (file/write_file), result rooted as role:"tool"', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('write_file', { path: 'native-write.txt', content: 'NATIVE_WRITE_CONTENT' });
+  mock.replyWith('Wrote it.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'write the file' }];
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    // The mutation actually happened.
+    assert.strictEqual(fs.readFileSync(path.join(CWD, 'native-write.txt'), 'utf8'), 'NATIVE_WRITE_CONTENT');
+    // The permission gate fired with the mutating descriptor (NOT auto-skipped
+    // as a read-only tool).
+    assert.deepStrictEqual(asks, [{ actionType: 'file', tag: 'write_file' }], 'write gate consulted once');
+    // The tool dispatched and the result is rooted on the tool_call id.
+    assert.strictEqual(ev.tools.length, 1);
+    assert.strictEqual(ev.tools[0].tag, 'write');
+    const toolMsg = assertNativeRooting(messages, 'write_file');
+    assert.match(toolMsg.content, /Wrote \d+ bytes to native-write\.txt/);
+
+    assert.strictEqual(metrics.turns.length, 2, 'tool turn + final turn');
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Wrote it.'));
+    assert.strictEqual(mock.pending(), 0);
+  } finally {
+    await mock.close();
+  }
+});
+
+test('XML write_file equivalent: same tool, same mutation, XML "Tool execution results" shape', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<write_file path="xml-write.txt">XML_WRITE_CONTENT</write_file>');
+  mock.replyWith('Wrote it.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'write the file' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.strictEqual(fs.readFileSync(path.join(CWD, 'xml-write.txt'), 'utf8'), 'XML_WRITE_CONTENT');
+    assert.deepStrictEqual(asks, [{ actionType: 'file', tag: 'write_file' }], 'same gate fires on the XML rail');
+    assert.strictEqual(ev.tools[0].tag, 'write');
+    // XML results come back as a role:'user' message, never role:'tool'.
+    const toolResult = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    assert.ok(toolResult && /Wrote \d+ bytes to xml-write\.txt/.test(toolResult.content));
+    assert.ok(!messages.some((m) => m.role === 'tool'), 'XML path does not use role:"tool" messages');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 2. Native file-mutating: edit_file (line replacement) — multi-arg native call.
+// ---------------------------------------------------------------------------
+
+test('native edit_file: replaces the target line, gate fires, result rooted', async () => {
+  fs.writeFileSync(path.join(CWD, 'native-edit.txt'), 'line1\nline2\nline3\n');
+  const mock = await startMockLLM();
+  // fromParams: { path, line, content } → ['edit_file', path, parseInt(line), content]
+  mock.replyWithToolCall('edit_file', { path: 'native-edit.txt', line: 2, content: 'EDITED_LINE_2' });
+  mock.replyWith('Edited.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'edit line 2' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.strictEqual(fs.readFileSync(path.join(CWD, 'native-edit.txt'), 'utf8'), 'line1\nEDITED_LINE_2\nline3\n');
+    assert.deepStrictEqual(asks, [{ actionType: 'file', tag: 'edit_file' }]);
+    assert.strictEqual(ev.tools[0].tag, 'edit_file');
+    assertNativeRooting(messages, 'edit_file');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 3. Native file-mutating: delete_file.
+// ---------------------------------------------------------------------------
+
+test('native delete_file: removes the file, gate fires, result rooted', async () => {
+  const target = path.join(CWD, 'native-delete.txt');
+  fs.writeFileSync(target, 'doomed');
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('delete_file', { path: 'native-delete.txt' });
+  mock.replyWith('Deleted.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'delete it' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.ok(!fs.existsSync(target), 'the file was deleted');
+    assert.deepStrictEqual(asks, [{ actionType: 'file', tag: 'delete_file' }]);
+    assert.strictEqual(ev.tools[0].tag, 'delete_file');
+    const toolMsg = assertNativeRooting(messages, 'delete_file');
+    assert.match(toolMsg.content, /Deleted native-delete\.txt/);
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 4. Native file-mutating: move_file (multi-arg src/dst).
+// ---------------------------------------------------------------------------
+
+test('native move_file: renames src→dst, gate fires, result rooted', async () => {
+  fs.writeFileSync(path.join(CWD, 'native-src.txt'), 'movable');
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('move_file', { src: 'native-src.txt', dst: 'native-dst.txt' });
+  mock.replyWith('Moved.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'move it' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.ok(!fs.existsSync(path.join(CWD, 'native-src.txt')), 'source gone');
+    assert.strictEqual(fs.readFileSync(path.join(CWD, 'native-dst.txt'), 'utf8'), 'movable', 'dst has the content');
+    assert.deepStrictEqual(asks, [{ actionType: 'file', tag: 'move_file' }]);
+    assert.strictEqual(ev.tools[0].tag, 'move_file');
+    assertNativeRooting(messages, 'move_file');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 5. Native shell/exec — paired with the XML <exec> equivalent.
+// ---------------------------------------------------------------------------
+
+test('native shell: dispatches, gate fires (shell/exec), result rooted as role:"tool"', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('shell', { command: 'echo NATIVE_SHELL_OUT' });
+  mock.replyWith('Ran it.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'run echo' }];
+    const { metrics } = await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.deepStrictEqual(asks, [{ actionType: 'shell', tag: 'exec' }], 'shell gate consulted with exec tag');
+    assert.strictEqual(ev.tools.length, 1);
+    assert.strictEqual(ev.tools[0].tag, 'shell');
+
+    const toolMsg = assertNativeRooting(messages, 'shell');
+    assert.match(toolMsg.content, /NATIVE_SHELL_OUT/, 'command stdout flowed back');
+    assert.match(toolMsg.content, /Exit code: 0/);
+
+    assert.strictEqual(metrics.turns.length, 2);
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Ran it.'));
+  } finally {
+    await mock.close();
+  }
+});
+
+test('XML shell equivalent: same dispatch, XML "Tool execution results" shape', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo XML_SHELL_OUT</exec>');
+  mock.replyWith('Ran it.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'run echo' }];
+    await runner.runAgentLoop(messages, 'test-model', 5, null, { callbacks: cb });
+
+    assert.deepStrictEqual(asks, [{ actionType: 'shell', tag: 'exec' }], 'same gate fires on the XML rail');
+    assert.strictEqual(ev.tools[0].tag, 'shell');
+    const toolResult = messages.find((m) => m.role === 'user' && /Tool execution results/.test(m.content));
+    assert.ok(toolResult && /XML_SHELL_OUT/.test(toolResult.content) && /Exit code: 0/.test(toolResult.content));
+    assert.ok(!messages.some((m) => m.role === 'tool'), 'XML path does not use role:"tool" messages');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 6. Native plan-mode: a mutating tool arriving via the native path is WITHHELD,
+//    and approval (plan mode off) lets it proceed — mirrors the XML plan test,
+//    additionally proving the withheld result is rooted as role:'tool' (native).
+// ---------------------------------------------------------------------------
+
+test('native plan mode: withholds the native mutating tool (no mutation), result rooted as role:"tool"', async () => {
+  const target = path.join(CWD, 'native-planned.txt');
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('write_file', { path: 'native-planned.txt', content: 'SHOULD_NOT_WRITE' });
+  mock.replyWith('Here is my plan.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'change the file' }];
+    const res = await runner.runAgentLoop(messages, 'test-model', 10, null, { callbacks: cb, planMode: true });
+
+    assert.ok(!fs.existsSync(target), 'the file was NOT written in plan mode');
+    assert.strictEqual(res.withheldActions.length, 1, 'one action withheld');
+    assert.strictEqual(res.withheldActions[0].tag, 'write');
+    assert.deepStrictEqual(ev.withheld.map((w) => w.tag), ['write'], 'onPlanWithhold fired for the native call');
+    // Plan-mode withholding happens BEFORE the permission gate — never consulted.
+    assert.deepStrictEqual(asks, [], 'no permission prompt for a withheld tool');
+
+    // The withheld notice is still rooted on the native tool_call id (the loop
+    // pushes role:'tool' for native calls — lib/agent.js ~1366), keeping the
+    // assistant tool_calls ↔ tool-result map consistent for the next turn.
+    const toolMsg = assertNativeRooting(messages, 'write_file');
+    assert.match(toolMsg.content, /\[plan mode\] Withheld pending approval/);
+    assert.ok(messages.some((m) => m.role === 'assistant' && m.content === 'Here is my plan.'), 'plan recorded');
+  } finally {
+    await mock.close();
+  }
+});
+
+test('native plan mode OFF (approval): the same native mutating tool executes', async () => {
+  const target = path.join(CWD, 'native-approved.txt');
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('write_file', { path: 'native-approved.txt', content: 'APPROVED' });
+  mock.replyWith('Done.');
+  try {
+    const { runner, asks } = buildRunner(mock.base);
+    const { ev, cb } = collector();
+    const messages = [{ role: 'user', content: 'write it' }];
+    const res = await runner.runAgentLoop(messages, 'test-model', 10, null, { callbacks: cb, planMode: false });
+
+    assert.strictEqual(fs.readFileSync(target, 'utf8'), 'APPROVED', 'the file was written after approval');
+    assert.strictEqual(res.withheldActions.length, 0, 'nothing withheld with plan mode off');
+    assert.deepStrictEqual(asks, [{ actionType: 'file', tag: 'write_file' }], 'gate fired on the executing path');
+    assert.strictEqual(ev.tools[0].tag, 'write');
+    assertNativeRooting(messages, 'write_file');
+  } finally {
+    await mock.close();
+  }
+});