ucode-agent 1.62.8 → 1.64.0

package/src/core/settings.js

@@ -0,0 +1,148 @@
+/**
+ * settings.js — what ucode may do without asking, and what runs around its work.
+ *
+ *   ~/.ucode/settings.json          yours, in every project
+ *   <project>/.ucode/settings.json  this project's, on top of yours
+ *
+ *   {
+ *     "commands": "ask",              ask before every command ("auto", the default, runs them)
+ *     "allow": ["npm test"],          never asked about: a command by its first words, or "mcp:server__tool"
+ *     "hooks": {
+ *       "afterEdit": ["npx prettier --write {files}"],
+ *       "beforeCommand": ["node guard.js"]     a non-zero exit stops the command
+ *     }
+ *   }
+ *
+ * A project's own hooks and MCP servers run commands on this computer, and a
+ * cloned repository can carry any it likes. So they run only once the user
+ * has said yes to them, and saying yes is remembered against exactly what was
+ * approved: change the hooks and ucode asks again.
+ */
+
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const UCODE_DIR = path.join(os.homedir(), '.ucode');
+export const USER_SETTINGS = path.join(UCODE_DIR, 'settings.json');
+export const TRUST_FILE = path.join(UCODE_DIR, 'trusted.json');
+export const projectSettingsFile = (cwd) => path.join(cwd, '.ucode', 'settings.json');
+
+export async function readJson(file) {
+  try {
+    const data = JSON.parse(await fs.readFile(file, 'utf8'));
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function writeJson(file, data) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(temp, `${JSON.stringify(data, null, 2)}\n`);
+  await fs.rename(temp, file);
+}
+
+const list = (v) => (Array.isArray(v) ? v : v ? [v] : []).map(String).filter((s) => s.trim());
+
+/** Both files, merged: allow lists add up, the project's "commands" wins. */
+export async function loadSettings(cwd, { userFile = USER_SETTINGS } = {}) {
+  const [user, project] = await Promise.all([readJson(userFile), readJson(projectSettingsFile(cwd))]);
+  const hooks = (s, key) => list(s.hooks?.[key]);
+  return {
+    commands: (project.commands ?? user.commands) === 'ask' ? 'ask' : 'auto',
+    allow: [...new Set([...list(user.allow), ...list(project.allow)])],
+    hooks: { afterEdit: hooks(user, 'afterEdit'), beforeCommand: hooks(user, 'beforeCommand') },
+    projectHooks: { afterEdit: hooks(project, 'afterEdit'), beforeCommand: hooks(project, 'beforeCommand') },
+  };
+}
+
+/**
+ * What "always allow" remembers: "npm test" for `npm test -- --watch`. Never
+ * shorter than a flag: allowing `node -e "…"` once must not allow every
+ * `node -e` after it, so a command whose second word is a flag is kept whole.
+ */
+export function commandKey(command) {
+  const words = String(command).trim().split(/\s+/).filter(Boolean);
+  if (!words[1] || words[1].startsWith('-')) return words.join(' ');
+  return words.slice(0, 2).join(' ');
+}
+
+/** Is this command (or "mcp:name") on the allow list? A whole-word prefix counts. */
+export function isAllowed(allow, command) {
+  const c = String(command).trim();
+  // Chained commands are never covered by an entry for their first part.
+  if (/[;&|`$<>]/.test(c) && !c.startsWith('mcp:')) return false;
+  return allow.some((a) => c === a || c.startsWith(`${a} `));
+}
+
+/** Add an entry to this project's allow list. */
+export async function addAllow(cwd, entry) {
+  const file = projectSettingsFile(cwd);
+  const settings = await readJson(file);
+  const allow = list(settings.allow);
+  if (!allow.includes(entry)) await writeJson(file, { ...settings, allow: [...allow, entry] });
+}
+
+/**
+ * What was approved, down to the scripts it runs. Hashing only the settings
+ * text would let `node .ucode/guard.js` be approved and guard.js swapped
+ * afterwards, so every word of the commands that names a file in the project
+ * adds that file's contents. (A package fetched by npx is not covered: pin
+ * its version in the command to approve one release.)
+ */
+async function fingerprint(cwd, value) {
+  const hash = createHash('sha1').update(JSON.stringify(value));
+  const words = JSON.stringify(value).match(/[\w./\\@-]+\.\w+/g) ?? [];
+  for (const word of [...new Set(words)].sort()) {
+    const abs = path.resolve(cwd, word);
+    if (!abs.startsWith(path.resolve(cwd))) continue;
+    const text = await fs.readFile(abs).catch(() => null);
+    if (text) hash.update(`\0${word}\0`).update(text);
+  }
+  return hash.digest('hex');
+}
+
+/** Has the user approved exactly this (the project's hooks, its MCP servers) here before? */
+export async function isTrusted(cwd, what, value, file = TRUST_FILE) {
+  const all = await readJson(file);
+  return all[`${path.resolve(cwd)}#${what}`] === (await fingerprint(cwd, value));
+}
+
+export async function trust(cwd, what, value, file = TRUST_FILE) {
+  const all = await readJson(file);
+  await writeJson(file, { ...all, [`${path.resolve(cwd)}#${what}`]: await fingerprint(cwd, value) });
+}
+
+/** A path safe to put on a shell command line as it is. */
+const SAFE_PATH = /^[\w./\\ @+~-]+$/;
+
+/**
+ * Run one hook. `{files}` becomes the changed files, quoted; they are also in
+ * UCODE_FILES. Resolves to { code, output } and never throws.
+ */
+export function runHook(command, { cwd, files = [], env = {}, timeout = 30_000 } = {}) {
+  const quoted = files.filter((f) => SAFE_PATH.test(f)).map((f) => `"${f}"`).join(' ');
+  const line = String(command).includes('{files}') ? String(command).split('{files}').join(quoted) : String(command);
+  return new Promise((resolve) => {
+    let output = '';
+    let child;
+    try {
+      child = spawn(line, {
+        cwd, shell: true, windowsHide: true,
+        env: { ...process.env, ...env, UCODE_FILES: files.join('\n') },
+      });
+    } catch (err) {
+      resolve({ code: -1, output: err.message });
+      return;
+    }
+    const timer = setTimeout(() => { output += `\n(stopped after ${timeout / 1000}s)`; child.kill(); }, timeout);
+    child.stdout?.on('data', (d) => { output += d; });
+    child.stderr?.on('data', (d) => { output += d; });
+    child.on('error', (err) => { clearTimeout(timer); resolve({ code: -1, output: err.message }); });
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code: code ?? -1, output: output.trim() }); });
+  });
+}

package/src/core/snapshot.js

@@ -0,0 +1,147 @@
+/**
+ * snapshot.js — the whole project as it was before each turn, for /undo.
+ *
+ * undo.js remembers files ucode's own tools write, for one turn. That misses
+ * everything a command changes — a script that rewrites a config, a generator
+ * that adds twenty files — and it forgets the moment the next turn starts. So
+ * the project is snapshotted before every turn into a hidden git repository
+ * of ucode's own, under ~/.ucode/snapshots: the project's own .git is never
+ * read or written, and a folder with no git at all gets the same undo.
+ *
+ * The project's .gitignore is honoured, and node_modules and build output are
+ * always left out: they are huge, and an install can simply be run again.
+ *
+ * ponytail: snapshots are never pruned. Git only stores what changed, so a
+ * long-lived project grows by its edits; `git gc` in the snapshot folder, or
+ * deleting it, is the upgrade path if that ever matters.
+ */
+
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { walk } from '../tools/shared.js';
+
+export const SNAPSHOT_HOME = path.join(os.homedir(), '.ucode', 'snapshots');
+
+/** Past this many files, snapshotting every turn would cost real time. */
+export const MAX_FILES = 3000;
+
+const EXCLUDE = [
+  'node_modules/', '.next/', 'dist/', 'build/', 'out/', 'coverage/', '.cache/', '.turbo/',
+  '.venv/', 'venv/', '__pycache__/', 'target/', '.ucode/', '*.log',
+];
+
+function run(args, { cwd }) {
+  return new Promise((resolve) => {
+    let out = '';
+    let err = '';
+    let child;
+    try {
+      child = spawn('git', args, { cwd, windowsHide: true, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+    } catch (e) {
+      resolve({ code: -1, out: '', err: e.message });
+      return;
+    }
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    child.on('error', (e) => resolve({ code: -1, out, err: e.message }));
+    child.on('close', (code) => resolve({ code, out, err }));
+  });
+}
+
+export class Snapshots {
+  constructor(cwd, { home = SNAPSHOT_HOME } = {}) {
+    this.cwd = path.resolve(cwd);
+    const id = createHash('sha1').update(this.cwd.toLowerCase()).digest('hex').slice(0, 16);
+    this.gitDir = path.join(home, `${id}.git`);
+    this.usable = null; // decided once, by ready()
+  }
+
+  git(args) {
+    return run([
+      `--git-dir=${this.gitDir}`, `--work-tree=${this.cwd}`,
+      '-c', 'core.autocrlf=false', '-c', 'core.safecrlf=false', '-c', 'core.longpaths=true',
+      '-c', 'user.name=ucode', '-c', 'user.email=ucode@localhost', '-c', 'commit.gpgsign=false',
+      ...args,
+    ], { cwd: this.cwd });
+  }
+
+  /**
+   * Whether this folder can be snapshotted: git is installed, the folder is a
+   * project rather than a home directory or a drive, and it is small enough
+   * that a snapshot costs a moment.
+   */
+  async ready() {
+    if (this.usable !== null) return this.usable;
+    this.usable = false;
+    if (process.env.UCODE_SNAPSHOTS === '0') return false;
+    const home = path.resolve(os.homedir());
+    if (this.cwd === home || this.cwd === path.parse(this.cwd).root) return false;
+    const files = await walk(this.cwd, { limit: MAX_FILES + 1 }).catch(() => null);
+    if (!files || files.length > MAX_FILES) return false;
+    try {
+      await fs.access(path.join(this.gitDir, 'HEAD'));
+    } catch {
+      await fs.mkdir(path.dirname(this.gitDir), { recursive: true });
+      const init = await run(['init', '-q', '--bare', this.gitDir], { cwd: path.dirname(this.gitDir) });
+      if (init.code !== 0) return false;
+    }
+    await fs.mkdir(path.join(this.gitDir, 'info'), { recursive: true });
+    await fs.writeFile(path.join(this.gitDir, 'info', 'exclude'), `${EXCLUDE.join('\n')}\n`);
+    this.usable = true;
+    return true;
+  }
+
+  /** Record the project as it is now. Resolves to the snapshot id, or null. */
+  async take(label = 'snapshot') {
+    if (!(await this.ready())) return null;
+    const add = await this.git(['add', '-A', '.']);
+    if (add.code !== 0) return null;
+    const commit = await this.git(['commit', '-q', '--allow-empty', '--no-verify', '-m', label]);
+    if (commit.code !== 0) return null;
+    const head = await this.git(['rev-parse', 'HEAD']);
+    return head.code === 0 ? head.out.trim() : null;
+  }
+
+  /** Files that differ between a snapshot and now: [{ status: 'A'|'M'|'D', file }]. */
+  async changedSince(id) {
+    const now = await this.take('now');
+    if (!now) return [];
+    const diff = await this.git(['diff', '--name-status', '--no-renames', id, now]);
+    if (diff.code !== 0) return [];
+    return diff.out.split('\n').filter(Boolean).map((line) => {
+      const [status, ...rest] = line.split('\t');
+      return { status: status[0], file: rest.join('\t') };
+    });
+  }
+
+  /**
+   * Put the project back the way it was at a snapshot. Files made since are
+   * removed; files changed or deleted since come back.
+   */
+  async restore(id) {
+    const out = { restored: [], removed: [], failed: [] };
+    const changes = await this.changedSince(id);
+    for (const { status, file } of changes) {
+      if (status === 'A') {
+        try {
+          await fs.rm(path.join(this.cwd, file), { force: true });
+          out.removed.push(file);
+        } catch (err) {
+          out.failed.push(`${file}: ${err.message}`);
+        }
+      }
+    }
+    const back = changes.filter((c) => c.status !== 'A').map((c) => c.file);
+    // In batches: Windows caps a command line at 32K characters.
+    for (let i = 0; i < back.length; i += 100) {
+      const batch = back.slice(i, i + 100);
+      const checkout = await this.git(['checkout', id, '--', ...batch]);
+      if (checkout.code === 0) out.restored.push(...batch);
+      else out.failed.push(checkout.err.trim().split('\n')[0] || 'git checkout failed');
+    }
+    return out;
+  }
+}

package/src/core/tests.js

@@ -42,7 +42,11 @@ export async function testRunnerFor(dir) {
     ['pytest.ini', 'pyproject.toml', 'setup.cfg', 'tox.ini'].map((f) =>
       fs.access(path.join(dir, f)).then(() => true, () => false))
   );
-  return py.some(Boolean) ? 'pytest' : null;
+  if (py.some(Boolean)) return 'pytest';
+  const at = (f) => fs.access(path.join(dir, f)).then(() => true, () => false);
+  if (await at('go.mod')) return 'go';
+  if (await at('Cargo.toml')) return 'cargo';
+  return null;
 }
 
 /** Quote a path for a shell, and use forward slashes so Windows agrees. */
@@ -71,6 +75,15 @@ export function relatedCommand(runner, files) {
     if (!tests.length) return null;
     return `python -m pytest -q ${tests.map(arg).join(' ')}`;
   }
+  // Go tests a package at a time: the packages that hold the changed files.
+  if (runner === 'go') {
+    const dirs = [...new Set(list.filter((f) => /\.go$/i.test(f)).map((f) => path.dirname(f).replace(/\\/g, '/')))];
+    if (!dirs.length) return null;
+    return `go test ${dirs.map((d) => `./${d === '.' ? '' : `${d}/`}...`).join(' ')}`;
+  }
+  if (runner === 'cargo') {
+    return list.some((f) => /\.rs$/i.test(f)) ? 'cargo test --quiet' : null;
+  }
   return null;
 }
 

package/src/core/voice.js

@@ -0,0 +1,172 @@
+/**
+ * voice.js — the mic button: say what you want instead of typing it.
+ *
+ * Recording uses what the computer already has, so there is nothing to
+ * install on Windows: its own sound recorder API (winmm, driven through
+ * PowerShell). macOS uses sox or ffmpeg, Linux arecord or sox, whichever is
+ * there. The recording is sent to the same Gemini model as everything else,
+ * which writes down what was said (see transcribe in provider.js).
+ */
+
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Longest a recording runs before it stops by itself. */
+export const MAX_RECORD_MS = 2 * 60_000;
+
+/**
+ * Loudest sample (of 32767) below which a recording counts as silence. A quiet
+ * room measured ~400 on a laptop mic, speech ~3,000 and up. UCODE_MIC_QUIET
+ * tunes it for a mic that reads differently.
+ */
+export const quietBelow = () => Number(process.env.UCODE_MIC_QUIET) || 800;
+
+// winmm's MCI strings refuse long paths (error 304), so the file sits directly
+// in the temp folder with a short name. The script says "ready" once it is
+// recording, and saves when a line arrives on stdin.
+const WINDOWS_SCRIPT = [
+  '$sig = \'[DllImport("winmm.dll", CharSet = CharSet.Unicode)] public static extern int mciSendString(string c, System.Text.StringBuilder r, int l, System.IntPtr h);\'',
+  '$w = Add-Type -MemberDefinition $sig -Name Mci -Namespace UcodeMic -PassThru',
+  'function mci($c) { $r = $w::mciSendString($c, $null, 0, [IntPtr]::Zero); if ($r -ne 0) { [Console]::Out.WriteLine("mci-error $r"); exit 1 } }',
+  'mci "open new type waveaudio alias ucodemic"',
+  'mci "set ucodemic bitspersample 16 channels 1 samplespersec 16000 bytespersec 32000 alignment 2"',
+  'mci "record ucodemic"',
+  '[Console]::Out.WriteLine("ready")',
+  '[void][Console]::In.ReadLine()',
+  'mci "stop ucodemic"',
+  'mci (\'save ucodemic "\' + $env:UCODE_MIC_FILE + \'"\')',
+  'mci "close ucodemic"',
+].join('\n');
+
+/**
+ * The recorders to try on this platform, in order. `stop` is how each is told
+ * to finish and write its file: a line on stdin, "q" on stdin, or SIGINT.
+ */
+export function recordersFor(platform, file) {
+  if (platform === 'win32') {
+    const encoded = Buffer.from(WINDOWS_SCRIPT, 'utf16le').toString('base64');
+    return [{
+      cmd: 'powershell.exe',
+      args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded],
+      stop: 'line',
+      saysReady: true,
+    }];
+  }
+  const sox = { cmd: 'rec', args: ['-q', '-c', '1', '-r', '16000', '-b', '16', file], stop: 'SIGINT' };
+  if (platform === 'darwin') {
+    return [sox, {
+      cmd: 'ffmpeg',
+      args: ['-loglevel', 'error', '-f', 'avfoundation', '-i', ':0', '-ac', '1', '-ar', '16000', '-y', file],
+      stop: 'q',
+    }];
+  }
+  return [{ cmd: 'arecord', args: ['-q', '-f', 'S16_LE', '-r', '16000', '-c', '1', file], stop: 'SIGINT' }, sox];
+}
+
+const NO_RECORDER = {
+  darwin: 'No recorder found. Install one with: brew install sox',
+  linux: 'No recorder found. Install one with: sudo apt install alsa-utils',
+};
+
+/** Start one recorder; resolves once it is listening, rejects with the reason it could not. */
+function launch(rec, file, run) {
+  return new Promise((resolve, reject) => {
+    const child = run(rec.cmd, rec.args, {
+      env: { ...process.env, UCODE_MIC_FILE: file },
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let out = '';
+    let settled = false;
+    const done = (fn, value) => { if (!settled) { settled = true; fn(value); } };
+
+    child.on('error', (err) => done(reject, err));
+    child.stdout?.on('data', (d) => {
+      out += d;
+      if (rec.saysReady && out.includes('ready')) done(resolve, child);
+      const code = /mci-error (\d+)/.exec(out)?.[1];
+      if (code) done(reject, new Error(`Windows could not use the microphone (error ${code}). Check one is plugged in and allowed in Settings › Privacy › Microphone.`));
+    });
+    child.on('exit', (code) => done(reject, new Error(`The recorder stopped before listening (exit ${code}). Check a microphone is connected.`)));
+    if (!rec.saysReady) child.on('spawn', () => done(resolve, child));
+  });
+}
+
+/**
+ * Start recording from the default microphone.
+ * Resolves to { stop() → Promise<Buffer|null>, cancel() → Promise<void> } once listening.
+ */
+export async function startRecording({ platform = process.platform, run = spawn, dir = os.tmpdir() } = {}) {
+  // A private folder of its own, so no other user can guess or pre-place the file.
+  const folder = await fs.mkdtemp(path.join(dir, 'ucm-'));
+  const file = path.join(folder, 'mic.wav');
+  const remove = () => fs.rm(folder, { recursive: true, force: true }).catch(() => {});
+
+  let child = null;
+  let rec = null;
+  try {
+    for (const candidate of recordersFor(platform, file)) {
+      try {
+        child = await launch(candidate, file, run);
+        rec = candidate;
+        break;
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+    }
+  } catch (err) {
+    await remove();
+    throw err;
+  }
+  if (!child) {
+    await remove();
+    throw new Error(NO_RECORDER[platform] ?? 'No sound recorder found on this computer.');
+  }
+
+  const closed = new Promise((resolve) => child.on('close', resolve));
+  // A recorder that will not finish is killed rather than waited on forever.
+  const finished = async () => {
+    const timer = setTimeout(() => child.kill('SIGKILL'), 10_000);
+    await closed;
+    clearTimeout(timer);
+  };
+
+  return {
+    async stop() {
+      if (rec.stop === 'line') child.stdin.write('\n');
+      else if (rec.stop === 'q') child.stdin.write('q');
+      else child.kill('SIGINT');
+      await finished();
+      const wav = await fs.readFile(file).catch(() => null);
+      await remove();
+      return wav;
+    },
+    async cancel() {
+      child.kill();
+      await finished();
+      await remove();
+    },
+  };
+}
+
+/** True when a 16-bit PCM WAV holds nothing louder than room noise, or under a third of a second. */
+export function isSilent(wav, threshold = quietBelow()) {
+  const at = wav.indexOf('data');
+  const start = at >= 0 ? at + 8 : 44;
+  if (wav.length - start < 16000 * 2 / 3) return true;
+  for (let i = start; i + 1 < wav.length; i += 2) {
+    if (Math.abs(wav.readInt16LE(i)) >= threshold) return false;
+  }
+  return true;
+}
+
+/** What the model heard, as one line for the input box: no quotes, no line breaks. */
+export function cleanTranscript(text) {
+  return String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^["'“”]+|["'“”]+$/g, '')
+    .trim();
+}

package/src/tools/browser.js

@@ -154,7 +154,8 @@ async function review(shots) {
     // tokens came back as an empty review. Keep the thinking short, and leave
     // room for the answer.
     maxOutputTokens: 4000,
-    reasoning: { effort: 'low' },
+    // Gemini's own field; the OpenRouter-style `reasoning` object was ignored.
+    effort: 'low',
     // The free vision model is often busy. One try, and a hard cap: a review
     // that cannot run is skipped, never waited on.
     attempts: 1,

package/src/tools/search.js

@@ -3,6 +3,7 @@
  * name pattern, and which lines match a regular expression.
  */
 
+import { spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { ToolFailure } from '../core/failure.js';
@@ -11,6 +12,59 @@ import {
   SKIP, MAX_GLOB_HITS, MAX_GREP_HITS, WALK_WIDTH,
 } from './shared.js';
 
+/** Whether `rg` runs here, asked once. UCODE_RIPGREP=0 never uses it. */
+let hasRipgrep;
+function ripgrepReady() {
+  if (process.env.UCODE_RIPGREP === '0') return Promise.resolve(false);
+  hasRipgrep ??= new Promise((resolve) => {
+    const child = spawn('rg', ['--version'], { windowsHide: true, stdio: 'ignore' });
+    child.on('error', () => resolve(false));
+    child.on('close', (code) => resolve(code === 0));
+  });
+  return hasRipgrep;
+}
+
+/**
+ * The same search through ripgrep, with the same rules as the walk below: the
+ * same folders skipped, hidden files and .gitignored ones searched, the same
+ * line format. Resolves to { hits, files }, or null when ripgrep is missing or
+ * cannot read the pattern.
+ */
+async function ripgrep(pattern, dir, { filter, ignoreCase }) {
+  if (!(await ripgrepReady())) return null;
+  const args = ['--line-number', '--no-heading', '--color', 'never', '--hidden', '--no-ignore', '--sort', 'path'];
+  for (const skip of SKIP) args.push('-g', `!${skip}/`);
+  if (filter) args.push('-g', filter);
+  if (ignoreCase) args.push('-i');
+  args.push('-e', pattern, '--', '.');
+
+  return new Promise((resolve) => {
+    const hits = [];
+    const files = new Set();
+    let rest = '';
+    let done = false;
+    const child = spawn('rg', args, { cwd: dir, windowsHide: true });
+    const finish = (value) => { if (!done) { done = true; resolve(value); } };
+    child.on('error', () => finish(null));
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      const lines = (rest + chunk).split(/\r?\n/);
+      rest = lines.pop();
+      for (const line of lines) {
+        const m = /^(.*?):(\d+):(.*)$/.exec(line);
+        if (!m || hits.length >= MAX_GREP_HITS) continue;
+        const rel = m[1].replace(/^\.[\\/]/, '').replace(/\\/g, '/');
+        const text = m[3].trim();
+        files.add(rel);
+        hits.push(`${rel}:${m[2]}: ${text.length > 200 ? `${text.slice(0, 200)}…` : text}`);
+      }
+      if (hits.length >= MAX_GREP_HITS) { child.kill(); finish({ hits, files: files.size }); }
+    });
+    // 0 found, 1 nothing found, 2 an error such as a pattern it cannot read.
+    child.on('close', (code) => finish(code === 0 || code === 1 || hits.length ? { hits, files: files.size } : null));
+  });
+}
+
 export async function listDir({ path: p = '.' }) {
   const target = resolveIn(p || '.', 'list_dir');
   await guard(target, `list ${target.abs}`);
@@ -131,6 +185,26 @@ export async function grep({ pattern, path: p = '.', glob: filter, ignore_case =
     throw fsFailure(err, 'searching file contents', target.show);
   });
 
+  // A directory goes to ripgrep when it is installed: it is many times faster
+  // on a real project. A pattern ripgrep reads differently (lookarounds,
+  // back-references) makes it fail, and the search below runs instead.
+  if (!stat.isFile()) {
+    const fast = await ripgrep(pattern, target.abs, { filter, ignoreCase: ignore_case });
+    if (fast) {
+      if (!fast.hits.length) {
+        return result(`No line matched /${pattern}/ under ${target.show}${filter ? ` (limited to ${filter})` : ''}.`, 'no matches');
+      }
+      const capped = fast.hits.length >= MAX_GREP_HITS
+        ? `\n[stopped at ${MAX_GREP_HITS} matches — narrow the pattern, or pass a glob]`
+        : '';
+      return result(
+        fast.hits.join('\n') + capped,
+        `${fast.hits.length} match${fast.hits.length === 1 ? '' : 'es'} in ` +
+        `${fast.files} file${fast.files === 1 ? '' : 's'}`
+      );
+    }
+  }
+
   let base = target.abs;
   let candidates;
   if (stat.isFile()) {

package/src/tools/shared.js

@@ -10,6 +10,7 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { ToolFailure, Declined } from '../core/failure.js';
+import { isAllowed, commandKey } from '../core/settings.js';
 
 /**
  * How much of a result the model may see.
@@ -63,7 +64,25 @@ export function setConfirm(fn) {
   asker = fn;
 }
 
-export async function confirm(action, detail, risk = 'write') {
+/**
+ * What may run without asking. `askCommands` is the "commands": "ask" setting;
+ * `allow` is the always-allow list; `onAlways` saves a new entry to it.
+ */
+let policy = { askCommands: false, allow: [], onAlways: null };
+
+export function setPolicy(next) {
+  policy = { ...policy, ...next };
+}
+
+/** Is this command, or "mcp:tool", on the always-allow list? */
+export const allowedNow = (subject) => isAllowed(policy.allow, subject);
+
+/**
+ * Ask before acting. `always` names what an "always" answer allows from then
+ * on: a command's first words, or "mcp:tool". Callers check allowedNow()
+ * against the whole command first — the entry is only what gets saved.
+ */
+export async function confirm(action, detail, risk = 'write', always = null) {
   if (!asker) {
     throw new ToolFailure({
       kind: 'cannot_ask',
@@ -72,7 +91,19 @@ export async function confirm(action, detail, risk = 'write') {
       fix: 'Run ucode in a terminal so it can prompt before acting.',
     });
   }
-  if (!(await asker({ action, detail, risk }))) throw new Declined(action);
+  const answer = await asker({ action, detail, risk, always });
+  if (answer === 'always' && always) {
+    policy = { ...policy, allow: [...policy.allow, always] };
+    await Promise.resolve(policy.onAlways?.(always)).catch(() => {});
+    return;
+  }
+  if (!answer) throw new Declined(action);
+}
+
+/** A command about to run, put to the user first when they asked for that. */
+export async function approveCommand(command, where) {
+  if (!policy.askCommands || allowedNow(command)) return;
+  await confirm(`run ${String(command).trim().slice(0, 160)}`, `in ${where}`, 'command', commandKey(command));
 }
 
 // ---------------------------------------------------------------------------

package/src/tools/shell.js

@@ -14,7 +14,7 @@ import { openSync, closeSync, readFileSync, mkdirSync, statSync } from 'node:fs'
 import os from 'node:os';
 import path from 'node:path';
 import { ToolFailure } from '../core/failure.js';
-import { resolveIn, guard, confirm, result, getRoot, MAX_OUTPUT } from './shared.js';
+import { resolveIn, guard, confirm, approveCommand, result, getRoot, MAX_OUTPUT } from './shared.js';
 
 const DEFAULT_TIMEOUT = 120_000;
 const MAX_TIMEOUT = 600_000;
@@ -713,6 +713,9 @@ export async function runCommand({ command, cwd, timeout_ms, background }, { onO
     : { abs: getRoot(), inside: true, show: '.' };
   await guard(workdir, `run a command in ${workdir.abs}`);
 
+  // "commands": "ask" in settings: every command is put to the user first.
+  await approveCommand(command, workdir.show);
+
   const env = childEnv();
   const server = startsServer(command);