Architecture Decision Records

Architecture Decision Records (ADRs)

This document aggregates all formal Architecture Decision Records (ADRs) governing AgentGate's runtime design, security boundaries, and infrastructure choices.

---

ADR 0001: Decision Model, Not Generative Judge

• Date: 2026-10-08
• Status: Accepted

Context

We need to judge if an agent's tool call is safe. The industry standard is an LLM-as-judge (prompting GPT-4 or Claude with instructions to inspect the call), but that approach suffers from:

• Excessive latency (500–2000ms per tool invocation).
• Unparseable outputs (JSON failures, formatting deviations).
• Lack of calibrated confidence (no true probability vector).
• Vulnerability to recursive prompt injection (attack payload jailbreaks the judge).

Decision

We use a specialized, fine-tuned classification decision model instead of a generative token-generating LLM. The model outputs closed-set probability distributions across 4 calibrated heads (untrusted_influence, goal_alignment, reversibility, external_send) via a single forward pass.

Consequences

• Sub-40ms execution latency (p95 < 38ms).
• Zero KV-cache overhead or generative hallucinations.
• Deterministic mathematical probabilities feeding downstream policy rules.

---

ADR 0002: Verdict Comes from a Policy Layer, Not the Model

• Date: 2026-10-08
• Status: Accepted

Context

The decision model produces probability vectors over risk classes. We need a way to map these probabilities to an operational verdict (allow, ask, or deny).

Decision

The verdict is computed by an explicit, deterministic policy layer (policy.yaml) outside of the model weights, rather than having the neural network directly output a compliance verdict.

Consequences

• Security teams can adjust thresholds per tool without retraining model weights.
• Complete explainability and auditability for every decision.
• Decouples mathematical risk estimation from organizational business rules.

---

ADR 0003: Structured YAML Conditions, No Expression Evaluation

• Date: 2026-10-08
• Status: Accepted

Context

The policy layer needs rules. Allowing arbitrary script expressions (such as JavaScript eval() or CEL expressions) introduces a secondary code injection attack surface.

Decision

We use structured YAML condition trees (all, any, gt, lt) instead of dynamic expression evaluation.

Consequences

• Zero code injection attack surface.
• Deterministic, schema-validated rules (enforced with Zod).
• Enables offline policy replay against historic traffic without runtime side effects.

---

ADR 0004: Explicit User Goal Declaration

• Date: 2026-10-08
• Status: Accepted

Context

The gateway needs to understand the user's intended objective to evaluate goal_alignment. MCP and standard tool calls do not natively carry the user's session goal. Inferring the goal from dynamic traffic is non-deterministic and error-prone.

Decision

The user goal must be supplied explicitly upon session initialization (POST /v1/sessions).

Consequences

• Eliminates goal inference false positives.
• Provides a cryptographic and traceable anchor for what the agent was authorized to do.

---

ADR 0005: Small Base Model First

• Date: 2026-10-08
• Status: Accepted

Context

We need to select a base model for fine-tuning. Larger models (7B, 14B+) provide capacity but require massive GPU clusters and introduce latency overheads exceeding 100ms.

Decision

We start with a compact base architecture (fine-tuned Qwen 0.8B via 4-bit LoRA with Unsloth) and scale upward only if empirical classification boundaries demand additional parameter capacity.

Consequences

• Fits easily within consumer and edge GPUs (< 2 GB VRAM).
• Extremely low inference latency (28ms p50).
• Highly cost-effective deployment across commodity cloud instances (T4, A10G, L4).

---

ADR 0006: Default Fail-Closed

• Date: 2026-10-08
• Status: Accepted

Context

When the decision server, database, or upstream network is unavailable or times out, the proxy must determine how to handle agent tool invocations.

Decision

The gateway defaults to fail-closed behavior (deny or route to operator review ask) whenever health checks or neural deadline timeouts are violated.

Consequences

• Guarantees safety during infrastructure failures or denial-of-service attempts.
• Read-only actions (such as read_file) can be explicitly whitelisted in policy.yaml if higher availability is required.

---

ADR 0007: Structured Provenance Tags in Context

• Date: 2026-10-08
• Status: Accepted

Context

The neural model must differentiate between trusted developer instructions and untrusted content (such as email bodies, web scrapes, or user comments).

Decision

The proxy parses conversation histories and marks untrusted inputs using structured XML-style tags (<untrusted>...</untrusted>) while strictly escaping delimiter strings within untrusted text.

Consequences

• Prevents delimiter spoofing by adversarial prompt injection payloads.
• Provides clear positional cues for the classification model.

---

ADR 0008: PostgreSQL for Unified Storage

• Date: 2026-10-08
• Status: Accepted

Context

AgentGate requires persistence for sessions, decisions, audit logs, policy versions, and human approvals. Introducing Kafka, Redis, and Mongo increases operational complexity.

Decision

We use PostgreSQL 16 as the single unified persistence engine. Real-time event propagation is handled via Postgres Pub/Sub (LISTEN / pg_notify).

Consequences

• Simple operational footprint (only one stateful container or managed DB).
• ACID transactions guarantee atomic policy activation and approval resolution.
• Keyset cursor pagination provides constant-time audit log queries over millions of events.