A preview is one of the most valuable interactions an agent can offer.
It lets a person see what the system believes it should do before that belief becomes an effect. It can expose an unexpected scope, a stale assumption, a missing approval, or a harmless misunderstanding while the work is still easy to correct.
But a preview becomes dangerous when it is treated as a promise.
A sentence such as “I will make these changes” can hide several important facts: whether the agent has actually checked the current state, what it observed, whether the preview itself performed any bounded external activity, whether the proposed outcome is still current, and whether the eventual action will be exactly the one the person reviewed.
The useful mental model is:
A preview is a proposal anchored to an observed state, not proof that the future effect will happen or remain appropriate.
HashiCorp's Terraform plan documentation provides a helpful analogy. A plan compares current configuration with observed state and proposes changes; the plan itself does not apply them. The documentation also warns that the target environment can change before a later application, which is why a final plan needs review. Agent products inherit the same gap between “what the system found then” and “what remains appropriate now.”
Separate four things that interfaces often collapse
Agent previews are clearer when they distinguish four states:
- State: Observation — What it means: The agent read or checked a source, environment, or task artifact — What it must not imply: That the observation is permanent, complete, or automatically current
- State: Proposal — What it means: The agent describes a possible effect based on its current understanding — What it must not imply: That the effect has happened or is still authorized
- State: Confirmation — What it means: A person or policy accepts a defined proposal under stated conditions — What it must not imply: An open-ended permission for future variations
- State: Execution — What it means: The system attempts the approved effect and records the outcome — What it must not imply: That a previewed outcome succeeded without reconciliation
The boundary matters because each state can change before the next one begins. A task may observe a current condition, generate a reasonable proposal, and then wait. During that wait, the relevant data, task scope, authority, or target state can change. If the system later executes without rechecking, it may carry out something different from what the user thought they approved.
A good preview does not hide that uncertainty. It makes the uncertainty reviewable.
The Effect Preview Contract
The Effect Preview Contract is a proposed record for an agent's pre-action view. It applies to any workflow where a result is more consequential than an ordinary draft: changing a shared artifact, submitting a request, modifying a record, running a workflow, or transferring data to an approved destination.
- Contract element: Objective and intended effect — What it records: The user goal and the exact high-level outcome the agent proposes — Why it matters: Ensures the preview is evaluated against the task rather than against a generic “looks reasonable” standard
- Contract element: Scope and exclusions — What it records: Which work surface, sources, records, or artifacts are included and what is deliberately untouched — Why it matters: Makes hidden expansion visible before it becomes an accidental side effect
- Contract element: Observed state and timestamp — What it records: The relevant current state, source posture, or dependency snapshot used to form the proposal — Why it matters: Gives reviewers a reason to ask whether the preview is still current
- Contract element: Assumptions and dependencies — What it records: What must remain true for the proposal to be valid — Why it matters: Separates verified facts from conditional reasoning
- Contract element: Preview-time activity — What it records: What the preview did and did not do while being prepared, such as read-only observation, simulation, or no external interaction — Why it matters: Prevents the label “preview” from obscuring activity that matters to the user
- Contract element: Validation and known limits — What it records: What was checked, what remains unknown, and what the preview cannot guarantee — Why it matters: Stops an attractive summary from being mistaken for complete verification
- Contract element: Expiry and execution binding — What it records: When the preview must be rechecked, and what must match before a later action can proceed — Why it matters: Prevents an old proposal from becoming standing permission for a changed effect
The contract does not require a long form for every low-impact task. A simple preview may render these fields in one concise card. The key is that the product stores enough state to answer the question that matters: “What exactly did we see, propose, and agree to, and is it still the same action now?”
A dry run needs a declared effect boundary
“Dry run” is a useful phrase only when users know what it means in that particular system.
Kubernetes documentation illustrates one familiar convention: a dry run can show the object that would be submitted without submitting it. Terraform uses planning to propose infrastructure changes before applying them. These conventions are valuable because the interface separates a representation of change from the change itself.
But a preview may still need to read state, resolve a dependency, query a service, or invoke a bounded simulation. Terraform planning reads current remote state and may query configured data sources, while terraform plan does not apply its proposed resource changes. The general lesson for agent products is not to assume that every preview is a complete absence of external observation. It is to declare the effect boundary.
For a preview, state in plain language:
- what information was read or inspected;
- whether the system contacted any external service;
- whether the system only produced a local representation or also reserved, queued, or otherwise changed a temporary state;
- which actions are explicitly excluded until a later confirmation; and
- whether the target was rechecked immediately before the preview was shown.
This is better for users and for builders. A preview that carries a clear activity label can be reviewed accurately. A vague “nothing happened” claim can become misleading if the preview had to access or alter a task-relevant state.
Confirmation should bind to the proposal, not to a mood
A confirmation button does not automatically produce informed approval. If the button means “continue with whatever the agent thinks is best,” it is simply a broad authorization wrapped in a reassuring interface. OpenAI's prompt-injection guidance presents confirmation before consequential action as one layer in a broader safety design; the confirmation still needs a specific, current proposal to be meaningful.
A useful confirmation points to a stable proposal. It should identify:
- the intended effect and scope;
- the known limitations or uncertainties;
- the important input or target snapshot;
- the data class involved, if any data could move across a boundary;
- the expiration or revalidation condition; and
- what happens if the state no longer matches when execution begins.
The user does not need to inspect every internal detail. They do need to know the actual commitment they are making. If a changed condition would alter the proposal materially, the system should render a new preview or request a renewed confirmation rather than reusing the old one.
This is especially important for long-running agents. A confirmation can arrive after the agent has compacted its context, been interrupted, resumed on a newer source, or had its plan revised. The contract gives the resuming system a durable record that says: this is what was approved, under these assumptions, for this effect.
Previews expose the quality of agent reasoning
A well-designed preview is not merely a consent screen. It is a diagnostic tool.
If the agent cannot state the intended effect, it may not understand the task. If it cannot name what it inspected, it may be operating from stale or fabricated context. If it cannot explain what remains unknown, it may be overconfident. If it cannot say what would invalidate the preview, it may be treating time and changing state as irrelevant.
The preview therefore becomes a compact test for agent quality:
- Preview question: What will change? — What a weak answer reveals: Vague intent or hidden scope — What a strong answer enables: Review against the user's actual goal
- Preview question: Why now? — What a weak answer reveals: No current evidence or unexamined assumption — What a strong answer enables: A check on timing, freshness, and task relevance
- Preview question: What did the agent inspect? — What a weak answer reveals: Missing provenance and unbounded context — What a strong answer enables: A way to verify the proposal's basis
- Preview question: What is not included? — What a weak answer reveals: Silent scope expansion risk — What a strong answer enables: A clear boundary for review
- Preview question: What could make this stale? — What a weak answer reveals: No invalidation model — What a strong answer enables: Safe recheck before execution
- Preview question: What has happened already? — What a weak answer reveals: Confusion between proposal and effect — What a strong answer enables: Truthful lifecycle status
The effect preview is thus not an ornamental explanation. It is a control surface for task scope, truthfulness, and human judgment.
Make revalidation proportional
Not every preview needs the same recheck. The duration and depth should follow the volatility and consequence of the task.
A low-impact draft proposal may remain useful even if it is hours old. A preview that relies on quickly changing data, a shared mutable record, or a narrow approval boundary may need revalidation immediately before execution.
A proportionate policy can distinguish:
- Condition: Inputs and target state are stable, and the effect is reversible — Appropriate response: Reuse the preview within a declared window
- Condition: Inputs remain stable but the task waited through a handoff or pause — Appropriate response: Recheck the task scope and approval binding before execution
- Condition: Relevant source or target state changed — Appropriate response: Regenerate or materially update the preview
- Condition: Authority or confirmation conditions changed — Appropriate response: Hold and request a new decision
- Condition: The earlier preview cannot establish what happened during its own preparation — Appropriate response: Mark the preview limited and require reconciliation before action
The goal is not to force confirmation fatigue. It is to make the recheck depend on the real reasons a proposal could become wrong.
Measure preview integrity, not click-through rate
A preview flow can be polished and still unreliable. Measure whether it preserves the relationship between proposal, approval, and effect.
Useful metrics include:
- Preview-to-effect match rate: How often does the applied outcome materially match the reviewed proposal?
- Staleness catch rate: How often does revalidation discover a changed condition before an action proceeds?
- Scope-discovery rate: How often do users find an unwanted inclusion or omission during preview?
- Uncertainty disclosure rate: How often does the preview correctly state what it did not verify?
- Confirmation relevance: How often do users approve a proposal that later needs a materially different effect?
- Preview-side-effect transparency: How often does the record accurately state any bounded activity performed while preparing the preview?
These metrics encourage a system that earns trust by making uncertainty visible early, not by making a confirmation screen effortless to dismiss.
A practical adoption path
- Identify one agent workflow that currently moves directly from reasoning to a consequential effect.
- Add a preview state that produces a durable proposal before the effect.
- Write the seven contract elements in product language users can understand.
- Label exactly what the preview did and did not do while it was generated.
- Bind confirmation to the proposal's scope, observed state, and expiry condition.
- Recheck the assumptions when the task resumes or the target becomes volatile.
- Add examples where a state change, altered authority, or new evidence forces a refreshed preview.
- Use user feedback to remove unnecessary detail, but do not remove the facts that distinguish a proposal from execution.
The goal is simple: let an agent show its work before it acts, while remaining honest that a proposed future is not the same as a completed one.
What we are learning building Virillio Code
Virillio Code is in development. High-level work around durable tasks, review boundaries, and scoped tools suggests that a preview should be treated as a real task artifact with a source state, a declared scope, and an expiry rule. The Effect Preview Contract is a proposed educational framework, not a description of a released product capability.
Sources and further reading
- terraform plan command reference — HashiCorp — A plan is a proposal formed from observed state that does not apply changes by itself and may become stale before a later application.
- Terraform data sources — HashiCorp — Terraform may read configured data sources during planning when their inputs are known, even though the plan does not apply proposed resource changes.
- kubectl usage conventions — Kubernetes — A dry-run convention previews a proposed object without submitting it.
- Understanding prompt injections — OpenAI — Confirmations before consequential actions are one layer of agent safety controls.
Editorial disclosure
This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.