Define trusted local CLI access versus restricted filesystem isolation

[manishiitg]

Problem

Native AgentWorks workflow shells currently use a macOS sandbox profile with (allow default), deny the AgentWorks project root, and re-allow approved workspace paths. This intentionally leaves the rest of the user's home directory available so locally installed CLIs such as AWS CLI, Google Workspace CLI, gcloud, kubectl, Docker, Node/npm, and future user-installed tools can resolve their normal configuration, credentials, caches, and state.

A review confirmed that this also means a workflow shell can read unrelated home files through paths such as $HOME, ~, or language APIs such as Python Path.home(). The existing FolderGuard E2E tests only validate paths inside the temporary project root and therefore do not cover this boundary.

Product constraint

Normal local automation must continue to support arbitrary CLIs installed by users. A hardcoded list of CLI profiles is not sufficient because every CLI stores configuration differently, including:

• ~/.config/<tool>
• ~/.<tool>
• ~/Library/Application Support/<tool>
• macOS Keychain
• custom paths and environment variables

Allowing every installed CLI with its full normal behavior is effectively broad local access: interpreters such as Python, Node, and shell are also CLIs and can read arbitrary user files.

Current decision

Keep the existing trusted local behavior unchanged for now. Do not introduce hardcoded CLI-profile restrictions or change the native default until the product model is decided.

Design questions

• Should workflows expose explicit Trusted local access and Restricted workspace access modes?
• Should trusted local access be global, per workflow, or granted at first run?
• What should be the default for user-created local workflows versus imported/shared workflows?
• How should the UI clearly communicate laptop-file and local-credential authority?
• Can scheduled/background workflows have a different default from interactive local workflows?
• How should explicit selected-folder grants and workflow secrets interact with restricted mode?
• What migration behavior should existing workflows receive?

Required tests before implementation

1. Capture the current trusted-local before-state using decoy files and the real workspace HTTP shell endpoint.
2. Test bypass spellings: absolute paths, $HOME, ~, Python/Node home expansion, and symlink escapes.
3. Verify arbitrary executables located in user-home PATH directories continue to launch.
4. Run installed CLI compatibility checks for AWS CLI, gcloud, GWS, kubectl, Docker, GitHub CLI, and NVM Node.
5. Verify authenticated CLI behavior separately where live accounts are required.
6. Verify explicit host-folder read-only/read-write grants.
7. Test both the workspace API boundary and a real workflow step through the MCP bridge.
8. Ensure the AgentWorks source/config root remains protected in every mode.

Acceptance criteria

A future implementation must make the authority model explicit and testable without silently breaking user-installed CLIs or falsely claiming that FolderGuard confines a trusted-local workflow to workspace files.

[mprealtrainingsys]

Concrete data point for the trusted-vs-restricted design question, at a different layer (worth cross-referencing here).

Where: mcpagent's codex-cli integration (agent/coding_agent_integrations.go), not the FolderGuard macOS sandbox this issue describes — codex CLI has its own internal --sandbox flag (read-only / workspace-write / danger-full-access) independent of the OS-level sandbox.

What happened: Earlier today (commit 477dff6) codex's sandbox was hardcoded to read-only for every session, everywhere, as a P0 containment measure (codex ships an unremovable native functions.exec tool that can't be excluded from the tool-only-through-bridge policy any other way). That broke an interactive single-owner consumer (sparkquill/family-server) outright: codex's read-only mode has no writes and no native network (there's no read-only+network mode), and codex tends to disengage from tools entirely when its own preamble says "read-only, no network."

Resolution (commits 874aec7, 0eeec12, 11e2f2a): made the sandbox mode configurable per Agent (CodexSandboxMode / WithCodexSandbox, CodexNetworkAccess / WithCodexNetworkAccess), then flipped the default back to workspace-write (matching how codex ran for most of the project's life). read-only is now a deliberate, narrow opt-in for the two cases where it actually earns its keep:

• a session that deliberately withholds shell from the bridge (e.g. "web_search only, no shell") — read-only is the only thing that makes that restriction hold for codex specifically
• a session that needs every action to hit an audit trail that native exec would otherwise bypass

For everything else — interactive callers, or any session where the bridge already grants shell (so blocking codex's native writes stops nothing real, since the same writes are reachable through the bridge anyway) — workspace-write is now the default with no opt-in required.

Relevance to this issue's design questions: this landed on essentially the same shape #181 is asking about — an explicit default posture for the common/interactive case, with the stricter mode as an opt-in tied to why a session needs it (tool-set restriction or audit-trail integrity), rather than autonomous-vs-interactive alone. It also independently confirms the question "can scheduled/background workflows have a different default from interactive ones?" is the right frame — that's exactly the distinction that determined the right default here, just at codex's own sandbox layer instead of FolderGuard's.