shell_tool

Annotation used to mark state attributes as purely internal for a given middleware.

Configuration contract for persistent shell sessions.

Concrete subclasses encapsulate how a shell process is launched and constrained.

Each policy documents its security guarantees and the operating environments in which it is appropriate. Use HostExecutionPolicy for trusted, same-host execution; CodexSandboxExecutionPolicy when the Codex CLI sandbox is available and you want additional syscall restrictions; and DockerExecutionPolicy for container-level isolation using Docker.

Launch the shell through the Codex CLI sandbox.

Ideal when you have the Codex CLI installed and want the additional syscall and filesystem restrictions provided by Anthropic's Seatbelt (macOS) or Landlock/seccomp (Linux) profiles. Commands still run on the host, but within the sandbox requested by the CLI. If the Codex binary is unavailable or the runtime lacks the required kernel features (e.g., Landlock inside some containers), process startup fails with a RuntimeError.

Configure sandbox behavior via config_overrides to align with your Codex CLI profile. This policy does not add its own resource limits; combine it with host-level guards (cgroups, container resource limits) as needed.

Run the shell inside a dedicated Docker container.

Choose this policy when commands originate from untrusted users or you require strong isolation between sessions. By default the workspace is bind-mounted only when it refers to an existing non-temporary directory; ephemeral sessions run without a mount to minimise host exposure. The container's network namespace is disabled by default (--network none) and you can enable further hardening via read_only_rootfs and user.

The security guarantees depend on your Docker daemon configuration. Run the agent on a host where Docker is locked down (rootless mode, AppArmor/SELinux, etc.) and review any additional volumes or capabilities passed through extra_run_args. The default image is python:3.12-alpine3.19; supply a custom image if you need preinstalled tooling.

Run the shell directly on the host process.

This policy is best suited for trusted or single-tenant environments (CI jobs, developer workstations, pre-sandboxed containers) where the agent must access the host filesystem and tooling without additional isolation. Enforces optional CPU and memory limits to prevent runaway commands but offers no filesystem or network sandboxing; commands can modify anything the process user can reach.

On Linux platforms resource limits are applied with resource.prlimit after the shell starts. On macOS, where prlimit is unavailable, limits are set in a preexec_fn before exec. In both cases the shell runs in its own process group so timeouts can terminate the full subtree.

Raised when configured to block on detected sensitive values.

Represents an individual match of sensitive data.

Configuration for handling a single PII type.

Resolved redaction rule ready for execution.

Base middleware class for an agent.

Subclass this and implement any of the defined methods to customize agent behavior between steps in the main agent loop.

State schema for the agent.

Agent state extension for tracking shell session resources.

Structured result from command execution.

Persistent shell session that supports sequential command execution.

Middleware that registers a persistent shell tool for agents.

The middleware exposes a single long-lived shell session. Use the execution policy to match your deployment's security posture:

• HostExecutionPolicy – full host access; best for trusted environments where the agent already runs inside a container or VM that provides isolation.
• CodexSandboxExecutionPolicy – reuses the Codex CLI sandbox for additional syscall/filesystem restrictions when the CLI is available.
• DockerExecutionPolicy – launches a separate Docker container for each agent run, providing harder isolation, optional read-only root filesystems, and user remapping.

When no policy is provided the middleware defaults to HostExecutionPolicy.