Module shell 

Shell/process manager.

Runs commands from the workspace root with output streaming, timeouts, cancellation, and a process registry that tracks active commands.

Design

• Commands run from the workspace root by default. An optional cwd can be specified relative to the root; paths escaping the root are rejected.
• Output is captured from piped stdout/stderr. The blocking read happens on a worker thread; the TUI drains the result through the normal tool event channel so it never blocks.
• Timeouts kill the process and produce a Timeout status.
• Cancellation is cooperative: a shared CancelToken is checked by the worker thread between reads; when signalled the process is killed and the result is recorded as Cancelled.
• A ProcessRegistry tracks active commands, separating one-shot commands (waited on for completion) from long-lived background processes. A background child gets an independent cancellation handle, stays owned by the registry after the tool call returns, and is reaped on completion, explicit cancellation, application quit, or registry drop.

Safety

• fd --exec, rg --pre, sed -i, awk system() and arbitrary shell-string execution are not exposed by this module — the model provides an argv array, never a shell string.
• The command runs via std::process::Command argv; no /bin/sh -c.
• stdout/stderr bytes are capped at MAX_OUTPUT_BYTES; lines truncate at MAX_LINE_LEN.
• Paths are contained to the workspace root.

Structs

ActiveProcess

A process snapshot returned by the registry.

ProcessOutput

A bounded snapshot of output retained for an active process.

ProcessRegistry

Registry of active processes.

ProcessResult

Structured result of a process execution.

ShellArgs

Arguments for a shell command execution.

Enums

ProcessKind

Whether a command is a one-shot (waited for completion) or a long-lived background process (tracked separately by the registry).

ProcessStatus

Process lifecycle status recorded by the registry and in the transcript.

Constants

NAME

Functions

definition

Provider-visible definition for run_shell.

execute_request

Execute a registry request for run_shell.

execute_request_with_cancel

Execute a run_shell request with the cancellation token for its enclosing agent run.

execute_request_with_cancel_and_registry

Execute a run_shell request with cancellation and an optional application-owned background-process registry.

parse_arguments

Parse provider JSON arguments for run_shell.

redact_secrets

Redact known secret patterns from a line of command output.

run_command

Run a shell command with streaming output capture, timeout, and cancellation.

run_command_with_registry

Execute a shell command, handing background ownership to registry.