Files

T

HAL9000 e7e7eedc4f docs: add git worktree sandbox guide, extend sandbox/plan-apply/context-tiers refs

- docs/modules/git-worktree-sandbox.md: new module guide for GitWorktreeSandbox
  (PR #5998) covering execute/apply phases, non-git fallback, conflict handling,
  and context hydration integration
- docs/reference/sandbox.md: add Strategy Selection section and Git Worktree
  Sandbox section documenting execute/apply phases and non-git fallback
- docs/reference/plan_apply.md: add Git Worktree Merge-Based Apply section with
  CLI output panels and fallback behaviour; update intro to reference PR #5998
- docs/reference/context_tiers.md: add Context Tier Hydration section documenting
  ContextTierHydrator (PR #4219), hydration algorithm, exclusion rules,
  configuration parameters, and LLMExecuteActor integration
- mkdocs.yml: add Git Worktree Sandbox to Modules nav

2026-04-28 09:25:34 +00:00

5.9 KiB

Raw Blame History

Git Worktree Sandbox

The Git Worktree Sandbox provides git-native isolation for plan execution on git-checkout resources. Introduced in v3.5.0 (PR #5998), it replaces the previous flat shutil.copy2 apply with a proper git merge workflow, giving users a clean git history and conflict-detection on apply.

Why Git Worktrees?

A git worktree is a linked working tree that shares the same git object database as the main repository but has its own checked-out branch and working directory. This means:

Isolation: LLM-generated changes are committed to a dedicated branch (cleveragents/plan-<plan_id>) without touching the main working tree.
Auditability: Every plan execution produces a real git commit with a diff you can inspect before merging.
Conflict detection: git merge surfaces conflicts that flat file copy would silently overwrite.
Rollback: The worktree branch can be deleted without affecting the main branch.

Architecture

agents plan execute <plan_id>
        │
        ▼
  GitWorktreeSandbox.create()
        │
        ├── git worktree add /tmp/ca-wt-<id> -b cleveragents/plan-<plan_id>
        │
        ▼
  LLMExecuteActor writes files to worktree path
        │
        ▼
  git commit -m "plan: <plan_id> execute output"  (inside worktree)
        │
        ▼
  sandbox_ref stored → plan record

agents plan apply <plan_id>
        │
        ▼
  GitWorktreeSandbox.commit()
        │
        ├── git merge --no-ff cleveragents/plan-<plan_id>
        │
        ├── Display Apply Summary panel
        ├── Display Sandbox Cleanup panel
        ├── Display Next Steps panel
        └── ✓ OK  Changes applied

Execute Phase

When agents plan execute <plan_id> runs for a plan linked to a git-checkout resource:

GitWorktreeSandbox.create() is called with the resource's root path.
A temporary directory is created (e.g. /tmp/ca-wt-<ulid>).
git worktree add <tmp_dir> -b cleveragents/plan-<plan_id> creates the isolated branch.
The LLMExecuteActor writes all generated files into <tmp_dir>.
Changes are committed: git commit -m "plan: <plan_id> execute output".
The worktree path is stored as a sandbox reference in the plan record.

Apply Phase

When agents plan apply <plan_id> runs:

The sandbox reference is resolved to the worktree path.
git merge --no-ff cleveragents/plan-<plan_id> is run in the main repository.
On success, the CLI renders:

╭─ Apply Summary ─────────────────────────────────────────────╮
│  Plan:       01HXYZ...                                       │
│  Artifacts:  3 files                                         │
│  Changes:    +42 / -7                                        │
│  Project:    my-project                                       │
│  Applied at: 2026-04-10T14:23:00Z                           │
╰─────────────────────────────────────────────────────────────╯
╭─ Sandbox Cleanup ───────────────────────────────────────────╮
│  ✓ Worktree removed                                          │
│  ✓ Branch merged to main                                     │
╰─────────────────────────────────────────────────────────────╯
╭─ Next Steps ────────────────────────────────────────────────╮
│  Review changes: git diff HEAD~1                             │
│  Commit if satisfied: git commit --amend                     │
╰─────────────────────────────────────────────────────────────╯
✓ OK  Changes applied

The worktree is removed: git worktree remove <tmp_dir> --force.
The worktree branch is deleted: git branch -d cleveragents/plan-<plan_id>.

Non-Git Fallback

If the linked resource is not a git repository (e.g. a plain directory resource), the sandbox falls back to CopyOnWriteSandbox:

Files are copied from the sandbox directory to the project directory using shutil.copy2.
Path traversal guards prevent writes outside the project root.
Protected directories (.git, .cleveragents, node_modules, __pycache__) are skipped.

Merge Conflict Handling

If git merge encounters conflicts:

The plan transitions to ERRORED processing state.
error_message is set to "Merge failed: <details>".
error_details includes merge_conflict and sandbox_rollback: "pending".

Recovery steps:

# Review the conflict details
agents plan errors <plan_id>

# Manually resolve conflicts in the worktree branch
git checkout cleveragents/plan-<plan_id>
# ... resolve conflicts ...
git commit -m "resolve: manual conflict resolution"

# Re-apply
agents plan apply <plan_id>

Context Hydration

Before the LLM writes files to the worktree, the ContextTierHydrator pre-populates the ContextTierService with the project's source files. This ensures the LLM has full file context during execution.

See Context Tiers Reference for details on the hydration pipeline.

5.9 KiB Raw Blame History