41 lines
1.9 KiB
Markdown
41 lines
1.9 KiB
Markdown
# 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](../USER-AGENTS.md) for scope and verification.
|