@arnilo/prism 0.6.0 → 0.8.0

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

@@ -3,6 +3,7 @@ import { AgentRunSuspended } from "../../agent-approval.js";
 import { resolveLoop, resolveToolConcurrency } from "../../agent-loops.js";
 import { validateRunStateOptions } from "../../agent-run-state.js";
 import { activeTools } from "../../agent-tool-dispatch.js";
+import { resolveRunAttentionCompiler } from "../../attention-compiler.js";
 import { AgentLoopStateError, AgentRunError, AgentRunStateError } from "../../contracts.js";
 import { assertGuardrailsAllowed, runGuardrails } from "../../guardrails.js";
 import { identityTelemetryAttributes, ownershipFromIdentity, resolveRunIdentity } from "../../identity.js";
@@ -16,13 +17,106 @@ import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } fro
 import { composeSystemPrompt, mergeSystemPromptConfig } from "../../system-prompts.js";
 import { resolveToolResultFold } from "../../tool-result-fold.js";
 import { createSearchToolsTool, createToolSearchState, resolveToolsDisclosure } from "../../tool-search.js";
-import { createToolRegistry } from "../../tools.js";
+import { createToolRegistry, selectRunTools } from "../../tools.js";
 import { bridgeAbort, createUsageAccumulator, inputToMessages, isDurableLoop, isSteerSoftInterrupt, mergeGuardrails, throwIfAborted, } from "../helpers.js";
-import { cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
+import { checkpointDurableTurn, cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
 import { generateWithRetry, recordProviderUsage } from "./provider-round.js";
 import { bindChargeToolRound, bindDispatchToolCall, replayDurableNestedAndPending, runLoopUntilSettled, suspendGatedRound, } from "./tool-round.js";
 const PROMPT_VERSION_MAX_NAME_BYTES = 256;
 const PROMPT_VERSION_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Cap on the host stop detail that reaches the result, ledger, and timeline (plan 084 Task 2). */
+const TURN_STOP_DETAIL_MAX_BYTES = 256;
+/**
+ * `RunOptions.turnPolicy` stopped the run at a turn boundary (plan 084 Task 2). Internal control
+ * signal: it unwinds any loop shape and `executeRun` turns it into a clean terminal success with
+ * `stopReason: "host_policy"` — never a run error.
+ */
+class AgentRunStopped extends Error {
+    constructor() {
+        super("Agent run stopped by host turn policy");
+        this.name = "AgentRunStopped";
+    }
+}
+/** Host turn-policy misuse: a throwing or malformed callback fails the run closed. */
+class TurnPolicyError extends Error {
+    code = "ERR_PRISM_TURN_POLICY";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TurnPolicyError";
+    }
+}
+/** Validate `RunOptions.turnPolicy` once, before any provider turn (plan 084 Task 2). */
+function assertTurnPolicy(policy, resolvedLimits) {
+    if (policy === undefined)
+        return;
+    if (typeof policy !== "object" || policy === null)
+        throw new TypeError("RunOptions.turnPolicy must be an object");
+    if (policy.stop !== undefined && typeof policy.stop !== "function") {
+        throw new TypeError("RunOptions.turnPolicy.stop must be a function");
+    }
+    const maxTurns = policy.maxTurns;
+    if (maxTurns === undefined)
+        return;
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
+        throw new TypeError("RunOptions.turnPolicy.maxTurns must be a positive safe integer");
+    }
+    // Same narrowing law as `limits`: a run overlay may tighten the agent's cap, never widen it.
+    const configured = resolvedLimits.maxTurns;
+    if (configured !== null && maxTurns > configured) {
+        throw new TypeError(`RunOptions.turnPolicy.maxTurns (${maxTurns}) cannot widen limits.maxTurns (${configured})`);
+    }
+}
+/** Redact and bound a host stop reason; anything unusable fails the run closed. */
+function boundedStopDetail(session, reason) {
+    if (typeof reason !== "string" || reason.length === 0) {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop must return a non-empty reason string");
+    }
+    const redacted = session.redact(reason);
+    if (Buffer.byteLength(redacted, "utf8") > TURN_STOP_DETAIL_MAX_BYTES) {
+        throw new TurnPolicyError(`RunOptions.turnPolicy.stop reason must be at most ${TURN_STOP_DETAIL_MAX_BYTES} UTF-8 bytes`);
+    }
+    return redacted;
+}
+/**
+ * Evaluate the host turn policy at the current provider-turn boundary (plan 084 Task 2). Returns
+ * the stop to record, or `undefined` to run the turn. Omitted policy → nothing is read or called.
+ */
+function evaluateTurnStop(ctx) {
+    const policy = ctx.options.turnPolicy;
+    if (!policy)
+        return undefined;
+    const turn = Math.max(1, ctx.session.activeLoopTurn);
+    const turns = turn - 1;
+    if (policy.maxTurns !== undefined && turns >= policy.maxTurns)
+        return { reason: "turn_limit", detail: "maxTurns" };
+    if (!policy.stop)
+        return undefined;
+    const context = {
+        sessionId: ctx.session.id,
+        runId: ctx.runId,
+        turn,
+        turns,
+        toolCalls: ctx.toolCalls,
+        ...(ctx.runUsage.value() ? { usage: ctx.runUsage.value() } : {}),
+        metadata: ctx.metadata,
+    };
+    let decision;
+    try {
+        decision = policy.stop(context);
+    }
+    catch (error) {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop threw", { cause: error });
+    }
+    if (decision === null || typeof decision !== "object" || typeof decision.then === "function") {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop must synchronously return a TurnStopDecision");
+    }
+    const action = decision.action;
+    if (action === "continue")
+        return undefined;
+    if (action !== "stop")
+        throw new TurnPolicyError('RunOptions.turnPolicy.stop decision action must be "continue" or "stop"');
+    return { reason: "host_policy", detail: boundedStopDetail(ctx.session, decision.reason) };
+}
 function assertPromptVersionRef(ref) {
     if (ref === undefined)
         return undefined;
@@ -61,7 +155,12 @@ async function assembleRoundContext(params) {
     };
     await session.activeLedger?.appendRun(redactRunLedgerRecord(startRecord, session.activeRedactor));
     await session.rebuildHistory();
-    const { registry: baseRegistry, tools: activeToolList } = activeTools(session.agent.config.tools);
+    const { tools: listed } = activeTools(session.agent.config.tools);
+    const selected = selectRunTools(listed, options.toolNames, resumed?.state?.toolNames);
+    session.activeToolNames = selected.grant;
+    // Run-local snapshot: concurrent runs and MCP refresh must not mutate this registry.
+    const activeToolList = selected.tools;
+    const baseRegistry = createToolRegistry(activeToolList);
     const toolsDisclosure = resolveToolsDisclosure(options.toolsDisclosure, session.agent.config.toolsDisclosure);
     const toolSearch = toolsDisclosure === "search" && activeToolList.length > 0
         ? {
@@ -115,6 +214,26 @@ async function assembleRoundContext(params) {
     const providerOptions = resolveRunProviderOptions(options, session.agent.config);
     assertStructuredOutputRequestSupported(options.model ?? session.agent.config.model, providerOptions);
     const validate = options.validate ?? session.agent.config.validator;
+    // Resolved once per run, before any provider turn: a bad setting or a widening run overlay
+    // fails here rather than on the turn that happens to cross the ratio (plan 074 C12).
+    const attentionCompiler = resolveRunAttentionCompiler(session.agent.config.attentionCompiler, options.attentionCompiler, options.model ?? session.agent.config.model);
+    // Telemetry seam (plan 074 T6): one `attention_compiled` per mutated turn, counts and the
+    // measured ratio inputs only. Under-ratio turns and compiler-off runs emit nothing.
+    const onAttentionReport = attentionCompiler
+        ? (report) => session.emit({
+            type: "attention_compiled",
+            sessionId: session.id,
+            runId,
+            used: report.used,
+            usedAfter: report.usedAfter,
+            inputCap: report.inputCap,
+            triggerRatio: report.triggerRatio,
+            droppedThinkingTurns: report.droppedThinkingTurns,
+            stubbedToolResults: report.stubbedToolResults,
+            stubbedBytes: report.stubbedBytes,
+            truncated: report.truncated,
+        })
+        : undefined;
     const instructionInjectors = options.instructionInjectors ?? session.agent.config.instructionInjectors ?? [];
     const inputLayout = options.inputLayout ?? session.agent.config.inputLayout;
     const loop = resolveLoop(options, session.agent.config);
@@ -148,6 +267,8 @@ async function assembleRoundContext(params) {
         assembledTurn: false,
         artifactFinished: false,
         artifactFailedInfo: undefined,
+        toolCalls: 0,
+        toolResults: [],
         runUsage,
         loopCtx: undefined,
     };
@@ -183,6 +304,11 @@ async function assembleRoundContext(params) {
                 toolsSearch: session.agent.config.toolsSearch,
                 activatedTools: session.activatedTools,
                 toolResultFold: resolveToolResultFold(options.toolResultFold, session.agent.config.toolResultFold),
+                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.
+                attentionSticky: attentionCompiler ? session.attentionStickyFor() : undefined,
+                onAttentionReport,
                 loadedSkills: session.loadedSkills,
                 tools,
                 resourceLoader: session.agent.config.resourceLoader,
@@ -205,10 +331,24 @@ async function assembleRoundContext(params) {
             if (!ctx.assembledTurn)
                 limits.charge("maxTurns");
             ctx.assembledTurn = false;
+            // Host turn policy (plan 084 Task 2): evaluated at the same turn boundary as the
+            // crash-recovery checkpoint below, before any provider work. Throwing unwinds any loop
+            // shape; `executeRun` converts it into a clean terminal success with `stopReason`.
+            const stop = evaluateTurnStop(ctx);
+            if (stop) {
+                ctx.runStop = stop;
+                ctx.loopCtx.finishReason = stop.reason;
+                throw new AgentRunStopped();
+            }
+            // Crash-recovery boundary (plan 084 Task 1): after the previous turn's tool results are in
+            // the store and before this provider request. No-op unless `checkpointPolicy: "every-turn"`.
+            if (session.activeDurable?.options.checkpointPolicy === "every-turn") {
+                await checkpointDurableTurn(session, { runId, model, limits });
+            }
             const policyResult = await session.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
             const middlewareRequest = (await session.agent.config.middleware?.run("provider_request", policyResult.request)) ?? policyResult.request;
             try {
-                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt));
+                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt), ctx.toolResults);
             }
             catch (error) {
                 if (isSteerSoftInterrupt(error)) {
@@ -257,6 +397,7 @@ 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 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");
@@ -299,6 +440,9 @@ export async function executeRun(session, input, options, runId, resumed) {
     const startedAt = new Date().toISOString();
     let runError;
     let runStatus = "succeeded";
+    // Set only on the clean-success path; the finish ledger record carries them (plan 084 Task 2).
+    let stopReason;
+    let stopDetail;
     const runUsage = createUsageAccumulator();
     let usage;
     const metadata = {
@@ -343,8 +487,16 @@ export async function executeRun(session, input, options, runId, resumed) {
             }
             ctx.loop.restore?.(resumedLoopState.snapshot);
         }
-        const loopUsage = await runLoopUntilSettled(ctx);
-        if (ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
+        const loopUsage = await runLoopUntilSettled(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)
+                return undefined;
+            throw error;
+        });
+        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",
@@ -387,7 +539,7 @@ export async function executeRun(session, input, options, runId, resumed) {
         throw new AgentRunError(result, { cause: error });
     }
     finally {
-        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError });
+        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError, stopReason, stopDetail });
     }
 }
 //# sourceMappingURL=assemble.js.map

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

@@ -15,6 +15,19 @@ export declare function suspendDurable(session: SessionHost, input: {
     /** Full replacement when provided; otherwise the recorded nested runs are preserved. */
     readonly nestedRuns?: readonly NestedRunRef[];
 }): Promise<AgentRunState>;
+/**
+ * Turn-boundary crash-recovery checkpoint (plan 084 Task 1). Called before each provider
+ * request when `checkpointPolicy: "every-turn"`; a no-op otherwise, so default-policy runs keep
+ * the 0.8.x checkpoint shape and write count unchanged. Pending-decision markers are dropped:
+ * at a turn boundary every gated call has been resolved or the run already suspended, and a
+ * stale marker must never replay. The recorded `checkpointPolicy` makes the cadence survive
+ * into a resumed run, and loop-local state rides along exactly as it does at suspension.
+ */
+export declare function checkpointDurableTurn(session: SessionHost, input: {
+    readonly runId: string;
+    readonly model: ModelConfig;
+    readonly limits: RunLimitTracker;
+}): Promise<void>;
 export declare function persistSucceeded(ctx: RoundContext, loopUsage: Usage | undefined): Promise<AgentRunResult>;
 export declare function cleanupRun(input: {
     session: SessionHost;
@@ -25,4 +38,7 @@ export declare function cleanupRun(input: {
     startedAt: string;
     runStatus: AgentRunResult["status"];
     runError: ErrorInfo | undefined;
+    /** Clean stop taxonomy for the finish record; only written for a succeeded run (plan 084 Task 2). */
+    stopReason?: import("../../contracts.js").AgentFinishReason;
+    stopDetail?: string;
 }): Promise<void>;

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

@@ -9,11 +9,14 @@ export async function persistDurable(session, state) {
     const durable = session.activeDurable;
     if (!durable)
         throw new AgentRunStateError("Durable run state is not configured");
+    const withGrant = session.activeToolNames !== undefined ? { ...state, toolNames: session.activeToolNames } : state;
+    const attentionSticky = session.serializedAttentionSticky();
     const persisted = durable.options.persistSessionState
         ? {
-            ...state,
+            ...withGrant,
             sessionState: {
                 loadedSkillNames: session.loadedSkills.list(),
+                ...(attentionSticky ? { attentionSticky } : {}),
                 ...(session.activatedTools.list().length ? { activatedToolNames: session.activatedTools.list() } : {}),
                 ...(durable.options.includeSkillBodies
                     ? {
@@ -24,7 +27,7 @@ export async function persistDurable(session, state) {
                     : {}),
             },
         }
-        : state;
+        : withGrant;
     const saved = await saveAgentRunState({
         checkpoints: durable.options.checkpoints,
         state: persisted,
@@ -74,8 +77,50 @@ export async function suspendDurable(session, input) {
         counters: input.limits.snapshot(),
     });
 }
+/**
+ * Turn-boundary crash-recovery checkpoint (plan 084 Task 1). Called before each provider
+ * request when `checkpointPolicy: "every-turn"`; a no-op otherwise, so default-policy runs keep
+ * the 0.8.x checkpoint shape and write count unchanged. Pending-decision markers are dropped:
+ * at a turn boundary every gated call has been resolved or the run already suspended, and a
+ * stale marker must never replay. The recorded `checkpointPolicy` makes the cadence survive
+ * into a resumed run, and loop-local state rides along exactly as it does at suspension.
+ */
+export async function checkpointDurableTurn(session, input) {
+    const durable = session.activeDurable;
+    if (durable?.options.checkpointPolicy !== "every-turn")
+        return;
+    const loop = session.activeLoop;
+    const loopState = loop?.snapshot ? boundedLoopSnapshot(loop.name, loop.revision ?? "1", loop.snapshot()) : undefined;
+    const state = durable.state ??
+        initialAgentRunState({
+            agent: session.agent,
+            options: durable.options,
+            runId: input.runId,
+            sessionId: session.id,
+            leafId: session.currentLeafId,
+            model: input.model,
+            counters: input.limits.snapshot(),
+            deadlineAt: input.limits.deadlineAt,
+            status: "running",
+            interruptBeforeTool: durable.options.interruptBeforeTool,
+        });
+    await persistDurable(session, {
+        ...state,
+        leafId: session.currentLeafId,
+        status: "running",
+        interruption: undefined,
+        // The input messages are already in the session store by the time a turn boundary is
+        // reached; keeping them would re-append them on a later resume.
+        input: undefined,
+        pending: undefined,
+        pendingCalls: undefined,
+        ...(loopState ? { loopState } : {}),
+        counters: input.limits.snapshot(),
+    });
+}
 export async function persistSucceeded(ctx, loopUsage) {
     const { session, runId, runUsage } = ctx;
+    const stop = ctx.runStop;
     const usage = runUsage.value() ?? loopUsage;
     if (usage && session.activeLedger) {
         const usageRecord = {
@@ -94,12 +139,15 @@ export async function persistSucceeded(ctx, loopUsage) {
         ? 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 } : {}),
             pending: undefined,
             pendingCalls: undefined,
             nestedRuns: undefined,
             stickyDecisions: undefined,
             interruption: undefined,
-            loopState: undefined,
+            ...(stop ? {} : { loopState: undefined }),
         })
         : undefined;
     session.emit({
@@ -108,8 +156,17 @@ export async function persistSucceeded(ctx, loopUsage) {
         runId,
         usage,
         ...(ctx.loopCtx.finishReason ? { finishReason: ctx.loopCtx.finishReason } : {}),
+        ...(stop?.detail ? { stopDetail: stop.detail } : {}),
+    });
+    const stopReason = ctx.runStop?.reason ?? ctx.loopCtx.finishReason;
+    return session.buildRunResult({
+        runId,
+        status: "succeeded",
+        usage,
+        runState,
+        ...(stopReason ? { stopReason } : {}),
+        ...(stop?.detail ? { stopDetail: stop.detail } : {}),
     });
-    return session.buildRunResult({ runId, status: "succeeded", usage, runState });
 }
 export async function cleanupRun(input) {
     const { session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError } = input;
@@ -135,6 +192,8 @@ export async function cleanupRun(input) {
                 status: runStatus,
                 startedAt,
                 finishedAt: new Date().toISOString(),
+                ...(input.runStatus === "succeeded" && input.stopReason ? { stopReason: input.stopReason } : {}),
+                ...(input.runStatus === "succeeded" && input.stopDetail ? { stopDetail: input.stopDetail } : {}),
                 abortReason: controller.signal.aborted ? String(controller.signal.reason) : undefined,
                 error: runError,
                 ...(session.activePromptVersion ? { promptVersion: session.activePromptVersion } : {}),
@@ -155,6 +214,7 @@ export async function cleanupRun(input) {
         session.activeMetadata = undefined;
         session.activePromptVersion = undefined;
         session.activeLimits?.dispose();
+        session.activeToolNames = undefined;
         session.activeLimits = undefined;
         session.activeLimitOutputBuffer = false;
         session.activeRedactor = undefined;

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

@@ -1,6 +1,6 @@
 /** Provider-round phase of runInternal (plan 059). */
-import type { ProviderRequest, ProviderTurnResult, RunOptions, Usage } from "../../contracts.js";
+import type { ProviderRequest, ProviderTurnResult, RunOptions, ToolResult, Usage } from "../../contracts.js";
 import type { RoundContext, SessionHost } from "./types.js";
 export declare function recordProviderUsage(ctx: RoundContext, turnUsage: Usage | undefined, turn: number, attempt: number): Promise<void>;
-export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>): Promise<ProviderTurnResult>;
-export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>): Promise<ProviderTurnResult>;
+export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;
+export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;

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

@@ -1,7 +1,7 @@
 /** Provider-round phase of runInternal (plan 059). */
 import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "../../guardrails.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "../../observability.js";
-import { providerToolCallDeltaContent } from "../../provider-events.js";
+import { providerError, providerToolCallDeltaContent } from "../../provider-events.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "../../redaction.js";
 import { createDefaultRetryPolicy, waitForRetry } from "../../retry.js";
 import { bridgeAbort, errorFromInfo, isSteerSoftInterrupt, jsonBytes, mergeRetry, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, } from "../helpers.js";
@@ -70,13 +70,13 @@ export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
     };
     await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
 }
-export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage) {
+export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage, toolResults = []) {
     const retry = mergeRetry(session.agent.config.retry, options.retry);
     const secrets = [...requestSecrets, ...(retry?.secrets ?? [])];
     const policy = retry?.policy ?? (retry ? createDefaultRetryPolicy(retry) : undefined);
     for (let attempt = 1;; attempt += 1) {
         try {
-            return await generateProviderTurn(session, request, runId, signal, secrets, turn, attempt, recordUsage);
+            return await generateProviderTurn(session, request, runId, signal, secrets, turn, attempt, recordUsage, toolResults);
         }
         catch (error) {
             if (error instanceof GuardrailError || isSteerSoftInterrupt(error))
@@ -100,7 +100,7 @@ export async function generateWithRetry(session, request, runId, options, signal
         }
     }
 }
-export async function generateProviderTurn(session, request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage) {
+export async function generateProviderTurn(session, request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage, toolResults = []) {
     session.activeLimits.charge("maxProviderAttempts");
     session.activeLimits.charge("maxRequestBytes", jsonBytes(request));
     const startedAt = performance.now();
@@ -189,7 +189,13 @@ export async function generateProviderTurn(session, request, runId, signal, secr
                 stage: "output",
                 guardrails: session.activeGuardrails,
                 value: { content, calls, messageId, started, usage },
-                context: { sessionId: session.id, runId, metadata: session.activeMetadata ?? {}, signal: turnAbort.signal },
+                context: {
+                    sessionId: session.id,
+                    runId,
+                    metadata: session.activeMetadata ?? {},
+                    signal: turnAbort.signal,
+                    toolResults,
+                },
                 redactor: session.activeRedactor,
                 emit: (event) => session.emit(event),
             }));
@@ -223,7 +229,7 @@ export async function generateProviderTurn(session, request, runId, signal, secr
             throw new SteerSoftInterrupt();
         }
         const latencyMs = Math.round(performance.now() - startedAt);
-        const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : errorToErrorInfo(error, secrets);
+        const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : providerError(error, secrets).error;
         await recordTurnUsage();
         session.emit({
             type: "provider_turn_finished",

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

@@ -251,8 +251,9 @@ export function bindDispatchToolCall(ctx) {
         if (ctx.session.activeGatedRound?.has(call.id)) {
             return { toolCallId: call.id, name: call.name, metadata: { approvalPending: true } };
         }
+        ctx.toolCalls += 1;
         try {
-            return await dispatchToolCall({
+            const result = await dispatchToolCall({
                 call,
                 registry: ctx.registry,
                 context: {
@@ -278,6 +279,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) } } : {}),
                 limitTracker: ctx.limits,
                 beforeExecute: async (mediatedCall) => {
                     const durable = ctx.session.activeDurable;
@@ -328,6 +330,8 @@ export function bindDispatchToolCall(ctx) {
                 },
                 validate: ctx.validate,
             });
+            ctx.toolResults.push(result);
+            return result;
         }
         catch (error) {
             if (error instanceof AgentDelegationSuspendedError && !error.toolCall)

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

@@ -1,7 +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 { Agent, AgentEvent, AgentLoopStrategy, AgentRunResult, AIProvider, ErrorInfo, Guardrails, LoopContext, Message, ModelConfig, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunLedger, RunOptions, SessionEntry, SessionStore, Skill, ToolDefinition, ToolEffectStore, ToolRegistry, Usage } from "../../contracts.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 { AgentIdentity } from "../../identity.js";
 import type { AgentInput } from "../../input.js";
 import type { SecretRedactor } from "../../redaction.js";
@@ -47,6 +48,15 @@ export type SessionHost = {
     readonly activatedTools: ActiveToolSet;
     restoredSkillBodies: readonly LoadedSkillBodiesEntry[];
     activeRunSkills: readonly Skill[];
+    /** Names-only grant for this run; undefined means the full registered set. */
+    activeToolNames?: readonly string[];
+    /** Sticky mutation frontier for this session (plan 074 C10); session-owned so it survives
+     *  across turns, runs, and provider rounds. Lazily created on first use. */
+    attentionStickyFor(): AttentionStickyFrontier;
+    /** Plan 074 P3: bounded frontier snapshot for durable checkpoints (undefined before any mutation). */
+    serializedAttentionSticky(): PersistedAttentionStickyFrontier | undefined;
+    /** Plan 074 P3: restore a frontier that was validated when the checkpoint was loaded. */
+    restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
     invalidateSnapshot(): void;
     resolveRunProvider(options: RunOptions): void;
     emit(event: AgentEvent): void;
@@ -77,6 +87,11 @@ export type SessionHost = {
     snapshot(): Promise<SessionContextSnapshot>;
 };
 export declare function asSessionHost(session: unknown): SessionHost;
+/** Why a run's loop ended, plus the host's stop detail when `RunOptions.turnPolicy` stopped it. */
+export type RunStopInfo = {
+    readonly reason: AgentFinishReason;
+    readonly detail?: string;
+};
 export type RoundContext = {
     session: SessionHost;
     input: AgentInput;
@@ -107,6 +122,12 @@ export type RoundContext = {
         message: string;
         code?: string | number;
     } | undefined;
+    /** Host tool calls dispatched in this run; the turn-boundary context's `toolCalls` (plan 084 Task 2). */
+    toolCalls: number;
+    /** Completed host tool results from this run, for output evidence guardrails (plan 084 Task 5). */
+    toolResults: ToolResult[];
+    /** Set when a `RunOptions.turnPolicy` stop ended the loop (plan 084 Task 2). */
+    runStop?: RunStopInfo;
     runUsage: {
         add(usage: Usage): void;
         value(): Usage | undefined;

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

@@ -1,6 +1,7 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { ActiveDurableRun } from "../agent-approval.js";
 import type { PendingToolCall, StoredAgentRunState } from "../agent-run-state.js";
+import { type AttentionStickyFrontier, type PersistedAttentionStickyFrontier } from "../attention-compiler.js";
 import type { Agent, AgentEvent, AgentRunResult, AgentRunState, AgentRunStateOptions, AgentSession, AgentSessionConfig, AIProvider, CompactionOptions, CompactionResult, ErrorInfo, Message, OwnershipScope, PendingDecision, PromptVersionRef, ProviderRequest, RunDecision, RunOptions, SessionEntry, Skill, SteerOptions, SubscribeOptions, ToolDefinition, ToolEffectStore, Usage } from "../contracts.js";
 import type { AgentIdentity } from "../identity.js";
 import type { AgentInput } from "../input.js";
@@ -48,6 +49,19 @@ export declare class RuntimeAgentSession implements AgentSession {
     restoredSkillBodies: readonly LoadedSkillBodiesEntry[];
     /** Skills of the current run (for the bodies snapshot); replaced at each run start. */
     activeRunSkills: readonly import("../contracts.js").Skill[];
+    /** Per-run tool allow-list (Task 21); undefined means the full registered set. */
+    activeToolNames?: readonly string[];
+    /** Sticky frontier for this session (plan 074 C10); created on first use, so a session whose
+     *  agents never enable the compiler allocates nothing. Mutations stay applied once made, so a
+     *  later under-ratio turn re-applies them instead of rewriting the prompt-cache prefix. */
+    private attentionSticky?;
+    attentionStickyFor(): AttentionStickyFrontier;
+    /** Plan 074 P3: bounded snapshot for a durable checkpoint; `undefined` when the session never
+     *  mutated anything, so a compiler-off (or never-over-ratio) session persists nothing extra. */
+    serializedAttentionSticky(): PersistedAttentionStickyFrontier | undefined;
+    /** Plan 074 P3: restore a frontier validated at checkpoint load, so a resumed run keeps its
+     *  stubs instead of re-deciding its first turn from the ratio. */
+    restoreAttentionSticky(persisted: PersistedAttentionStickyFrontier): void;
     /** Plan 015 Task 4: re-add persisted loaded-skill names (names only; bodies re-resolve on demand). */
     restoreLoadedSkills(names: readonly string[]): void;
     /** Plan 041: re-add persisted activated-tool names (names only; inert for absent tools). */
@@ -81,6 +95,8 @@ export declare class RuntimeAgentSession implements AgentSession {
         readonly limit?: import("../contracts.js").RunLimitBreach;
         readonly error?: ErrorInfo;
         readonly abortReason?: string;
+        readonly stopReason?: import("../contracts.js").AgentFinishReason;
+        readonly stopDetail?: string;
         readonly runState?: AgentRunState;
         readonly interruption?: import("../contracts.js").AgentRunInterruption;
     }): AgentRunResult;