Function run_shell_command 

pub async fn run_shell_command(
    project_root: &Path,
    args: &Value,
    max_lines: usize,
    bg: &BgRegistry,
    sink: Option<(&dyn EngineSink, &str)>,
    trust: &TrustMode,
) -> Result<ShellOutput>

Execute a shell command with timeout, output capping, and optional streaming.

When sink is provided, each line of stdout/stderr is emitted as a ToolOutputLine event as it arrives — giving the TUI a live terminal feel. The full output is still collected and returned as the tool result.

When args["background"] is true, the process is spawned detached and this function returns immediately with the PID. The BgRegistry tracks the child so it is cleaned up (SIGTERM) when the session ends.