mixdog 0.9.143 → 0.9.144

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.143",
+  "version": "0.9.144",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/src/lib/rules-builder.cjs

@@ -202,12 +202,32 @@ function stripFrontmatter(markdown) {
   return String(markdown || '').replace(/^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, '').trim();
 }
 
-const WEB_SEARCH_ROUTE_RE = /^[ \t]*current or external information discovery→`web_search`;[ \t]*\r?\n?/gm;
-const WEB_FETCH_ROUTE_RE = /^[ \t]*page or documentation body retrieval from a known URL→`web_fetch`\.[ \t]*\r?\n?/gm;
-const RECALL_ROUTE_RE = /^-[ \t]*past facts recorded in prior work or sessions→`recall`[ \t]*\r?\n[ \t]*\(stored history only, never current local state\)\.[ \t]*\r?\n?/gm;
-const MEMORY_ROUTE_RE = /^-[ \t]*Durable memory creation or update→`memory`; store a compact English[ \t]*\r?\n[ \t]*statement\.[\s\S]*$/m;
-const EMPTY_RESEARCH_RE = /^# Research[ \t]*\r?\n(?:[ \t]*\r?\n)*-[ \t]*Research routes:[ \t]*\r?\n?/gm;
-const EMPTY_MEMORY_RE = /^# Memory[ \t]*\r?\n(?:[ \t]*\r?\n)*/gm;
+// Tool dependency is declared as metadata, not matched against prose. A
+// `<!-- tools: a, b -->` marker binds the block that follows it: the block
+// survives while any listed tool is on the session surface and disappears
+// once every one of them is omitted. Markers never reach the model.
+const TOOL_MARKER_RE = /^[ \t]*<!--[ \t]*tools:[ \t]*([^>]*?)[ \t]*-->[ \t]*$/;
+
+function markerTools(line) {
+  const match = TOOL_MARKER_RE.exec(String(line ?? ''));
+  if (!match) return null;
+  return match[1].split(',').map((name) => name.trim().toLowerCase()).filter(Boolean);
+}
+
+// A marked block runs from the line after the marker through every deeper
+// indented continuation line, ending at the next marker, blank line, or a
+// line at the same or shallower indent.
+function markedBlockEnd(lines, start) {
+  const indent = lines[start].search(/\S/);
+  let end = start + 1;
+  while (end < lines.length) {
+    const line = lines[end];
+    if (!line.trim() || markerTools(line)) break;
+    if (line.search(/\S/) <= indent) break;
+    end += 1;
+  }
+  return end;
+}
 
 function omitKeySet(omitTools) {
   return new Set((Array.isArray(omitTools) ? omitTools : []).map((name) => String(name || '').toLowerCase()).filter(Boolean));
@@ -216,16 +236,25 @@ function omitKeySet(omitTools) {
 /** Drop routing clauses for tools that are not on the session surface. */
 function omitToolRoutes(text, omitTools = []) {
   const deny = omitKeySet(omitTools);
-  let out = String(text || '');
-  if (deny.has('web_search')) out = out.replace(WEB_SEARCH_ROUTE_RE, '');
-  if (deny.has('web_fetch')) out = out.replace(WEB_FETCH_ROUTE_RE, '');
-  if (deny.has('recall')) out = out.replace(RECALL_ROUTE_RE, '');
-  if (deny.has('memory')) out = out.replace(MEMORY_ROUTE_RE, '');
-  if (deny.has('web_search') && deny.has('web_fetch')) {
-    out = out.replace(EMPTY_RESEARCH_RE, '');
+  const lines = String(text || '').split(/\r?\n/);
+  const kept = [];
+  let index = 0;
+  while (index < lines.length) {
+    const tools = markerTools(lines[index]);
+    if (!tools) {
+      kept.push(lines[index]);
+      index += 1;
+      continue;
+    }
+    index += 1;
+    if (index >= lines.length) break;
+    const end = markedBlockEnd(lines, index);
+    if (!tools.length || !tools.every((name) => deny.has(name))) {
+      kept.push(...lines.slice(index, end));
+    }
+    index = end;
   }
-  if (deny.has('recall') && deny.has('memory')) out = out.replace(EMPTY_MEMORY_RE, '');
-  return out.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n');
+  return kept.join('\n').replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
 }
 
 // Framing line under the style header: the block owns user-facing prose only,

package/src/rules/lead/lead-brief.md

@@ -1,13 +1,12 @@
 # Lead Brief
 
-- Minimum chars, maximum info: one-line fragments. Every role's `Task:` is
-  mandatory and lossless — build it from the original request and the official
-  spec/test acceptance criteria, preserving intent, required and forbidden
-  outcomes, completion/stop boundary, user-supplied exact targets, and exact
-  replacements/outputs. Never infer exactness from task name, file count, or
-  difficulty.
-- Omit role-known rules, repeated context/facts, and padding; split scope
-  without discarding requirements.
+- Every role's `Task:` is mandatory and lossless — build it from the original
+  request and the official spec/test acceptance criteria, preserving intent,
+  required and forbidden outcomes, completion/stop boundary, user-supplied
+  exact targets, and exact replacements/outputs.
+- Never infer exactness from task name, file count, or difficulty.
+- Minimum chars, maximum info: one-line fragments, no role-known rules, no
+  repeated context or facts, no padding.
 - Other fields are task-specific deltas — `Anchors:` (`file:line` plus a
   one-line conclusion, never log/code bodies), `Allow/Forbid:`, `Deliver:`
   (sets handoff shape/size); omit empty fields. State outcomes, not methods,

package/src/rules/shared/10-tool-workflow.md

@@ -1,20 +1,40 @@
 # Tool Workflow
 
-- Minimize tool turns through maximal useful parallelism: in each turn, issue
-  every necessary non-overlapping call whose inputs are already known.
-- Defer a call only when its inputs depend on an earlier result; never add
-  duplicate or irrelevant calls merely to increase fanout.
-- Apply one analysis to many targets as one parameterized call when supported,
-  not one call per target.
+- Investigate, build, and verify only what the requested outcome requires, at
+  the level it requires; trust internal and framework guarantees.
+- Minimize tool turns through maximal useful parallelism. Cost is counted in
+  rounds, not calls: a batch is one round, so a call-count saving never
+  justifies a worse-routed call. Plan the fewest evidence-complete dependent
+  rounds first, then the fewest calls within each round.
+- In each round, issue every necessary non-overlapping call whose inputs are
+  already known; defer a call only when its target or arguments require an
+  earlier result.
+- Route each remaining evidence facet once to its primary owner, preferring the
+  operation that directly returns the evidence needed for the next decision. A
+  summary, overview, or enumeration is not a prerequisite when that operation's
+  complete inputs are already known; if independently required, batch it with
+  the detailed operation.
+- Never duplicate a facet, widen retrieval speculatively, or cap fanout; apply
+  one analysis to many targets as one parameterized call when supported.
 1. Determine the required outcome and missing information; requirements are
    not evidence.
 2. If needed, gather only missing information through Research or Exploration;
    use Execution when the information can only be produced by running a program
-   or observing runtime state. Stop when it is already known or sufficiently
-   obtained.
+   or observing runtime state.
 3. Perform the required answer, edit, or execution in the fewest safe coherent
    calls.
 4. Verify only affected facets and essential invariants when required.
+- Known state — system guarantees, supplied facts, visible tool returns,
+  applied patches, and passed checks — is never re-found, re-derived, or
+  re-verified at any granularity: no re-query call, no confirmation subcommand
+  inside a shell command, no availability probe for what the operation itself
+  would report, no reopening a file to confirm an edit, no rerun of a passed
+  check.
+- Mine each returned result fully before opening the next round. A follow-up
+  is valid only for evidence a result omitted, invalidated, or newly made
+  necessary; an independently required call that no result created belonged in
+  the earlier batch.
+- Evidence that determines the answer, edit, or deliverable ends retrieval.
 - Treat failure as new evidence and repeat steps 1–4 only for affected facets.
   Report a blocker when no deterministic next action remains.
 - Use only named tools present in the current tool surface.

package/src/rules/shared/20-research.md

@@ -1,6 +1,10 @@
+<!-- tools: web_search, web_fetch -->
 # Research
 
+<!-- tools: web_search, web_fetch -->
 - Research routes:
+<!-- tools: web_search -->
   current or external information discovery→`web_search`;
+<!-- tools: web_fetch -->
   page or documentation body retrieval from a known URL→`web_fetch`.
 

package/src/rules/shared/30-exploration.md

@@ -2,43 +2,31 @@
 
 - Use read-only means for inspection; never mutate to clear an obstacle or
   unexpected state. Preserve evidence before a required mutation can destroy it.
-- Local Project exploration routes:
-  unknown file/directory location, paths only needed→`find`;
-  wildcard/recursive paths→`glob` (including known-root unknown descendants);
+- Ownership is exclusive: each evidence type has one owner, another tool's
+  ability to reach the same target is never an alternative route, and a
+  successful owner result closes that facet — only a different evidence type
+  routes elsewhere.
+- Route the missing evidence to its primary owner:
+  repository state, history, or diff→`git`;
+  exact symbol declaration, body, usage, or relation→`code_graph`;
+  literal, regex, or text location→`grep`;
+  known-file content, range, or image→`read`;
+  wildcard or recursive file paths→`glob`;
   known directory's immediate entries→`list`;
-  exact symbol, body, or relation→`code_graph`
-  (identifier declarations/usages→`code_graph`; literal values/strings→`grep`);
-  literal/regex pattern search within file contents→`grep`;
-  content or an anchored line range from a known file when pattern search is
-  insufficient or unnecessary→`read`.
-- Read-only tools — `find`, `glob`, `list`, `grep`, `code_graph`, `read` —
-  always batch safely in parallel.
-- Paths reachable by expanding an environment variable or the home directory
-  are resolved locations, not unknowns.
-- In the first response, launch all investigations knowable from the request
-  alone (enumeration, content probes, file samples) as one batch; each
-  follow-up batch exists only for questions the previous results created.
-- Batching never licenses a guessed `glob.path`
-  (unknown location → `find` first; omit path for the current Project).
+  unknown file or directory location→`find`.
+- Use a path locator only when the owner's required target is unknown. Paths
+  reachable by expanding an environment variable or the home directory are
+  resolved locations, not unknowns.
 - Enumerate sibling directories or same-kind files with one wildcard call
   (`glob`, or `read` with a glob for content sampling), never a
   directory-by-directory `list` walk or one `read` per file.
-- Before choosing an implementation, inspect only the nearest relevant code,
-  configuration, and established pattern needed to verify local conventions or
-  dependency availability.
-
-- Requirements define what must be true; evidence establishes what is true.
-  Never use one as the other. Treat supplied target locations as resolved;
-  access them directly without locator searches. Before deciding how to parse,
-  count, transform, or summarize files whose format has not been inspected,
-  inspect the original content itself. Within the current project, pass project-relative
-  paths and omit optional scopes equal to its root; explicit paths may be
-  outside cwd only for targets outside the project.
-- Do not re-read content already returned by any tool or reopen a successfully
-  edited file solely to confirm the edit. Read only missing context or content
-  invalidated by a reported failure, partial operation, or external change.
-- `code_graph references` supplies the declaration and scoped usages and ends
-  that facet; values/locations end at the context `grep` returns; `read` covers
-  only omitted lines or missing anchored ranges. Any visible returned span can
-  supply exact source context; do not fetch it again.
+- Treat supplied target locations as resolved; access them directly without
+  locator searches. Within the current project, pass project-relative paths and
+  omit optional scopes equal to its root; explicit paths may be outside cwd
+  only for targets outside the project.
+- Before deciding how to parse, count, transform, or summarize files whose
+  format has not been inspected, inspect the original content itself.
+- Returned declarations, bodies, usages, relations, and contextual spans from
+  any tool — not only `read` — are source context; `read` covers only omitted
+  lines or missing anchored ranges.
 

package/src/rules/shared/40-editing.md

@@ -1,11 +1,15 @@
 # Editing
 
+- A required new file is created directly: Add File is itself the atomic
+  absence check, so inspect only if it reports the target already exists.
 - Source: use exact current target text from any visible evidence, including
   user input, tool output, or an applied edit result; never reconstruct it from
   another file, a sample, or expectation.
 - Placement: with `edit`, use an exact unique target string, expanding exact
   surrounding text when needed; with `apply_patch`, use exact unchanged context
   and add a class/function locator when context alone is not unique.
+- Apply all determined changes in the fewest safe calls the active tool
+  supports; a file written in one call is written complete.
 - Batch scope: never split one file across concurrent edit calls. Group
   same-intent changes with exact context into coherent calls; issue disjoint
   calls together in one turn, and defer ambiguous or result-dependent changes.

package/src/rules/shared/50-execution.md

@@ -2,4 +2,5 @@
 
 - Evidence or artifacts available only through program execution, calculation,
   data transformation, generated output, or unsupported-format decoding→`shell`;
+  an already-open shell is never a routing reason.
 

package/src/rules/shared/60-verification.md

@@ -5,6 +5,15 @@
   invariants; use an umbrella suite only when the user explicitly requests it
   or a documented project or release process requires it.
 - Issue all independent checks in one turn.
+- Blocking checks cover only essential integrity, security, compatibility, and
+  buildability invariants. Treat mutable behavior, UX, exact text, snapshots,
+  and implementation shape as advisory specifications; update them when the
+  requested behavior changes instead of preserving obsolete behavior.
+- A check runs at the strictness the task requires; never raise a tool's own
+  severity beyond it.
 - If verification fails, collect all failures, leave Verification, complete all
   determinable fixes, then re-enter Verification for the resulting state.
+- A successful verification closes the task unless later changes affect it;
+  rerun a failed action only after its inputs or subject change, otherwise
+  report it unresolved.
 

package/src/rules/shared/70-delivery.md

@@ -2,5 +2,4 @@
 
 - Commit, push, release, and deployment happen only on the user's explicit
   request.
-- Repository state or history explicitly asked about, and every repository
-  mutation→`git`; never part of exploration batching.
+- Every repository mutation→`git`.

package/src/rules/shared/80-memory.md

@@ -1,11 +1,15 @@
+<!-- tools: recall, memory -->
 # Memory
 
+<!-- tools: recall -->
 - past facts recorded in prior work or sessions→`recall`
   (stored history only, never current local state).
+<!-- tools: memory -->
 - Durable memory creation or update→`memory`; store a compact English
   statement.
+<!-- tools: memory -->
 - Use judgment to decide whether a durable memory should be stored, whether
   user confirmation is needed, and which scope best fits the context.
+<!-- tools: memory -->
 - Omit `project_id` for the current Project, use `"common"` for shared memory,
-  or provide an explicit Project slug for another named Project. `*` is
-  read-only.
+  or an explicit Project slug for another named Project; `*` is read-only.

package/src/runtime/agent/orchestrator/providers/lib/grok-tool-schema.mjs

@@ -65,6 +65,26 @@ function firstExclusiveRequired(branches) {
     return [];
 }
 
+const ARRAY_DROP_NOTE = 'This provider accepts a single value here, not an array.';
+
+function describesArray(schema) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return false;
+    return schema.type === 'array' || (Array.isArray(schema.type) && schema.type.includes('array'));
+}
+
+// Flattening keeps one branch, so a description that still promises the dropped
+// shape would advertise more than the wire schema accepts. Project the loss
+// into the text the model actually reads.
+function projectDroppedBranches(schema, dropped) {
+    if (describesArray(schema) || !dropped.some(describesArray)) return schema;
+    const description = String(schema.description || '').trim();
+    if (description.includes(ARRAY_DROP_NOTE)) return schema;
+    return {
+        ...schema,
+        description: description ? `${description} ${ARRAY_DROP_NOTE}` : ARRAY_DROP_NOTE,
+    };
+}
+
 function normalizeGrokPropertySchema(schema) {
     if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema;
     const branches = [
@@ -75,7 +95,8 @@ function normalizeGrokPropertySchema(schema) {
         const first = branches.find(branch => branch && typeof branch === 'object' && !Array.isArray(branch));
         if (first) {
             const { anyOf: _anyOf, oneOf: _oneOf, ...siblings } = schema;
-            return normalizeGrokPropertySchema({ ...first, ...siblings });
+            const dropped = branches.filter(branch => branch !== first);
+            return normalizeGrokPropertySchema(projectDroppedBranches({ ...first, ...siblings }, dropped));
         }
     }
     if (!schema.properties || typeof schema.properties !== 'object') return schema;

package/src/runtime/agent/orchestrator/session/agent-loop.mjs

@@ -203,7 +203,13 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     };
     const sessionRef = opts.session || null;
     let _providerPrefixGuardState = sessionRef?._providerPrefixGuardState || null;
-    let _fixedProviderToolSurface = sessionRef?._providerToolSurfaceSnapshot || null;
+    // Provider tool snapshots are request-loop state, never durable session
+    // state. Older builds persisted this field, which let a resumed session
+    // keep advertising a retired schema even after session.tools was rebuilt.
+    if (sessionRef && Object.prototype.hasOwnProperty.call(sessionRef, '_providerToolSurfaceSnapshot')) {
+        delete sessionRef._providerToolSurfaceSnapshot;
+    }
+    let _fixedProviderToolSurface = null;
     const loopUsageMetricsEpoch = () => Number(sessionRef?.usageMetricsEpoch) || 0;
     const loopUsageMetricsTurnId = () => Number(sessionRef?.usageMetricsTurnId) || 0;
     // Sub-agent (worker/heavy-worker/reviewer/…) sessions
@@ -496,7 +502,6 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             });
             if (!_fixedProviderToolSurface) {
                 _fixedProviderToolSurface = _candidateSendTools;
-                if (sessionRef) sessionRef._providerToolSurfaceSnapshot = _fixedProviderToolSurface;
             }
             sendTools = _fixedProviderToolSurface;
             requestToolScope = {

package/src/runtime/agent/orchestrator/session/evidence-union.test.mjs

@@ -142,7 +142,7 @@ test('apply_patch, shell, and mutating git batches invalidate all earlier eviden
         ['apply_patch', {}],
         ['shell', {}],
         ['git', { command: 'git commit -m test' }],
-        ['git', { command: "git reflog delete 'HEAD@{1}'", confirm: true }],
+        ['git', { command: "git reflog delete 'HEAD@{1}'" }],
     ]) {
         const messages = [
             call('read_1', 'read', { file_path: 'src/a.mjs' }),

package/src/runtime/agent/orchestrator/session/image-strip-recovery.test.mjs

@@ -164,6 +164,67 @@ test('agent loop heals one rejected tail image and the next turn stays usable',
     assert.equal(nextCalls, 1);
 });
 
+test('agent loop keeps provider tool snapshots turn-local', async () => {
+    const oldTool = {
+        name: 'shell',
+        description: 'old schema',
+        inputSchema: { type: 'object', properties: { retired: { type: 'boolean' } } },
+    };
+    const currentTool = {
+        name: 'shell',
+        description: 'current schema',
+        inputSchema: { type: 'object', properties: { command: { type: 'string' } } },
+    };
+    const nextTool = {
+        name: 'shell',
+        description: 'next schema',
+        inputSchema: { type: 'object', properties: { command: { type: 'string' }, timeout_ms: { type: 'number' } } },
+    };
+    const sentToolDescriptions = [];
+    const provider = {
+        async send(_messages, _model, tools) {
+            sentToolDescriptions.push(tools?.[0]?.description);
+            return { content: 'done', toolCalls: [], stopReason: 'end_turn' };
+        },
+    };
+    const session = {
+        id: 'provider-tool-snapshot-lifetime-test',
+        owner: 'cli',
+        contextWindow: 200_000,
+        rawContextWindow: 200_000,
+        compaction: { auto: false },
+        _providerToolSurfaceSnapshot: [oldTool],
+    };
+    const messages = [
+        { role: 'system', content: 'system' },
+        { role: 'user', content: 'first turn' },
+    ];
+
+    await agentLoop(
+        provider,
+        messages,
+        'fake-model',
+        [currentTool],
+        null,
+        process.cwd(),
+        { session, sessionId: session.id },
+    );
+    assert.equal(Object.hasOwn(session, '_providerToolSurfaceSnapshot'), false);
+
+    messages.push({ role: 'user', content: 'next turn' });
+    await agentLoop(
+        provider,
+        messages,
+        'fake-model',
+        [nextTool],
+        null,
+        process.cwd(),
+        { session, sessionId: session.id },
+    );
+
+    assert.deepEqual(sentToolDescriptions, ['current schema', 'next schema']);
+});
+
 test('mid-stream xAI generation crash is retryable even as invalid_request_error', () => {
     const err = new Error('xAI Responses stream error: Internal error during token generation');
     err.providerWireError = true;

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

@@ -32,8 +32,14 @@ const GREP_CTX_HEAD_LIMIT_MAX = 40;
 
 // Unbounded (no offset/limit) plain full reads default to this window instead of
 // pulling the whole file; the read tool's ranged-read footer then hands the
-// caller the next offset to page with.
-const READ_GUARD_DEFAULT_LIMIT = 1000;
+// caller the next offset to page with. At 1000 a single default read returned
+// 51KB of an unread log; halving it capped the largest read at 20KB and the
+// callers paged on instead of re-reading (tool-budget bench, 20260821).
+// MIXDOG_READ_DEFAULT_LIMIT overrides for A/B runs.
+const READ_GUARD_DEFAULT_LIMIT = (() => {
+    const parsed = parseInt(process.env.MIXDOG_READ_DEFAULT_LIMIT ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 500;
+})();
 
 // Best-effort clamp notice channel: stash a one-line note on the args so a
 // surfacing consumer can echo it. Underscore-prefixed; ignored by executors.
@@ -660,10 +666,10 @@ function guardRead(a) {
 }
 
 function guardShell(a) {
-    const allowed = new Set(['command', 'timeout_ms', 'run_in_background', 'monitor_interval_ms']);
+    const allowed = new Set(['command', 'timeout_ms']);
     const unsupported = Object.keys(a).find((key) => !allowed.has(key));
     if (unsupported) {
-        return `Error: shell arg "${unsupported}" is unsupported; use only command, timeout_ms, run_in_background, and monitor_interval_ms`;
+        return `Error: shell arg "${unsupported}" is unsupported; use only command and timeout_ms`;
     }
     if (!hasOwn(a, 'command')) {
         return 'Error: shell requires "command"';
@@ -677,12 +683,6 @@ function guardShell(a) {
     if (hasOwn(a, 'timeout_ms') && (typeof a.timeout_ms !== 'number' || !Number.isFinite(a.timeout_ms) || a.timeout_ms < 0)) {
         return `Error: shell arg "timeout_ms" must be a non-negative number (got ${describeType(a.timeout_ms)})`;
     }
-    if (hasOwn(a, 'run_in_background') && typeof a.run_in_background !== 'boolean') {
-        return `Error: shell arg "run_in_background" must be a boolean (got ${describeType(a.run_in_background)})`;
-    }
-    if (hasOwn(a, 'monitor_interval_ms') && !isValidShellMonitorIntervalMs(a.monitor_interval_ms)) {
-        return `Error: shell arg "monitor_interval_ms" must be 0 or an integer from ${SHELL_MONITOR_INTERVAL_MIN_MS} to ${SHELL_MONITOR_INTERVAL_MAX_MS} ms`;
-    }
     return null;
 }
 

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

@@ -62,14 +62,12 @@ import {
     SHELL_RUNTIME_CANDIDATES,
 } from './runtime-capabilities.mjs';
 import { planDirectExeSpawn } from './shell-direct-exe.mjs';
-import { resolveShellMonitorIntervalMs } from './shell-monitor.mjs';
 
 // Commands start in the foreground. Only work still running after the
-// 15 s coordination budget is promoted to a tracked background task.
-// Raised from 10 s (2026-08-15): repo verification units (node --test +
-// tool-smoke) cluster at 10.7-11.2 s, so every routine check crossed the
-// budget by a hair and cost a notification round-trip.
-export const DEFAULT_SHELL_AUTO_BACKGROUND_MS = 15_000;
+// 10 s coordination budget is promoted to a tracked background task.
+// Short commands therefore complete in the original tool turn, while longer
+// work returns partial output plus task_id and finishes by notification.
+export const DEFAULT_SHELL_AUTO_BACKGROUND_MS = 10_000;
 
 // Post-exec drift detection. After a foreground shell command, compare the
 // live mtime+size of files mixdog has already read this session against their
@@ -470,11 +468,6 @@ export async function executeBashTool(args, workDir, options = {}) {
     const _bgTasksDisabled = /^(1|true|yes|on)$/i.test(
         String(process.env.MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS || '').trim(),
     );
-    const runInBackground = args.run_in_background === true;
-    const monitorIntervalMs = resolveShellMonitorIntervalMs(args.monitor_interval_ms);
-    if (runInBackground && _bgTasksDisabled) {
-        return formatShellToolFailure('background tasks are disabled for this process');
-    }
 
     let shellEffects;
     let combinedBashAbort = null;
@@ -485,7 +478,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     }
     // timeout_ms is a caller-requested HARD total deadline, not a foreground
     // wait budget. Omitted/0 means no deadline: the command starts foreground,
-    // then the 15 s coordination budget promotes it without shortening its
+    // then the 10 s coordination budget promotes it without shortening its
     // lifetime. This matches the public schema and avoids accidental kills
     // caused by callers guessing how long a build might take.
     const _envMaxTimeout = parseInt(process.env.BASH_MAX_TIMEOUT_MS ?? '', 10);
@@ -528,9 +521,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     const backgroundMaxMs = Number.isFinite(_bgMaxEnvMs) && _bgMaxEnvMs > 0
         ? Math.min(Math.floor(_bgMaxEnvMs), TIMER_MAX_MS)
         : 0;
-    // A run_in_background start never holds the caller, so the cap IS its
-    // deadline; there is no foreground window to carve out of it first.
-    const execTimeoutMs = runInBackground && !hasExplicitTimeout ? backgroundMaxMs : timeout;
+    const execTimeoutMs = timeout;
     // A caller deadline at or below the foreground window has no remaining
     // budget to transfer. Let execShellCommand enforce that timeout instead of
     // adopting the child with timeoutMs=0, which means unlimited to shell-jobs.
@@ -539,7 +530,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     const mergeStderr = true;
     // Main-agent blocking budget. A timeout is the command's total deadline,
     // not permission to hold the conversation open for that whole duration:
-    // after 15 s a still-running command becomes a tracked background task and
+    // after 10 s a still-running command becomes a tracked background task and
     // completion is pushed to the owner. Explicit timeouts keep their remaining
     // deadline after promotion.
     // MIXDOG_SHELL_AUTO_BACKGROUND_MS overrides; an explicit 0 disables.
@@ -623,7 +614,6 @@ export async function executeBashTool(args, workDir, options = {}) {
             timeoutMs: execTimeoutMs,
             abortSignal: combinedBashAbort.signal,
             autoBackgroundMs,
-            startInBackground: runInBackground,
             // On a foreground timeout, promote the still-running child to a
             // tracked background job only when an explicit deadline has
             // remaining budget; omitted deadlines may stay unlimited.
@@ -678,7 +668,7 @@ export async function executeBashTool(args, workDir, options = {}) {
                             stderr: (!mergeStderr && result.stderrPath) ? normalizeOutputPath(result.stderrPath) : null,
                             cwd: bashWorkDir,
                             timeoutMs: result.backgroundTimeoutMs || 0,
-                            monitor_interval_ms: monitorIntervalMs,
+                            monitor_interval_ms: 0,
                         },
                         resultType: 'shell_task_result',
                         cancel: () => killShellJob(result.jobId),
@@ -690,7 +680,7 @@ export async function executeBashTool(args, workDir, options = {}) {
                         callerSessionId: options?.callerSessionId || options?.sessionId,
                         routingSessionId: options?.routingSessionId || options?.sessionId,
                         clientHostPid: options?.clientHostPid,
-                    }, { monitorIntervalMs });
+                    });
                 } catch { /* best effort */ }
             }
             const partialOutput = renderBackgroundPartialOutput(

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

@@ -1,15 +1,12 @@
 // --- Tool definitions for external models ---
 //
 // CANONICAL SOURCE for built-in tool schemas and annotations (compressible,
-// readOnlyHint, destructiveHint, etc.). Descriptions carry the tool CONTRACT
-// only (behavior + argument shapes); usage policy lives in rules/shared/*.md.
+// readOnlyHint, destructiveHint, etc.). A description carries the tool's
+// 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 {
-    SHELL_MONITOR_INTERVAL_DEFAULT_MS,
-    SHELL_MONITOR_INTERVAL_MAX_MS,
-    SHELL_MONITOR_INTERVAL_MIN_MS,
-} from './shell-monitor.mjs';
+import { SHELL_MONITOR_INTERVAL_MAX_MS } from './shell-monitor.mjs';
 const _shellSyntaxCheat =
     process.platform === 'win32'
         ? ' PowerShell: use ; between independent commands; use if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } between dependent commands; single-quote inline scripts, avoid nested double quotes; /c/→C:\\; $PID is reserved.'
@@ -17,12 +14,9 @@ const _shellSyntaxCheat =
 // Keep the routing map short and adjacent to the shell's primary description.
 // PowerShell aliases appear only on win32.
 const _shellToolRouting = process.platform === 'win32'
-    ? 'Use read, NOT cat/Get-Content/head/tail; list, NOT ls/dir; find/glob, NOT find; grep, NOT grep/rg/Select-String; edit/apply_patch, NOT sed/awk/heredocs/echo/Set-Content.'
-    : 'Use read, NOT cat/head/tail; list, NOT ls; find/glob, NOT find; grep, NOT grep/rg; edit/apply_patch, NOT sed/awk/heredocs/echo.';
-// When background tasks are disabled for this process, drop the
-// run_in_background field from the schema entirely so the model cannot burn a
-// failure turn attempting it. Mirrors bash-tool's runtime guard, which stays
-// as defense in depth. Process-stable env, evaluated once at module load.
+    ? 'Use read, NOT cat/Get-Content/head/tail; list, NOT ls/dir; find/glob, NOT find; grep, NOT grep/rg/Select-String; edit/apply_patch, NOT sed/awk/echo/Set-Content or a file-writing heredoc.'
+    : 'Use read, NOT cat/head/tail; list, NOT ls; find/glob, NOT find; grep, NOT grep/rg; edit/apply_patch, NOT sed/awk/echo or a file-writing heredoc.';
+// Process-stable switch used to describe foreground-only execution accurately.
 const _shellBackgroundDisabled = /^(1|true|yes|on)$/i.test(
     String(process.env.MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS || '').trim(),
 );
@@ -32,12 +26,12 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Read',
         annotations: { title: 'Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges. Images render for viewing; not directories. Replaces cat/head/tail.',
+        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges, bounded to the narrowest range that answers the question. Spans another tool already returned are source context; read only what they omit. Images render for viewing; not directories. Replaces cat/head/tail.',
         inputSchema: {
             type: 'object',
             properties: {
                 file_path: {
-                    type: 'string',                    description: 'Known file path as plain text; not a JSON array or annotated path. A glob (e.g. "logs/*.log") fans out to per-file results (cap 10, newest first); literal-named files win over expansion.',
+                    type: 'string',                    description: 'Known file path as plain text. A glob (e.g. "logs/*.log") fans out to per-file results (cap 10, newest first); literal-named files win over expansion.',
                 },
                 offset: {
                     type: 'integer',
@@ -47,7 +41,7 @@ export const BUILTIN_TOOLS = [
                 limit: {
                     type: 'integer',
                     minimum: 1,
-                    description: 'Maximum line count as a bare integer; default 1000.',
+                    description: 'Maximum line count as a bare integer; default 500.',
                 },
             },
             required: ['file_path'],
@@ -58,7 +52,7 @@ export const BUILTIN_TOOLS = [
         name: 'edit',
         title: 'Edit',
         annotations: { title: 'Edit', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false, compressible: false, compressibleLossless: true },
-        description: 'Replace exact text in one file. old_string must match once unless replace_all is true. Empty old_string creates a missing file or fills an empty file; it never overwrites a non-empty file.',
+        description: 'Replace exact text in one file. Use exact text already in context; never re-open the file to build old_string or to verify a successful edit. old_string must match once unless replace_all is true. Empty old_string creates a missing file or fills an empty file; it never overwrites a non-empty file.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -87,7 +81,7 @@ export const BUILTIN_TOOLS = [
         name: 'shell',
         title: 'Shell',
         annotations: { title: 'Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run programs, runtime/state operations, calculations, transformations, file generation, and unsupported-format inspection. Avoid file operations covered by dedicated tools unless explicitly instructed or after verifying that a dedicated tool cannot do the job. ${_shellToolRouting} ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : 'Commands use a 15s foreground window by default—not a timeout. Still-running work continues as a tracked task_id and completes by notification. Periodic monitoring is off by default; set monitor_interval_ms to 300000 (5m) or longer. Use run_in_background for known long-running commands or intentional servers/watchers, task monitor to change or disable monitoring, task read for an extra current snapshot, and never poll in a loop.'}`,
+        description: `Run programs, runtime/state operations, calculations, transformations, file generation, and unsupported-format inspection. ${_shellToolRouting} Avoid file operations covered by dedicated tools unless explicitly instructed or after verifying that a dedicated tool cannot do the job. An already-open shell is never a reason to route work to it. ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : 'Commands use a 10s foreground window by default—not a timeout. Still-running work continues as a tracked task_id and completes by notification. Use task monitor only after promotion when periodic progress is needed, task read for an extra current snapshot, and never poll in a loop.'}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -97,20 +91,6 @@ export const BUILTIN_TOOLS = [
                     minimum: 0,
                     description: 'Optional hard total deadline in ms; kills the command even after background promotion. Omit or 0 = no deadline.',
                 },
-                ...(_shellBackgroundDisabled ? {} : {
-                    run_in_background: {
-                        type: 'boolean',
-                        default: false,
-                        description: 'Start immediately as a tracked task for a known long-running command or intentional server/watcher. Default false.',
-                    },
-                    monitor_interval_ms: {
-                        type: 'integer',
-                        minimum: 0,
-                        maximum: SHELL_MONITOR_INTERVAL_MAX_MS,
-                        default: SHELL_MONITOR_INTERVAL_DEFAULT_MS,
-                        description: 'Periodic progress interval for tracked shell tasks in ms. Default 0 disables it; use 300000 (5m) or longer to enable.',
-                    },
-                }),
             },
             required: ['command'],
             additionalProperties: false,
@@ -121,7 +101,7 @@ export const BUILTIN_TOOLS = [
         name: 'task',
         title: 'Task',
         annotations: { title: 'Task', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        description: 'List shell tasks, read one current output snapshot, change periodic monitoring, or cancel by task_id; completion always arrives by notification.',
+        description: 'List shell tasks, read one current output snapshot, change periodic monitoring, or cancel by task_id. Call it only when a snapshot must drive a decision; never poll in a loop — completion always arrives by notification.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -142,7 +122,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Grep',
         annotations: { title: 'Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Read-only; safe to batch in parallel. Search file contents for literal or regex matches and return contextual path:line blocks. Ripgrep-dialect regex (e.g. "log.*Error"; escape literal braces; patterns match within one line). Replaces grep/rg.',
+        description: 'Read-only; safe to batch in parallel. Search file contents for literal or regex matches and return contextual path:line blocks that are directly usable; read only the lines they omit. A wide reconnaissance pattern goes to mode:files first; context:0 when only the location is needed. Ripgrep-dialect regex (e.g. "log.*Error"; escape literal braces; patterns match within one line). Replaces grep/rg.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -172,7 +152,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Glob',
         annotations: { title: 'Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Read-only; safe to batch in parallel. Return wildcard-matching file paths under a known base directory when those paths are needed. Directories never match; enumerate them with list. Omit path for the current Project; if the base location is unknown, use find first. Newest first by default. Replaces find -name.',
+        description: 'Read-only; safe to batch in parallel. Return wildcard-matching file paths under a known base directory when those paths are needed. Omit path for the current Project; if the base location is unknown, use find first. Directories never match. Newest first by default. Replaces find -name.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -194,7 +174,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Find Files',
         annotations: { title: 'Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Read-only; safe to batch in parallel. Fuzzy filename/directory path lookup when the location itself is unknown; returns paths only.',
+        description: 'Read-only; safe to batch in parallel. Fuzzy filename/directory path lookup when the location itself is unknown; returns paths only. Skip it when the path is already known or resolvable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -213,7 +193,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'List Directory',
         annotations: { title: 'List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: "Read-only; safe to batch in parallel. Return a known directory's immediate entries (path + type) when the entry list itself is needed; not a prerequisite for another tool on that directory — tree walks go to glob, name hunts to find. No wildcard; meta:true adds size/mtime/mode.",
+        description: "Read-only; safe to batch in parallel. Return a known directory's immediate entries (path + type) when the entry list itself is needed; never as a prerequisite for another tool on that directory. No wildcard; meta:true adds size/mtime/mode.",
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -41,12 +41,11 @@ export const GIT_TOOL_DEF = {
         openWorldHint: true,
         compressible: true,
     },
-    description: 'Run one Git command directly, without a shell. Shell operators and substitution are rejected. Repository mutations are serialized. High-risk destructive commands require confirm:true. Successful output is compacted.',
+    description: 'Run one Git command directly, without a shell. History, blame, and old commits are evidence only when the task itself is about the past; work on current code ends at status and diff. Use diff directly when changed content for a known target is required; status is the repository summary. Shell operators and substitution are rejected. Repository mutations are serialized. Successful output is compacted.',
     inputSchema: {
         type: 'object',
         properties: {
             command: { type: 'string', description: 'Full command beginning with git. Quote arguments as for a shell; shell operators are not allowed.' },
-            confirm: { type: 'boolean', description: 'Set true only when a rejected high-risk command explicitly requires it.' },
             output_limit: { type: 'integer', minimum: 1, maximum: 500, description: 'Item/line cap. Default 50; git log defaults to 10.' },
         },
         required: ['command'],
@@ -251,34 +250,6 @@ function runGit(plan, argv, options = {}) {
     return runProcess('git', [...plan.globalArgs, ...argv], { cwd: plan.cwd, signal: options.signal });
 }
 
-function destructiveReason(plan) {
-    const { operation, args } = plan;
-    // Dry-run previews mutate nothing: git either prints what WOULD happen or
-    // rejects the flag where unsupported, so the confirm gate only taxes safe
-    // inspection (2026-08-17 bench: `reflog expire --dry-run` was refused and
-    // the model paid a +56s workaround detour). `-n` short clusters count only
-    // for the subcommands where -n MEANS dry-run (clean/push/prune) — on
-    // e.g. `commit -n` it means --no-verify and must keep the gate.
-    if (args.includes('--dry-run')) return '';
-    if (['clean', 'push', 'prune'].includes(operation)
-        && args.some((value) => /^-[a-z]*n[a-z]*$/.test(value))) return '';
-    if (operation === 'reset' && args.includes('--hard')) return 'git reset --hard';
-    if (operation === 'clean' && args.some((value) => value === '--force' || /^-[^-]*f/.test(value))) return 'git clean --force';
-    if (operation === 'gc' && args.some((value) => value === '--prune=now' || value === '--aggressive')) return `git gc ${args.find((value) => value.startsWith('--prune') || value === '--aggressive')}`;
-    if (operation === 'prune') return 'git prune';
-    if (operation === 'filter-branch') return 'git filter-branch';
-    if (operation === 'update-ref' && args.includes('-d')) return 'git update-ref -d';
-    if (operation === 'symbolic-ref' && args.includes('--delete')) return 'git symbolic-ref --delete';
-    if (operation === 'reflog' && ['delete', 'expire'].includes(actionOf(operation, args))) return `git reflog ${actionOf(operation, args)}`;
-    if (operation === 'push' && args.some((value) => value.startsWith('--force') || value.startsWith('+'))) return 'git push --force';
-    if (operation === 'branch' && args.some((value) => value === '-D' || value === '--delete-force')) return 'git branch -D';
-    if (operation === 'commit' && args.includes('--amend')) return 'git commit --amend';
-    if (operation === 'stash' && actionOf(operation, args) === 'clear') return 'git stash clear';
-    if (operation === 'worktree' && actionOf(operation, args) === 'remove' && args.includes('--force')) return 'git worktree remove --force';
-    if (['checkout', 'switch'].includes(operation) && args.some((value) => value === '-f' || value === '--force' || value === '--discard-changes')) return `git ${operation} --force`;
-    return null;
-}
-
 function hasOutputFormat(args) {
     return args.some((value) => /^(?:--format|--pretty)(?:=|$)/.test(value) || value === '--oneline');
 }
@@ -605,8 +576,6 @@ export async function executeGitTool(input, workDir, options = {}) {
     }
     const limitDefault = plan.operation === 'log' ? 10 : 50;
     const limit = Math.min(500, Math.max(1, Number(input.output_limit) || limitDefault));
-    const reason = destructiveReason(plan);
-    if (reason && input.confirm !== true) return fail(`${reason} requires confirm:true`);
     const signal = options?.signal || options?.abortSignal || null;
     if (plan.operation === 'init' || plan.operation === 'clone') {
         const target = creationTarget(plan);

package/src/runtime/agent/orchestrator/tools/builtin/git-command-tool.test.mjs

@@ -51,8 +51,7 @@ test('git command tool preserves shell syntax, compacts output, and gates destru
     assert.match(JSON.stringify(parseOk(await git(repo, 'count-objects -v'))), /count:/);
     parseOk(await git(repo, 'check-ref-format refs/heads/test'));
     assert.match(String(await git(repo, 'archive HEAD')), /^Error: git archive requires -o\/--output/);
-    assert.match(String(await git(repo, 'prune')), /^Error: git prune requires confirm:true/);
-    parseOk(await git(repo, 'prune --expire=now', { confirm: true }));
+    parseOk(await git(repo, 'prune --expire=now'));
     const shown = parseOk(await git(repo, `show ${base}`, { output_limit: 5 }));
     assert.equal(shown.commit.oid, base);
     assert.deepEqual(shown.diff.files, ['base.txt']);
@@ -66,8 +65,7 @@ test('git command tool preserves shell syntax, compacts output, and gates destru
     const batchShow = parseOk(await git(repo, `show ${base} ${secretCommit}`, { output_limit: 5 })).commits;
     assert.deepEqual(batchShow.map((row) => row.commit.oid), [base, secretCommit]);
 
-    assert.match(String(await git(repo, `reset --hard ${base}`)), /^Error: git reset --hard requires confirm:true/);
-    parseOk(await git(repo, `reset --hard ${base}`, { confirm: true }));
+    parseOk(await git(repo, `reset --hard ${base}`));
     const fsck = parseOk(await git(repo, 'fsck --full --unreachable --no-reflogs', { output_limit: 20 }));
     assert.match(JSON.stringify(fsck), new RegExp(secretCommit));
 
@@ -75,16 +73,13 @@ test('git command tool preserves shell syntax, compacts output, and gates destru
     assert.ok(reflog.entries.some((row) => row.oid === secretCommit));
     const selectors = reflog.entries.map((row) => row.selector).filter((value, index, all) => all.indexOf(value) === index).slice(0, 2);
     const deleteCommand = `reflog delete --rewrite ${selectors.map(quote).join(' ')}`;
-    assert.match(String(await git(repo, deleteCommand)), /^Error: git reflog delete requires confirm:true/);
-    parseOk(await git(repo, deleteCommand, { confirm: true }));
-    // Dry-run previews skip the confirm gate: nothing mutates.
+    parseOk(await git(repo, deleteCommand));
+    // Dry-run previews mutate nothing and still return a normal result.
     parseOk(await git(repo, 'reflog expire --dry-run --verbose --expire-unreachable=now --all'));
     parseOk(await git(repo, 'prune --dry-run'));
     parseOk(await git(repo, 'clean -nd'));
-    assert.match(String(await git(repo, 'reflog expire --expire-unreachable=now --all --rewrite')), /^Error: git reflog expire requires confirm:true/);
-    parseOk(await git(repo, 'reflog expire --expire-unreachable=now --all --rewrite', { confirm: true }));
-    assert.match(String(await git(repo, 'gc --prune=now')), /^Error: git gc --prune=now requires confirm:true/);
-    parseOk(await git(repo, 'gc --prune=now', { confirm: true }));
+    parseOk(await git(repo, 'reflog expire --expire-unreachable=now --all --rewrite'));
+    parseOk(await git(repo, 'gc --prune=now'));
 
     renameSync(join(repo, 'base.txt'), join(repo, 'renamed.txt'));
     parseOk(await git(repo, 'add --all'));
@@ -92,7 +87,7 @@ test('git command tool preserves shell syntax, compacts output, and gates destru
     const renameText = renameDiff.patch || renameDiff.output;
     assert.match(renameText, /rename from base\.txt/);
     assert.match(renameText, /rename to renamed\.txt/);
-    parseOk(await git(repo, 'reset --hard HEAD', { confirm: true }));
+    parseOk(await git(repo, 'reset --hard HEAD'));
 
     writeFileSync(join(repo, 'base.txt'), `${Array.from({ length: 120 }, (_, i) => `changed-${i}`).join('\n')}\n`);
     const rawDiff = spawnSync('git', ['-C', repo, 'diff', '--', 'base.txt'], { encoding: 'utf8' }).stdout;
@@ -135,7 +130,6 @@ test('git command tool preserves shell syntax, compacts output, and gates destru
     assert.match(JSON.stringify(parseOk(await git(repo, 'worktree list --porcelain'))), /topic/);
     assert.match(JSON.stringify(parseOk(await git(repo, 'branch --list'))), /topic/);
 
-    assert.match(String(await git(repo, 'push --force origin HEAD')), /^Error: git push --force requires confirm:true/);
     assert.match(String(await executeGitTool({ command: 'git status && git log' }, root)), /^Error: git command must not contain shell operators/);
 });
 
@@ -184,10 +178,11 @@ test('git failure detail folds progress frames and keeps the fatal tail', () =>
 
 test('git schema exposes only the compact shell-compatible contract', () => {
     const properties = GIT_TOOL_DEF.inputSchema.properties;
-    assert.deepEqual(Object.keys(properties), ['command', 'confirm', 'output_limit']);
+    assert.deepEqual(Object.keys(properties), ['command', 'output_limit']);
     assert.deepEqual(GIT_TOOL_DEF.inputSchema.required, ['command']);
     assert.equal(properties.command.minLength, undefined);
-    assert.match(properties.confirm.description, /only when a rejected high-risk command/i);
+    assert.doesNotMatch(GIT_TOOL_DEF.description, /confirm/i);
+    assert.match(GIT_TOOL_DEF.description, /Use diff directly when changed content for a known target is required/i);
     assert.match(GIT_TOOL_DEF.description, /Run one Git command directly, without a shell/i);
     assert.match(GIT_TOOL_DEF.description, /repository mutations are serialized/i);
 });

package/src/runtime/agent/orchestrator/tools/builtin/lib/grep-context-expander.mjs

@@ -16,7 +16,7 @@ import {
     relativeGrepLine,
 } from './search-input-helpers.mjs';
 
-export const GREP_CONTEXT_CHAR_BUDGET_DEFAULT = 10_000;
+export const GREP_CONTEXT_CHAR_BUDGET_DEFAULT = 5_000;
 const GREP_FOCUSED_CONTEXT_RADIUS = 12;
 const GREP_FOCUSED_RAW_BLOCKS = 3;
 // Anchors must stay usable as evidence without a follow-up read: keep the

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,13 +3,13 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Read-only; safe to batch in parallel. Source-file structure, symbol relations, and flow. File modes use files[]; symbol modes use symbols[]; symbols may combine both to filter a file outline. Exact identifiers use find_symbol/references/callers/callees; keywords use symbol_search/search. find_symbol returns declaration/body; references returns declaration/usages plus optional body; callers/callees return locations.',
+    description: 'Read-only; safe to batch in parallel. Source-file structure, symbol relations, and flow. Exact identifiers route directly to find_symbol/references/callers/callees; symbol-name keywords use symbol_search/search. Source text, literals, regex, and conceptual keywords use grep. File modes use files[]; symbol modes use symbols[]. overview and mode:symbols return file summaries. find_symbol returns declaration/body; references returns declaration/usages plus optional body; callers/callees return locations.',
     inputSchema: {
       type: 'object',
       properties: {
         mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees'], description: 'File modes: overview, imports, dependents, related, and impact. symbols with files[] returns an optionally filtered file outline; remaining modes use symbols[].' },
-        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: 'Project-relative source path(s). Required for imports, dependents, related, impact, and file-outline symbols; optional for overview or to scope symbol modes.' },
-        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: 'Exact identifiers or keywords; batch in one symbols[] call. Required by lookup and relation modes; optional filters for mode:symbols.' },
+        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: 'Project-relative source path(s); required by file modes, optional to scope symbol modes.' },
+        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: 'Exact identifiers or symbol-name keywords; batch in one symbols[] call; required by symbol modes, optional filter for mode:symbols.' },
         body: { type: 'boolean', description: 'Include declaration body: find_symbol defaults true; references is opt-in.' },
         limit: { type: 'integer', minimum: 1, maximum: 500, description: 'Maximum results; modes may enforce lower caps.' },
         depth: { type: 'integer', minimum: 1, maximum: 5, description: 'Overview hierarchy or caller traversal depth; default 1.' },

package/src/runtime/agent/orchestrator/tools/patch-tool-defs.mjs

@@ -23,7 +23,7 @@ eof_line: "*** End of File" LF
 // Lark custom tool. The tiny JSON schema remains only for function-only
 // compatibility paths; runtime knobs stay off the model surface.
 const APPLY_PATCH_FREEFORM_DESCRIPTION =
-  'Edit files with one raw V4A patch; do not wrap it in JSON. Use one Add/Delete/Update File block per target path and multiple @@ hunks within one Update File block. Add File atomically creates the file and missing parent directories, failing without changes if the target already exists. Multi-file patches commit valid files and report rejected files separately.';
+  'Edit files with one raw V4A patch; do not wrap it in JSON. Use one Add/Delete/Update File block per target path and multiple @@ hunks within one Update File block. Add File atomically creates the file and missing parent directories, failing without changes if the target already exists; call it directly without a prior read, list, or mkdir. Use exact lines already in context; never re-open the file to build context or to verify a successful patch. Multi-file patches commit valid files and report rejected files separately.';
 
 const APPLY_PATCH_JSON_DESCRIPTION = 'Edit files with one complete V4A patch in `patch`.';
 

package/src/runtime/agent/orchestrator/tools/shell-command.mjs

@@ -217,7 +217,6 @@ export function execShellCommand({
   timeoutMs,
   abortSignal,
   autoBackgroundMs,
-  startInBackground = false,
   onProgress,
   onOutputTail,
   clientHostPid,
@@ -603,8 +602,8 @@ export function execShellCommand({
     // resolve the call immediately with a 'backgrounded' result while the
     // child keeps running, adopted into the shell-jobs registry but still
     // owned by this CLI process:
-    //   1. the optional autoBackgroundMs soft threshold (MIXDOG_SHELL_AUTO_
-    //      BACKGROUND_MS opt-in) — an EARLIER promotion before the timeout, and
+    //   1. the autoBackgroundMs soft foreground threshold — an EARLIER
+    //      promotion before the timeout, and
     //   2. the foreground timeout deadline (backgroundOnTimeout) — the default
     //      promote-on-timeout that replaces the old tree-kill.
     // A capped explicit foreground timeout supplies its remaining deadline to
@@ -773,9 +772,7 @@ export function execShellCommand({
       const secs = Math.max(0, Math.round(_elapsedSinceStart() / 1000));
       const _verb = reason === 'timeout'
         ? `moved to background at timeout after ${secs}s`
-        : (reason === 'explicit'
-          ? 'started in background'
-          : `auto-backgrounded after ${secs}s`);
+        : `auto-backgrounded after ${secs}s`;
       resolveResult(
         new ExecResult({
           stdout,
@@ -889,9 +886,7 @@ export function execShellCommand({
     // Arm the auto-background timer only for the genuine foreground one-shot
     // path: a positive threshold strictly below the hard timeout, and not a
     // trailing-`&` background command (those already detach + settle on exit).
-    if (startInBackground && !_isBackground) {
-      setImmediate(() => { fireAutoBackground({ reason: 'explicit' }); });
-    } else if (
+    if (
       typeof autoBackgroundMs === 'number' &&
       autoBackgroundMs > 0 &&
       !_isBackground &&

package/src/session-runtime/agent-disable.test.mjs

@@ -58,19 +58,21 @@ test('disabled agents are stored apart from the route and survive canonicalizati
 
 test('a disabled agent leaves the Lead prompt and the delegation surface', () => {
   const { data, helpers } = fixture(['worker', 'reviewer']);
-  const enabled = helpers.activeWorkflowContext({}, data);
+  // The shipped fallback is Solo, so a delegating pack is selected explicitly.
+  const cowork = (extra = {}) => ({ workflow: { active: 'default' }, ...extra });
+  const enabled = helpers.activeWorkflowContext(cowork(), data);
   assert.match(enabled.context, /# Available Agents/);
   assert.match(enabled.context, /\(worker\)/);
   assert.equal(enabled.summary.delegatesAgents, true);
 
-  const partial = helpers.activeWorkflowContext({ disabledAgents: ['worker'] }, data);
+  const partial = helpers.activeWorkflowContext(cowork({ disabledAgents: ['worker'] }), data);
   assert.equal(partial.context.includes('(worker)'), false);
   assert.match(partial.context, /\(reviewer\)/);
   assert.equal(partial.summary.delegatesAgents, true);
 
   // Nobody left to delegate to: the agent tool drops exactly as it does for a
   // non-delegating pack.
-  const none = helpers.activeWorkflowContext({ disabledAgents: ['worker', 'reviewer'] }, data);
+  const none = helpers.activeWorkflowContext(cowork({ disabledAgents: ['worker', 'reviewer'] }), data);
   assert.equal(none.context.includes('# Available Agents'), false);
   assert.equal(none.summary.delegatesAgents, false);
   assert.deepEqual(helpers.delegatableAgentIds({ disabledAgents: ['worker'] }, data), ['reviewer']);

package/src/session-runtime/tool-policy-surface.test.mjs

@@ -11,21 +11,59 @@ import { DEFERRED_DEFAULT_LEAD_TOOLS } from './tool-catalog-data.mjs';
 const require = createRequire(import.meta.url);
 const { omitToolRoutes, buildSharedToolContent } = require('../lib/rules-builder.cjs');
 
+// Tool dependency is declared by `<!-- tools: … -->` markers, so this fixture
+// carries the markers rather than prose the builder would have to match.
 const SAMPLE_ROUTES = [
+  '<!-- tools: web_search, web_fetch -->',
   '# Research',
   '',
+  '<!-- tools: web_search, web_fetch -->',
   '- Research routes:',
+  '<!-- tools: web_search -->',
   '  current or external information discovery→`web_search`;',
+  '<!-- tools: web_fetch -->',
   '  page or documentation body retrieval from a known URL→`web_fetch`.',
+  '<!-- tools: recall, memory -->',
   '# Memory',
   '',
+  '<!-- tools: recall -->',
   '- past facts recorded in prior work or sessions→`recall`',
   '  (stored history only, never current local state).',
+  '<!-- tools: memory -->',
   '- Durable memory creation or update→`memory`; store a compact English',
   '  statement.',
+  '<!-- tools: memory -->',
   '- Use judgment to decide whether a durable memory should be stored.',
 ].join('\n');
 
+test('omitToolRoutes strips markers and keeps every clause when nothing is omitted', () => {
+  const kept = omitToolRoutes(SAMPLE_ROUTES, []);
+  assert.equal(kept.includes('<!--'), false);
+  assert.equal(kept.includes('`web_search`'), true);
+  assert.equal(kept.includes('`web_fetch`'), true);
+  assert.equal(kept.includes('`recall`'), true);
+  assert.equal(kept.includes('`memory`'), true);
+  assert.equal(kept.includes('# Research'), true);
+  assert.equal(kept.includes('# Memory'), true);
+  // The continuation line stays attached to the clause it belongs to.
+  assert.match(kept, /→`recall`\n\s+\(stored history only, never current local state\)\./);
+});
+
+test('omitToolRoutes drops a clause only when every tool it declares is omitted', () => {
+  const noSearchOnly = omitToolRoutes(SAMPLE_ROUTES, ['web_search']);
+  assert.equal(noSearchOnly.includes('`web_search`'), false);
+  assert.equal(noSearchOnly.includes('`web_fetch`'), true);
+  // The section and its lead-in survive while one route remains.
+  assert.equal(noSearchOnly.includes('# Research'), true);
+  assert.equal(noSearchOnly.includes('Research routes:'), true);
+
+  const noMemoryOnly = omitToolRoutes(SAMPLE_ROUTES, ['memory']);
+  assert.equal(noMemoryOnly.includes('`recall`'), true);
+  assert.equal(noMemoryOnly.includes('`memory`'), false);
+  // Guidance that only makes sense with the memory tool goes with it.
+  assert.equal(noMemoryOnly.includes('Use judgment'), false);
+});
+
 test('omitToolRoutes drops web search and memory clauses independently', () => {
   const noSearch = omitToolRoutes(SAMPLE_ROUTES, ['web_search', 'web_fetch']);
   assert.equal(noSearch.includes('`web_search`'), false);
@@ -72,26 +110,41 @@ test('shared tool rules keep workflow and shell-boundary anchors', () => {
   // intentionally changes.
   const full = buildSharedToolContent({ PLUGIN_ROOT: join(process.cwd(), 'src') });
   assert.match(full, /Minimize tool turns through maximal useful parallelism/i);
-  assert.match(full, /in each turn, issue\s+every necessary non-overlapping call whose inputs are already known/i);
-  assert.match(full, /Defer a call only when its inputs depend on an earlier result/i);
-  assert.match(full, /Apply one analysis to many targets as one parameterized call/i);
+  assert.match(full, /In each round, issue every necessary non-overlapping call whose inputs are\s+already known/i);
+  assert.match(full, /Investigate, build, and verify only what the requested outcome requires, at\s+the level it requires/i);
+  assert.match(full, /A check runs at the strictness the task requires; never raise a tool's own\s+severity beyond it/i);
+  assert.match(full, /Cost is counted in\s+rounds, not calls/i);
+  assert.match(full, /Plan the fewest evidence-complete dependent\s+rounds first/i);
+  assert.match(full, /defer a call only when its target or arguments require an\s+earlier result/i);
+  assert.match(full, /Route each remaining evidence facet once to its primary owner, preferring the\s+operation that directly returns the evidence needed for the next decision/i);
+  assert.match(full, /summary, overview, or enumeration is not a prerequisite when that operation's\s+complete inputs are already known/i);
+  assert.match(full, /apply\s+one analysis to many targets as one parameterized call/i);
   assert.match(full, /use Execution when the information can only be produced by running a program\s+or observing runtime state/i);
   assert.match(full, /Evidence or artifacts available only through program execution, calculation,\s+data transformation, generated output, or unsupported-format decoding→`shell`/i);
-  assert.match(full, /environment variable or the home directory\s+are resolved locations/i);
+  assert.match(full, /an already-open shell is never a routing reason/i);
+  assert.match(full, /Route the missing evidence to its primary owner/i);
+  assert.match(full, /repository state, history, or diff→`git`/i);
+  assert.match(full, /Ownership is exclusive: each evidence type has one owner/i);
+  assert.match(full, /a\s+successful owner result closes that facet/i);
+  assert.match(full, /Blocking checks cover only essential integrity, security, compatibility, and\s+buildability invariants/i);
+  assert.match(full, /environment variable or the home directory are\s+resolved locations/i);
   assert.match(full, /Use read-only means for inspection; never mutate to clear an obstacle or\s+unexpected state/i);
-  assert.match(full, /batching never licenses a guessed `glob\.path`/i);
-  assert.match(full, /unknown location → `find` first/i);
-  assert.match(full, /inspect only the nearest relevant code,\s+configuration, and established pattern needed to verify local conventions or\s+dependency availability/i);
-  assert.match(full, /Do not re-read content already returned by any tool or reopen a successfully\s+edited file solely to confirm the edit/i);
+  assert.match(full, /literal, regex, or text location→`grep`;\s+known-file content, range, or image→`read`/i);
+  assert.match(full, /is never re-found, re-derived, or\s+re-verified at any granularity/i);
+  assert.match(full, /Mine each returned result fully before opening the next round/i);
+  assert.match(full, /Evidence that determines the answer, edit, or deliverable ends retrieval/i);
   assert.match(full, /Enter Verification only after all planned work is complete/i);
   assert.match(full, /use an umbrella suite only when the user explicitly requests it\s+or a documented project or release process requires it/i);
   assert.match(full, /If verification fails, collect all failures, leave Verification/i);
-  assert.doesNotMatch(full, /passed checks|affected failed checks once/i);
-  assert.match(full, /Repository state or history explicitly asked about, and every repository\s+mutation→`git`; never part of exploration batching/i);
-  assert.doesNotMatch(full, /read-only `git`/i);
+  assert.match(full, /A successful verification closes the task unless later changes affect it/i);
+  assert.doesNotMatch(full, /affected failed checks once/i);
+  assert.match(full, /Every repository mutation→`git`/i);
+  assert.doesNotMatch(full, /always batch safely in parallel/i);
+  assert.match(full, /A required new file is created directly: Add File is itself the atomic\s+absence check/i);
   assert.match(full, /Source: use exact current target text from any visible evidence/i);
   assert.match(full, /Placement: with `edit`, use an exact unique target string/i);
   assert.match(full, /with `apply_patch`, use exact unchanged context/i);
+  assert.match(full, /Apply all determined changes in the fewest safe calls the active tool\s+supports/i);
   assert.match(full, /Batch scope: never split one file across concurrent edit calls/i);
   assert.match(full, /Commit, push, release, and deployment happen only on the user's explicit\s+request/i);
   assert.match(full, /past facts recorded in prior work or sessions→`recall`/i);

package/src/session-runtime/workflow.mjs

@@ -29,7 +29,10 @@ const STARTER_AGENT_ORDER = new Map([
   ['heavy-worker', 1],
   ['reviewer', 2],
 ]);
-export const DEFAULT_WORKFLOW_ID = 'default';
+// Fallback workflow for a config with no explicit selection, for an unknown
+// id, and for the pack reset after a delete. Solo is the shipped default
+// working mode; the cowork pack (directory id `default`) is opt-in.
+export const DEFAULT_WORKFLOW_ID = 'solo';
 
 const WEB_SEARCH_CAPABLE_PROVIDERS = new Set([
   'openai-oauth', 'openai', 'grok-oauth', 'xai', 'gemini', 'anthropic', 'anthropic-oauth',
@@ -245,8 +248,10 @@ export function createWorkflowHelpers({ rootDir, dataDir, readMarkdownDocument,
     // Solo leads (user decision: solo is the default working mode), the
     // cowork pack (built-in id `default`) second, then customs alphabetically
     // — every picker (TUI, desktop sidebar, onboarding) shares this order.
+    // The cowork id stays literal here: DEFAULT_WORKFLOW_ID now means "the
+    // fallback pack" (solo), not "the pack whose directory is `default`".
     const weight = (pack) => pack.id === 'solo' ? 0
-      : (pack.id === DEFAULT_WORKFLOW_ID || pack.id === 'cowork') ? 1 : 2;
+      : (pack.id === 'default' || pack.id === 'cowork') ? 1 : 2;
     return [...byId.values()].sort((a, b) =>
       (weight(a) - weight(b)) || a.name.localeCompare(b.name));
   }
@@ -277,7 +282,7 @@ export function createWorkflowHelpers({ rootDir, dataDir, readMarkdownDocument,
     const id = normalizeWorkflowId(pack?.id, DEFAULT_WORKFLOW_ID);
     return {
       id,
-      name: clean(pack?.name) || (id === DEFAULT_WORKFLOW_ID ? 'Default' : id),
+      name: clean(pack?.name) || (id === 'default' ? 'Default' : id),
       description: clean(pack?.description),
       source: clean(pack?.source),
       // Delegation surface field: the session stores this summary as

package/src/tui/session/turn.mjs

@@ -972,6 +972,11 @@ export function createRunTurn(bag) {
         // computed this number.
         onContextPressure: (info) => {
           if (!markTurnProgress('context-pressure')) return;
+          // This direct pressure publication exists only to make the gauge hit
+          // 100% on the exact frame auto-compaction starts. Routine pre-send
+          // checks stay on the canonical contextStatus path instead of
+          // competing with its provider-aligned value.
+          if (info?.willCompact !== true) return;
           const used = Math.max(0, Number(info?.usedTokens) || 0);
           if (!used) return;
           set({

package/src/workflows/default/WORKFLOW.md

@@ -10,11 +10,12 @@ Consult the user and build the plan together. Before the user explicitly
 approves the latest plan, work is read-only investigation and planning — no
 edits, state mutation, or delegation. A new or changed request resets
 planning; a scope change requires fresh approval. Explicit read-only requests
-proceed immediately; approval precedes edits, state mutation, or delegation.
-Ask the user only for decisions.
+proceed immediately; approval precedes edits, state mutation, and delegation,
+and on approval all in-scope work completes without reapproval. Ask the user
+only for decisions.
 
-On approval, complete all in-scope work without reapproval. Lead delegates
-maximally: one suitable agent per independent scope, all spawned in one turn;
+Lead delegates maximally: one suitable agent per independent scope,
+all spawned in one turn;
 only a scope that depends on another's output waits. Split the plan into as
 many scopes as possible: disjoint file/module sets are independent; merge only
 on a true output dependency. Prefer parallel scopes over sequential slices in

package/src/workflows/solo/WORKFLOW.md

@@ -11,11 +11,9 @@ Consult the user and build the plan together. Before the user explicitly
 approves the latest plan, work is read-only investigation and planning — no
 edits, state mutation, or delegation. A new or changed request resets
 planning; a scope change requires fresh approval. Explicit read-only requests
-proceed immediately; approval precedes edits, state mutation, or delegation.
-Ask the user only for decisions.
-
-On approval, complete all in-scope work without reapproval. Lead executes
-every scope itself — never spawn, send, or delegate to agents.
+proceed immediately; approval precedes edits and state mutation, and on
+approval all in-scope work completes without reapproval. Ask the user only for
+decisions. Lead executes every scope itself.
 
 Report the result against the approved plan. Build happens only on an explicit
 user request.