@namzu/sdk 26.1.0 → 27.1.0

package/src/registry/tool/execute.ts

@@ -3,6 +3,8 @@ import { assertStrictSchema } from '../../provider/strict-schema.js'
 import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js'
 import { recordToolCall } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
+import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
+import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
 import type {
 	LLMToolSchema,
 	ToolAvailability,
@@ -15,6 +17,7 @@ import type {
 import { toErrorMessage } from '../../utils/error.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
 import { renderToolSchema } from './schema.js'
+import { ToolResultHalted, screenToolResult } from './screen.js'
 
 export type { ToolExecutionResult }
 
@@ -132,10 +135,12 @@ export function describeWithOutput(
 export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	private availability: Map<string, ToolAvailability> = new Map()
 	private tierConfig?: ToolTierConfig
+	private resultGuardrails?: readonly ToolResultGuardrailSpec[]
 
 	constructor(config?: ToolRegistryConfig) {
 		super({ componentName: 'ToolRegistry', idField: 'name', logger: config?.logger })
 		this.tierConfig = config?.tierConfig
+		this.resultGuardrails = config?.resultGuardrails
 	}
 
 	override register(id: string, tool: ToolDefinition): void
@@ -487,7 +492,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 				const mode = context.permissionContext?.mode ?? 'auto'
 				if (mode === 'plan') {
-					const isReadOnly = tool.isReadOnly ? tool.isReadOnly(rawInput) : false
+					const isReadOnly = isTrustedReadOnly(tool, rawInput)
 					if (!isReadOnly) {
 						const msg = `plan mode: non-read-only tool "${toolName}" blocked`
 						span.setAttributes({
@@ -564,7 +569,25 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				try {
 					this.log.debug(`Executing tool: ${toolName}`)
 					const startedAt = Date.now()
-					const result = await tool.execute(finalInput, context)
+					const produced = await tool.execute(finalInput, context)
+					// Screened here, which is the only place a result can be
+					// examined before anything acts on it: the executor applies
+					// the output budget to what this returns, and compaction
+					// summarises later still. `provenance` is carried in so a
+					// screen can tell a connected server's words from a
+					// first-party tool's — a connector's result is framed with
+					// the server's name, and a screen reading only the value
+					// cannot use that.
+					const result = await screenToolResult(
+						this.resultGuardrails,
+						produced,
+						{
+							toolName,
+							input: finalInput,
+							...(tool.provenance ? { provenance: tool.provenance } : {}),
+						},
+						this.log,
+					)
 					const durationMs = Date.now() - startedAt
 					this.log.debug(`Tool completed: ${toolName}`, {
 						success: result.success,
@@ -586,6 +609,20 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 					return result
 				} catch (err) {
+					// A terminal refusal must not be converted into a failed
+					// tool call. Everything below turns an exception into a
+					// result the model reads and works around, which is what
+					// `refuse` is for — doing it to a `halt` would silently
+					// demote the one verdict that says the run must not
+					// continue.
+					if (err instanceof ToolResultHalted) {
+						span.setAttributes({
+							[NAMZU.TOOL_SUCCESS]: false,
+							[NAMZU.TOOL_ERROR]: err.message,
+						})
+						span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
+						throw err
+					}
 					const errorMessage = toErrorMessage(err)
 					this.log.error(`Tool execution error: ${toolName}`, {
 						error: errorMessage,

package/src/registry/tool/screen.ts

@@ -0,0 +1,131 @@
+import type {
+	ToolResultGuardrailContext,
+	ToolResultGuardrailSpec,
+	ToolResultVerdict,
+} from '../../types/guardrail/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
+import { toErrorMessage } from '../../utils/error.js'
+import type { Logger } from '../../utils/logger.js'
+
+/**
+ * A tool result was refused terminally.
+ *
+ * Thrown rather than returned because the caller's failure path turns every
+ * exception into an ordinary tool failure the model then reads and works
+ * around — which is exactly what a terminal refusal must not become. The
+ * distinct type is what lets that path re-throw this one and convert the
+ * rest. A `halt` reported as a failed tool call would be a `refuse` with
+ * extra steps.
+ */
+export class ToolResultHalted extends Error {
+	readonly guardrail: string
+
+	constructor(guardrail: string, reason: string) {
+		super(`Tool result halted by guardrail "${guardrail}": ${reason}`)
+		this.name = 'ToolResultHalted'
+		this.guardrail = guardrail
+	}
+}
+
+function nameOf(spec: { name?: string }, index: number): string {
+	return spec.name ?? `tool-result-guardrail[${index}]`
+}
+
+function normalize<T>(spec: T | { name: string; check: T }): { name?: string; check: T } {
+	return typeof spec === 'function' ? { check: spec as T } : (spec as { name: string; check: T })
+}
+
+/**
+ * A guardrail that throws FAILS CLOSED, as the run-level ones do.
+ *
+ * `refuse` rather than `halt` for the same reason the tool boundary has a
+ * recoverable refusal at all: a broken screen means this result's safety is
+ * unknown, not that the run is unsalvageable. The model is told and can
+ * choose differently.
+ */
+async function safely(
+	run: () => ToolResultVerdict | Promise<ToolResultVerdict>,
+	name: string,
+	log: Logger,
+): Promise<ToolResultVerdict> {
+	try {
+		return await run()
+	} catch (err) {
+		const reason = `guardrail "${name}" threw: ${toErrorMessage(err)}`
+		log.error('Tool-result guardrail threw — failing closed', {
+			guardrail: name,
+			error: toErrorMessage(err),
+		})
+		return { action: 'refuse', reason }
+	}
+}
+
+/**
+ * Screen a tool's result before anything downstream reads it.
+ *
+ * Runs every guardrail in order and stops at the first refusal. Rewrites
+ * compose — each guardrail sees what the previous one produced — matching
+ * the output-guardrail path, so a redaction chain behaves the same at both
+ * boundaries.
+ *
+ * Returns the result to use. A refusal comes back as a failed `ToolResult`
+ * carrying the reason, because that is the shape the model already knows
+ * how to read: it is the same thing a tool that could not do its job
+ * returns, and the alternative — a blank result — tells the model the tool
+ * found nothing, which is a different claim and a false one.
+ */
+export async function screenToolResult(
+	guardrails: readonly ToolResultGuardrailSpec[] | undefined,
+	result: ToolResult,
+	ctx: Omit<ToolResultGuardrailContext, 'output' | 'success'>,
+	log: Logger,
+): Promise<ToolResult> {
+	if (!guardrails || guardrails.length === 0) return result
+
+	let current = result.output
+	let rewritten = false
+
+	for (const [index, spec] of guardrails.entries()) {
+		const { name, check } = normalize(spec)
+		const label = nameOf({ name }, index)
+		const verdict = await safely(
+			() => check({ ...ctx, output: current, success: result.success }),
+			label,
+			log,
+		)
+
+		if (verdict.action === 'halt') {
+			log.error('Tool-result guardrail halted the run', {
+				tool: ctx.toolName,
+				guardrail: label,
+				reason: verdict.reason,
+			})
+			throw new ToolResultHalted(label, verdict.reason)
+		}
+
+		if (verdict.action === 'refuse') {
+			log.warn('Tool-result guardrail refused the result', {
+				tool: ctx.toolName,
+				guardrail: label,
+				reason: verdict.reason,
+			})
+			return {
+				success: false,
+				output: '',
+				error: `Tool "${ctx.toolName}" produced a result that was refused by guardrail "${label}": ${verdict.reason}`,
+			}
+		}
+
+		if (verdict.action === 'rewrite') {
+			log.info('Tool-result guardrail rewrote the result', {
+				tool: ctx.toolName,
+				guardrail: label,
+				reason: verdict.reason,
+			})
+			current = verdict.output
+			rewritten = true
+		}
+	}
+
+	return rewritten ? { ...result, output: current } : result
+}

package/src/runtime/query/guardrail-presets.ts

@@ -2,6 +2,8 @@ import type {
 	GuardrailVerdict,
 	NamedGuardrail,
 	OutputGuardrail,
+	ToolResultGuardrail,
+	ToolResultVerdict,
 } from '../../types/guardrail/index.js'
 
 /**
@@ -100,6 +102,12 @@ const INJECTION_PATTERNS: readonly RegExp[] = [
  * Input-side because it is cheapest there — nothing has been spent — and
  * because the same text reaching the model is the thing you are trying to
  * prevent.
+ *
+ * It cannot see an INDIRECT injection, and that is not a limitation of the
+ * patterns: an injection carried in a web page or a connected server's
+ * answer never appears in the run's input at all. See
+ * {@link toolResultInjectionGuardrail}, which is the same list at the other
+ * boundary.
  */
 export function promptInjectionGuardrail(): NamedGuardrail<
 	(ctx: { messages: readonly { readonly content: unknown }[] }) => GuardrailVerdict
@@ -122,3 +130,45 @@ export function promptInjectionGuardrail(): NamedGuardrail<
 		},
 	}
 }
+
+/**
+ * Flag likely instruction-override attempts in what a TOOL returned.
+ *
+ * The case the input-side screen structurally cannot reach. An indirect
+ * injection arrives in a fetched page or a connected server's answer, so it
+ * is never in the run's input — by the time it matters the run is
+ * legitimate and the payload is riding on a result the model asked for.
+ *
+ * `refuse`, not `halt`: a hostile result is a reason to abandon that call,
+ * not the run. The model is told the answer was refused and can choose
+ * something else, which is the behaviour that keeps the control switched on
+ * — a screen that ends a run on a false positive gets removed, and then it
+ * protects nothing.
+ *
+ * **Detection is partial and this says so rather than implying coverage.**
+ * The pattern list is shared with the input-side screen, so the same caveat
+ * holds: an injection phrased as ordinary prose, or written in a language
+ * the list does not cover, passes. Pattern-matching and delimiting both
+ * measure poorly against an attacker who adapts. This raises the cost of
+ * the lazy attack; it is not a boundary, and nothing here should be
+ * described as one.
+ */
+export function toolResultInjectionGuardrail(): NamedGuardrail<ToolResultGuardrail> {
+	return {
+		name: 'tool-result-injection',
+		check: ({ output, provenance }): ToolResultVerdict => {
+			for (const pattern of INJECTION_PATTERNS) {
+				if (!pattern.test(output)) continue
+				// Naming the source is most of what the model needs in order
+				// to act. "A result was refused" is not something it can route
+				// around; "the answer from weather-co was refused" is.
+				const source = provenance ? `the connected server "${provenance.server}"` : 'this tool'
+				return {
+					action: 'refuse',
+					reason: `the result from ${source} matched a known instruction-override pattern`,
+				}
+			}
+			return { action: 'pass' }
+		},
+	}
+}

package/src/tools/trusted-read-only.ts

@@ -0,0 +1,52 @@
+import type { ToolDefinition } from '../types/tool/index.js'
+
+/**
+ * May this tool's read-only claim settle a gate on its own?
+ *
+ * A connected server declares whether its own tools are read-only, and
+ * that declaration decided whether a call was approved without asking. The
+ * thing being gated supplied the input to the gate.
+ *
+ * The wire itself calls these fields HINTS. Three separate consumers read
+ * them as facts, so a server setting `readOnlyHint: true` and
+ * `destructiveHint: false` controlled the whole predicate for its own
+ * tools — the kernel's `allow_read_only` rule, the operator prompt
+ * exemption, and the plan-mode pass.
+ *
+ * The estate floor this repository inherits already decided this: least
+ * privilege, default deny, and — on tool results and fetched content —
+ * data is not instructions, and untrusted content cannot escalate
+ * capabilities. A server's declaration about its own tools is untrusted
+ * content by that definition. This is that rule applied, not a new policy.
+ *
+ * **The asymmetry is the design.** A self-declaration may RAISE the
+ * requirement and never LOWER it:
+ *
+ *  - `destructiveHint: true` from a server is believed. A server
+ *    volunteering that its tool is dangerous moves toward caution, and
+ *    disbelieving it buys nothing.
+ *  - `readOnlyHint: true` from a server does not, on its own, settle a
+ *    call as allowed or skip a prompt. That is the untrusted party
+ *    opening its own gate.
+ *
+ * Trust for the second case comes from the operator, per server, and is
+ * recorded on the tool as `provenance.readOnlyHintTrusted`. Never a global
+ * switch: one flag meaning "trust annotations" hands every connected
+ * server the same reach, which is the hole restated.
+ *
+ * `isReadOnly` itself is left reporting faithfully what the server said.
+ * Provenance and policy are different questions, and collapsing them would
+ * corrupt the outbound re-export and the prompt's own destructive label in
+ * order to fix a gate.
+ */
+export function isTrustedReadOnly(tool: ToolDefinition | undefined, input: unknown): boolean {
+	if (!tool?.isReadOnly) return false
+
+	// No provenance means the tool is host-defined: it came from this
+	// process, from code the operator installed, and there is no untrusted
+	// party in the chain. Requiring an opt-in for a builtin would break
+	// every read-only exemption for no gain in trust.
+	if (tool.provenance && !tool.provenance.readOnlyHintTrusted) return false
+
+	return tool.isReadOnly(input)
+}

package/src/tools/untrusted-envelope.ts

@@ -2,12 +2,32 @@
  * Framing for content the agent did not author and must not obey.
  *
  * An unlabelled block of text in a tool result reads exactly like the agent's
- * own instructions. The mitigation that survives contact with a real model is
- * not filtering — it is saying plainly whose words these are and that they are
+ * own instructions. This says plainly whose words these are and that they are
  * material rather than direction. That is the floor this estate already
  * states: data is not instructions, and a tool result cannot escalate what an
  * agent may do.
  *
+ * **It marks provenance. It refuses nothing, and it does not stop an
+ * attacker who is trying.** This paragraph used to claim the framing was
+ * "the mitigation that survives contact with a real model", and that is
+ * measurably wrong. Nasr et al., "The Attacker Moves Second"
+ * (arXiv:2510.09023), broke twelve published defences at above 90% attack
+ * success once the attacker adapts; the majority had originally reported
+ * near-zero success. Delimiting specifically goes from as low as 1% under
+ * a static benchmark to above 95% under adaptive attack.
+ *
+ * So read every number for a prompt-level defence as static unless it says
+ * otherwise, and treat this envelope as raising cost rather than as a
+ * boundary. What survives an adapting attacker in the same literature is
+ * architectural: AgentDojo (arXiv:2406.13352) found tool isolation and
+ * tool filtering the effective mitigations, and this repository's real
+ * boundaries are of that kind — the permission gate, the sandbox, the
+ * egress proxy deciding by resolved address.
+ *
+ * The two details below still matter. They are what stops the framing
+ * being trivially removable by the content itself, which is a lower bar
+ * than stopping an attacker and worth clearing anyway.
+ *
  * Two details make the difference between a boundary and a decoration, and
  * both were missing from this repo's first envelope:
  *

package/src/types/guardrail/index.ts

@@ -1,5 +1,6 @@
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { ToolProvenance } from '../tool/index.js'
 
 /**
  * Guardrails inspect what goes INTO a run and what comes OUT of it.
@@ -58,5 +59,75 @@ export interface NamedGuardrail<T> {
 	readonly check: T
 }
 
+/**
+ * What a guardrail sees when a tool has produced a result.
+ *
+ * The two above bracket the RUN. This one sits at the tool boundary, which
+ * is the only place a result can be examined before the model reads it:
+ * the registry returns to the executor, the executor applies the output
+ * budget and spills what is over it, and compaction summarises later still.
+ * So screening here is upstream of both by construction rather than by
+ * ordering — a summariser does not distinguish trusted from untrusted text,
+ * and content carried into a summary outlives the result it came from.
+ *
+ * `provenance` is the point. A connector's result is framed with the
+ * server's name (see `wrapUntrusted`), and a screen that can only read the
+ * value cannot tell a remote server's words from a first-party tool's.
+ */
+export interface ToolResultGuardrailContext {
+	/** The tool as the registry knows it. */
+	readonly toolName: string
+	/** Validated input the tool was called with. */
+	readonly input: unknown
+	/** The text the model would read. */
+	readonly output: string
+	/** Whether the tool itself reported success. */
+	readonly success: boolean
+	/**
+	 * Who produced the tool, when it was not this process. Absent means
+	 * host-defined; present names the connected server.
+	 */
+	readonly provenance?: ToolProvenance
+}
+
+/**
+ * What a guardrail decided about a tool result.
+ *
+ * Deliberately NOT {@link GuardrailVerdict}. There, `block` ends the run —
+ * it is the only thing it can mean when the subject is the run's input or
+ * its final answer. At a tool boundary the useful refusal is usually the
+ * other one: fail this call, tell the model why, and let it choose
+ * something else. Reusing the word would give one spelling two meanings
+ * across boundaries, and a host that shared a function between them would
+ * get the wrong one silently.
+ *
+ * Hence two refusals rather than one:
+ *
+ *  - `refuse` — recoverable. The `tool_use` fails with the reason in place
+ *    of the output. Not blank and not dropped: a model shown an empty
+ *    result concludes the tool found nothing, which is a different fact and
+ *    invites the retry loop the refusal was meant to prevent.
+ *  - `halt` — terminal, for what must not be survived.
+ *
+ * `rewrite` is for REDACTION — a credential or an account number that
+ * should not enter context — and this is the last boundary where it can be
+ * removed before it does. It is **not** for neutralising an injection:
+ * editing an attack presumes you understood the payload well enough to
+ * defang it, and the systems that screen for attacks block instead. The two
+ * are the same mechanism and only the discipline separates them, which is
+ * why it is written here rather than left to be inferred.
+ */
+export type ToolResultVerdict =
+	| { readonly action: 'pass' }
+	| { readonly action: 'refuse'; readonly reason: string }
+	| { readonly action: 'halt'; readonly reason: string }
+	| { readonly action: 'rewrite'; readonly output: string; readonly reason?: string }
+
+export type ToolResultGuardrail = (
+	ctx: ToolResultGuardrailContext,
+) => ToolResultVerdict | Promise<ToolResultVerdict>
+
+export type ToolResultGuardrailSpec = ToolResultGuardrail | NamedGuardrail<ToolResultGuardrail>
+
 export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>
 export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>

package/src/types/tool/index.ts

@@ -1,5 +1,10 @@
 import type { z } from 'zod'
 import type { Logger } from '../../utils/logger.js'
+// Type-only, and circular by design: a tool-result guardrail is described in
+// terms of the tool that produced the result, and the registry that holds
+// the guardrails is described here. Erased at compile time, so neither
+// module exists at runtime to depend on the other.
+import type { ToolResultGuardrailSpec } from '../guardrail/index.js'
 import type { RunId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { PermissionMode } from '../permission/index.js'
@@ -322,6 +327,36 @@ export interface ToolDefinition<TInput = unknown> {
 	isReadOnly?(input: TInput): boolean
 	isDestructive?(input: TInput): boolean
 	isConcurrencySafe?(input: TInput): boolean
+
+	/**
+	 * Where this tool came from, when it did not come from here.
+	 *
+	 * Absent means host-defined: this process, code the operator installed,
+	 * no untrusted party in the chain. Present means a connected server
+	 * supplied both the tool and its own description of what the tool does
+	 * — including whether it is read-only, which three separate gates were
+	 * treating as a fact rather than as the hint the wire calls it.
+	 *
+	 * See {@link isTrustedReadOnly}. This field exists so a gate can tell
+	 * the two apart; `isReadOnly` keeps reporting faithfully what the
+	 * server said, because the outbound re-export and the destructive
+	 * label shown to a human both need the server's own answer.
+	 */
+	provenance?: ToolProvenance
+}
+
+export interface ToolProvenance {
+	/** The connected server this tool came from, named as configured. */
+	readonly server: string
+	/**
+	 * The operator marked this server's read-only claims as trustworthy.
+	 *
+	 * Per server, never global: one switch meaning "trust annotations"
+	 * hands every connected server the same reach, which is the hole it
+	 * would be closing. Default false — an unmarked server's claim raises
+	 * the requirement and never lowers it.
+	 */
+	readonly readOnlyHintTrusted: boolean
 }
 
 export type ToolPermission =
@@ -360,6 +395,16 @@ export interface ToolTierConfig {
 export interface ToolRegistryConfig {
 	logger?: Logger
 	tierConfig?: ToolTierConfig
+	/**
+	 * Screens run against every tool result before anything downstream
+	 * reads it — the output budget, compaction, and the model itself are
+	 * all past this point.
+	 *
+	 * Absent means no screening, which is what shipped before this existed:
+	 * a connected server's text reached the model unexamined. See
+	 * {@link ToolResultGuardrailSpec}.
+	 */
+	resultGuardrails?: readonly ToolResultGuardrailSpec[]
 }
 
 export interface ToolExecutionResult extends ToolResult {

package/src/verification/rules.ts

@@ -1,4 +1,5 @@
 import { DANGEROUS_PATTERNS } from '../constants/tools/index.js'
+import { isTrustedReadOnly } from '../tools/trusted-read-only.js'
 import type { ToolDefinition } from '../types/tool/index.js'
 import type { GateDecision, VerificationRule } from '../types/verification/index.js'
 
@@ -12,7 +13,10 @@ export function evaluateRule(
 ): GateDecision | null {
 	switch (rule.type) {
 		case 'allow_read_only': {
-			return toolDef?.isReadOnly?.(toolInput) ? 'allow' : null
+			// A server's own claim about its own tool cannot settle this. See
+			// `isTrustedReadOnly`: a self-declaration may raise the requirement
+			// and never lower it.
+			return isTrustedReadOnly(toolDef, toolInput) ? 'allow' : null
 		}
 
 		case 'deny_dangerous_patterns': {