@deepstrike/sdk 0.2.22 → 0.2.23

package/dist/governance.d.ts

@@ -29,7 +29,28 @@ export interface GovernancePolicy {
         windowMs: number;
     }[];
     constraints?: GovernanceConstraint[];
+    /** I5: when true (default), the runner pre-filters denied tools out of the schema passed to the
+     *  provider — the model never sees them and never tries to call them, eliminating the rollback
+     *  turn the kernel would otherwise produce. The denied tool names are also surfaced as a single
+     *  line on the system slot so the model knows not to plan around them. Set to false to fall
+     *  back to the v0.2.22 rollback-based behavior (useful for measuring the delta or when the
+     *  agent should learn the denial via a real attempt). */
+    surfaceDeniedInSystem?: boolean;
 }
+/** I5: walk the tool list and bucket each tool into `allowed` / `denied` based on a declarative
+ *  policy. A tool is denied when:
+ *    - the tool name appears in `vetoes`
+ *    - a `rules[i].pattern` matches the tool name and the rule's `action === "deny"`
+ *    - or `defaultAction === "deny"` and no `allow` rule matches
+ *  `ask_user` is treated as allowed at the schema layer — the runtime decides at call time.
+ *  Pattern matching is exact match or a glob with a single trailing `*` (so `"write_*"` denies
+ *  `write_file` and `write_db`). Pure — no side effects. */
+export declare function governanceFilterSchema<T extends {
+    name: string;
+}>(tools: T[], policy: GovernancePolicy | undefined): {
+    allowed: T[];
+    denied: string[];
+};
 export type GovernanceConstraint = {
     kind: "required";
     tool: string;

package/dist/governance.js

@@ -32,6 +32,38 @@ export class Governance {
         return this.inner.evaluate(toolName, argsJson);
     }
 }
+/** I5: walk the tool list and bucket each tool into `allowed` / `denied` based on a declarative
+ *  policy. A tool is denied when:
+ *    - the tool name appears in `vetoes`
+ *    - a `rules[i].pattern` matches the tool name and the rule's `action === "deny"`
+ *    - or `defaultAction === "deny"` and no `allow` rule matches
+ *  `ask_user` is treated as allowed at the schema layer — the runtime decides at call time.
+ *  Pattern matching is exact match or a glob with a single trailing `*` (so `"write_*"` denies
+ *  `write_file` and `write_db`). Pure — no side effects. */
+export function governanceFilterSchema(tools, policy) {
+    if (!policy)
+        return { allowed: tools, denied: [] };
+    const vetoes = new Set(policy.vetoes ?? []);
+    const allowed = [];
+    const denied = [];
+    const matches = (pat, name) => pat === name || (pat.endsWith("*") && name.startsWith(pat.slice(0, -1)));
+    for (const tool of tools) {
+        if (vetoes.has(tool.name)) {
+            denied.push(tool.name);
+            continue;
+        }
+        let action = policy.defaultAction ?? "allow";
+        for (const r of policy.rules ?? []) {
+            if (matches(r.pattern, tool.name))
+                action = r.action;
+        }
+        if (action === "deny")
+            denied.push(tool.name);
+        else
+            allowed.push(tool);
+    }
+    return { allowed, denied };
+}
 /**
  * Convert a declarative {@link GovernancePolicy} into the `load_governance_policy`
  * kernel event payload (snake_case wire fields). Pure — no side effects.

package/dist/harness/harness.d.ts

@@ -5,6 +5,14 @@ export interface Criterion {
     text: string;
     required: boolean;
     weight?: number;
+    /** I3.3 (A4): optional stable identifier from the host's contract layer (e.g. an
+     *  `acceptance[].id` field). The harness does not interpret it; it just threads it through to
+     *  `verdictFn` so the host can dispatch per-criterion deterministic checks by id. */
+    id?: string;
+    /** I3.3 (A4): host hint — when true, the host has a deterministic check for this criterion
+     *  and would short-circuit the LLM eval. The harness still defers to the host's `verdictFn`
+     *  for the actual decision; this is purely a transparency field on the request. */
+    machineCheckable?: boolean;
 }
 export interface CriterionResult {
     criterion: string;
@@ -83,6 +91,14 @@ export declare class SinglePassHarness {
     run(request: HarnessRequest): Promise<HarnessOutcome>;
     stream(request: HarnessRequest): AsyncIterable<StreamEvent>;
 }
+/**
+ * @deprecated I3.4 (A1): prefer {@link HarnessLoop} with `verdictFn` for host-defined judgment.
+ * `EvalLoopHarness.stream()` does NOT honor the `gate` passed via `request.gate` (only `.run()`
+ * does), which is a long-standing footgun for streaming hosts. `HarnessLoop` runs the eval loop
+ * uniformly across both stream and run, accepts an optional `verdictFn` for short-circuiting the
+ * built-in LLM eval, and otherwise mirrors `EvalLoopHarness`'s behavior. New code should use
+ * `HarnessLoop`; existing call sites can migrate by switching the class + (if applicable)
+ * passing a `verdictFn` for the same gate logic. Slated for removal in a future major. */
 export declare class EvalLoopHarness {
     private runner;
     private gate;
@@ -91,15 +107,29 @@ export declare class EvalLoopHarness {
     run(request: HarnessRequest): Promise<HarnessOutcome>;
     stream(request: HarnessRequest): AsyncIterable<StreamEvent>;
 }
+/** I3.2 (A2/A3): host-supplied judgment for each attempt's result. Returning a `Verdict` short-
+ *  circuits the built-in LLM eval (no `evalProvider.stream` call); returning `undefined` defers to
+ *  the built-in eval (enables hybrid judgment: machine-checkable items deterministic, subjective
+ *  items LLM). Pure addition — when not set, HarnessLoop.stream() is byte-equivalent to its prior
+ *  behavior. The closure owns its own context (doc reader, deterministic checks, etc.); the SDK
+ *  is intentionally agnostic about what it inspects. */
+export type VerdictFn = (ctx: {
+    goal: string;
+    criteria: Criterion[];
+    attempt: number;
+    result: string;
+}) => Verdict | undefined | Promise<Verdict | undefined>;
 export interface HarnessLoopOptions {
     maxAttempts?: number;
     skillDir?: string;
+    verdictFn?: VerdictFn;
 }
 export declare class HarnessLoop {
     private runner;
     private evalProvider;
     private maxAttempts;
     private skillDir?;
+    private verdictFn?;
     constructor(runner: RuntimeRunner, evalProvider: import("../types.js").LLMProvider, options?: HarnessLoopOptions);
     run(request: HarnessRequest): Promise<HarnessOutcome>;
     stream(request: HarnessRequest): AsyncIterable<HarnessEvent>;

package/dist/harness/harness.js

@@ -26,6 +26,14 @@ export class SinglePassHarness {
         yield* this.runner.run({ sessionId: crypto.randomUUID(), goal: request.goal, criteria: request.criteria?.map(c => c.text), extensions: request.extensions });
     }
 }
+/**
+ * @deprecated I3.4 (A1): prefer {@link HarnessLoop} with `verdictFn` for host-defined judgment.
+ * `EvalLoopHarness.stream()` does NOT honor the `gate` passed via `request.gate` (only `.run()`
+ * does), which is a long-standing footgun for streaming hosts. `HarnessLoop` runs the eval loop
+ * uniformly across both stream and run, accepts an optional `verdictFn` for short-circuiting the
+ * built-in LLM eval, and otherwise mirrors `EvalLoopHarness`'s behavior. New code should use
+ * `HarnessLoop`; existing call sites can migrate by switching the class + (if applicable)
+ * passing a `verdictFn` for the same gate logic. Slated for removal in a future major. */
 export class EvalLoopHarness {
     runner;
     gate;
@@ -53,11 +61,13 @@ export class HarnessLoop {
     evalProvider;
     maxAttempts;
     skillDir;
+    verdictFn;
     constructor(runner, evalProvider, options = {}) {
         this.runner = runner;
         this.evalProvider = evalProvider;
         this.maxAttempts = options.maxAttempts ?? 3;
         this.skillDir = options.skillDir;
+        this.verdictFn = options.verdictFn;
     }
     async run(request) {
         let last;
@@ -125,28 +135,38 @@ export class HarnessLoop {
                 }
             }
             yield { type: "supervising" };
-            // #6 (0.5.0): the eval/verdict compute is the kernel's stateless free functions (was the
-            // EvalPipeline state machine). Build the eval prompt, call the eval LLM, parse the verdict.
-            const evalMsgs = kernel.buildEvalMessages(request.goal, criteria, lastResult, attempt, true);
-            let evalText = "";
-            const evalContext = {
-                systemText: evalMsgs.filter((m) => m.role === "system").map((m) => m.content).join("\n\n"),
-                turns: evalMsgs.filter((m) => m.role !== "system"),
-            };
-            for await (const evt of this.evalProvider.stream(evalContext, [], undefined)) {
-                if (evt.type === "text_delta")
-                    evalText += evt.delta;
+            // I3.2 (A2/A3): host-supplied `verdictFn` short-circuits the LLM eval. When it returns a
+            // Verdict, use it; when it returns undefined, defer to the built-in eval (hybrid path).
+            let verdict;
+            let skillCandidate;
+            if (this.verdictFn) {
+                verdict = await this.verdictFn({ goal: request.goal, criteria, attempt, result: lastResult });
+            }
+            if (!verdict) {
+                // #6 (0.5.0): the eval/verdict compute is the kernel's stateless free functions (was the
+                // EvalPipeline state machine). Build the eval prompt, call the eval LLM, parse the verdict.
+                const evalMsgs = kernel.buildEvalMessages(request.goal, criteria, lastResult, attempt, true);
+                let evalText = "";
+                const evalContext = {
+                    systemText: evalMsgs.filter((m) => m.role === "system").map((m) => m.content).join("\n\n"),
+                    turns: evalMsgs.filter((m) => m.role !== "system"),
+                };
+                for await (const evt of this.evalProvider.stream(evalContext, [], undefined)) {
+                    if (evt.type === "text_delta")
+                        evalText += evt.delta;
+                }
+                const parsed = kernel.parseVerdict(evalText);
+                verdict = {
+                    passed: parsed.passed,
+                    overallScore: parsed.overallScore,
+                    feedback: parsed.feedback,
+                    details: parsed.details ?? [],
+                };
+                skillCandidate = parsed.skillCandidate;
             }
-            const parsed = kernel.parseVerdict(evalText);
-            const verdict = {
-                passed: parsed.passed,
-                overallScore: parsed.overallScore,
-                feedback: parsed.feedback,
-                details: parsed.details ?? [],
-            };
             if (verdict.passed) {
-                if (parsed.skillCandidate && this.skillDir) {
-                    const { name, description, whenToUse, content } = parsed.skillCandidate;
+                if (skillCandidate && this.skillDir) {
+                    const { name, description, whenToUse, content } = skillCandidate;
                     const fm = ["---", `name: ${name}`, `description: ${description}`,
                         whenToUse ? `when_to_use: ${whenToUse}` : null, "---", ""]
                         .filter(Boolean).join("\n");

package/dist/index.d.ts

@@ -71,7 +71,7 @@ export type { PermissionDecision, Permission } from "./safety/permissions.js";
 export { Governance, governancePolicyToKernelEvent } from "./governance.js";
 export type { GovernanceVerdict, GovernancePolicy, GovernanceConstraint } from "./governance.js";
 export { SinglePassHarness, EvalLoopHarness, HarnessLoop } from "./harness/harness.js";
-export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate } from "./harness/harness.js";
+export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, QualityGate, CriterionResult, HarnessEvent, VerdictFn } from "./harness/harness.js";
 export type { Message, ToolCall, ToolResult, ToolSchema, ContentPart, TextPart, ImagePart, AudioPart, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolChunk, ToolDeltaEvent, ToolSuspendEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, RetryConfig, TokenUsage, ProviderToolSpec, ProviderRunState, ProviderReplay, RenderedContext, ReplayabilityAssessment, CacheBreakpointStrategy, } from "./types.js";
 export type { AgentCapabilityFilter, AgentIdentity, AgentIsolation, AgentRunSpec, AgentProcessChangedObservation, ContextInheritance, KernelAgentRole, LoopResult, MilestoneCheckResult, MilestoneContract, MilestonePhase, MilestonePolicy, SubAgentResult, TerminationReason, WorkflowSpec, WorkflowNodeSpec, WorkflowTaskSpec, WorkflowSpawnInfo, } from "./types/agent.js";
 export { agentIdentitySub, agentRunSpecToKernel, milestoneCheckFail, milestoneCheckPass, milestoneCheckResultToKernel, subAgentResultToKernel, workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules, genEval, } from "./types/agent.js";

package/dist/providers/anthropic.js

@@ -139,6 +139,11 @@ export class AnthropicProvider {
         const msgs = this.buildMessages(context, strategy);
         assertCacheBudget(system, tools.length);
         const requestExtensions = this.requestExtensions(extensions);
+        const builtTools = tools.length ? this.buildTools(tools, !Array.isArray(system), strategy) : undefined;
+        // I1: capture which slots will carry cache_control so cache_read_input_tokens can be
+        // attributed pro-rata when the response arrives. Honest annotation: Anthropic returns one
+        // scalar (no per-slot breakdown), so this is an estimate, not authoritative.
+        const slotBp = countCacheControlSlots(system, builtTools, msgs);
         const toolBlocks = {};
         const nativeBlocks = {};
         let finalText = "";
@@ -149,7 +154,7 @@ export class AnthropicProvider {
             max_tokens: typeof extensions?.max_tokens === "number" ? extensions.max_tokens : 8096,
             ...(system ? { system } : {}),
             messages: msgs,
-            ...(tools.length ? { tools: this.buildTools(tools, !Array.isArray(system), strategy) } : {}),
+            ...(builtTools ? { tools: builtTools } : {}),
         }, extensions, signal);
         let uncachedInput = 0;
         let cacheReadTokens = 0;
@@ -171,6 +176,7 @@ export class AnthropicProvider {
                     // context-pressure/compaction — excluding cached tokens would make a
                     // cache-heavy turn look tiny and suppress compaction until a 413.
                     const inputTokens = uncachedInput + cacheReadTokens + cacheCreationTokens;
+                    const bySlot = estimateCacheReadBySlot(cacheReadTokens, slotBp);
                     yield {
                         type: "usage",
                         totalTokens: inputTokens + outputTokens,
@@ -178,6 +184,7 @@ export class AnthropicProvider {
                         outputTokens,
                         cacheReadInputTokens: cacheReadTokens,
                         cacheCreationInputTokens: cacheCreationTokens,
+                        ...(bySlot ? { cacheReadInputTokensBySlot: bySlot } : {}),
                     };
                 }
             }
@@ -304,6 +311,58 @@ function resolveCacheBreakpointStrategy(extensions) {
     }
     return "default";
 }
+/**
+ * I1: count which slots of the outgoing request carry a `cache_control` breakpoint. Used to
+ * pro-rata-attribute the response's `cache_read_input_tokens` (a single scalar with no per-slot
+ * breakdown) across the slots that contributed to the cache hit. Returns whether each slot has
+ * any breakpoint — not the actual count, since pro-rata only needs the contributing slot set.
+ */
+function countCacheControlSlots(system, builtTools, msgs) {
+    const sysBp = Array.isArray(system) && system.some(b => b?.cache_control != null);
+    const toolBp = !!builtTools && builtTools.some(t => t?.cache_control != null);
+    let msgBp = false;
+    for (const m of msgs) {
+        if (Array.isArray(m.content)) {
+            if (m.content.some(b => b?.cache_control != null)) {
+                msgBp = true;
+                break;
+            }
+        }
+    }
+    return { system: sysBp, tools: toolBp, messages: msgBp };
+}
+/**
+ * I1: split the response's `cache_read_input_tokens` evenly across the slots that carried a
+ * cache_control breakpoint on the request. Returns undefined when there's no cache read or no
+ * contributing slot — in those cases the consumer is better off seeing the field absent than
+ * seeing all zeros. The remainder (if the total doesn't divide evenly) lands on the first
+ * contributing slot to keep the sum exact.
+ */
+function estimateCacheReadBySlot(cacheRead, slotBp) {
+    if (cacheRead <= 0)
+        return undefined;
+    const count = (slotBp.system ? 1 : 0) + (slotBp.tools ? 1 : 0) + (slotBp.messages ? 1 : 0);
+    if (count === 0)
+        return undefined;
+    const share = Math.floor(cacheRead / count);
+    const remainder = cacheRead - share * count;
+    const out = {};
+    let firstDone = false;
+    const give = () => {
+        if (!firstDone) {
+            firstDone = true;
+            return share + remainder;
+        }
+        return share;
+    };
+    if (slotBp.system)
+        out.system = give();
+    if (slotBp.tools)
+        out.tools = give();
+    if (slotBp.messages)
+        out.messages = give();
+    return out;
+}
 /** Anthropic accepts at most this many cache_control breakpoints per request. */
 const MAX_CACHE_BREAKPOINTS = 4;
 /**

package/dist/runtime/runner.d.ts

@@ -36,6 +36,16 @@ export interface TurnMetrics {
     inputTokens: number;
     /** Tokens served from the prompt cache this turn (Anthropic `cache_read_input_tokens`). */
     cacheReadTokens: number;
+    /** I1: per-slot attribution of `cacheReadTokens`. Anthropic reports a single cache-read total,
+     *  not a per-block breakdown — this field is a pro-rata estimate over the slots that actually
+     *  carried a `cache_control` breakpoint on the request. Missing / empty when the provider does
+     *  not honor `cache_control` (OpenAI-family auto-cache) or when no breakpoints were placed.
+     *  Useful for diagnosing which slot is buying the cache hit when comparing strategies. */
+    cacheReadTokensBySlot?: {
+        system?: number;
+        tools?: number;
+        messages?: number;
+    };
     /** Tokens written to the prompt cache this turn (Anthropic `cache_creation_input_tokens`). */
     cacheCreationTokens: number;
 }
@@ -60,6 +70,17 @@ export interface RuntimeOptions {
     maxTurns?: number;
     timeoutMs?: number;
     agentId?: string;
+    /** I4: optional run-start memory pre-fetch hook. The runner calls this ONCE per run, before the
+     *  first LLM turn, with the request's goal and (optional) run-spec. Each returned query string
+     *  becomes a `dreamStore.search(agentId, q, 5)` and the resulting hits are paged into the
+     *  context's knowledge partition before turn 1, so the model sees them on first call. Returning
+     *  `undefined` / empty array is a no-op. Requires `dreamStore` + `agentId`; missing either ⇒
+     *  silently skipped (errs-open). Bench memory-recall shows -57% turns / -55% dollars when
+     *  relevant memories land on turn 1 instead of being discovered via the meta-tool on turn 3+. */
+    preQueryMemory?: (ctx: {
+        goal: string;
+        runSpec?: AgentRunSpec;
+    }) => Promise<string[] | undefined> | string[] | undefined;
     systemPrompt?: string;
     initialMemory?: string[];
     skillDir?: string;

package/dist/runtime/runner.js

@@ -11,7 +11,7 @@ import { defaultSubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { extractJsonValue, schemaInstruction, schemaRetryInstruction, validateAgainstSchema, } from "./output-schema.js";
 import { resolveReducer } from "./reducers.js";
 import { loopInstruction, classifyInstruction, judgeGoal, extractLoopContinue, extractClassifyBranch, extractJudgeWinner, } from "./workflow-control-flow.js";
-import { governancePolicyToKernelEvent } from "../governance.js";
+import { governancePolicyToKernelEvent, governanceFilterSchema } from "../governance.js";
 import { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
 import { assertNativeProfile } from "./os-profile.js";
 import { LargeResultSpool } from "./large-result-spool.js";
@@ -973,6 +973,26 @@ export class RuntimeRunner {
                 message: attachmentsToKernelMessage(attachments),
             });
         }
+        // I4: pre-fetch memory into the knowledge partition before the first LLM turn. Skipped on
+        // resumes (memory was already on the prior context) and when dreamStore/agentId is absent.
+        if (!resumeMidRun && this.opts.preQueryMemory && this.opts.dreamStore && this.opts.agentId) {
+            try {
+                const queries = await this.opts.preQueryMemory({ goal, runSpec: this.opts.runSpec });
+                const entries = [];
+                for (const q of queries ?? []) {
+                    if (typeof q !== "string" || !q.trim())
+                        continue;
+                    const hits = await this.opts.dreamStore.search(this.opts.agentId, q, 5);
+                    for (const hit of hits) {
+                        entries.push({ content: `[memory score=${hit.score.toFixed(3)}] ${hit.text}`, source: "memory" });
+                    }
+                }
+                if (entries.length > 0) {
+                    kernelApply(runtime, this.pendingObservations, { kind: "page_in", entries });
+                }
+            }
+            catch { /* errs-open — a faulty pre-fetch never breaks the run */ }
+        }
         let action = resumeMidRun
             ? kernelAction(runtime, this.pendingObservations, { kind: "resume" })
             : kernelAction(runtime, this.pendingObservations, startPayload);
@@ -980,369 +1000,440 @@ export class RuntimeRunner {
         // P0-C: the skill loaded and in effect going into the current turn (updated when the model's
         // `skill` tool call resolves). Drives the per-turn `activeSkill` metric → dwell measurement.
         let activeSkill;
-        while (!runtime.isTerminal()) {
-            // Page-in must run before appendObservations drains pending kernel observations.
-            if (action.kind === "execute_tool") {
-                await this.applyKernelPageIn(runtime, sessionId);
-            }
-            nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
-            this.nextArchiveStart = nextCompressedArchiveStart;
-            if (this.interrupted) {
-                action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
-                break;
-            }
-            if (this.opts.signalSource) {
-                const sig = await this.opts.signalSource.nextSignal();
-                if (sig) {
-                    // Kernel-routed: the kernel decides disposition (dedup/queue/interrupt) and emits
-                    // `signal_disposed`. An actionable disposition yields a new action to adopt; queued/observed/
-                    // ignored yields none (kernel buffers).
-                    const sigAction = kernelMaybeAction(runtime, this.pendingObservations, signalToKernelEvent(sig));
-                    if (sigAction)
-                        action = sigAction;
+        // I0b: wrap the main loop so any uncaught kernel exception (typically a NAPI
+        // Status::InvalidArg from a malformed input — e.g. RuntimeSignal.source with a wrong shape,
+        // or an unrecognized event kind) is observable rather than silently propagating out of the
+        // async generator. Without this wrap the runner emits no `run_terminal` event, so downstream
+        // observability (session log, bench mechanism hooks) can't distinguish "the kernel rejected
+        // an input" from "the run is still in progress."
+        try {
+            while (!runtime.isTerminal()) {
+                // Page-in must run before appendObservations drains pending kernel observations.
+                if (action.kind === "execute_tool") {
+                    await this.applyKernelPageIn(runtime, sessionId);
                 }
-            }
-            if (runtime.isTerminal())
-                break;
-            if (action.kind === "call_provider") {
-                // M5 v2.1: top-level auto-pivot at the safe point. If the agent authored sub-workflow(s) via
-                // `start_workflow`, drive each in THIS kernel now (the kernel is in Reason / `call_provider`,
-                // NOT suspended — driving mid-suspend would clobber the single-slot suspend state), inject the
-                // outcome into context, and re-render. Loop-top placement (vs only after `tool_results`) catches
-                // EVERY path to `call_provider` — including resuming after an approval gate — so a queued spec
-                // is never stranded. Drains the queue; fires once per authored batch.
-                if (this.pendingAuthoredWorkflows.length > 0) {
-                    action = await this.driveAuthoredWorkflows(runtime, action);
+                nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
+                this.nextArchiveStart = nextCompressedArchiveStart;
+                if (this.interrupted) {
+                    action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
+                    break;
                 }
-                const finalToolCalls = [];
-                let finalText = "";
-                const context = action.context;
-                const tools = action.tools;
-                let turnTokens = 0;
-                let turnInputTokens = 0;
-                let turnOutputTokens = 0;
-                let turnCacheReadTokens = 0;
-                let turnCacheCreationTokens = 0;
-                let shouldRetry = false;
-                const abortSignal = this.abortController?.signal;
-                try {
-                    for await (const evt of this.opts.provider.stream(context, tools, Object.keys(ext).length ? ext : undefined, providerState, abortSignal)) {
-                        // #2-B-ii: a preempting `interrupt()` fires `abortController` — stop consuming the live
-                        // stream immediately (providers that forward `signal` also abort the socket; the rest at
-                        // least stop here at the next event). The loop-top `interrupted` check then ends the run.
-                        if (abortSignal?.aborted)
-                            break;
-                        if (evt.type === "usage") {
-                            const usageEvt = evt;
-                            turnTokens = usageEvt.totalTokens;
-                            turnInputTokens = usageEvt.inputTokens ?? 0;
-                            turnOutputTokens = usageEvt.outputTokens ?? 0;
-                            // P0-C: capture the prompt-cache split for the tool-gating hit-rate baseline.
-                            turnCacheReadTokens = usageEvt.cacheReadInputTokens ?? 0;
-                            turnCacheCreationTokens = usageEvt.cacheCreationInputTokens ?? 0;
-                            continue;
-                        }
-                        yield evt;
-                        if (evt.type === "text_delta")
-                            finalText += evt.delta;
-                        else if (evt.type === "tool_call") {
-                            const tc = evt;
-                            finalToolCalls.push({ id: tc.id, name: tc.name, arguments: JSON.stringify(tc.arguments) });
-                        }
+                if (this.opts.signalSource) {
+                    const sig = await this.opts.signalSource.nextSignal();
+                    if (sig) {
+                        // Kernel-routed: the kernel decides disposition (dedup/queue/interrupt) and emits
+                        // `signal_disposed`. An actionable disposition yields a new action to adopt; queued/observed/
+                        // ignored yields none (kernel buffers).
+                        const sigAction = kernelMaybeAction(runtime, this.pendingObservations, signalToKernelEvent(sig));
+                        if (sigAction)
+                            action = sigAction;
+                        // I0a: a Critical-urgency signal carries user_abort intent. The kernel disposes it as
+                        // InterruptNow (forces a Reason turn) but does NOT call abortController.abort() unless
+                        // sub-agents are suspended — so the no-sub-agent path (e.g. the signal-injection bench
+                        // scenario) wouldn't otherwise set `this.interrupted`, and the eventual run_terminal would
+                        // report `reason: "error"` indistinguishable from a crash. Mark it here so the final
+                        // classification in the run_terminal emit picks `user_abort`.
+                        if (sig.urgency === "critical")
+                            this.interrupted = true;
                     }
                 }
-                catch (err) {
-                    // #2-B-ii: an aborted in-flight request surfaces as an AbortError — treat it as an interrupt
-                    // (the loop-top `interrupted` check converts it to a clean `timeout`/UserAbort), not a crash.
-                    if (abortSignal?.aborted) {
-                        this.interrupted = true;
+                if (runtime.isTerminal())
+                    break;
+                if (action.kind === "call_provider") {
+                    // M5 v2.1: top-level auto-pivot at the safe point. If the agent authored sub-workflow(s) via
+                    // `start_workflow`, drive each in THIS kernel now (the kernel is in Reason / `call_provider`,
+                    // NOT suspended — driving mid-suspend would clobber the single-slot suspend state), inject the
+                    // outcome into context, and re-render. Loop-top placement (vs only after `tool_results`) catches
+                    // EVERY path to `call_provider` — including resuming after an approval gate — so a queued spec
+                    // is never stranded. Drains the queue; fires once per authored batch.
+                    if (this.pendingAuthoredWorkflows.length > 0) {
+                        action = await this.driveAuthoredWorkflows(runtime, action);
                     }
-                    const errMsg = String(err).toLowerCase();
-                    if ((errMsg.includes("413") || errMsg.includes("too long") || errMsg.includes("context length exceeded") || errMsg.includes("context_length_exceeded")) &&
-                        !hasAttemptedReactiveCompact) {
-                        hasAttemptedReactiveCompact = true;
-                        if (forceCompact(runtime, this.pendingObservations)) {
-                            nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
-                            shouldRetry = true;
+                    const finalToolCalls = [];
+                    let finalText = "";
+                    // I5: governance schema-level pre-filter. When a declarative GovernancePolicy is loaded
+                    // and `surfaceDeniedInSystem !== false`, drop denied tools from the schema BEFORE the
+                    // model sees them — the model can't plan a call it doesn't know about, so the rollback
+                    // overhead disappears. The list of denied names is appended to systemKnowledge so the
+                    // model knows not to plan around them.
+                    let context = action.context;
+                    let tools = action.tools;
+                    if (this.opts.governancePolicy && this.opts.governancePolicy.surfaceDeniedInSystem !== false) {
+                        const { allowed, denied } = governanceFilterSchema(tools, this.opts.governancePolicy);
+                        if (denied.length > 0) {
+                            tools = allowed;
+                            const note = `[governance] the following tools are denied for this run and will fail if called: ${denied.join(", ")}.`;
+                            context = {
+                                ...context,
+                                systemKnowledge: context.systemKnowledge
+                                    ? `${context.systemKnowledge}\n\n${note}`
+                                    : note,
+                            };
                         }
                     }
-                    if (!shouldRetry) {
-                        yield { type: "error", message: String(err) };
+                    let turnTokens = 0;
+                    let turnInputTokens = 0;
+                    let turnOutputTokens = 0;
+                    let turnCacheReadTokens = 0;
+                    let turnCacheCreationTokens = 0;
+                    let turnCacheReadBySlot;
+                    let shouldRetry = false;
+                    const abortSignal = this.abortController?.signal;
+                    try {
+                        for await (const evt of this.opts.provider.stream(context, tools, Object.keys(ext).length ? ext : undefined, providerState, abortSignal)) {
+                            // #2-B-ii: a preempting `interrupt()` fires `abortController` — stop consuming the live
+                            // stream immediately (providers that forward `signal` also abort the socket; the rest at
+                            // least stop here at the next event). The loop-top `interrupted` check then ends the run.
+                            if (abortSignal?.aborted)
+                                break;
+                            if (evt.type === "usage") {
+                                const usageEvt = evt;
+                                turnTokens = usageEvt.totalTokens;
+                                turnInputTokens = usageEvt.inputTokens ?? 0;
+                                turnOutputTokens = usageEvt.outputTokens ?? 0;
+                                // P0-C: capture the prompt-cache split for the tool-gating hit-rate baseline.
+                                turnCacheReadTokens = usageEvt.cacheReadInputTokens ?? 0;
+                                turnCacheCreationTokens = usageEvt.cacheCreationInputTokens ?? 0;
+                                // I1: per-slot attribution forwarded into TurnMetrics. Undefined when the provider
+                                // doesn't honor cache_control (OpenAI-family auto-cache).
+                                turnCacheReadBySlot = usageEvt.cacheReadInputTokensBySlot;
+                                continue;
+                            }
+                            yield evt;
+                            if (evt.type === "text_delta")
+                                finalText += evt.delta;
+                            else if (evt.type === "tool_call") {
+                                const tc = evt;
+                                finalToolCalls.push({ id: tc.id, name: tc.name, arguments: JSON.stringify(tc.arguments) });
+                            }
+                        }
+                    }
+                    catch (err) {
+                        // #2-B-ii: an aborted in-flight request surfaces as an AbortError — treat it as an interrupt
+                        // (the loop-top `interrupted` check converts it to a clean `timeout`/UserAbort), not a crash.
+                        if (abortSignal?.aborted) {
+                            this.interrupted = true;
+                        }
+                        const errMsg = String(err).toLowerCase();
+                        if ((errMsg.includes("413") || errMsg.includes("too long") || errMsg.includes("context length exceeded") || errMsg.includes("context_length_exceeded")) &&
+                            !hasAttemptedReactiveCompact) {
+                            hasAttemptedReactiveCompact = true;
+                            if (forceCompact(runtime, this.pendingObservations)) {
+                                nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
+                                shouldRetry = true;
+                            }
+                        }
+                        if (!shouldRetry) {
+                            yield { type: "error", message: String(err) };
+                            action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
+                            break;
+                        }
+                    }
+                    // #2-B-ii: stream aborted (preempt/interrupt) via the break path (provider yielded no error) —
+                    // end the turn now with a timeout so the kernel terminates the run, rather than feeding the
+                    // partial assistant output as a normal turn.
+                    if (abortSignal?.aborted) {
                         action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
                         break;
                     }
-                }
-                // #2-B-ii: stream aborted (preempt/interrupt) via the break path (provider yielded no error) —
-                // end the turn now with a timeout so the kernel terminates the run, rather than feeding the
-                // partial assistant output as a normal turn.
-                if (abortSignal?.aborted) {
-                    action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
-                    break;
-                }
-                if (shouldRetry) {
-                    action = {
-                        kind: "call_provider",
-                        context: runtime.render(),
-                        tools,
+                    if (shouldRetry) {
+                        action = {
+                            kind: "call_provider",
+                            context: runtime.render(),
+                            tools,
+                        };
+                        continue;
+                    }
+                    const assistantMessage = {
+                        role: "assistant",
+                        content: finalText,
+                        toolCalls: finalToolCalls,
+                        tokenCount: turnOutputTokens || turnTokens || undefined,
                     };
-                    continue;
-                }
-                const assistantMessage = {
-                    role: "assistant",
-                    content: finalText,
-                    toolCalls: finalToolCalls,
-                    tokenCount: turnOutputTokens || turnTokens || undefined,
-                };
-                const providerEvent = {
-                    kind: "provider_result",
-                    message: messageToKernelMessage(assistantMessage),
-                    ...(turnInputTokens > 0 ? { observed_input_tokens: turnInputTokens } : {}),
-                    ...(turnOutputTokens > 0 ? { observed_output_tokens: turnOutputTokens } : {}),
-                    now_ms: Date.now(),
-                };
-                let nextAction = kernelMaybeAction(runtime, this.pendingObservations, providerEvent);
-                if (!nextAction && this.pendingObservations.some(o => o.kind === "suspended")) {
-                    const resolved = await this.resolveKernelSuspend(runtime, sessionId);
-                    for (const evt of resolved.events)
-                        yield evt;
-                    nextAction = kernelAction(runtime, this.pendingObservations, {
-                        kind: "resume",
-                        approved_calls: resolved.approved,
-                        denied_calls: resolved.denied,
-                    });
-                }
-                action = nextAction ?? kernelAction(runtime, this.pendingObservations, providerEvent);
-                const providerReplay = peekProviderReplay(this.opts.provider, finalText, finalToolCalls);
-                await this.opts.sessionLog.append(sessionId, buildLlmCompletedEvent({
-                    turn: runtime.turn(),
-                    content: finalText,
-                    tokenCount: turnOutputTokens || turnTokens || undefined,
-                    toolCalls: finalToolCalls,
-                    providerReplay,
-                }));
-                // P0-C: emit per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect
-                // GOING INTO this turn; a `skill` call here only takes effect next turn, so emit first, then
-                // advance. Wrapped so a faulty sink can never break the run (pure observation).
-                if (this.opts.onTurnMetrics) {
-                    try {
-                        this.opts.onTurnMetrics({
-                            turn: runtime.turn(),
-                            toolsExposed: tools.length,
-                            toolsCalled: finalToolCalls.length,
-                            activeSkill,
-                            inputTokens: turnInputTokens,
-                            cacheReadTokens: turnCacheReadTokens,
-                            cacheCreationTokens: turnCacheCreationTokens,
+                    const providerEvent = {
+                        kind: "provider_result",
+                        message: messageToKernelMessage(assistantMessage),
+                        ...(turnInputTokens > 0 ? { observed_input_tokens: turnInputTokens } : {}),
+                        ...(turnOutputTokens > 0 ? { observed_output_tokens: turnOutputTokens } : {}),
+                        now_ms: Date.now(),
+                    };
+                    let nextAction = kernelMaybeAction(runtime, this.pendingObservations, providerEvent);
+                    if (!nextAction && this.pendingObservations.some(o => o.kind === "suspended")) {
+                        const resolved = await this.resolveKernelSuspend(runtime, sessionId);
+                        for (const evt of resolved.events)
+                            yield evt;
+                        nextAction = kernelAction(runtime, this.pendingObservations, {
+                            kind: "resume",
+                            approved_calls: resolved.approved,
+                            denied_calls: resolved.denied,
                         });
                     }
-                    catch { /* metrics must never break the run */ }
-                }
-                const skillCall = finalToolCalls.find(c => c.name === "skill");
-                if (skillCall) {
-                    try {
-                        const name = JSON.parse(skillCall.arguments || "{}").name;
-                        if (name)
-                            activeSkill = name;
-                    }
-                    catch { /* malformed skill args — leave activeSkill unchanged */ }
-                }
-            }
-            else if (action.kind === "execute_tool") {
-                const allCalls = action.calls;
-                await this.opts.sessionLog.append(sessionId, { kind: "tool_requested", turn: runtime.turn(), calls: allCalls });
-                const runCtx = {
-                    agentId: this.opts.agentId,
-                    skillDir: this.opts.skillDir,
-                    dreamStore: this.opts.dreamStore,
-                    knowledgeSource: this.opts.knowledgeSource,
-                    onToolSuspend: this.opts.onToolSuspend,
-                    onPermissionRequest: this.opts.onPermissionRequest,
-                    resultSpool: this.opts.resultSpool ?? new LargeResultSpool(),
-                };
-                const toolResults = [];
-                const normalCalls = allCalls.filter(c => c.name !== "update_plan" && c.name !== "submit_workflow_nodes" && c.name !== "start_workflow");
-                const planCalls = allCalls.filter(c => c.name === "update_plan");
-                // M5 v1: `start_workflow` (author a sub-workflow) flattens to the same append path as
-                // `submit_workflow_nodes` — a `WorkflowSpec` is a node batch. (v2 adds top-level bootstrap.)
-                const submitCalls = allCalls.filter(c => c.name === "submit_workflow_nodes" || c.name === "start_workflow");
-                for (const call of planCalls) {
-                    const update = parseUpdatePlanArgs(call.arguments);
-                    kernelApply(runtime, this.pendingObservations, {
-                        kind: "update_task",
-                        update: taskUpdateToKernel(update),
-                    });
-                    const result = { callId: call.id, output: "success", isError: false };
-                    toolResults.push(result);
-                    yield { type: "tool_result", callId: call.id, content: "success", isError: false };
-                }
-                // R3-1: `submit_workflow_nodes` cannot be applied to this runner's kernel — when this runner
-                // is a workflow node, the workflow lives in the *parent* kernel. Surface the requested nodes
-                // as a stream event; the orchestrator collects them onto the node's result and `runWorkflow`
-                // sends `submit_workflow_nodes` to the parent kernel. (When not a workflow node, the event is
-                // simply unconsumed — a no-op.)
-                for (const call of submitCalls) {
-                    // M5 v2.1: a TOP-LEVEL agent authoring a whole sub-workflow via `start_workflow` — record the
-                    // full spec and AUTO-PIVOT once this tool turn resolves (the loop drives it in this kernel and
-                    // injects the outcome). A workflow-NODE's `start_workflow` (and every `submit_workflow_nodes`)
-                    // instead FLATTENS: the batch is surfaced for the parent `runWorkflow` to append.
-                    if (call.name === "start_workflow" && !this.opts.isWorkflowNode) {
-                        const spec = parseStartWorkflowSpec(call.arguments);
-                        if (spec) {
-                            this.pendingAuthoredWorkflows.push(spec);
-                            const out = "workflow authored; executing now";
-                            toolResults.push({ callId: call.id, output: out, isError: false });
-                            yield { type: "tool_result", callId: call.id, content: out, isError: false };
-                            continue;
-                        }
-                    }
-                    // `start_workflow` wraps the batch as `{ spec: { nodes } }`; `submit_workflow_nodes` is `{ nodes }`.
-                    const nodes = call.name === "start_workflow"
-                        ? parseStartWorkflowArgs(call.arguments)
-                        : parseSubmitWorkflowNodesArgs(call.arguments);
-                    yield { type: "workflow_nodes_submitted", nodes };
-                    const result = { callId: call.id, output: "submitted", isError: false };
-                    toolResults.push(result);
-                    yield { type: "tool_result", callId: call.id, content: "submitted", isError: false };
-                }
-                if (normalCalls.length > 0) {
-                    for await (const evt of this.opts.executionPlane.executeAll(normalCalls, runCtx)) {
-                        yield evt;
-                        if (evt.type === "tool_result") {
-                            const tre = evt;
-                            toolResults.push({
-                                callId: tre.callId,
-                                output: tre.content,
-                                isError: tre.isError,
-                                isFatal: tre.isFatal,
-                                errorKind: tre.errorKind,
-                            });
-                        }
-                        else if (evt.type === "tool_argument_repaired") {
-                            const tare = evt;
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "tool_argument_repaired",
+                    action = nextAction ?? kernelAction(runtime, this.pendingObservations, providerEvent);
+                    const providerReplay = peekProviderReplay(this.opts.provider, finalText, finalToolCalls);
+                    await this.opts.sessionLog.append(sessionId, buildLlmCompletedEvent({
+                        turn: runtime.turn(),
+                        content: finalText,
+                        tokenCount: turnOutputTokens || turnTokens || undefined,
+                        toolCalls: finalToolCalls,
+                        providerReplay,
+                    }));
+                    // P0-C: emit per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect
+                    // GOING INTO this turn; a `skill` call here only takes effect next turn, so emit first, then
+                    // advance. Wrapped so a faulty sink can never break the run (pure observation).
+                    if (this.opts.onTurnMetrics) {
+                        try {
+                            this.opts.onTurnMetrics({
                                 turn: runtime.turn(),
-                                tool: tare.name,
-                                original_arguments: tare.originalArguments,
-                                repaired_arguments: tare.repairedArguments,
+                                toolsExposed: tools.length,
+                                toolsCalled: finalToolCalls.length,
+                                activeSkill,
+                                inputTokens: turnInputTokens,
+                                cacheReadTokens: turnCacheReadTokens,
+                                cacheCreationTokens: turnCacheCreationTokens,
+                                ...(turnCacheReadBySlot ? { cacheReadTokensBySlot: turnCacheReadBySlot } : {}),
                             });
                         }
-                        else if (evt.type === "tool_denied") {
-                            const tde = evt;
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "tool_denied",
-                                turn: runtime.turn(),
-                                call_id: tde.callId,
-                                tool_name: tde.toolName,
-                                reason: tde.reason,
-                            });
+                        catch { /* metrics must never break the run */ }
+                    }
+                    const skillCall = finalToolCalls.find(c => c.name === "skill");
+                    if (skillCall) {
+                        try {
+                            const name = JSON.parse(skillCall.arguments || "{}").name;
+                            if (name)
+                                activeSkill = name;
                         }
-                        else if (evt.type === "permission_request") {
-                            const pre = evt;
-                            const turn = runtime.turn();
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "permission_requested",
-                                turn,
-                                tool: pre.toolName,
-                                arguments: pre.arguments,
-                                reason: pre.reason,
-                            });
+                        catch { /* malformed skill args — leave activeSkill unchanged */ }
+                    }
+                }
+                else if (action.kind === "execute_tool") {
+                    const allCalls = action.calls;
+                    await this.opts.sessionLog.append(sessionId, { kind: "tool_requested", turn: runtime.turn(), calls: allCalls });
+                    const runCtx = {
+                        agentId: this.opts.agentId,
+                        skillDir: this.opts.skillDir,
+                        dreamStore: this.opts.dreamStore,
+                        knowledgeSource: this.opts.knowledgeSource,
+                        onToolSuspend: this.opts.onToolSuspend,
+                        onPermissionRequest: this.opts.onPermissionRequest,
+                        resultSpool: this.opts.resultSpool ?? new LargeResultSpool(),
+                    };
+                    const toolResults = [];
+                    const normalCalls = allCalls.filter(c => c.name !== "update_plan" && c.name !== "submit_workflow_nodes" && c.name !== "start_workflow");
+                    const planCalls = allCalls.filter(c => c.name === "update_plan");
+                    // M5 v1: `start_workflow` (author a sub-workflow) flattens to the same append path as
+                    // `submit_workflow_nodes` — a `WorkflowSpec` is a node batch. (v2 adds top-level bootstrap.)
+                    const submitCalls = allCalls.filter(c => c.name === "submit_workflow_nodes" || c.name === "start_workflow");
+                    for (const call of planCalls) {
+                        const update = parseUpdatePlanArgs(call.arguments);
+                        kernelApply(runtime, this.pendingObservations, {
+                            kind: "update_task",
+                            update: taskUpdateToKernel(update),
+                        });
+                        const result = { callId: call.id, output: "success", isError: false };
+                        toolResults.push(result);
+                        yield { type: "tool_result", callId: call.id, content: "success", isError: false };
+                    }
+                    // R3-1: `submit_workflow_nodes` cannot be applied to this runner's kernel — when this runner
+                    // is a workflow node, the workflow lives in the *parent* kernel. Surface the requested nodes
+                    // as a stream event; the orchestrator collects them onto the node's result and `runWorkflow`
+                    // sends `submit_workflow_nodes` to the parent kernel. (When not a workflow node, the event is
+                    // simply unconsumed — a no-op.)
+                    for (const call of submitCalls) {
+                        // M5 v2.1: a TOP-LEVEL agent authoring a whole sub-workflow via `start_workflow` — record the
+                        // full spec and AUTO-PIVOT once this tool turn resolves (the loop drives it in this kernel and
+                        // injects the outcome). A workflow-NODE's `start_workflow` (and every `submit_workflow_nodes`)
+                        // instead FLATTENS: the batch is surfaced for the parent `runWorkflow` to append.
+                        if (call.name === "start_workflow" && !this.opts.isWorkflowNode) {
+                            const spec = parseStartWorkflowSpec(call.arguments);
+                            if (spec) {
+                                this.pendingAuthoredWorkflows.push(spec);
+                                const out = "workflow authored; executing now";
+                                toolResults.push({ callId: call.id, output: out, isError: false });
+                                yield { type: "tool_result", callId: call.id, content: out, isError: false };
+                                continue;
+                            }
                         }
-                        else if (evt.type === "permission_resolved") {
-                            const resolved = evt;
-                            const turn = runtime.turn();
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "permission_resolved",
-                                turn,
-                                approved: resolved.approved,
-                                responder: resolved.responder,
-                            });
+                        // `start_workflow` wraps the batch as `{ spec: { nodes } }`; `submit_workflow_nodes` is `{ nodes }`.
+                        const nodes = call.name === "start_workflow"
+                            ? parseStartWorkflowArgs(call.arguments)
+                            : parseSubmitWorkflowNodesArgs(call.arguments);
+                        yield { type: "workflow_nodes_submitted", nodes };
+                        const result = { callId: call.id, output: "submitted", isError: false };
+                        toolResults.push(result);
+                        yield { type: "tool_result", callId: call.id, content: "submitted", isError: false };
+                    }
+                    if (normalCalls.length > 0) {
+                        for await (const evt of this.opts.executionPlane.executeAll(normalCalls, runCtx)) {
+                            yield evt;
+                            if (evt.type === "tool_result") {
+                                const tre = evt;
+                                toolResults.push({
+                                    callId: tre.callId,
+                                    output: tre.content,
+                                    isError: tre.isError,
+                                    isFatal: tre.isFatal,
+                                    errorKind: tre.errorKind,
+                                });
+                            }
+                            else if (evt.type === "tool_argument_repaired") {
+                                const tare = evt;
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "tool_argument_repaired",
+                                    turn: runtime.turn(),
+                                    tool: tare.name,
+                                    original_arguments: tare.originalArguments,
+                                    repaired_arguments: tare.repairedArguments,
+                                });
+                            }
+                            else if (evt.type === "tool_denied") {
+                                const tde = evt;
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "tool_denied",
+                                    turn: runtime.turn(),
+                                    call_id: tde.callId,
+                                    tool_name: tde.toolName,
+                                    reason: tde.reason,
+                                });
+                            }
+                            else if (evt.type === "permission_request") {
+                                const pre = evt;
+                                const turn = runtime.turn();
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "permission_requested",
+                                    turn,
+                                    tool: pre.toolName,
+                                    arguments: pre.arguments,
+                                    reason: pre.reason,
+                                });
+                            }
+                            else if (evt.type === "permission_resolved") {
+                                const resolved = evt;
+                                const turn = runtime.turn();
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "permission_resolved",
+                                    turn,
+                                    approved: resolved.approved,
+                                    responder: resolved.responder,
+                                });
+                            }
                         }
+                        const names = normalCalls.map(c => c.name).join(", ");
+                        kernelApply(runtime, this.pendingObservations, {
+                            kind: "update_task",
+                            update: taskUpdateToKernel({ progress: `Executed tools: ${names}` }),
+                        });
                     }
-                    const names = normalCalls.map(c => c.name).join(", ");
-                    kernelApply(runtime, this.pendingObservations, {
-                        kind: "update_task",
-                        update: taskUpdateToKernel({ progress: `Executed tools: ${names}` }),
+                    await this.opts.sessionLog.append(sessionId, {
+                        kind: "tool_completed",
+                        turn: runtime.turn(),
+                        results: toolResults.map(r => ({
+                            call_id: r.callId,
+                            output: r.output,
+                            is_error: r.isError,
+                            token_count: r.tokenCount,
+                        })),
                     });
-                }
-                await this.opts.sessionLog.append(sessionId, {
-                    kind: "tool_completed",
-                    turn: runtime.turn(),
-                    results: toolResults.map(r => ({
-                        call_id: r.callId,
-                        output: r.output,
-                        is_error: r.isError,
-                        token_count: r.tokenCount,
-                    })),
-                });
-                for (const call of normalCalls) {
-                    const result = toolResults.find(r => r.callId === call.id);
-                    if (result) {
-                        this.pendingSpoolOutputs.set(call.id, { tool: call.name, output: result.output });
+                    for (const call of normalCalls) {
+                        const result = toolResults.find(r => r.callId === call.id);
+                        if (result) {
+                            this.pendingSpoolOutputs.set(call.id, { tool: call.name, output: result.output });
+                        }
                     }
-                }
-                // P1-B B3: a `skill` call that resolved successfully activates that skill in the kernel, so
-                // the next `call_provider` narrows the toolset to its declared tools. Fed before `tool_results`
-                // (which computes the next action). Errs-open: a failed/missing skill load doesn't activate.
-                for (const call of allCalls) {
-                    if (call.name !== "skill")
-                        continue;
-                    const res = toolResults.find(r => r.callId === call.id);
-                    if (!res || res.isError)
-                        continue;
-                    try {
-                        const name = JSON.parse(call.arguments || "{}").name;
-                        if (name)
-                            kernelApply(runtime, this.pendingObservations, { kind: "skill_activated", name });
+                    // P1-B B3: a `skill` call that resolved successfully activates that skill in the kernel, so
+                    // the next `call_provider` narrows the toolset to its declared tools. Fed before `tool_results`
+                    // (which computes the next action). Errs-open: a failed/missing skill load doesn't activate.
+                    for (const call of allCalls) {
+                        if (call.name !== "skill")
+                            continue;
+                        const res = toolResults.find(r => r.callId === call.id);
+                        if (!res || res.isError)
+                            continue;
+                        try {
+                            const name = JSON.parse(call.arguments || "{}").name;
+                            if (name)
+                                kernelApply(runtime, this.pendingObservations, { kind: "skill_activated", name });
+                        }
+                        catch { /* malformed skill args — skip activation */ }
                     }
-                    catch { /* malformed skill args — skip activation */ }
-                }
-                action = kernelAction(runtime, this.pendingObservations, {
-                    kind: "tool_results",
-                    results: toolResults.map(toolResultToKernel),
-                });
-            }
-            else if (action.kind === "evaluate_milestone") {
-                const milestonePolicy = this.opts.milestonePolicy ?? "require_verifier";
-                if (milestonePolicy === "auto_pass") {
                     action = kernelAction(runtime, this.pendingObservations, {
-                        kind: "milestone_result",
-                        result: milestoneCheckResultToKernel(milestoneCheckPass(action.phaseId)),
+                        kind: "tool_results",
+                        results: toolResults.map(toolResultToKernel),
                     });
-                    this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
                 }
-                else if (this.opts.onMilestoneEvaluate) {
-                    const check = await this.opts.onMilestoneEvaluate({
-                        phaseId: action.phaseId,
-                        criteria: action.criteria,
-                        requiredEvidence: action.requiredEvidence,
-                    });
-                    action = kernelAction(runtime, this.pendingObservations, {
-                        kind: "milestone_result",
-                        result: milestoneCheckResultToKernel(check),
-                    });
-                    this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                else if (action.kind === "evaluate_milestone") {
+                    const milestonePolicy = this.opts.milestonePolicy ?? "require_verifier";
+                    if (milestonePolicy === "auto_pass") {
+                        action = kernelAction(runtime, this.pendingObservations, {
+                            kind: "milestone_result",
+                            result: milestoneCheckResultToKernel(milestoneCheckPass(action.phaseId)),
+                        });
+                        this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                    }
+                    else if (this.opts.onMilestoneEvaluate) {
+                        const check = await this.opts.onMilestoneEvaluate({
+                            phaseId: action.phaseId,
+                            criteria: action.criteria,
+                            requiredEvidence: action.requiredEvidence,
+                        });
+                        action = kernelAction(runtime, this.pendingObservations, {
+                            kind: "milestone_result",
+                            result: milestoneCheckResultToKernel(check),
+                        });
+                        this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                    }
+                    else {
+                        this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                        const turnsUsed = Math.max(1, runtime.turn());
+                        await this.opts.sessionLog.append(sessionId, buildRunTerminalEvent({
+                            reason: "milestone_pending",
+                            turnsUsed,
+                            totalTokens: 0,
+                        }));
+                        yield { type: "done", iterations: turnsUsed, totalTokens: 0, status: "milestone_pending" };
+                        this.activeKernel = null;
+                        this.currentSessionId = null;
+                        return;
+                    }
                 }
-                else {
-                    this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
-                    const turnsUsed = Math.max(1, runtime.turn());
-                    await this.opts.sessionLog.append(sessionId, buildRunTerminalEvent({
-                        reason: "milestone_pending",
-                        turnsUsed,
-                        totalTokens: 0,
-                    }));
-                    yield { type: "done", iterations: turnsUsed, totalTokens: 0, status: "milestone_pending" };
-                    this.activeKernel = null;
-                    this.currentSessionId = null;
-                    return;
+                else if (action.kind === "done") {
+                    break;
                 }
             }
-            else if (action.kind === "done") {
-                break;
+        }
+        catch (err) {
+            // I0b: kernel rejection (or any other thrown error inside the loop) reaches us here.
+            // Classify by NAPI status code or message pattern — `invalid_arg` for surface-shape rejects,
+            // `error` for everything else — then emit run_terminal so observability sees a clean end.
+            // The yield-error path mirrors what the in-flight provider-stream catch does.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const code = err.code;
+            const isInvalidArg = code === "InvalidArg" ||
+                errMsg.toLowerCase().includes("invalidarg") ||
+                errMsg.toLowerCase().includes("invalid argument");
+            const reason = isInvalidArg ? "invalid_arg" : "error";
+            yield { type: "error", message: errMsg };
+            try {
+                await this.opts.sessionLog.append(sessionId, buildRunTerminalEvent({
+                    reason,
+                    turnsUsed: runtime.turn() || 0,
+                    totalTokens: 0,
+                }));
             }
+            catch { /* session log failure must not mask the original error */ }
+            yield { type: "done", iterations: runtime.turn() || 0, totalTokens: 0, status: reason };
+            this.activeKernel = null;
+            this.currentSessionId = null;
+            this.dashboard = null;
+            return;
         }
         const result = action.kind === "done" ? action.result : undefined;
-        const status = result?.termination ?? "error";
+        // I0a: when the loop exits without a clean kernel-done — typically because a hard interrupt
+        // aborted the in-flight LLM stream and the catch path sent `timeout` (which the kernel handles
+        // by injecting a rollback note and continuing, not by terminating) — preserve the preempt
+        // intent in the run_terminal reason. Without this, every interrupt-curtailed run reports
+        // `reason: "error"` and the bench / observability layer can't distinguish preemption from a
+        // genuine crash. Mirrors WASM/Python/Rust.
+        const status = result?.termination ?? (this.interrupted ? "user_abort" : "error");
         const turnsUsed = result ? Math.max(1, result.turnsUsed) : runtime.turn() || 0;
         const totalTokens = result?.totalTokensUsed ?? 0;
         nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);

package/dist/types.d.ts

@@ -84,6 +84,15 @@ export interface UsageEvent extends StreamEvent {
     cacheReadInputTokens?: number;
     /** Prompt tokens written to cache this request (billed ~1.25x). Subset of inputTokens. */
     cacheCreationInputTokens?: number;
+    /** I1: per-slot pro-rata attribution of `cacheReadInputTokens`. Estimated, not authoritative —
+     *  Anthropic returns a single cache-read total, so the SDK divides it evenly across the slots
+     *  that carried a `cache_control` breakpoint on the request. Missing when the provider doesn't
+     *  honor `cache_control` (OpenAI-family auto-cache) or when no breakpoints were placed. */
+    cacheReadInputTokensBySlot?: {
+        system?: number;
+        tools?: number;
+        messages?: number;
+    };
 }
 export type ToolChunk = string | {
     type: "text";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.22",
+    "@deepstrike/core": "0.2.23",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },