mixdog 0.9.10 → 0.9.11

package/src/runtime/agent/orchestrator/providers/openai-compat-xai.mjs

@@ -66,11 +66,30 @@ export function xaiResponsesCacheRouting(opts, params, rawTools, model) {
     const providerKey = resolveProviderCacheKey(opts, 'xai');
     const prefixSeed = xaiPrefixSeed({ opts, params, rawTools, model });
     const prefixHash = traceHash(prefixSeed);
+    // Optional lane sharding (OpenAI prompt-caching guidance: keep each
+    // prefix+prompt_cache_key combo under ~15 RPM). When lane shards are
+    // enabled (MIXDOG_XAI_RESPONSES_CACHE_LANE_SHARDS=N or lane auto), mix the
+    // assigned slot into the routing seed so sessions spread across N server
+    // cache keys instead of overflowing one. Slot is derived from a hash of
+    // the session id (NOT in-process round-robin: headless workers run one
+    // session per process, where round-robin degenerates to slot 0 for
+    // everyone). Default stays a single shared key (lane disabled) —
+    // identical seed/key to before.
+    const lane = xaiResponsesPromptCacheLane(opts, null, { prefixHash, ownerSessionHash: sessionId ? traceHash(sessionId) : null });
+    const laneEnabled = lane?.enabled === true;
+    const laneShards = Number.isFinite(Number(lane?.shards)) && Number(lane.shards) > 0 ? Number(lane.shards) : 0;
+    const explicitSlot = Number(opts?.promptCacheLaneSlot ?? opts?.xaiCacheLaneSlot);
+    const laneSlot = Number.isFinite(explicitSlot) && explicitSlot >= 0
+        ? (laneShards > 0 ? Math.floor(explicitSlot) % laneShards : Math.floor(explicitSlot))
+        : (laneShards > 0
+            ? createHash('sha256').update(sessionId || String(process.pid)).digest().readUInt32BE(0) % laneShards
+            : Number.isFinite(Number(lane?.slot)) ? Number(lane.slot) : 0);
     const routingSeed = stableTraceStringify({
         scope: 'xai-responses-prefix-v1',
         providerKey: String(providerKey),
         model: model || null,
         prefixHash,
+        ...(laneEnabled ? { laneSlot } : {}),
     });
     return {
         key: deterministicUuidFromKey(routingSeed),
@@ -78,6 +97,10 @@ export function xaiResponsesCacheRouting(opts, params, rawTools, model) {
         seedHash: traceHash(routingSeed),
         prefixHash,
         ownerSessionHash: sessionId ? traceHash(sessionId) : null,
+        ...(laneEnabled ? {
+            laneIndex: laneSlot,
+            activeLanes: Number.isFinite(Number(lane?.shards)) && Number(lane.shards) > 0 ? Number(lane.shards) : null,
+        } : {}),
     };
 }
 

package/src/runtime/agent/orchestrator/session/loop/deferred-call-through.mjs

@@ -0,0 +1,79 @@
+// Deferred catalog call-through: inactive catalog tool_use → discovery bookkeeping
+// then normal executeTool routing (runtime errors only; no pre-dispatch schema).
+import { clean } from '../../../../../session-runtime/session-text.mjs';
+import { isReadonlySelectable, selectDeferredTools } from '../../../../../session-runtime/tool-catalog.mjs';
+
+/** Skill-list plumbing only; mutation/MCP/builtins must use the catalog+mode gate. */
+const INACTIVE_INFRA_BYPASS = new Set(['skills_list', 'skill_view']);
+
+function isActiveSessionTool(session, name) {
+    const key = clean(name);
+    if (!key || !Array.isArray(session?.tools)) return false;
+    return session.tools.some((tool) => clean(tool?.name) === key);
+}
+
+function lookupDeferredCatalogTool(session, name) {
+    const catalog = Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : [];
+    const key = clean(name);
+    if (!key) return null;
+    for (const tool of catalog) {
+        const n = clean(tool?.name);
+        if (n === key || n.toLowerCase() === key.toLowerCase()) return tool;
+    }
+    return null;
+}
+
+export function isOnDeferredToolSurface(session, name) {
+    if (!session) return false;
+    return isActiveSessionTool(session, name) || lookupDeferredCatalogTool(session, name) !== null;
+}
+
+export function toolExecutesWhenInactive(name) {
+    return INACTIVE_INFRA_BYPASS.has(name);
+}
+
+function resolveDeferredSelectMode(session) {
+    const spec = session?.toolSpec;
+    if (spec == null || spec === '') return null;
+    if (spec === 'readonly') return 'readonly';
+    if (spec === 'full' || spec === 'mcp') return 'full';
+    if (Array.isArray(spec)) {
+        if (!spec.length) return null;
+        if (spec.includes('full')) return 'full';
+        if (spec.includes('tools:readonly')) return 'readonly';
+        return 'full';
+    }
+    return null;
+}
+
+function denyDeferredCallThrough(message) {
+    return { deny: message };
+}
+
+/**
+ * Inactive deferred catalog hits: readonly/mode gate + promoteToActive, or deny.
+ * Returns null when not applicable (not in catalog, already active, infra allowlist).
+ */
+export function prepareDeferredToolCallThrough(sessionRef, name, _args) {
+    if (!sessionRef) return null;
+    const tool = lookupDeferredCatalogTool(sessionRef, name);
+    if (!tool) return null;
+    if (isActiveSessionTool(sessionRef, name)) return null;
+    if (toolExecutesWhenInactive(name)) return null;
+
+    const toolLabel = clean(tool.name) || clean(name) || 'tool';
+    const resolvedMode = resolveDeferredSelectMode(sessionRef);
+    if (resolvedMode === null) {
+        if (!isReadonlySelectable(tool)) {
+            return denyDeferredCallThrough(
+                `Error: tool "${toolLabel}" is deferred and cannot be auto-loaded without a resolved tool mode; use tool_search or load it explicitly.`,
+            );
+        }
+    } else if (resolvedMode === 'readonly' && !isReadonlySelectable(tool)) {
+        return denyDeferredCallThrough(`Error: tool "${toolLabel}" is not available in readonly mode`);
+    }
+
+    const selectMode = resolvedMode === null ? 'readonly' : resolvedMode;
+    selectDeferredTools(sessionRef, [toolLabel], selectMode, { promoteToActive: true });
+    return null;
+}

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

@@ -3,7 +3,7 @@
 // shell/apply_patch/builtin/external-adapter) through before/after hooks and the
 // scoped-cache outcome bookkeeping. No behavior change: bodies are verbatim from
 // loop.mjs, re-exported via the facade so existing importers keep working.
-import { executeMcpTool, isMcpTool, mcpToolHasField } from '../../mcp/client.mjs';
+import { executeMcpTool, isMcpTool, isRegisteredMcpTool, mcpToolHasField } from '../../mcp/client.mjs';
 import { executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool, isExternalAdapterTool } from '../../tools/builtin.mjs';
 import { executeBashSessionTool } from '../../tools/bash-session.mjs';
 import { executePatchTool } from '../../tools/patch.mjs';
@@ -21,6 +21,7 @@ import {
     buildAgentBashSessionArgs,
     resolvePreToolAskApproval,
 } from './tool-helpers.mjs';
+import { isOnDeferredToolSurface, prepareDeferredToolCallThrough } from './deferred-call-through.mjs';
 
 let codeGraphRuntimePromise = null;
 async function executeCodeGraphToolLazy(name, args, cwd, signal = null, options = {}) {
@@ -125,6 +126,8 @@ export async function executeTool(name, args, cwd, callerSessionId, sessionRef,
     const afterToolHook = typeof executeOpts.afterToolHook === 'function'
         ? executeOpts.afterToolHook
         : sessionRef?.afterToolHook;
+    const deferredPrep = prepareDeferredToolCallThrough(sessionRef, name, args);
+    if (deferredPrep?.deny) return deferredPrep.deny;
     const __result = await (async () => {
     if (name === 'Skill') {
         return viewSkill(cwd, args?.name);
@@ -136,6 +139,9 @@ export async function executeTool(name, args, cwd, callerSessionId, sessionRef,
         return viewSkill(cwd, args?.name);
     }
     if (isMcpTool(name)) {
+        if (!isOnDeferredToolSurface(sessionRef, name) && !isRegisteredMcpTool(name)) {
+            return formatUnknownBuiltinToolMessage(name, args, 'tool');
+        }
         // 24h trace data shows ~24% of external MCP calls are cwd-sensitive
         // (bash / grep / read / list / glob etc.) but the worker session's
         // cwd was previously dropped here. Inject cwd only when the tool's

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

@@ -4,7 +4,13 @@
 import { isMcpTool } from '../../mcp/client.mjs';
 import { isBuiltinTool } from '../../tools/builtin.mjs';
 import { isInternalTool } from '../../internal-tools.mjs';
-import { collectSkillsCached, loadSkillResource, buildSkillToolEnvelope } from '../../context/collect.mjs';
+import {
+    collectSkillsCached,
+    loadSkillResource,
+    buildSkillToolEnvelope,
+    filterSkillsExcludingDisabled,
+    isSkillDisabled,
+} from '../../context/collect.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 
 // Eager-dispatch: tools with readOnlyHint:true in their declaration are safe
@@ -37,12 +43,13 @@ export function getToolKind(name) {
     return 'builtin';
 }
 export function buildSkillsListResponse(cwd) {
-    const skills = collectSkillsCached(cwd);
+    const skills = filterSkillsExcludingDisabled(collectSkillsCached(cwd));
     const entries = skills.map(s => ({ name: s.name, description: s.description || '' }));
     return JSON.stringify({ skills: entries });
 }
 export function viewSkill(cwd, name) {
     if (!name) return 'Error: skill name is required';
+    if (isSkillDisabled(name)) return `Error: skill "${name}" is disabled`;
     const res = loadSkillResource(name, cwd);
     if (!res) return `Error: skill "${name}" not found`;
     // Return the general tool envelope: the model-visible tool_result is the

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

@@ -13,7 +13,7 @@ import {
 } from './compact.mjs';
 import { estimateMessagesTokens, estimateTranscriptContextUsage } from './context-utils.mjs';
 import { executeInternalTool } from '../internal-tools.mjs';
-import { collectSkillsCached, buildSkillManifest, composeSystemPrompt } from '../context/collect.mjs';
+import { collectPromptSkillsCached, buildSkillManifest, composeSystemPrompt } from '../context/collect.mjs';
 import { saveSession, saveSessionAsync, loadSession, listStoredSessionSummaries, sweepStaleSessions, markSessionClosed, bumpSessionGeneration, setLiveSession } from './store.mjs';
 import { clearReadDedupSession, tryPrefetchCached, setPrefetchCached } from './read-dedup.mjs';
 import { clearOffloadSession } from './tool-result-offload.mjs';
@@ -636,7 +636,7 @@ export function createSession(opts) {
     // maintenance roles are deliberately narrowed away from the Skill tool.
     // Do not leak a Skill manifest into those hidden prompts when no Skill()
     // loader is available.
-    const skills = (opts.skipSkills || hiddenAgent) ? [] : collectSkillsCached(opts.cwd);
+    const skills = (opts.skipSkills || hiddenAgent) ? [] : collectPromptSkillsCached(opts.cwd);
 
     // BP1 is shared tool policy (+ compact skill manifest in compose). BP2 is
     // role/system rules. User-defined schedules/webhooks ride as normal user
@@ -1785,7 +1785,7 @@ export async function resumeSession(sessionId, preset) {
     // createSession so resume and spawn produce identical BP_1 shapes.
     const oldTools = session.tools || [];
     const ownerIsAgent = isAgentOwner(session);
-    const skills = ownerIsAgent ? [] : collectSkillsCached(session.cwd);
+    const skills = ownerIsAgent ? [] : collectPromptSkillsCached(session.cwd);
     let toolSpec = ownerIsAgent ? 'full' : (preset || session.preset || 'full');
     if (session.profileId && _agentRuntimeApi?.getProfile) {
         try {

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

@@ -9,7 +9,7 @@
 // callers may pass either spelling (e.g. `glob` alias for grep, or
 // `file_path` alias for read.path).
 
-import { coerceShapeFlex, hasGlobMagic } from './path-utils.mjs';
+import { coerceReadFamilyPathArg, coerceShapeFlex, hasGlobMagic } from './path-utils.mjs';
 
 const MAX_INT = 100000;
 // Explicit grep context should be large enough to frame a function/block without
@@ -368,11 +368,11 @@ function guardRead(a) {
         return 'Error: read requires "path" (or alias file_path).';
     }
     // Some providers/models send a batched path array as a JSON string despite
-    // the schema. The executor already accepts that shape via coerceShapeFlex(),
-    // but validation runs first; apply the same lossless shape coercion here so
-    // valid batched reads do not waste a retry turn.
+    // the schema (or path:"[]" meaning cwd). The executor coerces via
+    // coerceReadFamilyPathArg(); mirror that here so validation does not reject
+    // shapes the executor would absorb.
     if (hasOwn(a, 'path')) {
-        a.path = coerceShapeFlex(a.path);
+        a.path = coerceReadFamilyPathArg(a.path);
     }
     // path can be string | string[] | object[]; file_path is string
     if (hasOwn(a, 'path')) {

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

@@ -12,7 +12,7 @@
 // adapter expects — the caller (builtin.mjs default: case) falls back to
 // the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
 import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
-import { dirname, sep } from 'node:path';
+import { dirname } from 'node:path';
 import { atomicWrite } from './atomic-write.mjs';
 import { assertPathsReachable } from './fs-reachability.mjs';
 import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath } from './path-utils.mjs';
@@ -102,25 +102,6 @@ function guardRealTarget(fullPath) {
     return null;
 }
 
-// Write containment — mirrors apply_patch's realBase check: the REAL resolved
-// target (symlinks flattened, create-mode suffix re-attached lexically) must
-// stay inside the REAL workDir. A lexically-inside path whose ancestor
-// symlink/junction lands outside the project must not be writable through
-// this adapter surface (apply_patch refuses the same shape).
-function guardBaseContainment(fullPath, workDir) {
-    let realBase;
-    try { realBase = realpathSync(workDir); } catch { return null; }
-    const nearest = realpathNearestExisting(fullPath);
-    if (!nearest) return null;
-    const realResolved = nearest.real + fullPath.slice(nearest.probe.length);
-    const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
-    const baseWithSep = realBase.endsWith(sep) ? realBase : realBase + sep;
-    if (fold(realResolved) !== fold(realBase) && !fold(realResolved).startsWith(fold(baseWithSep))) {
-        return `Error: cannot write outside the working directory: ${normalizeOutputPath(realResolved)} escapes ${normalizeOutputPath(realBase)}`;
-    }
-    return null;
-}
-
 async function resolveTargetPath(args, workDir) {
     const raw = args?.path ?? args?.file_path;
     if (typeof raw !== 'string' || raw.length === 0) return null;
@@ -138,8 +119,6 @@ async function resolveTargetPath(args, workDir) {
     catch (e) { return { error: `Error: ${e?.message || e}` }; }
     const realGuardErr = guardRealTarget(full);
     if (realGuardErr) return { error: realGuardErr };
-    const containErr = guardBaseContainment(full, workDir);
-    if (containErr) return { error: containErr };
     return { full };
 }
 

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

@@ -1,12 +1,14 @@
 import { readdirSync } from 'fs';
 import { basename, relative } from 'path';
 import {
+    coerceReadFamilyPathArg,
     extractGlobBaseDirectory,
     hasGlobMagic,
     normalizeInputPath,
     normalizeOutputPath,
     resolveAgainstCwd,
 } from './path-utils.mjs';
+import { tryReadFamilyEnoentRedirect } from './search-path-diagnostics.mjs';
 import { normalizeErrorMessage } from './path-diagnostics.mjs';
 import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component } from './device-paths.mjs';
 import {
@@ -37,6 +39,19 @@ const LIST_WALK_TIMEOUT_MS = 20_000;
 const LIST_ABSOLUTE_CAP = 50_000;
 
 /** undefined / invalid / negative → defaultCap; 0 = no page cap (absolute caps still apply). */
+async function readFamilyPathEnoentOrError(workDir, fullPath, inputPath, args, options, err, rerunTool) {
+    const redirected = await tryReadFamilyEnoentRedirect({
+        workDir,
+        resolvedPath: fullPath,
+        requestedPath: inputPath,
+        errCode: err?.code,
+        options,
+        rerun: (target, opts) => rerunTool({ ...args, path: target }, workDir, opts),
+    });
+    if (redirected) return redirected;
+    return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+}
+
 function normalizeListHeadLimit(raw, defaultCap) {
     if (raw === undefined || raw === null || raw === '') return defaultCap;
     const n = Number(raw);
@@ -60,6 +75,7 @@ function listGuardPath(p) {
 }
 
 export async function executeListTool(args, workDir, options = {}) {
+    args.path = coerceReadFamilyPathArg(args.path, workDir);
     if (Array.isArray(args.path)) {
         const list = [...new Set(args.path.map((p) => (typeof p === 'string' ? p.trim() : '')).filter((p) => p.length > 0))];
         const capped = list.length > 10;
@@ -120,7 +136,9 @@ export async function executeListTool(args, workDir, options = {}) {
     catch (err) { return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`; }
     let st;
     try { st = getCachedReadOnlyStat(fullPath); }
-    catch (err) { return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`; }
+    catch (err) {
+        return await readFamilyPathEnoentOrError(workDir, fullPath, inputPath, args, options, err, executeListTool);
+    }
     if (!st.isDirectory()) return `Error: not a directory — ${normalizeOutputPath(fullPath)}`;
 
     const rows = [];
@@ -251,7 +269,9 @@ export async function executeTreeTool(args, workDir, options = {}) {
     catch (err) { return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`; }
     let st;
     try { st = getCachedReadOnlyStat(fullPath); }
-    catch (err) { return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`; }
+    catch (err) {
+        return await readFamilyPathEnoentOrError(workDir, fullPath, inputPath, args, options, err, executeListTool);
+    }
     if (!st.isDirectory()) return `Error: not a directory — ${normalizeOutputPath(fullPath)}`;
     const lines = [`${normalizeOutputPath(fullPath)}/`];
     const prefixStack = [''];
@@ -407,6 +427,7 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
 }
 
 export async function executeFindFilesTool(args, workDir, options = {}) {
+    args.path = coerceReadFamilyPathArg(args.path, workDir);
     args.path = normalizeInputPath(args.path);
     let inputPath = args.path || '.';
     let namePattern = typeof args.name === 'string' ? args.name : null;
@@ -511,7 +532,9 @@ export async function executeFindFilesTool(args, workDir, options = {}) {
     catch (err) { return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`; }
     let rootStat;
     try { rootStat = getCachedReadOnlyStat(fullPath); }
-    catch (err) { return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`; }
+    catch (err) {
+        return await readFamilyPathEnoentOrError(workDir, fullPath, inputPath, args, options, err, executeFindFilesTool);
+    }
     if (!rootStat.isDirectory()) return `Error: not a directory — ${normalizeOutputPath(fullPath)}`;
 
     const matches = [];

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

@@ -1,6 +1,6 @@
 import { homedir } from 'os';
 import { isAbsolute, relative, resolve } from 'path';
-import { realpathSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
 import { isWSL } from '../../../../shared/wsl.mjs';
 
 // Restore the on-disk casing of a path (win32 only). rg relativizes candidate
@@ -237,3 +237,31 @@ export function coerceShapeFlex(value) {
     }
     return value;
 }
+
+// JSON-stringified path arrays (path:"[]") and empty arrays mean "search cwd".
+// Bracket-shaped strings that exist on disk (e.g. a literal `[x]` directory) are
+// left untouched — JSON reinterpretation only runs after a stat miss.
+export function coerceReadFamilyPathArg(path, workDir = null) {
+    if (path === undefined || path === null || path === '') return path;
+    if (typeof path === 'string' && typeof workDir === 'string' && workDir) {
+        const trimmed = path.trim();
+        if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+            try {
+                const resolved = resolveAgainstCwd(normalizeInputPath(trimmed), workDir);
+                statSync(resolved);
+                return path;
+            } catch { /* not a literal bracket path — allow JSON coercion */ }
+        }
+    }
+    const coerced = coerceShapeFlex(path);
+    if (!Array.isArray(coerced)) return coerced;
+    const list = coerced
+        // Region objects ({path,offset,limit}) must pass through untouched —
+        // read's batch dispatcher consumes them. Only strings are trimmed.
+        .map((p) => (typeof p === 'string' ? p.trim() : p))
+        .filter((p) => (typeof p === 'string' ? p.length > 0 : (p && typeof p === 'object')));
+    if (list.length === 0) return '.';
+    // Collapse to scalar only for a lone string; a lone region object must
+    // stay an array so read's object-batch dispatcher handles it.
+    return list.length === 1 && typeof list[0] === 'string' ? list[0] : list;
+}

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

@@ -3,7 +3,7 @@ import * as fsPromises from 'fs/promises';
 import { readFile } from 'fs/promises';
 import { extname } from 'path';
 import { normalizeInputPath } from './path-utils.mjs';
-import { findFileByBasename, findBySuffixStrip } from './path-diagnostics.mjs';
+import { buildNotFoundHint, tryReadFamilyEnoentRedirect } from './search-path-diagnostics.mjs';
 import { getReadSnapshot } from './read-snapshot-runtime.mjs';
 import { snapshotCoversFullFile, statMatchesSnapshot } from './snapshot-helpers.mjs';
 import { formatBinaryReadPreview } from './binary-file.mjs';
@@ -202,24 +202,25 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     }
     if (!st) {
         const err = _statErr;
+        const redirected = await tryReadFamilyEnoentRedirect({
+            workDir,
+            resolvedPath: fullPath,
+            requestedPath: filePath,
+            errCode: err?.code,
+            options,
+            rerun: (target, opts) => executeSingleReadTool(
+                { ...args, path: target },
+                workDir,
+                readStateScope,
+                opts,
+                helpers,
+            ),
+        });
+        if (redirected) return redirected;
         const similar = findSimilarFile(fullPath);
         let hint = similar ? ` Did you mean "${normalizeOutputPath(similar)}"?` : '';
-        // Right-name / wrong-directory miss: findSimilarFile only checks the
-        // same dir. Locate the basename elsewhere in the tree and name the real
-        // path(s) directly — the route a model would otherwise reconstruct with
-        // a grep/glob storm.
         if (!similar) {
-            // Hallucinated absolute-prefix recovery first: no directory walk,
-            // stats directly (finds vendor/ paths the basename BFS skips).
-            const suffixHit = findBySuffixStrip(workDir, fullPath);
-            if (suffixHit) {
-                hint = ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". Read that path directly.`;
-            } else {
-                const elsewhere = findFileByBasename(workDir, fullPath);
-                if (elsewhere.length) {
-                    hint = ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. Read that path directly.`;
-                }
-            }
+            hint = buildNotFoundHint(workDir, fullPath, 'Read', err?.code);
         }
         const _rawMsg = err instanceof Error ? err.message : String(err);
         const _safeMsg = normalizeErrorMessage(_rawMsg, workDir);

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

@@ -5,6 +5,7 @@ import { readEntryCoalescedDiskWindow } from './read-batch.mjs';
 import { readPathStringGuardError } from './read-open.mjs';
 import { parseReadLineNumberArg } from './read-args.mjs';
 import { assertPathsReachable } from './fs-reachability.mjs';
+import { coerceReadFamilyPathArg } from './path-utils.mjs';
 
 function hasLineCoordinate(path) {
     return typeof path === 'string' && /(?:#L\d+|:\d+(?:-\d+)?(?::|$))/i.test(path);
@@ -109,7 +110,7 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
             args.offset = Math.trunc(ccOffset) - 1;
         }
     }
-    args.path = coerceShapeFlex(args.path);
+    args.path = coerceReadFamilyPathArg(args.path, workDir);
     // Reachability preflight up front (all shapes) — before readPathStringGuardError /
     // image stat, all of which can touch sync FS.
     {

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

@@ -30,6 +30,7 @@ export function buildGrepCacheKey(parts) {
         fileType,
         onlyMatching,
         pcre2,
+        withFilename,
     } = parts;
     return [
         'grep',
@@ -48,6 +49,7 @@ export function buildGrepCacheKey(parts) {
         onlyMatching ? 'o1' : 'o0',
         Array.isArray(fileType) ? fileType.join('\x01') : (fileType || ''),
         pcre2 ? 'p1' : 'p0',
+        withFilename ? 'H1' : 'H0',
     ].join('|');
 }
 
@@ -67,6 +69,7 @@ export function buildGrepRgArgs(parts) {
         onlyMatching,
         fixedStrings = false,
         pcre2 = false,
+        withFilename = false,
     } = parts;
     // `--hidden`: search dotfiles/dot-dirs (.github, .mixdog) that
     // rg skips by default. The DEFAULT_IGNORE_GLOBS below still exclude .git and
@@ -78,6 +81,7 @@ export function buildGrepRgArgs(parts) {
         rgArgs.push('--count');
     } else {
         rgArgs.push('--no-heading');
+        if (withFilename) rgArgs.push('-H');
         if (showLineNumbers) rgArgs.push('--line-number');
         if (beforeN !== null) rgArgs.push('-B', String(beforeN));
         if (afterN !== null) rgArgs.push('-A', String(afterN));

package/src/runtime/agent/orchestrator/tools/builtin/search-path-diagnostics.mjs

@@ -64,12 +64,38 @@ export function stripEmbeddedPathQuotes(p) {
 // not-found codes: EACCES/EPERM etc. keep their real failure semantics and
 // must not trigger same-basename guidance or the BFS scan.
 const NOT_FOUND_CODES = new Set(['ENOENT', 'ENOTDIR']);
+export function resolveUniqueEnoentRedirect(workDir, missingPath, errCode = 'ENOENT') {
+    if (!NOT_FOUND_CODES.has(String(errCode || 'ENOENT'))) return null;
+    const suffixHit = findBySuffixStrip(workDir, missingPath);
+    if (suffixHit) return suffixHit;
+    const elsewhere = findFileByBasename(workDir, missingPath);
+    if (elsewhere.length === 1) return elsewhere[0];
+    return null;
+}
+
+export function redirectedFromPrefix(requestedPath) {
+    return `[redirected from ${normalizeOutputPath(requestedPath)}]\n`;
+}
+
+export async function tryReadFamilyEnoentRedirect({
+    workDir,
+    resolvedPath,
+    requestedPath,
+    errCode,
+    options,
+    rerun,
+}) {
+    if (options?._enoentRedirectFrom) return null;
+    const target = resolveUniqueEnoentRedirect(workDir, resolvedPath, errCode);
+    if (!target) return null;
+    const body = await rerun(target, { ...options, _enoentRedirectFrom: resolvedPath });
+    const shown = requestedPath ?? resolvedPath;
+    return redirectedFromPrefix(shown) + body;
+}
+
 export function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'ENOENT') {
     if (!NOT_FOUND_CODES.has(String(errCode || 'ENOENT'))) return '';
-    const suffixHit = findBySuffixStrip(workDir, missingPath);
-    if (suffixHit) {
-        return ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". ${actionVerb} that path directly.`;
-    }
+    if (resolveUniqueEnoentRedirect(workDir, missingPath, errCode)) return '';
     const elsewhere = findFileByBasename(workDir, missingPath);
     if (elsewhere.length) {
         return ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. ${actionVerb} that path directly.`;