@theokit/sdk 4.53.1 → 4.55.0

package/dist/{chunk-F77UENR6.cjs → chunk-F5WMX4EA.cjs}

@@ -1,36 +1,38 @@
 'use strict';
 
-var chunk2D43RD5D_cjs = require('./chunk-2D43RD5D.cjs');
-var chunk665SFFFR_cjs = require('./chunk-665SFFFR.cjs');
+var chunkV2UUGUY4_cjs = require('./chunk-V2UUGUY4.cjs');
+var chunk5UOVYM3P_cjs = require('./chunk-5UOVYM3P.cjs');
+var chunk53CBTBWO_cjs = require('./chunk-53CBTBWO.cjs');
 var chunkBV2MWEMV_cjs = require('./chunk-BV2MWEMV.cjs');
-var chunkXPR366DL_cjs = require('./chunk-XPR366DL.cjs');
-var chunkOUOXM36O_cjs = require('./chunk-OUOXM36O.cjs');
-var chunk2FYEVT2B_cjs = require('./chunk-2FYEVT2B.cjs');
-var chunkBDTVFIPB_cjs = require('./chunk-BDTVFIPB.cjs');
+var chunkNGESVVJN_cjs = require('./chunk-NGESVVJN.cjs');
+var chunkEI2Q7SJ5_cjs = require('./chunk-EI2Q7SJ5.cjs');
+var chunkYPJ5NH5N_cjs = require('./chunk-YPJ5NH5N.cjs');
+var chunkHLPSLDGL_cjs = require('./chunk-HLPSLDGL.cjs');
 var chunk2ZPEDVLM_cjs = require('./chunk-2ZPEDVLM.cjs');
-var chunkOKLYRPKL_cjs = require('./chunk-OKLYRPKL.cjs');
-var chunkHAWE74GQ_cjs = require('./chunk-HAWE74GQ.cjs');
-var chunkRAHSWE5C_cjs = require('./chunk-RAHSWE5C.cjs');
+var chunkQ47R5E2X_cjs = require('./chunk-Q47R5E2X.cjs');
+var chunkU2AC6JUP_cjs = require('./chunk-U2AC6JUP.cjs');
+var chunkWJVHMTKB_cjs = require('./chunk-WJVHMTKB.cjs');
 var chunk6JSIEDKL_cjs = require('./chunk-6JSIEDKL.cjs');
-var chunkB4YA6BRS_cjs = require('./chunk-B4YA6BRS.cjs');
+var chunk4O5TGQBW_cjs = require('./chunk-4O5TGQBW.cjs');
 var chunkNINIJCHU_cjs = require('./chunk-NINIJCHU.cjs');
+var chunk3YJNUKYN_cjs = require('./chunk-3YJNUKYN.cjs');
 var chunkVJ26EKGJ_cjs = require('./chunk-VJ26EKGJ.cjs');
-var chunkWQ53UQL4_cjs = require('./chunk-WQ53UQL4.cjs');
-var chunkY4AXQOT4_cjs = require('./chunk-Y4AXQOT4.cjs');
-var chunkTTJ54H3E_cjs = require('./chunk-TTJ54H3E.cjs');
-var chunkYLQQX5W2_cjs = require('./chunk-YLQQX5W2.cjs');
-var chunkWJVHMTKB_cjs = require('./chunk-WJVHMTKB.cjs');
-var chunkC4H6PB5J_cjs = require('./chunk-C4H6PB5J.cjs');
-var chunkE7FJOO4G_cjs = require('./chunk-E7FJOO4G.cjs');
-var chunkADLLFY3H_cjs = require('./chunk-ADLLFY3H.cjs');
-var chunkVYHJZVL5_cjs = require('./chunk-VYHJZVL5.cjs');
-var chunkVUKQL3L2_cjs = require('./chunk-VUKQL3L2.cjs');
-var chunkZN2DGEY3_cjs = require('./chunk-ZN2DGEY3.cjs');
-var chunkZT57WTUJ_cjs = require('./chunk-ZT57WTUJ.cjs');
+var chunkR3UPQFKK_cjs = require('./chunk-R3UPQFKK.cjs');
 var chunkVKJ7V7EB_cjs = require('./chunk-VKJ7V7EB.cjs');
-var chunkSZHU7A5B_cjs = require('./chunk-SZHU7A5B.cjs');
-var chunkLPVIRJVF_cjs = require('./chunk-LPVIRJVF.cjs');
-var chunkBM6N4KHO_cjs = require('./chunk-BM6N4KHO.cjs');
+var chunkILCGLTSA_cjs = require('./chunk-ILCGLTSA.cjs');
+var chunkJHPGF3FP_cjs = require('./chunk-JHPGF3FP.cjs');
+var chunk2ADR2GSO_cjs = require('./chunk-2ADR2GSO.cjs');
+var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
+var chunkI6TGFUCO_cjs = require('./chunk-I6TGFUCO.cjs');
+var chunkHJBMA5MB_cjs = require('./chunk-HJBMA5MB.cjs');
+var chunkIWBGCBR6_cjs = require('./chunk-IWBGCBR6.cjs');
+var chunkXSX2UU6Y_cjs = require('./chunk-XSX2UU6Y.cjs');
+var chunk3EE6LVWT_cjs = require('./chunk-3EE6LVWT.cjs');
+var chunk6HTXPPHK_cjs = require('./chunk-6HTXPPHK.cjs');
+var chunkNIRE5CNO_cjs = require('./chunk-NIRE5CNO.cjs');
+var chunkK3FW2XZD_cjs = require('./chunk-K3FW2XZD.cjs');
+var chunkJTB5Q42C_cjs = require('./chunk-JTB5Q42C.cjs');
+var chunkNUKRL3I6_cjs = require('./chunk-NUKRL3I6.cjs');
 var promises = require('fs/promises');
 var crypto = require('crypto');
 var path = require('path');
@@ -226,7 +228,7 @@ async function agentGenerate(agent, agentModel, agentApiKey, agentLocal, input,
   const { output, maxRetries, errorStrategy, ...sendOptions } = options;
   const run = await agent.send(input, sendOptions);
   const result = await run.wait();
-  const { generateObjectImpl, GenerateObjectError } = await import('./generate-object-AVXOJK2I.cjs');
+  const { generateObjectImpl, GenerateObjectError } = await import('./generate-object-PGSP5U7N.cjs');
   const answer = structurableAnswerOrThrow(result, GenerateObjectError);
   const { getAgentFacade } = await import('./agent-factory-registry-UU46BUMU.cjs');
   const facade = getAgentFacade();
@@ -315,7 +317,7 @@ function normalizeModel(m) {
   if (m === void 0 || typeof m !== "string") return m;
   const id = m.trim();
   if (id.length === 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       'model must be a non-empty "provider/model" id string or a ModelSelection object',
       { code: "invalid_model_selection" }
     );
@@ -451,7 +453,7 @@ function registryPath(cwd) {
   return path.join(cwd, REGISTRY_RELATIVE_PATH);
 }
 async function loadRegistry(cwd) {
-  return chunkHAWE74GQ_cjs.readVersionedJson({
+  return chunkU2AC6JUP_cjs.readVersionedJson({
     path: registryPath(cwd),
     currentVersion: SCHEMA_VERSION,
     defaultValue: () => ({}),
@@ -474,8 +476,8 @@ async function saveRegistry(cwd, agents2) {
     serialized[id] = toSerialized(agent);
   }
   const path = registryPath(cwd);
-  await chunkYLQQX5W2_cjs.withCwdMutex(`registry:${cwd}`, async () => {
-    await chunkHAWE74GQ_cjs.writeVersionedJson(path, serialized, SCHEMA_VERSION);
+  await chunkZF2LDKQQ_cjs.withCwdMutex(`registry:${cwd}`, async () => {
+    await chunkU2AC6JUP_cjs.writeVersionedJson(path, serialized, SCHEMA_VERSION);
   });
 }
 function toSerialized(agent) {
@@ -542,7 +544,7 @@ function scheduleSaveForCwd(cwd) {
       }
     } catch (cause) {
       const msg = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] registry persist failed (${cwd}): ${msg}
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] registry persist failed (${cwd}): ${msg}
 `);
     } finally {
       pendingSaves.delete(cwd);
@@ -558,10 +560,11 @@ function registerAgent(agent) {
 function getRegisteredAgent(agentId) {
   return agents.get(agentId);
 }
-function listRegisteredAgents(runtime, cwd) {
+function listRegisteredAgents(runtime, cwd, includeArchived = false) {
   let out = Array.from(agents.values());
   if (runtime !== void 0) out = out.filter((agent) => agent.runtime === runtime);
   if (cwd !== void 0) out = out.filter((agent) => resolveRegistryCwd(agent) === cwd);
+  if (!includeArchived) out = out.filter((agent) => !agent.archived);
   return out;
 }
 function updateRegisteredAgent(agentId, update) {
@@ -881,14 +884,14 @@ async function readLegacyFacts(jsonPath) {
 }
 async function writeMigratedFacts(cwd, jsonPath, facts) {
   try {
-    for (const fact of facts) await chunkBDTVFIPB_cjs.appendFactToMarkdown(cwd, fact);
+    for (const fact of facts) await chunk5UOVYM3P_cjs.appendFactToMarkdown(cwd, fact);
     await promises.unlink(jsonPath).catch(() => void 0);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] migrated ${facts.length} fact(s) from ${jsonPath} to MEMORY.md
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] migrated ${facts.length} fact(s) from ${jsonPath} to MEMORY.md
 `);
     return { migrated: true, factCount: facts.length };
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] memory migration failed (readonly fs?): ${message}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] memory migration failed (readonly fs?): ${message}
 `);
     return { migrated: false, factCount: 0, reason: "readonly-fs" };
   }
@@ -898,12 +901,12 @@ async function migrateLegacyJson(cwd, config) {
   const key = `${cwd}::${config.namespace ?? "default"}::${config.scope ?? "agent"}::${config.userId ?? "default"}`;
   if (migrationRun.has(key)) return { migrated: false, factCount: 0, reason: "already-migrated" };
   migrationRun.add(key);
-  const jsonPath = chunkBDTVFIPB_cjs.legacyMemoryJsonPath(cwd, config);
+  const jsonPath = chunk5UOVYM3P_cjs.legacyMemoryJsonPath(cwd, config);
   if (!await fileExists(jsonPath)) {
     return { migrated: false, factCount: 0, reason: "no-legacy-json" };
   }
-  if (await fileExists(chunkBDTVFIPB_cjs.memoryMdPath(cwd))) {
-    chunkBM6N4KHO_cjs.diag(
+  if (await fileExists(chunk5UOVYM3P_cjs.memoryMdPath(cwd))) {
+    chunkNUKRL3I6_cjs.diag(
       `[theokit-sdk] memory migration skipped: both MEMORY.md and legacy JSON exist at ${jsonPath}; leaving both intact
 `
     );
@@ -927,13 +930,13 @@ function extractMemoryFact(message) {
 async function readMemoryFacts(cwd, config) {
   if (!config.enabled) return [];
   await migrateLegacyJson(cwd, config);
-  return chunkBDTVFIPB_cjs.readFacts(cwd, config);
+  return chunk5UOVYM3P_cjs.readFacts(cwd, config);
 }
 async function appendMemoryFact(cwd, config, fact) {
   if (!config.enabled) return;
   await migrateLegacyJson(cwd, config);
-  const sanitized = { text: chunkBM6N4KHO_cjs.redactSecrets(fact.text) };
-  await chunkBDTVFIPB_cjs.appendFact(cwd, config, sanitized);
+  const sanitized = { text: chunkJTB5Q42C_cjs.redactSecrets(fact.text) };
+  await chunk5UOVYM3P_cjs.appendFact(cwd, config, sanitized);
 }
 
 // src/internal/runtime/fixtures/fixture-scripts.ts
@@ -1281,7 +1284,7 @@ function redactScriptSecrets(script) {
 function redactEventSecrets(event) {
   const serialized = JSON.stringify(event);
   const localStripped = serialized.replace(FIXTURE_SENTINEL, "***");
-  const redacted = chunkBM6N4KHO_cjs.redactSecrets(localStripped);
+  const redacted = chunkJTB5Q42C_cjs.redactSecrets(localStripped);
   if (redacted === serialized) return event;
   return JSON.parse(redacted);
 }
@@ -1603,8 +1606,8 @@ function createRealCloudRun(options) {
     cancellable: false,
     conversation: []
   };
-  const apiKey = chunkBM6N4KHO_cjs.resolveApiKey(options.agentOptions.apiKey);
-  const baseUrl = chunk2FYEVT2B_cjs.getConfiguredBaseUrl();
+  const apiKey = chunkJTB5Q42C_cjs.resolveApiKey(options.agentOptions.apiKey);
+  const baseUrl = chunkHLPSLDGL_cjs.getConfiguredBaseUrl();
   const handle = new RealCloudRun(
     {
       id,
@@ -1677,7 +1680,7 @@ var RealCloudRun = class extends FixtureRunBase {
     });
     if (!response.ok) {
       const text = await response.text().catch(() => "");
-      throw new chunkLPVIRJVF_cjs.NetworkError(
+      throw new chunkK3FW2XZD_cjs.NetworkError(
         `Cloud Run endpoint returned ${response.status}: ${text.slice(0, 200)}`,
         { code: "cloud_run_http_error" }
       );
@@ -1687,7 +1690,7 @@ var RealCloudRun = class extends FixtureRunBase {
   async consumeStream(response) {
     let finalStatus = "finished";
     let finalText = "";
-    for await (const record of chunk2FYEVT2B_cjs.parseSseStream(response.body, this.controller.signal)) {
+    for await (const record of chunkHLPSLDGL_cjs.parseSseStream(response.body, this.controller.signal)) {
       const parsed = safeParse(record.data);
       if (parsed === void 0) continue;
       const update = this.applyRecord(record.event, parsed);
@@ -1711,7 +1714,7 @@ var RealCloudRun = class extends FixtureRunBase {
     }
     if (eventName === "result") {
       const update = {
-        finalStatus: parsed.status ?? "finished"
+        finalStatus: parsed.status === void 0 ? "finished" : toRunStatus(parsed.status)
       };
       if (typeof parsed.result === "string") update.finalText = parsed.result;
       return update;
@@ -1723,7 +1726,7 @@ var RealCloudRun = class extends FixtureRunBase {
       type: "status",
       agent_id: this.agentId,
       run_id: this.id,
-      status
+      status: toWireStatus(status)
     };
   }
   buildAssistantEvent(text) {
@@ -1745,6 +1748,43 @@ var RealCloudRun = class extends FixtureRunBase {
     this.transitionTo("error");
   }
 };
+var SERVER_STATUS_TO_RUN_STATUS = {
+  creating: "running",
+  running: "running",
+  finished: "finished",
+  error: "error",
+  cancelled: "cancelled",
+  expired: "error"
+};
+var WIRE_STATUSES = [
+  "CREATING",
+  "RUNNING",
+  "FINISHED",
+  "ERROR",
+  "CANCELLED",
+  "EXPIRED"
+];
+function toWireStatus(token) {
+  if (typeof token === "string") {
+    const upper = token.toUpperCase();
+    const match = WIRE_STATUSES.find((candidate) => candidate === upper);
+    if (match !== void 0) return match;
+  }
+  throw new chunkK3FW2XZD_cjs.NetworkError(
+    `Cloud Run stream reported an unrecognised status ${JSON.stringify(token)}; expected one of ${WIRE_STATUSES.join(", ")} (case-insensitive)`,
+    { code: "cloud_run_unknown_status" }
+  );
+}
+function toRunStatus(token) {
+  if (typeof token === "string") {
+    const mapped = SERVER_STATUS_TO_RUN_STATUS[token.toLowerCase()];
+    if (mapped !== void 0) return mapped;
+  }
+  throw new chunkK3FW2XZD_cjs.NetworkError(
+    `Cloud Run stream reported an unrecognised status ${JSON.stringify(token)}; expected one of ${Object.keys(SERVER_STATUS_TO_RUN_STATUS).join(", ")} (case-insensitive)`,
+    { code: "cloud_run_unknown_status" }
+  );
+}
 function safeParse(data2) {
   try {
     return JSON.parse(data2);
@@ -1795,8 +1835,8 @@ var CloudAgent = class {
    * cloud operations are pre-release and must surface explicit errors.
    */
   isFixtureMode() {
-    const apiKey = chunkBM6N4KHO_cjs.resolveApiKey(this.options.apiKey);
-    return chunk2FYEVT2B_cjs.isFixtureApiKey(apiKey) && chunk2FYEVT2B_cjs.getConfiguredBaseUrl() === void 0;
+    const apiKey = chunkJTB5Q42C_cjs.resolveApiKey(this.options.apiKey);
+    return chunkHLPSLDGL_cjs.isFixtureApiKey(apiKey) && chunkHLPSLDGL_cjs.getConfiguredBaseUrl() === void 0;
   }
   // SE9 — integrated structured output; delegates to the shared helper.
   generate(message, options) {
@@ -1810,8 +1850,9 @@ var CloudAgent = class {
     );
   }
   async send(message, options = {}) {
+    if (this.disposed) throw new chunkK3FW2XZD_cjs.AgentDisposedError(this.agentId);
     if (options.tools !== void 0 && options.tools.length > 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         "Custom inline tools are local-only in SDK v1.0 \u2014 cloud agents cannot serialize handler functions",
         { code: "cloud_custom_tools_rejected" }
       );
@@ -1821,7 +1862,7 @@ var CloudAgent = class {
       throw new UnsupportedTaskOperationError("send", { cause: void 0 });
     }
     return new Promise((resolve, reject) => {
-      void chunkYLQQX5W2_cjs.withCwdMutex(`agent-send:${this.agentId}`, async () => {
+      void chunkZF2LDKQQ_cjs.withCwdMutex(`agent-send:${this.agentId}`, async () => {
         let run;
         try {
           run = await this.sendLocked(message, options);
@@ -1846,8 +1887,8 @@ var CloudAgent = class {
     }
     const userText = typeof message === "string" ? message : message.text;
     const systemPrompt = await this.resolveSystemPromptForSend(userText, options);
-    const apiKey = chunkBM6N4KHO_cjs.resolveApiKey(this.options.apiKey);
-    const useRealRuntime = apiKey !== void 0 && !chunk2FYEVT2B_cjs.isFixtureApiKey(apiKey) && chunk2FYEVT2B_cjs.getConfiguredBaseUrl() !== void 0;
+    const apiKey = chunkJTB5Q42C_cjs.resolveApiKey(this.options.apiKey);
+    const useRealRuntime = apiKey !== void 0 && !chunkHLPSLDGL_cjs.isFixtureApiKey(apiKey) && chunkHLPSLDGL_cjs.getConfiguredBaseUrl() !== void 0;
     return useRealRuntime ? createRealCloudRun({
       agentId: this.agentId,
       model: this.model ?? { id: DEFAULT_AGENTIC_MODEL_ID },
@@ -1896,7 +1937,7 @@ var CloudAgent = class {
   listArtifacts() {
     if (!this.isFixtureMode()) {
       return Promise.reject(
-        new chunkLPVIRJVF_cjs.ConfigurationError(
+        new chunkK3FW2XZD_cjs.ConfigurationError(
           "Cloud runtime is pre-release. listArtifacts() will return real artifacts when Theo PaaS ships; today it is only available in fixture mode (theo_test_* keys).",
           { code: "cloud_runtime_pre_release" }
         )
@@ -1906,11 +1947,11 @@ var CloudAgent = class {
   }
   downloadArtifact(path) {
     try {
-      chunkZT57WTUJ_cjs.validateArtifactPath(path);
+      chunkR3UPQFKK_cjs.validateArtifactPath(path);
     } catch (cause) {
-      if (cause instanceof chunkZT57WTUJ_cjs.PathTraversalError) {
+      if (cause instanceof chunkR3UPQFKK_cjs.PathTraversalError) {
         return Promise.reject(
-          new chunkLPVIRJVF_cjs.ConfigurationError(`Artifact path must stay inside the workspace: ${path}`, {
+          new chunkK3FW2XZD_cjs.ConfigurationError(`Artifact path must stay inside the workspace: ${path}`, {
             code: "artifact_path_traversal",
             cause
           })
@@ -1920,7 +1961,7 @@ var CloudAgent = class {
     }
     if (!this.isFixtureMode()) {
       return Promise.reject(
-        new chunkLPVIRJVF_cjs.ConfigurationError(
+        new chunkK3FW2XZD_cjs.ConfigurationError(
           "Cloud runtime is pre-release. downloadArtifact() will fetch real PaaS artifacts when the cloud runtime ships; today it is only available in fixture mode (theo_test_* keys).",
           { code: "cloud_runtime_pre_release" }
         )
@@ -1929,7 +1970,7 @@ var CloudAgent = class {
     const match = buildFixtureArtifacts().find((artifact) => artifact.path === path);
     if (match === void 0) {
       return Promise.reject(
-        new chunkLPVIRJVF_cjs.UnknownAgentError(`Artifact ${path} not found`, { code: "unknown_artifact" })
+        new chunkK3FW2XZD_cjs.UnknownAgentError(`Artifact ${path} not found`, { code: "unknown_artifact" })
       );
     }
     return Promise.resolve(Buffer.from(`fixture artifact content for ${path}
@@ -1943,7 +1984,7 @@ var CloudAgent = class {
    * @public
    */
   runUntil() {
-    throw new chunkLPVIRJVF_cjs.UnsupportedRunOperationError(
+    throw new chunkK3FW2XZD_cjs.UnsupportedRunOperationError(
       "Agent.runUntil() is not supported on cloud agents. Cloud runtime manages goal loops server-side. Use a local agent for autonomous Ralph loops.",
       "runUntil"
     );
@@ -1954,7 +1995,7 @@ var CloudAgent = class {
    * @public
    */
   fork() {
-    throw new chunkLPVIRJVF_cjs.UnsupportedRunOperationError(
+    throw new chunkK3FW2XZD_cjs.UnsupportedRunOperationError(
       "Agent.fork() is not supported on cloud agents. Fork inheritance requires local credential + system-prompt access. Use a local agent.",
       "fork"
     );
@@ -1966,7 +2007,7 @@ var CloudAgent = class {
    * @public
    */
   runToCompletion() {
-    throw new chunkLPVIRJVF_cjs.UnsupportedRunOperationError(
+    throw new chunkK3FW2XZD_cjs.UnsupportedRunOperationError(
       "Agent.runToCompletion() is not supported on cloud agents. Cloud runtime manages continuation server-side. Use a local agent.",
       "runToCompletion"
     );
@@ -1978,7 +2019,7 @@ var CloudAgent = class {
    * @public
    */
   streamToCompletion() {
-    throw new chunkLPVIRJVF_cjs.UnsupportedRunOperationError(
+    throw new chunkK3FW2XZD_cjs.UnsupportedRunOperationError(
       "Agent.streamToCompletion() is not supported on cloud agents. Cloud runtime manages continuation server-side. Use a local agent.",
       "streamToCompletion"
     );
@@ -1992,7 +2033,7 @@ var CloudAgent = class {
    */
   usePersonality() {
     return Promise.reject(
-      new chunkLPVIRJVF_cjs.UnsupportedRunOperationError(
+      new chunkK3FW2XZD_cjs.UnsupportedRunOperationError(
         "Agent.usePersonality() is not supported on cloud agents (pre-release). Use a local agent or wait for cloud GA.",
         "usePersonality"
       )
@@ -2020,7 +2061,7 @@ function validateCloudToolParity(options) {
 function rejectProcessors(options) {
   const hasProcessors = (options.inputProcessors?.length ?? 0) > 0 || (options.outputProcessors?.length ?? 0) > 0;
   if (hasProcessors) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Cloud agents can't run guardrail processors \u2014 a Processor carries function handlers that don't survive serialization to PaaS. Run processors on a local agent, or move the guardrail into a server-side gateway in front of TheoCloud.",
       { code: "cloud_incompatible_function_resolver" }
     );
@@ -2028,7 +2069,7 @@ function rejectProcessors(options) {
 }
 function rejectFunctionSystemPrompt(options) {
   if (typeof options.systemPrompt === "function") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Cloud agents require systemPrompt as a serializable string. SystemPromptResolver functions can't run on PaaS \u2014 resolve to a string before Agent.create() or move the dynamic logic into a hook rule.",
       { code: "cloud_incompatible_function_resolver" }
     );
@@ -2036,7 +2077,7 @@ function rejectFunctionSystemPrompt(options) {
 }
 function rejectFunctionSkills(options) {
   if (typeof options.skills === "function") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Cloud agents require skills as a static settings object. SkillsResolver functions can't run on PaaS \u2014 resolve to a SkillsSettings object before Agent.create() or move the dynamic logic into a hook rule.",
       { code: "cloud_incompatible_function_resolver" }
     );
@@ -2048,7 +2089,7 @@ function rejectStdioMcpLocalPaths(options) {
     if (!isStdioCommandConfig(config)) continue;
     const command = config.command ?? "";
     if (isLocalPath(command)) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `MCP server "${name}" uses a local-FS command path (${command}). Cloud agents can't reach local binaries \u2014 use a bare command (npx, uvx, node, \u2026) that the PaaS VM image provides, or switch to an HTTP MCP server.`,
         { code: "cloud_incompatible_mcp_stdio_local" }
       );
@@ -2068,19 +2109,19 @@ function isLocalPath(command) {
 function resolveSessionDir(local) {
   if (local?.sessionDir !== void 0) {
     if (local.baseDir !== void 0) {
-      chunkBM6N4KHO_cjs.diag(
+      chunkNUKRL3I6_cjs.diag(
         "[theokit-sdk] local.sessionDir and local.baseDir are both set; using sessionDir. baseDir is the deprecated name for the same option (#301)."
       );
     }
-    return chunkY4AXQOT4_cjs.expandTilde(local.sessionDir);
+    return chunkJHPGF3FP_cjs.expandTilde(local.sessionDir);
   }
   if (local?.baseDir !== void 0) {
-    chunkBM6N4KHO_cjs.diag(
+    chunkNUKRL3I6_cjs.diag(
       "[theokit-sdk] local.baseDir is deprecated; rename it to local.sessionDir (#301). It is the directory for session transcripts, not the working directory \u2014 that is local.cwd."
     );
-    return chunkY4AXQOT4_cjs.expandTilde(local.baseDir);
+    return chunkJHPGF3FP_cjs.expandTilde(local.baseDir);
   }
-  return chunkY4AXQOT4_cjs.defaultBaseDir();
+  return chunkJHPGF3FP_cjs.defaultBaseDir();
 }
 var SCHEMA_VERSION2 = 1;
 var FILE_NAME = "personality.json";
@@ -2107,14 +2148,14 @@ async function readState(filePath) {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    chunk665SFFFR_cjs.warnOnce(
+    chunk53CBTBWO_cjs.warnOnce(
       "personality-store-json-parse",
       "[theokit-sdk] personality.json is malformed; treating as empty"
     );
     return emptyState();
   }
   if (!isStateV1(parsed)) {
-    chunk665SFFFR_cjs.warnOnce(
+    chunk53CBTBWO_cjs.warnOnce(
       "personality-store-bad-version",
       `[theokit-sdk] personality.json has unknown version; treating as empty (file kept untouched)`
     );
@@ -2145,9 +2186,9 @@ var PersonalityStore = class {
       try {
         await this.#persist(agentId, slug);
       } catch (err) {
-        chunk665SFFFR_cjs.warnOnce(
+        chunk53CBTBWO_cjs.warnOnce(
           `personality-store-persist-failure-${agentId}`,
-          `[theokit-sdk] personality persist failed for ${chunkBM6N4KHO_cjs.redactSecrets(agentId)}: ${chunkBM6N4KHO_cjs.redactSecrets(
+          `[theokit-sdk] personality persist failed for ${chunkJTB5Q42C_cjs.redactSecrets(agentId)}: ${chunkJTB5Q42C_cjs.redactSecrets(
             err.message
           )}`
         );
@@ -2162,9 +2203,9 @@ var PersonalityStore = class {
     try {
       state = await readState(filePath);
     } catch (err) {
-      chunk665SFFFR_cjs.warnOnce(
+      chunk53CBTBWO_cjs.warnOnce(
         `personality-store-hydrate-failure-${agentId}`,
-        `[theokit-sdk] personality hydrate failed for ${chunkBM6N4KHO_cjs.redactSecrets(agentId)}: ${chunkBM6N4KHO_cjs.redactSecrets(
+        `[theokit-sdk] personality hydrate failed for ${chunkJTB5Q42C_cjs.redactSecrets(agentId)}: ${chunkJTB5Q42C_cjs.redactSecrets(
           err.message
         )}`
       );
@@ -2181,17 +2222,17 @@ var PersonalityStore = class {
   async #persist(agentId, slug) {
     const filePath = this.#filePath();
     await promises.mkdir(path.dirname(filePath), { recursive: true });
-    await chunkTTJ54H3E_cjs.withFileLock(filePath, async () => {
+    await chunk2ADR2GSO_cjs.withFileLock(filePath, async () => {
       const current = await readState(filePath);
       const nextAgents = { ...current.agents };
       if (slug === void 0) delete nextAgents[agentId];
       else nextAgents[agentId] = slug;
       const next = { version: SCHEMA_VERSION2, agents: nextAgents };
-      await chunkC4H6PB5J_cjs.atomicWriteJson(filePath, next);
+      await chunkI6TGFUCO_cjs.atomicWriteJson(filePath, next);
     });
   }
   #filePath() {
-    return path.join(chunkHAWE74GQ_cjs.getTheokitHome(this.#cwd), FILE_NAME);
+    return path.join(chunkU2AC6JUP_cjs.getTheokitHome(this.#cwd), FILE_NAME);
   }
 };
 
@@ -2214,7 +2255,7 @@ function createPluginContext() {
     },
     on(hook, handler) {
       if (typeof handler !== "function") {
-        chunkBM6N4KHO_cjs.diag(`[theokit-sdk] ignoring non-function handler for hook "${hook}"
+        chunkNUKRL3I6_cjs.diag(`[theokit-sdk] ignoring non-function handler for hook "${hook}"
 `);
         return;
       }
@@ -2267,7 +2308,7 @@ var PluginManager = class {
     const seen = /* @__PURE__ */ new Set();
     for (const plugin of plugins) {
       if (seen.has(plugin.name)) {
-        chunkBM6N4KHO_cjs.diag(
+        chunkNUKRL3I6_cjs.diag(
           `[theokit-sdk] duplicate plugin name "${plugin.name}" \u2014 both will register independently
 `
         );
@@ -2294,7 +2335,7 @@ var PluginManager = class {
    */
   async register(plugin) {
     if (plugin.kind !== "general") {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `late register supports general plugins only (got "${plugin.kind}" for "${plugin.name}")`,
         { code: "plugin_late_register_kind" }
       );
@@ -2351,7 +2392,7 @@ var PluginManager = class {
           parts.push(result.recalledContext);
         }
       } catch (err) {
-        chunkBM6N4KHO_cjs.diag(
+        chunkNUKRL3I6_cjs.diag(
           `[theokit-sdk] pre_user_send hook failed: ${err instanceof Error ? err.message : String(err)}
 `
         );
@@ -2379,7 +2420,7 @@ var PluginManager = class {
       try {
         await h(ctx);
       } catch (err) {
-        chunkBM6N4KHO_cjs.diag(
+        chunkNUKRL3I6_cjs.diag(
           `[theokit-sdk] post_assistant_reply hook failed: ${err instanceof Error ? err.message : String(err)}
 `
         );
@@ -2395,7 +2436,7 @@ var PluginManager = class {
       try {
         await h(ctx);
       } catch (err) {
-        chunkBM6N4KHO_cjs.diag(
+        chunkNUKRL3I6_cjs.diag(
           `[theokit-sdk] ${name} hook failed: ${err instanceof Error ? err.message : String(err)}
 `
         );
@@ -2410,7 +2451,7 @@ var PluginManager = class {
         const out = await h(current, ctx);
         if (out !== void 0) current = out;
       } catch (err) {
-        chunkBM6N4KHO_cjs.diag(
+        chunkNUKRL3I6_cjs.diag(
           `[theokit-sdk] ${name} hook failed: ${err instanceof Error ? err.message : String(err)}
 `
         );
@@ -2552,7 +2593,7 @@ var HooksExecutor = class {
       this.config = {};
       return;
     }
-    this.config = await chunk665SFFFR_cjs.loadHookConfig(this.cwd);
+    this.config = await chunk53CBTBWO_cjs.loadHookConfig(this.cwd);
   }
   /** Fire every hook registered for `event` and aggregate the decisions. */
   async run(payload) {
@@ -2656,13 +2697,16 @@ function buildContextBudgetEvent(model, resolved) {
 }
 
 // src/internal/runtime/lifecycle/post-run-lifecycle.ts
+function sessionTranscriptAllowed(memory) {
+  return memory?.enabled !== false;
+}
 function resolveWindowForRun(model, contextWindow) {
   const override = contextWindow !== void 0 && contextWindow > 0 ? contextWindow : void 0;
-  return chunkADLLFY3H_cjs.resolveEffectiveContextWindow({
+  return chunkXSX2UU6Y_cjs.resolveEffectiveContextWindow({
     ...override !== void 0 ? { override } : {},
-    catalog: chunkVUKQL3L2_cjs.getCatalogModelInfo(model)?.limit?.context,
-    margin: chunkADLLFY3H_cjs.CONTEXT_WINDOW_MARGIN,
-    floor: chunkADLLFY3H_cjs.CONTEXT_WINDOW_FLOOR
+    catalog: chunkNIRE5CNO_cjs.getCatalogModelInfo(model)?.limit?.context,
+    margin: chunkXSX2UU6Y_cjs.CONTEXT_WINDOW_MARGIN,
+    floor: chunkXSX2UU6Y_cjs.CONTEXT_WINDOW_FLOOR
   });
 }
 async function runPostRunLifecycle(inputs) {
@@ -2686,32 +2730,32 @@ async function runPostRunLifecycle(inputs) {
     try {
       const partial = await safeConversation(run);
       if (partial !== void 0) {
-        chunk2D43RD5D_cjs.persistTurnToTranscript(sessionStore, { cwd: workspaceCwd, agentId, model }, agentId, {
+        chunkV2UUGUY4_cjs.persistTurnToTranscript(sessionStore, { cwd: workspaceCwd, agentId, model }, agentId, {
           userText,
           conversation: partial
         });
       }
     } catch (cause) {
       const msg = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] partial transcript write failed (${agentId}): ${msg}
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] partial transcript write failed (${agentId}): ${msg}
 `);
     }
-    await chunk2D43RD5D_cjs.flushSessionWrites();
+    await chunkV2UUGUY4_cjs.flushSessionWrites();
     return;
   }
   if (result.result !== void 0) {
-    chunk2D43RD5D_cjs.appendSessionMessage(agentId, { role: "assistant", text: result.result });
+    chunkV2UUGUY4_cjs.appendSessionMessage(agentId, { role: "assistant", text: result.result });
   }
   const conversation = await safeConversation(run);
   const resolvedWindow = resolveWindowForRun(model, contextWindow);
   const effectiveWindow = resolvedWindow.window;
   const budgetEvent = buildContextBudgetEvent(model, resolvedWindow);
   if (budgetEvent !== void 0 && onRunEvent !== void 0) {
-    chunkXPR366DL_cjs.emitRunEvent(onRunEvent, budgetEvent);
+    chunkNGESVVJN_cjs.emitRunEvent(onRunEvent, budgetEvent);
   }
   const lastRequestUsage = result.usage?.requests?.at(-1)?.totalTokens;
   const usageForTrigger = lastRequestUsage ?? result.usage?.totalTokens;
-  chunk2D43RD5D_cjs.persistTurnToTranscript(
+  chunkV2UUGUY4_cjs.persistTurnToTranscript(
     sessionStore,
     { cwd: workspaceCwd, agentId, model },
     agentId,
@@ -2723,15 +2767,15 @@ async function runPostRunLifecycle(inputs) {
         // The EFFECTIVE window (after override, clamp and margin) — not the declared one. Swapping for
         // `contextWindow` here would budget against a number the clamp already rejected.
         contextWindow: effectiveWindow,
-        summarize: chunk2FYEVT2B_cjs.buildDefaultSummarizer({
+        summarize: chunkHLPSLDGL_cjs.buildDefaultSummarizer({
           agentModel: model,
           ...inputs.apiKey !== void 0 ? { apiKey: inputs.apiKey } : {}
         })
       }
     },
-    onRunEvent !== void 0 ? () => chunkXPR366DL_cjs.emitRunEvent(onRunEvent, { type: "compact_boundary", trigger: "auto" }) : void 0
+    onRunEvent !== void 0 ? () => chunkNGESVVJN_cjs.emitRunEvent(onRunEvent, { type: "compact_boundary", trigger: "auto" }) : void 0
   );
-  if (result.status === "finished" && result.result !== void 0) {
+  if (result.status === "finished" && result.result !== void 0 && sessionTranscriptAllowed(inputs.memory)) {
     const summaryArgs = {
       cwd: workspaceCwd,
       runId: result.id,
@@ -2745,14 +2789,14 @@ async function runPostRunLifecycle(inputs) {
       if (memoryProvider?.recordSessionSummary !== void 0) {
         await memoryProvider.recordSessionSummary(summaryArgs);
       } else {
-        await chunkBDTVFIPB_cjs.writeSessionSummary(summaryArgs);
+        await chunk5UOVYM3P_cjs.writeSessionSummary(summaryArgs);
       }
       if (!shouldUsePortMemoryPath()) {
         void memoryGlue.syncIfReady();
       }
     } catch (cause) {
       const message = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] session summary write failed (${result.id}): ${message}
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] session summary write failed (${result.id}): ${message}
 `);
     }
   }
@@ -2765,7 +2809,7 @@ async function runPostRunLifecycle(inputs) {
     agentId,
     runId: result.id
   });
-  await chunk2D43RD5D_cjs.flushSessionWrites();
+  await chunkV2UUGUY4_cjs.flushSessionWrites();
 }
 async function safeConversation(run) {
   try {
@@ -2840,7 +2884,7 @@ var warned = /* @__PURE__ */ new Set();
 function warnDoubleReasoningOnce() {
   if (warned.has("double-reasoning")) return;
   warned.add("double-reasoning");
-  chunkBM6N4KHO_cjs.diag(
+  chunkNUKRL3I6_cjs.diag(
     "[theokit-sdk] `reasoning: true` skipped \u2014 a native reasoning model is configured (model.params thinking/reasoning); native reasoning wins. Remove one to silence.\n"
   );
 }
@@ -2873,9 +2917,9 @@ var SkillsManager = class {
   }
   async refresh() {
     const skillsRoot = this.skillsDir ?? path.join(this.cwd, ".theokit", "skills");
-    const discovered = await chunkZN2DGEY3_cjs.discoverSkills(skillsRoot, {
+    const discovered = await chunk3YJNUKYN_cjs.discoverSkills(skillsRoot, {
       onInvalidSkill: (info) => {
-        chunkBM6N4KHO_cjs.diag(`[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
+        chunkNUKRL3I6_cjs.diag(`[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
 `);
       }
     });
@@ -2899,7 +2943,7 @@ var SkillsManager = class {
   async get(name) {
     const skill = this.skills.find((s) => s.name === name);
     if (skill === void 0) return void 0;
-    const instructions = typeof skill.instructions === "string" ? skill.instructions : chunkZN2DGEY3_cjs.stripSkillFrontmatter(await promises.readFile(skill.source, "utf8"));
+    const instructions = typeof skill.instructions === "string" ? skill.instructions : chunk3YJNUKYN_cjs.stripSkillFrontmatter(await promises.readFile(skill.source, "utf8"));
     const references = skill.references;
     return {
       name: skill.name,
@@ -2985,7 +3029,7 @@ async function safeCall(fn, fallback, label = "safeCall") {
     return await fn();
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] ${label} failed: ${message}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] ${label} failed: ${message}
 `);
     return fallback;
   }
@@ -2999,7 +3043,7 @@ var ActiveMemoryPromptProvider = class {
     if (ctx.activeMemorySummary === void 0 || ctx.activeMemorySummary.length === 0) {
       return Promise.resolve(void 0);
     }
-    const body = chunkZN2DGEY3_cjs.escapeBlockBody(ctx.activeMemorySummary);
+    const body = chunk3YJNUKYN_cjs.escapeBlockBody(ctx.activeMemorySummary);
     return Promise.resolve(`<active-memory>
 ${body}
 </active-memory>`);
@@ -3052,7 +3096,7 @@ function formatSource(name, tokens) {
   if (tokens.length === 0) {
     return `  <source name="${escapeAttribute(name)}" />`;
   }
-  const body = chunkZN2DGEY3_cjs.escapeBlockBody(tokens.join(" "));
+  const body = chunk3YJNUKYN_cjs.escapeBlockBody(tokens.join(" "));
   return `  <source name="${escapeAttribute(name)}">
     ${body}
   </source>`;
@@ -3068,7 +3112,7 @@ var MemoryPromptProvider = class {
   contribute(ctx) {
     if (ctx.memoryAutoInject === false) return Promise.resolve(void 0);
     if (ctx.memory.length === 0) return Promise.resolve(void 0);
-    const lines = ctx.memory.map((fact) => `  - ${chunkZN2DGEY3_cjs.escapeBlockBody(fact.text)}`);
+    const lines = ctx.memory.map((fact) => `  - ${chunk3YJNUKYN_cjs.escapeBlockBody(fact.text)}`);
     return Promise.resolve(`<memory>
 ${lines.join("\n")}
 </memory>`);
@@ -3090,7 +3134,7 @@ var SkillsPromptProvider = class {
   priority = 20;
   contribute(ctx) {
     if (ctx.skillsAutoInject === false) return Promise.resolve(void 0);
-    return Promise.resolve(chunkZN2DGEY3_cjs.buildSkillsBlock(ctx.skills));
+    return Promise.resolve(chunk3YJNUKYN_cjs.buildSkillsBlock(ctx.skills));
   }
 };
 
@@ -3102,7 +3146,7 @@ var SystemPromptPipeline = class _SystemPromptPipeline {
     for (const p of providers) {
       const key = `${p.priority}:${p.id}`;
       if (seen.has(key)) {
-        throw new chunkLPVIRJVF_cjs.ConfigurationError(`Duplicate system-prompt provider ${key}`, {
+        throw new chunkK3FW2XZD_cjs.ConfigurationError(`Duplicate system-prompt provider ${key}`, {
           code: "pipeline_duplicate_provider"
         });
       }
@@ -3149,7 +3193,7 @@ function validateAgentOptions(options) {
   ensureRuntimeShape(options);
   if (options.local !== void 0) {
     if (options.model === void 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError("Local agents require a model selection", {
+      throw new chunkK3FW2XZD_cjs.ConfigurationError("Local agents require a model selection", {
         code: "missing_model"
       });
     }
@@ -3173,7 +3217,7 @@ function validateCredentialPoolShape(options) {
     ([, arr]) => Array.isArray(arr) && arr.some((k) => typeof k === "string" && k.length > 0)
   );
   if (populated.length === 0) return;
-  throw new chunkLPVIRJVF_cjs.ConfigurationError(
+  throw new chunkK3FW2XZD_cjs.ConfigurationError(
     "Ambiguous credential configuration: use either `apiKey: '...'` (single-key, simplest) OR `apiKeys: { provider: [...] }` (multi-key pool), not both.",
     { code: "credential_pool_ambiguous" }
   );
@@ -3182,7 +3226,7 @@ function validatePlugins(options) {
   const plugins = options.plugins;
   if (plugins?.paths === void 0) return;
   if (options.cloud !== void 0 && plugins.paths.length > 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Cloud agents require committed plugin manifests; local plugin paths are not supported",
       { code: "cloud_plugin_path_rejected" }
     );
@@ -3190,7 +3234,7 @@ function validatePlugins(options) {
 }
 function ensureRuntimeShape(options) {
   if (options.local !== void 0 && options.cloud !== void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Pass either local or cloud \u2014 they are mutually exclusive runtimes",
       { code: "runtime_exclusive" }
     );
@@ -3198,7 +3242,7 @@ function ensureRuntimeShape(options) {
 }
 function rejectProgrammaticHooks(options) {
   if (options.hooks !== void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Programmatic hooks are not supported \u2014 hooks are file-based only (.theokit/hooks.json)",
       { code: "programmatic_hooks_rejected" }
     );
@@ -3208,7 +3252,7 @@ function validateCloud(cloud) {
   if (cloud.envVars !== void 0) {
     for (const key of Object.keys(cloud.envVars)) {
       if (key.startsWith("THEOKIT_")) {
-        throw new chunkLPVIRJVF_cjs.ConfigurationError(
+        throw new chunkK3FW2XZD_cjs.ConfigurationError(
           `Cloud envVars cannot use the reserved THEOKIT_ prefix (got "${key}")`,
           { code: "reserved_env_prefix" }
         );
@@ -3220,7 +3264,7 @@ function validateMcpServers(options) {
   if (options.mcpServers === void 0) return;
   for (const [name, config] of Object.entries(options.mcpServers)) {
     if (options.cloud !== void 0 && isStdioWithCwd(config)) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `MCP server "${name}" uses stdio with cwd, which is rejected for cloud agents`,
         { code: "cloud_stdio_cwd_rejected" }
       );
@@ -3239,25 +3283,31 @@ function validateSubagents(agents2) {
   if (agents2 === void 0) return;
   for (const [name, definition] of Object.entries(agents2)) {
     if (typeof definition.description !== "string" || definition.description.length === 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(`Subagent "${name}" requires a non-empty description`, {
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(`Subagent "${name}" requires a non-empty description`, {
         code: "subagent_missing_description"
       });
     }
     if (typeof definition.prompt !== "string" || definition.prompt.length === 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(`Subagent "${name}" requires a non-empty prompt`, {
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(`Subagent "${name}" requires a non-empty prompt`, {
         code: "subagent_missing_prompt"
       });
     }
   }
 }
 var TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
-var RESERVED_TOOL_NAMES = /* @__PURE__ */ new Set(["shell", "memory_search", "memory_get"]);
-function validateToolCatalog(tools) {
+var BUILTIN_TOOL_NAMES = ["shell", "memory_search", "memory_get"];
+var RESERVED_TOOL_NAMES = new Set(BUILTIN_TOOL_NAMES);
+function reservedNamesFor(withheld) {
+  if (withheld === void 0 || withheld.length === 0) return RESERVED_TOOL_NAMES;
+  return new Set(BUILTIN_TOOL_NAMES.filter((name) => !withheld.includes(name)));
+}
+function validateToolCatalog(tools, withheldBuiltins) {
+  const reserved = reservedNamesFor(withheldBuiltins);
   const seen = /* @__PURE__ */ new Set();
   for (const tool of tools) {
-    validateSingleTool(tool);
+    validateSingleTool(tool, reserved);
     if (seen.has(tool.name)) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(`Duplicate custom tool name "${tool.name}"`, {
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(`Duplicate custom tool name "${tool.name}"`, {
         code: "duplicate_tool_name"
       });
     }
@@ -3268,37 +3318,37 @@ function validateCustomTools(options) {
   const tools = options.tools;
   if (tools === void 0 || tools.length === 0) return;
   if (options.cloud !== void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Custom inline tools are local-only in SDK v1.0 \u2014 cloud agents cannot serialize handler functions",
       { code: "cloud_custom_tools_rejected" }
     );
   }
-  validateToolCatalog(tools);
+  validateToolCatalog(tools, options.withheldBuiltinTools);
 }
-function validateSingleTool(tool) {
-  validateToolName(tool);
+function validateSingleTool(tool, reserved) {
+  validateToolName(tool, reserved);
   validateToolDescription(tool);
   validateToolSchema(tool);
   if (typeof tool.handler !== "function") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Custom tool "${tool.name}" requires a handler function`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Custom tool "${tool.name}" requires a handler function`, {
       code: "tool_missing_handler"
     });
   }
 }
-function validateToolName(tool) {
+function validateToolName(tool, reserved) {
   if (typeof tool.name !== "string" || tool.name.length === 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError("Custom tool requires a non-empty name", {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError("Custom tool requires a non-empty name", {
       code: "tool_missing_name"
     });
   }
   if (!TOOL_NAME_PATTERN.test(tool.name)) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Custom tool name "${tool.name}" must match /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/`,
       { code: "tool_invalid_name" }
     );
   }
-  if (RESERVED_TOOL_NAMES.has(tool.name) || tool.name.startsWith("mcp_")) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+  if (reserved.has(tool.name) || tool.name.startsWith("mcp_")) {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Custom tool name "${tool.name}" collides with a reserved SDK tool name`,
       { code: "tool_reserved_name" }
     );
@@ -3306,7 +3356,7 @@ function validateToolName(tool) {
 }
 function validateToolDescription(tool) {
   if (typeof tool.description !== "string" || tool.description.length === 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Custom tool "${tool.name}" requires a non-empty description`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Custom tool "${tool.name}" requires a non-empty description`, {
       code: "tool_missing_description"
     });
   }
@@ -3314,12 +3364,12 @@ function validateToolDescription(tool) {
 function validateToolSchema(tool) {
   const schema = tool.inputSchema;
   if (schema === null || schema === void 0 || typeof schema !== "object") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Custom tool "${tool.name}" requires an inputSchema object`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Custom tool "${tool.name}" requires an inputSchema object`, {
       code: "tool_missing_schema"
     });
   }
   if (schema.type !== "object") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Custom tool "${tool.name}" inputSchema must declare \`type: "object"\``,
       { code: "tool_invalid_schema_type" }
     );
@@ -3330,7 +3380,7 @@ function validateMemory(options) {
   if (memory?.storePath === void 0) return;
   const storePath = memory.storePath;
   if (storePath.includes("..") || storePath.startsWith("/") || /^[A-Z]:/i.test(storePath)) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Memory storePath must stay inside the workspace; got "${storePath}"`,
       { code: "memory_path_traversal" }
     );
@@ -3352,7 +3402,7 @@ var HISTOGRAM_NAMES = {
 };
 function safeRequire(moduleName) {
   try {
-    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-F77UENR6.cjs', document.baseURI).href)));
+    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-F5WMX4EA.cjs', document.baseURI).href)));
     return r(moduleName);
   } catch {
     return void 0;
@@ -3431,7 +3481,7 @@ var langfuseAdapter = {
       }
     }
     if (lf.LangfuseSpanProcessor === void 0) {
-      chunkBM6N4KHO_cjs.diag(
+      chunkNUKRL3I6_cjs.diag(
         "[theokit-sdk] @langfuse/node detected but LangfuseSpanProcessor not found (v2?). Use Langfuse v3+ for auto-instrumentation.\n"
       );
       return;
@@ -3459,6 +3509,9 @@ var langsmithAdapter = {
 
 // src/internal/telemetry/adapters/posthog.ts
 var registeredHere6 = false;
+function presentEnv(value) {
+  return value !== void 0 && value.trim().length > 0 ? value : void 0;
+}
 var posthogAdapter = {
   moduleName: "posthog-node",
   displayName: "PostHog",
@@ -3468,12 +3521,12 @@ var posthogAdapter = {
     const ph = safeRequire("posthog-node");
     const otel = safeRequire("@opentelemetry/api");
     if (ph === void 0 || otel === void 0) return;
-    const key = process.env.POSTHOG_API_KEY ?? process.env.POSTHOG_PROJECT_API_KEY;
+    const key = presentEnv(process.env.POSTHOG_API_KEY) ?? presentEnv(process.env.POSTHOG_PROJECT_API_KEY);
     if (typeof key !== "string" || key.length === 0) {
       return;
     }
     const client = new ph.PostHog(key, {
-      host: process.env.POSTHOG_HOST ?? "https://us.i.posthog.com"
+      host: presentEnv(process.env.POSTHOG_HOST) ?? "https://us.i.posthog.com"
     });
     const provider = otel.trace.getTracerProvider();
     if (provider.addSpanProcessor === void 0) return;
@@ -3560,11 +3613,11 @@ function tryAutoRegisterAdapters(settings) {
     try {
       adapter.register();
       registered.add(adapter.moduleName);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] telemetry: ${adapter.displayName} auto-instrumented.
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] telemetry: ${adapter.displayName} auto-instrumented.
 `);
     } catch (cause) {
       const message = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(
+      chunkNUKRL3I6_cjs.diag(
         `[theokit-sdk] telemetry: ${adapter.displayName} detected but failed to register: ${message}
 `
       );
@@ -3577,7 +3630,7 @@ var cachedOtel;
 function loadOtel() {
   if (cachedOtel === void 0) {
     try {
-      const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-F77UENR6.cjs', document.baseURI).href)));
+      const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-F5WMX4EA.cjs', document.baseURI).href)));
       const mod = r("@opentelemetry/api");
       cachedOtel = mod;
     } catch {
@@ -3620,7 +3673,7 @@ function safe(op, fallback) {
     if (!warnedOnce) {
       warnedOnce = true;
       const message = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(
+      chunkNUKRL3I6_cjs.diag(
         `[theokit-sdk] telemetry exporter error (suppressed; agent.send continues): ${message}
 `
       );
@@ -3634,7 +3687,7 @@ function createTelemetry(settings) {
   if (otel === null) {
     if (!warnedOnce) {
       warnedOnce = true;
-      chunkBM6N4KHO_cjs.diag(
+      chunkNUKRL3I6_cjs.diag(
         "[theokit-sdk] telemetry.enabled = true but `@opentelemetry/api` is not installed; telemetry is a no-op.\n"
       );
     }
@@ -3728,12 +3781,12 @@ function wrapSpan(span, openSpans) {
 }
 function redactAttrValue(value) {
   if (typeof value !== "string") return value;
-  return chunkBM6N4KHO_cjs.redactSecrets(value);
+  return chunkJTB5Q42C_cjs.redactSecrets(value);
 }
 function redactAttrs(attrs) {
   const out = {};
   for (const [k, v] of Object.entries(attrs)) {
-    out[k] = typeof v === "string" ? chunkBM6N4KHO_cjs.redactSecrets(v) : v;
+    out[k] = typeof v === "string" ? chunkJTB5Q42C_cjs.redactSecrets(v) : v;
   }
   return out;
 }
@@ -3751,10 +3804,11 @@ var ProvidersManagerImpl = class {
   routes() {
     const resolved = [];
     const modelProvider = providerFromModel(this.model);
+    const modelId = this.model?.id;
     const seen = /* @__PURE__ */ new Set();
     if (this.providers?.routes !== void 0) {
       for (const route of this.providers.routes) {
-        const resolvedRoute = resolveRoute(route, modelProvider, this.plugins);
+        const resolvedRoute = resolveRoute(route, modelProvider, modelId, this.plugins);
         if (!seen.has(route.capability)) {
           seen.add(route.capability);
           resolved.push(resolvedRoute);
@@ -3770,9 +3824,9 @@ function providerFromModel(model) {
   if (id.includes(":")) return id.split(":")[0];
   return void 0;
 }
-function resolveRoute(route, modelProvider, plugins) {
+function resolveRoute(route, modelProvider, modelId, plugins) {
   if (route.capability === "chat" && modelProvider === route.provider) {
-    const modelName = extractModelName(modelProvider, route);
+    const modelName = extractModelName(modelProvider, modelId, route);
     const base = {
       capability: route.capability,
       provider: route.provider,
@@ -3794,13 +3848,11 @@ function resolveRoute(route, modelProvider, plugins) {
     reason: "explicit-route"
   };
 }
-function extractModelName(prefix, route) {
+function extractModelName(prefix, modelId, route) {
   if (route.model !== void 0) return route.model;
-  return prefix === route.provider ? defaultModelForProvider(prefix) : void 0;
-}
-function defaultModelForProvider(provider) {
-  if (provider === "anthropic") return "claude-3-7-sonnet";
-  return void 0;
+  if (prefix !== route.provider || modelId === void 0) return void 0;
+  const name = modelId.slice(modelId.indexOf(":") + 1);
+  return name.length > 0 ? name : void 0;
 }
 var MAX_MD_FILE_BYTES = 1048576;
 async function loadMarkdownEntities(opts) {
@@ -3815,10 +3867,10 @@ async function loadMarkdownEntities(opts) {
     const raw = await promises.readFile(resolved.source, "utf8").catch(() => null);
     if (raw === null) continue;
     const split = splitFrontmatter(raw, resolved.source, errorCodePrefix);
-    const fields = chunkSZHU7A5B_cjs.parseSimpleYaml(split.frontmatter);
+    const fields = chunkIWBGCBR6_cjs.parseSimpleYaml(split.frontmatter);
     const parsed = schema.safeParse(fields);
     if (!parsed.success) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `Invalid frontmatter in ${resolved.source}: ${parsed.error.message}`,
         { code: `${errorCodePrefix}_frontmatter_invalid` }
       );
@@ -3836,13 +3888,13 @@ async function assertFileSizeUnderCap(source, errorCodePrefix) {
   try {
     const info = await promises.stat(source);
     if (info.size > MAX_MD_FILE_BYTES) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `Config file ${source} exceeds 1 MB size limit (${info.size} bytes). Reduce the file or split into multiple entities.`,
         { code: `${errorCodePrefix}_file_too_large` }
       );
     }
   } catch (cause) {
-    if (cause instanceof chunkLPVIRJVF_cjs.ConfigurationError) throw cause;
+    if (cause instanceof chunkK3FW2XZD_cjs.ConfigurationError) throw cause;
   }
 }
 async function readDirSafe(dir, errorCodePrefix) {
@@ -3851,7 +3903,7 @@ async function readDirSafe(dir, errorCodePrefix) {
   } catch (cause) {
     const code = cause.code;
     if (code === "ENOENT") return null;
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Failed to read ${dir}`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Failed to read ${dir}`, {
       code: `${errorCodePrefix}_dir_read_error`,
       cause
     });
@@ -3868,7 +3920,7 @@ function resolveEntryPath(entry, pattern, dir) {
 function splitFrontmatter(raw, source, errorCodePrefix) {
   const match = /^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/.exec(raw);
   if (match === null) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Missing or malformed frontmatter in ${source} (expected \`---\` delimited block at file head)`,
       { code: `${errorCodePrefix}_missing_frontmatter` }
     );
@@ -3897,7 +3949,7 @@ function applyAggregateCap(sources, maxTotal) {
     }
     const remaining = maxTotal - totalBytes;
     if (remaining > 0) {
-      const { finalContent } = chunkOKLYRPKL_cjs.truncateWithMarker(s.content, remaining);
+      const { finalContent } = chunkQ47R5E2X_cjs.truncateWithMarker(s.content, remaining);
       kept.push({ ...s, content: finalContent, truncated: true });
       totalBytes = maxTotal;
     } else {
@@ -3971,9 +4023,9 @@ var FileContextManager = class {
     this.lastScope = [...touchedFiles];
     const config = await loadContextConfig(this.cwd);
     const legacy = await loadSources(config, this.cwd);
-    const maxBytesPerFile = this.settings.maxBytesPerFile ?? chunkOKLYRPKL_cjs.DEFAULT_MAX_BYTES_PER_FILE;
+    const maxBytesPerFile = this.settings.maxBytesPerFile ?? chunkQ47R5E2X_cjs.DEFAULT_MAX_BYTES_PER_FILE;
     const maxBytesTotal = this.settings.maxBytesTotal ?? DEFAULT_MAX_BYTES_TOTAL;
-    const discovered = await chunkOKLYRPKL_cjs.runDiscovery({
+    const discovered = await chunkQ47R5E2X_cjs.runDiscovery({
       cwd: this.cwd,
       maxBytesPerFile,
       skipLegacyTheokitContext: true,
@@ -4042,7 +4094,7 @@ async function loadContextConfig(cwd) {
   });
   if (mdEntities.length > 0) {
     if (fs.existsSync(jsonPath)) {
-      chunk665SFFFR_cjs.warnOnce(
+      chunk53CBTBWO_cjs.warnOnce(
         "context-both-present",
         "[theokit-sdk] both .theokit/context/ and .theokit/context.json detected \u2014 using markdown; remove context.json"
       );
@@ -4052,7 +4104,7 @@ async function loadContextConfig(cwd) {
     };
   }
   if (!fs.existsSync(jsonPath)) return { sources: [] };
-  chunk665SFFFR_cjs.warnOnce(
+  chunk53CBTBWO_cjs.warnOnce(
     "context-json-deprecated",
     "[theokit-sdk] .theokit/context.json is deprecated; migrate to .theokit/context/<name>.md via theokit-migrate-config"
   );
@@ -4060,7 +4112,7 @@ async function loadContextConfig(cwd) {
   try {
     raw = await promises.readFile(jsonPath, "utf8");
   } catch (cause) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Failed to read context config: ${jsonPath}`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Failed to read context config: ${jsonPath}`, {
       code: "context_read_error",
       cause
     });
@@ -4072,13 +4124,13 @@ function parseConfig(raw, configPath) {
   try {
     parsed = JSON.parse(raw);
   } catch (cause) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Invalid JSON in context config: ${configPath}`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Invalid JSON in context config: ${configPath}`, {
       code: "context_json_invalid",
       cause
     });
   }
   if (!parsed || typeof parsed !== "object") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Context config must be an object: ${configPath}`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Context config must be an object: ${configPath}`, {
       code: "context_config_shape"
     });
   }
@@ -4093,7 +4145,7 @@ function parseConfig(raw, configPath) {
 }
 function readSources(sourcesRaw, configPath) {
   if (!Array.isArray(sourcesRaw)) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Context config sources must be an array: ${configPath}`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Context config sources must be an array: ${configPath}`, {
       code: "context_sources_shape"
     });
   }
@@ -4118,7 +4170,6 @@ async function loadSources(config, cwd) {
       continue;
     }
     try {
-      await promises.stat(absolute);
       const content = await promises.readFile(absolute, "utf8");
       const tokens = tokenizeContent(content);
       results.push({ ...source, status: "included", tokens });
@@ -4191,7 +4242,7 @@ var PluginsManager = class {
   async refresh() {
     this.plugins = [];
     const pluginsRoot = path.join(this.cwd, ".theokit", "plugins");
-    const entries = await chunkSZHU7A5B_cjs.readWorkspaceDir(pluginsRoot, "plugins_read_error", "plugins directory");
+    const entries = await chunkIWBGCBR6_cjs.readWorkspaceDir(pluginsRoot, "plugins_read_error", "plugins directory");
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       const folderName = entry.name;
@@ -4199,13 +4250,13 @@ var PluginsManager = class {
       const jsonPath = path.join(pluginsRoot, folderName, "plugin.json");
       const metadata = fs.existsSync(mdPath) ? await loadPluginManifestFromMarkdown(pluginsRoot, folderName) : await loadPluginManifestFromJson(jsonPath, folderName);
       if (fs.existsSync(mdPath) && fs.existsSync(jsonPath)) {
-        chunk665SFFFR_cjs.warnOnce(
+        chunk53CBTBWO_cjs.warnOnce(
           `plugin-${folderName}-both`,
           `[theokit-sdk] both ${folderName}/PLUGIN.md and ${folderName}/plugin.json detected \u2014 using markdown; remove plugin.json`
         );
       }
       if (!fs.existsSync(mdPath) && fs.existsSync(jsonPath)) {
-        chunk665SFFFR_cjs.warnOnce(
+        chunk53CBTBWO_cjs.warnOnce(
           "plugin-json-deprecated",
           "[theokit-sdk] plugin.json manifests are deprecated; migrate to PLUGIN.md via theokit-migrate-config"
         );
@@ -4223,20 +4274,35 @@ var PluginsManager = class {
     const entry = metadata.entry;
     if (entry === void 0) return;
     const pluginRoot = path.join(this.cwd, ".theokit", "plugins", folderName);
-    const entryPath = chunkZT57WTUJ_cjs.safePathJoin(pluginRoot, entry);
+    const entryPath = chunkR3UPQFKK_cjs.safePathJoin(pluginRoot, entry);
     try {
       await promises.readFile(entryPath, "utf8");
     } catch (cause) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(`Plugin ${metadata.name} entry file is missing: ${entry}`, {
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(`Plugin ${metadata.name} entry file is missing: ${entry}`, {
         code: "plugin_entry_missing",
         cause
       });
     }
   }
+  /**
+   * B-107 measured this guard as unreachable and it was REMOVED on 2026-08-20. The pre-push gate
+   * caught the regression the same hour: `tests/contract/plugins.contract.test.ts:69` drives
+   * `Agent.create` with `cloud` plus `plugins.paths` and requires a `ConfigurationError`.
+   *
+   * The measurement that said "unreachable" was a `tsc` probe returning TS2353 — `plugins.paths` is
+   * not in the declared `AgentOptions`. That proves the option is undeclarable in TypeScript; it
+   * does NOT prove the value cannot arrive. The contract test casts through a `ProposedAgentOptions`
+   * shape it declares itself, which is exactly what a JavaScript caller, a JSON config or an `as`
+   * cast does. Runtime boundary validation exists for values types cannot stop
+   * (`rules/architecture.md` § 1) — so "the type system forbids it" is never on its own a reason to
+   * delete a boundary check.
+   *
+   * Do not remove this again without making `tests/contract/plugins.contract.test.ts` go red first.
+   */
   assertCloudRules() {
     if (!this.cloud) return;
     if (this.localPaths !== void 0 && this.localPaths.length > 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         "Cloud agents reject local plugin paths \u2014 plugins must come from committed repo files",
         { code: "cloud_plugin_path_rejected" }
       );
@@ -4248,7 +4314,7 @@ async function loadPluginManifestFromJson(manifestPath, folderName) {
   try {
     raw = await promises.readFile(manifestPath, "utf8");
   } catch (cause) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Plugin ${folderName} is missing plugin.json`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Plugin ${folderName} is missing plugin.json`, {
       code: "plugin_missing_manifest",
       cause
     });
@@ -4257,13 +4323,13 @@ async function loadPluginManifestFromJson(manifestPath, folderName) {
   try {
     parsed = JSON.parse(raw);
   } catch (cause) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Plugin ${folderName} manifest is invalid JSON`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Plugin ${folderName} manifest is invalid JSON`, {
       code: "plugin_manifest_invalid",
       cause
     });
   }
   if (!parsed || typeof parsed !== "object") {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Plugin ${folderName} manifest must be an object`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Plugin ${folderName} manifest must be an object`, {
       code: "plugin_manifest_shape"
     });
   }
@@ -4282,7 +4348,7 @@ async function loadPluginManifestFromMarkdown(pluginsRoot, folderName) {
   try {
     raw = await promises.readFile(mdPath, "utf8");
   } catch (cause) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Plugin ${folderName} is missing PLUGIN.md`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Plugin ${folderName} is missing PLUGIN.md`, {
       code: "plugin_missing_manifest",
       cause
     });
@@ -4297,7 +4363,7 @@ async function loadPluginManifestFromMarkdown(pluginsRoot, folderName) {
   });
   const entity = entities.find((e) => e.slug === "PLUGIN");
   if (entity === void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(`Plugin ${folderName} PLUGIN.md not parseable`, {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Plugin ${folderName} PLUGIN.md not parseable`, {
       code: "plugin_missing_manifest"
     });
   }
@@ -4571,7 +4637,7 @@ function assertValidThresholds(soft, hard) {
     ["hardThreshold", hard]
   ]) {
     if (!Number.isInteger(value) || value < 1) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `doomLoop.${label} must be a positive integer (received ${value}).`,
         { code: "invalid_doom_loop_threshold" }
       );
@@ -4794,8 +4860,10 @@ async function initLoopContext(inputs) {
       memoryProviderHandle = void 0;
     }
   }
-  const tools = await collectTools(inputs.mcp, inputs.runEventSink);
+  const withheld = new Set(inputs.withheldBuiltinTools ?? []);
+  const tools = await collectTools(inputs.mcp, withheld, inputs.runEventSink);
   for (const memTool of inputs.memoryTools ?? []) {
+    if (withheld.has(memTool.name)) continue;
     tools.push({
       name: memTool.name,
       description: memTool.description,
@@ -4821,6 +4889,7 @@ async function initLoopContext(inputs) {
       providerTools = [];
     }
     for (const providerTool of providerTools) {
+      if (withheld.has(providerTool.name)) continue;
       tools.push({
         name: providerTool.name,
         description: providerTool.description,
@@ -4880,18 +4949,25 @@ async function initLoopContext(inputs) {
 }
 async function safeListTools(client, serverName, sink) {
   try {
-    return await client.listTools();
+    const listed = await client.listTools();
+    chunkNGESVVJN_cjs.emitRunEvent(sink, {
+      type: "mcp_server_ready",
+      serverName: serverName ?? "unknown",
+      tools: listed.map((tool) => tool.name)
+    });
+    return listed;
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
     const server = serverName ?? "unknown";
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] mcp listTools failed (server=${server}): ${message}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] mcp listTools failed (server=${server}): ${message}
 `);
-    chunkXPR366DL_cjs.emitRunEvent(sink, { type: "mcp_server_failed", serverName: server, message });
+    chunkNGESVVJN_cjs.emitRunEvent(sink, { type: "mcp_server_failed", serverName: server, message });
     return [];
   }
 }
-async function collectTools(mcp, sink) {
-  const tools = [
+function shellToolDescriptor(withheld) {
+  if (withheld.has("shell")) return [];
+  return [
     {
       name: "shell",
       description: "Run a shell command in the workspace and return stdout/stderr.",
@@ -4903,6 +4979,9 @@ async function collectTools(mcp, sink) {
       origin: "shell"
     }
   ];
+}
+async function collectTools(mcp, withheld, sink) {
+  const tools = shellToolDescriptor(withheld);
   for (const [serverName, client] of mcp.entries()) {
     const mcpTools = await safeListTools(client, serverName, sink);
     for (const tool of mcpTools) {
@@ -4921,6 +5000,13 @@ async function collectTools(mcp, sink) {
 function sanitize(name) {
   return name.replace(/[^a-zA-Z0-9-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "");
 }
+var KEY_PREFIX = "theokit-";
+var KEY_HEX_LENGTH = 32;
+function derivePromptCacheKey(sessionId) {
+  if (sessionId === void 0 || sessionId.trim().length === 0) return void 0;
+  const digest = crypto.createHash("sha256").update(sessionId, "utf8").digest("hex");
+  return `${KEY_PREFIX}${digest.slice(0, KEY_HEX_LENGTH)}`;
+}
 
 // src/internal/tool-dispatch/strip-think.ts
 var THINK_PATTERN = /<think>[\s\S]*?<\/think>\s*/g;
@@ -4954,7 +5040,7 @@ function emitLlmMetrics(inputs, result, startAt) {
     inputs.telemetry?.recordHistogram(HISTOGRAM_NAMES.LLM_USAGE_MISSING, 1, {
       provider: inputs.llm.name
     });
-    chunkBM6N4KHO_cjs.diag(
+    chunkNUKRL3I6_cjs.diag(
       `[theokit-sdk] llm usage missing from ${inputs.llm.name} finish \u2014 budget may undercount
 `
     );
@@ -4992,6 +5078,16 @@ async function streamLlmTurn(inputs, ctx) {
       // Step-cap force-close: forward the per-run tool gate (`"none"` on a ceiling round forces a
       // text close even though tools are advertised). Absent ⇒ provider default (auto).
       ...inputs.toolChoice !== void 0 ? { toolChoice: inputs.toolChoice } : {},
+      // usetheokit/theokit-sdk#383 — the prompt-cache key, derived HERE and from `inputs.agentId`
+      // because this is the one place that sees the session identity on every round. `agentId` is
+      // the run's session identity (`Agent.getOrCreate(sessionId)`), so the derived key is identical
+      // on round 1 and round 12 of a turn, identical on turn 2 of the same session, and different
+      // for a different session. Deriving it per round from a stable input is what makes it a cache
+      // key; minting one anywhere that runs more than once per session would not be.
+      ...(() => {
+        const key = derivePromptCacheKey(inputs.agentId);
+        return key !== void 0 ? { promptCacheKey: key } : {};
+      })(),
       messages: ctx.messages,
       tools: ctx.tools.map(toLlmTool)
     },
@@ -5032,13 +5128,12 @@ async function streamLlmTurn(inputs, ctx) {
   };
 }
 async function collectLlmEvents(generator, inputs, ctx) {
-  let accumulatedText = "";
   let errored = false;
   let finishValue;
   let thinking;
+  const partial = { text: "" };
   try {
-    const result = await runCollectorLoop(generator, inputs, ctx);
-    accumulatedText = result.accumulatedText;
+    const result = await runCollectorLoop(generator, inputs, ctx, partial);
     errored = result.errored;
     finishValue = result.finishValue;
     thinking = result.thinking;
@@ -5048,10 +5143,12 @@ async function collectLlmEvents(generator, inputs, ctx) {
       ctx.events.push(buildAssistantEvent(inputs, "[aborted]"));
     } else {
       registerLoopError(ctx, cause);
-      ctx.finalText = "";
+      ctx.finalText = partial.text;
+      if (partial.text !== "") ctx.events.push(buildAssistantEvent(inputs, partial.text));
     }
     errored = true;
   }
+  const accumulatedText = partial.text;
   return {
     accumulatedText,
     errored,
@@ -5082,8 +5179,7 @@ async function consumeStreamEvent(inputs, reasoning, event) {
   }
   return "";
 }
-async function runCollectorLoop(generator, inputs, ctx) {
-  let accumulatedText = "";
+async function runCollectorLoop(generator, inputs, ctx, partial) {
   const reasoning = { text: "", startedAt: void 0, signature: void 0 };
   let errored = false;
   let finishValue;
@@ -5097,16 +5193,16 @@ async function runCollectorLoop(generator, inputs, ctx) {
       }
       if (next.value.type === "error") {
         registerLoopError(ctx, next.value);
-        ctx.finalText = "";
+        ctx.finalText = partial.text;
         errored = true;
         break;
       }
-      accumulatedText += await consumeStreamEvent(inputs, reasoning, next.value);
+      partial.text += await consumeStreamEvent(inputs, reasoning, next.value);
     }
   } finally {
     thinking = await finalizeReasoning(inputs, ctx, reasoning);
   }
-  return { accumulatedText, errored, finishValue, ...thinking !== void 0 ? { thinking } : {} };
+  return { errored, finishValue, ...thinking !== void 0 ? { thinking } : {} };
 }
 async function consumeReasoningDelta(inputs, reasoning, delta) {
   if (delta.signature !== void 0) reasoning.signature = delta.signature;
@@ -5250,7 +5346,7 @@ function coerceArgsToSchema(args, schema) {
 }
 
 // src/tool-error.ts
-var ToolError = class extends chunkLPVIRJVF_cjs.TheokitAgentError {
+var ToolError = class extends chunkK3FW2XZD_cjs.TheokitAgentError {
   name = "ToolError";
   /** The error content surfaced to the model: a string, or text/image blocks. */
   content;
@@ -5444,7 +5540,7 @@ function raceToolExecution(exec, opts) {
 // src/internal/agent-loop/tool-dispatch.ts
 async function dispatchTools(inputs, tools, toolCalls, events, parentSpan) {
   const maxConcurrent = inputs.maxConcurrentTools ?? 4;
-  return chunkWQ53UQL4_cjs.mapWithConcurrency(
+  return chunkILCGLTSA_cjs.mapWithConcurrency(
     toolCalls,
     maxConcurrent,
     (call) => dispatchSingleCall(inputs, tools, call, events, parentSpan)
@@ -5472,7 +5568,7 @@ async function dispatchSingleCall(inputs, tools, call, events, parentSpan) {
     toolSpan?.end();
     return fileVeto;
   }
-  chunkXPR366DL_cjs.emitRunEvent(inputs.runEventSink, {
+  chunkNGESVVJN_cjs.emitRunEvent(inputs.runEventSink, {
     type: "tool_progress",
     toolName: workingCall.name,
     toolCallId: callId
@@ -5503,7 +5599,7 @@ function applyRepairAndExtractCall(tools, call) {
 function vetoFromForkWhitelist(inputs, call, callId, events) {
   const whitelistDecision = chunkVJ26EKGJ_cjs.checkToolWhitelist(call.name);
   if (whitelistDecision.allowed) return void 0;
-  chunkXPR366DL_cjs.emitRunEvent(inputs.runEventSink, {
+  chunkNGESVVJN_cjs.emitRunEvent(inputs.runEventSink, {
     type: "permission_denied",
     toolName: call.name,
     toolCallId: callId,
@@ -5548,7 +5644,7 @@ async function vetoFromPluginPreHook(inputs, call, callId, events) {
     ...inputs.permissionMode !== void 0 ? { permissionMode: inputs.permissionMode } : {}
   });
   if (pluginVeto === void 0) return void 0;
-  chunkXPR366DL_cjs.emitRunEvent(inputs.runEventSink, {
+  chunkNGESVVJN_cjs.emitRunEvent(inputs.runEventSink, {
     type: "permission_denied",
     toolName: call.name,
     toolCallId: callId,
@@ -5577,7 +5673,7 @@ async function vetoFromFileHookPreDecision(inputs, call, callId, events) {
     runId: inputs.runId
   });
   if (!preDecision.blocked) return void 0;
-  chunkXPR366DL_cjs.emitRunEvent(inputs.runEventSink, {
+  chunkNGESVVJN_cjs.emitRunEvent(inputs.runEventSink, {
     type: "permission_denied",
     toolName: call.name,
     toolCallId: callId,
@@ -5678,7 +5774,7 @@ function finalizeSpanAndPostHook(inputs, call, callId, result, events, toolSpan)
     agentId: inputs.agentId,
     runId: inputs.runId
   }).catch((err) => {
-    chunkBM6N4KHO_cjs.diag(
+    chunkNUKRL3I6_cjs.diag(
       `[theokit-sdk] postToolUse hook error (swallowed): ${err instanceof Error ? err.message : String(err)}
 `
     );
@@ -5697,7 +5793,7 @@ async function emitToolLifecycleDelta(inputs, update) {
   try {
     await inputs.onDelta({ update });
   } catch (err) {
-    chunkBM6N4KHO_cjs.diag(
+    chunkNUKRL3I6_cjs.diag(
       `[theokit-sdk] onDelta tool-lifecycle emit error (swallowed): ${err instanceof Error ? err.message : String(err)}
 `
     );
@@ -5709,7 +5805,7 @@ async function safeEmitToolHook(callback, event) {
     await callback(event);
   } catch (cause) {
     const msg = cause instanceof Error ? cause.message : String(cause);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] tool lifecycle hook threw: ${msg}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] tool lifecycle hook threw: ${msg}
 `);
   }
 }
@@ -5776,7 +5872,7 @@ function applyToolResultGuard(parts, opts) {
     (p) => (
       // SE7 — guard the TEXT of a tool result (string or the text blocks of a
       // structured content); image blocks pass through untouched.
-      p.type === "tool_result" ? { ...p, content: chunk2FYEVT2B_cjs.renderToolResultContentText(p.content, (t) => guardText(t, opts)) } : p
+      p.type === "tool_result" ? { ...p, content: chunkHLPSLDGL_cjs.renderToolResultContentText(p.content, (t) => guardText(t, opts)) } : p
     )
   );
 }
@@ -5928,7 +6024,7 @@ function stripDateSuffix(model) {
   return model.replace(/-\d{4}-?\d{2}-?\d{2}$/, "");
 }
 function normalizeAnthropicDots(model) {
-  return model.replace(/(\d+)\.(\d+)/g, "$1-$2");
+  return model.replace(/(?<=\d)\.(?=\d)/g, "-");
 }
 function stripOpenRouterPrefix(modelId) {
   return modelId.startsWith("openrouter/") ? modelId.slice("openrouter/".length) : modelId;
@@ -5971,7 +6067,7 @@ function catalogCostFallback(provider, cleanedModel) {
   const candidates = [`${provider}/${cleanedModel}`, cleanedModel];
   if (stripped !== cleanedModel) candidates.push(`${provider}/${stripped}`, stripped);
   for (const key of candidates) {
-    const info = chunkVUKQL3L2_cjs.getCatalogModelInfo(key);
+    const info = chunkNIRE5CNO_cjs.getCatalogModelInfo(key);
     const cost = info?.cost;
     if (cost === void 0) continue;
     const [prov, ...modelParts] = key.split("/");
@@ -5983,7 +6079,7 @@ function catalogCostFallback(provider, cleanedModel) {
       ...cost.cache_read !== void 0 ? { cacheReadCostPerMillion: cost.cache_read } : {},
       ...cost.cache_write !== void 0 ? { cacheWriteCostPerMillion: cost.cache_write } : {},
       // M44 M5 fix — honest provenance: a key patched by the LIVE models-dev source is not "vendored".
-      pricingVersion: chunkVUKQL3L2_cjs.isPatchedModelKey(key) ? "catalog-models-dev" : "catalog-vendored"
+      pricingVersion: chunkNIRE5CNO_cjs.isPatchedModelKey(key) ? "catalog-models-dev" : "catalog-vendored"
     };
   }
   return void 0;
@@ -6109,7 +6205,7 @@ function accumulateUsage(usage, turn) {
 function computeUsageCost(inputs, usage) {
   const modelId = inputs.model.id;
   if (modelId === void 0 || modelId === "auto") return void 0;
-  const parsed = chunkVYHJZVL5_cjs.parseModelId(modelId);
+  const parsed = chunk3EE6LVWT_cjs.parseModelId(modelId);
   const provider = parsed.provider ?? inputs.llm.name;
   const model = parsed.provider !== void 0 ? parsed.name : modelId;
   return computeCost({ provider, model, usage });
@@ -6181,6 +6277,12 @@ async function runAgentLoop(inputs) {
     }
     if (budget.shouldContinue() === false && ctx.finalStatus === "finished" && ctx.finalText === "") {
       ctx.finalStatus = "error";
+      if (ctx.error === void 0) {
+        ctx.error = {
+          message: `Run stopped after ${budget.total} iteration(s) without producing a reply \u2014 the model was still calling tools when the budget ran out. Raise \`SendOptions.maxIterations\` (default 8), or inspect \`RunResult.stoppedAtIterationLimit\` to continue the run.`,
+          code: "iteration_limit_reached"
+        };
+      }
     }
     sendSpan?.setAttribute("status", ctx.finalStatus);
     if (ctx.stoppedByDoomLoop === true) sendSpan?.setAttribute("stoppedByDoomLoop", true);
@@ -6436,15 +6538,15 @@ var FallbackLlmClient = class {
     let lastError;
     for (const client of this.clients) {
       if (signal.aborted) throw abortError(signal);
-      const attempt = await chunk2FYEVT2B_cjs.tryFirstEvent(client, request, signal, true);
+      const attempt = await chunkHLPSLDGL_cjs.tryFirstEvent(client, request, signal, true);
       if (attempt.kind === "handshake_error") {
         lastError = attempt.error;
         continue;
       }
-      return yield* chunk2FYEVT2B_cjs.relayStream(attempt.generator, attempt.firstResult);
+      return yield* chunkHLPSLDGL_cjs.relayStream(attempt.generator, attempt.firstResult);
     }
     if (lastError !== void 0) throw lastError;
-    throw new chunkLPVIRJVF_cjs.NetworkError("FallbackLlmClient has no providers configured", {
+    throw new chunkK3FW2XZD_cjs.NetworkError("FallbackLlmClient has no providers configured", {
       code: "fallback_empty_chain"
     });
   }
@@ -6467,7 +6569,7 @@ function reconnectDelay(attempt) {
   return ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
 }
 function mcpTimeoutError(name, timeoutMs) {
-  return new chunkLPVIRJVF_cjs.NetworkError(`MCP ${name} request timed out after ${timeoutMs}ms`, {
+  return new chunkK3FW2XZD_cjs.NetworkError(`MCP ${name} request timed out after ${timeoutMs}ms`, {
     code: "mcp_timeout"
   });
 }
@@ -6550,7 +6652,7 @@ var StdioMcpClient = class extends BaseMcpClient {
     child.stdin.on("error", () => void 0);
     child.on("error", () => {
       this.rejectAllPending(
-        new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} process crashed`, { code: "mcp_crashed" })
+        new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} process crashed`, { code: "mcp_crashed" })
       );
     });
     child.on("exit", () => {
@@ -6558,7 +6660,7 @@ var StdioMcpClient = class extends BaseMcpClient {
       this.child = void 0;
       this.dropped = true;
       this.rejectAllPending(
-        new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} disconnected`, { code: "mcp_disconnected" })
+        new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} disconnected`, { code: "mcp_disconnected" })
       );
     });
   }
@@ -6586,7 +6688,7 @@ var StdioMcpClient = class extends BaseMcpClient {
     if (this.child !== void 0) return Promise.resolve();
     if (!this.dropped) {
       return Promise.reject(
-        new chunkLPVIRJVF_cjs.ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
+        new chunkK3FW2XZD_cjs.ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
       );
     }
     this.reconnectPromise ??= this.reconnect().finally(() => {
@@ -6607,13 +6709,13 @@ var StdioMcpClient = class extends BaseMcpClient {
         lastErr = err;
       }
     }
-    throw new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} reconnect exhausted`, {
+    throw new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} reconnect exhausted`, {
       code: "mcp_disconnected",
       ...lastErr instanceof Error ? { cause: lastErr } : {}
     });
   }
   async close() {
-    this.rejectAllPending(new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} closed`, { code: "mcp_closed" }));
+    this.rejectAllPending(new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} closed`, { code: "mcp_closed" }));
     const child = this.child;
     this.child = void 0;
     this.dropped = false;
@@ -6632,7 +6734,7 @@ var StdioMcpClient = class extends BaseMcpClient {
     if (this.buffer.length > MAX_STDIO_BUFFER_BYTES) {
       this.buffer = "";
       this.rejectAllPending(
-        new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} exceeded stdout buffer limit`, {
+        new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} exceeded stdout buffer limit`, {
           code: "mcp_buffer_overflow"
         })
       );
@@ -6667,7 +6769,7 @@ var StdioMcpClient = class extends BaseMcpClient {
     if (child !== void 0) return this.send(child, method, params);
     if (this.dropped) return this.reconnectAndRequest(method, params);
     return Promise.reject(
-      new chunkLPVIRJVF_cjs.ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
+      new chunkK3FW2XZD_cjs.ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" })
     );
   }
   /** M2 #59 — reconnect a dropped client, then send. Separate async path so the
@@ -6676,7 +6778,7 @@ var StdioMcpClient = class extends BaseMcpClient {
     await this.ensureConnected();
     const child = this.child;
     if (child === void 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" });
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(`MCP ${this.name} is not initialized`, { code: "mcp_not_init" });
     }
     return this.send(child, method, params);
   }
@@ -6693,7 +6795,7 @@ var StdioMcpClient = class extends BaseMcpClient {
         this.child = void 0;
         this.dropped = true;
         this.rejectAllPending(
-          new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} disconnected`, { code: "mcp_disconnected" })
+          new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} disconnected`, { code: "mcp_disconnected" })
         );
       }, this.timeoutMs);
       this.pending.set(id, { resolve, reject, timer });
@@ -6744,12 +6846,6 @@ var HttpMcpClient = class extends BaseMcpClient {
       ...this.config.headers ?? {}
     };
   }
-  /**
-   * Capture the session on the FIRST response that carries it (the `initialize`).
-   *
-   * Never overwritten by a later one: a server that re-issues mid-session would otherwise split
-   * the session in two, and the second half would not see the first half's state.
-   */
   /**
    * Read one JSON-RPC response, in either encoding the server may choose.
    *
@@ -6771,10 +6867,16 @@ var HttpMcpClient = class extends BaseMcpClient {
       if (payload === "") continue;
       return JSON.parse(payload);
     }
-    throw new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} returned an event stream with no data payload`, {
+    throw new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} returned an event stream with no data payload`, {
       code: "mcp_http_error"
     });
   }
+  /**
+   * Capture the session on the FIRST response that carries it (the `initialize`).
+   *
+   * Never overwritten by a later one: a server that re-issues mid-session would otherwise split
+   * the session in two, and the second half would not see the first half's state.
+   */
   captureSession(response) {
     if (this.sessionId !== void 0) return;
     const issued = response.headers.get("mcp-session-id");
@@ -6799,7 +6901,7 @@ var HttpMcpClient = class extends BaseMcpClient {
       throw cause;
     }
     if (!response.ok) {
-      throw new chunkLPVIRJVF_cjs.NetworkError(`MCP ${this.name} returned ${response.status}`, {
+      throw new chunkK3FW2XZD_cjs.NetworkError(`MCP ${this.name} returned ${response.status}`, {
         code: "mcp_http_error"
       });
     }
@@ -6815,14 +6917,14 @@ var HttpMcpClient = class extends BaseMcpClient {
 function resolveMcpCwd(configCwd) {
   if (configCwd === void 0) return process.cwd();
   if (path.isAbsolute(configCwd)) return configCwd;
-  return chunkZT57WTUJ_cjs.safePathJoin(process.cwd(), configCwd);
+  return chunkR3UPQFKK_cjs.safePathJoin(process.cwd(), configCwd);
 }
 
 // src/internal/providers/register-plugin-providers.ts
 function registerPluginProviderProfiles(entries) {
   let registered2 = 0;
   for (const entry of entries) {
-    chunkVUKQL3L2_cjs.registerProvider(entry.profile);
+    chunkNIRE5CNO_cjs.registerProvider(entry.profile);
     registered2 += 1;
   }
   return registered2;
@@ -6902,7 +7004,7 @@ function applyPersonalityFilter(exposedTools, whitelist, opts) {
     if (exposedSet.has(name)) continue;
     const hint = suggestClosest(name, exposedSet);
     const message = hint !== void 0 ? `[theokit-sdk] personality "${opts?.personalityName ?? "?"}" references unknown tool "${name}"; did you mean "${hint}"?` : `[theokit-sdk] personality "${opts?.personalityName ?? "?"}" references unknown tool "${name}" (not exposed)`;
-    chunk665SFFFR_cjs.warnOnce(
+    chunk53CBTBWO_cjs.warnOnce(
       `personality-tool-missing|${opts?.agentId ?? "?"}|${opts?.personalityName ?? "?"}|${name}`,
       message
     );
@@ -6944,7 +7046,7 @@ function levenshtein(a, b) {
 // src/internal/local-agent/real-local-run-tools.ts
 function declarativeSubagentTools(agents2, parentTools) {
   if (agents2 === void 0 || Object.keys(agents2).length === 0) return [];
-  return chunkB4YA6BRS_cjs.subAgentToolsFromDefinitions(agents2, parentTools);
+  return chunk4O5TGQBW_cjs.subAgentToolsFromDefinitions(agents2, parentTools);
 }
 function resolveInheritedCredentials(agentOptions) {
   const parentPlugins = Array.isArray(agentOptions.plugins) ? agentOptions.plugins : void 0;
@@ -6956,14 +7058,20 @@ function resolveInheritedCredentials(agentOptions) {
     ...parentSandbox !== void 0 ? { sandbox: parentSandbox } : {}
   };
 }
-function buildCustomToolsInput(agentOptions, sendOptions, pluginManager, personalityToolWhitelist, agentId, personalityName, subagents, effectiveModel) {
+function withheldBuiltinsInput(agentOptions) {
+  const withheld = agentOptions.withheldBuiltinTools;
+  if (withheld === void 0 || withheld.length === 0) return {};
+  return { withheldBuiltinTools: withheld };
+}
+function buildRunToolCatalogInput(agentOptions, sendOptions, pluginManager, personalityToolWhitelist, agentId, personalityName, subagents, effectiveModel) {
+  const builtins = withheldBuiltinsInput(agentOptions);
   const baseTools = sendOptions?.tools ?? agentOptions.tools ?? [];
   const agentsForTools = subagents !== void 0 && Object.keys(subagents).length > 0 ? subagents : agentOptions.agents;
   const subagentTools = declarativeSubagentTools(agentsForTools, baseTools);
   const pluginTools = pluginManager?.aggregated.tools ?? [];
   const reasoningTools = reasoningActive(agentOptions.reasoning, effectiveModel) ? [createThinkTool()] : [];
   if (baseTools.length === 0 && subagentTools.length === 0 && pluginTools.length === 0 && reasoningTools.length === 0) {
-    return {};
+    return builtins;
   }
   const allTools = [...baseTools, ...subagentTools, ...pluginTools, ...reasoningTools];
   const merged = allTools.map((tool) => ({
@@ -6976,8 +7084,8 @@ function buildCustomToolsInput(agentOptions, sendOptions, pluginManager, persona
     agentId,
     personalityName
   });
-  if (customTools.length === 0 && personalityToolWhitelist === void 0) return {};
-  return { customTools };
+  if (customTools.length === 0 && personalityToolWhitelist === void 0) return builtins;
+  return { customTools, ...builtins };
 }
 
 // src/internal/local-agent/real-local-run.ts
@@ -7011,25 +7119,26 @@ function createRealLocalRun(options) {
 }
 var pluginProvidersAnnounced = false;
 function resolveRunProvider(options) {
-  chunkVUKQL3L2_cjs.registerBuiltins();
+  chunkNIRE5CNO_cjs.registerBuiltins();
   const profiles = options.pluginManager?.aggregated.providerProfiles ?? [];
   const registered2 = registerPluginProviderProfiles(profiles);
   if (registered2 > 0 && !pluginProvidersAnnounced) {
     pluginProvidersAnnounced = true;
     const names = profiles.map((e) => e.profile.name).join(", ");
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] registered ${registered2} plugin provider profile(s): ${names}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] registered ${registered2} plugin provider profile(s): ${names}
 `);
   }
-  const parsedModel = chunkVYHJZVL5_cjs.parseModelId(options.model?.id);
-  const modelInferredProvider = parsedModel.provider !== void 0 && chunkVUKQL3L2_cjs.getProviderProfile(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
-  const keyInferredProvider = chunk2FYEVT2B_cjs.inferProviderFromApiKey(options.agentOptions.apiKey);
-  const primary = options.agentOptions.providers?.routes?.[0]?.provider ?? keyInferredProvider ?? modelInferredProvider ?? chunk2FYEVT2B_cjs.detectPrimaryProvider();
+  const parsedModel = chunk3EE6LVWT_cjs.parseModelId(options.model?.id);
+  const modelInferredProvider = parsedModel.provider !== void 0 && chunkNIRE5CNO_cjs.getProviderProfile(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
+  const keyInferredProvider = chunkHLPSLDGL_cjs.inferProviderFromApiKey(options.agentOptions.apiKey);
+  const primary = options.agentOptions.providers?.routes?.[0]?.provider ?? keyInferredProvider ?? modelInferredProvider ?? chunkHLPSLDGL_cjs.detectPrimaryProvider();
+  chunkHLPSLDGL_cjs.warnProviderPrecedenceOnce(modelInferredProvider, primary);
   const effectiveModelId = modelInferredProvider !== void 0 && modelInferredProvider === primary ? parsedModel.name : options.model?.id ?? "claude-sonnet-4-6";
   return { primary, effectiveModelId };
 }
 function mergeExplicitApiKey(pools, primary, apiKey) {
   if (apiKey === void 0 || apiKey.length === 0) return pools;
-  if (chunk2FYEVT2B_cjs.isFixtureApiKey(apiKey) || apiKey === LOCAL_RUNTIME_MOCK_KEY) return pools;
+  if (chunkHLPSLDGL_cjs.isFixtureApiKey(apiKey) || apiKey === LOCAL_RUNTIME_MOCK_KEY) return pools;
   const existing = pools?.[primary];
   if (existing !== void 0 && existing.length > 0) return pools;
   return { ...pools ?? {}, [primary]: [apiKey] };
@@ -7037,7 +7146,7 @@ function mergeExplicitApiKey(pools, primary, apiKey) {
 function buildLoopInputs(options, runId, userText, userImages) {
   const maxIterations = options.sendOptions.maxIterations;
   if (maxIterations !== void 0 && (!Number.isInteger(maxIterations) || maxIterations < 1)) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `SendOptions.maxIterations must be a positive integer, got ${maxIterations}`,
       { code: "invalid_max_iterations" }
     );
@@ -7052,14 +7161,16 @@ function buildLoopInputs(options, runId, userText, userImages) {
   const credentialPoolStrategy = options.agentOptions.providers?.credentialPoolStrategy;
   const extractToolCallsFromContent = options.agentOptions.providers?.routes?.[0]?.extractToolCallsFromContent;
   const rateLimitSink = options.sendOptions.onRunEvent;
-  const chain = chunk2FYEVT2B_cjs.resolveProviderChain({
+  const modelBaseUrl = options.model?.url;
+  const chain = chunkHLPSLDGL_cjs.resolveProviderChain({
     primary,
+    ...modelBaseUrl !== void 0 ? { baseUrl: modelBaseUrl } : {},
     ...fallback !== void 0 ? { fallback } : {},
     ...apiKeys !== void 0 ? { apiKeys } : {},
     ...credentialPoolStrategy !== void 0 ? { credentialPoolStrategy } : {},
     ...extractToolCallsFromContent === true ? { extractToolCallsFromContent: true } : {},
     ...rateLimitSink !== void 0 ? {
-      onRateLimit: (info) => chunkXPR366DL_cjs.emitRunEvent(rateLimitSink, { type: "rate_limit", ...info })
+      onRateLimit: (info) => chunkNGESVVJN_cjs.emitRunEvent(rateLimitSink, { type: "rate_limit", ...info })
     } : {}
   });
   const llm = chain.length === 1 ? chain[0] : new FallbackLlmClient(chain);
@@ -7090,7 +7201,7 @@ function buildLoopInputs(options, runId, userText, userImages) {
     } : {},
     ...options.priorMessages !== void 0 ? { priorMessages: options.priorMessages } : {},
     ...options.memoryTools !== void 0 && options.memoryTools.length > 0 ? { memoryTools: options.memoryTools } : {},
-    ...buildCustomToolsInput(
+    ...buildRunToolCatalogInput(
       options.agentOptions,
       options.sendOptions,
       options.pluginManager,
@@ -7241,7 +7352,7 @@ var RealLocalRun = class extends FixtureRunBase {
     };
     try {
       const runLoop = () => inputs.activeTools !== void 0 ? chunkVJ26EKGJ_cjs.withToolWhitelist(new Set(inputs.activeTools), () => runAgentLoop(inputs)) : runAgentLoop(inputs);
-      const output = await chunkB4YA6BRS_cjs.withInheritedSubAgentCredentials(this.inheritedCredentials, runLoop);
+      const output = await chunk4O5TGQBW_cjs.withInheritedSubAgentCredentials(this.inheritedCredentials, runLoop);
       this.applyAgentLoopOutput(output);
       this.transitionTo(output.finalStatus);
     } catch (cause) {
@@ -7334,7 +7445,7 @@ function buildRealRunOptions(args) {
   };
 }
 async function createFixtureRunHelper(args) {
-  const sessionMessages = chunk2D43RD5D_cjs.getSessionMessages(args.inputs.agentId);
+  const sessionMessages = chunkV2UUGUY4_cjs.getSessionMessages(args.inputs.agentId);
   const projectMcpServers = args.inputs.settingSourcesIncludeProject ? await readProjectMcpServers(args.inputs.workspaceCwd) : {};
   return createLocalRun({
     agentId: args.inputs.agentId,
@@ -7352,8 +7463,8 @@ async function createFixtureRunHelper(args) {
   });
 }
 async function dispatchLocalRun(args) {
-  const apiKey = chunkBM6N4KHO_cjs.resolveApiKey(args.inputs.options.apiKey);
-  if (chunk2FYEVT2B_cjs.shouldUseRealLocalRuntime(apiKey)) {
+  const apiKey = chunkJTB5Q42C_cjs.resolveApiKey(args.inputs.options.apiKey);
+  if (chunkHLPSLDGL_cjs.shouldUseRealLocalRuntime(apiKey)) {
     return createRealLocalRun(
       buildRealRunOptions({
         inputs: args.inputs,
@@ -7388,20 +7499,20 @@ async function readProjectMcpServers(cwd) {
 
 // src/internal/local-agent/local-agent-invalidate.ts
 async function applyDeferredInvalidation(agentId, pending, refresh) {
-  chunkBM6N4KHO_cjs.diag(`[theokit-sdk] applying deferred cache invalidation (${agentId}): ${pending.reason}
+  chunkNUKRL3I6_cjs.diag(`[theokit-sdk] applying deferred cache invalidation (${agentId}): ${pending.reason}
 `);
   try {
     await refresh();
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] invalidateCache reload failed (continuing): ${msg}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] invalidateCache reload failed (continuing): ${msg}
 `);
   }
 }
 async function invalidateCacheImpl(agentId, reason, options, disposed, dispose, setPending) {
   if (disposed) return;
   if (options.applyNow === true) {
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] invalidateCache applyNow disposing agent (${agentId}): ${reason}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] invalidateCache applyNow disposing agent (${agentId}): ${reason}
 `);
     await dispose();
     return;
@@ -7462,7 +7573,7 @@ var LiveAgentRegistry = class {
     const existing = this.#agents.get(id);
     if (existing !== void 0 && existing.agent !== agent) {
       void existing.agent.dispose().catch(() => {
-        chunkBM6N4KHO_cjs.diag(`[theokit-sdk] dispose during overwrite failed (${id})
+        chunkNUKRL3I6_cjs.diag(`[theokit-sdk] dispose during overwrite failed (${id})
 `);
       });
     }
@@ -7566,7 +7677,7 @@ var LiveAgentRegistry = class {
       await agent.dispose();
     } catch (cause) {
       const msg = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] dispose during eviction failed (${id}): ${msg}
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] dispose during eviction failed (${id}): ${msg}
 `);
     }
     if (this.#onEvict !== void 0) {
@@ -7574,7 +7685,7 @@ var LiveAgentRegistry = class {
         this.#onEvict(id, reason);
       } catch (cause) {
         const msg = cause instanceof Error ? cause.message : String(cause);
-        chunkBM6N4KHO_cjs.diag(`[theokit-sdk] onEvict listener threw (${id}): ${msg}
+        chunkNUKRL3I6_cjs.diag(`[theokit-sdk] onEvict listener threw (${id}): ${msg}
 `);
       }
     }
@@ -7590,7 +7701,7 @@ async function acquireLeaseIfPossible(store, agentId) {
     await a.call(store, agentId);
   } catch (err) {
     if (err instanceof Error && err.name === "SessionBusyError") throw err;
-    chunkBM6N4KHO_cjs.diag(
+    chunkNUKRL3I6_cjs.diag(
       `[theokit-sdk] writer lease unavailable for ${agentId} (${err instanceof Error ? err.message : String(err)}) \u2014 proceeding without single-writer protection
 `
     );
@@ -7607,18 +7718,18 @@ async function disposeSessionStore(store) {
 async function disposeLocalAgentSession(agent) {
   liveAgentRegistry.forget(agent.agentId);
   agent.lifecycleAbortController.abort();
-  await chunkYLQQX5W2_cjs.withCwdMutex(`agent-send:${agent.agentId}`, () => Promise.resolve());
+  await chunkZF2LDKQQ_cjs.withCwdMutex(`agent-send:${agent.agentId}`, () => Promise.resolve());
   disposeSessionMcpClients(agent.agentId);
-  await chunk2D43RD5D_cjs.flushSessionWrites();
+  await chunkV2UUGUY4_cjs.flushSessionWrites();
   await flushRegistrySaves(agent.workspaceCwd);
   await disposeSessionStore(agent.sessionStore);
-  chunk2D43RD5D_cjs.discardSession(agent.workspaceCwd, agent.agentId);
+  chunkV2UUGUY4_cjs.discardSession(agent.workspaceCwd, agent.agentId);
 }
 async function reloadLocalAgent(agent) {
   if (agent.context !== void 0) await agent.context.refresh();
   if (agent.skillsManager !== void 0) await agent.skillsManager.refresh();
   if (agent.pluginsManager !== void 0) await agent.pluginsManager.refresh();
-  return await chunkE7FJOO4G_cjs.loadSubagents(
+  return await chunkHJBMA5MB_cjs.loadSubagents(
     agent.workspaceCwd,
     agent.settingSourcesIncludeProject,
     agent.options.agents
@@ -7626,12 +7737,12 @@ async function reloadLocalAgent(agent) {
 }
 async function persistActiveMemoryTranscript(cwd, transcript) {
   try {
-    const dir = path.join(chunkBDTVFIPB_cjs.memoryDir(cwd), "transcripts", "active-memory");
+    const dir = path.join(chunk5UOVYM3P_cjs.memoryDir(cwd), "transcripts", "active-memory");
     const file = path.join(dir, `${transcript.runId}.json`);
-    await chunkC4H6PB5J_cjs.atomicWriteJson(file, transcript);
+    await chunkI6TGFUCO_cjs.atomicWriteJson(file, transcript);
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] active-memory transcript persist failed: ${message}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] active-memory transcript persist failed: ${message}
 `);
   }
 }
@@ -7752,7 +7863,7 @@ async function searchOnce(args, cfg, query, started) {
     return { summary, durationMs: Date.now() - started, status: "ok", hits };
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
-    chunkBM6N4KHO_cjs.diag(`[theokit-sdk] active-memory recall failed: ${message}
+    chunkNUKRL3I6_cjs.diag(`[theokit-sdk] active-memory recall failed: ${message}
 `);
     return { summary: void 0, durationMs: Date.now() - started, status: "error", hits: [] };
   }
@@ -7872,7 +7983,7 @@ var azureOpenAiMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "azure-openai",
   autoSelectPriority: 25,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "azure-openai",
       defaultBaseUrl: "https://your-resource.openai.azure.com",
@@ -7908,7 +8019,7 @@ var cohereMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "cohere",
   autoSelectPriority: 30,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "cohere",
       defaultBaseUrl: "https://api.cohere.com",
@@ -7954,7 +8065,7 @@ var deepinfraMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "deepinfra",
   autoSelectPriority: 13,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "deepinfra",
       defaultBaseUrl: "https://api.deepinfra.com",
@@ -7980,7 +8091,7 @@ var geminiMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "gemini",
   autoSelectPriority: 30,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "gemini",
       defaultBaseUrl: "https://generativelanguage.googleapis.com",
@@ -8008,7 +8119,7 @@ var jinaMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "jina",
   autoSelectPriority: 35,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "jina",
       defaultBaseUrl: "https://api.jina.ai",
@@ -8031,7 +8142,7 @@ var mistralMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "mistral",
   autoSelectPriority: 18,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "mistral",
       defaultBaseUrl: "https://api.mistral.ai",
@@ -8073,7 +8184,7 @@ var ollamaMemoryEmbeddingProviderAdapter = {
   autoSelectPriority: 10,
   create: (options) => {
     const apiKey = options.apiKey ?? process.env.OLLAMA_API_KEY ?? OLLAMA_LOCAL_SENTINEL_KEY;
-    return chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+    return chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
       {
         id: "ollama",
         defaultBaseUrl: "http://localhost:11434",
@@ -8100,7 +8211,7 @@ var openAiMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "openai",
   autoSelectPriority: 20,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "openai",
       defaultBaseUrl: "https://api.openai.com",
@@ -8127,7 +8238,7 @@ var openRouterMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "openrouter",
   autoSelectPriority: 15,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "openrouter",
       defaultBaseUrl: "https://openrouter.ai/api",
@@ -8155,7 +8266,7 @@ var voyageMemoryEmbeddingProviderAdapter = {
   transport: "remote",
   authProviderId: "voyage",
   autoSelectPriority: 14,
-  create: (options) => chunkRAHSWE5C_cjs.createOpenAiCompatibleRuntime(
+  create: (options) => chunkEI2Q7SJ5_cjs.createOpenAiCompatibleRuntime(
     {
       id: "voyage",
       defaultBaseUrl: "https://api.voyageai.com",
@@ -8256,7 +8367,7 @@ function createMemorySearchTool(opts) {
   };
 }
 function createMemoryGetTool(opts) {
-  const memoryRoot = path.resolve(chunkBDTVFIPB_cjs.memoryDir(opts.cwd));
+  const memoryRoot = path.resolve(chunk5UOVYM3P_cjs.memoryDir(opts.cwd));
   return {
     name: "memory_get",
     description: GET_DESCRIPTION,
@@ -8267,7 +8378,7 @@ function createMemoryGetTool(opts) {
       const lines = readNumber(input.lines);
       const resolved = path.resolve(memoryRoot, relPath);
       if (!isPathInside(memoryRoot, resolved)) {
-        throw new chunkLPVIRJVF_cjs.ConfigurationError(
+        throw new chunkK3FW2XZD_cjs.ConfigurationError(
           `memory_get rejected path that escapes memory root: ${relPath}`,
           { code: "memory_path_escapes_root" }
         );
@@ -8287,7 +8398,7 @@ function readString(value, errorIfMissing, allowUndefined = false) {
   if (typeof value === "string") return value;
   if (allowUndefined && (value === void 0 || value === null)) return "";
   if (errorIfMissing !== void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(errorIfMissing, { code: "memory_tool_bad_args" });
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(errorIfMissing, { code: "memory_tool_bad_args" });
   }
   return "";
 }
@@ -8362,7 +8473,7 @@ var LocalAgentMemory = class {
       const openOpts = { cwd: this.workspaceCwd };
       if (embedding !== void 0) openOpts.embedding = embedding;
       if (cfg?.backend !== void 0) openOpts.backend = cfg.backend;
-      this.index = await chunkBDTVFIPB_cjs.IndexManager.open(openOpts);
+      this.index = await chunk5UOVYM3P_cjs.IndexManager.open(openOpts);
       await this.index.sync();
       this.toolsCache = [
         createMemorySearchTool({ index: this.index }),
@@ -8377,7 +8488,7 @@ var LocalAgentMemory = class {
       const warned2 = g[sym];
       if (!warned2.has(message)) {
         warned2.add(message);
-        chunkBM6N4KHO_cjs.diag(`[theokit-sdk] memory tools unavailable: ${message}
+        chunkNUKRL3I6_cjs.diag(`[theokit-sdk] memory tools unavailable: ${message}
 `);
       }
       return void 0;
@@ -8386,7 +8497,7 @@ var LocalAgentMemory = class {
   async runActiveMemoryIfEnabled(userText, priorMessages, telemetry) {
     const cfg = this.options.memory?.activeRecall;
     if (cfg?.enabled !== true || this.index === void 0) return void 0;
-    if (this.breaker === void 0) this.breaker = new chunk2FYEVT2B_cjs.CircuitBreaker();
+    if (this.breaker === void 0) this.breaker = new chunkHLPSLDGL_cjs.CircuitBreaker();
     if (this.cache === void 0) this.cache = new ActiveMemoryCache();
     const result = await runActiveMemory({
       userText,
@@ -8436,7 +8547,7 @@ var LocalAgentMemory = class {
       await this.index.sync();
     } catch (cause) {
       const message = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] session index sync failed: ${message}
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] session index sync failed: ${message}
 `);
     }
   }
@@ -8449,7 +8560,7 @@ var LocalAgentMemory = class {
       return await adapter.create(cfg.model !== void 0 ? { model: cfg.model } : {});
     } catch (cause) {
       const message = cause instanceof Error ? cause.message : String(cause);
-      chunkBM6N4KHO_cjs.diag(`[theokit-sdk] memory embedding ${cfg.provider} unavailable: ${message}
+      chunkNUKRL3I6_cjs.diag(`[theokit-sdk] memory embedding ${cfg.provider} unavailable: ${message}
 `);
       return void 0;
     }
@@ -8457,22 +8568,33 @@ var LocalAgentMemory = class {
 };
 
 // src/internal/local-agent/local-agent-memory-direct.ts
+async function createAvailableAdapters(entries, workspaceCwd) {
+  const available = [];
+  for (const entry of entries) {
+    const instance = await entry.createProvider(workspaceCwd);
+    if (instance.isAvailable() === false) {
+      chunkNUKRL3I6_cjs.diag(
+        `[theokit-sdk] memory adapter "${instance.id}" reports itself unavailable (plugin "${entry.pluginName}") \u2014 skipping it. Check its credentials.
+`
+      );
+      continue;
+    }
+    available.push(instance);
+  }
+  return available;
+}
 function buildAgentMemory(pluginManager, workspaceCwd, defaultContext) {
   let resolved;
   async function ensure() {
     if (resolved !== void 0) return resolved;
     const entries = pluginManager.aggregated.memoryProviders;
-    const created = [];
-    for (const entry of entries) {
-      const instance = await entry.createProvider(workspaceCwd);
-      created.push(instance);
-    }
+    const created = await createAvailableAdapters(entries, workspaceCwd);
     for (const adapter of created) {
       if (adapter.initialize !== void 0) {
         await adapter.initialize();
       }
     }
-    resolved = { adapters: created, initialized: true };
+    resolved = { adapters: created, initialized: true, registered: entries.length };
     return resolved;
   }
   function mergeContext(partial) {
@@ -8485,7 +8607,7 @@ function buildAgentMemory(pluginManager, workspaceCwd, defaultContext) {
       ...partial?.metadata !== void 0 ? { metadata: partial.metadata } : defaultContext?.metadata !== void 0 ? { metadata: defaultContext.metadata } : {}
     };
     if (merged.userId === "") {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         "agent.memory requires a userId \u2014 either set AgentOptions.memoryContext.userId or pass ctx.userId at call time.",
         { code: "memory_context_missing_user_id" }
       );
@@ -8495,8 +8617,8 @@ function buildAgentMemory(pluginManager, workspaceCwd, defaultContext) {
   async function requireAdapters() {
     const r = await ensure();
     if (r.adapters.length === 0) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
-        "No memory adapter registered. Pass a memory plugin in AgentOptions.plugins (e.g. supermemoryMemory({...})).",
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
+        r.registered === 0 ? "No memory adapter registered. Pass a memory plugin in AgentOptions.plugins (e.g. supermemoryMemory({...}))." : `All ${r.registered} registered memory adapter(s) reported themselves unavailable \u2014 see the warnings naming each one. Check their credentials.`,
         { code: "no_memory_adapter" }
       );
     }
@@ -8536,7 +8658,7 @@ function buildAgentMemory(pluginManager, workspaceCwd, defaultContext) {
       const prefix = id.split(":", 1)[0] ?? "";
       const target = adapters.find((a) => a.id === prefix);
       if (target === void 0) {
-        throw new chunkLPVIRJVF_cjs.ConfigurationError(
+        throw new chunkK3FW2XZD_cjs.ConfigurationError(
           `No adapter found for MemoryId prefix "${prefix}" (registered: ${adapters.map((a) => a.id).join(", ")}).`,
           { code: "no_memory_adapter" }
         );
@@ -8609,7 +8731,7 @@ function createLocalAgentMemoryProvider(opts) {
       return { facts: [], systemPromptAdditions: summary };
     },
     async recordSessionSummary(args) {
-      await chunkBDTVFIPB_cjs.writeSessionSummary(args);
+      await chunk5UOVYM3P_cjs.writeSessionSummary(args);
     },
     async sync(handle) {
       const state = handle[INTERNAL_LAM_KEY];
@@ -8687,19 +8809,19 @@ var PersonalityRegistry = class _PersonalityRegistry {
 function addEntity(byName, entity, origin, collisionMap) {
   const fm = entity.frontmatter;
   if (PersonalityRegistry.isReservedClearSlug(fm.name)) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Personality name "${fm.name}" is reserved (used to clear active preset)`,
       { code: "personality_reserved_name" }
     );
   }
   if (entity.body.trim().length === 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Personality "${fm.name}" has empty body (system prompt required)`,
       { code: "personality_empty_body" }
     );
   }
   if (origin === "project" && collisionMap?.has(fm.name)) {
-    chunk665SFFFR_cjs.warnOnce(
+    chunk53CBTBWO_cjs.warnOnce(
       `personality-collision-${fm.name}`,
       `[theokit-sdk] personality "${fm.name}" overridden by project preset`
     );
@@ -8728,7 +8850,7 @@ async function performPersonalitySwitch(args) {
     const preset = args.registry.get(args.requestedName);
     if (preset === void 0) {
       const available = args.registry.all().map((p) => p.name).join(", ") || "(none)";
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `Personality "${args.requestedName}" not found. Available: ${available}`,
         { code: "personality_not_found" }
       );
@@ -8749,14 +8871,14 @@ async function performPersonalitySwitch(args) {
 
 // src/internal/local-agent/local-agent-personality-extensions.ts
 function resolveActivePersonalityPreset(args) {
-  const forkCtx = chunk665SFFFR_cjs.currentPersonalityContext();
+  const forkCtx = chunk53CBTBWO_cjs.currentPersonalityContext();
   const slug = forkCtx !== void 0 ? forkCtx.slug : args.personalityStore.active(args.agentId);
   if (slug === void 0) return void 0;
   return args.personalityRegistry?.get(slug);
 }
 async function ensurePersonalityRegistryIfNeeded(args) {
   if (args.personalityRegistry !== void 0) return args.personalityRegistry;
-  const forkSlug = chunk665SFFFR_cjs.currentPersonalityContext()?.slug;
+  const forkSlug = chunk53CBTBWO_cjs.currentPersonalityContext()?.slug;
   const ownSlug = args.personalityStore.active(args.agentId);
   if (forkSlug === void 0 && ownSlug === void 0) return void 0;
   return await PersonalityRegistry.load(args.workspaceCwd);
@@ -8770,8 +8892,8 @@ ${preset.systemPrompt}`;
 }
 async function localAgentUsePersonality(args) {
   if (args.disposed) throw new Error("Agent has been disposed");
-  if (chunk665SFFFR_cjs.currentPersonalityContext() !== void 0) {
-    chunk665SFFFR_cjs.warnPersonalitySwitchInsideFork(args.agentId);
+  if (chunk53CBTBWO_cjs.currentPersonalityContext() !== void 0) {
+    chunk53CBTBWO_cjs.warnPersonalitySwitchInsideFork(args.agentId);
     return null;
   }
   let registry = args.personalityRegistry;
@@ -8779,7 +8901,7 @@ async function localAgentUsePersonality(args) {
     registry = await PersonalityRegistry.load(args.workspaceCwd);
     args.onRegistryLoaded(registry);
   }
-  return chunkYLQQX5W2_cjs.withCwdMutex(
+  return chunkZF2LDKQQ_cjs.withCwdMutex(
     `agent-send:${args.agentId}`,
     () => performPersonalitySwitch({
       agentId: args.agentId,
@@ -8788,8 +8910,8 @@ async function localAgentUsePersonality(args) {
       registry,
       store: args.personalityStore,
       invalidateCache: (reason) => args.invalidateCache(reason),
-      appendSessionMessage: (msg) => chunk2D43RD5D_cjs.appendSessionMessage(args.agentId, msg),
-      clearSession: () => chunk2D43RD5D_cjs.clearSession(args.agentId),
+      appendSessionMessage: (msg) => chunkV2UUGUY4_cjs.appendSessionMessage(args.agentId, msg),
+      clearSession: () => chunkV2UUGUY4_cjs.clearSession(args.agentId),
       opts: args.opts ?? {}
     })
   );
@@ -8800,7 +8922,7 @@ function localAgentRunUntil(agent, goal, options) {
   async function* wrap() {
     const { runUntilImpl } = await import('./run-until-U2B5FJJI.cjs');
     const buildDeps = async () => {
-      const { judgeCallImpl } = await import('./judge-call-G5SGV2M2.cjs');
+      const { judgeCallImpl } = await import('./judge-call-EGYRC2RE.cjs');
       const { getAgentFacade } = await import('./agent-factory-registry-UU46BUMU.cjs');
       const create = getAgentFacade().create;
       return {
@@ -8821,19 +8943,19 @@ function localAgentRunUntil(agent, goal, options) {
 }
 function localAgentRunToCompletion(agent, message, options) {
   async function run() {
-    const { runToCompletionImpl } = await import('./run-to-completion-J73I6IY4.cjs');
+    const { runToCompletionImpl } = await import('./run-to-completion-X4OWM673.cjs');
     return runToCompletionImpl({ send: (m, o) => agent.send(m, o) }, message, options);
   }
   return run();
 }
 async function* localAgentStreamToCompletion(agent, message, options) {
-  const { streamToCompletionImpl } = await import('./stream-to-completion-H2MHISSK.cjs');
+  const { streamToCompletionImpl } = await import('./stream-to-completion-SRISU5AB.cjs');
   return yield* streamToCompletionImpl({ send: (m, o) => agent.send(m, o) }, message, options);
 }
 async function localAgentFork(parent, options) {
   const { forkAgentImpl } = await import('./fork-agent-Y2IK2RYU.cjs');
   const { getAgentFacade } = await import('./agent-factory-registry-UU46BUMU.cjs');
-  const { withPersonalityContext } = await import('./context-7USNN6LP.cjs');
+  const { withPersonalityContext } = await import('./context-VMIE4BMD.cjs');
   const create = getAgentFacade().create;
   return withPersonalityContext(
     { slug: parent.personalitySlugSnapshot, isFork: true },
@@ -8893,7 +9015,7 @@ function wrapRunWithCompletionCheck(args) {
       judgeOpts
     );
     const complete = !verdict.parseFailed && verdict.verdict === "done";
-    chunkXPR366DL_cjs.emitRunEvent(args.onRunEvent, {
+    chunkNGESVVJN_cjs.emitRunEvent(args.onRunEvent, {
       type: "completion_check",
       complete,
       reason: verdict.reason
@@ -9040,7 +9162,7 @@ function wrapRunWithOutputProcessors(args) {
     if (result.status !== "finished" || result.result === void 0) return result;
     const res = await runOutputProcessors(args.processors, result.result, args.agentId);
     if (res.kind === "ok") return { ...result, result: res.value };
-    chunkXPR366DL_cjs.emitRunEvent(args.onRunEvent, {
+    chunkNGESVVJN_cjs.emitRunEvent(args.onRunEvent, {
       type: "tripwire",
       reason: res.tripwire.reason,
       processorId: res.tripwire.processorId
@@ -9083,6 +9205,15 @@ ${recalled}
 ${args.userText}`;
   return typeof args.original === "string" ? wrapped : { ...args.original, text: wrapped };
 }
+async function runCalledATool(run) {
+  try {
+    for await (const event of run.stream()) {
+      if (event.type === "tool_call") return true;
+    }
+  } catch {
+  }
+  return false;
+}
 function wrapRunWithPostReplyHook(args) {
   const handlers = args.pluginManager.hooksFor("post_assistant_reply");
   if (handlers.length === 0) return args.run;
@@ -9094,6 +9225,12 @@ function wrapRunWithPostReplyHook(args) {
       reply: replyText,
       agentId: args.agentId,
       runId: result.id,
+      // #358 — whether this reply is safely replayable. A consumer (the semantic cache) must not
+      // re-serve an answer produced by a tool call, and had nothing to key on. The run knows:
+      // `stream()` replays its buffered events after `wait()` (ADR 0006), so a `tool_call` among
+      // them is the signal. Computed here, inside a path that only runs when a hook is registered
+      // and is already fire-and-forget, so it never lands on the caller's critical path.
+      usedTools: await runCalledATool(args.run),
       ...args.options.memoryContext !== void 0 ? { memoryContext: args.options.memoryContext } : {}
     };
     void args.pluginManager.runPostAssistantReplyHooks(ctx);
@@ -9115,7 +9252,7 @@ async function applyInputProcessors(inputs, message, rawUserText, options, sendM
   }
   const res = await runInputProcessors(processors, rawUserText, inputs.agentId);
   if (res.kind === "tripwire") {
-    chunkXPR366DL_cjs.emitRunEvent(options.onRunEvent, {
+    chunkNGESVVJN_cjs.emitRunEvent(options.onRunEvent, {
       type: "tripwire",
       reason: res.tripwire.reason,
       processorId: res.tripwire.processorId
@@ -9132,7 +9269,7 @@ async function applyInputProcessors(inputs, message, rawUserText, options, sendM
   return { userText: res.value, effectiveMessage };
 }
 async function executeSendLocked(inputs, message, options) {
-  if (inputs.disposed) throw new chunkLPVIRJVF_cjs.AgentDisposedError(inputs.agentId);
+  if (inputs.disposed) throw new chunkK3FW2XZD_cjs.AgentDisposedError(inputs.agentId);
   await consumePending(inputs.agentId, inputs.invalidationPending, inputs.clearInvalidation, inputs.reload);
   const sendModel = normalizeModel(options.model);
   inputs.applyModelOverride(sendModel);
@@ -9143,7 +9280,7 @@ async function executeSendLocked(inputs, message, options) {
   if (inputs.options.onBeforeSend !== void 0) {
     await inputs.options.onBeforeSend({
       conversationId: inputs.agentId,
-      previousMessageCount: chunk2D43RD5D_cjs.getSessionMessages(inputs.agentId).length
+      previousMessageCount: chunkV2UUGUY4_cjs.getSessionMessages(inputs.agentId).length
     });
   }
   await inputs.runPreHook(userText);
@@ -9155,8 +9292,8 @@ async function executeSendLocked(inputs, message, options) {
     userText,
     sendOptions: options
   });
-  const priorMessages = [...chunk2D43RD5D_cjs.getSessionMessages(inputs.agentId)];
-  chunk2D43RD5D_cjs.appendSessionMessage(inputs.agentId, { role: "user", text: userText });
+  const priorMessages = [...chunkV2UUGUY4_cjs.getSessionMessages(inputs.agentId)];
+  chunkV2UUGUY4_cjs.appendSessionMessage(inputs.agentId, { role: "user", text: userText });
   await persistMemoryFactIfWritePrompt(inputs.workspaceCwd, inputs.options.memory, userText);
   const memoryFacts = await readMemoryForSend(inputs.workspaceCwd, inputs.options.memory);
   const portPathActive = shouldUsePortMemoryPath();
@@ -9214,7 +9351,7 @@ async function executeSendLocked(inputs, message, options) {
 function buildCompletionCheckDeps() {
   return {
     judge: async (ctx, opts) => {
-      const { judgeCallImpl } = await import('./judge-call-G5SGV2M2.cjs');
+      const { judgeCallImpl } = await import('./judge-call-EGYRC2RE.cjs');
       const { getAgentFacade } = await import('./agent-factory-registry-UU46BUMU.cjs');
       return judgeCallImpl(ctx, opts, { create: getAgentFacade().create });
     }
@@ -9234,7 +9371,7 @@ function registerRunAsTask(run, agentId, taskOpt, userText) {
     promptPreview: userText.slice(0, 120),
     ...opts.meta ?? {}
   };
-  void chunkXPR366DL_cjs.submit({
+  void chunkNGESVVJN_cjs.submit({
     kind: "run",
     work: async (ctx) => {
       ctx.signal.addEventListener(
@@ -9319,7 +9456,7 @@ var LocalAgent = class {
     this.options = options;
     this.workspaceCwd = resolveCwd(options.local?.cwd);
     this.transcriptBaseDir = resolveSessionDir(options.local);
-    this.sessionStore = options.local?.sessionStore ?? new chunkOUOXM36O_cjs.FsSessionStore({ baseDir: this.transcriptBaseDir, cwd: this.workspaceCwd });
+    this.sessionStore = options.local?.sessionStore ?? new chunkYPJ5NH5N_cjs.FsSessionStore({ baseDir: this.transcriptBaseDir, cwd: this.workspaceCwd });
     this.settingSourcesIncludeProject = includesSetting(options, "project");
     this.settingSourcesIncludePlugins = includesSetting(options, "plugins");
     const sub = bootstrapSubmanagers({
@@ -9362,14 +9499,14 @@ var LocalAgent = class {
     if (this.pluginsManager !== void 0) await this.pluginsManager.initialize();
     const codePlugins = chunkBV2MWEMV_cjs.extractCodePlugins(this.options.plugins);
     await this.pluginManagerCode.initialize(codePlugins);
-    this.resolvedSubagents = await chunkE7FJOO4G_cjs.loadSubagents(
+    this.resolvedSubagents = await chunkHJBMA5MB_cjs.loadSubagents(
       this.workspaceCwd,
       this.settingSourcesIncludeProject,
       this.options.agents
     );
     await acquireLeaseIfPossible(this.sessionStore, this.agentId);
     try {
-      await chunk2D43RD5D_cjs.hydrateSession(this.agentId, { store: this.sessionStore, cwd: this.workspaceCwd });
+      await chunkV2UUGUY4_cjs.hydrateSession(this.agentId, { store: this.sessionStore, cwd: this.workspaceCwd });
       await this.personalityStore.hydrate(this.agentId);
     } catch (err) {
       await releaseLeaseIfPossible(this.sessionStore, this.agentId);
@@ -9391,14 +9528,14 @@ var LocalAgent = class {
   }
   async send(message, options = {}) {
     if (options.tools !== void 0 && options.tools.length > 0) {
-      validateToolCatalog(options.tools);
+      validateToolCatalog(options.tools, this.options.withheldBuiltinTools);
     }
     const sendSpan = this._telemetry.startSpan(SPAN_NAMES.AGENT_SEND, {
       agentId: this.agentId,
       ...this.model?.id !== void 0 ? { model: this.model.id } : {}
     });
     return new Promise((resolve, reject) => {
-      void chunkYLQQX5W2_cjs.withCwdMutex(
+      void chunkZF2LDKQQ_cjs.withCwdMutex(
         `agent-send:${this.agentId}`,
         () => this.runLockedSendCycle(message, options, sendSpan, resolve, reject)
       );
@@ -9449,6 +9586,8 @@ var LocalAgent = class {
         ...options.onRunEvent !== void 0 ? { onRunEvent: options.onRunEvent } : {},
         hooksExecutor: this.hooksExecutor,
         memoryGlue: this.memoryGlue,
+        // usetheokit/theokit-sdk#382 — the transcript write reads this and nothing else.
+        memory: this.options.memory,
         ...postRunProvider !== void 0 ? { memoryProvider: postRunProvider } : {}
       });
     } finally {
@@ -9518,7 +9657,7 @@ var LocalAgent = class {
       agentId: this.agentId
     });
     if (preRun.blocked) {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         `preRun hook denied execution: ${preRun.reason ?? "unspecified"}`,
         { code: "hook_denied" }
       );
@@ -9599,7 +9738,7 @@ var LocalAgent = class {
   }
   // biome-ignore format: G8 budget — see listArtifacts.
   downloadArtifact(_path) {
-    return Promise.reject(new chunkLPVIRJVF_cjs.UnsupportedRunOperationError("Artifacts are not supported for local agents", "downloadArtifact"));
+    return Promise.reject(new chunkK3FW2XZD_cjs.UnsupportedRunOperationError("Artifacts are not supported for local agents", "downloadArtifact"));
   }
   // biome-ignore format: G8 budget — delegates to `local-agent-runtime-extensions.ts`; kept 1-line.
   runUntil(goal, options) {
@@ -9644,7 +9783,7 @@ async function guardAgainstIdCollision(options) {
   const persistenceCwd = resolveAgentPersistenceCwd(options);
   await hydrateRegistryFromDisk(persistenceCwd);
   if (getRegisteredAgent(options.agentId) !== void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       `Agent "${options.agentId}" already exists. Use Agent.resume("${options.agentId}") to reattach, or pick a different agentId.`,
       { code: "agent_id_already_exists" }
     );
@@ -9677,7 +9816,7 @@ async function maybeInjectHandoffTools(options) {
     const spec = "@theokit/sdk-handoff/internal/tool-injector";
     mod = await import(spec);
   } catch (err) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError(
+    throw new chunkK3FW2XZD_cjs.ConfigurationError(
       "Agent.create({ handoffs: [...] }) requires @theokit/sdk-handoff. Install it: pnpm add @theokit/sdk-handoff. Or migrate to the preferred plugin pattern: plugins: [Handoff.asPlugin({ targets: [...] })] (see docs/migration/1-x-to-2-0.md#handoff).",
       { code: "handoff_package_missing", cause: err }
     );
@@ -9694,47 +9833,57 @@ async function maybeInjectHandoffTools(options) {
     tools: [...existingTools, ...handoffTools]
   };
 }
+function keyWillFlowToProvider(apiKey, provider) {
+  if (chunkHLPSLDGL_cjs.isFixtureApiKey(apiKey)) return false;
+  if (chunkHLPSLDGL_cjs.getConfiguredBaseUrl() !== void 0) return false;
+  if (provider === void 0) return false;
+  const profile = chunk6HTXPPHK_cjs.getProviderProfile(provider);
+  if (profile === void 0) return false;
+  return profile.authType !== "none";
+}
+function missingApiKeyMessage() {
+  const present = chunkHLPSLDGL_cjs.presentProviderCredentialEnvVars();
+  const base = `Missing API key \u2014 set ${chunkJTB5Q42C_cjs.API_KEY_ENV_VAR}, or pass \`apiKey\` to Agent.create()`;
+  if (present.length === 0) return `${base}.`;
+  return `${base}. ${present.join(" and ")} ${present.length === 1 ? "is" : "are"} set, but a provider credential is not read from the environment automatically \u2014 pass it explicitly, e.g. \`Agent.create({ apiKey: process.env.${present[0]}, ... })\`.`;
+}
 async function createLocalAgent(options) {
-  const apiKey = chunkBM6N4KHO_cjs.resolveApiKey(options.apiKey);
+  const apiKey = chunkJTB5Q42C_cjs.resolveApiKey(options.apiKey);
   if (apiKey === void 0) {
-    throw new chunkLPVIRJVF_cjs.AuthenticationError("Missing API key", { code: "missing_api_key" });
+    throw new chunkK3FW2XZD_cjs.AuthenticationError(missingApiKeyMessage(), { code: "missing_api_key" });
   }
-  const willFlowToProvider = !chunk2FYEVT2B_cjs.isFixtureApiKey(apiKey) && !chunk2FYEVT2B_cjs.shouldUseRealLocalRuntime(apiKey);
+  const provider = providerFromModelId(normalizeModel(options.model)?.id);
+  const willFlowToProvider = keyWillFlowToProvider(apiKey, provider);
   const shape = validateApiKeyShape(apiKey, {
     strict: willFlowToProvider,
     // `options.model` is already normalized by `runCreateUnderSpan`; `normalizeModel`
     // here is the idempotent narrowing of the widened public type (`{id}` passes
     // through by reference) — cleaner than an `as` cast.
-    ...willFlowToProvider ? { provider: providerFromModelId(normalizeModel(options.model)?.id) } : {}
+    ...willFlowToProvider ? { provider } : {}
   });
   if (shape.malformed) {
-    throw new chunkLPVIRJVF_cjs.AuthenticationError(shape.message, { code: "malformed_api_key" });
-  }
-  if (!chunk2FYEVT2B_cjs.isFixtureApiKey(apiKey) && chunk2FYEVT2B_cjs.getConfiguredBaseUrl() === void 0 && !chunk2FYEVT2B_cjs.shouldUseRealLocalRuntime(apiKey)) {
-    throw new chunkLPVIRJVF_cjs.AuthenticationError("Invalid API key", {
-      code: "authentication_error"
-    });
+    throw new chunkK3FW2XZD_cjs.AuthenticationError(shape.message, { code: "malformed_api_key" });
   }
   const agent = new LocalAgent(options);
   await agent.initialize();
   return agent;
 }
 async function createCloudAgent(options) {
-  const apiKey = chunkBM6N4KHO_cjs.resolveApiKey(options.apiKey);
+  const apiKey = chunkJTB5Q42C_cjs.resolveApiKey(options.apiKey);
   if (apiKey === void 0) {
-    throw new chunkLPVIRJVF_cjs.ConfigurationError("Missing API key for cloud agent", {
+    throw new chunkK3FW2XZD_cjs.ConfigurationError("Missing API key for cloud agent", {
       code: "missing_api_key"
     });
   }
   const shape = validateApiKeyShape(apiKey);
   if (shape.malformed) {
-    throw new chunkLPVIRJVF_cjs.AuthenticationError(shape.message, { code: "malformed_api_key" });
+    throw new chunkK3FW2XZD_cjs.AuthenticationError(shape.message, { code: "malformed_api_key" });
   }
-  const baseUrl = chunk2FYEVT2B_cjs.getConfiguredBaseUrl();
+  const baseUrl = chunkHLPSLDGL_cjs.getConfiguredBaseUrl();
   if (baseUrl === void 0) {
     return new CloudAgent(options);
   }
-  const response = await chunk2FYEVT2B_cjs.httpRequest("/v1/agents", {
+  const response = await chunkHLPSLDGL_cjs.httpRequest("/v1/agents", {
     apiKey,
     method: "POST",
     body: {
@@ -9759,7 +9908,7 @@ function resolveAgentPersistenceCwd(options) {
   return process.cwd();
 }
 async function rehydrateExistingAgent(agentId, existing, options) {
-  await chunk2FYEVT2B_cjs.discoverProviderPlugins();
+  await chunkHLPSLDGL_cjs.discoverProviderPlugins();
   await validateRehydratedAgent(agentId, existing);
   const mergedLocal = options.local !== void 0 && existing.options.local !== void 0 ? { ...existing.options.local, ...options.local } : options.local ?? existing.options.local;
   const mergedOptions = {
@@ -9790,7 +9939,7 @@ async function validateRehydratedAgent(agentId, entry) {
       throw new Error(`Workspace path is not a directory: ${candidate}`);
     }
   } catch (cause) {
-    throw new chunkLPVIRJVF_cjs.UnknownAgentError(
+    throw new chunkK3FW2XZD_cjs.UnknownAgentError(
       `Agent "${agentId}" cannot be rehydrated \u2014 workspace cwd "${candidate}" is missing or inaccessible.`,
       { code: "agent_rehydration_failed", cause }
     );
@@ -9835,17 +9984,33 @@ async function setAgentName(agentId, name) {
   updateRegisteredAgent(agentId, { name });
   await flushRegistrySaves();
 }
-async function getRegisteredAgentOrThrow(agentId) {
+async function getRegisteredAgentOrThrow(agentId, cwd = process.cwd()) {
   let agent = getRegisteredAgent(agentId);
   if (agent === void 0) {
-    await hydrateRegistryFromDisk(process.cwd());
+    await hydrateRegistryFromDisk(cwd);
     agent = getRegisteredAgent(agentId);
   }
   if (agent === void 0) {
-    throw new chunkLPVIRJVF_cjs.UnknownAgentError(`Agent ${agentId} not found`, { code: "unknown_agent" });
+    throw new chunkK3FW2XZD_cjs.UnknownAgentError(`Agent ${agentId} not found`, { code: "unknown_agent" });
   }
   return agent;
 }
+function paginateByKey(all, keyOf, limit, cursor, sortByKey) {
+  if (limit === void 0) return { items: [...all] };
+  const ordered = sortByKey ? [...all].sort((a, b) => {
+    const ka = keyOf(a);
+    const kb = keyOf(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  }) : [...all];
+  const startIndex = cursor === void 0 ? 0 : ordered.findIndex((item) => keyOf(item) === cursor) + 1;
+  const page = ordered.slice(startIndex, startIndex + limit);
+  const hasMore = startIndex + limit < ordered.length;
+  const last = page[page.length - 1];
+  return {
+    items: page,
+    ...hasMore && last !== void 0 ? { nextCursor: keyOf(last) } : {}
+  };
+}
 
 // src/agent.ts
 var streamObjectImport;
@@ -9887,7 +10052,7 @@ var Agent = class _Agent {
       pluginCount: enabledPluginNames(options.plugins).length
     });
     try {
-      await chunk2FYEVT2B_cjs.discoverProviderPlugins();
+      await chunkHLPSLDGL_cjs.discoverProviderPlugins();
       const agent = await runCreateUnderSpan(options, span);
       return agent;
     } catch (err) {
@@ -9928,8 +10093,8 @@ var Agent = class _Agent {
       const run = await agent.send(message);
       const result = await run.wait();
       if (options.throwOnError === true && result.status === "error" && result.error !== void 0) {
-        throw new chunkLPVIRJVF_cjs.AgentRunError(result.error.message, {
-          code: chunkLPVIRJVF_cjs.coerceToKnownAgentRunErrorCode(result.error.code),
+        throw new chunkK3FW2XZD_cjs.AgentRunError(result.error.message, {
+          code: chunkK3FW2XZD_cjs.coerceToKnownAgentRunErrorCode(result.error.code),
           cause: result.error.cause
         });
       }
@@ -9956,7 +10121,7 @@ var Agent = class _Agent {
     if (existing !== void 0) {
       return await rehydrateExistingAgent(agentId, existing, options);
     }
-    throw new chunkLPVIRJVF_cjs.UnknownAgentError(
+    throw new chunkK3FW2XZD_cjs.UnknownAgentError(
       `Agent "${agentId}" not found. Use Agent.create({ agentId, ... }) for first-time setup, or catch UnknownAgentError to branch resume-vs-create.`,
       { code: "unknown_agent" }
     );
@@ -9985,7 +10150,7 @@ var Agent = class _Agent {
    * @public
    */
   static async generateObject(options) {
-    const { generateObjectImpl } = await import('./generate-object-AVXOJK2I.cjs');
+    const { generateObjectImpl } = await import('./generate-object-PGSP5U7N.cjs');
     return generateObjectImpl(options, {
       create: (opts) => _Agent.create(opts),
       delete: (agentId) => _Agent.delete(agentId)
@@ -10009,7 +10174,7 @@ var Agent = class _Agent {
       delete: (agentId) => _Agent.delete(agentId)
     };
     async function* wrapper() {
-      streamObjectImport ??= import('./stream-object-L3Q7PBMF.cjs');
+      streamObjectImport ??= import('./stream-object-BUCF5PHO.cjs');
       const { streamObjectImpl } = await streamObjectImport;
       yield* streamObjectImpl(options, deps);
     }
@@ -10033,7 +10198,7 @@ var Agent = class _Agent {
    * @public
    */
   static async batch(prompts, options) {
-    const { batchImpl } = await import('./batch-ZEFN5SO7.cjs');
+    const { batchImpl } = await import('./batch-ND32UKZS.cjs');
     return batchImpl(prompts, options, { create: (opts) => _Agent.create(opts) });
   }
   /**
@@ -10077,34 +10242,57 @@ var Agent = class _Agent {
     return fresh;
   }
   /**
-   * List agents (local or cloud). M107 — `cwd` is READ now, not ignored;
-   * `limit`/`cursor` still are not (see `tests/agent-list-cwd.test.ts`).
+   * List agents (local or cloud). M107 — `cwd` is READ, not ignored. B-115 (2026-08-19) —
+   * `includeArchived` and `limit`/`cursor` are READ too now; see `ListAgentsOptions`'s doc for the
+   * pagination contract and why the unlimited (no `limit`) case is unaffected.
    *
    * @public
    */
   static async list(options = {}) {
     const cwd = ("cwd" in options ? options.cwd : void 0) ?? process.cwd();
     await hydrateRegistryFromDisk(cwd);
-    const items = listRegisteredAgents(options.runtime, cwd).map((agent) => toAgentInfo(agent));
-    return { items };
+    const includeArchived = "includeArchived" in options ? options.includeArchived ?? false : false;
+    const agents2 = listRegisteredAgents(options.runtime, cwd, includeArchived);
+    const { items, nextCursor } = paginateByKey(
+      agents2,
+      (agent) => agent.agentId,
+      options.limit,
+      options.cursor,
+      /* sortByKey */
+      true
+    );
+    return {
+      items: items.map((agent) => toAgentInfo(agent)),
+      ...nextCursor !== void 0 ? { nextCursor } : {}
+    };
   }
   /**
-   * Get metadata for a single agent.
+   * Get metadata for a single agent. B-115 (2026-08-19) — `cwd` is READ now (see
+   * `GetAgentOptions`'s doc); it used to be accepted and silently ignored.
    *
    * @public
    */
-  static async get(agentId, _options = {}) {
-    const agent = await getRegisteredAgentOrThrow(agentId);
+  static async get(agentId, options = {}) {
+    const agent = await getRegisteredAgentOrThrow(agentId, options.cwd);
     return toAgentInfo(agent);
   }
   /**
-   * List runs for an agent.
+   * List runs for an agent. B-115 (2026-08-19) — `cwd` and `limit`/`cursor` are READ now (see
+   * `ListRunsOptions`'s doc); they used to be accepted and silently ignored.
    *
    * @public
    */
-  static async listRuns(agentId, _options = {}) {
-    await getRegisteredAgentOrThrow(agentId);
-    return { items: listRunsByAgent(agentId) };
+  static async listRuns(agentId, options = {}) {
+    await getRegisteredAgentOrThrow(agentId, options.cwd);
+    const { items, nextCursor } = paginateByKey(
+      listRunsByAgent(agentId),
+      (run) => run.id,
+      options.limit,
+      options.cursor,
+      /* sortByKey */
+      false
+    );
+    return { items, ...nextCursor !== void 0 ? { nextCursor } : {} };
   }
   /**
    * Get a single run.
@@ -10113,14 +10301,14 @@ var Agent = class _Agent {
    */
   static async getRun(runId, options = {}) {
     if (options.runtime === "cloud") {
-      throw new chunkLPVIRJVF_cjs.ConfigurationError(
+      throw new chunkK3FW2XZD_cjs.ConfigurationError(
         "Cloud runtime is pre-release. Theo PaaS endpoints are not wired yet \u2014 getRun({ runtime: 'cloud' }) will be enabled when the PaaS ships.",
         { code: "cloud_runtime_pre_release" }
       );
     }
     const existing = getRun(runId);
     if (existing !== void 0) return existing;
-    throw new chunkLPVIRJVF_cjs.UnknownAgentError(
+    throw new chunkK3FW2XZD_cjs.UnknownAgentError(
       `Run ${runId} is not in this process's registry. It may have been disposed, persisted in a previous process, or never created.`,
       { code: "run_not_found" }
     );
@@ -10167,13 +10355,13 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new chunkLPVIRJVF_cjs.UnknownAgentError(
+      throw new chunkK3FW2XZD_cjs.UnknownAgentError(
         `No local agent "${agentId}" registered \u2014 compact targets local sessions.`
       );
     }
-    const { compactSessionTranscript, buildDefaultSummarizer: buildDefaultSummarizer2 } = await import('./compact-session-EPFBQ46Z.cjs');
+    const { compactSessionTranscript, buildDefaultSummarizer: buildDefaultSummarizer2 } = await import('./compact-session-LEWF554G.cjs');
     const { cwd, model, store } = await openLocalStore(reg);
-    return chunk2D43RD5D_cjs.enqueueSessionWrite(
+    return chunkV2UUGUY4_cjs.enqueueSessionWrite(
       cwd,
       agentId,
       () => compactSessionTranscript({
@@ -10203,11 +10391,11 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new chunkLPVIRJVF_cjs.UnknownAgentError(
+      throw new chunkK3FW2XZD_cjs.UnknownAgentError(
         `No local agent "${agentId}" registered \u2014 injectSessionTurn targets local sessions.`
       );
     }
-    const { injectSessionTurn } = await import('./inject-session-AUQLBDRS.cjs');
+    const { injectSessionTurn } = await import('./inject-session-WQGGMCQY.cjs');
     const { cwd, model, store } = await openLocalStore(reg);
     await injectSessionTurn({
       store,
@@ -10242,11 +10430,11 @@ var Agent = class _Agent {
       reg = getRegisteredAgent(agentId);
     }
     if (reg === void 0 || reg.runtime !== "local") {
-      throw new chunkLPVIRJVF_cjs.UnknownAgentError(
+      throw new chunkK3FW2XZD_cjs.UnknownAgentError(
         `No local agent "${agentId}" registered \u2014 transcript targets local sessions.`
       );
     }
-    const { readSessionMessages } = await import('./agent-session-store-DUGBAX5V.cjs');
+    const { readSessionMessages } = await import('./agent-session-store-ZJ3JSRS4.cjs');
     const { store } = await openLocalStore(reg);
     return readSessionMessages(store, agentId);
   }
@@ -10267,7 +10455,7 @@ var Agent = class _Agent {
    */
   static async describe(agentId) {
     const agent = await getRegisteredAgentOrThrow(agentId);
-    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-VRW73QQT.cjs');
+    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-AZIXJ7D3.cjs');
     const settingSources = agent.options.local?.settingSources;
     const subagents = await loadSubagents2(
       agent.cwd ?? process.cwd(),
@@ -10282,7 +10470,7 @@ var Agent = class _Agent {
       //
       // Honest limit, stated because the alternative is an implied claim: `tools` is still the
       // DECLARED catalog. Plugin tools and the reasoning `think` tool are assembled per run by
-      // `buildCustomToolsInput`, so they are not knowable from the registry alone. Documented on
+      // `buildRunToolCatalogInput`, so they are not knowable from the registry alone. Documented on
       // `AgentDescription.tools`.
       tools: (agent.options.tools ?? []).map((tool) => ({
         name: tool.name,
@@ -10311,12 +10499,12 @@ async function getOrCreateUncached(agentId, options) {
   try {
     return await Agent.resume(agentId, options);
   } catch (err) {
-    if (!(err instanceof chunkLPVIRJVF_cjs.UnknownAgentError)) throw err;
+    if (!(err instanceof chunkK3FW2XZD_cjs.UnknownAgentError)) throw err;
   }
   try {
     return await Agent.create({ ...options, agentId });
   } catch (err) {
-    if (err instanceof chunkLPVIRJVF_cjs.ConfigurationError && err.code === "agent_id_already_exists") {
+    if (err instanceof chunkK3FW2XZD_cjs.ConfigurationError && err.code === "agent_id_already_exists") {
       return await Agent.resume(agentId, options);
     }
     throw err;
@@ -10334,8 +10522,8 @@ async function openLocalStore(reg) {
   const cwd = reg.cwd ?? process.cwd();
   const optModel = reg.options.model;
   const model = reg.model?.id ?? (typeof optModel === "string" ? optModel : optModel?.id) ?? "unknown";
-  const { FsSessionStore: FsSessionStore2 } = await import('./fs-session-store-VVY2AHWG.cjs');
-  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await import('./session-transcript-DOM3UTXR.cjs');
+  const { FsSessionStore: FsSessionStore2 } = await import('./fs-session-store-3MOJQGP2.cjs');
+  const { defaultBaseDir: defaultBaseDir2, expandTilde: expandTilde2 } = await import('./session-transcript-JXHFTB7G.cjs');
   const configuredSessionDir = reg.options.local?.sessionDir ?? reg.options.local?.baseDir;
   const baseDir = configuredSessionDir !== void 0 ? expandTilde2(configuredSessionDir) : defaultBaseDir2();
   return { cwd, model, store: new FsSessionStore2({ baseDir, cwd }) };
@@ -10352,5 +10540,5 @@ exports.computeCost = computeCost;
 exports.generateCronId = generateCronId;
 exports.getPricingEntry = getPricingEntry;
 exports.openRouterMemoryEmbeddingProviderAdapter = openRouterMemoryEmbeddingProviderAdapter;
-//# sourceMappingURL=chunk-F77UENR6.cjs.map
-//# sourceMappingURL=chunk-F77UENR6.cjs.map
+//# sourceMappingURL=chunk-F5WMX4EA.cjs.map
+//# sourceMappingURL=chunk-F5WMX4EA.cjs.map