mixdog 0.9.35 → 0.9.37

package/src/runtime/agent/orchestrator/session/cache/scoped-cache.mjs

@@ -179,22 +179,24 @@ function _bumpCounter(sessionId, field) {
  * null on miss. On hit returns the full entry
  * { content, firstToolUseId, ts }.
  */
-export function tryScopedToolCached({ sessionId, toolName, args, cwd }) {
+export function tryScopedToolCached({ sessionId, toolName, args, cwd, countStats = true, touch = true } = {}) {
     if (!sessionId || !toolName) return null;
     const map = _scopedBySession.get(sessionId);
     if (!map) {
-        _bumpCounter(sessionId, 'misses');
+        if (countStats) _bumpCounter(sessionId, 'misses');
         return null;
     }
     const key = _scopedKey(toolName, args, cwd);
     const entry = map.get(key);
     if (!entry) {
-        _bumpCounter(sessionId, 'misses');
+        if (countStats) _bumpCounter(sessionId, 'misses');
         return null;
     }
-    map.delete(key);
-    map.set(key, entry);
-    _bumpCounter(sessionId, 'hits');
+    if (touch) {
+        map.delete(key);
+        map.set(key, entry);
+    }
+    if (countStats) _bumpCounter(sessionId, 'hits');
     return { content: entry.content, firstToolUseId: entry.firstToolUseId || null, ts: entry.ts };
 }
 

package/src/runtime/agent/orchestrator/session/eager-dispatch.mjs

@@ -6,7 +6,8 @@
 // identical to the inline closures it replaced.
 import { normalizeToolEnvelope } from './tool-envelope.mjs';
 import { isInvalidToolArgsMarker } from '../providers/openai-compat-stream.mjs';
-import { _intraTurnSig } from './loop/tool-classify.mjs';
+import { _intraTurnSig, _isReadTool, _isScopedCacheableTool, _stripMcpPrefix } from './loop/tool-classify.mjs';
+import { tryReadCached, tryScopedToolCached } from './read-dedup.mjs';
 import { preDispatchDenyForSession } from './loop/pre-dispatch-deny.mjs';
 import { executeTool } from './loop/tool-exec.mjs';
 import { crossTurnSignature } from './loop/completion-guards.mjs';
@@ -63,6 +64,23 @@ export function createEagerDispatcher({
                 const _prior = crossTurnCalls.get(_ctSig);
                 if (_prior && _prior.firstIteration < getIterations()) return null;
             }
+            // Cache short-circuit (mirrors the serial-body lookup at
+            // tool-batch.mjs). If this read / scoped-cacheable call would be
+            // served from the session cache in the serial for-body, do NOT
+            // execute it eagerly — the serial path returns the cached body
+            // (read cache is stat-validated; scoped cache is dep-root evicted).
+            // Returning null here skips redundant IO under concurrent agents
+            // and, combined with the non-barrier `continue` in startEagerRun,
+            // never blocks a later independent eager read behind a cache stub.
+            // If the entry is invalidated before the serial body re-checks,
+            // that call simply executes serially — correctness is preserved.
+            if (sessionId) {
+                if (_isReadTool(call.name)) {
+                    if (tryReadCached({ sessionId, args: call.arguments, cwd }) !== null) return null;
+                } else if (_isScopedCacheableTool(call.name)) {
+                    if (tryScopedToolCached({ sessionId, toolName: _stripMcpPrefix(call.name), args: call.arguments, cwd, countStats: false, touch: false }) !== null) return null;
+                }
+            }
             const toolKind = getToolKind(call.name);
             // Shared pre-dispatch deny: identical predicate runs in the
             // serial path below. If any role/permission guard would reject
@@ -137,7 +155,15 @@ export function createEagerDispatcher({
                 const call = calls[j];
                 if (!call?.id || !isEagerDispatchable(call.name, tools)) break;
                 if (dupSet && dupSet.has(call.id)) continue;
-                if (!startEagerTool(call) && !pending.has(call.id)) break;
+                // A null return here is NOT a state barrier: the loop above
+                // already breaks at the first non-eager (mutation/bash/unknown)
+                // tool, so every call reached here is read-only. A null means a
+                // non-barrier stub — intra-turn in-flight dup, repeat-failure /
+                // cross-turn dedup, pre-dispatch-deny, invalid-args, or a cache
+                // short-circuit. `continue` (not `break`) so a stub in the
+                // middle of a contiguous eager run does not stop LATER
+                // independent eager reads from starting early.
+                if (!startEagerTool(call) && !pending.has(call.id)) continue;
             }
         };
         let _streamEagerBlocked = false;

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

@@ -2,8 +2,6 @@
 // loop.mjs. These drive cross-turn read dedup, scoped caching, shell routing,
 // and duplicate-call detection. Strips the MCP prefix so direct calls and
 // MCP-wrapped calls share the same cache.
-import { createHash } from 'crypto';
-
 export const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
 
 export function _stripMcpPrefix(name) {
@@ -73,5 +71,5 @@ export function _canonicalArgs(args) {
     } catch { return String(args); }
 }
 export function _intraTurnSig(name, args) {
-    return createHash('sha256').update(`${name}:${_canonicalArgs(args)}`).digest('hex').slice(0, 16);
+    return `${name}:${_canonicalArgs(args)}`;
 }

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

@@ -16,10 +16,23 @@ import { isAgentOwner } from '../../agent-owner.mjs';
 // Eager-dispatch: tools with readOnlyHint:true in their declaration are safe
 // to execute during SSE parsing so tool work overlaps with the rest of the
 // stream. Writes, bash, MCP and skills stay serial after send() returns.
+// Memoized: the read-only name Set is built once per distinct `tools` array
+// (keyed by identity via a module-level WeakMap) so repeated per-call lookups
+// are O(1) instead of O(N) tools.find scans.
+const _eagerNameSetByTools = new WeakMap();
 export function isEagerDispatchable(name, tools) {
     if (!Array.isArray(tools)) return false;
-    const def = tools.find(t => t?.name === name);
-    return def?.annotations?.readOnlyHint === true;
+    let set = _eagerNameSetByTools.get(tools);
+    if (set === undefined) {
+        set = new Set();
+        for (const t of tools) {
+            if (t?.annotations?.readOnlyHint === true && typeof t.name === 'string') {
+                set.add(t.name);
+            }
+        }
+        _eagerNameSetByTools.set(tools, set);
+    }
+    return set.has(name);
 }
 export function messagesArrayChanged(before, after) {
     if (!Array.isArray(before) || !Array.isArray(after)) return before !== after;

package/src/runtime/agent/orchestrator/session/manager/ask-session.mjs

@@ -340,25 +340,24 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
                     onToolResult: typeof askOpts?.onToolResult === 'function' ? askOpts.onToolResult : undefined,
                     onToolApproval: typeof askOpts?.onToolApproval === 'function' ? askOpts.onToolApproval : undefined,
                     onCompactEvent: typeof askOpts?.onCompactEvent === 'function' ? askOpts.onCompactEvent : undefined,
-                    // Mid-turn steering drain. agentLoop calls this at every
-                    // tool-batch boundary (before the next provider.send) and
-                    // injects any returned strings as user turns — so input
-                    // (user typing, `agent type=send`) that arrives WHILE a
-                    // long multi-tool turn is in flight is picked up on the
-                    // model's very next iteration instead of waiting for the
-                    // whole task to finish. The post-turn _pendingTail drain
-                    // below still handles "followUp" input that lands after the
-                    // agent would otherwise stop. Same queue, two drain points.
-                    drainSteering: (sid) => {
+                    // Claude Code parity: mid-chain queued prompt/notification
+                    // drain is owned by agentLoop at provider-continuation
+                    // boundaries (after a tool batch, before the next send).
+                    // The post-loop _pendingTail drain below still handles
+                    // items that arrive after the model would otherwise stop.
+                    drainSteering: (sid, drainOptions = {}) => {
                         const out = [];
                         if (typeof askOpts?.drainSteering === 'function') {
                             try {
-                                const drained = askOpts.drainSteering(sid || sessionId);
+                                const drained = askOpts.drainSteering(sid || sessionId, drainOptions);
                                 if (Array.isArray(drained)) out.push(...drained);
                             } catch { /* best-effort steering drain */ }
                         }
-                        try { out.push(...drainPendingMessages(sid || sessionId)); }
-                        catch { /* best-effort pending drain */ }
+                        // Do NOT drain manager/pending-messages here: those
+                        // entries have no mode/priority/slash metadata, so
+                        // draining them mid-chain would bypass Claude Code's
+                        // queued_command filters. They are consumed by the
+                        // post-loop _pendingTail drain below.
                         return out;
                     },
                     onSteerMessage: typeof askOpts?.onSteerMessage === 'function' ? askOpts.onSteerMessage : undefined,
@@ -574,6 +573,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
             // owning background task in `running` and suppress its completion
             // notification. Cap the wait; let a slow write finish in the
             // background instead of holding askSession() open indefinitely.
+            let terminalSaveTimedOut = false;
             {
                 const savePromise = saveSessionAsync(session, { expectedGeneration: askGeneration });
                 let saveTimer = null;
@@ -587,6 +587,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
                         saveTimeout,
                     ]);
                     if (outcome === '__save_timeout__') {
+                        terminalSaveTimedOut = true;
                         try { process.stderr.write(`[session] terminal save exceeded ${TERMINAL_SAVE_TIMEOUT_MS}ms; continuing best-effort (${sessionId})\n`); } catch {}
                         // Don't drop the write — let it settle in the background.
                         savePromise.catch((err) => {
@@ -674,10 +675,18 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
             const _mergedTail = _mergePendingMessageEntries(_drained);
             if (_mergedTail?.content) {
                 _pendingTail.push(_mergedTail.content);
-                const refreshed = loadSession(sessionId);
-                if (refreshed && refreshed.closed !== true) {
-                    activeSession = refreshed;
-                    runtime.session = refreshed;
+                if (terminalSaveTimedOut) {
+                    // The disk snapshot may still be stale; carry the just-
+                    // committed in-memory session into the follow-up turn so
+                    // the queued tail sees the preceding assistant/tool context.
+                    activeSession = session;
+                    runtime.session = session;
+                } else {
+                    const refreshed = loadSession(sessionId);
+                    if (refreshed && refreshed.closed !== true) {
+                        activeSession = refreshed;
+                        runtime.session = refreshed;
+                    }
                 }
                 continue;
             }

package/src/runtime/agent/orchestrator/session/manager/prompt-utils.mjs

@@ -73,13 +73,13 @@ function temporalPromptText(content) {
 function promptNeedsDateReminder(content) {
     const text = temporalPromptText(content);
     if (!text) return false;
-    return /(?:오늘|내일|어제|모레|그저께|요즘|최근|방금|아까|현재\s*(?:날짜|시간|시각)|지금\s*(?:몇\s*시|시간|날짜|요일)|몇\s*월\s*몇\s*일|몇\s*시|무슨\s*요일|요일|날짜|이번\s*(?:주|달|월|년)|지난\s*(?:주|달|월|년)|다음\s*(?:주|달|월|년)|올해|작년|내년|today|tomorrow|yesterday|recently|current\s+(?:date|time)|what\s+(?:date|time)|which\s+day|weekday|this\s+(?:week|month|year)|last\s+(?:week|month|year)|next\s+(?:week|month|year))/i.test(text);
+    return /(?:\uC624\uB298|\uB0B4\uC77C|\uC5B4\uC81C|\uBAA8\uB808|\uADF8\uC800\uAED8|\uC694\uC998|\uCD5C\uADFC|\uBC29\uAE08|\uC544\uAE4C|\uD604\uC7AC\s*(?:\uB0A0\uC9DC|\uC2DC\uAC04|\uC2DC\uAC01)|\uC9C0\uAE08\s*(?:\uBA87\s*\uC2DC|\uC2DC\uAC04|\uB0A0\uC9DC|\uC694\uC77C)|\uBA87\s*\uC6D4\s*\uBA87\s*\uC77C|\uBA87\s*\uC2DC|\uBB34\uC2A8\s*\uC694\uC77C|\uC694\uC77C|\uB0A0\uC9DC|\uC774\uBC88\s*(?:\uC8FC|\uB2EC|\uC6D4|\uB144)|\uC9C0\uB09C\s*(?:\uC8FC|\uB2EC|\uC6D4|\uB144)|\uB2E4\uC74C\s*(?:\uC8FC|\uB2EC|\uC6D4|\uB144)|\uC62C\uD574|\uC791\uB144|\uB0B4\uB144|today|tomorrow|yesterday|recently|current\s+(?:date|time)|what\s+(?:date|time)|which\s+day|weekday|this\s+(?:week|month|year)|last\s+(?:week|month|year)|next\s+(?:week|month|year))/i.test(text);
 }
 
 function promptNeedsTimeReminder(content) {
     const text = temporalPromptText(content);
     if (!text) return false;
-    return /(?:현재\s*(?:시간|시각)|지금\s*(?:몇\s*시|시간)|몇\s*시|시각|시간|current\s+time|what\s+time|time\s+is\s+it)/i.test(text);
+    return /(?:\uD604\uC7AC\s*(?:\uC2DC\uAC04|\uC2DC\uAC01)|\uC9C0\uAE08\s*(?:\uBA87\s*\uC2DC|\uC2DC\uAC04)|\uBA87\s*\uC2DC|\uC2DC\uAC01|\uC2DC\uAC04|current\s+time|what\s+time|time\s+is\s+it)/i.test(text);
 }
 
 export function buildCurrentTimeBlock(content) {

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -34,6 +34,27 @@ import { getAgentRuntimeSync, warnAgentRuntimeResolveFailureOnce } from './agent
 import { mintSessionId } from './session-id.mjs';
 import { providerCacheKey } from './provider-cache-key.mjs';
 
+function buildSessionProviderCacheOpts(providerName, sessionId, agent = null) {
+    // Keep this in sync with createSession's provider-cache policy: only
+    // explicit-breakpoint providers get BP cache opts here; OpenAI/key-prefix
+    // providers use promptCacheKey and request-time strategy instead.
+    if (cacheCapabilityForProvider(providerName) !== 'explicit-breakpoint') return null;
+    try {
+        let autoClear = null;
+        if (!agent || agent === 'lead') {
+            const loadedConfig = loadConfig({ secrets: false });
+            const normalizedAutoClear = normalizeAutoClearConfig(loadedConfig?.autoClear);
+            autoClear = {
+                ...normalizedAutoClear,
+                idleMs: resolveAutoClearIdleMs(loadedConfig, providerName),
+            };
+        }
+        return buildProviderCacheOpts(providerName, sessionId, agent, { autoClear });
+    } catch {
+        return null;
+    }
+}
+
 // --- agent spawn (createSession) ---
 // opts can pass either a `preset` object (from config.presets) or raw provider/model.
 // Preset shape: { name, provider, model, effort?, fast?, tools? }
@@ -107,22 +128,7 @@ export function createSession(opts) {
     // cacheRetention:'24h' shape) were never exercised by createSession
     // before this change, and are left untouched to avoid altering live
     // OpenAI/other-provider request shape as a side effect of this fix.
-    if (!providerCacheOpts && cacheCapabilityForProvider(providerName) === 'explicit-breakpoint') {
-        try {
-            let autoClear = null;
-            if (!opts.agent || opts.agent === 'lead') {
-                const loadedConfig = loadConfig({ secrets: false });
-                const normalizedAutoClear = normalizeAutoClearConfig(loadedConfig?.autoClear);
-                autoClear = {
-                    ...normalizedAutoClear,
-                    idleMs: resolveAutoClearIdleMs(loadedConfig, providerName),
-                };
-            }
-            providerCacheOpts = buildProviderCacheOpts(providerName, id, opts.agent, { autoClear });
-        } catch {
-            providerCacheOpts = null;
-        }
-    }
+    if (!providerCacheOpts) providerCacheOpts = buildSessionProviderCacheOpts(providerName, id, opts.agent);
     const messages = [];
     const ownerIsAgent = isAgentOwner(opts.owner);
     const resolvedAgent = opts.agent || opts.role || profile?.taskType || null;
@@ -425,6 +431,8 @@ export function updateSessionRoute(id, route = {}) {
         || (route.model && route.model !== previousModel);
     if (routeChanged) {
         const now = Date.now();
+        session.promptCacheKey = providerCacheKey(session.provider);
+        session.providerCacheOpts = buildSessionProviderCacheOpts(session.provider, session.id, session.agent) || null;
         session.lastInputTokens = 0;
         session.lastOutputTokens = 0;
         session.lastCachedReadTokens = 0;

package/src/runtime/agent/orchestrator/session/result-classification.mjs

@@ -8,6 +8,8 @@
  *
  * Matches documented tool-return error conventions:
  *   "Error: ..."      — Node/MCP tool errors (grep, find_symbol, read, code_graph, etc.)
+ *   "Error: [shell-tool-failed] ..." — shell tool/control-plane failure
+ *   "Error: [shell-run-failed] ..."  — shell command process failure
  *   "Error [code N]:" — structured builtin tool errors
  *   "[error ..."      — bracketed error format
  *   "[exit code: ..." — bash non-zero exit

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

@@ -96,6 +96,9 @@ export async function processToolBatch(ctx) {
             if (isBuiltinTool(call.name)) {
                 call.name = canonicalizeBuiltinToolName(call.name);
             }
+            // Per-call cross-turn signature, computed at most once (lazily, only
+            // when the call is eager — both consumer sites are eager-gated).
+            let _ctSig = null;
             if (_duplicateCallIds.has(call.id)) {
                 const _firstId = _dupFirstId.get(call.id);
                 const _stub = `[intra-turn-dedup] identical read-only \`${call.name}\` call was already executed in this same assistant turn as tool_use_id=${_firstId}. The first call's tool_result is in context immediately above; skipping re-execution to save tokens. If you needed a different slice of the file, narrow the next call (different path / offset / limit / pattern) so it has a distinct signature.`;
@@ -113,7 +116,7 @@ export async function processToolBatch(ctx) {
             // escalation tail once the session has emitted 5+ dedup stubs total.
             // Never applies to write/bash/MCP/skill tools (not eager-dispatchable).
             if (isEagerDispatchable(call.name, tools)) {
-                const _ctSig = crossTurnSignature(call.name, call.arguments);
+                _ctSig = crossTurnSignature(call.name, call.arguments);
                 const _prior = crossTurnCalls.get(_ctSig);
                 if (_prior && _prior.firstIteration < iterations) {
                     _prior.count += 1;
@@ -576,7 +579,7 @@ export async function processToolBatch(ctx) {
                 if (_executeOk) {
                     const _isEager = isEagerDispatchable(call.name, tools);
                     if (_isEager) {
-                        const _ctSig = crossTurnSignature(call.name, call.arguments);
+                        if (_ctSig === null) _ctSig = crossTurnSignature(call.name, call.arguments);
                         if (!crossTurnCalls.has(_ctSig)) {
                             crossTurnCalls.set(_ctSig, { count: 1, firstIteration: iterations });
                             if (crossTurnCalls.size > crossTurnCap) {

package/src/runtime/agent/orchestrator/stall-policy.mjs

@@ -219,6 +219,24 @@ export const PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: 10_000, maxMs: STALL_WARN_MS },
 );
 
+// WS-specific semantic idle window. Do NOT reuse
+// PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS here: that shared SSE default was raised to
+// ~285s to avoid false-aborting Anthropic effort-mode streams that legitimately
+// produce no deltas while thinking. The WS transport is different: a silent
+// OpenAI/xAI websocket turn can sit with only connection/metadata activity while
+// the TUI lead-turn watchdog is also 300s. If the provider waits ~285-300s
+// before surfacing the stall, the UI watchdog often wins and the user only sees
+// "Turn timed out after 300s" instead of a provider retry/fallback.
+//
+// Keep WS hangs bounded well below the TUI watchdog while still allowing normal
+// long reasoning streams that emit reasoning/text/tool deltas (those reset this
+// timer). Env-overridable for experiments.
+export const PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS = resolveTimeoutMs(
+    ['MIXDOG_PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS', 'MIXDOG_PROVIDER_WS_OUTPUT_IDLE_TIMEOUT_MS'],
+    120_000,
+    { minMs: 10_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
 // First retry has a small floor (250ms) instead of 0ms: an immediate reissue on
 // a transient 5xx burst lets parallel workers thundering-herd the backend in
 // lockstep (jitter alone can't decluster a 0ms base). Subsequent steps keep the

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

@@ -168,10 +168,15 @@ function _prependDestructiveWarning(command, text) {
     return `${warnings.map((w) => `⚠️ ${w}`).join('\n')}\n${text}`;
 }
 
+export function formatShellToolFailure(message) {
+    const text = String(message ?? '').replace(/^Error:\s*/i, '').trim() || 'shell tool failed';
+    return `Error: [shell-tool-failed] ${text}`;
+}
+
 export async function executeBashTool(args, workDir, options = {}) {
     const requestedCwd = args.cwd ?? args.workdir;
     const cwdResult = resolveOptionalCwd(requestedCwd, workDir);
-    if (cwdResult.error) return cwdResult.error;
+    if (cwdResult.error) return formatShellToolFailure(cwdResult.error);
     // Session cwd carry-over (no live shell): when the model
     // passes an explicit cwd it wins and updates the store on the next probe;
     // otherwise reuse the last stored cwd for this session if it still exists.
@@ -199,7 +204,7 @@ export async function executeBashTool(args, workDir, options = {}) {
         // persistent:true. Run the full sweep here so both paths share the
         // same blocklist before dispatch.
         const _policyBlock = checkExecPolicyMessage(_rawCmd);
-        if (_policyBlock) return _policyBlock;
+        if (_policyBlock) return formatShellToolFailure(_policyBlock);
     }
 
     // An empty-string session_id is NOT a persistent-session request: `typeof
@@ -208,7 +213,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     // error, which models then retry in a loop. Require a non-blank id.
     if (args.persistent === true || (typeof args.session_id === 'string' && args.session_id.trim().length > 0)) {
         if (process.platform === 'win32') {
-            return 'Error: persistent shell sessions are disabled on Windows native-shell mode; run one-shot PowerShell commands without persistent/session_id.';
+            return formatShellToolFailure('persistent shell sessions are disabled on Windows native-shell mode; run one-shot PowerShell commands without persistent/session_id.');
         }
         const { executeBashSessionTool } = await import('../bash-session.mjs');
         let persistAbort = null;
@@ -227,7 +232,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     }
 
     let command = args.command;
-    if (!command) return 'Error: command is required';
+    if (!command) return formatShellToolFailure('command is required');
 
     // Resolve the shell up front so shell-type-specific handling (PS-only wmic
     // rewrite, PS UTF-8 prefix) can gate on it. kind 'default' is byte-identical
@@ -238,9 +243,9 @@ export async function executeBashTool(args, workDir, options = {}) {
     const resolvedSpec = resolveShellFor(shellKind);
     if (!resolvedSpec) {
         if (shellKind === 'bash') {
-            return "Error: Git Bash not found — install Git for Windows or omit shell:'bash'.";
+            return formatShellToolFailure("Git Bash not found — install Git for Windows or omit shell:'bash'.");
         }
-        return "Error: pwsh (PowerShell) not found — install PowerShell or omit shell:'powershell'.";
+        return formatShellToolFailure("pwsh (PowerShell) not found — install PowerShell or omit shell:'powershell'.");
     }
 
     // wmic→PowerShell rewrite is PowerShell-only; never mangle a command bound
@@ -251,7 +256,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     const wmicRewrite = resolvedSpec.shellType === 'powershell'
         ? maybeRewriteWmicProcessCommand(command)
         : null;
-    if (wmicRewrite?.error) return `Error: ${wmicRewrite.error}`;
+    if (wmicRewrite?.error) return formatShellToolFailure(wmicRewrite.error);
     if (wmicRewrite?.command) command = wmicRewrite.command;
 
     // PowerShell hygiene preflight (Windows PS-only; POSIX no-op): losslessly
@@ -262,19 +267,19 @@ export async function executeBashTool(args, workDir, options = {}) {
         shellType: resolvedSpec.shellType,
         shellName: resolvedSpec.shell,
     });
-    if (psHygiene.block) return psHygiene.block;
+    if (psHygiene.block) return formatShellToolFailure(psHygiene.block);
     command = psHygiene.command;
 
     const _execPolicyBlock = checkExecPolicyMessage(command);
     if (_execPolicyBlock) {
-        return _execPolicyBlock;
+        return formatShellToolFailure(_execPolicyBlock);
     }
 
     let shellEffects;
     try {
         shellEffects = await analyzeShellCommandEffects(command, bashWorkDir);
     } catch (err) {
-        return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+        return formatShellToolFailure(normalizeErrorMessage(err instanceof Error ? err.message : String(err)));
     }
     // Keep foreground commands on a long tool-owned timeout. The MCP dispatch
     // layer must not add a shorter fallback ceiling when timeout is omitted.
@@ -314,7 +319,7 @@ export async function executeBashTool(args, workDir, options = {}) {
             : Math.min(timeoutMs, wmicRewrite?.timeoutMs || MAX_BASH_TIMEOUT_MS));
     const mergeStderr = args.merge_stderr === true;
     const longForegroundHint = foregroundLongCommandHint(command, timeout, { ...args, run_in_background: runInBackground });
-    if (longForegroundHint) return longForegroundHint;
+    if (longForegroundHint) return formatShellToolFailure(longForegroundHint);
     // Auto-background threshold. Reference-CLI parity: sync commands run to
     // their timeout without any default auto-promotion, so the default is 0
     // (disabled) for ALL callers. It is an explicit opt-in only: set
@@ -347,7 +352,7 @@ export async function executeBashTool(args, workDir, options = {}) {
             try {
                 wrappedCommand = await wrapCommandWithSnapshot(shell, command);
             } catch (wrapErr) {
-                return `Error: shell snapshot wrapper failed — ${normalizeErrorMessage(wrapErr instanceof Error ? wrapErr.message : String(wrapErr))}`;
+                return formatShellToolFailure(`shell snapshot wrapper failed — ${normalizeErrorMessage(wrapErr instanceof Error ? wrapErr.message : String(wrapErr))}`);
             }
         } else {
             wrappedCommand = command;
@@ -367,7 +372,7 @@ export async function executeBashTool(args, workDir, options = {}) {
                 // claude.exe pid (server-main threads callerSession.clientHostPid).
                 clientHostPid: options?.clientHostPid,
             });
-            if (job && job.error) return `Error: ${job.error}`;
+            if (job && job.error) return formatShellToolFailure(job.error);
             let task;
             try {
                 task = registerBackgroundTask({
@@ -395,7 +400,7 @@ export async function executeBashTool(args, workDir, options = {}) {
                 });
             } catch (err) {
                 try { killShellJob(job.jobId); } catch { /* best effort cleanup */ }
-                return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+                return formatShellToolFailure(normalizeErrorMessage(err instanceof Error ? err.message : String(err)));
             }
             // Wire a one-shot completion push so the dispatching session learns
             // the background task finished (no polling tool is auto-driven). The
@@ -525,7 +530,9 @@ export async function executeBashTool(args, workDir, options = {}) {
             : (result.killed ? 'SIGKILL' : (result.signal || null));
         const exitCode = signal ? null : result.exitCode;
         const benignExitOne = _isBenignSearchExitOne(command, exitCode, signal, stderr);
-        const isReallyErrored = !!signal || (exitCode !== 0 && exitCode !== null && !benignExitOne);
+        const shellToolFailed = result.failurePhase === 'tool' || !!result.outputCaptureError;
+        const shellRunFailed = !shellToolFailed && (!!signal || (exitCode !== 0 && exitCode !== null && !benignExitOne));
+        const isReallyErrored = shellToolFailed || shellRunFailed;
         const _driftNote = '';
         // Distinct timeout marker so callers see "killed by timeout after Nms"
         // vs an external signal (e.g. user Ctrl-C, OOM kill). result.timedOut
@@ -538,11 +545,16 @@ export async function executeBashTool(args, workDir, options = {}) {
         const timeoutHint = result.timedOut
             ? ` — command killed after ${timeout} ms; if it legitimately needs longer, retry with a larger timeout`
             : '';
-        const statusMarker = result.timedOut
-            ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]${timeoutHint}`
-            : (signal
-                ? `[signal: ${signal}]`
-                : (isReallyErrored ? `[exit code: ${exitCode}]` : ''));
+        const statusDetail = shellToolFailed
+            ? `[${result.outputCaptureError ? 'output capture failed' : (result.failureReason || 'tool failed')}]`
+            : (result.timedOut
+                ? `[timeout: ${timeout}ms signal: ${signal || 'SIGTERM'}]${timeoutHint}`
+                : (signal
+                    ? `[signal: ${signal}]`
+                    : (shellRunFailed ? `[exit code: ${exitCode}]` : '')));
+        const statusMarker = shellToolFailed
+            ? `[shell-tool-failed] ${statusDetail}`
+            : (shellRunFailed ? `[shell-run-failed] ${statusDetail}` : '');
         const errorPrefix = isReallyErrored ? 'Error: ' : '';
         if (mergeStderr) {
             // Post-exit concatenation. True chunk-level interleaving would
@@ -569,6 +581,9 @@ export async function executeBashTool(args, workDir, options = {}) {
             const sizeKb = Math.round((result.stderrFileSize || 0) / 1024);
             spillBlock += `\n[stderr: ${normalizeOutputPath(result.stderrPath)} (${sizeKb} KB)]`;
         }
+        if (result.outputCaptureError) {
+            spillBlock += `\n[tool capture error: ${normalizeErrorMessage(result.outputCaptureError?.message || String(result.outputCaptureError))}]`;
+        }
         const warningBlock = [
             wmicRewrite?.note || '',
         ].filter(Boolean).join('\n');

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

@@ -31,7 +31,7 @@ function _shellMaxTimeoutMs() {
 // the process lifetime, so this is evaluated once at module load.
 const _shellSyntaxCheat =
     process.platform === 'win32'
-        ? ' PowerShell: grep→Select-String, tail→Get-Content -Tail, head→Get-Content -TotalCount, /c/→C:\\, && 미지원 시 ; 사용, $PID 예약.'
+        ? ' PowerShell: grep→Select-String, tail→Get-Content -Tail, head→Get-Content -TotalCount, /c/→C:\\, if && is unsupported use ;, $PID is reserved.'
         : '';
 
 export const BUILTIN_TOOLS = [
@@ -109,7 +109,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Exact text/regex in a verified file/dir scope. Unknown scope → find/glob first. files_with_matches/count for broad anchors, content_with_context for narrow answers.',
+        description: 'Exact text/regex in verified scope. Unknown path/name → find first; no path "." + guessed src/**. Broad: files_with_matches/count; narrow: content_with_context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -125,14 +125,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified file or dir. Array = several scopes.',
+                    description: 'Verified file/dir only; unknown → find first.',
                 },
                 glob: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Glob filter to narrow scope.',
+                    description: 'Glob filter; no guessed src/** under path ".".',
                 },
                 output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad: files_with_matches/count; narrow: content_with_context.' },
                 head_limit: { type: 'number', minimum: 0, description: 'Max results.' },
@@ -148,7 +148,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by exact glob from verified roots. Batch patterns and roots as arrays in one call.',
+        description: 'Exact glob from verified roots. Unknown root/name → find first; no path "." + guessed src/**. Batch arrays.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -164,7 +164,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Base directory/directories. Batch multiple roots as path[] in one call.',
+                    description: 'Verified base dir(s); unknown → find first. Batch path[].',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip entries.' },
@@ -176,7 +176,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by partial path/name, including dot-directories. Use for unverified path/name guesses; returns verified paths. Batch query[].',
+        description: 'Partial path/name lookup incl dot dirs; verify roots before grep/glob. Batch query[].',
         inputSchema: {
             type: 'object',
             properties: {