mixdog 1.3.5 → 1.4.1

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/misuse-guard.mjs

@@ -0,0 +1,240 @@
+// Runtime guards against shell-tool misuse, run in the shell tool's validation
+// step before hooks, approvals and execution (tool-exec.mjs) and again, once,
+// for callers that reach executeBashTool without that step:
+//   1. a leading whole-second sleep of 2 s or more is rejected (a wait belongs
+//      to background + task wait);
+//   2. a plain leading `cd <dir>` moves into the `cwd` argument;
+//   3. a shell file read (cat/Get-Content/grep/ls …) gets a pointer to the
+//      read / grep / list tools — a note now, a rejection when the mode flips.
+import { shellSplitPipelineSegments, shellSplitSegments, shellTokenize } from '../shell-analysis.mjs';
+import { resolveShellFor } from '../shell-runtime.mjs';
+import { formatShellToolFailure } from './result-format.mjs';
+
+/** `warn` runs the read with a note; `reject` returns the block without running. */
+export const SHELL_FILE_READ_MODE = 'warn';
+export const SHELL_FILE_READ_NOTE = 'Note: use the read / grep / list tools for files instead of the shell.';
+const SHELL_FILE_READ_BLOCK =
+  'Blocked: use read / grep / list for files instead of the shell (read takes offset/limit for a window of a large file).';
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// ── 1. leading sleep ─────────────────────────────────────────────────────────
+
+// Sub-2-second pacing stays allowed: only a bare whole-second sleep of 2 or
+// more is refused. Float seconds, `-Milliseconds`, unit suffixes, pipelines,
+// subshells and later statements are not matched.
+const LEADING_SLEEP_MIN_SECONDS = 2;
+// The first statement ends the command or is followed by `;`, `&&` or a newline.
+const STATEMENT_END = String.raw`(?=\s*(?:$|;|&&|\r?\n))`;
+// The argument stays on the command's line: a number on the next line is its own statement.
+// PowerShell takes any prefix of `-Seconds` (`-s`, `-sec`, …) as the seconds parameter.
+const POSIX_SLEEP_RE = new RegExp(String.raw`^\s*sleep[ \t]+(\d+)${STATEMENT_END}`);
+const POWERSHELL_SLEEP_RE = new RegExp(
+  String.raw`^\s*(?:start-sleep|sleep)[ \t]+(?:-s(?:e(?:c(?:o(?:n(?:d(?:s)?)?)?)?)?)?[ \t:]+)?(\d+)${STATEMENT_END}`,
+  'i'
+);
+
+/** Whole seconds of the sleep the command starts with, or null when it does not start with one. */
+function leadingSleepSeconds(command, shellType) {
+  const match = (shellType === 'powershell' ? POWERSHELL_SLEEP_RE : POSIX_SLEEP_RE).exec(String(command ?? ''));
+  return match ? Number(match[1]) : null;
+}
+
+function leadingSleepFailure(command, shellType) {
+  const seconds = leadingSleepSeconds(command, shellType);
+  if (seconds === null || seconds < LEADING_SLEEP_MIN_SECONDS) return null;
+  return formatShellToolFailure(
+    `Blocked: the leading sleep of ${seconds} s was not run. For a long-running command use background:true; its completion arrives automatically. To wait for a specific task when the result is needed now, use task wait — do not poll in a sleep loop. A deliberate delay under ${LEADING_SLEEP_MIN_SECONDS} seconds is allowed.`
+  );
+}
+
+// ── 2. leading cd → cwd ──────────────────────────────────────────────────────
+
+// One plain path token: quoted (no variable or escape characters) or unquoted
+// (no shell metacharacters, glob characters included), then `;` or `&&` and a remainder.
+const CD_RE =
+  /^\s*(?:cd|set-location)\s+(?:-path\s+)?(?:"([^"$`]+)"|'([^'$`]+)'|([^\s;&|<>"'`$(){}*?[,@%#!]+))\s*(?:;|&&)\s*(\S[\s\S]*)$/i;
+// `Set-Location -Path` expands wildcards even in a quoted path; a POSIX shell
+// keeps a quoted glob literal, so only PowerShell leaves those unrewritten.
+const POWERSHELL_WILDCARD_RE = /[*?[]/;
+const CD_LIKE_RE = /^(?:cd|set-location|pushd|popd)(?:\s|;|&|$)/i;
+
+/** `{ dir, rest }` for a command that starts with a plain `cd <dir>` and more, else null. */
+function splitLeadingCd(command, shellType) {
+  const match = CD_RE.exec(String(command ?? ''));
+  if (!match) return null;
+  const dir = match[1] ?? match[2] ?? match[3];
+  const rest = match[4];
+  if (CD_LIKE_RE.test(rest)) return null;
+  if (dir.trim() === '' || dir.startsWith('-')) return null;
+  if (shellType === 'powershell' && POWERSHELL_WILDCARD_RE.test(dir)) return null;
+  // `~user` is another account's home in a shell, not a folder named so; a
+  // quoted `~` is a literal directory name, only an unquoted one is home.
+  if (dir.startsWith('~') && (match[3] === undefined || !/^~(?:[\\/]|$)/.test(dir))) return null;
+  // A POSIX backslash escapes; only single quotes keep it literal.
+  if (shellType !== 'powershell' && match[2] === undefined && dir.includes('\\')) return null;
+  return { dir, rest };
+}
+
+// ── 3. shell file reads ──────────────────────────────────────────────────────
+
+const POWERSHELL_READERS = {
+  'get-content': 'read',
+  gc: 'read',
+  cat: 'read',
+  type: 'read',
+  'select-string': 'grep',
+  sls: 'grep',
+  'get-childitem': 'list',
+  gci: 'list',
+  ls: 'list',
+  dir: 'list',
+  rg: 'grep',
+};
+const POSIX_READERS = {
+  cat: 'read',
+  head: 'read',
+  tail: 'read',
+  less: 'read',
+  grep: 'grep',
+  rg: 'grep',
+  ls: 'list',
+  find: 'list',
+};
+// Flags whose next token is a path or pattern operand, and flags whose next
+// token is a plain value; both are read off the operand count.
+const OPERAND_FLAGS = new Set(['-path', '-literalpath', '-pattern', '-e', '--regexp', '-f', '--file']);
+const VALUE_FLAGS = new Set(['-encoding', '-filter', '-include', '-exclude', '-g', '--glob', '-t', '--type']);
+// A later pipeline stage that only shapes text; anything else is a program
+// the first stage feeds.
+const TEXT_FILTERS = new Set([
+  'select-object',
+  'select',
+  'select-string',
+  'sls',
+  'where-object',
+  'sort-object',
+  'sort',
+  'measure-object',
+  'format-table',
+  'format-list',
+  'ft',
+  'fl',
+  'out-string',
+  'out-host',
+  'head',
+  'tail',
+  'grep',
+  'egrep',
+  'rg',
+  'wc',
+  'uniq',
+  'cut',
+  'findstr',
+]);
+const FIND_WRITERS = new Set(['-exec', '-execdir', '-ok', '-okdir', '-delete', '-fprint', '-fprintf', '-fls']);
+const BENIGN_REDIRECT_TARGET = /^(?:&\d|\$null|\/dev\/null|nul)$/i;
+
+const commandName = (token) =>
+  String(token ?? '')
+    .toLowerCase()
+    .replace(/^.*[\\/]/, '')
+    .replace(/\.exe$/, '');
+
+// The path/pattern operands of a stage, or null when it writes a file.
+function stageOperands(args) {
+  const operands = [];
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (token === '>' || token === '>>') {
+      if (!BENIGN_REDIRECT_TARGET.test(args[i + 1] ?? '')) return null;
+      i++;
+      continue;
+    }
+    const flag = token.toLowerCase();
+    if (flag.startsWith('-') && flag.length > 1) {
+      if (OPERAND_FLAGS.has(flag) && i + 1 < args.length) operands.push(args[++i]);
+      else if (VALUE_FLAGS.has(flag)) i++;
+      continue;
+    }
+    // A bare count (`head -n 5`, `tail -n +5`) is a flag value, not an operand.
+    if (!/^[+-]?\d+$/.test(token)) operands.push(token);
+  }
+  return operands;
+}
+
+/**
+ * `{ tool, command }` when the command's first statement starts with a
+ * read-only file command on a path — the tool that does that job — else null.
+ * A pipeline whose later stage is a program, a write, and a first stage that
+ * reads piped input are not file reads.
+ */
+function detectShellFileRead(command, shellType) {
+  const first = shellSplitSegments(String(command ?? ''))[0];
+  if (!first) return null;
+  const stages = shellSplitPipelineSegments(first);
+  const tokens = shellTokenize(stages[0] ?? '');
+  if (!tokens || tokens.length === 0) return null;
+  const name = commandName(tokens[0]);
+  const tool = (shellType === 'powershell' ? POWERSHELL_READERS : POSIX_READERS)[name];
+  if (!tool) return null;
+  for (const stage of stages.slice(1)) {
+    if (!TEXT_FILTERS.has(commandName(stage.trim().split(/\s+/)[0]))) return null;
+  }
+  const args = tokens.slice(1);
+  if (name === 'find') {
+    const lowered = args.map((token) => token.toLowerCase());
+    const matchesNames = lowered.some((token) => ['-name', '-iname', '-path', '-regex'].includes(token));
+    return matchesNames && !lowered.some((token) => FIND_WRITERS.has(token)) ? { tool, command: name } : null;
+  }
+  const operands = stageOperands(args);
+  if (!operands) return null;
+  // A search names its pattern and then the path it reads; with one operand it reads piped input.
+  const minOperands = tool === 'grep' ? 2 : 1;
+  return operands.length >= minOperands ? { tool, command: name } : null;
+}
+
+// ── the guard ────────────────────────────────────────────────────────────────
+
+/** The syntax family of the shell a call asks for (`args.shell`, as foreign adapters set it), else the default shell's. */
+export function requestedShellType(args) {
+  const requested = typeof args?.shell === 'string' && args.shell ? resolveShellFor(args.shell) : null;
+  return (requested ?? resolveShellFor('default'))?.shellType;
+}
+
+function recordFileRead(telemetry, entry) {
+  if (!telemetry || typeof telemetry !== 'object') return;
+  if (!Array.isArray(telemetry.shellMisuse)) telemetry.shellMisuse = [];
+  telemetry.shellMisuse.push({ kind: 'file-read', ...entry });
+}
+
+/**
+ * Apply the three guards to a shell call.
+ * @returns {{ failure: string } | { args: object, notes: string[] }} the
+ *   rejection, or the call to run (a leading `cd` moved into `cwd`) with the
+ *   lines to add to its result.
+ */
+export function guardShellCall(
+  args,
+  { shellType, fileReadMode = SHELL_FILE_READ_MODE, agent = null, sessionId = null, telemetry = null } = {}
+) {
+  if (!isPlainObject(args) || typeof args.command !== 'string') return { args, notes: [] };
+  const notes = [];
+  let guarded = args;
+  const moved = args.cwd == null ? splitLeadingCd(args.command, shellType) : null;
+  if (moved) {
+    guarded = { ...args, command: moved.rest, cwd: moved.dir };
+    notes.push(`Moved \`cd ${moved.dir}\` into cwd.`);
+  }
+  if (args.background !== true) {
+    const sleepFailure = leadingSleepFailure(guarded.command, shellType);
+    if (sleepFailure) return { failure: sleepFailure };
+  }
+  const read = detectShellFileRead(guarded.command, shellType);
+  if (read) {
+    recordFileRead(telemetry, { mode: fileReadMode, tool: read.tool, command: read.command, agent, sessionId });
+    if (fileReadMode === 'reject') return { failure: formatShellToolFailure(SHELL_FILE_READ_BLOCK) };
+    notes.push(SHELL_FILE_READ_NOTE);
+  }
+  return { args: guarded, notes };
+}

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/result-format.mjs

@@ -118,7 +118,7 @@ const _PS_UNIX_EQUIVALENTS = {
   head: 'Select-Object -First N',
   tail: 'Select-Object -Last N',
   wc: 'Measure-Object -Line',
-  grep: 'Select-String (or the grep tool)',
+  grep: 'the grep tool',
   sed: 'the edit tool',
   awk: 'ForEach-Object / the edit tool',
   pgrep: 'Get-Process -Name <name>',

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/shell-cwd.mjs

@@ -0,0 +1,38 @@
+// The shell tool's optional `cwd` argument: where one command runs. Omitted,
+// the command runs in the session cwd; a relative value resolves against it.
+import { stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+// `~`, `~/x` (and `~\x` on Windows) name the user's home folder.
+function expandHome(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/') || (process.platform === 'win32' && path.startsWith('~\\'))) {
+    return resolve(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+/** The directory a shell call runs in: its `cwd` argument resolved against the session cwd. */
+export function effectiveShellCwd(args, sessionCwd) {
+  const requested = args?.cwd;
+  // Trim only decides blank; a name with edge spaces is used as given.
+  if (typeof requested !== 'string' || requested.trim() === '') return sessionCwd;
+  return resolve(sessionCwd || process.cwd(), expandHome(requested));
+}
+
+/** The cwd hooks and approvals see for a tool call: the effective one for shell, the session cwd otherwise. */
+export function effectiveToolCwd(toolName, args, sessionCwd) {
+  return toolName === 'shell' ? effectiveShellCwd(args, sessionCwd) : sessionCwd;
+}
+
+/** An error naming the path when `dir` is not an existing directory, else null. */
+export async function shellCwdError(dir) {
+  let info;
+  try {
+    info = await stat(dir);
+  } catch {
+    return `shell cwd "${dir}" does not exist`;
+  }
+  return info.isDirectory() ? null : `shell cwd "${dir}" is not a directory`;
+}

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/spawn-env.mjs

@@ -1,3 +1,4 @@
+import { applySessionScratchEnv } from '../../../../../shared/session-scratch.mjs';
 import { withSkillLauncherPath } from '../../../../../shared/skill-script-runtime.mjs';
 import {
   applyShellEgressPolicy,
@@ -6,7 +7,8 @@ import {
   scrubRuntimeRootVars,
 } from '../../env-scrub.mjs';
 
-export function buildShellSpawnEnv(cwd, baseEnv = process.env) {
+// `sessionId` points TEMP/TMP/TMPDIR at that session's scratch directory.
+export function buildShellSpawnEnv(cwd, baseEnv = process.env, sessionId = null) {
   const spawnEnv = {
     ...baseEnv,
     LANG: 'C.UTF-8',
@@ -24,5 +26,5 @@ export function buildShellSpawnEnv(cwd, baseEnv = process.env) {
   // `mixdog-skill-node` (a skill's ${MIXDOG_SKILL_NODE}) resolves in every
   // model shell; only this env gets the entry, never the daemon's own.
   withSkillLauncherPath(spawnEnv);
-  return spawnEnv;
+  return applySessionScratchEnv(spawnEnv, sessionId);
 }

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool.mjs

@@ -25,6 +25,8 @@ import { planShellDeadlines } from './bash-tool/deadline-plan.mjs';
 import { planShellInvocation } from './bash-tool/invocation-plan.mjs';
 import { renderBackgroundedResult } from './bash-tool/backgrounded-result.mjs';
 import { renderCompletedResult } from './bash-tool/completed-result.mjs';
+import { effectiveShellCwd, shellCwdError } from './bash-tool/shell-cwd.mjs';
+import { guardShellCall, requestedShellType } from './bash-tool/misuse-guard.mjs';
 
 export {
   SURVIVING_DESCENDANTS_WARNING,
@@ -64,9 +66,26 @@ function settleMutationCaches(shellEffects, backgroundJobId, runSettled = null)
 }
 
 export async function executeBashTool(args, workDir, options = {}) {
-  // Every call starts from the current Project root. A command-local `cd`
-  // never creates a second session cwd authority beside the dedicated cwd tool.
-  const bashWorkDir = workDir;
+  // The tool-exec layer already guarded the call before its hooks ran and left
+  // its notes; a direct caller is guarded here.
+  const guarded = Array.isArray(options?.shellGuardNotes)
+    ? { args, notes: options.shellGuardNotes }
+    : guardShellCall(args, {
+        shellType: requestedShellType(args),
+        agent: options?.agent,
+        sessionId: options?.sessionId,
+        telemetry: options?.resultTelemetry,
+      });
+  if (guarded.failure) return guarded.failure;
+  args = guarded.args;
+  const guardNotes = guarded.notes;
+  // A call starts from the current Project root unless it names a `cwd`. A
+  // command-local `cd` never creates a second session cwd authority beside it.
+  const bashWorkDir = effectiveShellCwd(args, workDir);
+  if (bashWorkDir !== workDir) {
+    const cwdError = await shellCwdError(bashWorkDir);
+    if (cwdError) return formatShellToolFailure(cwdError);
+  }
   // Approval comes from the runtime's options, never from model-supplied args.
   const elevationApproved = options?.elevationApproved === true;
   const prepared = prepareShellCommand(args, { elevationApproved });
@@ -97,7 +116,12 @@ export async function executeBashTool(args, workDir, options = {}) {
   // A queued run, or a foreground tree that may outlive its result, settles later.
   let runSettled = null;
   try {
-    const invocation = await planShellInvocation({ command, resolvedSpec, cwd: bashWorkDir });
+    const invocation = await planShellInvocation({
+      command,
+      resolvedSpec,
+      cwd: bashWorkDir,
+      sessionId: options?.callerSessionId || options?.sessionId || null,
+    });
     if (invocation.failure) return invocation.failure;
     combinedAbort = combineAbortSignals(await sessionAbortSignal(options?.sessionId), options?.abortSignal || null);
     const startedAtMs = Date.now();
@@ -106,6 +130,7 @@ export async function executeBashTool(args, workDir, options = {}) {
       shellArg: invocation.execShellArg,
       shellArgs: invocation.execShellArgs,
       command: invocation.wrappedCommand,
+      displayCommand: command,
       execScript: invocation.execScript,
       directArgv: invocation.directArgv,
       elevationApproved,
@@ -147,12 +172,12 @@ export async function executeBashTool(args, workDir, options = {}) {
       stdout,
       stderr,
     };
-    if (backgrounded) return renderBackgroundedResult(rendering);
+    if (backgrounded) return renderBackgroundedResult({ ...rendering, notes: guardNotes.join('\n') });
     return renderCompletedResult({
       ...rendering,
       analysisCommand,
       timeout: deadlines.timeout,
-      rewriteNote: [wmicRewrite?.note, bashismRewrite?.note].filter(Boolean).join('\n'),
+      rewriteNote: [wmicRewrite?.note, bashismRewrite?.note, ...guardNotes].filter(Boolean).join('\n'),
     });
   } finally {
     inputWake?.dispose();

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -5,7 +5,7 @@
 // behavior, argument shapes, and the usage boundaries that only apply to that
 // tool; cross-tool policy lives in rules/shared/*.md.
 // Platform-specific command syntax belongs next to the command argument.
-import { GIT_TOOL_DEF } from './git-command-tool.mjs';
+import { GIT_AGENT_TOOL_DEF, GIT_TOOL_DEF } from './git-command-tool.mjs';
 import { PUBLIC_PATH_BATCH_LIMIT, PUBLIC_READ_WINDOW_MAX } from './arg-guard.mjs';
 import { GITHUB_TOOL_DEF } from '../../../../github/tool.mjs';
 import { envFlag } from '../../../../shared/env.mjs';
@@ -27,13 +27,71 @@ export const TASK_WAIT_TIMEOUT_DEFAULT_MS = TASK_WAIT_DEFAULT_MS;
 export const TASK_WAIT_TIMEOUT_MIN_MS = TASK_WAIT_MIN_MS;
 export const TASK_WAIT_TIMEOUT_MAX_MS = TASK_WAIT_MAX_MS;
 const _holdS = budgetSeconds(SHELL_HOLD_DEFAULT_MS);
-const _shellSyntaxCheat =
-  process.platform === 'win32'
-    ? " PowerShell: ; between independent commands, if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } between dependent ones; no heredoc, </dev/null or | head/tail/wc (Select-Object -First/-Last); multiline python/node via @'…'@ | python - (node -); 2>$null; /c/→C:\\; $PID is reserved."
-    : ' Bash: chain dependent commands with &&; multiline input via a quoted heredoc delimiter, not extra quoting/escape layers.';
 // Process-stable switch used to describe foreground-only execution accurately.
 const _shellBackgroundDisabled = envFlag('MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS');
 
+// Shell kinds the description is written for: 'powershell' or 'posix' (bash,
+// zsh, sh, Git Bash, WSL), the `shellType` of the runtime's resolved shell.
+// BUILTIN_TOOLS is static, so it carries the platform's default kind; a
+// session whose configured system shell is the other kind gets the matching
+// text through bindShellKind where the session tool schema is assembled.
+const _defaultShellKind = process.platform === 'win32' ? 'powershell' : 'posix';
+
+// The kind's banned commands → replacement tool. `edit/apply_patch` is
+// rewritten per model by the edit-dialect surface filter.
+export function buildShellRoutingRules(kind = _defaultShellKind) {
+  const pairs =
+    kind === 'powershell'
+      ? 'Get-Content/gc/cat/type→read; Get-ChildItem/dir/ls→list/glob/find; Select-String/findstr→grep; Set-Content/Add-Content/Out-File/`>`→edit/apply_patch'
+      : 'cat/head/tail/less→read; ls/tree→list; find→glob/find; grep/rg/ag→grep; file authoring via sed/awk/echo >/tee/heredoc→edit/apply_patch';
+  return `Never use shell commands/scripts for work other tools cover: ${pairs}; git→git (-C <dir> for other folders); code structure→code_graph.`;
+}
+
+function buildShellDescription(kind) {
+  const run = _shellBackgroundDisabled
+    ? 'Commands run in the foreground until completion.'
+    : `Holds ${_holdS}s; then, or on input/task notification, backgrounds with task_id (command keeps running). Completion is automatic; never poll, and never sleep/poll-loop inside the shell (background:true or wait_ms instead; for an external job, background a command that exits when it ends). Result needed now: task wait. Independent long runs: background:true; cancel when done.`;
+  return `Run programs, builds, tests and computation. ${buildShellRoutingRules(kind)} ${run}`;
+}
+
+function buildShellCommandDescription(kind) {
+  const cheat =
+    kind === 'powershell'
+      ? " PowerShell: ; between independent commands, if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } between dependent ones; no Bash heredocs or </dev/null; Select-Object shapes program output, not file reads; multiline python/node via @'…'@ | python - (node -); 2>$null; /c/→C:\\; $PID is reserved."
+      : ' Bash: chain dependent commands with &&; multiline input via a quoted heredoc delimiter, not extra quoting/escape layers.';
+  return `Command.${cheat}`;
+}
+
+// One bound copy per (tool, kind), so a session's shell tool keeps its identity
+// and bytes from turn to turn.
+const _boundShellTools = new WeakMap();
+
+/** The shell tool with the text of `kind`, when that differs from the static default. */
+export function bindShellKind(tool, kind) {
+  if (tool?.name !== 'shell' || kind === _defaultShellKind || (kind !== 'powershell' && kind !== 'posix')) return tool;
+  const cached = _boundShellTools.get(tool)?.get(kind);
+  if (cached) return cached;
+  const properties = tool.inputSchema?.properties || {};
+  const bound = {
+    ...tool,
+    description: buildShellDescription(kind),
+    inputSchema: {
+      ...tool.inputSchema,
+      properties: {
+        ...properties,
+        command: { ...properties.command, description: buildShellCommandDescription(kind) },
+      },
+    },
+  };
+  if (!_boundShellTools.has(tool)) _boundShellTools.set(tool, new Map());
+  _boundShellTools.get(tool).set(kind, bound);
+  return bound;
+}
+
+function taskTimeoutDescription(defaultMs) {
+  return `Wait ceiling in ms; else current output at the ceiling. Default ${defaultMs}; clamped to ${TASK_WAIT_TIMEOUT_MIN_MS}-${TASK_WAIT_TIMEOUT_MAX_MS}.`;
+}
+
 export const BUILTIN_TOOLS = [
   {
     name: 'read',
@@ -47,7 +105,7 @@ export const BUILTIN_TOOLS = [
       compressible: false,
     },
     description:
-      "Read file windows or images. One call per read stage: {file_path, offset, limit} entries for every located site (≤10 files per call), never a whole large file. Content in context is never read again. Missing paths are reported, never replaced. Directories: list. Binaries: bounded hex. Rows carry no line numbers; `[lines a-b]` gives each block's range. Never count rows: before writing a line number, copy it from grep, code_graph or git diff output; otherwise cite path and symbol.",
+      "Read file windows or images. One call per read stage: {file_path, offset, limit} entries for every located site, never a whole large file. Content in context is never read again. Missing paths are reported, never replaced. Directories: list. Binaries: bounded hex. Rows carry no line numbers; `[lines a-b]` gives each block's range. Never count rows: before writing a line number, copy it from grep, code_graph or git diff output; otherwise cite path and symbol.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -75,8 +133,7 @@ export const BUILTIN_TOOLS = [
               },
             },
           ],
-          description:
-            'Path(s) or {file_path, offset, limit} entries; overlapping windows of one file merge. A glob fans out to ≤10 newest files, 25 lines each.',
+          description: 'Overlapping windows of one file merge. A glob fans out to ≤10 newest files.',
         },
         offset: {
           type: 'integer',
@@ -113,14 +170,11 @@ export const BUILTIN_TOOLS = [
       compressibleLossless: true,
     },
     description:
-      'Replace exact text in one file. old_string must match once unless replace_all is true. Every non-overlapping edit of the stage in one response, using existing text, not text another edit creates; many files → one edit per file, all in that response. Widened replacements keep intervening lines verbatim.',
+      'Replace exact text in one file. old_string must match once unless replace_all is true. Every non-overlapping edit of the stage in one response, using existing text, not text another edit creates; many files → one edit per file. Widened replacements keep intervening lines verbatim.',
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: {
-          type: 'string',
-          description: 'Path to the file to modify.',
-        },
+        file_path: { type: 'string' },
         old_string: {
           type: 'string',
           description:
@@ -133,7 +187,7 @@ export const BUILTIN_TOOLS = [
         replace_all: {
           type: 'boolean',
           default: false,
-          description: 'Replace all occurrences of old_string; default false.',
+          description: 'Replace all occurrences of old_string.',
         },
       },
       required: ['file_path', 'old_string', 'new_string'],
@@ -151,11 +205,15 @@ export const BUILTIN_TOOLS = [
       openWorldHint: true,
       compressible: true,
     },
-    description: `Run programs, builds, tests and computation. Never use shell commands or scripts for work covered by dedicated tools: cat/head/tail→read, ls→list, find→glob, filename lookup→find, grep/rg→grep, code structure→code_graph, file edits/writes (sed/awk/redirection)→edit/apply_patch, Git→git when that tool is on the surface. Tool names are not shell commands. ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : `Holds up to ${_holdS}s for the result. Still running at ${_holdS}s, or new user input or a task notification arrives: it moves to the background (never killed) and returns task_id plus output so far. Completion is delivered automatically; task wait only when you need the result now. If no execution slot frees, the command is queued as a background task. Dev servers/watchers: background:true, and stop them with task cancel when done.`}`,
+    description: buildShellDescription(_defaultShellKind),
     inputSchema: {
       type: 'object',
       properties: {
-        command: { type: 'string', description: `Command.${_shellSyntaxCheat}` },
+        command: { type: 'string', description: buildShellCommandDescription(_defaultShellKind) },
+        cwd: {
+          type: 'string',
+          description: 'Working directory; default the Project. Use it instead of cd/Set-Location.',
+        },
         timeout_ms: {
           type: 'integer',
           minimum: 0,
@@ -165,7 +223,7 @@ export const BUILTIN_TOOLS = [
           type: 'integer',
           minimum: SHELL_HOLD_MIN_MS,
           maximum: SHELL_HOLD_MAX_MS,
-          description: `Hold in ms before a still-running command moves to the background (default ${SHELL_HOLD_DEFAULT_MS}). Usually omit.`,
+          description: `Hold in ms before a still-running command moves to the background (default ${SHELL_HOLD_DEFAULT_MS}). Usually omit; for a long finite command needed next, set up to ${SHELL_HOLD_MAX_MS}.`,
         },
         background: {
           type: 'boolean',
@@ -196,7 +254,7 @@ export const BUILTIN_TOOLS = [
       openWorldHint: false,
     },
     description:
-      'Manage shell tasks. Completion is delivered automatically; wait only when you need the result now, never poll with read. wait returns when the task finishes, or when new user input or any task notification arrives (the task keeps running). read/wait return new output, prioritizing the tail on completion. output:tail re-reads recent output without advancing the cursor; use read on the log path for omitted content.',
+      'Manage shell tasks. Completion is delivered automatically; wait only when you need the result now, never poll with read. wait returns when the task finishes, or when new user input or any task notification arrives (the task keeps running). read/wait return new output, prioritizing the tail on completion. Use read on the log path for omitted content.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -209,13 +267,13 @@ export const BUILTIN_TOOLS = [
         timeout_ms: {
           type: 'integer',
           minimum: 0,
-          description: `Wait ceiling in ms; returns on completion, new user input or a task notification, else current output at the ceiling. Default ${TASK_WAIT_TIMEOUT_DEFAULT_MS} (agents ${AGENT_TASK_WAIT_DEFAULT_MS}); clamped to ${TASK_WAIT_TIMEOUT_MIN_MS}-${TASK_WAIT_TIMEOUT_MAX_MS}.`,
+          description: taskTimeoutDescription(TASK_WAIT_TIMEOUT_DEFAULT_MS),
         },
         output: {
           type: 'string',
           enum: ['new', 'tail'],
           description:
-            'read/wait only. Default new; tail replays recent output after an interruption or context loss. Up to 8 KiB per stream while running, 12 KiB on completion or replay; original logs are preserved.',
+            'read/wait only. Default new; tail re-reads recent output without advancing the cursor, after an interruption or context loss. Up to 8 KiB per stream while running, 12 KiB on completion or replay; original logs are preserved.',
         },
       },
       required: ['action'],
@@ -266,7 +324,7 @@ export const BUILTIN_TOOLS = [
           description:
             'Requested results; default 250; 0 unlimited. Context output caps at 40 blocks; continue via the returned offset.',
         },
-        offset: { type: 'integer', minimum: 0, description: 'Result offset.' },
+        offset: { type: 'integer', minimum: 0 },
         context: {
           type: 'integer',
           minimum: 0,
@@ -298,7 +356,7 @@ export const BUILTIN_TOOLS = [
       compressible: true,
     },
     description:
-      'Wildcard file-path lookup under a known directory; directories never match. Omit path for the current Project; no preliminary listing. Unknown base: find first with a known path fragment. Gitignored paths need include_noise:true.',
+      'Wildcard file-path lookup under a known directory; directories never match. No preliminary listing. Unknown base: find first with a known path fragment.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -316,7 +374,7 @@ export const BUILTIN_TOOLS = [
           description: 'mtime default (newest first); natural = raw walk order, cheaper on huge trees.',
         },
         limit: { type: 'integer', minimum: 0, description: 'Max entries; default 100; 0 unlimited.' },
-        offset: { type: 'integer', minimum: 0, description: 'Entry offset.' },
+        offset: { type: 'integer', minimum: 0 },
         include_noise: {
           type: 'boolean',
           description: 'Also search gitignored trees.',
@@ -346,7 +404,7 @@ export const BUILTIN_TOOLS = [
           type: 'string',
           minLength: 1,
           pattern: '\\S',
-          description: 'Non-empty filename/path fragment; space-separated fragments AND-match within one path.',
+          description: 'Filename/path fragment; space-separated fragments AND-match within one path.',
         },
         path: { type: 'string', description: 'Base directory; omit for the current Project.' },
         limit: { type: 'integer', minimum: 0, description: 'Max paths; default 25; 0 unlimited.' },
@@ -387,10 +445,36 @@ export const BUILTIN_TOOLS = [
           maximum: 100,
           description: 'Max entries; default 100; 0 = no page cap (absolute cap still applies).',
         },
-        offset: { type: 'integer', minimum: 0, description: 'Entry offset.' },
+        offset: { type: 'integer', minimum: 0 },
       },
-      required: [],
       additionalProperties: false,
     },
   },
 ];
+
+// What a delegated agent's session sees of the tools whose text differs from
+// the Lead's: git (worktree operations are Lead-only) and task (the agent wait
+// default). Keyed by the shared definition, so a rebuilt list binds once.
+const _taskTool = BUILTIN_TOOLS.find((tool) => tool.name === 'task');
+const _agentTaskTool = {
+  ..._taskTool,
+  inputSchema: {
+    ..._taskTool.inputSchema,
+    properties: {
+      ..._taskTool.inputSchema.properties,
+      timeout_ms: {
+        ..._taskTool.inputSchema.properties.timeout_ms,
+        description: taskTimeoutDescription(AGENT_TASK_WAIT_DEFAULT_MS),
+      },
+    },
+  },
+};
+const _agentToolVariants = new Map([
+  [GIT_TOOL_DEF, GIT_AGENT_TOOL_DEF],
+  [_taskTool, _agentTaskTool],
+]);
+
+/** The agent-session variant of `tool`, or `tool` itself when it has none. */
+export function bindAgentOwner(tool) {
+  return _agentToolVariants.get(tool) ?? tool;
+}

package/src/runtime/agent/orchestrator/tools/builtin/cache-layers.mjs

@@ -324,7 +324,13 @@ export function rawContentCacheSet(fullPath, stat, rawBuf, now = Date.now()) {
   if (!canPublishReadCache(fullPath)) return;
   if (!fullPath || !Buffer.isBuffer(rawBuf)) return;
   const version = fileVersion(stat);
-  if (!version || !canCacheReadFile(version) || rawBuf.length !== version.size || rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES) return;
+  if (
+    !version ||
+    !canCacheReadFile(version) ||
+    rawBuf.length !== version.size ||
+    rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES
+  )
+    return;
   const key = canonicalCachePath(fullPath);
   rawContentCacheDelete(key);
   RAW_CONTENT_CACHE.set(key, {