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.
ShellToolMiddleware(
self,
workspace_root: str | Path | None = None,
*,
startup_commands: tuple[str, ...] | list[str] | str | None = None,
shutdown_commands: tuple[str, ...] | list[str] | str | None = None,
execution_policy: BaseExecutionPolicy | None = None,
redaction_rules: tuple[RedactionRule, ...] | list[RedactionRule] | None = None,
tool_description: str | None = None,
tool_name: str = SHELL_TOOL_NAME,
shell_command: Sequence[str] | str | None = None,
env: Mapping[str, Any] | None = None
)| Name | Type | Description |
|---|---|---|
workspace_root | str | Path | None | Default: NoneBase directory for the shell session. If omitted, a temporary directory is created when the agent starts and removed when it ends. |
startup_commands | tuple[str, ...] | list[str] | str | None | Default: NoneOptional commands executed sequentially after the session starts. |
shutdown_commands | tuple[str, ...] | list[str] | str | None | Default: NoneOptional commands executed before the session shuts down. |
execution_policy | BaseExecutionPolicy | None | Default: NoneExecution policy controlling timeouts, output limits, and resource configuration. Defaults to |
redaction_rules | tuple[RedactionRule, ...] | list[RedactionRule] | None | Default: NoneOptional redaction rules to sanitize command output before returning it to the model. Warning Redaction rules are applied post execution and do not prevent
exfiltration of secrets or sensitive data when using
|
tool_description | str | None | Default: NoneOptional override for the registered shell tool description. |
tool_name | str | Default: SHELL_TOOL_NAMEName for the registered shell tool. Defaults to |
shell_command | Sequence[str] | str | None | Default: NoneOptional shell executable (string) or argument sequence used to launch the persistent session. Defaults to an implementation-defined bash command. |
env | Mapping[str, Any] | None | Default: NoneOptional environment variables to supply to the shell session. Values are coerced to strings before command execution. If omitted, the session inherits the parent process environment. |
| Name | Type |
|---|---|
| workspace_root | str | Path | None |
| startup_commands | tuple[str, ...] | list[str] | str | None |
| shutdown_commands | tuple[str, ...] | list[str] | str | None |
| execution_policy | BaseExecutionPolicy | None |
| redaction_rules | tuple[RedactionRule, ...] | list[RedactionRule] | None |
| tool_description | str | None |
| tool_name | str |
| shell_command | Sequence[str] | str | None |
| env | Mapping[str, Any] | None |
Start the shell session and run startup commands.
Async start the shell session and run startup commands.
Run shutdown commands and release resources when an agent completes.
Async run shutdown commands and release resources when an agent completes.
Logic to run before the model is called.
Async logic to run before the model is called.
Logic to run after the model is called.
Async logic to run after the model is called.
Intercept and control model execution via handler callback.
Intercept and control async model execution via handler callback.
Intercept tool execution for retries, monitoring, or modification.
Intercept and control async tool execution via handler callback.