mixdog 1.3.5 → 1.4.0

package/src/runtime/agent/orchestrator/session/thinking-binding.mjs

@@ -0,0 +1,108 @@
+// Thinking replay is bound to the request prefix that produced it.
+//
+// An Anthropic thinking block's signature records the conversation prefix it
+// was generated under: the top-level system prompt, the tool set, and every
+// earlier message. A request whose system or tools changed since then carries
+// blocks the API drops before the model sees them (unbilled, so the provider's
+// count no longer includes them) or, where the check is enforced, refuses with
+// a 400. The drop also takes every LATER thinking block, so a transcript that
+// keeps the stale blocks loses the reasoning of every turn that follows them.
+//
+// Where the runtime itself changes that prefix — a heir carrying a conversation
+// into a prompt built for it, a folded or migrated prompt — the stored thinking
+// can never be replayed again. It is stripped once, at that boundary, the
+// documented recovery: each turn keeps its text and tool calls, and the next
+// turns' thinking binds to the new prefix and is replayed normally. Leaving it
+// in place also kept charging every signature to the local context estimate,
+// which then ran far above what the provider actually counted.
+//
+// One round is never stripped: a trailing tool round whose next request still
+// continues it (the latest assistant turn called tools and no final reply
+// followed — an idle session can stop there after a provider error). Its
+// latest assistant turn must go back starting with its thinking, so removing
+// that thinking is a refused request too. When the prefix changed under such a
+// round, the round is ended explicitly instead (`rebindToChangedPrefix`).
+import { contextAckMessage } from './compact/user-message-kind.mjs';
+import { collectAssistantToolCallIds } from './context-tool-pairs.mjs';
+import { assistantMessageWithoutThinkingReplay } from './thinking-replay-recovery.mjs';
+
+/** The runtime turn that ends an open tool round: a context ack, so the
+ *  transcript never shows it and Compact never reads it as a reply. */
+function toolRoundClosure() {
+  const ack = contextAckMessage();
+  return { ...ack, meta: { ...ack.meta, synthetic: true } };
+}
+
+const callsTools = (message) =>
+  collectAssistantToolCallIds(message).length > 0 ||
+  (Array.isArray(message?.providerReplay?.items) &&
+    message.providerReplay.items.some((item) => item?.type === 'tool_use'));
+
+/**
+ * Index where the trailing open tool round starts (the assistant/tool run that
+ * ends with the latest assistant turn's results; later user or notification
+ * input may follow), or -1 when the latest assistant turn is a final reply.
+ * Read from the persisted transcript alone.
+ */
+export function openToolRoundStart(messages) {
+  if (!Array.isArray(messages)) return -1;
+  const latest = messages.findLastIndex((message) => message?.role === 'assistant');
+  if (latest < 0 || !callsTools(messages[latest])) return -1;
+  let start = latest;
+  while (start > 0 && ['assistant', 'tool'].includes(messages[start - 1]?.role)) start -= 1;
+  return start;
+}
+
+/** What the next request sends ahead of the conversation: the system blocks and tools. */
+export function requestPrefixIdentity(session) {
+  return JSON.stringify([
+    (Array.isArray(session?.messages) ? session.messages : [])
+      .filter((message) => message?.role === 'system')
+      .map((message) => message.content),
+    session?.tools,
+  ]);
+}
+
+/**
+ * `messages` without Anthropic thinking replay (thinking / redacted_thinking
+ * blocks, wherever an assistant turn stores them); text and tool calls stay.
+ * The trailing open tool round keeps its thinking: everything stripped is a
+ * leading run, which leaves the round's own blocks valid.
+ * Replaces changed messages, never mutates; the same array when none changed.
+ */
+export function withoutThinkingReplay(messages) {
+  if (!Array.isArray(messages)) return messages;
+  const open = openToolRoundStart(messages);
+  const end = open < 0 ? messages.length : open;
+  let changed = false;
+  const out = messages.map((message, index) => {
+    const stripped = index < end ? assistantMessageWithoutThinkingReplay(message) : null;
+    if (!stripped) return message;
+    changed = true;
+    return stripped;
+  });
+  return changed ? out : messages;
+}
+
+/**
+ * `messages` for a request prefix that changed under them: no thinking replay
+ * at all. An open tool round that carries thinking can neither keep it (bound
+ * to the old prefix) nor lose it (its continuation must start with it), so it
+ * is ended first by a runtime turn right after its last tool result, ahead of
+ * any later input (a task notification stays pending after it); the next
+ * request then starts a new turn. Never mutates; the same array when nothing
+ * changed.
+ */
+export function rebindToChangedPrefix(messages) {
+  if (!Array.isArray(messages)) return messages;
+  const open = openToolRoundStart(messages);
+  if (open < 0) return withoutThinkingReplay(messages);
+  let end = messages.findLastIndex((message) => message?.role === 'assistant') + 1;
+  while (messages[end]?.role === 'tool') end += 1;
+  const roundThinks = messages
+    .slice(open, end)
+    .some((message) => assistantMessageWithoutThinkingReplay(message) !== null);
+  return withoutThinkingReplay(
+    roundThinks ? [...messages.slice(0, end), toolRoundClosure(), ...messages.slice(end)] : messages
+  );
+}

package/src/runtime/agent/orchestrator/session/tool-batch/pre-dispatch.mjs

@@ -103,8 +103,8 @@ function crossTurnStub(batch, call, ctSig) {
 // (which spans ONE assistant turn): when the model re-issues an IDENTICAL
 // normalized call that has already failed repeatFailLimit times in a row
 // across iterations, stop re-executing — the result will not change, and
-// each retry burns a full LLM round-trip with no iteration cap to end it. The
-// call stays unresolved; the guard only skips re-execution.
+// each retry burns a full LLM round-trip. The call stays unresolved; the
+// guard only skips re-execution.
 function repeatFailureSkip(batch, call, sigs) {
   const { sessionRef, repeatFailLimit } = batch;
   const rfg = sessionRef?._repeatFailGuard;

package/src/runtime/agent/orchestrator/session/tool-batch/record-outcome.mjs

@@ -4,6 +4,7 @@
 // consumes.
 import { resolve as resolvePath, isAbsolute } from 'node:path';
 import { normalizeToolEnvelope } from '../tool-envelope.mjs';
+import { effectiveToolCwd } from '../../tools/builtin/bash-tool/shell-cwd.mjs';
 import {
   invalidatePathForSession,
   clearReadDedupSession,
@@ -85,7 +86,7 @@ async function fireToolFailureHook(batch, call, result) {
     await hook({
       name: call.name,
       args: call.arguments,
-      cwd: batch.cwd,
+      cwd: effectiveToolCwd(call.name, call.arguments, batch.cwd),
       sessionId: batch.sessionId,
       toolCallId: call.id,
       result: typeof result === 'string' ? result : String(result ?? ''),

package/src/runtime/agent/orchestrator/session/transcript-restore/restore.mjs

@@ -64,6 +64,20 @@ function restoredFailureFields(value) {
   };
 }
 
+/** Whether `message` was posted into the thread outside any turn: it says so
+ *  (`transcript.posted`, stamped by agent-home-delivery.mjs), or it is a row
+ *  stored before that marker existed. Those carry the id agent-home-delivery
+ *  mints for every posted row (`messageIdOf`: `routine_<runId>`) and are not
+ *  prompts: an agent's own message (assistant role) or a result/held-request
+ *  notice (stored under the user role, but not a prompt). The `routine_` scheme
+ *  alone is not enough: routine-home-turn.mjs:144 gives the prompt of a routine
+ *  fire (user role) the same prefix, and that prompt opens a real turn. */
+function isPostedMessage(message, transcript) {
+  if (transcript.posted === true) return true;
+  if (typeof transcript.messageId !== 'string' || !transcript.messageId.startsWith('routine_')) return false;
+  return message?.role !== 'user' || isRoutineResultMessage(message) || isHeldRequestMessage(message);
+}
+
 function restoredTranscriptMetadata(message) {
   const value = message?.meta?.transcript;
   if (!value || typeof value !== 'object') return {};
@@ -87,6 +101,8 @@ function restoredTranscriptMetadata(message) {
     // messages back to these rows.
     ...(typeof value.messageId === 'string' && value.messageId ? { messageId: value.messageId } : {}),
     ...(Number.isFinite(Number(value.at)) ? { at: Number(value.at) } : {}),
+    // Delivered into the thread outside any turn (agent-home-delivery.mjs).
+    ...(isPostedMessage(message, value) ? { posted: true } : {}),
     ...transcriptRouteMetadataFields(value),
     ...(typeof value.sender === 'string' && value.sender ? { sender: value.sender } : {}),
     ...(typeof value.device === 'string' && value.device ? { device: value.device } : {}),
@@ -400,7 +416,7 @@ function restoredUserTranscriptItems(message, nextId, userText) {
   // A schedule's result in its owner's home thread: a notice row.
   // A held request of an unattended run (human-gate/held-message.mjs) likewise.
   if (isRoutineResultMessage(message) || isHeldRequestMessage(message)) {
-    const { messageId, at } = restoredTranscriptMetadata(message);
+    const { messageId, at, posted } = restoredTranscriptMetadata(message);
     return [
       {
         kind: 'notice',
@@ -408,6 +424,7 @@ function restoredUserTranscriptItems(message, nextId, userText) {
         ...(isHeldRequestMessage(message) ? heldRequestNotice(message) : routineResultNotice(message)),
         ...(messageId ? { messageId } : {}),
         ...(at ? { at } : {}),
+        ...(posted ? { posted } : {}),
       },
     ];
   }

package/src/runtime/agent/orchestrator/session/transcript-restore/tool-result-status.mjs

@@ -13,6 +13,7 @@ import { formatAggregateDetail, summarizeToolResult, toolLoadingTargets } from '
 import { normalizeToolName } from '../../../../shared/tool-primitives.mjs';
 import { gitResultError, gitResultExitCode } from '../../../../shared/tool-card-model/git-result.mjs';
 import { readRowsForDisplay } from '../../../../shared/read-row-numbers.mjs';
+import { visualizeOwnerMetaSessionId } from '../../../../visualize-bridge/tool-meta.mjs';
 
 const CANCELLED_RESULT_STATUS_LINE = '[status: cancelled]';
 
@@ -292,15 +293,16 @@ export function assignUiDiffFromMessage(target, source) {
 }
 
 /** Structured side channel a tool result may carry next to its text (the
- * Computer Use capability refusal): a stable code plus the capability names.
- * Anything else is dropped so stored history stays small and predictable. */
-export function toolMetaFromMessage(source) {
+ * Computer Use capability refusal): a stable code plus the capability names,
+ * and the owner conversation of a `visualize` call run for another session's
+ * work (visualize-bridge/tool-meta.mjs). Anything else is dropped so stored
+ * history stays small and predictable. */
+function toolMetaFromMessage(source) {
   const meta = source?.toolMeta ?? source?.content?.toolMeta;
   if (!meta || typeof meta !== 'object' || typeof meta.code !== 'string' || !meta.code) return undefined;
-  const missing = Array.isArray(meta.missing)
-    ? meta.missing.filter((name) => typeof name === 'string' && name)
-    : [];
-  return { code: meta.code, missing };
+  const missing = Array.isArray(meta.missing) ? meta.missing.filter((name) => typeof name === 'string' && name) : [];
+  const ownerSessionId = visualizeOwnerMetaSessionId(meta.ownerSessionId);
+  return { code: meta.code, missing, ...(ownerSessionId ? { ownerSessionId } : {}) };
 }
 
 export function toolMetaPatchFromMessage(source) {

package/src/runtime/agent/orchestrator/session/transcript-restore/tool-result-text.mjs

@@ -132,8 +132,8 @@ export function toolGroupedDisplayFallback(resultText, text, rawText) {
   return resultText;
 }
 
-export function toolErrorDisplay(value, surface = 'tool') {
-  const text = presentErrorText(value, { surface });
+export function toolErrorDisplay(value, surface = 'tool', { providerLabel } = {}) {
+  const text = presentErrorText(value, { surface, providerLabel });
   if (
     /^(?:Search failed|Fetch failed|No first response|No progress|Cancelled|The .+ went stale|(?:Web search agent|Agent|Tool|Request) (?:stopped|was cancelled))/i.test(
       text

package/src/runtime/agent/orchestrator/session/turn-failure.mjs

@@ -3,6 +3,7 @@
 // session shows the same failure, reason and quota stop as the live one.
 import { errText } from '../../../shared/err-text.mjs';
 import { safeErrorDetails } from '../../../shared/error-presentation.mjs';
+import { providerDisplayName } from '../../../shared/provider-display-name.mjs';
 import { providerErrorKind } from '../providers/provider-error-kind.mjs';
 import { toolErrorDisplay } from './transcript-restore/tool-result-text.mjs';
 
@@ -39,7 +40,10 @@ export function turnFailureRecord(error, route = {}) {
     providerKind,
     errorKind,
     quota,
-    detail: toolErrorDisplay(error, 'turn').replace(/^Error:\s*/i, ''),
+    // The provider is named from the turn's own route, never from the error.
+    detail: toolErrorDisplay(error, 'turn', {
+      providerLabel: route.provider ? providerDisplayName(route.provider) : undefined,
+    }).replace(/^Error:\s*/i, ''),
     errorDetails: safeErrorDetails(errText(error)),
   };
 }

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

@@ -780,10 +780,13 @@ function guardRead(a) {
 }
 
 function guardShell(a) {
-  const allowed = new Set(['command', 'timeout_ms', 'wait_ms', 'background']);
+  const allowed = new Set(['command', 'cwd', 'timeout_ms', 'wait_ms', 'background']);
   const unsupported = Object.keys(a).find((key) => !allowed.has(key));
   if (unsupported) {
-    return `Error: shell arg "${unsupported}" is unsupported; use only command, timeout_ms, wait_ms, and background`;
+    return `Error: shell arg "${unsupported}" is unsupported; use only command, cwd, timeout_ms, wait_ms, and background`;
+  }
+  if (hasOwn(a, 'cwd') && (typeof a.cwd !== 'string' || a.cwd.trim().length === 0)) {
+    return `Error: shell arg "cwd" must be a non-empty string (got ${describeType(a.cwd)})`;
   }
   if (hasOwn(a, 'background') && typeof a.background !== 'boolean') {
     return `Error: shell arg "background" must be a boolean (got ${describeType(a.background)})`;

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

@@ -52,7 +52,17 @@ function registerPromotedTask({ result, command, cwd, options, startedAtMs }) {
 // running, now promoted as a tracked shell-job. Surface the task_id + partial
 // output for manual task control instead of keeping the tool call open until
 // the hard timeout.
-export function renderBackgroundedResult({ result, command, cwd, options, startedAtMs, teePlan, stdout, stderr }) {
+export function renderBackgroundedResult({
+  result,
+  command,
+  cwd,
+  options,
+  startedAtMs,
+  teePlan,
+  stdout,
+  stderr,
+  notes = '',
+}) {
   let task = null;
   if (result.jobId) {
     task = registerPromotedTask({ result, command, cwd, options, startedAtMs });
@@ -91,6 +101,7 @@ export function renderBackgroundedResult({ result, command, cwd, options, starte
       )
     : renderBackgroundPartialOutput(stdout, stderr);
   const lines = _backgroundResultLines({
+    warning: notes,
     taskBlock,
     message: result.backgroundMessage || DEFAULT_BACKGROUND_MESSAGE,
     partialOutput,

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.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 });
@@ -106,6 +125,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 +167,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();