Approvals & ChangePlans

Approvals and ChangePlans are the safety path for actions that need user review. They let Anyy pause before a risky tool call or state-changing plan, persist the pending decision, and replay the approved action through a trusted route.

When Approval Is Required

Approval depends on the effective tool descriptor and tool-specific behavior:

Case	Behavior
Direct reads	Usually run without approval.
Audited low-risk writes	Run and write audit records when the descriptor requires it.
Connector mutations	Return needs_approval before sending or mutating external records.
Desktop control	computer_use asks for capture grants and approval for mutating actions.
Host/config/root-capable actions	Use confirmation or ChangePlan policy before execution.
Force-required actions	Offer only force_approve and deny.

Toolsets only control visibility. A visible tool still keeps its own risk, approval policy, execution policy, output budget, timeout, and audit category.

ChangePlan Lifecycle

Created

A tool result with status change_plan_created creates a pending ChangePlan and an approval prompt. The plan stores:

Field	Meaning
title	Human-readable plan name.
risk	Risk class such as config-high, dangerous, or force-required.
execution_policy	change_plan or force_change_plan.
preconditions	Conditions that should hold before execution.
current_state	Structured snapshot used for review.
proposed_changes	Intended mutations.
commands	Commands or operations to execute.
validation_steps	Checks to run after execution.
rollback_steps / rollback_mode	Recovery instructions when available.
expected_impact	User-facing impact summary.
plan_hash	Hash checked before approved execution.

Pending ChangePlans default to a 10 minute expiry.

Approved

Approving a prompt marks the ChangePlan approved. Force approval marks it force_approved and writes a force-path audit event.

Anyy checks that the approval decision was actually offered by the prompt. If only force_approve was offered, a plain approve decision is upgraded to force_approve in the trusted decision path.

Executed

Before execution, Anyy verifies that:

Check	Purpose
Status	The plan is approved or force-approved as required.
Expiry	Non-force plans have not expired.
Plan hash	The approved plan still matches the plan being executed.
Policy	force_change_plan plans are force-approved before execution.

Execution can mark a plan executing, verified, failed, or rolled_back.

Approval Surfaces

Approval routes are represented as tui, cli, weixin, or dashboard. Available routes depend on the session surface and runtime path that created the approval.

The approval prompt includes:

Field	Meaning
kind	tool_call or change_plan.
session_id / turn_id	Scope for replay and display.
tool_call_id	Original tool call when applicable.
change_plan_id	Plan id for ChangePlan approvals.
title, summary, risk	Review text.
options	Allowed decisions.
expires_at	Approval expiry.

Scheduled Approvals

Cron-created ChangePlans can carry scheduled metadata such as cron_job_id, cron_run_id, origin session, channel binding, role, actor, and workspace. The approval summary includes the scheduled due time when that context is present.

Audit Trail

Approvals and ChangePlans write audit events:

Event	Category
Prompt decision	approval
Force approval	force_path
Plan created/updated/approved/executing/verified/failed/rolled back	change_plan

Tool replay also records approval correlation metadata so an audit trail can tie the approved execution back to the approval id, tool call id, and ChangePlan id.

Dashboard Approvals Page

The dashboard's Approvals page lists open and decided approvals through the approval.list RPC. It can approve or deny open prompts from the browser session.

The dashboard page is intentionally scoped to approval decisions. Detailed tool logs, plan internals, and session transcripts remain in the relevant runtime, audit, or session views.