@arnilo/prism 0.9.0 → 0.11.0

package/dist/checkpoint-restore.js

@@ -1,53 +1,129 @@
 /**
- * Checkpoint restore hooks (plan 094 Task 3). A hook restores one external layer (git commit,
- * document version, workspace fingerprint) recorded in a checkpoint's sidecar metadata.
+ * Checkpoint restore hooks (plan 094 Task 3; reverse compensation plan 109 Task 2). A hook restores
+ * one external layer (git commit, document version, workspace fingerprint) recorded in a
+ * checkpoint's sidecar metadata.
  *
- * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails
- * or times out aborts the resume with `CheckpointRestoreError` naming that hook, so the
- * conversation restore never applies on top of a half-restored external world. Hosts that need
- * every layer back where they were re-run the whole restore after fixing the failing layer.
+ * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails or
+ * times out aborts the resume with `CheckpointRestoreError` naming that hook, so the conversation
+ * restore never applies on top of a half-restored external world. A handler may also declare a
+ * `compensate` direction: on failure the applied layers — including the failing one, which may be
+ * half-applied — are undone in reverse order and the error carries a best-effort
+ * `CheckpointRestoreCompensation` report. Compensation never runs after the caller aborted, never
+ * masks the original failure, and the checkpoint stays resumable either way.
  */
 /** Per-hook ceiling for a restore (plan 094 Task 3 default). */
 export const DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS = 10_000;
 /** Thrown when a restore hook fails or times out; the checkpoint and conversation are untouched. */
 export class CheckpointRestoreError extends Error {
     code = "ERR_PRISM_CHECKPOINT_RESTORE";
-    /** Name of the failing hook (`fn.name` or `hook[i]`). */
+    /** Name of the failing hook (`id`, `hook.name`, or `hook[i]`). */
     hook;
-    constructor(hook, cause) {
+    constructor(hook, cause, compensation) {
         super(`Checkpoint restore hook ${hook} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
         this.name = "CheckpointRestoreError";
         this.hook = hook;
+        if (compensation)
+            this.compensation = compensation;
     }
 }
+/** Compensation reasons are operator hints, not log lines: capped at this many UTF-8 bytes. */
+const MAX_COMPENSATION_REASON_BYTES = 1_024;
+/** One handler identity per restore, resolved once at the executor boundary (plan 109 Task 2). */
+function normalizeRestoreHandler(handler, index) {
+    if (typeof handler === "function")
+        return { id: handler.name || `hook[${index}]`, restore: handler };
+    return {
+        id: handler.id ?? handler.restore.name ?? `hook[${index}]`,
+        restore: handler.restore,
+        ...(handler.compensate ? { compensate: handler.compensate } : {}),
+    };
+}
+/** Run one direction of one handler under the per-hook timeout, reporting failure instead of throwing. */
+async function invokeRestoreHandler(handler, context, timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+    const started = Date.now();
+    try {
+        await handler(context, signal);
+        return { ok: true, durationMs: Date.now() - started };
+    }
+    catch (error) {
+        // Our own abort means the hook either ignored the signal or lost the race; name the timeout.
+        const timedOut = controller.signal.aborted && !callerSignal?.aborted;
+        return { ok: false, cause: timedOut ? controller.signal.reason : error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** UTF-8-safe truncation; no suffix, so the cap is exact. */
+function truncateUtf8Bytes(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    let bytes = 0;
+    let end = 0;
+    for (const char of text) {
+        const size = Buffer.byteLength(char, "utf8");
+        if (bytes + size > maxBytes)
+            break;
+        bytes += size;
+        end += char.length;
+    }
+    return text.slice(0, end);
+}
+/** Redacted, byte-bounded operator hint; hook arguments are never copied into it. */
+function compensationReason(error, redactor) {
+    const message = error instanceof Error ? error.message : String(error);
+    return truncateUtf8Bytes(redactor ? redactor.redact(message) : message, MAX_COMPENSATION_REASON_BYTES);
+}
 /**
- * Run restore hooks sequentially and report the audit. A hook failure throws
- * `CheckpointRestoreError` immediately (later hooks do not run); an already-aborted caller signal
- * throws its own abort reason so the resume reads as cancelled rather than as a restore failure.
+ * Reverse pass over the applied layers (`failedIndex`…0, failing hook first). Best-effort: a
+ * failing compensation is recorded once and the pass continues; a caller abort stops the pass and
+ * rethrows the abort reason unchanged, so a cancel still reads as cancelled.
+ */
+async function compensateRestoreHandlers(handlers, failedIndex, context, timeoutMs, options) {
+    const ran = [];
+    let failed;
+    for (let index = failedIndex; index >= 0; index -= 1) {
+        const handler = handlers[index];
+        if (!handler?.compensate)
+            continue;
+        options.signal?.throwIfAborted();
+        const outcome = await invokeRestoreHandler(handler.compensate, context, timeoutMs, options.signal);
+        options.signal?.throwIfAborted();
+        ran.push(handler.id);
+        if (!outcome.ok && failed === undefined)
+            failed = { hook: handler.id, reason: compensationReason(outcome.cause, options.redactor) };
+    }
+    if (ran.length === 0)
+        return undefined;
+    return { ran, ...(failed ? { failed } : {}) };
+}
+/**
+ * Run restore handlers sequentially and report the audit. A handler failure throws
+ * `CheckpointRestoreError` immediately (later handlers do not run) after a best-effort reverse
+ * compensation pass over the applied layers; with no `compensate` declared anywhere, the failure
+ * shape is exactly plan 094's. An already-aborted caller signal throws its own abort reason so the
+ * resume reads as cancelled rather than as a restore failure, and a caller abort during the pass
+ * stops it before the next handler runs.
  */
 export async function runCheckpointRestoreHooks(hooks, context, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS;
     const started = Date.now();
     const entries = [];
-    for (const [index, hook] of hooks.entries()) {
+    const handlers = hooks.map((handler, index) => normalizeRestoreHandler(handler, index));
+    for (const [index, handler] of handlers.entries()) {
         options.signal?.throwIfAborted();
-        const name = hook.name || `hook[${index}]`;
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
-        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-        const hookStarted = Date.now();
-        try {
-            await hook(context, signal);
-        }
-        catch (error) {
-            // Our own abort means the hook either ignored the signal or lost the race; name the timeout.
-            const timedOut = controller.signal.aborted && !options.signal?.aborted;
-            throw new CheckpointRestoreError(name, timedOut ? controller.signal.reason : error);
-        }
-        finally {
-            clearTimeout(timer);
+        const outcome = await invokeRestoreHandler(handler.restore, context, timeoutMs, options.signal);
+        if (!outcome.ok) {
+            // Security: never run host compensation code once the caller has aborted.
+            const compensation = options.signal?.aborted
+                ? undefined
+                : await compensateRestoreHandlers(handlers, index, context, timeoutMs, options);
+            throw new CheckpointRestoreError(handler.id, outcome.cause, compensation);
         }
-        entries.push({ hook: name, durationMs: Date.now() - hookStarted });
+        entries.push({ hook: handler.id, durationMs: outcome.durationMs });
     }
     return { hooks: entries, durationMs: Date.now() - started };
 }

package/dist/context-budget.d.ts

@@ -96,3 +96,14 @@ export declare function measureInputCost(options: MeasureInputCostOptions): {
     tokens: number;
     bytes: number;
 };
+/** Plan 103 T6: the host's `contextBudget.tokenEstimator`, validated exactly like the budget pass
+ * validates it (a non-function, or a non-finite/negative count, fails closed with `TypeError`).
+ * `undefined` when no host estimator is configured, so callers can fall through to the built-in
+ * heuristic. Exported for the usage seam (`provider-round.ts`) — deliberately not re-exported by
+ * `src/index.ts`, so the public surface is unchanged. */
+export declare function resolveHostTokenEstimator(budget: ContextBudget | undefined): TokenEstimator | undefined;
+/** Plan 103 T6: tool declarations and context blocks projected with the assembler's own
+ * `measureAll` text shapes, so the usage-fallback estimate and the budget pass cannot drift
+ * (never `JSON.stringify` of the raw schemas). Exported for the usage seam — deliberately not
+ * re-exported by `src/index.ts`. */
+export declare function estimateRequestExtrasTokens(tools: readonly ToolDefinition[] | undefined, context: readonly ContextBlock[] | undefined, estimateTokens: TokenEstimator): number;

package/dist/context-budget.js

@@ -246,7 +246,7 @@ function measureAll(groups, context, skills, tools, skillContext, demotedBodies,
     for (const message of groups.toolResults)
         addMessage(message);
     for (const block of context) {
-        const text = `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
+        const text = contextBlockMeasureText(block);
         tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
@@ -256,12 +256,35 @@ function measureAll(groups, context, skills, tools, skillContext, demotedBodies,
         bytes += estimateTextBytes(text);
     }
     if (tools?.length) {
-        const text = `Available tools:\n${tools.map((tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`).join("\n")}`;
+        const text = toolsMeasureText(tools);
         tokens += estimateTokens(text);
         bytes += estimateTextBytes(text);
     }
     return { tokens, bytes };
 }
+/** Plan 103 T6: the host's `contextBudget.tokenEstimator`, validated exactly like the budget pass
+ * validates it (a non-function, or a non-finite/negative count, fails closed with `TypeError`).
+ * `undefined` when no host estimator is configured, so callers can fall through to the built-in
+ * heuristic. Exported for the usage seam (`provider-round.ts`) — deliberately not re-exported by
+ * `src/index.ts`, so the public surface is unchanged. */
+export function resolveHostTokenEstimator(budget) {
+    if (budget?.tokenEstimator === undefined)
+        return undefined;
+    return resolveTokenEstimator(budget);
+}
+/** Plan 103 T6: tool declarations and context blocks projected with the assembler's own
+ * `measureAll` text shapes, so the usage-fallback estimate and the budget pass cannot drift
+ * (never `JSON.stringify` of the raw schemas). Exported for the usage seam — deliberately not
+ * re-exported by `src/index.ts`. */
+export function estimateRequestExtrasTokens(tools, context, estimateTokens) {
+    let tokens = 0;
+    if (context?.length)
+        for (const block of context)
+            tokens += estimateTokens(contextBlockMeasureText(block));
+    if (tools?.length)
+        tokens += estimateTokens(toolsMeasureText(tools));
+    return tokens;
+}
 function overBudget(cost, budget) {
     if (budget.maxInputTokens !== undefined && cost.tokens > budget.maxInputTokens)
         return true;
@@ -342,4 +365,12 @@ function contextBlockText(block) {
     })
         .join("\n");
 }
+/** The context block exactly as `measureAll` measures it (plan 103 T6 shares this shape with the usage seam). */
+function contextBlockMeasureText(block) {
+    return `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
+}
+/** The tool list exactly as `measureAll` measures it (plan 103 T6 shares this shape with the usage seam). */
+function toolsMeasureText(tools) {
+    return `Available tools:\n${tools.map((tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`).join("\n")}`;
+}
 //# sourceMappingURL=context-budget.js.map

package/dist/contracts-core/agent.d.ts

@@ -11,7 +11,7 @@ import type { CompactionOptions, RetryOptions } from "./compaction.js";
 import type { ContentBlock, ErrorInfo, JsonObject, Message, ModelConfig } from "./content.js";
 import type { ProviderRequestPolicy, SystemPromptConfig } from "./extensions.js";
 import type { GuardrailPackRef } from "./guardrail-packs.js";
-import type { AgentLoopOptions, AgentLoopStrategy } from "./loop.js";
+import type { AgentLoopOptions, AgentLoopStrategy, StopHook } from "./loop.js";
 import type { OwnershipScope } from "./persistence.js";
 import type { AIProvider, ProviderRequestOptions, ProviderResolver } from "./provider.js";
 import type { ResourceLoader } from "./resources.js";
@@ -86,11 +86,24 @@ export interface AgentConfig {
      *  Omitted keeps today's request bytes; per-run options may only relax this setting. */
     readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
     /**
-     * Missing-usage fallback (plan 091 T2): `"fallback"` (default) records a labeled
-     * estimate when a provider turn reports no usage; `"off"` leaves usage absent —
-     * never zero. Estimates are marked `Usage.estimated` and are never priced.
+     * Missing-usage handling (plan 091 T2, plan 103 T5): `"fallback"` (default) records a labeled
+     * estimate when a provider turn reports no usage; `"off"` leaves usage absent — never zero;
+     * `"strict"` refuses a usage-less turn instead, failing the run with `code: "usage_missing"`
+     * (`name: "UsageMissingError"`) so a host whose cost gates cannot tolerate approximations never
+     * runs on an estimate. A refusal is a harness decision, not a provider failure, so it carries no
+     * `failureClass` and is never retried. Estimates are marked `Usage.estimated` and never priced.
      */
-    readonly usageEstimation?: "fallback" | "off";
+    readonly usageEstimation?: "fallback" | "off" | "strict";
+    /**
+     * Session-turn context budget (plan 103 T6): forwarded to every `assembleProviderInput`
+     * call this agent's sessions make, so a session gets the same eviction, `tokenEstimator`,
+     * and `reportOmissions` semantics as a direct assembler caller. Mutually exclusive with
+     * `attentionCompiler` (rejected at assembly). With `usageEstimation: "fallback"`, the
+     * missing-usage estimate prefers this budget's own measurement: the request's
+     * `ContextBudgetReport.keptTokens` when `reportOmissions` is on, else the `tokenEstimator`
+     * projection — see [Runs and usage](../../docs/runs-and-usage.md).
+     */
+    readonly contextBudget?: import("../context-budget.js").ContextBudget;
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -124,6 +137,8 @@ export interface AgentConfig {
     readonly inputLayout?: InputAssemblyLayout;
     readonly loop?: AgentLoopStrategy | AgentLoopOptions;
     readonly guardrails?: Guardrails;
+    /** Run-end stop hooks (plan 106 R1); `RunOptions.stopHooks` appends to this list. */
+    readonly stopHooks?: readonly StopHook[];
     /** Opt-in durable interruption/checkpointing default for this agent. */
     readonly runState?: AgentRunStateOptions;
     /** Internal marker set by createSecureAgent(); makes security defaults immutable per run. */
@@ -183,6 +198,12 @@ export interface AgentSessionCloneOptions {
 }
 export type SubscriberOverflowPolicy = "close" | "drop_oldest" | "drop_newest";
 export interface SubscribeOptions {
+    /**
+     * Plan 104 T5: `true` keeps this subscriber open across runs of the same session; it is then
+     * closed only by the host (`subscription.close()` / `session.closeSubscribers()`) or by an
+     * overflow under the default `close` policy. Default `false` (closed at run end).
+     */
+    readonly acrossRuns?: boolean;
     /** Maximum queued events for a subscriber that is not actively awaiting `next()`. Defaults to 1024. */
     readonly maxQueuedEvents?: number;
     /** What to do when `maxQueuedEvents` is reached. Defaults to `close`. */

package/dist/contracts-core/extensions.d.ts

@@ -7,6 +7,7 @@ import type { Middleware, MiddlewareHookName, MiddlewareRegistry } from "../midd
 import type { AgentDefinition, CommandDefinition, ContextProvider, InputBuilder, InstructionInjector, PromptBuilder, Skill } from "./agent.js";
 import type { CompactionStrategy, RetryPolicy } from "./compaction.js";
 import type { ErrorInfo, ModelConfig } from "./content.js";
+import type { StopHook } from "./loop.js";
 import type { StoreFactory } from "./persistence.js";
 import type { AIProvider, ProviderRequest } from "./provider.js";
 import type { Credential, CredentialResolver, ResourceLoader, SettingsProvider } from "./resources.js";
@@ -160,4 +161,6 @@ export interface ExtensionAPI {
     registerProviderRequestPolicy(policy: ProviderRequestPolicy): void;
     registerSystemPromptContribution(contribution: SystemPromptContribution): void;
     registerInstructionInjector(injector: InstructionInjector): void;
+    /** Contributes an inert run-end stop hook; activate it via `activateKernel()` → `AgentConfig.stopHooks` (plan 106 R1). */
+    registerStopHook(hook: StopHook): void;
 }

package/dist/contracts-core/guardrail-packs.d.ts

@@ -1,10 +1,10 @@
 /**
  * Guardrail packs (plan 092 Task 2): config-declared, restrictive-only rule sets compiled once per
  * session onto the existing tool interception seams (`tool_input` / `tool_output`). Packs can only
- * deny or tripwire — they never grant permissions, widen arguments, or add a stage.
+ * deny, tripwire, or ask for approval — they never grant permissions, widen arguments, or add a stage.
  */
 import type { JsonObject } from "./content.js";
-export type GuardrailRuleAction = "deny" | "tripwire";
+export type GuardrailRuleAction = "deny" | "tripwire" | "ask";
 /** Read-only identity view handed to a pack rule predicate (never carries a raw argument echo). */
 export interface GuardrailRuleContext {
     readonly toolName: string;
@@ -25,7 +25,12 @@ export interface GuardrailRule {
     readonly argPath?: string | readonly string[];
     /** Typed predicate escape hatch (host-trusted like all host code); deny when it returns true. Exactly one of `pattern` / `deny`. */
     readonly deny?: (args: JsonObject, context: GuardrailRuleContext) => boolean;
-    /** Defaults to `deny`; `tripwire` also rejects the enclosing run. `ask` has no deterministic seam (plan 092 Task 1). */
+    /**
+     * Defaults to `deny`. `tripwire` also rejects the enclosing run. `ask` suspends a durable run
+     * before the call dispatches (the pending decision names this rule) and blocks the call in a run
+     * that cannot suspend; it requires `pattern` — an opaque predicate cannot raise an approval
+     * (plan 104 Task 3).
+     */
     readonly action?: GuardrailRuleAction;
     /** Bounded, redacted record reason; defaults to the pack/rule id. */
     readonly reason?: string;

package/dist/contracts-core/loop.d.ts

@@ -46,6 +46,36 @@ export interface TurnPolicyOptions {
      */
     readonly stop?: (context: TurnBoundaryContext) => TurnStopDecision;
 }
+/**
+ * Run-end stop-hook contract (plan 106 R1). Stop hooks run at a natural loop end — never after a
+ * loop ceiling, a host turn-policy stop, or an artifact failure — and decide whether the run is
+ * done. The first `continue` queues `reason` (plus optional `steer`) through the same steer path a
+ * host would use and re-enters the loop; `stop` (or no hook continuing) ends the run normally.
+ */
+export interface StopHookContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    /** Provider turns already assembled in this run (resumption continues the run's counter). */
+    readonly turn: number;
+    /** Live transcript at loop end; hooks read it, never mutate it. */
+    readonly history: readonly Message[];
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+    /** True on every invocation after the first continuation in this run (Claude Code `stop_hook_active`). */
+    readonly stopHookActive: boolean;
+}
+/** `continue` re-enters the loop with `reason` queued as a steer (optional extra `steer` message follows it). */
+export type StopHookDecision = {
+    readonly action: "stop";
+} | {
+    readonly action: "continue";
+    readonly reason: string;
+    readonly steer?: string | Message;
+};
+export interface StopHook {
+    readonly name: string;
+    decide(context: StopHookContext): StopHookDecision | Promise<StopHookDecision>;
+}
 export interface LoopContext {
     readonly sessionId: string;
     readonly runId: string;
@@ -54,6 +84,12 @@ export interface LoopContext {
     readonly history: Message[];
     readonly input: AgentInput;
     readonly inputMessages: readonly Message[];
+    /**
+     * True when this `run()` call is a stop-hook continuation re-entry (plan 106 R1): `input` and
+     * `inputMessages` are empty because the continuation message is already in `history`. Custom
+     * strategies must not replay run-start input when this is set.
+     */
+    readonly continuation?: boolean;
     readonly maxToolRounds: number;
     /**
      * Why the loop stopped, when a limit/ceiling ends the run cleanly (F4). Strategies set

package/dist/contracts-core/provider.d.ts

@@ -74,8 +74,13 @@ export type ProviderStopReason = "end_turn" | "tool_calls" | "max_output_tokens"
  * axis, so a host can see which limit was closest without instrumenting the session.
  */
 export interface TurnBudgets {
-    /** Provider-reported input tokens for this turn; absent when the provider reported none. */
+    /** Input tokens charged for this turn: provider-reported, or a labeled fallback estimate when the
+     *  provider reported none; absent when neither exists. See `inputTokensSource`. */
     readonly inputTokens?: number;
+    /** Provenance of `inputTokens`: `"reported"` from the provider, `"estimated"` from the
+     *  `usageEstimation: "fallback"` seam. Absent together with `inputTokens`; `usage.estimated` stays
+     *  the authoritative label for the turn's usage. */
+    readonly inputTokensSource?: "reported" | "estimated";
     /** Resolved per-request input cap (attention compiler when enabled); absent when no cap derivable. */
     readonly inputCap?: number;
     /** Cumulative run input budget (`RunLimits.maxInputTokens`); absent when the axis is disabled. */

package/dist/contracts-core/run-limits.d.ts

@@ -22,6 +22,12 @@ export interface RunLimits {
         readonly amount: number;
         readonly currency: string;
     };
+    /**
+     * Clean cap on stop-hook continuations in one run (plan 106 R1). Default 3; `0` observes stop
+     * hooks but never continues; `null` disables the cap. Layers narrow by min like every other
+     * policy axis, and the cap ends the run with `stopReason: "hook_limit"` (no limit breach).
+     */
+    readonly maxStopContinuations?: number | null;
 }
 /** Fully resolved limits after `resolveRunLimits`: every policy axis is a finite cap or `null` (disabled). */
 export interface ResolvedRunLimits {
@@ -39,8 +45,11 @@ export interface ResolvedRunLimits {
         readonly amount: number;
         readonly currency: string;
     };
+    /** Stop-hook continuation cap (plan 106 R1); not a run-limit counter axis. */
+    readonly maxStopContinuations: number | null;
 }
-export type RunLimitName = keyof Required<RunLimits>;
+/** Counter-backed limit axes; `maxStopContinuations` caps a clean stop instead of a breach. */
+export type RunLimitName = Exclude<keyof Required<RunLimits>, "maxStopContinuations">;
 export interface RunLimitCounters {
     readonly turns: number;
     readonly providerAttempts: number;

package/dist/contracts-core/session.d.ts

@@ -30,7 +30,8 @@ export interface SessionStore {
     get?(id: string): Promise<SessionEntry | undefined>;
     /** DB-friendly branch read: return one branch's ancestor chain as a page so adapters
      *  avoid `list(sessionId)` (full-session scan) + in-memory rebuild. Optional — the
-     *  built-in memory/JSONL stores omit it and the runtime falls back to `list()`. */
+     *  built-in JSONL store omits it and the runtime falls back to `list()`. The memory
+     *  store implements it. */
     readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;
     /**
      * Optional bounded session search. Prefer implementing this **or** returning a companion

package/dist/contracts-protocol.d.ts

@@ -1,6 +1,6 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, BudgetAxisUsage, BudgetConsumedCounters, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, ProviderStopReason, RetryOptions, RunLimitBreach, RunLimitName, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, ToolCallSummary, TurnBudgets, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { CacheUsageReport } from "./cache-helpers.js";
 import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, BudgetAxisUsage, BudgetConsumedCounters, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, ProviderStopReason, RetryOptions, RunLimitBreach, RunLimitName, RunLimits, Skill, StopHook, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, ToolCallSummary, TurnBudgets, TurnPolicyOptions, Usage } from "./contracts-core.js";
 import type { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -137,6 +137,8 @@ export interface RunOptions {
      * evaluated before every provider request. Omitted → no callback runs.
      */
     readonly turnPolicy?: TurnPolicyOptions;
+    /** Appended to agent-level stop hooks for this run (plan 106 R1). */
+    readonly stopHooks?: readonly StopHook[];
 }
 export interface ProviderTurnMetadata {
     readonly providerId: string;
@@ -193,8 +195,8 @@ export interface DelegatedAgentStep {
         readonly label?: string;
     };
 }
-/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop; the rest are loop ceilings (F4). */
-export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy";
+/** Why a run stopped cleanly. `host_policy` is a `RunOptions.turnPolicy` stop, `hook_limit` a stop-hook continuation cap; the rest are loop ceilings (F4). */
+export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal" | "host_policy" | "hook_limit";
 /**
  * Origin of an agent event forwarded from a delegated child (supervisor child-event passthrough).
  * Present only on child events routed onto a parent stream; absent on a session's own events.
@@ -215,7 +217,7 @@ type AgentEventPayload = {
     readonly sessionId: string;
     readonly runId: string;
     readonly usage?: Usage;
-    /** Why the loop stopped, when a limit/ceiling or a host turn policy ended the run cleanly (F4). Absent = natural end. */
+    /** Why the loop stopped, when a limit/ceiling, a host turn policy, or a stop-hook continuation cap ended the run cleanly (F4). Absent = natural end. */
     readonly finishReason?: AgentFinishReason;
     /** Host stop detail from `TurnPolicyOptions.stop` (≤256 bytes, redacted). Present only with `finishReason: "host_policy"`. */
     readonly stopDetail?: string;

package/dist/contracts-run-state.d.ts

@@ -1,6 +1,7 @@
-import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
+import type { CheckpointRestoreHandler } from "./checkpoint-restore.js";
+import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointRecord, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ContextMeter, ErrorInfo, GuardrailPackRef, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
 import type { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
-import type { CheckpointRestoreHook } from "./checkpoint-restore.js";
+import type { BudgetExhaustionAttribution } from "./run-limits.js";
 export type AgentRunStatus = "succeeded" | "failed" | "aborted" | "suspended" | "denied";
 export type AgentRunInterruptionKind = "input_guardrail" | "tool_approval" | "elicitation";
 export type ApprovalOutcome = "allow_once" | "allow_for_run" | "reject_once" | "reject_for_run";
@@ -27,6 +28,16 @@ export interface PendingDecision {
     readonly reason: string;
     /** Typed payload contract for elicitation decisions. */
     readonly elicitationSchema?: JsonObject;
+    /**
+     * Plan 104 T3: pack `ask` rule that gated this call as `pack:<pack>/<rule>` (bounded by the
+     * compile-time id limits), present only when a pack rule raised the decision.
+     */
+    readonly guardrail?: string;
+    /** Plan 104 T3: machine-readable ids behind `guardrail`, so a host never parses the name. */
+    readonly guardrailRule?: {
+        readonly pack: string;
+        readonly rule: string;
+    };
     /** Delegation chain, root-first; core-written, never client-supplied. */
     readonly attribution?: {
         readonly path: readonly string[];
@@ -38,6 +49,8 @@ export interface AgentRunInterruption {
     readonly reason: string;
     readonly toolCallId?: string;
     readonly toolName?: string;
+    /** Plan 104 T3: the pack rule that raised this suspension (`pack:<pack>/<rule>`), when one did. */
+    readonly guardrail?: string;
     /** All unresolved approval requests of this suspension; absent for legacy single approvals. */
     readonly pendingDecisions?: readonly PendingDecision[];
 }
@@ -235,8 +248,8 @@ export interface AgentCheckpointRestoreContext {
     readonly metadata?: AgentRunCheckpointMetadata;
     readonly checkpoint: CheckpointRecord;
 }
-/** Host code restoring one external layer before a durable resume applies. */
-export type AgentCheckpointRestoreHook = CheckpointRestoreHook<AgentCheckpointRestoreContext>;
+/** Host code restoring or compensating one external layer before a durable resume applies. */
+export type AgentCheckpointRestoreHook = CheckpointRestoreHandler<AgentCheckpointRestoreContext>;
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
     /** Current host-authored revision; must exactly match the checkpoint. */
@@ -266,7 +279,9 @@ export interface AgentRunResumeOptions {
      * Plan 094 Task 3: external-state restore hooks. Every hook must succeed (sequentially, each
      * within `restoreHookTimeoutMs`) before the claim write and the conversation restore apply;
      * the first failure throws `CheckpointRestoreError` naming the hook and leaves the checkpoint
-     * suspended. Hosts that register hooks on the lifecycle instead pass them once there.
+     * suspended. Plan 109 Task 2: an entry may be `{ id?, restore, compensate? }`, and on failure the
+     * applied layers are compensated in reverse order (best-effort) before the throw. Hosts that
+     * register hooks on the lifecycle instead pass them once there.
      */
     readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
     /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
@@ -313,6 +328,11 @@ export interface AgentRunResult {
     readonly usage?: Usage;
     /** Present when the run hit a configured resource ceiling. */
     readonly limit?: RunLimitBreach;
+    /**
+     * Present with `limit` when the run died on a ceiling: the same plan-087 attribution payload the
+     * `budget_exhausted` event carries (`limit` stays on {@link AgentRunResult.limit}).
+     */
+    readonly attribution?: BudgetExhaustionAttribution;
     /** Present when `status` is `"failed"` or when a failed attempt still produced partial output. */
     readonly error?: ErrorInfo;
     /** String form of the abort reason when `status` is `"aborted"`. */
@@ -350,6 +370,12 @@ export interface SteerOptions {
 }
 export interface AgentSession {
     readonly id: string;
+    /**
+     * Plan 104 Task 2: guardrail pack refs this session enforces (the restored rows after a durable
+     * resume); `undefined` when it enforces none. Pass to `snapshotRunBundle({ packs })` for the
+     * recorded identity that matches enforcement.
+     */
+    readonly guardrailPackRefs?: readonly GuardrailPackRef[];
     /** Current branch leaf entry id; advances on every append/run and is re-pointed by `checkout`.
      *  Undefined until the first entry lands (a fresh session with no history). */
     readonly leafId: string | undefined;
@@ -361,10 +387,26 @@ export interface AgentSession {
      * Fails closed when no run is active or the pending queue exceeds caps.
      */
     steer(input: string | Message | readonly Message[], options?: SteerOptions): void;
-    /** Subscribe first, then start exactly one run and yield only that run's events until it terminates. */
+    /**
+     * Subscribe first, then start exactly one run and yield only that run's events until it terminates.
+     * This subscription belongs to `stream()`: it is closed when the owned run settles (so a pre-flight
+     * rejection unblocks the consumer instead of parking it behind a run that never emits).
+     */
     stream(input: string | Message | readonly Message[], options?: RunOptions & SubscribeOptions): AsyncIterable<AgentEvent>;
     compact(options?: CompactionOptions): Promise<CompactionResult>;
+    /**
+     * Subscribe to this session's live events. A run-scoped subscriber (default) is closed when the run
+     * ends, suspends, or is denied; `SubscribeOptions.acrossRuns: true` keeps it open across runs until
+     * `subscription.close()`, `closeSubscribers()`, or a queue overflow closes it.
+     */
     subscribe(options?: SubscribeOptions): AsyncIterable<AgentEvent>;
+    /**
+     * Plan 106 R2: session teardown. Dispatches `session_shutdown` middleware once (idempotent), then
+     * closes every subscriber (`acrossRuns` included); calling it twice is a no-op. Call after the
+     * active run settles. Subscriber-only teardown stays `break`ing the `for await` (or calling the
+     * iterator's `return()`). See [Agent/session runtime](agent-session-runtime.md).
+     */
+    close(): Promise<void>;
     abort(reason?: unknown): void;
     entries(): Promise<readonly SessionEntry[]>;
     checkout(leafId?: string): Promise<void>;

package/dist/contributions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentDefinition, AuthMethod, CommandDefinition, CompactionStrategy, ContextProvider, CredentialResolver, DiscoveredContribution, InputBuilder, InstructionInjector, PromptBuilder, ProviderPackage, ProviderRequestPolicy, ResourceLoader, RetryPolicy, SettingsProvider, Skill, StoreFactory, SystemPromptContribution, ToolDefinition } from "./contracts.js";
+import type { AgentDefinition, AuthMethod, CommandDefinition, CompactionStrategy, ContextProvider, CredentialResolver, DiscoveredContribution, InputBuilder, InstructionInjector, PromptBuilder, ProviderPackage, ProviderRequestPolicy, ResourceLoader, RetryPolicy, SettingsProvider, Skill, StopHook, StoreFactory, SystemPromptContribution, ToolDefinition } from "./contracts.js";
 import { type ModelRegistry } from "./models.js";
 import { type ProviderRegistry } from "./providers.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
@@ -35,6 +35,7 @@ export interface ContributionRegistries {
     readonly providerRequestPolicies: ContributionRegistry<ProviderRequestPolicy>;
     readonly systemPromptContributions: ContributionRegistry<SystemPromptContribution>;
     readonly instructionInjectors: ContributionRegistry<InstructionInjector>;
+    readonly stopHooks: ContributionRegistry<StopHook>;
 }
 export interface ContributionRegistriesOptions extends DuplicateRegistrationOptions {
 }

package/dist/contributions.js

@@ -49,6 +49,7 @@ export function createContributionRegistries(options = {}) {
         providerRequestPolicies: createContributionRegistry(registryOptions("provider request policy")),
         systemPromptContributions: createContributionRegistry(registryOptions("system prompt contribution")),
         instructionInjectors: createContributionRegistry(registryOptions("instruction injector")),
+        stopHooks: createContributionRegistry(registryOptions("stop hook")),
     };
 }
 /** Register discovered contributions into the given registries. Inert: skill