[feature] Path-rewrite enforcement when isolation: "worktree" is set on Agent tool

Worktree-isolation contract hardening proposal

Date: 2026-05-28
Status: PROPOSAL

Problem

Observed 6+ worktree-isolation contract failures in a single session, despite the recent fix that introduced isolation: worktree frontmatter on the Agent tool. The contract is incomplete.

Failure modes (3 categories)

Category 1: Absolute paths reach across the worktree boundary

Write/Edit tool calls with absolute paths under the parent checkout (e.g. <repo-root>/<file>) succeed regardless of which worktree the agent runs in. No path validation against the worktree root.

Observed tonight: five separate sub-agent dispatches across the same session. All recovered; some via manual user intervention.

Category 2: Bash cd outside worktree silently accepted

Agents that read the runtime banner's "current working directory" and prepend cd <repo-root> && ... re-anchor themselves in the shared main checkout for the rest of the session.

Category 3: Sub-agent git checkout on shared main

Agents dispatched without explicit isolation: worktree (e.g. nested sub-agent classes whose frontmatter doesn't declare isolation) can git checkout -b <branch> on the shared parent checkout. The parent's branch state changes silently.

Proposed 4-prong mitigation

Prong A (highest leverage): Path-rewrite enforcement when isolation: worktree

When an agent's frontmatter declares isolation, the runtime wraps Write/Edit calls with a path validator:

1. Resolve requested absolute path to canonical form
2. Verify it falls under the agent's worktree root
3. Reject calls outside the worktree root with a structured error pointing to the correct path

This is the highest-value mitigation -- directly closes Category 1.

Prong B: Bash cd boundary enforcement

When isolation is active, Bash commands containing cd <path> where path is outside the worktree root should be rejected OR warned on first occurrence.

Implementation: intercept cd in agent shell wrapper, validate target. Lighter alternative: on each Bash call return, validate final pwd is still inside the worktree; warn if not.

Prong C: Default isolation for nested sub-agent dispatches

When an agent with isolation: worktree dispatches a sub-agent (without explicit isolation), the runtime should INHERIT the parent's isolation posture by default. Today, sub-agents run in shared main unless the parent explicitly opts in.

Prong D: Explicit branch-switching denial on shared main

When the runtime detects an isolated agent attempting git checkout / git switch to a non-default branch on a path that appears to be the parent's shared main, reject the call.

Implementation: parse git checkout / git switch invocations, resolve cwd, verify it's not the parent's shared checkout when isolation is declared.

Operational workarounds (until platform fix lands)

1. First Bash call in every isolated worker MUST be pwd, with pre-flight system instruction to STOP if pwd shows shared main.
2. Briefs MUST list explicit absolute paths under the worktree root for all Write/Edit operations.
3. Briefs MUST forbid cd to anywhere outside worktree root.
4. For nested sub-agent dispatches, explicitly pass isolation: worktree even if the type definition doesn't have it in frontmatter.
5. Post-dispatch verification: after a worker returns, git status --short in shared main. Uncommitted edits not made by you = worker leaked.

Action

Anthropic should evaluate + rank prongs A-D by build cost vs leverage. The path-rewrite enforcement (Prong A) is the most direct close on the largest failure class.