Design: mcpx write policy — one gate for writes (ask/allow/deny, argument rules, unknown-outcome ledger) #2126

Design (repo design architect, pass 12, 2026-10-29): one policy evaluator in a new internal/policy package, evaluated inside resolveAndGuard after it gains the call's arguments, in a fixed order — hidden-tool check (existing) → unknown-write ledger check → argument rules → write mode → confirmDestructive floor. The three origin issues below are three separately-filed slices of one design; they share one seam, one write classification, and one evaluator (#1986's own body: "Design the two together… the evaluator is one function so the two can never disagree"). This design adopts them as its phases instead of filing parallel implementation issues.

Design doc: files/designs/code-mcpx-write-policy.md in the keep-the-four-repos-healthy goal workspace (problem, current-state audit against origin/main 73ba3a96, proposal, alternatives, risks, open questions).

Why now / grounding

• The only write gate today is elicit.confirmDestructive (default off, internal/settings/consumer.go:65; internal/daemon/consumer.go:382) — a boolean aimed at one annotation. It never shows the arguments, because resolveAndGuard (internal/daemon/registry.go:868) and confirmDestructive are both argument-blind even though all three call paths (Call registry.go:852, CallReporting input_required.go:75, CallAsk routes_proto.go:302) hold args in hand.
• The validator argument rules were blocked on (ex-nix#254) now exists: internal/schemaval, landed by mcpx: Phase 1 of #1481 — schemaval core: a real JSON Schema 2020-12 validator + dialect policy (no call-path changes) #1482 and wired in by mcpx: Phase 2 of #1481 — validate tool arguments at CallTool (enforce, -32602) + structuredContent against outputSchema (warn-only) #1483 (internal/mcpclient/schemacheck.go). Tool-pattern keys are config.ToolPatterns; the classification precedent is destructiveHint (internal/daemon/consumer.go:439-444, spec defaults — inverted, it is the write classification).
• No unknown-outcome recording exists anywhere in pkgs/mcpx/internal (grep-verified): a write lost after dispatch leaves no trace and the next write proceeds.

Decisions recorded in the design doc

1. Classification shared and annotation-derived (write iff readOnlyHint is not true); annotation dishonesty stays owned by mcpx: smaller conformance gaps -- user identity, annotation trust, rate limits, cursors, URI encoding, prompt validation, restart, invalidation #1957 — argument rules are the annotation-independent control.
2. Modes are settings (policy.write, daemon scope, ask default per mcpx: a write policy -- ask, allow, deny -- with the exact call shown when asking #1979's acceptance; per-server writePolicy override); rules are per-server config (argumentRules, kept over a folded policy block — mcpx: argument rules -- allow a call by its arguments, per tool and per argument (JSON Schema; depends on #254) #1986 open question 1 resolved); the evaluator is the shared part.
3. ask renders the exact call (tool + canonical arguments) through the existing broker confirmation; elicit.confirmDestructive is subsumed as a floor (destructive asks even under allow — decision 0002's "no level skips a consent gate").
4. Rule refusals render natively per surface (daemon 400 HiddenTool-style naming argument path/value/constraint/rule origin; MCP pass-through isError: true result) — mcpx: argument rules -- allow a call by its arguments, per tool and per argument (JSON Schema; depends on #254) #1986 open question 3 resolved by the hidden-tool precedent. Rules only tighten (allOf across pool/server/layered files); bad schema or non-RE2 pattern is a load-time config error; dead rules warn at load and on catalog change.
5. Unknown-outcome ledger is a versioned state-dir file (server, tool, args SHA-256 — never the arguments — time, surface), written atomically, persisted across restarts, never auto-cleared; "ambiguous" is conservative (post-dispatch marker only once request bytes were written).
6. The policy is an operator consent gate, not the autonomy dial (decision 0002, pkgs/mcpx/docs/decisions/0002-autonomy-dial.md: confirmDestructive classed "not the dial"); neither clamps the other, and Phase 1 documents the interaction.

Phased breakdown (each independently landable)

• Phase 1 — the gate: mcpx: a write policy -- ask, allow, deny -- with the exact call shown when asking #1979 (sub-issue). Plumb args into resolveAndGuard; internal/policy + classification; policy.write + per-server writePolicy; exact-call ask; deny; confirmDestructive subsumption; dial documentation. Leaves ledger/rules steps as no-op hooks. Acceptance: mcpx: a write policy -- ask, allow, deny -- with the exact call shown when asking #1979's own checklist.
• Phase 2 — argument rules: mcpx: argument rules -- allow a call by its arguments, per tool and per argument (JSON Schema; depends on #254) #1986 (sub-issue, gated on Phase 1, status/blocked). argumentRules config + schemaval compilation, evaluation before the mode step, per-surface refusals, dead-rule warnings. Acceptance: mcpx: argument rules -- allow a call by its arguments, per tool and per argument (JSON Schema; depends on #254) #1986's own checklist including its four worked examples. Triage first confirms mcpx: JSON Schema validation of tool inputs/outputs and elicitation schemas (7 conformance rows) #1951's in-review reconciliation does not reopen the validator question.
• Phase 3 — unknown-outcome ledger: mcpx: block further writes after a write whose outcome is unknown #1977 (sub-issue, gated on Phase 1, status/blocked). Post-dispatch error marker, state-dir ledger, guard step, mcpx writes / mcpx writes clear <server> + /v1 clear route, restart-persistence tests. Acceptance: mcpx: block further writes after a write whose outcome is unknown #1977's own checklist. On landing, post evidence on tracker mcpx: adopt what is useful from codex-connectors-mcp #1984 for its mcpx: a write policy -- ask, allow, deny -- with the exact call shown when asking #1979/mcpx: block further writes after a write whose outcome is unknown #1977 checkboxes.

Not in this design (open questions in the doc)

Schema advertising of rules (allOf in mcpx types / tools/list); pinning/set (#1933's slice); redaction of secret-shaped values in ask renderings; per-principal policy (waits on #1968/#1972); ledger visibility in mcpx status.

Related: #1984 (tracker that lists #1979/#1977), #1481 (validation — dependency, not a slice), #1957 (annotation trust), #1634 (landed; its client recovery sits below this design's recording point).

{"kind":"design","by":"repo-design-architect-code","pass":12,"date":"2026-10-29","design_doc":"files/designs/code-mcpx-write-policy.md","phases":{"1":1979,"2":1986,"3":1977},"origins":{"1979":"dezren39/nix#340","1986":"dezren39/nix#355","1977":"dezren39/nix#339"}}