@arnilo/prism 0.0.6 → 0.0.7

package/dist/run-limits.js

@@ -0,0 +1,163 @@
+export const DEFAULT_RUN_LIMITS = Object.freeze({
+    maxTurns: 16,
+    maxProviderAttempts: 24,
+    maxToolRounds: 8,
+    maxToolCalls: 32,
+    maxWallTimeMs: 120_000,
+    maxRequestBytes: 8 * 1024 * 1024,
+    maxResponseBytes: 8 * 1024 * 1024,
+    maxInputTokens: 40_000,
+    maxOutputTokens: 10_000,
+    maxTotalTokens: 50_000,
+});
+export const HARD_MAX_RUN_COST = 10_000;
+export const HARD_RUN_LIMITS = Object.freeze({
+    maxTurns: 64,
+    maxProviderAttempts: 256,
+    maxToolRounds: 64,
+    maxToolCalls: 256,
+    maxWallTimeMs: 30 * 60_000,
+    maxRequestBytes: 64 * 1024 * 1024,
+    maxResponseBytes: 64 * 1024 * 1024,
+    maxInputTokens: 1_000_000,
+    maxOutputTokens: 250_000,
+    maxTotalTokens: 1_000_000,
+});
+const LIMIT_NAMES = Object.keys(DEFAULT_RUN_LIMITS);
+const COUNTER_FOR = {
+    maxTurns: "turns",
+    maxProviderAttempts: "providerAttempts",
+    maxToolRounds: "toolRounds",
+    maxToolCalls: "toolCalls",
+    maxWallTimeMs: "wallTimeMs",
+    maxRequestBytes: "requestBytes",
+    maxResponseBytes: "responseBytes",
+    maxInputTokens: "inputTokens",
+    maxOutputTokens: "outputTokens",
+    maxTotalTokens: "totalTokens",
+    maxCost: "cost",
+};
+export class RunLimitError extends Error {
+    breach;
+    code = "ERR_PRISM_RUN_LIMIT";
+    constructor(breach) {
+        super(`Run limit exceeded: ${breach.limit}`);
+        this.breach = breach;
+        this.name = "RunLimitError";
+    }
+}
+/** Validate one host-authored layer. Defaults are applied only after inheritance is resolved. */
+export function resolveRunLimits(agent, run) {
+    const base = agent ? validateLimits(agent) : undefined;
+    const override = run ? validateLimits(run) : undefined;
+    const resolved = { ...DEFAULT_RUN_LIMITS };
+    for (const name of LIMIT_NAMES) {
+        if (base?.[name] !== undefined)
+            resolved[name] = base[name];
+        if (override?.[name] !== undefined)
+            resolved[name] = base ? Math.min(resolved[name], override[name]) : override[name];
+    }
+    const maxCost = override?.maxCost ?? base?.maxCost;
+    return Object.freeze({ ...resolved, ...(maxCost ? { maxCost: base?.maxCost && override?.maxCost ? { amount: Math.min(base.maxCost.amount, override.maxCost.amount), currency: base.maxCost.currency === override.maxCost.currency ? base.maxCost.currency : failCurrency() } : maxCost } : {}) });
+}
+function failCurrency() { throw new TypeError("Run limit currencies must match when narrowed"); }
+function validateLimits(input) {
+    for (const name of LIMIT_NAMES) {
+        const value = input[name];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1 || value > HARD_RUN_LIMITS[name]) {
+            throw new TypeError(`${name} must be a positive safe integer at most ${HARD_RUN_LIMITS[name]}`);
+        }
+    }
+    if (input.maxCost) {
+        const { amount, currency } = input.maxCost;
+        if (!Number.isFinite(amount) || amount < 0 || amount > HARD_MAX_RUN_COST || !currency.trim())
+            throw new TypeError(`maxCost requires a finite amount from 0 through ${HARD_MAX_RUN_COST} and currency`);
+    }
+    return input;
+}
+export class RunLimitTracker {
+    options;
+    limits;
+    startedAt = performance.now();
+    deadlineAt;
+    counters;
+    timer;
+    exceeded;
+    constructor(limits, options = {}) {
+        this.options = options;
+        this.limits = limits;
+        this.counters = { turns: 0, providerAttempts: 0, toolRounds: 0, toolCalls: 0, wallTimeMs: 0, requestBytes: 0, responseBytes: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0, cost: 0, ...options.snapshot };
+        for (const [key, value] of Object.entries(this.counters)) {
+            if (!Number.isFinite(value) || value < 0 || (key !== "cost" && !Number.isSafeInteger(value))) {
+                throw new TypeError("Run limit snapshot must contain finite non-negative counters");
+            }
+        }
+        const deadline = options.deadlineAt ? Date.parse(options.deadlineAt) : Date.now() + limits.maxWallTimeMs;
+        if (!Number.isFinite(deadline))
+            throw new TypeError("Run limit deadlineAt is invalid");
+        this.deadlineAt = new Date(deadline).toISOString();
+        const remaining = Math.max(0, deadline - Date.now());
+        this.timer = setTimeout(() => this.exceed("maxWallTimeMs", limits.maxWallTimeMs), remaining);
+        this.timer.unref?.();
+        if (remaining === 0)
+            this.exceed("maxWallTimeMs", limits.maxWallTimeMs);
+    }
+    get breach() { return this.exceeded; }
+    snapshot() { return { ...this.counters, wallTimeMs: Math.min(this.limits.maxWallTimeMs, Math.ceil(performance.now() - this.startedAt)) }; }
+    dispose() { if (this.timer)
+        clearTimeout(this.timer); this.timer = undefined; }
+    charge(limit, delta = 1) {
+        if (!Number.isSafeInteger(delta) || delta < 0)
+            throw new TypeError("Run limit delta must be a non-negative safe integer");
+        const counter = COUNTER_FOR[limit];
+        const observed = this.counters[counter] + delta;
+        if (!Number.isSafeInteger(observed))
+            this.exceed(limit, Number.MAX_SAFE_INTEGER + 1);
+        this.counters[counter] = observed;
+        if (observed > this.limits[limit])
+            this.exceed(limit, observed);
+    }
+    recordUsage(usage) {
+        if (!usage) {
+            if (this.limits.maxCost)
+                this.exceed("maxCost", Number.POSITIVE_INFINITY);
+            return;
+        }
+        for (const key of ["inputTokens", "outputTokens", "totalTokens", "cacheReadTokens", "cacheWriteTokens"]) {
+            const value = usage[key];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+                throw new TypeError(`Provider usage ${key} must be a non-negative safe integer`);
+        }
+        const total = usage.totalTokens ?? ((usage.inputTokens ?? 0) + (usage.outputTokens ?? 0));
+        if (!Number.isSafeInteger(total))
+            throw new TypeError("Provider usage totalTokens is invalid");
+        this.charge("maxInputTokens", usage.inputTokens ?? 0);
+        this.charge("maxOutputTokens", usage.outputTokens ?? 0);
+        this.charge("maxTotalTokens", total);
+        if (usage.cost !== undefined && (!Number.isFinite(usage.cost) || usage.cost < 0))
+            throw new TypeError("Provider usage cost must be finite and non-negative");
+        if (!this.limits.maxCost)
+            return;
+        if (usage.cost === undefined || usage.currency !== this.limits.maxCost.currency)
+            this.exceed("maxCost", Number.POSITIVE_INFINITY);
+        const observed = this.counters.cost + usage.cost;
+        this.counters.cost = observed;
+        if (observed > this.limits.maxCost.amount)
+            this.exceed("maxCost", observed);
+    }
+    exceed(limit, observed) {
+        if (!this.exceeded) {
+            const maximum = limit === "maxCost" ? this.limits.maxCost?.amount ?? 0 : this.limits[limit];
+            this.exceeded = { limit, maximum, observed, ...(limit === "maxCost" && this.limits.maxCost ? { currency: this.limits.maxCost.currency } : {}) };
+            this.options.onExceeded?.(this.exceeded);
+        }
+        if (limit !== "maxWallTimeMs")
+            throw new RunLimitError(this.exceeded);
+    }
+}
+export function createRunLimitTracker(limits, options) {
+    return new RunLimitTracker(resolveRunLimits(undefined, limits), options);
+}
+//# sourceMappingURL=run-limits.js.map

package/dist/secure-agent.d.ts

@@ -0,0 +1,3 @@
+import type { Agent, SecureAgentOptions } from "./contracts.js";
+/** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
+export declare function createSecureAgent(options: SecureAgentOptions): Agent;

package/dist/secure-agent.js

@@ -0,0 +1,63 @@
+import { createAgent } from "./agents.js";
+import { validateRunStateOptions } from "./agent-run-state.js";
+import { resolveRunLimits } from "./run-limits.js";
+import { createToolParameterValidator, createToolRegistry } from "./tools.js";
+/** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
+export function createSecureAgent(options) {
+    if (!options.id.trim())
+        throw new TypeError("Secure agent requires a non-empty id");
+    if (!options.definitionRevision.trim())
+        throw new TypeError("Secure agent requires a non-empty definitionRevision");
+    if (!options.redactor || typeof options.redactor.redact !== "function")
+        throw new TypeError("Secure agent requires a redactor");
+    if (!options.permission || typeof options.permission.check !== "function")
+        throw new TypeError("Secure agent requires a permission policy");
+    if (!options.trust || typeof options.trust.check !== "function")
+        throw new TypeError("Secure agent requires a trust policy");
+    if (!options.toolArgumentValidator || typeof options.toolArgumentValidator.validate !== "function")
+        throw new TypeError("Secure agent requires a tool argument validator");
+    if (!options.limits || Object.keys(options.limits).length === 0)
+        throw new TypeError("Secure agent requires explicit limits");
+    if (!options.ownership || !Object.values(options.ownership).some((value) => typeof value === "string" && value.trim()))
+        throw new TypeError("Secure agent requires non-empty ownership");
+    for (const tool of options.tools) {
+        if (!tool.name.trim())
+            throw new TypeError("Secure agent tool names must be non-empty");
+        if (!tool.parameters || Object.keys(tool.parameters).length === 0)
+            throw new TypeError(`Secure agent tool ${tool.name} requires a non-empty parameters schema`);
+    }
+    resolveRunLimits(options.limits);
+    const runState = Object.freeze({ ...options.runState, definitionRevision: options.definitionRevision, interruptBeforeTool: true });
+    validateRunStateOptions(runState);
+    const config = Object.freeze({
+        ...withoutSecureFields(options),
+        id: options.id,
+        tools: createToolRegistry(options.tools, { duplicate: "error" }),
+        validator: createToolParameterValidator(options.toolArgumentValidator, { missingSchema: "reject" }),
+        redactor: options.redactor,
+        permission: options.permission,
+        trust: options.trust,
+        ownership: Object.freeze({ ...options.ownership }),
+        limits: Object.freeze({ ...options.limits }),
+        guardrails: freezeGuardrails(options.guardrails),
+        runState,
+        secure: true,
+    });
+    return createAgent(config);
+}
+function withoutSecureFields(options) {
+    const { tools: _tools, toolArgumentValidator: _validator, redactor: _redactor, permission: _permission, trust: _trust, ownership: _ownership, limits: _limits, guardrails: _guardrails, definitionRevision: _revision, runState: _runState, ...config } = options;
+    return config;
+}
+function freezeGuardrails(guardrails) {
+    if (!guardrails)
+        return undefined;
+    return Object.freeze({
+        ...guardrails,
+        input: Object.freeze([...(guardrails.input ?? [])]),
+        output: Object.freeze([...(guardrails.output ?? [])]),
+        toolInput: Object.freeze([...(guardrails.toolInput ?? [])]),
+        toolOutput: Object.freeze([...(guardrails.toolOutput ?? [])]),
+    });
+}
+//# sourceMappingURL=secure-agent.js.map

package/dist/tools.d.ts

@@ -1,8 +1,9 @@
-import type { AgentEvent, ErrorInfo, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { RunLimitTracker } from "./run-limits.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
-import { type PermissionPolicy } from "./security.js";
+import { type PermissionPolicy, type TrustPolicy } from "./security.js";
 export interface ToolFilter {
     readonly allow?: readonly string[];
     readonly deny?: readonly string[];
@@ -33,12 +34,19 @@ export interface DispatchToolCallOptions {
     readonly filter?: ToolFilterInput;
     readonly middleware?: MiddlewareRegistry;
     readonly validate?: ToolValidator;
+    /** Adapter-specific policy check immediately before the tool side effect. */
+    readonly beforeExecute?: (call: ToolCallContent, tool: ToolDefinition, context: ToolExecutionContext) => void | Promise<void>;
     readonly emit?: (event: AgentEvent) => void | Promise<void>;
     readonly secrets?: readonly (string | undefined)[];
     readonly permission?: PermissionPolicy;
+    readonly trust?: TrustPolicy;
     readonly redactor?: SecretRedactor;
     readonly ledger?: RunLedger;
     readonly ownership?: OwnershipScope;
+    /** Tool stages run after middleware normalization and before side effects/exposure. */
+    readonly guardrails?: Guardrails;
+    /** Shared run tracker; direct hosts may supply one for their call scope. */
+    readonly limitTracker?: RunLimitTracker;
 }
 export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 }

package/dist/tools.js

@@ -1,8 +1,9 @@
 import { isJsonObject } from "./config.js";
 import { createId } from "./ids.js";
+import { GuardrailError, runGuardrails } from "./guardrails.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
-import { assertPermission } from "./security.js";
+import { assertPermission, assertTrusted } from "./security.js";
 /** Wrap a schema adapter as the existing `ToolValidator` seam used by dispatch and the agent runtime. */
 export function createToolParameterValidator(validator, options = {}) {
     const missingSchema = options.missingSchema ?? "allow";
@@ -59,10 +60,28 @@ function toolExecutionMetadata(startedAt, status) {
 export async function dispatchToolCall(options) {
     const secrets = options.secrets ?? [];
     const startedAt = new Date().toISOString();
-    const precheck = await checkCall(options.call, options, startedAt);
-    if (precheck)
-        return precheck;
+    options.limitTracker?.charge("maxToolCalls");
     const mediatedCall = await (options.middleware?.run("tool_call", options.call) ?? options.call);
+    const inputGuards = await runGuardrails({
+        stage: "tool_input",
+        guardrails: options.guardrails,
+        value: mediatedCall,
+        context: {
+            sessionId: options.context.sessionId,
+            runId: options.context.runId,
+            toolCallId: mediatedCall.id,
+            toolName: mediatedCall.name,
+            metadata: options.context.metadata ?? {},
+            signal: options.context.signal,
+        },
+        redactor: options.redactor,
+        emit: options.emit,
+    });
+    if (inputGuards.terminal) {
+        if (inputGuards.terminal.action !== "block")
+            throw new GuardrailError(inputGuards.terminal);
+        return blocked(mediatedCall, options.context, "guardrail_blocked", { message: "Tool call blocked by guardrail" }, options, startedAt);
+    }
     const tool = options.registry.get(mediatedCall.name);
     const postcheck = await checkCall(mediatedCall, options, startedAt);
     if (postcheck)
@@ -89,6 +108,7 @@ export async function dispatchToolCall(options) {
         },
     };
     try {
+        await assertTrusted(options.trust, { kind: "tool", target: mediatedCall.name, capability: "execute", metadata: options.context.metadata });
         await assertPermission(options.permission, { kind: "tool", action: "execute", target: mediatedCall.name, metadata: options.context.metadata });
     }
     catch (error) {
@@ -97,11 +117,39 @@ export async function dispatchToolCall(options) {
     const validation = await options.validate?.(tool, mediatedCall.arguments, context);
     if (validation)
         return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options, startedAt);
+    try {
+        await options.beforeExecute?.(mediatedCall, tool, context);
+    }
+    catch (error) {
+        if (error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED")
+            throw error;
+        return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
+    }
     await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
     await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
     try {
         const raw = await tool.execute(mediatedCall.arguments, context);
         const mediatedResult = await (options.middleware?.run("tool_result", raw) ?? raw);
+        const outputGuards = await runGuardrails({
+            stage: "tool_output",
+            guardrails: options.guardrails,
+            value: mediatedResult,
+            context: {
+                sessionId: context.sessionId,
+                runId: context.runId,
+                toolCallId: mediatedCall.id,
+                toolName: mediatedCall.name,
+                metadata: context.metadata ?? {},
+                signal: context.signal,
+            },
+            redactor: options.redactor,
+            emit: options.emit,
+        });
+        if (outputGuards.terminal) {
+            if (outputGuards.terminal.action !== "block")
+                throw new GuardrailError(outputGuards.terminal);
+            return blocked(mediatedCall, context, "guardrail_blocked", { message: "Tool result blocked by guardrail" }, options, startedAt);
+        }
         const result = options.redactor?.redact(mediatedResult) ?? mediatedResult;
         const finishedAt = new Date().toISOString();
         const metadata = toolExecutionMetadata(startedAt, "finished");
@@ -110,6 +158,8 @@ export async function dispatchToolCall(options) {
         return result;
     }
     catch (error) {
+        if (error instanceof GuardrailError)
+            throw error;
         const info = errorToErrorInfo(error, secrets);
         const result = { toolCallId: mediatedCall.id, name: mediatedCall.name, error: info };
         const finishedAt = new Date().toISOString();

package/docs/agent-events.md

@@ -38,11 +38,12 @@ The `AgentEvent` union (grouped by concern):
 
 | Group | Variants |
 | --- | --- |
-| Agent lifecycle | `agent_started`, `agent_finished` |
+| Agent lifecycle | `agent_started`, `agent_suspended`, `agent_resumed`, `agent_denied`, `agent_finished` |
 | Turns | `turn_started`, `turn_finished` |
 | Provider turns | `provider_turn_started`, `provider_turn_finished` |
 | Assistant messages | `message_started`, `message_delta`, `message_finished` |
 | Tool execution | `tool_execution_started`, `tool_execution_progress`, `tool_execution_finished`, `tool_execution_error`, `tool_execution_blocked` |
+| Guardrails | `guardrail_decision` |
 | Queue/subscribers | `queue_updated`, `event_subscriber_overflow` |
 | Compaction | `compaction_started`, `compaction_finished` |
 | Retry | `retry_scheduled` |
@@ -59,6 +60,9 @@ Agent / turn / message events:
 | --- | --- |
 | `agent_started` | `sessionId`, `runId` |
 | `agent_finished` | `sessionId`, `runId`, `usage?: Usage` (aggregate of all usage-bearing provider turns) |
+| `agent_suspended` | `sessionId`, `runId`, redacted `interruption`, checkpoint `version`; no tool side effect has started. |
+| `agent_resumed` | `sessionId`, `runId`, checkpoint `version`. |
+| `agent_denied` | `sessionId`, `runId`, redacted `interruption`, checkpoint `version`; no tool side effect runs. |
 | `turn_started` / `turn_finished` | `sessionId`, `runId`, `turn: number` |
 | `message_started` / `message_finished` | `sessionId`, `runId`, `message: Message` |
 | `message_delta` | `sessionId`, `runId`, `content: ContentBlock` (`tool_call_delta` fragments may appear here for live UI streaming; stored messages use final `tool_call` blocks) |
@@ -75,6 +79,14 @@ Tool execution events:
 | `tool_execution_error` | `sessionId`, `runId`, `call: ToolCallContent`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 | `tool_execution_blocked` | `sessionId`, `runId`, `toolCallId`, `name`, `reason: string`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 
+Guardrail events:
+
+| Variant | Fields |
+| --- | --- |
+| `guardrail_decision` | `sessionId`, `runId`, optional `toolCallId`/`toolName`, and redacted bounded `record: GuardrailRecord` (`guardrail`, stage, action, reason, metadata). |
+
+Guardrails emit their decision before a terminal run error or blocked tool result. Provider-output checks buffer assistant content, and tool-output checks discard blocked raw results before event/ledger/transcript exposure; see [Guardrails](guardrails.md).
+
 Queue / subscriber / compaction / retry / provider events:
 
 | Variant | Fields |

package/docs/agent-loops.md

@@ -57,7 +57,7 @@ await session.run(input, {
     parser: hostParser,       // optional; default treats assistant text as the value
     repairer: hostRepairer,  // optional; default stringifies validation.errors[].message
     maxRevisions: 3,         // optional; default 3
-    toolCalls: "bounded",    // optional; default "disabled"; uses RunOptions.maxToolRounds
+    toolCalls: "bounded",    // optional; default "disabled"; uses limits.maxToolRounds
   },
 });
 
@@ -80,7 +80,7 @@ type AgentLoopOptions =
       readonly parser?: ArtifactParser<unknown>;
       readonly repairer?: ArtifactRepairer<unknown>;
       readonly maxRevisions?: number;
-      /** Default "disabled". "bounded" dispatches sequentially up to RunOptions.maxToolRounds. */
+      /** Default "disabled". "bounded" dispatches sequentially up to limits.maxToolRounds. */
       readonly toolCalls?: "disabled" | "bounded";
     };
 ```
@@ -109,6 +109,10 @@ Host callback contracts (all generic over host `T`):
 | `appendMessage(message)` | Appends to the store under the run (redacted). |
 | `emit(event)` | Emits a redacted `AgentEvent`. |
 
+## Durable runs
+
+`RunOptions.runState` supports only built-in loop options (`single-shot` and `generate-validate-revise`). A custom `AgentLoopStrategy` has arbitrary in-memory cursor state, so durable configuration rejects it before provider work. Built-in suspension occurs only before an input provider call or immediately before a tool side effect; completed provider turns remain in `SessionStore` history and are not repeated after `resumeAgentRun()`.
+
 ## Outputs / response / events
 
 `AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` as a fallback for custom loops. Core runtime independently accumulates every usage-bearing provider turn in O(turns), persists scoped turn/run rows, and emits `agent_finished` with the aggregate.
@@ -202,7 +206,7 @@ await session.run(input, { loop: twoShotLoop });
 - `{ strategy: "single-shot" }` resolves to the exported `singleShotLoop`; `{ strategy: "generate-validate-revise", ... }` is mapped by `resolveLoop()` to `generateValidateReviseLoop(opts)`. An unknown `strategy` throws before the first turn. Passing an `AgentLoopStrategy` instance bypasses the options form entirely (custom-loop escape hatch).
 - The loop is resolved once per run inside `RuntimeAgentSession.run()`, after the usual setup (provider/skills/tools resolution, history rebuild, model-change entry, input append, auto-compaction). The runtime's outer try/catch/finally, run-exclusivity, abort bridging, and subscriber close remain in place around `loop.run(ctx)`.
 - `LoopContext.assemble(nextInput, toolResults?)` accepts an optional tool-result accumulator so `singleShotLoop` can pass its loop-local results. Bounded artifact tools append results directly to shared history, then assemble the next turn with empty new input; no second transcript path exists.
-- `maxToolRounds` bounds both `singleShotLoop` and opt-in bounded artifact tool rounds across the whole run. Artifact mode always dispatches sequentially, regardless of `toolConcurrency`; all dispatches still use existing registry/filter/permission/validator/middleware/redactor/ledger guards.
+- `limits.maxToolRounds` bounds both `singleShotLoop` and opt-in bounded artifact tool rounds across the whole run. Artifact mode always dispatches sequentially, regardless of `toolConcurrency`; all dispatches still use existing registry/filter/permission/validator/middleware/redactor/ledger guards. Deprecated `maxToolRounds` only narrows this limit.
 - `maxRevisions` (default 3) counts only failed call-free artifact candidates. Bounded artifact runs make at most `1 + maxRevisions + maxToolRounds` provider turns. A tool-round limit is terminal and returns last usage after `artifact_failed`; it does not throw.
 - A revision cycle appends one assistant draft and one repair user message per revision to the session store, so store entries reflect every attempted draft. The original user input is stored once by the runtime and pushed into loop history once on the first turn. Repair messages are assembled as the next provider `nextInput` and only pushed into live history after that revision request has been generated, so the model never receives a duplicated repair instruction.
 
@@ -215,6 +219,10 @@ await session.run(input, { loop: twoShotLoop });
 - The loop is a plain object/factory; no class hierarchy, no background work, no extra dependencies. `LoopContext` is a single object literal of bound arrows built once per run.
 - The Synapta-free boundary is guarded by tests: `src/` imports no `synapta*` package, and the `Artifact*`/`AgentLoop*`/`LoopContext` contracts contain no `workflow`/`node`/`step` field names. Hosts supply their own schema; no host domain type is imported by `src/`.
 
+## Guardrails
+
+Built-in loops and custom loops that use `LoopContext.generate()` / `LoopContext.dispatchToolCall()` inherit runtime guardrails. Provider output is checked before a loop appends assistant content; tool stages remain in shared dispatch. Do not call providers or `ToolDefinition.execute()` directly if guardrail enforcement is required; see [Guardrails](guardrails.md).
+
 ## Related APIs
 - [Agent/session runtime](agent-session-runtime.md): `RuntimeAgentSession.run()` builds the `LoopContext` and delegates to the resolved loop.
 - [Agent events](agent-events.md): the `artifact_*` event variants and ordering emitted by `generateValidateReviseLoop`.

package/docs/agent-session-runtime.md

@@ -5,6 +5,7 @@
 The agent/session runtime adds the minimal shared SDK surface for running provider turns, dispatching complete host-owned tool calls, and subscribing to session events:
 
 - `createAgent(config)`
+- `createSecureAgent(options)` for opt-in fail-closed composition
 - `createAgentSession(config)`
 - `agent.createSession(config)`
 - `session.run(input, options)` → `AgentRunResult`
@@ -17,6 +18,8 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `session.checkout(leafId?)`
 - `session.fork(options?)`
 - `session.clone(options?)`
+- `resumeAgentRun(agent, ref, decision, options)`
+- `createAgentRunLifecycle({ checkpoints, resolveAgent })` for host-selected remote status/resume adapters
 
 The runtime streams provider text/tool-call content into `AgentEvent` values. Complete `tool_call` events are dispatched through the active host `ToolRegistry`, then returned as tool-result messages on the next provider turn. When a store is supplied, user, assistant, tool-result, and model-change entries are appended under the current branch leaf. Abort propagation and run exclusivity use native `AbortController`.
 
@@ -43,7 +46,9 @@ string | Message | readonly Message[]
 
 `AgentSessionConfig.store` overrides `AgentConfig.store`; otherwise the session gets a private memory store. `AgentSessionConfig.leafId` selects the branch leaf to resume from.
 
-`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"legacy"` by default, or opt-in `"cache_aware"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. `RunOptions.maxToolRounds` bounds repeated tool turns and defaults to `1`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
+`AgentConfig.limits` sets run ceilings; `RunOptions.limits` may only narrow configured agent values. Limits cover turns, provider attempts, tool rounds/calls, wall time, request/response bytes, tokens, and optional single-currency cost. A breach emits one `run_limit_exceeded` event and throws `AgentRunError` with `result.limit`; see [Runs and usage ledger](runs-and-usage.md#run-limits).
+
+`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"legacy"` by default, or opt-in `"cache_aware"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. Deprecated `RunOptions.maxToolRounds` narrows `limits.maxToolRounds`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
 
 ## Outputs / response / events
 
@@ -160,6 +165,33 @@ await agent.createSession().run("Hi", { model: overrideModel });
 - Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, or docs examples.
 - The event broadcaster is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`. It adds no dependency, timer, filesystem/network discovery, worker, or durable queue.
 
+## Durable interruption
+
+Set `runState` with a host-owned `CheckpointStore`, stable `definitionRevision`, and `interruptBeforeTool: true` to suspend at a persisted pre-side-effect boundary. A suspended result has `status: "suspended"`, a redacted `interruption`, and `runState.version`; it releases session resources before returning.
+
+```ts
+const result = await session.run("Publish draft", {
+  runState: { checkpoints, definitionRevision: "2026-07-20.1", interruptBeforeTool: true },
+});
+if (result.status === "suspended") {
+  await resumeAgentRun(agent, { runId: result.runId, sessionId: result.sessionId }, {
+    decision: "approve", expectedVersion: result.runState!.version!,
+  }, { checkpoints, definitionRevision: "2026-07-20.1" });
+}
+```
+
+Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. Only built-in loop options are durable; custom `AgentLoopStrategy` rejects before provider work.
+
+## Secure composition
+
+`createSecureAgent()` is optional; `createAgent()` remains explicit and backward-compatible. Secure composition requires an ID, non-empty definition revision, exact non-empty ownership, redactor, permission and trust policies, finite explicit limits, a host `ToolArgumentValidator`, non-empty schema for every tool, and checkpoints. It builds a duplicate-error registry, rejects missing schemas, always enables durable pre-tool interruption, and reuses normal provider/request policies without discovery or background work.
+
+Per-run options may narrow `limits` and append `guardrails`; they cannot replace secure ownership, redaction, validator, or durable checkpoint policy. Every active tool is trust-checked then permission-checked before validation and its side effect. See [`examples/secure-agent.ts`](../examples/secure-agent.ts).
+
+## Guardrails
+
+`AgentConfig.guardrails` applies typed input, output, tool-input, and tool-output checks to every run. `RunOptions.guardrails` appends checks for one run. Input checks run before session append; configured output checks buffer provider content until allowed, so blocked content is never emitted or stored. See [Guardrails](guardrails.md).
+
 ## Related APIs
 
 - [Public contracts](public-contracts.md): `Agent`, `AgentSession`, `RunOptions`, and `AgentEvent` contracts.

package/docs/guardrails.md

@@ -0,0 +1,75 @@
+# Guardrails
+
+## What it does
+
+Guardrails are typed, fail-closed checks at input, completed provider output, tool input, and raw tool output boundaries. `session.run()` evaluates configured stages through one core runner; `dispatchToolCall()` uses same runner for direct, MCP-server, and workflow tool calls.
+
+## When to use it
+
+Use guardrails to block unsafe prompts, model responses, tool arguments, or tool results before their next boundary. Use a redactor for known secrets. Do not treat guardrails as a sandbox, secret detector, permission policy, or validation replacement.
+
+## Inputs / request
+
+```ts
+import type { Guardrail, Guardrails } from "@arnilo/prism";
+
+const pii: Guardrail<"input"> = {
+  name: "pii",
+  stage: "input",
+  evaluate: ({ value }) => JSON.stringify(value).includes("SSN")
+    ? { action: "tripwire", reason: "pii" }
+    : { action: "allow" },
+};
+
+const guardrails: Guardrails = { input: [pii], maxConcurrency: 1 };
+```
+
+Set `AgentConfig.guardrails` for every session run or `RunOptions.guardrails` to append checks for one run. `DispatchToolCallOptions.guardrails`, workflow `RunWorkflowOptions.guardrails`, and MCP server `CreatePrismMcpServerOptions.guardrails` apply tool stages to direct calls. A stage has `Guardrail<"input" | "output" | "tool_input" | "tool_output">`, a name, optional revision, and `evaluate(context)` result.
+
+Decisions are `allow`, `block`, `tripwire`, or `interrupt`. Evaluation defaults to declaration-order sequential. `maxConcurrency` may be 1–16; records are emitted in declaration order. Thrown or malformed decisions become a fail-closed tripwire. Decision reasons are capped at 4 KiB and metadata at 16 KiB after JSON normalization and optional redaction.
+
+## Outputs / response / events
+
+Every evaluated guard produces a redacted `guardrail_decision` `AgentEvent` with a bounded `GuardrailRecord`. An input or output terminal decision rejects the run with `GuardrailError`; `tripwire` stops remaining evaluation. A tool-input or tool-output `block` returns a redacted blocked `ToolResult`; a `tripwire` rejects the enclosing run. `interrupt` is reserved for durable runs and currently fails closed with `ERR_PRISM_GUARDRAIL_INTERRUPT_UNAVAILABLE`.
+
+Ordering is fixed:
+
+1. input before session append, compaction, or provider work;
+2. provider output is privately collected, then output checks run before any assistant message event or persistence;
+3. tool input runs after tool-call middleware normalization and before lookup, permission, validation, execution policy, and side effect;
+4. tool output runs after the side effect but before redaction, tool events, ledger rows, transcript append, or next turn.
+
+With no output guardrails, provider streaming retains existing behavior. With output guardrails, message events are buffered until the completed provider turn is allowed.
+
+## Request/response example
+
+```json
+{
+  "event": {
+    "type": "guardrail_decision",
+    "record": { "guardrail": "pii", "stage": "input", "action": "tripwire", "reason": "pii" }
+  }
+}
+```
+
+## Implementation example
+
+```ts
+const agent = createAgent({ model, provider, guardrails: { input: [pii], output: [responseGuard] } });
+await agent.createSession().run("Draft reply", { guardrails: { toolInput: [commandGuard] } });
+```
+
+## Extension and configuration notes
+
+Guardrails are callbacks supplied by the host. Prism does not discover, load, retry, or persist callback code. `createSecureAgent()` keeps configured guardrails and only appends run-level checks; it never lets a run remove secure defaults. Custom loops receive guarded `LoopContext.generate()` and `LoopContext.dispatchToolCall()`; host code that directly calls a provider or `ToolDefinition.execute()` is outside the runtime boundary.
+
+## Security and performance notes
+
+Output buffering prevents blocked provider content from reaching subscribers, session entries, ledgers, parsers, delegation, or tools. Tool-output checks receive raw results but Prism discards blocked raw output before event, ledger, transcript, or MCP exposure. Redaction replaces exact known values only; it is not general secret detection. Parallel checks receive an abort signal, but callback code must honor it to stop in-flight work.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md)
+- [Tools](tools.md)
+- [Agent events](agent-events.md)
+- [Host security](host-security.md)

package/docs/host-security.md

@@ -25,10 +25,12 @@ Start from explicit host inputs. Do not let runtime code discover security state
 | Permission decisions | allow/deny rules or approval UI result | `createStaticPermissionPolicy`, `assertPermission()` |
 | Tool allow-list | active tools for this agent/session/run | `createToolRegistry`, `filterTools()`, `dispatchToolCall()` |
 | Tool argument rules | host validator | `AgentConfig.validator`, `RunOptions.validate`, `ToolValidator` |
+| Guardrail decisions | host callback allow/block/tripwire policy | `Guardrails`, `Guardrail`, `GuardrailError` |
 | Coding execution policy | path/command approval adapter | `ExecutionPolicy`, `@arnilo/prism-coding-security` |
 | Remote media policy | public/default pinned DNS or explicit trusted transport | `SsrfPolicy`, `resolveMediaContentBlock()` |
 | Durable history | host database adapter | `SessionStore`, `assertSessionStoreConforms()` |
 | Durable audit | host ledger adapter | `RunLedger`, `redactRunLedgerRecord()` |
+| Durable interruption | host checkpoint + session stores, exact ownership | `RunOptions.runState`, `resumeAgentRun()`, `createAgentRunLifecycle()`, `createSecureAgent()` |
 | Extensions | explicit package imports only | `createExtensionKernel`, `ExtensionAPI` |
 | Remote agent/workflow API | host authentication + ownership mapping | `@arnilo/prism-server`, `createPrismHandler()` |
 | MCP server exposure | host MCP auth + selected capability list | `createPrismMcpServer()`, `createPrismMcpWebHandler()` |
@@ -41,7 +43,9 @@ Security controls fail closed before side effects when wired at the guarded edge
 - permission denial blocks extension setup, resource loading, and tool execution
 - unknown or denied tools emit `tool_execution_blocked`
 - validator failures emit `tool_execution_blocked` with `validation_failed`
-- configured redactors scrub provider requests, agent events, session entries, ledger records, tool errors, extension errors, and injector context
+- configured guardrails fail closed; output stages buffer blocked provider/tool content before events, ledgers, session entries, or MCP responses
+- configured redactors scrub provider requests, agent events, session entries, ledger records, tool errors, extension errors, injector context, and durable run checkpoints
+- durable resume requires host-derived exact ownership and checkpoint version; `createAgentRunLifecycle()` exposes only public state through explicitly selected server/MCP capabilities; never accept ownership or resume input from an approval body
 
 These checks are explicit function calls during load, assembly, dispatch, append, or run handling. Prism adds no background watchers, filesystem scanners, network probes, credential polling, or automatic extension discovery.
 
@@ -104,7 +108,7 @@ const tools = createToolRegistry(filterTools([readNotes], { allow: ["notes/read"
 void { apiKey, redactor, permission, trust, tools, validate };
 ```
 
-Wire those values where they matter: provider adapters receive the resolved credential, agents/runs receive `redactor`, tool dispatch receives `permission` and `validate`, resource/extension loaders receive `trust` and `permission`, and durable adapters receive already-redacted entries/records.
+Wire those values where they matter: provider adapters receive the resolved credential, agents/runs receive `redactor`, tool dispatch receives `trust`, `permission`, and `validate`, resource/extension loaders receive `trust` and `permission`, and durable adapters receive already-redacted entries/records. `createSecureAgent()` is an opt-in shortcut that requires these agent/tool seams, strict schemas, finite limits, exact ownership, and durable approval before every tool side effect; low-level `createAgent()` stays explicit.
 
 ## Extension and configuration notes