MCP Mode Policy & Confirmation Rules

Defines how the three interaction modes (Ask, Plan, Execute) govern tool availability, mutation safety, and confirmation flows in the AMOF MCP server.

Mode Definitions

Ask Mode

Property	Value
Purpose	Read-only inspection, explanation, comparison, suggestion
Mutations	Forbidden. All write operations return an error with guidance to switch mode.
CLI equivalent	Running amof status, amof release status, amof ticket list

Plan Mode

Property	Value
Purpose	Gather state, propose multi-step plans, preview impact, no actual mutations
Mutations	Forbidden (actual). All mutating tools run in dry_run=True / preview mode.
CLI equivalent	Running commands with --dry-run flag

Execute Mode

Property	Value
Purpose	Perform actual mutations with appropriate confirmation gates
Mutations	Allowed. Confirmation required for dangerous-write tools.
CLI equivalent	Running commands without --dry-run, with -y or --force after user confirms

Mode Lifecycle

1. Explicit per-tool parameter    (highest priority)
2. Session-level mode state       (set by amof_set_mode tool)
3. Default mode                   (ask)

ask ──────► plan ──────► execute
 ▲            │              │
 └────────────┴──────────────┘
       (any direction allowed)

Confirmation Protocol

Confirmation Types

Type	UX Pattern	When Used
none	Tool executes immediately	read-only and safe-write tools
simple	"Proceed with X? [Yes/No]"	Moderate-risk: push, archive, install
preview-then-confirm	Tool returns preview, then asks "Execute?"	High-risk: release bump, promote
type-to-confirm	User types resource name to confirm	Critical: discard, spin destroy

Two-Phase Confirmation Flow

Phase 1: Tool call → returns confirmation request (no mutation)
Phase 2: Client confirms → tool executes the mutation

Each confirmation request generates a UUID token that is single-use, expires after 5 minutes, and ties to the exact preview state.

Classification Matrix

#	Tool	Safety	Ask	Plan	Execute	Confirm
1	amof_list_ecosystems	read-only	yes	yes	yes	none
2	amof_get_server_status	read-only	yes	yes	yes	none
8	amof_install_ecosystem	dangerous	explain	dry-run	execute	simple
10	amof_push_ecosystem	dangerous	explain	dry-run	execute	simple
11	amof_spin_deploy	dangerous	explain	dry-run	execute	preview
12	amof_spin_destroy	dangerous	explain	dry-run	execute	type
20	amof_discard_ecosystem	dangerous	explain	dry-run	execute	type
26	amof_release_bump	dangerous	explain	dry-run	execute	preview
27	amof_release_promote	dangerous	explain	dry-run	execute	preview

Same Intent, Three Modes

"Deploy this ecosystem"

Ask mode: Returns a description of what would happen, current state, and guidance to switch mode.

Plan mode: Runs dry-run, returns preview with provisioner, script, estimated duration, and execute hint.

Execute mode: After confirmation, queues the deployment and returns run_id for tracking.

"Discard this ecosystem"

Ask mode: Explains the irreversible action, lists what would be deleted, suggests archiving first.

Plan mode: Returns preview of branches and directories that would be deleted.

Execute mode: Type-to-confirm -- user must type the ecosystem name to proceed.