1.9 KiB
ADR 0016: Explicit user-agent capabilities and recoverable personal changes
- Status: accepted
- Date: 2026-10-12
Context
Workspace agents and the desktop assistant are user-level clients, distinct from the privileged broker. The existing MCP desktop files were not consumed by the shipped desktop, system proposals were not durable plans, user-installed agents could not be granted narrowly, and reconnects/history persistence lacked adequate failure handling.
Decision
Keep workspace write authority explicit, expose user-installed tools through read-only directory grants, and isolate networking by default. Fixed Bubblewrap and descriptor-pinned mounts are mandatory. Shared networking is an explicit capability, including host loopback access.
Use native desktop formats behind closed schemas and a fixed action catalogue. Journal before mutation, retain recovery records, and refuse undo over external edits. Stage package proposals using the existing reviewed-plan service without executing or authenticating from MCP.
Separate desktop and CLI follow-up context; use bounded private descriptor-based storage and serialize appends/clears. Recover bridge availability with compatible handshakes and bounded retries, without replaying pending work. Bundle both user binaries with the installer/runtime and explicitly install Bubblewrap.
Serialize descriptor inheritance around all executor process spawns. Lock release waits for in-flight fork/exec transitions; intentional worker leases retain the mutation lock after broker death.
Consequences
Remote agents need explicit network grants. Existing unused desktop settings and checkpoints are not migrated. Native settings require reload; a safe live IPC and host-held authenticated MCP transport need separate implementation and acceptance. The jail never receives the host home or runtime as a connectivity shortcut. See USER-AGENTS.md for scope and verification.