Claude Code Background Agents: Bash Skips the Worktree Guard

I started nine background sessions with claude --bg on this Mac mini and had them try eight writes against the main checkout. Two were Write tool calls from one session, and the worktree guard rejected both: "This background session hasn't isolated its changes yet. Call EnterWorktree first." The other six wrote through Bash, and all six writes landed in the main checkout. That includes three sessions that had already moved into their own worktree and then wrote back to the parent repo by absolute path.

That is the main result here. The rest of this post covers how background agents are hosted on macOS, what one costs in memory, what survives a dead terminal and a mid-run auto-update, and why claude rm refused to delete a worktree that had nothing in it but a plugin's state folder.

What claude --bg starts

Background sessions came in with agent view, which Claude Code 2.1.139 added as a research preview on 11 May 2026. The agent view documentation describes a "supervisor" that keeps sessions running after you close the terminal. On my machine the supervisor is a process called claude daemon run --origin transient. It was reparented to PID 1, had no controlling terminal and led its own process group. It is not a LaunchAgent: claude daemon --help in 2.1.303 says "Service install is disabled in this version — the daemon runs on demand and exits when the last client disconnects."

Under the daemon, every session gets a claude bg-pty-host process that owns a pseudo-terminal, and the session itself runs inside it. The daemon also keeps one pre-warmed spare session. When I ran claude --bg, the log showed bg claimed-spare 87a88408 and then bg spare spawned host, so the next launch would also find a warm process. The command returned in 0.89 seconds. In a folder I hadn't trusted yet, it exited with code 1 after 0.66 seconds and printed "Workspace not trusted. Run `claude` in … once and accept the trust prompt, then retry." Version 2.1.281 changed it to refuse untrusted folders this way when it can't show the prompt. I accepted the trust dialog once in tmux, where the default answer is "No, exit", as I noted in my post on Claude Code in tmux.

The cost is memory. With four background sessions open, I counted 11 Claude processes using 2,355 MB of resident memory. The daemon took 161 MB, each pty host about 81 MB, the idle spare 124 MB, and the four sessions 366 to 517 MB each. The nine interactive sessions on the same machine were using 294 to 412 MB each. So the fixed overhead is about 367 MB for the daemon and the warm spare, and each session adds about 81 MB for its pty host on top of its own memory.

$ claude --bg --model haiku "Run the shell command: sleep 45 && date > done.txt"
Starting background service…
backgrounded · 87a88408
  claude agents             list sessions
  claude attach 87a88408    open in this terminal
  claude logs 87a88408      show recent output
  claude stop 87a88408      stop this session

The worktree guard covers edit tools, not Bash

Each background session gets a system prompt section titled "Background Session". It tells the model to call EnterWorktree before making code changes and says "This is enforced: file edits in the shared checkout are rejected until you isolate." That holds for the Write tool. I told a session in bypass permissions mode not to isolate and to write notes.txt with Write. Both attempts were rejected, and the error message named the opt-out, "worktree": {"bgIsolation": "none"}. Bash was a different story.

Three sessions never isolated. One wrote a new file with date > done.txt, and two edited the tracked README.md with sed -i. git status in the main checkout then showed M README.md. Three more sessions called EnterWorktree first, got a worktree under .claude/worktrees/, and then wrote to the parent checkout by absolute path. All three writes went through, in both auto mode and bypass mode.

This matches the documentation more closely than the system prompt suggests. The agent view page says the guard blocks Edit, Write and NotebookEdit, and it lists "the write is outside the working directory" as a case where isolation is skipped. It doesn't mention Bash. The changelog has several fixes for "worktree-isolated sessions" refusing Bash commands, so a Bash check exists somewhere, but it didn't fire in any of these six runs. The guard is useful for keeping parallel sessions from colliding through the edit tools. It isn't a filesystem boundary. If you need one, the sandbox or a container is the layer that enforces paths, and I made the same point about auto mode's classifier.

Dead terminals, auto-updates and cleanup

The docs say sessions keep running after the terminal closes. I couldn't drop a real SSH connection, because this machine doesn't have key login to itself. Instead I launched claude --bg inside a tmux session and killed that session at 16:38:42. The background job finished its sleep 40 and wrote its file at 16:39:30. A reboot is a different case. The docs say a restart stops background sessions, and nothing here is registered with launchd to bring them back. On this Mac, FileVault means someone has to log in at the machine after a reboot anyway.

I also got a test I hadn't planned. At 16:39:42 another Claude Code process on the machine auto-updated the binary from 2.1.303 to 2.1.308 while my session was running. The daemon log recorded binary at ~/.local/bin/claude changed, then shutting down (cause=upgrade, uptime=60s, leases=0, live_workers=1). A new 2.1.308 daemon started 1.3 seconds later and logged bg adopt: adopted=1 respawned=0 dead=0. The session kept running on the old binary, under a pty host that was now an orphan of PID 1, and it finished normally. To move it to the new version you run claude respawn. I covered the update side of this in Claude Code not updating: headless claude -p never checks, but any interactive session can swap the symlink under you.

Cleanup had one surprise. claude stop keeps the worktree. claude rm on a session that had isolated but never written a file refused with exit code 1: "The worktree has uncommitted changes. Deleting it would lose them." The only change was an untracked .omc/ folder written by a plugin's hooks. Once I deleted it, rm removed both the worktree and its worktree-* branch. If your hooks write state into the working directory, expect rm to refuse until you clean it up. The message also offers deleting the session from agent view (Ctrl+X twice), which discards the files. This is the same problem as the 92 ignored paths that stay behind when a worktree is created, seen from the other end.

After the last rm the daemon logged "idle 5s with no clients — exiting", and every background process was gone within 16 seconds. It also refreshes the OAuth token itself (auth: proactive refresh succeeded). That matters on a machine like this one, where an expired OAuth session once blanked 17 hours of runs.

The changelog: 367 entries, 72% fixes

To check how settled this is, I pulled the 9,372-line CHANGELOG.md and matched entries that mention background sessions, --bg, agent view, claude agents, attach, respawn, the daemon or bgIsolation. From 2.1.139 through 2.1.304 there are 367 matching entries: 266 start with "Fixed" and 20 with "Added". They appear in 83 of the 148 releases since agent view shipped. The monthly counts were 90 in May, 64 in June, 83 in July, 35 in August, 42 in September and 53 in October so far. Thirty entries concern worktrees or isolation, including 2.1.154's "Fixed subagents in background sessions bypassing the worktree-isolation guard". Fixes are still coming every week, which fits the research preview label.

On Hacker News, the launch thread for the agent view announcement opened with "Folks will probably say, 'I just use cmux, or tmux, or tabs, or warp'". A comment in August describes checking long-running sessions over a slow SSH link while on vacation and letting claude agents background them instead of tmux. In a thread about Codex installing a background daemon, another user lists the claude bg processes still running with no Claude Code in the foreground.

Where it fits next to tmux

My long jobs on this machine run in tmux, and the scheduled slots run as claude -p from launchd, as in claude -p background tasks. --bg gives me things tmux doesn't. claude agents --json reports state (working, blocked, done) and waitingFor: "permission prompt" without a TTY, and every job keeps a state.json under ~/.claude/jobs/<id>/. Edit tools also go to a worktree by default. Some things are worse. claude logs returned 18,254 bytes of raw terminal output, and after stripping escape codes 498 lines were left, mostly spinner frames. claude attach without a TTY exited with code 0 after printing "Attaching…", which a script would read as success. And the worktree guard doesn't apply to Bash.

For unattended work that edits a repo, I'd treat the worktree as the place I want the session to work, not a guarantee. Check git status in the main checkout after a background job, and use the sandbox if a stray write would actually hurt you.

FAQ

How do I run Claude Code agents in the background?

Run claude --bg "your task" in a folder you've already trusted. It prints a short ID and returns right away. claude agents lists sessions, claude attach <id> opens one, claude logs <id> prints recent output, and claude stop and claude rm end and delete it. In an untrusted folder it exits with code 1 and asks you to run claude there once first.

Do Claude Code background agents edit my working copy?

The Edit, Write and NotebookEdit tools are blocked in the shared checkout until the session calls EnterWorktree, unless you set worktree.bgIsolation to "none". Bash commands are not blocked. In my tests on 2.1.303 and 2.1.308, six of six Bash writes reached the main checkout, three of them after the session had already moved into a worktree.

How do I stop a Claude Code background agent?

claude stop <id> ends the process and keeps the conversation and worktree. claude rm <id> deletes the session and its worktree, but it refuses when the worktree has uncommitted or untracked files, including files written by hooks. When the last session is removed, the supervisor exits after about 5 seconds idle.

How this was measured: on 22 October 2026, between 16:33 and 16:43 KST, on a Mac mini (M4, macOS 26.4.1) running Claude Code 2.1.303 and, after an auto-update at 16:39, 2.1.308. I used Haiku 5.5 in a throwaway one-commit git repo, with auto mode as the default, the Bash sandbox off and a plugin's hooks installed. Each of the eight write tests ran once, and I read the results from session transcripts, ~/.claude/daemon.log, claude agents --json and git status. I did not test a real SSH drop, sleep, the one-hour idle stop the docs describe, a reboot, Linux, other models, or the sandbox turned on. The changelog count is a keyword match over CHANGELOG.md fetched the same day, with release dates from the npm registry. Hacker News threads were read through the Algolia API. Raw outputs are kept in this site's research notes.