min-agent 0.3.0 → 0.4.0

package/dist/tools/bash.js

@@ -3,11 +3,30 @@ import { spawn } from "child_process";
 import path from "path";
 import { confirm, isDangerousCommand, isAutoApprove } from "../confirm.js";
 import { writeFullToolOutput } from "../tool-output.js";
+import { planSandboxedSpawn } from "../sandbox.js";
+import { getEffectiveConfig } from "../config.js";
 const MAX_STREAM_BYTES = 200 * 1024;
 const MAX_OUTPUT_BYTES = 100_000;
+/** Default wall-clock limit so one hung command cannot stall the whole turn. */
+export const DEFAULT_BASH_TIMEOUT_MS = 10 * 60 * 1000;
+/** Resolve the timeout for a command: explicit > config > default. 0 disables. */
+export function resolveBashTimeout(explicit) {
+    if (typeof explicit === "number" && Number.isFinite(explicit) && explicit >= 0)
+        return Math.floor(explicit);
+    const configured = getEffectiveConfig().tools?.bashTimeoutMs;
+    if (typeof configured === "number" && Number.isFinite(configured) && configured >= 0)
+        return Math.floor(configured);
+    return DEFAULT_BASH_TIMEOUT_MS;
+}
 /** Track active child processes so they can be killed on abort (e.g. ESC). */
 const activeRuns = new Set();
 let sigintRegistered = false;
+/** Sandbox caveats are shown once per process to avoid spamming every command. */
+let sandboxWarningShown = false;
+/** Test hook: allow the sandbox caveat to be shown again. */
+export function resetSandboxWarningShown() {
+    sandboxWarningShown = false;
+}
 /**
  * Registered exactly once: Ctrl+C kills all active commands instead of leaking a handler per call.
  * When nothing is running, re-dispatch the signal so the process can exit normally
@@ -51,13 +70,19 @@ export function killActiveProcesses() {
     activeRuns.clear();
 }
 export const bashTool = tool({
-    description: "Run a shell command. Use this for system operations, running builds, tests, git commands, etc. The command runs in the current working directory (or `cwd` if specified). You SHOULD set a timeout based on how long you expect the command to take. If no timeout is set, the command runs until it finishes or the user manually interrupts (Ctrl+C).",
+    description: "Run a shell command. Use this for system operations, running builds, tests, git commands, etc. The command runs in the current working directory (or `cwd` if specified). Commands are killed after 10 minutes by default; set `timeout` for anything expected to run longer (or shorter).",
     inputSchema: jsonSchema({
         type: "object",
         properties: {
             command: { type: "string", description: "The shell command to execute" },
-            timeout: { type: "number", description: "Timeout in milliseconds. Set based on expected duration (e.g. 5000 for quick commands, 60000 for builds). Omit only for commands with unpredictable duration." },
-            cwd: { type: "string", description: "Working directory for the command (relative to the current directory or absolute)" },
+            timeout: {
+                type: "number",
+                description: "Timeout in milliseconds. Defaults to 600000 (10 minutes). Set a smaller value for quick commands or a larger one for long builds.",
+            },
+            cwd: {
+                type: "string",
+                description: "Working directory for the command (relative to the current directory or absolute)",
+            },
         },
         required: ["command"],
     }),
@@ -74,9 +99,24 @@ export const bashTool = tool({
 export async function executeBash(command, timeout, cwd) {
     ensureSigintHandler();
     return new Promise((resolve) => {
+        const isWin = process.platform === "win32";
+        const resolvedCwd = cwd ? path.resolve(process.cwd(), cwd) : process.cwd();
+        const plan = planSandboxedSpawn(command, resolvedCwd, {
+            ...process.env,
+            ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}),
+        });
+        if ("error" in plan) {
+            resolve(plan.error);
+            return;
+        }
+        let notice = "";
+        if (plan.warning && !sandboxWarningShown) {
+            sandboxWarningShown = true;
+            notice = `${plan.warning}\n\n`;
+        }
         const run = {
             proc: undefined,
-            resolve,
+            resolve: (value) => resolve(notice + value),
             stdoutChunks: [],
             stderrChunks: [],
             killed: false,
@@ -85,15 +125,12 @@ export async function executeBash(command, timeout, cwd) {
             stderrTruncated: false,
         };
         activeRuns.add(run);
-        // On Windows, force UTF-8 codepage to avoid Chinese garbled text
-        const isWin = process.platform === "win32";
-        const actualCommand = isWin ? `chcp 65001 >nul && ${command}` : command;
-        const proc = spawn(actualCommand, [], {
-            shell: true,
-            cwd: cwd ? path.resolve(process.cwd(), cwd) : process.cwd(),
+        const proc = spawn(plan.file, plan.args, {
+            shell: plan.shell,
+            cwd: plan.cwd,
             stdio: ["ignore", "pipe", "pipe"],
             detached: process.platform !== "win32",
-            env: { ...process.env, ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}) },
+            env: plan.env,
         });
         run.proc = proc;
         const collect = (chunks, truncated) => (chunk) => {
@@ -106,15 +143,16 @@ export async function executeBash(command, timeout, cwd) {
         };
         proc.stdout?.on("data", collect(run.stdoutChunks, "stdoutTruncated"));
         proc.stderr?.on("data", collect(run.stderrChunks, "stderrTruncated"));
-        // Timeout kill (only if timeout is specified)
-        if (timeout && timeout > 0) {
+        // Timeout kill (explicit value, config default, or the 10 minute fallback)
+        const effectiveTimeout = resolveBashTimeout(timeout);
+        if (effectiveTimeout > 0) {
             run.timer = setTimeout(() => {
                 run.killed = true;
                 run.settled = true;
                 killProcess(proc.pid);
-                resolve(formatOutput(run) +
-                    `\n\n[Command timed out after ${timeout}ms and was killed. Retry with a larger timeout if needed.]`);
-            }, timeout);
+                run.resolve(formatOutput(run) +
+                    `\n\n[Command timed out after ${effectiveTimeout}ms and was killed. Retry with a larger timeout if needed.]`);
+            }, effectiveTimeout);
         }
         proc.on("close", (code) => {
             activeRuns.delete(run);
@@ -125,10 +163,10 @@ export async function executeBash(command, timeout, cwd) {
             run.settled = true;
             const output = formatOutput(run);
             if (code === 0) {
-                resolve(output || "(no output)");
+                run.resolve(output || "(no output)");
             }
             else {
-                resolve(`Exit code ${code}\n${output || "(no output)"}`);
+                run.resolve(`Exit code ${code}\n${output || "(no output)"}`);
             }
         });
         proc.on("error", (err) => {
@@ -138,7 +176,7 @@ export async function executeBash(command, timeout, cwd) {
             if (run.killed || run.settled)
                 return;
             run.settled = true;
-            resolve(`Error: ${err.message}`);
+            run.resolve(`Error: ${err.message}`);
         });
     });
 }

package/dist/tools/code_search.js

@@ -1,5 +1,6 @@
 import { tool, jsonSchema } from "ai";
 import { truncateToolOutput } from "../tool-output.js";
+import { getEffectiveSandboxPolicy, networkDeniedMessage } from "../sandbox.js";
 const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
 export const codeSearchTool = tool({
     description: `Search and get relevant context for any programming task using Exa Code API.
@@ -25,6 +26,11 @@ Usage:
         required: ["query"],
     }),
     execute: async ({ query, tokensNum }) => {
+        if (getEffectiveSandboxPolicy().network === "deny")
+            return `Code search error: ${networkDeniedMessage()}`;
+        if (!process.env.EXA_API_KEY?.trim()) {
+            return "Code search error: EXA_API_KEY is not set. Configure it in your environment to enable code search.";
+        }
         const tokens = Math.max(1000, Math.min(50000, tokensNum ?? 5000));
         try {
             const result = await callExaCode(query, tokens);
@@ -34,7 +40,7 @@ Usage:
             return truncateToolOutput(result, { direction: "head" }).content;
         }
         catch (err) {
-            return `Code search error: ${err.message}`;
+            return `Code search error: ${err instanceof Error ? err.message : String(err)}`;
         }
     },
 });

package/dist/tools/edit.js

@@ -1,8 +1,9 @@
 import { tool, jsonSchema } from "ai";
-import { readFile, writeFile, rename, unlink } from "fs/promises";
-import { randomBytes } from "crypto";
+import { readFile } from "fs/promises";
 import path from "path";
-import { confirm, isAutoApprove } from "../confirm.js";
+import { confirm, isEditAutoApprove } from "../confirm.js";
+import { pathAccessError } from "../sandbox.js";
+import { atomicWriteFile } from "./atomic-file.js";
 export const editTool = tool({
     description: "Edit a file by replacing a specific text block with new content. The oldText must match exactly (including whitespace and indentation). Use this for precise edits instead of rewriting entire files.",
     inputSchema: jsonSchema({
@@ -19,13 +20,16 @@ export const editTool = tool({
             return "Error: oldText must not be empty";
         if (oldText === newText)
             return "No change: oldText equals newText";
+        const denied = pathAccessError(filePath, "write");
+        if (denied)
+            return `Error: ${denied}`;
         const resolved = path.resolve(process.cwd(), filePath);
         let content;
         try {
             content = await readFile(resolved, "utf-8");
         }
         catch (err) {
-            return `Error: cannot read ${filePath}: ${err.message}`;
+            return `Error: cannot read ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
         }
         const occurrences = content.split(oldText).length - 1;
         if (occurrences === 0) {
@@ -44,21 +48,18 @@ export const editTool = tool({
             return `Error: oldText found ${occurrences} times in ${filePath}. Please provide more context to make the match unique.`;
         }
         // Confirm edit
-        if (!isAutoApprove()) {
+        if (!isEditAutoApprove()) {
             const preview = (s) => (s.length > 80 ? s.slice(0, 80) + "..." : s);
             const approved = await confirm(`Edit ${filePath}:\nreplace "${preview(oldText)}"\nwith "${preview(newText)}"`);
             if (!approved)
                 return "Edit rejected by user.";
         }
         const updated = content.replace(oldText, newText);
-        const tmpPath = path.join(path.dirname(resolved), `.${path.basename(resolved)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
         try {
-            await writeFile(tmpPath, updated, "utf-8");
-            await rename(tmpPath, resolved);
+            await atomicWriteFile(resolved, updated);
         }
         catch (err) {
-            await unlink(tmpPath).catch(() => { });
-            return `Error: cannot write ${filePath}: ${err.message}`;
+            return `Error: cannot write ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
         }
         const oldLines = oldText.split("\n").length;
         const newLines = newText.split("\n").length;

package/dist/tools/explore.js

@@ -5,8 +5,12 @@ import { readTool } from "./read.js";
 import { globTool } from "./glob.js";
 import { grepTool } from "./grep.js";
 import { stripThinkingFromAssistantText } from "../assistant-stream.js";
+import { unwrapXmlSearchTags } from "../xml-search.js";
 import { truncateToolOutput } from "../tool-output.js";
-const EXPLORE_SYSTEM = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+import { log } from "../logger.js";
+import { getEffectiveConfig } from "../config.js";
+function exploreSystem() {
+    return `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 
 Your strengths:
 - Rapidly finding files using glob patterns
@@ -27,8 +31,14 @@ Complete the search request efficiently and report findings clearly.
 
 Working directory: ${process.cwd()}
 Platform: ${process.platform}`;
+}
 const EXPLORE_MAX_STEPS = 20;
-export function createExploreTool(modelId, abortSignal, onUsage) {
+function resolveExploreSteps(explicit) {
+    const configured = getEffectiveConfig().agent?.exploreMaxSteps;
+    const value = explicit ?? configured ?? EXPLORE_MAX_STEPS;
+    return Number.isFinite(value) && value >= 1 ? Math.floor(value) : EXPLORE_MAX_STEPS;
+}
+export function createExploreTool(modelId, abortSignal, onUsage, context = {}) {
     return tool({
         description: `Deep codebase exploration agent. Use this to understand project structure, find files by patterns, search code for keywords, trace module relationships, or answer questions about the codebase.
 
@@ -53,22 +63,23 @@ Examples:
             const level = thoroughness ?? "medium";
             console.error(`\x1b[90m  ┌─ Explore (${level}): ${query.slice(0, 60)}\x1b[0m`);
             try {
-                const result = await runExploreAgent(query, level, modelId, abortSignal);
+                const result = await runExploreAgent(query, level, modelId, abortSignal, context);
                 if (result.usage)
                     onUsage?.(result.usage);
                 console.error(`\x1b[90m  └─ ✓ Done\x1b[0m`);
-                return truncateToolOutput(result.text, { direction: "head" }).content;
+                return truncateToolOutput(result.text, { direction: "tail" }).content;
             }
             catch (err) {
                 if (abortSignal?.aborted)
                     return "Explore cancelled by user.";
+                log("error", `explore agent failed: ${err?.message ?? String(err)}`);
                 console.error(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
                 return `Explore error: ${err.message}`;
             }
         },
     });
 }
-async function runExploreAgent(query, thoroughness, modelId, abortSignal) {
+async function runExploreAgent(query, thoroughness, modelId, abortSignal, context = {}) {
     const model = resolveModel(modelId);
     // Read-only tools only
     const tools = {
@@ -88,13 +99,15 @@ Task: ${query}`;
     const signal = abortSignal ? AbortSignal.any([abortSignal, controller.signal]) : controller.signal;
     const result = streamText({
         model,
-        system: EXPLORE_SYSTEM,
+        system: exploreSystem(),
         messages,
         tools,
-        stopWhen: stepCountIs(EXPLORE_MAX_STEPS),
+        stopWhen: stepCountIs(resolveExploreSteps(context.maxSteps)),
         maxRetries: 2,
         abortSignal: signal,
-        onError() { },
+        onError({ error }) {
+            log("warn", `explore step failed (will retry): ${String(error)}`);
+        },
     });
     let assistantText = "";
     for await (const event of result.fullStream) {
@@ -104,10 +117,21 @@ Task: ${query}`;
                 break;
             case "tool-call":
                 console.error(`\x1b[90m  │ ⚡ ${event.toolName}\x1b[0m`);
+                if (context.shouldStop?.()) {
+                    log("warn", "explore agent stopped: parent budget reached");
+                    controller.abort();
+                    return {
+                        text: unwrapXmlSearchTags(stripThinkingFromAssistantText(assistantText)) +
+                            "\n\n[Explore stopped: run budget reached]",
+                    };
+                }
                 break;
             case "error":
+                log("error", `explore stream error: ${String(event.error)}`);
                 controller.abort();
-                return { text: stripThinkingFromAssistantText(assistantText) || `[Explore error: ${event.error}]` };
+                return {
+                    text: unwrapXmlSearchTags(stripThinkingFromAssistantText(assistantText)) || `[Explore error: ${event.error}]`,
+                };
         }
     }
     let usage;
@@ -116,18 +140,54 @@ Task: ${query}`;
     }
     catch { }
     return {
-        text: stripThinkingFromAssistantText(assistantText) || "(explore agent produced no output)",
+        text: unwrapXmlSearchTags(stripThinkingFromAssistantText(assistantText)) || "(explore agent produced no output)",
         usage,
     };
 }
 /* ── Read-only bash: white-listed commands only, no redirection / chaining ── */
 const READ_ONLY_BINS = new Set([
-    "ls", "find", "cat", "wc", "head", "tail", "grep", "rg", "tree", "pwd", "stat", "du",
-    "file", "which", "echo", "printf", "sort", "uniq", "cut", "tr", "awk", "sed", "basename",
-    "dirname", "realpath", "env", "printenv", "git",
+    "ls",
+    "find",
+    "cat",
+    "wc",
+    "head",
+    "tail",
+    "grep",
+    "rg",
+    "tree",
+    "pwd",
+    "stat",
+    "du",
+    "file",
+    "which",
+    "echo",
+    "printf",
+    "sort",
+    "uniq",
+    "cut",
+    "tr",
+    "awk",
+    "sed",
+    "basename",
+    "dirname",
+    "realpath",
+    "env",
+    "printenv",
+    "git",
 ]);
 const READ_ONLY_GIT_CMDS = new Set([
-    "status", "log", "diff", "show", "rev-parse", "branch", "remote", "tag", "ls-files", "help", "--version", "version",
+    "status",
+    "log",
+    "diff",
+    "show",
+    "rev-parse",
+    "branch",
+    "remote",
+    "tag",
+    "ls-files",
+    "help",
+    "--version",
+    "version",
 ]);
 /** True if the command only inspects state (no writes, redirection, pipes, or chaining). */
 export function isReadOnlyCommand(command) {

package/dist/tools/glob.js

@@ -1,6 +1,7 @@
 import { tool, jsonSchema } from "ai";
 import { glob } from "glob";
 import { truncateToolOutput } from "../tool-output.js";
+import { pathAccessError } from "../sandbox.js";
 export const globTool = tool({
     description: "Find files matching a glob pattern. Returns a list of file paths. Use this to discover project structure and find files.",
     inputSchema: jsonSchema({
@@ -12,6 +13,9 @@ export const globTool = tool({
         required: ["pattern"],
     }),
     execute: async ({ pattern, cwd }) => {
+        const denied = pathAccessError(cwd ?? ".", "read");
+        if (denied)
+            return `Error: ${denied}`;
         try {
             const matches = await glob(pattern, {
                 cwd: cwd ?? process.cwd(),

package/dist/tools/grep.js

@@ -3,6 +3,7 @@ import { readdir, readFile, stat } from "fs/promises";
 import { spawn } from "child_process";
 import path from "path";
 import { truncateToolOutput } from "../tool-output.js";
+import { pathAccessError } from "../sandbox.js";
 const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".out", "coverage", ".min-agent"]);
 const MAX_RESULTS = 500;
 const MAX_FILE_BYTES = 5 * 1024 * 1024;
@@ -10,7 +11,10 @@ const MAX_RG_OUTPUT_BYTES = 8 * 1024 * 1024;
 const WALK_CONCURRENCY = 8;
 /** Convert a simple glob like "*.ts" into an anchored regex for file names. */
 function globToRegex(glob) {
-    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
     return new RegExp(`^${escaped}$`);
 }
 /** Fast path: shell out to ripgrep when available. Resolves null if rg is missing or fails. */
@@ -19,19 +23,19 @@ function rgSearch(pattern, root, includeRegex, ignore) {
         "--no-heading",
         "--line-number",
         "-i",
-        "-e", pattern,
-        "--max-count", "1",
-        "-g", "!*.lock",
-        "--max-filesize", String(MAX_FILE_BYTES),
+        "-e",
+        pattern,
+        "--max-count",
+        "1",
+        "-g",
+        "!*.lock",
+        "--max-filesize",
+        String(MAX_FILE_BYTES),
     ];
     for (const dir of ignore)
         args.push("-g", `!${dir}/**`);
     if (includeRegex) {
-        const glob = includeRegex.source
-            .replace(/^\^/, "")
-            .replace(/\$$/, "")
-            .replace(/\\\./g, ".")
-            .replace(/\.\*/g, "*");
+        const glob = includeRegex.source.replace(/^\^/, "").replace(/\$$/, "").replace(/\\\./g, ".").replace(/\.\*/g, "*");
         args.push("-g", glob);
     }
     args.push(root);
@@ -132,6 +136,9 @@ export const grepTool = tool({
             const regex = new RegExp(pattern);
             const includeRegex = include ? globToRegex(include) : null;
             const root = path.resolve(process.cwd(), searchPath ?? ".");
+            const denied = pathAccessError(root, "read");
+            if (denied)
+                return `Error: ${denied}`;
             const results = [];
             const info = await stat(root).catch(() => null);
             if (!info)

package/dist/tools/index.js

@@ -7,11 +7,14 @@ import { globTool } from "./glob.js";
 import { grepTool } from "./grep.js";
 import { webSearchTool } from "./web_search.js";
 import { webFetchTool } from "./web_fetch.js";
-import { todoTool } from "./todo.js";
 import { questionTool } from "./question.js";
 import { codeSearchTool } from "./code_search.js";
-/** Chat mode: general assistant tools (fewer tools = less token overhead) */
-export function createChatTools() {
+/**
+ * Builtin tools shared by main runs and sub-agents. `todo` is deliberately
+ * absent: it must be bound to a per-run TaskState, so callers register their
+ * own instance via createTodoTool.
+ */
+export function createTools() {
     const tools = {
         bash: bashTool,
         read: readTool,
@@ -22,24 +25,6 @@ export function createChatTools() {
         grep: grepTool,
         search_web: webSearchTool,
         web_fetch: webFetchTool,
-        todo: todoTool,
-        question: questionTool,
-    };
-    return tools;
-}
-/** Code mode: full tool set including task tracking and code search. Todo replaced per-run by the caller. */
-export function createCodeTools() {
-    const tools = {
-        bash: bashTool,
-        read: readTool,
-        write: writeTool,
-        edit: editTool,
-        apply_patch: applyPatchTool,
-        glob: globTool,
-        grep: grepTool,
-        search_web: webSearchTool,
-        web_fetch: webFetchTool,
-        todo: todoTool,
         question: questionTool,
     };
     if (process.env.EXA_API_KEY) {

package/dist/tools/question.js

@@ -1,5 +1,6 @@
 import { tool, jsonSchema } from "ai";
 import { askQuestion } from "../confirm.js";
+import { normalizeQuestionOptions, normalizeQuestionPrompt } from "../question-format.js";
 export const questionTool = tool({
     description: `Ask the user a question to get clarification before proceeding. Use this when:
 - The task is ambiguous and you need more information
@@ -7,28 +8,46 @@ export const questionTool = tool({
 - You need confirmation before a potentially destructive action
 - You're unsure about a requirement or preference
 
-Provide clear, specific questions. Optionally include numbered options for the user to choose from.`,
+Provide a clear, specific question. Optional choices should be an array of strings. Object items with label/description are also accepted.`,
     inputSchema: jsonSchema({
         type: "object",
         properties: {
             question: { type: "string", description: "The question to ask the user" },
             options: {
                 type: "array",
-                items: { type: "string" },
-                description: "Optional list of choices for the user to pick from",
+                items: {
+                    anyOf: [
+                        { type: "string" },
+                        {
+                            type: "object",
+                            properties: {
+                                label: { type: "string" },
+                                description: { type: "string" },
+                                key: { type: "string" },
+                            },
+                        },
+                    ],
+                },
+                description: "Optional list of choices. Prefer plain strings; {label, description} objects are also accepted.",
             },
         },
         required: ["question"],
     }),
     execute: async ({ question, options }) => {
-        const answer = await askQuestion(question, options);
+        const prompt = normalizeQuestionPrompt(question);
+        if (!prompt.trim())
+            return "Error: question is required.";
+        const choices = normalizeQuestionOptions(options);
+        const answer = await askQuestion(prompt, choices.length > 0 ? choices : undefined);
         if (answer === null)
             return "User cancelled the question";
-        if (options && options.length > 0) {
-            const idx = parseInt(answer) - 1;
-            if (idx >= 0 && idx < options.length) {
-                return `User chose: ${options[idx]}`;
-            }
+        if (choices.length > 0) {
+            const exact = choices.find((c) => c === answer);
+            if (exact)
+                return `User chose: ${exact}`;
+            const idx = parseInt(answer, 10) - 1;
+            if (Number.isInteger(idx) && idx >= 0 && idx < choices.length)
+                return `User chose: ${choices[idx]}`;
         }
         return `User answered: ${answer}`;
     },

package/dist/tools/read.js

@@ -4,9 +4,8 @@ import { stat, readFile } from "fs/promises";
 import { createInterface } from "readline";
 import path from "path";
 import { TOOL_OUTPUT_MAX_BYTES, truncateToolOutput } from "../tool-output.js";
-import { InstructionTracker } from "../instructions.js";
-// Shared tracker instance for context-aware instruction discovery
-const instructionTracker = new InstructionTracker();
+import { getActiveInstructionTracker } from "../instructions.js";
+import { pathAccessError } from "../sandbox.js";
 /** Files above this size are streamed instead of loaded into memory. */
 const STREAM_THRESHOLD_BYTES = 20 * 1024 * 1024;
 /** Stream lines [start, end] (1-indexed, inclusive) without loading the whole file. */
@@ -65,6 +64,9 @@ export const readTool = tool({
         required: ["filePath"],
     }),
     execute: async ({ filePath, startLine, endLine }) => {
+        const denied = pathAccessError(filePath, "read");
+        if (denied)
+            return `Error: ${denied}`;
         const resolved = path.resolve(process.cwd(), filePath);
         try {
             const info = await stat(resolved);
@@ -94,7 +96,7 @@ export const readTool = tool({
                 result = await readFile(resolved, "utf-8");
             }
             // Context-aware: discover nearby instruction files
-            const nearbyInstructions = instructionTracker.resolveForFile(resolved);
+            const nearbyInstructions = getActiveInstructionTracker().resolveForFile(resolved);
             if (nearbyInstructions.length > 0) {
                 result += "\n\n<system-reminder>\n" + nearbyInstructions.join("\n\n") + "\n</system-reminder>";
             }