@arnilo/prism 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,4 +1,27 @@
-## [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)
 

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.9.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-channels` | 0.9.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.9.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.9.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
-| `@arnilo/prism-providers` | 0.9.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.9.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.9.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.9.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.9.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-web-tools` | 0.9.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
-| `@arnilo/prism-work` | 0.9.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,6 +1,6 @@
 import type { CheckpointRestoreAudit } from "./checkpoint-restore.js";
 import type { StoredAgentRunState } from "./agent-run-state.js";
-import { Agent, AgentRunCheckpointMetadata, 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;
@@ -32,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

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-run-lifecycle.js

@@ -99,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);
@@ -138,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) {
@@ -175,16 +182,23 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         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) {

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

@@ -1,5 +1,5 @@
 import { type PersistedAttentionFoldLedger, type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
-import type { Agent, AgentRunCheckpointMetadata, AgentRunCheckpointMetadataSource, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
+import type { Agent, AgentRunCheckpointMetadata, AgentRunCheckpointMetadataSource, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, GuardrailRule, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
@@ -56,6 +56,9 @@ export interface StoredAgentRunState extends AgentRunState {
          *  the same stub bytes instead of re-summarizing. Written and restored independently of
          *  `persistSessionState`. Validated on load. */
         readonly attentionFold?: PersistedAttentionFoldLedger;
+        /** Plan 104 T2: compiled pack refs plus pack-owned state, so a resume re-enforces exactly what
+         *  the suspended run enforced. Written only with `persistSessionState`; validated on load. */
+        readonly guardrailPacks?: PersistedGuardrailPacks;
     };
     /** Per-run allow-list (Task 21). Absent = full registered set (legacy checkpoints). */
     readonly toolNames?: readonly string[];
@@ -66,17 +69,34 @@ export interface StoredAgentRunState extends AgentRunState {
      */
     readonly checkpointPolicy?: "every-turn";
     /**
-     * Set when a terminal state was written by a `RunOptions.turnPolicy` stop (plan 084 Task 2):
-     * the run succeeded cleanly but its frontier is intact, so `decision: "continue"` may resume
-     * it. Absent on every other state — a naturally finished run is never continuable.
+     * Set when a terminal state was written by a clean run-end stop that leaves the frontier intact:
+     * a `RunOptions.turnPolicy` stop (`host_policy`, plan 084 Task 2) or a stop-hook continuation cap
+     * (`hook_limit`, plan 106 R1). The run succeeded but `decision: "continue"` may resume it. Absent
+     * on every other state — a naturally finished run is never continuable.
      */
-    readonly stopReason?: "host_policy";
+    readonly stopReason?: "host_policy" | "hook_limit";
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export declare const MAX_PERSISTED_SKILL_NAMES = 64;
 export declare const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
 /** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */
 export declare const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128;
+/** Plan 104 T2: one replayable pack row — the id, the version it was compiled at, and host options. */
+interface PersistedGuardrailPackRef {
+    readonly id: string;
+    readonly version: number;
+    readonly options?: Readonly<Record<string, unknown>>;
+    /** Inline pattern rules; closures and `RegExp` patterns never reach a checkpoint (refused at save). */
+    readonly rules?: readonly GuardrailRule[];
+}
+/**
+ * Plan 104 T2: the checkpoint-side pack block written with `persistSessionState`. Rows replay a
+ * registered pack by `id`/`version` or an inline pack by its pattern `rules` (plan 104 T3).
+ */
+export interface PersistedGuardrailPacks {
+    readonly packs: readonly PersistedGuardrailPackRef[];
+    readonly state?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export declare const BUILT_IN_LOOP_REVISIONS: Readonly<Record<string, string>>;
 /** Validate a strategy snapshot as JSON-compatible and package it for the durable envelope. */
@@ -132,3 +152,4 @@ export declare function initialAgentRunState(input: {
     readonly interruptBeforeTool?: boolean;
 }): StoredAgentRunState;
 export declare function parseAgentRunState(value: unknown, version?: number): StoredAgentRunState;
+export {};

package/dist/agent-run-state.js

@@ -16,6 +16,12 @@ export const MAX_PERSISTED_SKILL_NAMES = 64;
 export const MAX_PERSISTED_SKILL_NAME_CHARS = 256;
 /** Plan 041: activated-tool names ride the same budget discipline (cap 128; multiple searches accumulate). */
 export const MAX_PERSISTED_ACTIVATED_TOOL_NAMES = 128;
+/** Plan 104 T2: persisted pack refs and state (cap matches `MAX_GUARDRAIL_PACKS`; ids match the pack cap). */
+const MAX_PERSISTED_GUARDRAIL_PACKS = 8;
+const MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS = 96;
+const MAX_PERSISTED_GUARDRAIL_PACK_RULES = 64;
+/** Per-pack options/state byte ceiling; the whole session state is still bounded by `maxStateBytes`. */
+const MAX_PERSISTED_GUARDRAIL_PACK_BYTES = 8 * 1024;
 /** Revision stamps of the built-in loops; custom strategies declare their own `revision`. */
 export const BUILT_IN_LOOP_REVISIONS = {
     "single-shot": "1",
@@ -270,7 +276,7 @@ export function parseAgentRunState(value, version) {
     if (state.checkpointPolicy !== undefined && state.checkpointPolicy !== "every-turn") {
         throw new AgentRunStateError("Malformed agent run checkpoint policy");
     }
-    if (state.stopReason !== undefined && state.stopReason !== "host_policy") {
+    if (state.stopReason !== undefined && state.stopReason !== "host_policy" && state.stopReason !== "hook_limit") {
         throw new AgentRunStateError("Malformed agent run stop reason");
     }
     // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
@@ -353,5 +359,95 @@ function validateSessionState(sessionState) {
     if (fold !== undefined && restoreAttentionFoldLedger(fold) === undefined) {
         throw new AgentRunStateError("Malformed agent run attention fold ledger");
     }
+    validateGuardrailPackState(sessionState.guardrailPacks);
+}
+/**
+ * Plan 104 T2/T3: bounds for the persisted pack block. Rows replay a registered pack by id/version or
+ * an inline pack by its pattern rules, and state may only name those rows — anything else fails the
+ * load, because a dropped pack silently re-allows what it existed to deny. Rule data is re-validated
+ * (pattern compile, id/reason caps) by the compiler that replays it; this checks the JSON envelope.
+ */
+function validateGuardrailPackState(value) {
+    if (value === undefined)
+        return;
+    const raw = value;
+    if (!raw || typeof raw !== "object" || !Array.isArray(raw.packs)) {
+        throw new AgentRunStateError("Malformed agent run guardrail pack state");
+    }
+    if (raw.packs.length > MAX_PERSISTED_GUARDRAIL_PACKS) {
+        throw new AgentRunStateError(`Persisted guardrail packs exceed ${MAX_PERSISTED_GUARDRAIL_PACKS} entries`);
+    }
+    const ids = new Set();
+    for (const row of raw.packs) {
+        if (!isPlainObject(row))
+            throw new AgentRunStateError("Malformed agent run guardrail pack row");
+        const { id, version, options } = row;
+        if (typeof id !== "string" || !id.trim() || id.length > MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS) {
+            throw new AgentRunStateError(`Persisted guardrail pack ids must be non-empty strings of at most ${MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS} chars`);
+        }
+        if (ids.has(id))
+            throw new AgentRunStateError(`Duplicate persisted guardrail pack id "${id}"`);
+        ids.add(id);
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" version must be a positive integer`);
+        }
+        if (options !== undefined && !isPlainObject(options)) {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" options must be an object`);
+        }
+        if (options !== undefined)
+            boundPackBytes(options, `Pack "${id}" options`);
+        validatePersistedPackRules(id, row);
+    }
+    if (raw.state === undefined)
+        return;
+    if (!isPlainObject(raw.state))
+        throw new AgentRunStateError("Malformed agent run guardrail pack state");
+    for (const [id, state] of Object.entries(raw.state)) {
+        if (!ids.has(id))
+            throw new AgentRunStateError(`Persisted guardrail pack state names unknown pack "${id}"`);
+        if (!isPlainObject(state))
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" state must be an object`);
+        boundPackBytes(state, `Pack "${id}" state`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Plan 104 T3: a persisted inline pack must be pattern data — a closure or `RegExp` cannot restore. */
+function validatePersistedPackRules(id, row) {
+    if (row.rules === undefined)
+        return;
+    if (!Array.isArray(row.rules))
+        throw new AgentRunStateError(`Persisted guardrail pack "${id}" rules must be an array`);
+    if (row.rules.length === 0 || row.rules.length > MAX_PERSISTED_GUARDRAIL_PACK_RULES) {
+        throw new AgentRunStateError(`Persisted guardrail pack "${id}" rules must number 1..${MAX_PERSISTED_GUARDRAIL_PACK_RULES}`);
+    }
+    for (const rule of row.rules) {
+        if (!isPlainObject(rule))
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule must be an object`);
+        const { id: ruleId, pattern, deny } = rule;
+        if (typeof ruleId !== "string" || !ruleId.trim() || ruleId.length > MAX_PERSISTED_GUARDRAIL_PACK_ID_CHARS) {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule ids must be non-empty strings`);
+        }
+        if (deny !== undefined)
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule "${ruleId}" carries a deny predicate`);
+        if (pattern !== undefined && typeof pattern !== "string") {
+            throw new AgentRunStateError(`Persisted guardrail pack "${id}" rule "${ruleId}" pattern must be a string`);
+        }
+        boundPackBytes(rule, `Pack "${id}" rule "${ruleId}"`);
+    }
+}
+/** A pack's state must be JSON and under its per-pack ceiling: refuse, never truncate. */
+function boundPackBytes(value, label) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        throw new AgentRunStateError(`${label} must be JSON serializable`);
+    }
+    if ((text ? Buffer.byteLength(text) : 0) > MAX_PERSISTED_GUARDRAIL_PACK_BYTES) {
+        throw new AgentRunStateError(`${label} exceeds ${MAX_PERSISTED_GUARDRAIL_PACK_BYTES} bytes`);
+    }
 }
 //# sourceMappingURL=agent-run-state.js.map

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

@@ -3,6 +3,8 @@ import type { AgentEvent, SubscribeOptions } from "../contracts.js";
 export declare class EventSubscriber implements AsyncIterable<AgentEvent>, AsyncIterator<AgentEvent> {
     private readonly sessionId;
     private readonly onClose;
+    /** Plan 104 T5: run-scoped unless the host opted into `acrossRuns`. */
+    readonly acrossRuns: boolean;
     private readonly queue;
     private readonly waiters;
     private readonly maxQueuedEvents;

package/dist/agent-session/event-subscriber.js

@@ -1,6 +1,8 @@
 export class EventSubscriber {
     sessionId;
     onClose;
+    /** Plan 104 T5: run-scoped unless the host opted into `acrossRuns`. */
+    acrossRuns;
     queue = [];
     waiters = [];
     maxQueuedEvents;
@@ -12,6 +14,7 @@ export class EventSubscriber {
         const maxQueuedEvents = options.maxQueuedEvents ?? 1024;
         this.maxQueuedEvents = Number.isFinite(maxQueuedEvents) ? Math.max(1, Math.floor(maxQueuedEvents)) : 1024;
         this.overflow = options.overflow ?? "close";
+        this.acrossRuns = options.acrossRuns === true;
     }
     [Symbol.asyncIterator]() {
         return this;