@arnilo/prism 0.8.0 → 0.9.0

package/dist/contracts-protocol.d.ts

@@ -1,4 +1,6 @@
-import type { AgentLoopOptions, AgentLoopStrategy, ArtifactValidation, CompactionOptions, ContentBlock, ErrorInfo, GuardrailRecord, Guardrails, InstructionInjector, JsonObject, Message, ModelConfig, OwnershipScope, ProviderRequestOptions, ProviderRequestPolicy, ProviderResolver, RetryOptions, RunLimitBreach, RunLimits, Skill, SubscriberOverflowPolicy, SystemPromptConfig, ToolCallAuthority, ToolCallContent, TurnPolicyOptions, Usage } from "./contracts-core.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, 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 { AgentRunInterruption, AgentRunStateOptions } from "./contracts-run-state.js";
 import type { SecretRedactor } from "./redaction.js";
 import type { ToolValidator } from "./tools.js";
@@ -28,6 +30,7 @@ export type ProviderEvent = {
 } | {
     readonly type: "done";
     readonly usage?: Usage;
+    readonly stopReason?: ProviderStopReason;
 } | {
     readonly type: "error";
     readonly error: ErrorInfo;
@@ -108,6 +111,10 @@ export interface RunOptions {
     readonly toolNames?: readonly string[];
     /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
     readonly toolsDisclosure?: import("./tool-search.js").ToolsDisclosure;
+    /** Per-turn restrictive allow-list over the run grant. Overrides `AgentConfig.toolNarrowing`. */
+    readonly toolNarrowing?: import("./contracts-core/agent.js").ToolNarrowing;
+    /** Opt-in: tools hidden this turn stay callable by name (default off). Overrides agent config. */
+    readonly allowHiddenToolCalls?: true;
     readonly toolsSearch?: import("./tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
@@ -140,6 +147,17 @@ export interface ProviderTurnMetadata {
     readonly httpStatus?: number;
     readonly rateLimitRemaining?: number;
     readonly rateLimitResetMs?: number;
+    /** Why the provider turn stopped (plan 087 T1); present on `provider_turn_finished` only. */
+    readonly stopReason?: ProviderStopReason;
+    /** Effective budget state at turn end (plan 087 T1); present on `provider_turn_finished` only. */
+    readonly budgets?: TurnBudgets;
+    /** Provider-reported cache usage and derived hit rate; absent when cache usage is unknown. */
+    readonly cache?: CacheUsageReport;
+    /** Effective tool menu this turn. Names hashed in request order; never includes args. */
+    readonly tools?: {
+        readonly count: number;
+        readonly idsHash: string;
+    };
 }
 export interface ToolExecutionMetadata {
     readonly durationMs: number;
@@ -177,7 +195,18 @@ export interface DelegatedAgentStep {
 }
 /** 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";
-export type AgentEvent = {
+/**
+ * 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.
+ */
+export interface ChildEventOrigin {
+    readonly childId: string;
+    readonly delegationId: string;
+    /** Delegation depth: 1 is a direct child of the hosting supervisor. */
+    readonly depth: number;
+}
+/** Payload union of every agent event; the exported `AgentEvent` adds the optional child origin tag. */
+type AgentEventPayload = {
     readonly type: "agent_started";
     readonly sessionId: string;
     readonly runId: string;
@@ -201,6 +230,8 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly version: number;
+    /** Plan 094 Task 3: audit of the external-state restore hooks that ran before this claim. */
+    readonly restore?: CheckpointRestoreAudit;
 } | {
     readonly type: "agent_denied";
     readonly sessionId: string;
@@ -217,6 +248,17 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly turn: number;
+} | {
+    /**
+     * Host middleware completed this turn without a provider request (plan 096). No `usage` field:
+     * a deterministic turn has no provider cost, so accounting must never zero-fill one.
+     */
+    readonly type: "deterministic_turn";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    /** Answering middleware id (provenance); ids only, never free host code. */
+    readonly middleware: string;
 } | {
     readonly type: "provider_turn_started";
     readonly sessionId: string;
@@ -281,6 +323,13 @@ export type AgentEvent = {
     readonly reason: string;
     readonly error: ErrorInfo;
     readonly metadata: ToolExecutionMetadata;
+} | {
+    /** Host `toolNarrowing` asked for names outside the run grant; those names were dropped. */
+    readonly type: "tool_narrowing_clamped";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly dropped: readonly string[];
 } | {
     readonly type: "guardrail_decision";
     readonly sessionId: string;
@@ -293,6 +342,16 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly breach: RunLimitBreach;
+} | {
+    /** Terminal attribution for a run that died on a run limit (plan 087 T2): which axis fired,
+     *  counters at exhaustion, how close the other axes were, and hashes of recent tool calls. */
+    readonly type: "budget_exhausted";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly limit: RunLimitName;
+    readonly consumed: BudgetConsumedCounters;
+    readonly closestOtherAxes: readonly BudgetAxisUsage[];
+    readonly recentToolCalls: readonly ToolCallSummary[];
 } | {
     readonly type: "queue_updated";
     readonly sessionId: string;
@@ -383,6 +442,14 @@ export type AgentEvent = {
     readonly attempt: number;
     readonly result: ArtifactValidation;
 };
+/**
+ * One agent event. `child` is set only when the event was forwarded from a delegated child
+ * (e.g. supervisor `report: "stream"` passthrough), so hosts can route it onto a parent stream
+ * without per-event-type special cases. It never replaces the event's own `sessionId`/`runId`.
+ */
+export type AgentEvent = AgentEventPayload & {
+    readonly child?: ChildEventOrigin;
+};
 export type ToolEffectKind = "none" | "local_mutation" | "external_mutation";
 export type ToolEffectIdempotency = "none" | "optional" | "required" | "tool_managed" | "unsupported";
 /** Static or validated-argument classification of one tool call's side-effect behavior. */
@@ -688,4 +755,11 @@ export interface ProviderTurnResult {
     readonly messageId?: string;
     readonly started: boolean;
     readonly usage?: Usage;
+    /**
+     * Provenance for turns that did not come from the provider (plan 096):
+     * `{ deterministic: { middleware } }`. Copied onto the assistant `Message.metadata`, so it
+     * serializes with the transcript and survives replay. Absent for provider turns.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
+export {};

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

@@ -1,5 +1,6 @@
-import type { AgentSessionCloneOptions, AgentSessionForkOptions, CheckpointStore, CompactionOptions, CompactionResult, ContentBlock, ErrorInfo, JsonObject, JsonValue, Message, ModelConfig, OwnershipScope, RunLimitBreach, SessionEntry, SubscribeOptions, ToolCallContent, Usage } from "./contracts-core.js";
+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 { AgentEvent, AgentFinishReason, RunOptions, ToolEffectKind } from "./contracts-protocol.js";
+import type { CheckpointRestoreHook } from "./checkpoint-restore.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";
@@ -139,6 +140,15 @@ export declare const HARD_MAX_ACTION_CONSTRAINTS = 64;
 export declare const MAX_ATTRIBUTION_DEPTH = 8;
 export declare const MAX_ACTION_CONSTRAINT_BYTES: number;
 export declare const HARD_MAX_ACTION_CONSTRAINT_BYTES: number;
+/**
+ * Opaque host sidecar pinned to one checkpoint *record* (git commit, document version,
+ * workspace fingerprint) — never part of the run-state value, so it costs no `maxStateBytes`
+ * budget and is invisible to state parsing. Bounded to `MAX_AGENT_RUN_METADATA_BYTES` (4 KiB)
+ * and redacted like the state value at every write.
+ */
+export type AgentRunCheckpointMetadata = Readonly<Record<string, string>>;
+/** Host source for checkpoint sidecar metadata: a fixed map or a live provider resolved per write. */
+export type AgentRunCheckpointMetadataSource = AgentRunCheckpointMetadata | (() => AgentRunCheckpointMetadata | undefined);
 export interface AgentRunStateOptions {
     readonly checkpoints: CheckpointStore;
     /** Host-authored immutable revision required for durable runs. */
@@ -156,6 +166,12 @@ export interface AgentRunStateOptions {
     readonly checkpointPolicy?: "decision" | "every-turn";
     /** Suspend every tool call before its side effect. */
     readonly interruptBeforeTool?: boolean;
+    /**
+     * Sidecar metadata written with every checkpoint of this run (and carried into a resumed
+     * run). A provider is resolved at each checkpoint write, so a host closure can pin state
+     * that moves mid-run (e.g. the current git commit). Absent = records stay byte-identical.
+     */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
     readonly maxStateBytes?: number;
     readonly fencingToken?: number;
     /** Enables sticky auto-apply when a nested suspension first surfaces during this run. */
@@ -204,6 +220,23 @@ export interface AgentRunResume {
     /** Batch decision path; exactly one of decision/decisions. Applied as one atomic CAS transition. */
     readonly decisions?: readonly RunDecision[];
 }
+/**
+ * Checkpoint handed to a restore hook (plan 094 Task 3). `checkpoint.value` is the raw stored
+ * run-state value; `metadata` is the redacted, bounded sidecar map hosts write via
+ * `AgentRunStateOptions.checkpointMetadata`.
+ */
+export interface AgentCheckpointRestoreContext {
+    readonly runId: string;
+    readonly sessionId: string;
+    /** Version of the checkpoint being claimed; a hook may pass it to an external system's own CAS. */
+    readonly version: number;
+    /** State being claimed: `running` for crash recovery, `suspended` for a decision resume. */
+    readonly status: AgentRunStatus | "running";
+    readonly metadata?: AgentRunCheckpointMetadata;
+    readonly checkpoint: CheckpointRecord;
+}
+/** Host code restoring one external layer before a durable resume applies. */
+export type AgentCheckpointRestoreHook = CheckpointRestoreHook<AgentCheckpointRestoreContext>;
 export interface AgentRunResumeOptions {
     readonly checkpoints: CheckpointStore;
     /** Current host-authored revision; must exactly match the checkpoint. */
@@ -224,6 +257,20 @@ export interface AgentRunResumeOptions {
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */
     readonly includeSkillBodies?: boolean;
+    /**
+     * Checkpoint sidecar metadata for the claim write (and the resumed run's later checkpoints).
+     * Absent = the record's existing metadata is preserved unchanged.
+     */
+    readonly checkpointMetadata?: AgentRunCheckpointMetadataSource;
+    /**
+     * 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.
+     */
+    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 `resumeAgentRunStream()`; `signal` is inherited from the base resume options. */
 export interface AgentRunResumeStreamOptions extends AgentRunResumeOptions, SubscribeOptions {
@@ -235,6 +282,8 @@ export interface AgentRunRef {
 export interface AgentRunStatusResult {
     readonly state: AgentRunState;
     readonly version: number;
+    /** Checkpoint sidecar metadata; absent when the record carries none (or carries only malformed entries). */
+    readonly metadata?: AgentRunCheckpointMetadata;
 }
 export declare class AgentRunStateError extends Error {
     readonly code = "ERR_PRISM_AGENT_RUN_STATE";
@@ -319,6 +368,12 @@ export interface AgentSession {
     abort(reason?: unknown): void;
     entries(): Promise<readonly SessionEntry[]>;
     checkout(leafId?: string): Promise<void>;
+    /**
+     * Context-fill read (plan 091 T2): latest provider turn's input tokens
+     * (reported or labeled estimate) plus the resolved per-request cap, run input
+     * budget, and used ratio. Before any provider turn it estimates stored history.
+     */
+    contextMeter(): ContextMeter;
     fork(options?: AgentSessionForkOptions): AgentSession;
     clone(options?: AgentSessionCloneOptions): Promise<AgentSession>;
 }

package/dist/guardrail-packs/coding-standard.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned coding hygiene: file mutations confined to configured roots, test files read-only. */
+export declare const codingStandardPack: GuardrailPackDefinition;

package/dist/guardrail-packs/coding-standard.js

@@ -0,0 +1,63 @@
+import { resolve as resolvePath, sep } from "node:path";
+import { GuardrailPackError } from "./errors.js";
+/** File-mutating prism coding tool names (plan 092 Task 1: `shell`/`read` are not mutations). */
+const MUTATING_TOOLS = ["write", "edit", "delete", "move"];
+const PATH_ARGS = ["path", "paths", "from", "to"];
+const TEST_FILE_PATTERN = /(^|[\\/])(?:__tests__|tests?|specs?)[\\/]|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const MAX_ROOTS = 16;
+function pathStrings(args) {
+    const paths = [];
+    for (const key of PATH_ARGS) {
+        const value = args[key];
+        if (typeof value === "string")
+            paths.push(value);
+        else if (Array.isArray(value))
+            paths.push(...value.filter((item) => typeof item === "string"));
+    }
+    return paths;
+}
+function readRoots(value, cwd) {
+    if (value === undefined)
+        return [cwd];
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_ROOTS) {
+        throw new GuardrailPackError(`coding-standard options.roots must be a non-empty string array (max ${MAX_ROOTS})`);
+    }
+    return value.map((root) => {
+        if (typeof root !== "string" || !root.trim())
+            throw new GuardrailPackError("coding-standard options.roots entries must be non-empty strings");
+        return resolvePath(cwd, root);
+    });
+}
+/** Lazy containment: no symlink resolution (a link inside a root can still point out); execution policy/sandbox remains the hard boundary. */
+function outsideRoots(candidate, roots, cwd) {
+    const resolved = resolvePath(cwd, candidate);
+    return !roots.some((root) => resolved === root || resolved.startsWith(root.endsWith(sep) ? root : `${root}${sep}`));
+}
+/** Canned coding hygiene: file mutations confined to configured roots, test files read-only. */
+export const codingStandardPack = {
+    id: "coding-standard",
+    version: 1,
+    description: "Restricts file mutation to configured workspace roots and blocks test-file rewrites.",
+    build(options) {
+        const cwd = resolvePath(typeof options.cwd === "string" ? options.cwd : process.cwd());
+        const roots = readRoots(options.roots, cwd);
+        return {
+            rules: [
+                {
+                    id: "no-unrelated-file-edits",
+                    tool: MUTATING_TOOLS,
+                    reason: "File edits are restricted to the configured workspace roots",
+                    deny: (args) => pathStrings(args).some((candidate) => outsideRoots(candidate, roots, cwd)),
+                },
+                {
+                    id: "no-test-rewrites",
+                    tool: MUTATING_TOOLS,
+                    pattern: TEST_FILE_PATTERN,
+                    argPath: PATH_ARGS,
+                    reason: "Test files are read-only under this pack",
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=coding-standard.js.map

package/dist/guardrail-packs/destructive-commands.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned destructive shell/SQL patterns on the `shell` tool's `command` argument. */
+export declare const destructiveCommandsPack: GuardrailPackDefinition;

package/dist/guardrail-packs/destructive-commands.js

@@ -0,0 +1,46 @@
+/** Shell commands that destroy data or history. Denies `--force-with-lease` too: both rewrite remote history. */
+const DESTRUCTIVE_COMMANDS = [
+    {
+        id: "no-recursive-force-delete",
+        pattern: /\brm\s+(?:[^\n;&|]*?\s)?-(?=[a-z]*r)(?=[a-z]*f)[a-z]+/i,
+        reason: "Recursive force delete is not allowed",
+    },
+    {
+        id: "no-long-flag-force-delete",
+        pattern: /\brm\s+[^\n;&|]*--recursive\b[^\n;&|]*--force\b|\brm\s+[^\n;&|]*--force\b[^\n;&|]*--recursive\b/i,
+        reason: "Recursive force delete is not allowed",
+    },
+    {
+        id: "no-force-push",
+        pattern: /\bgit\s+push\b[^\n;&|]*(?:--force\b|(?:^|\s)-f(?:\s|$))/i,
+        reason: "Force push is not allowed",
+    },
+    {
+        id: "no-destructive-sql",
+        pattern: /\b(?:drop|truncate)\s+table\b/i,
+        reason: "Destructive SQL is not allowed",
+    },
+    {
+        id: "no-device-overwrite",
+        pattern: /\bmkfs(?:\.\w+)?\b|\bdd\b[^\n;&|]*\bof=\/dev\//i,
+        reason: "Raw device overwrite is not allowed",
+    },
+];
+/** Canned destructive shell/SQL patterns on the `shell` tool's `command` argument. */
+export const destructiveCommandsPack = {
+    id: "destructive-commands",
+    version: 1,
+    description: "Blocks destructive shell and SQL commands (recursive force delete, force push, drop table, device overwrite).",
+    build() {
+        return {
+            rules: DESTRUCTIVE_COMMANDS.map(({ id, pattern, reason }) => ({
+                id,
+                tool: "shell",
+                pattern,
+                argPath: "command",
+                reason,
+            })),
+        };
+    },
+};
+//# sourceMappingURL=destructive-commands.js.map

package/dist/guardrail-packs/errors.d.ts

@@ -0,0 +1,7 @@
+/** Guardrail pack config/compile error (plan 092 Task 2). Config mistakes fail closed at compile time. */
+export declare class GuardrailPackError extends Error {
+    readonly code = "ERR_PRISM_GUARDRAIL_PACK";
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}

package/dist/guardrail-packs/errors.js

@@ -0,0 +1,9 @@
+/** Guardrail pack config/compile error (plan 092 Task 2). Config mistakes fail closed at compile time. */
+export class GuardrailPackError extends Error {
+    code = "ERR_PRISM_GUARDRAIL_PACK";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "GuardrailPackError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/guardrail-packs/index.d.ts

@@ -0,0 +1,4 @@
+import type { GuardrailPackDefinition } from "./types.js";
+export declare const BUILT_IN_GUARDRAIL_PACKS: ReadonlyMap<string, GuardrailPackDefinition>;
+/** Built-in pack ids, in registry order. */
+export declare const BUILT_IN_GUARDRAIL_PACK_IDS: readonly string[];

package/dist/guardrail-packs/index.js

@@ -0,0 +1,15 @@
+/** Built-in guardrail pack registry (plan 092 Task 2). Definitions are pure data + pure factories. */
+import { codingStandardPack } from "./coding-standard.js";
+import { destructiveCommandsPack } from "./destructive-commands.js";
+import { secretsHygienePack } from "./secrets-hygiene.js";
+import { validationRespectPack } from "./validation-respect.js";
+const DEFINITIONS = [
+    codingStandardPack,
+    destructiveCommandsPack,
+    validationRespectPack,
+    secretsHygienePack,
+];
+export const BUILT_IN_GUARDRAIL_PACKS = new Map(DEFINITIONS.map((definition) => [definition.id, definition]));
+/** Built-in pack ids, in registry order. */
+export const BUILT_IN_GUARDRAIL_PACK_IDS = DEFINITIONS.map((definition) => definition.id);
+//# sourceMappingURL=index.js.map

package/dist/guardrail-packs/secrets-hygiene.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned secret hygiene: any tool argument carrying credential-shaped material is denied. */
+export declare const secretsHygienePack: GuardrailPackDefinition;

package/dist/guardrail-packs/secrets-hygiene.js

@@ -0,0 +1,23 @@
+/**
+ * Known credential shapes, all quantifier-bounded so a hostile argument string cannot blow up the regex.
+ * Prism redaction matches exact known values only (plan 092 Task 1), so these patterns ship with the pack.
+ */
+const SECRET_PATTERN = /(?:sk-[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.|xox[baprs]-[A-Za-z0-9-]{10,})/;
+/** Canned secret hygiene: any tool argument carrying credential-shaped material is denied. */
+export const secretsHygienePack = {
+    id: "secrets-hygiene",
+    version: 1,
+    description: "Blocks tool calls whose arguments carry secret-shaped material (API keys, tokens, private keys).",
+    build() {
+        return {
+            rules: [
+                {
+                    id: "no-secret-material-in-arguments",
+                    pattern: SECRET_PATTERN,
+                    reason: "Tool arguments contain secret-shaped material",
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=secrets-hygiene.js.map

package/dist/guardrail-packs/types.d.ts

@@ -0,0 +1,16 @@
+/** Internal guardrail-pack definition types (plan 092 Task 2). Not SDK surface; hosts configure packs via `AgentSessionConfig.guardrailPacks`. */
+import type { GuardrailRule, GuardrailRuleContext } from "../contracts-core/guardrail-packs.js";
+import type { ToolResult } from "../contracts-protocol.js";
+/** What a pack's `build` returns: restrictive rules plus an optional pure result observer. */
+export interface GuardrailPackRules {
+    readonly rules: readonly GuardrailRule[];
+    /** Records tool results into pack-local state (never denies); a throw fails closed as a guardrail tripwire. */
+    readonly observe?: (state: Record<string, unknown>, result: ToolResult, context: GuardrailRuleContext) => void;
+}
+export interface GuardrailPackDefinition {
+    readonly id: string;
+    readonly version: number;
+    readonly description: string;
+    /** Pure factory: options in, rules out. No session access, no I/O. */
+    readonly build: (options: Readonly<Record<string, unknown>>) => GuardrailPackRules;
+}

package/dist/guardrail-packs/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/guardrail-packs/validation-respect.d.ts

@@ -0,0 +1,3 @@
+import type { GuardrailPackDefinition } from "./types.js";
+/** Canned "respect failed validation": once a validation tool result fails, file mutations are denied until one passes. */
+export declare const validationRespectPack: GuardrailPackDefinition;

package/dist/guardrail-packs/validation-respect.js

@@ -0,0 +1,53 @@
+import { GuardrailPackError } from "./errors.js";
+const MUTATING_TOOLS = ["write", "edit", "delete", "move"];
+/** Validation-style tool names. `shell` is opt-in (`validationTools`): a non-zero shell exit is a failure signal too. */
+const DEFAULT_VALIDATION_TOOLS = ["test", "run_tests", "validate", "validation", "lint", "typecheck", "check"];
+const MAX_VALIDATION_TOOLS = 16;
+/** A tool result failed when it carries an error, or reported a non-zero `exitCode` (the shell tool's shape). */
+function resultFailed(result) {
+    if (result.error !== undefined)
+        return true;
+    const value = result.value;
+    if (!value || typeof value !== "object" || !("exitCode" in value))
+        return false;
+    const exitCode = value.exitCode;
+    return typeof exitCode === "number" && exitCode !== 0;
+}
+function readValidationTools(value) {
+    if (value === undefined)
+        return DEFAULT_VALIDATION_TOOLS;
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_VALIDATION_TOOLS) {
+        throw new GuardrailPackError(`validation-respect options.validationTools must be a non-empty string array (max ${MAX_VALIDATION_TOOLS})`);
+    }
+    return value.map((name) => {
+        if (typeof name !== "string" || !name.trim()) {
+            throw new GuardrailPackError("validation-respect options.validationTools entries must be non-empty strings");
+        }
+        return name;
+    });
+}
+/** Canned "respect failed validation": once a validation tool result fails, file mutations are denied until one passes. */
+export const validationRespectPack = {
+    id: "validation-respect",
+    version: 1,
+    description: "Denies file mutations after a failed validation tool result until a later validation passes.",
+    build(options) {
+        const validationTools = readValidationTools(options.validationTools);
+        return {
+            observe(state, result, context) {
+                if (!validationTools.includes(context.toolName))
+                    return;
+                state.validationFailed = resultFailed(result) ? context.toolName : undefined;
+            },
+            rules: [
+                {
+                    id: "no-mutation-after-failed-validation",
+                    tool: MUTATING_TOOLS,
+                    reason: "A previous validation result failed; fix it before mutating files",
+                    deny: (_args, context) => context.state.validationFailed !== undefined,
+                },
+            ],
+        };
+    },
+};
+//# sourceMappingURL=validation-respect.js.map

package/dist/guardrails.d.ts

@@ -1,6 +1,10 @@
-import type { AgentEvent, GuardrailContext, GuardrailRecord, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
+import type { AgentEvent, GuardrailContext, GuardrailPackRef, GuardrailRecord, GuardrailStage, Guardrails, GuardrailValue } from "./contracts.js";
+export { GuardrailPackError } from "./guardrail-packs/errors.js";
 import type { SecretRedactor } from "./redaction.js";
 export declare const MAX_GUARDRAIL_CONCURRENCY = 16;
+/** Guardrail pack compile bounds (plan 092 Task 2). All ceilings are config-shape limits, not runtime budgets. */
+export declare const MAX_GUARDRAIL_PACKS = 8;
+export declare const MAX_GUARDRAIL_PACK_RULES = 64;
 export declare class GuardrailError extends Error {
     readonly code: string;
     readonly record: GuardrailRecord;
@@ -23,3 +27,18 @@ export interface GuardrailRunResult {
 /** Evaluate one typed stage. Default is declaration-order sequential; bounded parallel mode still reports declaration order. */
 export declare function runGuardrails<S extends GuardrailStage>(options: RunGuardrailsOptions<S>): Promise<GuardrailRunResult>;
 export declare function assertGuardrailsAllowed(result: GuardrailRunResult): void;
+/** One `guardrail:<stage>` identity row of a compiled pack, for run-bundle fingerprints. */
+export interface GuardrailPackRow {
+    readonly name: string;
+    readonly stage: "tool_input" | "tool_output";
+    readonly revision: string | null;
+}
+/**
+ * Compiles `guardrailPacks` config onto the existing tool interception seams: one `tool_input`
+ * guardrail per rule (`name = pack:<pack>/<rule>`), plus one `tool_output` recorder for packs that
+ * observe results. Compiled once per session — patterns are compiled here, never per tool call.
+ * Throws `GuardrailPackError` on malformed config (fail closed); returns `undefined` when unset.
+ */
+export declare function compileGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): Guardrails | undefined;
+/** Stable identity rows for the same config `compileGuardrailPacks` accepts (no state, no guardrails built). */
+export declare function describeGuardrailPacks(refs: readonly GuardrailPackRef[] | undefined, registry?: ReadonlyMap<string, import("./guardrail-packs/types.js").GuardrailPackDefinition>): readonly GuardrailPackRow[];