Destructive Action Guard

Destructive Action Guard is a cross-platform Codex guardrail for destructive shell, filesystem, Git, and mirror commands.

It classifies risky commands before execution, prefers deterministic logic over prompt-only judgment, and fails closed when wrappers, wildcards, or target sets cannot be resolved safely.

The repository ships three things together:

• Python helper CLIs: doctor, print-snippets, and evaluate-command
• A Codex plugin manifest and bundled plugin assets
• Two skills: destructive-action-guard and the compatibility shim safe-delete-review

What it does

• Treats command-like prefixes such as sudo, env, time, cmd.exe, powershell.exe, and bash -c as commands, not casual natural language.
• Classifies risky destructive families such as rm, del, Remove-Item, git clean, git reset --hard, robocopy /MIR, and rsync --delete.
• Resolves exact filesystem targets when wildcard or relative paths can be expanded deterministically.
• Requires preview-first workflows for command families that support them.
• Marks targets that fall outside the reviewed project root.
• Validates either a source checkout or an installed package bundle with doctor.

What it refuses

• Destructive natural-language requests that do not resolve to an exact reviewed target set
• Partial or unresolved wildcard expansion
• Wrapper chains that are too deep to classify safely
• git clean, robocopy, and rsync delete flows that skip their preview step
• Commands that look destructive but cannot be normalized with confidence

Supported command families

• Filesystem delete: rm, del, erase, rmdir, rd, Remove-Item
• Git cleanup: git clean
• Git hard reset: git reset --hard
• Mirror and sync deletion: robocopy /MIR, /PURGE, /MOVE, /MOV, and rsync --delete
• Common wrappers: sudo, env, time, cmd.exe /c, powershell -Command, pwsh -Command, bash -c, sh -c, zsh -c

Install

This repository is ready to build wheels and source distributions for PyPI, but if you are working from the repo today, install from a checkout or a locally built wheel.

From a checkout

python -m pip install -e .
doctor --plugin-root . --json

Build a distributable wheel and sdist

python -m pip install build
python -m build

Install the built wheel

python -m pip install dist/destructive_action_guard-0.1.0-py3-none-any.whl

After installation, these public helpers are available:

• doctor
• print-snippets
• evaluate-command

Repo-local wrappers are also available under scripts/ for working directly from a checkout.

CLI contract

evaluate-command

evaluate-command accepts a command or request and returns one of five classification outcomes:

• safe
• preview-only
• destructive
• ambiguous
• forbidden

Exit codes are part of the public contract:

• 0: safe or preview-only
• 10: destructive
• 11: ambiguous
• 12: forbidden

argparse usage errors remain on their normal non-zero path and are not part of that mapping.

JSON output is designed to stay stable where possible. Important fields include:

• classification
• normalized_family
• preview_strategy
• exact_targets
• unresolved_targets
• outside_project_targets
• approval

print-snippets

print-snippets prints recommended Codex config and rules snippets without editing the user environment.

doctor

doctor validates either:

• a source checkout with the repo-root plugin layout, or
• an installed package bundle with the plugin assets shipped inside the wheel

It does not rewrite Codex config or rules files.

Examples

Classify a destructive Git cleanup:

evaluate-command --command "git clean -fdx" --json

Classify a preview-only cleanup:

evaluate-command --command "git clean -nfdx" --json

Classify a wrapper-hidden destructive command:

evaluate-command --command "sudo rm -rf build" --cwd . --project-root . --json

Classify a Windows PowerShell wrapper:

evaluate-command --command "powershell -NoProfile -Command \"Remove-Item temp.txt\"" --platform windows --json

Expand a deterministic wildcard request:

evaluate-command --command "Remove *.log recursively" --cwd . --json

Print recommended snippets:

print-snippets --platform windows --section all

Inspect a source checkout or installed bundle:

doctor --plugin-root . --json

Example JSON for a preview-required command:

{
  "classification": "ambiguous",
  "normalized_family": "git_clean",
  "preview_strategy": {
    "mode": "preview",
    "commands": ["git clean -ndx"],
    "notes": ["Run preview mode first and approve only the reviewed target set."]
  },
  "requires_approval": false,
  "risk_level": "critical",
  "refusal_reason": "git clean requires preview output before destructive approval."
}

Non-goals

This project is not:

• a shell executor
• a general-purpose shell parser for every dialect and edge case
• a replacement for backups, snapshots, or version control
• a tool that silently edits global Codex safety configuration

Skills

• skills/destructive-action-guard/SKILL.md
• skills/safe-delete-review/SKILL.md

Docs

• docs/INSTALL.md
• docs/EXAMPLES.md
• docs/DESIGN.md
• docs/THREAT_MODEL.md
• docs/VERSIONING.md
• REPO_LAUNCH_CHECKLIST.md
• CONTRIBUTING.md
• SECURITY.md

License

Released under the MIT License.