Workspace and execution

This page defines the current contract for workspace identity, execution roots, worktree isolation, and host-local execution policy.

Last verified: 2026-05-23 against src/types.rs ActiveWorkspaceEntry, WorkspaceOccupancyRecord, WorktreeSession, ExecutionSnapshot, and src/runtime/workspace.rs.

Source RFCs

Core model

Every agent has exactly one active workspace. The active workspace defines:

Concept	Meaning
`workspace_id`	Stable identifier for the workspace
`workspace_anchor`	Filesystem path to the workspace root
`execution_root`	The root for process execution (may differ from anchor)
`cwd`	Current working directory for shell commands
`projection_kind`	How the workspace is projected (`CanonicalRoot`, `GitWorktreeRoot`)
`access_mode`	How the agent holds the workspace (`SharedRead`, `ExclusiveWrite`)

Active workspace vs shell `cd`

The active workspace is runtime state, not shell state.
Shell cd in ExecCommand changes that one command's working directory but does not change the active workspace, instruction root, AGENTS.md scope, or ApplyPatch relative-path base.
UseWorkspace is the tool for switching the active workspace.

Agent home

agent_home is the built-in fallback workspace for agent-local state:

Directory	Purpose
`AGENTS.md`	Long-lived agent contract (loaded as guidance)
`memory/`	Curated memory markdown (`self.md`, `operator.md`)
`notes/`	Working notes
`work-items/`	WorkItem plan artifacts (`plan.md`)
`skills/`	Agent-local skills
`.holon/`	Runtime-owned state, ledger, index, cache

Key contract:

.holon/ is runtime-owned; agents must not edit it.
AGENTS.md may evolve but should capture durable agent behavior, not transient plans or copied project docs.
agent_home is always available as a workspace, even when no project workspace is attached.

Workspace occupancy

Workspaces track occupancy: which agent holds the workspace and how:

Field	Purpose
`holder_agent_id`	The agent currently occupying the workspace
`access_mode`	`SharedRead` or `ExclusiveWrite`
`acquired_at`	When occupancy was acquired
`released_at`	When occupancy was released (if released)

Workspace occupancy is used for coordination; it is not a hard lock. The runtime uses occupancy records for diagnostics and cleanup, not for preventing concurrent access at the filesystem level.

Worktrees

When an agent needs isolated file changes, UseWorkspace with mode=isolated creates a runtime-managed worktree:

The worktree has a separate execution_root from the canonical workspace.
Worktree lifecycle is tied to the agent session; the runtime cleans up on agent stop or explicit release.
Worktrees use the host-local filesystem (git worktrees or temp directories); they are not containerized sandboxes.

Execution snapshot (`ExecutionSnapshot`)

The ExecutionSnapshot in AgentSummary captures the current execution context:

Active run id
Active workspace id and occupancy
Execution root and cwd
Worktree session (if applicable)
Host-local policy flags

Host-local policy

Holon's current execution model is host-local: processes run on the host filesystem with the agent user's permissions. Key constraints:

cwd is always within the execution root.
Process execution is not containerized or sandboxed by the runtime.
Network access is not confined by default.
The execution_environment summary in model context describes the current policy snapshot as a transparency contract, not a hard sandbox guarantee.

Known gaps

Worktree cleanup is best-effort; stale worktrees may persist after abnormal agent termination.
Workspace occupancy is advisory; the runtime does not enforce exclusive write access at the filesystem level.
Isolated worktrees use git worktrees; non-git workspaces fall back to temp directories with weaker cleanup guarantees.