Design Principles

Design Principles

Every Agentoolbox tool — shipped or planned — keeps the same contract. That consistency is the product: an agent can call any gate and reason about the result the same way. If a proposal can't meet this contract, it doesn't ship.

The contract

1. Deterministic. The same input always produces the same verdict. No generative model sits in the decision path, so results are reproducible and testable in CI.
2. Offline by default. No network calls on the hot path — detection data (checksums, tables, rule sets) ships with the tool. A gate may offer an explicit opt-in networked mode (e.g. DNS resolution for SSRF rebinding), never implicitly.
3. Fast. Sub-500ms, and most gates run in single-digit milliseconds. A gate slow enough to skip is a gate that gets skipped.
4. Checkable facts only. Every verdict is backed by a checksum, a bundled authoritative table, a grammar, or arithmetic — never a subjective judgment. We answer "is this well-formed / permitted / in-range?", not "is this good?".
5. A single verdict shape. Every tool returns PASS / FLAG / BLOCK plus a tamper-evident SHA-256 certificate suitable for an audit trail.
6. Agent-callable. Built for the propose → validate → execute seam and priced per call (0.0001 SOL; 10 free calls per IP, no signup).

Why deterministic, not "AI-powered"

The failures we guard against are themselves caused by probabilistic systems: a model hallucinates a package, confuses mg with mcg, or scales a decimal wrong. Adding another probabilistic layer to catch those would inherit the same failure mode. A gate is only trustworthy as a final check if it is reproducible — same input, same answer, every time, provable in a unit test. That is why the decision path is pure rules and math.

PASS / FLAG / BLOCK

• PASS — no issue found; safe to proceed.
• FLAG — a potential issue; surface for review or apply policy. Advisory, not fatal.
• BLOCK — a confirmed problem; do not proceed.

Most tools accept a policy (e.g. blockSeverityAtOrAbove) and an enforcement mode (block / flag / audit) so the caller decides how strict the gate is without changing the underlying detection.

The certificate

Every verdict is bound to a certificate:

sha256:<hex( sha256(subject) : verdict : findings : timestamp )>

It hashes the input (never the raw sensitive content), the verdict, the finding count, and a timestamp — so a downstream system can require and re-check a certificate without ever handling the original data. Today the certificate proves integrity (it wasn't altered). Cryptographic authenticity — a server-side signature (HMAC/Ed25519) plus a public verification path — is on the Roadmap.

The seam: propose → validate → execute

Agentoolbox is built for one specific place in an agent loop: after the model proposes an action and before that action executes.

LLM proposes an action
      ↓
[ Agentoolbox gate(s): PASS / FLAG / BLOCK + certificate ]
      ↓ only on PASS (or FLAG, per policy)
Execute the action

The gates are deliberately narrow — one checkable question each — so they compose. A trading agent runs units + rug + slippage + position in parallel; a coding agent runs secrets + imports + vulnerabilities before it installs anything.