Write confinement
Write confinement is an operating-system fence under execute_command and the write_file,
edit_file, create_pdf and the rm, mv, cp and mkdir tools. With it on, a command can write only inside:
- the session’s working directory;
- when the working directory is inside a git repository, the repository’s top-level directory, so
git addandgit commitwork from a subdirectory. For a linked worktree or a submodule, its git directory and the shared main.gitare included too. A repository whose top level is your home directory or above it is ignored; - Jazz’s scratch directory (
~/.jazz/workspace); - temp directories (
$TMPDIR,/tmp,/var/tmp); - developer tool caches:
~/.cache,~/.bun,~/.npm,~/.pnpm-store,~/.yarn,~/.cargo/registry,~/.cargo/git, and~/Library/Cacheson macOS.
Everything else on disk stays readable and unwritable. Reads and the network are not
confined. The rest of your home directory, including ~/.ssh, shell startup files and
~/.jazz itself, cannot be written by a confined command. Confinement covers file writes only: it
does not stop a command from sending data over the network.
When it is on
| Surface | Default |
|---|---|
| Interactive chat with a person at the terminal | off |
jazz run in a terminal where its questions reach you |
off |
jazz run piped, in CI or cron; bridge bots (Telegram, Discord, iMessage, WhatsApp) |
on |
| Peers, webhooks, goals, loops, daemon work | on |
The rule is whether a person is at the terminal who can type continue: when nobody is, the fence
is on. Set shell.confinement in your global config to choose the mode yourself:
{ "shell": { "confinement": "on" } }
off is the only value that lets commands run unconfined. The project layer is applied after the
global one: a project’s .jazz/config.json can turn confinement on even when your global config
says off, but a project off is ignored (Jazz says so), so a project can only add the fence.
What Jazz needs from the machine
| Platform | Backend | Needs |
|---|---|---|
| macOS | /usr/bin/sandbox-exec |
Nothing to install. |
| Linux | bwrap (bubblewrap) |
apt install bubblewrap and user namespaces. |
| Windows | none | Run Jazz in WSL, or set shell.confinement to off. |
Jazz runs a real command under the backend once per process and reports what held:
full: a write outside the roots was refused and a write inside succeeded.partial: confinement holds with a named gap. On Linux hosts whose kernel refuses a private/dev, device nodes under/devstay writable.none: no backend, or one that did not refuse the outside write.
When confinement is on and the level is none, commands are refused, not run unconfined. The
message says why and what to install, or that shell.confinement: "off" is the way to opt out.
The level appears in /info.
When a command is denied
A write outside the roots fails with Operation not permitted (macOS) or Read-only file system
(Linux). Jazz recognizes it only when the command exited non-zero, a stderr line ends in one of
those texts, and the path on that line lies outside the roots. The result then carries
confinement.deniedPath and tells the model it may retry that exact command once with escalate
set to a reason.
The retry goes through the approval prompt, which shows the denied path and the reason and is asked even when a policy would auto-approve the command. Approving runs that one call unconfined. Nobody is asked on a surface with no one to answer, so the model is told to write inside the roots instead. A command can be escalated once; a command that was never denied cannot be escalated.
The file tools do not escalate: a path outside the roots is refused with the roots named.
Limits
- The fence covers writes, not reads or the network.
- The file tools (
write_file,edit_file,create_pdf,rm,mv,cp,mkdir) check their paths in-process. Each resolves the target’s real path, mutates that path rather than the original string, and re-checks the directory it relies on (its identity and that it is not a symlink) as the last step before the mutating call, refusing if it changed. Node and Bun have noopenator no-follow primitives, so a window of a few microseconds remains between that check and the syscall. Closing it needs a process that can swap a directory in that gap while a tool call runs: the realistic one is a confined shell command racing a file-tool call in the same batch. The confined shell itself cannot escape, because the operating system confines it. manage_scratchpadwrites only under Jazz’s own scratch directory, which is a writable root, so it needs no separate check.- Commands the daemon runs from a
wait_forjob and the operator’s!escape run unconfined. sandbox-execis deprecated by Apple but ships on every supported macOS.- Linux support needs
bwrapand unprivileged user namespaces; hosts without them reportnone. - Seatbelt and bwrap enforce at the kernel, so a command cannot lift the fence from inside; a process that is not a child of the command (a daemon you started earlier) is not fenced.