Per-worktree access isolation for sub-agents and parallel sessions

Problem

When running multiple Claude Code sessions in parallel across git worktrees (e.g., one session per PR), there is no mechanism to prevent a session working in worktree A from reading or writing files in worktree B.

Current options and their limitations:

| Approach | Behavior |
|---|---|
| additionalDirectories with parent path (e.g., .worktrees/) | Grants access to all sibling worktrees |
| additionalDirectories with specific worktree path | Safe but requires manual config per worktree |
| isolation: "worktree" on Agent tool | Creates a new temporary worktree (isolated copy), but doesn't restrict access to other configured paths |
| EnterWorktree / ExitWorktree | Switches working directory but doesn't restrict access to other paths |
| Launch separate claude process per worktree | Effectively isolated, but no programmatic way to enforce it |

Desired Behavior

When a sub-agent or session is scoped to a specific worktree, it should only be able to access files within that worktree — not sibling worktrees or other directories outside its scope. This would enable safe, truly parallel workstreams without risk of cross-contamination.

Proposed Plan

1. Scoped additionalDirectories per agent/session — Allow isolation: "worktree" (or a new parameter) to restrict the sub-agent's file access to only the assigned worktree directory, overriding any broader additionalDirectories from the parent session.

1. Worktree-aware permission boundaries — When a session enters a worktree (via EnterWorktree or isolation), automatically restrict Read, Edit, Write, and Bash file operations to paths within that worktree (plus the shared .git metadata).

1. Explicit opt-in for cross-worktree access — If cross-worktree access is genuinely needed, require an explicit flag (e.g., isolation: "worktree-shared") rather than making it the default.

Use Case

Running parallel Claude Code sessions on different PRs/branches, each in its own worktree. Each session should be sandboxed so it cannot accidentally modify or read code from another in-progress PR.

🤖 Generated with Claude Code