Imported from Recusive/Orbit-Code (codex-rs/shell-escalation/AGENTS.md). Install upstream with npx skills add Recusive/Orbit-Code --skill shell-escalation. Copyright stays with the author.

codex-rs/shell-escalation/

This file applies to codex-rs/shell-escalation/ and its descendants. Follow the repo root AGENTS.md first, then use the local rules below when you edit this subtree.

Agent Guidance

• Follow the repo-root Rust rules in /Users/no9labs/Developer/Recursive/codex/AGENTS.md: keep modules focused, prefer exhaustive matches, and avoid touching sandbox-env handling unless the task explicitly requires it.
• This subtree belongs to the codex-shell-escalation crate. Keep public re-exports, module wiring, and tests in sync with any behavior changes here.

Validate

• cd /Users/no9labs/Developer/Recursive/codex/codex-rs && cargo test -p codex-shell-escalation

Directory Map

The summary below is based on the existing directory documentation and cross-checked against the files currently present here.

Unix shell-escalation protocol and codex-execve-wrapper binary.

What this folder does

Implements the exec-interception protocol that allows a sandboxed shell to escalate commands to run outside the sandbox. A patched bash invokes codex-execve-wrapper on every exec() call. The wrapper sends the proposed command to the escalation server over a Unix domain socket, and the server responds with Run (execute in sandbox), Escalate (forward file descriptors and execute outside sandbox), or Deny (reject the command).

What it plugs into

• Used by codex-core for sandbox command execution on Unix.
• The EscalateServer is instantiated by the runtime when running shell commands with sandbox escalation.
• The codex-execve-wrapper binary is set as the EXEC_WRAPPER / BASH_EXEC_WRAPPER environment variable for the patched shell.

Imports from

• codex-protocol -- EscalationPermissions, Permissions, approval types.
• codex-utils-absolute-path -- path normalization.
• socket2 -- Unix socket pair creation.
• tokio, tokio-util -- async runtime, cancellation tokens.
• clap -- CLI argument parsing for the wrapper binary.
• libc -- low-level Unix syscalls (execv, dup2, etc.).

Exports to

• EscalateServer -- the server that listens for escalation requests.
• EscalationSession -- session handle with environment overlay for the shell process.
• EscalationPolicy trait -- callers implement this to decide Run/Escalate/Deny.
• ShellCommandExecutor trait -- callers implement this for process spawning.
• ExecParams, ExecResult, PreparedExec -- execution parameter/result types.
• Stopwatch -- pausable timer for command timeouts.
• main_execve_wrapper -- entrypoint for the wrapper binary.
• ESCALATE_SOCKET_ENV_VAR -- environment variable name for the socket FD.

Key files

• Cargo.toml -- crate manifest; builds codex-execve-wrapper binary.
• README.md -- protocol documentation and patched-bash build instructions.
• src/lib.rs -- conditional compilation gate (Unix only) and public re-exports.
• src/unix/ -- Unix implementation.