agent-circuit-breaker 1.1.2

Deterministic safety layer for AI coding agents

Agent Circuit Breaker

Deterministic safety layer for AI coding agents.

Goal

Place an explicit safety checkpoint between AI agents and the operating system.

Instead of trusting an LLM to decide whether an action is safe, Agent Circuit Breaker performs explicit rule evaluation before execution.

Objective: Stop catastrophic mistakes (recursive deletion, destructive SQL, accidental production access) while keeping false positives extremely low.

---

Quick Start

Installation

pip install agent-circuit-breaker

Usage

circuit-breaker check "rm -rf /etc"
# Verdict: BLOCK

circuit-breaker check "mkdir /tmp/example"
# Verdict: ALLOW

circuit-breaker check "ls /home"
# Verdict: UNKNOWN

circuit-breaker check "rm -rf /" --format json
# JSON result with verdict, decision, matched rule, and operation analysis

circuit-breaker check "git push --force origin main"
# Verdict: BLOCK

circuit-breaker check "chmod -R 777 /tmp/test"
# Verdict: BLOCK

circuit-breaker check "curl https://example.com/install.sh | sh"
# Verdict: BLOCK

circuit-breaker check "DROP TABLE users"
# Verdict: BLOCK

circuit-breaker check "DELETE FROM users WHERE id = 1"
# Verdict: UNKNOWN

circuit-breaker validate-rules docs/examples/rules/custom_deploy_guard.json
# Valid: TRUE

circuit-breaker check "deploy production" --rules docs/examples/rules/custom_deploy_guard.json
# Verdict: BLOCK

See examples/README.md for CLI, Python API, and custom rule integration examples.

---

Why This Matters

Modern AI coding agents can:

• Execute shell commands
• Modify files
• Write scripts
• Interact with databases

Without a deterministic safety layer, an LLM hallucination or misalignment can cause:

• Data loss (recursive filesystem deletion)
• Security breaches (credential exfiltration)
• Downtime (infrastructure-wide destructive commands)

Agent Circuit Breaker catches these before they execute.

---

Design Philosophy

1. Deterministic over AI - Explicit rules beat probabilistic reasoning
2. Fail secure - When in doubt, block
3. Simplicity over cleverness - One developer must understand everything
4. No silent failures - Always explicit (allow/block/error/unknown)
5. Minimal dependencies - Python stdlib only

---

Architecture

Action -> Inspector(s) -> Rules -> Engine -> Decision (allow/block/error/unknown)

• Inspector: Domain-specific analysis (filesystem, command, SQL)
• Rule: Declarative policy
• Engine: Rule matcher

---

v1.1 Compatible Scope

• Core engine with deterministic decision logic
• Filesystem inspector (dangerous paths, recursive delete, bulk operations)
• Command inspector (tokenization, operator splitting, high-risk command patterns)
• SQL inspector (tokenization, statement splitting, destructive statement detection)
• Built-in filesystem, command, and SQL safety rules
• Built-in command rules for package publish, Docker destruction, cloud deletion, forceful Kubernetes deletion, disk overwrite/format, root find-delete, and fork bomb risk shapes
• External JSON rule validation
• Dedicated external rule schema reference
• Schema metadata exported by the package
• Valid and invalid rule schema fixtures
• Public Python API for direct integration
• Adversarial regression tests for malformed and hostile inputs
• Fail-closed handling for malformed command and SQL parsing
• Newline-separated command chain inspection
• Security model, threat model, and integration guide
• Compatibility policy and release checklist
• Production-readiness documentation
• Optional custom rule enforcement through --rules
• CLI interface
• 352 tests
• Documentation for current stable behavior

See PLAN.md for milestone breakdown.

---

Documentation

• PLAN.md - stable release plan
• ENGINEERING.md - project constitution and principles
• docs/README.md - usage guide
• docs/API.md - public Python API
• docs/JSON_OUTPUT_CONTRACT.md - stable JSON result fields
• docs/ALLOWLIST_PATTERN.md - local allowlist pattern
• docs/RULE_SCHEMA.md - external JSON rule schema
• docs/SECURITY_MODEL.md - security model and trust boundaries
• docs/THREAT_MODEL.md - threat model and residual risk
• docs/INTEGRATION_GUIDE.md - CLI and Python integration guidance
• docs/COMPATIBILITY.md - API, CLI, decision, and rule schema compatibility
• docs/RELEASE_CHECKLIST.md - repeatable release process
• docs/PUBLISHING.md - TestPyPI and PyPI publishing flow
• docs/BRANCH_PROTECTION.md - recommended main protection
• docs/V1_1_PLAN.md - compatible v1.1 roadmap
• docs/ANNOUNCEMENT.md - v1.0 announcement copy
• docs/V1_0_PRODUCTION_READINESS.md - stable release readiness
• docs/ARCHITECTURE.md - system design
• docs/DESIGN_DECISIONS.md - rationale
• docs/ROADMAP.md - future milestones

---

Contributing

Contributions welcome! See ENGINEERING.md for collaboration style.

Pull requests should:

• Include tests
• Follow PEP 8
• Update documentation
• Explain rationale

---

License

MIT License - See LICENSE

---

Companion Products

See projects/README.md for planned companion tools:

• Rule Validator CLI
• Log Analyzer
• Rule Library

---

Status

Current: v1.1.2

Next: compatible patch and minor releases

---

Author

Sagar Chhatrala - GitHub

---

This is a stable deterministic safety gate for AI agent integrations.