Lesson 5 · 20 min
Two agents in the same checkout don't throw an error: one silently erases the other's work. A worktree gives each one its own copy and turns the silent loss into a visible conflict at merge time. A sandbox does the same with permissions: the reviewer reads, but doesn't write. In this lesson you prove both without spending quota.
Start the lesson
Goal: give each agent that writes its own worktree and each reviewer a read-only sandbox, and prove the difference.
Click each one. The rehearsal right below proves the first two.
A worktree isolates files, not processes: two worktrees still share ports, the local database, and quota.
A throwaway repository and two fake agents that read, think (A 2 s, B 1 s), and write the whole file.
E=${TMPDIR:-/tmp}/ensaio-multi/wt; rm -rf $E && mkdir -p $E && cd $E
git init -q repo && cd repo && git config user.name ensaio && git config user.email ensaio@local
printf 'versao = 1\nnome = treino\ncor = azul\n' > config.txt && git add -A && git commit -qm base
# an "agent" reads the file, thinks for $4 s and writes the whole file (like the Write tool); A thinks longer than B
agente() { c=$(cat "$1/config.txt"); sleep "$4"; printf '%s\n' "$c" | sed "$2" > "$1/config.txt"; echo "$3 gravou"; }
echo "## A) dois agentes no MESMO checkout"
agente . 's/azul/verde/' A 2 & agente . 's/versao = 1/versao = 2/' B 1 & wait
cat config.txt
git checkout -q config.txt
echo "## B) um worktree para cada agente"
git worktree add -q ../wt-a -b agente-a && git worktree add -q ../wt-b -b agente-b
agente ../wt-a 's/azul/verde/' A 2 & agente ../wt-b 's/versao = 1/versao = 2/' B 1 & wait
git -C ../wt-a commit -qam "A: cor" && git -C ../wt-b commit -qam "B: versão"
git merge -q agente-a && git merge -q --no-edit agente-b && cat config.txt
git worktree list | wc -l## A) dois agentes no MESMO checkout B gravou A gravou versao = 1 nome = treino cor = verde ## B) um worktree para cada agente B gravou A gravou Auto-merging config.txt versao = 2 nome = treino cor = verde 3
In A, both said "gravou", but only one of the two changes survived: A read the file before B wrote and, since it thinks longer, wrote over it, and version 2 disappeared. In B, both changes made it in.
The different waits (A 2 s, B 1 s) fix the order so the rehearsal always gives the same result (18 of 18 rounds identical on 10/19/2026). With equal waits, whoever writes last changes from round to round, but you never end up with both changes.
Two worktrees changing the SAME line (cor roxo × cor preto), captured in the same repository:
Auto-merging config.txt CONFLICT (content): Merge conflict in config.txt Automatic merge failed; fix conflicts and then commit the result. saída: 1
In a single checkout, this would be a silent loss. Here git stops and shows it. The one who resolves it is the orchestrator (or you), not one of the two agents.
Claude Code 2.1.303 and Codex CLI 0.163.0, per the docs read on 10/19/2026.
claude --worktree [name] creates the worktree in .claude/worktrees/[name] and opens the session there. It needs at least one commit and, in interactive mode, the folder marked as trusted (run claude once in it).
Files ignored by git, like .env, don't go to the worktree; list them in a .worktreeinclude at the root to copy them.
Hooks using ${CLAUDE_PROJECT_DIR} keep running in the main checkout; it's the hook's cwd field that follows the worktree.
In the frontmatter, isolation: worktree gives the subagent a temporary worktree, which disappears on its own if it changes nothing.
Heads up: the branch starts from the default branch, not from your session's HEAD. Anything you haven't committed isn't there.
A background session (claude --bg) enters a worktree before editing. Agent teams don't isolate: split the files by owner.
A periodic cleanup removes worktrees created by Claude that are older than cleanupPeriodDays and hold no work.
codex exec --worktree "[pedido]" runs in a managed worktree (it doesn't combine with resume or --ephemeral). In the TUI, /worktree.
Sandbox: -s read-only for those who only review, -s workspace-write for those who execute. The docs ask you to avoid --dangerously-bypass-approvals-and-sandbox outside a dedicated VM.
codex sandbox runs any command under the same rules Codex uses for its own. It doesn't call a model.
E=${TMPDIR:-/tmp}/ensaio-multi/sbx; rm -rf $E && mkdir -p $E && cd $E
codex sandbox -c sandbox_mode=read-only -- bash -c 'echo x > a.txt 2>/dev/null && echo "read-only: gravou" || echo "read-only: bloqueado na pasta"'
codex sandbox -c sandbox_mode=workspace-write -- bash -c 'echo x > b.txt && echo "workspace-write: gravou na pasta"; echo x > ~/fora-sbx.txt 2>/dev/null && echo "gravou fora" || echo "workspace-write: bloqueado fora da pasta"'
ls; ls ~/fora-sbx.txt 2>&1 | tail -1# terminal 1: opens the session already inside the worktree (no need to ask for anything) cd ~/treino-multi && claude --worktree treino-a # terminal 2, with the session open: cd ~/treino-multi && git worktree list | grep -c ".claude/worktrees/treino-a" git branch --list worktree-treino-a # terminal 1: /exit (worktree with no changes: choose remove, if it asks). Then: git worktree list | wc -l
bash: line 1: a.txt: Read-only file system read-only: bloqueado na pasta workspace-write: gravou na pasta bash: line 1: ~/fora-sbx.txt: Read-only file system workspace-write: bloqueado fora da pasta b.txt ls: cannot access '~/fora-sbx.txt': No such file or directory
Edited on purpose: your home folder path shows up as ~. The read-only run didn't write even inside the folder; workspace-write wrote b.txt and was blocked outside.
A worktree starts from a commit. In a freshly created git init, claude --worktree exits before calling the model (captured with Claude Code 2.1.303):
Error creating worktree: Failed to resolve base branch "HEAD": git rev-parse returned no commit for HEAD (for example in a new repository, or on a branch without a commit yet), so Claude Code has nothing to base a worktree on. (…) saída: 1
Make a commit and run it again.
Two rehearsals and one real worktree.
Run the two-agent rehearsal.
Done when: in A, only one of the two changes survives: cat config.txt shows versao = 1 and cor = verde (B's change disappeared); in B, it shows versao = 2 and cor = verde; the last line is 3.
Run the codex sandbox rehearsal.
Done when: you see read-only: bloqueado na pasta, workspace-write: gravou na pasta and workspace-write: bloqueado fora da pasta, and ls shows only b.txt.
In the practice project, open claude --worktree treino-a in one terminal and check from another. When you exit, a clean worktree is removed (in a named session, Claude asks first).
Done when: with the session open, git worktree list | grep -c ".claude/worktrees/treino-a" → 1 and the branch worktree-treino-a exists; after you exit, git worktree list | wc -l → 1 (if it stayed, git worktree remove .claude/worktrees/treino-a).
Question 1 of 4
Two agents edited the same file in the same checkout and both said "gravou". What could have happened?skill
Question 2 of 4
Why is a merge conflict between two worktrees a good sign?skill
Question 3 of 4
A subagent with isolation: worktree can't find the change you made and didn't commit. Why?
Question 4 of 4
Which Codex sandbox should you give a reviewer that only runs tests and reads?
Choose one option. The explanation appears after your attempt.