An Omni.Tool for file operations scoped to a base directory.

Provides read, write, patch, list, and delete commands over a configurable directory. Configuration controls whether writes are allowed and whether subdirectories are supported.

# Full read-write access with nested subdirectories
tool = Omni.Tools.Files.new(base_dir: "/data/workspace")

# Read-only access, flat (no subdirectories)
tool = Omni.Tools.Files.new(base_dir: "/data/docs", read_only: true, nested: false)

The tool delegates all operations to Omni.Tools.Files.FS, which can also be used independently of the tool machinery.

REPL integration

When using both Files and REPL tools together, the Omni.Tools.Repl.Extensions.Files extension lets agent code in the sandbox read and write files directly — without a separate tool use round-trip. See that module's docs for setup.

Options

Either pass a pre-built %FS{} struct or the options to build one:

• :fs — a %Omni.Tools.Files.FS{} struct. When provided, :base_dir, :read_only, and :nested are ignored.
• :base_dir (required if :fs is not given) — absolute path to the base directory (created on first write if it doesn't exist).
• :read_only — restricts to read and list only. Default false.
• :nested — allows subdirectory paths in ids. Default true.

Application config

Any option can be set under the module key in application config — instance opts to new/1 take precedence. See Omni.Tools for details.

config :omni_tools, Omni.Tools.Files,
  read_only: true,
  nested: false