Shackle: A pre-execution ALLOW/DENY/HITL gate for AI agents (open source)

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 0

Star 5

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

117 Commits

117 Commits

.github

.github

fixtures

fixtures

legal

legal

shackle

shackle

tests

tests

v2

v2

.gitignore

.gitignore

CONFORMANCE.md

CONFORMANCE.md

INTEGRATIONS.md

INTEGRATIONS.md

LICENSE

LICENSE

README.md

README.md

SP-1.0-SPECIFICATION.md

SP-1.0-SPECIFICATION.md

badge.svg

badge.svg

demo.py

demo.py

index.html

index.html

logo.png

logo.png

pyproject.toml

pyproject.toml

registry.html

registry.html

registry.json

registry.json

setup.py

setup.py

Repository files navigation

The runtime governance layer — and the SP/1.0 conformance standard — for autonomous AI agents. SHACKLE mediates every agent tool call in real time: runaway token loops, unhandled tool cascades, and budget overruns are stopped before the next call fires. It is live, it runs today, and its reference implementation provably passes its own conformance suite. This is not a proposal or a prototype — it is a working standard you can run, verify, and be certified against. (Cost is read from usage after each call, so SHACKLE halts the loop, not the single call that crossed the line; see the AGPL best-effort disclaimer below.)

🔒 SP/1.0 — The Conformance Standard

SHACKLE is not only a runtime circuit breaker — it is the authored, verifiable conformance standard for runtime mediation of agent tool calls.

Decision surface: ALLOW / DENY / HITL

Conformance model: Valid(τ) ⇔ Required(τ) ⊆ Supported(τ)

15 hash-verifiable conformance vectors in fixtures/conformance.json — 10 decision-core + 5 HITL transition cases (approve / reject / modify / defer-escalate / duplicate-resume)

Pure reference implementation: shackle/conformance.py — a stdlib-only decide(config, state, call) -> (verdict, reason)

Executable proof: pytest tests/test_conformance.py runs every vector against the reference

Core invariant: history-visible ≠ runtime-executable — a record that an action happened is not proof the transition was supported

A runtime is SHACKLE-conformant iff it passes the published fixture set — provable by reproduction, not assertion. See CONFORMANCE.md for the full specification and how to claim conformance. The fixture hashes have been independently reproduced by third parties.

Which layer is which: shackle/conformance.py + fixtures/conformance.json are the conformance-verified layer — the authored spec and its 15 hash-verifiable vectors, with a reference decide(). shackle/core.py is the shipped runtime integration (the @Guard decorator): it maps its live TriggerEngine/ExecutionState onto decide()'s (config, state, call) contract and consults the same reference decide() on every evaluated tool call and every LLM call, recording the verdict on state.last_decision. So "SP/1.0-conformant" refers to the spec, the fixtures, and the reference implementation the shipped runtime actually calls — one decision surface, not two implementations that happen to agree.

Authorship & provenance: SHACKLE, the Required ⊆ Supported conformance model, the decide() surface, and the HITL transition contract are authored by Dante Bullock (@Fame510), sole author. First published 2026-06-17.

📜 What SP/1.0 Actually Is

SP/1.0 (SHACKLE Protocol 1.0) is a conformance standard for runtime mediation of autonomous AI agent actions. In plain terms: it defines — precisely, and in a way anyone can independently verify — what it means for a system to correctly decide whether an agent is allowed to take its next action.

Every AI agent, at every step, is about to do something: call a tool, spend budget, invoke another agent, execute a transaction. SP/1.0 governs that moment. It specifies three things no other agent framework pins down as a verifiable contract:

The decision surface — ALLOW / DENY / HITL. Every mediated action resolves to exactly one verdict: allow it, deny it, or halt for a human. There is no fourth state and no ambiguity. Each verdict carries a deterministic, inspectable reason.

The conformance model — Valid(τ) ⇔ Required(τ) ⊆ Supported(τ). A transition is valid if and only if everything it requires is within what the system provably supports. This is the mathematical spine of the standard: capability is a set relationship, not a promise.

The core invariant — history-visible ≠ runtime-executable. The fact that an action is recorded, resumed, or replayed is not evidence that it was ever authorized. A rejected or deferred action that comes back around is denied, not waved through. This single rule closes the class of failures where agents "resume" their way past their own guardrails.

SP/1.0 ships as 15 hash-verifiable conformance vectors (fixtures/conformance.json) — 10 decision-core cases plus 5 human-in-the-loop transition cases (approve / reject / modify / defer-escalate / duplicate-resume) — and a stdlib-only reference implementation (shackle/conformance.py). You do not take the standard on faith. You run it. pytest tests/test_conformance.py executes every vector against the reference, and the reference implementation passes its own suite — verified, not asserted.

🎓 What It Means to Be SHACKLE Certified

SHACKLE Certification is proof — not a promise — that a runtime correctly enforces the SP/1.0 mediation contract. It is measured entirely against the public, hash-verifiable fixtures. The same vectors that certify you are the ones anyone else can re-run to check your claim. There is no private audit, no trust-us seal, no pay-to-pass: certification is reproduction.

For a buyer, "SHACKLE Certified" answers the question every serious acquirer, enterprise, and regulator eventually asks about an autonomous system: "Can you prove it does what it's allowed to do — and nothing else?" A certified runtime can. In minutes. From a clean clone.

Certification Levels

Level Name What it guarantees

SP/1.0-Core Core Conformance The runtime resolves every mediated action to the correct ALLOW / DENY / HITL verdict, with the correct deny reason. The decision surface is sound.

SP/1.0-HITL Transition-Complete Core, plus correct handling of every human-in-the-loop transition: approve, reject, modify, defer-escalate, and duplicate-resume. Rejected and deferred actions provably cannot execute by being replayed.

SP/1.0-Sovereign Enterprise Runtime HITL, plus atomic daemon state, tamper-evident ledgering, and audit export. The full accountability layer an enterprise or acquirer can hold to account.

How to Get Certified (open to any runtime, today)

Run the suite against your runtime: pytest tests/test_conformance.py and pytest v2/tests/test_v2_conformance.py.

Capture the evidence. SHACKLE emits a per-fixture pass/fail report with the fixture hashes it verified against. That report is your conformance artifact — independently reproducible by anyone.

Submit for listing. Open a certification request with your report and a public, reproducible evidence link. An automated check re-runs the public fixtures; a maintainer verifies before listing.

Get listed. Verified runtimes appear in the public SHACKLE Conformance Registry with the level achieved, SP/1.0 version, and date — and may display the SP/1.0 Certified badge.

An open standard, an open door

SP/1.0 is a neutral, public standard. Any agent runtime — including competing frameworks and competing safety products — is invited to test against it and be listed. The fixtures are public. The verdicts are deterministic. The registry is open. We hold our own reference implementation to exactly the bar we ask of everyone else, and we publish our fixtures so the claim is checkable.

That is the entire philosophy: a standard is only worth what it can withstand. If a runtime conforms, the registry proves it. If it doesn't, the fixtures show exactly where. Either way, the measure is public and the same for everyone.

Certify your agents. → Run the fixtures · Get listed · View the registry

Integrations (LiteLLM + AutoGen)

SHACKLE now ships first-class governance for the biggest chokepoints in the agent stack. See INTEGRATIONS.md for full usage and LiteLLM proxy config.yaml examples.

LiteLLM guardrail (shackle/litellm_shackle_guardrail.py) — enforce SP/1.0 on any LiteLLM-powered agent (CrewAI, AutoGen, LangGraph, custom):

ShackleGuardrail — Option A, backed directly by the pure SP/1.0 reference decide() (conformance-exact, dependency-light).

ShackleEngineGuardrail — Option B, driven by the full TriggerEngine (stateful budget / repeat / timeout).

Both provide sync check()/record() for the SDK and async_pre_call_hook/async_post_call_success_hook for the LiteLLM proxy. litellm is an optional dependency.

AutoGen wrapper (shackle/autogen_shackle_wrapper.py) — wrap_tool decorator + create_shackle_agent factory that govern AutoGen tool calls through the same engine. AutoGen is optional; wrap_tool works without it.

One integration = coverage for the whole supply chain: because LiteLLM sits under most agent frameworks, the guardrail governs them through a single chokepoint. All decisions trace to the hash-pinned fixtures in fixtures/conformance.json.

Provenance

SHACKLE was built by Dante Bullock, a 52-year-old self-taught systems architect and engineer out of Oakland, California. No venture capital. No corporate incubator. Just raw necessity and a refusal to watch autonomous agents burn money in silent infinite loops.

Rather than guessing what the agent ecosystem needed, Sovereign Logic used real-time web scraping and community sentiment mining to audit the issue trackers of CrewAI, AutoGen, and LangGraph — mapping the exact systemic failures affecting developers in production, then building the drop-in circuit breaker to fix them.

This is infrastructure built by a developer, for developers — sovereign, lean, and zero-bloat.

🎯 When to Use SHACKLE

SHACKLE is purpose-built for:

Local development and debugging — Interactive HITL console gives you real-time control

CLI agents and supervised workflows — Resume/Skip/Abort when loops are detected

Cross-framework coverage — One decorator works across CrewAI, LangGraph, and AutoGen

Budget enforcement — Client-side token tracking prevents runaway costs

Iterative testing — Catch loops early in the development cycle

For headless production APIs (serverless functions, FastAPI endpoints, background workers where blocking for human input isn't an option), consider framework-native solutions like TokenCircuit for automated LangGraph overrides.

SHACKLE and production-oriented tools solve complementary problems: use SHACKLE during development and testing, then transition to automated overrides for deployed APIs if needed.

⚡ The Problem

AI agents are highly capable, but their error-handling is fundamentally broken. When an agent hits an unhandled tool error (401 Unauthorized, changed API payload, dead endpoint), it rarely self-corrects. Instead, it enters a "Loop of Death" — retrying the exact same tool with the exact same input, burning your context window and running up massive API bills in minutes.

Frameworks like CrewAI, AutoGen, and LangGraph lack native, framework-agnostic spending guardrails or deterministic loop breakers.

🛡️ The Solution

SHACKLE is a lightweight, zero-dependency governance layer that sits inside your runtime via dynamic Python shims. It intercepts LLM calls and tool executions client-side, monitoring execution state deterministically.

When an agent breaches your boundaries, SHACKLE trips the circuit breaker, halts execution, and drops you into an interactive terminal console.

Key Features

1-Line Install — no refactoring your agent topology

Loop of Death Pre

[truncated for AI cost control]