@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/tool-directives.d.ts

@@ -0,0 +1,38 @@
+import type { AdvisoryLevel } from './types.js';
+/**
+ * What of a tool's text reads as an instruction to the agent: an order to set its instructions
+ * aside, the name of a tool it can call, an order, or a claim of authority. The last three count
+ * only beside a destination.
+ */
+declare const DIRECTIVE_SIGNALS: readonly ["override", "tool_name", "order", "authority"];
+/** One of {@linkcode DIRECTIVE_SIGNALS}. */
+type DirectiveSignal = (typeof DIRECTIVE_SIGNALS)[number];
+/** A stretch of a tool's text that instructs the agent, and what about it does. */
+interface Directive {
+    signal: DirectiveSignal;
+    start: number;
+    end: number;
+}
+/** One range for each run of overlapping `ranges`, in order. */
+declare function mergedRanges(ranges: readonly [number, number][]): [number, number][];
+/**
+ * Real indirect injection rarely names what it attacks, so this looks for content that behaves
+ * like an instruction: each order, claim of authority, tool name, and destination, where it sits
+ * in `text`. A page documenting an email API legitimately says "call send_email", so the
+ * detector that reads with this (`tool_instructions`) starts at `flag`.
+ *
+ * `callableTools` is the set the model can invoke this turn. A result naming one is the
+ * highest-precision signal: ordinary data has no reason to, and no generic filter can check it
+ * without the turn's registry.
+ *
+ * The text is read normalized. Where that changes it, each signal found is placed on the
+ * stretch of `text` it was read from (`normalizedView`).
+ */
+declare function directives(text: string, callableTools?: readonly string[]): Directive[];
+/**
+ * How strongly a tool's text reads as instructions, by the `signals` found in it: `high` for an
+ * order to drop instructions, a callable tool's name, or two signals together.
+ */
+declare function advisoryLevel(signals: readonly (string | undefined)[]): AdvisoryLevel;
+export type { Directive, DirectiveSignal };
+export { advisoryLevel, DIRECTIVE_SIGNALS, directives, mergedRanges };

package/esm/src/guardrails/tool-directives.js

@@ -0,0 +1,195 @@
+import { typoFolded } from './injection.js';
+import { overrideFrame } from './injection-patterns.js';
+import { normalizedView, normalizeForDetection } from './normalize.js';
+/**
+ * Imperatives aimed at an agent rather than a reader.
+ *
+ * Bounded quantifiers throughout: tool results can be large, and an unbounded
+ * scanner on attacker-controlled bytes is a denial-of-service surface.
+ */
+const IMPERATIVES = [
+    /\b(?:next|final|remaining)\s+steps?\s*[:—-]/gi,
+    /\byou\s+(?:must|should|need\s+to|are\s+required\s+to)\s+(?:now\s+)?\w{2,20}/gi,
+    /\bto\s+(?:complete|finish|fulfil|fulfill)\s+(?:this|the)\s+\w{2,20}/gi,
+    /\b(?:call|invoke|run|execute)\s+(?:the\s+)?[\w.-]{2,40}\s+(?:tool|function)\b/gi,
+    /\b(?:send|forward|email|transfer|upload|post)\s+(?:the\s+|all\s+|your\s+)?[\w\s]{2,40}\s+to\s+\S{3,80}/gi,
+    /\b(?:delete|remove|drop|purge)\s+(?:the\s+|all\s+)?[\w\s]{2,40}\b/gi,
+];
+/**
+ * A concrete external destination — the thing exfiltration needs and ordinary
+ * process prose almost never carries.
+ *
+ * This is the discriminator. Directive language on its own is everywhere in
+ * legitimate tool output: documentation says "you must be an admin", support
+ * articles say "to remove a user", status reports say "the user has approved".
+ * Measured on a benign sample, directive signals alone produced false positives
+ * on most of it. Pairing a signal with a destination removed all of them.
+ *
+ * The pairing is close. A web page always carries an address somewhere, and a
+ * shop's page says "Remove This Item" and "if you need to exchange it, send us
+ * an email at …": of 20 real search results, a destination anywhere in the
+ * result flagged 3. An order or a claim counts when the destination is in what
+ * it orders, up to the next comma; a tool's name when one is in its sentence.
+ */
+const EXFIL_TARGET = /\b[\w.+-]{1,64}@[\w-]{1,63}(?:\.[\w-]{1,63}){1,4}\b|\bhttps?:\/\/\S{4,120}/i;
+const EXFIL_TARGETS = new RegExp(EXFIL_TARGET.source, 'gi');
+/** How far from a signal its sentence is read, where the text has no sentence ends. */
+const SENTENCE_REACH = 240;
+/** Whether a sentence of `text` ends at `at`: a line break, or `.`, `!`, or `?` before a space. */
+function endsSentence(text, at) {
+    const ch = text[at];
+    if (ch === '\n')
+        return true;
+    return (ch === '.' || ch === '!' || ch === '?') && /\s/.test(text[at + 1] ?? ' ');
+}
+/** Whether a clause of `text` ends at `at`: where a sentence does, or at `,` or `;` before a space. */
+function endsClause(text, at) {
+    const ch = text[at];
+    return endsSentence(text, at) || ((ch === ',' || ch === ';') && /\s/.test(text[at + 1] ?? ' '));
+}
+/** Where the stretch of `text` from `end` stops: at the first place `ends` holds, at most `SENTENCE_REACH` on. */
+function reachFrom(text, end, ends) {
+    let to = end;
+    const ceiling = Math.min(text.length, end + SENTENCE_REACH);
+    while (to < ceiling && !ends(text, to))
+        to += 1;
+    return to;
+}
+/** Where the sentence of `text` holding `start` begins, at most `SENTENCE_REACH` back. */
+function sentenceStart(text, start) {
+    let from = start;
+    const floor = Math.max(0, start - SENTENCE_REACH);
+    while (from > floor && !endsSentence(text, from - 1))
+        from -= 1;
+    return from;
+}
+/** Claims of permission or provenance the content cannot actually hold. */
+const AUTHORITY = [
+    /\b(?:the\s+)?user\s+has\s+(?:already\s+)?(?:approved|authorised|authorized|confirmed|requested)\b/gi,
+    /\b(?:system|admin|operator)\s+(?:note|notice|message|override|instruction)s?\s*[:—-]/gi,
+    /\bon\s+behalf\s+of\s+the\s+(?:user|operator|admin)\b/gi,
+    /\bthis\s+(?:is|was)\s+(?:pre-?)?(?:approved|authorised|authorized)\b/gi,
+];
+/**
+ * An order to set instructions aside. Data has no reason to address the
+ * agent's instructions, so here the order counts when negated and with more
+ * words between its verb and its object than `injection-patterns.ts` allows.
+ */
+const OVERRIDE = [new RegExp(overrideFrame(5), 'gi')];
+/** Every destination in `text` between `from` and `to`. */
+function targetsIn(text, from, to) {
+    return [...text.slice(from, to).matchAll(EXFIL_TARGETS)].map((match) => [
+        from + match.index,
+        from + match.index + match[0].length,
+    ]);
+}
+/** Each match of `patterns` in `text` that names a destination before its clause ends, and the destinations it names. */
+function directsOut(patterns, text) {
+    return patterns.flatMap((pattern) => [...text.matchAll(pattern)].flatMap((match) => {
+        const end = match.index + match[0].length;
+        const targets = targetsIn(text, match.index, reachFrom(text, end, endsClause));
+        return targets.length > 0 ? [[match.index, end], ...targets] : [];
+    }));
+}
+/** Each order in `text` to set instructions aside, read with its misspellings put right. */
+function overrides(text) {
+    const folded = typoFolded(text);
+    return OVERRIDE.flatMap((pattern) => [...folded.text.matchAll(pattern)].map((match) => [folded.at(match.index), folded.at(match.index + match[0].length - 1) + 1]));
+}
+function isToolNameBoundary(ch) {
+    return ch === undefined || !/[a-z0-9_-]/i.test(ch);
+}
+/**
+ * Where `text` names `tool`, at word boundaries, in a sentence with a
+ * destination: the name, and the destinations of its sentence. A name inside a
+ * destination (`https://shop.example/search`) is part of the address. Registry
+ * input is not compiled as a pattern.
+ */
+function directsToTool(text, tool) {
+    if (tool.length < 3) {
+        return [];
+    }
+    const haystack = text.toLowerCase();
+    const needle = tool.toLowerCase();
+    const found = [];
+    let at = haystack.indexOf(needle);
+    while (at >= 0) {
+        const end = at + needle.length;
+        if (isToolNameBoundary(haystack[at - 1]) && isToolNameBoundary(haystack[end])) {
+            const targets = targetsIn(text, sentenceStart(text, at), reachFrom(text, end, endsSentence));
+            const isInTarget = targets.some(([start, stop]) => start <= at && end <= stop);
+            if (targets.length > 0 && !isInTarget) {
+                found.push([at, end], ...targets);
+            }
+        }
+        at = haystack.indexOf(needle, end);
+    }
+    return found;
+}
+/**
+ * What of a tool's text reads as an instruction to the agent: an order to set its instructions
+ * aside, the name of a tool it can call, an order, or a claim of authority. The last three count
+ * only beside a destination.
+ */
+const DIRECTIVE_SIGNALS = ['override', 'tool_name', 'order', 'authority'];
+/** One range for each run of overlapping `ranges`, in order. */
+function mergedRanges(ranges) {
+    const runs = [];
+    for (const [start, end] of [...ranges].sort((a, b) => a[0] - b[0])) {
+        const last = runs.at(-1);
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            runs.push([start, end]);
+    }
+    return runs;
+}
+/** One directive for each run of overlapping `ranges`. */
+function directivesOf(signal, ranges) {
+    return mergedRanges(ranges).map(([start, end]) => ({ signal, start, end }));
+}
+/**
+ * Real indirect injection rarely names what it attacks, so this looks for content that behaves
+ * like an instruction: each order, claim of authority, tool name, and destination, where it sits
+ * in `text`. A page documenting an email API legitimately says "call send_email", so the
+ * detector that reads with this (`tool_instructions`) starts at `flag`.
+ *
+ * `callableTools` is the set the model can invoke this turn. A result naming one is the
+ * highest-precision signal: ordinary data has no reason to, and no generic filter can check it
+ * without the turn's registry.
+ *
+ * The text is read normalized. Where that changes it, each signal found is placed on the
+ * stretch of `text` it was read from (`normalizedView`).
+ */
+function directives(text, callableTools = []) {
+    if (!text) {
+        return [];
+    }
+    const normalized = normalizeForDetection(text);
+    const found = directivesOf('override', overrides(normalized));
+    // why: No destination, no exfiltration. Action-shaped attacks that carry no target
+    // are left to the taint gate, which does not depend on reading the content.
+    if (EXFIL_TARGET.test(normalized)) {
+        found.push(...directivesOf('tool_name', callableTools.flatMap((tool) => directsToTool(normalized, tool))), ...directivesOf('order', directsOut(IMPERATIVES, normalized)), ...directivesOf('authority', directsOut(AUTHORITY, normalized)));
+    }
+    if (normalized === text || found.length === 0)
+        return found;
+    const view = normalizedView(text);
+    return found.map(({ signal, start, end }) => ({
+        signal,
+        start: view.start[start] ?? text.length,
+        end: view.end[end - 1] ?? text.length,
+    }));
+}
+/**
+ * How strongly a tool's text reads as instructions, by the `signals` found in it: `high` for an
+ * order to drop instructions, a callable tool's name, or two signals together.
+ */
+function advisoryLevel(signals) {
+    if (signals.length === 0) {
+        return 'none';
+    }
+    const kinds = new Set(signals);
+    return kinds.has('tool_name') || kinds.has('override') || kinds.size > 1 ? 'high' : 'elevated';
+}
+export { advisoryLevel, DIRECTIVE_SIGNALS, directives, mergedRanges };

package/esm/src/guardrails/tool-leak.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What `tool_leak` reads for: the names of the profile's own tools, each as a word of its own,
+ * and the names of their parameters in double quotes, as tool-call JSON writes its keys. A
+ * parameter is often a plain word (`city`, `query`), so outside quotes it is left alone.
+ *
+ * @module
+ */
+import type { RedactSpan } from '../observability/spans.js';
+/** The names of a profile's own tools, and of their parameters. */
+interface OwnTools {
+    names: readonly string[];
+    params: readonly string[];
+}
+/** A literal of a name to find, and the pattern that reads a match of it. */
+interface NamePattern {
+    literal: string;
+    regex: RegExp;
+}
+/** The pattern of each name of `own`. A tool's name starts and ends where a word does. */
+declare function namePatterns(own: OwnTools): NamePattern[];
+/** Every match of a name of `own` in `text`. */
+declare function toolLeakSpans(text: string, own: OwnTools | undefined): RedactSpan[];
+/** `own` without the names in `innocent`, or `undefined` when none is left. */
+declare function ownToolsWithout(own: OwnTools | undefined, innocent?: readonly string[]): OwnTools | undefined;
+export type { NamePattern, OwnTools };
+export { namePatterns, ownToolsWithout, toolLeakSpans };

package/esm/src/guardrails/tool-leak.js

@@ -0,0 +1,45 @@
+/**
+ * What `tool_leak` reads for: the names of the profile's own tools, each as a word of its own,
+ * and the names of their parameters in double quotes, as tool-call JSON writes its keys. A
+ * parameter is often a plain word (`city`, `query`), so outside quotes it is left alone.
+ *
+ * @module
+ */
+const WORD = '[A-Za-z0-9_]';
+function escaped(text) {
+    return text.replace(/[\\^$.*+?()[\]{}|/-]/g, '\\$&');
+}
+/** The pattern of each name of `own`. A tool's name starts and ends where a word does. */
+function namePatterns(own) {
+    const after = `(?!${WORD})`;
+    const names = [...new Set(own.names)].filter(Boolean).map((name) => ({
+        literal: name,
+        regex: new RegExp(`(?<!${WORD})${escaped(name)}${after}`, 'g'),
+    }));
+    const keys = [...new Set(own.params)]
+        .filter(Boolean)
+        .flatMap((param) => [`"${param}"`, `\\"${param}\\"`])
+        .map((literal) => ({ literal, regex: new RegExp(escaped(literal), 'g') }));
+    return [...names, ...keys];
+}
+/** Every match of a name of `own` in `text`. */
+function toolLeakSpans(text, own) {
+    if (!own)
+        return [];
+    return namePatterns(own).flatMap(({ literal, regex }) => text.includes(literal)
+        ? [...text.matchAll(regex)].map(({ index, 0: match }) => ({
+            start: index,
+            end: index + match.length,
+            kind: 'tool',
+        }))
+        : []);
+}
+/** `own` without the names in `innocent`, or `undefined` when none is left. */
+function ownToolsWithout(own, innocent = []) {
+    if (!own)
+        return undefined;
+    const names = own.names.filter((name) => !innocent.includes(name));
+    const params = own.params.filter((name) => !innocent.includes(name));
+    return names.length + params.length > 0 ? { names, params } : undefined;
+}
+export { namePatterns, ownToolsWithout, toolLeakSpans };

package/esm/src/guardrails/tool-result.d.ts

@@ -0,0 +1,92 @@
+import type { ToolBoundary } from './boundaries.js';
+import { type DetectScope } from './detect-at.js';
+import { type LabelOverrides } from './labels.js';
+import type { AdvisoryLevel, GuardrailEvent, GuardrailHit, Provenance, ResolvedGuardrailPolicy, ToolOrigin, TurnTaint, Verdict } from './types.js';
+/** The closing tag of the fence a tool result is wrapped in. */
+declare const TOOL_CLOSE = "</tool_data>";
+/** True when the tool's bytes come from outside the host. */
+declare function isRemoteOrigin(origin: ToolOrigin): boolean;
+/**
+ * The origin is on the tag rather than in prose so a result cannot claim a
+ * friendlier provenance than it has by writing one into its own body.
+ */
+declare function wrapToolData(text: string, provenance: Provenance, advisory?: AdvisoryLevel, labels?: LabelOverrides): string;
+/** A tool result after the guard: the text the model sees, any event, and the suspicious hits. */
+export interface GuardedToolText {
+    /** Absent when a match blocks: the model does not read the text. */
+    text?: string;
+    /** Emitted when the guard did anything worth recording. */
+    event?: GuardrailEvent;
+    /**
+     * What `tool_instructions` found. Legitimate tool output is frequently
+     * instruction-shaped, so the detector starts at `flag`; whatever its action,
+     * these raise the turn's taint.
+     */
+    suspicious?: GuardrailHit[];
+}
+/**
+ * `finding` is the tool's summary and `data` its structured payload; both reach
+ * the model, so both are guarded together rather than only the prose half.
+ */
+declare function composeToolText(finding: string, data: unknown): string;
+/**
+ * Local host tools are still detected — a host tool reading a database returns
+ * data the host did not write — but only remote origins are fenced, because
+ * fencing a local tool's output would change prompts hosts have already tuned.
+ * `boundary` is absent for text that crosses none: a provider builtin's, or a
+ * failure already read at its own boundary.
+ */
+declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, callableTools?: readonly string[], labels?: LabelOverrides): GuardedToolText;
+/**
+ * A remote server authors its own error strings, so an unguarded failure message
+ * is the cleanest injection path across this boundary: it reaches the model
+ * verbatim and is framed by the kernel as a system report.
+ */
+declare function guardToolFailureText(message: string, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined): GuardedToolText;
+/** What a call shows the person of one value, after it was read at `tool_shown_<kind>`. */
+export interface ShownToolValue {
+    /** The value to show: every match set to `redact` replaced. Absent when a match blocks it. */
+    value?: unknown;
+    event?: GuardrailEvent;
+}
+/**
+ * A call's output, error, artifacts, and trace reach the person on the turn's events, apart from
+ * what the model read back: the host's server forwards them to the browser as they are. Each is
+ * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
+ * untouched: what the model read is settled at `tool_output_<kind>`.
+ */
+declare function guardShownValue(value: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined): ShownToolValue;
+/** A tool call's arguments after they were read at their boundary. */
+export interface InspectedToolArguments {
+    /** The arguments to call the tool with. Absent when a match blocks: the tool is not called. */
+    args?: unknown;
+    event?: GuardrailEvent;
+}
+/**
+ * Arguments are model-authored, so the risk is not instruction smuggling but
+ * exfiltration: a credential lifted from context and posted outward as a
+ * parameter. The whole call is read as it will be sent; `redact` then replaces
+ * the match inside each string it sits in, so the tool is called with the
+ * placeholder. `scope` is what the detectors of what is the profile's own
+ * read of the turn: the canary, and its system instruction.
+ */
+declare function inspectToolArguments(args: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, scope?: DetectScope): InspectedToolArguments;
+/** The guardrail event for a tool call verdict, or `undefined` when it was allowed. */
+declare function toolCallEvent(verdict: Verdict, provenance: Provenance): GuardrailEvent | undefined;
+/**
+ * Only remote origins taint: a local host tool returns bytes the host's own code
+ * produced, and treating those as attacker-influenceable would make the gate
+ * useless in practice.
+ */
+declare function recordTaint(taint: TurnTaint | undefined, provenance: Provenance, suspicious?: GuardrailHit[]): TurnTaint;
+/** True when the turn has read content from outside the host. */
+declare function isTainted(taint: TurnTaint | undefined): boolean;
+/** True when something the turn read looked like instructions. */
+declare function isSuspicious(taint: TurnTaint | undefined): boolean;
+/**
+ * A `flag` says the call is happening on a tainted turn and is worth recording; a
+ * `block` says the profile asked for it to be refused. Reporting happens whether
+ * or not enforcement is configured, so the risk is visible before a host opts in.
+ */
+declare function checkTaintGate(taint: TurnTaint | undefined, access: string, policy: ResolvedGuardrailPolicy, labels?: LabelOverrides): Verdict;
+export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };

package/esm/src/guardrails/tool-result.js

@@ -0,0 +1,272 @@
+import { mapStrings } from '../kernel/engine/tree.js';
+import { detectAt, detectEvent, detectReads, } from './detect-at.js';
+import { readValue } from './detect-reply.js';
+import { labelText } from './labels.js';
+import { DETECT_RULES, EGRESS_RULES, TOOL_RULES } from './rules.js';
+import { textForScan } from './serialize.js';
+import { advisoryLevel } from './tool-directives.js';
+/** The closing tag of the fence a tool result is wrapped in. */
+const TOOL_CLOSE = '</tool_data>';
+const TOOL_OPEN = '<tool_data';
+/** Origins whose bytes the host does not author and cannot vouch for. */
+const REMOTE_ORIGINS = new Set(['http', 'mcp', 'delegated']);
+/** True when the tool's bytes come from outside the host. */
+function isRemoteOrigin(origin) {
+    return REMOTE_ORIGINS.has(origin);
+}
+/**
+ * Strip fence markers a tool result tried to forge before wrapping it.
+ * Linear scan — avoids polynomial regex on forged `<tool_data…>` runs.
+ */
+function stripToolFences(text) {
+    const lower = text.toLowerCase();
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const openAt = lower.indexOf(TOOL_OPEN, i);
+        const closeAt = lower.indexOf(TOOL_CLOSE, i);
+        let next = -1;
+        let kind = null;
+        if (openAt >= 0 && (closeAt < 0 || openAt <= closeAt)) {
+            next = openAt;
+            kind = 'open';
+        }
+        else if (closeAt >= 0) {
+            next = closeAt;
+            kind = 'close';
+        }
+        if (next < 0 || kind === null) {
+            out += text.slice(i);
+            break;
+        }
+        out += text.slice(i, next);
+        if (kind === 'close') {
+            i = next + TOOL_CLOSE.length;
+            continue;
+        }
+        const gt = text.indexOf('>', next + TOOL_OPEN.length);
+        if (gt < 0) {
+            out += text.slice(next);
+            break;
+        }
+        i = gt + 1;
+    }
+    return out;
+}
+/**
+ * The origin is on the tag rather than in prose so a result cannot claim a
+ * friendlier provenance than it has by writing one into its own body.
+ */
+function wrapToolData(text, provenance, advisory = 'none', labels) {
+    const guidance = labelText('advisory.guidance', {}, labels).trim();
+    const attrs = `tool="${provenance.tool}" origin="${provenance.origin}"` +
+        (advisory === 'none' ? '' : ` advisory="${advisory}"`);
+    const notice = advisory === 'none'
+        ? ''
+        : `${advisoryNotice(advisory, labels)}${guidance ? ` ${guidance}` : ''}\n`;
+    return `<${'tool_data'} ${attrs}>\n${notice}${stripToolFences(text)}\n${TOOL_CLOSE}`;
+}
+/**
+ * Deliberately an observation, not an instruction: what the agent should do about
+ * it is product behaviour, supplied by the host as labels `advisory.guidance`. Emitted
+ * only when signals fired, so it stays rare enough to carry weight — a warning on
+ * every fetch is one the model learns to skip.
+ */
+function advisoryNotice(advisory, labels) {
+    const key = advisory === 'high' ? 'advisory.notice_high' : 'advisory.notice_elevated';
+    return labelText(key, {}, labels);
+}
+/**
+ * `finding` is the tool's summary and `data` its structured payload; both reach
+ * the model, so both are guarded together rather than only the prose half.
+ */
+function composeToolText(finding, data) {
+    if (data === undefined) {
+        return finding;
+    }
+    const rendered = textForScan(data);
+    if (rendered.unscannable) {
+        return finding;
+    }
+    return `${finding}\n${rendered.text}`;
+}
+const NOTHING_FOUND = { action: 'allow', hits: [] };
+/** `text` read at `boundary`, or passed as it is when the text crosses none. */
+function readAt(text, boundary, detect, scope) {
+    return boundary ? detectAt(text, boundary, detect, scope) : { ...NOTHING_FOUND, text };
+}
+/**
+ * Local host tools are still detected — a host tool reading a database returns
+ * data the host did not write — but only remote origins are fenced, because
+ * fencing a local tool's output would change prompts hosts have already tuned.
+ * `boundary` is absent for text that crosses none: a provider builtin's, or a
+ * failure already read at its own boundary.
+ */
+function guardToolResult(finding, data, provenance, policy, boundary, callableTools = [], labels) {
+    const composed = composeToolText(finding, data);
+    const detected = readAt(composed, boundary, policy.detect, { callable: callableTools });
+    const suspicious = detected.hits.filter(({ rule }) => rule === DETECT_RULES.tool_instructions);
+    const remote = isRemoteOrigin(provenance.origin);
+    const event = detected.action === 'allow'
+        ? undefined
+        : {
+            stage: 'tool_result',
+            ...(boundary ? { boundary } : {}),
+            trust: 'untrusted',
+            action: detected.action,
+            hits: detected.hits,
+            provenance,
+        };
+    const found = {
+        ...(suspicious.length > 0 ? { suspicious } : {}),
+        ...(event ? { event } : {}),
+    };
+    if (detected.text === undefined)
+        return found;
+    const fenced = remote
+        ? wrapToolData(detected.text, provenance, advisoryLevel(suspicious.map(({ signal }) => signal)), labels)
+        : detected.text;
+    return { text: fenced, ...found };
+}
+/**
+ * A remote server authors its own error strings, so an unguarded failure message
+ * is the cleanest injection path across this boundary: it reaches the model
+ * verbatim and is framed by the kernel as a system report.
+ */
+function guardToolFailureText(message, provenance, policy, boundary) {
+    const detected = readAt(stripToolFences(message), boundary, policy.detect);
+    const event = boundary ? detectEvent(boundary, detected, provenance) : undefined;
+    return {
+        ...(detected.text === undefined ? {} : { text: detected.text }),
+        ...(event ? { event } : {}),
+    };
+}
+/**
+ * A call's output, error, artifacts, and trace reach the person on the turn's events, apart from
+ * what the model read back: the host's server forwards them to the browser as they are. Each is
+ * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
+ * untouched: what the model read is settled at `tool_output_<kind>`.
+ */
+function guardShownValue(value, provenance, policy, boundary) {
+    if (!boundary || value === undefined)
+        return { value };
+    const found = readValue(value, boundary, policy.detect);
+    const event = detectEvent(boundary, found, provenance);
+    return {
+        ...(found.action === 'block' ? {} : { value: found.value }),
+        ...(event ? { event } : {}),
+    };
+}
+/**
+ * Arguments are model-authored, so the risk is not instruction smuggling but
+ * exfiltration: a credential lifted from context and posted outward as a
+ * parameter. The whole call is read as it will be sent; `redact` then replaces
+ * the match inside each string it sits in, so the tool is called with the
+ * placeholder. `scope` is what the detectors of what is the profile's own
+ * read of the turn: the canary, and its system instruction.
+ */
+function inspectToolArguments(args, provenance, policy, boundary, scope = {}) {
+    if (!(boundary && detectReads([boundary], policy.detect))) {
+        return { args };
+    }
+    const stopped = (hits) => {
+        const event = detectEvent(boundary, { action: 'block', hits }, provenance);
+        return event ? { event } : {};
+    };
+    const rendered = textForScan(args);
+    if (rendered.unscannable) {
+        // why: Cannot inspect it, so cannot vouch for it. Fail closed.
+        return stopped([{ rule: EGRESS_RULES.unscannable, severity: 'high' }]);
+    }
+    const detected = detectAt(rendered.text, boundary, policy.detect, scope);
+    if (detected.action === 'block')
+        return stopped(detected.hits);
+    const event = detectEvent(boundary, detected, provenance);
+    if (detected.action !== 'redact')
+        return { args, ...(event ? { event } : {}) };
+    const safe = mapStrings(args, (text) => detectAt(text, boundary, policy.detect, scope).text ?? '');
+    const left = detectAt(textForScan(safe).text, boundary, policy.detect, scope).action;
+    // why: A match in a key, or one that runs across values, has no string to replace: the tool is not called.
+    if (left === 'redact' || left === 'block')
+        return stopped(detected.hits);
+    return { args: safe, ...(event ? { event } : {}) };
+}
+/** The guardrail event for a tool call verdict, or `undefined` when it was allowed. */
+function toolCallEvent(verdict, provenance) {
+    if (verdict.action === 'allow') {
+        return undefined;
+    }
+    return {
+        stage: 'tool_call',
+        trust: 'untrusted',
+        action: verdict.action,
+        hits: verdict.hits,
+        provenance,
+    };
+}
+/**
+ * Only remote origins taint: a local host tool returns bytes the host's own code
+ * produced, and treating those as attacker-influenceable would make the gate
+ * useless in practice.
+ */
+function recordTaint(taint, provenance, suspicious = []) {
+    const sources = taint?.sources ?? [];
+    const prior = taint?.suspicious ?? [];
+    if (!isRemoteOrigin(provenance.origin)) {
+        return { sources, suspicious: prior };
+    }
+    return { sources: [...sources, provenance], suspicious: [...prior, ...suspicious] };
+}
+/** True when the turn has read content from outside the host. */
+function isTainted(taint) {
+    return (taint?.sources.length ?? 0) > 0;
+}
+/** True when something the turn read looked like instructions. */
+function isSuspicious(taint) {
+    return (taint?.suspicious.length ?? 0) > 0;
+}
+/** Capability rank, so a single threshold can express "this and anything worse". */
+const CAPABILITY_RANK = {
+    'read-only': 0,
+    'read-write': 1,
+    destructive: 2,
+};
+const GATE_RANK = {
+    off: Number.POSITIVE_INFINITY,
+    destructive: 2,
+    write: 1,
+};
+/**
+ * A `flag` says the call is happening on a tainted turn and is worth recording; a
+ * `block` says the profile asked for it to be refused. Reporting happens whether
+ * or not enforcement is configured, so the risk is visible before a host opts in.
+ */
+function checkTaintGate(taint, access, policy, labels) {
+    if (!isTainted(taint)) {
+        return { action: 'allow' };
+    }
+    const rank = CAPABILITY_RANK[access] ?? 0;
+    if (rank === 0) {
+        return { action: 'allow' };
+    }
+    const suspicious = isSuspicious(taint);
+    const hits = [
+        {
+            rule: suspicious ? TOOL_RULES.steeredTurn : TOOL_RULES.taintedTurn,
+            severity: 'high',
+        },
+    ];
+    // why: Gated on origin alone. Whether the content looked directive changes the rule
+    // reported, never whether the call is refused.
+    if (rank < GATE_RANK[policy.taint?.afterRemoteRead ?? 'off']) {
+        return { action: 'flag', hits };
+    }
+    const read = taint?.sources.map((s) => s.tool).join(', ') ?? '';
+    const reason = labelText(suspicious ? 'taint.reason_steered' : 'taint.reason_tainted', {}, labels);
+    return {
+        action: 'block',
+        hits,
+        rejection: labelText('taint.blocked', { access, sources: read, reason }, labels),
+    };
+}
+export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };