@mono-agent/agent-runtime 0.3.0 → 0.4.1

package/src/agent/transcript.js

@@ -84,6 +84,17 @@ function summarizeTurn(turn, { maxChars = DEFAULT_TURN_SUMMARY_CHARS } = {}) {
 // is nothing usable to resume from. Older turns beyond `verbatimTurns` are
 // summarized into a one-paragraph snippet; only the trailing `verbatimTurns`
 // keep their full assistant text + tool detail.
+/**
+ * @param {Array<*>} events
+ * @param {Object} [options]
+ * @param {number} [options.maxTurns]
+ * @param {number} [options.verbatimTurns]
+ * @param {number} [options.maxChars]
+ * @param {number} [options.toolResultChars]
+ * @param {number} [options.assistantTextChars]
+ * @param {number} [options.turnSummaryChars]
+ * @param {import('../runtime-brand.js').RuntimeBrand} [options.runtimeBrand]
+ */
 export function buildTranscriptTailSnapshot(events, {
   maxTurns = DEFAULT_MAX_TURNS,
   verbatimTurns = DEFAULT_VERBATIM_TURNS,
@@ -91,6 +102,10 @@ export function buildTranscriptTailSnapshot(events, {
   toolResultChars = DEFAULT_TOOL_RESULT_CHARS,
   assistantTextChars = DEFAULT_ASSISTANT_TEXT_CHARS,
   turnSummaryChars = DEFAULT_TURN_SUMMARY_CHARS,
+  // The resolved RuntimeBrand for the schema id. The router (the only caller)
+  // threads the instance brand; absent (deep/default callers) it falls back to
+  // the module-default context brand.
+  runtimeBrand,
 } = {}) {
   if (!Array.isArray(events) || events.length === 0) return null;
   const turns = [];
@@ -154,7 +169,7 @@ export function buildTranscriptTailSnapshot(events, {
     turn_index: turns.length - tailWindow.length + idx + 1,
     summary: summarizeTurn(turn, { maxChars: turnSummaryChars }),
   }));
-  const brand = readRuntimeBrand();
+  const brand = runtimeBrand ?? readRuntimeBrand();
   const snapshot = {
     schema: `${brand.schemaPrefix}.transcript-tail.v1`,
     captured_at: Date.now(),

package/src/ai/cost.js

@@ -1,5 +1,52 @@
-import { getModel as getPiModel } from "@earendil-works/pi-ai";
+// @ts-check
 
+// pi 0.80 moved the static catalog reads off the pi-ai root (`getModel` is now
+// deprecated/compat-only). `getBuiltinModel(provider, id)` from `providers/all`
+// is the non-deprecated replacement with the same signature and the same
+// undefined-on-miss behavior the pricing lookup below relies on.
+import { getBuiltinModel as getPiModel } from "@earendil-works/pi-ai/providers/all";
+
+/**
+ * @typedef {Object} ParsedModelReference
+ * @property {string|null} sdk
+ * @property {string} [provider]
+ * @property {string} model
+ */
+
+/**
+ * @typedef {Object} NormalizedPricing
+ * @property {number|null} input
+ * @property {number|null} cacheRead
+ * @property {number|null} cacheWrite
+ * @property {number|null} output
+ * @property {string} source
+ * @property {boolean} priced
+ */
+
+/**
+ * @typedef {Object} PricingInputRow
+ * Duck-typed pricing row a host (or the pi catalog) supplies: either
+ * camelCase or the provider's `*_per_million` snake_case spelling.
+ * @property {number|string} [input]
+ * @property {number|string} [input_per_million]
+ * @property {number|string} [cacheRead]
+ * @property {number|string} [cachedInput]
+ * @property {number|string} [cached_input_per_million]
+ * @property {number|string} [cacheWrite]
+ * @property {number|string} [cache_write_per_million]
+ * @property {number|string} [cache_creation_per_million]
+ * @property {number|string} [output]
+ * @property {number|string} [output_per_million]
+ */
+
+// STATIC FALLBACK, consulted only AFTER pi's live catalog (piCatalogPricing via
+// getBuiltinModel("anthropic", ...)). pi's anthropic catalog already carries the
+// same per-million rates for the currently-shipping models, so this table only
+// wins for Claude ids pi's catalog does not (yet) know — newer/renamed models
+// added here before they land in a pinned pi-ai release. STALENESS: these are
+// hand-maintained USD/1M-token rates and can drift from Anthropic's published
+// pricing; treat them as a best-effort backstop for cost DIAGNOSTICS only (never
+// control flow), and refresh when bumping pi-ai or when Anthropic reprices.
 const CLAUDE_PRICING = {
   "claude-haiku-4-5-20251001": { input: 1.0, cacheRead: 0.1, cacheWrite: 1.25, output: 5.0 },
   "claude-haiku-4-5": { input: 1.0, cacheRead: 0.1, cacheWrite: 1.25, output: 5.0 },
@@ -11,17 +58,34 @@ const CLAUDE_PRICING = {
   "claude-opus-4-5": { input: 5.0, cacheRead: 0.5, cacheWrite: 6.25, output: 25.0 },
 };
 
+/**
+ * @param {*} value
+ * @returns {number|null}
+ */
 function finiteOrNull(value) {
   if (value == null || value === "") return null;
   const n = Number(value);
   return Number.isFinite(n) && n >= 0 ? n : null;
 }
 
+/**
+ * @param {*} value
+ * @param {number} [fallback]
+ * @returns {number}
+ */
 function rate(value, fallback = 0) {
   const n = finiteOrNull(value);
   return n == null ? fallback : n;
 }
 
+/**
+ * @param {PricingInputRow|null|undefined} pricing
+ * @param {Object} [options]
+ * @param {string} [options.source]
+ * @param {boolean} [options.priced]
+ * @param {number} [options.missing]
+ * @returns {NormalizedPricing|null}
+ */
 function normalizePricing(pricing, { source, priced = true, missing = 0 } = {}) {
   if (!pricing || typeof pricing !== "object") return null;
   const input = rate(pricing.input ?? pricing.input_per_million, missing);
@@ -41,14 +105,25 @@ function normalizePricing(pricing, { source, priced = true, missing = 0 } = {})
   return { input, cacheRead, cacheWrite, output, source, priced };
 }
 
+/**
+ * @param {string} source
+ * @returns {NormalizedPricing}
+ */
 function zeroPricing(source) {
   return { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, source, priced: true };
 }
 
+/**
+ * @returns {NormalizedPricing}
+ */
 function unknownPricing() {
   return { input: null, cacheRead: null, cacheWrite: null, output: null, source: "unknown", priced: false };
 }
 
+/**
+ * @param {string} reference
+ * @returns {ParsedModelReference|null}
+ */
 function parseReference(reference) {
   if (typeof reference !== "string" || !reference.trim()) return null;
   if (reference.startsWith("vercel:")) {
@@ -72,6 +147,10 @@ function parseReference(reference) {
   return { sdk: reference.slice(0, i), model: reference.slice(i + 1) };
 }
 
+/**
+ * @param {string} baseUrl
+ * @returns {boolean}
+ */
 function isPrivateHost(baseUrl) {
   try {
     const host = new URL(baseUrl).hostname.toLowerCase().replace(/^\[|\]$/g, "");
@@ -88,6 +167,10 @@ function isPrivateHost(baseUrl) {
   }
 }
 
+/**
+ * @param {PricingInputRow} [pricing]
+ * @returns {boolean}
+ */
 function pricingHasRates(pricing = {}) {
   return [
     pricing.input_per_million,
@@ -97,16 +180,41 @@ function pricingHasRates(pricing = {}) {
   ].some((value) => finiteOrNull(value) != null);
 }
 
+/**
+ * Live pricing from pi-ai's builtin catalog (getBuiltinModel). Handles two
+ * shapes:
+ *   - sdk "pi": `parsed.provider` is the pi provider id (openai, openai-codex,
+ *     github-copilot, custom, ...). Codex/openai references route here via
+ *     parseReference (codex:* -> openai-codex, openai:* -> openai), so they get
+ *     the SAME catalog treatment — priced when pi's catalog has that model
+ *     (openai gpt-* do), unpriced (-> falls through to unknown) when it does not
+ *     (e.g. openai-codex `gpt-5-codex` is not in the pinned catalog).
+ *   - sdk "claude": looked up under pi's "anthropic" provider (its models carry
+ *     `cost`), so pi's live rates win over the static CLAUDE_PRICING fallback.
+ * @param {ParsedModelReference|null|undefined} parsed
+ * @returns {NormalizedPricing|null}
+ */
 function piCatalogPricing(parsed) {
-  if (parsed?.sdk !== "pi" || !parsed.provider || !parsed.model) return null;
+  if (!parsed?.model) return null;
+  let provider;
+  if (parsed.sdk === "pi" && parsed.provider) provider = parsed.provider;
+  else if (parsed.sdk === "claude") provider = "anthropic";
+  else return null;
   try {
-    const model = getPiModel(parsed.provider, parsed.model);
+    // `provider` may be a caller-supplied id (custom providers included), wider
+    // than pi-ai's built-in KnownProvider catalog union; the catalog lookup
+    // itself is the runtime check, guarded by the catch below.
+    const model = getPiModel(/** @type {*} */ (provider), parsed.model);
     return model?.cost ? normalizePricing(model.cost, { source: "pi-catalog" }) : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * @param {ParsedModelReference|null|undefined} parsed
+ * @returns {NormalizedPricing|null}
+ */
 function claudePricing(parsed) {
   if (parsed?.sdk !== "claude") return null;
   return normalizePricing(CLAUDE_PRICING[parsed.model], { source: "claude-table" });
@@ -118,6 +226,12 @@ function claudePricing(parsed) {
 // The pricing helpers below (`normalizePricing`, `zeroPricing`, `unknownPricing`,
 // `pricingHasRates`, `isPrivateHost`, `parseReference`) are exported so hosts
 // can build their own resolvers without re-implementing the row-shape conversion.
+/**
+ * @param {Object} [options]
+ * @param {(parsed: ParsedModelReference) => (NormalizedPricing|null)} [options.resolveCustomPricing]
+ * @param {string} [options.model]
+ * @returns {NormalizedPricing}
+ */
 export function resolvePricing({ resolveCustomPricing, model } = {}) {
   const parsed = parseReference(model);
   if (!parsed) return unknownPricing();
@@ -132,6 +246,17 @@ export function resolvePricing({ resolveCustomPricing, model } = {}) {
 
 export { normalizePricing, zeroPricing, unknownPricing, pricingHasRates, isPrivateHost, parseReference };
 
+/**
+ * @param {Object} [options]
+ * @param {(parsed: ParsedModelReference) => (NormalizedPricing|null)} [options.resolveCustomPricing]
+ * @param {string} [options.model]
+ * @param {number} [options.inputTokens]
+ * @param {number} [options.outputTokens]
+ * @param {number} [options.cachedTokens]
+ * @param {number} [options.cacheWriteTokens]
+ * @param {number} [options.cacheCreationTokens]
+ * @returns {number|null}
+ */
 export function estimateCost({
   resolveCustomPricing,
   model,

package/src/ai/failure.js

@@ -1,3 +1,42 @@
+// @ts-check
+
+/**
+ * @typedef {Object} RetryableProviderFailureInfo
+ * @property {boolean} retryable
+ * @property {string|null} subkind
+ * @property {string|null} requestId
+ */
+
+/**
+ * @typedef {"spawn" | "timeout" | "stall" | "usage_limit" | "invalid_result"
+ *   | "invalid_delegation" | "tool_failure" | "provider_unavailable"
+ *   | "provider_unavailable_exhausted" | "provider_auth"
+ *   | "skipped_capability_mismatch" | "cancelled" | "cancelled_user"
+ *   | "cancelled_shutdown" | "cancelled_signal" | "abandoned"
+ *   | "session_not_found" | "session_busy" | (string & {})} FailureKind
+ * OPEN string union. The literals above are the CORE taxonomy the kernel itself
+ * derives from provider/runtime signals in `classifyFailure` /
+ * `retryableProviderFailureInfo` (and `provider_unavailable_exhausted`, produced
+ * by the router on chain exhaustion). The union is intentionally open
+ * (`string & {}`) because `FAILURE_KINDS` also transports HOST-TAXONOMY kinds
+ * the kernel never originates on its own:
+ *   - `child_failed`, `budget_exceeded` — `classifyFailure` only returns these
+ *     when the HOST passes the matching `childFailed` / `budgetExceeded` (or a
+ *     `cancelInitiator: "budget"`) input; the kernel never infers them from a
+ *     provider signal.
+ *   - `delegation_agent_not_in_team`, `delegation_team_roster_empty`,
+ *     `invalid_delegation`, `cancelled_stale` (`stale_reconcile`) — set by a
+ *     host coordinator (planner/roster/reconcile logic) and merely carried
+ *     through `FAILURE_KINDS` / the `hint` passthrough; the kernel transports
+ *     them in the result contract but never emits them from its own paths.
+ * Hosts (e.g. worklab's coordinator) validate against `FAILURE_KINDS` and may
+ * define additional kinds — accepting them at the type level is deliberate.
+ */
+
+// FAILURE_KINDS is the runtime vocabulary: `classifyFailure`'s `hint`
+// passthrough accepts any member, and hosts validate `task_runs.failure_kind`
+// against it. See the `FailureKind` typedef above for which members the kernel
+// derives itself vs. which are host-taxonomy kinds it only transports.
 export const FAILURE_KINDS = [
   "spawn",
   "timeout",
@@ -8,6 +47,8 @@ export const FAILURE_KINDS = [
   "tool_failure",
   "provider_unavailable",
   "provider_unavailable_exhausted",
+  "provider_auth",
+  "skipped_capability_mismatch",
   "child_failed",
   "budget_exceeded",
   "cancelled",
@@ -29,12 +70,32 @@ export const FAILURE_KINDS = [
 ];
 
 const USAGE_LIMIT_RE = /(rate limit|usage limit|max tokens|max turns|context length|too many tokens)/i;
-const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|service unavailable|503|502|gateway|fetch failed|network|websocket)/i;
+const PROVIDER_AUTH_RE = /(no api key|missing api key|api key required|invalid api key|incorrect api key|authentication|authorization|not authorized|forbidden|oauth (?:refresh|auth|authentication|token).*failed|credential store (?:read|modify) failed|401|403)/i;
+// Mirrors the conservative connection-error/refused/failed alternation added to
+// RETRYABLE_PROVIDER_RE / retryableProviderSubkind below for pi 0.80's terse
+// "Connection error." — without it, classifyFailure (used directly by hosts
+// like worklab's coordinator, independent of retryableProviderFailureInfo) maps
+// that same terse text to the generic "spawn" kind instead of
+// "provider_unavailable".
+const PROVIDER_UNAVAILABLE_RE = /(econn|enotfound|etimedout|timed? ?out|service unavailable|503|502|gateway|fetch failed|network|websocket|\bconnection (?:error|refused|failed)\b|\bcould not connect\b)/i;
 const TOOL_FAILURE_RE = /(tool .* failed|mcp tool|permission denied|EACCES|read-only file system)/i;
-const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|invalid api key|incorrect api key|authentication|authorization|not authorized|forbidden|billing|insufficient[_ ]quota|quota exceeded|model[_ ]not[_ ]found|unsupported model|permission denied|bad request|401|403|404)/i;
-const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error)/i;
+const NON_RETRYABLE_PROVIDER_RE = /(invalid[_ ]request|unknown parameter|no api key|missing api key|api key required|invalid api key|incorrect api key|authentication|authorization|not authorized|forbidden|billing|insufficient[_ ]quota|quota exceeded|model[_ ]not[_ ]found|unsupported model|permission denied|bad request|401|403|404)/i;
+// pi 0.80's openai-client-style bridge collapses a connection-refused/unreachable
+// provider down to a terse "Connection error." with no cause text (no ECONNREFUSED,
+// no fetch failed) — the `\bconnection (?:error|refused|failed)\b|\bcould not connect\b`
+// alternation below is the motivating fix so that case still fails over instead of
+// being classified as non-retryable.
+const RETRYABLE_PROVIDER_RE = /(currently overloaded|server(?:s)? (?:is |are )?overloaded|try again later|retry your request|request id|service unavailable|temporar(?:y|ily)|timed? ?out|stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|etimedout|network|429|too many requests|500|502|503|504|gateway|internal server error|\bconnection (?:error|refused|failed)\b|\bcould not connect\b)/i;
 export const PROVIDER_ABORT_RE = /\b(?:terminated|aborted before final output|aborted before final|stream aborted|stream was aborted|stream disconnected|websocket (?:error|disconnected|closed)|socket hang up|und_err_socket|econnreset|premature close)\b/i;
 
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isProviderAuthFailureText(text = "") {
+  return PROVIDER_AUTH_RE.test(text || "");
+}
+
 function requestIdFromText(text) {
   const match = /\b(?:request[_ -]?id|req[_ -]?id)\s*[:#]?\s*([A-Za-z0-9._:-]{8,})/i.exec(text || "");
   return match?.[1]?.replace(/[.,;:]+$/, "") || null;
@@ -44,12 +105,21 @@ function retryableProviderSubkind(text) {
   if (/overloaded/i.test(text)) return "overloaded";
   if (/429|too many requests|rate limit/i.test(text)) return "rate_limited";
   if (/timed? ?out|etimedout/i.test(text)) return "timeout";
-  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network/i.test(text)) return "network";
+  // pi 0.80's terse "Connection error." (no ECONNREFUSED/fetch-failed detail) still
+  // needs to land in the "network" subkind so a down provider fails over.
+  if (/stream disconnected|fetch failed|econnreset|econnrefused|eai_again|enotfound|network|\bconnection (?:error|refused|failed)\b|\bcould not connect\b/i.test(text)) return "network";
   if (/500|502|503|504|service unavailable|gateway|internal server error/i.test(text)) return "server_error";
   if (/retry your request|try again later|request id|processing your request/i.test(text)) return "retryable_request";
   return null;
 }
 
+/**
+ * @param {Object} [options]
+ * @param {string} [options.errorText]
+ * @param {string} [options.stderrTail]
+ * @param {string|null} [options.failureKind]
+ * @returns {RetryableProviderFailureInfo}
+ */
 export function retryableProviderFailureInfo({
   errorText = "",
   stderrTail = "",
@@ -80,6 +150,22 @@ export function retryableProviderFailureInfo({
 // errors) into one of FAILURE_KINDS. Every adapter / spawn-worker / watcher
 // path should funnel through this so the values in `task_runs.failure_kind`
 // stay coherent.
+/**
+ * @param {Object} [options]
+ * @param {number|null} [options.exitCode]
+ * @param {string|null} [options.signal]
+ * @param {string} [options.errorText]
+ * @param {string} [options.stderrTail]
+ * @param {boolean} [options.timedOut]
+ * @param {boolean} [options.cancelRequested]
+ * @param {string|null} [options.cancelInitiator]
+ * @param {boolean} [options.resultParseError]
+ * @param {boolean} [options.mcpInitFailed]
+ * @param {boolean} [options.budgetExceeded]
+ * @param {boolean} [options.childFailed]
+ * @param {string|null} [options.hint]
+ * @returns {FailureKind|null} One of FAILURE_KINDS, or null for a clean exit.
+ */
 export function classifyFailure({
   exitCode = null,
   signal = null,
@@ -122,6 +208,7 @@ export function classifyFailure({
   const haystack = `${errorText || ""}\n${stderrTail || ""}`;
   if (USAGE_LIMIT_RE.test(haystack)) return "usage_limit";
   if (TOOL_FAILURE_RE.test(haystack)) return "tool_failure";
+  if (PROVIDER_AUTH_RE.test(haystack)) return "provider_auth";
   if (PROVIDER_UNAVAILABLE_RE.test(haystack)) return "provider_unavailable";
   if (mcpInitFailed && haystack.toLowerCase().includes("mcp")) return "tool_failure";
 
@@ -133,6 +220,11 @@ export function classifyFailure({
 // of stderr; we only want the last few KB for diagnostics. Returns a string
 // guaranteed to be ≤ `limit` bytes, with a `[truncated …]` marker if anything
 // was dropped.
+/**
+ * @param {Object} [options]
+ * @param {number} [options.limit]
+ * @returns {{push: (chunk: (string|Buffer|null|undefined)) => void, toString: () => string, readonly bytesDropped: number}}
+ */
 export function createStderrTail({ limit = 8 * 1024 } = {}) {
   let buffer = "";
   let dropped = 0;

package/src/ai/index.js

@@ -9,6 +9,7 @@ export {
   disposeProviderSession,
 } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
+export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
 export {
   buildCapabilitiesUsed,
   toolCompactionAppliedFromWarnings,

package/src/ai/live-input-prompt.js

@@ -3,7 +3,17 @@
 // consumers; the queue/normalize/supports helpers stay in core/live-input.js
 // for the API + coordinator + worker callers that don't need this string.
 
-export function formatLiveInputGuidance(text) {
+// A host or run `prompts.liveInputGuidance(body)` override, when supplied,
+// replaces the default guidance wrapper below; otherwise the default is used.
+/**
+ * @param {string} text
+ * @param {import('./types.js').RuntimePromptOverrides} [prompts]
+ * @returns {string}
+ */
+export function formatLiveInputGuidance(text, prompts) {
+  if (typeof prompts?.liveInputGuidance === "function") {
+    return prompts.liveInputGuidance(String(text || ""));
+  }
   return [
     "Live guidance from the user:",
     String(text || ""),

package/src/ai/providers/claude-cli.js

@@ -443,14 +443,18 @@ export async function generateCliResponse(systemPrompt, options = {}) {
   const start = Date.now();
   const resolved = options.model;
   const prompt = promptFromMessages(options.messages);
-  const dir = mkdtempSync(join(tmpdir(), readRuntimeBrand().tempdirPrefix));
+  const dir = mkdtempSync(join(tmpdir(), (options.toolContext?.runtimeBrand ?? readRuntimeBrand()).tempdirPrefix));
   const schemaPath = options.outputSchema ? join(dir, "output-schema.json") : null;
   if (schemaPath) writeFileSync(schemaPath, JSON.stringify(options.outputSchema));
   const mcpServers = options.mcpServers || {};
   const mcpConfigPath = hasEntries(mcpServers) && resolved.sdk === "claude-code"
     ? join(dir, "mcp.json")
     : null;
-  if (mcpConfigPath) writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers }, null, 2));
+  // Owner-only mode: this temp config carries full mcpServers env (including a
+  // resolved embedding apiKey) and lives under shared /tmp. The 0700 parent dir
+  // (mkdtempSync) already blocks cross-user traversal; 0o600 is defense-in-depth
+  // matching the idiom in packages/agent-contracts/src/json-source.ts and pi-auth.js.
+  if (mcpConfigPath) writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers }, null, 2), { mode: 0o600 });
   const reusableSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
     || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
     || null;

package/src/ai/providers/claude-sdk.js

@@ -15,6 +15,7 @@ import { runtimeCapabilities } from "../runtime/capabilities.js";
 import { buildCapabilitiesUsed, toolCompactionAppliedFromWarnings } from "../runtime/capabilities-used.js";
 import { MAX_TOOL_RESULT_BYTES, summarisePayload } from "../../agent/tool-bloat.js";
 import { normalizeMcpToolParams } from "../../agent/tools/pi-bridge.js";
+import { deprecatedSettingsWarning } from "../../agent/compaction.js";
 import { readRuntimeBrand } from "../../agent/tools/shared/runtime-context.js";
 import { createApprovalManager } from "../../agent/approval.js";
 import {
@@ -266,12 +267,28 @@ function claudeToolResponseBlocks(toolResponse) {
   }
 }
 
-function toolPayloadLimit(options) {
+// Resolve the tool_result byte cap. Precedence is PER-GROUP (MIGRATION.md §8):
+//   explicit options.toolPayloadMaxBytes
+//   -> typed options.toolLimits — when this group is PRESENT it wins wholesale:
+//      its toolPayloadMaxBytes is used if valid, otherwise the default; the
+//      DEPRECATED settings fallback below is never consulted for this group,
+//      even if toolLimits.toolPayloadMaxBytes itself is absent/invalid.
+//   -> DEPRECATED options.settings.agent_tool_payload_max_bytes (usedSettings),
+//      only consulted when options.toolLimits is entirely absent.
+//   -> MAX_TOOL_RESULT_BYTES default.
+// `usedSettings` lets the caller emit one deprecation warning per run when the
+// legacy settings fallback was actually consumed.
+export function toolPayloadLimit(options) {
   const explicit = Number(options.toolPayloadMaxBytes);
-  if (Number.isFinite(explicit) && explicit > 0) return Math.floor(explicit);
+  if (Number.isFinite(explicit) && explicit > 0) return { bytes: Math.floor(explicit), usedSettings: false };
+  if (options.toolLimits) {
+    const typed = Number(options.toolLimits.toolPayloadMaxBytes);
+    if (Number.isFinite(typed) && typed > 0) return { bytes: Math.floor(typed), usedSettings: false };
+    return { bytes: MAX_TOOL_RESULT_BYTES, usedSettings: false };
+  }
   const configured = Number(options.settings?.agent_tool_payload_max_bytes);
-  if (Number.isFinite(configured) && configured > 0) return Math.floor(configured);
-  return MAX_TOOL_RESULT_BYTES;
+  if (Number.isFinite(configured) && configured > 0) return { bytes: Math.floor(configured), usedSettings: true };
+  return { bytes: MAX_TOOL_RESULT_BYTES, usedSettings: false };
 }
 
 function claudeEditPath(toolName, toolInput) {
@@ -289,6 +306,10 @@ function fileEditStateKey(input, toolUseID, path) {
   return toolUseID || input?.tool_use_id || input?.toolUseID || `${input?.tool_name || "file_edit"}:${path}`;
 }
 
+/**
+ * @param {any} change
+ * @param {{status?: any, before?: any, after?: any, error?: any}} [options]
+ */
 function fileEditPayload(change, { status, before, after, error } = {}) {
   const lineStats = statsForCompletedChange(change, before, after);
   const completedChange = lineStats ? { ...change, line_stats: lineStats } : change;
@@ -331,6 +352,11 @@ function createClaudeFileEditHooks({ cwd, emitEvent }) {
     state.started = true;
   }
 
+  /**
+   * @param {any} input
+   * @param {any} toolUseID
+   * @param {{status?: any, error?: any}} [options]
+   */
   function complete(input, toolUseID, { status, error } = {}) {
     const directKey = toolUseID || input?.tool_use_id || input?.toolUseID;
     const fallback = createState(input, toolUseID, { readBefore: false });
@@ -483,10 +509,10 @@ function createClaudeCanUseTool(approvalManager, modelName) {
   };
 }
 
-async function* livePromptMessages({ initialPrompt, liveInput, sessionId }) {
+async function* livePromptMessages({ initialPrompt, liveInput, sessionId, prompts }) {
   yield makeSdkUserMessage(initialPrompt, sessionId);
   for await (const message of liveInput) {
-    yield makeSdkUserMessage(formatLiveInputGuidance(message.body), sessionId, message.id || randomUUID());
+    yield makeSdkUserMessage(formatLiveInputGuidance(message.body, prompts), sessionId, message.id || randomUUID());
   }
 }
 
@@ -515,7 +541,7 @@ export async function generateClaudeResponse(systemPrompt, options) {
   const reusableProviderSessionId = pickSessionId(options.sessionId, options.providerSessionId);
   const persistArtifact = options.persistArtifact || null;
   const qaOutputDir = options.qaOutputDir || options.runArtifactDir || null;
-  const toolPayloadMaxBytes = toolPayloadLimit(options);
+  const { bytes: toolPayloadMaxBytes, usedSettings: toolPayloadFromSettings } = toolPayloadLimit(options);
   let providerSessionId = reusableProviderSessionId;
   let lastToolName = null;
   let toolResultsSeen = 0;
@@ -526,6 +552,16 @@ export async function generateClaudeResponse(systemPrompt, options) {
     onEvent(event);
   }
 
+  // Deprecated `settings` fallback for the tool_result byte cap was consumed;
+  // surface the one-per-run deprecation warning (the typed `toolLimits` object
+  // is the supported path). mono-agent never passes `settings`, so this never
+  // fires there.
+  if (toolPayloadFromSettings) {
+    const warning = deprecatedSettingsWarning(["agent_tool_payload_max_bytes"]);
+    runtimeWarnings.push(warning);
+    emitEvent({ type: "runtime_warning", ...warning });
+  }
+
   function noteToolUse(toolName) {
     if (toolName) lastToolName = toolName;
   }
@@ -552,6 +588,9 @@ export async function generateClaudeResponse(systemPrompt, options) {
     ? "default"
     : permissionMode;
   const nativeAgents = claudeNativeAgentDefinitions(options.nativeSubagents);
+  // Assembled incrementally, then handed across the SDK `query` boundary
+  // (outputFormat/resume/maxTurns are attached conditionally below).
+  /** @type {any} */
   const queryOptions = {
     systemPrompt,
     model: modelWithContextWindow(model.model, options.contextWindow),
@@ -588,7 +627,7 @@ export async function generateClaudeResponse(systemPrompt, options) {
   }
 
   const prompt = options.liveInput
-    ? livePromptMessages({ initialPrompt: promptString, liveInput: options.liveInput, sessionId: reusableProviderSessionId || randomUUID() })
+    ? livePromptMessages({ initialPrompt: promptString, liveInput: options.liveInput, sessionId: reusableProviderSessionId || randomUUID(), prompts: options.prompts })
     : promptString;
   const providerRequestStartedAt = Date.now();
   emitEvent({
@@ -598,7 +637,7 @@ export async function generateClaudeResponse(systemPrompt, options) {
     runtime: "sdk",
     timestamp: providerRequestStartedAt,
   });
-  const stream = query({ prompt, options: queryOptions });
+  const stream = query({ prompt: /** @type {any} */ (prompt), options: queryOptions });
 
   let text = "";
   let usage = {};
@@ -672,8 +711,12 @@ export async function generateClaudeResponse(systemPrompt, options) {
         text += delta;
         for (const toolName of assistantToolNames(event)) noteToolUse(toolName);
       }
-      else if (event.type === "error") {
-        const message = event.error?.message || event.error || "sdk stream error";
+      // The SDK's message union does not declare a runtime `error` event, but
+      // the runtime can emit one; keep this defensive branch and cast past the
+      // narrowed union.
+      else if (/** @type {any} */ (event).type === "error") {
+        const errorEvent = /** @type {any} */ (event);
+        const message = errorEvent.error?.message || errorEvent.error || "sdk stream error";
         if (hasPreservableFinalOutput()) {
           preservePostSuccessError(`Claude SDK emitted an error after final output; preserved final result. ${message}`);
         } else {
@@ -711,7 +754,7 @@ export async function generateClaudeResponse(systemPrompt, options) {
             if (failureKind === "invalid_result") {
               runtimeWarnings.push(makeRuntimeWarning(
                 resultError.message,
-                `${readRuntimeBrand().schemaPrefix}_result_validation`,
+                `${(options.toolContext?.runtimeBrand ?? readRuntimeBrand()).schemaPrefix}_result_validation`,
               ));
             }
             errorDetails = buildClaudeErrorDetails({