FilesystemMiddlewareOptions

Backend instance or factory (default: StateBackend)

Optional descriptions for built-in filesystem tools.

Keys correspond to FsToolName. Descriptions for tools that are not enabled by the tools allowlist are ignored because those tools are not exposed to the model.

Default cap on the number of matches the grep tool returns (default: 1000).

When the cap is hit, the returned matches are flagged as truncated and a note tells the model to narrow the search. A per-call max_count tool argument overrides this default. Set to null to disable the cap.

Optional token limit before evicting a HumanMessage to the filesystem (default: 50000 tokens, ~200KB)

Filesystem permission rules enforced on every tool call.

Rules are evaluated in declaration order; first match wins; permissive default. Applies to ls, read_file, write_file, edit_file, glob, and grep.

Note on execute: permissions are not enforced on execute because shell commands can access any path regardless of path-based rules. Using permissions with an execution-capable backend (one where isSandboxBackend returns true) throws a ConfigurationError unless either:

• execute is disabled via tools, or
• the backend is a CompositeBackend and every permission path is scoped to a route prefix.

When omitted or empty, all filesystem operations are permitted.

Optional filesystem-specific usage guidance. Omitted by default because tool schemas provide it.

Allowlist of built-in filesystem tools to expose to the model.

• undefined, null, and "all" preserve the default behavior: every filesystem tool is registered, subject to backend capability filtering.
• Passing an array restricts the middleware to only those tool names.
• read_file must be included in every explicit array because it is used by normal file-inspection flows and by large-result recovery guidance.
• Backend capability checks still narrow the final visible tool set. For example, execute is removed when the resolved backend does not support command execution, even if it appears in this allowlist.
• User-provided non-filesystem tools are not affected by this allowlist.

Optional token limit before evicting a tool result to the filesystem (default: 20000 tokens, ~80KB)