ADR: Composer pasted directory references
- Status: Accepted
- Date: 2026-11-03
- Related: ADR 0059, ADR 0070
Context
A directory has no regular-file bytes, and Chromium can omit its clipboard File. Copying its tree into scratch would create an expensive and stale snapshot.
Decision
On an explicit native-file paste, Electron main captures bounded native clipboard file metadata. Directories become typed draft references and removable folder cards above the editable text, with a name, localized Folder label and full-path tooltip. Mixed regular files use the sender-bound one-shot selection capability to register live file references. Main captures the selection before filesystem awaits and accepts no renderer paths. The bridge is main-window-only and blocked from MCP/plugin callers. macOS reads raw pasteboard types, Linux reads native file URI lists, and Windows reads the complete native FileDropList in a bounded STA PowerShell invocation. Native raw formats are not gated on Electron's normalized MIME enumeration.
Directory references serialize as escaped <dir>absolute/path</dir> markers plus one instruction to inspect directory structure and read relevant files as needed for the current request. They never enter binary attachment transport, previews, recursive copies or file snapshots. References grant no new filesystem access; existing tool permission checks apply. Removing a card removes its prompt hint. The user bubble displays the references as folder cards. Its local reveal action is restricted to the main renderer and an existing absolute directory. The action reveals the directory in the system file manager and returns no contents.
Consequences
Generated image/text paste and the existing directory-drop choice remain. Native disk files follow the local-file-reference decision above. Clipboard file metadata is read only for a paste gesture, never polled or added to clipboard history. Draft/history metadata retains directory paths rather than contents. Directories may change or disappear before later use. The existing JSON reference shape gains the additive directory kind; Host protocol and database schema versions remain unchanged.