Destructive-operation flagging

[apgiorgi]

Motivation

In agent mode there are no interactive prompts (#12). That removes the human's natural safety net. We need an explicit, machine-recognizable mechanism for destructive operations so:

• agents can detect "this command needs explicit confirmation" before running it
• humans get a clear safeguard
• the contract is consistent across the whole CLI

Spec

Annotation

• Every command in the catalog (Machine-readable command catalog #15) carries destructive: true|false
• Destructive examples: deleting a budget, modifying a customer-level setting, anything irreversible

Confirmation mechanism

• Default: destructive commands refuse to run without one of:
  • --yes / --confirm flag
  • DCI_CONFIRM_DESTRUCTIVE=1 env var (session-scoped opt-in)
  • Interactive y/N prompt — only when stdin is a TTY and not in agent mode
• Without confirmation: exit code 30 (validation error) and a structured error like:

  { "error": { "code": "DESTRUCTIVE_REQUIRES_CONFIRMATION", "hint": "Re-run with --yes" } }

Dry-run

• Every destructive command supports --dry-run that emits what would happen, without doing it
• Encouraged path for agents to preview before committing

Reporting

• Destructive operations always print a structured "action summary" on success (what was changed, identifiers, before/after where feasible)

References

• Grafana gcx CLI — identifies and highlights destructive operations requiring explicit confirmation, reducing agent mistakes: https://grafana.com/blog/get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool/
• axi.md — principle 6 (no interactive prompts, structured errors): https://axi.md/

Dependencies

• Blocked by Stable exit codes, structured errors, idempotency #12 (structured error envelope) and Machine-readable command catalog #15 (catalog annotation)

Open questions

• Granularity: is destructive: true enough, or do we need severity tiers (e.g. reversible-soft-delete vs. permanent)?
• Should --dry-run be mandatory on every destructive command, or opt-in per command?

Acceptance criteria

• Every destructive command annotated in the catalog
• --yes / DCI_CONFIRM_DESTRUCTIVE gating enforced uniformly
• --dry-run supported on every destructive command
• Structured action-summary output on success