"""Safe subprocess wrappers for tool execution."""

from __future__ import annotations

import subprocess
from collections.abc import Sequence


def run_command(argv: Sequence[str]) -> subprocess.CompletedProcess[str]:
    """Run a subprocess safely (no shell) and return completed process."""
    return subprocess.run(  # noqa: S603
        list(argv),
        check=True,
        capture_output=True,
        text=True,
        shell=False,
    )


def run_command_allow_fail(argv: Sequence[str]) -> subprocess.CompletedProcess[str]:
    """Run a subprocess safely without raising on non-zero exit."""
    return subprocess.run(  # noqa: S603
        list(argv),
        check=False,
        capture_output=True,
        text=True,
        shell=False,
    )


def spawn_background(argv: Sequence[str]) -> subprocess.Popen[bytes]:
    """Start a long-running daemon process (fire-and-forget, no shell)."""
    return subprocess.Popen(  # noqa: S603
        list(argv),
        stdout=subprocess.DEVNULL,
        stderr=subprocess.DEVNULL,
        shell=False,
    )