Lookout

Lookout is the guardrail layer that sits between agent inputs/outputs and the LLM. It is four independent scanners composed into a middleware:

injection — heuristic prompt-injection detector (role-override, system-prompt leak, jailbreak tropes, confusable unicode).
args — JSON Schema validation of tool-call arguments before they reach the tool implementation.
output — structured-output parser that strips markdown fences, validates against schema, and produces a corrective re-prompt.
secrets — regex-based secrets redactor for outbound text.

All layers are purely in-process — no network calls in the default build. An optional Lakera bridge is available for the injection layer but disabled unless explicitly wired. When a scanner blocks something it emits guardrail.input_blocked or guardrail.output_blocked into the Crew Journal so the action is auditable. The matched secret value is NEVER persisted in the entry payload — only the finding kind and a stable redacted detail string.

Verdicts

type Verdict string
const (
    VerdictAllow    Verdict = "allow"    // pass through unchanged
    VerdictBlock    Verdict = "block"    // refuse to process
    VerdictSanitize Verdict = "sanitize" // cleaned version available
)

Severity maps to journal severity:

Lookout severity	Journal severity
`low`	`info`
`medium`	`notice`
`high`	`warn`
`critical`	`error`

Input guard

Runs on every user/tool-result message before it reaches the LLM:

guard := lookout.InputGuard(journalEmitter)
ctx = lookout.WithScope(ctx, lookout.Scope{WorkspaceID: ws, CrewID: crew, AgentID: agent})

_, err := guard(ctx, userMessage)
if lookout.IsBlocked(err) {
    // refuse the call; guardrail.input_blocked already emitted
}

Detectors (in injection.go):

Kind	Detail
`role_override`	Phrases like “ignore previous instructions”, “you are now”, “disregard system prompt”.
`system_prompt_leak`	Attempts to exfiltrate the system prompt.
`jailbreak`	Known jailbreak trope patterns (DAN, hypothetical framings, translations-as-evasion).
`zero_width_unicode`	ZWSP/ZWNJ/ZWJ/BOM codepoints.
`rtl_override_unicode`	RTL override codepoint (U+202E), escalated by per-1024-rune density.
`lakera_detected`	External Lakera Guard verdict when enabled.

The guard is wired into llm.Middleware so every Complete() call is scanned. The Stream() path runs through the same lookoutCaller chain (internal/llm/middleware.go), scanning every user/tool message synchronously before the first token flows.

Per-routine action policy

The default is hard-block on any high/critical finding. Routines whose upstream produces text that occasionally trips the heuristic on benign content (translations, security write-ups, adversarial-prompt research) can opt into a softer mode via DSL:

name: my-routine
guardrails:
  input:
    prompt_injection:
      action: sanitize    # block (default) | sanitize | log

Action	Behaviour	When to use
`block` (default)	Refuses the call; returns `*BlockedError`.	Production routines processing trusted inputs.
`sanitize`	Replaces matched byte ranges with `[REDACTED]`, lets the (defanged) text through.	Noisy upstreams where false positives would block legit traffic.
`log`	Passes the original text through unchanged; emits the journal entry only.	Observability-only mode; great for tuning the heuristic against a real workload.

The journal entry fires for ALL modes — log mode is observability, not “guard disabled”. The GuardListener integration hook (below) fires for all modes too. Sanitize uses offset-based replacement (Finding.Position + Finding.MatchEnd) so long matches and synthetic unicode findings (zero-width, RTL override) are properly redacted. An earlier substring-based implementation silently let those through.

Integration callback

Wire a callback to a notification target (Slack, PagerDuty, the hooks subsystem) so guardrail trips don’t just land in the journal:

ctx = lookout.WithGuardListener(ctx, func(ctx context.Context, direction string, findings []lookout.Finding) {
    // synchronous — keep cheap or dispatch async inside
    notify(direction, findings)
})

Runs synchronously after the journal entry is written, regardless of the action policy. The pipeline runner (internal/pipeline/runner_llm.go) already wires this to hooks.Dispatch(EventOnGuardrailTriggered, ...) when both the DB and a journal emitter are available — see the on_guardrail_triggered hook event.

Output guard

The default output policy is sanitize-and-pass. The secrets scanner runs over every outbound text and returns a redacted copy alongside findings:

guard := lookout.OutputGuard(j)
redacted, err := guard(ctx, llmOutput)
// redacted may differ from llmOutput; err is non-nil only on journal emit failure

Why sanitize instead of block? Losing an entire response because one sk-xxxx slipped through is too disruptive; redaction preserves the response while surfacing the finding in the journal. Callers that want hard-block semantics should re-scan the returned text and refuse downstream. Note: the output guard is NOT wired into llm.Middleware. Scanning output there would mutate text while leaving the provider-reported token counts intact — a desync. Output scanning lives in the orchestrator streaming pipeline where text mutations are visible to the agent loop.

Secrets detectors

Defined in secrets.go:

Kind	Pattern
`secret_openai`	`sk-[A-Za-z0-9]{20,}`
`secret_anthropic`	`sk-ant-[A-Za-z0-9_-]{40,}`
`secret_aws`	`AKIA` access key IDs (`AKIA` + 16 chars)
`secret_github_pat`	GitHub PAT — `ghp_` + 36 chars
`secret_github_oauth`	GitHub OAuth token — `gho_` + 36 chars
`secret_github_app`	GitHub server token — `ghs_` + 36 chars
`secret_bearer_token`	`Bearer <token>` (≥20 chars)
`secret_password`	quoted `password=...` / `password: "..."` assignments
`secret_api_key`	Generic `api_key=...`, `X-API-Key: ...` assignments

The stored finding carries kind and a redacted detail like "openai API key (prefix: sk-...)". The raw match is never emitted.

Tool-arg schema validation

lookout.ValidateArgs(schema, args) runs a minimal JSON-Schema-shaped validator (type / properties / required / items / enum / additionalProperties) over a tool call’s arguments. schema is a lookout.Schema struct, not a raw JSON string. Use it before dispatching:

if err := lookout.ValidateArgs(mySchema, toolArgs); err != nil {
    // Block the tool call; err describes which field didn't satisfy the schema.
}

ValidateArgs returns error (nil on pass) — concretely *ArgsInvalidError, whose Path points at the offending dotted JSON path. Type mismatches, missing required fields, and out-of-enum values all produce a non-nil error; unknown keys are rejected only when the schema sets additionalProperties: false. Empty schema (Type == "") = pass.

Adding a detector

Add a new Kind constant in types.go, a regex/detector function in the relevant layer file (injection.go, secrets.go, output.go), and register it in the scanner’s internal rule list. Tests in lookout_test.go use table-driven cases — add one for every new kind. Guidelines:

Detectors must be pure (no network, no state). The one exception, Lakera, is gated behind an explicit WithLakeraAPIKey option.
Never put the raw matched value in the Finding.Matched field for a secret detector. Use a prefix or a kind string.
Severity should reflect operational risk, not “how confident the regex is”. A false-positive secret_anthropic at warn is fine; one at critical would flood oncall.

Gotchas

Output guard is not in the LLM middleware. If you add a new streaming consumer, wire OutputGuard yourself or secrets may flow through to clients unredacted.

More edge cases

Scope is required. emitGuardEntry silently no-ops if lookout.ScopeFromContext(ctx) returns zero. Always wrap your request context with lookout.WithScope(ctx, scope) before invoking the guards — the HTTP handler chain does this for you.
Sanitize verdict is not a block. The returned text is the safe version; the err is non-nil only if the journal emit fell over.

LLM middleware — where InputGuard is composed.
Harbormaster — complementary: approvals gate the action, Lookout sanitises the content.
Crew Journal — guardrail.input_blocked / guardrail.output_blocked.

Get Started

Guides

Security

Configuration

Manifest Reference

Lookout

Lookout

Verdicts

Input guard

Per-routine action policy

Integration callback

Output guard

Secrets detectors

Tool-arg schema validation

Adding a detector

Gotchas

​Lookout

​Verdicts

​Input guard

​Per-routine action policy

​Integration callback

​Output guard

​Secrets detectors

​Tool-arg schema validation

​Adding a detector

​Gotchas

​Related

Lookout

Verdicts

Input guard

Per-routine action policy

Integration callback

Output guard

Secrets detectors

Tool-arg schema validation

Adding a detector

Gotchas

Related