Function spawn_background_bash

src/tool_system/tools/bash/background.py:44–176

Spawn *command* in the background and register it on *context*. Returns a dict that mirrors the shape consumed by ``_bash_map_result_to_api``: it includes the background task id plus a human-readable message instructing the model how to poll the output.

(
    *,
    command: str,
    cwd: Path,
    description: str | None,
    context: ToolContext,
)

def spawn_background_bash(
    *,
    command: str,
    cwd: Path,
    description: str | None,
    context: ToolContext,
) -> dict[str, Any]:
    """Spawn *command* in the background and register it on *context*.

    Returns a dict that mirrors the shape consumed by
    ``_bash_map_result_to_api``: it includes the background task id plus a
    human-readable message instructing the model how to poll the output.
    """
    # Chapter-10 / WI-1.4: prefixed task id (``b<8 base36 chars>``) instead
    # of the legacy ``uuid4().hex[:8]``. Mirrors TS Task.ts:79-105 — the
    # ``b`` prefix is what TaskStop / TaskOutput dispatch on.
    task_id = generate_task_id("local_bash")
    output_path = _bg_output_dir() / f"{task_id}.log"
    output_path.touch(exist_ok=True)

    output_handle = open(output_path, "wb", buffering=0)

    # Same wrapper the foreground path uses, so a trailing ``cd`` still writes
    # the final PWD for inspection. Exit code is appended to the log after the
    # process exits so ``TaskOutput`` can report it even if Popen.wait() races
    # with the reader.
    wrapped = (
        f"{{ {command}\n}}; __rc=$?; "
        f"echo \"__CLAWCODEX_EXIT__=$__rc\" >&2; "
        f"exit $__rc"
    )

    # ``stdin=DEVNULL`` mirrors the foreground bash path: prevents background
    # commands that read fd 0 from blocking on a TTY inherited from clawcodex's
    # REPL (see bash_tool.py:_run_bash_with_abort for the same reasoning).
    proc = subprocess.Popen(
        ["bash", "-lc", wrapped],
        cwd=str(cwd),
        stdin=subprocess.DEVNULL,
        stdout=output_handle,
        stderr=subprocess.STDOUT,
        start_new_session=True,
    )

    started_at = time.time()
    state = LocalShellTaskState(
        id=task_id,
        type="local_bash",
        status="running",
        description=description or command,
        start_time=started_at,
        # ``output_file`` (chapter-10 base field) carries the same string
        # as ``output_path`` (bash-specific name kept for legacy readers).
        output_file=str(output_path),
        command=command,
        cwd=str(cwd),
        pid=proc.pid,
        output_path=str(output_path),