ADR-0024: A model never writes — it proposes, the server proves the proposal, and only a person’s confirmation applies it
- Status: Accepted
- Date: 2026-11-06
- Scope: core (any backend feature where a language model can change a user’s or a tenant’s data)
Context
“Ask the user before writing” is easy to put in a prompt, and Expenses did. A prompt-only
confirmation failed the way 0019-llm-features-prompts-shape-code-enforces predicts (expenses
0027-assistant-writes-are-proposals-the-user-confirms):
- the model wrote without asking when it was confident, and asked about trivia when it was not;
- a card shown to the user and the write that followed were two different things the model
produced, and they could disagree; - a write that was going to fail (a name already taken, a limit) failed only after the user had
said yes, so the user saw an error for something the assistant had offered; - after a confirmation note appeared at the end of the model’s own earlier replies, the model
imitated it and told the user a card still pending had been confirmed.
Decision
1. The only write path is a proposal confirmed by a person
The model’s write tool records a proposal and changes nothing. Applying it is a separate request
that only the person makes (a tap on a card). There is no flag that lets the model write directly.
2. A proposal carries fully resolved commands and a summary written by code
The stored proposal holds the commands exactly as they will run (ids, not names) and a summary of
the change that code produced from them. The person confirms the summary; the server applies the
commands. The model’s prose never reaches either.
3. The server proves a proposal before showing it
Before a card exists, the server runs the real write through the real use case inside a
transaction that is always rolled back. A validation error, a conflict or a constraint reaches
the model as a refusal it can correct; it never reaches the person at confirm. A write therefore
has no side effect outside the database, or that side effect is deferred to the real apply.
4. Confirm is idempotent, owner-only, and refuses stale proposals
Confirm locks the proposal, applies it once, and moves its status (pending → confirmed, cancelled
or expired; status is the source of truth, core 0001-status-as-source-of-truth). Only its owner
may confirm. If something it names has changed hands or gone, confirm refuses and the proposal
stays pending. Proposals expire, and each ends only by the person or by expiry: a new proposal
never cancels another.
5. The set of operations is an allowlist in code
Each operation the model can propose is a class (plan, summary, apply). Whatever has no class
(authentication, account, billing, legal, administration) cannot be reached. Adding an operation
is a scope decision as much as code.
6. The model learns the outcome from the server, placed where it cannot imitate it
A proposal’s status reaches the model as a note at the start of the person’s next message, never
on the model’s own reply, and code strips anything shaped like such a note from the model’s
answers.
7. Deleting is the last operation to add, and only in a form that keeps totals whole
Prefer operations that can be undone by another operation. Where a delete is needed, add it as a
conversion that keeps what the person sees elsewhere unchanged, not as a bare delete.
Consequences
- The promise “nothing changes without your confirmation” is true by construction, so it can be
stated in terms of use as a guarantee. - A new operation ships backend-only when the card is generic: the summary is data (operation id,
lines, labelled facts), and clients render unknown kinds bare. - Accepted: each proposal costs one rolled-back write, and confirm runs it again.
- Accepted: bulk changes have no undo yet beyond another proposal.
Amendment — 2026-11-11: the summary is readable by the person who confirms it
A summary written by code from the resolved command can still be unreadable: the agents platform’s clinic agent
cancelled appointments by an id from the clinic’s system, and the card read “Consulta: f35d64c9”. The model then asked
in prose first (“shall I cancel this one?”) and the person confirmed twice — or, calling at once, confirmed an id they
could not read (agents 0020-actions-end-a-conversation-and-land-in-the-inbox, c_cancel 0/3).
- A value that is a code is shown with what it refers to, in the person’s words (“the appointment with Dr. Ana,
Tuesday 17/11 at 14:30”). The command keeps the code. - That description is the model’s words, like every value the model chose; the summary’s structure and every figure
stay code’s (§2). It goes on the card only, never into what is sent or stored as the command. - When code can resolve the code to its record itself, prefer that to the model’s description.
Related
- 0019-llm-features-prompts-shape-code-enforces — why confirmation is code, not a prompt rule
- 0023-model-facing-data-is-a-catalog — the read side; operations sit in the same two-level index
- Expenses 0027-assistant-writes-are-proposals-the-user-confirms — the worked example
(propose_changes,WriteTrial,ChangeSummary,chat_proposals)