Hmbown/CodeWhale · error · anyhow::Error

TTY mode requires background execution (set background: true

Error message

TTY mode requires background execution (set background: true).

What it means

TTY shell mode is implemented only on the background execution path (execute_background/_sandboxed with a pty). The foreground synchronous path (execute_sync_sandboxed) has no way to attach a TTY and stream interaction, so requesting tty: true with background: false/absent is rejected up front with this message.

Source

Thrown at crates/tui/src/tools/shell.rs:2044

            let bounded_output = timeout_bounds_ms == (1, BASH_MAX_TIMEOUT_MS);
            self.spawn_background_sandboxed(
                command,
                &work_dir,
                &exec_env,
                None,
                stdin_data,
                tty,
                ShellSpawnContext {
                    owner_agent,
                    owner_session_id,
                    work_lifecycle,
                },
                persist_pending,
                bounded_output,
            )
        } else {
            if tty {
                return Err(anyhow!(
                    "TTY mode requires background execution (set background: true)."
                ));
            }
            Self::execute_sync_sandboxed(command, &work_dir, timeout_ms, stdin_data, &exec_env)
        }
    }

    /// Interactive variant that accepts extra env vars (#456 shell_env hook).
    pub fn execute_interactive_with_policy_env(
        &mut self,
        command: &str,
        working_dir: Option<&str>,
        timeout_ms: u64,
        policy_override: Option<ExecutionSandboxPolicy>,
        extra_env: HashMap<String, String>,
    ) -> Result<ShellResult> {
        crate::shell_dispatcher::ShellDispatcher::log_exec(command);

View on GitHub (pinned to 0c42157ee5)

Solutions

Set background: true together with tty: true, then interact via stdin/output polling.
If you need synchronous output, drop tty and read the captured stdout/stderr instead.

Example fix

// before
exec_shell("python3", { tty: true })

// after
exec_shell("python3", { tty: true, background: true })

Defensive patterns

Strategy: validation

Validate before calling

if request.tty && !request.background {
    return Err("tty requires background: true");
}
exec_shell(request)?;

Type guard

function isValidShellRequest(req: { tty?: boolean; background?: boolean }): boolean {
  return !req.tty || req.background === true;
}

Prevention

Treat tty and background as a paired option: always set background: true when tty: true.
Validate the flag combination at request-build time, not after the error round-trip.

When it happens

Trigger: Calling the shell execute API with tty: true and background unset/false — the sync path is chosen and the tty flag is checked before dispatch.

Common situations: An agent wants interactive output but forgot the background flag; a caller copies tty from another tool's schema without enabling background.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/fda1d26636d97aa0. Report an issue: GitHub.