feat(mcp): add separate structured send preflight and explanations #357

Problem

MCP callers currently perform dry-run through the non-idempotent send_message tool, and even dry_run=true requires the destination's send capability. The v1.3 CLI also offers human-readable delivery explanations, but there is no stable structured MCP explanation contract.

Proposed scope

Design a separate send-validation/explanation tool and a least-privilege preflight capability. Reuse the CLI's target, route, message-budget and storage/ownership checks rather than duplicating them or parsing its human-readable explanation text.

The tool name, policy schema evolution and result schema require design review before implementation.

Acceptance criteria

• Define explicit authorization for validation-only use. Existing v1 policies must not silently acquire new capabilities; current send and wake authorization remains unchanged.
• Validate normal message input and the exact operator-approved destination/agent/home route. Do not reinterpret a model-supplied URI or alias as authority for a different route.
• Return a versioned structured explanation with a field allowlist: checked facts, limitations, refusal/unknown reasons and operator actions. Do not expose raw paths, message contents, credentials or native transcripts.
• A preflight must not enqueue, post, wake a model, reserve a wake budget, create handoff intent/authority or modify policy/presets.
• Account explicitly for existing dry-run probes and local/network process effects; do not claim inspection is purely metadata-only or approve read-only annotations without verifying actual behavior.
• Explain mode is text-only in the current CLI. Introduce a shared structured representation or equivalent reviewed contract; do not scrape text or silently change public CLI JSON.
• Passing is a point-in-time validation, not route reservation, effective-storage attestation, permission approval, later-send safety, consumption or ACK.
• Unsupported device/handoff/explanation combinations fail explicitly; adding this tool does not expand their support.
• Tests prove zero native submission/model/wake/budget effects for success, refusal, cancellation and timeout; preserve payload bounds, ownership guards and no automatic resend.
• Installed stdio and schema tests cover validation-only policy, old-policy compatibility, disclosure limits and separate host approvals.

Related work

Depends on the MCP destination/capability contract. Reuses ordinary CLI explanation work #323 without reopening its completed scope. Keep native storage/generation limitations #268/#180 separate.

Source: v1.3.3 MCP adapter and CLI reference.

Planning

Proposed v1.4.0 candidate, priority P2; no committed release date. Registration does not authorize implementation, live sends, merge, release or operations.

Tracking dependencies

Depends on #356 for destination/capability reporting and policy evolution. Coordinate safe explanation/error fields with #358. Preset integration #359 is a separate fourth v1.4.0 candidate slice, authorized by the owner on 2026-11-02; it is not part of this preflight PR. Handoff #360 remains excluded.