@deepstrike/sdk 0.2.22 → 0.2.24

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

@@ -56,7 +56,9 @@ export type { CreateProviderOptions, EndpointProfileId } from "./providers/catal
 export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from "./providers/replay-validator.js";
 export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "./runtime/provider-replay.js";
 export { tool, streamingTool, executeTools, readFile, validateToolArguments } from "./tools/index.js";
-export type { RegisteredTool } from "./tools/index.js";
+export type { RegisteredTool, ToolExecContext } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
+export type { ToolEnvelope, ToolEnvelopeOk, ToolEnvelopeFail } from "./tools/errors.js";
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 export type { SkillMetadata } from "./skills/loader.js";
 export { WorkingMemory } from "./memory/working.js";
@@ -71,8 +73,8 @@ 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 { 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 { 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, ToolAuditFailedEvent, 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";
 export type { AcceptanceCriterion, VerificationContract, ContractCheckResult, } from "./collaboration/contract.js";

package/dist/index.js

@@ -39,6 +39,7 @@ export { ProviderReplayValidationError, DEGRADED_REASONING_PLACEHOLDER } from ".
 export { assessProviderReplayability, peekProviderReplay, seedProviderReplayFromEvents, isReplayCompatibleWithProvider, } from "./runtime/provider-replay.js";
 // ── Tools & Skills ─────────────────────────────────────────────────────────
 export { tool, streamingTool, executeTools, readFile, validateToolArguments } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
 export { scanSkillDir, readSkillFile } from "./skills/loader.js";
 // ── Memory ─────────────────────────────────────────────────────────────────
 export { WorkingMemory } from "./memory/working.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/execution-plane.js

@@ -1,4 +1,5 @@
-import { isAsyncIterable, normalizeToolChunk, toolChunkText, validateToolArguments } from "../tools/index.js";
+import { isAsyncIterable, maybeWarnFailureShapedChunk, normalizeToolChunk, toolChunkText, validateToolArguments } from "../tools/index.js";
+import { formatToolError } from "../tools/errors.js";
 import { readSkillFile } from "../skills/loader.js";
 import { LargeResultSpool } from "./large-result-spool.js";
 export class LocalExecutionPlane {
@@ -102,6 +103,20 @@ export class LocalExecutionPlane {
         const registered = this.tools.get(call.name);
         if (!registered)
             return { callId: call.id, output: `unknown tool: ${call.name}`, isError: true };
+        // `audit` failure buffer is hoisted above the try-block so the catch path can flush any
+        // best-effort failures recorded before the main throw.
+        const auditFailures = [];
+        const callCtx = {
+            ...(ctx.cwd !== undefined ? { cwd: ctx.cwd } : {}),
+            audit: async (label, fn) => {
+                try {
+                    await fn();
+                }
+                catch (err) {
+                    auditFailures.push({ label, error: formatToolError(err) });
+                }
+            },
+        };
         try {
             const args = JSON.parse(call.arguments || "{}");
             const originalArgsStr = JSON.stringify(args);
@@ -119,7 +134,8 @@ export class LocalExecutionPlane {
             }
             // M3/G4: pass the run context (incl. `cwd`) so cwd-aware tools scope their work to the
             // sub-agent's worktree. `RunContext` is structurally assignable to the tool's `ToolExecContext`.
-            const output = await registered.execute(args, ctx);
+            // The per-call `audit` helper (above) layers best-effort side-effect handling on top.
+            const output = await registered.execute(args, callCtx);
             if (isAsyncIterable(output)) {
                 let combined = "";
                 const iterator = output[Symbol.asyncIterator]();
@@ -145,16 +161,28 @@ export class LocalExecutionPlane {
                     }
                     const delta = toolChunkText(next.value);
                     combined += delta;
+                    if (delta)
+                        maybeWarnFailureShapedChunk(call.name, delta);
                     yield { type: "tool_delta", callId: call.id, name: call.name, ...(delta ? { delta } : {}), chunk };
                 }
+                for (const f of auditFailures) {
+                    yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+                }
                 return { callId: call.id, output: combined, isError: false };
             }
+            for (const f of auditFailures) {
+                yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+            }
             return { callId: call.id, output, isError: false };
         }
         catch (err) {
+            // Audit failures recorded before the main throw are still informational; surface them.
+            for (const f of auditFailures) {
+                yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+            }
             return {
                 callId: call.id,
-                output: String(err),
+                output: formatToolError(err),
                 isError: true,
                 isFatal: Boolean(err?.isFatal),
                 errorKind: err?.errorKind,
@@ -185,7 +213,7 @@ export async function resolvePermissionRequest(request, ctx) {
         return {
             approved: false,
             responder: "permission_handler",
-            reason: `permission handler failed: ${String(err)}`,
+            reason: `permission handler failed: ${formatToolError(err)}`,
         };
     }
 }

package/dist/runtime/mcp-proxy-plane.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { LocalExecutionPlane } from "./execution-plane.js";
+import { formatToolError } from "../tools/errors.js";
 class McpConnection {
     serverName;
     config;
@@ -97,7 +98,7 @@ class McpConnection {
             return { output: text || JSON.stringify(result), isError: result.isError ?? false };
         }
         catch (err) {
-            return { output: String(err), isError: true };
+            return { output: formatToolError(err), isError: true };
         }
     }
     async stop() {

package/dist/runtime/process-sandbox-plane.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { mkdir } from "node:fs/promises";
 import { tool } from "../tools/index.js";
 import { LocalExecutionPlane } from "./execution-plane.js";
+import { formatToolError } from "../tools/errors.js";
 /**
  * ExecutionPlane that runs subprocesses with a sandbox directory as cwd.
  * Extends LocalExecutionPlane with two built-in tools:
@@ -73,7 +74,7 @@ export class ProcessSandboxPlane extends LocalExecutionPlane {
             child.stdout.on("data", capture);
             child.stderr.on("data", capture);
             child.on("close", code => settle(Buffer.concat(chunks).toString("utf8"), code !== 0));
-            child.on("error", err => settle(String(err), true));
+            child.on("error", err => settle(formatToolError(err), true));
         });
     }
     makeBashTool() {

package/dist/runtime/remote-vpc-plane.js

@@ -1,4 +1,5 @@
 import { LocalExecutionPlane } from "./execution-plane.js";
+import { formatToolError } from "../tools/errors.js";
 /**
  * ExecutionPlane that forwards tool calls over HTTP to a worker inside a customer VPC.
  *
@@ -76,7 +77,7 @@ export class RemoteVpcPlane {
             return { output: result.output, isError: result.isError ?? false };
         }
         catch (err) {
-            return { output: String(err), isError: true };
+            return { output: formatToolError(err), isError: true };
         }
     }
 }

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;