Merge pull request #25602 from dvdksn/fix/issue-354-clone-mode-docs

Clarify clone mode and Claude worktree isolation

Author: dvdksn

content/manuals/ai/sandboxes/agents/claude-code.md

@@ -74,9 +74,9 @@ for available options.
 ## Agents view
 
 Claude Code's [agents view](https://code.claude.com/docs/en/agent-view)
-dispatches tasks to subagents that work in parallel, each in its own
-Git worktree. Pair it with [clone mode](../workflows.md#clone-mode) for an
-isolated multi-agent workflow:
+starts background sessions that run tasks in parallel. Pair it with
+[clone mode](../workflows.md#clone-mode) to keep their changes inside the
+sandbox:
 
 ```console
 $ sbx run --clone claude -- agents
@@ -92,10 +92,14 @@ use Claude Code's auto mode or pass the flag explicitly:
 $ sbx run --clone claude -- --dangerously-skip-permissions agents
 ```
 
-The subagents' worktrees live inside the sandbox's private clone — none
-of them touches your host repository. Each subagent commits to its own
-branch, and you review the work from the host by fetching the
-`sandbox-<sandbox-name>` remote:
+Claude Code may use branches or worktrees to keep changes from its background
+sessions separate. This depends on the task, Claude Code configuration, and
+project instructions. The `--clone` flag doesn't control this behavior. Claude
+Code creates any branches and worktrees inside the sandbox, not in your host
+checkout.
+
+To review a branch created by a session, fetch the
+`sandbox-<sandbox-name>` remote from the host:
 
 ```console
 $ git fetch sandbox-<sandbox-name>

content/manuals/ai/sandboxes/usage.md

@@ -135,8 +135,10 @@ it when you create the sandbox:
 
 - Direct mode is the default. The agent has read-write access to your working
   tree, and changes appear on your host immediately.
-- [Clone mode](#clone-mode) uses `--clone`. The agent works in a private Git
-  clone inside the sandbox, and your host repository is mounted read-only.
+- [Clone mode](#clone-mode) uses `--clone`. The agent edits a separate Git clone
+  inside the sandbox. Its changes stay there until you fetch them or the agent
+  pushes them. Your host repository is also available at
+  `/run/sandbox/source`, but only with read access.
 
 For guidance on branch strategy, fetching work from a sandbox, and parallel
 agent workflows, see [Git workflows](workflows.md#git-workflows). For the

content/manuals/ai/sandboxes/workflows.md

@@ -59,16 +59,16 @@ turn-by-turn.
 
 ### Clone mode
 
-In clone mode, the sandbox gets a private Git clone. The agent manages its
-own branches and commits inside that clone; your host working tree is never
-touched. When the agent is done, you either fetch its branches to the host or
-ask the agent to push directly to your fork.
+In clone mode, `sbx` creates a separate Git clone inside the sandbox. The agent
+edits this clone instead of your host working tree. Its changes stay inside the
+sandbox until you fetch a branch or the agent pushes one to a remote. Your host
+repository is also available at `/run/sandbox/source`, but only with read
+access. The sandbox clone is not a Git worktree linked to your host checkout.
 
-Clone mode is designed for parallelism: a single clone-mode sandbox can hold
-many branches at once, and subagent orchestrators (such as Claude Code's
-[agents view](agents/claude-code.md#agents-view)) can dispatch independent
-tasks to separate agents, each working on its own branch or worktree inside
-the clone.
+A single clone-mode sandbox can hold multiple branches and worktrees for
+parallel tasks. The `--clone` flag creates the clone, but it doesn't separate
+one task from another. To keep parallel tasks isolated, instruct your agent tool
+to create a separate branch or worktree for each task.
 
 > [!NOTE]
 > `--clone` is a create-time flag and cannot be changed on an existing
@@ -135,10 +135,9 @@ It's only reachable while the sandbox is running:
    $ sbx run --clone claude
    ```
 
-2. Dispatch each independent task to a separate subagent. Claude Code handles
-   branch isolation for subagents automatically in agents view. For other
-   agents (such as Codex), add an instruction to `AGENTS.md` to get the same
-   behavior:
+2. Dispatch each independent task to a separate background session. Your agent
+   tool may use branches or worktrees to keep their changes separate. If it
+   doesn't, add a project instruction such as:
 
    ```markdown
    Always start each task on its own git branch before making changes.