@arnilo/prism 0.0.96 → 0.1.1

package/dist/agents.js

@@ -1,22 +1,27 @@
-import { AgentRunError, AgentRunStateError } from "./contracts.js";
-import { resolveLoop, resolveToolConcurrency } from "./agent-loops.js";
-import { createId } from "./ids.js";
-import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "./guardrails.js";
-import { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
+import { createHash } from "node:crypto";
+import { resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
+import { agentFingerprint, boundedLoopSnapshot, initialAgentRunState, loadAgentRunState, publicState, saveAgentRunState, validateRunStateOptions, } from "./agent-run-state.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
+import { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, MAX_ATTRIBUTION_DEPTH, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_STICKY_DECISIONS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, } from "./contracts.js";
+import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "./guardrails.js";
+import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "./identity.js";
+import { createId } from "./ids.js";
 import { assembleProviderInput } from "./input.js";
+import { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
 import { providerToolCallDeltaContent, reconstructToolCallDeltas } from "./provider-events.js";
 import { createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult } from "./provider-request-policy.js";
-import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "./structured-output.js";
-import { errorToErrorInfo, redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "./redaction.js";
-import { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
+import { errorToErrorInfo, redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry, } from "./redaction.js";
 import { createDefaultRetryPolicy, waitForRetry } from "./retry.js";
-import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext } from "./session-stores.js";
 import { isFlushableRunLedger } from "./run-ledger.js";
-import { createToolRegistry, dispatchToolCall } from "./tools.js";
 import { RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.js";
-import { agentFingerprint, initialAgentRunState, loadAgentRunState, publicState, saveAgentRunState, validateRunStateOptions } from "./agent-run-state.js";
+import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext, } from "./session-stores.js";
 import { resolveActiveSkills } from "./skills.js";
+import { createLoadedSkillSet, resolveSkillsDisclosure } from "./skill-disclosure.js";
+import { resolveToolResultFold } from "./tool-result-fold.js";
+import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "./structured-output.js";
+import { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
+import { createToolRegistry, dispatchToolCall, resolveToolEffectDeclaration } from "./tools.js";
+import { canonicalToolEffectJson, toolEffectArgumentsHash } from "./tool-effects.js";
 export function createAgent(config) {
     return {
         config,
@@ -30,46 +35,411 @@ export function createAgentSession(config) {
 }
 /** Resume a persisted built-in run. A claimed/dispatched tool is never replayed automatically. */
 export async function resumeAgentRun(agent, ref, resume, options) {
+    return executePreparedAgentRunResume(await prepareAgentRunResume(agent, ref, resume, options));
+}
+/** Subscribe before resuming one durable run. Early consumer return aborts that resumed execution. */
+export async function* resumeAgentRunStream(agent, ref, resume, options) {
+    throwIfAbortedSignal(options.signal);
+    const prepared = await prepareAgentRunResume(agent, ref, resume, options, options.signal);
+    const subscription = prepared.session.subscribe(options);
+    let settled = false;
+    const runPromise = executePreparedAgentRunResume(prepared, options.signal).finally(() => {
+        settled = true;
+    });
+    try {
+        for await (const event of subscription) {
+            if ("runId" in event && event.runId !== ref.runId)
+                continue;
+            yield event;
+        }
+        await runPromise;
+    }
+    finally {
+        if (!settled) {
+            prepared.session.abort(new Error("resume stream consumer closed"));
+            await runPromise.catch(() => undefined);
+        }
+    }
+}
+async function prepareAgentRunResume(agent, ref, resume, options, signal) {
+    throwIfAbortedSignal(signal);
     const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
-    if (state.definitionRevision !== options.definitionRevision || state.agentId !== (agent.config.id ?? agent.config.name) || state.fingerprint !== agentFingerprint(agent, options.definitionRevision)) {
+    if (state.definitionRevision !== options.definitionRevision ||
+        state.agentId !== (agent.config.id ?? agent.config.name) ||
+        state.fingerprint !== agentFingerprint(agent, options.definitionRevision)) {
         throw new AgentRunStateError("Agent definition revision or fingerprint mismatch on resume");
     }
     if (record.version !== resume.expectedVersion || state.status !== "suspended") {
         throw new AgentRunStateError("Stale or non-suspended agent run resume");
     }
+    const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
+    if (resume.decision !== undefined && resume.decisions !== undefined) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume accepts exactly one of decision or decisions");
+    }
+    const pendingDecisions = pendingDecisionsOf(state);
+    // Legacy approve maps to allow-once on every pending decision; legacy deny keeps its
+    // terminal-denied behavior. Batch decisions are validated and applied atomically below.
+    const resolved = resume.decisions !== undefined
+        ? await resolveRunDecisions({ agent, state, decisions: resume.decisions, signal })
+        : resume.decision === "approve" && pendingDecisions
+            ? await resolveRunDecisions({
+                agent,
+                state,
+                decisions: pendingDecisions.map((pending) => ({ approvalId: pending.approvalId, outcome: "allow_once" })),
+                signal,
+            })
+            : undefined;
+    if (resume.decision === undefined && resume.decisions === undefined) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Resume requires a decision or decisions");
+    }
+    if (resolved && resolved.remaining.length > 0) {
+        throwIfAbortedSignal(signal);
+        const single = resolved.remaining.length === 1 ? resolved.remaining[0] : undefined;
+        const interruption = {
+            kind: state.interruption?.kind ?? "tool_approval",
+            reason: `${resolved.remaining.length} approval request(s) remain`,
+            ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
+            ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
+            pendingDecisions: resolved.remaining,
+        };
+        const resuspended = await saveAgentRunState({
+            checkpoints: options.checkpoints,
+            state: {
+                ...state,
+                status: "suspended",
+                interruption,
+                pending: undefined,
+                // Decided approvals persist on their entries so a partial batch never loses them;
+                // they dispatch (or synthesize their result) when the run finally resumes.
+                pendingCalls: state.pendingCalls?.map((entry) => {
+                    const decision = resolved.decisionsById.get(entry.approvalId);
+                    return decision ? { ...entry, decision } : entry;
+                }),
+                // Decided nested approvals persist on their nested-run entries, keyed by
+                // root-visible approval id, so a partial batch never loses them either.
+                nestedRuns: state.nestedRuns?.map((entry) => {
+                    const decided = entry.approvals.filter((approval) => resolved.decisionsById.has(approval.id));
+                    if (decided.length === 0)
+                        return entry;
+                    return {
+                        ...entry,
+                        decisions: {
+                            ...entry.decisions,
+                            ...Object.fromEntries(decided.map((approval) => [approval.id, resolved.decisionsById.get(approval.id)])),
+                        },
+                    };
+                }),
+                stickyDecisions: resolved.stickyDecisions,
+            },
+            expectedVersion: record.version,
+            ownership: options.ownership,
+            fencingToken: options.fencingToken,
+        });
+        return {
+            kind: "resuspend",
+            session,
+            interruption,
+            version: resuspended.record.version,
+            ownership: options.ownership,
+            result: {
+                sessionId: state.sessionId,
+                runId: state.runId,
+                status: "suspended",
+                leafId: state.leafId,
+                text: "",
+                content: [],
+                runState: publicState(resuspended.state),
+                interruption,
+            },
+        };
+    }
     if (resume.decision === "deny") {
+        throwIfAbortedSignal(signal);
         const denied = await saveAgentRunState({
             checkpoints: options.checkpoints,
-            state: { ...state, status: "denied" },
+            state: {
+                ...state,
+                status: "denied",
+                loopState: undefined,
+                pendingCalls: undefined,
+                nestedRuns: undefined,
+                stickyDecisions: undefined,
+            },
             expectedVersion: record.version,
             ownership: options.ownership,
             fencingToken: options.fencingToken,
         });
-        const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
-        await session.recordDurableDenial(state.runId, state.interruption, denied.record.version, options.ownership);
-        const runState = publicState(denied.state);
-        return { sessionId: state.sessionId, runId: state.runId, status: "denied", leafId: state.leafId, text: "", content: [], runState, interruption: state.interruption };
+        return {
+            kind: "deny",
+            session,
+            interruption: state.interruption,
+            version: denied.record.version,
+            ownership: options.ownership,
+            result: {
+                sessionId: state.sessionId,
+                runId: state.runId,
+                status: "denied",
+                leafId: state.leafId,
+                text: "",
+                content: [],
+                runState: publicState(denied.state),
+                interruption: state.interruption,
+            },
+        };
     }
-    if (state.pending?.status === "dispatched")
+    if (state.pending?.status === "dispatched" || state.pendingCalls?.some((entry) => entry.status === "dispatched")) {
         throw new AgentRunStateError("Ambiguous dispatched tool requires operator resolution");
+    }
     const configured = agent.config.runState;
     if (configured && (configured.checkpoints !== options.checkpoints || configured.definitionRevision !== options.definitionRevision)) {
         throw new AgentRunStateError("Agent durable run-state configuration mismatch on resume");
     }
+    throwIfAbortedSignal(signal);
     const claimed = await saveAgentRunState({
         checkpoints: options.checkpoints,
-        state: { ...state, status: "running", interruption: undefined },
+        state: {
+            ...state,
+            status: "running",
+            interruption: undefined,
+            stickyDecisions: resolved?.stickyDecisions ?? state.stickyDecisions,
+        },
         expectedVersion: record.version,
         ownership: options.ownership,
         fencingToken: options.fencingToken,
     });
-    const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
-    return session.resumeDurable(claimed.state, configured ?? {
-        checkpoints: options.checkpoints,
-        definitionRevision: options.definitionRevision,
-        interruptBeforeTool: state.interruptBeforeTool,
-        fencingToken: options.fencingToken,
-    }, options.ownership);
+    return {
+        kind: "approve",
+        session,
+        state: claimed.state,
+        decisions: resolved?.decisionsById,
+        ownership: options.ownership,
+        runState: configured ?? {
+            checkpoints: options.checkpoints,
+            definitionRevision: options.definitionRevision,
+            interruptBeforeTool: state.interruptBeforeTool,
+            fencingToken: options.fencingToken,
+            resumeNestedRun: options.resumeNestedRun,
+        },
+    };
+}
+/** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
+function pendingDecisionsOf(state) {
+    if (state.interruption?.pendingDecisions)
+        return state.interruption.pendingDecisions;
+    if (state.pending) {
+        return [
+            {
+                approvalId: state.pending.call.id,
+                kind: "tool_approval",
+                toolCallId: state.pending.call.id,
+                scope: { toolName: state.pending.call.name },
+                reason: state.interruption?.reason ?? "Tool side effect requires approval",
+            },
+        ];
+    }
+    return undefined;
+}
+/**
+ * Validate one decision batch against the suspended state. Fail-closed and atomic: any
+ * invalid entry rejects the whole batch before any CAS, leaving state and version untouched.
+ * Unknown and foreign approval ids share one non-enumerating error.
+ */
+async function resolveRunDecisions(input) {
+    const { agent, state, decisions } = input;
+    if (decisions.length === 0)
+        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Decision batch must not be empty");
+    if (decisions.length > HARD_MAX_PENDING_DECISIONS) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision batch exceeds ${HARD_MAX_PENDING_DECISIONS} entries`);
+    }
+    const pending = pendingDecisionsOf(state);
+    if (!pending?.length)
+        throw new AgentDecisionError("ERR_PRISM_DECISION_UNKNOWN", "No pending approval decisions for this run");
+    const byId = new Map(pending.map((entry) => [entry.approvalId, entry]));
+    const seen = new Set();
+    const decisionsById = new Map();
+    const stickies = [];
+    const decidedAt = new Date().toISOString();
+    const { registry } = activeTools(agent.config.tools);
+    for (const decision of decisions) {
+        if (seen.has(decision.approvalId)) {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_DUPLICATE", "Duplicate approval decision in batch");
+        }
+        seen.add(decision.approvalId);
+        const target = byId.get(decision.approvalId);
+        if (!target)
+            throw new AgentDecisionError("ERR_PRISM_DECISION_UNKNOWN", "Unknown approval decision");
+        if (decision.reason !== undefined && Buffer.byteLength(decision.reason, "utf8") > MAX_DECISION_REASON_BYTES) {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Decision reason exceeds ${MAX_DECISION_REASON_BYTES} bytes`);
+        }
+        if (decision.outcome !== "allow_once" &&
+            decision.outcome !== "allow_for_run" &&
+            decision.outcome !== "reject_once" &&
+            decision.outcome !== "reject_for_run") {
+            throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Unknown approval outcome");
+        }
+        if (decision.modifiedArguments !== undefined) {
+            if (target.kind !== "tool_approval" || !target.toolCallId) {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_SCOPE", "Modified arguments apply only to tool approvals");
+            }
+            await validateModifiedArguments(agent, registry, state, target, decision.modifiedArguments, input.signal);
+        }
+        if (decision.elicitation !== undefined) {
+            if (target.kind !== "elicitation") {
+                throw new AgentDecisionError("ERR_PRISM_DECISION_SCOPE", "Elicitation payload applies only to elicitation decisions");
+            }
+            await validateElicitationPayload(agent, state, target, decision.elicitation, input.signal);
+        }
+        decisionsById.set(decision.approvalId, decision);
+        if (decision.outcome === "allow_for_run" || decision.outcome === "reject_for_run") {
+            stickies.push({
+                // A decision with modified arguments must not stick to the original arguments hash:
+                // the modification is one-off, so the sticky scope matches by name/effect/identity only.
+                scope: decision.modifiedArguments !== undefined ? { ...target.scope, argumentsHash: undefined } : target.scope,
+                outcome: decision.outcome,
+                ...(decision.reason !== undefined ? { reason: decision.reason } : {}),
+                // Root-owned sticky scope includes the delegation path for nested decisions.
+                ...(target.attribution ? { attribution: target.attribution } : {}),
+                decidedAt,
+            });
+        }
+    }
+    const stickyDecisions = [...(state.stickyDecisions ?? []), ...stickies];
+    if (stickyDecisions.length > DEFAULT_MAX_STICKY_DECISIONS) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Sticky decisions exceed ${DEFAULT_MAX_STICKY_DECISIONS} per run`);
+    }
+    return {
+        decisionsById,
+        stickyDecisions,
+        remaining: pending.filter((entry) => !seen.has(entry.approvalId)),
+    };
+}
+/** Decision-time revalidation of modified arguments: schema, then input guardrails. Policy and trust re-run at dispatch. */
+async function validateModifiedArguments(agent, registry, state, target, modified, signal) {
+    const invalid = (message, cause) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message, { cause });
+    if (JSON.stringify(modified) === undefined || Buffer.byteLength(JSON.stringify(modified), "utf8") > MAX_ELICITATION_BYTES) {
+        throw invalid("Modified arguments must be a bounded JSON object");
+    }
+    const call = state.pendingCalls?.find((entry) => entry.approvalId === target.approvalId)?.call ??
+        (state.pending && state.pending.call.id === target.toolCallId ? state.pending.call : undefined);
+    const toolName = target.scope.toolName ?? call?.name ?? "";
+    const tool = registry.get(toolName);
+    const context = { sessionId: state.sessionId, runId: state.runId, toolCallId: target.toolCallId ?? "", signal };
+    if (agent.config.validator && tool) {
+        const validation = await agent.config.validator(tool, modified, context);
+        if (validation)
+            throw invalid("Modified arguments failed schema validation");
+    }
+    const value = call
+        ? { ...call, arguments: modified }
+        : { type: "tool_call", id: target.toolCallId ?? "", name: toolName, arguments: modified };
+    const guarded = await runGuardrails({
+        stage: "tool_input",
+        guardrails: agent.config.guardrails,
+        value,
+        context: {
+            sessionId: state.sessionId,
+            runId: state.runId,
+            toolCallId: target.toolCallId,
+            toolName,
+            metadata: {},
+            signal,
+        },
+        redactor: agent.config.redactor,
+    });
+    if (guarded.terminal)
+        throw invalid("Modified arguments blocked by guardrail");
+}
+/**
+ * Resolve a tool's declared elicitation contract for a gated call. A throwing hook falls back to
+ * plain tool approval: malformed model args then surface as a tool error after approval, never
+ * as a run failure at the gate. Output is bounded before it enters the pending-decision record.
+ */
+function toolElicitationRequest(tool, args, context) {
+    if (!tool?.elicitation)
+        return undefined;
+    let request;
+    try {
+        request = tool.elicitation(args, context);
+    }
+    catch {
+        return undefined;
+    }
+    if (!request)
+        return undefined;
+    const schemaText = JSON.stringify(request.schema);
+    if (schemaText === undefined || Buffer.byteLength(schemaText, "utf8") > HARD_MAX_ELICITATION_BYTES)
+        return undefined;
+    const reason = request.reason;
+    if (reason !== undefined && Buffer.byteLength(reason, "utf8") > MAX_DECISION_REASON_BYTES)
+        return { schema: request.schema };
+    return { schema: request.schema, ...(reason !== undefined ? { reason } : {}) };
+}
+/** Elicitation payload check: bounded JSON object, schema-required keys, host validator when configured. */
+async function validateElicitationPayload(agent, state, target, payload, signal) {
+    const invalid = (message) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message);
+    const text = JSON.stringify(payload);
+    if (text === undefined || Buffer.byteLength(text, "utf8") > MAX_ELICITATION_BYTES) {
+        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Elicitation payload exceeds ${MAX_ELICITATION_BYTES} bytes`);
+    }
+    const schema = target.elicitationSchema;
+    if (schema) {
+        const required = schema.required;
+        if (Array.isArray(required)) {
+            for (const key of required) {
+                if (typeof key === "string" && !Object.hasOwn(payload, key))
+                    throw invalid(`Elicitation payload missing required key ${key}`);
+            }
+        }
+        if (agent.config.validator) {
+            const tool = {
+                name: target.scope.toolName ?? "elicitation",
+                parameters: schema,
+                execute: () => ({ toolCallId: "", name: "elicitation" }),
+            };
+            const context = { sessionId: state.sessionId, runId: state.runId, toolCallId: target.toolCallId ?? "elicitation", signal };
+            const validation = await agent.config.validator(tool, payload, context);
+            if (validation)
+                throw invalid("Elicitation payload failed schema validation");
+        }
+    }
+    // Tool-declared answer-shape validation, re-derived from the current registry (never persisted).
+    const call = state.pendingCalls?.find((entry) => entry.call.id === target.toolCallId)?.call;
+    const tool = call ? activeTools(agent.config.tools).registry.get(call.name) : undefined;
+    const validate = tool?.elicitation && call
+        ? safeToolElicitationValidate(tool, call.arguments, {
+            sessionId: state.sessionId,
+            runId: state.runId,
+            toolCallId: target.toolCallId ?? "elicitation",
+            signal,
+        })
+        : undefined;
+    if (validate) {
+        try {
+            validate(payload);
+        }
+        catch (error) {
+            throw invalid(error instanceof Error ? error.message : "Elicitation payload rejected by tool validation");
+        }
+    }
+}
+function safeToolElicitationValidate(tool, args, context) {
+    try {
+        return tool.elicitation(args, context)?.validate;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function executePreparedAgentRunResume(prepared, signal) {
+    if (prepared.kind === "deny") {
+        await prepared.session.recordDurableDenial(prepared.result.runId, prepared.interruption, prepared.version, prepared.ownership);
+        return prepared.result;
+    }
+    if (prepared.kind === "resuspend") {
+        await prepared.session.recordDurableResumption(prepared.result.runId, prepared.interruption, prepared.version, prepared.ownership);
+        return prepared.result;
+    }
+    return prepared.session.resumeDurable(prepared.state, prepared.runState, prepared.ownership, signal, prepared.decisions);
 }
 class AgentRunSuspended extends Error {
     state;
@@ -82,6 +452,30 @@ class AgentRunSuspended extends Error {
         this.name = "AgentRunSuspended";
     }
 }
+/** Root-visible nested approval id: hashed so it stays bounded and non-enumerating at any depth. */
+function nestedApprovalId(runId, childApprovalId) {
+    return `sub_${createHash("sha256").update(`${runId}:${childApprovalId}`).digest("hex")}`;
+}
+function pathsEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+function decisionScopesEqual(a, b) {
+    if (a.toolName !== b.toolName || a.argumentsHash !== b.argumentsHash || a.effectKind !== b.effectKind || a.identity !== b.identity)
+        return false;
+    if (a.actionConstraints === undefined || b.actionConstraints === undefined)
+        return a.actionConstraints === b.actionConstraints;
+    const keys = Object.keys(a.actionConstraints);
+    return (keys.length === Object.keys(b.actionConstraints).length &&
+        keys.every((key) => key in b.actionConstraints &&
+            canonicalToolEffectJson(a.actionConstraints[key]) === canonicalToolEffectJson(b.actionConstraints[key])));
+}
+function nestedOutcomeToolResult(outcome, toolCallId, name) {
+    return outcome.status === "completed"
+        ? { toolCallId, name, ...(outcome.value !== undefined ? { value: outcome.value } : {}) }
+        : { toolCallId, name, error: { code: outcome.code, message: outcome.message } };
+}
 class RuntimeAgentSession {
     id;
     agent;
@@ -91,17 +485,28 @@ class RuntimeAgentSession {
     currentLeafId;
     history = [];
     activeRun;
+    activeRunId;
+    activeProviderTurnAbort;
+    pendingSoftInterrupt = false;
+    pendingSteers = [];
+    pendingSteerBytes = 0;
     activeRedactor;
     activeProvider;
     activeLedger;
+    activeEffectStore;
     activeOwnership;
+    activeIdentity;
     activeIdempotencyKey;
     activeGuardrails;
     activeMetadata;
     activeLimits;
     activeLimitOutputBuffer = false;
     activeDurable;
+    activeLoop;
+    /** Gated calls of the current tool round awaiting one collected suspension. */
+    activeGatedRound;
     activeLoopTurn = 1;
+    loadedSkills = createLoadedSkillSet();
     ledgerChain = Promise.resolve();
     ledgerFailure;
     snapshotGeneration = 0;
@@ -124,21 +529,76 @@ class RuntimeAgentSession {
     async run(input, options = {}) {
         return this.runInternal(input, options, randomId("run"));
     }
-    async resumeDurable(state, runState, ownership) {
-        return this.runInternal(state.input ?? [], { runState, ownership }, state.runId, { options: runState, state, version: state.version });
+    steer(input, options = {}) {
+        if (!this.activeRun || !this.activeRunId)
+            throw new Error("Agent session has no active run to steer");
+        const messages = inputToMessages(input).map((message) => this.redact(message));
+        if (messages.length === 0)
+            throw new Error("steer requires non-empty input");
+        let addBytes = 0;
+        for (const message of messages)
+            addBytes += messageTextBytes(message);
+        if (this.pendingSteers.length + messages.length > DEFAULT_MAX_PENDING_STEERS) {
+            throw new Error(`steer queue exceeds max pending messages (${DEFAULT_MAX_PENDING_STEERS})`);
+        }
+        if (this.pendingSteerBytes + addBytes > DEFAULT_MAX_PENDING_STEER_BYTES) {
+            throw new Error(`steer queue exceeds max pending bytes (${DEFAULT_MAX_PENDING_STEER_BYTES})`);
+        }
+        this.pendingSteers.push(...messages);
+        this.pendingSteerBytes += addBytes;
+        this.emit({ type: "queue_updated", sessionId: this.id, runId: this.activeRunId, size: this.pendingSteers.length });
+        if (options.softInterrupt) {
+            if (this.activeProviderTurnAbort)
+                this.activeProviderTurnAbort.abort(new SteerSoftInterrupt());
+            else
+                this.pendingSoftInterrupt = true;
+        }
+    }
+    async resumeDurable(state, runState, ownership, signal, decisions) {
+        return this.runInternal(state.input ?? [], { runState, ownership, signal }, state.runId, {
+            options: runState,
+            state,
+            version: state.version,
+            decisions,
+        });
+    }
+    async recordDurableResumption(runId, interruption, version, ownership) {
+        this.activeLedger = this.agent.config.runLedger;
+        this.activeOwnership = ownership ?? this.agent.config.ownership;
+        this.activeRedactor = this.agent.config.redactor;
+        try {
+            this.emit({ type: "agent_suspended", sessionId: this.id, runId, interruption, version });
+            await this.drainLedger();
+        }
+        finally {
+            this.activeLedger = undefined;
+            this.activeOwnership = undefined;
+            this.activeRedactor = undefined;
+            this.closeSubscribers();
+        }
     }
     async recordDurableDenial(runId, interruption, version, ownership) {
         this.activeLedger = this.agent.config.runLedger;
         this.activeOwnership = ownership ?? this.agent.config.ownership;
         this.activeRedactor = this.agent.config.redactor;
-        this.emit({ type: "agent_denied", sessionId: this.id, runId, interruption, version });
-        await this.drainLedger();
-        this.activeLedger = undefined;
-        this.activeOwnership = undefined;
-        this.activeRedactor = undefined;
+        try {
+            this.emit({ type: "agent_denied", sessionId: this.id, runId, interruption, version });
+            await this.drainLedger();
+        }
+        finally {
+            this.activeLedger = undefined;
+            this.activeOwnership = undefined;
+            this.activeRedactor = undefined;
+            this.closeSubscribers();
+        }
     }
     async runInternal(input, options, runId, resumed) {
-        if (this.agent.config.secure && (options.redactor !== undefined || options.ownership !== undefined || options.validate !== undefined || options.runState !== undefined)) {
+        if (this.agent.config.secure &&
+            (options.redactor !== undefined ||
+                options.ownership !== undefined ||
+                options.validate !== undefined ||
+                options.effectStore !== undefined ||
+                options.runState !== undefined)) {
             throw new AgentRunStateError("Secure agent defaults cannot be replaced per run");
         }
         const requestedLimits = options.maxToolRounds === undefined
@@ -151,11 +611,12 @@ class RuntimeAgentSession {
         }
         if (durableOptions) {
             validateRunStateOptions(durableOptions);
-            if (options.model || options.guardrails || options.loop)
-                throw new AgentRunStateError("Durable runs require model, guardrails, and loop on AgentConfig for fingerprinting");
+            if (options.model || options.guardrails || options.loop || options.effectStore)
+                throw new AgentRunStateError("Durable runs require model, guardrails, loop, and effect store on AgentConfig for fingerprinting");
             const configuredLoop = this.agent.config.loop;
-            if (configuredLoop && !isBuiltInLoop(configuredLoop))
-                throw new AgentRunStateError("Custom AgentLoopStrategy is not durable");
+            if (configuredLoop && !isDurableLoop(configuredLoop)) {
+                throw new AgentLoopStateError("ERR_PRISM_LOOP_NOT_DURABLE", "Custom AgentLoopStrategy on a durable run requires snapshot and restore hooks");
+            }
         }
         if (this.activeRun) {
             const error = new Error("Agent session already has an active run");
@@ -165,12 +626,21 @@ class RuntimeAgentSession {
         const controller = new AbortController();
         const cleanupSignal = bridgeAbort(options.signal, controller);
         this.activeRun = controller;
+        this.activeRunId = runId;
+        this.pendingSteers = [];
+        this.pendingSteerBytes = 0;
+        this.pendingSoftInterrupt = false;
         this.activeRedactor = options.redactor ?? this.agent.config.redactor;
         this.activeLedger = options.runLedger ?? this.agent.config.runLedger;
+        this.activeEffectStore = options.effectStore ?? this.agent.config.effectStore;
         this.activeOwnership = options.ownership ?? this.agent.config.ownership;
+        this.activeIdentity = resolveRunIdentity(options.identity, this.agent.config.identity, this.activeOwnership);
+        if (this.activeIdentity && !this.activeOwnership)
+            this.activeOwnership = ownershipFromIdentity(this.activeIdentity);
         this.activeIdempotencyKey = options.idempotencyKey ?? this.agent.config.idempotencyKey;
         this.activeGuardrails = mergeGuardrails(this.agent.config.guardrails, options.guardrails);
         this.activeDurable = resumed ?? (durableOptions ? { options: durableOptions, version: 0 } : undefined);
+        this.activeGatedRound = undefined;
         if (resumed)
             this.invalidateSnapshot();
         const model = options.model ?? this.agent.config.model;
@@ -179,7 +649,12 @@ class RuntimeAgentSession {
         let runStatus = "succeeded";
         const runUsage = createUsageAccumulator();
         let usage;
-        const metadata = { ...this.agent.config.metadata, ...this.metadata, ...options.metadata };
+        const metadata = {
+            ...this.agent.config.metadata,
+            ...this.metadata,
+            ...options.metadata,
+            ...(this.activeIdentity ? identityTelemetryAttributes(this.activeIdentity) : {}),
+        };
         this.activeMetadata = metadata;
         const limits = new RunLimitTracker(resolvedLimits, {
             onExceeded: (breach) => {
@@ -213,7 +688,14 @@ class RuntimeAgentSession {
             const { registry, tools } = activeTools(this.agent.config.tools);
             const activeSkills = this.resolveRunSkills(options, tools);
             if (options.model && JSON.stringify(options.model) !== JSON.stringify(this.agent.config.model)) {
-                await this.appendEntry(createSessionEntry({ sessionId: this.id, parentId: this.currentLeafId, runId, kind: "model_change", previousModel: this.agent.config.model, model: options.model }));
+                await this.appendEntry(createSessionEntry({
+                    sessionId: this.id,
+                    parentId: this.currentLeafId,
+                    runId,
+                    kind: "model_change",
+                    previousModel: this.agent.config.model,
+                    model: options.model,
+                }));
             }
             const inputMessages = inputToMessages(input).map((message) => this.redact(message));
             const inputGuardrails = await runGuardrails({
@@ -224,20 +706,24 @@ class RuntimeAgentSession {
                 redactor: this.activeRedactor,
                 emit: (event) => this.emit(event),
             });
-            if (inputGuardrails.terminal?.action === "interrupt" && this.activeDurable) {
-                if (!resumed) {
-                    const interruption = { kind: "input_guardrail", reason: inputGuardrails.terminal.reason ?? "Input requires approval" };
-                    throw new AgentRunSuspended(await this.suspendDurable({ runId, model, limits, interruption, messages: inputMessages }), interruption);
-                }
+            // Input-guardrail decision table:
+            // - interrupt + durable + fresh run  → suspend for approval.
+            // - interrupt + durable + resumed run → proceed: resuming IS the operator approval.
+            // - interrupt without durable, or block/tripwire → fail via assertGuardrailsAllowed.
+            const approvedByResume = resumed !== undefined && inputGuardrails.terminal?.action === "interrupt" && this.activeDurable !== undefined;
+            if (inputGuardrails.terminal?.action === "interrupt" && this.activeDurable && !approvedByResume) {
+                const interruption = { kind: "input_guardrail", reason: inputGuardrails.terminal.reason ?? "Input requires approval" };
+                throw new AgentRunSuspended(await this.suspendDurable({ runId, model, limits, interruption, messages: inputMessages }), interruption);
             }
-            else {
+            if (inputGuardrails.terminal && !approvedByResume)
                 assertGuardrailsAllowed(inputGuardrails);
-            }
             for (const message of inputMessages)
                 await this.appendMessage(message, runId);
             await this.autoCompact(runId, options, controller.signal, inputMessages);
             const maxToolRounds = resolvedLimits.maxToolRounds;
-            const systemInstructions = composeSystemPrompt(mergeSystemPromptConfig(this.agent.config.systemPrompt, options.systemPrompt), { base: this.agent.config.instructions });
+            const systemInstructions = composeSystemPrompt(mergeSystemPromptConfig(this.agent.config.systemPrompt, options.systemPrompt), {
+                base: this.agent.config.instructions,
+            });
             const contextProviders = [
                 ...(this.agent.config.context ?? []),
                 // ponytail: skill context after host context; no per-skill token budget yet.
@@ -250,6 +736,7 @@ class RuntimeAgentSession {
             const instructionInjectors = options.instructionInjectors ?? this.agent.config.instructionInjectors ?? [];
             const inputLayout = options.inputLayout ?? this.agent.config.inputLayout;
             const loop = resolveLoop(options, this.agent.config);
+            this.activeLoop = loop;
             const toolConcurrency = resolveToolConcurrency(options, this.agent.config);
             this.activeLoopTurn = 1;
             const recordProviderUsage = async (turnUsage, turn, attempt) => {
@@ -272,6 +759,113 @@ class RuntimeAgentSession {
                 };
                 await this.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, this.activeRedactor));
             };
+            // Suspends the run when a round recorded gated calls. Fires at the next provider turn
+            // (generate) or after the loop ends, so ungated round siblings dispatch first.
+            const suspendGatedRound = async () => {
+                const gated = this.activeGatedRound;
+                if (!gated?.size)
+                    return;
+                const entries = [...gated.values()];
+                const decisions = entries.map((gatedCall) => gatedCall.decision);
+                const single = decisions.length === 1 ? decisions[0] : undefined;
+                const interruption = {
+                    kind: single?.kind === "elicitation" ? "elicitation" : "tool_approval",
+                    reason: single ? single.reason : `${decisions.length} tool side effects require approval`,
+                    ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
+                    ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
+                    pendingDecisions: decisions,
+                };
+                throw new AgentRunSuspended(await this.suspendDurable({ runId, model, limits, interruption, pendingCalls: entries.map((gatedCall) => gatedCall.entry) }), interruption);
+            };
+            // Suspends on a nested run's pending decisions, merging any still-ready round entries
+            // (with their decisions attached) so a nested signal mid-replay never drops own work.
+            const suspendNested = async (nested) => {
+                const state = this.activeDurable?.state;
+                const kept = (state?.pendingCalls ?? [])
+                    .filter((entry) => entry.status === "ready")
+                    .map((entry) => {
+                    const decision = entry.decision ?? resumed?.decisions?.get(entry.approvalId);
+                    return decision ? { ...entry, decision } : entry;
+                });
+                const gated = [...(this.activeGatedRound?.values() ?? [])];
+                const pendingCalls = [
+                    ...kept,
+                    ...gated.map((gatedCall) => gatedCall.entry),
+                    { call: nested.toolCall, status: "ready", approvalId: `nr_${nested.entry.runId}` },
+                ];
+                const keptIds = new Set(kept.map((entry) => entry.approvalId));
+                const decisions = [
+                    ...(state?.interruption?.pendingDecisions ?? []).filter((pending) => keptIds.has(pending.approvalId)),
+                    ...gated.map((gatedCall) => gatedCall.decision),
+                    ...nested.pending,
+                ];
+                if (decisions.length > HARD_MAX_PENDING_DECISIONS) {
+                    throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Pending decisions exceed ${HARD_MAX_PENDING_DECISIONS} per run`);
+                }
+                const single = decisions.length === 1 ? decisions[0] : undefined;
+                const interruption = {
+                    kind: single?.kind ?? "tool_approval",
+                    reason: single ? single.reason : `${decisions.length} approval request(s) need a decision`,
+                    ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
+                    ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
+                    pendingDecisions: decisions,
+                };
+                throw new AgentRunSuspended(await this.suspendDurable({
+                    runId,
+                    model,
+                    limits,
+                    interruption,
+                    pendingCalls,
+                    nestedRuns: [...(state?.nestedRuns ?? []), nested.entry],
+                }), interruption);
+            };
+            // Converts a nested-run suspension into either root-visible pending decisions (hashed,
+            // attributed approval ids) or — when a root sticky covers every surfaced decision and a
+            // hook is available — an immediate child resume loop ending in a synthesized tool result.
+            const applyNestedRun = async (input) => {
+                let current = input.pending;
+                // ponytail: sticky auto-apply only when the whole surfaced set is covered; mixed sets
+                // surface to the host. Hook round-trips capped at 4 per suspension event.
+                for (let depth = 0;; depth += 1) {
+                    const attributed = current.map((decision) => {
+                        const id = nestedApprovalId(input.ref.runId, decision.approvalId);
+                        return {
+                            id,
+                            childApprovalId: decision.approvalId,
+                            decision: { ...decision, approvalId: id, attribution: decision.attribution ?? { path: input.path } },
+                        };
+                    });
+                    if (attributed.some(({ decision }) => (decision.attribution?.path.length ?? 0) > MAX_ATTRIBUTION_DEPTH)) {
+                        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Attribution path exceeds ${MAX_ATTRIBUTION_DEPTH} entries`);
+                    }
+                    const allSticky = attributed.length > 0 && attributed.every(({ decision }) => this.matchNestedSticky(decision) !== undefined);
+                    if (!input.hook || !allSticky || depth >= 4) {
+                        return {
+                            entry: {
+                                runId: input.ref.runId,
+                                ...(input.ref.sessionId ? { sessionId: input.ref.sessionId } : {}),
+                                toolCallId: input.toolCall.id,
+                                path: attributed[0]?.decision.attribution?.path ?? input.path,
+                                approvals: attributed.map(({ id, childApprovalId }) => ({ id, childApprovalId })),
+                            },
+                            pending: attributed.map(({ decision }) => decision),
+                        };
+                    }
+                    const outcome = await input.hook({ ref: input.ref, toolCallId: input.toolCall.id, path: input.path }, attributed.map(({ childApprovalId, decision }) => {
+                        const sticky = this.matchNestedSticky(decision);
+                        return {
+                            approvalId: childApprovalId,
+                            outcome: sticky.outcome,
+                            ...(sticky.reason !== undefined ? { reason: sticky.reason } : {}),
+                        };
+                    }));
+                    if (outcome.status === "suspended") {
+                        current = outcome.pendingDecisions;
+                        continue;
+                    }
+                    return { toolResult: nestedOutcomeToolResult(outcome, input.toolCall.id, input.toolCall.name) };
+                }
+            };
             // ponytail: LoopContext binds existing private helpers; loop orchestrates only.
             let assembledTurn = false;
             let artifactFinished = false;
@@ -286,6 +880,7 @@ class RuntimeAgentSession {
                 inputMessages,
                 maxToolRounds,
                 toolConcurrency,
+                restoredLoopState: resumed?.state?.loopState?.snapshot,
                 assemble: async (nextInput, toolResults, turn) => {
                     limits.charge("maxTurns");
                     const request = await assembleProviderInput({
@@ -302,6 +897,9 @@ class RuntimeAgentSession {
                         promptBuilder: this.agent.config.promptBuilder,
                         contextProviders,
                         skills: activeSkills,
+                        skillsDisclosure: resolveSkillsDisclosure(options.skillsDisclosure, this.agent.config.skillsDisclosure),
+                        toolResultFold: resolveToolResultFold(options.toolResultFold, this.agent.config.toolResultFold),
+                        loadedSkills: this.loadedSkills,
                         tools,
                         resourceLoader: this.agent.config.resourceLoader,
                         permission: this.agent.config.permission,
@@ -320,53 +918,151 @@ class RuntimeAgentSession {
                 chargeToolRound: (calls) => {
                     if (calls.length > 0)
                         limits.charge("maxToolRounds");
+                    const durable = this.activeDurable;
+                    if (!durable || !durable.options.interruptBeforeTool || calls.length === 0)
+                        return;
+                    // Round-level gate: record one pending decision per uncovered gated call. Ungated
+                    // and sticky-allowed calls still dispatch; the suspension fires at the next provider
+                    // turn (or run end) via suspendGatedRound. Per-call beforeExecute is the backstop
+                    // for loops that dispatch without charging a round.
+                    for (const call of calls) {
+                        if (this.matchStickyDecision(call, registry))
+                            continue;
+                        const approvalId = randomId("approval");
+                        this.activeGatedRound ??= new Map();
+                        this.activeGatedRound.set(call.id, {
+                            entry: { call, status: "ready", approvalId },
+                            decision: this.buildPendingDecision(call, approvalId, registry, runId, metadata, controller.signal),
+                        });
+                    }
+                    if (this.activeGatedRound && this.activeGatedRound.size > DEFAULT_MAX_PENDING_DECISIONS) {
+                        throw new AgentDecisionError("ERR_PRISM_DECISION_LIMIT", `Pending decisions exceed ${DEFAULT_MAX_PENDING_DECISIONS} per run`);
+                    }
                 },
                 generate: async (request) => {
+                    await suspendGatedRound();
                     if (!assembledTurn)
                         limits.charge("maxTurns");
                     assembledTurn = false;
                     const policyResult = await this.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
-                    const middlewareRequest = await this.agent.config.middleware?.run("provider_request", policyResult.request) ?? policyResult.request;
-                    return this.generateWithRetry(this.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, this.activeLoopTurn, recordProviderUsage);
+                    const middlewareRequest = (await this.agent.config.middleware?.run("provider_request", policyResult.request)) ?? policyResult.request;
+                    try {
+                        return await this.generateWithRetry(this.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, this.activeLoopTurn, recordProviderUsage);
+                    }
+                    catch (error) {
+                        if (isSteerSoftInterrupt(error)) {
+                            return { content: [], calls: [], started: false, usage: undefined };
+                        }
+                        throw error;
+                    }
                 },
                 isToolCallExclusive: (call) => registry.get(call.name)?.exclusive === true,
-                dispatchToolCall: (call) => dispatchToolCall({
-                    call,
-                    registry,
-                    context: { sessionId: this.id, runId, toolCallId: call.id, signal: controller.signal, metadata },
-                    middleware: this.agent.config.middleware,
-                    emit: (event) => this.emit(event),
-                    permission: this.agent.config.permission,
-                    trust: this.agent.config.trust,
-                    redactor: this.activeRedactor,
-                    ledger: this.activeLedger,
-                    ownership: this.activeOwnership,
-                    guardrails: this.activeGuardrails,
-                    limitTracker: limits,
-                    beforeExecute: async (mediatedCall) => {
-                        const durable = this.activeDurable;
-                        if (!durable)
-                            return;
-                        const pending = durable.state?.pending;
-                        if (pending?.call.id === mediatedCall.id && pending.status === "ready") {
-                            await this.persistDurable({ ...durable.state, status: "running", pending: { ...pending, status: "dispatched" }, interruption: undefined });
-                            return;
-                        }
-                        if (!durable.options.interruptBeforeTool)
-                            return;
-                        const interruption = { kind: "tool_approval", reason: "Tool side effect requires approval", toolCallId: mediatedCall.id, toolName: mediatedCall.name };
-                        throw new AgentRunSuspended(await this.suspendDurable({
-                            runId,
-                            model,
-                            limits,
-                            interruption,
-                            pending: { call: mediatedCall, status: "ready" },
-                        }), interruption);
-                    },
-                    // ponytail: RunOptions wins; array-compose deferred (roadmap: compose-later).
-                    validate,
-                }),
+                dispatchToolCall: async (call) => {
+                    const sticky = this.matchStickyDecision(call, registry);
+                    if (sticky?.outcome === "reject_for_run") {
+                        return {
+                            toolCallId: call.id,
+                            name: call.name,
+                            error: { code: "approval_rejected", message: sticky.reason ?? "Rejected for this run" },
+                        };
+                    }
+                    if (this.activeGatedRound?.has(call.id)) {
+                        // Gated this round: never dispatched. The marker is skipped by
+                        // dispatchToolCallsInOrder so the transcript stays free of phantom results.
+                        return { toolCallId: call.id, name: call.name, metadata: { approvalPending: true } };
+                    }
+                    try {
+                        return await dispatchToolCall({
+                            call,
+                            registry,
+                            context: {
+                                sessionId: this.id,
+                                runId,
+                                toolCallId: call.id,
+                                signal: controller.signal,
+                                metadata: {
+                                    ...metadata,
+                                    loadedSkills: this.loadedSkills,
+                                    activeTools: tools,
+                                    activeSkillNames: activeSkills.map((skill) => skill.name),
+                                },
+                                identity: this.activeIdentity,
+                            },
+                            middleware: this.agent.config.middleware,
+                            emit: (event) => this.emit(event),
+                            permission: this.agent.config.permission,
+                            trust: this.agent.config.trust,
+                            redactor: this.activeRedactor,
+                            ledger: this.activeLedger,
+                            effectStore: this.activeEffectStore,
+                            ownership: this.activeOwnership,
+                            identity: this.activeIdentity,
+                            guardrails: this.activeGuardrails,
+                            limitTracker: limits,
+                            beforeExecute: async (mediatedCall) => {
+                                const durable = this.activeDurable;
+                                if (!durable)
+                                    return;
+                                const pendingCalls = durable.state?.pendingCalls;
+                                const matched = pendingCalls?.find((entry) => entry.call.id === mediatedCall.id && entry.status === "ready");
+                                if (matched) {
+                                    await this.persistDurable({
+                                        ...durable.state,
+                                        status: "running",
+                                        pendingCalls: pendingCalls.map((entry) => (entry === matched ? { ...entry, status: "dispatched" } : entry)),
+                                        interruption: undefined,
+                                    });
+                                    return;
+                                }
+                                const pending = durable.state?.pending;
+                                if (pending?.call.id === mediatedCall.id && pending.status === "ready") {
+                                    await this.persistDurable({
+                                        ...durable.state,
+                                        status: "running",
+                                        pending: { ...pending, status: "dispatched" },
+                                        interruption: undefined,
+                                    });
+                                    return;
+                                }
+                                if (!durable.options.interruptBeforeTool)
+                                    return;
+                                if (this.matchStickyDecision(mediatedCall, registry)?.outcome === "allow_for_run")
+                                    return;
+                                // Backstop for loops that dispatch without awaiting chargeToolRound: suspend on
+                                // the first uncovered gated call with a single pending decision.
+                                const approvalId = randomId("approval");
+                                const decision = this.buildPendingDecision(mediatedCall, approvalId, registry, runId, metadata, controller.signal);
+                                const interruption = {
+                                    kind: "tool_approval",
+                                    reason: decision.reason,
+                                    toolCallId: mediatedCall.id,
+                                    toolName: mediatedCall.name,
+                                    pendingDecisions: [decision],
+                                };
+                                throw new AgentRunSuspended(await this.suspendDurable({
+                                    runId,
+                                    model,
+                                    limits,
+                                    interruption,
+                                    pending: { call: mediatedCall, status: "ready" },
+                                    pendingCalls: [{ call: mediatedCall, status: "ready", approvalId }],
+                                }), interruption);
+                            },
+                            // ponytail: RunOptions wins; array-compose deferred (roadmap: compose-later).
+                            validate,
+                        });
+                    }
+                    catch (error) {
+                        // Link the suspension signal to the hosting call so the root suspension can
+                        // synthesize this call's tool_result when the nested run later terminates.
+                        if (error instanceof AgentDelegationSuspendedError && !error.toolCall)
+                            error.toolCall = call;
+                        throw error;
+                    }
+                },
                 appendMessage: (message) => this.appendMessage(message, runId),
+                hasPendingSteers: () => this.pendingSteers.length > 0,
+                applyPendingSteers: () => this.applyPendingSteers(runId, metadata, controller.signal),
                 emit: (event) => {
                     if (event.type === "turn_started")
                         this.activeLoopTurn = event.turn;
@@ -383,17 +1079,178 @@ class RuntimeAgentSession {
                     this.emit(event);
                 },
             };
-            if (resumed?.state?.pending?.status === "ready") {
-                const result = await ctx.dispatchToolCall(resumed.state.pending.call);
+            const replayToolResult = async (result) => {
                 await ctx.appendMessage({
                     role: "tool",
-                    content: [{ type: "tool_result", toolCallId: result.toolCallId, name: result.name, result: result.value, error: result.error }, ...(result.content ?? [])],
+                    content: [
+                        { type: "tool_result", toolCallId: result.toolCallId, name: result.name, result: result.value, error: result.error },
+                        ...(result.content ?? []),
+                    ],
                     metadata: result.metadata,
                 });
+            };
+            // Handles a nested-run suspension signal: sticky auto-apply appends a synthesized
+            // tool_result and returns; anything else re-suspends the root (throws AgentRunSuspended).
+            const handleNestedSignal = async (error) => {
+                const durableOptions = this.activeDurable?.options;
+                if (!durableOptions || !error.toolCall) {
+                    throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Nested-run suspension requires durable run state and a hosting tool call");
+                }
+                if (error.pendingDecisions.length === 0) {
+                    throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Nested-run suspension carried no pending decisions");
+                }
+                const applied = await applyNestedRun({
+                    ref: error.ref,
+                    toolCall: error.toolCall,
+                    path: error.path ?? [],
+                    pending: error.pendingDecisions,
+                    hook: durableOptions.resumeNestedRun,
+                });
+                if ("toolResult" in applied) {
+                    await replayToolResult(applied.toolResult);
+                    return;
+                }
+                await suspendNested({ entry: applied.entry, toolCall: error.toolCall, pending: applied.pending });
+            };
+            // Route decided nested-run approvals back to their children before replaying own calls.
+            // Undecided or re-suspended children re-suspend the root with the surfaced remainder.
+            let resumePendingCalls = resumed?.state?.pendingCalls;
+            if (resumed?.state?.nestedRuns?.length) {
+                const nestedRuns = resumed.state.nestedRuns;
+                const hook = this.activeDurable?.options.resumeNestedRun;
+                const oldPending = resumed.state.interruption?.pendingDecisions ?? [];
+                const nestedApprovalIds = new Set(nestedRuns.flatMap((entry) => entry.approvals.map((approval) => approval.id)));
+                const remainingNested = [];
+                const surfacedPending = [];
+                const resolvedToolCallIds = new Set();
+                for (const entry of nestedRuns) {
+                    const grouped = [];
+                    for (const approval of entry.approvals) {
+                        const decision = entry.decisions?.[approval.id] ?? resumed.decisions?.get(approval.id);
+                        if (decision)
+                            grouped.push({ ...decision, approvalId: approval.childApprovalId });
+                    }
+                    if (grouped.length === 0) {
+                        remainingNested.push(entry);
+                        surfacedPending.push(...oldPending.filter((pending) => entry.approvals.some((approval) => approval.id === pending.approvalId)));
+                        continue;
+                    }
+                    if (!hook) {
+                        throw new AgentDecisionError("ERR_PRISM_DECISION_INVALID", "Nested-run decisions require a resumeNestedRun hook");
+                    }
+                    const toolCall = resumePendingCalls?.find((pending) => pending.call.id === entry.toolCallId)?.call;
+                    if (!toolCall)
+                        throw new AgentRunStateError("Nested run link is missing its tool call");
+                    const ref = { runId: entry.runId, ...(entry.sessionId ? { sessionId: entry.sessionId } : {}) };
+                    const outcome = await hook({ ref, toolCallId: entry.toolCallId, path: entry.path }, grouped);
+                    if (outcome.status !== "suspended") {
+                        await replayToolResult(nestedOutcomeToolResult(outcome, entry.toolCallId, toolCall.name));
+                        resolvedToolCallIds.add(entry.toolCallId);
+                        continue;
+                    }
+                    const applied = await applyNestedRun({ ref, toolCall, path: entry.path, pending: outcome.pendingDecisions, hook });
+                    if ("toolResult" in applied) {
+                        await replayToolResult(applied.toolResult);
+                        resolvedToolCallIds.add(entry.toolCallId);
+                    }
+                    else {
+                        remainingNested.push(applied.entry);
+                        surfacedPending.push(...applied.pending);
+                    }
+                }
+                resumePendingCalls = resumePendingCalls
+                    ?.filter((entry) => !resolvedToolCallIds.has(entry.call.id))
+                    .map((entry) => {
+                    const decision = resumed.decisions?.get(entry.approvalId);
+                    return decision && !entry.decision ? { ...entry, decision } : entry;
+                });
+                if (this.activeDurable?.state) {
+                    this.activeDurable.state = {
+                        ...this.activeDurable.state,
+                        pendingCalls: resumePendingCalls?.length ? resumePendingCalls : undefined,
+                        nestedRuns: remainingNested.length ? remainingNested : undefined,
+                    };
+                }
+                const remainingOwn = oldPending.filter((pending) => !nestedApprovalIds.has(pending.approvalId) &&
+                    !resumed.decisions?.has(pending.approvalId) &&
+                    !resumePendingCalls?.some((entry) => entry.approvalId === pending.approvalId && entry.decision !== undefined));
+                if (remainingOwn.length > 0 || surfacedPending.length > 0) {
+                    const pendingDecisions = [...remainingOwn, ...surfacedPending];
+                    const single = pendingDecisions.length === 1 ? pendingDecisions[0] : undefined;
+                    const interruption = {
+                        kind: single?.kind ?? "tool_approval",
+                        reason: `${pendingDecisions.length} approval request(s) remain`,
+                        ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
+                        ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
+                        pendingDecisions,
+                    };
+                    throw new AgentRunSuspended(await this.suspendDurable({
+                        runId,
+                        model,
+                        limits,
+                        interruption,
+                        pendingCalls: resumePendingCalls,
+                        nestedRuns: remainingNested,
+                    }), interruption);
+                }
+            }
+            if (resumePendingCalls?.length) {
+                for (const entry of resumePendingCalls) {
+                    if (entry.status !== "ready")
+                        continue;
+                    const decision = entry.decision ?? resumed?.decisions?.get(entry.approvalId);
+                    if (decision && (decision.outcome === "reject_once" || decision.outcome === "reject_for_run")) {
+                        await replayToolResult({
+                            toolCallId: entry.call.id,
+                            name: entry.call.name,
+                            error: { code: "approval_rejected", message: decision.reason ?? "Approval rejected" },
+                        });
+                        continue;
+                    }
+                    if (decision?.elicitation !== undefined) {
+                        // Elicitation acceptance resolves the suspended call with the validated payload.
+                        await replayToolResult({ toolCallId: entry.call.id, name: entry.call.name, value: decision.elicitation });
+                        continue;
+                    }
+                    const call = decision?.modifiedArguments ? { ...entry.call, arguments: decision.modifiedArguments } : entry.call;
+                    try {
+                        await replayToolResult(await ctx.dispatchToolCall(call));
+                    }
+                    catch (error) {
+                        if (!(error instanceof AgentDelegationSuspendedError))
+                            throw error;
+                        await handleNestedSignal(error);
+                    }
+                }
+            }
+            else if (resumed?.state?.pending?.status === "ready") {
+                await replayToolResult(await ctx.dispatchToolCall(resumed.state.pending.call));
+            }
+            const resumedLoopState = resumed?.state?.loopState;
+            if (resumedLoopState) {
+                if (loop.name !== resumedLoopState.name || (loop.revision ?? "1") !== resumedLoopState.revision) {
+                    throw new AgentLoopStateError("ERR_PRISM_LOOP_REVISION", `Loop ${resumedLoopState.name} revision ${resumedLoopState.revision} does not match the resumed durable run`);
+                }
+                loop.restore?.(resumedLoopState.snapshot);
+            }
+            let loopUsage;
+            while (true) {
+                try {
+                    loopUsage = await loop.run(ctx);
+                    await suspendGatedRound();
+                    break;
+                }
+                catch (error) {
+                    if (!(error instanceof AgentDelegationSuspendedError))
+                        throw error;
+                    await handleNestedSignal(error);
+                }
             }
-            const loopUsage = await loop.run(ctx);
             if (loop.name === "generate-validate-revise" && !artifactFinished) {
-                throw Object.assign(new Error(artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), { name: "ArtifactFailed", code: artifactFailedInfo?.code ?? "artifact_failed" });
+                throw Object.assign(new Error(artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), {
+                    name: "ArtifactFailed",
+                    code: artifactFailedInfo?.code ?? "artifact_failed",
+                });
             }
             usage = runUsage.value() ?? loopUsage;
             if (usage && this.activeLedger) {
@@ -410,7 +1267,16 @@ class RuntimeAgentSession {
             }
             await this.drainLedger();
             const runState = this.activeDurable?.state
-                ? await this.persistDurable({ ...this.activeDurable.state, status: "succeeded", pending: undefined, interruption: undefined })
+                ? await this.persistDurable({
+                    ...this.activeDurable.state,
+                    status: "succeeded",
+                    pending: undefined,
+                    pendingCalls: undefined,
+                    nestedRuns: undefined,
+                    stickyDecisions: undefined,
+                    interruption: undefined,
+                    loopState: undefined,
+                })
                 : undefined;
             this.emit({ type: "agent_finished", sessionId: this.id, runId, usage });
             return this.buildRunResult({ runId, status: "succeeded", usage, runState });
@@ -427,7 +1293,15 @@ class RuntimeAgentSession {
             const breach = error instanceof RunLimitError ? error.breach : limits.breach;
             runStatus = breach ? "failed" : controller.signal.aborted ? "aborted" : "failed";
             const runState = this.activeDurable?.state
-                ? await this.persistDurable({ ...this.activeDurable.state, status: runStatus, interruption: undefined })
+                ? await this.persistDurable({
+                    ...this.activeDurable.state,
+                    status: runStatus,
+                    interruption: undefined,
+                    loopState: undefined,
+                    pendingCalls: undefined,
+                    nestedRuns: undefined,
+                    stickyDecisions: undefined,
+                })
                 : undefined;
             const result = this.buildRunResult({
                 runId,
@@ -443,6 +1317,13 @@ class RuntimeAgentSession {
         finally {
             if (this.activeRun === controller)
                 this.activeRun = undefined;
+            this.activeRunId = undefined;
+            this.activeLoop = undefined;
+            this.activeGatedRound = undefined;
+            this.activeProviderTurnAbort = undefined;
+            this.pendingSoftInterrupt = false;
+            this.pendingSteers = [];
+            this.pendingSteerBytes = 0;
             try {
                 await this.drainLedger();
                 if (this.activeLedger) {
@@ -468,7 +1349,9 @@ class RuntimeAgentSession {
             }
             finally {
                 this.activeLedger = undefined;
+                this.activeEffectStore = undefined;
                 this.activeOwnership = undefined;
+                this.activeIdentity = undefined;
                 this.activeIdempotencyKey = undefined;
                 this.activeGuardrails = undefined;
                 this.activeMetadata = undefined;
@@ -534,21 +1417,27 @@ class RuntimeAgentSession {
         const durable = this.activeDurable;
         if (!durable)
             throw new AgentRunStateError("Durable interruption is not configured");
-        const state = durable.state ?? initialAgentRunState({
-            agent: this.agent,
-            options: durable.options,
-            runId: input.runId,
-            sessionId: this.id,
-            leafId: this.currentLeafId,
-            model: input.model,
-            counters: input.limits.snapshot(),
-            deadlineAt: input.limits.deadlineAt,
-            status: "suspended",
-            interruption: input.interruption,
-            messages: input.messages,
-            pending: input.pending,
-            interruptBeforeTool: durable.options.interruptBeforeTool,
-        });
+        // Capture loop-local state before persisting the suspension. Undefined before the loop
+        // starts (input-guardrail suspensions) and for snapshot-less built-ins.
+        const loop = this.activeLoop;
+        const loopState = loop?.snapshot ? boundedLoopSnapshot(loop.name, loop.revision ?? "1", loop.snapshot()) : undefined;
+        const state = durable.state ??
+            initialAgentRunState({
+                agent: this.agent,
+                options: durable.options,
+                runId: input.runId,
+                sessionId: this.id,
+                leafId: this.currentLeafId,
+                model: input.model,
+                counters: input.limits.snapshot(),
+                deadlineAt: input.limits.deadlineAt,
+                status: "suspended",
+                interruption: input.interruption,
+                messages: input.messages,
+                pending: input.pending,
+                pendingCalls: input.pendingCalls,
+                interruptBeforeTool: durable.options.interruptBeforeTool,
+            });
         return this.persistDurable({
             ...state,
             leafId: this.currentLeafId,
@@ -556,9 +1445,96 @@ class RuntimeAgentSession {
             interruption: input.interruption,
             ...(input.messages ? { input: input.messages } : {}),
             ...(input.pending ? { pending: input.pending } : {}),
+            ...(input.pendingCalls ? { pendingCalls: input.pendingCalls } : {}),
+            nestedRuns: input.nestedRuns ?? state.nestedRuns,
+            ...(loopState ? { loopState } : {}),
             counters: input.limits.snapshot(),
         });
     }
+    /** First attributed sticky whose scope and delegation path exactly match a nested decision. */
+    matchNestedSticky(decision) {
+        const stickies = this.activeDurable?.state?.stickyDecisions;
+        return stickies?.find((sticky) => sticky.attribution !== undefined &&
+            pathsEqual(sticky.attribution.path, decision.attribution?.path) &&
+            decisionScopesEqual(sticky.scope, decision.scope));
+    }
+    /** First sticky decision whose scope exactly matches this call, if any. */
+    matchStickyDecision(call, registry) {
+        const stickies = this.activeDurable?.state?.stickyDecisions;
+        if (!stickies?.length)
+            return undefined;
+        const identityRef = decisionIdentityRef(this.activeIdentity);
+        let argumentsHash;
+        let effectKind;
+        let effectResolved = false;
+        return stickies.find((sticky) => {
+            if (sticky.attribution !== undefined)
+                return false; // nested-run stickies match decisions, not calls
+            const scope = sticky.scope;
+            if (scope.toolName !== undefined && scope.toolName !== call.name)
+                return false;
+            if (scope.identity !== undefined && scope.identity !== identityRef)
+                return false;
+            if (scope.argumentsHash !== undefined) {
+                argumentsHash ??= toolEffectArgumentsHash(call.arguments);
+                if (scope.argumentsHash !== argumentsHash)
+                    return false;
+            }
+            if (scope.effectKind !== undefined) {
+                if (!effectResolved) {
+                    effectResolved = true;
+                    const tool = registry.get(call.name);
+                    effectKind = tool?.effect
+                        ? resolveToolEffectDeclaration(tool, call.arguments, { sessionId: this.id, runId: "", toolCallId: call.id })?.kind
+                        : undefined;
+                }
+                if (scope.effectKind !== effectKind)
+                    return false;
+            }
+            if (scope.actionConstraints) {
+                for (const [key, value] of Object.entries(scope.actionConstraints)) {
+                    const actual = call.arguments[key];
+                    if (canonicalToolEffectJson(actual === undefined ? null : actual) !== canonicalToolEffectJson(value))
+                        return false;
+                }
+            }
+            return true;
+        });
+    }
+    /** Redacted pending-decision descriptor for one gated call; never carries raw arguments. */
+    buildPendingDecision(call, approvalId, registry, runId, metadata, signal) {
+        const tool = registry.get(call.name);
+        const declaration = tool?.effect
+            ? resolveToolEffectDeclaration(tool, call.arguments, {
+                sessionId: this.id,
+                runId,
+                toolCallId: call.id,
+                signal,
+                metadata,
+            })
+            : undefined;
+        const identityRef = decisionIdentityRef(this.activeIdentity);
+        const elicitation = toolElicitationRequest(tool, call.arguments, {
+            sessionId: this.id,
+            runId,
+            toolCallId: call.id,
+            signal,
+            metadata,
+        });
+        return {
+            approvalId,
+            kind: elicitation ? "elicitation" : "tool_approval",
+            toolCallId: call.id,
+            scope: {
+                toolName: call.name,
+                argumentsHash: toolEffectArgumentsHash(call.arguments),
+                ...(declaration && declaration.kind !== "none" ? { effectKind: declaration.kind } : {}),
+                ...(identityRef ? { identity: identityRef } : {}),
+            },
+            reason: elicitation?.reason ?? "Tool side effect requires approval",
+            ...(elicitation ? { elicitationSchema: elicitation.schema } : {}),
+        };
+    }
     async persistDurable(state) {
         const durable = this.activeDurable;
         if (!durable)
@@ -596,7 +1572,13 @@ class RuntimeAgentSession {
         await this.rebuildHistory();
     }
     fork(options = {}) {
-        return createAgentSession({ agent: this.agent, id: this.id, store: this.store, leafId: options.leafId ?? this.currentLeafId, metadata: this.metadata });
+        return createAgentSession({
+            agent: this.agent,
+            id: this.id,
+            store: this.store,
+            leafId: options.leafId ?? this.currentLeafId,
+            metadata: this.metadata,
+        });
     }
     async clone(options = {}) {
         const id = options.id ?? randomId("session");
@@ -612,7 +1594,13 @@ class RuntimeAgentSession {
             const { id: _oldId, parentId: _oldParentId, sessionId: _oldSessionId, ...rest } = entry;
             await this.store.append({ ...rest, id: nextId, parentId: entry.parentId ? remap.get(entry.parentId) : undefined, sessionId: id });
         }
-        return createAgentSession({ agent: this.agent, id, store: this.store, leafId: branch.length ? remap.get(branch[branch.length - 1].id) : undefined, metadata: this.metadata });
+        return createAgentSession({
+            agent: this.agent,
+            id,
+            store: this.store,
+            leafId: branch.length ? remap.get(branch[branch.length - 1].id) : undefined,
+            metadata: this.metadata,
+        });
     }
     branchReader() {
         // ponytail: prefer the store's readBranchPath (one ancestor-chain query) when present so a
@@ -626,9 +1614,7 @@ class RuntimeAgentSession {
         // the resolver entirely; otherwise `RunOptions.providerSource` overrides
         // `AgentConfig.providerSource` for this run. A miss on every source fails
         // closed with `Unknown provider: ${model.provider}` before any provider turn.
-        const provider = this.agent.config.provider ??
-            options.providerSource?.(model) ??
-            this.agent.config.providerSource?.(model);
+        const provider = this.agent.config.provider ?? options.providerSource?.(model) ?? this.agent.config.providerSource?.(model);
         if (!provider)
             throw new Error(`Unknown provider: ${model.provider}`);
         this.activeProvider = provider;
@@ -638,7 +1624,11 @@ class RuntimeAgentSession {
         if (configured && typeof configured === "object" && "list" in configured) {
             if (options.activeSkills)
                 return resolveActiveSkills({ registry: configured, names: options.activeSkills, tools });
-            return configured.list();
+            if (options.skills !== undefined)
+                return options.skills;
+            if (options.activateAllSkills ?? this.agent.config.activateAllSkills)
+                return configured.list();
+            return [];
         }
         const arr = options.skills ?? (Array.isArray(configured) ? configured : []);
         return arr;
@@ -693,7 +1683,7 @@ class RuntimeAgentSession {
                 return await this.generateProviderTurn(request, runId, signal, secrets, turn, attempt, recordUsage);
             }
             catch (error) {
-                if (error instanceof GuardrailError)
+                if (error instanceof GuardrailError || isSteerSoftInterrupt(error))
                     throw error;
                 const failure = error instanceof ProviderTurnFailure ? error : undefined;
                 const info = failure ? redactSecrets(failure.info, secrets) : errorToErrorInfo(error, secrets);
@@ -701,7 +1691,10 @@ class RuntimeAgentSession {
                     throw errorFromInfo(info);
                 const context = { sessionId: this.id, runId, attempt, error: info, metadata: retry?.metadata, signal };
                 let decision = await policy.decide(context);
-                const payload = await this.agent.config.middleware?.run("retry", { context, decision }) ?? { context, decision };
+                const payload = (await this.agent.config.middleware?.run("retry", { context, decision })) ?? {
+                    context,
+                    decision,
+                };
                 decision = payload.decision;
                 if (!decision.retry)
                     throw errorFromInfo(info);
@@ -745,9 +1738,18 @@ class RuntimeAgentSession {
             usageRecorded = true;
             await recordUsage?.(usage, turn, attempt);
         };
+        const turnAbort = new AbortController();
+        const cleanupTurn = bridgeAbort(signal, turnAbort);
+        this.activeProviderTurnAbort = turnAbort;
+        if (this.pendingSoftInterrupt) {
+            this.pendingSoftInterrupt = false;
+            turnAbort.abort(new SteerSoftInterrupt());
+        }
+        const turnRequest = { ...request, signal: turnAbort.signal };
         try {
-            for await (const event of this.activeProvider.generate(request)) {
-                throwIfAborted(signal);
+            throwIfAborted(turnAbort.signal);
+            for await (const event of this.activeProvider.generate(turnRequest)) {
+                throwIfAborted(turnAbort.signal);
                 this.activeLimits.charge("maxResponseBytes", jsonBytes(event));
                 if (event.type === "error")
                     throw new ProviderTurnFailure(event.error, started);
@@ -791,7 +1793,7 @@ class RuntimeAgentSession {
                     stage: "output",
                     guardrails: this.activeGuardrails,
                     value: { content, calls, messageId, started, usage },
-                    context: { sessionId: this.id, runId, metadata: this.activeMetadata ?? {}, signal },
+                    context: { sessionId: this.id, runId, metadata: this.activeMetadata ?? {}, signal: turnAbort.signal },
                     redactor: this.activeRedactor,
                     emit: (event) => this.emit(event),
                 }));
@@ -811,6 +1813,19 @@ class RuntimeAgentSession {
             return { content, calls, messageId, started, usage };
         }
         catch (error) {
+            if (isSteerSoftInterrupt(error) || isSteerSoftInterrupt(turnAbort.signal.reason)) {
+                await recordTurnUsage();
+                const latencyMs = Math.round(performance.now() - startedAt);
+                this.emit({
+                    type: "provider_turn_finished",
+                    sessionId: this.id,
+                    runId,
+                    turn,
+                    metadata: buildMetadata({ latencyMs }),
+                    usage,
+                });
+                throw new SteerSoftInterrupt();
+            }
             const latencyMs = Math.round(performance.now() - startedAt);
             const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : errorToErrorInfo(error, secrets);
             await recordTurnUsage();
@@ -827,6 +1842,48 @@ class RuntimeAgentSession {
                 throw error;
             throw new ProviderTurnFailure(info, started);
         }
+        finally {
+            cleanupTurn();
+            if (this.activeProviderTurnAbort === turnAbort)
+                this.activeProviderTurnAbort = undefined;
+        }
+    }
+    async applyPendingSteers(runId, metadata, signal) {
+        if (this.pendingSteers.length === 0)
+            return false;
+        const drained = this.pendingSteers.splice(0);
+        this.pendingSteerBytes = 0;
+        this.emit({ type: "queue_updated", sessionId: this.id, runId, size: 0 });
+        for (const message of drained) {
+            throwIfAborted(signal);
+            const inputGuardrails = await runGuardrails({
+                stage: "input",
+                guardrails: this.activeGuardrails,
+                value: [message],
+                context: { sessionId: this.id, runId, metadata, signal },
+                redactor: this.activeRedactor,
+                emit: (event) => this.emit(event),
+            });
+            // Mid-run steer: a terminal decision drops the message (never enters history or
+            // the session store) and the run continues. Run-start input blocking still fails
+            // the run — only the blast radius of steered input is narrowed.
+            const terminal = inputGuardrails.terminal;
+            if (terminal) {
+                if (terminal.action === "interrupt")
+                    throw new GuardrailError(terminal);
+                this.emit({
+                    type: "steer_rejected",
+                    sessionId: this.id,
+                    runId,
+                    message: this.activeRedactor ? this.activeRedactor.redact(message) : message,
+                    record: terminal,
+                });
+                continue;
+            }
+            this.history.push(message);
+            await this.appendMessage(message, runId);
+        }
+        return true;
     }
     async applyProviderRequestPolicies(request, runId, options, metadata, signal) {
         const policies = [...policyList(this.agent.config.providerRequestPolicies), ...policyList(options.providerRequestPolicies)];
@@ -853,16 +1910,35 @@ class RuntimeAgentSession {
         throwIfAbortedSignal(signal);
         const entries = await this.entries();
         const secrets = options.secrets ?? [];
-        const strategy = options.strategy ?? createDefaultCompactionStrategy({ keepRecentEntries: options.keepRecentEntries, maxSummaryChars: options.maxSummaryChars, secrets });
-        const context = { sessionId: this.id, entries, keepRecentEntries: options.keepRecentEntries, trigger, secrets, metadata: options.metadata, signal };
+        const strategy = options.strategy ??
+            createDefaultCompactionStrategy({ keepRecentEntries: options.keepRecentEntries, maxSummaryChars: options.maxSummaryChars, secrets });
+        const context = {
+            sessionId: this.id,
+            entries,
+            keepRecentEntries: options.keepRecentEntries,
+            trigger,
+            secrets,
+            metadata: options.metadata,
+            signal,
+        };
         this.emit({ type: "compaction_started", sessionId: this.id, runId });
         let result = await strategy.compact(context);
         result = { ...result, summary: redactSecrets(result.summary, secrets) };
-        const payload = await this.agent.config.middleware?.run("compaction", { context, result }) ?? { context, result };
+        const payload = (await this.agent.config.middleware?.run("compaction", { context, result })) ?? {
+            context,
+            result,
+        };
         result = { ...payload.result, summary: redactSecrets(payload.result.summary, secrets) };
         const source = result.entries?.find((entry) => entry.kind === "compaction");
         const data = isCompactionEntryData(source?.data) ? source.data : undefined;
-        const entry = createSessionEntry({ sessionId: this.id, parentId: this.currentLeafId, runId, kind: "compaction", summary: result.summary, data });
+        const entry = createSessionEntry({
+            sessionId: this.id,
+            parentId: this.currentLeafId,
+            runId,
+            kind: "compaction",
+            summary: result.summary,
+            data,
+        });
         await this.appendEntry(entry);
         const finalResult = { ...result, entries: [entry] };
         this.emit({ type: "compaction_finished", sessionId: this.id, runId, summary: finalResult.summary });
@@ -987,6 +2063,27 @@ function inputToMessages(input) {
         return [input];
     return [...input];
 }
+const steerTextEncoder = new TextEncoder();
+function messageTextBytes(message) {
+    let total = 0;
+    for (const block of message.content) {
+        if (block.type === "text")
+            total += steerTextEncoder.encode(block.text).byteLength;
+    }
+    return total;
+}
+const STEER_SOFT_INTERRUPT_CODE = "steer_soft_interrupt";
+class SteerSoftInterrupt extends Error {
+    code = STEER_SOFT_INTERRUPT_CODE;
+    constructor() {
+        super("Provider turn soft-interrupted by steer");
+        this.name = "SteerSoftInterrupt";
+    }
+}
+function isSteerSoftInterrupt(error) {
+    return (error instanceof SteerSoftInterrupt ||
+        (typeof error === "object" && error !== null && error.code === STEER_SOFT_INTERRUPT_CODE));
+}
 function finalAssistantMessage(history) {
     for (let index = history.length - 1; index >= 0; index -= 1) {
         const message = history[index];
@@ -1039,8 +2136,22 @@ function mergeCompaction(agent, run) {
         return { ...(agent || {}), ...run };
     return agent || undefined;
 }
-function isBuiltInLoop(loop) {
-    return typeof loop === "object" && loop !== null && "strategy" in loop;
+/** Compact redacted principal reference used in decision scopes; never a credential. */
+function decisionIdentityRef(identity) {
+    return identity ? `${identity.tenantId}:${identity.principal.kind}:${identity.principal.id}` : undefined;
+}
+/**
+ * Durable-run gate: built-in option forms and the single-shot singleton are durable via the
+ * pending-call mechanism; a custom strategy must declare both snapshot and restore hooks.
+ */
+function isDurableLoop(loop) {
+    if (typeof loop !== "object" || loop === null)
+        return true;
+    if ("strategy" in loop)
+        return true;
+    if (loop === singleShotLoop)
+        return true;
+    return typeof loop.snapshot === "function" && typeof loop.restore === "function";
 }
 function mergeGuardrails(agent, run) {
     if (!agent && !run)
@@ -1057,11 +2168,25 @@ function withoutTrailingInput(messages, input) {
     const next = [...messages];
     for (let i = input.length - 1; i >= 0; i -= 1) {
         const last = next.at(-1);
-        if (last && JSON.stringify(last) === JSON.stringify(input[i]))
+        if (last && stableMessageKey(last) === stableMessageKey(input[i]))
             next.pop();
     }
     return next;
 }
+// Key-order-insensitive comparison: a redacted-then-reassembled message with reordered
+// keys must still dedupe against the trailing input, or auto-compaction duplicates it.
+function stableMessageKey(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableMessageKey).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableMessageKey(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
 function bridgeAbort(signal, controller) {
     if (!signal)
         return () => undefined;
@@ -1079,9 +2204,10 @@ function throwIfAbortedSignal(signal) {
     if (signal?.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
 }
+const jsonTextEncoder = new TextEncoder();
 function jsonBytes(value) {
     try {
-        return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+        return jsonTextEncoder.encode(JSON.stringify(value)).byteLength;
     }
     catch {
         throw new TypeError("Provider request or event must be JSON-serializable for run limits");
@@ -1098,8 +2224,8 @@ function createUsageAccumulator() {
                 if (value !== undefined)
                     sums.set(key, (sums.get(key) ?? 0) + value);
             }
-            const total = usage.totalTokens
-                ?? (usage.inputTokens !== undefined || usage.outputTokens !== undefined
+            const total = usage.totalTokens ??
+                (usage.inputTokens !== undefined || usage.outputTokens !== undefined
                     ? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
                     : undefined);
             if (total !== undefined)