| --- |
| license: apache-2.0 |
| library_name: interlock |
| pipeline_tag: text-classification |
| tags: |
| - agent-safety |
| - tool-use |
| - guardrails |
| - ai-safety |
| language: |
| - en |
| --- |
| |
| # Interlock |
|
|
| Interlock judges a *proposed agent tool call* against *what the user actually |
| asked for*. Content shields read the request and ask whether it is harmful. |
| Interlock reads the request/action pair and asks a different question: is this |
| call **more** than what was asked? |
|
|
| It is deliberately blind to where a deviation came from. A widened `path` |
| argument looks the same whether it originated in a prompt injection, a |
| jailbreak, or an ordinary model mistake, and the defence is the same either |
| way. |
|
|
| ## Output |
|
|
| Three-valued, never binary: |
|
|
| | decision | meaning | |
| |-----------|---------| |
| | `allow` | the call stays within what the request asked for | |
| | `confirm` | the call should be put to the user before it runs | |
| | `block` | the call goes materially beyond the request | |
|
|
| The three decisions are `allow`, `confirm`, `block`. Alongside the decision the model |
| predicts a deviation type, one of `none`, `scope_expansion`, `unrequested_action`, `irreversible_unconfirmed`, `target_mismatch`, `out_of_scope`, `privilege_escalation`. |
|
|
| `confirm` is a first-class outcome. Collapsing it into `block` would trade a |
| question for a refusal on exactly the cases where the request is ambiguous. |
|
|
| ## Two tiers |
|
|
| **Tier 1 -- linear (1080 parameters).** A two-headed multinomial |
| logistic regression over 107 structured request/action alignment |
| features. Pure NumPy at inference: no tokeniser, no torch. This is the tier |
| that runs on every agent turn. Shipped as `interlock_linear.npz`, with the |
| fitted operating point in `policy.json`. |
|
|
| **Tier 2 -- encoder (optional).** ModernBERT-base with a decision head and a |
| deviation head, reading a role-annotated text rendering of the same pair. More |
| accurate where the wording rather than the structure carries the signal, and |
| correspondingly slower. Shipped as `interlock.onnx` when it has been trained |
| and exported; the export is verified against the torch model to within 1e-3 on |
| the raw logits before it is published. |
|
|
| A third file, `interlock-linear.gguf`, is a weight container for tier 1 with |
| its feature names and operating point attached. It is not a runtime: llama.cpp |
| has no architecture for this classification head and cannot serve it. The |
| verified runtimes are NumPy for tier 1 and ONNX Runtime for tier 2. |
|
|
| ## Evaluation, and the split that makes it mean something |
|
|
| The train/test split is taken at **tool family** granularity, not at row |
| granularity. Training and validation draw on `fs, shell, mail, calendar, issues`. |
| The held-out split draws on `browser, crm, storage, db` -- every tool schema |
| in it is one the model has never seen. The split is verified against the files |
| on disk, not just asserted in code. |
|
|
| Measured for tier 1: |
|
|
| | split | over-blocking | deviation detection | |
| |-------|---------------|---------------------| |
| | validation (seen families, unseen world) | 2.9% | 88.0% | |
| | held-out families (unseen tool schemas) | 1.8% | 79.3% | |
|
|
| Over-blocking is the fraction of *legitimate* calls that were interrupted, and |
| it is the headline number. A shield that interrupts real work gets switched |
| off, and a switched-off shield detects nothing. Detection is reported second |
| for that reason, not first. |
|
|
| Latency, timing a full check per call including encoding: 0.247 ms mean, 0.663 ms p95 over 400 single-threaded calls on arm64. |
| Timing the model's arithmetic alone would understate what a deployment pays. |
|
|
| ## Intended use |
|
|
| Interlock sits between an agent's proposed tool call and its execution. Given |
| the user's request, the proposed call and the tool's schema, it returns a |
| verdict that a harness can act on: proceed, ask the user, or refuse. It is |
| designed for agent runtimes where tool schemas are declared and where a |
| confirmation prompt is a cheaper failure than an unwanted side effect. |
|
|
| ```python |
| from interlock.model import load_shield |
| |
| shield = load_shield("artifacts") |
| # The request names one file. The call names the directory that contains it. |
| verdict = shield.check( |
| "Archive the Q3 notes at /work/apollo/q3-notes.md", |
| {"tool": "fs.delete_path", "arguments": {"path": "/work/apollo", "recursive": True}}, |
| ) |
| print(verdict.decision, verdict.deviation) # block scope_expansion |
| for reason in verdict.reasons: |
| print(" -", reason) |
| ``` |
|
|
| Nothing about that call reads as dangerous on its own: it is an ordinary delete, |
| on an ordinary path, in the project the user named. It is wrong only relative to |
| the request, which is the only place the difference exists. |
|
|
| A tool the model has never seen still gets a verdict rather than an exception, |
| because an agent can propose anything: |
|
|
| ```python |
| verdict = shield.check( |
| "Rotate the API key for the billing service", |
| {"tool": "acme.rotate_key", "arguments": {"service": "billing"}}, |
| ) |
| print(verdict.decision, verdict.known_tool) # confirm False |
| ``` |
|
|
| It is not a content moderation model, not a prompt-injection detector, and not |
| a substitute for sandboxing or for asking the user. |
|
|
| ## Limitations |
|
|
| - **Synthetic data.** Every episode, tool schema and deviation in training is |
| generated. The tool families model common operation shapes rather than any |
| particular product's API, and no real service was contacted at any point. |
| Performance on production agent traffic is unmeasured here. |
| - **English only.** Requests and tool descriptions are English. Nothing has |
| been measured in any other language. |
| - **One layer among several.** Interlock reads the correspondence between a |
| request and a call. It does not read the content of a payload for harm, does |
| not sandbox anything, and cannot see effects that occur outside the tool |
| call it is shown. |
| - **It does not guarantee safety.** An `allow` verdict means this shield found |
| no boundary deviation, which is a weaker statement than "this call is safe". |
| Deploy it beside content shields, sandboxing and human confirmation, not |
| instead of them. |
| - **Unseen tools cost accuracy.** Detection falls from 88.0% to |
| 79.3% on held-out tool families. The over-blocking rate holds, so |
| the degradation shows up as missed deviations rather than as new |
| interruptions, but it is real. |
| - **The operating point is a choice.** Thresholds were fitted against an |
| explicit over-blocking budget on validation data. A deployment with a |
| different tolerance for interruption should refit them rather than inherit |
| these. |
|
|
| ## Files |
|
|
| | file | what it is | |
| |------|------------| |
| | `interlock_linear.npz` | tier-1 weights, the default serving path | |
| | `policy.json` | fitted decision thresholds | |
| | `train_report_linear.json` | measured metrics for tier 1 | |
| | `interlock.onnx` | tier-2 graph, when the encoder has been trained | |
| | `interlock-linear.gguf` | tier-1 weight container, not a runtime | |
| | `latency.json` | measured per-call latency and peak RSS | |
|
|
| Card generated 2026-08-30T01:30:45+00:00 for `NagaYu/interlock`. |
|
|
