shell/
September 4, 2026 · View on GitHub
English | 中文
Summary
The shell group provides command execution to agents: run a foreground command and read its bounded output, or start a background process and poll it, on POSIX with Bash and on Windows with PowerShell. Exactly one executor implementation is mounted per composition; the sandboxing executors confine every command through the sandbox capability, and the model-facing bash and pwsh tools sit on top of whichever executor is mounted. Choose a Bash executor for POSIX, a PowerShell executor for Windows, and pick the sandboxing variant when commands need file-level confinement.
Table of Contents
Packages
| Package | Role | ctx key |
|---|---|---|
shell | Defines the executor contract: foreground runs, background handles, and request resolution | ctx.shell |
bash-local | Runs Bash commands as fresh bash -c processes on POSIX | registers ctx.shell |
bash-sandbox | Runs Bash commands confined through the sandbox capability, reporting denials as facts | registers ctx.shell |
pwsh-local | Runs PowerShell commands as fresh pwsh -Command processes on Windows | registers ctx.shell |
pwsh-sandbox | Runs PowerShell commands confined through the sandbox capability | registers ctx.shell |
shell-env | Supplies the managed DSH_* environment every shell command receives | ctx.shellEnv |
tool-bash | Exposes Bash execution and background jobs to the model as the bash tool | registers on ctx.tools |
tool-bash-persistent | Runs model shell calls in one owner-isolated persistent Bash session | registers on ctx.tools |
tool-pwsh | Exposes PowerShell execution to the model as the pwsh tool | registers on ctx.tools |
tool-pwsh-persistent | Runs model shell calls in one owner-isolated persistent PowerShell session | registers on ctx.tools |
A profile layer selects exactly one executor implementation (the win32 layer swaps the POSIX rows for the pwsh ones; mounting two fails loud on the duplicate service registration) and the model-facing tools it needs. A sandboxed composition also selects a ctx.sandbox provider and ctx.sandboxPolicy; the base bundle owns the shipped wiring.
Related documentation
- Bash executor subsystem — the shared request/spec vocabulary, results, background processes, and the service contract.
- Sandbox subsystem — the confinement capability the sandboxing executors consume.
Dev Note
None.