@arnilo/prism 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,4 +1,65 @@
-## [Unreleased]
+## [0.10.0] - 2026-09-21 (hook lifecycle completion, scoped agent memory)
+
+> **Twelve publishable packages.** All 105–106 features ship behind their documented options and defaults: `@arnilo/prism-hooks` is the new twelfth package, and scoped memory is an opt-in subpath that does nothing until a host constructs it. Predecessor published line is **0.9.0**. Plans 097 (trajectory export) and 107 (behavior/graft removals) were not implemented for this line and are deferred rather than held unstarted against the cut. Registry/tag writes stay operator-authorized.
+
+### Added
+- **Scoped persistent memory (`@arnilo/prism-memory/scoped`).** New opt-in subpath: `createScopedMemoryPolicy({ memory, fabric, scopeRoot, policy })` is a policy and lifecycle layer over stores the host already configured (no fifth store). Create is inert and fails closed unless `scope.resourceId` equals the resolved `scopeRoot` and a `threadId` is set; the read path oversamples `fabric.recall`, applies an abstain floor (`activation.minSimilarity` 0.35) and activation budget (`topK` 3), ranks by `fabricScore × exp(−ageDays/tauDays) × (1 + ln(1 + uses))` (`tauDays` 30), and returns `{ hits: [], abstained: true }` rather than a weak hit. Writes go through a conservative post-run reviewer (`reviewSession`, strict JSON, garbage → zero writes), land as `candidate` records, and flip to `verified` after `promotion.reuseThreshold` (2) successful recalls — ledger status only, no fabric rewrite. `gcPass()` proposes archives onto `pending()` and never deletes (`legal_hold` skipped), `rememberFact` keeps a bounded working block (`maxChars` 2200, overflow throws `MemoryLimitError` with `consolidate first`), an injection scan plus an optional staged approval gate (`approval.default: "off"`) guard content, and a deterministic git audit mirror renders notes. State lives in one JSON ledger at `<scopeRoot>/.memory/state.json` (ids, counters, timestamps — never note content). Sizing: one reviewer call per run, one ledger read plus one write per recall, no model calls on the read path. See [docs/scoped-memory.md](docs/scoped-memory.md).
+- **Scoped memory evaluation and health.** `runScopedMemoryEval` runs a win-rate A/B (with/without scoped memory) over a host-provided task set, `probePrecisionAt3` and `probeLocomoRecall` score the read path, `scopedMemoryHealth` reports counts plus conversion/activation/duplication rates, and `createScopedMemoryHealthCommand` exposes the same numbers as a command. See [docs/scoped-memory.md](docs/scoped-memory.md).
+- **Stop hooks with bounded continuation.** `AgentConfig.stopHooks` / `RunOptions.stopHooks` run at the natural end of an agent loop with a `StopHookContext` (session and run ids, turn, redacted history, `stopHookActive`) and answer `{ action: "stop" }` or `{ action: "continue", reason }`; a continuation re-enters the loop with the reason queued as the next turn's steer — run-start input is never replayed — and `RunLimits.maxStopContinuations` (default 3, `0` disables, `null` uncaps) ends the run cleanly with the new `hook_limit` finish reason, which `checkpointPolicy: "every-turn"` leaves resumable. Extensions register hooks with `ExtensionAPI.registerStopHook()`. See [docs/hooks.md](docs/hooks.md).
+- **Agent-event bridge and session lifecycle hooks.** `forwardAgentEvents(source, events, options?)` keeps the extension bus in step with a run (`agent_started` → `before_agent_start`, `turn_started` / `turn_finished` → `turn`, `tool_execution_started` → `tool_call`, `tool_execution_finished` → `tool_result`), delivering in event order with the original event as the read-only payload and never rethrowing into the run; core emits `session_start` once per session (durable resumes included) and `session_shutdown` on the new idempotent `AgentSession.close()`. See [docs/extensions.md](docs/extensions.md), [docs/middleware-hooks.md](docs/middleware-hooks.md).
+- **Pre-compaction rewrite seam.** The `compaction_request` middleware hook runs after `compaction_started` and before the strategy, so a handler returns the `CompactionContext` the strategy actually compacts (entries and budget) and the following `compaction` hook plus `compaction_finished` event report that result. See [docs/middleware-hooks.md](docs/middleware-hooks.md).
+- **`@arnilo/prism-hooks`, the hooks-file adapter.** New twelfth publishable package: `parseHooksConfig(text | object)` accepts the Claude flat and Codex `{ "hooks": { … } }` shapes, and `createHooksExtension(config, options)` compiles them onto public seams — `SessionStart` / `UserPromptSubmit` `additionalContext` through an instruction injector, `UserPromptSubmit` / `PreToolUse` / `PostToolUse` guardrails for denies, `tool_call` / `tool_result` middleware for `updatedInput` and post-tool context, and `Stop` onto stop hooks. Handlers are `command` (spawned shell-free, hash-pinned with `hookCommandHash()`) or `mcp_tool` (host-provided client, `${field.path}` templates), with seconds-based `timeout`, per-handler `additionalContextLimit` (default 2500 tokens, spilling to `<tempdir>/hook_outputs/`), and Codex's `continue: false` read as the stop signal. See [docs/hooks.md](docs/hooks.md).
+- **Unified hook map.** [docs/hooks.md](docs/hooks.md) is the owning page for the hook model: the five families (transform, decide, inject, run-end control, observe), one row per Claude Code / Codex event mapped to its Prism surface or a documented non-goal with rationale (`PermissionRequest` stays host policy), the adapter reference, and migration steps from an existing `hooks.json` config.
+- **Examples.** `examples/scoped-memory.ts` (scope guard → facts overflow → reviewer → abstain/hit recall → promotion → GC approval → mirror), `examples/hooks-json.ts` (a declarative `hooks.json` compiled onto guardrails, injectors, and stop hooks), and `examples/hooks-audit-command.mjs` (an audit-trail command handler).
+
+### Changed
+- **Lockstep `0.9.0` → `0.10.0`.** All twelve publishable manifests move together with `^0.10.0` internal ranges; the lockfile, the `src/index.ts` version constant, the docs index banner, the release-workflow tag lists, and the generated package-truth artifact agree (enforced by `scripts/version-literal-gate.test.mjs`).
+- **Compat baselines regenerated at 0.10.0**: `+47` public names with **zero removals**, zero renames, and zero signature breaks (`@arnilo/prism` +6, `@arnilo/prism-memory` +41, `@arnilo/prism-hooks` new at 34). The only consumer-visible type addition is `AgentSession.close()`; see [docs/migration.md](docs/migration.md).
+- **Budgets rebaselined with recorded reasons**: export ceilings `@arnilo/prism` 1456, `@arnilo/prism-memory` 934, `@arnilo/prism-hooks` 34, plus the non-null assertion ratchet; the root artifact diet is unchanged this cut.
+- **Coverage thresholds gained the new package's row** (`@arnilo/prism-hooks` 84.7 / 78.67 / 90), so the coverage summary fails closed on a new package instead of passing silently.
+- **Migration notes for 0.9.0 hosts**: [docs/migration.md](docs/migration.md) — the `AgentSession.close()` addition, `session_start` / `session_shutdown` now being emitted, the new `hook_limit` finish reason, the `maxStopContinuations` default, and the opt-in scoped-memory subpath.
+
+### Security
+- **Stop hooks and the hooks-file adapter fail closed.** `StopHook` entries are validated at run start (`name` plus `decide`), a malformed decision or a throwing handler is a non-blocking error that never silently allows a stop, `maxStopContinuations` (default 3) bounds continuation loops, and the adapter's `command` handlers spawn shell-free with tokenized argv and a `hookCommandHash()` trust pin. Codex's `continue: false` reads as the stop signal, not a continuation.
+- **Scoped memory never widens access and never deletes.** Create fails closed on a scope mismatch, unknown policy fields are ignored and invalid values fail closed, recall abstains below the floor, GC only proposes, `legal_hold` is skipped, the ledger stores no note content, and the mirror is deterministic.
+
+## [0.9.0] - 2026-09-20 (attention budget axes, turn traces, cache-stable disclosure, tool narrowing, guardrail packs, background agents, session search, deterministic turns, shared scopes)
+
+> **Eleven publishable packages.** All 086–098 features ship behind their documented options, joined by the live-stream terminal fix (plan 100). Predecessor published line is **0.8.0**. Registry/tag writes stay operator-authorized.
+
+### Added
+- **Attention budget axes and durable folding.** `attentionCompiler.trigger` accepts `input_ratio` (the legacy axis), `run_input_ratio` (fires against `RunLimits.maxInputTokens` instead of the model window), `token_floor`, and a host predicate, alone or as an any-of array; `attentionCompiler.durable: true` writes the fold ledger and sticky frontier into the checkpoint so a resumed run keeps its stubs. See [docs/attention-compiler.md](docs/attention-compiler.md).
+- **Turn traces and exhaustion attribution.** `provider_turn_finished` carries a closed `stopReason` taxonomy, a `budgets` snapshot, the effective tool menu (`tools.count` / `tools.idsHash`), and provider-reported cache counts with a per-turn `hitRate`; `agent_finished` carries `finishReason` / `stopDetail`, `AgentRunResult.stopReason` names host-policy and loop-ceiling stops, and the execution timeline adds `turns[i].stopReason` plus `timeline.exhaustion`. See [docs/agent-events.md](docs/agent-events.md), [docs/execution-timeline.md](docs/execution-timeline.md).
+- **Cache-stable progressive disclosure and cache metrics.** Skill bodies, deferred tool schemas, and loaded references land at cache-stable positions (append-only tail or explicit invalidation); cache read/write tokens and per-turn hit rate are recorded on usage records and turn events. See [docs/provider-caching.md](docs/provider-caching.md), [docs/prefix-stability-conformance.md](docs/prefix-stability-conformance.md).
+- **Per-turn tool narrowing.** `AgentConfig.toolNarrowing` / `RunOptions.toolNarrowing` returns the effective tool subset before each provider turn; out-of-grant names are dropped and reported on `tool_narrowing_clamped`. See [docs/tools.md](docs/tools.md).
+- **Usage estimation and the context meter.** `estimateMessageTokens` / `MODEL_FAMILY_TOKENS` / `resolveModelFamily` produce labeled `TokenEstimate`s, `AgentConfig.usageEstimation: "fallback"` (default) charges one labeled estimate for usage-less providers, and `session.contextMeter()` exposes `{ inputTokens, source, inputCap?, runInputBudget?, usedRatio? }`. See [docs/runs-and-usage.md](docs/runs-and-usage.md).
+- **Execution guardrail packs.** `guardrailPacks` compiles four built-in restrictive rule sets (`coding-standard`, `destructive-commands`, `validation-respect`, `secrets-hygiene`) onto existing tool stages, each with a trajectory scorer (`createGuardrailPackScorer`). See [docs/guardrails.md](docs/guardrails.md).
+- **Background child agents and child-event passthrough.** `lifetime: "session"`, `report: "on-complete" | "milestones" | "stream"`, `milestone`, and `budgetShare` on `delegate` / `delegateAsync` / `spawn_agent`, with `child_milestone`, `child_failed`, and rate-coalesced child events. See [docs/supervisors.md](docs/supervisors.md), [docs/multi-agent-patterns.md](docs/multi-agent-patterns.md).
+- **Checkpoint sidecar metadata and restore hooks.** A redacted ≤4 KB `checkpointMetadata` map rides every checkpoint record without charging `maxStateBytes`, and `restoreHooks` revert external layers before a resume claims the run. See [docs/durable-runs.md](docs/durable-runs.md).
+- **Bounded workspace session search.** `SessionStore.searchSessions?(query)` over workspace/time/provider/label/kind/ownership filters with an indexed full-text path (SQLite FTS5, Postgres `tsvector`, migration 004) and a shared linear matcher for memory and JSONL stores. See [docs/session-stores.md](docs/session-stores.md).
+- **Deterministic no-model turns.** The `beforeProviderTurn` middleware hook answers a turn from host data (`BeforeProviderTurnPayload` → `DeterministicTurnAnswer`) with no provider request, recorded as `deterministic` on the timeline and graded by `createDeterministicTurnScorer`. See [docs/middleware-hooks.md](docs/middleware-hooks.md).
+- **Shared work scopes for observational memory.** `sharedScopes` at attach time plus owner-branch grants (`grant` / `revoke`) let granted sessions contribute to and read one scope, with deny-by-default rechecks, `onScopeAccess` auditing, and revocation at the next read. See [docs/compaction-observational-memory.md](docs/compaction-observational-memory.md).
+- **Retrieval revocation and a zero-service default reranker.** `createDeletionPropagator` (+ `collectInvalidationIds` / `listInvalidatedIds`, `repointSource`, `retireWikiSources`, RAG/wiki handlers) propagates deletion and revocation through derived artifacts, `createAccessRecheck` rechecks governed sources per query, and `resolveReranker({ kind: "local" })` / `createLocalReranker()` run an in-process cross-encoder behind the `LocalRerankRuntime` seam with no declared inference dependency. See [docs/rag.md](docs/rag.md), [docs/embeddings.md](docs/embeddings.md).
+- **Examples.** `examples/attention-budget-axes.ts`, `examples/tool-narrowing-planes.ts`, `examples/session-search.ts`.
+
+### Changed
+- **Lockstep `0.8.0` → `0.9.0`.** All eleven publishable manifests move together with `^0.9.0` internal ranges; the lockfile, the `src/index.ts` version constant, the docs index banner, the release-workflow tag lists, and the generated package-truth artifact agree (enforced by `scripts/version-literal-gate.test.mjs`).
+- **A limit death no longer ends a stream early.** The terminal set is exactly `agent_finished` / `agent_denied` / `error`, decided by one exported `isTerminalAgentEventType` predicate shared by the memory, NATS, and Postgres sources, AG-UI replay, the A2A stream break, AG-UI `filterRun`, and conversation replay; `run_limit_exceeded` → `budget_exhausted` → `error` now reaches page, subscribe, and replay consumers in order. See [docs/migrate-to-0.9.md](docs/migrate-to-0.9.md).
+- **Usage-less providers are charged a labeled estimate by default.** `AgentConfig.usageEstimation: "fallback"` records one `TokenEstimate` (`estimated: true` + `confidence`) at the existing usage seam; reported usage always wins, and `"off"` keeps the previous zero-for-no-usage behavior.
+- **Compat baselines regenerated at 0.9.0**: `+119` public names with **zero removals** and zero renames (`@arnilo/prism` +49, `@arnilo/prism-memory` +60, `@arnilo/prism-core` +10). One type-level consumer change: the `recordUsage` callback of `generateProviderTurn` / `generateWithRetry` returns `Promise<Usage | undefined>` instead of `Promise<void>`.
+- **Budgets rebaselined with recorded reasons**: root packed/unpacked/file count, per-package export ceilings, and the non-null assertion ratchet carry the measured 0.9.0 values and the plans that moved them.
+- **Migration guide for 0.8.0 hosts**: [docs/migrate-to-0.9.md](docs/migrate-to-0.9.md) — four behavior changes inside existing surfaces, every new option with defaults and sizing lines, upgrade steps, and rollback — indexed from [docs/migration.md](docs/migration.md) and [docs/index.md](docs/index.md).
+
+### Fixed
+- **Streams ended one record early on a run-limit death.** In-memory, NATS, Postgres, and AG-UI replay consumers treated `run_limit_exceeded` as terminal, so a subscriber that stopped at the first breach record never saw the `budget_exhausted` attribution or the terminal `error` (`assertAgentEventSourceConforms` now asserts the delivery order against every source implementation).
+- **Attention folding was inert when the run input cap sat below the model window.** The new `run_input_ratio` axis evaluates cumulative run spend plus the assembled request, so a 500k run cap under a 1M-window model folds instead of dying at the cap.
+- **Unindexed session search could scan an unbounded store.** Memory and JSONL stores share `searchLinearSessions` with contract linear caps, overridable only within their hard bounds.
+
+### Security
+- **Guardrail packs fail closed on secrets and destructive commands.** `secrets-hygiene` scans tool arguments for credential shapes, `destructive-commands` matches shell commands, and `coding-standard` keeps edits inside `options.roots`; every pack is restrictive-only, so a pack can never widen a host policy. Cap: 8 packs, 64 rules per pack.
+- **Shared-scope access is deny-by-default and audited.** Absent, unknown, revoked, unreachable, or not-opened-locally scope state denies the read, every decision reaches `onScopeAccess`, revocation lands on the next read, and the host `entries(sessionId)` callback stays inside one `OwnershipScope`.
+- **Checkpoint metadata and restore hooks are redacted and bounded.** The sidecar map is redacted unconditionally (no public-key exemption) and capped at 4 KiB; a failing or timed-out restore hook aborts the restore rather than claiming the run.
+- **Estimates can never masquerade as provider truth.** Every estimated token count carries `estimated: true` (and `confidence`), reported usage is never overwritten, and estimates never produce a price — a configured `maxCost` stays the fail-closed envelope.
 
 ## [0.8.0] - 2026-09-18 (messaging channels, connected apps, work family, durable runs, honesty gates)
 

package/README.md

@@ -158,21 +158,22 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 ## Packages
 
 <!-- generated:package-truth:inventory begin -->
-**11 publishable manifests** — root `@arnilo/prism` plus 10 workspace packages (4 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
+**12 publishable manifests** — root `@arnilo/prism` plus 11 workspace packages (4 `prism-*` family packages, 7 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.8.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-channels` | 0.8.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
-| `@arnilo/prism-coding-tools` | 0.8.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.8.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
-| `@arnilo/prism-providers` | 0.8.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.8.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.8.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.8.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.8.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-web-tools` | 0.8.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
-| `@arnilo/prism-work` | 0.8.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
+| `@arnilo/prism` | 0.10.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-channels` | 0.10.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
+| `@arnilo/prism-coding-tools` | 0.10.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.10.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
+| `@arnilo/prism-providers` | 0.10.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.10.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.10.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-hooks` | 0.10.0 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams |
+| `@arnilo/prism-mcp` | 0.10.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.10.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
+| `@arnilo/prism-web-tools` | 0.10.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism-work` | 0.10.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts

package/dist/agent-approval.d.ts

@@ -1,5 +1,6 @@
+import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
 import type { StoredAgentRunState } from "./agent-run-state.js";
-import { Agent, AgentRunResume, AgentRunState, AgentRunStateOptions, DecisionScope, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
+import { Agent, AgentRunCheckpointMetadata, AgentRunResume, AgentRunState, AgentRunStateOptions, DecisionScope, Guardrails, NestedRunOutcome, PendingDecision, RunDecision, StickyDecision, ToolResult } from "./contracts.js";
 import type { AgentIdentity } from "./identity.js";
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
 export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly PendingDecision[] | undefined;
@@ -31,6 +32,12 @@ export declare function resolveRunDecisions(input: {
     readonly state: StoredAgentRunState;
     readonly decisions: readonly RunDecision[];
     readonly signal?: AbortSignal;
+    /**
+     * Plan 104 T6: extra `tool_input` guardrails for decision-time revalidation of modified arguments —
+     * the resumed session's restored pack rules. Session-scoped on purpose: `agent.config.guardrails` is
+     * never mutated, so no other session of that agent inherits the packs.
+     */
+    readonly guardrails?: Guardrails;
 }): Promise<ResolvedRunDecisions>;
 /**
  * Resolve a tool's declared elicitation contract for a gated call. A throwing hook falls back to
@@ -50,7 +57,15 @@ export declare function decisionScopesEqual(a: DecisionScope, b: DecisionScope):
 export declare function nestedOutcomeToolResult(outcome: Exclude<NestedRunOutcome, {
     status: "suspended";
 }>, toolCallId: string, name: string): ToolResult;
-export interface ActiveDurableRun {
+/**
+ * Non-state extras carried into a resumed run: the sidecar metadata seed (so later checkpoint
+ * writes preserve the record's map) and the restore audit emitted on `agent_resumed`.
+ */
+export interface ActiveDurableRunExtras {
+    readonly checkpointMetadata?: AgentRunCheckpointMetadata;
+    readonly restore?: CheckpointRestoreAudit;
+}
+export interface ActiveDurableRun extends ActiveDurableRunExtras {
     readonly options: AgentRunStateOptions;
     state?: StoredAgentRunState;
     version: number;

package/dist/agent-approval.js

@@ -2,7 +2,7 @@
 import { createHash } from "node:crypto";
 import { activeTools, validateElicitationPayload } from "./agent-tool-dispatch.js";
 import { AgentDecisionError, DEFAULT_MAX_STICKY_DECISIONS, HARD_MAX_PENDING_DECISIONS, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, } from "./contracts.js";
-import { runGuardrails } from "./guardrails.js";
+import { guardrailRefusalText, runGuardrails } from "./guardrails.js";
 import { canonicalToolEffectJson } from "./tool-effects.js";
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
 export function pendingDecisionsOf(state) {
@@ -148,7 +148,7 @@ export async function resolveRunDecisions(input) {
             if (target.kind !== "tool_approval" || !target.toolCallId) {
                 throw new AgentDecisionError("ERR_PRISM_DECISION_SCOPE", "Modified arguments apply only to tool approvals");
             }
-            await validateModifiedArguments(agent, registry, state, target, decision.modifiedArguments, input.signal);
+            await validateModifiedArguments(agent, registry, state, target, decision.modifiedArguments, input.signal, input.guardrails);
         }
         if (decision.elicitation !== undefined) {
             if (target.kind !== "elicitation") {
@@ -181,7 +181,7 @@ export async function resolveRunDecisions(input) {
     };
 }
 /** Decision-time revalidation of modified arguments: schema, then input guardrails. Policy and trust re-run at dispatch. */
-async function validateModifiedArguments(agent, registry, state, target, modified, signal) {
+async function validateModifiedArguments(agent, registry, state, target, modified, signal, extraGuardrails) {
     const invalid = (message, cause) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message, { cause });
     if (JSON.stringify(modified) === undefined || Buffer.byteLength(JSON.stringify(modified), "utf8") > MAX_ELICITATION_BYTES) {
         throw invalid("Modified arguments must be a bounded JSON object");
@@ -199,9 +199,15 @@ async function validateModifiedArguments(agent, registry, state, target, modifie
     const value = call
         ? { ...call, arguments: modified }
         : { type: "tool_call", id: target.toolCallId ?? "", name: toolName, arguments: modified };
+    // Plan 104 T6: the session's pack rules join the agent's own here, so an approval that edits
+    // arguments into a pack-violating state is refused at decision time instead of being accepted and
+    // stopped at dispatch. Only `tool_input` is evaluated by this function, so only it is merged.
+    const guardrails = extraGuardrails?.toolInput?.length
+        ? { ...agent.config.guardrails, toolInput: [...(agent.config.guardrails?.toolInput ?? []), ...extraGuardrails.toolInput] }
+        : agent.config.guardrails;
     const guarded = await runGuardrails({
         stage: "tool_input",
-        guardrails: agent.config.guardrails,
+        guardrails,
         value,
         context: {
             sessionId: state.sessionId,
@@ -213,8 +219,11 @@ async function validateModifiedArguments(agent, registry, state, target, modifie
         },
         redactor: agent.config.redactor,
     });
-    if (guarded.terminal)
-        throw invalid("Modified arguments blocked by guardrail");
+    if (guarded.terminal) {
+        // A compiled pack rule is named (bounded, redacted) so the host sees which rule refused the edit;
+        // the arguments themselves are never echoed.
+        throw invalid(guardrailRefusalText(guarded.terminal, "Modified arguments blocked") ?? "Modified arguments blocked by guardrail");
+    }
 }
 /**
  * Resolve a tool's declared elicitation contract for a gated call. A throwing hook falls back to

package/dist/agent-event-source.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEventSource, AgentEventSourceOptions } from "./contracts.js";
+import type { AgentEvent, AgentEventSource, AgentEventSourceOptions } from "./contracts.js";
 export type AgentEventSourceErrorCode = "ERR_PRISM_AGENT_EVENT_SOURCE_INPUT" | "ERR_PRISM_AGENT_EVENT_SOURCE_CURSOR" | "ERR_PRISM_AGENT_EVENT_SOURCE_RETENTION" | "ERR_PRISM_AGENT_EVENT_SOURCE_OVERFLOW" | "ERR_PRISM_AGENT_EVENT_SOURCE_CLOSED";
 export declare class AgentEventSourceError extends Error {
     readonly code: AgentEventSourceErrorCode;
@@ -9,3 +9,11 @@ export declare class AgentEventSourceError extends Error {
  * wakeup or persistence; use a database-backed source for distributed delivery.
  */
 export declare function createMemoryAgentEventSource(options?: AgentEventSourceOptions): AgentEventSource;
+/**
+ * Terminal-set membership for agent event streams: a run's stream ends on its outcome record.
+ *
+ * Attribution records — `run_limit_exceeded` and `budget_exhausted` — are delivered *before* that
+ * outcome (the `error` that follows a run-limit death), so a page, subscription, or replay must
+ * keep reading past them. Every stream-ending site routes through this one predicate.
+ */
+export declare function isTerminalAgentEventType(type: AgentEvent["type"]): boolean;

package/dist/agent-event-source.js

@@ -439,12 +439,19 @@ function positionAfter(records, cursor, stream) {
 }
 function terminalAt(records, after) {
     const last = records.at(-1);
-    if (!last || !isTerminal(last))
+    if (!last || !isTerminalAgentEventType(last.type))
         return false;
     return after === undefined || after.sequence <= last.sequence;
 }
-function isTerminal(record) {
-    return (record.type === "agent_finished" || record.type === "agent_denied" || record.type === "run_limit_exceeded" || record.type === "error");
+/**
+ * Terminal-set membership for agent event streams: a run's stream ends on its outcome record.
+ *
+ * Attribution records — `run_limit_exceeded` and `budget_exhausted` — are delivered *before* that
+ * outcome (the `error` that follows a run-limit death), so a page, subscription, or replay must
+ * keep reading past them. Every stream-ending site routes through this one predicate.
+ */
+export function isTerminalAgentEventType(type) {
+    return type === "agent_finished" || type === "agent_denied" || type === "error";
 }
 function sameRecord(existing, input) {
     const { sequence: _existingSequence, ...existingWithoutSequence } = existing;

package/dist/agent-loops.js

@@ -25,12 +25,14 @@ export const singleShotLoop = {
             ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
             const request = await ctx.assemble(nextInput, undefined, turn);
             throwIfAborted(ctx.signal);
-            const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
+            const { content, calls, messageId, started, usage: turnUsage, metadata: turnMetadata } = await ctx.generate(request);
             usage = turnUsage ?? usage;
             if (turn === 1)
                 ctx.history.push(...ctx.inputMessages);
             if (started) {
-                const message = { id: messageId, role: "assistant", content };
+                // Turn provenance (plan 096): a deterministic answer carries `{ deterministic: { middleware } }`
+                // so the persisted transcript proves the turn had no model behind it.
+                const message = { id: messageId, role: "assistant", content, ...(turnMetadata ? { metadata: turnMetadata } : {}) };
                 ctx.history.push(message);
                 await ctx.appendMessage(message);
                 ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
@@ -140,7 +142,7 @@ export function generateValidateReviseLoop(opts) {
                     }
                 }
                 throwIfAborted(ctx.signal);
-                const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
+                const { content, calls, messageId, started, usage: turnUsage, metadata: turnMetadata } = await ctx.generate(request);
                 usage = turnUsage ?? usage;
                 if (pendingHistory.length > 0) {
                     ctx.history.push(...pendingHistory);
@@ -149,7 +151,8 @@ export function generateValidateReviseLoop(opts) {
                 if (turn === 1)
                     ctx.history.push(...ctx.inputMessages);
                 if (started) {
-                    const message = { id: messageId, role: "assistant", content };
+                    // Same provenance contract as singleShotLoop (plan 096).
+                    const message = { id: messageId, role: "assistant", content, ...(turnMetadata ? { metadata: turnMetadata } : {}) };
                     ctx.history.push(message);
                     await ctx.appendMessage(message);
                     ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });

package/dist/agent-run-lifecycle.d.ts

@@ -1,4 +1,4 @@
-import type { Agent, AgentEvent, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunResumeStreamOptions, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
+import type { Agent, AgentCheckpointRestoreHook, AgentEvent, AgentRunCheckpointMetadataSource, AgentRunRef, AgentRunResult, AgentRunResume, AgentRunResumeOptions, AgentRunResumeStreamOptions, AgentRunStatusResult, CheckpointStore, OwnershipScope, SubscribeOptions } from "./contracts.js";
 export interface AgentRunLifecycleAgent {
     readonly agent: Agent;
     /** Current host-authored revision; it must match the stored revision. */
@@ -12,6 +12,14 @@ export interface AgentRunLifecycleOptions {
         readonly signal?: AbortSignal;
     }) => AgentRunLifecycleAgent | Promise<AgentRunLifecycleAgent>;
     readonly fencingToken?: number;
+    /**
+     * Plan 094 Task 3: external-state restore hooks, run on every claiming resume before the
+     * checkpoint is claimed. Registered once here because a resume builds its session from the
+     * stored state (there is no live session to register against beforehand).
+     */
+    readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
+    /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly restoreHookTimeoutMs?: number;
 }
 export interface AgentRunLifecycleRequest {
     readonly ownership?: OwnershipScope;
@@ -22,6 +30,12 @@ export interface AgentRunLifecycleRequest {
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies on resume (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
+    /** Checkpoint sidecar metadata applied on resume (and to the resumed run's later checkpoints). */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
+    /** Plan 094 Task 3: restore hooks for this resume; the lifecycle's own hooks are used when omitted. */
+    readonly restoreHooks?: readonly AgentCheckpointRestoreHook[];
+    /** Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly restoreHookTimeoutMs?: number;
 }
 /** Bounded live-event options for a durable lifecycle resume. */
 export interface AgentRunLifecycleStreamRequest extends AgentRunLifecycleRequest, SubscribeOptions {

package/dist/agent-run-lifecycle.js

@@ -1,21 +1,31 @@
 import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
-import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
+import { agentFingerprint, loadAgentRunState, publicState, resolveCheckpointMetadata, saveAgentRunState } from "./agent-run-state.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
-import { parseAttentionStickyFrontier } from "./attention-compiler.js";
+import { parseAttentionStickyFrontier, restoreAttentionFoldLedger } from "./attention-compiler.js";
+import { runCheckpointRestoreHooks } from "./checkpoint-restore.js";
 import { AgentRunStateError } from "./contracts.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
         throw new AgentRunStateError("Agent run capability mismatch");
 }
+/** Lifecycle-registered hooks run first, then per-request ones; either timeout setting wins for both. */
+function restoreHookOptions(lifecycle, request) {
+    const hooks = [...(lifecycle.restoreHooks ?? []), ...(request.restoreHooks ?? [])];
+    const timeoutMs = request.restoreHookTimeoutMs ?? lifecycle.restoreHookTimeoutMs;
+    return {
+        ...(hooks.length > 0 ? { restoreHooks: hooks } : {}),
+        ...(timeoutMs === undefined ? {} : { restoreHookTimeoutMs: timeoutMs }),
+    };
+}
 /** Host capability for durable agent status/resume. Adapters supply authorized ownership only. */
 export function createAgentRunLifecycle(options) {
     return {
         async status(ref, request = {}) {
             request.signal?.throwIfAborted();
-            const { state, record } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
+            const { state, record, metadata } = await loadAgentRunState(options.checkpoints, ref, request.ownership);
             assertAgentId(state.agentId, request.agentId);
             request.signal?.throwIfAborted();
-            return { state: publicState({ ...state, version: record.version }), version: record.version };
+            return { state: publicState({ ...state, version: record.version }), version: record.version, ...(metadata ? { metadata } : {}) };
         },
         async resume(ref, resume, request = {}) {
             request.signal?.throwIfAborted();
@@ -31,6 +41,8 @@ export function createAgentRunLifecycle(options) {
                 signal: request.signal,
                 persistSessionState: request.persistSessionState,
                 includeSkillBodies: request.includeSkillBodies,
+                ...(request.checkpointMetadata === undefined ? {} : { checkpointMetadata: request.checkpointMetadata }),
+                ...restoreHookOptions(options, request),
             });
         },
         async *resumeStream(ref, resume, request = {}) {
@@ -49,6 +61,8 @@ export function createAgentRunLifecycle(options) {
                 overflow: request.overflow,
                 persistSessionState: request.persistSessionState,
                 includeSkillBodies: request.includeSkillBodies,
+                ...(request.checkpointMetadata === undefined ? {} : { checkpointMetadata: request.checkpointMetadata }),
+                ...restoreHookOptions(options, request),
             });
         },
     };
@@ -85,12 +99,13 @@ export async function* resumeAgentRunStream(agent, ref, resume, options) {
 }
 /**
  * A `continue` resume needs a run whose frontier is intact: a crash-recovery checkpoint
- * (`status: "running"`) or a turn-policy stop, which writes a terminal state that still carries
- * the frontier (plan 084 Task 2). Every other terminal state is final — a naturally finished run
- * must never be resurrected.
+ * (`status: "running"`) or a clean run-end stop — a turn-policy stop or a stop-hook continuation
+ * cap — which writes a terminal state that still carries the frontier (plan 084 Task 2, plan 106 R1).
+ * Every other terminal state is final — a naturally finished run must never be resurrected.
  */
 function isContinuableState(state) {
-    return state.status === "running" || (state.status === "succeeded" && state.stopReason === "host_policy");
+    return (state.status === "running" ||
+        (state.status === "succeeded" && (state.stopReason === "host_policy" || state.stopReason === "hook_limit")));
 }
 async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     throwIfAbortedSignal(signal);
@@ -99,7 +114,10 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     // and malformed untyped batches fail closed here instead of falling through to approval.
     assertValidAgentRunResume(resume);
     const continuing = resume.decision === "continue";
-    const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
+    const { record, state, metadata: recordMetadata } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
+    // Sidecar metadata: a resume-time source wins; otherwise the record's existing map is
+    // preserved on every write below, so a non-durable resume cannot wipe it.
+    const checkpointMetadata = resolveCheckpointMetadata(options.checkpointMetadata) ?? recordMetadata;
     if (state.definitionRevision !== options.definitionRevision ||
         state.agentId !== (agent.config.id ?? agent.config.name) ||
         state.fingerprint !== agentFingerprint(agent, options.definitionRevision)) {
@@ -121,6 +139,12 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     // Plan 078 Task 7: hand the reconstructed session to an observer (supervisor child-event pump)
     // before any event flows. Called for every resume outcome; a throw fails closed.
     options.onSession?.(session);
+    // Plan 104 T2: pack enforcement rides the checkpoint. A run without `persistSessionState` never
+    // writes the key, so its presence is the host's opt-in — restore before any turn (and before the
+    // pending-decision block, which may re-run input guardrails) or fail closed on a pack mismatch.
+    if (state.sessionState?.guardrailPacks) {
+        session.restoreGuardrailPacks(state.sessionState.guardrailPacks.packs, state.sessionState.guardrailPacks.state);
+    }
     // Opt-in session-state restore (plan 015 Task 4): names only; bodies re-resolve from
     // the live registry the next time the model (re)loads them via load_skill.
     if (options.persistSessionState && state.sessionState?.loadedSkillNames) {
@@ -137,22 +161,44 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         if (frontier)
             session.restoreAttentionSticky(frontier);
     }
+    // Plan 086 T3: durable folding writes its own ledger (with the frontier it belongs to), so it
+    // is restored whenever the checkpoint carries one — the `durable` opt-in was the host's
+    // consent, and a run without it never has this key. Without the frontier the ledger's rows
+    // would not be re-applied on an under-ratio turn, so the two ride together.
+    if (state.sessionState?.attentionFold) {
+        const ledger = restoreAttentionFoldLedger(state.sessionState.attentionFold);
+        if (ledger) {
+            session.restoreAttentionFold(ledger);
+            if (!options.persistSessionState && state.sessionState.attentionSticky) {
+                const frontier = parseAttentionStickyFrontier(state.sessionState.attentionSticky);
+                if (frontier)
+                    session.restoreAttentionSticky(frontier);
+            }
+        }
+    }
     // Plan 018 Task 6 (closeout `checkpoint-bodies`): restore exact instructions so the
     // resumed session renders them registry-independently (no load_skill round-trip).
     if (options.persistSessionState && options.includeSkillBodies && state.sessionState?.loadedSkillBodies) {
         session.restoreLoadedSkillBodies(state.sessionState.loadedSkillBodies);
     }
     const pendingDecisions = pendingDecisionsOf(state);
+    // Plan 104 T6: pack rules revalidate modified arguments at decision time. The set is the session's
+    // restored deny/tripwire rules plus its `ask` rules compiled as blocks — an approval that edits
+    // arguments into *any* pack-violating state is refused instead of becoming a run-wide allowance.
+    // Passed explicitly (never read from agent config), so a checkpoint that carried packs fails closed.
+    const sessionGuardrails = { toolInput: [...(session.packGuardrails?.toolInput ?? []), ...(session.packAskBlocks?.toolInput ?? [])] };
+    const decisionGuardrails = sessionGuardrails.toolInput.length > 0 ? sessionGuardrails : undefined;
     // Legacy approve maps to allow-once on every pending decision; legacy deny keeps its
     // terminal-denied behavior. Batch decisions are validated and applied atomically below.
     const resolved = resume.decisions !== undefined
-        ? await resolveRunDecisions({ agent, state, decisions: resume.decisions, signal })
+        ? await resolveRunDecisions({ agent, state, decisions: resume.decisions, signal, guardrails: decisionGuardrails })
         : resume.decision === "approve" && pendingDecisions
             ? await resolveRunDecisions({
                 agent,
                 state,
                 decisions: pendingDecisions.map((pending) => ({ approvalId: pending.approvalId, outcome: "allow_once" })),
                 signal,
+                guardrails: decisionGuardrails,
             })
             : undefined;
     if (resolved && resolved.remaining.length > 0) {
@@ -231,6 +277,7 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
             expectedVersion: record.version,
             ownership: options.ownership,
             fencingToken: options.fencingToken,
+            ...(checkpointMetadata ? { metadata: checkpointMetadata } : {}),
         });
         return {
             kind: "deny",
@@ -258,6 +305,21 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         throw new AgentRunStateError("Agent durable run-state configuration mismatch on resume");
     }
     throwIfAbortedSignal(signal);
+    // Plan 094 Task 3: restore external state (git commit, document versions) before the claim
+    // write. Every hook must succeed — a throw here leaves the checkpoint exactly as it was, and
+    // the conversation restore below never runs, so no half-restored world is claimed as resumed.
+    const restoreHooks = options.restoreHooks ?? [];
+    const restore = restoreHooks.length
+        ? await runCheckpointRestoreHooks(restoreHooks, {
+            runId: state.runId,
+            sessionId: state.sessionId,
+            version: record.version,
+            status: state.status,
+            ...(recordMetadata ? { metadata: recordMetadata } : {}),
+            checkpoint: record,
+        }, { timeoutMs: options.restoreHookTimeoutMs, signal })
+        : undefined;
+    throwIfAbortedSignal(signal);
     const claimed = await saveAgentRunState({
         checkpoints: options.checkpoints,
         state: {
@@ -269,6 +331,7 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         expectedVersion: record.version,
         ownership: options.ownership,
         fencingToken: options.fencingToken,
+        ...(checkpointMetadata ? { metadata: checkpointMetadata } : {}),
     });
     return {
         kind: "claim",
@@ -276,6 +339,9 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         state: claimed.state,
         decisions: resolved?.decisionsById,
         ownership: options.ownership,
+        // The configured object must be passed by identity (agent-session assemble rejects a
+        // replaced config); its own `checkpointMetadata` provider wins, and the resolved map rides
+        // the session as a seed so later writes preserve a record's existing sidecar.
         runState: configured ?? {
             checkpoints: options.checkpoints,
             definitionRevision: options.definitionRevision,
@@ -286,6 +352,8 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
             // turn checkpoints without the host repeating the option on resume.
             ...(state.checkpointPolicy ? { checkpointPolicy: state.checkpointPolicy } : {}),
         },
+        ...(checkpointMetadata ? { checkpointMetadata } : {}),
+        ...(restore ? { restore } : {}),
     };
 }
 /** Pending decisions of a suspended state, synthesizing the legacy single-approval shape. */
@@ -298,6 +366,9 @@ async function executePreparedAgentRunResume(prepared, signal) {
         await prepared.session.recordDurableResumption(prepared.result.runId, prepared.interruption, prepared.version, prepared.ownership);
         return prepared.result;
     }
-    return prepared.session.resumeDurable(prepared.state, prepared.runState, prepared.ownership, signal, prepared.decisions);
+    return prepared.session.resumeDurable(prepared.state, prepared.runState, prepared.ownership, signal, prepared.decisions, {
+        ...(prepared.checkpointMetadata ? { checkpointMetadata: prepared.checkpointMetadata } : {}),
+        ...(prepared.restore ? { restore: prepared.restore } : {}),
+    });
 }
 //# sourceMappingURL=agent-run-lifecycle.js.map