micro-models-agent 0.13.1 → 0.13.3

package/dist/modules/hallucination/confidence.js

@@ -1,13 +1,6 @@
 import { t } from "../../i18n/index";
-const UNCERTAINTY_MARKERS = [
-    "i think",
-    "maybe",
-    "probably",
-    "i believe",
-    "not sure",
-    "might be",
-];
 const MIN_CHARS = 1;
+const MIN_WORDS = 5;
 export class ConfidenceCheck {
     previousResponse = "";
     setPreviousResponse(response) {
@@ -17,6 +10,16 @@ export class ConfidenceCheck {
         if (!response || response.length < MIN_CHARS) {
             return { status: "retry", reason: t("hall.short_response") };
         }
+        // Language-agnostic: very short response with no structured content
+        const wordCount = response.split(/\s+/).filter(Boolean).length;
+        const hasStructure = /```|^\s*[-*]\s|^\s*\d+\.\s|<[^>]+>/m.test(response);
+        if (wordCount < MIN_WORDS && !hasStructure) {
+            return {
+                status: "warn",
+                reason: t("hall.short_response"),
+            };
+        }
+        // Language-agnostic: repetition detection via word overlap
         if (this.previousResponse) {
             const overlap = this.calculateOverlap(response, this.previousResponse);
             if (overlap > 0.5) {
@@ -26,13 +29,17 @@ export class ConfidenceCheck {
                 };
             }
         }
-        const lower = response.toLowerCase();
-        const foundMarkers = UNCERTAINTY_MARKERS.filter((m) => lower.includes(m));
-        if (foundMarkers.length > 0) {
-            return {
-                status: "warn",
-                reason: t("hall.uncertainty", { markers: foundMarkers.join(", ") }),
-            };
+        // Language-agnostic: very low word diversity (same words repeated)
+        const words = response.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+        if (words.length >= 10) {
+            const unique = new Set(words);
+            const diversity = unique.size / words.length;
+            if (diversity < 0.25) {
+                return {
+                    status: "warn",
+                    reason: t("hall.repetitive", { pct: Math.round((1 - diversity) * 100) }),
+                };
+            }
         }
         return { status: "pass" };
     }

package/dist/modules/hallucination/consistency.js

@@ -19,7 +19,35 @@ export class ConsistencyCheck {
         const lower = response.toLowerCase();
         for (const d of this.decisions) {
             const decisionWords = d.decision.toLowerCase().split(/\s+/).filter(w => w.length > 3);
-            const contradicts = decisionWords.some(word => lower.includes(`instead of ${word}`) || lower.includes(`not ${word}`));
+            const contradicts = decisionWords.some(word => {
+                // English patterns
+                if (lower.includes(`instead of ${word}`))
+                    return true;
+                if (lower.includes(`not ${word}`))
+                    return true;
+                if (lower.includes(`replacing ${word} with`))
+                    return true;
+                if (lower.includes(`switching to`))
+                    return true;
+                if (lower.includes(`changing from ${word}`))
+                    return true;
+                if (lower.includes(`abandoning ${word}`))
+                    return true;
+                // Russian patterns
+                if (lower.includes(`вместо ${word}`))
+                    return true;
+                if (lower.includes(`заменяя ${word}`))
+                    return true;
+                if (lower.includes(`заменяем ${word}`))
+                    return true;
+                if (lower.includes(`переключаемся на`))
+                    return true;
+                if (lower.includes(`от ${word} к`))
+                    return true;
+                if (lower.includes(`отказываемся от ${word}`))
+                    return true;
+                return false;
+            });
             if (contradicts) {
                 return {
                     status: 'warn',

package/dist/modules/hallucination/factual.js

@@ -6,6 +6,10 @@ const FILE_EXTENSIONS = new Set([
     "tsx",
     "js",
     "jsx",
+    "mjs",
+    "cjs",
+    "mts",
+    "cts",
     "json",
     "md",
     "yaml",
@@ -32,12 +36,17 @@ const FILE_EXTENSIONS = new Set([
     "cmd",
     "txt",
     "env",
+    "env.local",
+    "env.production",
     "gitignore",
     "dockerignore",
     "dockerfile",
     "makefile",
     "cmake",
     "toml",
+    "lock",
+    "config",
+    "log",
     "xml",
     "sql",
     "graphql",
@@ -45,10 +54,20 @@ const FILE_EXTENSIONS = new Set([
     "wasm",
 ]);
 const VERSION_PATTERN = /^\d+(\.\d+)*$/;
-const COMMON_WORDS = new Set(["node.js", "Node.js"]);
+const COMMON_WORDS = new Set([
+    "node.js", "Node.js",
+    "console.log", "console.error", "console.warn", "console.info",
+    "Math.floor", "Math.ceil", "Math.round", "Math.max", "Math.min",
+    "JSON.parse", "JSON.stringify",
+    "Object.keys", "Object.values", "Object.entries",
+    "Array.from", "Array.isArray",
+    "Date.now", "Date.parse",
+    "RegExp", "Promise",
+]);
 export class FactualCheck {
     knownPaths = new Set();
     createdPaths = new Set();
+    readFiles = new Set();
     baseDir = process.cwd();
     setBaseDir(dir) {
         this.baseDir = dir;
@@ -58,6 +77,8 @@ export class FactualCheck {
         const base = path.split(/[/\\]/).pop();
         if (base && base !== path)
             this.knownPaths.add(base);
+        // Track that this file was actually read by the agent
+        this.readFiles.add(base || path);
     }
     trackCreatedPath(path) {
         this.knownPaths.add(path);
@@ -73,12 +94,30 @@ export class FactualCheck {
             this.knownPaths.add(base);
         this.createdPaths.delete(path);
     }
+    /**
+     * Register file paths found in a document (e.g. structure.md, README).
+     * Files mentioned in project documentation are not hallucinations.
+     */
+    trackDocumentContent(content) {
+        // Match common path patterns in documentation
+        const pathPatterns = /(?:^|\s)([\w\-./]+\.\w{1,10})(?:\s|$|[,;)])/gm;
+        let match;
+        while ((match = pathPatterns.exec(content)) !== null) {
+            const file = match[1];
+            if (file.includes('/') || file.includes('\\')) {
+                this.knownPaths.add(file);
+            }
+            const base = file.split(/[/\\]/).pop();
+            if (base)
+                this.knownPaths.add(base);
+        }
+    }
     pathExistsOnDisk(path) {
         try {
-            if (path.startsWith("/") ||
-                path.startsWith("~") ||
-                /^[A-Za-z]:/.test(path)) {
-                return existsSync(path);
+            // Skip absolute paths — they're either system paths or outside the project.
+            // On Windows, existsSync('/...') can hang on certain paths.
+            if (path.startsWith("/") || path.startsWith("~") || /^[A-Za-z]:/.test(path)) {
+                return false;
             }
             return existsSync(join(this.baseDir, path));
         }
@@ -94,10 +133,13 @@ export class FactualCheck {
                 return false;
             if (VERSION_PATTERN.test(p))
                 return false;
-            if (p.startsWith("/"))
-                return false;
             if (COMMON_WORDS.has(p))
                 return false;
+            // Skip absolute paths — agent responses use relative paths; absolute
+            // paths are either system paths or URLs, and existsSync can hang on
+            // Windows for root-relative paths like "/page.html".
+            if (p.startsWith("/") || p.startsWith("~") || /^[A-Za-z]:/.test(p))
+                return false;
             if (this.pathExistsOnDisk(p))
                 return false;
             const ext = p.split(".").pop()?.toLowerCase() || "";

package/dist/modules/processes/registry.js

@@ -134,6 +134,12 @@ class ProcessRegistry {
         const sorted = Array.from(this.procs.values()).sort((a, b) => a.startedAt.localeCompare(b.startedAt));
         const toRemove = sorted.slice(0, sorted.length - MAX_KEPT_PROCESSES + 1);
         for (const entry of toRemove) {
+            if (entry.status === "running") {
+                const child = this.children.get(entry.id);
+                if (child) {
+                    killTree(child);
+                }
+            }
             this.procs.delete(entry.id);
             this.children.delete(entry.id);
         }

package/dist/modules/security/command-validator.js

@@ -9,6 +9,40 @@ const FALLBACK_BASH_CONFIG = {
     logCommands: true,
 };
 export const DEFAULT_BASH_CONFIG = DEFAULT_SECURITY_CONFIG?.bash || FALLBACK_BASH_CONFIG;
+/**
+ * Extract the actual base command from a shell command string.
+ * Handles path prefixes, env assignments, and sudo.
+ *
+ * Examples:
+ *   "/usr/bin/rm -rf /"           → "rm"
+ *   "sudo /usr/bin/rm file"       → "rm"
+ *   "NODE_ENV=prod node app.js"   → "node"
+ *   "env PATH=/x rm -rf /"        → "rm"
+ *   "cmd=rm; $cmd -rf /"          → "cmd" (variable indirection — not expanded)
+ */
+function extractBaseCommand(trimmed) {
+    const tokens = trimmed.split(/\s+/);
+    let i = 0;
+    // Skip env assignments (KEY=val, KEY="val", etc.) and prefixed commands
+    while (i < tokens.length) {
+        const tok = tokens[i];
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*=/.test(tok)) {
+            i++;
+            continue;
+        }
+        if (tok === "sudo" || tok === "env" || tok === "command" || tok === "exec" || tok === "nohup") {
+            i++;
+            continue;
+        }
+        break;
+    }
+    if (i >= tokens.length)
+        return tokens[0] ?? "";
+    // Extract basename from path (e.g. /usr/bin/rm → rm)
+    const raw = tokens[i];
+    const parts = raw.split(/[\\/]/);
+    return parts[parts.length - 1] || raw;
+}
 /**
  * Check if a command is allowed based on security configuration
  */
@@ -23,8 +57,20 @@ export function isCommandAllowed(command, securityConfig) {
     if (!trimmedCommand) {
         return { allowed: false, reason: "Empty command" };
     }
-    // Extract base command (first word)
-    const baseCommand = trimmedCommand.split(/\s+/)[0];
+    // Check dangerous operators FIRST — before parsing the base command.
+    // e.g. "curl http://x | bash" must be caught even though curl isn't blacklisted.
+    if (config.blockDangerousFlags) {
+        for (const op of config.dangerousOperators || []) {
+            if (trimmedCommand.includes(op)) {
+                return {
+                    allowed: false,
+                    reason: `Operator "${op}" is not allowed`,
+                };
+            }
+        }
+    }
+    // Extract actual base command (handles paths, env vars, sudo)
+    const baseCommand = extractBaseCommand(trimmedCommand);
     // Check whitelist first (if non-empty, only whitelisted commands are allowed)
     if (config.whitelist.length > 0) {
         if (!config.whitelist.includes(baseCommand)) {
@@ -34,30 +80,27 @@ export function isCommandAllowed(command, securityConfig) {
             };
         }
     }
-    // Check blacklist
+    // Check blacklist (against the extracted basename, not the raw token)
     if (config.blacklist.includes(baseCommand)) {
         return {
             allowed: false,
             reason: `Command "${baseCommand}" is blacklisted`,
         };
     }
-    // Check for dangerous operators
-    if (config.blockDangerousFlags) {
-        for (const op of config.dangerousOperators || []) {
-            if (command.includes(op)) {
-                return {
-                    allowed: false,
-                    reason: `Operator "${op}" is not allowed`,
-                };
-            }
-        }
+    // Also check the raw first token in case it's a simple name
+    const rawFirst = trimmedCommand.split(/\s+/)[0];
+    if (rawFirst !== baseCommand && config.blacklist.includes(rawFirst)) {
+        return {
+            allowed: false,
+            reason: `Command "${rawFirst}" is blacklisted`,
+        };
     }
     // Check for dangerous flags
     if (config.blockDangerousFlags) {
         for (const flag of config.dangerousFlags || []) {
             // Check for flag as whole word or with equals
             const flagPattern = new RegExp(`(?:^|\\s)${flag}(?:\\s|$|=)`);
-            if (flagPattern.test(command)) {
+            if (flagPattern.test(trimmedCommand)) {
                 return {
                     allowed: false,
                     reason: `Dangerous flag "${flag}" is not allowed`,

package/dist/modules/security/encryption.js

@@ -1,7 +1,7 @@
 import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
 import { homedir } from 'os';
 import { join } from 'path';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from 'fs';
 const DEFAULT_CONFIG = {
     keyPath: join(homedir(), '.mma', '.encryption-key'),
     algorithm: 'aes-256-gcm',
@@ -44,13 +44,15 @@ export function getOrCreateEncryptionKey(config) {
         return Buffer.from(keyBase64, 'base64');
     }
     catch {
-        // If we can't read the key file, generate a new one
-        const key = generateEncryptionKey();
+        // Backup the corrupted key file before throwing
         try {
-            writeFileSync(keyPath, key.toString('base64'), { mode: 0o600 });
+            const backupPath = `${keyPath}.corrupted.${Date.now()}`;
+            copyFileSync(keyPath, backupPath);
         }
-        catch { /* ignore */ }
-        return key;
+        catch { /* backup failed, continue */ }
+        throw new Error(`Encryption key file is corrupted or unreadable: ${keyPath}. ` +
+            `All previously encrypted data will be unrecoverable. ` +
+            `Delete the key file to generate a new one.`);
     }
 }
 /**

package/dist/modules/session/module.js

@@ -19,10 +19,6 @@ export class SessionModule {
     getPlugin() {
         return {
             name: 'session',
-            onSessionStart: (_ctx) => {
-            },
-            onSessionEnd: (_ctx) => {
-            },
         };
     }
 }

package/dist/tools/bash.js

@@ -19,6 +19,25 @@ function adaptCommandForWindows(command) {
     }
     return command;
 }
+/** Common Unix → Windows command mapping for error hints. */
+const UNIX_TO_WIN_HINTS = {
+    'ls': 'Use "dir" or the list_dir tool instead.',
+    'pwd': 'Use "echo %cd%" or the file_info tool instead.',
+    'cat': 'Use "type" or the read_file tool instead.',
+    'cp': 'Use "copy" or the move_file tool instead.',
+    'mv': 'Use "move" or the move_file tool instead.',
+    'rm': 'Use "del" or the delete_file tool instead.',
+    'grep': 'Use "findstr" or the grep tool instead.',
+    'chmod': 'Use icacls or the chmod tool instead.',
+    'touch': 'Use type nul > file or the write_file tool instead.',
+    'find': 'Use "dir /s" or the glob tool instead.',
+    'head': 'Use the read_file tool with offset/limit instead.',
+    'tail': 'Use the read_file tool instead.',
+    'wc': 'Use the read_file tool instead.',
+    'diff': 'Use the diff tool instead.',
+    'which': 'Use "where" instead.',
+    'echo': 'echo works on Windows, but avoid pipes (|).',
+};
 export const bashTool = {
     name: 'bash',
     description: 'Execute a shell command and return its output. Use for running tests, build, git, and shell operations. Long-running commands (dev servers, watchers) start in the background and return a process id immediately — manage them with process_list, process_log, process_kill. Set background=true to force background execution.',
@@ -90,6 +109,14 @@ export const bashTool = {
             else if (!output && res.code !== 0) {
                 output = `(exit code ${res.code})`;
             }
+            // On Windows, hint about Unix commands that don't work
+            if (platform() === 'win32' && res.code !== 0) {
+                const firstWord = command.trim().split(/\s+/)[0]?.split(/[\\/]/).pop();
+                const hint = firstWord ? UNIX_TO_WIN_HINTS[firstWord] : undefined;
+                if (hint) {
+                    output = `${output}\n\nHint: "${firstWord}" may not work on Windows. ${hint}`;
+                }
+            }
             // Update audit log with result
             if (securityConfig?.logCommands) {
                 logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), res.code === 0, `Working directory: ${workdir}, Output length: ${res.stdout.length}`);

package/dist/tools/create-dir.js

@@ -1,9 +1,9 @@
 import { mkdirSync, existsSync } from "fs";
-import { resolve, normalize } from "path";
 import { t } from "../i18n/index";
 import { isPathWritable } from "../modules/security/path-validator";
 import { logFileWrite, logSecurityBlock } from "../modules/security/audit-log";
 import { getSessionSecurityConfig } from "../modules/security/session-isolation";
+import { safeResolvePath } from "./path-utils";
 export const createDirTool = {
     name: "create_dir",
     description: "Create a directory (and any intermediate directories).",
@@ -17,8 +17,7 @@ export const createDirTool = {
     },
     handler: async (ctx, args) => {
         const path = String(args.path);
-        const baseDir = resolve(ctx.baseDir);
-        const resolved = resolve(baseDir, normalize(path));
+        const resolved = safeResolvePath(ctx.baseDir, path);
         // Get session-specific security config
         const securityConfig = ctx.sessionContext
             ? getSessionSecurityConfig(ctx.config, ctx.sessionContext)
@@ -34,7 +33,7 @@ export const createDirTool = {
             };
         }
         // Check path permissions
-        const scopeCheck = isPathWritable(ctx.baseDir, path, ctx.scope, ctx.config.security?.paths);
+        const scopeCheck = isPathWritable(ctx.baseDir, resolved, ctx.scope, ctx.config.security?.paths);
         if (!scopeCheck.allowed) {
             logSecurityBlock(ctx.sessionId, "file_write", scopeCheck.reason || "Path not allowed", path);
             return {

package/dist/tools/delete-file.js

@@ -1,10 +1,10 @@
 import { unlinkSync, existsSync, statSync, readFileSync } from "fs";
-import { resolve, normalize } from "path";
 import { t } from "../i18n/index";
 import { isPathWritable } from "../modules/security/path-validator";
 import { logFileDelete, logSecurityBlock } from "../modules/security/audit-log";
 import { getSessionSecurityConfig } from "../modules/security/session-isolation";
 import { generateDeleteDiff } from "../ui/diff";
+import { safeResolvePath } from "./path-utils";
 export const deleteFileTool = {
     name: "delete_file",
     description: "Delete a file from the filesystem.",
@@ -18,8 +18,7 @@ export const deleteFileTool = {
     },
     handler: async (ctx, args) => {
         const path = String(args.path);
-        const baseDir = resolve(ctx.baseDir);
-        const resolved = resolve(baseDir, normalize(path));
+        const resolved = safeResolvePath(ctx.baseDir, path);
         // Get session-specific security config
         const securityConfig = ctx.sessionContext
             ? getSessionSecurityConfig(ctx.config, ctx.sessionContext)
@@ -35,7 +34,7 @@ export const deleteFileTool = {
             };
         }
         // Check path permissions
-        const scopeCheck = isPathWritable(ctx.baseDir, path, ctx.scope, ctx.config.security?.paths);
+        const scopeCheck = isPathWritable(ctx.baseDir, resolved, ctx.scope, ctx.config.security?.paths);
         if (!scopeCheck.allowed) {
             logSecurityBlock(ctx.sessionId, "file_delete", scopeCheck.reason || "Path not allowed", path);
             return {

package/dist/tools/edit-file.js

@@ -1,11 +1,11 @@
 import { readFileSync, writeFileSync } from "fs";
-import { resolve, normalize } from "path";
 import { t } from "../i18n/index";
 import { isPathWritable } from "../modules/security/path-validator";
 import { scanContent } from "../modules/security/content-scanner";
 import { logFileWrite, logSecurityBlock } from "../modules/security/audit-log";
 import { getSessionSecurityConfig } from "../modules/security/session-isolation";
 import { generateDiff } from "../ui/diff";
+import { safeResolvePath } from "./path-utils";
 export const editFileTool = {
     name: "edit_file",
     description: "Find and replace text in an existing file. Uses exact string match (not regex).",
@@ -21,8 +21,7 @@ export const editFileTool = {
     },
     handler: async (ctx, args) => {
         const path = String(args.path);
-        const baseDir = resolve(ctx.baseDir);
-        const resolved = resolve(baseDir, normalize(path));
+        const resolved = safeResolvePath(ctx.baseDir, path);
         // Get session-specific security config
         const securityConfig = ctx.sessionContext
             ? getSessionSecurityConfig(ctx.config, ctx.sessionContext)
@@ -38,7 +37,7 @@ export const editFileTool = {
             };
         }
         // Check path permissions
-        const scopeCheck = isPathWritable(ctx.baseDir, path, ctx.scope, ctx.config.security?.paths);
+        const scopeCheck = isPathWritable(ctx.baseDir, resolved, ctx.scope, ctx.config.security?.paths);
         if (!scopeCheck.allowed) {
             logSecurityBlock(ctx.sessionId, "file_write", scopeCheck.reason || "Path not allowed", path);
             return {

package/dist/tools/executor.js

@@ -86,4 +86,10 @@ export class ToolExecutor {
     getToolDefinitions(tags) {
         return this.registry.getAllForLLM(tags);
     }
+    getRegistry() {
+        return this.registry;
+    }
+    setScope(scope) {
+        this.ctx.scope = scope;
+    }
 }

package/dist/tools/file-info.js

@@ -1,7 +1,7 @@
 import { statSync, existsSync } from 'fs';
-import { resolve, normalize } from 'path';
 import { t } from '../i18n/index';
 import { isPathInScope } from '../modules/security/path-validator';
+import { safeResolvePath } from './path-utils';
 export const fileInfoTool = {
     name: 'file_info',
     description: 'Get metadata about a file or directory (size, creation date, modification date).',
@@ -15,10 +15,9 @@ export const fileInfoTool = {
     },
     handler: async (ctx, args) => {
         const path = String(args.path);
-        const baseDir = resolve(ctx.baseDir);
-        const resolved = resolve(baseDir, normalize(path));
+        const resolved = safeResolvePath(ctx.baseDir, path);
         // Check path permissions
-        const scopeCheck = isPathInScope(ctx.baseDir, path, ctx.scope, ctx.config.security?.paths);
+        const scopeCheck = isPathInScope(ctx.baseDir, resolved, ctx.scope, ctx.config.security?.paths);
         if (!scopeCheck.allowed) {
             return {
                 success: false,

package/dist/tools/list-dir.js

@@ -1,7 +1,8 @@
 import { readdirSync, statSync, existsSync } from 'fs';
-import { resolve, normalize } from 'path';
+import { resolve } from 'path';
 import { t } from '../i18n/index';
 import { isPathInScope } from '../modules/security/path-validator';
+import { safeResolvePath } from './path-utils';
 export const listDirTool = {
     name: 'list_dir',
     description: 'List files and directories in a given path.',
@@ -15,10 +16,9 @@ export const listDirTool = {
     },
     handler: async (ctx, args) => {
         const path = String(args.path);
-        const baseDir = resolve(ctx.baseDir);
-        const resolved = resolve(baseDir, normalize(path));
+        const resolved = safeResolvePath(ctx.baseDir, path);
         // Check path permissions
-        const scopeCheck = isPathInScope(ctx.baseDir, path, ctx.scope, ctx.config.security?.paths);
+        const scopeCheck = isPathInScope(ctx.baseDir, resolved, ctx.scope, ctx.config.security?.paths);
         if (!scopeCheck.allowed) {
             return {
                 success: false,

package/dist/tools/path-utils.js

@@ -0,0 +1,51 @@
+import { resolve, normalize, dirname, basename, sep } from 'path';
+import { existsSync } from 'fs';
+/**
+ * Resolve a user-provided path against baseDir.
+ *
+ * Handles common model mistakes:
+ * 1. Leading slash: "/testing/cat3" → resolve relative to baseDir
+ * 2. Missing separator: "E:\agent_test" when baseDir is "E:\agent\_test"
+ *    → inserts the missing backslash
+ *
+ * For new files the parent directory must exist; we check that instead of
+ * the full path so write_file still works.
+ */
+export function safeResolvePath(baseDir, userPath) {
+    const norm = normalize(userPath);
+    const stripped = norm.replace(/^[/\\]/, '');
+    const resolved = resolve(baseDir, stripped);
+    // Fast path: if it exists (or parent does for new files), return it
+    if (existsSync(resolved) || existsSync(dirname(resolved)))
+        return resolved;
+    const baseNorm = normalize(baseDir);
+    // Walk ancestors and look for missing separators
+    let cur = baseNorm;
+    while (cur && cur !== dirname(cur)) {
+        const name = basename(cur);
+        if (!name) {
+            cur = dirname(cur);
+            continue;
+        }
+        let idx = stripped.toLowerCase().indexOf(name.toLowerCase());
+        while (idx >= 0) {
+            const afterIdx = idx + name.length;
+            const afterChar = stripped[afterIdx];
+            if (afterChar && afterChar !== '\\' && afterChar !== '/') {
+                const fixed = stripped.slice(0, afterIdx) + sep + stripped.slice(afterIdx);
+                const fixedResolved = resolve(baseDir, normalize(fixed));
+                if (existsSync(fixedResolved) || existsSync(dirname(fixedResolved))) {
+                    return fixedResolved;
+                }
+                // Try from ancestor's parent
+                const fromParent = resolve(dirname(cur), normalize(fixed));
+                if (existsSync(fromParent) || existsSync(dirname(fromParent))) {
+                    return fromParent;
+                }
+            }
+            idx = stripped.toLowerCase().indexOf(name.toLowerCase(), idx + 1);
+        }
+        cur = dirname(cur);
+    }
+    return resolved;
+}

package/dist/tools/read-file.js

@@ -1,9 +1,10 @@
 import { readFileSync, existsSync } from "fs";
-import { resolve, normalize, extname } from "path";
+import { extname } from "path";
 import { t } from "../i18n/index";
 import { isPathInScope } from "../modules/security/path-validator";
 import { DEFAULT_SECURITY_CONFIG } from "../config/security";
 import { logSecurityBlock } from "../modules/security/audit-log";
+import { safeResolvePath } from "./path-utils";
 /** Default number of lines returned when the caller omits `limit`. */
 const DEFAULT_LIMIT = 50;
 export const readFileTool = {
@@ -27,8 +28,9 @@ export const readFileTool = {
     },
     handler: async (ctx, args) => {
         const path = String(args.path);
+        const resolved = safeResolvePath(ctx.baseDir, path);
         const securityPaths = ctx.config?.security?.paths || DEFAULT_SECURITY_CONFIG.paths;
-        const scopeCheck = isPathInScope(ctx.baseDir, path, ctx.scope, securityPaths);
+        const scopeCheck = isPathInScope(ctx.baseDir, resolved, ctx.scope, securityPaths);
         if (!scopeCheck.allowed) {
             const pathStr = path;
             logSecurityBlock(ctx.sessionId || undefined, "file_read", scopeCheck.reason || "Path not allowed", pathStr);
@@ -39,12 +41,13 @@ export const readFileTool = {
                 }),
             };
         }
-        const resolved = resolve(ctx.baseDir, normalize(path));
         if (!existsSync(resolved)) {
             return { success: false, output: t("file.notfound", { path }) };
         }
         ctx.trackReadPath?.(path);
         const content = readFileSync(resolved, "utf-8");
+        // Track file paths mentioned in the document (e.g. structure.md, README)
+        ctx.trackDocumentContent?.(content);
         const lines = content.split("\n");
         const total = lines.length;
         const offset = args.offset || 1;