Execution Environments

An Agent Adapter answers how Forge talks to an agent. An Execution Environment answers where the work runs.

Keeping these independent prevents every adapter from reimplementing worktree, Docker, SSH, and remote behavior.

First environment

The first implementation is LocalWorktreeEnvironment.

It provides a prepared working directory inside a Git worktree plus a controlled environment for process execution.

Interface direction

Do not freeze an over-large interface before use. The boundary will likely need capabilities such as:

Prepare
WorkingDirectory
Environment
Exec / process launching integration
Cleanup

File reads/writes may remain ordinary filesystem operations when local; do not add remote-oriented methods until the second environment proves they are required.

Future environments

Possible later implementations:

• local checkout (for carefully chosen human-only workflows);
• Docker;
• SSH;
• remote development machine;
• managed remote sandbox.

These are intentionally not MVP work.

Environment snapshot

An Agent Run should preserve enough immutable information to explain what environment/strategy it used even if current settings change.

Trust

Preparing an environment may execute repository-defined setup commands. This crosses a trust boundary. Forge distinguishes opening a Project from trusting it to execute configured automation.

Separation from provider

Bad:

ClaudeAdapter:
  if docker ...
  if ssh ...
  if worktree ...

Preferred:

Task → choose Agent Strategy
     → choose Execution Environment

Orchestrator composes them

The exact composition mechanics will be learned while implementing the fake adapter and first worktree environment.