flowchart TB
    Client["Agent Client<br/>(LLM / CLI / MCP / Python)"] -->|"Intent { tool, params, idempotency_key }"| Kernel

    subgraph Kernel["AgentKernel (src/dispatcher.rs)"]
        direction TB
        S0["Step 0: SecurityGuard"]
        FSM["StateMachine<br/>can_execute_tool?"]
        IDEM["Idempotency lookup<br/>hit → cached output"]
        WAL["Wal (SQLite)<br/>PENDING → COMMITTED / FAILED"]
        RB["rollback()<br/>LIFO compensate() → DLQ on failure"]

        S0 -->|"SecurityViolation (no DB, no FSM change)"| Deny["Reject"]
        S0 -->|"pass"| FSM
        FSM -->|"denied"| Deny
        FSM -->|"authorized"| IDEM
        IDEM -->|"COMMITTED hit"| HIT["Return cached output"]
        IDEM -->|"miss"| WAL
        WAL -->|"execute()"| Tools
        Tools -->|"Ok"| OK["COMMITTED → Verifying"]
        Tools -->|"Err"| FAIL["FAILED → Compensating"]
        FAIL --> RB
        RB -->|"done / partial + DLQ"| Failed["Failed / RECOVERED_WITH_DLQ"]
    end

    subgraph Tools["ToolRegistry (Arc<dyn TransactionalTool>)"]
        FS["FsWriteTool<br/>write ↔ delete"]
        PAY["MockPaymentTool<br/>CHARGED ↔ REFUNDED"]
    end

sagashield/
├── src/                        # Rust library (zero .unwrap()/.expect())
│   ├── lib.rs                  # crate docs + compilable quickstart doctest
│   ├── error.rs                # typed KernelError
│   ├── types.rs                # ToolContext/ToolOutput/ActionStatus/DLQ/PruneReport
│   ├── traits.rs               # TransactionalTool { execute, compensate }
│   ├── wal.rs                  # SQLite WAL, LIFO rollback, DLQ, recovery, pruning
│   ├── fsm.rs                  # deterministic StateMachine (+ AwaitingApproval)
│   ├── dispatcher.rs           # AgentKernel: guard → FSM → WAL → rollback
│   ├── tools/                  # FsWriteTool, MockPaymentTool, CrashTool
│   ├── security/               # SecurityPolicy + SecurityGuard
│   ├── replay.rs               # dry-run SessionReplay with FSM re-validation
│   ├── audit.rs                # OpenTelemetry audit export
│   ├── mcp/                    # JSON-RPC 2.0 stdio server (10 tools)
│   ├── python.rs               # PyO3 bridge (feature "python")
│   └── bin/sagashield-mcp.rs   # standalone MCP binary
├── tests/                      # 37 integration tests (Rust) + Python binding checks
├── examples/                   # demo, security_demo, otel_export, run_evals, python_agent_demo.py
├── evals/                      # deterministic 50-scenario suite (seed=42) + results/
├── fuzz/                       # cargo-fuzz targets (path_guard, net_guard)
├── python/sagashield/          # pip SDK: decorator API + LangChain adapter
├── integrations/               # Claude Code / Cursor / Claude Desktop configs
├── .claude-plugin/             # Claude Code plugin marketplace manifest
├── .github/workflows/          # CI, release binaries, PyPI wheels, fuzz smoke
├── scripts/                    # local packaging (Windows .bat / Unix .sh)
├── Dockerfile                  # multi-stage, distroless, non-root, <30 MB target
├── SPEC.md  SECURITY.md  BENCHMARK.md  CHANGELOG.md
├── CONTRIBUTING.md  RELEASING.md  DISTRIBUTION.md
└── LICENSE-MIT  LICENSE-APACHE   (dual license, your choice)

# Python SDK (no compiler needed, Python ≥ 3.8)
pip install sagashield

# From source (Rust 1.88+, edition 2024; C compiler for bundled SQLite)
git clone https://github.com/sebastianmechno-sys/sagashield && cd sagashield
cargo build --release --bin sagashield-mcp

# Docker
docker build -t sagashield-mcp:0.3.0 .
docker run -i --rm -v sagashield-data:/data sagashield-mcp:0.3.0

use std::sync::Arc;
use sagashield::{
    AgentKernel, KernelError, ToolContext, ToolOutput, ToolRegistry,
    TransactionalTool, Wal,
};
use serde_json::{Value, json};

struct GreetTool;

#[async_trait::async_trait]
impl TransactionalTool for GreetTool {
    fn id(&self) -> &'static str { "greet" }

    async fn execute(&self, ctx: &ToolContext, args: Value)
        -> Result<ToolOutput, KernelError>
    {
        let name = args.get("name").and_then(Value::as_str).unwrap_or("world");
        Ok(ToolOutput::new(json!({ "greeting": format!("hello {name}") }))
            .with_effect(format!("greeted {name} at seq {}", ctx.step_seq)))
    }

    async fn compensate(&self, _ctx: &ToolContext, args: Value, _output: ToolOutput)
        -> Result<(), KernelError>
    {
        // ... undo the side effect (delete, refund, revoke) ...
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let wal = Arc::new(Wal::open_in_memory()?);
    let registry = ToolRegistry::new();
    registry.register(Arc::new(GreetTool))?;

    let mut kernel = AgentKernel::new(wal, registry);
    let session = uuid::Uuid::new_v4();

    kernel.begin_planning()?;                        // Idle → Planning
    kernel.begin_tool("greet")?;                     // → ExecutingTool(greet)
    let out = kernel
        .execute_tool(&session, "greet", json!({ "name": "ada" }), None)
        .await?;                                     // COMMITTED (or rollback + Failed)
    println!("{out:?}");
    Ok(())
}

let policy = sagashield::SecurityPolicy::new(
    vec!["./workspace".into()],
    vec![".env".into(), ".git".into(), "id_rsa".into()],
    vec!["api.openai.com".into()],
);
let mut kernel = AgentKernel::with_security_guard(wal, registry, Arc::new(policy));

pip install sagashield          # or: maturin develop --features python (from source)

from sagashield import SagaKernel, SecurityPolicy, transactional_tool

@transactional_tool("write_order", compensate_with=remove_file)
def write_order(ctx, args):
    with open(args["path"], "w") as fh:
        fh.write(args["content"])
    return {"path": args["path"]}

kernel = SagaKernel(policy=SecurityPolicy(["./workspace"]))
kernel.register_decorated()
kernel.begin_planning()
kernel.begin_tool("write_order")
kernel.execute_tool("write_order", {"path": "workspace/a.txt", "content": "hi"})
# Python exceptions trigger Rust-side LIFO rollback; traversal raises
# SecurityViolationError; replay/export_audit_otel read the same WAL.

claude mcp add sagashield -- /path/to/sagashield-mcp   # Claude Code CLI

cargo test                                        # 37 integration tests + doctest
cargo test --test security_fuzz_test              # 1,300+ hostile inputs, zero panics
cargo run --example demo                          # crash → LIFO rollback, real files
cargo run --example security_demo                 # prompt-injection neutralized
cargo run --example otel_export                   # OTel resourceSpans on stdout
python tests/python_binding_test.py               # 11/11 binding checks