Shell Execution Tools

Relevant source files

• codex-rs/core-plugins/src/script_attribution.rs
• codex-rs/core-plugins/src/script_attribution_tests.rs
• codex-rs/core/src/exec.rs
• codex-rs/core/src/exec_policy.rs
• codex-rs/core/src/exec_policy_tests.rs
• codex-rs/core/src/exec_policy_windows_tests.rs
• codex-rs/core/src/sandboxing/mod.rs
• codex-rs/core/src/shell.rs
• codex-rs/core/src/shell_snapshot.rs
• codex-rs/core/src/shell_snapshot_tests.rs
• codex-rs/core/src/tasks/user_shell.rs
• codex-rs/core/src/tools/orchestrator.rs
• codex-rs/core/src/tools/runtimes/apply_patch.rs
• codex-rs/core/src/tools/runtimes/apply_patch_tests.rs
• codex-rs/core/src/tools/runtimes/mod.rs
• codex-rs/core/src/tools/runtimes/mod_tests.rs
• codex-rs/core/src/tools/runtimes/shell.rs
• codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs
• codex-rs/core/src/tools/runtimes/shell/unix_escalation_tests.rs
• codex-rs/core/src/tools/runtimes/unified_exec.rs
• codex-rs/core/src/tools/sandboxing.rs
• codex-rs/core/tests/common/zsh_fork.rs
• codex-rs/core/tests/suite/approvals.rs
• codex-rs/core/tests/suite/exec_policy.rs
• codex-rs/core/tests/suite/models_etag_responses.rs
• codex-rs/core/tests/suite/shell_snapshot.rs
• codex-rs/core/tests/suite/skill_approval.rs
• codex-rs/shell-command/src/bash.rs
• codex-rs/shell-command/src/parse_command.rs

This page documents the shell execution tools that enable Codex to run commands on the user's system. These tools are the primary interface for executing shell commands, managing interactive processes, and handling multi-turn command interactions. It covers the core shell abstraction, the specialized unix_escalation protocol for Zsh, and the unified interactive execution system.

Overview

Codex provides shell execution capabilities through tools that handle both non-interactive script execution and interactive PTY sessions. The system supports multiple backends, including a standard process spawner and a specialized zsh fork for enhanced control and safety.

Tool Name	Purpose	Implementation Runtime	Backend Options
shell_command	Execute script-style commands	ShellRuntime codex-rs/core/src/tools/runtimes/shell.rs90	Classic, ZshFork
exec_command	Interactive PTY sessions	UnifiedExecRuntime codex-rs/core/src/tools/runtimes/unified_exec.rs98	Direct or ZshFork
write_stdin	Send input to running PTY	UnifiedExecProcessManager	ProcessStore

The execution environment is governed by ExecParams codex-rs/core/src/exec.rs92-105 and ExecRequest codex-rs/core/src/sandboxing/mod.rs47-70 which encapsulate command arguments, working directories, environment variables, and sandbox policies.

Sources: codex-rs/core/src/exec.rs92-105 codex-rs/core/src/sandboxing/mod.rs47-70 codex-rs/core/src/tools/runtimes/shell.rs90-92 codex-rs/core/src/tools/runtimes/unified_exec.rs98-102

Backend Selection and Execution Flow

The system selects a backend based on configuration and the user's environment. On Unix systems, the zsh fork is preferred for its ability to intercept execve calls and apply granular security policies.

Title: Shell Execution Backend Routing

Implementation Details:

• ZshFork: If Feature::ShellZshFork is enabled and the user shell is Zsh codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs114-121 the system uses a patched zsh binary and codex-shell-escalation server codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs52-65
• Standard Execution: Falls back to execute_env which calls execute_exec_request codex-rs/core/src/sandboxing/mod.rs180-185

Sources: codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs114-121 codex-rs/core/src/sandboxing/mod.rs180-185 codex-rs/core/src/tools/runtimes/shell.rs76-88

Unified Exec: Interactive Process Management

The Unified Exec system manages long-running interactive processes (PTYs) that persist across multiple model turns. It is orchestrated by the UnifiedExecProcessManager.

Process Lifecycle

1. Orchestration: The UnifiedExecRuntime codex-rs/core/src/tools/runtimes/unified_exec.rs98-102 handles approvals and sandbox selection via the ToolOrchestrator.
2. Execution: UnifiedExecRequest codex-rs/core/src/tools/runtimes/unified_exec.rs63-82 encapsulates the resolved parameters for the process manager.
3. Capture Policy: Uses ExecCapturePolicy::ShellTool to maintain historical output caps and timeout behavior codex-rs/core/src/exec.rs108-111
4. Pruning: The process manager maintains a ProcessStore to manage active handles, pruning them when limits are reached.

Output Streaming

Live output is streamed back to the session via EventMsg::ExecCommandOutputDelta codex-rs/core/src/exec.rs37-38 The system enforces a limit of 10,000 delta events per call to prevent flooding codex-rs/core/src/exec.rs80 Hard caps are enforced by EXEC_OUTPUT_MAX_BYTES (defined by DEFAULT_OUTPUT_BYTES_CAP) codex-rs/core/src/exec.rs76

Sources: codex-rs/core/src/tools/runtimes/unified_exec.rs63-102 codex-rs/core/src/exec.rs37-80 codex-rs/core/src/exec.rs108-115

Unix Escalation Protocol (Zsh Fork)

The unix_escalation module codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs1 implements a protocol for managing shell execution through a patched Zsh process. This allows Codex to intercept sub-commands and apply "Just-in-Time" (JIT) approvals.

Key Components

• EscalateServer: A communication bridge between the core agent and the patched shell codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs52
• EscalationSession: Manages the state of an escalated shell interaction codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs58
• codex-execve-wrapper: A wrapper binary used to intercept execution attempts via the EXEC_WRAPPER environment variable.

Approval Logic

If a command requires approval (based on AskForApproval settings), the system can pause execution and request user intervention. It specifically handles:

• Sandbox Approval: Required when a command attempts to break out of default sandbox constraints codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs84-85
• Rule-Based Approval: Triggered by specific exec_policy matches codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs86-87

Sources: codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs52-172 codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs82-87

Environment and Context Management

Before execution, Codex constructs a sanitized environment to prevent leaking sensitive information while ensuring the shell functions correctly.

Environment Variable Policy

The exec_env_for_sandbox_permissions function codex-rs/core/src/tools/runtimes/shell.rs27 prepares environment variables based on the requested sandbox permissions. This includes stripping managed proxy environment variables if escalated permissions are required to prevent bypasses.

Snapshot Integration

For POSIX shells (Bash/Zsh/sh), Codex can wrap commands to source a shell snapshot before execution codex-rs/core/src/tasks/user_shell.rs26 This ensures that aliases, functions, and exported variables from the user's interactive session are available to the agent.

Title: Environment Context to Rewritten Shell Command Mapping

Sources: codex-rs/core/src/tasks/user_shell.rs158-176 codex-rs/core/src/tools/runtimes/shell.rs27-28 codex-rs/core/src/shell_snapshot.rs28-41

User Shell Commands

The /shell command in the UI allows users to execute commands directly. This is handled by the UserShellCommandTask codex-rs/core/src/tasks/user_shell.rs60-68

• Permissions: Typically runs with standalone turn lifecycle logic codex-rs/core/src/tasks/user_shell.rs110-126
• Mode: Can run as a StandaloneTurn (new turn lifecycle) or ActiveTurnAuxiliary (within an existing turn) codex-rs/core/src/tasks/user_shell.rs50-57
• Timeout: Defaults to 1 hour (USER_SHELL_TIMEOUT_MS) for user-initiated commands codex-rs/core/src/tasks/user_shell.rs47

Sources: codex-rs/core/src/tasks/user_shell.rs47-126 codex-rs/core/src/tasks/user_shell.rs50-57