TTY mode requires background execution (set background…

Error message

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

What it means

The shell tool's foreground (synchronous) execution path does not support TTY mode. When a command is executed in the foreground with `tty: true`, the tool refuses before spawning because a PTY-backed child cannot be managed correctly on the synchronous path. The error tells you exactly how to proceed: run the command with `background: true` so it goes through the background PTY lane.

Solutions

Set `background: true` along with `tty: true` so the command runs on the background PTY path, and drive it via `action: "interact"` with the returned task_id
If the command does not actually need a TTY (non-interactive work), drop `tty: true` and run it in the foreground
Use the persistent PTY tools (`terminal/run` / `terminal/send`) instead of the one-shot shell tool
Launch the command in a new terminal window if it requires a full interactive terminal

Example fix

// before
{ "command": "python", "tty": true }
// after
{ "command": "python", "tty": true, "background": true }

Defensive patterns

Strategy: validation

Validate before calling

// before invoking the tool
if request.tty && !request.background {
    return Err("tty requires background: set background: true or drop tty");
}

Prevention

Default to non-TTY foreground execution; only add tty when the program truly needs one
Whenever you set tty: true, always set background: true and drive the task via task_id/interact
For interactive programs prefer the terminal/run + terminal/send persistent PTY lane

When it happens

Trigger: Calling the shell/bash tool with `tty: true` while `background` is false/absent, so control reaches the `else` branch of execute() which calls execute_sync_sandboxed only when tty is false.

Common situations: Users ask the agent to run interactive programs (REPLs, editors, watch tasks, programs prompting for input/passwords) in the foreground; agents set tty: true for such commands without setting background: true; older sessions or prompts that never set background.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/fda1d26636d97aa0. Report an issue: GitHub.

Appendix: source

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

                command,
                &work_dir,
                &exec_env,
                None,
                stdin_data,
                tty,
                ShellSpawnContext {
                    owner_agent,
                    owner_session_id,
                    origin_tool_call_id,
                    origin_turn_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 73e0f67d83)