Command Guard

suv guard assesses a command before execution and returns an exit code your shell or CI script can act on.

Usage

suv guard 'git status' --verbose
suv guard 'npm install example-package'
suv guard --block-at critical 'npm install example-package'

Pass the full command line as a single quoted argument. Guard only assesses the text; it does not execute it. Use single quotes for literal command text, particularly text containing shell substitutions.

Exit 0 means the assessment is below the threshold or no risk pattern matched. Exit 2 means blocked, with the reason printed to stderr. Invalid CLI arguments also use exit code 2, so read the diagnostic when troubleshooting.

Use in a Script or CI

# Run the known command only if its check succeeds
suv guard 'npm ci' && npm ci

Guard uses the same risk rules as the dashboard and reports, including custom patterns and ignore patterns. Package installs can match High risk, so choose your threshold deliberately. For checks over commands already recorded, use suv agent report --fail-on.

Interactive Zsh Blocking

To check commands when you press Enter, add this widget to ~/.zshrc and reload the shell. The widget checks the input before accepting it; a preexec hook is too late to cancel execution.

suv-guard-accept-line() {
  if [[ -n "$BUFFER" ]] && ! suv guard "$BUFFER"; then
    zle -M "Command blocked by suv guard"
    return 1
  fi
  zle .accept-line
}
zle -N accept-line suv-guard-accept-line

The standard shell integration does not install this widget automatically. If you already customize accept-line, integrate the check into that widget.

Project Risk Rules

A .suvadu.toml in the current directory or nearest ancestor can supply project-specific risk patterns:

[[agent.risk_extra_patterns]]
pattern = '^internal-deploy\s+production\b'
level = "critical"
description = "Production deployment needs review"

See project configuration for precedence and merge behavior. The blocking threshold is selected with --block-at, not a config field.

Risk assessment is pattern-based. It catches known risky forms, including eval, base64-to-shell pipelines, and certain command substitutions, but does not prove an arbitrary command is safe. Blocking applies only where you wire guard into execution.