Huanqi Cao
3d5ba3b83f
The inheritable `Deny Everyone FILE_DELETE_CHILD` also reached FILES, and 0x40 is a member of FILE_ALL_ACCESS: measured against a real runner, a Medium caller's CreateFileW(GENERIC_ALL) on every file, directory, and temp root inside a granted root returned ACCESS_DENIED. The deny now carries CONTAINER_INHERIT_ACE, so files keep working; a FullControl open of a DIRECTORY inside a granted root stays denied and is pinned as the residual cost of denying a right the full-access mask contains. Also from the review: - Leaks on fail-closed paths: the label ACL on both early SetEntriesInAclW exits, the read descriptor when the label build fails, and the parsed capability SID when either well-known-SID creation fails. - `revokeWrite` keeps the shared Low label while another capability grant remains on the directory, so two grants on one path stay independently revocable; `hasExactLabel` delegates to hasExactEntry. - The delete probe uses process.execPath, restrictTokenIntegrity guards a zero-length SID, and verify/abi-probe.cpp covers the new constants (compiled; static_asserts pass). - Consumers updated in the same change: sandbox-local source comments and README pair, pwsh-sandbox README pair, docs/subsystems/sandbox pair, and the 2026-07-06 sandbox note pair no longer cite the Everyone-write boundary as a current partial reason. - New Agent Note records the mandatory-integrity decision, the deny scoping, the standing label with its externality (other Low-integrity processes running as the user, surviving the session), and the rejected alternatives; the 2026-08-08 note cross-links it. - New runner pins: NUL stays writable under the Low token, the FullControl file/directory split, and the shared-label revoke. Per-file coverage back to 100%.
description, kind
| description | kind |
|---|---|
| The bash capability family for deployments and maintainers choosing and composing a shell executor, sandboxing, and the model-facing bash and pwsh tools. | package-group |
shell/ — bash capability family
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 loudly at load time 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 complete service contract.
- Sandbox subsystem — the confinement capability the sandboxing executors consume.
Dev Note
None.