@arnilo/prism 0.0.24 → 0.0.25

package/dist/contracts.d.ts

@@ -508,14 +508,144 @@ export interface SubscribeOptions {
     readonly overflow?: SubscriberOverflowPolicy;
 }
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
-export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval";
+export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
+export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
+export type PendingDecisionKind = "tool_approval" | "elicitation";
+/** Redacted match scope for one pending or sticky decision; never contains raw tool arguments. */
+export interface DecisionScope {
+    readonly toolName?: string;
+    readonly effectKind?: ToolEffectKind;
+    /** Redacted principal reference (tenant/kind/id); never a credential. */
+    readonly identity?: string;
+    /** Bounded argument-value constraints; deep-equal matched per key. */
+    readonly actionConstraints?: Readonly<Record<string, JsonValue>>;
+    /** SHA-256 of canonical JSON arguments; present instead of raw arguments. */
+    readonly argumentsHash?: string;
+}
+/** One redacted, unresolved approval request inside a suspended durable run. */
+export interface PendingDecision {
+    /** Unique within the run; nested runs use supervisor-prefixed ids. */
+    readonly approvalId: string;
+    readonly kind: PendingDecisionKind;
+    readonly toolCallId?: string;
+    readonly scope: DecisionScope;
+    /** Bounded, redacted. */
+    readonly reason: string;
+    /** Typed payload contract for elicitation decisions. */
+    readonly elicitationSchema?: JsonObject;
+    /** Delegation chain, root-first; core-written, never client-supplied. */
+    readonly attribution?: {
+        readonly path: readonly string[];
+    };
+}
 /** Redacted safe-boundary descriptor; never contains tool arguments. */
 export interface AgentRunInterruption {
     readonly kind: AgentRunInterruptionKind;
     readonly reason: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** All unresolved approval requests of this suspension; absent for legacy single approvals. */
+    readonly pendingDecisions?: readonly PendingDecision[];
+}
+/** One host decision applied to one pending approval request. */
+export interface RunDecision {
+    readonly approvalId: string;
+    readonly outcome: ApprovalOutcome;
+    /** Bounded to 2 KiB; redacted. */
+    readonly reason?: string;
+    /** Revalidated (schema, guardrails, policy) before dispatch; produces a new arguments hash. */
+    readonly modifiedArguments?: JsonObject;
+    /** Elicitation payload; validated against the pending decision's elicitationSchema. */
+    readonly elicitation?: JsonObject;
+}
+/** Run-scoped sticky decision; exact scope match, rechecked against policy, dropped at run end. */
+export interface StickyDecision {
+    readonly scope: DecisionScope;
+    readonly outcome: "allow_for_run" | "reject_for_run";
+    readonly reason?: string;
+    readonly decidedAt: string;
+    /** Delegation path when the sticky was created for a nested-run decision. */
+    readonly attribution?: {
+        readonly path: readonly string[];
+    };
+}
+/** Root-visible link between one nested approval and the child-run approval id. */
+export interface NestedRunApproval {
+    /** Root-visible approval id (hashed, non-enumerating across runs). */
+    readonly id: string;
+    /** Approval id as the nested run recorded it. */
+    readonly childApprovalId: string;
+}
+/** Root-visible link between a suspended nested run and the tool call that hosted it. */
+export interface NestedRunRef {
+    readonly runId: string;
+    readonly sessionId?: string;
+    readonly toolCallId: string;
+    /** Redacted delegation path (child ids, root first). */
+    readonly path: readonly string[];
+    readonly approvals: readonly NestedRunApproval[];
+    /** Decisions persisted by a partial batch, keyed by root-visible approval id. */
+    readonly decisions?: Readonly<Record<string, RunDecision>>;
+}
+/** Outcome of resuming a nested run through the host-supplied hook. */
+export type NestedRunOutcome = {
+    readonly status: "suspended";
+    readonly pendingDecisions: readonly PendingDecision[];
+} | {
+    readonly status: "completed";
+    readonly value?: JsonValue;
+} | {
+    readonly status: "failed";
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Host hook that resumes a nested run (supervisor child) with child-visible decisions.
+ * Used both when a nested suspension first surfaces (sticky auto-apply) and when root
+ * decisions route back to the child on resume.
+ */
+export type ResumeNestedRun = (nested: {
+    readonly ref: AgentRunRef;
+    readonly toolCallId: string;
+    readonly path: readonly string[];
+}, decisions: readonly RunDecision[]) => Promise<NestedRunOutcome>;
+/**
+ * Thrown by a delegated-run host (e.g. the supervisor) when a nested run suspends on
+ * pending decisions inside a tool execution. Core converts it into a root suspension
+ * with attributed, root-visible approval ids; the dispatching wrapper attaches `toolCall`.
+ */
+export declare class AgentDelegationSuspendedError extends Error {
+    readonly ref: AgentRunRef;
+    readonly pendingDecisions: readonly PendingDecision[];
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    readonly path?: readonly string[] | undefined;
+    readonly code = "ERR_PRISM_DELEGATION_SUSPENDED";
+    toolCall?: ToolCallContent;
+    constructor(ref: AgentRunRef, pendingDecisions: readonly PendingDecision[], 
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    path?: readonly string[] | undefined);
+}
+/** Shared decision-contract violations. Unknown and foreign approval ids share one non-enumerating error. */
+export declare class AgentDecisionError extends Error {
+    readonly code: "ERR_PRISM_DECISION_STALE" | "ERR_PRISM_DECISION_UNKNOWN" | "ERR_PRISM_DECISION_DUPLICATE" | "ERR_PRISM_DECISION_SCOPE" | "ERR_PRISM_DECISION_INVALID" | "ERR_PRISM_DECISION_LIMIT";
+    constructor(code: "ERR_PRISM_DECISION_STALE" | "ERR_PRISM_DECISION_UNKNOWN" | "ERR_PRISM_DECISION_DUPLICATE" | "ERR_PRISM_DECISION_SCOPE" | "ERR_PRISM_DECISION_INVALID" | "ERR_PRISM_DECISION_LIMIT", message: string, options?: {
+        readonly cause?: unknown;
+    });
 }
+export declare const DEFAULT_MAX_PENDING_DECISIONS = 32;
+export declare const HARD_MAX_PENDING_DECISIONS = 128;
+export declare const DEFAULT_MAX_STICKY_DECISIONS = 64;
+export declare const HARD_MAX_STICKY_DECISIONS = 256;
+export declare const MAX_DECISION_REASON_BYTES: number;
+export declare const HARD_MAX_DECISION_REASON_BYTES: number;
+export declare const MAX_ELICITATION_BYTES: number;
+export declare const HARD_MAX_ELICITATION_BYTES: number;
+export declare const MAX_ACTION_CONSTRAINTS = 32;
+export declare const HARD_MAX_ACTION_CONSTRAINTS = 64;
+/** Maximum delegation attribution depth for surfaced nested pending decisions. */
+export declare const MAX_ATTRIBUTION_DEPTH = 8;
+export declare const MAX_ACTION_CONSTRAINT_BYTES: number;
+export declare const HARD_MAX_ACTION_CONSTRAINT_BYTES: number;
 export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
@@ -524,6 +654,8 @@ export interface AgentRunStateOptions {
     readonly interruptBeforeTool?: boolean;
     readonly maxStateBytes?: number;
     readonly fencingToken?: number;
+    /** Enables sticky auto-apply when a nested suspension first surfaces during this run. */
+    readonly resumeNestedRun?: ResumeNestedRun;
 }
 /** Versioned, redacted checkpoint payload. Treat as opaque except status/version/interruption. */
 export interface AgentRunState {
@@ -540,8 +672,11 @@ export interface AgentRunState {
     readonly version?: number;
 }
 export interface AgentRunResume {
-    readonly decision: "approve" | "deny";
     readonly expectedVersion: number;
+    /** Legacy single-approval path; `approve` allows all pending once, `deny` terminates the run denied. */
+    readonly decision?: "approve" | "deny";
+    /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
+    readonly decisions?: readonly RunDecision[];
 }
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
@@ -549,6 +684,8 @@ export interface AgentRunResumeOptions {
     readonly definitionRevision: string;
     readonly ownership?: OwnershipScope;
     readonly fencingToken?: number;
+    /** Routes root decisions for nested-run approvals back to the child (e.g. supervisor). */
+    readonly resumeNestedRun?: ResumeNestedRun;
 }
 /** Bounded, abortable options for `resumeAgentRunStream()`. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
@@ -566,6 +703,13 @@ export declare class AgentRunStateError extends Error {
     readonly code = "ERR_PRISM_AGENT_RUN_STATE";
     constructor(message: string);
 }
+/** Durable-loop contract violations: hook-less custom strategy on a durable run, invalid snapshot, or revision drift. */
+export declare class AgentLoopStateError extends Error {
+    readonly code: "ERR_PRISM_LOOP_NOT_DURABLE" | "ERR_PRISM_LOOP_SNAPSHOT" | "ERR_PRISM_LOOP_REVISION";
+    constructor(code: "ERR_PRISM_LOOP_NOT_DURABLE" | "ERR_PRISM_LOOP_SNAPSHOT" | "ERR_PRISM_LOOP_REVISION", message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
 /** Terminal result of `session.run()` / `session.prompt()`. Failed and aborted runs throw {@link AgentRunError} with this shape attached. */
 export interface AgentRunResult {
     readonly sessionId: string;
@@ -847,6 +991,19 @@ export interface ToolEffectDeclaration {
 }
 /** Runs after argument validation. It must be synchronous, deterministic, bounded, and side-effect-free. */
 export type ToolEffectClassifier = (args: JsonObject, context: ToolExecutionContext) => ToolEffectDeclaration;
+/**
+ * Elicitation contract declared by a tool. When a durable gated run suspends on this tool,
+ * the pending decision has kind `elicitation` and carries this schema as its payload contract;
+ * the resume decision's `elicitation` payload resolves the call without executing it.
+ */
+export interface ToolElicitationRequest {
+    /** Typed payload contract; bounded to HARD_MAX_ELICITATION_BYTES when serialized. */
+    readonly schema: JsonObject;
+    /** Human-facing reason (e.g. the question); bounded to MAX_DECISION_REASON_BYTES. */
+    readonly reason?: string;
+    /** Answer-shape validation beyond structural schema checks; throw to reject the payload. */
+    readonly validate?: (payload: JsonObject) => void;
+}
 export interface ToolDefinition {
     readonly name: string;
     readonly description?: string;
@@ -855,6 +1012,8 @@ export interface ToolDefinition {
     readonly exclusive?: boolean;
     /** Optional side-effect declaration. Omitted tools retain legacy unmanaged dispatch. */
     readonly effect?: ToolEffectDeclaration | ToolEffectClassifier;
+    /** Optional elicitation contract for durable gating; return undefined to fall back to plain tool approval. */
+    readonly elicitation?: (args: JsonObject, context: ToolExecutionContext) => ToolElicitationRequest | undefined;
     execute(args: JsonObject, context: ToolExecutionContext): Promise<ToolResult> | ToolResult;
 }
 export interface ToolRegistry {
@@ -2022,8 +2181,13 @@ export interface LoopContext {
     /** Maximum independent tool calls dispatched concurrently per provider turn. Default `1`. */
     readonly toolConcurrency: number;
     assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;
-    /** Charges a complete tool round before any call in it can start. */
-    chargeToolRound?(calls: readonly ToolCallContent[]): void;
+    /**
+     * Charges a complete tool round before any call in it can start. On durable interrupt
+     * runs this is also the round-level approval gate: it collects every gated call of the
+     * round into one suspension. Loops must await it; dispatch without it falls back to
+     * per-call single-decision suspensions.
+     */
+    chargeToolRound?(calls: readonly ToolCallContent[]): void | Promise<void>;
     generate(request: ProviderRequest): Promise<ProviderTurnResult>;
     dispatchToolCall(call: ToolCallContent): Promise<ToolResult>;
     isToolCallExclusive?(call: ToolCallContent): boolean;
@@ -2033,10 +2197,23 @@ export interface LoopContext {
     hasPendingSteers?(): boolean;
     /** Drain pending steers into history/session. Returns true when any were applied. */
     applyPendingSteers?(): Promise<boolean>;
+    /** Snapshot captured at the last suspension when the strategy declared snapshot/restore. Present only on resume. */
+    readonly restoredLoopState?: JsonValue;
 }
 export interface AgentLoopStrategy {
     readonly name: string;
+    /** Host-authored loop revision. Joins the durable-run fingerprint when snapshot hooks are present. */
+    readonly revision?: string;
     run(ctx: LoopContext): Promise<Usage | undefined>;
+    /**
+     * Capture loop-local resumable state at suspension. Must return a JSON-compatible value;
+     * core bounds and redacts it inside the durable run-state envelope. Declare together with
+     * `restore`; a custom strategy without both hooks is rejected before any provider call on
+     * durable runs (`AgentLoopStateError` / `ERR_PRISM_LOOP_NOT_DURABLE`).
+     */
+    snapshot?(): JsonValue;
+    /** Rehydrate from a previously captured snapshot; must throw on drift. Called before `run` on resume. */
+    restore?(snapshot: JsonValue): void;
 }
 export type AgentLoopOptions = {
     readonly strategy: "single-shot";

package/dist/contracts.js

@@ -1,3 +1,47 @@
+/**
+ * Thrown by a delegated-run host (e.g. the supervisor) when a nested run suspends on
+ * pending decisions inside a tool execution. Core converts it into a root suspension
+ * with attributed, root-visible approval ids; the dispatching wrapper attaches `toolCall`.
+ */
+export class AgentDelegationSuspendedError extends Error {
+    ref;
+    pendingDecisions;
+    path;
+    code = "ERR_PRISM_DELEGATION_SUSPENDED";
+    toolCall;
+    constructor(ref, pendingDecisions, 
+    /** Redacted delegation path (child ids) used when decisions carry no attribution. */
+    path) {
+        super("Delegated run suspended");
+        this.ref = ref;
+        this.pendingDecisions = pendingDecisions;
+        this.path = path;
+        this.name = "AgentDelegationSuspendedError";
+    }
+}
+/** Shared decision-contract violations. Unknown and foreign approval ids share one non-enumerating error. */
+export class AgentDecisionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AgentDecisionError";
+    }
+}
+export const DEFAULT_MAX_PENDING_DECISIONS = 32;
+export const HARD_MAX_PENDING_DECISIONS = 128;
+export const DEFAULT_MAX_STICKY_DECISIONS = 64;
+export const HARD_MAX_STICKY_DECISIONS = 256;
+export const MAX_DECISION_REASON_BYTES = 2 * 1024;
+export const HARD_MAX_DECISION_REASON_BYTES = 8 * 1024;
+export const MAX_ELICITATION_BYTES = 16 * 1024;
+export const HARD_MAX_ELICITATION_BYTES = 64 * 1024;
+export const MAX_ACTION_CONSTRAINTS = 32;
+export const HARD_MAX_ACTION_CONSTRAINTS = 64;
+/** Maximum delegation attribution depth for surfaced nested pending decisions. */
+export const MAX_ATTRIBUTION_DEPTH = 8;
+export const MAX_ACTION_CONSTRAINT_BYTES = 4 * 1024;
+export const HARD_MAX_ACTION_CONSTRAINT_BYTES = 16 * 1024;
 export class AgentRunStateError extends Error {
     code = "ERR_PRISM_AGENT_RUN_STATE";
     constructor(message) {
@@ -5,6 +49,15 @@ export class AgentRunStateError extends Error {
         this.name = "AgentRunStateError";
     }
 }
+/** Durable-loop contract violations: hook-less custom strategy on a durable run, invalid snapshot, or revision drift. */
+export class AgentLoopStateError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AgentLoopStateError";
+    }
+}
 export class AgentRunError extends Error {
     result;
     constructor(result, options) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { resolveAgentDefinition } from "./agent-definitions.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop, } from "./agent-loops.js";
 export type { AgentRunLifecycle, AgentRunLifecycleAgent, AgentRunLifecycleOptions, AgentRunLifecycleRequest, AgentRunLifecycleStreamRequest, } from "./agent-run-lifecycle.js";
 export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
-export type { StoredAgentRunState } from "./agent-run-state.js";
+export type { PendingToolCall, StoredAgentRunState } from "./agent-run-state.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export type { ArtifactApproval, ArtifactApprovalState, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, } from "./artifacts.js";
@@ -20,8 +20,8 @@ export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMe
 export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission, ContextBudgetOmissionKind, ContextBudgetReport, } from "./context-budget.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export type * from "./contracts.js";
-export type { ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, } from "./contracts.js";
-export { AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, ResumeNestedRun, RunDecision, StickyDecision, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, RunLimitCounters, RunLimitName, SecureAgentOptions, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, MAX_ATTRIBUTION_DEPTH, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, HARD_MAX_STICKY_DECISIONS, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
@@ -105,5 +105,5 @@ export type { ToolEffectErrorCode } from "./tool-effects.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.0.24";
+export declare const version = "0.0.25";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -10,7 +10,7 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
-export { AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, MAX_ATTRIBUTION_DEPTH, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, HARD_MAX_STICKY_DECISIONS, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, assertSessionMetadataKey, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
@@ -57,6 +57,6 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.0.24";
+export const version = "0.0.25";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolEffectStore, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolEffectDeclaration, ToolEffectStore, ToolRegistry, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
@@ -57,3 +57,4 @@ export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 export declare function createToolRegistry(tools?: readonly ToolDefinition[], options?: ToolRegistryOptions): ToolRegistry;
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;
+export declare function resolveToolEffectDeclaration(tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext): ToolEffectDeclaration | undefined;

package/dist/tools.js

@@ -153,7 +153,8 @@ export async function dispatchToolCall(options) {
     }
     catch (error) {
         await failBeforeEffect(effect, isSuspended(error) ? "failed_retryable" : "failed_terminal");
-        if (isSuspended(error))
+        // Loop-state contract errors (snapshot capture) are terminal run errors, not tool errors.
+        if (isSuspended(error) || isLoopStateError(error) || isDelegationSuspended(error))
             throw error;
         return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
     }
@@ -222,6 +223,14 @@ export async function dispatchToolCall(options) {
     catch (error) {
         if (completedResult)
             return completedResult;
+        // Nested-run suspensions must propagate to the run loop, never become tool errors.
+        if (isDelegationSuspended(error)) {
+            if (effect && (effect.dispatched || dispatchAttempted))
+                await unknownEffectResult(effect, mediatedCall);
+            else
+                await failBeforeEffect(effect, "failed_retryable");
+            throw error;
+        }
         if (effect && (effect.dispatched || dispatchAttempted))
             return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
         await failBeforeEffect(effect, "failed_terminal");
@@ -298,7 +307,7 @@ async function prepareToolEffect(tool, call, context, options) {
         },
     };
 }
-function resolveToolEffectDeclaration(tool, args, context) {
+export function resolveToolEffectDeclaration(tool, args, context) {
     const classifierContext = Object.freeze({
         sessionId: context.sessionId,
         runId: context.runId,
@@ -389,6 +398,12 @@ function effectErrorResult(call, code, message) {
 function isSuspended(error) {
     return error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED";
 }
+function isLoopStateError(error) {
+    return typeof error?.code === "string" && error.code.startsWith("ERR_PRISM_LOOP_");
+}
+function isDelegationSuspended(error) {
+    return error?.code === "ERR_PRISM_DELEGATION_SUSPENDED";
+}
 async function checkCall(call, options, startedAt) {
     const context = options.context;
     const tool = options.registry.get(call.name);

package/docs/0.1.0-readiness.md

@@ -1,12 +1,12 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.0.24** is the current release line (Phase 7 distributed events and recoverable tool effects); **1.0** readiness remains operator-gated, not automatic.
+Status: **0.0.25** is the current release line (Phase 8 durable custom loops and human-in-the-loop); **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table. The
 **Last evidence** column records the 2026-07-26 **0.0.16** baseline snapshot
 (Phase 11, Node v24.18.0, Linux x86_64). Treat it as historical floor evidence,
 not the current release tag. Re-run each gate on the target release tree before
-cutting 0.0.24 / 1.0. The decision to cut 1.0 stays with the operator after
+cutting 0.0.25 / 1.0. The decision to cut 1.0 stays with the operator after
 operator-gated legs run in a protected environment and Phase 12 demand evidence
 exists.
 
@@ -14,15 +14,16 @@ Evidence trail: [`docs/review-coverage-2026-07-26-phase-11.md`](./review-coverag
 (addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
 [`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md).
 
-## Current line (0.0.24)
+## Current line (0.0.25)
 
 | Item | Status |
 |---|---|
-| Published graph | **47** publishable manifests at **0.0.24** (`docs/release-and-install.md`) |
-| Phase 7 distributed events/effects | `AgentEventSource`, `ToolEffectStore`, AG-UI MCP/A2A fronting; enterprise `toolEffects`; schema v6/v7 + enterprise migration 002 |
-| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.23 → 0.0.24 distributed events and recoverable tool effects` |
-| Protected database evidence | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; `benchmark-0.0.24.json` under Task 0 ceilings |
-| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.24 database evidence is recorded separately |
+| Published graph | **47** publishable manifests at **0.0.25** (`docs/release-and-install.md`) |
+| Phase 8 durable loops / HITL | Custom-loop snapshot/restore, shared pending decisions, nested attributions, A2UI + standard AG-UI projectors |
+| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.24 → 0.0.25 durable custom loops and human-in-the-loop` |
+| Network-free Phase 8 evidence | `scripts/phase8-conformance.test.mjs`; `benchmark-0.0.25.json` under Task 0 ceilings |
+| Protected database evidence (Phase 7) | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; `benchmark-0.0.24.json` under prior ceilings |
+| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.25 loop/HITL evidence is recorded separately |
 
 ## Gate table
 

package/docs/ag-ui-adoption.md

@@ -7,7 +7,7 @@ This page records Prism's compatibility review against official AG-UI `@ag-ui/co
 Official material reviewed:
 
 - [Events](https://docs.ag-ui.com/concepts/events), [messages](https://docs.ag-ui.com/concepts/messages), [tools](https://docs.ag-ui.com/concepts/tools), [state](https://docs.ag-ui.com/concepts/state), [reasoning](https://docs.ag-ui.com/concepts/reasoning), [interrupts](https://docs.ag-ui.com/concepts/interrupts), [capabilities](https://docs.ag-ui.com/concepts/capabilities), [serialization](https://docs.ag-ui.com/concepts/serialization), [server quickstart](https://docs.ag-ui.com/quickstart/server), and [protocol architecture](https://docs.ag-ui.com/concepts/architecture).
-- Official [MCP/A2A/AG-UI relationship](https://docs.ag-ui.com/agentic-protocols), [integrations](https://docs.ag-ui.com/integrations), [`@ag-ui/mcp-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-middleware), [`@ag-ui/mcp-apps-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-apps-middleware), [`@ag-ui/a2a`](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/a2a/typescript), and [`@ag-ui/a2a-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2a-middleware).
+- Official [MCP/A2A/AG-UI relationship](https://docs.ag-ui.com/agentic-protocols), [integrations](https://docs.ag-ui.com/integrations), [`@ag-ui/mcp-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-middleware), [`@ag-ui/mcp-apps-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-apps-middleware), [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware) (Prism ships an in-package opt-in painter with frozen caps; no runtime dependency), [`@ag-ui/a2a`](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/a2a/typescript), and [`@ag-ui/a2a-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2a-middleware).
 - A2A [current specification](https://a2a-protocol.org/latest/specification/) and [streaming rules](https://a2a-protocol.org/latest/topics/streaming-and-async/).
 - MCP Apps [SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) and the [`io.modelcontextprotocol/ui` draft specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx).
 

package/docs/ag-ui.md

@@ -35,7 +35,8 @@ npm install @arnilo/prism @arnilo/prism-ag-ui
 | `lifecycle` + `resolveRun` | Optional durable status/resume path. Required only for a resumed interruption. |
 | `interrupts.resume` | Optional host aggregate-policy callback for multiple AG-UI interrupts; it returns one current-version core approve/deny decision. |
 | `replay` | Optional page adapter or `createAgentEventSourceAgUiReplay(source, options)` for gap-free distributed replay/live follow. |
-| `projection` | Explicit safe tool/state/messages/activity/reasoning/raw/custom/interrupt projection. Omit each callback for default deny. |
+| `projection` | Explicit safe tool/state/messages/activity/reasoning/raw/custom/interrupt projection. Omit each callback for default deny. Prefer `composeAgUiProjections(createMessagesFromSessionProjection(...), createStateFromStoreProjection(...), createActivityFromToolProgressProjection(), host)` for standard families. |
+| `a2ui` | Opt-in A2UI painting middleware (`{ catalogId, mode, renderToolName?, allowedCatalogIds?, limits? }`). Detects `a2ui_operations` tool results and/or streams from `render_a2ui` args; paints `a2ui-surface` activity events. Absent = inert. |
 | `capabilities` | Optional host declaration narrowed to implemented SSE/projector/lifecycle features; read `handler.capabilities`. |
 | `redactor`, `limits` | Host redaction and narrowing-only finite caps. |
 
@@ -105,6 +106,43 @@ All identity, authorization, session/thread mapping, durable checkpoint lookup,
 
 Co-work projection reuses the same allow-list: `AgUiProjection.coWork(event)` may return a curated, JSON-serializable payload for a co-work event; absent it, the redacted event fields are exposed. Wire `coWorkContext` to derive thread/artifact/identity from the authorized request (never client JSON) and `coWork` to a `createCoWorkReplay()` over your durable artifact/draft/snapshot stores. The handler projects one bounded page after the run; mount a dedicated cursor-paged co-work endpoint when full pagination is needed.
 
+Durable interrupts carry the shared decision batch: the fallback interrupt includes the redacted `pendingDecisions` under `metadata` and its `responseSchema` accepts either the legacy `{ decision: "approve" | "deny" }` or a `{ decisions: [{ approvalId, outcome, reason?, modifiedArguments?, elicitation? }] }` batch. All batch entries are shape- and cap-validated at the boundary (count ≤ 128, ids ≤ 128 chars, four outcomes, reason ≤ 8 KiB, payloads ≤ 64 KiB) and core re-validates each against the recorded pending set under the single CAS. `interrupts.resume` may return the batch form (`{ decisions, expectedVersion? }`); legacy `editedArgs` resume payloads still deny. ACP permission prompts offer the four outcomes (`allow_once` / `allow_always` / `reject_once` / `reject_always`) and map them onto the batch; a cancelled prompt stays deny-closed.
+
+### Standard projectors (opt-in)
+
+Three batteries-included factories return `AgUiProjection` fragments. Compose with host projectors via `composeAgUiProjections(...fragments)` — **first defined callback wins** (left to right); `undefined` fragments are skipped. Absent factories keep 0.0.24 default-deny.
+
+```ts
+createAgUiHandler({
+  projection: composeAgUiProjections(
+    createMessagesFromSessionProjection({ getMessages: () => authorizedAgUiMessages, redact }),
+    createStateFromStoreProjection(runStateStore),
+    createActivityFromToolProgressProjection(),
+    hostCustom,
+  ),
+});
+```
+
+| Factory | Emits | Notes |
+| --- | --- | --- |
+| `createMessagesFromSessionProjection` | `MESSAGES_SNAPSHOT` | Host `getMessages()` for authorized history, or live `message_finished` accumulation. Caps 128/1024. Redact drops closed. |
+| `createStateFromStoreProjection(store)` | `STATE_SNAPSHOT` on `agent_started`; RFC 6902 `STATE_DELTA` (add/replace/remove) when `store.get()` changes | Host store; optional `subscribe` only marks dirty — no Prism watcher. Oversized/throw → drop closed. |
+| `createActivityFromToolProgressProjection` | `ACTIVITY_SNAPSHOT` / `ACTIVITY_DELTA` from `tool_execution_progress` | Default `activityType: "tool-progress"`. Missing progress+metadata → drop closed. |
+
+### A2UI painting middleware (opt-in)
+
+`createAgUiHandler({ a2ui: { catalogId, mode } })` paints A2UI v0.9 surfaces without a host `projection.activity` callback:
+
+| Mode | Source | Paint |
+| --- | --- | --- |
+| `fixed-schema` | Tool result `{ a2ui_operations: [...] }` | First batch with `createSurface` → `ACTIVITY_SNAPSHOT` (`activityType: "a2ui-surface"`); later batches → `ACTIVITY_DELTA` |
+| `streaming` | `tool_call_delta` args of `renderToolName` (default `render_a2ui`) | Progressive `ACTIVITY_SNAPSHOT` with `replace: true` only when complete ops extractable — never partial JSON |
+| `both` | Both paths; streamed surfaces are not re-painted from the final envelope |
+
+Host `catalogId` is stamped when absent; model-supplied ids outside `allowedCatalogIds` (default `[catalogId]`) are overwritten. Invalid ops emit one bounded `CUSTOM` event `prism.a2ui.error` and paint nothing. Caps: 64/512 ops per message, 64 KiB/1 MiB per op, 16/64 surfaces per run, depth 32/64.
+
+User actions arrive as untrusted `AgUiA2UiAction` values on `input.project({ a2uiActions })` (from `forwardedProps.a2uiAction` or activity/tool-result shapes). Without `input.project` they stay default-deny — Prism never synthesizes a `log_a2ui_event` tool call (documented divergence from official `@ag-ui/a2ui-middleware`). Example: `examples/ag-ui-a2ui.ts`.
+
 ## Security and performance notes
 
 Authorize every start/replay/resume/proxy/follow. Treat protocol fields, MCP metadata/HTML, and A2A cards/parts as untrusted; persist run/task correlation before output and redact streams. MCP Apps requires extension acknowledgement, exact proxy origin, same-bridge visibility, approval, `ui://` HTML/MIME bounds, and sandbox CSP. It never retries UI mutations; Task 4 adds recovery.

package/docs/agent-loops.md

@@ -118,7 +118,15 @@ Optional steer hooks on `LoopContext` (0.0.11): `hasPendingSteers?()` / `applyPe
 
 ## 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()`.
+`RunOptions.runState` supports the built-in loop options (`single-shot` and `generate-validate-revise`) and custom strategies that opt into durable state. `single-shot` is durable via the runtime's pending-call mechanism and carries no loop-local state. `generate-validate-revise` snapshots `{ attempts, artifactPhase, savedSchema, pendingHistory }` at `revision: "1"`. A custom `AgentLoopStrategy` must declare both snapshot hooks or durable configuration rejects it with `AgentLoopStateError` (`ERR_PRISM_LOOP_NOT_DURABLE`) before any provider call:
+
+| Member | Purpose |
+| --- | --- |
+| `revision?: string` | Host-authored loop revision. Joins the durable-run fingerprint, so a loop change without a `definitionRevision` bump fails closed on resume. |
+| `snapshot?(): JsonValue` | Capture loop-local resumable state at suspension. Must be JSON-compatible; core redacts it and bounds it inside the durable run-state envelope (`maxStateBytes`, depth 32). A non-JSON value fails the run with `ERR_PRISM_LOOP_SNAPSHOT`. |
+| `restore?(snapshot): void` | Rehydrate from the captured snapshot; must throw on drift. Called once before `run(ctx)` on resume. Also available as `ctx.restoredLoopState`. |
+
+The snapshot is stored as `loopState: { name, revision, snapshot }` on the durable run state and cleared when the run reaches a terminal status. On resume, a name/revision mismatch between the stored `loopState` and the resolved strategy fails closed (`ERR_PRISM_LOOP_REVISION`), and the fingerprint check independently rejects any loop drift. 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
 

package/docs/agent-session-runtime.md

@@ -176,7 +176,14 @@ await agent.createSession().run("Hi", { model: overrideModel });
 
 ## 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.
+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. When a provider turn requests several tools, the round is collected into **one** suspension whose `interruption.pendingDecisions` holds one redacted `PendingDecision` per gated call (`approvalId`, kind, scope with tool name/effect kind/identity/arguments hash — never raw arguments); ungated calls still dispatch.
+
+`resumeAgentRun` accepts exactly one of:
+
+- `decision: "approve" | "deny"` — legacy single-approval path. `approve` allows every pending decision once; `deny` terminates the run as `denied`.
+- `decisions: readonly RunDecision[]` — one atomic batch. Every entry validates against the recorded pending set (unknown/foreign `approvalId`, duplicates, stale `expectedVersion`, invalid outcomes fail the whole batch closed with `AgentDecisionError` and leave state and version untouched). Outcomes: `allow_once`, `allow_for_run`, `reject_once`, `reject_for_run`. `reject_*` continues the run with a blocked tool result carrying the bounded (2 KB) `reason`. `modifiedArguments` are revalidated (schema, then input guardrails; permission/trust re-run at dispatch) and produce a new arguments hash. `elicitation` payloads are validated against the pending decision's `elicitationSchema` (required keys plus the configured host validator) and resolve the suspended call without executing it. A batch deciding a strict subset persists the decided entries and re-suspends with the remainder pending at the bumped version.
+
+`*_for_run` outcomes append a `StickyDecision` to the durable run state: later calls in the same run matching the scope exactly (all recorded fields) proceed or are blocked without a new suspension, policy still enforced at dispatch. Sticky decisions expire when the run reaches any terminal status. Caps: 32 pending decisions per run (hard 128), 64 sticky decisions (hard 256), 2 KB decision reasons, 16 KB elicitation payloads.
 
 ```ts
 const result = await session.run("Publish draft", {
@@ -189,7 +196,7 @@ if (result.status === "suspended") {
 }
 ```
 
-Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. The fingerprint hashes the agent id/name, `definitionRevision`, model, instructions, system-prompt contributions, skills (name/instructions/tool names), tool definitions (name/parameters/exclusive), guardrail definitions (name/stage/revision), and loop strategy — changing any of them without bumping `definitionRevision` fails resume closed instead of silently continuing with different agent semantics. 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. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. 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. State is bounded at save by `runState.maxStateBytes` (default 256 KB, at most the 1 MB hard cap); load bounds against the 1 MB hard cap only, so state saved with a raised limit stays resumable while oversized records are still rejected. Only built-in loop options are durable; custom `AgentLoopStrategy` rejects before provider work.
+Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. The fingerprint hashes the agent id/name, `definitionRevision`, model, instructions, system-prompt contributions, skills (name/instructions/tool names), tool definitions (name/parameters/exclusive), guardrail definitions (name/stage/revision), and loop strategy — changing any of them without bumping `definitionRevision` fails resume closed instead of silently continuing with different agent semantics. 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. `resumeStream()` uses that same claim path and bounded subscriber, so adapters do not poll or duplicate resume logic. 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. State is bounded at save by `runState.maxStateBytes` (default 256 KB, at most the 1 MB hard cap); load bounds against the 1 MB hard cap only, so state saved with a raised limit stays resumable while oversized records are still rejected. Built-in loop options are durable; custom `AgentLoopStrategy` instances are durable when they declare `snapshot`/`restore` hooks (see [Agent loops § Durable runs](agent-loops.md#durable-runs)) and reject before provider work otherwise.
 
 ## Secure composition
 

package/docs/coding-security.md

@@ -143,7 +143,7 @@ Policies are ordinary host values: attach one globally through `createCodingTool
 
 The Docker reference adapter starts by recorded container ID/label, uses argument arrays only, mounts source read-only, populates a size-bounded tmpfs `/workspace`, drops all capabilities, enables `no-new-privileges`, runs with `--init`, and never exposes the Docker socket, privileged mode, or host PID/IPC namespaces. Image pull/build/update stays outside Prism. Protected real-Docker checks are opt-in via `PRISM_TEST_DOCKER_SANDBOX=1` with host-supplied `PRISM_TEST_DOCKER_BIN` and digest-pinned `PRISM_TEST_DOCKER_IMAGE`.
 
-Callback approval remains process-local. For approval that must survive restart, wrap the action in an opted-in workflow `toolNode({ approval: { reason, data?, resumeSchema? } })`. The workflow persists `suspended` state before any tool side effect. After explicit approve, it recomputes the action and invokes this package's current `ExecutionPolicy`; durable approval never populates or bypasses the process-local approval cache. Adapters should emit chunks through `request.onData` as they arrive and honor `request.signal`/`request.timeout`; buffering is unnecessary. Coding-agent composes caller abort with its total-output controller, so ignoring the supplied signal defeats process termination even though Prism stops retaining output at the cap. Default caching is `none`; use run-scoped caching only when repeated approval within one run is desired, and session scope only when that wider lifecycle is intentional.
+Callback approval remains process-local. For approval that must survive restart, wrap the action in an opted-in workflow `toolNode({ approval: { reason, data?, resumeSchema? } })`. `ask_user_decision` also maps onto the shared decision model: inside a durable gated agent run its call suspends as a kind-`elicitation` pending decision whose schema carries the choice contract (option-id enums) plus the full question/options UX payload on a Prism-owned schema extension property; the resume decision's `elicitation` payload (a `selectedId`/`selectedIds`/`customText` answer) is validated against the schema and the tool-level answer-shape rules, then resolves the call without invoking the blocking `ask()` callback. The process-local `ask()` path and the workflow suspend/resume path are unchanged. The workflow persists `suspended` state before any tool side effect. After explicit approve, it recomputes the action and invokes this package's current `ExecutionPolicy`; durable approval never populates or bypasses the process-local approval cache. Adapters should emit chunks through `request.onData` as they arrive and honor `request.signal`/`request.timeout`; buffering is unnecessary. Coding-agent composes caller abort with its total-output controller, so ignoring the supplied signal defeats process termination even though Prism stops retaining output at the cap. Default caching is `none`; use run-scoped caching only when repeated approval within one run is desired, and session scope only when that wider lifecycle is intentional.
 
 ## Security and performance notes