Crate paigasus_helikon_tools 

Sandboxed filesystem and process tools for the Paigasus Helikon AI SDK.

This crate provides agent Tools that operate inside a Sandbox — a directory opened as an OS-confined capability (cap-std), so ReadTool, WriteTool, and EditTool cannot escape it via .., absolute paths, or symlinks.

Containment and BashTool

BashTool runs commands through a pluggable ExecutionBackend, so its containment depends on the backend it is given. HostBackend (the default) is a cwd-pinned shell and NOT a security boundary — the cap-std containment that jails the filesystem tools does not extend to a spawned child process, which can read and write anything this process can (absolute paths, .., ~, and the network). With no PermissionPolicy installed the control layer is permissive, so a host-backed BashTool runs ungated — pair it with a PermissionPolicy or DenyRule::tool("Bash"). The OsSandboxBackend (behind the os-sandbox feature) instead enforces containment at the OS layer — on Linux via Landlock + seccomp (filesystem reads/writes + syscalls + network), on macOS via Seatbelt (sandbox-exec; write-only filesystem containment + an all-or-nothing network toggle). Each backend reports what it enforces via ExecutionBackend::guarantees, surfaced in the tool’s description.

Structs

BashTool

A shell tool backed by a pluggable ExecutionBackend.

BashToolBuilder

Builder for BashTool. Obtain one via BashTool::builder.

EditTool

Replace an exact string in a sandbox file. Refuses (does not guess) when old_string is missing or ambiguous.

ExecOutput

The captured result of one command run. Non-zero exit, timeout, and truncation are normal results the model inspects — never errors.

ExecRequest

A request to run one shell command. #[non_exhaustive] so per-call knobs (stdin, env overrides) can be added later without a breaking change.

HostBackend

The default, cwd-pinned execution backend. See the module docs: not a security boundary.

HostBackendBuilder

Builder for HostBackend.

ReadTool

Read a UTF-8 text file relative to the sandbox root, optionally windowed by line. Read-only; allowed under Plan mode.

ResourceLimits

Resource limits applied to a command via setrlimit (unix). Each None leaves the inherited limit. See HostBackend for the default policy.

Sandbox

A directory opened as an OS-confined capability. Filesystem operations performed through this handle are resolved relative to the root and cannot escape it (.., absolute paths, and escaping symlinks are rejected).

SandboxGuarantees

What a backend enforces, surfaced to docs / traces / the tool description.

WriteTool

Create or overwrite a file relative to the sandbox root, creating parent directories inside the sandbox as needed.

Enums

Isolation

The isolation level enforced on one axis (filesystem / network / syscalls).

SandboxError

Errors from constructing a Sandbox. In-invoke boundary violations use paigasus_helikon_core::ToolError::Denied, not this type.

Traits

ExecutionBackend

A backend that runs one shell command under some containment tier.