@juspay/neurolink 12.27.2 → 12.28.1

package/dist/cli/factories/commandFactory.d.ts

@@ -145,6 +145,11 @@ export declare class CLICommandFactory {
             description: string;
             alias: string;
         };
+        toolRoot: {
+            type: "string";
+            array: boolean;
+            description: string;
+        };
         format: {
             choices: string[];
             default: string;
@@ -609,6 +614,17 @@ export declare class CLICommandFactory {
             alias: string;
         };
     };
+    static readonly agentOptions: {
+        agentMode: {
+            type: "boolean";
+            description: string;
+        };
+        maxSteps: {
+            type: "number";
+            description: string;
+            coerce: (value: unknown) => number;
+        };
+    };
     private static buildOptions;
     private static processCliImages;
     private static processCliCSVFiles;
@@ -920,6 +936,10 @@ export declare class CLICommandFactory {
      * Flush Langfuse traces before exit
      */
     private static flushLangfuseTraces;
+    /** process.exit discards piped stdout queued past the 64 KiB buffer; resolves false if the reader stalls past the bound. */
+    private static flushStdout;
+    /** Forced exit that fails loudly when queued output could not be delivered. */
+    private static exitAfterStdoutDrain;
 }
 /** Re-export of CLICommandFactory's static option definitions for direct import by tests/tooling. */
 export declare const commonOptions: {
@@ -1048,6 +1068,11 @@ export declare const commonOptions: {
         description: string;
         alias: string;
     };
+    toolRoot: {
+        type: "string";
+        array: boolean;
+        description: string;
+    };
     format: {
         choices: string[];
         default: string;

package/dist/cli/factories/commandFactory.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
 import ora from "ora";
+import { STEP_LIMITS } from "../../core/constants.js";
 import { ModelResolver } from "../../models/modelResolver.js";
 import { providerChoicesFor } from "../../factories/mediaHandlerCatalog.js";
 import { globalSession } from "../../session/globalSessionState.js";
@@ -48,6 +49,21 @@ const DERIVED_PROVIDER_CHOICES = [
 ];
 /** Space-separated form for the bash-completion script, kept in sync with DERIVED_PROVIDER_CHOICES by construction. */
 export const BASH_COMPLETION_PROVIDERS = DERIVED_PROVIDER_CHOICES.join(" ");
+/** EX_IOERR (sysexits.h): the result could not be fully written to stdout. */
+const STDOUT_DRAIN_FAILED_EXIT_CODE = 74;
+const DEFAULT_STDOUT_DRAIN_TIMEOUT_MS = 30_000;
+const STDOUT_DRAIN_WARNING = "neurolink: stdout drain timed out; output may be incomplete\n";
+let stdoutDrainTimeoutMs;
+const resolveStdoutDrainTimeoutMs = () => {
+    if (stdoutDrainTimeoutMs === undefined) {
+        const override = Number(process.env.NEUROLINK_STDOUT_DRAIN_TIMEOUT_MS);
+        stdoutDrainTimeoutMs =
+            Number.isFinite(override) && override > 0
+                ? override
+                : DEFAULT_STDOUT_DRAIN_TIMEOUT_MS;
+    }
+    return stdoutDrainTimeoutMs;
+};
 /**
  * CLI Command Factory for generate commands
  */
@@ -221,6 +237,11 @@ export class CLICommandFactory {
             description: "System prompt to guide AI behavior",
             alias: "s",
         },
+        toolRoot: {
+            type: "string",
+            array: true,
+            description: "Directory the built-in file tools may read and write (repeatable). Defaults to the working directory. Constrains bash's working directory, not its commands.",
+        },
         // Output control options
         format: {
             choices: ["text", "json", "table"],
@@ -736,6 +757,26 @@ export class CLICommandFactory {
             alias: "skills-dir",
         },
     };
+    // Registered on generate and stream only; the flags mean nothing elsewhere.
+    static agentOptions = {
+        agentMode: {
+            type: "boolean",
+            description: "Run as an autonomous terminal agent: prepend Neurolink's versioned agent instructions to the system prompt",
+        },
+        maxSteps: {
+            type: "number",
+            description: `Maximum tool-calling steps before the turn stops (integer ${STEP_LIMITS.min}-${STEP_LIMITS.max}, default ${STEP_LIMITS.default}; some providers cap lower)`,
+            coerce: (value) => {
+                if (typeof value !== "number" ||
+                    !Number.isInteger(value) ||
+                    value < STEP_LIMITS.min ||
+                    value > STEP_LIMITS.max) {
+                    throw new Error(`--max-steps must be an integer between ${STEP_LIMITS.min} and ${STEP_LIMITS.max}`);
+                }
+                return value;
+            },
+        },
+    };
     // Helper method to build options for commands. `excludeOptions` drops
     // common flags from registration entirely (not just from validation) —
     // #1191 round-5: batch uses this to omit `commonOptions.file` so `--file`
@@ -882,6 +923,8 @@ export class CLICommandFactory {
             stopSequences: argv.stopSequences,
             enabledToolNames: argv.enabledToolNames,
             systemPrompt: argv.system,
+            agentMode: argv.agentMode,
+            maxSteps: argv.maxSteps,
             timeout: argv.timeout,
             disableTools: argv.disableTools,
             enableAnalytics: argv.enableAnalytics,
@@ -1531,7 +1574,8 @@ export class CLICommandFactory {
                     .example('$0 generate "Summarize this report" --pdf ./report.pdf', "Analyze a PDF document")
                     .example('$0 generate "Key trends?" --csv large-data.csv --csvMaxRows 100', "Analyze a CSV with a row limit")
                     .example('$0 generate "Compare the chart and the report" --image ./chart.png --pdf ./report.pdf', "Combine multiple file types in one prompt")
-                    .example('$0 generate "What is in this file?" --file ./data.json', "Auto-detect a file type with --file"));
+                    .example('$0 generate "What is in this file?" --file ./data.json', "Auto-detect a file type with --file")
+                    .example('$0 generate "Fix the failing config" --agent-mode --max-steps 60', "Run as an autonomous terminal agent with a step budget"), CLICommandFactory.agentOptions);
             },
             handler: async (argv) => await CLICommandFactory.executeGenerate(argv),
         };
@@ -1556,7 +1600,7 @@ export class CLICommandFactory {
                     .example('$0 stream "Narrate this video" --video path/to/video.mp4', "Stream video analysis")
                     .example('$0 stream "Describe this image" --image ./photo.jpg', "Stream image analysis (multimodal input)")
                     .example('$0 stream "Summarize this document" --pdf ./report.pdf', "Stream PDF analysis")
-                    .example('$0 stream "Explain this dataset" --csv ./data.csv --csv-format markdown', "Stream CSV analysis"));
+                    .example('$0 stream "Explain this dataset" --csv ./data.csv --csv-format markdown', "Stream CSV analysis"), CLICommandFactory.agentOptions);
             },
             handler: async (argv) => await CLICommandFactory.executeStream(argv),
         };
@@ -2261,7 +2305,7 @@ export class CLICommandFactory {
                 logger.error("Error during SDK shutdown:", shutdownError);
             }
             if (!globalSession.getCurrentSessionId()) {
-                process.exit();
+                await CLICommandFactory.exitAfterStdoutDrain();
             }
         }
     }
@@ -2562,7 +2606,7 @@ export class CLICommandFactory {
         }
         if (!globalSession.getCurrentSessionId()) {
             await CLICommandFactory.flushLangfuseTraces();
-            process.exit(0);
+            await CLICommandFactory.exitAfterStdoutDrain(0);
         }
     }
     /**
@@ -2627,7 +2671,7 @@ export class CLICommandFactory {
                 }
                 if (!globalSession.getCurrentSessionId()) {
                     await CLICommandFactory.flushLangfuseTraces();
-                    process.exit(0);
+                    await CLICommandFactory.exitAfterStdoutDrain(0);
                 }
                 return;
             }
@@ -2646,6 +2690,7 @@ export class CLICommandFactory {
             if (skillsConfig) {
                 globalSession.setSkillsConfig(skillsConfig);
             }
+            globalSession.setFileToolRoots(argv.toolRoot);
             // Initialize SDK and session
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
@@ -2700,6 +2745,8 @@ export class CLICommandFactory {
                 topK: enhancedOptions.topK,
                 stopSequences: enhancedOptions.stopSequences,
                 systemPrompt: enhancedOptions.systemPrompt,
+                agentMode: enhancedOptions.agentMode,
+                maxSteps: enhancedOptions.maxSteps,
                 timeout: enhancedOptions.timeout
                     ? enhancedOptions.timeout * 1000
                     : undefined,
@@ -2892,7 +2939,7 @@ export class CLICommandFactory {
         }
         if (!globalSession.getCurrentSessionId()) {
             await CLICommandFactory.flushLangfuseTraces();
-            process.exit(0);
+            await CLICommandFactory.exitAfterStdoutDrain(0);
         }
     }
     /**
@@ -2914,6 +2961,7 @@ export class CLICommandFactory {
         if (skillsConfig) {
             globalSession.setSkillsConfig(skillsConfig);
         }
+        globalSession.setFileToolRoots(argv.toolRoot);
         const sdk = globalSession.getOrCreateNeuroLink();
         const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
         const enhancedOptions = { ...options, ...sessionVariables };
@@ -2949,6 +2997,8 @@ export class CLICommandFactory {
             topK: enhancedOptions.topK,
             stopSequences: enhancedOptions.stopSequences,
             systemPrompt: enhancedOptions.systemPrompt,
+            agentMode: enhancedOptions.agentMode,
+            maxSteps: enhancedOptions.maxSteps,
             timeout: enhancedOptions.timeout
                 ? enhancedOptions.timeout * 1000
                 : undefined,
@@ -3391,7 +3441,7 @@ export class CLICommandFactory {
             await CLICommandFactory.handleStreamOutput(options, fullContent);
             if (!globalSession.getCurrentSessionId()) {
                 await CLICommandFactory.flushLangfuseTraces();
-                process.exit(0);
+                await CLICommandFactory.exitAfterStdoutDrain(0);
             }
         }
         catch (error) {
@@ -3462,6 +3512,7 @@ export class CLICommandFactory {
             if (skillsConfig) {
                 globalSession.setSkillsConfig(skillsConfig);
             }
+            globalSession.setFileToolRoots(argv.toolRoot);
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };
@@ -3595,7 +3646,7 @@ export class CLICommandFactory {
             CLICommandFactory.handleOutput(results, options);
             if (!globalSession.getCurrentSessionId()) {
                 await CLICommandFactory.flushLangfuseTraces();
-                process.exit(0);
+                await CLICommandFactory.exitAfterStdoutDrain(0);
             }
         }
         catch (error) {
@@ -4561,6 +4612,25 @@ export class CLICommandFactory {
             logger.error("[CLI] Error flushing Langfuse traces", { error });
         }
     }
+    /** process.exit discards piped stdout queued past the 64 KiB buffer; resolves false if the reader stalls past the bound. */
+    static flushStdout() {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), resolveStdoutDrainTimeoutMs());
+            timer.unref();
+            process.stdout.write("", () => {
+                clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    }
+    /** Forced exit that fails loudly when queued output could not be delivered. */
+    static async exitAfterStdoutDrain(exitCode) {
+        if (await CLICommandFactory.flushStdout()) {
+            process.exit(exitCode);
+        }
+        process.stderr.write(STDOUT_DRAIN_WARNING);
+        process.exit(STDOUT_DRAIN_FAILED_EXIT_CODE);
+    }
 }
 /** Re-export of CLICommandFactory's static option definitions for direct import by tests/tooling. */
 export const commonOptions = CLICommandFactory.commonOptions;

package/dist/cli/loop/optionsSchema.d.ts

@@ -4,4 +4,4 @@ import type { OptionSchema, TextGenerationOptions } from "../../types/index.js";
  * This object provides metadata for validation and help text in the CLI loop.
  * It is derived from the main TextGenerationOptions interface to ensure consistency.
  */
-export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "imageOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation" | "toolExecutionCapture" | "toolExecutionRecorder">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "imageOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation" | "toolExecutionCapture" | "toolExecutionRecorder" | "toolRoots">, OptionSchema>;

package/dist/core/baseProvider.d.ts

@@ -1,7 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "../index.js";
 import type { NeuroLink } from "../neurolink.js";
-import type { UnknownRecord, MiddlewareFactoryOptions, StreamOptions, StreamResult, AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult, ValidationSchema, EmbedInput, DecisionRequest, DecisionResult } from "../types/index.js";
+import type { FileToolRootPolicy, UnknownRecord, MiddlewareFactoryOptions, StreamOptions, StreamResult, AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult, ValidationSchema, EmbedInput, DecisionRequest, DecisionResult } from "../types/index.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 import type { LanguageModel, ModelMessage, RawUsageObject, Tool, ToolCallRepairFunction, ToolSet } from "../types/index.js";
 export declare abstract class BaseProvider implements AIProvider {
@@ -11,6 +11,7 @@ export declare abstract class BaseProvider implements AIProvider {
     protected middlewareOptions?: MiddlewareFactoryOptions;
     protected readonly directTools: {};
     protected mcpTools?: Record<string, Tool>;
+    private fileToolRootsBound;
     protected customTools?: Map<string, unknown>;
     protected toolExecutor?: (toolName: string, params: unknown) => Promise<unknown>;
     protected sessionId?: string;
@@ -532,6 +533,21 @@ export declare abstract class BaseProvider implements AIProvider {
     /**
      * Get all available tools - delegated to ToolsManager
      */
+    /**
+     * Bind the built-in file tools to one request's root policy. NeuroLink
+     * calls this before every provider call that carries the caller's options,
+     * because several providers override generate()/stream() and assemble
+     * their tools without passing through BaseProvider's entry points.
+     * Providers are created per request, so a bound policy never reaches
+     * another request.
+     */
+    setFileToolRootPolicy(policy: FileToolRootPolicy | undefined): void;
+    /**
+     * Resolve roots for a provider called directly, without NeuroLink. A
+     * policy NeuroLink already bound is left alone unless these options carry
+     * their own. An invalid root throws, before any model request.
+     */
+    private applyFileToolRoots;
     protected getAllTools(): Promise<Record<string, Tool>>;
     /**
      * Calculate actual cost - delegated to TelemetryHandler

package/dist/core/baseProvider.js

@@ -1,5 +1,6 @@
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
-import { directAgentTools } from "../agent/directTools.js";
+import { createDirectAgentTools, directAgentTools, } from "../agent/directTools.js";
+import { boundFileToolRoots, resolveFileToolRootPolicy, } from "../utils/fileToolRoots.js";
 import { defaultProviderFor } from "../factories/mediaHandlerCatalog.js";
 import { DECISION_PROVIDERS, PROVIDER_DESCRIPTORS_BY_NAME, } from "../factories/providerDescriptors.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
@@ -120,6 +121,7 @@ export class BaseProvider {
         ? {}
         : directAgentTools;
     mcpTools; // MCP tools loaded dynamically when available
+    fileToolRootsBound = false;
     customTools; // Custom tools from registerTool()
     toolExecutor; // Tool executor from setupToolExecutor
     sessionId;
@@ -225,6 +227,7 @@ export class BaseProvider {
         // maxTokens (getSafeMaxTokens consults the discovered output ceiling).
         await this.ensureModelLimits();
         let options = this.normalizeStreamOptions(optionsOrPrompt);
+        this.applyFileToolRoots(options);
         // Before anything else, and before a single byte leaves the process: an
         // execution policy this provider cannot honour is an error, and a policy
         // whose shape could be read two ways is an error. Both are silent bugs at
@@ -1292,6 +1295,7 @@ export class BaseProvider {
         await this.ensureModelLimits();
         const options = this.normalizeTextOptions(optionsOrPrompt);
         this.validateOptions(options);
+        this.applyFileToolRoots(options);
         const startTime = Date.now();
         // One span per attempt. runGenerateInActiveContext ends the span on the
         // way out (success or failure), so a model-fallback retry must not reuse
@@ -2156,7 +2160,50 @@ export class BaseProvider {
     /**
      * Get all available tools - delegated to ToolsManager
      */
+    /**
+     * Bind the built-in file tools to one request's root policy. NeuroLink
+     * calls this before every provider call that carries the caller's options,
+     * because several providers override generate()/stream() and assemble
+     * their tools without passing through BaseProvider's entry points.
+     * Providers are created per request, so a bound policy never reaches
+     * another request.
+     */
+    setFileToolRootPolicy(policy) {
+        if (policy === undefined || Object.keys(this.directTools).length === 0) {
+            return;
+        }
+        this.fileToolRootsBound = true;
+        this.toolsManager.setDirectTools(policy.roots === null ? this.directTools : createDirectAgentTools(policy));
+    }
+    /**
+     * Resolve roots for a provider called directly, without NeuroLink. A
+     * policy NeuroLink already bound is left alone unless these options carry
+     * their own. An invalid root throws, before any model request.
+     */
+    applyFileToolRoots(options) {
+        if (Object.keys(this.directTools).length === 0) {
+            return;
+        }
+        const bound = boundFileToolRoots(options);
+        if (bound !== undefined) {
+            this.setFileToolRootPolicy(bound);
+            return;
+        }
+        if (this.fileToolRootsBound && options.toolRoots === undefined) {
+            return;
+        }
+        this.setFileToolRootPolicy(resolveFileToolRootPolicy({
+            perCall: options.toolRoots,
+            instance: this.neurolink?.getToolsConfig()?.fileRoots,
+        }));
+    }
     async getAllTools() {
+        // Any path that reaches tool assembly without a bound policy — an internal
+        // caller, or a provider whose generate()/stream() skips the base entry
+        // points — gets the instance's roots rather than the working directory.
+        if (!this.fileToolRootsBound) {
+            this.applyFileToolRoots({});
+        }
         return this.toolsManager.getAllTools();
     }
     /**

package/dist/core/modules/ToolsManager.d.ts

@@ -20,7 +20,7 @@ export declare function buildMCPSchemaValidator(toolName: string, schema: Record
 }) | undefined>;
 export declare class ToolsManager {
     private readonly providerName;
-    private readonly directTools;
+    private directTools;
     private readonly neurolink?;
     private readonly utilities?;
     protected mcpTools?: Record<string, Tool>;
@@ -112,6 +112,12 @@ export declare class ToolsManager {
      * Get direct tools (built-in agent tools)
      */
     getDirectTools(): Record<string, unknown>;
+    /**
+     * Replace the direct tools for this provider instance — used to bind the
+     * built-in file tools to one request's root policy. Providers are created
+     * per request, so this never leaks a boundary into another request.
+     */
+    setDirectTools(tools: Record<string, unknown>): void;
     /**
      * Get MCP tools
      */

package/dist/core/modules/ToolsManager.js

@@ -550,6 +550,14 @@ export class ToolsManager {
     getDirectTools() {
         return this.directTools;
     }
+    /**
+     * Replace the direct tools for this provider instance — used to bind the
+     * built-in file tools to one request's root policy. Providers are created
+     * per request, so this never leaks a boundary into another request.
+     */
+    setDirectTools(tools) {
+        this.directTools = tools;
+    }
     /**
      * Get MCP tools
      */

package/dist/index.d.ts

@@ -504,5 +504,6 @@ export { validateResponse } from "./utils/responseValidator.js";
 export { TripwireEvaluator, createDefaultTripwireEvaluator, commonTripwires, } from "./utils/tripwireEvaluator.js";
 export { Agent } from "./agent/agent.js";
 export { AgentNetwork } from "./agent/agentNetwork.js";
+export { TERMINAL_AGENT_PROMPT_V1, TERMINAL_AGENT_PROMPT_V2, TERMINAL_AGENT_PROMPT_VERSION, } from "./agent/prompts/terminalAgentPrompt.js";
 export { AgentCoordinator, TaskDistributor, MessageBus, NetworkOrchestrator, NetworkTopology, TopologyBuilder, } from "./agent/index.js";
 export { createLocalUsageReader, getLocalUsageDescriptors, getRegisteredLocalUsageCliIds, readAllLocalUsage, registerLocalUsageReader, } from "./localUsage/index.js";

package/dist/index.js

@@ -823,6 +823,7 @@ export { TripwireEvaluator, createDefaultTripwireEvaluator, commonTripwires, } f
 // ============================================================================
 export { Agent } from "./agent/agent.js";
 export { AgentNetwork } from "./agent/agentNetwork.js";
+export { TERMINAL_AGENT_PROMPT_V1, TERMINAL_AGENT_PROMPT_V2, TERMINAL_AGENT_PROMPT_VERSION, } from "./agent/prompts/terminalAgentPrompt.js";
 // Advanced agent orchestration exports
 export { 
 // Coordination

package/dist/mcp/toolRegistry.d.ts

@@ -2,7 +2,7 @@
  * MCP Tool Registry - Extended Registry with Tool Management
  * Updated to match industry standard camelCase interfaces
  */
-import type { MCPServerInfo, ToolImplementation, ToolInfo, ExecutionContext, HITLManager } from "../types/index.js";
+import type { MCPServerInfo, ToolImplementation, ToolInfo, ExecutionContext, FileToolRootPolicy, HITLManager } from "../types/index.js";
 import { MCPRegistry } from "./registry.js";
 export declare class MCPToolRegistry extends MCPRegistry {
     private tools;
@@ -10,6 +10,7 @@ export declare class MCPToolRegistry extends MCPRegistry {
     private toolExecutionStats;
     private builtInServerInfos;
     private hitlManager?;
+    private fileToolRootResolver;
     constructor();
     /**
      * Set HITL manager for human-in-the-loop safety mechanisms
@@ -20,6 +21,16 @@ export declare class MCPToolRegistry extends MCPRegistry {
      * Get current HITL manager
      */
     getHITLManager(): HITLManager | undefined;
+    /**
+     * Resolve file-tool roots for built-in tools executed on this registry
+     * without a per-call policy. Set by the NeuroLink instance that created it.
+     */
+    setFileToolRootResolver(resolver: () => FileToolRootPolicy): void;
+    /**
+     * The built-in tool bound to the policy that applies to this execution: one
+     * NeuroLink bound on the context, else this registry's owner's roots.
+     */
+    private directToolFor;
     /**
      * Register all direct tools from directAgentTools
      */

package/dist/mcp/toolRegistry.js

@@ -6,7 +6,8 @@ import { MCPRegistry } from "./registry.js";
 import { registryLogger } from "../utils/logger.js";
 import { randomUUID } from "crypto";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
-import { directAgentTools } from "../agent/directTools.js";
+import { createDirectAgentTools, directAgentTools, } from "../agent/directTools.js";
+import { boundFileToolRoots, resolveFileToolRootPolicy, } from "../utils/fileToolRoots.js";
 import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
@@ -21,6 +22,9 @@ export class MCPToolRegistry extends MCPRegistry {
     toolExecutionStats = new Map();
     builtInServerInfos = []; // DIRECT storage for MCPServerInfo
     hitlManager; // Optional HITL manager for safety mechanisms
+    // The owning NeuroLink's file-tool roots, for callers (HTTP tool routes, CLI)
+    // that execute built-in tools on this registry without a bound policy.
+    fileToolRootResolver = () => resolveFileToolRootPolicy({});
     constructor() {
         super();
         if (!shouldDisableBuiltinTools()) {
@@ -46,6 +50,25 @@ export class MCPToolRegistry extends MCPRegistry {
     getHITLManager() {
         return this.hitlManager;
     }
+    /**
+     * Resolve file-tool roots for built-in tools executed on this registry
+     * without a per-call policy. Set by the NeuroLink instance that created it.
+     */
+    setFileToolRootResolver(resolver) {
+        this.fileToolRootResolver = resolver;
+    }
+    /**
+     * The built-in tool bound to the policy that applies to this execution: one
+     * NeuroLink bound on the context, else this registry's owner's roots.
+     */
+    directToolFor(toolName, fallback, context) {
+        const policy = boundFileToolRoots(context) ?? this.fileToolRootResolver();
+        if (policy.roots === null) {
+            return fallback;
+        }
+        const bound = createDirectAgentTools(policy);
+        return bound[toolName] ?? fallback;
+    }
     /**
      * Register all direct tools from directAgentTools
      */
@@ -75,7 +98,8 @@ export class MCPToolRegistry extends MCPRegistry {
                     try {
                         // Direct tools from AI SDK expect their specific parameter structure
                         // Each tool validates its own parameters, so we safely pass them through
-                        const result = await toolDef.execute(params, {
+                        const boundTool = this.directToolFor(toolName, toolDef, context);
+                        const result = await boundTool.execute(params, {
                             toolCallId: context?.sessionId || "unknown",
                             messages: [],
                         });

package/dist/neurolink.d.ts

@@ -1388,6 +1388,19 @@ export declare class NeuroLink {
      * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
      * instance policy with per-call options on every generate/stream call.
      */
+    /**
+     * The policy an entry point bound to `options`, or — for an internal path
+     * that built its own options — the instance policy narrowed by any
+     * per-call `toolRoots`. Never trusts a public field.
+     */
+    private fileToolRootsFor;
+    /**
+     * A worker's tool config: it inherits this instance's file-tool roots, and a
+     * worker-level `fileRoots` may only narrow them (throws otherwise).
+     */
+    private workerToolsConfig;
+    /** File-tool roots for one call: per-call roots narrow the instance's `tools.fileRoots`. */
+    private resolveFileToolRoots;
     getToolsConfig(): ToolConfig | undefined;
     /**
      * Tools discovered via `search_tools` for a session (`tools.discovery`