Lightweight coding agent that runs in your terminal
Rust
Extend child commands with session and descriptor controls (#47604)
Charlie Marshb8d365b18ec2
diff --git a/codex-rs/exec-server/src/fs_sandbox.rs b/codex-rs/exec-server/src/fs_sandbox.rsindex db4c4872f4..eee175c0cf 100644--- a/codex-rs/exec-server/src/fs_sandbox.rs+++ b/codex-rs/exec-server/src/fs_sandbox.rs@@ -531,7 +531,7 @@ pub(crate) fn spawn_command(command.fallback(SpawnFallback::ReturnError);// macOS cannot receive passed fds with close-on-exec set atomically.#[cfg(target_os = "macos")]- command.descriptor_policy(DescriptorPolicy::StdioOnly);+ command.descriptor_policy(DescriptorPolicy::Explicit);command.spawn().map_err(io_error)}diff --git a/codex-rs/rmcp-client/src/stdio_server_launcher.rs b/codex-rs/rmcp-client/src/stdio_server_launcher.rsindex 65ba1f0c5a..84db78081e 100644--- a/codex-rs/rmcp-client/src/stdio_server_launcher.rs+++ b/codex-rs/rmcp-client/src/stdio_server_launcher.rs@@ -284,10 +284,10 @@ impl LocalStdioServerLauncher {command.process_mode(ProcessMode::NewGroup);// MCP uses only stdio; unrelated orchestrator descriptors must not// propagate into the server or commands it launches.- // StdioOnly is currently Unix-only. Windows can still inherit unrelated+ // Descriptor allowlisting is Unix-only. Windows can still inherit unrelated// handles and needs a handle allowlist in the shared spawn backend.#[cfg(unix)]- command.descriptor_policy(DescriptorPolicy::StdioOnly);+ command.descriptor_policy(DescriptorPolicy::Explicit);command};#[cfg(windows)]diff --git a/codex-rs/utils/pty/src/child_command.rs b/codex-rs/utils/pty/src/child_command.rsindex 01a010e1af..0f549c3719 100644--- a/codex-rs/utils/pty/src/child_command.rs+++ b/codex-rs/utils/pty/src/child_command.rs@@ -2,8 +2,8 @@//!//! The wrapped Tokio command is private: callers cannot install callbacks or//! change settings that the native backend cannot inspect. Children receive only-//! explicitly supplied environment variables and default to kill-on-drop. Stdio, descriptor-//! inheritance, and compatibility fallbacks are configured independently.+//! explicitly supplied environment variables and default to kill-on-drop. Stdio,+//! descriptor inheritance, and compatibility fallbacks are configured independently.use std::ffi::OsStr;#[cfg(unix)]@@ -15,18 +15,29 @@ use std::process::Stdio as TokioStdio;use crate::child::Child;use crate::child::ChildKind;-/// Relationship between a child and its parent's process group.+/// Relationship between a child and its parent's session and process group.+///+/// These settings apply only on Unix; other platforms use their default behavior.#[derive(Clone, Copy)]pub enum ProcessMode {+ /// Keep the parent's session, process group, and controlling terminal.Inherit,+ /// Create a process group led by the child, keeping the parent's session and+ /// controlling terminal. This allows signaling the child's group separately.NewGroup,+ /// Create a session and process group led by the child, detaching from the+ /// parent's controlling terminal.+ ///+ /// Native spawning is an optimization; compatibility fallbacks may fork.+ NewSession,}-/// Descriptors visible to a Unix child beyond its explicit stdio.+/// Whether Unix children inherit ambient descriptors or only explicit stdio and+/// the descriptors selected by `Command::preserve_fds`.#[derive(Clone, Copy, PartialEq, Eq)]pub enum DescriptorPolicy {Inherit,- StdioOnly,+ Explicit,}/// Whether a native launch may use Command's executable-text and PATH fallbacks.@@ -52,6 +63,7 @@ pub(crate) enum ChildDropPolicy {/// An explicit child stdin, including a socket used for bidirectional fd transfer.pub enum ChildStdin {Piped,+ Null,#[cfg(unix)]File(std::os::fd::OwnedFd),}@@ -65,6 +77,10 @@ pub struct Command {pub(crate) stdin: ChildStdin,pub(crate) drop_policy: ChildDropPolicy,#[cfg(unix)]+ pub(crate) inherited_fds: Vec<std::os::fd::RawFd>,+ #[cfg(target_os = "linux")]+ parent_pid: Option<libc::pid_t>,+ #[cfg(unix)]pub(crate) arg0: Option<OsString>,}@@ -85,6 +101,10 @@ impl Command {stdin: ChildStdin::Piped,drop_policy: ChildDropPolicy::KillAndReap,#[cfg(unix)]+ inherited_fds: Vec::new(),+ #[cfg(target_os = "linux")]+ parent_pid: None,+ #[cfg(unix)]arg0: None,}}@@ -152,6 +172,32 @@ impl Command {self}+ /// Preserve live inheritable descriptors at their existing numbers.+ /// The caller must keep them open until spawning returns. We do not duplicate+ /// or close them: closing even a duplicate releases the parent's POSIX record+ /// locks. Closed and CLOEXEC descriptors remain excluded.+ #[cfg(unix)]+ pub fn preserve_fds(&mut self, fds: &[std::os::fd::RawFd]) -> &mut Self {+ self.inherited_fds = fds+ .iter()+ .copied()+ .filter(|fd| {+ // SAFETY: fcntl reports invalid descriptors without dereferencing memory.+ let flags = unsafe { libc::fcntl(*fd, libc::F_GETFD) };+ *fd > libc::STDERR_FILENO && flags >= 0 && flags & libc::FD_CLOEXEC == 0+ })+ .collect();+ self+ }++ /// Keep the existing Linux pipe behavior when the spawning parent exits.+ #[cfg(target_os = "linux")]+ pub fn terminate_on_parent_death(&mut self) -> &mut Self {+ // SAFETY: getpid has no preconditions.+ self.parent_pid = Some(unsafe { libc::getpid() });+ self+ }+#[cfg(unix)]pub fn arg0(&mut self, arg0: impl AsRef<OsStr>) -> &mut Self {self.inner.arg0(arg0.as_ref());@@ -176,8 +222,10 @@ impl Command {let command = self.inner.as_std();let program = command.get_program();if (Path::new(program).is_relative()- || self.descriptor_policy == DescriptorPolicy::StdioOnly- || self.fallback == SpawnFallback::ReturnError)+ || self.descriptor_policy == DescriptorPolicy::Explicit+ || self.fallback == SpawnFallback::ReturnError+ || matches!(self.process_mode, ProcessMode::NewSession)+ || !self.inherited_fds.is_empty())&& !program.is_empty()&& let Some(child) = crate::child::macos::NativeChild::spawn(&self)?{@@ -186,17 +234,37 @@ impl Command {}self.inner.stdin(match self.stdin {ChildStdin::Piped => TokioStdio::piped(),+ ChildStdin::Null => TokioStdio::null(),#[cfg(unix)]ChildStdin::File(fd) => TokioStdio::from(fd),});#[cfg(unix)]- if self.descriptor_policy == DescriptorPolicy::StdioOnly {- // SAFETY: This preserves the existing Unix descriptor cleanup before exec.- unsafe {- self.inner.pre_exec(|| {- crate::pty::close_inherited_fds_except(&[]);- Ok(())- });+ {+ let new_session = matches!(self.process_mode, ProcessMode::NewSession);+ let explicit_fds = self.descriptor_policy == DescriptorPolicy::Explicit;+ let targets = self.inherited_fds;+ #[cfg(target_os = "linux")]+ let parent_pid = self.parent_pid;+ #[cfg(not(target_os = "linux"))]+ let parent_pid: Option<i32> = None;+ if new_session || explicit_fds || !targets.is_empty() || parent_pid.is_some() {+ // SAFETY: Keep the existing Unix pre-exec setup in the fallback+ // backend. The caller keeps the selected descriptors open, and+ // this callback only changes the child's descriptor table.+ unsafe {+ self.inner.pre_exec(move || {+ if new_session {+ crate::process_group::detach_from_tty()?;+ }+ if let Some(parent_pid) = parent_pid {+ crate::process_group::set_parent_death_signal(parent_pid)?;+ }+ if explicit_fds {+ crate::pty::close_inherited_fds_except(&targets);+ }+ Ok(())+ });+ }}}#[cfg(unix)]diff --git a/codex-rs/utils/pty/src/child_tests.rs b/codex-rs/utils/pty/src/child_tests.rsindex 0fd28e8360..b3dedb376e 100644--- a/codex-rs/utils/pty/src/child_tests.rs+++ b/codex-rs/utils/pty/src/child_tests.rs@@ -1,4 +1,4 @@-//! Regression coverage for output-pipe lifetimes and runtime-independent reaping.+//! Regression coverage for child descriptors, process modes, and runtime-independent reaping.use std::future::Future;use std::future::poll_fn;@@ -161,3 +161,171 @@ fn wait_until_reaped(pid: u32) -> anyhow::Result<()> {}Ok(())}++#[tokio::test]+async fn preserved_descriptor_can_use_the_last_slot_below_the_limit() -> anyhow::Result<()> {+ use std::os::fd::AsRawFd;+ use std::os::fd::FromRawFd;+ if std::env::var_os("CODEX_TEST_ISOLATED_FD_LIMIT").is_none() {+ let output = std::process::Command::new(std::env::current_exe()?)+ .args([+ "--exact",+ "child::tests::preserved_descriptor_can_use_the_last_slot_below_the_limit",+ "--nocapture",+ ])+ .env("CODEX_TEST_ISOLATED_FD_LIMIT", "1")+ .output()?;+ assert!(output.status.success(), "{output:?}");+ return Ok(());+ }+ // Use a known, small limit without changing other tests' process-wide limit.+ let mut limit = std::mem::MaybeUninit::<libc::rlimit>::uninit();+ // SAFETY: getrlimit initializes writable storage.+ assert_eq!(+ unsafe { libc::getrlimit(libc::RLIMIT_NOFILE, limit.as_mut_ptr()) },+ 0+ );+ // SAFETY: getrlimit succeeded.+ let mut limit = unsafe { limit.assume_init() };+ limit.rlim_cur = limit.rlim_cur.min(256);+ // SAFETY: Only this isolated test process's soft limit is lowered.+ assert_eq!(unsafe { libc::setrlimit(libc::RLIMIT_NOFILE, &limit) }, 0);+ let last = i32::try_from(limit.rlim_cur - 1)?;+ let root = tempfile::tempdir()?;+ let path = root.path().join("input");+ std::fs::write(&path, "preserved")?;+ let source = std::fs::File::open(path)?;+ let fd = unsafe { libc::fcntl(source.as_raw_fd(), libc::F_DUPFD_CLOEXEC, last) };+ anyhow::ensure!(fd == last, "could not reserve the last descriptor slot");+ let fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fd) };+ assert_eq!(unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_SETFD, 0) }, 0);+ let mut command = crate::Command::new("/bin/cat");+ command+ .arg(format!("/dev/fd/{last}"))+ .stdin(crate::ChildStdin::Null)+ .descriptor_policy(crate::DescriptorPolicy::Explicit)+ .preserve_fds(&[last]);+ let output = command.spawn()?.wait_with_output().await?;+ assert!(output.status.success(), "{output:?}");+ assert_eq!(output.stdout, b"preserved");+ Ok(())+}++#[tokio::test]+async fn process_mode_is_preserved_by_both_backends() -> anyhow::Result<()> {+ use crate::ProcessMode;+ use std::os::unix::fs::PermissionsExt;+ let root = tempfile::tempdir()?;+ std::os::unix::fs::symlink("/bin/cat", root.path().join("server"))?;+ let script = root.path().join("executable-text");+ std::fs::write(&script, "exec /bin/cat\n")?;+ std::fs::set_permissions(&script, std::fs::Permissions::from_mode(/*mode*/ 0o755))?;+ for program in ["./server", "/bin/cat", "./executable-text"] {+ for mode in [+ ProcessMode::Inherit,+ ProcessMode::NewGroup,+ ProcessMode::NewSession,+ ] {+ let mut command = Command::new(program);+ command.current_dir(root.path()).process_mode(mode);+ let mut child = match command.spawn() {+ Ok(child) => child,+ Err(error) if program == "./executable-text" => {+ // Executable-text fallback depends on both libc and std's+ // spawn backend. Compare the same mode with std directly.+ let mut baseline = tokio::process::Command::new(program);+ baseline+ .current_dir(root.path())+ .env_clear()+ .kill_on_drop(true);+ match mode {+ ProcessMode::Inherit => {}+ ProcessMode::NewGroup => {+ baseline.process_group(/*pgroup*/ 0);+ }+ ProcessMode::NewSession => {+ // SAFETY: Session setup is async-signal-safe.+ unsafe {+ baseline.pre_exec(crate::process_group::detach_from_tty);+ }+ }+ }+ let expected = baseline+ .spawn()+ .expect_err("legacy spawn must also reject executable text");+ assert_eq!(error.raw_os_error(), expected.raw_os_error());+ continue;+ }+ Err(error) => return Err(error.into()),+ };+ let pid = child.id().expect("live PID") as libc::pid_t;+ // SAFETY: These calls only inspect the current process.+ let (parent_group, parent_session) = unsafe { (libc::getpgrp(), libc::getsid(0)) };+ let expected = match mode {+ ProcessMode::Inherit => (parent_group, parent_session),+ ProcessMode::NewGroup => (pid, parent_session),+ ProcessMode::NewSession => (pid, pid),+ };+ // SAFETY: The child is still owned and blocked on its stdin pipe.+ assert_eq!(unsafe { (libc::getpgid(pid), libc::getsid(pid)) }, expected);+ child.kill().await?;+ }+ }+ Ok(())+}++#[tokio::test]+async fn preserving_descriptors_keeps_parent_record_locks() -> anyhow::Result<()> {+ use std::io::Read;+ if let Some(path) = std::env::var_os("CODEX_TEST_RECORD_LOCK") {+ // Wait until spawn has returned and dropped the parent's command.+ std::io::stdin().read_exact(&mut [0])?;+ let file = std::fs::OpenOptions::new().write(true).open(path)?;+ // SAFETY: A zeroed flock with these fields describes the whole file.+ let mut lock: libc::flock = unsafe { std::mem::zeroed() };+ lock.l_type = libc::F_WRLCK as _;+ lock.l_whence = libc::SEEK_SET as _;+ assert_eq!(+ unsafe { libc::fcntl(file.as_raw_fd(), libc::F_SETLK, &lock) },+ -1+ );+ assert!(matches!(+ std::io::Error::last_os_error().raw_os_error(),+ Some(libc::EACCES | libc::EAGAIN)+ ));+ return Ok(());+ }+ let file = tempfile::NamedTempFile::new()?;+ // SAFETY: The descriptor remains owned and open throughout the launch.+ assert_eq!(+ unsafe { libc::fcntl(file.as_raw_fd(), libc::F_SETFD, 0) },+ 0+ );+ let mut lock: libc::flock = unsafe { std::mem::zeroed() };+ lock.l_type = libc::F_WRLCK as _;+ lock.l_whence = libc::SEEK_SET as _;+ assert_eq!(+ unsafe { libc::fcntl(file.as_raw_fd(), libc::F_SETLK, &lock) },+ 0+ );+ let mut command = Command::new(std::env::current_exe()?);+ command+ .args([+ "--exact",+ "child::tests::preserving_descriptors_keeps_parent_record_locks",+ "--nocapture",+ ])+ .env("CODEX_TEST_RECORD_LOCK", file.path())+ .descriptor_policy(crate::DescriptorPolicy::Explicit)+ .preserve_fds(&[file.as_raw_fd()]);+ let mut child = command.spawn()?;+ child+ .stdin+ .take()+ .expect("piped stdin")+ .write_all(b"x")+ .await?;+ let output = child.wait_with_output().await?;+ assert!(output.status.success(), "{output:?}");+ Ok(())+}diff --git a/codex-rs/utils/pty/src/macos_child.rs b/codex-rs/utils/pty/src/macos_child.rsindex 5a0158b848..7d3f5a34d0 100644--- a/codex-rs/utils/pty/src/macos_child.rs+++ b/codex-rs/utils/pty/src/macos_child.rs@@ -27,6 +27,10 @@ use crate::child_command::ChildDropPolicy;use crate::child::reaper;+// Apple's spawn.h defines this extension on our minimum macOS 12, but libc+// does not expose it. A new session also creates a new process group.+const POSIX_SPAWN_SETSID: libc::c_int = 0x0400;+// libc does not expose this Apple extension. It is available since macOS 10.15,// before Codex's minimum supported macOS version (12).unsafe extern "C" {@@ -96,6 +100,7 @@ impl NativeChild {Some(ChildStdin::from_std(OwnedFd::from(writer).into())?),)}+ crate::ChildStdin::Null => (std::fs::File::open("/dev/null")?.into(), None),crate::ChildStdin::File(fd) => (fd.try_clone()?, None),};let (stdout_read, stdout_write) = io::pipe()?;@@ -129,8 +134,19 @@ impl NativeChild {target as i32,))?;}+ for target in &request.inherited_fds {+ let result =+ libc::posix_spawn_file_actions_adddup2(&mut actions.0, *target, *target);+ // macOS file actions can reject valid high descriptors below+ // RLIMIT_NOFILE. The existing dup2 fallback supports them.+ if result == libc::EBADF && request.fallback == crate::SpawnFallback::Compatible {+ return Ok(None);+ }+ cvt(result)?;+ }let group_flags = match request.process_mode {crate::ProcessMode::Inherit => 0,+ crate::ProcessMode::NewSession => POSIX_SPAWN_SETSID,crate::ProcessMode::NewGroup => {cvt(libc::posix_spawnattr_setpgroup(&mut attrs.0,@@ -145,7 +161,7 @@ impl NativeChild {cvt(libc::posix_spawnattr_setsigdefault(&mut attrs.0, &defaults))?;let descriptor_flags = match request.descriptor_policy {crate::DescriptorPolicy::Inherit => 0,- crate::DescriptorPolicy::StdioOnly => libc::POSIX_SPAWN_CLOEXEC_DEFAULT,+ crate::DescriptorPolicy::Explicit => libc::POSIX_SPAWN_CLOEXEC_DEFAULT,};cvt(libc::posix_spawnattr_setflags(&mut attrs.0,diff --git a/codex-rs/utils/pty/src/macos_child_tests.rs b/codex-rs/utils/pty/src/macos_child_tests.rsindex 921a71bfa7..b2a29876ff 100644--- a/codex-rs/utils/pty/src/macos_child_tests.rs+++ b/codex-rs/utils/pty/src/macos_child_tests.rs@@ -296,26 +296,3 @@ fn dropping_after_runtime_shutdown_kills_and_reaps_child() -> anyhow::Result<()>);Ok(())}--#[tokio::test]-async fn process_mode_is_preserved_by_both_backends() -> anyhow::Result<()> {- let root = tempfile::tempdir()?;- symlink("/bin/cat", root.path().join("server"))?;- for program in ["./server", "/bin/cat"] {- for mode in [ProcessMode::Inherit, ProcessMode::NewGroup] {- let mut command = Command::new(program);- command.current_dir(root.path()).process_mode(mode);- let mut child = command.spawn()?;- let pid = child.id().expect("live PID") as libc::pid_t;- let expected = match mode {- // SAFETY: getpgrp only inspects the current process.- ProcessMode::Inherit => unsafe { libc::getpgrp() },- ProcessMode::NewGroup => pid,- };- // SAFETY: The child is still owned and blocked on its stdin pipe.- assert_eq!(unsafe { libc::getpgid(pid) }, expected);- child.kill().await?;- }- }- Ok(())-}diff --git a/codex-rs/utils/pty/src/macos_descriptor_tests.rs b/codex-rs/utils/pty/src/macos_descriptor_tests.rsindex 405c14b852..7b4da64645 100644--- a/codex-rs/utils/pty/src/macos_descriptor_tests.rs+++ b/codex-rs/utils/pty/src/macos_descriptor_tests.rs@@ -3,6 +3,7 @@use super::*;use pretty_assertions::assert_eq;use std::fs;+use std::io::Seek;use std::os::fd::AsRawFd;use std::os::fd::FromRawFd;use std::os::fd::OwnedFd;@@ -34,7 +35,7 @@ async fn explicit_stdio_excludes_inheritable_descriptors_without_changing_parentlet mut command = Command::new("/bin/sh");command.args(["-c", &script])- .descriptor_policy(DescriptorPolicy::StdioOnly);+ .descriptor_policy(DescriptorPolicy::Explicit);let output = command.spawn()?.wait_with_output().await?;assert_eq!((output.status.success(), output.stdout, output.stderr),@@ -59,7 +60,7 @@ async fn socket_stdin_preserves_bidirectional_io_and_custom_argv0() -> anyhow::R.arg0("helper").env("FS_TEST", "literal ; $value").stdin(ChildStdin::File(socket.into()))- .descriptor_policy(DescriptorPolicy::StdioOnly)+ .descriptor_policy(DescriptorPolicy::Explicit).fallback(SpawnFallback::ReturnError);let child = command.spawn()?;assert!(child.stdin.is_none());@@ -92,3 +93,44 @@ async fn native_launch_can_reject_executable_text_without_shell_fallback() -> anassert_eq!(error.raw_os_error(), Some(libc::ENOEXEC));Ok(())}++#[tokio::test]+async fn inherited_descriptors_survive_native_and_executable_text_spawns() -> anyhow::Result<()> {+ let directory = tempfile::tempdir()?;+ let data = directory.path().join("data");+ fs::write(&data, "captured descriptor")?;+ let mut file = fs::File::open(&data)?;+ for native in [true, false] {+ file.rewind()?;+ // SAFETY: Duplicate this live file into a new inheritable descriptor.+ let raw = unsafe { libc::fcntl(file.as_raw_fd(), libc::F_DUPFD, 100) };+ assert!(raw >= 100);+ // SAFETY: fcntl returned a newly owned descriptor.+ let _original = unsafe { OwnedFd::from_raw_fd(raw) };+ let descriptor = format!("/dev/fd/{raw}");+ let mut command = if native {+ let mut command = Command::new("/bin/cat");+ command.arg(&descriptor);+ command+ } else {+ let script = directory.path().join("executable-text");+ fs::write(&script, format!("/bin/cat {descriptor}\n"))?;+ fs::set_permissions(&script, fs::Permissions::from_mode(/*mode*/ 0o755))?;+ Command::new(script)+ };+ command+ .descriptor_policy(DescriptorPolicy::Explicit)+ .preserve_fds(&[raw]);+ let child = command.spawn()?;+ assert_eq!(+ matches!(child.inner, crate::child::ChildKind::Native(_)),+ native+ );+ let output = child.wait_with_output().await?;+ assert_eq!(+ (output.status.code(), output.stdout, output.stderr),+ (Some(0), b"captured descriptor".to_vec(), vec![])+ );+ }+ Ok(())+}