Workspace

Acolyte resolves one workspace per request, detects its ecosystem and commands, and constrains tool access to the validated workspace boundary.

Workspace root

Each request runs with one workspace root directory.

If no workspace is provided, Acolyte uses the current working directory. When a workspace path is provided, it must exist and be a directory.

Detection

Workspace behavior has two detection layers:

Root detection: The runtime resolves the active workspace from request input (workspace) or defaults to process CWD.
Profile detection: The workspace detector infers ecosystem and commands (format/lint/test, package manager) from project files and caches the result per workspace for reuse.

Sandbox

Tool filesystem access is scoped to the sandbox boundary.

Access inside the boundary is allowed. Access outside it is denied. This rule is enforced across tool entry paths, including CLI tool mode (acolyte tool ...).

The boundary is the outermost enclosing git repository, or the workspace root when there is none and when the only enclosing repository is at or above the home directory. The repository is the project, so the boundary is the project rather than whichever directory Acolyte was started in.

Workspace	Boundary	Why
a repository root	itself	the common case
a subdirectory of a repository	the repository root	one project, opened partway in
a worktree nested in its repository	the primary checkout	project-owned paths linked back to it stay reachable
a worktree outside its repository	the worktree	nothing above it belongs to the project
any path under a git-tracked home	the workspace	a home repository must not turn one project’s grant into everything the user owns
not in a repository	the workspace	no project to widen to

File enumeration and search scoping stay keyed to the workspace root in every case, so discovery still sees only the workspace’s own files.

Path checks are fail-closed and use resolved-path validation (realpath) so symlink escapes are blocked. For paths that do not exist yet, validation resolves the nearest existing parent and enforces the same boundary.

For shell-run, Acolyte executes argv (cmd + args) without shell evaluation. The command path and path-like arguments are validated against the workspace sandbox, and execution runs with a restricted environment allowlist. This is command-level enforcement, not kernel-level process isolation, and it does not constrain filesystem access performed internally by the executed binary.

No special temp-root exception exists in sandbox enforcement.

Execution policy

Acolyte has no per-tool approval layer. Once a task begins, tools can work within the validated workspace boundary; attempts to cross it return structured sandbox errors.

Sandbox violations

Boundary violations are returned as structured tool errors:

code — E_SANDBOX_VIOLATION
kind — sandbox_violation

Workspace profile

Acolyte detects and stores a workspace profile with:

ecosystem
package manager
format command
lint command
test command

The profile is used by lifecycle effects and tooling behavior, including format/lint runs on edited files and scoped test execution through detected test commands.

Profile detection is implemented by workspace detector modules and exposed via resolveWorkspaceProfile.

Observability

Workspace and sandbox behavior is visible in lifecycle debug/trace events:

lifecycle.workspace.profile
lifecycle.workspace.sandbox

A boundary violation surfaces as lifecycle.error carrying the sandbox-violation code and kind.

Key files

src/workspace-contract.ts — WorkspaceProfile and WorkspaceCommand types
src/workspace-profile.ts — profile resolution, caching, and instruction generation
src/workspace-detectors.ts — ecosystem detection from project files
src/workspace-sandbox.ts — path validation and sandbox enforcement