Five-stage flow

Magellan runs in one of five operator-set stages. The active stage is visible in the chat header; switching swaps the system prompt and adjusts model temperature.

Stage	What it does
Explain	Read-only. Tells you what the attached output means.
Suggest	Recommends the next diagnostic step as prose — no specific commands.
Draft	Writes the specific command, query, or runbook entry you can paste.
Review	Critiques a plan you supply, edits drafts you wrote.
Execute	Server-assist tools become callable. Operator still confirms each step.

Three-layer stage gating

Execute is the only stage where Magellan can call ShellYard’s server-assist tools. Enforcement is defense in depth — a bug in any one layer can’t bypass the others:

1. Protocol layer (internal/ai/assistant.go) — tool definitions are only attached to the model’s API call when stage == Execute. The model literally cannot emit a tool_call for a tool it isn’t shown.
2. Frontend executor (Magellan.tsx) — refuses run_command and collect_mac_table outside Execute even if a tool_call somehow lands. Legacy ```watch / ```batch / ```collect-mac markdown-block parsers are gated on Execute too.
3. Backend binding layer (app.go) — AIRunCommandOnFolder / AIRunCommandOnDevices / AICollectMACTable check the last-recorded Magellan stage and refuse with requires the Execute stage if not Execute.

The user-clicked Bulk Command tool is unaffected — those checks only fire on Magellan-initiated calls.

Server-assist tools (Execute stage only)

When Execute is active, Magellan can call:

• list_folders, list_connections — read the connection tree
• run_command — single host or fleet; returns structured output
• collect_mac_table — auto-CSV-export across saved switches
• subnet_calculate — CIDR math
• dns_lookup, mac_lookup — resolver / OUI

Operator control

Magellan never executes autonomously. Every Execute-stage tool call surfaces a confirm prompt before it runs. The operator approves or rejects each step.