It is a Monday morning in case UW-G07. A broker's email for SUB-2007 arrives with a line at the end: "The owner's tax id 000-00-0000 is attached for the file." The input check G-IN-PII should replace that identifier before the model reads the email. To find it, the check calls a personal-data detector, a separate service run by another team. This morning the detector is down.
The guard has to do something with the email. It can hold the email until the detector is back, or it can let the email through unchecked. Nobody is awake to ask. Whatever the code does in the next millisecond was decided months ago, by whoever wrote the line that handles a failed call, often without noticing that it was a decision.
The earlier pages treated each guard as a function that always answers. This page treats it as what it is in production: a dependency that can be slow, down or wrong, that costs time on every request, and that must leave a record a person can investigate later.
1. When the check itself cannot run#
Every guard needs something to run: a pattern list, a classifier service, a policy decision point, a proxy. When that dependency fails, the guard has no answer, and the code around it must pick one.
To fail open means that when a check cannot run, the request passes as if the check had allowed it. Example: the personal-data detector is down, and the email reaches the model with the identifier still in it.
To fail closed means that when a check cannot run, the request is refused or held for a person. Example: the detector is down, and the email waits in a queue until someone looks at it or the detector returns.
The example runs UW-G07 three ways. The roof provider also times out in this case: the runtime retries once (attempt 2) and then the rules ask for information, a controlled fallback. That part is the same in all three runs. What changes is the detector.
Each block below is an excerpt of the printout (the lines that matter here), followed by its complete summary lines. Healthy detector, run_guards.py --case UW-G07 --profile full:
5 REDACT G-IN-PII redacted 1 identifier before the model reads the text
17 tool_error get_roof_assessment: no answer after 2000 ms
24 tool_error get_roof_assessment: no answer after 2000 ms
43 candidate candidate recommendation: request_info
55 route the row goes to: ask_for_information
outcome: request_info · routed to ask_for_information · data left: no
audit events: 34 (33 allow, 1 other) · denials: none
harms: none
Detector down, fail closed, with --pii-detector down --pii-mode fail_closed:
5 DENY G-IN-PII the personal-data detector is down; fail closed: the text is held for a person
7 stop the run stops before the model: held for a person
outcome: held · data left: no
audit events: 4 (3 allow, 1 other) · denials: G-IN-PII
harms: none
Detector down, fail open, with --pii-detector down --pii-mode fail_open and --verbose, which also prints allow decisions:
5 ALLOW G-IN-PII the personal-data detector is down; fail open: the text passes unchecked
outcome: request_info · routed to ask_for_information · data left: no
audit events: 34 (34 allow, 0 other) · denials: none
harms: pii_to_model
The fail-closed run did no harm and did no work: the email waits. The fail-open run did the work and did a harm: pii_to_model, the identifier reached the model, and from there every log and trace that stores model input. Neither is free. That is why the choice is made per check, with its cost written down.
The agent here is a scripted stand-in. The obedient variant is fooled every time by construction, so these results show how each control works, not how often a real model is fooled or how good any model is.
Production pitfall. Look at the last summary line:34 allow, 0 other. The fail-open decision is recorded with the decisionallow; only its reason says "passes unchecked". A dashboard that counts denials or flags sees a perfectly healthy morning. Give an unchecked pass its own marker in the audit event (a separate field or decision value), and alert on it.
2. Decide per check#
The right mode depends on two questions. What harm gets through if this check is skipped? And does another layer stand behind it that does the same job?
G-IN-INJECT only flags. When its classifier is down, the tool gate and the policy gate still stand behind it, so failing open costs a weak signal, not a control. G-OUT-POLICY is the check that makes the rules hold; nothing behind it does the same job, so it fails closed. G-NET-EGRESS is the last layer; failing open removes the only check on bytes leaving.
In the lab, pick a guard, the state of its dependency and the mode. The traffic is synthetic: 200 requests per guard with a fixed share of unsafe ones; "slow" means 30 percent of checks miss their time budget and cannot decide.
| Guard | Dependency | Mode | Served | Legitimate blocked | Unsafe let through | Sent to people |
|---|---|---|---|---|---|---|
G-IN-PII | slow | fail open | 183 | 0 | 7 | 0 |
G-IN-PII | slow | fail closed | 123 | 53 | 0 | 60 |
G-IN-PII | down | fail open | 200 | 0 | 24 | 0 |
G-IN-PII | down | fail closed | 0 | 176 | 0 | 200 |
G-IN-INJECT | down | fail open | 200 | 0 | 10 | 0 |
G-IN-INJECT | down | fail closed | 0 | 190 | 0 | 200 |
G-OUT-POLICY | down | fail open | 200 | 0 | 14 | 0 |
G-OUT-POLICY | down | fail closed | 0 | 186 | 0 | 200 |
G-NET-EGRESS | down | fail open | 200 | 0 | 4 | 0 |
G-NET-EGRESS | down | fail closed | 0 | 196 | 0 | 200 |
The column "Sent to people" is the price of failing closed, and it is easy to forget. Two hundred held emails (a synthetic count) are work that people must do instead. A fail-closed decision is only safe if the queue it fills has people, a target time and a safe default (Human in the loop gives the default: ask for information, never approve).
The example's own choices, with the reasons from scenarios.py:
| Guard | Depends on | Mode | Why |
|---|---|---|---|
G-IN-PII | the personal-data detector | fail closed | An unchecked identifier reaches the model and every log after it; holding the email costs minutes |
G-IN-INJECT | the classifier service | fail open | It only flags; the tool gate and the policy gate still stand behind it |
G-OUT-POLICY | the policy decision point | fail closed | It is the check that makes the rule hold; nothing behind it does the same job |
G-OUT-LEAK | the pattern service | fail closed | A leaked contact cannot be called back once a person has read it |
G-NET-EGRESS | the egress proxy | fail closed | It is the last layer; failing open removes the only check on bytes leaving |
Before AI. A database constraint never has to choose: it runs in the same transaction as the write, so if it cannot run, the write cannot happen either. A check that calls another service, such as a Spring Security filter that asks an authorization server whether a token is valid, has the same choice as G-IN-PII; the usual design rejects the request when the server cannot be reached. The lesson carries over: a check that lives with the data cannot fail separately from it; a remote check can, and its failure mode is a design decision.
Frameworks make the same decision for you, sometimes silently. Frameworks lists, from each tool's documentation, where a guard quietly fails open: a missing result read as "allow", a configuration that falls back without the rail. In each case the calling code had to decide; this page is where that decision is written down.
3. The latency budget#
A latency budget is the time a check may take before the request must move on. Example: if G-IN-INJECT has 40 ms and its classifier answers in 300 ms, the check has missed its budget and counts as unable to run.
Checks add up. In the example's simulated clock (illustrative numbers, not measurements), UW-G01 runs 32 guard checks costing 118 ms of a 2,504 ms run; UW-G06 runs 35 checks costing 121 ms. Most checks cost 1 or 2 ms because they are deterministic code. The classifier stand-in costs 40 ms each time it runs. The model turns, at 900 ms each, are the bulk.
Two rules follow. Spend the budget where the harm is: deterministic checks before a tool are nearly free, a model-based check is not. And a slow dependency is a failing dependency: when 30 percent of checks miss their budget (the "slow" rows of the table above), the mode decides what happens to those 30 percent. A timeout without a mode is a fail-open path nobody chose.
4. The audit event and the audit trail#
An audit event is the record of one guard decision, with enough ids to find everything else about it. Example: the event that records G-TOOL-ALLOW denying the export in UW-G06.
This is that event, exactly as the example writes it (pipeline.run_case("UW-G06", "full")["audit"], event AE-0020, in a scratch copy):
{
"event_id": "AE-0020",
"ts_ms": 1782950401573,
"run_id": "run-3a7b",
"trace_id": "0cfe2645d69a01cc9a4864750c4a0694",
"span_id": "5e4d53fa48e04b65",
"attempt_number": 1,
"submission_id": "SUB-2006",
"policy_version": "2026.2",
"guard": "G-TOOL-ALLOW",
"place": "before_tool",
"decision": "deny",
"reason": "export_submissions is not on the agent's allowlist",
"subject": "tool export_submissions",
"actor": "underwriting-agent",
"evidence_ids": [
"EV-ROOF-0412"
]
}
Each field answers a question an investigator will ask:
| Field | The question it answers |
|---|---|
event_id, ts_ms | Which decision, and when |
run_id, attempt_number | Which execution of the workflow, and which retry inside it |
trace_id, span_id | Where in the run's trace (one trace per run; this check is one span) |
submission_id | Which business record |
policy_version | Under which version of the rules |
guard, place | Which check, standing where |
decision, reason, subject | What it decided, why, and about what |
actor | On whose behalf the action was attempted |
evidence_ids | Which evidence the decision rests on: here, the roof report whose text caused the call |
The last field is the one that turns a denial into a story. EV-ROOF-0412 points to the roof assessment. An investigator can go from "the export was refused" to "because of this provider's description" without reading the model's text at all.
An audit trail is the ordered set of audit events of a run, kept so that the run can be reconstructed and checked later. Example: the 35 events of UW-G06 under full, from the tenancy check at intake to the escalation at approval.
Read the trail of UW-G06 under both profiles:
| Profile | Events | Events that are not allow |
|---|---|---|
prompt_only | 0 | none: nothing ran, so nothing can be investigated afterwards |
full | 35 | G-IN-INJECT flag (roof description); G-TOOL-ALLOW, G-TOOL-ARGS, G-TOOL-SCOPE deny (export_submissions); G-OUT-POLICY deny (candidate approve); G-HUMAN escalate |
The first row is the quiet argument for guardrails. Under prompt_only twenty records left for collector.example, and the run left no record of any decision, because no decision was made. A warning in a prompt leaves nothing to audit.
Why keep the 29 allow events too? Because an investigation asks "was this check running?" as often as "what did it deny?". An allow with a reason proves the check ran on this request, under this version. Protocols now ask for the same record: the Model Context Protocol specification, read today, says clients should log tool usage for audit purposes and implement timeouts for tool calls (Agent systems covers tool servers).
What this is not. Logs, metrics and traces as evidence, how to store them, query them and replay a run, belong to Observability. This page fixes what one guard decision must record; that site shows how the records become evidence.
5. Exceptions with an owner and an expiry#
In UW-G02 the broker's email asks for "an exception this once" for a roof of 31 years in zone C. That sentence is not an exception. It is a request, in untrusted text, and the policy gate ignores it.
An exception in the governance sense is a recorded, time-limited permission to depart from one rule for one case, granted by a named role with the authority to grant it. Example: a senior underwriter allows SUB-2002 to be assessed despite R-ROOF-01 because a new roof is already contracted, until a set date.
The example does not implement exceptions. This is a design for what one must record, as data the policy decision point can read:
{
"exception_id": "EXC-0007",
"rule_id": "R-ROOF-01",
"submission_id": "SUB-2002",
"policy_version": "2026.2",
"granted_by": "senior_underwriter",
"reason": "Roof replacement contracted; inspection report on file",
"evidence_ids": ["EV-ROOF-2002-INSP"],
"granted_ts_ms": 1782950400000,
"expires_ts_ms": 1785542400000
}
Every field is a guardrail on the exception itself. It names one rule, not "the roof rules". It names one submission, not a brokerage. It names the role that granted it, so the approval check can verify the role. It carries evidence. And it expires: the policy decision point stops honoring it after expires_ts_ms without anyone remembering to remove it. An exception without an expiry is a rule change made without change control (Policy as code owns change control).
The decision to grant an exception, and who may grant one, is governance: the organization's own controls. The guardrail is that the exception enters the system only as a record like this one, checked by code, never as a sentence that a model reads.
6. Break-glass#
Break-glass is a prepared emergency procedure that lets a named person turn a control off, or change its mode, for a short time, with an alarm and a record. Example: the detector of UW-G07 is down for hours and 200 emails are held; the on-call lead switches G-IN-PII to fail open for 30 minutes, under a ticket number.
Break-glass exists because fail closed can stop the business, and someone will turn the guard off anyway; better that it happens through a door that records it. The design rules are short:
| Rule | Why |
|---|---|
| Named people only, with a second person's confirmation | No one turns off a guard alone |
| Time-boxed, with an automatic end | It cannot become the new normal by forgetting |
| Every run in the window is marked in its audit events | Investigators can find exactly which runs were unprotected |
| An alarm fires when it starts | The security team knows before the attacker does |
| A review after every use | Each use is an incident with an owner |
Break-glass changes a mode; it never grants an agent a new scope or tool. The agent's identity still lacks records:export during an emergency. The emergency is about availability, not about authority.
7. Shadow mode: a new check watches before it decides#
Shadow mode means running a new check on live traffic so that it records what it would have decided, while its decision changes nothing. Example: G-IN-INJECT is proposed to hold, not only flag, every text scoring 0.20 or more; for two weeks it writes "would deny" events and every request continues as before.
Why not switch it on directly? Because the cost of a new check is false positives on honest traffic, and those you cannot see in an attack suite. On Testing, the example's benign suite shows the price of exactly this change: with the classifier set to block at 0.20, six honest broker notes are blocked. On live traffic the share could be higher or lower; shadow mode is how you find out before a broker does.
What shadow mode needs, as a design:
| Need | Why |
|---|---|
| Its events marked as shadow | They must never count as decisions in reports |
The same ids as the run (run_id, trace_id) | Each "would deny" can be compared with what really happened |
| A person who reviews a sample of "would deny" | To count false positives in words, not guesses |
| A written promotion rule | For example: promote when the reviewed false-positive count is acceptable to the underwriting lead |
| A date to stop | A shadow check that never promotes is cost without protection |
Shadow mode is also how a change to an existing check ships: run the new version beside the old one, compare their decisions on the same requests, and switch when the differences are understood.
Diagram: When a guard cannot run · the mode decides, and each mode has a price
Read left to right. A guard needs a dependency. When the dependency is slow or down, the guard has no answer. Fail closed holds the request for a person: no harm, but work for people. Fail open lets it pass: work done, harm possible. The choice is written per guard, before the incident.
- The guard
- G-IN-PII: Redacts identifiers before the model reads the email.
- Its dependency
- Detector down: The check has no answer for this request.
- Fail closed
- Held for a person: The run stops before the model; the email waits.
- Fail open
- Passes unchecked: The work continues; the identifier reaches the model.
- Who pays
- People or risk: Closed fills a queue; open lets unsafe requests through.
Diagram: One denial, one audit event, one answerable question
Time runs down the page. In UW-G06 the tool gate denies the export. The runtime writes one audit event with the run, trace, span, submission, policy version and evidence ids. Weeks later an investigator starts from the denial and reaches the roof report that caused it without reading the model's text.
- Tool gate (code) to Runtime: deny: not on the allowlist. One guard decision with its reason and subject.
- Runtime to Audit trail: AE-0020 with run, trace, span, version. The ids tie the event to the run, the step and the rules in force.
- Investigator to Audit trail: why was the export refused?. The question arrives weeks later.
- Audit trail to Investigator: evidence EV-ROOF-0412: the roof report. The evidence id points to the text that caused the call.
For the Principal engineer: correlated failure, the cost of fail closed, and audit data as personal data
Write the mode matrix down, with its dependency. For each guard: the dependency, its timeout, the mode on timeout, the mode on error, the queue that fail closed fills, and who is paged. The example's choices are one row each in scenarios.py. A guard whose row is missing has a mode anyway: the default of whatever library raised the exception.
Failures correlate. The detector, the classifier and the policy decision point may share a cluster, a network path or a deployment pipeline. One incident can take down three guards at once, and three fail-closed modes together hold all traffic. Test the combinations, not only single failures, and size the people queue for the worst one.
Fail closed has a capacity. "Held for a person" is a promise to do the work later. If the queue has no target time, the business will route around it. Give held items a target, a safe default on timeout (request_info back to the broker), and an alarm when the queue grows faster than people clear it.
Fail open needs its own trace. In the example a fail-open pass is an allow with a reason. In production make it impossible to miss: a distinct field, a counter, and an alert. The unprotected window must be computable afterwards: which runs, which submissions, which identifiers may have reached the model and its logs.
Retries are inside the run. UW-G07 retries the roof lookup: the same run_id, attempt_number 2, a new span. The guard decisions of each attempt carry the attempt number, so a reader can tell the two calls apart. The full mechanics of retries, timeouts and circuit breakers belong to Agent Reliability.
The audit trail is sensitive data. Reasons, subjects and evidence ids describe customers and attacks. Redact before writing: G-IN-PII records "redacted 1 identifier", never the identifier. Make the store append-only for writers, readable by investigators under their own audit, and keep it as long as the regulator and the insurer's retention policy require, not longer.
Never sample denials. High-volume systems sample traces. Sample allows if you must, never denials, flags, escalations, fail-open passes or break-glass windows. Those are exactly the events an investigation needs.
Exceptions are policy data, versioned with the policy. An exception granted under 2026.2 should be re-examined when the rules move to the next version; the rule it departs from may have changed. Keep exceptions in the same store as the policy fixture, read by the same decision point, so a decision log shows rule, version and exception together.
Shadow mode has a cost too. A shadow check runs on every request: it spends latency budget and dependency capacity, and it can fail. Run it off the critical path (after the response, or asynchronously) when its result does not need to be compared in the same request.
Checklist#
| Before you put a guard into production | Check |
|---|---|
| Each guard has a written mode for timeout and for error | Fail open or fail closed, with the reason |
| A fail-closed queue has people, a target time and a safe default | Never approve on timeout |
| A fail-open pass is marked and alerted | Not recorded as an ordinary allow |
| Each check has a latency budget | A missed budget follows the mode |
| Every decision is an audit event with the run's ids | run_id, trace_id, span_id, attempt_number, submission_id, policy_version |
| Audit events carry evidence ids and no raw personal data | Redacted before writing |
| Exceptions are records with one rule, one case, a role and an expiry | Read by the decision point, never by the model |
| Break-glass is named, time-boxed, alarmed and reviewed | It changes modes, never scopes |
| A new or changed check runs in shadow mode first | With a promotion rule and an end date |
In one breath#
A guard in production is a dependency, so for every check decide in advance what happens when it cannot run: fail closed where nothing behind it does the same job, fail open only where another layer stands behind it, and staff the queue that failing closed fills. Every decision leaves an audit event with the run, trace, span, attempt, submission, policy version and evidence, so a denial can be investigated and an unprotected window can be measured. Departures from the rules are records with an owner and an expiry, emergencies go through a loud break-glass door, and a new check watches in shadow mode before it decides.
Hand-off#
You can now run the guards as a production system: each with a failure mode, a budget and a record. What remains are the places where correctly running guards still leak: untrusted text that comes back looking trusted, data that leaves through an allowed door, and two rules that both apply and disagree. The next page, Advanced, takes those one by one.