Logic to run after the model is called.
| 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: None |
shutdown_commands | tuple[str, ...] | list[str] | str | None | Default: None |
execution_policy | BaseExecutionPolicy | None | Default: None |
redaction_rules | tuple[RedactionRule, ...] | list[RedactionRule] | None | Default: None |
tool_description | str | None | Default: None |
tool_name | str | Default: SHELL_TOOL_NAME |
shell_command | Sequence[str] | str | None | Default: None |
env | Mapping[str, Any] | None | Default: None |
| 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 |
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.
Optional commands executed sequentially after the session starts.
Optional commands executed before the session shuts down.
Execution policy controlling timeouts, output limits, and resource configuration.
Defaults to HostExecutionPolicy for native execution.
Optional redaction rules to sanitize command output before returning it to the model.
Redaction rules are applied post execution and do not prevent
exfiltration of secrets or sensitive data when using
HostExecutionPolicy.
Optional override for the registered shell tool description.
Name for the registered shell tool.
Defaults to "shell".
Optional shell executable (string) or argument sequence used to launch the persistent session.
Defaults to an implementation-defined bash command.
Optional 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.