Retrieval Governance

Retrieval governance controls what your agents can see. Every retrieved document is evaluated against your rules before it reaches the agent’s context window — allow, redact, deny, or escalate per document. There is no additional code beyond the visiq() call shown in the Quickstart.

How retrieval governance works

When visiq() wraps your agent, it instruments every retriever it finds. The flow:

Agent calls a retriever tool (e.g., search_knowledge with query "Q3 revenue")
The retriever fetches raw results from the vector store
Each returned document is evaluated in-process against a locally cached rule bundle
Allow — document enters the context window unchanged
Redact — sensitive fields and patterns are masked before the agent sees the document
Deny — document is silently suppressed; the agent never sees it
Escalate — the access is recorded for human review; retrieval is synchronous (it can’t pause on a human), so the rule chooses whether the document passes through or comes back masked in the meantime

No error is thrown for denied documents — suppression is a normal policy outcome. If every document is denied, the retriever returns an empty array. Evaluation is local: the SDK evaluates against a cached rule bundle refreshed in the background (roughly every 5 seconds, with ETag/304 caching), so there is no network round-trip in the retrieval hot path. On a cold start with no bundle loaded yet, the mode envelope decides: an agent confirmed in enforce that has lost its bundle stays fail-closed — nothing leaks while rules are unknown — while a never-confirmed agent runs monitor (monitor-until-confirmed), observing without suppressing. Retrieval’s no-match default stays deny (the data-protection floor) wherever enforcement is active.

How retrievers are detected

The harness checks three structural patterns on each object it walks:

Pattern	Match condition	What gets instrumented
LangChain `BaseRetriever`	`tool._getRelevantDocuments` exists	`_getRelevantDocuments()` wrapped
Generic retriever	`tool.retrieve` exists	`retrieve()` wrapped
Nested retriever	`tool.retriever` is an object	Recurses into `.retriever` and re-applies the above patterns

Retriever-backed tools

Many frameworks wrap the retriever inside a tool function. The harness recognizes a retriever-backed tool structurally (a reachable .retriever property) or by name — names containing retriev, or search/knowledge-style names that carry no mutation verb (knowledge_base_update is treated as an action tool, not a retriever). Two cases follow:

Retriever reachable — the backing retriever is instrumented directly, so every document is evaluated with its own metadata (classification, data_categories, …) before the tool joins the results into a string. Full per-document fidelity.
Retriever hidden in a closure — LangChain’s createRetrieverTool captures the retriever in a closure and returns one joined string. The harness wraps the tool’s function and filters that string as a single blob: always-on secret detection, pattern masking, and whole-result rules still apply, but rules keyed on per-document metadata cannot fire on a metadata-less string. The SDK logs a one-time console warning for each such tool. For full per-document governance, pass the retriever to visiq() directly or use a tool that returns a Document[].

A tool that both retrieves and mutates (e.g. retrieve_and_archive) is a hybrid: one decision tagged ['retrieval', 'action'] governs both legs — the action side gates the call itself, the retrieval side filters what comes back.

Retrieval governance is not LangChain-only. On execute-based frameworks — Vercel AI SDK, Mastra, OpenAI Agents SDK, LlamaIndex, VoltAgent — the same visiq() call filters tool results through the retrieval facet.

Always-on secret detection

Even with zero authored rules, retrieved content passes a deterministic value-shape floor that masks sensitive values by shape, wherever they appear: private keys, JWTs, cloud and vendor API keys (AWS, GitHub, Slack, Stripe, Google, LLM providers), bearer tokens, connection strings with inline passwords, checksum-validated card numbers and IBANs, SSNs, tax IDs, and email addresses. Detectors with a larger false-positive surface (phone numbers, IP addresses, MAC addresses, bank routing codes) are available opt-in. Manage detectors under Settings → Organization → Security in the dashboard.

Key concepts

Rules

Policies over document metadata, trust tiers, and surfaces. Author in natural language, in the visual condition builder, or as policy source directly.

Need-to-know defaults

Every tenant is seeded a curated catalog of 35 default rules combining each agent’s trust tier (tier1 highest trust → tier3 restricted) with its business function: agents that need a data category get it, medium-trust access escalates or is masked, and agents with no need-to-know never see raw values.

Content redaction

Mask SSNs, credentials, and account numbers inside permitted documents. The agent sees the structure but not the sensitive values.

Signed receipts

Decisions — action and retrieval alike — emit record envelopes with asynchronous Ed25519-signed receipts (retrieval envelopes require artifact signing to be enabled for your organization). Tamper-evident proof for compliance audits.

Agent modes

Governance mode is set per agent, is server-authoritative, and is controlled from the Harness → Agents page in the dashboard — not from SDK config:

Mode	Behavior
`monitor`	Evaluate and record every decision but never block or mask — observe-only. The default for every new agent.
`enforce`	Apply per-document decisions — deny, redact, and escalate per policy.
`off`	Bypass retrieval governance entirely — all documents pass through.

Agents the harness sees for the first time are auto-provisioned in monitor mode, so instrumenting an agent never disrupts it. Watch its decision telemetry, tune your rules, then flip that one agent to enforce — no config change or redeploy required.

Monitor-first rollout is the intended adoption path: you see exactly what would have been denied, redacted, or escalated before any of it is enforced.

Operations of one rule engine

Action governance and retrieval governance are not two systems — they are the same rule engine evaluating one event against the operations it carries. An event is tagged with an operations[] set (action, retrieval, delegation — a hybrid read-then-write tool carries ['retrieval', 'action']), and a rule applies to whatever operations it targets, emitting an outcome from one shared vocabulary. The operations differ only in where the harness intercepts.

Dimension	Action operation	Retrieval operation
Governs	What agents can do (tool calls)	What agents can see (retrieved context)
Interception	Wrapped tool dispatch methods (`invoke`, `call`, `_call`) — framework callbacks are audit-only because they cannot block	Wrapped retriever methods (`_getRelevantDocuments`, `retrieve`) plus tool-result filtering
Outcomes	permit / deny / approval_required / mask	allow / deny / redact / escalate
Audit	Record envelopes with signed receipts, plus the human-approval queue	Record envelopes with signed receipts, plus a per-document audit log

The unified outcome set is permit · deny · approval_required · redact · escalate · mask; each operation uses only the subset that applies to it. The retrieval facet’s pass-through outcome appears on the wire as allow — the retrieval-plane spelling of the unified permit. (The unified POST /evaluate normalizes it to permit; the per-facet POST /recall/evaluate returns the literal allow.) Every operation is evaluated by the same engine — they activate together from a single visiq() call.

Next steps

Rules

The rule model: policy format, trust tiers, surfaces, and masking.

Receipts

Tamper-evident audit trail with Ed25519 signatures.

Emergency Bypass

Suspend one rule during an incident — bounded, audited, auto-expiring.

API Reference

REST API for rules, receipts, and the audit log.

Quickstart

Action Governance