[Phase 4.B] ExecutionContext abstraction: local | worktree | e2b-sandbox

[frankbria]

Overview

Phase 4.B introduces an ExecutionContext abstraction so that conductor.py and all agent adapters can isolate task execution from the shared filesystem.

Motivation

cf work batch run --strategy parallel currently runs concurrent threads on the same live filesystem with no isolation. Agents can corrupt each other's work, hit git index locks, or overwrite changes.

Deliverables

codeframe/core/sandbox/context.py

Define the ExecutionContext protocol/dataclass:

class IsolationLevel(str, Enum):
    NONE = "none"         # shared filesystem (current behavior)
    WORKTREE = "worktree" # git worktree per task
    CLOUD = "cloud"       # E2B Linux VM per task

@dataclass
class ExecutionContext:
    task_id: str
    isolation: IsolationLevel
    workspace_path: Path
    cleanup: Callable[[], None]  # called on task completion

CLI flag

• --isolation none|worktree|cloud on cf work start and cf work batch run
• Default: none (preserves current behavior)

Integration points

• conductor.py passes ExecutionContext to each worker
• All agent adapters (ReactAgent, ClaudeCodeAdapter, etc.) respect context.workspace_path
• Runtime creates/tears down context around each task run

Acceptance Criteria

• ExecutionContext dataclass defined in core/sandbox/context.py
• IsolationLevel enum with none | worktree | cloud
• --isolation flag wired up on cf work start and cf work batch run
• conductor.py creates context before dispatch, cleans up after
• Tests for context lifecycle (create, use, cleanup)
• Default none preserves all existing behavior

Dependencies

• Blocked by nothing (can start now)
• Blocks: worktree isolation (#next), E2BAgentAdapter (#next+1)

Track

Phase 4.B — Execution Environment Layer

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• codeframe/core/context.py is the task context loader (file/PRD loading) — not the execution isolation abstraction. The new ExecutionContext must live in a new codeframe/core/sandbox/ package.
• BatchRun already has an isolate: bool field and _execute_task_subprocess already accepts a worktree_path: Optional[Path] parameter (currently unused), giving clear integration hooks.
• start_batch() in file:codeframe/core/conductor.py already accepts isolate: bool but does nothing with it yet.
• The CLI commands work start (work_start) and batch run (batch_run) in file:codeframe/cli/app.py are the two surfaces that need the --isolation flag.
• gitpython is already a declared dependency, so git worktree operations are available.

Approach

Create the ExecutionContext abstraction as a new codeframe/core/sandbox/ package, wire the --isolation flag into both CLI commands, thread the context through conductor.py's dispatch path, and have each agent adapter respect context.workspace_path. The none level is a no-op wrapper so all existing behavior is preserved by default.

---

Implementation Steps

1. Create codeframe/core/sandbox/ package

Create codeframe/core/sandbox/__init__.py (empty or re-exporting the public API).

---

2. Define ExecutionContext in codeframe/core/sandbox/context.py

Define the following in this new file:

• IsolationLevel enum (str, Enum) with three members:

  • NONE = "none" — shared filesystem, current behavior
  • WORKTREE = "worktree" — git worktree per task
  • CLOUD = "cloud" — E2B Linux VM per task (reserved for a future phase)

• ExecutionContext dataclass with fields:

  • task_id: str
  • isolation: IsolationLevel
  • workspace_path: Path — the root path the agent should operate in
  • cleanup: Callable[[], None] — called after task completion

• create_execution_context(task_id, isolation, repo_path) -> ExecutionContext factory function:

  • IsolationLevel.NONE → returns an ExecutionContext where workspace_path = repo_path and cleanup is a no-op.
  • IsolationLevel.WORKTREE → uses gitpython (git.Repo) to create a worktree at a temp path (e.g., repo_path / ".codeframe" / "worktrees" / task_id), sets workspace_path to that path, and sets cleanup to remove the worktree via repo.git.worktree("remove", "--force", path).
  • IsolationLevel.CLOUD → raises NotImplementedError with a message pointing to the future E2B phase.

sequenceDiagram
    participant Conductor
    participant Factory as create_execution_context()
    participant Git as gitpython
    participant Agent

    Conductor->>Factory: task_id, isolation, repo_path
    alt isolation == NONE
        Factory-->>Conductor: ctx(workspace_path=repo_path, cleanup=noop)
    else isolation == WORKTREE
        Factory->>Git: repo.git.worktree("add", worktree_path, "HEAD")
        Git-->>Factory: worktree created
        Factory-->>Conductor: ctx(workspace_path=worktree_path, cleanup=remove_worktree)
    end
    Conductor->>Agent: execute(workspace_path=ctx.workspace_path)
    Agent-->>Conductor: done
    Conductor->>Factory: ctx.cleanup()

---

3. Add --isolation flag to cf work start

In file:codeframe/cli/app.py, inside work_start():

• Add a isolation: str Typer option with --isolation, default "none", using click.Choice(["none", "worktree", "cloud"], case_sensitive=False).
• Pass the resolved isolation value down to runtime.execute_agent() as a new keyword argument isolation.

---

4. Add --isolation flag to cf work batch run

In file:codeframe/cli/app.py, inside batch_run():

• Add the same isolation Typer option.
• Pass it to conductor.start_batch() as a new isolation parameter (replacing or supplementing the existing isolate: bool).

---

5. Thread isolation through conductor.start_batch() and BatchRun

In file:codeframe/core/conductor.py:

• Change BatchRun.isolate: bool to BatchRun.isolation: str (defaulting to "none"), or add isolation: str alongside the existing field. Update _save_batch / _row_to_batch accordingly.
• Update start_batch() signature to accept isolation: str = "none" and store it on the BatchRun.
• In _execute_single_task() and the execute_task closure inside _execute_group_parallel(), call create_execution_context(task_id, IsolationLevel(batch.isolation), workspace.repo_path) before dispatching, then call ctx.cleanup() in a finally block after the task completes.
• Pass ctx.workspace_path to _execute_task_subprocess() via the already-present worktree_path parameter.

---

6. Use context.workspace_path in _execute_task_subprocess()

In file:codeframe/core/conductor.py, _execute_task_subprocess() already accepts worktree_path: Optional[Path] and already passes it as cwd to subprocess.Popen. No structural change needed here — the worktree path flows through correctly once step 5 populates it.

---

7. Thread isolation through runtime.execute_agent()

In file:codeframe/core/runtime.py (the module imported by work_start):

• Add isolation: str = "none" to execute_agent().
• Before calling the agent, call create_execution_context(task_id, IsolationLevel(isolation), workspace.repo_path).
• Pass ctx.workspace_path to the agent constructor/runner (see step 8).
• Call ctx.cleanup() in a finally block after the agent returns.

---

8. Make agent adapters respect workspace_path

In file:codeframe/core/react_agent.py (ReactAgent.__init__) and file:codeframe/core/agent.py (Agent.__init__):

• Both already accept a workspace parameter and derive their working path from workspace.repo_path. Add an optional workspace_path: Optional[Path] = None parameter; when provided, use it in place of workspace.repo_path for all file I/O and subprocess cwd calls.
• In file:codeframe/agents/worker_agent.py (WorkerAgent), apply the same pattern.

Note: For IsolationLevel.NONE the passed workspace_path equals repo_path, so no behavioral change occurs.

---

9. Update _save_batch / _row_to_batch for the new field

In file:codeframe/core/conductor.py:

• The batch_runs INSERT statement and _row_to_batch currently store engine as the last column. Add isolation as an additional column (or reuse the existing isolate bool column by storing the string value). Ensure the schema migration is handled gracefully (e.g., ALTER TABLE batch_runs ADD COLUMN isolation TEXT DEFAULT 'none' guarded by a try/except).

---

Data flow summary

graph TD
    CLI["cf work start --isolation worktree\ncf work batch run --isolation worktree"]
    Runtime["runtime.execute_agent(isolation=...)"]
    Conductor["conductor.start_batch(isolation=...)"]
    Factory["create_execution_context()"]
    CTX["ExecutionContext\n(workspace_path, cleanup)"]
    Agent["ReactAgent / Agent\n(workspace_path=ctx.workspace_path)"]
    Subprocess["_execute_task_subprocess(worktree_path=ctx.workspace_path)"]
    Cleanup["ctx.cleanup()  →  git worktree remove"]

    CLI --> Runtime
    CLI --> Conductor
    Runtime --> Factory
    Conductor --> Factory
    Factory --> CTX
    CTX --> Agent
    CTX --> Subprocess
    Agent --> Cleanup
    Subprocess --> Cleanup

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `codeframe/core/context.py` is the **task context loader** (file/PRD loading) — not the execution isolation abstraction. The new `ExecutionContext` must live in a new `codeframe/core/sandbox/` package.
- `BatchRun` already has an `isolate: bool` field and `_execute_task_subprocess` already accepts a `worktree_path: Optional[Path]` parameter (currently unused), giving clear integration hooks.
- `start_batch()` in `file:codeframe/core/conductor.py` already accepts `isolate: bool` but does nothing with it yet.
- The CLI commands `work start` (`work_start`) and `batch run` (`batch_run`) in `file:codeframe/cli/app.py` are the two surfaces that need the `--isolation` flag.
- `gitpython` is already a declared dependency, so git worktree operations are available.

## Approach

Create the `ExecutionContext` abstraction as a new `codeframe/core/sandbox/` package, wire the `--isolation` flag into both CLI commands, thread the context through `conductor.py`'s dispatch path, and have each agent adapter respect `context.workspace_path`. The `none` level is a no-op wrapper so all existing behavior is preserved by default.

---

## Implementation Steps

### 1. Create `codeframe/core/sandbox/` package

Create `codeframe/core/sandbox/__init__.py` (empty or re-exporting the public API).

---

### 2. Define `ExecutionContext` in `codeframe/core/sandbox/context.py`

Define the following in this new file:

- **`IsolationLevel` enum** (`str, Enum`) with three members:
  - `NONE = "none"` — shared filesystem, current behavior
  - `WORKTREE = "worktree"` — git worktree per task
  - `CLOUD = "cloud"` — E2B Linux VM per task (reserved for a future phase)

- **`ExecutionContext` dataclass** with fields:
  - `task_id: str`
  - `isolation: IsolationLevel`
  - `workspace_path: Path` — the root path the agent should operate in
  - `cleanup: Callable[[], None]` — called after task completion

- **`create_execution_context(task_id, isolation, repo_path) -> ExecutionContext`** factory function:
  - `IsolationLevel.NONE` → returns an `ExecutionContext` where `workspace_path = repo_path` and `cleanup` is a no-op.
  - `IsolationLevel.WORKTREE` → uses `gitpython` (`git.Repo`) to create a worktree at a temp path (e.g., `repo_path / ".codeframe" / "worktrees" / task_id`), sets `workspace_path` to that path, and sets `cleanup` to remove the worktree via `repo.git.worktree("remove", "--force", path)`.
  - `IsolationLevel.CLOUD` → raises `NotImplementedError` with a message pointing to the future E2B phase.

```
sequenceDiagram
    participant Conductor
    participant Factory as create_execution_context()
    participant Git as gitpython
    participant Agent

    Conductor->>Factory: task_id, isolation, repo_path
    alt isolation == NONE
        Factory-->>Conductor: ctx(workspace_path=repo_path, cleanup=noop)
    else isolation == WORKTREE
        Factory->>Git: repo.git.worktree("add", worktree_path, "HEAD")
        Git-->>Factory: worktree created
        Factory-->>Conductor: ctx(workspace_path=worktree_path, cleanup=remove_worktree)
    end
    Conductor->>Agent: execute(workspace_path=ctx.workspace_path)
    Agent-->>Conductor: done
    Conductor->>Factory: ctx.cleanup()
```

---

### 3. Add `--isolation` flag to `cf work start`

In `file:codeframe/cli/app.py`, inside `work_start()`:

- Add a `isolation: str` Typer option with `--isolation`, default `"none"`, using `click.Choice(["none", "worktree", "cloud"], case_sensitive=False)`.
- Pass the resolved `isolation` value down to `runtime.execute_agent()` as a new keyword argument `isolation`.

---

### 4. Add `--isolation` flag to `cf work batch run`

In `file:codeframe/cli/app.py`, inside `batch_run()`:

- Add the same `isolation` Typer option.
- Pass it to `conductor.start_batch()` as a new `isolation` parameter (replacing or supplementing the existing `isolate: bool`).

---

### 5. Thread `isolation` through `conductor.start_batch()` and `BatchRun`

In `file:codeframe/core/conductor.py`:

- Change `BatchRun.isolate: bool` to `BatchRun.isolation: str` (defaulting to `"none"`), or add `isolation: str` alongside the existing field. Update `_save_batch` / `_row_to_batch` accordingly.
- Update `start_batch()` signature to accept `isolation: str = "none"` and store it on the `BatchRun`.
- In `_execute_single_task()` and the `execute_task` closure inside `_execute_group_parallel()`, call `create_execution_context(task_id, IsolationLevel(batch.isolation), workspace.repo_path)` before dispatching, then call `ctx.cleanup()` in a `finally` block after the task completes.
- Pass `ctx.workspace_path` to `_execute_task_subprocess()` via the already-present `worktree_path` parameter.

---

### 6. Use `context.workspace_path` in `_execute_task_subprocess()`

In `file:codeframe/core/conductor.py`, `_execute_task_subprocess()` already accepts `worktree_path: Optional[Path]` and already passes it as `cwd` to `subprocess.Popen`. No structural change needed here — the worktree path flows through correctly once step 5 populates it.

---

### 7. Thread `isolation` through `runtime.execute_agent()`

In `file:codeframe/core/runtime.py` (the module imported by `work_start`):

- Add `isolation: str = "none"` to `execute_agent()`.
- Before calling the agent, call `create_execution_context(task_id, IsolationLevel(isolation), workspace.repo_path)`.
- Pass `ctx.workspace_path` to the agent constructor/runner (see step 8).
- Call `ctx.cleanup()` in a `finally` block after the agent returns.

---

### 8. Make agent adapters respect `workspace_path`

In `file:codeframe/core/react_agent.py` (`ReactAgent.__init__`) and `file:codeframe/core/agent.py` (`Agent.__init__`):

- Both already accept a `workspace` parameter and derive their working path from `workspace.repo_path`. Add an optional `workspace_path: Optional[Path] = None` parameter; when provided, use it in place of `workspace.repo_path` for all file I/O and subprocess `cwd` calls.
- In `file:codeframe/agents/worker_agent.py` (`WorkerAgent`), apply the same pattern.

> **Note:** For `IsolationLevel.NONE` the passed `workspace_path` equals `repo_path`, so no behavioral change occurs.

---

### 9. Update `_save_batch` / `_row_to_batch` for the new field

In `file:codeframe/core/conductor.py`:

- The `batch_runs` INSERT statement and `_row_to_batch` currently store `engine` as the last column. Add `isolation` as an additional column (or reuse the existing `isolate` bool column by storing the string value). Ensure the schema migration is handled gracefully (e.g., `ALTER TABLE batch_runs ADD COLUMN isolation TEXT DEFAULT 'none'` guarded by a `try/except`).

---

### Data flow summary

```
graph TD
    CLI["cf work start --isolation worktree\ncf work batch run --isolation worktree"]
    Runtime["runtime.execute_agent(isolation=...)"]
    Conductor["conductor.start_batch(isolation=...)"]
    Factory["create_execution_context()"]
    CTX["ExecutionContext\n(workspace_path, cleanup)"]
    Agent["ReactAgent / Agent\n(workspace_path=ctx.workspace_path)"]
    Subprocess["_execute_task_subprocess(worktree_path=ctx.workspace_path)"]
    Cleanup["ctx.cleanup()  →  git worktree remove"]

    CLI --> Runtime
    CLI --> Conductor
    Runtime --> Factory
    Conductor --> Factory
    Factory --> CTX
    CTX --> Agent
    CTX --> Subprocess
    Agent --> Cleanup
    Subprocess --> Cleanup
```

---

Execution Information

Branch: main
Commit: 7d5caab

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#425 - feat(core): wire StallAction dispatch into ReactAgent and runtime (#401) [merged]
#435 - refactor(core): unify ReactAgent context loading via TaskContextPackager [merged]
#441 - feat(core): worktree-per-task isolation for parallel batch execution [merged]
#514 - docs(roadmap): restructure Phase 4 with execution environment layer [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!