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. Installing a named package (npm install express, pip install requests) matches High risk, while installing what the project already declares (npm ci, pip install -r requirements.txt) is Low, 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. Since 0.5.1 it rates every command of a line — chained, piped, or wrapped in sudo, env, bash -c, ssh host, $(…) or find -exec — so cd build && rm -rf /srv is blocked on its second command. It catches known risky forms, including eval, base64-to-shell pipelines, and certain command substitutions, but does not prove an arbitrary command is safe. Guard is not a sandbox: blocking applies only where you wire guard into execution.