dcg (Destructive Command Guard)

A high-performance hook for AI coding agents that blocks destructive commands before they execute, protecting your work from accidental deletion across Claude Code, Codex CLI, Gemini CLI, Copilot CLI, VS Code Copilot Chat, Cursor, Hermes Agent, Grok (xAI), Posit Assistant, Oh My Pi, Factory Droid's Execute tool, and related tools.

Supported: Claude Code, Codex CLI 0.125.0+, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Cursor IDE, Hermes Agent, Posit Assistant (Positron/RStudio extension, standalone server, and pa terminal client), Grok (xAI) (native ~/.grok/hooks/ plus Claude compatibility layer), Antigravity CLI (agy) (native ~/.gemini/config/hooks.json via dcg install --agy), OpenCode (native tool.execute.before plugin via dcg install --opencode — see docs/opencode-integration.md), Oh My Pi (omp) (native tool_call extension via dcg install --omp), Crush (native hooks.PreToolUse entry in crush.json via dcg install --crush — see docs/crush-integration.md), Reasonix (native hooks.PreToolUse entry in settings.json via dcg install --reasonix — see docs/reasonix-integration.md), Muse Code (native hooks.PreToolUse matcher group in ~/.config/muse/settings.json via dcg install --muse — see docs/muse-integration.md), Amp (native tool.call plugin via dcg install --amp — see docs/amp-integration.md), Pi (via extension recipe), Aider (limited—git hooks only), Continue (detection only)

Factory Droid's Execute tool is supported through dcg install --droid; see coverage and Script-mode limitations.

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash -s -- --easy-mode

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.ps1"))) -EasyMode -Verify

---

TL;DR

The Problem: AI coding agents (Claude, Codex, Gemini, Copilot, etc.) occasionally run catastrophic commands like git reset --hard, rm -rf ./src, or DROP TABLE users—destroying hours of uncommitted work in seconds.

The Solution: dcg is a high-performance hook that intercepts destructive commands before they execute, blocking them with clear explanations and safer alternatives.

Why Use dcg?

Feature	What It Does
Zero-Config Protection	Blocks dangerous git/filesystem commands out of the box
50+ Security Packs	Databases, Kubernetes, Docker, AWS/GCP/Azure, Terraform, and more
Sub-Millisecond Latency	SIMD-accelerated filtering—you won't notice it's there
Heredoc/Inline Script Scanning	Catches python -c "os.remove(...)" and embedded shell scripts
Smart Context Detection	Won't block grep "rm -rf" (data) but will block rm -rf / (execution)
Rich Terminal Output	Human-readable denial panels, rule context, and suggestions on stderr
Agent-Safe Streams	Machine-readable hook output stays on stdout while rich UI stays on stderr
Native Codex Support	Codex CLI 0.125.0+ receives a minimal stdout JSON denial that current clients enforce reliably
Graceful Degradation	Plain output for CI, pipes, dumb terminals, and no-color environments
Scan Mode for CI	Pre-commit hooks and CI integration to catch dangerous commands in code review
Bounded Failure Policy	Analysis timeouts become explicit review/block outcomes; malformed raw hook envelopes remain auditable and configurable
Explain Mode	dcg explain "command" shows exactly why something is blocked

Quick Example

# AI agent tries to run:
$ git reset --hard HEAD~5

# dcg intercepts and blocks:
════════════════════════════════════════════════════════════════
BLOCKED  dcg
────────────────────────────────────────────────────────────────
Reason:  git reset --hard destroys uncommitted changes

Command: git reset --hard HEAD~5

Tip: Consider using 'git stash' first to save your changes.
════════════════════════════════════════════════════════════════

Enable More Protection

# ~/.config/dcg/config.toml
[packs]
enabled = [
    "database.postgresql",    # Blocks DROP TABLE, TRUNCATE
    "kubernetes.kubectl",     # Blocks kubectl delete namespace
    "cloud.aws",              # Blocks aws ec2 terminate-instances
    "containers.docker",      # Blocks docker system prune
]

Agent-Specific Profiles

dcg automatically detects which AI coding agent is invoking it and can apply agent-specific configuration. The trust_level field is an advisory label recorded in JSON output and logs — it does not directly change rule evaluation. Behavioral differences come from the other profile fields:

Option	Effect
disabled_packs	Removes rule packs from evaluation
extra_packs	Adds rule packs to evaluation
additional_allowlist	Adds command patterns that bypass deny rules
disabled_allowlist	When true, ignores all allowlist entries

# Trust Claude Code more — wider allowlist, fewer packs
[agents.claude-code]
trust_level = "high"
additional_allowlist = ["npm run build", "cargo test"]
disabled_packs = ["kubernetes"]

# Oh My Pi has its own canonical profile (distinct from legacy Pi)
[agents.omp]
trust_level = "medium"
extra_packs = ["strict_git"]

# Restrict unknown agents — extra rules, no allowlist bypass
[agents.unknown]
trust_level = "low"
extra_packs = ["strict_git", "database"]  # real pack / category IDs (see `dcg packs`)
disabled_allowlist = true

extra_packs/disabled_packs take the same pack and category IDs as [packs] enabled/disabled — a category ID like "database" expands to every database.* sub-pack. Use IDs listed by dcg packs or in docs/packs/README.md; "paranoid" is a graduation mode, not a pack, so enable the real strict_git pack for stricter git rules.

See docs/agents.md for full documentation on supported agents, trust levels, and configuration options.

Codex Support

dcg now treats Codex CLI as a first-class hook target, not just a Claude-shaped compatibility path. The installer configures Codex CLI 0.125.0+ automatically when it detects codex on PATH or an existing ~/.codex/ directory.

Codex behavior	dcg handling
Hook config	Merges a PreToolUse Bash hook into ~/.codex/hooks.json
Denied command	Exits 0 with a minimal hookSpecificOutput denial on stdout; human warning stays on stderr
Allowed command	Exits 0 with empty stdout and stderr
Existing hooks	Preserves coexisting hooks, keeps dcg first for Bash, and refuses to overwrite malformed JSON
Validation	Covered by subprocess protocol tests plus an opt-in real Codex E2E harness

Codex's hook input is intentionally close to Claude Code's, but Codex rejects unknown fields in hook output. dcg detects Codex payloads from the non-empty turn_id field and emits only Codex's documented denial fields so a blocked command is reported as blocked rather than as a failed hook. See docs/codex-integration.md for protocol details, manual probes, and troubleshooting.

---

Origins & Authors

This project began as a Python script by Jeffrey Emanuel, who recognized that AI coding agents, while incredibly useful, occasionally run catastrophic commands that destroy hours of uncommitted work. The original implementation was a simple but effective hook that intercepted dangerous git and filesystem commands before execution.

• Jeffrey Emanuel - Original concept and Python implementation (source); substantially expanded the Rust version with the modular pack system (50+ security packs), heredoc/inline-script scanning, the three-tier architecture, context classification, allowlists, scan mode, and the dual regex engine
• Darin Gordon - Initial Rust port with performance optimizations

The initial Rust port by Darin maintained pattern compatibility with the original Python implementation while adding sub-millisecond execution through SIMD-accelerated filtering and lazy-compiled regex patterns. Jeffrey subsequently expanded the Rust codebase dramatically to add the features described above.

Escape Hatch / Bypass

If dcg is blocking something you genuinely need to run:

Method	Scope	How
Env var bypass	Single command	DCG_BYPASS=1 <command>
Allow-once code	Single command	Copy the short code from the block message, run dcg allow-once <code>
Permanent allowlist	Rule or command	dcg allowlist add core.git:reset-hard -r "reason"
Remove the hook	All commands	Delete or comment out the dcg entry in ~/.claude/settings.json (or equivalent for your agent)

DCG_BYPASS=1 disables all protection for that invocation. Use it sparingly and prefer allowlists for recurring needs.

Modular Pack System

dcg uses a modular "pack" system to organize destructive command patterns by category. Packs can be enabled or disabled in the configuration file.

Category IDs expand to their sub-packs. Listing a bare category in enabled turns on every pack under it: enabled = ["database"] activates database.postgresql, database.mysql, and the rest of that category. You can still drop a single sub-pack with disabled = ["database.redis"]. The same expansion applies to agent-profile extra_packs / disabled_packs. Always use real pack or category IDs from dcg packs / docs/packs/README.md — a name like "paranoid" is a graduation mode, not a pack.

• Full pack ID index: docs/packs/README.md
• Canonical descriptions + pattern counts: dcg packs --verbose

Enabled by default (no config file)

With no config file present, dcg enables only the packs that guard against the most catastrophic, unrecoverable mistakes:

• core.filesystem - Dangerous recursive rm operations and equivalent filesystem destruction outside literal temp subdirectories (always enabled; cannot be removed from evaluation)
• core.git - Destructive git commands that lose uncommitted work, rewrite history, or destroy stashes (always enabled; cannot be removed from evaluation)
• system.disk - mkfs, dd-to-device, fdisk, parted, mdadm, lvm removal, wipefs (on by default; opt out with disabled = ["system.disk"])

"Cannot be removed" is not the same as "cannot be relaxed." A core.* pack always evaluates, so disabled = ["core.filesystem"] is ignored — but what dcg does with a match is policy, and policy is yours.

Relaxing a critical rule takes a per-rule entry. A broad warn or log — whether written as [policy.packs] or as [policy] default_mode — is silently raised back to deny for any rule whose severity is critical, and dcg does not report that it ignored the setting. Most of what core.filesystem and core.git exist to stop is exactly that severity, so the broad form alone will not do what it looks like it does:

# Relaxes only the high/medium rules. `rm -rf ~/work` still hard-denies,
# because core.filesystem:rm-rf-root-home is critical.
[policy.packs]
"core.filesystem" = "warn"

# Relaxes that one critical rule. This is the form that actually works.
[policy.rules]
"core.filesystem:rm-rf-root-home" = "warn"

warn lets the command run and records the decision; log does the same silently; ask requests operator review where the hook protocol supports it. Use dcg explain --format json '<command>' and read mode to confirm which mode a rule actually resolved to before relying on it. See Configuration for the constraint and Graduated Response for the severity ladder.

On native Windows, two additional packs are on by default so a fresh install blocks catastrophic native-Windows operations with no config. The hook also activates these two packs on Linux/macOS for a request identified as Cmd or PowerShell by its tool label or recognized Windows command syntax:

• windows.filesystem - cmd del /s, rd /s, format <drive>: and PowerShell Remove-Item -Recurse (with or without -Force; aliases included), Clear-Content, Clear-RecycleBin (opt out with disabled = ["windows.filesystem"] or ["windows"])
• windows.system - vssadmin delete shadows / wmic shadowcopy delete (Volume Shadow Copy destruction), diskpart, Format-Volume, Clear-Disk, Remove-Partition, cipher /w, bcdedit /delete (opt out with disabled = ["windows.system"] or ["windows"])

For example, a powershell hook payload or a Bash-labeled rmdir /s /q d:\ request activates these protections even on Linux/macOS. Ordinary POSIX requests keep the three base defaults above; a generic tool label or a Windows-looking string alone does not establish the executing shell. Explicit pack exclusions still apply to this automatic activation. See Windows protection for shell metadata and quoting guidance.

The broader windows.misc (reg delete, net user /delete, wsl --unregister, robocopy /MIR) and windows.powershell (registry/provider deletes, Remove-LocalUser, Disable-ComputerRestore, Remove-VM) packs are opt-in on every platform. To select Windows protection explicitly (e.g. to scan committed .ps1/.cmd scripts in CI), use [packs] enabled = ["windows"] or name the required sub-packs.

Every other pack — including database.postgresql and containers.docker — is opt-in and is not active until a config file enables it. Running dcg init writes a starter ~/.config/dcg/config.toml whose [packs] enabled list turns on database.postgresql and containers.docker as common examples, but that is a generated starter config, not the no-config default. Enable any pack below by adding it to [packs] enabled — see Enable More Protection.

Storage Packs

• storage.s3 - Protects against destructive S3 operations like bucket removal, recursive deletes, and sync --delete.
• storage.gcs - Protects against destructive GCS operations like bucket removal, object deletion, and recursive deletes.
• storage.minio - Protects against destructive MinIO Client (mc) operations like bucket removal, object deletion, and admin operations.
• storage.azure_blob - Protects against destructive Azure Blob Storage operations like container deletion, blob deletion, and azcopy remove.

Remote Packs

• remote.rsync - Protects against destructive rsync operations like --delete and its variants.
• remote.scp - Protects against destructive SCP operations like overwrites to system paths.
• remote.ssh - Protects against destructive SSH operations like remote command execution and key management.

Database Packs

• database.postgresql - Protects against destructive PostgreSQL operations like DROP DATABASE, TRUNCATE, and dropdb.
• database.mysql - MySQL/MariaDB guard.
• database.mongodb - Protects against destructive MongoDB operations like dropDatabase, dropCollection, and remove without criteria.
• database.redis - Protects against destructive Redis operations like FLUSHALL, FLUSHDB, and mass key deletion.
• database.sqlite - Protects against destructive SQLite operations like DROP TABLE, DELETE without WHERE, and accidental data loss.
• database.snowflake - Protects modern snow sql inline queries, files, stdin, nested sources, destructive data operations, pipelines, warehouses, and account privileges.
• database.supabase - Protects against destructive Supabase CLI operations including database resets, migration rollbacks, function/secret/storage deletion, project removal, and infrastructure changes.
• database.databricks - Protects against destructive Databricks CLI operations like account workspace deletion, bundle destroy, recursive workspace/fs deletion, permanent cluster deletion, secret-scope removal, and arbitrary REST DELETE calls.
• database.bigquery - Protects the bq CLI and GoogleSQL against dataset drops (DROP SCHEMA), table overwrites, unfiltered DML (WHERE TRUE is GoogleSQL's full-table idiom), and settings that shorten the time-travel recovery window.

Container Packs

• containers.docker - Protects against destructive Docker operations like system prune, volume prune, and force removal.
• containers.compose - Protects against destructive Docker Compose operations like down -v which removes volumes.
• containers.podman - Protects against destructive Podman operations like system prune, volume prune, and force removal.

Kubernetes Packs

• kubernetes.kubectl - Protects against destructive kubectl operations like delete namespace, drain, and mass deletion.
• kubernetes.helm - Protects against destructive Helm operations like uninstall and rollback without dry-run.
• kubernetes.kustomize - Protects against destructive Kustomize operations when combined with kubectl delete or applied without review.

Cloud Provider Packs

• cloud.aws - Protects against destructive AWS CLI operations like terminate-instances, delete-db-instance, and s3 rm --recursive.
• cloud.azure - Protects against destructive Azure CLI operations like vm delete, storage account delete, and resource group delete.
• cloud.gcp - Protects against destructive gcloud operations like instances delete, sql instances delete, and gsutil rm -r.

CDN Packs

• cdn.cloudflare_workers - Protects against destructive Cloudflare Workers, KV, R2, and D1 operations via the Wrangler CLI.
• cdn.cloudfront - Protects against destructive AWS CloudFront operations like deleting distributions, cache policies, and functions.
• cdn.fastly - Protects against destructive Fastly CLI operations like service, domain, backend, and VCL deletion.

API Gateway Packs

• apigateway.apigee - Protects against destructive Google Apigee CLI and apigeecli operations.
• apigateway.aws - Protects against destructive AWS API Gateway CLI operations for both REST APIs and HTTP APIs.
• apigateway.kong - Protects against destructive Kong Gateway CLI, deck CLI, and Admin API operations.

Infrastructure Packs

• infrastructure.ansible - Protects against destructive Ansible operations like dangerous shell commands and unchecked playbook runs.
• infrastructure.atmos - Protects against destructive Atmos operations like terraform deploy (auto-approve), clean, destroy, state rm/taint, and helmfile destroy.
• infrastructure.pulumi - Protects against destructive Pulumi operations like destroy and up with -y (auto-approve).
• infrastructure.terraform - Protects against destructive Terraform operations like destroy, taint, and apply with -auto-approve.

System Packs

• system.disk - Protects against destructive disk operations including dd to devices, mkfs, partition table modifications (fdisk/parted), RAID management (mdadm), btrfs filesystem operations, device-mapper (dmsetup), network block devices (nbd-client), and LVM commands (pvremove, vgremove, lvremove, lvreduce, pvmove).
• system.permissions - Protects against dangerous permission changes like chmod 777, recursive chmod/chown on system directories.
• system.services - Protects against dangerous service operations like stopping critical services and modifying init configuration.

When system.permissions is enabled, POSIX chmod, chown, and chgrp checks use the complete invocation: recursive options can occur after targets or in flag bundles, and option values such as --reference="chmod 777 notes" remain filename data. The ordinary relative-file chmod exemption requires every target to qualify and no recursive option. Thus chmod 755 notes -vR /etc and chmod 777 notes /etc/shadow require review. Independent rule matches stay separate: granting chmod-777 does not also grant chmod-recursive-root, and granting chmod-setuid does not exempt a simultaneous chmod-setgid match. Unsupported or dynamic arguments retain conservative pattern checks.

CI/CD Packs

• cicd.circleci - Protects against destructive CircleCI operations like deleting contexts, removing secrets, deleting orbs/namespaces, or removing pipelines.
• cicd.github_actions - Protects against destructive GitHub Actions operations like deleting secrets/variables or using gh api DELETE against /actions endpoints.
• cicd.gitlab_ci - Protects against destructive GitLab CI/CD operations like deleting variables, removing artifacts, and unregistering runners.
• cicd.jenkins - Protects against destructive Jenkins CLI/API operations like deleting jobs, nodes, credentials, or build history.

Secrets Management Packs

• secrets.aws_secrets - Protects against destructive AWS Secrets Manager and SSM Parameter Store operations like delete-secret and delete-parameter.
• secret_disclosure - Exact opt-in protection against secret-manager commands that expose credential values through agent-visible output or agent-chosen files; injection commands such as infisical run, op run, and doppler run remain allowed. It is intentionally outside the secrets.* category so existing enabled = ["secrets"] configurations do not change policy on upgrade.
• secrets.doppler - Protects against destructive Doppler CLI operations like deleting secrets, configs, environments, or projects.
• secrets.infisical - Protects against deleting Infisical secrets, folders, and dynamic-secret leases, plus resetting local Infisical configuration.
• secrets.onepassword - Protects against destructive 1Password CLI operations like deleting items, documents, users, groups, and vaults.
• secrets.vault - Protects against destructive Vault CLI operations like deleting secrets, disabling auth/secret engines, revoking leases/tokens, and deleting policies.

Provider packs preserve dcg's default destructive-operation scope: read commands remain allowed. Teams that also treat transcript disclosure as destructive can enable the separate policy explicitly:

[packs]
enabled = ["secrets.infisical", "secret_disclosure"]

With secret_disclosure enabled, value-emitting reads such as infisical secrets get, infisical export, op read, doppler secrets download, vault kv get, aws secretsmanager get-secret-value, aws secretsmanager batch-get-secret-value, and decrypted SSM reads are blocked. Metadata inspection, CLI help, and direct process injection remain available. The opt-in careful_company_running_windows preset also includes both new packs as deliberate members of its pinned secret-store policy.

Platform Packs

• platform.azure_devops - Protects against destructive azure-devops Azure CLI extension operations across az devops, az repos, az pipelines and az boards: deleting team projects, repositories, refs, branch policies, pipelines, variable groups, wikis, teams, service connections and work items, removing users and group memberships, resetting permission ACLs, and issuing arbitrary state-changing az devops invoke REST calls. az artifacts exposes no destructive command and carries no rule. Read-only verbs and ordinary development flow are untouched.
• platform.github - Protects against destructive GitHub CLI operations like changing repository visibility or deleting repositories, gists, releases, or SSH keys.
• platform.gitlab - Protects against destructive GitLab platform operations like deleting projects, releases, protected branches, and webhooks.
• platform.kamal - Protects against destructive Kamal 2.x operations that tear down the stack (kamal remove), delete accessory data directories (kamal accessory remove), drop proxy routing, take the app offline, or prune the images that kamal rollback relies on.
• platform.modal - Protects against destructive Modal serverless platform operations like recursive volume removal, app stops with --force, and secret deletion.
• platform.railway - Protects against destructive Railway CLI and Public API operations that can delete projects, environments, services, functions, volumes, variables, or deployments.

DNS Packs

• dns.cloudflare - Protects against destructive Cloudflare DNS operations like record deletion, zone deletion, and targeted Terraform destroy.
• dns.generic - Protects against destructive or risky DNS tooling usage (nsupdate deletes, zone transfers).
• dns.route53 - Protects against destructive AWS Route53 DNS operations like hosted zone deletion and record set DELETE changes.

Email Packs

• email.mailgun - Protects against destructive Mailgun API operations like domain deletion, route deletion, and mailing list removal.
• email.postmark - Protects against destructive Postmark API operations like server deletion, template deletion, and sender signature removal.
• email.sendgrid - Protects against destructive SendGrid API operations like template deletion, API key deletion, and domain authentication removal.
• email.ses - Protects against destructive AWS Simple Email Service operations like identity deletion, template deletion, and configuration set removal.

Feature Flag Packs

• featureflags.flipt - Protects against destructive Flipt CLI and API operations.
• featureflags.launchdarkly - Protects against destructive LaunchDarkly CLI and API operations.
• featureflags.split - Protects against destructive Split.io CLI and API operations.
• featureflags.unleash - Protects against destructive Unleash CLI and API operations.

Load Balancer Packs

• loadbalancer.elb - Protects against destructive AWS Elastic Load Balancing (ELB/ALB/NLB) operations like deleting load balancers, target groups, or deregistering targets from live traffic.
• loadbalancer.haproxy - Protects against destructive HAProxy load balancer operations like stopping the service or disabling backends via runtime API.
• loadbalancer.nginx - Protects against destructive nginx load balancer operations like stopping the service or deleting config files.
• loadbalancer.traefik - Protects against destructive Traefik load balancer operations like stopping containers, deleting config, or API deletions.

Messaging Packs

• messaging.kafka - Protects against destructive Kafka CLI operations like deleting topics, removing consumer groups, resetting offsets, and deleting records.
• messaging.nats - Protects against destructive NATS/JetStream operations like deleting streams, consumers, key-value entries, objects, and accounts.
• messaging.rabbitmq - Protects against destructive RabbitMQ operations like deleting queues/exchanges, purging queues, deleting vhosts, and resetting cluster state.
• messaging.sqs_sns - Protects against destructive AWS SQS and SNS operations like deleting queues, purging messages, deleting topics, and removing subscriptions.

Monitoring Packs

• monitoring.datadog - Protects against destructive Datadog CLI/API operations like deleting monitors and dashboards.
• monitoring.newrelic - Protects against destructive New Relic CLI/API operations like deleting entities or alerting resources.
• monitoring.pagerduty - Protects against destructive PagerDuty CLI/API operations like deleting services and schedules (which can break incident routing).
• monitoring.prometheus - Protects against destructive Prometheus/Grafana operations like deleting time series data or dashboards/datasources.
• monitoring.splunk - Protects against destructive Splunk CLI/API operations like index removal and REST API DELETE calls.

Payment Packs

• payment.braintree - Protects against destructive Braintree/PayPal payment operations like deleting customers or cancelling subscriptions via API/SDK calls.
• payment.square - Protects against destructive Square CLI/API operations like deleting catalog objects or customers (which can break payment flows).
• payment.stripe - Protects against destructive Stripe CLI/API operations like deleting webhook endpoints and customers, or rotating API keys without coordination.

Search Engine Packs

• search.algolia - Protects against destructive Algolia operations like deleting indices, clearing objects, removing rules/synonyms, and deleting API keys.
• search.elasticsearch - Protects against destructive Elasticsearch REST API operations like index deletion, delete-by-query, index close, and cluster setting changes.
• search.meilisearch - Protects against destructive Meilisearch REST API operations like index deletion, document deletion, delete-batch, and API key removal.
• search.opensearch - Protects against destructive OpenSearch REST API operations and AWS CLI domain deletions.

Backup Packs

• backup.borg - Protects against destructive borg operations like delete, prune, compact, and recreate.
• backup.rclone - Protects against destructive rclone operations like sync, delete, purge, dedupe, and move.
• backup.restic - Protects against destructive restic operations like forgetting snapshots, pruning data, removing keys, and cache cleanup.
• backup.velero - Protects against destructive velero operations like deleting backups, schedules, and locations.

Windows Packs

Native-Windows (cmd.exe + PowerShell) destructive-command protection. windows.filesystem and windows.system are default-on on native Windows and activate for recognized Cmd/PowerShell hook payloads on other hosts; windows.misc and windows.powershell are opt-in everywhere. Ordinary POSIX requests do not activate the Windows packs. All patterns are case-insensitive.

• windows.filesystem - Recursive/forced filesystem destruction: cmd del /s, rd /s/rmdir /s, format <drive>:; PowerShell Remove-Item -Recurse (with or without -Force; -Force only broadens coverage to hidden/read-only items; aliases rm/del/rd/ri included), Clear-Content, Clear-RecycleBin. Whitelists PowerShell -WhatIf previews only on cmdlets/aliases that honor it, plus temp-dir deletes.
• windows.system - Catastrophic disk/system operations: vssadmin delete shadows and wmic shadowcopy delete (Volume Shadow Copy destruction — a ransomware hallmark), diskpart, Format-Volume, Clear-Disk, Remove-Partition, Initialize-Disk/Reset-PhysicalDisk, cipher /w, bcdedit /delete.
• windows.misc - Registry/account/service/WSL/copy destruction: reg delete, net user|localgroup /delete, sc delete, schtasks /delete, wsl --unregister (destroys a WSL distro), robocopy /MIR (mirror-delete).
• windows.powershell - Destructive PowerShell cmdlets: registry/provider deletes (Remove-Item HKLM:\, Remove-ItemProperty, Remove-PSDrive), Remove-LocalUser/Remove-LocalGroup, Unregister-ScheduledTask, Disable-ComputerRestore, forced Stop-Computer/Restart-Computer, Remove-VM/Remove-AppxPackage.

Careful Company (Windows) Preset

Every other pack answers "will this command destroy something?". This preset also answers "is this command sending our data somewhere, or switching off the controls that watch it?" — the question that matters once an agent runs on a Windows workstation with tool-permission prompts disabled. The same policy is applied to statically inspectable commands submitted through either PowerShell or cmd.exe, including Cmd's caret escaping, control prefixes, nested cmd /c / call, and command chaining. It is opt-in on every platform, and one line enables the whole posture:

[packs]
enabled = ["careful_company_running_windows"]

With this exact preset ID enabled, the hook evaluation deadline defaults to 3000 ms instead of the ordinary 1000 ms unless config or DCG_HOOK_TIMEOUT_MS explicitly supplies another value. This changes only the time available to reach the same fail-closed decision. Inspect the effective value and source with dcg config --format json.

That turns on the six sub-packs below and the existing destruction coverage the same posture needs: the current windows.*, database.* (including Snowflake), storage.*, remote.*, backup.*, secrets.*, and cloud.* packs. Membership is an explicit pinned list rather than a prefix rule, so a future pack added to one of those reused categories does not silently join this security posture — it has to be added deliberately. (A future careful_company_running_windows.* sub-pack does join, through ordinary category expansion.) Any member can be dropped individually with disabled = ["remote.rsync"].

• careful_company_running_windows.email - Sending mail from the workstation: Send-MailMessage, System.Net.Mail.SmtpClient, Outlook COM automation, Microsoft Graph sendMail, transactional mail-API send endpoints, aws ses send-email, SMTP CLI tools (blat, swaks, msmtp, git send-email, curl --mail-rcpt), and persistent forwarding rules (New-InboxRule -ForwardTo, Set-Mailbox -ForwardingSmtpAddress).
• careful_company_running_windows.chat - Chat and webhook destinations: Slack incoming webhooks and Web API writes, Teams connectors and Power Automate triggers, Discord, Telegram, Google Chat, Twilio, Zapier/IFTTT, PagerDuty, and request catchers such as webhook.site and interact.sh.
• careful_company_running_windows.upload - HTTP file-upload primitives (-InFile, -Form, curl -T, -F field=@file, --data-binary @file, --post-file, WebClient.UploadFile, GetRequestStream, MultipartFormDataContent, BITS uploads), file-drop/paste services, gh gist create, certreq -Post, and request bodies built from file or clipboard contents.
• careful_company_running_windows.transfer - Outbound file transfer: scp/sftp/WinSCP to a remote destination, scripted FTP, tftp put, rsync and rclone to a remote, cloud-storage uploads (aws s3 cp local→s3://, az storage blob upload, azcopy, gsutil cp→gs://, b2/s3cmd/mc/wrangler r2), peer-to-peer senders, WebDAV mounts, and copy LOLBins (esentutl /y, print /D:).
• careful_company_running_windows.tunnel - Channels that expose the workstation or bypass inspection: ngrok, cloudflared, devtunnel/code tunnel, localtunnel, tailscale funnel, ssh -R/-D, chisel/frp, ncat/netcat/socat, PowerShell raw sockets, netsh interface portproxy, DNS tunnels, and out-of-band callback domains.
• careful_company_running_windows.guardrails - Turning off the safety net: Defender (Set-MpPreference -Disable*/-ExclusionPath), the firewall, EDR and event-log services, BitLocker, Set-ExecutionPolicy Bypass, script-block logging, event-log clearing, , plus unreviewed remote code (, , mshta/regsvr32 remote payloads). Diagnosis stays open: , , and are whitelisted.

False positives are the design constraint. Rules require positive evidence of egress — an attached file, a known egress host, a mutating method — so ordinary GETs, -OutFile/curl -o downloads, and every package-manager install pass through untouched (fetching from a known file-drop or paste host is the one exception, and it warns rather than blocks). Requests whose destinations are all internal (loopback, RFC1918, *.internal/*.corp/*.local, bare intranet hostnames) are whitelisted, with the cloud metadata endpoints (169.254.169.254, metadata.google.internal) deliberately excluded from that allowance. Searching for a token (Select-String "Send-MailMessage" *.ps1) and dcg explain "<command>" are never blocked. git push to a named remote is untouched, and SMB copies to a corporate share are out of scope.

Genuinely ambiguous cases warn instead of blocking (Medium severity: the command runs and the decision is recorded) — a POST with an inline body is a GraphQL query as often as an exfiltration. Promote them when your posture calls for it:

[policy.rules]
"careful_company_running_windows.upload:cli-http-mutating-request" = "deny"
"careful_company_running_windows.upload:ps-http-mutating-request" = "deny"

This preset carries one built-in trust boundary you should know about. While any careful_company_running_windows.* pack is enabled, a command whose executable is hfdt (optionally path-qualified) is allowed without evaluating any pack at all — not just this preset's. hfdt rm -rf /data is permitted with the preset on and denied with it off. The exemption is structural rather than textual: it requires hfdt to be the actual executable of the whole command and refuses chains, redirection, and process substitution, so hfdt …; Invoke-RestMethod … and hfdt $(…) are evaluated normally. If you do not run that tool, this never fires; if you do, treat it as an explicit decision to trust it completely. See docs/careful-company-windows.md.

Other first-party internal tooling gets no such exemption and should be allowlisted, which keeps the grant narrow and recorded:

dcg allowlist add-command "mytool publish --to https://artifacts.corp.internal" \
  -r "First-party internal publisher" --user

Other Packs

• package_managers - Protects against dangerous package manager operations like publishing packages and removing critical system packages.
• strict_git - Stricter git protections: blocks all force pushes, rebases, and history rewriting operations.

Enable packs in ~/.config/dcg/config.toml:

[packs]
enabled = [
    # Databases
    "database.postgresql",
    "database.redis",
    "database.supabase",

    # Containers and orchestration
    "containers.docker",
    "kubernetes",  # Enables all kubernetes sub-packs

    # Cloud providers
    "cloud.aws",
    "cloud.gcp",

    # Secrets management
    "secrets.aws_secrets",
    "secrets.vault",

    # CI/CD
    "cicd.jenkins",
    "cicd.gitlab_ci",

    # Messaging
    "messaging.kafka",
    "messaging.sqs_sns",

    # Search engines
    "search.elasticsearch",

    # Backup
    "backup.restic",

    # Platform
    "platform.github",
    "platform.railway",

    # Monitoring
    "monitoring.splunk",
]

Custom Packs

Create your own organization-specific security packs using YAML files. Custom packs let you define patterns for internal tools, deployment scripts, and proprietary systems without modifying dcg.

[packs]
custom_paths = [
    "~/.config/dcg/packs/*.yaml",      # User packs
    ".dcg/packs/*.yaml",               # Project-local packs
]

For detailed pack authoring guide, schema reference, and examples, see docs/custom-packs.md.

Validate your pack before deployment:

dcg pack validate mypack.yaml

Heredoc scanning configuration:

[heredoc]
# Enable scanning for heredocs and inline scripts (python -c, bash -c, etc.).
enabled = true

# Extraction timeout budget (milliseconds).
timeout_ms = 50

# Resource limits for extracted bodies.
max_body_bytes = 1048576
max_body_lines = 10000
max_heredocs = 10

# Optional language filter (scan only these languages). Omit for "all".
# languages = ["python", "bash", "javascript", "typescript", "ruby", "perl", "go"]

# Bounded heredoc fallback (strict mode can block instead).
fallback_on_parse_error = true
fallback_on_timeout = true

CLI overrides for heredoc scanning:

• --heredoc-scan / --no-heredoc-scan
• --heredoc-timeout <ms>
• --heredoc-languages <lang1,lang2,...>

Heredoc documentation:

• docs/adr-001-heredoc-scanning.md (architecture and rationale)
• docs/patterns.md (pattern authoring + inventory)
• docs/security.md (threat model and incident response)

Heredoc Three-Tier Architecture

Heredoc and inline script scanning uses a three-tier pipeline designed for performance and accuracy:

Command Input
     │
     ▼
┌─────────────────┐
│ Tier 1: Trigger │ ─── No match ──► ALLOW (fast path, <100μs)
│   (RegexSet)    │
└────────┬────────┘
         │ Match
         ▼
┌─────────────────┐
│ Tier 2: Extract │ ─── Error/Timeout ──► FALLBACK SCAN or BLOCK (strict)
│   (<1ms)        │
└────────┬────────┘
         │ Success
         ▼
┌─────────────────┐
│ Tier 3: AST     │ ─── No match ──► ALLOW
│   (<5ms)        │ ─── Match ──► BLOCK
└─────────────────┘

Tier 1: Trigger Detection (<100μs)

Ultra-fast regex screening to detect heredoc indicators. Uses a compiled RegexSet for O(n) matching against all trigger patterns simultaneously:

static HEREDOC_TRIGGERS: LazyLock<RegexSet> = LazyLock::new(|| {
    RegexSet::new([
        r"<<-?\s*(?:['\x22][^'\x22]*['\x22]|[\w.-]+)",  // Heredocs
        r"<<<",                                          // Here-strings
        r"\bpython[0-9.]*\b.*\s+-[A-Za-z]*[ce]",        // python -c/-e
        r"\bruby[0-9.]*\b.*\s+-[A-Za-z]*e",             // ruby -e
        r"\bnode(js)?[0-9.]*\b.*\s+-[A-Za-z]*[ep]",     // node -e/-p
        r"\b(sh|bash|zsh)\b.*\s+-[A-Za-z]*c",           // bash -c
        // ... more patterns
    ])
});

Commands without any trigger patterns skip directly to ALLOW—no further processing needed.

Tier 2: Content Extraction (<1ms)

For commands that trigger, extract the actual content to be evaluated:

• Heredocs: cat <<EOF ... EOF → extracts body between delimiters
• Here-strings: cat <<< "content" → extracts quoted content
• Inline scripts: python -c "code" → extracts the code argument

Extraction is bounded by configurable limits:

• Maximum body size (default: 1MB)
• Maximum lines (default: 10,000)
• Maximum heredocs per command (default: 10)
• Timeout (default: 50ms)

pub struct ExtractionLimits {
    pub max_body_bytes: usize,
    pub max_body_lines: usize,
    pub max_heredocs: usize,
    pub timeout_ms: u64,
}

Tier 3: AST Pattern Matching (<5ms)

Extracted content is parsed using language-specific AST grammars (via tree-sitter/ast-grep) and matched against structural patterns:

// Example: detect subprocess.run with shell=True and rm -rf
let pattern = r#"
    call_expression {
        function: attribute { object: "subprocess" attr: "run" }
        arguments: argument_list {
            contains string { contains "rm -rf" }
            contains keyword_argument { keyword: "shell" value: "True" }
        }
    }
"#;

Recursive Shell Analysis:

When extracted content is itself a shell script (e.g., bash -c "git reset --hard"), Tier 3 recursively extracts inner commands and re-evaluates them through the full pipeline:

if content.language == ScriptLanguage::Bash {
    let inner_commands = extract_shell_commands(&content.content);
    for inner in inner_commands {
        // Re-evaluate inner command against all packs
        if let Some(result) = evaluate_command(&inner, ...) {
            if result.decision == Deny {
                return result; // Block the outer command
            }
        }
    }
}

If you encounter commands that should be blocked, please file an issue.

Environment Variables

Environment variables override config files (highest priority):

• DCG_PACKS="containers.docker,kubernetes": enable packs (comma-separated)
• DCG_DISABLE="kubernetes.helm": disable packs/sub-packs (comma-separated)
• DCG_VERBOSE=0-3: verbosity level (0 = quiet, 3 = trace)
• DCG_LOG=<filter>: hook-mode diagnostics; sends the evaluator's tracing events to stderr (DCG_LOG=debug, or a tracing filter such as destructive_command_guard::heredoc=trace). Unset by default.
• DCG_QUIET=1: suppress non-error output
• DCG_COLOR=auto|always|never: color mode
• DCG_NO_RICH=1: disable rich terminal formatting and use plain rendering
• DCG_NO_COLOR=1: disable colored output (same as NO_COLOR)
• DCG_LEGACY_OUTPUT=1: force plain output paths (same as --legacy-output)
• DCG_ROBOT=1: enable robot mode for JSON stdout and quiet stderr
• DCG_HIGH_CONTRAST=1: enable high-contrast output (ASCII borders + monochrome palette)
• DCG_FORMAT=text|json|sarif: default output format (command-specific — see Output Formats for which values each subcommand actually accepts; real SARIF is dcg scan-only)
• DCG_FAIL_CLOSED=1: block (deny) on hook input that cannot be parsed, instead of the default fail-open allow (opt-in; see Bounded Failure Policy)
• DCG_UNVERIFIED_DECISION=deny|ask: decision for commands dcg could not verify (evaluation timeout, or over max_command_bytes); deny suits unattended sessions where nobody can answer ask (see Bounded Failure Policy)
• DCG_BRIDGE_CRASH_DECISION=allow: let a command through when the OpenCode plugin or the Oh My Pi bridge started dcg but got no verdict from it (dcg crashed or was killed); the default blocks (see Bounded Failure Policy)

Command History

Command history is opt-in ([history] enabled = true). When enabled, the hook records every evaluated command (redacted per redaction_mode; the default "pattern" replaces recognised credential shapes with placeholders and truncates long quoted arguments) in a SQLite database that dcg history, dcg stats, and dcg suggest-allowlist read.

Where the database lives, highest priority first:

1. DCG_HISTORY_DB environment variable
2. [history] database_path in config (~ expanded; relative paths resolve against the working directory)
3. An existing history.db beside config.toml (~/.config/dcg/history.db) from a release before 0.15 — it keeps being used until you move it
4. The platform state directory: $XDG_STATE_HOME/dcg/history.db, defaulting to ~/.local/state/dcg/history.db on Linux/macOS, and %LOCALAPPDATA%\dcg\history.db on Windows

History is state, not configuration, so it no longer defaults into ~/.config/dcg; a sandbox that mounts the config directory read-only keeps working. Directories dcg creates for the database are owner-only (0700). dcg doctor prints the resolved path, which rule selected it, and whether the hook can write there.

What a row can and cannot tell you:

• hostname is the machine that recorded the row, so databases copied off several machines can be merged and still attributed.
• exit_code is always NULL on rows the hook writes. dcg runs before the command, so it never learns how the command ended. Read NULL as "unknown", not as "succeeded". History records dcg's decisions (allow, deny, warn, bypass); it cannot by itself show that an allowed command did damage.
• dcg history analyze works from those decisions. With no recorded commands it says so and makes no recommendations. A pack that never matched is listed but never recommended for removal: a guard pack that stays quiet is working.

Output Formats and DCG_FORMAT

--format (and the DCG_FORMAT env var, which seeds the default) is command-specific: each subcommand accepts only its own set of values, and an unrecognized value is a usage error (exit 2). DCG_FORMAT applies wherever a command has a --format flag and is silently ignored by commands that don't.

Command	Accepted --format values	Notes
dcg scan	pretty, json, markdown, sarif	Only command that emits real SARIF 2.1.0
dcg test	pretty (alias text), json (aliases sarif, structured), toon
dcg config	pretty (alias text), json (alias sarif)
dcg packs	pretty (alias text), json (alias sarif)
dcg explain	pretty, json (alias sarif)
dcg doctor	pretty, json (alias sarif)
dcg simulate	pretty, json (alias sarif)
dcg corpus	json, pretty (alias sarif)
dcg suggest-allowlist	text, json (alias sarif)

sarif is a JSON alias on every command except dcg scan. This is deliberate so that setting DCG_FORMAT=sarif globally degrades gracefully — dcg scan produces a real SARIF report while other commands fall back to their structured JSON rather than erroring. If you need machine-readable output from a non-scan command, prefer --format json (which is unambiguous); use dcg scan --format sarif for SARIF. --robot forces JSON regardless of --format.

Configuration Hierarchy

dcg supports layered configuration from multiple trusted sources, with higher-priority sources overriding lower ones:

1. Environment Variables (DCG_* prefix) [HIGHEST PRIORITY]
2. Explicit Config File (DCG_CONFIG env var)
3. User Config (~/.config/dcg/config.toml)
4. System Config (/etc/dcg/config.toml)
5. Compiled Defaults [LOWEST PRIORITY]

An automatically discovered .dcg.toml is intentionally not a normal precedence layer. A repository is untrusted when it is first cloned, so its config may only add enforcement: enable built-in packs, add deny policy entries, opt into general.fail_closed, enable heredoc scanning, or turn off heredoc bounded fallbacks. Settings that grant trust or reduce coverage — including allow overrides, pack disables, custom pack paths, custom regex overrides (including block regexes), resource limits, language filters, agent profiles, nested project overrides, and per-rule target-path exemptions — are ignored during automatic discovery.

Automatic project discovery reads only a direct regular file bound to the handle it actually reads: O_NOFOLLOW plus descriptor identity on Unix (including macOS), and a reparse-point-refusing open plus handle/path identity on native Windows. A symlinked .dcg.toml is refused on every platform.

To deliberately trust the complete repository config for one invocation, select it explicitly: DCG_CONFIG=.dcg.toml dcg .... An explicit file has the same full authority as any other user-selected config.

Accessibility & Themes

dcg supports colorblind-safe palettes and high-contrast output. Colors are always paired with symbols/labels to avoid conveying meaning by color alone.

[output]
high_contrast = true       # ASCII borders + black/white palette

[theme]
palette = "colorblind"     # default | colorblind | high-contrast
use_unicode = true         # false for ASCII-only
use_color = true           # false for monochrome

Configuration File Locations:

Level	Path	Use Case
System	/etc/dcg/config.toml	Organization-wide defaults
User	~/.config/dcg/config.toml	Personal preferences
Project	.dcg.toml (repo root)	Automatically discovered enforcement-only policy
Explicit	DCG_CONFIG=/path/to/file	Testing or override

The machine-wide system-config layer is accepted on Unix only after the file and every directory in its direct path are root-owned and not group/world writable. Native Windows currently ignores that implicit layer until native ACL and reparse-point validation is implemented; use a user config or an explicit DCG_CONFIG file there.

Merging Behavior:

Configuration layers are merged additively, with higher-priority sources overriding specific fields:

// Only fields explicitly set in higher-priority configs override
// Missing fields retain values from lower-priority sources
fn merge_layer(&mut self, other: ConfigLayer) {
    if let Some(verbose) = other.general.verbose {
        self.general.verbose = verbose;  // Override if present
    }
    // Unset fields retain previous values
}

This means you can set organization defaults in /etc/dcg/config.toml, personal preferences in ~/.config/dcg/config.toml, and repository-owned hardening in .dcg.toml without letting a newly cloned repository weaken the user's guard. Use DCG_CONFIG=.dcg.toml only after reviewing a project file that needs full override authority.

Project-Specific Pack Configuration:

The [projects] section allows different pack configurations for different repositories:

[projects."/home/user/work/production-api"]
packs = { enabled = ["database.postgresql", "cloud.aws"], disabled = [] }

[projects."/home/user/personal/experiments"]
packs = { enabled = [], disabled = ["core.git"] }  # More permissive for experiments

Bounded Failure Policy

dcg distinguishes an unreadable hook envelope from a command whose safety evaluation began but could not finish. It never treats elapsed analysis time or an oversized extracted command as proof that execution is safe.

Scenario	Default behavior	Strict/configured behavior
Malformed or oversized raw hook JSON	Allow with an audit warning	general.fail_closed = true denies
Transient hook stdin I/O error	Allow with an audit warning	Always fail-open because the payload was not attacker-controlled
Extracted command exceeds max_command_bytes	Explicit indeterminate result	Review-capable clients receive ask (unverified_decision = "deny" turns this into a deny); other clients block
Absolute evaluation deadline expires	Explicit indeterminate result	Review-capable clients receive ask (unverified_decision = "deny" turns this into a deny); other clients block
A safety regex fails during evaluation, including backtracking work exhaustion	Incomplete analysis, never a silent allow	Proven blocking findings retain their denial; otherwise request review or block according to the unverified policy. Warning/log policy and confidence or rebase-recovery exemptions cannot hide the incomplete analysis
Heredoc extraction/parse/AST failure	Run the bounded fallback scanner	fallback_on_parse_error = false or fallback_on_timeout = false blocks
OpenCode plugin or Oh My Pi bridge: dcg cannot be started (missing or not executable)	Allow with a visible diagnostic, so a broken install does not block every command	OMP: DCG_UNVERIFIED_DECISION=deny in its environment blocks; the config-file setting cannot apply because dcg never read it
OpenCode plugin or Oh My Pi bridge: dcg started but gave no verdict (killed by a signal or the bridge's timeout, an unexpected exit status; for OpenCode also exit 0 without its explicit allow line)	Block, with the reason and a visible diagnostic; a deny dcg wrote before dying still stands	DCG_BRIDGE_CRASH_DECISION=allow in the agent's environment lets such commands through; DCG_UNVERIFIED_DECISION=deny still blocks
A panic in the hook after its configuration is loaded and before a shell command is known to be allowed	The unverified-command response for the request's protocol (ask, or deny under unverified_decision = "deny")	Always blocking

Configurable Strictness:

Raw hook-envelope fail-open behavior and embedded-code fallback behavior are configured independently.

For heredoc/inline-script analysis specifically:

[heredoc]
fallback_on_parse_error = false  # Block on heredoc parse errors
fallback_on_timeout = false      # Block on heredoc timeouts

For the top-level hook input (the JSON dcg reads from stdin), enable fail-closed mode so that input which cannot be parsed at all is blocked instead of allowed:

[general]
fail_closed = true   # Deny when the hook input itself is unparseable

or at runtime:

DCG_FAIL_CLOSED=1   # env var overrides the config value

For the two unverified outcomes (evaluation deadline expired, or command over max_command_bytes), the default ask presumes a human is present to answer. On unattended or autonomous sessions there is no such human, and anything auto-answering prompts would approve exactly the commands dcg declined to inspect. Opt those sessions into denial instead:

[general]
unverified_decision = "deny"   # refuse what could not be inspected

or at runtime with DCG_UNVERIFIED_DECISION=deny. The denial reason is actionable (shrink or split the command; raise hook_timeout_ms / max_command_bytes after review), and ordinary verified commands are unaffected. A repository .dcg.toml may set unverified_decision = "deny" (tightening) but never relax an operator's deny back to ask.

A payload that itself declares "permission_mode": "bypassPermissions" or "dontAsk" gets the deny posture automatically: Claude Code documents that a hook deny holds in those modes, but not what a hook ask does there. Only an explicit DCG_UNVERIFIED_DECISION=ask overrides this.

The default is fail-open (unparseable input is allowed) and is unchanged unless you opt in. With fail-closed enabled, a genuinely unparseable hook payload produces a deny (a permissionDecision: deny for Claude-style hooks; a "decision":"deny" line plus a non-zero exit for dcg hook --batch). Transient IO read errors still fail open even in this mode, since they are not attacker-controlled malformed payloads.

Even under the fail-open default, an unparseable, oversized or non-UTF-8 payload is not allowed blind: dcg scans the raw text for a shell tool's "command" value and evaluates it. A command that would be denied (or asked about) gets that answer; only a payload with no evaluable shell command, or one whose command is allowed, falls through to the fail-open allow. Unpaired UTF-16 surrogate escapes (\ud800), which JavaScript hosts can emit, are replaced with U+FFFD before parsing rather than failing it.

A leading UTF-8 BOM (EF BB BF) is stripped before parsing in all hook paths, so a BOM-prefixed but otherwise-valid command is correctly evaluated (and blocked if dangerous) rather than allowed through as "unparseable".

With strict mode enabled, dcg blocks malformed attacker-controlled hook input and reports why. Separately, when heredoc parsing cannot complete and fallback is enabled, dcg runs a lightweight bounded check over the original command:

static FALLBACK_PATTERNS: LazyLock<RegexSet> = LazyLock::new(|| {
    RegexSet::new([
        r"shutil\.rmtree",
        r"os\.remove",
        r"fs\.rmSync",
        r"\brm\s+-[a-zA-Z]*r[a-zA-Z]*f",
        r"\bgit\s+reset\s+--hard\b",
        // ... other critical patterns
    ])
});

This fallback is specific to embedded-code extraction. It is not used for a raw hook envelope that could not be parsed, and it does not turn a deadline or an oversized extracted command into an allow.

Absolute Evaluation Deadline:

To prevent any single command from blocking indefinitely, dcg enforces an end-to-end evaluation deadline. The ordinary default is 1000ms; the careful_company_running_windows preset defaults to 3000ms, and an explicit general.hook_timeout_ms or DCG_HOOK_TIMEOUT_MS overrides either default (values below 10ms are clamped to that safety minimum). Exhausting that budget produces an explicit indeterminate result, which requests operator review where the hook protocol supports it and otherwise blocks.

The deadline intentionally uses monotonic wall-clock time. A CPU-time budget would stop advancing while dcg was descheduled or waiting on a bounded operation, so it could not guarantee hook latency. On a heavily loaded host, increase hook_timeout_ms and use dcg test --enforce-budget to exercise the same evaluator-side budget outside a live hook.

Installation

Quick Install (Recommended)

The easiest way to install is using the install script, which downloads a prebuilt binary for your platform:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash -s -- --easy-mode

Easy mode auto-detects your platform, downloads the right binary, verifies SHA256 checksums, configures all supported AI agent hooks and bridges (Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor IDE, Hermes Agent, Posit Assistant, Oh My Pi, OpenCode, Crush, Reasonix, Factory Droid, Aider), and updates your PATH. For Codex CLI 0.125.0+, the installer merges a PreToolUse Bash hook into ~/.codex/hooks.json; invalid JSON or malformed existing Codex hook shapes are left unchanged and reported instead of being overwritten.

Homebrew

The upstream tap supports Apple Silicon and Intel macOS plus ARM64 and x86_64 Linux:

brew install dicklesworthstone/tap/dcg
dcg install

Homebrew installs only the dcg binary. The explicit dcg install step configures hooks for the coding agents detected on your machine; the formula does not mutate hook or configuration files during package installation.

If your Homebrew installation enforces tap trust, trust this formula before installing it:

brew trust --formula dicklesworthstone/tap/dcg
brew install dicklesworthstone/tap/dcg
dcg install

Manual install (no curl | bash)

Every release archive is signed, so you can verify it yourself and never run the installer script:

V=v0.15.0; T=aarch64-apple-darwin   # or x86_64-unknown-linux-musl, etc.
curl -fLO "https://github.com/Dicklesworthstone/destructive_command_guard/releases/download/$V/dcg-$T.tar.xz"
curl -fLO "https://github.com/Dicklesworthstone/destructive_command_guard/releases/download/$V/dcg-$T.tar.xz.minisig"
minisign -Vm "dcg-$T.tar.xz" -P RWSoYi6NXJWzaRs1mJmOwwXrZfPWcq6MXnQlNMLBYKzlIQTLwuVQG6uO
tar -xJf "dcg-$T.tar.xz" && install -m 0755 dcg ~/.local/bin/dcg
dcg install   # configure agent hooks

Each archive also has a .sha256 and a .sigstore.json bundle. Verify the bundle with cosign verify-blob --new-bundle-format --key <pub> --bundle dcg-$T.tar.xz.sigstore.json dcg-$T.tar.xz, where <pub> is the key pinned as COSIGN_RELEASE_PUBLIC_KEY in install.sh.

Other options:

Interactive mode (prompts for each step; prompts read your terminal via /dev/tty, so they work even when the script is piped through bash. With no terminal at all — e.g. CI — the installer proceeds with safe defaults and prints each decision it makes):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash

Install specific version:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash -s -- --version v0.7.6

Install to /usr/local/bin (system-wide, requires sudo):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | sudo bash -s -- --system

Build from source instead of downloading binary:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash -s -- --from-source

Download/install only (skip agent hook configuration):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)" | bash -s -- --no-configure

Note: If you have gum installed, the installer will use it for fancy terminal formatting.

The installer verifies each adjacent .minisig with the embedded release public key when minisign is available. A present but invalid signature is always fatal; --require-minisign also makes a missing sidecar or verifier fatal. The pinned key ID for current releases is 69B3955C8D2E62A8; the retired 36B847D11BA5A0D0 key is accepted only when installing v0.6.7. Trusted Sigstore cosign bundles are checked independently against either the pinned local-release public key or the repository's GitHub Actions OIDC identity, and the SHA256 checksum remains mandatory. Cosign versions affected by CVE-2026-22703 are not trusted. The installer falls back to building from source if no prebuilt is available and removes the legacy Python predecessor (git_safety_guard.py) if present.

• Aider: No PreToolUse-style interception. The installer enables git-commit-verify: true in ~/.aider.conf.yml so git hooks run. For full protection, install dcg as a git pre-commit hook.
• Continue: No shell command interception hooks. The installer detects Continue but cannot auto-configure protection. Use a git pre-commit hook instead.
• Codex CLI: PreToolUse hooks via ~/.codex/hooks.json (stable in Codex 0.125.0+; the codex_hooks feature is on by default). dcg detects Codex from the turn_id stdin field and emits the minimal documented hookSpecificOutput deny JSON with exit code 0; dcg-only metadata is omitted so Codex's strict parser accepts the decision. The Unix installer and install.ps1 both merge dcg's hook into the existing hooks object, detect an already-current dcg hook exactly, leave invalid JSON or malformed hook shapes untouched, and surface the failure reason in the install summary. After installation, open Codex's /hooks UI once to trust the hook. uninstall.sh and uninstall.ps1 remove only dcg-owned Codex hooks and preserve coexisting entries. See the Codex integration notes. Caveats: the model can still write scripts to disk to bypass hook-based blocking; and Codex's PreToolUse hooks do not yet intercept every unified_exec shell path, so treat it as a guardrail rather than a complete enforcement boundary.
• GitHub Copilot CLI: The installer writes a user-level hook to ${COPILOT_HOME:-~/.copilot}/hooks/dcg.json, protecting every workspace. The generated preToolUse hook covers both Unix bash and Windows powershell payloads and emits Copilot's exact top-level permission-decision JSON.
• VS Code Copilot Chat: Current VS Code releases load by default, so the Claude Code hook installed by dcg also protects Copilot Chat without a second bridge or duplicate hook. dcg recognizes VS Code's documented shell tool plus the observed compatibility names and , reads , and returns VS Code's documented deny. The newer Copilot (and the Agents window built on it) sends a batched envelope instead — with JSON-encoded argument strings; dcg evaluates every shell entry in the batch independently and a single destructive entry denies the request (#252). Agent hooks are still a VS Code preview feature and can be disabled by organization policy; use or the output channel to confirm that the hook loaded.

Recommended: After installing, run dcg setup to add a shell startup check that warns you if the dcg hook is ever silently removed from ~/.claude/settings.json.

From source (Rust 1.95+; pinned nightly recommended)

The locked dependency graph requires Rust 1.95 or newer. Release builds use the repository's known-good nightly-2026-08-25 pin; the included rust-toolchain.toml selects it automatically inside a checkout.

# Install the release toolchain if you don't have it
rustup toolchain install nightly-2026-08-25

# Install the tagged source reproducibly
cargo +nightly-2026-08-25 install --locked --git https://github.com/Dicklesworthstone/destructive_command_guard --tag v0.7.6 destructive_command_guard

Manual build

git clone https://github.com/Dicklesworthstone/destructive_command_guard
cd destructive_command_guard
# rust-toolchain.toml automatically selects the pinned release nightly
cargo build --release
cp target/release/dcg ~/.local/bin/

Updating

Run the built-in updater to re-run the installer for your platform:

dcg update

Optional flags mirror the installer scripts (examples):

dcg update --version v0.7.6
dcg update --system
dcg update --verify
dcg update --verify --no-configure  # binary only; preserve existing hook wiring

You can always re-run install.sh / install.ps1 directly if preferred.

Local builds, pinning, and update refusal (#320)

For most tools, being overwritten by the official release is the right outcome. For a guard it is not necessarily: a locally built binary may carry coverage the published release does not have yet, and replacing it silently downgrades protection. dcg therefore embeds build provenance at compile time (git describe --tags --dirty, shown as a Commit: line in dcg --version, plus the full commit object id shown as Git SHA:; release pipelines additionally set an explicit DCG_RELEASE_BUILD=1 marker) and uses it three ways:

• dcg update refuses early — before any network or installer work — when the installed binary is a local build ahead of its release tag, or when the install is pinned. The explicit escape hatch is dcg update --replace-local-build.
• An opt-in pin: general.update_pin = true (or DCG_UPDATE_PIN=1) makes the refusal unconditional and also suppresses the background "update available" nudge, so dcg stops advertising an action it will then refuse.
• A doctor check (build_provenance, warning-only): flags an unpinned local build ahead of its release tag — precisely the state that is one routine dcg update away from silent loss — and recommends the pin.

Builds without git metadata (e.g. cargo install from a registry tarball) have unknown provenance; only the pin applies to them.

Prebuilt Binaries

Prebuilt binaries are available for:

• Linux x86_64, statically linked with musl (x86_64-unknown-linux-musl)
• Linux ARM64 (aarch64-unknown-linux-gnu)
• macOS Intel (x86_64-apple-darwin)
• macOS Apple Silicon (aarch64-apple-darwin)
• Windows x64 (x86_64-pc-windows-msvc)
• Windows ARM64 (aarch64-pc-windows-msvc)

Download from GitHub Releases and verify the SHA256 checksum. Starting with v0.7.5, each manually published artifact has an adjacent .minisig, verifiable with the DSR-managed public key (key ID 69B3955C8D2E62A8). The installers do this automatically when minisign is installed; pass --require-minisign on Unix or -RequireMinisign on Windows to require that verification path. The v0.6.7 manual release used the retired key 36B847D11BA5A0D0; installer trust is explicitly scoped to that version.

minisign -Vm dcg-<target>.<archive> \
  -x dcg-<target>.<archive>.minisig \
  -P 'RWSoYi6NXJWzaRs1mJmOwwXrZfPWcq6MXnQlNMLBYKzlIQTLwuVQG6uO'

Release artifacts may also include a Sigstore bundle (.sigstore.json) for verification with cosign verify-blob. Workflow builds bind that bundle to the repository's GitHub Actions OIDC identity; local DSR builds use a pinned self-managed cosign key (public-key DER SHA256 fingerprint 0e6947743daf39d6413cb25f6c96601427e38885f3a756e9f98f37d66e6df7a4). The installers accept either trust path, require cosign 2.6.2+/3.0.4+, and still require the per-artifact SHA256 checksum.

Uninstalling

Remove dcg and all its hooks from AI agents:

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/uninstall.sh | bash

On Windows:

irm https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/uninstall.ps1 | iex

The Unix uninstaller:

• Removes dcg hooks and marker-owned bridges from Claude Code, Codex CLI, Cursor IDE, Gemini CLI, GitHub Copilot CLI (user-level plus legacy repo-local), Hermes Agent, Posit Assistant, OpenCode, Oh My Pi, Crush, Reasonix, Factory Droid (through the installed DCG binary), and Aider
• Removes the dcg binary
• Removes configuration (~/.config/dcg/) and history (the history.db SQLite files in ~/.config/dcg/ or ${XDG_STATE_HOME:-~/.local/state}/dcg/, plus ~/.local/share/dcg/)
• Prompts for confirmation before making changes

The PowerShell uninstaller removes the Windows dcg.exe binary, the exact User PATH entry added by install.ps1, dcg hooks or marker-owned extensions from Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor IDE, Hermes Agent, Posit Assistant, Oh My Pi, Grok, and Antigravity (agy), plus dcg configuration/history from native %APPDATA% / %LOCALAPPDATA% and any legacy ~/.config / ~/.local/share locations.

Options:

• --yes - Skip confirmation prompt
• --keep-config - Preserve configuration files
• --keep-history - Preserve history database
• --purge - Remove everything (overrides keep flags)

Claude Code Configuration

DCG uses $CLAUDE_CONFIG_DIR/settings.json when CLAUDE_CONFIG_DIR is set and non-empty; otherwise it uses ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json). This applies to dcg install, dcg uninstall, dcg doctor, dcg setup, hook self-healing, the shell startup check, and the Bash and PowerShell installers. XDG_CONFIG_HOME does not override this choice. The Claude Code environment-variable reference documents CLAUDE_CONFIG_DIR as the user configuration directory override.

Use the same environment for Claude Code and DCG when installing or checking a separate profile. For example:

export CLAUDE_CONFIG_DIR="$HOME/.nightforge/claude"
dcg install
dcg doctor --strict

In PowerShell, set $env:CLAUDE_CONFIG_DIR = "$HOME\.nightforge\claude" before running the same DCG commands or the installer. A leading ~, ~/, or native Windows ~\ is expanded to the user's home; relative paths are resolved from the command's current directory. Prefer an absolute path when starting sessions in different workspaces. An unset or empty value preserves the default location. Only the selected user settings are changed, with unrelated keys and hooks preserved. Project installation with --project continues to use <repo>/.claude/settings.json.

Doctor reports the settings path it checked in both human-readable and JSON output. A hook in the default directory cannot satisfy the check for a different active directory: dcg doctor --strict fails until the selected settings have a valid hook. dcg doctor --fix repairs that selected file.

Grok's Claude compatibility layer continues to read ~/.claude/settings.json and does not honor CLAUDE_CONFIG_DIR; doctor checks that default file separately. Other integrations keep their own configuration locations. For Grok with an alternate Claude configuration, prefer dcg install --grok. Self-healing also uses the identified host's settings: an invocation from another recognized host does not repair the relocated Claude configuration merely because it inherited CLAUDE_CONFIG_DIR.

For a manual installation, add the following to the active settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell|Monitor",
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/dcg"
          }
        ]
      }
    ]
  }
}

Replace /absolute/path/to/dcg with the exact output of command -v dcg. Never register a safety hook as bare dcg: agent hooks run under a non-interactive shell whose PATH may omit ~/.local/bin, causing the hook to fail open. On native Windows, let install.ps1 write the PowerShell-safe absolute invocation (& 'C:\...\dcg.exe' plus "shell": "powershell").

Claude Code exposes Bash, PowerShell, and Monitor tools that can execute shell commands. Monitor runs its command as a POSIX shell script; its commandless WebSocket (ws) mode needs no command evaluation. The native PowerShell installer also runs dcg through an explicitly selected PowerShell hook shell; this prevents Git Bash from stripping backslashes out of an absolute C:\...\dcg.exe path. Re-running the installer migrates a legacy dcg hook while preserving unrelated hooks under their original matchers.

Important: Restart Claude Code after adding the hook configuration.

The matcher is a regex over the tool name and must cover all three tools: omitting PowerShell or Monitor leaves their commands unguarded. dcg install, the installers, dcg doctor --fix, and hook self-healing all write Bash|PowerShell|Monitor and migrate pre-existing Bash or Bash|PowerShell dcg entries without adding duplicate hooks or widening unrelated matchers.

Codex CLI Configuration

Codex CLI 0.125.0+ supports stable PreToolUse hooks. The installer writes or merges this automatically, but the manual configuration lives at ~/.codex/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/absolute/path/to/dcg"
          }
        ]
      }
    ]
  }
}

Codex denials intentionally omit dcg's extended Claude-only fields: dcg exits 0 with the minimal documented hookSpecificOutput JSON on stdout. Allowed commands stay silent with exit code 0.

Gemini CLI Configuration

Add to ~/.gemini/settings.json:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command",
        "hooks": [
          {
            "name": "dcg",
            "type": "command",
            "command": "/absolute/path/to/dcg",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Important: Restart Gemini CLI after adding the hook configuration.

Crush Configuration

dcg install --crush does this for you (and dcg uninstall --crush undoes it). By hand, add to ~/.config/crush/crush.json (or a project crush.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "name": "dcg",
        "matcher": "^bash$",
        "command": "/absolute/path/to/dcg",
        "timeout": 5
      }
    ]
  }
}

Crush pipes the tool call to dcg's stdin as {"event":"PreToolUse","tool_name":"bash","tool_input":{"command":"…"}} and reads {"decision":"deny","reason":"…"} back on exit 0. Allowed commands stay silent (Crush's normal permission prompt still applies — dcg never pre-approves). Start a new Crush session after editing the config. See docs/crush-integration.md.

Factory Droid Configuration

Run dcg install --droid for user-wide protection, or add --project for the current project (the Git root when present, otherwise the current directory). The installer registers the case-sensitive Execute tool with an absolute DCG path and --agent droid, preserves unrelated hooks and settings, and honors Factory's standalone hook-file precedence. A fresh install uses .factory/settings.json; an existing .factory/hooks.json is updated using its unwrapped event-map format. dcg uninstall --droid removes user registrations; add --project to remove project registrations.

Start a new Droid session and inspect /hooks after installation. dcg doctor checks the registration, and [agents.droid] configures agent-specific policy. Destructive tool_input.command values receive the same evaluation as other supported shell tools, with a Claude-compatible JSON denial. Hook loading has had version-specific regressions, and nested Execute calls inside Droid's Script tool are not verified as protected. See Factory Droid integration and verification for configuration locations, diagnostics, and a safe procedure to establish live coverage on your version.

Reasonix Configuration

dcg install --reasonix does this for you (and dcg uninstall --reasonix undoes it). By hand, add to <Reasonix home>/settings.json, or to a project .reasonix/settings.json. The home is $REASONIX_HOME if set, else ~/.reasonix, or %APPDATA%\reasonix on Windows:

{
  "hooks": {
    "PreToolUse": [
      {
        "match": "bash|pwsh",
        "command": "/absolute/path/to/dcg",
        "timeout": 5000
      }
    ]
  }
}

Reasonix pipes {"event":"PreToolUse","toolName":"bash","toolArgs":{"command":"…"}} to dcg's stdin and reads only the exit status. dcg exits 2 to block, and Reasonix shows the reason from stderr. Reasonix has no "ask" answer, so review requests block too. See docs/reasonix-integration.md.

Muse Code Configuration

dcg install --muse does this for you (and dcg uninstall --muse undoes it). By hand, add a matcher group to ${XDG_CONFIG_HOME:-~/.config}/muse/settings.json, which must declare "schema_version": 1:

{
  "schema_version": 1,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^(shell|exec_command|bash)$",
        "hooks": [
          { "type": "command", "command": "/absolute/path/to/dcg --agent muse" }
        ]
      }
    ]
  }
}

Keep --agent muse: Muse runs hooks in a cleared environment, and the flag is how dcg knows the request came from Muse (it selects [agents.muse] and fails closed on payloads it cannot read). Muse refuses the call when dcg prints a hookSpecificOutput deny; dcg prints nothing for an allowed command. Start a new Muse session after editing the file. See docs/muse-integration.md.

Amp Configuration

Amp has no hook file; dcg guards it through a plugin. dcg install --amp writes ${XDG_CONFIG_HOME:-~/.config}/amp/plugins/dcg-guard.js (or, with --project, <repo>/.amp/plugins/dcg-guard.js); dcg uninstall --amp removes the user-level file, and only if dcg wrote it. Reload Amp's plugins (Ctrl+O, then plugins: reload) or restart Amp, and check amp plugins list. The plugin rejects a destructive shell command with dcg's reason, asks through Amp's confirmation dialog when a dcg rule asks for review, and rejects any call it cannot verify. Do not edit the generated file; dcg doctor flags an edited copy and dcg install --amp restores it. See docs/amp-integration.md.

CLI Usage

While primarily designed as a hook, the binary supports direct invocation for testing, debugging, and understanding why commands are blocked or allowed.

# Show version with build metadata
dcg --version

# Show help with blocked command categories
dcg --help

# Test a command manually (pipe JSON to stdin)
echo '{"tool_name":"Bash","tool_input":{"command":"git reset --hard"}}' | dcg

Exclusive File Creation (dcg create-new)

Use create-new as a pipeline sink when the destination must be new. It opens the final path with the operating system's exclusive-create primitive, streams stdin byte-for-byte, and writes human status/errors to stderr so stdout stays empty:

producer | dcg create-new ./artifact.bin

The parent directory must already exist. The command exits non-zero without modifying anything if the destination is already a file, directory, or symlink; on Unix, a newly created file starts with private permissions (0600, subject to the process umask). A later stdin or disk error can leave the newly created path with a partial stream; create-new never removes or replaces that path.

Test Mode (dcg test)

Use dcg test to evaluate a command without executing it. This is useful for CI checks, false-positive debugging, and config validation before rollout.

Basic Usage

# Basic evaluation (human-readable output)
dcg test "rm -rf ./build"

# Structured output for automation
dcg test --format json "kubectl delete namespace prod" | jq -r .decision

# Use a specific config file
dcg test --config .dcg.prod.toml "docker system prune"

# Temporarily enable extra packs only for this test run
dcg test --with-packs containers.docker,database.postgresql "docker system prune"

# Read the candidate from stdin so it need not appear in dcg's own arguments
dcg test --stdin --format json < candidate-command.txt

# Apply the same wall-clock evaluation budget as the live hook
dcg test --enforce-budget --config .dcg.prod.toml "git status"

# Print full evaluation trace (same engine as `dcg explain`)
dcg test --explain "git reset --hard"

# Evaluate on the single dialect the Bash PreToolUse hook resolves
dcg test --dialect posix "echo 'AT&T'"

Exit Codes

• 0: command would be allowed
• 1: command would be blocked

Flags and Options

• -c, --config <PATH>: use a specific config file
• --stdin: read the candidate command from standard input; conflicts with the positional COMMAND
• --with-packs <ID1,ID2>: temporarily enable extra packs
• --explain: print detailed decision trace
• -f, --format <pretty|json|toon>: output format (default: pretty)
• --no-color: disable ANSI color output
• --heredoc-scan: force-enable heredoc/inline-script scanning
• --no-heredoc-scan: force-disable heredoc/inline-script scanning
• --heredoc-timeout <MS>: override heredoc extraction timeout budget
• --heredoc-languages <LANG1,LANG2>: limit heredoc AST scanning languages
• --enforce-budget: apply the effective live-hook wall-clock deadline (general.hook_timeout_ms, DCG_HOOK_TIMEOUT_MS, or the applicable default)
• --dialect <unknown|posix|ps|cmd> (also DCG_DIALECT): evaluate a single shell dialect instead of all of them. The default unknown fans out to every dialect because the CLI cannot know the source shell; posix reproduces the path the Bash PreToolUse hook takes and ps the PowerShell one (a Codex Bash payload on native Windows is evaluated as ps when it cannot parse as POSIX and as unknown otherwise — see docs/codex-integration.md). Use it when a diagnostic must match the live hook — an all-dialect run can report costs and evaluation paths the hook never has (for example, a literal & byte defeats quick-reject only on the all-dialect route). Also available on dcg explain.

Output Formats

• pretty: human-readable output with command context, matched rule info, and suggestions
• json: structured payload for scripts/CI; includes metadata like schema_version, dcg_version, command, decision, rule/pack fields, and allowlist/agent context when present
• toon: token-efficient structured encoding of the same payload used by json (useful for agent-to-agent/tool pipelines)

CI/CD Integration Examples

Fail fast in shell pipelines:

dcg test --format json "rm -rf /" > /tmp/dcg.json
jq -e '.decision == "allow"' /tmp/dcg.json

Minimal GitHub Actions step:

- name: Validate dangerous command policy
  run: |
    ~/.local/bin/dcg test --format json "git reset --hard HEAD~1" > /tmp/dcg-test.json
    jq -e '.decision == "allow"' /tmp/dcg-test.json

Troubleshooting

• Use --format json (or DCG_FORMAT=json) for machine parsing.
• Add --no-color if logs or parsers choke on ANSI output.
• If results differ between environments, check trusted config precedence (DCG_CONFIG, user/system config) plus the enforcement-only settings accepted from an automatically discovered project .dcg.toml.
• If a command is unexpectedly allowed, inspect active allowlists (dcg allowlist list) and enabled packs (dcg packs --verbose).
• For full decision traces, run dcg test --explain "<command>" (or dcg explain "<command>").

Explain Mode

When you need to understand exactly why a command was blocked (or allowed), the dcg explain command provides a detailed trace of the decision-making process:

# Explain why a command is blocked
dcg explain "git reset --hard HEAD"

# Explain a safe command
dcg explain "git status"

# Explain with verbose timing information
dcg explain --verbose "rm -rf /tmp/build"

# Output as JSON for programmatic use
dcg explain --format json "kubectl delete namespace production"

JSON output is versioned via schema_version (currently 4). v2 added matched_span, matched_text_preview, and explanation in the match object when a pattern is detected. v3 added the conservative indeterminate decision. v4 added mode and outcome.

decision is the evaluator's finding; outcome is what the hook does. A rule set to warn, ask, or log in [policy.rules]/[policy.packs] still produces decision: "deny" — the pattern did match — and mode names the configured policy that decides what happens next. outcome collapses the two into the one answer to gate on:

decision	mode	outcome	Command runs?
deny	deny	deny	No
deny	ask	ask	Only after operator review
deny	warn	warn	Yes, with a warning
deny	log	log	Yes, silently recorded
allow	absent	allow	Yes
indeterminate	absent	indeterminate	No — evaluation did not finish

indeterminate is the value a consumer is most likely to forget and least able to afford forgetting. dcg emits it when the hook deadline is exhausted or a nested payload could not be fully evaluated, and it means do not run this: the guard never downgrades an unfinished evaluation to allow. Treat any unrecognised outcome the same way.

Note that dcg test --format json is a different, separately versioned surface whose decision field already carries the resolved outcome, so it has no outcome field. The table above describes dcg explain --format json only.

The human-readable output reports the same resolved outcome, so dcg explain, dcg test, and the live hook agree on every rule.

Example Output:

Command: git reset --hard HEAD
Normalized: git reset --hard HEAD

Decision: BLOCKED
  Pack: core.git
  Rule: reset-hard
  Reason: git reset --hard destroys uncommitted changes

Evaluation Trace:
  [  0.8μs] Quick reject: passed (contains 'git')
  [  2.1μs] Normalize: no changes
  [  5.3μs] Safe patterns: no match (checked 34 patterns)
  [ 12.7μs] Destructive patterns: MATCH at pattern 'reset-hard'
  [ 12.9μs] Total time: 12.9μs

Suggestion: Consider using 'git stash' first to save your changes.

The explain mode shows:

• Normalized command: How dcg sees the command after path normalization
• Decision: Whether the command would be blocked or allowed
• Matching rule: Which pack and pattern triggered the decision
• Evaluation trace: Step-by-step timing of each evaluation stage
• Suggestion: Actionable guidance for safer alternatives

This is invaluable for debugging false positives, understanding pack coverage, and verifying that custom allowlist entries work as expected.

Allow-Once (Temporary Exceptions)

Sometimes you need to run a blocked command temporarily without permanently modifying your allowlist. The allow-once system provides short codes:

# When a command is blocked, dcg outputs a short code
# BLOCKED: git reset --hard HEAD
# Allow-once code: 123456
# To allow this: dcg allow-once 123456

# Use the short code to create a temporary exception
dcg allow-once 123456

# The exception is consumed by the first run. To keep it for repeated runs
# until it expires:
dcg allow-once 123456 --reusable

How Allow-Once Works:

1. When dcg blocks a command, it generates a short code (currently 6 numeric digits; collisions are handled via --pick / --hash)
2. The code is tied to the exact command that was blocked
3. Running dcg allow-once <code> creates a temporary exception
4. The exception is stored in ~/.config/dcg/pending_exceptions.jsonl
5. Exceptions are consumed by their first use, or expire after 24 hours (with --reusable, they last until expiry)
6. While active, the exception allows the same command in the same directory scope

This workflow is useful for:

• One-time administrative operations that are intentionally destructive
• Migration scripts that need to reset state
• Emergency fixes where permanent allowlist changes aren't appropriate

Security Considerations:

• Short codes are derived from SHA256 (or optional HMAC-SHA256 when DCG_ALLOW_ONCE_SECRET is set)
• Codes are never logged or transmitted
• The pending exceptions file is readable only by the current user
• Expired codes are automatically cleaned up

Rebase Recovery Mode

AI coding agents routinely get stuck when git pull --rebase fails partway — unstaged-changes errors, stash-pop conflicts, interrupted rebases. The documented recovery path is almost always git checkout -- . or git restore <paths>, both of which dcg hard-blocks (core.git:checkout-discard, core.git:restore-worktree). Agents then have to stop and ask a human to run the command manually.

Rebase-recovery mode is a narrow, bounded relaxation of those two rules that only fires under a genuine recovery signal. Outside that signal the default block is unchanged.

Two complementary signals unlock recovery:

1. Active rebase state (automatic, zero-config). When .git/rebase-merge/ or .git/rebase-apply/ exists, a rebase is in progress and the discard operations are the documented recovery path. dcg detects this state and converts the deny into an allow with a [dcg] Allowing ... → rebase-recovery mode note on stderr. No permit needed.

2. Explicit permit cookie (opt-in, short-lived). When the rebase already finished but the worktree is still messy (e.g. after a bad git stash pop), run:

   dcg rebase-recover            # default ttl: 120s
   dcg rebase-recover --ttl 60   # custom ttl (max: 600s)
   

   This writes a timestamp to .dcg/rebase-recovery-permit at the repo root. For the next N seconds (or until the first matching allow, whichever comes first), git checkout -- <path> and git restore <paths> are allowed. The permit is single-shot — one successful allow consumes it — so it can't silently unblock later unrelated commands within the TTL.

Scope and safety guarantees:

• Only four rules participate: core.git:checkout-discard, core.git:checkout-ref-discard, core.git:restore-worktree, core.git:restore-worktree-explicit.
• Nothing else is affected. git reset --hard, git clean -f, git push --force, etc. stay blocked even during an active rebase or with a permit active.
• The permit is scoped to the current repo's .dcg/ directory. It does not cross repos.
• Expired permits are auto-cleaned on the next check.

Typical recovery flow:

$ git pull --rebase
# ... fails with "unstaged changes" ...
$ git stash
$ git pull --rebase        # succeeds
$ git stash pop            # leaves messy worktree
$ git checkout -- .
BLOCKED by dcg  (core.git:checkout-discard)
  ... Recovering from a failed `git pull --rebase`?
  ... Run `dcg rebase-recover` in this repo, then retry the command on its own line
  ... (a leading `cd <repo> &&` is fine; nothing else may share the line).
$ dcg rebase-recover
dcg rebase-recovery permit issued ...
$ git checkout -- .        # now allowed, permit consumed
$ git push

See issue #104 for background.

The --version output includes build metadata for debugging:

dcg 0.1.0
  Built: 2026-01-07T22:13:10.413872881Z
  Rustc: 1.94.0-nightly
Rustc release: 1.94.0-nightly
Rustc commit: 0123456789abcdef0123456789abcdef01234567
Rustc date: 2026-01-06
Rustc host: x86_64-unknown-linux-gnu
  Target: x86_64-unknown-linux-musl
  Commit: v0.1.0
Git SHA: 0123456789abcdef0123456789abcdef01234567

This metadata is embedded at compile time via vergen, making it easy to identify exactly which build is running when troubleshooting. The absolute performance certificate compares all four stable Rustc identity fields with rustc -vV. That is deliberately a native-build check: a binary cross-compiled on a different compiler host needs separate build attestation instead of weakening the exact compiler identity requirement.

Repository Scanning

While the hook protects interactive command execution, teams also need protection against destructive commands that get committed into repositories. The dcg scan command extracts executable command contexts from files and evaluates them using the same pattern engine.

What Scan Is (and Is Not)

What it is:

• An extractor-based scanner that understands executable contexts
• Uses the same evaluator as hook mode for consistency
• Supports CI integration and pre-commit hooks

What it is NOT:

• A naive grep that matches strings everywhere
• A replacement for code review
• A static analysis tool for arbitrary languages

The key difference from grep: dcg scan understands that "rm -rf /" in a comment is data, not code. It uses extractors that understand file structure (shell scripts, Dockerfiles, CI workflows, package scripts, Makefiles, Terraform, Docker Compose) to find only actually-executed commands.

Supported File Formats

dcg scan includes specialized extractors for each file format, understanding which parts contain executable commands:

File Type	Detection	Executable Contexts
Shell Scripts	*.sh, *.bash, *.zsh, *.dash, *.ksh	Non-comment executable command lines
Dockerfile	Dockerfile, Dockerfile.*, *.dockerfile	RUN instructions (shell and exec forms)
GitHub Actions	.github/workflows/*.yml, .github/workflows/*.yaml	run: fields in steps
GitLab CI	.gitlab-ci.yml, *.gitlab-ci.yml	script:, before_script:, after_script:
Azure Pipelines	azure-pipelines.yml, azure-pipelines.yaml, azure-pipelines-*.yml, azure-pipelines-*.yaml	script:, bash:, powershell:, pwsh: tasks
CircleCI	.circleci/config.yml, .circleci/config.yaml	run: steps and nested command: fields
Makefile	Makefile	Tab-indented recipe lines
package.json	package.json	scripts object values
Terraform	*.tf	provisioner blocks (local-exec, remote-exec)
Docker Compose	docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml	command:, entrypoint:, healthcheck.test: fields
PowerShell	*.ps1, *.psm1,

Context-Aware Extraction:

Each extractor understands its format's semantics:

# GitHub Actions - only 'run:' is extracted
- name: Build
  run: |                    # ← Extracted
    npm install
    npm run build
  env:
    NODE_ENV: production    # ← Skipped (not executable)

# Dockerfile - only RUN instructions
FROM node:18
COPY . /app                 # ← Skipped
RUN npm install             # ← Extracted
RUN ["node", "server.js"]   # ← Extracted (exec form)
ENV PORT=3000               # ← Skipped

# Makefile - tab-indented lines under targets
build:
	npm install             # ← Extracted (recipe line)
	npm run build           # ← Extracted
SOURCES = $(wildcard *.js)  # ← Skipped (variable assignment)

Non-Executable Context Filtering:

Extractors intelligently skip data-only sections:

• Shell: Assignment-only lines (export VAR=value)
• YAML: environment:, labels:, volumes:, variables: blocks
• Terraform: Everything outside provisioner blocks
• All formats: Comments (format-appropriate: #, //, etc.)

Quick Start

# Install the pre-commit hook
dcg scan install-pre-commit

# Or manually run on staged files
dcg scan --staged

# Scan specific paths
dcg scan --paths scripts/ .github/workflows/

# Enable extra packs for this scan without changing persistent config
dcg scan --paths scripts/ --with-packs careful_company_running_windows

Recommended Rollout Plan

Start conservative to avoid developer friction:

# Week 1-2: Warn-first with narrow scope
dcg scan --staged --fail-on error  # Only fail on catastrophic rules

Create .dcg/hooks.toml with conservative defaults:

[scan]
fail_on = "error"          # Only fail on high-confidence catastrophic rules
format = "pretty"          # Human-readable output
redact = "quoted"          # Hide sensitive strings
truncate = 120             # Shorten long commands

[scan.paths]
include = [
    ".github/workflows/**",  # Start with CI configs
    "Dockerfile",            # Container builds
    "Makefile",              # Build scripts
]
exclude = [
    "target/**",
    "node_modules/**",
    "vendor/**",
]

Gradual expansion:

1. Week 1-2: Start with workflows/Dockerfiles only, --fail-on error
2. Week 3-4: Add Makefiles and shell scripts in scripts/
3. Month 2: Add --fail-on warning after reviewing findings
4. Ongoing: Add new extractors as team confidence grows

Pre-Commit Integration

One-Command Install

dcg scan install-pre-commit

This creates a .git/hooks/pre-commit that runs dcg scan --staged.

Manual Setup

If you prefer manual control or use a hook manager:

#!/bin/bash
# .git/hooks/pre-commit (or equivalent for your hook manager)

set -e

# Run dcg scan on staged files
dcg scan --staged --fail-on error

# Add other hooks below...

Uninstall

dcg scan uninstall-pre-commit

This only removes hooks installed by dcg (detected via sentinel comment).

Interpreting Findings

The output includes:

scripts/deploy.sh:42:5: [ERROR] core.git:reset-hard
  Command: git reset --hard HEAD
  Reason: git reset --hard destroys uncommitted changes
  Suggestion: Consider using 'git stash' first to save changes.

• File:Line:Col: Location in the source file
• Severity: ERROR (catastrophic) or WARNING (concerning)
• Rule ID: Stable identifier like core.git:reset-hard
• Command: The extracted command (may be redacted/truncated)
• Reason: Why this command is flagged
• Suggestion: How to make it safer

Fixing Findings

Option 1: Change the Code (Preferred)

Replace the dangerous command with a safer alternative:

# Instead of:
git reset --hard

# Use:
git stash push -m "before reset"
git reset --hard

Option 2: Understand with Explain

Get detailed analysis:

dcg explain "git reset --hard HEAD"

Option 3: Allowlist (When Intentional)

If the command is genuinely needed:

# User-owned exception scoped to this checkout
repo_root=$(git rev-parse --show-toplevel)
dcg allowlist add core.git:reset-hard --reason "Required for CI cleanup" \
  --user --path "$repo_root" --path "$repo_root/**"

# Or for a specific command
dcg allowlist add-command "rm -rf ./build" --reason "Build cleanup" \
  --user --path "$repo_root" --path "$repo_root/**"

The finding output includes a copy-paste allowlist command for convenience. Heredoc rules use stable IDs like heredoc.python.shutil_rmtree.

Privacy and Redaction

Scan supports redaction of potentially sensitive content in output. Use --redact quoted to hide quoted strings that may contain secrets:

# Original command:
curl -H "Authorization: Bearer $TOKEN" https://api.example.com

# With --redact quoted:
curl -H "..." https://api.example.com

Options:

• --redact none: Show full commands (default)
• --redact quoted: Hide quoted strings (recommended for CI logs)
• --redact aggressive: Hide more potential secrets

Configuration Reference

.dcg/hooks.toml (project-level, committed):

[scan]
# Exit non-zero when findings meet this threshold
fail_on = "error"      # Options: none, warning, error

# Output format
format = "pretty"      # Options: pretty, json, markdown

# Maximum file size to scan (bytes)
max_file_size = 1000000

# Stop after this many findings
max_findings = 50

# Redaction level for sensitive content
redact = "quoted"      # Options: none, quoted, aggressive

# Truncate long commands (chars; 0 = no truncation)
truncate = 120

[scan.paths]
# Only scan files matching these patterns
include = [
    "scripts/**",
    ".github/workflows/**",
    "Dockerfile*",
    "Makefile",
]

# Skip files matching these patterns
exclude = [
    "target/**",
    "node_modules/**",
    "*.md",
]

CLI flags override config file values.

CI Integration

GitHub Actions

name: Security Scan
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install dcg
        run: |
          curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh" | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Scan changed files
        run: |
          dcg scan --git-diff origin/${{ github.base_ref }}..HEAD \
            --format markdown \
            --fail-on error

GitLab CI

scan:
  stage: test
  script:
    - curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh" | bash
    - ~/.local/bin/dcg scan --git-diff origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD --fail-on error
  rules:
    - if: $CI_MERGE_REQUEST_ID

Bypass for Emergencies

If you need to bypass the pre-commit hook temporarily:

git commit --no-verify -m "Emergency fix"

This is logged and visible in git history. For permanent exceptions, use allowlists instead.

How It Works

Your AI agent invokes dcg as a PreToolUse hook before executing each shell command. The hook receives the command as JSON on stdin and runs through a four-stage pipeline:

1. JSON Parsing -- Validates the hook payload (Claude/Gemini/Copilot variants), extracts the command string. Non-shell tools are immediately allowed.
2. Normalization -- Builds a detection view by stripping recognized wrappers, environment assignments, and executable paths (/usr/bin/git becomes git), while retaining the original command and execution context for safe exemptions.
3. Quick Reject -- Searches command text and resolved executable names for pack keywords such as "git" or "rm". Original text remains available to custom policies, including keywords in environment assignments removed from the detection view.
4. Pattern Matching -- Checks safe exemptions in their original execution context before the relevant pack's destructive rules. Destructive matching retains the normalized view so wrappers cannot hide dangerous commands. An exemption is scoped to its pack and command segment; other packs and segments still undergo evaluation. Commands without a destructive match are allowed.

If blocked under a Claude-compatible JSON hook protocol, dcg outputs a JSON denial on stdout and a colorful human-readable warning on stderr. If blocked under Codex CLI, dcg follows Codex's strict hook contract with minimal stdout JSON and exit code 0. If allowed, dcg exits silently. Rich formatting is automatically disabled for CI, non-TTY output, dumb terminals, and no-color environments.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│   Claude / Codex / Gemini / Copilot / Cursor / Hermes hooks      │
│                                                                  │
│  User: "delete the build artifacts"                             │
│  Agent: executes `rm -rf ./build`                               │
│                                                                  │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼ PreToolUse hook (stdin: JSON)
┌─────────────────────────────────────────────────────────────────┐
│                     dcg                             │
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
│  │    Parse     │───▶│  Normalize   │───▶│ Quick Reject │       │
│  │    JSON      │    │   Command    │    │   Filter     │       │
│  └──────────────┘    └──────────────┘    └──────┬───────┘       │
│                                                  │               │
│                      ┌───────────────────────────┘               │
│                      ▼                                           │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Pattern Matching                        │   │
│  │                                                           │   │
│  │   1. Check SAFE_PATTERNS (whitelist) ──▶ Allow if match  │   │
│  │   2. Check DESTRUCTIVE_PATTERNS ──────▶ Deny if match    │   │
│  │   3. No match ────────────────────────▶ Allow (default)  │   │
│  │                                                           │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────┬───────────────────────────────────────────┘
                      │
                      ▼ stdout: JSON deny / empty allow
                        stderr: rich human output / Codex deny reason
┌─────────────────────────────────────────────────────────────────┐
│   Claude / Codex / Gemini / Copilot / Cursor / Hermes hooks      │
│                                                                  │
│  If denied: Shows block message, does NOT execute command       │
│  If allowed: Proceeds with command execution                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Context Classification System

Not every occurrence of a dangerous pattern is actually dangerous. The string git reset --hard appearing in a comment, a heredoc body, or a quoted string is fundamentally different from the same string appearing as an executed command. dcg uses a sophisticated context classification system to reduce false positives without compromising safety.

SpanKind Classification

Every token in a command is classified into one of these categories:

SpanKind	Description	Treatment
Executed	Command words and unquoted arguments	MUST check - highest priority
InlineCode	Content inside -c/-e flags (bash -c, python -c)	MUST check - code will be executed
Argument	Quoted arguments to known-safe commands	Lower priority, context-dependent
Data	Single-quoted strings (shell cannot interpolate)	Can skip - treated as literal data
HeredocBody	Content inside heredocs	Escalated to Tier 2/3 heredoc scanning
Comment	Shell comments (# ...)	Skip - never executed
Unknown	Cannot determine context	Conservative treatment as Executed

Why Context Matters

Consider these commands:

# Safe: the dangerous pattern is in a comment
echo "Reminder: never run git reset --hard"   # git reset --hard destroys changes

# Safe: the dangerous pattern is data being searched for
grep "git reset --hard" documentation.md

# Safe: the dangerous pattern is in a heredoc being written to a file
cat <<EOF > safety_guide.md
Warning: git reset --hard destroys uncommitted changes
EOF

# DANGEROUS: the pattern will be executed
git reset --hard HEAD

# DANGEROUS: the pattern is passed to bash -c for execution
bash -c "git reset --hard"

Without context classification, the first three examples would trigger false positives. The context classifier analyzes the AST (abstract syntax tree) structure to understand where patterns appear and only flags genuinely dangerous occurrences.

Interpreter source and process arguments

Shell substitution analysis preserves the boundary around a quoted heredoc supplied as a program to a proven non-shell interpreter, such as python3 - <<'PY' or node - <<'JS'. JavaScript backticks and other source bytes inside that body do not become outer shell substitutions. Quoted carets in Python regular expressions do not select a Windows shell dialect. The body still receives language-specific analysis and conservative destructive-pattern scanning, including Windows command evidence in opaque or aliased shell sinks. An unquoted delimiter, a rebound or wrapped interpreter, and stdin supplied to an interpreter's -c / -e command or script file retain their conservative treatment.

A plain cat <<'PY' | python3 - pipeline also preserves the consumer's language when the quoted body and both executables can be proven. The corresponding Python, JavaScript, Ruby, Perl and PHP source is not reparsed as a bare shell script. Shell consumers still receive shell analysis. Extra input files, transforming cat flags, and mutable producer lookup cannot establish a literal-source proof. Quoted shell arguments are similarly kept intact during dialect selection: the |^ in sed 's|^\./||' does not start a cmd command.

A quoted heredoc written by a plain cat > file and immediately consumed by node file, python3 file, ruby file, perl file, or php file also reaches the corresponding language checks. This bounded proof requires the same literal file path and an unmodified overwrite; an optional literal mkdir setup is supported. A script file handed to a supported POSIX shell such as bash or sh receives shell analysis. Append writes, transformations, wrappers, extra consumers and ambiguous control flow keep their conservative treatment. For a proven JavaScript file, an AST-confirmed => arrow is not a shell redirect. Shell command strings elsewhere in the source still receive the raw safety checks.

Recognized literal sed, awk 1 and tac reads before a quoted heredoc write do not make the newly written body executable. This ordering proof applies only to bounded synchronous readers in a straight-line command sequence. Later execution, including sed e, awk with system(), shell wrappers and remote consumers, still keeps the body visible to safety analysis.

Embedded process calls retain every argument position when reconstructed. For example, subprocess.run(["git", "-C", path, "diff", "HEAD"]) keeps the unknown path as the operand of -C; it cannot turn diff into that operand. Literal arguments retain quoting and unknown targets remain unknown. A spread or computed argument list with a known executable fails closed under a language-specific argv_unverified rule because its argument count cannot be proven. A wholly opaque process call retains the existing analysis posture.

Ambiguous shell substitutions carry the stable rules heredoc.posix:substitution-unverified or heredoc.powershell:substitution-unverified; substitution size and nesting limits use heredoc.shell:analysis-bounds.

Implementation Details

The context classifier uses a multi-pass approach:

1. Lexical Analysis: Identify quoted strings, comments, and heredoc markers
2. Structural Analysis: Build a tree of command structure, identifying pipes, subshells, and command substitutions
3. Flag Analysis: Detect -c, -e, and similar flags that introduce inline code contexts
4. Span Annotation: Tag each character range with its SpanKind

This approach achieves a significant reduction in false positives while maintaining the zero-false-negatives philosophy for actual command execution.

Design Principles

1. Whitelist-First Architecture

Safe patterns are checked before destructive patterns. This design ensures that explicitly safe commands (like git checkout -b) are never accidentally blocked, even if they partially match a destructive pattern (like git checkout).

git checkout -b feature    →  Matches SAFE "checkout-new-branch"  →  ALLOW
git checkout -- file.txt   →  No safe match, matches DESTRUCTIVE  →  DENY

2. Fail-Safe Defaults

The hook uses a default-allow policy for unrecognized commands. This ensures:

• The hook never breaks legitimate workflows
• Only known dangerous patterns are blocked
• New git commands are allowed until explicitly categorized

3. Zero False Negatives Philosophy

The pattern set prioritizes never allowing dangerous commands over avoiding false positives. A few extra prompts for manual confirmation are acceptable; lost work is not.

4. Defense in Depth

This hook is one layer of protection. It complements (not replaces):

• Regular commits and pushes
• Git stash before risky operations
• Proper backup strategies
• Code review processes

5. Minimal Latency

Every Bash command passes through this hook. Performance is critical:

• Lazy-initialized static regex patterns (compiled once, reused)
• Quick rejection filter eliminates 99%+ of commands before regex
• No heap allocations on the hot path for safe commands
• Sub-millisecond execution for typical commands

Pattern Matching System

Safe Patterns (Whitelist)

The safe pattern list contains narrowly scoped patterns covering:

Category	Patterns	Purpose
Branch creation	checkout -b, checkout --orphan	Creating branches is safe
Staged-only	restore --staged, restore -S	Unstaging doesn't touch working tree
Dry run	clean -n, clean --dry-run	Preview mode, no actual deletion
Temp cleanup	rm -rf /tmp/*, rm -rf /var/tmp/*	Ephemeral directories are safe
Dynamic temp roots	rm -rf $TMPDIR/*, rm -rf ${TMPDIR}/*	Blocked for review because the caller controls the variable
Quoted paths	rm -rf "/tmp/build"	Literal quoted temp paths are recognized safely
Separate flags	rm -r -f /tmp/*, rm -f -r /var/tmp/*	Flag ordering variants
Long flags	rm --recursive --force /tmp/*, /var/tmp/*	GNU-style long options

Destructive Patterns (Blacklist)

The destructive pattern list covers:

Category	Pattern	Reason
Work destruction	reset --hard, reset --merge	Destroys uncommitted changes
File reversion	checkout -- <path>	Discards file modifications
Worktree restore	restore (without --staged)	Discards uncommitted changes
Untracked deletion	clean -f	Permanently removes untracked files
History rewrite	push --force, push -f	Can destroy remote commits
Branch ref deletion/update	branch -d, branch --delete, branch -D, branch -f, branch -M, branch -C	Removes or force-overwrites a user-owned branch ref
Stash destruction	stash drop, stash clear	Permanently deletes stashed work
Filesystem nuke	rm -r, rm -R, rm --recursive (non-temp paths)	Recursive deletion outside temp, with or without --force

Pattern Syntax

Patterns use fancy-regex for advanced features:

// Negative lookahead: block restore UNLESS --staged is present
r"git\s+restore\s+(?!--staged\b)(?!-S\b)"

// Negative lookahead: don't match --force-with-lease
r"git\s+push\s+.*--force(?![-a-z])"

// Character class: match any flag ordering
r"rm\s+-[a-zA-Z]*[rR][a-zA-Z]*f[a-zA-Z]*"

Edge Cases Handled

Path Normalization

Commands may use absolute paths to binaries:

/usr/bin/git reset --hard          # Blocked ✓
/usr/local/bin/git checkout -- .   # Blocked ✓
/bin/rm -rf /home/user             # Blocked ✓

The normalizer uses regex to strip paths while preserving arguments:

git add /usr/bin/something         # "/usr/bin/something" is an argument, preserved

Flag Ordering Variants

The rm command accepts flags in many forms:

rm -rf /path          # Combined flags
rm -fr /path          # Reversed order
rm -r -f /path        # Separate flags
rm -f -r /path        # Separate, reversed
rm --recursive --force /path    # Long flags
rm --force --recursive /path    # Long flags, reversed
rm -rf --no-preserve-root /     # Additional flags

All variants are handled by flexible regex patterns.

Shell Variable Expansion

TMPDIR is controlled by the calling environment and can point anywhere. DCG therefore reviews variable-rooted destructive commands instead of assuming they resolve beneath /tmp:

rm -rf $TMPDIR/build           # Blocked: ambient root is unknown
rm -rf ${TMPDIR}/build         # Blocked: ambient root is unknown
rm -rf "$TMPDIR/build"         # Blocked even when quoted
rm -rf "${TMPDIR}/build"       # Blocked even when quoted
rm -rf "${TMPDIR:-/tmp}/build" # Blocked: environment may override default
rm -rf /tmp/build              # Allowed: literal temp subtree

Git Flag Combinations

Git commands can have flags in various positions:

git push --force                  # Blocked ✓
git push origin main --force      # Blocked ✓
git push --force origin main      # Blocked ✓
git push -f                       # Blocked ✓
git push --force-with-lease       # Allowed ✓ (safe alternative)

Staged vs Worktree Restore

The restore command has nuanced safety:

git restore --staged file.txt           # Allowed ✓ (unstaging only)
git restore -S file.txt                 # Allowed ✓ (short flag)
git restore file.txt                    # Blocked (discards changes)
git restore --worktree file.txt         # Blocked (explicit worktree)
git restore --staged --worktree file    # Blocked (includes worktree)
git restore -S -W file.txt              # Blocked (includes worktree)

Performance Optimizations

Dual Regex Engine Architecture

dcg uses a sophisticated dual-engine regex system that automatically selects the optimal engine for each pattern. This enables both guaranteed performance and advanced pattern matching features.

The Two Engines:

Engine	Crate	Time Complexity	Features	Use Case
Linear	regex	O(n) guaranteed	Basic regex, character classes, alternation	~85% of patterns
Backtracking	fancy_regex	O(2^n) worst case	Lookahead, lookbehind, backreferences	~15% of patterns

Automatic Engine Selection:

When a pattern is compiled, dcg analyzes it to determine which engine to use:

pub enum CompiledRegex {
    Linear(regex::Regex),           // O(n) guaranteed, no lookahead
    Backtracking(fancy_regex::Regex), // Supports lookahead/lookbehind
}

impl CompiledRegex {
    pub fn new(pattern: &str) -> Result<Self, Error> {
        // Try linear engine first (faster, predictable)
        if let Ok(re) = regex::Regex::new(pattern) {
            return Ok(CompiledRegex::Linear(re));
        }
        // Fall back to backtracking for advanced features
        Ok(CompiledRegex::Backtracking(fancy_regex::Regex::new(pattern)?))
    }
}

Why This Matters:

1. Performance predictability: The linear engine guarantees O(n) matching time, critical for a hook that runs on every command
2. Feature completeness: Some patterns require negative lookahead (e.g., "match --force but not --force-with-lease")
3. Automatic optimization: Pattern authors don't need to think about engine selection—dcg chooses optimally

Examples of Engine Selection:

// Linear engine (simple pattern)
r"git\s+reset\s+--hard"              // No advanced features needed

// Backtracking engine (negative lookahead)
r"git\s+push\s+.*--force(?![-a-z])"  // Must NOT be followed by "-with-lease"

// Linear engine (character classes)
r"rm\s+-[a-zA-Z]*[rR][a-zA-Z]*f"     // Complex but no lookahead

Performance Budget System

dcg operates under strict latency constraints - every shell command passes through the hook, so even small delays compound into noticeable sluggishness. src/perf.rs is the source of truth for performance budgets, CI benchmark expectations, and hook-mode deadlines.

For a structured phase breakdown of a real hook invocation, set DCG_PROFILE=1. DCG appends one DCG_PROFILE JSON line to stderr, with call counts and inclusive/exclusive wall times for request parsing, normalization, heredoc detection/extraction, pattern evaluation, AST work, and history recording. Main-thread and worker measurements are separate; worker time can overlap the hook's wait and must not be added to its total. Incomplete calls remain visible when a deadline expires. Input waiting has its own phase, and the hook total excludes process startup and CLI setup. The profile contains no command text. The existing DCG_LOG=dcg_perf=debug trace also remains available, including database open/insert events; its durations are inclusive and cannot be summed across nested or overlapping events. Disabled timers do not read the clock. See the issue #555 measurement guide for the schema, accounting rules, and security controls.

To reproduce issue #555 against a live incumbent in the same run:

python3 scripts/perf_baseline.py --bin target/release/dcg \
  --compare-bin /path/to/incumbent/dcg --warmup 3 --runs 30 \
  --history-profiles disabled,enabled,seeded,locked \
  --history-seed-rows 247625 \
  --output /tmp/dcg-hook-comparison.json
cargo bench --locked --bench heredoc_perf -- issue_555
cargo bench --locked --bench hook_latency -- issue_555

The comparison alternates incumbent/candidate order, validates every timed verdict, retains raw samples, and pairs each full hook with a bypass process. It tests 16 command shapes: ordinary and compound commands, 40/300-line executable Python and quoted data, commit-message substitutions, destructive Python at either end, nested interpreters, executable substitutions, and incomplete syntax. The command above selects four history profiles: disabled, enabled with a small database, seeded with 247,625 synthetic rows, and deliberately write-locked. Without --history-profiles, only disabled and enabled run. Each binary receives a separate database. On Unix the runner records child user+system CPU separately from wall time; instrumented probes run outside the timed samples. This diagnostic comparison is separate from the source-bound absolute latency gate, which also retains the 1/40/300-line scaling cases, and does not certify a loaded production database. CPU includes process startup; wall minus CPU is not solely storage contention. History has a background worker, but normal hook shutdown waits for it within the existing bounded budget. A quoted delimiter suppresses shell expansion; it does not stop python3 - or another interpreter executing its heredoc body.

The earlier stdin-provenance optimization avoids repeated walks for each segment when their required raw pipeline/exec-redirect bytes are absent. Possible matches retain the complete readers; no heredoc body or security rule is skipped. Its retained comparison evidence used an earlier 33-case interface (11 shapes across three history modes), before the broader AST and profiling changes described in the measurement guide. That interleaved Linux comparison on 2026-10-12 (25 measured pairs per case, 5 warmups, load average 6.3 at start, self-healing disabled) measured the following 300-line Python heredoc medians against the incumbent readers:

History mode	Incumbent wall	Candidate wall	Incumbent CPU	Candidate CPU
Disabled	106.9 ms	78.0 ms	103.6 ms	76.9 ms
Enabled, small database	124.2 ms	98.3 ms	121.0 ms	91.9 ms
Write-locked database	196.1 ms	150.9 ms	146.8 ms	117.6 ms

All 33 cases in that earlier comparison retained their expected verdicts. The 40-line case improved only modestly (36.1 to 34.9 ms with history off); short and compound commands were essentially unchanged. The bypass process floor was about 2–3 ms. Lock contention added roughly 50 ms to the short-command hook while CPU stayed near 11 ms, independently demonstrating storage wait on the normal shutdown path. These are diagnostic measurements on a changing host, not universal latencies or a reproduction of the reporter's 275 MB database. The initial run under concurrent compiler memory pressure was rejected on an unexpected ask, never counted as a successful fast allow.

Latency Tiers:

Tier	Path	Target	Warning Above	Panic Above
0	Quick reject	< 1μs	> 5μs	> 50μs
1	Fast path	< 75μs	> 150μs	> 500μs
2	Pattern match	< 100μs	> 250μs	> 1ms
3	Heredoc trigger	< 5μs	> 10μs	> 100μs
4	Heredoc extract	< 200μs	> 500μs	> 2ms
5	Language detect	< 20μs	> 50μs	> 200μs
6	Full heredoc pipeline	< 5ms	> 15ms	> 20ms

Hook mode also has an absolute wall-clock evaluation deadline (ordinary default: 1000ms; configurable). If that deadline is exhausted, dcg returns an explicit indeterminate decision: clients that support operator review receive ask, and clients without that state receive a blocking decision. A timeout never becomes a silent allow. Use dcg test --enforce-budget to apply the effective hook budget during a diagnostic test.

Bounded Evaluation Behavior:

If the absolute hook deadline is exhausted, dcg logs the event and marks the command indeterminate:

[WARN] Performance budget exceeded: Tier 2 (safe patterns) took 1.2ms (panic threshold: 500μs)
[WARN] Safety evaluation incomplete; requesting review or blocking

This design ensures that:

1. A pathological input cannot hang the user's terminal
2. Performance regressions are visible in logs
3. The tool never mistakes elapsed time for a safety proof

Budget Enforcement:

let deadline = Deadline::hook_default();

if deadline.is_exceeded() || !deadline.has_budget_for(&PATTERN_MATCH) {
    return EvaluationResult::indeterminate_due_to_budget();
}

Monitoring Performance:

Use dcg explain --verbose to see per-stage timing:

Evaluation Trace:
  [  0.3μs] Tier 0: Quick reject (PASS - below 1μs target)
  [  8.7μs] Tier 1: Fast path (PASS - below 75μs target)
  [ 15.2μs] Tier 2: Pattern match (PASS - below 100μs target)
  [ 15.4μs] Total: 15.4μs (PASS - below 5ms target)

Keyword-Based Pack Pre-filtering

Before expensive regex matching, dcg uses a multi-level keyword filtering system to quickly skip irrelevant packs. This is critical for performance—with 50+ packs available, checking every pattern against every command would be prohibitively slow.

How Keyword Filtering Works:

Each pack declares a set of keywords that must appear in a command for that pack to be relevant:

Pack {
    id: "database.postgresql".to_string(),
    keywords: &["psql", "dropdb", "createdb", "DROP", "TRUNCATE", "DELETE"],
    // ...
}

Two-Level Filtering:

1. Global Quick Reject: Before any pack evaluation, dcg checks if the command contains any keyword from any enabled pack. If not, the entire pack evaluation is skipped. A pack that declares no keywords stands this level down for the whole process, so it keeps the might_match contract below ("no keywords = always check patterns") rather than being silently skipped; dcg doctor and dcg pack validate name any pack in that state, because the cost is paid by every command.

2. Per-Pack Quick Reject: For each enabled pack, dcg checks if the command contains any of that pack's keywords before running expensive regex patterns.

Aho-Corasick Automaton:

For packs with multiple keywords, dcg builds an Aho-Corasick automaton that matches all keywords in a single O(n) pass:

// Built lazily on first pack access
pub keyword_matcher: Option<aho_corasick::AhoCorasick>,

pub fn might_match(&self, cmd: &str) -> bool {
    if self.keywords.is_empty() {
        return true; // No keywords = always check patterns
    }

    // O(n) matching regardless of keyword count
    if let Some(ref ac) = self.keyword_matcher {
        return ac.is_match(cmd);
    }

    // Fallback: sequential memchr search
    self.keywords.iter()
        .any(|kw| memmem::find(cmd.as_bytes(), kw.as_bytes()).is_some())
}

Context-Aware Keyword Matching:

Keywords are only matched within executable spans (not in comments, quoted strings, or data):

pub fn pack_aware_quick_reject(cmd: &str, enabled_keywords: &[&str]) -> bool {
    // First: fast substring check
    let any_substring = enabled_keywords.iter()
        .any(|kw| memmem::find(cmd.as_bytes(), kw.as_bytes()).is_some());

    if !any_substring {
        return true; // Safe to skip all pack evaluation
    }

    // Second: verify keyword appears in executable context
    let spans = classify_command(cmd);
    for span in spans.executable_spans() {
        if span_matches_any_keyword(span.text(cmd), enabled_keywords) {
            return false; // Must evaluate packs
        }
    }

    true // Keywords only in non-executable contexts, safe to skip
}

This approach ensures that a command like echo "psql" | grep DROP doesn't trigger PostgreSQL pack evaluation just because keywords appear in the data being processed.

1. Lazy Static Initialization

Regex patterns are compiled once on first use via LazyLock:

static SAFE_PATTERNS: LazyLock<Vec<Pattern>> = LazyLock::new(|| {
    vec![
        pattern!("checkout-new-branch", r"git\s+checkout\s+-b\s+"),
        // ... 33 more patterns
    ]
});

Subsequent invocations reuse the compiled patterns with zero compilation overhead.

2. SIMD-Accelerated Quick Rejection

Before any regex matching, a SIMD-accelerated substring search filters out irrelevant commands. The memchr crate uses CPU vector instructions (SSE2, AVX2, NEON) when available:

use memchr::memmem;

static GIT_FINDER: LazyLock<memmem::Finder<'static>> = LazyLock::new(|| memmem::Finder::new("git"));
static RM_FINDER: LazyLock<memmem::Finder<'static>> = LazyLock::new(|| memmem::Finder::new("rm"));

fn quick_reject(cmd: &str) -> bool {
    let bytes = cmd.as_bytes();
    GIT_FINDER.find(bytes).is_none() && RM_FINDER.find(bytes).is_none()
}

For commands like ls -la, cargo build, or npm install, this check short-circuits the entire matching pipeline. The memmem::Finder is pre-compiled once and reused, avoiding repeated setup costs.

3. Early Exit Within a Pack

A safe exemption skips the corresponding pack's destructive rules for the authorized command segment. Evaluation continues for other packs and shell segments, so one safe command cannot exempt a dangerous sibling.

Regex exemptions retain the original command's environment assignments, wrappers, executable paths, and redirections. For example, an exact custom safe pattern for /usr/bin/python3 -I /opt/tools/run_check.py --check does not also authorize that invocation with PATH=/somewhere prepended. Destructive patterns still inspect normalized commands, and custom destructive patterns also inspect the original command after data sanitization.

Nested commands retain their carrier's context. A custom safe grant can transfer to a nested command only when a safe pattern explicitly covers the complete original carrier as one shell segment. Earlier shell statements also prevent a later custom exemption unless they are provably neutral. See command text and safe exemptions for exact matching, unanchored patterns, and compound-command behavior.

4. Compile-Time Pattern Validation

The pattern! and destructive! macros include the pattern name in panic messages, making invalid patterns fail at first execution with clear diagnostics:

macro_rules! pattern {
    ($name:literal, $re:literal) => {
        Pattern {
            regex: Regex::new($re).expect(concat!("pattern '", $name, "' should compile")),
            name: $name,
        }
    };
}

5. Zero-Copy JSON Parsing

The serde_json parser operates on the input buffer without unnecessary copies. The command string is extracted directly from the parsed JSON value.

6. Zero-Allocation Path Normalization

Command normalization uses Cow<str> (copy-on-write) to avoid heap allocations in the common case:

fn normalize_command(cmd: &str) -> Cow<'_, str> {
    // Fast path: if command doesn't start with '/', no normalization needed
    if !cmd.starts_with('/') {
        return Cow::Borrowed(cmd);  // Zero allocation
    }
    PATH_NORMALIZER.replace(cmd, "$1")  // Allocation only when path is stripped
}

Most commands don't use absolute paths to git or rm, so this fast path avoids allocation entirely for 99%+ of inputs.

7. Release Profile Optimization

The release build uses aggressive optimization settings:

[profile.release]
opt-level = "z"     # Optimize for size (lean binary)
lto = true          # Link-time optimization across crates
codegen-units = 1   # Single codegen unit for better optimization
panic = "abort"     # Smaller binary, no unwinding overhead
strip = true        # Remove debug symbols

Example Block Message

When a destructive command is intercepted, the hook outputs a colorful warning to stderr (shown below without ANSI codes):

════════════════════════════════════════════════════════════════════════
BLOCKED  dcg
────────────────────────────────────────────────────────────────────────
Reason:  git reset --hard destroys uncommitted changes. Use 'git stash' first.

Command:  git reset --hard HEAD~1

Tip: If you need to run this command, execute it manually in a terminal.
     Consider using 'git stash' first to save your changes.
════════════════════════════════════════════════════════════════════════

Output Modes

dcg separates agent-facing data from human-facing display. This lets agents parse stable output while people watching the terminal still get readable, high-signal formatting.

Mode	Trigger	stdout	stderr
Hook allow	Safe command	Empty	Empty
JSON-hook deny	Claude Code, Gemini CLI, Copilot CLI, VS Code Copilot Chat, Posit Assistant, compatible hooks	Denial JSON	Rich or plain warning
Hermes block	Hermes Agent shell hook (pre_tool_call)	{"decision":"block","reason":...,"action":"block","message":...}	Rich or plain warning
Grok deny	Grok (xAI) PreToolUse hook (pre_tool_use event, run_terminal_cmd tool)	{"decision":"deny","reason":...} (exit 0)	Rich or plain warning
Antigravity deny	Antigravity CLI (agy) PreToolUse hook (toolCall.name: "run_command")	Only {"decision":"deny","reason":...} (exit 0)	Rich or plain warning
Antigravity warn	Antigravity CLI (agy) command with a warn policy	Empty (exit 0; ordinary permission checks remain with agy)	Rich or plain warning
Codex deny	Codex CLI 0.144.x hook input	Minimal hookSpecificOutput deny JSON	Deny reason with command, rule, and remediation
Robot mode	--robot or DCG_ROBOT=1	JSON	Silent
Plain fallback	DCG_NO_RICH=1, NO_COLOR=1, DCG_NO_COLOR=1, TERM=dumb, CI=1, non-TTY output, or --legacy-output	Mode-specific data	Plain text only

Rich Human Output

Rich output is for humans and always belongs on stderr. It includes the blocked command, severity, rule id, pack id, explanation, and safer alternatives when available:

BLOCKED  dcg
Reason:  git reset --hard destroys uncommitted changes
Rule:    core.git:reset-hard
Command: git reset --hard HEAD~1
Tip:     Use git stash to save your changes first.

Plain and No-Color Output

Use plain output for logs, terminals with limited capabilities, or tests that assert exact strings:

DCG_NO_RICH=1 dcg test "git reset --hard HEAD"
NO_COLOR=1 dcg explain "rm -rf ./build"
TERM=dumb dcg scan .

Build Features

Rich terminal output is enabled by default. For a lean build without the rich_rust dependency, compile with:

cargo build --release --no-default-features

Agent JSON Output

For automation, prefer robot mode or the hook protocol your agent expects:

# Robot-mode scripting: parse stdout JSON, ignore stderr.
dcg --robot test "rm -rf /" >decision.json 2>/dev/null

# Claude-compatible hook integration: parse stdout only when non-empty.
dcg < hook-input.json >hook-output.json 2>human-warning.txt

Codex integrations should parse the minimal stdout JSON; empty stdout with exit code 0 means allow.

Suggestion System

dcg doesn't just block commands—it provides actionable guidance to help users make safer choices. The suggestion system generates context-aware recommendations based on the specific command that was blocked.

Suggestion Categories:

Category	Purpose	Example
PreviewFirst	Run a dry-run/preview command first	"Run git clean -n first to preview deletions"
SaferAlternative	Use a safer command that achieves similar goals	"Use --force-with-lease instead of --force"
WorkflowFix	Fix the workflow to avoid the dangerous operation	"Commit your changes before resetting"
Documentation	Link to relevant documentation	"See man git-reset for reset options"
AllowSafely	How to allowlist if the operation is intentional	"Add to allowlist: dcg allowlist add core.git:reset-hard"

Contextual Suggestions by Command Type:

Command Type	Suggestion
git reset, git checkout --	"Consider using 'git stash' first to save your changes."
git clean	"Use 'git clean -n' first to preview what would be deleted."
git push --force	"Consider using '--force-with-lease' for safer force pushing."
rm -rf	"Verify the path carefully before running rm -rf manually."
kubectl delete	"Use kubectl delete --dry-run=client to preview deletions."
docker system prune	"Run with --dry-run first to see what would be removed."
DROP TABLE	"Consider TRUNCATE if you only need to remove data, not the schema."

Custom Suggestions in Packs:

Each destructive pattern can specify its own suggestion tailored to the specific operation:

destructive_pattern!(
    "restic-forget",
    r"restic(?:\s+--?\S+(?:\s+\S+)?)*\s+forget\b",
    "restic forget removes snapshots and can permanently delete backup data.",
    suggestion: "Run 'restic snapshots' first to review what would be affected."
)

This approach ensures that suggestions are always relevant to the specific context, not generic warnings.

Simultaneously, the hook outputs JSON to stdout for the Claude Code protocol:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "BLOCKED by dcg\n\nReason: ..."
  }
}

Security Considerations

What This Protects Against

• Accidental data loss: AI agents running git checkout -- or git reset --hard on files with uncommitted changes
• Remote history destruction: Force pushes that overwrite shared branch history
• Stash loss: Dropping or clearing stashes containing important work-in-progress
• Filesystem accidents: Recursive deletion outside designated temp directories

Inherent Limitations

While dcg provides comprehensive protection across many tools and platforms, some attack vectors are inherently difficult or impossible to protect against:

• Malicious actors: A determined attacker can bypass this hook

• Non-Bash commands: Direct file writes via Python/JavaScript, API calls, etc. are not intercepted

• Committed but unpushed work: The hook doesn't prevent loss of local-only commits

• Bugs in allowed commands: A git commit that accidentally includes wrong files

• Commands in scripts: If an agent runs ./deploy.sh, we don't inspect what's inside the script

• Dynamic stdin producers for protected REPL binaries (#191): dcg traces bounded literal echo/printf pipelines, single-file cat pipelines, < file redirects, and literal command substitutions into redis-cli, psql, mysql/mariadb, mongosh/mongo, and sqlite3; the reconstructed payload is evaluated by the consumer's own pack. It deliberately does not execute arbitrary producers to discover their output. An unknown/dynamic producer, missing or non-regular file, non-UTF-8 file, or payload over 256 KiB therefore fails closed as the stable high-severity rule <pack>:stdin-unverified (which can be explicitly allowlisted after review) instead of silently recreating the bypass. Direct arguments, heredocs, and here-strings remain covered by their existing paths. kubectl delete -f - / --filename=- is blocked directly unless it is a genuine client/server dry-run.

• Files opened after a wrapper changes the execution environment: recognized directory, user, and home/environment changes (such as env -C other, sudo -D other, sudo -u other, or env HOME=...) invalidate the caller's local file evidence. A benign local migration.sql cannot clear env -C other psql -X -f migration.sql; the guarded database client reports <pack>:stdin-unverified because the file it will open has not been verified. The same boundary applies to file-producing commands, database includes and shell escapes, PostgreSQL startup files, and sed program files (core.filesystem:sed-exec-unverified). Literal payloads still receive normal destructive-command analysis. The caller's own substitution or redirect retains its local source meaning, but includes inside that input use the consumer's execution environment. For example, checks the caller's , while an include inside it cannot borrow the caller's working directory. / disables only PostgreSQL startup files; it does not exempt the command's SQL or include files. These unverified denials use the normal exact-command review path, including the single-use code in Codex's ; see .

Threat Model

This hook assumes the AI agent is well-intentioned but fallible. It's designed to catch honest mistakes, not adversarial attacks. The hook runs with the same permissions as the Claude Code process.

Troubleshooting

Hook not blocking commands

1. Check hook registration: Run dcg doctor --strict with the same CLAUDE_CONFIG_DIR as Claude Code and verify the reported settings path contains the hook configuration
2. Restart Claude Code: Configuration changes require a restart
3. Check binary location: Ensure dcg is in your PATH
4. Test manually: Run echo '{"tool_name":"Bash","tool_input":{"command":"git reset --hard"}}' | dcg

Hook silently removed (recommended: add shell startup check)

Claude Code can silently remove the dcg hook when it rewrites the active user settings.json. This means you may lose protection without any warning.

Automatic setup -- dcg setup installs the hook and offers to add a shell startup check:

dcg setup               # Interactive — prompts before modifying RC files
dcg setup --shell-check # Non-interactive — adds the check automatically

Manual setup -- add this snippet to your ~/.zshrc and/or ~/.bashrc:

# dcg: warn if hook was silently removed from Claude Code settings
if command -v dcg &>/dev/null && command -v jq &>/dev/null; then
  if [ -f "$HOME/.claude/settings.json" ] && \
     ! jq -e '.hooks.PreToolUse[]? | select(.hooks[]?.command | test("dcg\"?$"))' \
       "$HOME/.claude/settings.json" &>/dev/null; then
    printf '\033[1;33m[dcg] Hook missing from ~/.claude/settings.json — run: dcg install\033[0m\n'
  fi
fi

This check:

• Runs in milliseconds (no noticeable shell startup delay)
• Is completely silent when the hook is present
• Shows a yellow warning only when the hook is missing
• Gracefully skips if dcg, jq, or settings.json are absent
• Works identically in bash and zsh

Note: The install.sh installer also offers to add this check during installation.

Hook blocking safe commands

1. Check for false positives: Some edge cases may not be covered by safe patterns
2. File an issue: Report the command that was incorrectly blocked
3. Temporary bypass: Have the user run the command manually in a separate terminal
4. Add to allowlist: Use the allowlist feature below for persistent overrides

Resolving False Positives with Allowlists

If dcg blocks a command that is safe in your specific context, you can add it to an allowlist. Effective allowlists are checked in this order:

1. Explicitly trusted project (.dcg/allowlist.toml): Active only when DCG_CONFIG selects the canonical repo-root .dcg.toml for that invocation
2. User (~/.config/dcg/allowlist.toml): Applies to all your projects
3. System (/etc/dcg/allowlist.toml): Applies system-wide

A checked-in project allowlist is inert by default. This prevents a newly cloned repository from granting itself permission to run destructive commands. All mutation commands default to the user layer; use repeatable --path flags to constrain an exception to a repository root and its descendants.

Adding a rule to the allowlist:

# Allow a specific rule by ID (recommended)
dcg allowlist add core.git:reset-hard -r "Used for CI cleanup"

# Scope a user-owned exception to one repository
repo_root=$(git rev-parse --show-toplevel)
dcg allowlist add core.git:reset-hard -r "CI cleanup" --user \
  --path "$repo_root" --path "$repo_root/**"

# Add to the user allowlist globally
dcg allowlist add core.git:reset-hard -r "Personal workflow" --user

# After reviewing .dcg.toml, explicitly activate and edit project policy
DCG_CONFIG="$repo_root/.dcg.toml" dcg allowlist add \
  core.git:reset-hard -r "Reviewed project policy" --project

# Allow with expiration (ISO 8601 format)
dcg allowlist add core.git:clean-force -r "Migration" --expires "2026-02-01T00:00:00Z"

# Allow a specific command (exact match) using add-command
dcg allowlist add-command "rm -rf ./build" -r "Build cleanup"

Listing allowlist entries:

# List entries from effective layers only
dcg allowlist list

# Inspect the raw project file (marked INACTIVE when it is untrusted)
dcg allowlist list --project

# List user allowlist only
dcg allowlist list --user

# Output as JSON
dcg allowlist list --format json

Removing entries:

# Remove a rule by ID
dcg allowlist remove core.git:reset-hard

# Remove from explicitly trusted project policy
DCG_CONFIG="$repo_root/.dcg.toml" dcg allowlist remove \
  core.git:reset-hard --project

Validating allowlist files:

# Check for issues (expired entries, invalid patterns)
dcg allowlist validate

# Strict mode: treat warnings as errors
dcg allowlist validate --strict

Pruning expired entries:

# Preview expired entries without changing files
dcg allowlist prune --dry-run

# Remove expired entries from effective layers (user, plus trusted project)
dcg allowlist prune

Example allowlist.toml:

[[allow]]
rule = "core.git:reset-hard"
reason = "Used for CI pipeline cleanup"
added_at = "2026-01-08T12:00:00Z"

[[allow]]
exact_command = "rm -rf ./build"
reason = "Safe build directory cleanup"
added_at = "2026-01-08T12:00:00Z"
expires_at = "2026-02-08T12:00:00Z"  # Optional expiration

[[allow]]
pattern = "rm -rf .*/build"
reason = "Build directories across projects"
risk_acknowledged = true  # Required for pattern-based entries
added_at = "2026-01-08T12:00:00Z"

Command grants bind to the original request. exact_command compares the complete command text, including environment assignments, executable paths, quoting, wrappers, and redirections. command_prefix and risk-acknowledged pattern entries also match that original text. For example, an exact grant for git reset --hard does not authorize PATH=/other/bin git reset --hard or sh -c 'git reset --hard'. An explicit grant for either complete form can authorize that form; extracting its child command during analysis never creates a new grant. [overrides] allow follows the same original-request boundary, and an applicable explicit block override still takes precedence. Confidence and policy re-evaluation keep that same boundary, including for temporary allow-once grants.

Rule entries remain scoped to the named rule. An intentionally unanchored allowlist regex retains the scope its author wrote, so use anchors when the approval is for one complete command. Destructive detection continues to use normalization to recognize dangerous commands behind assignments and wrappers.

Per-Rule Target-Path Exemptions

Agent runtimes hand each job a scratch directory under $HOME — Claude Code uses ~/.claude/jobs/<id>/tmp. An agent writing its own logs there trips core.filesystem:redirect-truncate-root-home and the rm -rf rules over and over, for a path that only the agent owns.

[overrides] allow is the wrong tool for that: it matches the whole command, so a pattern written for the log write also admits <safe-op> && git reset --hard. A target exemption is narrower — it is evaluated inside one rule's target check:

[rules."core.filesystem:redirect-truncate-root-home"]
exempt_target_globs = ["~/.claude/jobs/*/tmp/**"]

[rules."core.filesystem:rm-rf-root-home"]
exempt_target_globs = ["~/.claude/jobs/*/tmp/**"]

When that rule matches, dcg resolves the operation's target path. If the target is a literal path under one of the globs, that one rule does not fire. Every other rule still evaluates the complete command, so echo x > ~/.claude/jobs/abc/tmp/log && git reset --hard is still denied — by core.git:reset-hard, on its own merits.

Wiring doctor into automation. dcg doctor exits 0 by default, even when it reports "ok": false — so dcg doctor || handle_failure is dead code unless you ask for the verdict. Use --strict to make the exit status carry it:

dcg doctor --strict            # non-zero when checks fail
dcg doctor --format json --strict

The default is unchanged so existing pipelines keep working, and both output formats answer identically.

Supported rules. Target exemptions apply only where a literal target is actually resolvable. Configuring them anywhere else is inert, and dcg doctor warns about it rather than leaving you quietly unserved:

Rule	Target
core.filesystem:redirect-truncate-root-home	The redirect target(s)
core.filesystem:rm-rf-general	Every rm operand
core.filesystem:rm-rf-root-home	Every rm operand
core.filesystem:rm-r-f-separate	Every rm operand
core.filesystem:rm-r-f-separate-root-home	Every rm operand
core.filesystem:rm-recursive-force	Every rm operand
core.filesystem:rm-recursive-force-root-home	Every rm operand
core.filesystem:rm-recursive-general	Every rm operand
core.filesystem:rm-recursive-root-home	Every rm operand

Note that many ~- and /-rooted operands are attributed to the Critical rm-rf-root-home, not rm-rf-general: root, any direct child of /, a home directory (~, $HOME, /home/<user>, /Users/<user>) and its top-level entries, dotfile trees such as ~/.claude/..., anything under a system or mount directory (/etc, /usr, /var, /mnt, ...), and any operand containing an expansion, glob, or ... A static path two or more levels into a project inside a home directory (~/proj/dist) or outside the system directories (/data/proj/dist) is rm-rf-general. Check dcg explain "<command>" for the rule id you actually need.

Unresolved dynamic paths are never exempted. core.filesystem:redirect-truncate-dynamic-path deliberately supports no target-glob setting. echo x > $DIR/log stays denied when DIR is unknown, regardless of the configured globs. A variable, command substitution, backtick, glob, or %VAR% is never matched against an exemption glob as if its source text were the resolved path.

Separately, dcg's bounded POSIX analysis can prove some redirect targets benign without executing shell code (#536):

Proven form	Example
A literal assignment on the redirect's && success path	true && S=/tmp/d && echo hi > "$S/x"
A known variable with a literal suffix	S=/tmp/d; T="$S/sub"; echo hi > "$T/x"
A literal prefix and suffix around one proven scalar or loop variable	for i in 1 2 3; do echo hi > "/tmp/run-$i.log"; done
PID digits inside a literal /tmp/ path	echo hi > "/tmp/d-$$.log"
A supported mktemp substitution with an explicit temporary root	D=$(mktemp -d /tmp/v-XXXXXX); echo hi > "$D/p" or D=$(mktemp -d -p /tmp); echo hi > "$D/p"

Existing literal assignments and bare $(mktemp) / $(mktemp -d) scratch idioms remain supported. The final target must pass the benign-path checks, including rejection of every .. component and protected credential or .git files, even beneath /tmp. The additional symbolic proof requires a temporary root and is limited to eight binding levels, 4,096 expanded bytes, and 256 command segments. A binding that might be skipped before a running redirect, a binding in a pipeline or subshell, an unknown dependency, reassignment, or a variable-mutating command cannot establish this proof. Unrecognized mktemp syntax, templates for hidden directories, /etc roots, dynamic $TMPDIR roots, and -u/--dry-run keep their denials. This built-in proof does not add a configurable dynamic-path exemption, and every other redirect and command is still checked.

The loop proof also supports a single path assignment from the iteration variable immediately before the redirect, such as for i in 1 2; do log="/tmp/run-$i.log"; echo hi > "$log"; done. Every literal list value must yield a benign final path. Computed lists, conditional bindings, shell-maintained variables, later mutation within the loop, and additional expansions do not qualify.

Filesystem evidence belongs to the environment running the script. The new-home-file allowance uses local filesystem checks and therefore applies only to local scripts. An extracted SSH, container, namespace, or other-user script cannot use a same-named local file to establish that its redirect is safe (#534). For example, ssh host 'echo x > ~/notes.txt' stays denied even if the local ~/notes.txt is absent. A local redirect such as ssh host 'echo x' > ~/new-notes.txt keeps the local creation checks. Append and proven temporary paths in the remote script remain available, subject to the existing credential and Git protections.

The same boundary applies to files consumed by nested database or shell commands: remote files are unverified rather than read from the local disk. With the PostgreSQL pack enabled, remote psql startup files are unverified too; -X / --no-psqlrc disables those startup files so a literal SQL command can be evaluated directly. dcg does not connect to the other environment to inspect its files.

Literal script text piped into ssh host, an explicit remote stdin-reading shell, or an interactive docker / podman / nerdctl / kubectl / oc exec shell receives the same filesystem boundary. This includes supported process-substitution inputs. For example, printf '%s\n' 'echo x > ~/notes.txt' | ssh host cannot borrow local evidence that the file is new. Unknown script producers, compound remote dispatch, and unsupported carrier options require review through the existing unverified-source denial. Grouped and transformed producers retain the same conservative source checks as local shell pipelines.

Ordinary data consumers such as ssh host cat and docker exec -i container cat do not execute their input as program text. Disabled stdin and detached container exec also remain data paths. SSH's local command-execution options need separate review even with -n, because they can use the caller's stdin. Local output redirects on the carrier still use local creation checks. An exact-command dcg allow-once review remains available for a required operation; these checks do not add allowlist entries or inspect remote files.

Credential and login files are never exempted by path. core.filesystem:credential-file-write (writes to ~/.ssh/*, ~/.aws/credentials, ~/.netrc, ~/.npmrc, the shell rc files, /etc/sudoers*, /etc/passwd, and the rest of its list, by >/>>, tee, cp/mv/install/ln, dd, or sed -i — and, from a PowerShell or Cmd payload on any host, Add-Content/Set-Content/Out-File/Tee-Object/ New-Item/Copy-Item/Move-Item or copy/move) has no target-glob setting: the files are the point, so there is no "scratch" subset to carve out. Reads, chmod/chown, and appending to ~/.ssh/known_hosts are already allowed; for a project that legitimately manages one of these files, allowlist the rule id with a reason (that lifts only this rule — an existing file is still judged by redirect-truncate-root-home), or use dcg allow-once for a one-off.

Archive extraction uses the same protected-destination checks. Explicit destinations under credential directories or .git are denied for tar, bsdtar, unzip, and 7z / 7za / 7zr, including traditional tar flags, attached directory options, and repeated relative -C changes. Listing, testing, creating archives, and genuine stdout-only extraction do not acquire a destination-write denial. An archive filename, filter, or member named like an option cannot masquerade as a mode flag. For tar, dcg accounts for both GNU and BSD option semantics. This check protects explicit destinations; it does not inspect archive members or infer their paths from the archive's name. Credential-directory writes retain core.filesystem:credential-file-write, while .git writes retain core.filesystem:git-internals-write, so a grant for one does not exempt the other.

Shell redirects into .git retain the separate Critical rules core.filesystem:redirect-truncate-git-internals-relative and core.filesystem:redirect-append-git-internals-relative. Targets are decoded using the payload's shell dialect, so echo x >> .git\config is protected in PowerShell and Cmd on any host. When the shell is unknown, dcg checks each supported interpretation. An explicitly POSIX payload retains POSIX escape semantics. A grant for the generic dynamic-path rule cannot exempt a known Git target, and a grant for Git truncation does not exempt append or credential writes elsewhere in the same command. Other dynamic redirect targets still require their own review. For a required one-off write, use the exact-command dcg allow-once review path.

Glob semantics.

• ~ and ~/ expand to the user's home directory; ~user is not supported.
• * matches within a single path component; ** crosses separators.
• Matching is case-sensitive on every platform, like the scan include/exclude globs.
• Matching is lexical only — no stat, no canonicalization, no symlink resolution. A symlinked path is matched by its literal spelling, so a glob over ~/.claude/jobs/*/tmp/** does not follow a symlink planted inside it.
• A target containing a .. component is rejected outright rather than resolved: rm -rf ~/.claude/jobs/abc/tmp/../../../Documents never matches. Globs containing .. are rejected at load.
• An operation with several targets must prove every target exempt. rm -rf ~/.claude/jobs/abc/tmp/scratch ~/.ssh stays denied.
• Single-quoted rm operands are never exempted: the shell does not expand ~ inside them, so the literal spelling names a different path.
• An rm operand glued to a ( is never exempted: zsh reads ~/scratch/lo(g|x) as glob alternation and removes ~/scratch/log, not the spelled ~/scratch/lo (bash rejects the text as a syntax error). Brace expansion (lo{g..g}), embedded quotes (lo"g"), and escapes disqualify a target the same way, for both rm operands and redirect targets.

Trust boundary. A target exemption reduces coverage, so it follows the same rule as every other trust-reducing setting (see Configuration Hierarchy): it is ignored when it comes from an automatically discovered .dcg.toml. It is honored from the system config, the user config, and an explicit DCG_CONFIG file.

Output. A suppressed rule is an allow that came from configuration, so it is not silent: with general.verbose = true, dcg notes on stderr which rule matched, which target it saw, and which glob exempted it.

Performance issues

1. Check pattern count: Excessive custom patterns can slow matching
2. Profile with --release: Debug builds are significantly slower
3. Check stdin buffering: Slow JSON input can delay processing

Running Tests

Unit Tests

cargo test

The test suite includes 80+ tests covering:

• normalize_command_tests: Path stripping for git and rm binaries
• quick_reject_tests: Fast-path filtering for non-git/rm commands
• safe_pattern_tests: Whitelist accuracy for all safe pattern variants
• destructive_pattern_tests: Blacklist coverage for all dangerous commands
• input_parsing_tests: JSON parsing robustness and edge cases
• deny_output_tests: Output format validation
• integration_tests: End-to-end pipeline verification

Test with Coverage

cargo install cargo-tarpaulin
cargo tarpaulin --out Html

End-to-End Testing

The repository includes a comprehensive E2E test script with hundreds of command scenarios:

# Run full E2E test suite
./scripts/e2e_test.sh

# With verbose output
./scripts/e2e_test.sh --verbose

# With specific binary path
./scripts/e2e_test.sh --binary ./target/release/dcg

Codex CLI integration has a separate opt-in harness because it drives a real authenticated codex exec session against hermetic temporary repositories:

# Run the real Codex CLI smoke harness
./scripts/e2e_codex.sh --verbose --dcg-binary ./target/release/dcg

# Capture JSONL trace and failure artifacts for postmortems
./scripts/e2e_codex.sh --json --artifacts ./artifacts/codex-e2e --dcg-binary ./target/release/dcg

The Codex harness exits successfully with an explicit skipped status when Codex is unavailable or unauthenticated, so CI and developer machines without Codex access can run it without producing false failures. A full local run requires codex 0.125.0 or newer on PATH plus an authenticated codex login status; when Codex is responsive, expect roughly five minutes, with longer runtimes possible under rate limiting.

Useful debugging flags:

• --verbose mirrors the per-scenario logging style from scripts/e2e_test.sh.
• --artifacts DIR writes trace.jsonl plus per-failure stdout, stderr, prompts, repository state, manifests, and diffs.
• --keep-tempdirs preserves temporary repositories and isolated Codex homes for manual inspection after a failed run.

CI runs ./scripts/e2e_codex.sh --verbose --json --artifacts /tmp/codex_e2e_artifacts in a dedicated codex-e2e job on pushes to main only. The job installs Codex with npm, authenticates from the CODEX_API_KEY secret, and still goes green with a clear notice when Codex is unavailable, unauthenticated, quota-limited, or temporarily unable to reach the API.

The E2E suite covers:

• All destructive git commands (reset, checkout, restore, clean, push, branch, stash)
• Safe git commands (status, log, diff, add, commit, push, read-only branch listings)
• Filesystem commands (rm -rf with various paths and flag orderings)
• Absolute path handling (/usr/bin/git, /bin/rm)
• Non-Bash tools (Read, Write, Edit, Grep, Glob)
• Malformed JSON input (empty, missing fields, invalid syntax)
• Edge cases (sudo prefixes, quoted paths, variable expansion)

Continuous Integration

The project uses GitHub Actions for CI/CD:

CI Workflow (.github/workflows/ci.yml)

Runs on every push and pull request:

• Formatting check: cargo fmt --check
• Clippy lints: cargo clippy --all-targets -- -D warnings (pedantic + nursery enabled)
• Compilation check: cargo check --all-targets
• Unit tests: cargo nextest run with JUnit XML reports
• Coverage: cargo llvm-cov with LCOV output

Release Workflow (.github/workflows/dist.yml)

Triggered on version tags (v*):

• Builds optimized binaries for 6 platforms:
  • Linux x86_64, statically linked with musl (x86_64-unknown-linux-musl)
  • Linux ARM64 (aarch64-unknown-linux-gnu)
  • macOS Intel (x86_64-apple-darwin)
  • macOS Apple Silicon (aarch64-apple-darwin)
  • Windows x64 (x86_64-pc-windows-msvc)
  • Windows ARM64 (aarch64-pc-windows-msvc)
• Creates .tar.xz archives (Unix) or .zip (Windows)
• Generates SHA256 checksums for verification
• Publishes to GitHub Releases with auto-generated release notes

To create a release:

git tag v0.1.0
git push origin v0.1.0

FAQ

Q: Why block both git branch -d and git branch -D?

Lowercase -d verifies that Git considers a branch merged, but it still removes the branch name, upstream-tracking configuration, and convenient reflog reference. Those are user-owned state and may still matter after a merge. DCG therefore treats every branch deletion as an approval boundary; use git branch -vv, git branch --merged, and git branch --no-merged to review state without changing refs.

The two forms are separate rules. -d / --delete without force is core.git:branch-delete; -D, --delete --force, -f, -M and -C are core.git:branch-force-delete. To let an agent propose merged-branch cleanup for approval while still refusing forced deletion:

[policy.rules]
"core.git:branch-delete" = "ask"

Before v0.15.3 both forms were reported as core.git:branch-force-delete. A [policy.rules] or allowlist entry for that id still covers -d unless core.git:branch-delete has an entry of its own.

Q: Why is git push --force-with-lease allowed?

Force-with-lease is a safer alternative that refuses to push if the remote has commits you haven't seen. It prevents accidentally overwriting someone else's work.

Q: Why block recursive rm outside temp directories?

Recursive deletion can silently remove an ordinary writable directory tree even without -f. A typo, unexpected working directory, or wrong variable expansion can therefore destroy critical files with rm -r, rm -R, or their forced variants. DCG treats all of those forms as an approval boundary, while retaining the narrowly bounded policy for literal /tmp and /var/tmp subdirectories.

Q: Can I add custom patterns?

Yes. Create YAML pack files and point to them in your config. See the Custom Packs section and docs/custom-packs.md for the schema and examples.

Q: What if I really need to run a blocked command?

See Escape Hatch / Bypass. Options include DCG_BYPASS=1, allow-once codes, permanent allowlists, or running the command manually in a separate terminal.

Q: Does this work with other AI coding tools?

Yes. dcg natively supports Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Cursor IDE, OpenCode, Oh My Pi (omp), Crush, Reasonix, Muse Code, Amp, and Factory Droid's Execute interception paths. Droid's nested Script-mode calls remain unverified; see Factory Droid. Aider has limited git-hook support, and Continue is detected but cannot be auto-configured because it does not expose a pre-execution shell hook.

Q: What about database, Docker, Kubernetes, and cloud commands?

dcg includes 50+ packs covering all of these. See the Modular Pack System section for the full list. Enable the packs you need in your config.

Contributing

About Contributions: Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

Custom source license based on MIT with an OpenAI/Anthropic rider. See LICENSE for the complete terms.