@arnilo/prism 0.8.0 → 0.10.0

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

@@ -1,9 +1,14 @@
 /** Provider-round phase of runInternal (plan 059). */
+import { resolveInputCap } from "../../attention-compiler.js";
+import { cacheUsageReport } from "../../cache-helpers.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";
 import { providerError, providerToolCallDeltaContent } from "../../provider-events.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "../../redaction.js";
 import { createDefaultRetryPolicy, waitForRetry } from "../../retry.js";
+import { estimateTextTokensForFamily } from "../../usage-estimation.js";
 import { bridgeAbort, errorFromInfo, isSteerSoftInterrupt, jsonBytes, mergeRetry, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, } from "../helpers.js";
 function pushCoalescedContent(content, block) {
     const last = content.at(-1);
@@ -21,6 +26,51 @@ function pushCoalescedContent(content, block) {
     }
     content.push(block);
 }
+/** Resolve the per-request input cap for turn-budget metadata (plan 087 T1). A model without a
+ *  derivable cap (or a bad attention setting on an unrelated run) omits the field instead of
+ *  failing an emitting turn; the attention compiler, when enabled, is the cap authority. */
+export function resolveTurnInputCap(session, model) {
+    const setting = session.agent.config.attentionCompiler;
+    const options = typeof setting === "object" && setting !== null ? setting : undefined;
+    try {
+        return resolveInputCap(options ? { maxInputTokens: options.maxInputTokens, reserveTokens: options.reserveTokens } : {}, model);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Effective budget snapshot at turn end (plan 087 T1): O(1) from the run limit tracker. */
+function turnBudgets(session, model, usage) {
+    const tracker = session.activeLimits;
+    if (!tracker)
+        return undefined;
+    const snapshot = tracker.snapshot();
+    const inputCap = resolveTurnInputCap(session, model);
+    const runInputBudget = tracker.limits.maxInputTokens;
+    return {
+        ...(usage?.inputTokens === undefined
+            ? {}
+            : { inputTokens: usage.inputTokens, inputTokensSource: usage.estimated === true ? "estimated" : "reported" }),
+        ...(inputCap === undefined ? {} : { inputCap }),
+        ...(runInputBudget === null ? {} : { runInputBudget }),
+        runInputUsed: snapshot.inputTokens,
+        turns: snapshot.turns,
+        maxTurns: tracker.limits.maxTurns,
+    };
+}
+function cacheMetadata(usage) {
+    const cache = cacheUsageReport(usage);
+    return cache === undefined ? {} : { cache };
+}
+/** Native reason wins, except a generic `end_turn` on a turn that produced tool calls: protocols
+ *  with one generic completion value (Google `STOP`) are tool-call turns by content (plan 087 T1). */
+function normalizeTurnStopReason(native, calls) {
+    if (native === undefined)
+        return calls.length > 0 ? "tool_calls" : "end_turn";
+    if (native === "end_turn" && calls.length > 0)
+        return "tool_calls";
+    return native;
+}
 /**
  * Plan 062: price usage through the host's {@link CostCatalog} when the provider
  * did not report a cost itself. Stale/unknown quotes, catalog failures, or
@@ -46,17 +96,22 @@ async function withCatalogCost(catalog, model, usage, signal) {
         return usage; // catalog failure degrades to usage-only
     }
 }
-export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
+export async function recordProviderUsage(ctx, turnUsage, turn, attempt, request) {
     const { session, limits, runUsage, runId } = ctx;
-    const usage = turnUsage
-        ? await withCatalogCost(session.agent.config.costCatalog, ctx.model, turnUsage, ctx.controller.signal)
-        : undefined;
-    limits.recordUsage(usage);
-    if (!usage)
-        return;
-    runUsage.add(usage);
+    const usage = turnUsage ?? estimateTurnUsage(session, ctx.model, request);
+    // An estimate is never priced: a catalog quote on estimated tokens would invent billing.
+    const effective = usage && usage.estimated !== true
+        ? await withCatalogCost(session.agent.config.costCatalog, ctx.model, usage, ctx.controller.signal)
+        : usage;
+    limits.recordUsage(effective);
+    if (!effective)
+        return undefined;
+    if (effective.inputTokens !== undefined) {
+        session.activeInputMeter = { tokens: effective.inputTokens, source: effective.estimated === true ? "estimated" : "reported" };
+    }
+    runUsage.add(effective);
     if (!session.activeLedger)
-        return;
+        return effective;
     const usageRecord = {
         id: randomId("usage"),
         sessionId: session.id,
@@ -64,11 +119,134 @@ export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
         scope: "provider_turn",
         turn,
         attempt,
-        usage,
+        usage: effective,
         recordedAt: new Date().toISOString(),
         ...session.activeOwnership,
     };
     await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
+    return effective;
+}
+/**
+ * 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) {
+    // 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 = 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) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role !== "user")
+            continue;
+        return message.content.map((block) => (block.type === "text" ? block.text : "")).join("");
+    }
+    return "";
+}
+/**
+ * Plan 096: host middleware may answer the turn deterministically at the `beforeProviderTurn` seam —
+ * no provider request, no usage, mandatory provenance. `undefined` sends the turn to the provider
+ * unchanged; a malformed answer fails the run closed instead of falling through to the provider.
+ */
+export async function resolveDeterministicTurn(session, request, runId, turn, signal, toolResults = []) {
+    const middleware = session.agent.config.middleware;
+    if (!middleware)
+        return undefined;
+    const payload = await middleware.run("beforeProviderTurn", {
+        sessionId: session.id,
+        runId,
+        turn,
+        userText: lastUserText(request.messages),
+    });
+    const answer = payload?.answer;
+    if (answer === undefined)
+        return undefined;
+    const validated = validateDeterministicTurnAnswer(answer);
+    throwIfAborted(signal);
+    const messageId = randomId("msg");
+    // Same response-byte axis as provider output: a host answer must not bypass a run ceiling.
+    session.activeLimits?.charge("maxResponseBytes", jsonBytes(validated.content));
+    if (session.activeGuardrails?.output?.length) {
+        assertGuardrailsAllowed(await runGuardrails({
+            stage: "output",
+            guardrails: session.activeGuardrails,
+            value: { content: validated.content, calls: [], messageId, started: true, usage: undefined },
+            context: {
+                sessionId: session.id,
+                runId,
+                metadata: session.activeMetadata ?? {},
+                signal,
+                toolResults,
+            },
+            redactor: session.activeRedactor,
+            emit: (event) => session.emit(event),
+        }));
+    }
+    session.emit({
+        type: "deterministic_turn",
+        sessionId: session.id,
+        runId,
+        turn,
+        middleware: validated.provenance.middleware,
+    });
+    session.emit({
+        type: "message_started",
+        sessionId: session.id,
+        runId,
+        message: { id: messageId, role: "assistant", content: [] },
+    });
+    for (const block of validated.content)
+        session.emit({ type: "message_delta", sessionId: session.id, runId, content: block });
+    // Provenance rides the message into the store (plan 096 Task 2): the transcript alone proves no model ran.
+    return {
+        content: validated.content,
+        calls: [],
+        messageId,
+        started: true,
+        usage: undefined,
+        metadata: { deterministic: validated.provenance },
+    };
 }
 export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage, toolResults = []) {
     const retry = mergeRetry(session.agent.config.retry, options.retry);
@@ -119,7 +297,9 @@ export async function generateProviderTurn(session, request, runId, signal, secr
     let messageId;
     let started = false;
     let usage;
+    let nativeStopReason;
     let usageRecorded = false;
+    let effectiveUsage;
     const bufferedOutput = [];
     const bufferOutput = Boolean(session.activeGuardrails?.output?.length || session.activeLimitOutputBuffer);
     const emitOutput = (event) => {
@@ -130,9 +310,11 @@ export async function generateProviderTurn(session, request, runId, signal, secr
     };
     const recordTurnUsage = async () => {
         if (usageRecorded)
-            return;
+            return effectiveUsage;
         usageRecorded = true;
-        await recordUsage?.(usage, turn, attempt);
+        // The seam may return a labeled estimate (plan 091 T2); without a callback the reported value stands.
+        effectiveUsage = (await recordUsage?.(usage, turn, attempt)) ?? usage;
+        return effectiveUsage;
     };
     const turnAbort = new AbortController();
     const cleanupTurn = bridgeAbort(signal, turnAbort);
@@ -153,6 +335,7 @@ export async function generateProviderTurn(session, request, runId, signal, secr
                 usage = event.usage;
             if (event.type === "done") {
                 usage = event.usage ?? usage;
+                nativeStopReason = event.stopReason;
                 break;
             }
             if (event.type === "message_start") {
@@ -183,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({
@@ -209,10 +400,15 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             sessionId: session.id,
             runId,
             turn,
-            metadata: buildMetadata({ latencyMs }),
-            usage,
+            metadata: buildMetadata({
+                latencyMs,
+                stopReason: normalizeTurnStopReason(nativeStopReason, calls),
+                budgets: turnBudgets(session, request.model, effectiveUsage),
+                ...cacheMetadata(effectiveUsage),
+            }),
+            usage: effectiveUsage,
         });
-        return { content, calls, messageId, started, usage };
+        return { content, calls, messageId, started, usage: effectiveUsage };
     }
     catch (error) {
         if (isSteerSoftInterrupt(error) || isSteerSoftInterrupt(turnAbort.signal.reason)) {
@@ -223,8 +419,13 @@ export async function generateProviderTurn(session, request, runId, signal, secr
                 sessionId: session.id,
                 runId,
                 turn,
-                metadata: buildMetadata({ latencyMs }),
-                usage,
+                metadata: buildMetadata({
+                    latencyMs,
+                    stopReason: "abort",
+                    budgets: turnBudgets(session, request.model, effectiveUsage),
+                    ...cacheMetadata(effectiveUsage),
+                }),
+                usage: effectiveUsage,
             });
             throw new SteerSoftInterrupt();
         }
@@ -236,8 +437,14 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             sessionId: session.id,
             runId,
             turn,
-            metadata: buildMetadata({ latencyMs, httpStatus: readProviderHttpStatus(info) }),
-            usage,
+            metadata: buildMetadata({
+                latencyMs,
+                httpStatus: readProviderHttpStatus(info),
+                stopReason: signal.aborted || turnAbort.signal.aborted ? "abort" : "provider_error",
+                budgets: turnBudgets(session, request.model, effectiveUsage),
+                ...cacheMetadata(effectiveUsage),
+            }),
+            usage: effectiveUsage,
             error: info,
         });
         if (error instanceof GuardrailError || error instanceof ProviderTurnFailure)

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,51 @@ 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;
+function recordRecentToolCall(session, call) {
+    const recent = (session.activeRecentToolCalls ??= []);
+    recent.push({ id: call.id, name: call.name, argHash: `sha256:${toolEffectArgumentsHash(call.arguments)}` });
+    if (recent.length > RECENT_TOOL_CALL_LIMIT)
+        recent.shift();
+}
+function dispatchFilter(ctx) {
+    const hiddenOk = ctx.options.allowHiddenToolCalls ?? ctx.session.agent.config.allowHiddenToolCalls;
+    if (hiddenOk || ctx.turnAllow === undefined) {
+        return ctx.tools.length > 0 ? { filter: { allow: ctx.tools.map((tool) => tool.name) } } : {};
+    }
+    if (ctx.turnAllow.length > 0)
+        return { filter: { allow: ctx.turnAllow } };
+    return ctx.tools.length > 0 ? { filter: { deny: ctx.tools.map((tool) => tool.name) } } : {};
+}
 export function bindDispatchToolCall(ctx) {
     return async (call) => {
         const sticky = matchStickyDecision(ctx.session, call, ctx.registry);
@@ -252,6 +323,7 @@ export function bindDispatchToolCall(ctx) {
             return { toolCallId: call.id, name: call.name, metadata: { approvalPending: true } };
         }
         ctx.toolCalls += 1;
+        recordRecentToolCall(ctx.session, call);
         try {
             const result = await dispatchToolCall({
                 call,
@@ -279,7 +351,7 @@ export function bindDispatchToolCall(ctx) {
                 ownership: ctx.session.activeOwnership,
                 identity: ctx.session.activeIdentity,
                 guardrails: ctx.session.activeGuardrails,
-                ...(ctx.tools.length > 0 ? { filter: { allow: ctx.tools.map((tool) => tool.name) } } : {}),
+                ...dispatchFilter(ctx),
                 limitTracker: ctx.limits,
                 beforeExecute: async (mediatedCall) => {
                     const durable = ctx.session.activeDurable;

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 { AttentionStickyFrontier, 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, ToolDefinition, ToolEffectStore, ToolRegistry, ToolResult, Usage } from "../../contracts.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, 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";
@@ -33,9 +33,25 @@ export type SessionHost = {
     activeIdentity?: AgentIdentity;
     activeIdempotencyKey?: string;
     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;
+    /** Plan 091 T2: input tokens of the latest provider turn plus whether the
+     *  provider reported them. Set by the usage seam; read by `contextMeter()`. */
+    activeInputMeter?: {
+        readonly tokens: number;
+        readonly source: "reported" | "estimated";
+    };
+    /** Bounded last-N tool-call summaries of the active run (plan 087 T2): ids, names, arg hashes. */
+    activeRecentToolCalls?: ToolCallSummary[];
     activeLimitOutputBuffer: boolean;
     activeDurable?: ActiveDurableRun;
     activeLoop?: AgentLoopStrategy;
@@ -45,6 +61,8 @@ export type SessionHost = {
     }>;
     activeLoopTurn: number;
     readonly loadedSkills: LoadedSkillSet;
+    /** Run-owned monotonic prompt tail; cleared before each new run. */
+    readonly tailSegments: Map<string, Message>;
     readonly activatedTools: ActiveToolSet;
     restoredSkillBodies: readonly LoadedSkillBodiesEntry[];
     activeRunSkills: readonly Skill[];
@@ -57,11 +75,22 @@ export type SessionHost = {
     serializedAttentionSticky(): PersistedAttentionStickyFrontier | undefined;
     /** Plan 074 P3: restore a frontier that was validated when the checkpoint was loaded. */
     restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
+    /** Folded bodies for this session (plan 086 T3); session-owned so a resumed fold re-applies
+     *  the same stub bytes instead of calling the host `summarize` again. Lazily created. */
+    attentionFoldFor(): AttentionFoldLedger;
+    /** Plan 086 T3: bounded ledger snapshot for a durable checkpoint (undefined before any fold). */
+    serializedAttentionFold(): PersistedAttentionFoldLedger | undefined;
+    /** Plan 086 T3: adopt a ledger validated when the checkpoint was loaded. */
+    restoreAttentionFold(ledger: AttentionFoldLedger): void;
+    /** Plan 086 T3: `attention.compiler.durable` for the current run; set by the run assembler. */
+    attentionDurable: boolean;
     invalidateSnapshot(): void;
     resolveRunProvider(options: RunOptions): void;
     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>;
@@ -83,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;
@@ -116,6 +153,8 @@ export type RoundContext = {
     loop: AgentLoopStrategy;
     toolConcurrency: number;
     toolsDisclosure: import("../../tool-search.js").ToolsDisclosure;
+    /** Per-turn dispatch overlay; undefined when `toolNarrowing` is unset. */
+    turnAllow?: readonly string[];
     assembledTurn: boolean;
     artifactFinished: boolean;
     artifactFailedInfo: {
@@ -128,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;