agent-circuit-breaker 1.4.0

Local-first safety runtime for AI coding agents

Agent Circuit Breaker

Local-first safety runtime for AI coding agents.

Goal

Place an explicit safety checkpoint between AI agents and the operating system, developer tools, databases, and automation workflows.

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, route high-risk actions to approval, and leave an audit trail that a human or team can inspect later.

---

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 explain "git push --force origin main"
# Verdict, risk score, matched rule, and safer alternatives

circuit-breaker check "rm -rf /" --profile team
# Verdict: PENDING_APPROVAL

circuit-breaker approvals list
# Local pending approvals

circuit-breaker scan ./scripts ./README.md
# Static findings for scripts, docs, SQL, and CI files

circuit-breaker scan . --sarif > acb.sarif
# SARIF for GitHub code scanning

circuit-breaker check "ls /home" --mode strict
# Verdict: BLOCK

circuit-breaker-mcp-proxy --profile team -- python -m my_mcp_server
# Inspect MCP tools/call arguments before forwarding to the server

circuit-breaker check "rm -rf /" --audit
circuit-breaker timeline --verify
# Tamper-evident local audit timeline

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

circuit-breaker check "deploy production" --policy .agent-circuit-breaker/policy.json --require-signature
# Load only signed policy/rule JSON

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
• Call tools and APIs through local automation layers

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 gives individuals and teams a local control point before those actions 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
• Safety profiles and policy modes for personal, team, and production workflows
• Human approval outcome and local approval queue
• Explain mode with safer alternatives
• Static scan mode with SARIF output
• Tamper-evident audit timeline
• Central policy loading from file or explicit URL
• Plugin discovery and optional rule-provider loading
• External rule schema with scalar, regex, and boolean composite matchers
• Hook scaffold generation and pre-commit hook manifest
• Stdio JSON-RPC MCP proxy for guarding tools/call arguments before forwarding
• Optional signed policy and rule-pack verification
• 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
• 380 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/V1_3_RUNTIME_NOTES.md - v1.3 runtime scope and deferred hardening notes
• docs/releases/v1.4.0.md - v1.4 proxy and policy hardening notes
• 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.4.0

Next: adoption polish, broader integration examples, and release validation from TestPyPI/PyPI artifacts.

---

Author

Sagar Chhatrala - GitHub

---

This is a stable local-first safety runtime for AI agent integrations.