- Status: Accepted
- Date: 2026-10-19
- Decision register: D27, D32, D47, D48
- Supersedes ADR-0037 decision 4 (
bashstays out of the kernel) and the no-shell statements of ADR-0029 - Related: ADR-0023, ADR-0029, ADR-0037
The kernel tool set was read, ls, grep, find, write, edit. Models know a shell and git
intimately; the phases need them anyway — build a generated project, run a test suite, inspect
history and diffs — and a "tool not available" gap pushes that work outside the product. Two facts
shaped the design:
- Script steps already run arbitrary code. A script step runs model-written code as a child process in the job's OS account, with a cleared environment and no credentials (ADR-0029). A shell tool is the same boundary made interactive; it adds no new crossing.
- A shell is only as confining as the OS account. Path guards on file tools are defense in depth, not the isolation boundary (ADR-0029 D47/D48). What remains to design is not "whether a shell can be confined" (it cannot, beyond the account) but that every process the kernel starts obeys the same process rules and that git stays inside the workspace by itself.
-
shellreplaces pi's bash shape (command,timeoutin seconds) with kernel-owned execution: every call is onebash -cprocess through the launcher'srunProcess— the job's cleared environment (HOME,TEMP,TMPDIRat the job's scratch), a wall-clock timeout (default 60 s, max 600 s), the capture cap and kill-tree on timeout or abort. No state (cwd, variables) survives a call. pi's bash tool itself is never registered: it keeps a persistent shell in the host's environment and writes spill files outsideout. -
gittakes an explicit argument list — no shell, no alias expansion (the first argument must be a real git subcommand, because git expands a configuredalias.x '!command'for any other name) and no option that redirects the repository, loads configuration or starts a helper (-c,-C,--git-dir,--work-tree,--config,--upload-pack/-u,--exec,--ext-diff,--textconv,--output,submodule foreach). Read-only subcommands (status,log,diff,show,blame, ...) run anywhere in the job workspace; every other subcommand runs only where the job may write (out/, the scratch) — a mutating command must not touch a checkout the job only reads, so the agent clones or inits the repository there first. The environment is the job's cleared one plus git hardening:GIT_CONFIG_NOSYSTEM, no prompts, no pager,GIT_OPTIONAL_LOCKS=0, neutral commit identity, hooks at an empty directory,core.fsmonitor/diff.external/core.pager/core.askpass/credential.helperoverridden at command-line scope, andGIT_ALLOW_PROTOCOL=file:git:http:https:sshsoext::/fd::transports cannot run a command. -
lskeeps pi's flat listing unchanged and gainstreeanddepthparameters (depthimpliestree; default depth 3, max 8, capped listing): pi's definition cannot take extra parameters, so the kernel wraps it and renders the tree itself under the same guards. -
The kernel tool set is
read,ls,grep,find,write,edit,shell,git(tool-names.ts; agent allowlists name them per agent).
- Runtime jobs can build, test and inspect history; the built-in runtime agents allowlist the full set. Prompt text that promised "no shell" is rewritten to describe the boundary instead.
- The boundary to defend is the job's OS account (a read-only worktree at the OS level where
available, no credentials in the environment, capped output, redacted audit events) — unchanged
from ADR-0029, but now also what
shellruns behind.git's own guards are defense in depth for agents that are grantedgitbut notshell. - Residual risk accepted: a repository under review can still name a textconv driver for the
subcommands where
--no-textconvdoes not apply; that runs inside the same account with no secrets in the environment, equivalent toshell, which these agents also hold. - ADR-0037 decision 4 and ADR-0029's "runtime agent jobs have no shell" are superseded by this
decision. The write-confinement consequence of ADR-0037 (file tools confined to
out) stands.
- Keep
bashout of the kernel. Rejected: the phases need it, and script steps already run arbitrary code in the same account; the tool version is auditable per call, the script version hides it inside a step. - pi's
createBashToolDefinitionwith custom operations. Rejected: its session keeps a persistent shell and its output accumulator writes spill files outsideout; wrapping it costs the same work as owning the tool and keeps pi-specific behavior in the boundary path. gitas a read-only tool only. Rejected: provenance and same-stack uplift work need commits and checkouts; writes are confined to a clone underout//scratch instead.- A separate
treetool. Rejected:lsis the tool models reach for when looking around; tree is a shape of the same answer, so it is a parameter.
- Diff drivers (2026-11-01).
diff.externalandGIT_EXTERNAL_DIFFare no longer set to an empty value: git takes a set but empty value as an external diff command named "" and every patch failed.diff,logandshowrun with--no-ext-diff --no-textconvinstead.diff --no-index, and a diff whose path arguments leave the workspace (git compares them as plain files then), are refused. - Escapes closed (2026-11-01). The option checks also catch a command-starting short option bundled or with its
value attached (
clone -qu <cmd>,-u<cmd>,rebase -x<cmd>,grep -O<cmd>), and git refuses abbreviated long options (GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS, so--upload=<cmd>cannot stand for--upload-pack).configonly reads (--get,--get-all,--get-regexp,--list; no--file): configuration names commands (filter drivers,core.sshCommand,gpg.program).init,worktreeand the target ofclonemust be in the writable area, the source of a local clone in the workspace;--reference,--separate-git-dir,--templateand--open-files-in-pagerare refused, andwrite/editdo not reach inside a.gitfolder. - Transports (2026-11-01). A local repository (a path or a
file:URL) thatfetch,pull,remoteorsubmodulereach must be inside the job workspace, and one thatpushreaches must be in the writable area: a remote named by the command, or every configured remote when none is named, is read from the repository's configuration first, and forsubmodulethe URLs of.gitmodulestoo. Network remotes are unchanged.