@axlsdk/axl 0.22.2 → 0.22.3

package/dist/index.js

@@ -2118,17 +2118,22 @@ function resolveOpenAIReasoningEffort(model, resolved) {
   }
   return resolved.thinkingDisabled ? clampReasoningEffort(model, "none") : void 0;
 }
-var warnedChatMaxDowngrades = /* @__PURE__ */ new Set();
 function resolveOpenAIChatReasoningEffort(model, resolved) {
   const effort = resolveOpenAIReasoningEffort(model, resolved);
-  if (effort !== "max") return effort;
-  if (resolved.activeEffort === "max" && !warnedChatMaxDowngrades.has(model)) {
-    warnedChatMaxDowngrades.add(model);
-    console.warn(
-      `[axl] OpenAI Chat Completions does not accept effort "max" for ${model}; using "xhigh". Use the OpenAI Responses provider for native "max".`
-    );
-  }
-  return "xhigh";
+  return effort === "max" ? "xhigh" : effort;
+}
+function resolveOpenAIEffortResolution(options, resolveWireEffort, endpoint) {
+  const resolved = resolveThinkingOptions(options);
+  if (resolved.effort === void 0 || resolved.hasBudgetOverride) return void 0;
+  const model = typeof options.providerOptions?.model === "string" ? options.providerOptions.model : options.model;
+  const effective = resolveWireEffort(model, resolved);
+  if (effective === void 0 || effective === resolved.effort) return void 0;
+  return {
+    requested: resolved.effort,
+    effective,
+    clamped: true,
+    cause: `${endpoint} does not accept reasoning effort '${resolved.effort}' for ${model}; using '${effective}'`
+  };
 }
 var openaiReasoningEmit = (body, resolved, model) => {
   const oSeries = isOSeriesModel(model);
@@ -2153,6 +2158,15 @@ var OpenAIProvider = class extends OpenAICompatibleProvider {
   constructor(options = {}) {
     super({ profile: OPENAI_PROFILE, ...options });
   }
+  /** Report a clamped `effort` — Chat Completions caps `'max'` at `'xhigh'` and
+   *  rejects `'none'` before gpt-5.1 (clamped to `'minimal'`). */
+  effortResolution(options) {
+    return resolveOpenAIEffortResolution(
+      options,
+      resolveOpenAIChatReasoningEffort,
+      "OpenAI Chat Completions"
+    );
+  }
   computeCost(model, usage, _reportedCost, context) {
     return usage ? estimateDirectOpenAICost(model, usage, { ...context, baseUrl: this.baseUrl }) : void 0;
   }
@@ -2199,6 +2213,12 @@ var OpenAIResponsesProvider = class {
   inputCapabilities(model) {
     return model.trim().length > 0 ? { image: { sources: ["url", "bytes", "base64", "provider-file"] } } : {};
   }
+  /** Report a clamped `effort`. Responses accepts the native `'max'` tier that
+   *  Chat Completions caps, but still clamps `'none'` before gpt-5.1, `'xhigh'`
+   *  below gpt-5.2, and everything to `'high'` on gpt-5-pro. */
+  effortResolution(options) {
+    return resolveOpenAIEffortResolution(options, resolveOpenAIReasoningEffort, "OpenAI Responses");
+  }
   validateInput(request) {
     const modelOverride = request.providerOptions?.model;
     const effectiveModel = typeof modelOverride === "string" ? modelOverride : request.model;
@@ -2874,14 +2894,6 @@ function budgetToClaudeEffort(budget) {
   if (budget <= THINKING_BUDGETS.xhigh) return "xhigh";
   return "max";
 }
-var warnedFableDisable = /* @__PURE__ */ new Set();
-function warnFableDisable(model) {
-  if (warnedFableDisable.has(model)) return;
-  warnedFableDisable.add(model);
-  console.warn(
-    `[axl] thinking cannot be disabled on Anthropic ${model}; using adaptive thinking at effort 'low'.`
-  );
-}
 function resolveClaudeThinking(model, resolved) {
   const capability = resolveClaudeCapability(model);
   if (!capability) return { stripTemperature: false };
@@ -2901,11 +2913,14 @@ function resolveClaudeThinking(model, resolved) {
     }
     if (resolved.thinkingDisabled) {
       if (capability.thinking === "adaptive-always-on") {
-        warnFableDisable(model);
         return {
           thinking: { type: "adaptive" },
           outputConfig: { effort: "low" },
-          stripTemperature: true
+          stripTemperature: true,
+          clamp: {
+            effective: "low",
+            cause: `thinking cannot be disabled on Anthropic ${model}; using adaptive thinking at effort 'low'`
+          }
         };
       }
       if (activeEffort && capability.disableAt && !isEffortAtOrBelow(activeEffort, capability.disableAt)) {
@@ -2967,7 +2982,16 @@ function resolveClaudeThinking(model, resolved) {
     return {
       thinking: { type: "enabled", budget_tokens: budget },
       manualBudget: budget,
-      stripTemperature: true
+      stripTemperature: true,
+      // Legacy models take `budget_tokens`, not an effort level, and have no
+      // `effortLevels` — so `clampAnthropicEffort` folds 'max'/'xhigh' down to
+      // the 'high' tier and the request silently carries that tier's budget.
+      // Report it: an unreported budget-tier downgrade is exactly the silent
+      // clamp this capability exists to expose.
+      clamp: activeEffort === resolved.activeEffort ? void 0 : {
+        effective: activeEffort,
+        cause: `Anthropic ${model} takes thinking budget_tokens rather than an effort level, and its ceiling tier is '${activeEffort}'; effort '${resolved.activeEffort}' sends budget_tokens ${budget}`
+      }
     };
   }
   return { stripTemperature: capability.stripTemperature ?? false };
@@ -3078,6 +3102,26 @@ function mergeAnthropicUsage(initial, update) {
 }
 var AnthropicProvider = class {
   name = "anthropic";
+  /** Report a clamped `effort`. Anthropic clamps to each model's supported
+   *  `output_config.effort` levels, and models that always think fall back to
+   *  adaptive `'low'` when asked to disable thinking. Only reported when the
+   *  effective level is what the request body actually carries; an explicit
+   *  `thinkingBudget` is documented to override `effort`, so it is not a clamp. */
+  effortResolution(options) {
+    const resolved = resolveThinkingOptions(options);
+    if (resolved.effort === void 0 || resolved.hasBudgetOverride) return void 0;
+    const model = typeof options.providerOptions?.model === "string" ? options.providerOptions.model : options.model;
+    const config = resolveClaudeThinking(model, resolved);
+    const wireEffort = typeof config.outputConfig?.effort === "string" ? config.outputConfig.effort : void 0;
+    const effective = config.clamp?.effective ?? wireEffort;
+    if (effective === void 0 || effective === resolved.effort) return void 0;
+    return {
+      requested: resolved.effort,
+      effective,
+      clamped: true,
+      cause: config.clamp?.cause ?? `Anthropic ${model} does not support effort '${resolved.effort}'; using '${effective}'`
+    };
+  }
   inputCapabilities(model) {
     return model.trim().length > 0 ? { image: { sources: ["url", "bytes", "base64", "provider-file"] } } : {};
   }
@@ -3928,13 +3972,71 @@ function budgetToThinkingLevel(budgetTokens) {
 function minThinkingLevel(model) {
   return GEMINI_3X_MIN_THINKING_LEVEL.get(model) ?? "minimal";
 }
-var _warned3xEffortNone = /* @__PURE__ */ new Set();
-function warnGemini3xEffortNone(model) {
-  if (_warned3xEffortNone.has(model)) return;
-  _warned3xEffortNone.add(model);
-  console.warn(
-    `[axl] effort: 'none' on Gemini 3.x (${model}) maps to the model's minimum thinking level ('${minThinkingLevel(model)}'), not fully disabled. Gemini 3.x models cannot disable thinking entirely.`
-  );
+function resolveGeminiThinking(model, resolved) {
+  const is3x = isGemini3x(model);
+  if (resolved.thinkingDisabled) {
+    const minLevel = minThinkingLevel(model);
+    if (is3x) {
+      return {
+        interactionLevel: minLevel,
+        thinkingLevel: minLevel,
+        thinkingBudget: void 0,
+        attachThoughts: false,
+        // A `thinkingBudget: 0` disable has no unified effort to report against;
+        // only an explicit `effort: 'none'` is a clamp of a requested value.
+        clamp: resolved.effort === "none" ? {
+          effective: minLevel,
+          cause: `Gemini 3.x models cannot disable thinking; using the model minimum thinking level '${minLevel}'`
+        } : void 0
+      };
+    }
+    return {
+      interactionLevel: "minimal",
+      thinkingLevel: void 0,
+      thinkingBudget: 0,
+      attachThoughts: false
+    };
+  }
+  if (resolved.hasBudgetOverride) {
+    const budget = resolved.thinkingBudget;
+    const level = budgetToThinkingLevel(budget);
+    return {
+      interactionLevel: level,
+      thinkingLevel: is3x ? level : void 0,
+      thinkingBudget: is3x ? void 0 : budget,
+      attachThoughts: resolved.includeThoughts
+    };
+  }
+  if (resolved.activeEffort) {
+    const effort = resolved.activeEffort;
+    const budget = THINKING_BUDGETS2[effort] ?? 5e3;
+    if (is3x) {
+      const level = THINKING_LEVELS[effort] ?? "medium";
+      return {
+        interactionLevel: level,
+        thinkingLevel: level,
+        thinkingBudget: void 0,
+        attachThoughts: resolved.includeThoughts,
+        clamp: level === effort ? void 0 : {
+          effective: level,
+          cause: `Gemini 3.x thinking levels cap at 'high'; effort '${effort}' maps to '${level}'`
+        }
+      };
+    }
+    return {
+      interactionLevel: budgetToThinkingLevel(budget),
+      thinkingLevel: void 0,
+      // 2.5 Pro supports a higher max budget (32768) than other 2.5 models (24576).
+      thinkingBudget: effort === "max" && model === "gemini-2.5-pro" ? 32768 : budget,
+      attachThoughts: resolved.includeThoughts
+    };
+  }
+  return {
+    interactionLevel: void 0,
+    thinkingLevel: void 0,
+    thinkingBudget: void 0,
+    attachThoughts: resolved.includeThoughts
+  };
 }
 var GeminiProvider = class {
   name = "google";
@@ -4003,6 +4105,21 @@ var GeminiProvider = class {
   nativeStructuredOutputSupport() {
     return "lossy";
   }
+  /** Report a clamped `effort` (R7a). Gemini 3.x cannot disable thinking and
+   *  caps at `'high'`, so `'none'`, `'xhigh'` and `'max'` are not honored
+   *  verbatim there. Everything else — including 2.x disabled thinking — is
+   *  sent as asked, so there is nothing to report. */
+  effortResolution(options) {
+    const resolved = resolveThinkingOptions(options);
+    if (resolved.effort === void 0) return void 0;
+    const clamp = resolveGeminiThinking(this.requestModel(options), resolved).clamp;
+    return clamp ? {
+      requested: resolved.effort,
+      effective: clamp.effective,
+      clamped: true,
+      cause: clamp.cause
+    } : void 0;
+  }
   baseUrl;
   apiKeySource;
   callCounter = 0;
@@ -4177,12 +4294,9 @@ var GeminiProvider = class {
       generationConfig.tool_choice = typeof options.toolChoice === "string" ? options.toolChoice === "required" ? "any" : options.toolChoice : { allowed_tools: { mode: "any", tools: [options.toolChoice.function.name] } };
     }
     const thinking = resolveThinkingOptions(options);
-    if (thinking.thinkingDisabled) {
-      generationConfig.thinking_level = isGemini3x(model) ? minThinkingLevel(model) : "minimal";
-    } else if (thinking.hasBudgetOverride) {
-      generationConfig.thinking_level = budgetToThinkingLevel(thinking.thinkingBudget);
-    } else if (thinking.activeEffort) {
-      generationConfig.thinking_level = isGemini3x(model) ? THINKING_LEVELS[thinking.activeEffort] ?? "medium" : budgetToThinkingLevel(THINKING_BUDGETS2[thinking.activeEffort] ?? 5e3);
+    const thinkingPlan = resolveGeminiThinking(model, thinking);
+    if (thinkingPlan.interactionLevel !== void 0) {
+      generationConfig.thinking_level = thinkingPlan.interactionLevel;
     }
     if (thinking.includeThoughts) generationConfig.thinking_summaries = "auto";
     if (Object.keys(generationConfig).length) body.generation_config = generationConfig;
@@ -4618,50 +4732,17 @@ var GeminiProvider = class {
     if (Object.keys(generationConfig).length > 0) {
       body.generationConfig = generationConfig;
     }
-    const {
-      effort,
-      thinkingBudget,
-      includeThoughts,
-      thinkingDisabled,
-      activeEffort,
-      hasBudgetOverride
-    } = resolveThinkingOptions(options);
-    if (thinkingDisabled) {
-      if (isGemini3x(requestModel)) {
-        if (effort === "none") {
-          warnGemini3xEffortNone(requestModel);
-        }
-        generationConfig.thinkingConfig = { thinkingLevel: minThinkingLevel(requestModel) };
-      } else {
-        generationConfig.thinkingConfig = { thinkingBudget: 0 };
-      }
-      if (!body.generationConfig) body.generationConfig = generationConfig;
-    } else if (hasBudgetOverride) {
-      const config = {};
-      if (isGemini3x(requestModel)) {
-        config.thinkingLevel = budgetToThinkingLevel(thinkingBudget);
-      } else {
-        config.thinkingBudget = thinkingBudget;
-      }
-      if (includeThoughts) config.includeThoughts = true;
-      generationConfig.thinkingConfig = config;
-      if (!body.generationConfig) body.generationConfig = generationConfig;
-    } else if (activeEffort) {
-      const config = {};
-      if (isGemini3x(requestModel)) {
-        config.thinkingLevel = THINKING_LEVELS[activeEffort] ?? "medium";
-      } else {
-        if (activeEffort === "max" && requestModel === "gemini-2.5-pro") {
-          config.thinkingBudget = 32768;
-        } else {
-          config.thinkingBudget = THINKING_BUDGETS2[activeEffort] ?? 5e3;
-        }
-      }
-      if (includeThoughts) config.includeThoughts = true;
-      generationConfig.thinkingConfig = config;
-      if (!body.generationConfig) body.generationConfig = generationConfig;
-    } else if (includeThoughts) {
-      generationConfig.thinkingConfig = { includeThoughts: true };
+    const thinkingPlan = resolveGeminiThinking(requestModel, resolveThinkingOptions(options));
+    const thinkingConfig = {};
+    if (thinkingPlan.thinkingLevel !== void 0) {
+      thinkingConfig.thinkingLevel = thinkingPlan.thinkingLevel;
+    }
+    if (thinkingPlan.thinkingBudget !== void 0) {
+      thinkingConfig.thinkingBudget = thinkingPlan.thinkingBudget;
+    }
+    if (thinkingPlan.attachThoughts) thinkingConfig.includeThoughts = true;
+    if (Object.keys(thinkingConfig).length > 0) {
+      generationConfig.thinkingConfig = thinkingConfig;
       if (!body.generationConfig) body.generationConfig = generationConfig;
     }
     if (options.toolChoice !== void 0) {
@@ -7296,6 +7377,9 @@ var AXL_EVENT_TYPES = [
   // structured-output cliffs (oversized appended schema, dropped refinements,
   // streaming disabled, zero-guidance `schemaPrompt:'none'`).
   "schema_diagnostic",
+  // Provider capability diagnostics — the resolved provider could not honor a
+  // portable request knob verbatim (first kind: a clamped `effort`).
+  "provider_diagnostic",
   // Observability
   "log",
   "memory_remember",
@@ -7345,6 +7429,7 @@ var LIFECYCLE_TYPES = /* @__PURE__ */ new Set([
   "pipeline",
   "verify",
   "schema_diagnostic",
+  "provider_diagnostic",
   "workflow_start",
   "workflow_end",
   "transcription_start",
@@ -8273,6 +8358,10 @@ var LEGACY_REDACTION_RULES = {
   // which is user content or PII (field paths are schema-shape, preserved like
   // `string_delta.path`). Passthrough, as an explicit reviewed decision.
   schema_diagnostic: passthrough,
+  // `provider_diagnostic` carries only provider capability metadata — a provider
+  // name, a model id, and two effort level strings. No application data or user
+  // content ever reaches it. Passthrough, as an explicit reviewed decision.
+  provider_diagnostic: passthrough,
   log: (e) => {
     if (!e.data || typeof e.data !== "object" || Array.isArray(e.data)) return e;
     return { ...e, data: walkObjectOneLevel(e.data, LOG_PRESERVE_KEYS) };
@@ -8403,6 +8492,7 @@ var COMMON_V2_REDACTION_RULES = {
   string_delta: reuseLegacyRule("string_delta"),
   verify: reuseLegacyRule("verify"),
   schema_diagnostic: reuseLegacyRule("schema_diagnostic"),
+  provider_diagnostic: reuseLegacyRule("provider_diagnostic"),
   log: reuseLegacyRule("log"),
   memory_remember: reuseLegacyRule("memory_remember"),
   memory_recall: reuseLegacyRule("memory_recall"),
@@ -8498,13 +8588,14 @@ function detectDroppedRefinements(schema) {
 var DOCS_URL = "docs/observability.md#schema-diagnostics";
 var MAX_WARNED_KEYS = 2048;
 var warnedDiagnosticKeys = /* @__PURE__ */ new Set();
-function warnSchemaDiagnosticOnce(key, message, silent) {
+function warnDiagnosticOnce(key, message, silent, docs = DOCS_URL) {
   if (silent || process.env.AXL_DIAGNOSTICS_SILENT === "true") return;
   if (warnedDiagnosticKeys.has(key)) return;
   if (warnedDiagnosticKeys.size >= MAX_WARNED_KEYS) warnedDiagnosticKeys.clear();
   warnedDiagnosticKeys.add(key);
-  console.warn(`[axl] ${message} See ${DOCS_URL}.`);
+  console.warn(`[axl] ${message} See ${docs}.`);
 }
+var warnSchemaDiagnosticOnce = warnDiagnosticOnce;
 
 // src/config.ts
 function defineConfig(config) {
@@ -9354,7 +9445,22 @@ function appendRetryMessages(messages, content, feedbackMessage, providerMetadat
     content,
     ...providerMetadata ? { providerMetadata } : {}
   });
-  messages.push({ role: "system", content: feedbackMessage });
+  messages.push({ role: "user", content: feedbackMessage });
+}
+function isRetryAbort(value) {
+  return typeof value === "object" && value !== null && value.retry === false;
+}
+function describeValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `an array of length ${value.length}`;
+  if (typeof value === "object") {
+    const keys = Object.keys(value);
+    return keys.length > 0 ? `an object with keys [${keys.join(", ")}]` : "an empty object";
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return `the ${typeof value} ${JSON.stringify(value)}`;
+  }
+  return `a value of type ${typeof value}`;
 }
 function estimateMessagesTokens(messages) {
   let total = 0;
@@ -10291,6 +10397,7 @@ ${appendedSchemaText}`;
       provider,
       model
     });
+    this.emitProviderDiagnostics(agent2, options, { provider, model, providerOptions });
     if (handoffMessages && handoffMessages.length > 0) {
       const handoffContext = handoffMessages.filter(
         (m) => m.role === "assistant" || m.role === "tool"
@@ -10655,7 +10762,11 @@ ${appendedSchemaText}`;
                 retries: options.retries,
                 metadata: options.metadata,
                 validate: options.validate,
-                validateRetries: options.validateRetries
+                validateRetries: options.validateRetries,
+                // This seam serves both callers of a handoff: a plain `ctx.ask()` on an
+                // agent with `handoffs`, and the routed `ctx.delegate()` path, whose
+                // terminal ask is the handoff target. The hook travels like `validate`.
+                retryFeedback: options.retryFeedback
               } : void 0;
               const handoffFn = () => askStorage.run(targetFrame, async () => {
                 const delegateOriginal = agent2._delegateOriginalInput;
@@ -10804,9 +10915,10 @@ ${appendedSchemaText}`;
         const attempt = guardrailOutputRetries + 1;
         const maxAttempts = maxGuardrailRetries + 1;
         const onBlock = guardrails.onBlock ?? "throw";
+        const blockReason = outputResult.reason ?? "Output blocked by guardrail";
         let feedbackMessage;
         if (outputResult.block && onBlock === "retry" && guardrailOutputRetries < maxGuardrailRetries) {
-          feedbackMessage = `Your previous response was blocked by a safety guardrail: ${outputResult.reason ?? "Output blocked"}. Please provide a different response that complies with the guidelines.`;
+          feedbackMessage = `Your previous response was blocked by a safety guardrail: ${blockReason}. Please provide a different response that complies with the guidelines.`;
         }
         this.emitEvent({
           type: "guardrail",
@@ -10829,31 +10941,43 @@ ${appendedSchemaText}`;
         });
         if (outputResult.block) {
           if (feedbackMessage) {
-            this.emitEvent({
-              type: "pipeline",
-              agent: agent2._name,
-              status: "failed",
+            const decision = await this.resolveRetryFeedback(options?.retryFeedback, {
               stage: "guardrail",
-              attempt: guardrailOutputRetries + 1,
-              maxAttempts: maxGuardrailRetries + 1,
-              reason: feedbackMessage
+              attempt,
+              maxAttempts,
+              output: content,
+              reason: blockReason,
+              defaultMessage: feedbackMessage
             });
-            guardrailOutputRetries++;
-            appendRetryMessages(
-              currentMessages,
-              content,
-              feedbackMessage,
-              response.providerMetadata
-            );
-            pendingRetryReason = "guardrail";
-            continue;
+            if (decision.retry) {
+              this.emitEvent({
+                type: "pipeline",
+                agent: agent2._name,
+                status: "failed",
+                stage: "guardrail",
+                attempt,
+                maxAttempts,
+                reason: decision.message
+              });
+              guardrailOutputRetries++;
+              appendRetryMessages(
+                currentMessages,
+                content,
+                decision.message,
+                response.providerMetadata
+              );
+              pendingRetryReason = "guardrail";
+              continue;
+            }
+            this.currentSignal?.throwIfAborted();
+            throw new GuardrailError("output", blockReason);
           }
           if (typeof onBlock === "function") {
-            return onBlock(outputResult.reason ?? "Output blocked by guardrail", {
+            return onBlock(blockReason, {
               metadata: this.metadata
             });
           }
-          throw new GuardrailError("output", outputResult.reason ?? "Output blocked by guardrail");
+          throw new GuardrailError("output", blockReason);
         }
       }
       let validated = void 0;
@@ -10873,7 +10997,7 @@ ${appendedSchemaText}`;
           schemaErr = err;
           schemaReason = err instanceof Error ? err.message : String(err);
           if (schemaRetries < maxSchemaRetries) {
-            schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Please fix and try again.`;
+            schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Return a corrected response that matches the required schema.`;
           }
         }
         this.emitEvent({
@@ -10895,24 +11019,36 @@ ${appendedSchemaText}`;
         });
         if (!schemaValid) {
           if (schemaFeedback) {
-            this.emitEvent({
-              type: "pipeline",
-              agent: agent2._name,
-              status: "failed",
+            const decision = await this.resolveRetryFeedback(options.retryFeedback, {
               stage: "schema",
-              attempt: schemaRetries + 1,
-              maxAttempts: (options.retries ?? 3) + 1,
-              reason: schemaFeedback
+              attempt: schemaAttempt,
+              maxAttempts: schemaMaxAttempts,
+              output: content,
+              reason: schemaReason ?? "Schema parse failed",
+              ...schemaErr !== void 0 ? { error: schemaErr } : {},
+              defaultMessage: schemaFeedback
             });
-            schemaRetries++;
-            appendRetryMessages(
-              currentMessages,
-              content,
-              schemaFeedback,
-              response.providerMetadata
-            );
-            pendingRetryReason = "schema";
-            continue;
+            if (decision.retry) {
+              this.emitEvent({
+                type: "pipeline",
+                agent: agent2._name,
+                status: "failed",
+                stage: "schema",
+                attempt: schemaAttempt,
+                maxAttempts: schemaMaxAttempts,
+                reason: decision.message
+              });
+              schemaRetries++;
+              appendRetryMessages(
+                currentMessages,
+                content,
+                decision.message,
+                response.providerMetadata
+              );
+              pendingRetryReason = "schema";
+              continue;
+            }
+            this.currentSignal?.throwIfAborted();
           }
           const zodErr = schemaErr instanceof ZodError2 ? schemaErr : new ZodError2([
             {
@@ -10926,12 +11062,14 @@ ${appendedSchemaText}`;
       }
       if (options?.schema && options.validate) {
         let validateResult;
+        let validateErr;
         try {
           validateResult = await options.validate(validated, {
             metadata: this.metadata
           });
         } catch (err) {
           rethrowEventStreamOverflow(err);
+          validateErr = err;
           const reason = err instanceof Error ? err.message : String(err);
           validateResult = { valid: false, reason: `Validator error: ${reason}` };
         }
@@ -10940,7 +11078,7 @@ ${appendedSchemaText}`;
         const validateMaxAttempts = maxValidateRetries + 1;
         let validateFeedback;
         if (!validateResult.valid && validateRetries < maxValidateRetries) {
-          validateFeedback = `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`;
+          validateFeedback = `Your previous response failed validation: ${validateResult.reason ?? "Validation failed"}. Return a corrected response that satisfies the required schema and this rule.`;
         }
         this.emitEvent({
           type: "validate",
@@ -10961,24 +11099,37 @@ ${appendedSchemaText}`;
         });
         if (!validateResult.valid) {
           if (validateFeedback) {
-            this.emitEvent({
-              type: "pipeline",
-              agent: agent2._name,
-              status: "failed",
+            const decision = await this.resolveRetryFeedback(options.retryFeedback, {
               stage: "validate",
-              attempt: validateRetries + 1,
-              maxAttempts: (options.validateRetries ?? 2) + 1,
-              reason: validateFeedback
+              attempt: validateAttempt,
+              maxAttempts: validateMaxAttempts,
+              output: content,
+              parsed: validated,
+              reason: validateResult.reason ?? "Validation failed",
+              ...validateErr !== void 0 ? { error: validateErr } : {},
+              defaultMessage: validateFeedback
             });
-            validateRetries++;
-            appendRetryMessages(
-              currentMessages,
-              content,
-              validateFeedback,
-              response.providerMetadata
-            );
-            pendingRetryReason = "validate";
-            continue;
+            if (decision.retry) {
+              this.emitEvent({
+                type: "pipeline",
+                agent: agent2._name,
+                status: "failed",
+                stage: "validate",
+                attempt: validateAttempt,
+                maxAttempts: validateMaxAttempts,
+                reason: decision.message
+              });
+              validateRetries++;
+              appendRetryMessages(
+                currentMessages,
+                content,
+                decision.message,
+                response.providerMetadata
+              );
+              pendingRetryReason = "validate";
+              continue;
+            }
+            this.currentSignal?.throwIfAborted();
           }
           throw new ValidationError(
             validated,
@@ -11000,6 +11151,31 @@ ${appendedSchemaText}`;
     }
     throw new MaxTurnsError("ctx.ask()", maxTurns);
   }
+  /**
+   * Resolve the corrective feedback text for one rejected attempt, giving an optional
+   * caller-supplied `retryFeedback` hook the chance to replace it or to stop retrying.
+   *
+   * Called by all three output gates, only while a retry is still permitted (never on the
+   * exhausting attempt) and only after the gate's own event has been emitted, so a hook that
+   * throws or aborts can never erase the evidence that the gate rejected. A non-empty string
+   * replaces `defaultMessage` verbatim; `undefined` / `''` keeps it; `{ retry: false }` asks
+   * the gate to throw its typed terminal error. Hook exceptions propagate — a bug in caller
+   * code is not a model failure and must not be retried into silence, and neither is a
+   * return value outside the contract: an unrecognized shape throws instead of silently
+   * degrading to the default text, which would hide the defect behind extra token spend.
+   */
+  async resolveRetryFeedback(hook, info) {
+    if (!hook) return { retry: true, message: info.defaultMessage };
+    const result = await hook(info, { metadata: this.metadata });
+    if (result === void 0 || result === "") {
+      return { retry: true, message: info.defaultMessage };
+    }
+    if (typeof result === "string") return { retry: true, message: result };
+    if (isRetryAbort(result)) return { retry: false };
+    throw new TypeError(
+      `retryFeedback must return a string, undefined, or { retry: false }; received ${describeValue(result)}.`
+    );
+  }
   /**
    * Push the final assistant message into session history, preserving providerMetadata
    * (e.g., Gemini thought signatures needed for multi-turn reasoning context) and
@@ -11155,6 +11331,57 @@ ${appendedSchemaText}`;
       }
     }
   }
+  /**
+   * Emit a `provider_diagnostic` when the resolved provider reports that it
+   * could not honor the unified `effort` verbatim (P3/R6/R7).
+   *
+   * The adapter only *resolves* — it returns the requested and effective levels
+   * from the same pure resolver its request builder uses. The runtime decides
+   * how to surface that, because only the runtime can see the event bus and
+   * `AxlConfig.diagnostics.silent` (adapters receive `ProviderConfig` only).
+   *
+   * Called once per ask, so a tool loop with N provider round trips still emits
+   * one event; the `console.warn` dedupes once per process per distinct clamp.
+   * A throwing `effortResolution` is a provider bug and propagates.
+   */
+  emitProviderDiagnostics(agent2, options, ctx) {
+    if (!ctx.provider.effortResolution) return;
+    const resolution = ctx.provider.effortResolution({
+      model: ctx.model,
+      effort: options?.effort ?? agent2._config.effort,
+      thinkingBudget: options?.thinkingBudget ?? agent2._config.thinkingBudget,
+      includeThoughts: options?.includeThoughts ?? agent2._config.includeThoughts,
+      providerOptions: ctx.providerOptions
+    });
+    if (!resolution?.clamped) return;
+    if (typeof resolution.effective !== "string" || resolution.effective.length === 0 || typeof resolution.requested !== "string" || resolution.requested.length === 0) {
+      throw new TypeError(
+        `Provider '${ctx.provider.name ?? "unknown"}' returned a malformed EffortResolution for model '${ctx.model}': 'requested' and 'effective' must be non-empty strings when 'clamped' is true. Received ${JSON.stringify(resolution)}.`
+      );
+    }
+    const cause = resolution.cause ?? `effort '${resolution.requested}' is not supported as asked`;
+    this.emitEvent({
+      type: "provider_diagnostic",
+      agent: agent2._name,
+      data: {
+        kind: "effort_clamped",
+        ...ctx.provider.name ? { provider: ctx.provider.name } : {},
+        model: ctx.model,
+        requested: resolution.requested,
+        effective: resolution.effective,
+        cause
+      }
+    });
+    warnDiagnosticOnce(
+      // One warning per distinct clamp, not per ask: the same clamp across 500
+      // asks is one process-level surprise, while a different requested/effective
+      // pair is a genuinely new one.
+      `effort_clamped\0${ctx.provider.name ?? ""}\0${ctx.model}\0${resolution.requested}\0${resolution.effective}`,
+      `effort '${resolution.requested}' was clamped to '${resolution.effective}' on ${ctx.provider.name ? `${ctx.provider.name} ` : ""}${ctx.model} \u2014 ${cause}. A 'provider_diagnostic' event carries the same detail per ask.`,
+      this.config.diagnostics?.silent,
+      "docs/observability.md#provider-diagnostics"
+    );
+  }
   buildToolDefs(agent2, resolvedHandoffs) {
     const defs = [];
     if (agent2._config.tools) {
@@ -12435,7 +12662,8 @@ ${summaryResponse.content}`
         retries: options?.retries,
         metadata: options?.metadata,
         validate: options?.validate,
-        validateRetries: options?.validateRetries
+        validateRetries: options?.validateRetries,
+        retryFeedback: options?.retryFeedback
       });
     }
     const resolveCtx = options?.metadata ? { metadata: { ...this.metadata, ...options.metadata } } : { metadata: this.metadata };
@@ -12483,7 +12711,8 @@ ${summaryResponse.content}`
       retries: options?.retries,
       metadata: options?.metadata,
       validate: options?.validate,
-      validateRetries: options?.validateRetries
+      validateRetries: options?.validateRetries,
+      retryFeedback: options?.retryFeedback
     });
   }
   /** Transcribe recorded audio through the dedicated transcription registry.