@arnilo/prism 0.9.0 → 0.10.0

package/dist/contracts-core/provider.d.ts

@@ -74,8 +74,13 @@ export type ProviderStopReason = "end_turn" | "tool_calls" | "max_output_tokens"
  * axis, so a host can see which limit was closest without instrumenting the session.
  */
 export interface TurnBudgets {
-    /** Provider-reported input tokens for this turn; absent when the provider reported none. */
+    /** Input tokens charged for this turn: provider-reported, or a labeled fallback estimate when the
+     *  provider reported none; absent when neither exists. See `inputTokensSource`. */
     readonly inputTokens?: number;
+    /** Provenance of `inputTokens`: `"reported"` from the provider, `"estimated"` from the
+     *  `usageEstimation: "fallback"` seam. Absent together with `inputTokens`; `usage.estimated` stays
+     *  the authoritative label for the turn's usage. */
+    readonly inputTokensSource?: "reported" | "estimated";
     /** Resolved per-request input cap (attention compiler when enabled); absent when no cap derivable. */
     readonly inputCap?: number;
     /** Cumulative run input budget (`RunLimits.maxInputTokens`); absent when the axis is disabled. */

package/dist/contracts-core/run-limits.d.ts

@@ -22,6 +22,12 @@ export interface RunLimits {
         readonly amount: number;
         readonly currency: string;
     };
+    /**
+     * Clean cap on stop-hook continuations in one run (plan 106 R1). Default 3; `0` observes stop
+     * hooks but never continues; `null` disables the cap. Layers narrow by min like every other
+     * policy axis, and the cap ends the run with `stopReason: "hook_limit"` (no limit breach).
+     */
+    readonly maxStopContinuations?: number | null;
 }
 /** Fully resolved limits after `resolveRunLimits`: every policy axis is a finite cap or `null` (disabled). */
 export interface ResolvedRunLimits {
@@ -39,8 +45,11 @@ export interface ResolvedRunLimits {
         readonly amount: number;
         readonly currency: string;
     };
+    /** Stop-hook continuation cap (plan 106 R1); not a run-limit counter axis. */
+    readonly maxStopContinuations: number | null;
 }
-export type RunLimitName = keyof Required<RunLimits>;
+/** Counter-backed limit axes; `maxStopContinuations` caps a clean stop instead of a breach. */
+export type RunLimitName = Exclude<keyof Required<RunLimits>, "maxStopContinuations">;
 export interface RunLimitCounters {
     readonly turns: number;
     readonly providerAttempts: number;

package/dist/contracts-protocol.d.ts

@@ -1,6 +1,6 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, BudgetAxisUsage, BudgetConsumedCounters, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, ProviderStopReason, RetryOptions, RunLimitBreach, RunLimitName, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, ToolCallSummary, TurnBudgets, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { CacheUsageReport } from "./cache-helpers.js";
 import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, BudgetAxisUsage, BudgetConsumedCounters, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, ProviderStopReason, RetryOptions, RunLimitBreach, RunLimitName, RunLimits, Skill, StopHook, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, ToolCallSummary, TurnBudgets, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -137,6 +137,8 @@ export interface RunOptions {
      * evaluated before every provider request. Omitted → no callback runs.
      */
     readonly turnPolicy?: TurnPolicyOptions;
+    /** Appended to agent-level stop hooks for this run (plan 106 R1). */
+    readonly stopHooks?: readonly StopHook[];
 }
 export interface ProviderTurnMetadata {
     readonly providerId: string;
@@ -193,8 +195,8 @@ export interface DelegatedAgentStep {
         readonly label?: string;
     };
 }
-/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop; the rest are loop ceilings (F4). */
-export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy";
+/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop, `hook_limit` a stop-hook continuation cap; the rest are loop ceilings (F4). */
+export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy" | "hook_limit";
 /**
  * Origin of an agent event forwarded from a delegated child (supervisor child-event passthrough).
  * Present only on child events routed onto a parent stream; absent on a session's own events.
@@ -215,7 +217,7 @@ type AgentEventPayload = {
     readonly sessionId: string;
     readonly runId: string;
     readonly usage?: Usage;
-    /** Why the loop stopped, when a limit/ceiling or a host turn policy ended the run cleanly (F4). Absent = natural end. */
+    /** Why the loop stopped, when a limit/ceiling, a host turn policy, or a stop-hook continuation cap ended the run cleanly (F4). Absent = natural end. */
     readonly finishReason?: AgentFinishReason;
     /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). Present only with `finishReason: "host_policy"`. */
     readonly stopDetail?: string;

package/dist/contracts-run-state.d.ts

@@ -1,6 +1,6 @@
-import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
-import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
 import type { CheckpointRestoreHook } from "./checkpoint-restore.js";
+import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, GuardrailPackRef, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
+import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
 export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
@@ -27,6 +27,16 @@ export interface PendingDecision {
     readonly reason: string;
     /** Typed payload contract for elicitation decisions. */
     readonly elicitationSchema?: JsonObject;
+    /**
+     * Plan 104 T3: pack `ask` rule that gated this call as `pack:<pack>/<rule>` (bounded by the
+     * compile-time id limits), present only when a pack rule raised the decision.
+     */
+    readonly guardrail?: string;
+    /** Plan 104 T3: machine-readable ids behind `guardrail`, so a host never parses the name. */
+    readonly guardrailRule?: {
+        readonly pack: string;
+        readonly rule: string;
+    };
     /** Delegation chain, root-first; core-written, never client-supplied. */
     readonly attribution?: {
         readonly path: readonly string[];
@@ -38,6 +48,8 @@ export interface AgentRunInterruption {
     readonly reason: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** Plan 104 T3: the pack rule that raised this suspension (`pack:<pack>/<rule>`), when one did. */
+    readonly guardrail?: string;
     /** All unresolved approval requests of this suspension; absent for legacy single approvals. */
     readonly pendingDecisions?: readonly PendingDecision[];
 }
@@ -350,6 +362,12 @@ export interface SteerOptions {
 }
 export interface AgentSession {
     readonly id: string;
+    /**
+     * Plan 104 Task 2: guardrail pack refs this session enforces (the restored rows after a durable
+     * resume); `undefined` when it enforces none. Pass to `snapshotRunBundle({ packs })` for the
+     * recorded identity that matches enforcement.
+     */
+    readonly guardrailPackRefs?: readonly GuardrailPackRef[];
     /** Current branch leaf entry id; advances on every append/run and is re-pointed by `checkout`.
      *  Undefined until the first entry lands (a fresh session with no history). */
     readonly leafId: string | undefined;
@@ -361,10 +379,26 @@ export interface AgentSession {
      * Fails closed when no run is active or the pending queue exceeds caps.
      */
     steer(input: string | Message | readonly Message[], options?: SteerOptions): void;
-    /** Subscribe first, then start exactly one run and yield only that run's events until it terminates. */
+    /**
+     * Subscribe first, then start exactly one run and yield only that run's events until it terminates.
+     * This subscription belongs to `stream()`: it is closed when the owned run settles (so a pre-flight
+     * rejection unblocks the consumer instead of parking it behind a run that never emits).
+     */
     stream(input: string | Message | readonly Message[], options?: RunOptions & SubscribeOptions): AsyncIterable<AgentEvent>;
     compact(options?: CompactionOptions): Promise<CompactionResult>;
+    /**
+     * Subscribe to this session's live events. A run-scoped subscriber (default) is closed when the run
+     * ends, suspends, or is denied; `SubscribeOptions.acrossRuns: true` keeps it open across runs until
+     * `subscription.close()`, `closeSubscribers()`, or a queue overflow closes it.
+     */
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
+    /**
+     * Plan 106 R2: session teardown. Dispatches `session_shutdown` middleware once (idempotent), then
+     * closes every subscriber (`acrossRuns` included); calling it twice is a no-op. Call after the
+     * active run settles. Subscriber-only teardown stays `break`ing the `for await` (or calling the
+     * iterator's `return()`). See [Agent/session runtime](agent-session-runtime.md).
+     */
+    close(): Promise<void>;
     abort(reason?: unknown): void;
     entries(): Promise<readonly SessionEntry[]>;
     checkout(leafId?: string): Promise<void>;

package/dist/contributions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDefinition, AuthMethod, CommandDefinition, CompactionStrategy, ContextProvider, CredentialResolver, DiscoveredContribution, InputBuilder, InstructionInjector, PromptBuilder, ProviderPackage, ProviderRequestPolicy, ResourceLoader, RetryPolicy, SettingsProvider, Skill, StoreFactory, SystemPromptContribution, ToolDefinition } from "./contracts.js";
+import type { AgentDefinition, AuthMethod, CommandDefinition, CompactionStrategy, ContextProvider, CredentialResolver, DiscoveredContribution, InputBuilder, InstructionInjector, PromptBuilder, ProviderPackage, ProviderRequestPolicy, ResourceLoader, RetryPolicy, SettingsProvider, Skill, StopHook, StoreFactory, SystemPromptContribution, ToolDefinition } from "./contracts.js";
 import { type ModelRegistry } from "./models.js";
 import { type ProviderRegistry } from "./providers.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
@@ -35,6 +35,7 @@ export interface ContributionRegistries {
     readonly providerRequestPolicies: ContributionRegistry<ProviderRequestPolicy>;
     readonly systemPromptContributions: ContributionRegistry<SystemPromptContribution>;
     readonly instructionInjectors: ContributionRegistry<InstructionInjector>;
+    readonly stopHooks: ContributionRegistry<StopHook>;
 }
 export interface ContributionRegistriesOptions extends DuplicateRegistrationOptions {
 }

package/dist/contributions.js

@@ -49,6 +49,7 @@ export function createContributionRegistries(options = {}) {
         providerRequestPolicies: createContributionRegistry(registryOptions("provider request policy")),
         systemPromptContributions: createContributionRegistry(registryOptions("system prompt contribution")),
         instructionInjectors: createContributionRegistry(registryOptions("instruction injector")),
+        stopHooks: createContributionRegistry(registryOptions("stop hook")),
     };
 }
 /** Register discovered contributions into the given registries. Inert: skill

package/dist/extensions.d.ts

@@ -1,4 +1,4 @@
-import type { CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, ToolDefinition } from "./contracts.js";
+import type { AgentEvent, CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, StopHook, ToolDefinition } from "./contracts.js";
 import { type ContributionRegistries } from "./contributions.js";
 import { type MiddlewareRegistry } from "./middleware.js";
 import { type PermissionPolicy } from "./security.js";
@@ -40,6 +40,18 @@ export interface ExtensionKernel {
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;
+export interface AgentEventBridgeOptions {
+    /** Bridge-side failure (a source error, or a bus listener that throws under `errorPolicy: "throw"`).
+     *  Never rethrown — the bridge must not fail the run it is observing. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Forward an `AgentEvent` iterable onto the extension bus, one mapped lifecycle event at a time
+ * (plan 106 R2). Handlers run in event order and never in the run's path, so a slow or throwing
+ * listener cannot stall or fail the observed run. Returns an unsubscribe that stops forwarding and
+ * releases the source iterator.
+ */
+export declare function forwardAgentEvents(source: AsyncIterable<AgentEvent>, events: Pick<ExtensionEventBus, "emit">, options?: AgentEventBridgeOptions): () => void;
 /** Host-owned activation: copy contributed entries into the `createAgent()`
  *  fields that accept plain arrays. Contributions stay inert until the host
  *  passes the returned fields into runtime config. Array slots only —
@@ -51,6 +63,8 @@ export interface ActivatedKernelConfig {
     readonly skills: readonly Skill[];
     readonly instructionInjectors: readonly InstructionInjector[];
     readonly context: readonly ContextProvider[];
+    /** Run-end stop hooks (plan 106 R1); pass to `createAgent({ stopHooks })`. */
+    readonly stopHooks: readonly StopHook[];
     /** For host command surfaces (CLI/RPC/UI); not part of `AgentConfig`. */
     readonly commands: readonly CommandDefinition[];
     /** The kernel middleware registry itself; runs only when passed to runtime config. */

package/dist/extensions.js

@@ -143,6 +143,10 @@ export function createExtensionKernel(options = {}) {
             registries.instructionInjectors.register(injector.name, injector);
             track?.(() => registries.instructionInjectors.unregister(injector.name));
         },
+        registerStopHook(hook) {
+            registries.stopHooks.register(hook.name, hook);
+            track?.(() => registries.stopHooks.unregister(hook.name));
+        },
     });
     const unwind = (undo) => {
         for (const fn of undo.reverse()) {
@@ -190,12 +194,76 @@ export function createExtensionKernel(options = {}) {
         },
     };
 }
+/**
+ * Lifecycle hook each forwarded `AgentEvent` maps onto (plan 106 R2). Notification only: the bus
+ * receives the original event as `payload` and nothing is transformed. Events not listed here are
+ * ignored — notably `agent_finished` stays an AgentEvent and is not re-emitted as a bus event.
+ */
+const AGENT_EVENT_BRIDGE = {
+    agent_started: "before_agent_start",
+    turn_started: "turn",
+    turn_finished: "turn",
+    tool_execution_started: "tool_call",
+    tool_execution_finished: "tool_result",
+};
+/**
+ * Forward an `AgentEvent` iterable onto the extension bus, one mapped lifecycle event at a time
+ * (plan 106 R2). Handlers run in event order and never in the run's path, so a slow or throwing
+ * listener cannot stall or fail the observed run. Returns an unsubscribe that stops forwarding and
+ * releases the source iterator.
+ */
+export function forwardAgentEvents(source, events, options = {}) {
+    const iterator = source[Symbol.asyncIterator]();
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A throwing error callback must not become an unhandled rejection.
+        }
+    };
+    let stopped = false;
+    // Serially chained so a listener that awaits keeps event order; the run never awaits this chain.
+    let pending = Promise.resolve();
+    void (async () => {
+        try {
+            while (!stopped) {
+                const { value, done } = await iterator.next();
+                if (done || stopped)
+                    return;
+                const type = AGENT_EVENT_BRIDGE[value.type];
+                if (type === undefined)
+                    continue;
+                const event = { type, payload: value };
+                pending = pending.then(() => events.emit(event)).catch(report);
+            }
+        }
+        catch (error) {
+            if (!stopped)
+                report(error);
+        }
+    })();
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        void (async () => {
+            try {
+                await iterator.return?.();
+            }
+            catch (error) {
+                report(error);
+            }
+        })();
+    };
+}
 export function activateKernel(kernel) {
     return {
         tools: kernel.registries.tools.list(),
         skills: kernel.registries.skills.list(),
         instructionInjectors: kernel.registries.instructionInjectors.list(),
         context: kernel.registries.contextProviders.list(),
+        stopHooks: kernel.registries.stopHooks.list(),
         commands: kernel.registries.commands.list(),
         middleware: kernel.middleware,
     };

package/dist/guardrail-packs/types.d.ts

@@ -1,11 +1,20 @@
 /** Internal guardrail-pack definition types (plan 092 Task 2). Not SDK surface; hosts configure packs via `AgentSessionConfig.guardrailPacks`. */
 import type { GuardrailRule, GuardrailRuleContext } from "../contracts-core/guardrail-packs.js";
 import type { ToolResult } from "../contracts-protocol.js";
+/** Plan 104 Task 2: pack-owned durable-state codec. The pack decides what a checkpoint carries. */
+interface GuardrailPackStateCodec {
+    /** Serialize the live state for a checkpoint; `undefined` when nothing needs persisting. */
+    readonly snapshot: (state: Record<string, unknown>) => Readonly<Record<string, unknown>> | undefined;
+    /** Parse a persisted snapshot back into state fields; throw `GuardrailPackError` on a malformed value. */
+    readonly parse: (json: unknown) => Record<string, unknown>;
+}
 /** What a pack's `build` returns: restrictive rules plus an optional pure result observer. */
 export interface GuardrailPackRules {
     readonly rules: readonly GuardrailRule[];
     /** Records tool results into pack-local state (never denies); a throw fails closed as a guardrail tripwire. */
     readonly observe?: (state: Record<string, unknown>, result: ToolResult, context: GuardrailRuleContext) => void;
+    /** Optional codec making the pack's state survive a durable resume; a pack without one persists nothing. */
+    readonly state?: GuardrailPackStateCodec;
 }
 export interface GuardrailPackDefinition {
     readonly id: string;
@@ -14,3 +23,4 @@ export interface GuardrailPackDefinition {
     /** Pure factory: options in, rules out. No session access, no I/O. */
     readonly build: (options: Readonly<Record<string, unknown>>) => GuardrailPackRules;
 }
+export {};

package/dist/guardrail-packs/validation-respect.js

@@ -3,6 +3,7 @@ const MUTATING_TOOLS = ["write", "edit", "delete", "move"];
 /** Validation-style tool names. `shell` is opt-in (`validationTools`): a non-zero shell exit is a failure signal too. */
 const DEFAULT_VALIDATION_TOOLS = ["test", "run_tests", "validate", "validation", "lint", "typecheck", "check"];
 const MAX_VALIDATION_TOOLS = 16;
+const MAX_VALIDATION_TOOL_CHARS = 128;
 /** A tool result failed when it carries an error, or reported a non-zero `exitCode` (the shell tool's shape). */
 function resultFailed(result) {
     if (result.error !== undefined)
@@ -39,6 +40,21 @@ export const validationRespectPack = {
                     return;
                 state.validationFailed = resultFailed(result) ? context.toolName : undefined;
             },
+            // Plan 104 Task 2: one tool name (or nothing) survives a resume, so a mutation the suspended
+            // run denied stays denied. The codec is the pack's own bound: 128 chars, never arguments.
+            state: {
+                snapshot: (state) => (typeof state.validationFailed === "string" ? { validationFailed: state.validationFailed } : undefined),
+                parse: (json) => {
+                    const record = typeof json === "object" && json !== null ? json : {};
+                    const failed = record.validationFailed;
+                    if (failed === undefined)
+                        return {};
+                    if (typeof failed !== "string" || !failed.trim() || failed.length > MAX_VALIDATION_TOOL_CHARS) {
+                        throw new GuardrailPackError(`validation-respect persisted state.validationFailed must be a non-empty string of at most ${MAX_VALIDATION_TOOL_CHARS} chars`);
+                    }
+                    return { validationFailed: failed };
+                },
+            },
             rules: [
                 {
                     id: "no-mutation-after-failed-validation",

package/dist/guardrails.d.ts

@@ -1,10 +1,20 @@
-import type { AgentEvent, GuardrailContext, GuardrailPackRef, GuardrailRecord, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
+import type { AgentEvent, GuardrailContext, GuardrailPackRef, GuardrailRecord, GuardrailRule, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
 export { GuardrailPackError } from "./guardrail-packs/errors.js";
 import type { SecretRedactor } from "./redaction.js";
 export declare const MAX_GUARDRAIL_CONCURRENCY = 16;
 /** Guardrail pack compile bounds (plan 092 Task 2). All ceilings are config-shape limits, not runtime budgets. */
 export declare const MAX_GUARDRAIL_PACKS = 8;
 export declare const MAX_GUARDRAIL_PACK_RULES = 64;
+/**
+ * Plan 104 T4/T6: the bounded, redacted refusal line for a terminal record that came from a compiled
+ * pack rule — `<prefix> by guardrail rule pack:<pack>/<rule>`, plus the pack's own reason when it set
+ * one — or `undefined` for any other guardrail, so the caller keeps its own neutral text. Only the
+ * compiler writes the `pack`/`rule` metadata, so a host-written guardrail named `pack:…` is never
+ * presented as a pack rule. Reasons are redacted where the record is built, pack names are
+ * compiler-bounded to 128 bytes (the identity always survives the cap), and a long reason is
+ * truncated, so the same derivation serves the tool refusal and decision-time revalidation.
+ */
+export declare function guardrailRefusalText(record: GuardrailRecord, prefix?: string): string | undefined;
 export declare class GuardrailError extends Error {
     readonly code: string;
     readonly record: GuardrailRecord;
@@ -33,6 +43,30 @@ export interface GuardrailPackRow {
     readonly stage: "tool_input" | "tool_output";
     readonly revision: string | null;
 }
+/** Plan 104 Task 2: one replayable pack row of a durable checkpoint (`id`, resolved version, host options). */
+interface GuardrailPackRefRow {
+    readonly id: string;
+    readonly version: number;
+    /** Host options the pack was compiled with, replayed verbatim on resume so enforcement is identical. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /**
+     * Plan 104 T3: the host's own rule list for an inline pack. Patterns are data and ride the
+     * checkpoint; a `deny` predicate or a `RegExp` pattern cannot round-trip and is refused at save.
+     */
+    readonly rules?: readonly GuardrailRule[];
+}
+/** Plan 104 Task 2: a compile result that can round-trip through a durable checkpoint. */
+interface CompiledGuardrailPacks {
+    readonly guardrails: Guardrails | undefined;
+    /** Rows a durable checkpoint replays; empty when no packs are configured. */
+    readonly packs: readonly GuardrailPackRefRow[];
+    /** Plan 104 T3: `ask` rules as the charge-time durable gate — a match records `interrupt`. */
+    readonly askGate?: Guardrails;
+    /** Plan 104 T3: the same rules as plain blocks, merged into a run that cannot suspend. */
+    readonly askBlocks?: Guardrails;
+    /** Pack-owned state snapshot (`{ <packId>: <pack state> }`); `undefined` when nothing needs persisting. */
+    readonly snapshotState: () => Record<string, Readonly<Record<string, unknown>>> | undefined;
+}
 /**
  * Compiles `guardrailPacks` config onto the existing tool interception seams: one `tool_input`
  * guardrail per rule (`name = pack:<pack>/<rule>`), plus one `tool_output` recorder for packs that
@@ -40,5 +74,12 @@ export interface GuardrailPackRow {
  * Throws `GuardrailPackError` on malformed config (fail closed); returns `undefined` when unset.
  */
 export declare function compileGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): Guardrails | undefined;
+/**
+ * Plan 104 Task 2: the internal compile entry behind `compileGuardrailPacks`. Passing `initial`
+ * marks a durable restore — rows must then come from the installed registry, match its version, and
+ * parse through the pack's own state codec, so a mismatch fails closed instead of restoring a
+ * weaker policy. `snapshotState` is the checkpoint-side counterpart.
+ */
+export declare function compileGuardrailPacksWithState(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>, initial?: Readonly<Record<string, unknown>>): CompiledGuardrailPacks;
 /** Stable identity rows for the same config `compileGuardrailPacks` accepts (no state, no guardrails built). */
 export declare function describeGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): readonly GuardrailPackRow[];