@arnilo/prism 0.9.0 → 0.10.0

package/dist/agent-session/session/assemble.js

@@ -56,6 +56,104 @@ class TurnPolicyError extends Error {
         this.name = "TurnPolicyError";
     }
 }
+/** Stop-hook misuse: a throwing or malformed hook fails the run closed (plan 106 R1). */
+class StopHookError extends Error {
+    code = "ERR_PRISM_STOP_HOOK";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "StopHookError";
+    }
+}
+/** Validate the merged stop-hook list once per run, before any provider turn (plan 106 R1). */
+function assertStopHooks(hooks) {
+    for (const hook of hooks) {
+        if (typeof hook !== "object" ||
+            hook === null ||
+            typeof hook.name !== "string" ||
+            hook.name.length === 0 ||
+            typeof hook.decide !== "function") {
+            throw new TypeError("stopHooks entries must be StopHook objects with a non-empty name and a decide function");
+        }
+    }
+}
+/**
+ * Run stop hooks in order at a natural loop end (plan 106 R1). The first `continue` wins; every
+ * `stop` (or no hook continuing) leaves the run finished. Hook context is metadata plus the live
+ * transcript — tool arguments, prompts, and results are never reshaped by core.
+ */
+async function evaluateStopHooks(ctx, stopHookActive) {
+    const context = {
+        sessionId: ctx.session.id,
+        runId: ctx.runId,
+        turn: ctx.limits.snapshot().turns,
+        history: ctx.loopCtx.history,
+        metadata: ctx.metadata,
+        signal: ctx.controller.signal,
+        stopHookActive,
+    };
+    for (const hook of ctx.stopHooks) {
+        let decision;
+        try {
+            decision = await hook.decide(context);
+        }
+        catch (error) {
+            throw new StopHookError(`Stop hook "${hook.name}" threw`, { cause: error });
+        }
+        if (decision === null || typeof decision !== "object") {
+            throw new StopHookError(`Stop hook "${hook.name}" must return a StopHookDecision`);
+        }
+        const action = decision.action;
+        if (action === "stop")
+            continue;
+        if (action !== "continue") {
+            throw new StopHookError(`Stop hook "${hook.name}" decision action must be "stop" or "continue"`);
+        }
+        const reason = decision.reason;
+        if (typeof reason !== "string" || reason.length === 0) {
+            throw new StopHookError(`Stop hook "${hook.name}" continue decision requires a non-empty reason string`);
+        }
+        const steer = decision.steer;
+        if (!isStopHookSteer(steer)) {
+            throw new StopHookError(`Stop hook "${hook.name}" steer must be a string or Message`);
+        }
+        return steer === undefined ? { reason } : { reason, steer };
+    }
+    return undefined;
+}
+function isStopHookSteer(value) {
+    if (value === undefined || typeof value === "string")
+        return true;
+    if (typeof value !== "object" || value === null)
+        return false;
+    const message = value;
+    return typeof message.role === "string" && Array.isArray(message.content);
+}
+/**
+ * Queue a continuation through the host steer path (plan 106 R1): same redaction, same 8-message /
+ * 64 KiB caps, and the same input-guardrail re-check when the loop drains it. A queue failure fails
+ * the run closed — the hook asked for something the run cannot deliver.
+ */
+function queueStopHookContinuation(ctx, decision) {
+    const messages = [{ role: "user", content: [{ type: "text", text: decision.reason }] }];
+    if (decision.steer !== undefined) {
+        messages.push(typeof decision.steer === "string" ? { role: "user", content: [{ type: "text", text: decision.steer }] } : decision.steer);
+    }
+    try {
+        ctx.session.steer(messages);
+    }
+    catch (error) {
+        throw new StopHookError("Stop hook continuation could not be queued", { cause: error });
+    }
+}
+/** The generate-validate-revise loop promises a validated artifact; a bare return is a failure. */
+function assertArtifactOutcome(ctx) {
+    if (ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
+        throw Object.assign(new Error(ctx.artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), {
+            name: "ArtifactFailed",
+            code: ctx.artifactFailedInfo?.code ?? "artifact_failed",
+        });
+    }
+}
 /** Validate `RunOptions.turnPolicy` once, before any provider turn (plan 084 Task 2). */
 function assertTurnPolicy(policy, resolvedLimits) {
     if (policy === undefined)
@@ -146,7 +244,7 @@ function assertPromptVersionRef(ref) {
     return ref;
 }
 async function assembleRoundContext(params) {
-    const { session, input, options, runId, resumed, controller, model, startedAt, promptVersion, metadata, limits, runUsage } = params;
+    const { session, input, options, runId, resumed, controller, model, startedAt, promptVersion, metadata, limits, runUsage, stopHooks } = params;
     session.resolveRunProvider(options);
     throwIfAborted(controller.signal);
     session.emit({ type: "agent_started", sessionId: session.id, runId });
@@ -158,6 +256,9 @@ async function assembleRoundContext(params) {
             version: resumed.version,
             ...(resumed.restore ? { restore: resumed.restore } : {}),
         });
+    // Plan 106 R2: first run start of this session opens it. Awaited after the two emits above so the
+    // run's synchronous announce burst stays intact; middleware error policy owns failures.
+    await session.openSession(runId);
     const startRecord = {
         id: runId,
         sessionId: session.id,
@@ -304,6 +405,7 @@ async function assembleRoundContext(params) {
         artifactFailedInfo: undefined,
         toolCalls: 0,
         toolResults: [],
+        stopHooks,
         runUsage,
         loopCtx: undefined,
     };
@@ -373,6 +475,7 @@ async function assembleRoundContext(params) {
                 toolsSearch: session.agent.config.toolsSearch,
                 activatedTools: session.activatedTools,
                 toolResultFold: resolveToolResultFold(options.toolResultFold, session.agent.config.toolResultFold),
+                contextBudget: session.agent.config.contextBudget,
                 attentionCompiler,
                 // Session-owned: a stub made earlier stays applied even on a later under-ratio turn, so
                 // the prompt-cache prefix is not rewritten (C10). Undefined when the compiler is off.
@@ -469,6 +572,50 @@ async function assembleRoundContext(params) {
     ctx.loopCtx = loopCtx;
     return ctx;
 }
+/**
+ * Run the loop to settlement, then apply stop hooks at the natural loop end (plan 106 R1). Each
+ * `continue` queues its reason through the steer path and re-enters the loop with a continuation
+ * context whose `input`/`inputMessages` are empty — the continuation message is already in
+ * `history`, and replaying run-start input would duplicate it. A loop ceiling, a host turn-policy
+ * stop, or an artifact failure is not a natural end: hooks never run there, and a continuation leg
+ * that hits a ceiling ends the run instead of asking again. `limits.maxStopContinuations`
+ * (default 3; `0` observes only; `null` uncapped) bounds continuations as a clean `hook_limit` stop.
+ */
+async function runLoopWithStopHooks(ctx) {
+    let usage = await runLoopUntilSettled(ctx);
+    assertArtifactOutcome(ctx);
+    // Zero overhead when nothing is configured: no wrapper state, no reads.
+    if (ctx.stopHooks.length === 0)
+        return usage;
+    const cap = ctx.limits.limits.maxStopContinuations;
+    let continuations = 0;
+    let stopHookActive = false;
+    for (;;) {
+        if (ctx.runStop !== undefined || ctx.loopCtx.finishReason !== undefined)
+            return usage;
+        const decision = await evaluateStopHooks(ctx, stopHookActive);
+        if (!decision)
+            return usage;
+        if (cap !== null && continuations >= cap) {
+            ctx.loopCtx.finishReason = "hook_limit";
+            return usage;
+        }
+        continuations += 1;
+        stopHookActive = true;
+        queueStopHookContinuation(ctx, decision);
+        const continuationCtx = { ...ctx.loopCtx, input: [], inputMessages: [], continuation: true };
+        try {
+            usage = await runLoopUntilSettled({ ...ctx, loopCtx: continuationCtx });
+        }
+        finally {
+            // The loops set `finishReason` on the context they receive; carry it back so the ceiling
+            // survives onto the result, the finish record, and `persistSucceeded`.
+            if (continuationCtx.finishReason !== undefined)
+                ctx.loopCtx.finishReason = continuationCtx.finishReason;
+        }
+        assertArtifactOutcome(ctx);
+    }
+}
 export async function executeRun(session, input, options, runId, resumed) {
     const legacyMaxToolRounds = options.maxToolRounds;
     if (legacyMaxToolRounds !== undefined) {
@@ -486,6 +633,8 @@ export async function executeRun(session, input, options, runId, resumed) {
     const requestedLimits = options.limits;
     const resolvedLimits = resolveRunLimits(session.agent.config.limits, requestedLimits);
     assertTurnPolicy(options.turnPolicy, resolvedLimits);
+    const stopHooks = [...(session.agent.config.stopHooks ?? []), ...(options.stopHooks ?? [])];
+    assertStopHooks(stopHooks);
     const durableOptions = options.runState ?? session.agent.config.runState;
     if (session.agent.config.runState && options.runState && session.agent.config.runState !== options.runState) {
         throw new AgentRunStateError("RunOptions cannot replace agent durable run-state configuration");
@@ -519,8 +668,11 @@ export async function executeRun(session, input, options, runId, resumed) {
     if (session.activeIdentity && !session.activeOwnership)
         session.activeOwnership = ownershipFromIdentity(session.activeIdentity);
     session.activeIdempotencyKey = options.idempotencyKey ?? session.agent.config.idempotencyKey;
-    session.activeGuardrails = mergeGuardrails(mergeGuardrails(session.agent.config.guardrails, session.packGuardrails), options.guardrails);
     session.activeDurable = resumed ?? (durableOptions ? { options: durableOptions, version: 0 } : undefined);
+    // Plan 104 T3: an `ask` rule is gated at charge time when the run can suspend; a run that cannot
+    // suspend enforces the same rule as a plain block, so it joins the ordinary stage guardrails.
+    const packGuardrails = session.activeDurable ? session.packGuardrails : mergeGuardrails(session.packGuardrails, session.packAskBlocks);
+    session.activeGuardrails = mergeGuardrails(mergeGuardrails(session.agent.config.guardrails, packGuardrails), options.guardrails);
     // Plan 086 T3: reset here, so a suspension before the compiler is resolved (input guardrail)
     // cannot inherit the previous run's durable-folding flag. `assembleRoundContext` sets it true.
     session.attentionDurable = false;
@@ -570,6 +722,7 @@ export async function executeRun(session, input, options, runId, resumed) {
             metadata,
             limits,
             runUsage,
+            stopHooks,
         });
         await replayDurableNestedAndPending(ctx);
         const resumedLoopState = resumed?.state?.loopState;
@@ -579,7 +732,7 @@ export async function executeRun(session, input, options, runId, resumed) {
             }
             ctx.loop.restore?.(resumedLoopState.snapshot);
         }
-        const loopUsage = await runLoopUntilSettled(ctx).catch((error) => {
+        const loopUsage = await runLoopWithStopHooks(ctx).catch((error) => {
             // Host turn-policy stop (plan 084 Task 2): the loop was unwound on purpose at a turn
             // boundary. Not an error — the run settles cleanly and stays resumable.
             if (error instanceof AgentRunStopped)
@@ -588,12 +741,6 @@ export async function executeRun(session, input, options, runId, resumed) {
         });
         stopReason = ctx.runStop?.reason ?? ctx.loopCtx.finishReason;
         stopDetail = ctx.runStop?.detail;
-        if (!ctx.runStop && ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
-            throw Object.assign(new Error(ctx.artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), {
-                name: "ArtifactFailed",
-                code: ctx.artifactFailedInfo?.code ?? "artifact_failed",
-            });
-        }
         usage = runUsage.value() ?? loopUsage;
         return await persistSucceeded(ctx, loopUsage);
     }

package/dist/agent-session/session/persist.js

@@ -16,10 +16,14 @@ export async function persistDurable(session, state) {
     // did not keeps exactly today's bytes, where the frontier rides `persistSessionState`.
     const attentionSticky = persistSessionState || session.attentionDurable ? session.serializedAttentionSticky() : undefined;
     const attentionFold = session.attentionDurable ? session.serializedAttentionFold() : undefined;
+    // Plan 104 T2: pack refs and pack-owned state; the key only exists under the same opt-in, so a
+    // default checkpoint keeps exactly today's bytes.
+    const guardrailPacks = persistSessionState ? session.serializedGuardrailPackState() : undefined;
     const sessionState = {
         ...(persistSessionState
             ? {
                 loadedSkillNames: session.loadedSkills.list(),
+                ...(guardrailPacks ? { guardrailPacks } : {}),
                 ...(session.activatedTools.list().length ? { activatedToolNames: session.activatedTools.list() } : {}),
                 ...(durable.options.includeSkillBodies
                     ? {
@@ -160,19 +164,21 @@ export async function persistSucceeded(ctx, loopUsage) {
         await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
     }
     await session.drainLedger();
+    // Plan 084 Task 2 / plan 106 R1: a clean run-end stop keeps the frontier and marks the state
+    // continuable — a host turn-policy stop (`host_policy`) or a stop-hook continuation cap
+    // (`hook_limit`). Every other succeeded state drops its loop state and is final.
+    const continuableStop = stop ? "host_policy" : ctx.loopCtx.finishReason === "hook_limit" ? "hook_limit" : undefined;
     const runState = session.activeDurable?.state
         ? await persistDurable(session, {
             ...session.activeDurable.state,
             status: "succeeded",
-            // Plan 084 Task 2: a host-policy stop is terminal for the run but leaves the frontier
-            // intact — the loop state is kept and the state is marked continuable.
-            ...(stop ? { stopReason: "host_policy", leafId: session.currentLeafId } : {}),
+            ...(continuableStop ? { stopReason: continuableStop, leafId: session.currentLeafId } : {}),
             pending: undefined,
             pendingCalls: undefined,
             nestedRuns: undefined,
             stickyDecisions: undefined,
             interruption: undefined,
-            ...(stop ? {} : { loopState: undefined }),
+            ...(continuableStop ? {} : { loopState: undefined }),
         })
         : undefined;
     session.emit({
@@ -246,7 +252,7 @@ export async function cleanupRun(input) {
         session.activeRedactor = undefined;
         session.activeProvider = undefined;
         cleanupSignal();
-        session.closeSubscribers();
+        session.closeRunSubscribers();
     }
 }
 //# sourceMappingURL=persist.js.map

package/dist/agent-session/session/provider-round.js

@@ -1,7 +1,7 @@
 /** Provider-round phase of runInternal (plan 059). */
 import { resolveInputCap } from "../../attention-compiler.js";
 import { cacheUsageReport } from "../../cache-helpers.js";
-import { estimateMessageTokens } from "../../context-budget.js";
+import { estimateMessageTokens, estimateRequestExtrasTokens, getContextBudgetReport, resolveHostTokenEstimator, } from "../../context-budget.js";
 import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "../../guardrails.js";
 import { validateDeterministicTurnAnswer } from "../../middleware.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "../../observability.js";
@@ -48,7 +48,9 @@ function turnBudgets(session, model, usage) {
     const inputCap = resolveTurnInputCap(session, model);
     const runInputBudget = tracker.limits.maxInputTokens;
     return {
-        ...(usage?.inputTokens === undefined ? {} : { inputTokens: usage.inputTokens }),
+        ...(usage?.inputTokens === undefined
+            ? {}
+            : { inputTokens: usage.inputTokens, inputTokensSource: usage.estimated === true ? "estimated" : "reported" }),
         ...(inputCap === undefined ? {} : { inputCap }),
         ...(runInputBudget === null ? {} : { runInputBudget }),
         runInputUsed: snapshot.inputTokens,
@@ -125,21 +127,52 @@ export async function recordProviderUsage(ctx, turnUsage, turn, attempt, request
     return effective;
 }
 /**
- * Plan 091 T2 missing-usage fallback: when the provider reported nothing and the
- * agent did not turn estimation off, label an estimate of the turn's own request
- * (messages + tool declarations + context blocks). Returns `undefined` when
- * estimation is off or the request is unavailable — absent stays absent.
+ * Plan 091 T2 missing-usage fallback, plan 103 T6 exact-measurement reuse: when the provider
+ * reported nothing and the agent did not turn estimation off, label one estimate of the turn's
+ * own request, preferring the most exact measurement that already exists —
+ * 1. the budget pass's own `ContextBudgetReport.keptTokens` (whole request, post-eviction,
+ *    the same figure that decided evictions; excludes content added after the budget pass),
+ * 2. the host's `contextBudget.tokenEstimator`, projecting messages plus tool/context portions
+ *    through the assembler's own `measureAll` text shapes,
+ * 3. the plan-091 family heuristic for messages plus those same assembler shapes for extras
+ *    (no `JSON.stringify` of the schemas, so no drift from what the assembler measured).
+ * A host tokenizer's count is still an estimate (`confidence: "high"`, never `"reported"`);
+ * a report measured by the built-in ÷4 basis is honestly `"low"`. Returns `undefined` when
+ * estimation is not the fallback (`"off"` / `"strict"`) or the request is unavailable —
+ * absent stays absent.
  */
 function estimateTurnUsage(session, model, request) {
-    if (!request || session.agent.config.usageEstimation === "off")
+    // Omitted is the documented default (`"fallback"`), not a reason to skip estimation.
+    const mode = session.agent.config.usageEstimation ?? "fallback";
+    if (!request || mode !== "fallback")
         return undefined;
+    const hostEstimator = resolveHostTokenEstimator(session.agent.config.contextBudget);
+    const report = getContextBudgetReport(request);
+    if (report) {
+        return { inputTokens: report.keptTokens, estimated: true, confidence: hostEstimator === undefined ? "low" : "high" };
+    }
+    if (hostEstimator) {
+        let tokens = estimateRequestExtrasTokens(request.tools, request.context, hostEstimator);
+        for (const message of request.messages)
+            tokens += estimateMessageTokens(message, hostEstimator);
+        return { inputTokens: tokens, estimated: true, confidence: "high" };
+    }
     const estimate = estimateMessageTokens(request.messages, model.model);
-    const extras = request.tools?.length || request.context?.length ? JSON.stringify({ tools: request.tools, context: request.context }) : undefined;
-    return {
-        inputTokens: estimate.tokens + (extras === undefined ? 0 : estimateTextTokensForFamily(extras, model.model)),
-        estimated: true,
-        confidence: estimate.confidence,
-    };
+    const extras = estimateRequestExtrasTokens(request.tools, request.context, (text) => estimateTextTokensForFamily(text, model.model));
+    return { inputTokens: estimate.tokens + extras, estimated: true, confidence: estimate.confidence };
+}
+/**
+ * Plan 103 T5: the refusal `usageEstimation: "strict"` gives a completed turn that reported no
+ * usage. It rides the existing observable-failure path (one attempt, terminal `error` event) and
+ * stamps no `failureClass` — a harness refusal is not a provider failure, so `name`/`code` are
+ * what a host matches on. The info carries the turn number and mode only, never request content.
+ */
+function usageMissingFailure(turn) {
+    return new ProviderTurnFailure({
+        name: "UsageMissingError",
+        code: "usage_missing",
+        message: `provider reported no usage on turn ${turn} and usageEstimation is "strict"`,
+    }, true);
 }
 /** Latest user-role text in the assembled request; steered messages included. */
 function lastUserText(messages) {
@@ -333,6 +366,14 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             calls.push(call);
             emitOutput({ type: "message_delta", sessionId: session.id, runId, content: call });
         }
+        // Plan 103 T5: strict refuses a completed turn that reported no usage *before* the usage seam
+        // runs, so no estimate is projected, the cost catalog is not consulted, and the fail-closed
+        // `recordUsage(undefined)` maxCost breach cannot preempt the refusal. Marking the seam
+        // consulted keeps the catch below from re-entering it with the same missing usage.
+        if (usage === undefined && session.agent.config.usageEstimation === "strict") {
+            usageRecorded = true;
+            throw usageMissingFailure(turn);
+        }
         await recordTurnUsage();
         if (session.activeGuardrails?.output?.length) {
             assertGuardrailsAllowed(await runGuardrails({

package/dist/agent-session/session/tool-round.d.ts

@@ -1,10 +1,10 @@
 /** Tool-round phase of runInternal (plan 059). */
-import type { AgentRunRef, LoopContext, NestedRunRef, PendingDecision, ResumeNestedRun, StickyDecision, ToolCallContent, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
+import type { AgentRunRef, GuardrailRecord, LoopContext, NestedRunRef, PendingDecision, ResumeNestedRun, StickyDecision, ToolCallContent, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
 import { AgentDelegationSuspendedError } from "../../contracts.js";
 import type { RoundContext, SessionHost } from "./types.js";
 export declare function matchNestedSticky(session: SessionHost, decision: PendingDecision): StickyDecision | undefined;
 export declare function matchStickyDecision(session: SessionHost, call: ToolCallContent, registry: ToolRegistry): StickyDecision | undefined;
-export declare function buildPendingDecision(session: SessionHost, call: ToolCallContent, approvalId: string, registry: ToolRegistry, runId: string, metadata: Readonly<Record<string, unknown>>, signal: AbortSignal): PendingDecision;
+export declare function buildPendingDecision(session: SessionHost, call: ToolCallContent, approvalId: string, registry: ToolRegistry, runId: string, metadata: Readonly<Record<string, unknown>>, signal: AbortSignal, ask?: GuardrailRecord): PendingDecision;
 export declare function applyNestedRun(session: SessionHost, input: {
     ref: AgentRunRef;
     toolCall: ToolCallContent;

package/dist/agent-session/session/tool-round.js

@@ -3,6 +3,7 @@ import { AgentRunSuspended, decisionIdentityRef, decisionScopesEqual, nestedAppr
 import { toolElicitationRequest } from "../../agent-tool-dispatch.js";
 import { AgentDecisionError, AgentDelegationSuspendedError, AgentRunStateError, DEFAULT_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_DECISIONS, MAX_ATTRIBUTION_DEPTH, } from "../../contracts.js";
 import { toToolResultMessage } from "../../input.js";
+import { runGuardrails } from "../../guardrails.js";
 import { canonicalToolEffectJson, toolEffectArgumentsHash } from "../../tool-effects.js";
 import { dispatchToolCall, resolveToolEffectDeclaration } from "../../tools.js";
 import { randomId } from "../helpers.js";
@@ -55,7 +56,7 @@ export function matchStickyDecision(session, call, registry) {
         return true;
     });
 }
-export function buildPendingDecision(session, call, approvalId, registry, runId, metadata, signal) {
+export function buildPendingDecision(session, call, approvalId, registry, runId, metadata, signal, ask) {
     const tool = registry.get(call.name);
     const declaration = tool?.effect
         ? resolveToolEffectDeclaration(tool, call.arguments, {
@@ -74,6 +75,11 @@ export function buildPendingDecision(session, call, approvalId, registry, runId,
         signal,
         metadata,
     });
+    // Plan 104 T3: the pack `ask` rule that gated this call is named in the bounded reason and carried
+    // machine-readably, so a host never parses the name to know which rule raised the approval.
+    const pack = ask?.metadata?.pack;
+    const rule = ask?.metadata?.rule;
+    const guardrailRule = typeof pack === "string" && typeof rule === "string" ? { pack, rule } : undefined;
     return {
         approvalId,
         kind: elicitation ? "elicitation" : "tool_approval",
@@ -84,10 +90,22 @@ export function buildPendingDecision(session, call, approvalId, registry, runId,
             ...(declaration && declaration.kind !== "none" ? { effectKind: declaration.kind } : {}),
             ...(identityRef ? { identity: identityRef } : {}),
         },
-        reason: elicitation?.reason ?? "Tool side effect requires approval",
+        reason: elicitation?.reason ?? (ask ? askDecisionReason(ask) : "Tool side effect requires approval"),
         ...(elicitation ? { elicitationSchema: elicitation.schema } : {}),
+        ...(ask && guardrailRule ? { guardrail: ask.guardrail, guardrailRule } : {}),
     };
 }
+const MAX_ASK_DECISION_REASON_BYTES = 200;
+/** `pack:<pack>/<rule>` plus the pack's own reason, bounded like every other decision field. */
+function askDecisionReason(ask) {
+    const pack = ask.metadata?.pack;
+    const rule = ask.metadata?.rule;
+    const defaultReason = typeof pack === "string" && typeof rule === "string" ? `guardrail pack rule ${pack}/${rule}` : undefined;
+    const line = `Approval required by guardrail rule ${ask.guardrail}`;
+    const text = ask.reason && ask.reason !== defaultReason ? `${line}: ${ask.reason}` : line;
+    const bytes = new TextEncoder().encode(text);
+    return bytes.length <= MAX_ASK_DECISION_REASON_BYTES ? text : new TextDecoder().decode(bytes.subarray(0, MAX_ASK_DECISION_REASON_BYTES));
+}
 export async function applyNestedRun(session, input) {
     let current = input.pending;
     for (let depth = 0;; depth += 1) {
@@ -142,6 +160,7 @@ export async function suspendGatedRound(ctx) {
         reason: single ? single.reason : `${decisions.length} tool side effects require approval`,
         ...(single?.toolCallId ? { toolCallId: single.toolCallId } : {}),
         ...(single?.scope.toolName ? { toolName: single.scope.toolName } : {}),
+        ...(single?.guardrail ? { guardrail: single.guardrail } : {}),
         pendingDecisions: decisions,
     };
     throw new AgentRunSuspended(await suspendDurable(ctx.session, {
@@ -217,20 +236,27 @@ export async function handleNestedSignal(ctx, error) {
     await suspendNested(ctx, { entry: applied.entry, toolCall: error.toolCall, pending: applied.pending });
 }
 export function bindChargeToolRound(ctx) {
-    return (calls) => {
+    return async (calls) => {
         if (calls.length > 0)
             ctx.limits.charge("maxToolRounds");
         const durable = ctx.session.activeDurable;
-        if (!durable?.options.interruptBeforeTool || calls.length === 0)
+        // A run that cannot suspend never gates here: `activeGuardrails` already carries the pack `ask`
+        // rules as plain blocks (assemble.ts), so the ordinary stage path refuses the call.
+        if (!durable || calls.length === 0)
+            return;
+        if (!ctx.session.packAskGate && !durable.options.interruptBeforeTool)
             return;
         for (const call of calls) {
             if (matchStickyDecision(ctx.session, call, ctx.registry))
                 continue;
+            const ask = await matchAskGate(ctx, call);
+            if (!ask && !durable.options.interruptBeforeTool)
+                continue;
             const approvalId = randomId("approval");
             ctx.session.activeGatedRound ??= new Map();
             ctx.session.activeGatedRound.set(call.id, {
                 entry: { call, status: "ready", approvalId },
-                decision: buildPendingDecision(ctx.session, call, approvalId, ctx.registry, ctx.runId, ctx.metadata, ctx.controller.signal),
+                decision: buildPendingDecision(ctx.session, call, approvalId, ctx.registry, ctx.runId, ctx.metadata, ctx.controller.signal, ask),
             });
         }
         if (ctx.session.activeGatedRound && ctx.session.activeGatedRound.size > DEFAULT_MAX_PENDING_DECISIONS) {
@@ -238,6 +264,33 @@ export function bindChargeToolRound(ctx) {
         }
     };
 }
+/**
+ * Plan 104 T3: evaluate the pack `ask` rules for one call at charge time. The rules run through the
+ * same compiler and stage runner as every other pack rule, so matching, bounds, and redaction are
+ * shared; a match emits its `guardrail_decision` (`interrupt`: awaiting a decision) and gates the
+ * call before it can dispatch.
+ */
+async function matchAskGate(ctx, call) {
+    const gate = ctx.session.packAskGate;
+    if (!gate)
+        return undefined;
+    const result = await runGuardrails({
+        stage: "tool_input",
+        guardrails: gate,
+        value: call,
+        context: {
+            sessionId: ctx.session.id,
+            runId: ctx.runId,
+            toolCallId: call.id,
+            toolName: call.name,
+            metadata: ctx.metadata,
+            signal: ctx.controller.signal,
+        },
+        redactor: ctx.session.activeRedactor,
+        emit: (event) => ctx.session.emit(event),
+    });
+    return result.terminal;
+}
 /** Last-N dispatched tool calls kept for `budget_exhausted` attribution (plan 087 T2); the hash
  *  is the same canonical arguments hash the effect store uses, so raw args never enter events. */
 const RECENT_TOOL_CALL_LIMIT = 10;

package/dist/agent-session/session/types.d.ts

@@ -1,8 +1,8 @@
 /** Shared host/round types for runInternal phase split (plan 059). Internal only. */
 import type { ActiveDurableRun } from "../../agent-approval.js";
-import type { PendingToolCall } from "../../agent-run-state.js";
+import type { PendingToolCall, PersistedGuardrailPacks } from "../../agent-run-state.js";
 import type { AttentionFoldLedger, AttentionStickyFrontier, PersistedAttentionFoldLedger, PersistedAttentionStickyFrontier } from "../../attention-compiler.js";
-import type { Agent, AgentEvent, AgentFinishReason, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolCallSummary, ToolDefinition, ToolEffectStore, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
+import type { Agent, AgentEvent, AgentFinishReason, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, StopHook, ToolCallSummary, ToolDefinition, ToolEffectStore, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
 import type { AgentIdentity } from "../../identity.js";
 import type { AgentInput } from "../../input.js";
 import type { SecretRedactor } from "../../redaction.js";
@@ -35,6 +35,12 @@ export type SessionHost = {
     activeGuardrails?: Guardrails;
     /** Plan 092 Task 2: packs compiled once at session construction; read-only for phases. */
     readonly packGuardrails?: Guardrails;
+    /** Plan 104 T3: `ask` rules as the durable charge-time gate (`interrupt` records) and as plain
+     *  blocks for a run that cannot suspend. */
+    readonly packAskGate?: Guardrails;
+    readonly packAskBlocks?: Guardrails;
+    /** Plan 104 T2: pack refs + live pack-owned state for a durable checkpoint. */
+    serializedGuardrailPackState(): PersistedGuardrailPacks | undefined;
     activeMetadata?: Readonly<Record<string, unknown>>;
     activePromptVersion?: PromptVersionRef;
     activeLimits?: RunLimitTracker;
@@ -83,6 +89,8 @@ export type SessionHost = {
     emit(event: AgentEvent): void;
     rebuildHistory(): Promise<void>;
     resolveRunSkills(options: RunOptions, tools: readonly ToolDefinition[]): readonly Skill[];
+    /** Redacted, cap-checked steer queue push (plan 106 R1 uses it for stop-hook continuations). */
+    steer(input: AgentInput): void;
     appendEntry(entry: SessionEntry): Promise<void>;
     redact<T>(value: T): T;
     appendMessage(message: Message, runId: string): Promise<void>;
@@ -104,7 +112,15 @@ export type SessionHost = {
         readonly runState?: import("../../contracts.js").AgentRunState;
         readonly interruption?: import("../../contracts.js").AgentRunInterruption;
     }): AgentRunResult;
+    /**
+     * Plan 106 R2: dispatch `session_start` middleware once per session (first run start), awaited by
+     * the run assembler after the `agent_started`/`agent_resumed` emits. No-op on every later call.
+     */
+    openSession(runId: string): Promise<void>;
+    /** Session teardown: close every subscriber, run-scoped and `acrossRuns` alike. */
     closeSubscribers(): void;
+    /** Run end (finish, suspend, or deny): close only the subscribers that do not opt into `acrossRuns`. */
+    closeRunSubscribers(): void;
     snapshot(): Promise<SessionContextSnapshot>;
 };
 export declare function asSessionHost(session: unknown): SessionHost;
@@ -151,6 +167,8 @@ export type RoundContext = {
     toolResults: ToolResult[];
     /** Set when a `RunOptions.turnPolicy` stop ended the loop (plan 084 Task 2). */
     runStop?: RunStopInfo;
+    /** Merged agent + run stop hooks, in invocation order (plan 106 R1). Empty = wrapper skipped. */
+    stopHooks: readonly StopHook[];
     runUsage: {
         add(usage: Usage): void;
         value(): Usage | undefined;