feat(auth): separate filesystem read and write permissions

[juliusmarminge]

Direct workspace reads and edits currently share task permissions, while viewing local diffs requires review:write. Add filesystem:read for browsing, searching, file previews, and local diffs, and filesystem:write for file edits and saving plans. Both scopes remain in the Standard preset so narrower credentials can opt out of direct filesystem access.

Host workspace/media asset URLs require filesystem read permission when minted; attachments and project artwork retain their existing authorization. Web, desktop, and mobile controls follow each environment's grant. Losing write access stops pending autosaves and preserves unsaved drafts across closing and reopening the preview; an older editor's completed write cannot clear a newer draft's pending marker. Draft retention is released after confirmation or explicit clearing.

Retire review:write from new grants and the permission picker while keeping old credentials decodable. Existing connections must be paired again to receive filesystem scopes. These scopes govern direct client actions; they do not sandbox provider processes or terminal commands.

Validation: 17 filesystem access/browse tests, draft-retention regressions, and web/mobile typechecks pass. Offline file views distinguish connection failure from a pending permission check.

Pairing controls, captured from this layer’s base and head with the same viewport and default selection:

Before	After

Model: GPT-6. Harness: Codex.

---

Note

High Risk
Changes authentication and authorization for filesystem and asset access across server and all clients; misconfiguration or incomplete client updates could block file features or leave unexpected access until re-pairing.

Overview
Introduces filesystem:read and filesystem:write OAuth scopes and moves host file operations off broad orchestration/review grants. The server now requires filesystem read for listing, reading, searching, browsing, review diffs, and workspace/media asset URLs; filesystem write for projectsWriteFile. review:write is removed from new grants and pairing (AuthGrantScope) but still decodes on old sessions.

Web, mobile, and shared client runtime gate browse/search/preview, local git review sections, composer path search, and asset URL minting on filesystem:read; plan save and file edits need filesystem:write. Mobile and web file UIs use resolveFilesystemReadAccess for loading vs clear “cannot read host files” states. Read-only connections skip autosave, show read-only banners, and retain unsaved drafts until write access returns (with coordinator/query-state fixes so stale writes don’t clear newer edits).

Pairing settings and docs describe the new scopes; standard client defaults include both filesystem scopes. Server tests cover scope enforcement for RPC and assets.

^{Reviewed by Cursor Bugbot for commit 4b73b2d. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	13.6 KiB	—	15.1 KiB	✅
Codex	Thread snapshot wire	—	7.0 KiB	—	7.3 KiB	✅
Codex	Live turn WebSocket wire	—	6.6 KiB	—	7.8 KiB	✅
Codex	Live turn WebSocket decoded	—	57.1 KiB	—	66.4 KiB	✅
Codex	Live turn messages	—	10	—	21	✅
Claude	Total thread wire	—	13.6 KiB	—	15.1 KiB	✅
Claude	Thread snapshot wire	—	7.0 KiB	—	7.3 KiB	✅
Claude	Live turn WebSocket wire	—	6.5 KiB	—	7.8 KiB	✅
Claude	Live turn WebSocket decoded	—	57.9 KiB	—	66.4 KiB	✅
Claude	Live turn messages	—	10	—	21	✅

Baseline: unavailable · PR result: 4b73b2d · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 113.8 KiB
• Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the authorization model and default grants for filesystem reads and writes, then propagates those permissions through server RPCs and numerous web/mobile file-access paths. The security-sensitive scope migration and changed defaults warrant human review despite the accompanying tests and documentation.

No code changes detected at 4b73b2d. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{Bugbot Autofix is ON, but a cloud agent failed to start.}

^{Reviewed by Cursor Bugbot for commit 4b73b2d. Configure here.}

[cursor]

Pending grant shown as file denial

Medium Severity

useEnvironmentScope is false while the session is still unresolved, and these surfaces treat that as a confirmed missing filesystem:read grant. The add-project folder picker shows This connection cannot browse host folders before the grant is known, and composer path search returns the same kind of denial instead of staying pending.

Additional Locations (2)

• apps/mobile/src/state/queries.ts#L257-L277
• apps/web/src/state/queries.ts#L274-L297

 

^{Reviewed by Cursor Bugbot for commit 4b73b2d. Configure here.}

[cursor]

Offline new-task permission never settles

Medium Severity

fileAccessPending stays true whenever session data and error are both empty. On an offline or unavailable environment that never completes /api/auth/session, default workspace mode never settles, so the auto-branch effect cannot write a default branch.

 

^{Reviewed by Cursor Bugbot for commit 4b73b2d. Configure here.}