Destructive Command Guard (dcg)

The Lazy Pack Registry is a design pattern used in destructive_command_guard to eliminate eager regex compilation during startup. Instead of compiling all regular expressions when the registry is initialized, the system uses metadata-only specifications (PackSpec, SafePatternSpec, DestructivePatternSpec) and compiles regexes only when a pattern is actually evaluated for a command match. This preserves behavior, ordering, and attribution while improving performance on the hot path.

Key Evaluation Logic:

1. Safe pass: Iterates safe patterns across enabled packs; returns 'allow' on the first match.
2. Destructive pass: Iterates destructive patterns across enabled packs; returns the first match (respecting severity/mode).

Compilation is handled via std::sync::OnceLock, ensuring OnceLock::get_or_init is called only on the first match attempt.

The Execution Context Layer distinguishes between bytes that are executed code versus bytes that are merely data (strings, comments, documentation). This prevents the guard from blocking commands when a dangerous substring appears in a non-executable context, such as a git commit message or a search pattern.

There are two primary mechanisms for this:

1. Safe String-Argument Registry: A curated list of commands where specific flags are known to contain data rather than code.
2. Execution-Context Tokenizer: A shell tokenizer that classifies command segments into SpanKind categories to determine if they should be subject to pattern matching.

The Destructive Command Guard (dcg) acts as a middleware hook for AI agents (Claude, Codex, Gemini, Copilot, Cursor, Hermes). It intercepts command execution requests via a PreToolUse hook using JSON via stdin.

Workflow:

1. Parse & Normalize: The incoming JSON is parsed and the command is normalized.
2. Quick Reject: A fast filter eliminates most safe commands immediately.
3. Pattern Matching:
   • Check SAFE_PATTERNS (whitelist): If a match is found, the command is ALLOWED.
   • Check DESTRUCTIVE_PATTERNS (blacklist): If a match is found, the command is DENIED.
   • No match: The command is ALLOWED by default.
4. Output:
   • Allowed: Returns an empty JSON object to stdout.
   • Denied: Returns a JSON deny object to stdout and provides a rich human-readable reason to stderr.

The integration of rich_rust into dcg aims to provide premium, stylish terminal output for human observers via stderr, while ensuring that agent-facing output (JSON on stdout) remains completely untouched and compatible with AI coding agents.

Output Routing Strategy

• STDOUT: Reserved exclusively for pure JSON output intended for AI agents.
• STDERR: Used for all human-facing, colorful, and styled terminal output (Panels, Tables, Rules, Progress Bars).

The Interactive Mode is designed to prevent AI agents from bypassing command guards by requiring human-verifiable interaction. The security model relies on several core implementation requirements to ensure that an automated agent cannot simulate a human response.

Key security pillars include:

• TTY Detection: The system must detect if stdin is a TTY. If it is not a TTY (e.g., a piped input or a non-interactive shell), the command is immediately blocked to prevent automated bypass.
• Verification Challenges: The system uses interactive challenges such as random verification codes, timeouts, or semantic verification to ensure a human is present.
• Audit Logging: All interactive bypass attempts (both successful and failed) are logged with the timestamp, command, a hash of the code used, the result, and TTY information to detect automated attack patterns.

The development and usage of DCG are guided by these core principles:

• Stability (P0): Never hang, crash, or spike unpredictably. Maximum command processing time is capped at 10ms. The tool must fail-open on timeouts or parse errors.
• Safety (P1): Default to allowing unknown or ambiguous commands. Only deny high-confidence catastrophic commands with clear explanations.
• Determinism (P2): Ensure the same input always produces the same decision and attribution. Use stable pack ordering and provide decision traces via dcg explain.
• Precision (P3): Treat false positives as a primary concern. Use context-aware detection (distinguishing between executed commands and data) and allowlisting by rule ID.
• Incremental Delivery (P4): Prioritize correctness and false-positive reduction before adding deeper scanning or UX features.

The Destructive Command Guard (dcg) uses a graduated response system to handle destructive commands based on frequency and severity. There are three primary response levels:

• WARNING: The command is allowed to proceed. A warning is displayed to stderr and the event is logged. This is typically used for the first occurrence in a session.
• SOFT_BLOCK: The command is blocked initially. In interactive mode, the user can confirm to proceed by using the dcg confirm <code> command. This is triggered when a session threshold is exceeded.
• HARD_BLOCK: The command is blocked with no override. The user must either add the pattern to an allowlist or use dcg allow-once <code>. This is triggered when a history threshold is exceeded or when using paranoid mode.

dcg is designed for well-intentioned but fallible AI agents. It is not a security tool against malicious actors.

Key Limitations:

• Malicious Actors: A determined attacker can bypass the hook.
• Non-Bash Commands: Direct file writes via Python, JavaScript, or API calls are not intercepted.
• Scripts: dcg does not inspect the contents of scripts (e.g., ./deploy.sh).
• Committed Work: It cannot prevent the loss of local-only commits.
• Dynamic stdin: dcg traces bounded literal pipelines (like echo | ...) into REPLs (e.g., psql, mysql, sqlite3). However, it fails closed (blocks) on unknown/dynamic producers, non-UTF-8 files, or payloads exceeding 256 KiB to prevent bypasses via the <pack>:stdin-unverified rule.