Coding CLI filesystem security: Compatibility, Isolated Environment, and Verified Provider modes

[manishiitg]

Problem

AgentWorks supports coding CLIs such as Claude Code, Codex CLI, Cursor CLI, and Pi. These CLIs depend on host resources that are difficult to predict generically: binaries and system libraries, login/configuration files, transcripts, caches, Git identity and credentials, package managers, cloud configuration, network access, and sometimes login-shell initialization.

The current native macOS sandbox therefore starts from (allow default) and selectively protects the AgentWorks project/workspace using folder guards. This preserves broad CLI compatibility, but it cannot provide a perfect host-filesystem security boundary.

The core product problem is:

AgentWorks must support real coding CLIs without pretending that the same broad compatibility environment also provides strict filesystem isolation.

There is also a secondary enforcement concern: a restricted CLI process can reach local services over the network. The workspace HTTP service currently accepts execution/file requests without a strong execution-scoped authorization boundary. A filesystem-sandboxed process must not be able to ask an unsandboxed local service to perform a broader operation on its behalf.

Active scope

The current LLM-visible workspace registry intentionally excludes the old basic CRUD tools. update_workspace_file, delete_workspace_file, and move_workspace_file remain as legacy/library/example code and must not be treated as active production tools without proof that a reachable registry exposes them.

The active security surface includes:

• managed coding-CLI launches through the tmux provider adapters,
• execute_shell_command,
• diff_patch_workspace_file,
• code/script execution,
• MCP Bridge calls,
• browser/media operations that transfer workspace artifacts,
• direct reachability of the workspace HTTP service.

Root cause

The current design optimizes for unknown CLI compatibility:

• macOS uses an allow-by-default sandbox profile and adds targeted filesystem denies/allows,
• native shell execution inherits much of the host environment so installed CLIs work,
• provider adapters use real home-directory configuration and transcript state,
• provider requirements differ and change across CLI versions.

Folder guards remain valuable, but in this compatibility model they are best-effort workspace protection rather than a complete host isolation guarantee.

A second contributing cause is that authorization is transported through contexts, sessions, wrappers, clients, and request payloads. A local workspace service must not trust caller-supplied permission data or allow a missing guard to create an unrestricted second execution.

Revised solution: explicit CLI security modes

AgentWorks should make the compatibility/security choice explicit instead of presenting one mode as suitable for every CLI.

1. Compatibility mode

Preserve the current behavior:

• real host HOME, provider configuration, transcripts, credentials, caches, and installed tools,
• broad CLI compatibility,
• current folder guards around known workspace paths,
• clear product language that isolation is best-effort.

This is the migration mode for every existing workflow and Chief of Staff configuration. Existing sessions must not silently move to a stricter mode.

2. Isolated Environment mode

The CLI remains fully available, but it does not receive the user's real host files. It runs with:

• an AgentWorks-managed private HOME,
• private provider config/cache/transcript directories,
• separately configured or injected credentials,
• required system binaries/libraries,
• the assigned workspace paths,
• temporary storage.

Users authenticate/configure the provider inside this environment. The environment must persist when native CLI resume or saved authentication is required.

3. Verified Provider mode

Run a supported provider with a versioned, tested capability profile. The profile maps a human approval to implementation details such as:

• canonical provider executable,
• required provider configuration/authentication paths,
• transcript and cache paths,
• required environment-variable names,
• system/runtime dependencies,
• provider-native sandbox options,
• declared network requirements.

Users approve understandable capabilities, not raw paths. For example:

• "Use Codex CLI"
• "Use your existing Codex login and conversation history"
• "Use Git identity"
• "Access the configured AWS account"
• "Export reports to Downloads"

Raw executable and filesystem paths remain available under technical details. A changed executable identity, provider profile version, or additional requested capability requires revalidation/approval.

Verified Provider should become the recommended default only after the selected provider has passed real certification.

Builder-assisted profile discovery

A workflow Builder may run in Compatibility mode to learn what a step requires, then prepare the step for Verified Provider mode.

Flow:

1. Run a representative step in Compatibility/audit mode.
2. Collect trusted evidence: provider/version, process tree, declared workflow capabilities, workspace reads/writes, configuration/cache use, environment-variable names, network destinations, and sandbox denials.
3. Separate requirements into:
   • a provider baseline shared by all uses of that CLI,
   • a workflow-step overlay containing unusual external access.
4. Convert raw paths into human-readable capabilities.
5. Generate a candidate profile with evidence references.
6. Test the step under Verified Provider mode.
7. Present denied requirements as proposed changes.
8. Require a human to approve and freeze the resulting profile.

The Builder must never approve its own discovered permissions. A malicious or faulty CLI could intentionally touch sensitive files during discovery; observation is evidence, not authorization.

Because complete successful-read tracing may require privileged macOS instrumentation, the first version may combine certified provider contracts, declared workflow capabilities, launch telemetry, and sandbox-denial feedback rather than claiming perfect automatic discovery.

Runtime architecture

Resolve one immutable policy before starting a CLI execution:

type CLISecurityPolicy struct {
    Mode           string
    Provider       string
    WorkspaceRead  []string
    WorkspaceWrite []string
    HostRead       []string
    HostWrite      []string
    Environment    []string
    PrivateHome    string
    ProfileVersion string
}

Required flow:

chat/workflow request
  -> resolve effective user/workflow/provider policy
  -> attach immutable policy to the Agent
  -> pass policy through mcpagent into multi-llm-provider-go
  -> provider adapter launches the exact CLI under that policy

Coding CLIs are launched by tmux provider adapters. The sandbox wrapper must therefore execute inside the tmux pane around the CLI command. Sandboxing only the tmux client is insufficient because an existing tmux server would create the pane outside that client process's sandbox.

The model/agent cannot submit its own provider identity, executable path, or permission profile. AgentWorks resolves the configured provider ID, canonical executable, approved profile, and effective paths in trusted code.

Generic shell text cannot be reliably classified by parsing commands. In stricter modes, additional executables launched by a provider/process tree must remain inside the same policy and must not silently widen permissions.

Provider contracts

Extend the existing coding-agent provider contract with security metadata:

• expected executable names and identity checks,
• private-home support,
• required read/write/config/cache/transcript paths,
• required environment-variable names,
• provider-native sandbox features,
• profile version,
• certification status and evidence.

Start with one provider (Codex CLI is the preferred first candidate), then certify Claude Code, Cursor CLI, and Pi independently.

Workspace service boundary

Every security mode needs one invariant:

A CLI restricted by an AgentWorks policy cannot obtain broader authority by calling a local AgentWorks service.

The workspace service must reject unauthenticated direct execution/mutation calls and must not trust a caller to supply or widen its own folder guard. CLI tool use should go through the session-scoped MCP Bridge/agent server path, which resolves the existing session policy. Internal workspace-service credentials must never be injected into CLI environments.

Configuration and approval

Security policy is server-controlled configuration, not an agent-editable workflow file.

Support:

• a user/account default mode,
• approved provider profiles and profile versions,
• approved human-readable capabilities,
• optional workflow restrictions that can narrow but not silently widen the user policy,
• immutable effective policy stored with each execution/session,
• preflight validation for scheduled workflows.

Scheduled workflows cannot wait for interactive approval. They must be approved before scheduling or fail preflight with a clear missing-capability message. A stricter mode must never silently fall back to Compatibility.

Migration and product impact

• Existing workflows and Chief of Staff configurations resolve to Compatibility mode.
• Existing live tmux sessions retain their original effective mode until closed.
• Resume requires the same compatible environment/profile; Isolated mode reuses its persistent private home.
• API-model workflows are unaffected unless they launch shell/code processes.
• Scripted steps using Git, cloud CLIs, SSH, Downloads, or external repositories may require Verified capabilities or Compatibility mode.

Delivery phases

1. Add policy types/resolution/telemetry while preserving Compatibility behavior.
2. Record effective mode, provider identity, profile version, and exposed capability groups in execution metadata.
3. Protect the workspace-service boundary from direct permission widening.
4. Implement and certify Verified Provider for Codex CLI.
5. Add Builder-generated candidate profiles and Verified replay testing.
6. Add human-readable approval UI and scheduled-workflow preflight.
7. Certify remaining providers individually.
8. Implement persistent private homes for Isolated Environment mode.
9. Make Verified Provider the recommended default only after certification evidence is sufficient.

Acceptance criteria

• Existing workflows and Chief of Staff behave unchanged in Compatibility mode.
• Every coding-CLI execution records an immutable effective security mode and provider identity.
• A provider cannot select or widen its own profile.
• A changed profile/version/capability set is detected before execution.
• Verified runs expose only the approved provider baseline and workflow overlay.
• Isolated runs cannot read the real user home and retain their private provider state across resume.
• Direct workspace API calls cannot bypass the originating execution policy.
• Scheduled runs fail preflight instead of prompting or silently falling back.
• The UI presents human capabilities with optional technical path details.
• Real E2E certification covers workspace access, denied host access, login/configuration, MCP Bridge, transcripts/resume, nested processes, and local-service bypass attempts.

Relevant locations

• agent_go/pkg/common/types.go
• agent_go/pkg/workspace/execute_shell_command.go
• agent_go/cmd/server/server.go
• agent_go/cmd/server/virtual-tools/workspace_tool_registry.go
• agent_go/pkg/orchestrator/agents/workflow/step_based_workflow/controller_agent_factory.go
• workspace/server.go
• workspace/handlers/shell.go
• workspace/security/isolator.go
• workspace/security/environment.go
• mcpagent/agent/coding_agent_options.go
• mcpagent/agent/coding_agent_integrations.go
• multi-llm-provider-go/coding_agent_contract.go
• provider tmux adapters under multi-llm-provider-go/pkg/adapters/

[manishiitg]

Builder-side foundation is ready for review in draft PR #154.

Implemented:

• immutable copy-on-write session permission snapshots
• preserved hard deny and write-only deny paths across child sessions
• explicit empty/read-only guards fail closed across file, shell, and browser paths
• context-aware validation inside all workspace file operations, including diff patch and downloads
• symlink escape rejection
• permission cleanup on stop, clear, and retained-session eviction

The issue stays open. Remaining scope: signed workspace API authentication/capability leases, dedicated backup operation, environment credential broker, DB/default-path hardening, and full adversarial E2E coverage.

[manishiitg]

Implementation progress (local working trees; not committed/pushed yet):

• Added the three CLI filesystem modes with Compatibility as the default, preserving current workflows and Chief of Staff behavior.
• Added a server-owned, per-user security configuration store plus API and an explicit CLI Security settings UI.
• Implemented Codex strict enforcement on macOS inside the tmux pane using sandbox-exec, so an existing tmux server cannot escape the policy.
• Strict launches now use an empty environment plus an allowlist, immutable policy fingerprints per persistent session, explicit workspace grants, and fail closed on unsupported providers or policy changes.
• Isolated Environment mode gives Codex a persistent AgentWorks-owned private HOME/CODEX_HOME while keeping the CLI and network available.
• Verified Provider mode maps the approved provider_identity capability to the versioned Codex state directory (~/.codex).
• The trusted AgentWorks api-bridge executable is extracted from server-generated MCP configuration and allowlisted explicitly. Strict mode rejects relative bridge paths, additional MCP commands, and non-executable bridge targets.
• Added a private service token for managed workspace /api/execute; it is passed only between AgentWorks services and stripped from shell-command environments, closing the direct shell-to-workspace-API escalation path.
• Added macOS enforcement tests covering workspace access, denial of unrelated home files, execution inside tmux, private-home environment, installed Codex startup, and the explicitly trusted bridge path. Full Go test suites and the frontend production build pass.

Still intentionally separate follow-up work:

1. Workflow Builder compatibility-run discovery and replay as a versioned Verified Provider plan (including per-step provider resolution).
2. Authentication/proxying for the remaining workspace mutation routes; this slice protects the high-risk shell execution route first.
3. Certification profiles for Claude Code, Cursor, Agy, and Pi.

No strict mode silently falls back to Compatibility.