Flow control¶
Rules and matchers look at one event at a time. Prompt injection does not work one event at a time: an agent reads an email written by a stranger, and three steps later it sends your customer data to the address that email gave it. Each step looks harmless; the sequence is the attack.
Flow control decides at dispatch whether a tool call may run, given what the session has already read. Its rule is the "lethal trifecta" (private data, untrusted content, a way out) made structural:
| The session has read | Then a read |
a write |
a send |
|---|---|---|---|
| nothing labelled | runs | runs | runs |
| untrusted content (written by someone else) | runs | needs approval | needs approval |
| sensitive data (private) | runs | runs | needs approval |
The labels come from your declarations of what each tool returns, not from reading the content. A prompt injection cannot talk its way past them, because nothing inspects what it says.
Measured on an inbox assistant with gpt-4.1-mini, twice: unguarded, 65 and 64 emails to attacker addresses and 30 and 29 bank-detail tickets across 42 attack runs; with flow control, none executed. See examples/flow-control.
Declare your tools¶
tools:
read_inbox:
effect: read
returns: [untrusted, sensitive] # strangers write it, and it is private
read_crm:
effect: read
returns: sensitive
search_web:
effect: send # the query leaves the company
returns: untrusted
send_email:
effect: send
create_ticket:
effect: write
"crm_*": # globs work; an exact name wins over a glob
effect: read
returns: sensitive
flow:
undeclared: treat_as_send # or: deny
on_block: require_approval # or: deny
approval_tier: strong # or: soft
| Effect | Means | Examples |
|---|---|---|
read |
brings content in, changes nothing, sends nothing out | read a file, query a database |
write |
changes state inside the organisation | create a ticket, update a record |
send |
anything leaves the session's trust boundary, including arguments | email, webhook, web search, fetch a URL |
| Label | Put on a tool's results when |
|---|---|
untrusted |
someone other than the person the agent works for wrote it: email, web pages, uploaded files, tickets from customers |
sensitive |
it must not leave: customer records, HR, finance, secrets |
Declarations are the security boundary
A tool declared read whose arguments leave the company (a web search, a URL fetch, an
API lookup by name) is an exfiltration channel: "search for <the customer's ARR>". Declare
it send. When unsure, declare send.
An undeclared tool is treated as a send whose results are untrusted, or refused with
flow: {undeclared: deny} (recommended once your tool list is complete).
Globs. An exact name wins over a glob. When several globs match a tool, they combine
conservatively: the most restrictive effect and all their labels, so the order in the file never
matters ("crm_*": read and "crm_send*": send make crm_send_mail a send). A glob also
covers tools added later: "*_report": {effect: read} silently makes a future send_report a
read. Use globs only for families whose effect you control, and never "*": {effect: read}.
Use it¶
from theaios.guardrails import load_policy
from theaios.guardrails.flow import FlowGuard, FlowBlocked
guard = FlowGuard(load_policy("guardrails.yaml")) # one per process, kept for its lifetime
# In your tool dispatcher:
admission = guard.admit(session_id, "send_email", {"to": to, "body": body}, agent="assistant")
if admission.allowed:
try:
result = send_email(to=to, body=body)
finally:
guard.observe(session_id, "send_email") # after EVERY call that ran, even if it raised
elif admission.proposal is not None:
queue_for_approval(admission.proposal) # tell the model it is waiting
else:
refuse(admission.reasons)
Or let the guard do the three steps:
result = guard.call(session_id, "read_inbox", read_inbox) # admit, run, observe
guard.call(session_id, "send_email", send_email, {"to": to, "body": body}) # raises FlowBlocked
@guard.tool("send_email", session=lambda: current_session_id())
def send(to: str, body: str) -> str: ...
Arguments are passed as a dict, never mixed with the guard's own parameters: a model that puts
"agent": "admin" in its tool arguments cannot change the identity your profiles check.
Arguments must be plain JSON (strings, numbers, booleans, null, lists, objects with string
keys, at most 100 levels deep) and at most 1 MB; anything else raises ValueError, because the
approval digest must cover every byte.
observe must be called after every tool call that ran, including one that raised: an
error message can carry the injected content. call, the decorator and execute do it for
you. Forgetting it is the one way to misuse the API: the session would not know what it read.
Keep one guard. Taint lives in the guard's store. A guard created per request with the default in-memory store forgets everything between requests.
Each call is also evaluated against your existing rules and profiles, as an action event
(data = the arguments plus action = the tool name) and as a tool_call event
(data = {"tool_name": ..., "arguments": {...}}), so rules written for either scope apply.
A rule's deny wins over everything; a rule's require_approval joins the flow reasons in the
same proposal. agent is what your profiles and rules see; taint is per session_id only, so
never reuse a session id across users.
Typed denials¶
Every decision that is not a plain allow carries reasons with a code for programs, a sentence for people, and the tool calls that caused it:
admission.codes # [Code.UNTRUSTED_TO_SEND, Code.SENSITIVE_TO_SEND]
admission.reasons[0].message
# "the session read untrusted content (read_inbox); a send needs approval"
admission.reasons[0].provenance # [Provenance(tool="read_inbox", label=..., call_id=..., at=...)]
| Code | When |
|---|---|
undeclared_tool |
flow.undeclared: deny and the tool is not declared |
untrusted_to_write / untrusted_to_send |
the session read untrusted content |
sensitive_to_send |
the session read sensitive data |
rule_deny / rule_approval |
one of your rules |
Proposals: decided once, executed by code¶
A blocked call becomes a Proposal: the tool, the exact arguments, a SHA-256 digest of both,
the reasons and the tier. A person decides; your code runs it.
TOOLS = {"send_email": send_email, "create_ticket": create_ticket} # your tool registry
for p in guard.pending(session_id):
show(p.tool, p.args, [r.message for r in p.reasons])
guard.decide(p.id, approve=True, by="lea", note="checked the address") # once
guard.execute(p.id, TOOLS) # runs TOOLS[p.tool](**p.args), at most once
guard.proposal(p.id) # any proposal by id, whatever its status
- A proposal can be decided once; a second decision raises
ProposalError. executeruns only an approved proposal, only the function registered under the approved tool name, only with the proposed arguments, and at most once, even under concurrency. It is marked executed before it runs: a call that fails is not retried, and a retry needs a new approval.- If the model asks again for the same call, for the same reasons, while it is pending,
admitreturns the existing proposal instead of queueing a duplicate. If the reasons changed (the session read something since), a new proposal states them and the old one becomessuperseded, so the same call cannot be approved twice.clearleaves pending proposals pending: a person still decides them. pending,proposalanddecidereturn copies; changing them changes nothing.- Functions decorated with
@guard.toolcan go in the registry, under the name they were decorated with:executeruns the original function without admitting it again. Any other function, including your own wrapper around a decorated one, runs as it is (a wrapper that calls a guarded tool is guarded again). - The decorator passes default argument values explicitly, so the approver sees every value
the call will use. It refuses functions with
*args,**kwargsor positional-only parameters, whose calls could not be replayed exactly as approved. - Approval covers that one call. The session stays tainted: the next send needs its own
approval. To start a fresh task,
guard.clear(session_id, by="lea", reason="new task").
Durable state¶
By default labels and proposals live in memory. Keep them across restarts, and make the history tamper-evident, with a file store:
from theaios.guardrails import load_policy
from theaios.guardrails.flow import FileStore, FlowGuard
policy = load_policy("guardrails.yaml")
guard = FlowGuard(policy, store=FileStore(".guardrails_flow/state.jsonl"))
Every label, proposal, decision and clear is appended to a hash-chained log (theaios-core).
Next to it, state.jsonl.head records how many entries there are and the last hash, so that
deleting the last lines is caught too (a hash chain alone cannot see its end being cut).
FileStore checks both when it opens the file and raises StoreCorrupted rather than resume
from a history that was edited, truncated or emptied. Check a file from the command line:
- One store per file.
FileStoreholds an exclusive lock on the log while open; a second open, in this process or another, under any path or hard link, raisesStoreInUse. Close it (store.close()orwith FileStore(...) as store:) to release it. - Private. The files are created readable by their owner only (0600): they hold the arguments of proposed calls. Back them up and delete them like any data they contain.
- Recovery. The error says what happened. An interrupted write (crash) leaves an incomplete last line: remove only that line. Anything else (edited, deleted or reordered entries, a missing file or anchor) means the history cannot be trusted: restore both files from backup. Starting a new file drops every label and pending proposal; do it knowingly.
- Limits. This protects against accidents and naive tampering: a crash mid-write (at most one entry past the anchor is accepted), deleted last lines, an emptied file, edits, reordering, two writers. It does not stop someone who can write the directory: the chain uses no secret, so they can append valid entries and update the anchor, restore an older pair of files (re-arming an approval that already ran), or delete both files (a fresh, empty store). Write access to the state directory is control of the guard: protect it with file permissions and back it up.
Who may do what¶
The guard decides whether a call needs a person; it does not know who the person is.
What it protects against: the model, and the content the model reads. Your application
code is trusted: it can call your tools directly, and it can write the guard's store
(guard.store and its methods are internal; use the guard's methods). Flow control stops a
prompt injection from acting through the model; it does not stop your own code from bypassing
it.
- Never expose
decide,executeorclearas tools the model can call. The model would approve its own proposals or clear its own taint. by=indecideandclearis recorded as given: authenticate the approver in your own application before calling them, and check they may decide for that session.decide(approve=...)accepts onlyTrueorFalse: convert form or JSON input explicitly (the string"false"is truthy, so it is refused rather than read as an approval).- Anyone with a proposal id and the guard can call
execute; keep proposal ids inside your backend. - Agent and approval UI. Run the guard in one service (the one that runs the agent). Expose pending proposals and a decide endpoint from that service to your approval UI, instead of opening the same store from a second process.
- Show the approver the reasons and the exact arguments, and watch the approval rate: if people approve without reading, the control has become theatre.
What it costs, and what it does not do¶
- Approvals. Every write or send after untrusted content, and every send after sensitive data, waits for a person. Measure how many before deploying (the example shows how).
- The person still has to say no. A proposal makes an attack visible, with its reason and arguments; someone who approves everything approves the attack. Watch the approval rate.
- Content attacks are not covered. An injection that changes what the agent says (a wrong summary, a false number) rather than what it does passes. Use grounded numbers and TrustGate text checks.
- Labels are per session, not per value. After reading one untrusted email, every later send waits, even one built only from trusted data. Tracking each value's origin (as in CaMeL) would allow more without approval; it needs control of the agent's planner and is outside this library.
Grounded numbers¶
Generated reports and emails get the prose right and a figure wrong. check_numbers finds
each number in a generated text and looks for it in the sources the agent was given, allowing
for rounding and units:
from theaios.guardrails.grounding import check_numbers
report = check_numbers(draft, [crm_record, maria_email])
if not report.ok:
print(report.summary()) # "1 of 4 figures not found in sources: 3.4M"
"3.2M" is grounded by "3,215,000", "12.3%" by "12.34%" or "0.1234". European formats are read
too ("9.999.000", "9 999 000", "12,34%"). Whole numbers up to 10 ("3 steps") are skipped by
default (ignore_small=-1 checks them).
Not checked: dates in common formats ("2026-11-09", "11/09/2026", "14 March 2026",
"March 15, 2026"; month names in English only, so "14 mars 2026" is read as figures, and a
year without a day, as in "March 2026" or "Q3 2026", is checked as a figure),
identifiers glued to letters (gpt-4.1, Q3), and currencies ("$3,215,000" is grounded
by "3,215,000 EUR": check currencies with a text rule). A figure written at low precision
matches more ("3M" is grounded by anything from 2.5M to 3.5M). An ungrounded figure is not
necessarily wrong (a correct sum is ungrounded too): it is one nobody can trace.