{"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":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/shell.rs","lineNumber":2044,"sourceCode":"            let bounded_output = timeout_bounds_ms == (1, BASH_MAX_TIMEOUT_MS);\n            self.spawn_background_sandboxed(\n                command,\n                &work_dir,\n                &exec_env,\n                None,\n                stdin_data,\n                tty,\n                ShellSpawnContext {\n                    owner_agent,\n                    owner_session_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":2026,"sourceCodeEnd":2062,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/0c42157ee52f9d55af2b506d71b46249910f77d3/crates/tui/src/tools/shell.rs#L2026-L2062","documentation":"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.","triggerScenarios":"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.","commonSituations":"An agent wants interactive output but forgot the background flag; a caller copies tty from another tool's schema without enabling background.","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."],"exampleFix":"// before\nexec_shell(\"python3\", { tty: true })\n\n// after\nexec_shell(\"python3\", { tty: true, background: true })","handlingStrategy":"validation","validationCode":"if request.tty && !request.background {\n    return Err(\"tty requires background: true\");\n}\nexec_shell(request)?;","typeGuard":"function isValidShellRequest(req: { tty?: boolean; background?: boolean }): boolean {\n  return !req.tty || req.background === true;\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["shell","tty","option-combination","validation"],"backgroundTag":"invalid-option-combination","analyzedSha":"0c42157ee52f9d55af2b506d71b46249910f77d3","analyzedAt":"2026-08-20T21:50:45.477Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}