{"record":{"id":"fda1d26636d97aa0","repo":"Hmbown/CodeWhale","slug":"tty-mode-requires-background-execution-set-backgr","errorCode":null,"errorMessage":"TTY mode requires background execution (set background: true).","messagePattern":"TTY mode requires background execution \\(set background: true\\)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/shell.rs","lineNumber":2206,"sourceCode":"                command,\n                &work_dir,\n                &exec_env,\n                None,\n                stdin_data,\n                tty,\n                ShellSpawnContext {\n                    owner_agent,\n                    owner_session_id,\n                    origin_tool_call_id,\n                    origin_turn_id,\n                    work_lifecycle,\n                },\n                persist_pending,\n                bounded_output,\n            )\n        } else {\n            if tty {\n                return Err(anyhow!(\n                    \"TTY mode requires background execution (set background: true).\"\n                ));\n            }\n            Self::execute_sync_sandboxed(command, &work_dir, timeout_ms, stdin_data, &exec_env)\n        }\n    }\n\n    /// Interactive variant that accepts extra env vars (#456 shell_env hook).\n    pub fn execute_interactive_with_policy_env(\n        &mut self,\n        command: &str,\n        working_dir: Option<&str>,\n        timeout_ms: u64,\n        policy_override: Option<ExecutionSandboxPolicy>,\n        extra_env: HashMap<String, String>,\n    ) -> Result<ShellResult> {\n        crate::shell_dispatcher::ShellDispatcher::log_exec(command);\n","sourceCodeStart":2188,"sourceCodeEnd":2224,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tools/shell.rs#L2188-L2224","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n{ \"command\": \"python\", \"tty\": true }\n// after\n{ \"command\": \"python\", \"tty\": true, \"background\": true }","handlingStrategy":"validation","validationCode":"// before invoking the tool\nif request.tty && !request.background {\n    return Err(\"tty requires background: set background: true or drop tty\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["shell","tty","pty","background-execution"],"backgroundTag":"unsupported-operation","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}