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.
Check model call limits before making a model call.
Async check model call limits before making a model call.
Check for parallel write_todos tool calls and return errors if detected.
Check for parallel write_todos tool calls and return errors if detected.
Update the system message to include the todo system prompt.
Update the system message to include the todo system prompt.
Intercept tool execution for retries, monitoring, or modification.
Intercept and control async tool execution via handler callback.